docs+test: close v1.5.0 audit findings

Follow-up to the v1.5.0 cleanup. A four-angle audit found a handful of stale references and one coverage gap; this commit closes them all.

Doc fixes (live docs that lied about current state):

- CONTRIBUTING.md vocabulary schema: optional fields list said `mask_kind`/`mask_ref`; updated to `mask_spec` with the drawn-form shape, noting the v1.5.0 retirement.
- vocabulary/starter/README.md: dropped the deleted `tone_lifted_shadows_subject` row, fixed the count (5 → 4), explained why mask-bound starter entries are out for now.
- docs/adr/TA.md MCP component: corrected stale "27 tools across ... masks ... plus context stubs" to current 22 (vocab/edit 5 + versioning 6 + rendering 3 + ingest 3 + context 5).
- docs/testing.md: bumped "27 shipped tools" → 22, replaced `tone_lifted_shadows_subject` example with `gradient_top_dampen_highlights`, dropped the dead Masks tool category, rewrote the mask-bound coverage line around `apply_with_drawn_mask` and the spatial-difference assertion.
- docs/concept/02-project-concept.md § 10.1: rewrote the "configure a masking provider beyond the bundled coarse default" line; there is no bundled default. Phase 4 framed as drawn-form geometry, not PNG providers.
- docs/IMPLEMENTATION.md Slice 4: prepended a "Status note (2026-05-03) — superseded by ADR-076" callout. Historical narrative preserved as build record.

Append-only ADRs (partial-supersession status markers, mirroring what we did for ADR-021/022/055/057/058/074):

- ADR-056 (MCP tool surface): noted the 5 mask tools and `mask_override` arg are gone; surface is 22 not 27. Error-contract rules still in force.
- ADR-070 (CLI framework: Typer): noted the `masks` sub-command group is gone; CLI now has 1 sub-app (vocab) not 2. Typer choice stands.

Coverage gap (test integrity):

- tests/unit/mcp/tools/test_vocab_edit.py: added test_apply_primitive_with_mask_spec_routes_through_drawn_mask (proves the mask_spec branch in vocab_edit.py:_apply_primitive injects darktable:masks_history into the snapshotted XMP) and test_apply_primitive_with_invalid_mask_spec_returns_masking_error (malformed spec → MASKING_ERROR, not a stack trace).
- tests/integration/cli/test_cli_edit.py: added test_apply_primitive_with_mask_spec_routes_through_drawn_mask using `--pack expressive-baseline` and `gradient_top_dampen_highlights`. Mirrors the MCP coverage at the CLI dispatch layer.

Both branches now have explicit unit/integration coverage that doesn't require real darktable. The e2e tests in tests/e2e/expressive/test_mask_bound_entries.py continue to prove the binding actually shapes pixels.

CI: 440 unit + 206 integration + all gates green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chipi

docs/CONTRIBUTING.md

@@ -240,7 +240,7 @@ Some sliders have minimum granularity that prevents authoring exact zero values.
 
 Starting v0.3.0, vocabulary packs are loaded by `chemigram.core.vocab.VocabularyIndex` against a per-pack `manifest.json`. A pack is a directory whose root contains `manifest.json` plus a tree of `.dtstyle` files (the layout under `vocabulary/starter/` follows `layers/L1`, `layers/L2`, `layers/L3` per the architecture doc).
 
-The manifest's top-level shape is `{"entries": [...]}`. Each entry object follows the contract in `docs/adr/TA.md` `contracts/vocabulary-manifest`. Required fields per entry: `name`, `layer`, `path`, `touches`, `tags`, `description`, `modversions`, `darktable_version`, `source`, `license`. Optional: `subtype`, `mask_kind`, `mask_ref`, `global_variant`, `applies_to`. L1 entries must include `applies_to: {make, model, lens_model}` (exact-match per ADR-053).
+The manifest's top-level shape is `{"entries": [...]}`. Each entry object follows the contract in `docs/adr/TA.md` `contracts/vocabulary-manifest`. Required fields per entry: `name`, `layer`, `path`, `touches`, `tags`, `description`, `modversions`, `darktable_version`, `source`, `license`. Optional: `subtype`, `mask_spec`, `global_variant`, `applies_to`. L1 entries must include `applies_to: {make, model, lens_model}` (exact-match per ADR-053). Mask-bound entries declare a `mask_spec` of shape `{"dt_form": "gradient" | "ellipse" | "rectangle", "dt_params": {...}}` per ADR-076; the v1.4-and-earlier `mask_kind` / `mask_ref` fields were retired in v1.5.0 along with the PNG-mask path.
 
 The index validates eagerly: the dtstyle file must exist relative to `pack_root`, must parse cleanly, and the user-authored plugin's `<operation>` must appear in the manifest entry's `touches` list. Mismatches are `ManifestError` with the offending entry name in the message — fix the manifest, not the parser.
 

docs/IMPLEMENTATION.md

@@ -169,9 +169,11 @@ Phase 1 is decomposed into six slices. Slices roughly follow dependency order 
 
 ---
 
-### Slice 4 — Coarse masking + local adjustments ✅ shipped (v0.4.0)
+### Slice 4 — Coarse masking + local adjustments ✅ shipped (v0.4.0); architecturally superseded (v1.5.0)
 
-**Scope (shipped):**
+> **Status note (2026-05-03):** the substance of this slice — the `MaskingProvider` Protocol, `CoarseAgentProvider`, the PNG mask registry, the five mask MCP tools, the `mask_kind`/`mask_ref` schema, the `mask_override` apply argument — was all retired in v1.5.0 (ADR-076) when we discovered darktable doesn't read external PNG raster masks. The drawn-mask path (path 4a, v1.4.0) replaced it, validated end-to-end against real darktable. The historical scope below is preserved as build-record; for current architecture see ADR-076 and `concept/04-architecture.md` § 6.
+
+**Scope (shipped in v0.4.0; later superseded):**
 
 - `chemigram.core.masking` — `MaskingProvider` Protocol + `MaskResult` (ADR-057, #17).
 - `chemigram.core.masking.coarse_agent.CoarseAgentProvider` — sampling-based bundled default per ADR-058. Pillow rasterizer for bbox + polygon descriptors (#17).

docs/adr/ADR-056-mcp-tool-surface.md

@@ -1,6 +1,6 @@
 # ADR-056 — MCP tool surface: parameter shapes and error contract
 
-> Status · Accepted
+> Status · Accepted; partially superseded by ADR-076 (2026-05-03) — the 5 mask tools (`generate_mask`, `regenerate_mask`, `list_masks`, `tag_mask`, `invalidate_mask`) and the `apply_primitive(mask_override=…)` parameter were removed in v1.5.0; the surface is now 22 tools, not 27. The error-contract and parameter-shape rules in this ADR remain in force for the surviving tools.
 > Date · 2026-04-29
 > TA anchor · /components/mcp-server, /contracts/mcp-tools
 > Related RFC · RFC-010 (closes); supersedes the implementation note in ADR-033

docs/adr/ADR-070-cli-framework-typer.md

@@ -1,6 +1,6 @@
 # ADR-070 — CLI framework: Typer
 
-> Status · Accepted
+> Status · Accepted; partially superseded by ADR-076 (2026-05-03) — the `masks` sub-command group (list/generate/regenerate/tag/invalidate) was removed in v1.5.0; the CLI now has 1 sub-command group (`vocab`), not 2. Typer remains the framework choice and the rest of this ADR's reasoning stands.
 > Date · 2026-05-03
 > TA anchor ·/components/cli
 > Related RFC · RFC-020 (closes here)

docs/adr/TA.md

@@ -79,7 +79,7 @@ Drawn-mask serialization for vocabulary entries that shape only part of the fram
 
 Adapts subsystems 1–4 as agent-callable tools. Thin layer.
 
-**Files (shipped v0.3.0):** `src/chemigram/mcp/server.py` (bootstrap + stdio), `src/chemigram/mcp/registry.py` (tool registry + `ToolContext`), `src/chemigram/mcp/errors.py` (`ToolResult` / `ToolError` / `ErrorCode`), `src/chemigram/mcp/_test_harness.py` (in-memory client/server harness), `src/chemigram/mcp/tools/*` (27 tools across vocab/edit, versioning, rendering, ingest, masks, plus context stubs).
+**Files:** `src/chemigram/mcp/server.py` (bootstrap + stdio), `src/chemigram/mcp/registry.py` (tool registry + `ToolContext`), `src/chemigram/mcp/errors.py` (`ToolResult` / `ToolError` / `ErrorCode`), `src/chemigram/mcp/_test_harness.py` (in-memory client/server harness), `src/chemigram/mcp/tools/*` — 22 tools as of v1.5.0 across vocab/edit (5), versioning (6), rendering (3), ingest (3), context (5). The 5 mask tools (`generate_mask`/`regenerate_mask`/`list_masks`/`tag_mask`/`invalidate_mask`) shipped in v0.3.0–v0.4.0 and were removed in v1.5.0 per ADR-076 — see CHANGELOG.
 
 **Tool surface:** see TA/contracts/mcp-tools.
 

docs/concept/02-project-concept.md

@@ -437,7 +437,7 @@ Putting it all together — what a photographer experiences from first install t
 
 Install Chemigram. Initial setup creates `~/.chemigram/` with empty `taste.md`, default `config.toml`, isolated darktable configdir. Photographer spends an hour writing initial `taste.md` — what they can articulate about their preferences. Imperfect; fine.
 
-Optionally configure a masking provider beyond the bundled coarse default. For production-quality work on subjects, install `chemigram-masker-sam` sibling project.
+Note that v1.5.0 ships drawn-form geometric masks (gradient / ellipse / rectangle) baked into vocabulary entries' `mask_spec`. There is no AI-driven masker today; subject-precise content-aware masking is Phase 4 work via a sibling project (working name `chemigram-masker-sam`) that will produce darktable drawn-form geometry, not PNG bytes. ADR-076 documents the architecture and supersedes the v1.4-and-earlier PNG-mask path.
 
 ### 10.2 First session — Mode A on a single image
 

docs/testing.md

@@ -103,7 +103,7 @@ Tests live in three directories, codified in ADR-036, refined here with concrete
 - Every render code path: preview, export, with/without masks, different sizes.
 - Full MCP session shapes: ingest → bind → apply → render → export → snapshot.
 - Reset / branch / checkout semantics: each followed by a render to confirm the workspace state is intact.
-- Mask-bound primitives: real mask materialization → real render → assert the masked region differs from the unmasked region.
+- Mask-bound primitives: real `apply_with_drawn_mask` synthesis → real render → assert the masked region differs *spatially* from a same-dtstyle uniform render (path 4a; v1.4.0+).
 
 **Doesn't belong:**
 - Anything that doesn't ultimately validate pixels or filesystem state from a real darktable invocation.
@@ -119,7 +119,7 @@ These are the rules a PR must satisfy before it lands.
 - One unit test per input-validation path (schema rejects malformed input).
 - One integration test per error code the tool can return (`recoverable=True` errors all need at least one test).
 - One integration test for the happy path through `in_memory_session`.
-- If the tool produces side-effects on the filesystem (snapshot, mask, transcript): one integration test that asserts the post-state.
+- If the tool produces side-effects on the filesystem (snapshot, transcript): one integration test that asserts the post-state.
 - If the tool drives a render: one e2e test that asserts on the rendered pixels.
 
 ### When you add a vocabulary primitive
@@ -165,11 +165,11 @@ Every shipped primitive needs end-to-end pixel validation. The 5 starter entries
 | `expo_-0.5` | L3 | luma < `expo_+0.5` (relative ordering) |
 | `wb_warm_subtle` | L3 | warmth ratio (R+G)/(2B) increases |
 | `look_neutral` | L2 | composite renders without errors; specific channel asserts TBD |
-| `tone_lifted_shadows_subject` | L3 raster-mask-bound | masked region's shadow tones lifted vs unmasked baseline |
+| `gradient_top_dampen_highlights` | L3 drawn-mask-bound | masked region (top half) reads dimmer than uniform application |
 
 ### MCP tool surface
 
-All 27 shipped tools need:
+All 22 shipped tools need:
 - Unit input-validation coverage
 - Integration round-trip coverage through `in_memory_session`
 - E2e coverage for any tool that drives a render or mutates filesystem state
@@ -180,7 +180,7 @@ Categories:
 - **Layer binding:** `bind_layers`, `unbind_layers`
 - **Rendering:** `render_preview`, `compare`
 - **Export:** `export`
-- **Masks:** `generate_mask`, `regenerate_mask`, `list_masks`, `tag_mask`, `apply_primitive(mask_override=...)`
+- **Drawn-mask apply:** `apply_primitive` for entries with `mask_spec` set (routes through `apply_with_drawn_mask`; e2e proves the binding shapes the rendered effect). Standalone mask MCP tools were removed in v1.5.0 per ADR-076.
 - **Context:** `read_context`, `propose_taste_update`, `confirm_taste_update`, `propose_notes_update`, `confirm_notes_update`, `log_vocabulary_gap`
 - **Lifecycle:** `ingest_workspace`
 
@@ -194,13 +194,12 @@ Beyond per-tool coverage, the *combinations* matter:
 - snapshot → tag → reset → snapshot (the ADR-062 case)
 - branch → checkout → snapshot → checkout main → diff
 - tag (immutable) → re-tag (must fail)
-- snapshot → invalidate-mask → snapshot (mask reachability)
 
 ### Render paths
 
 - Preview at multiple sizes (256, 1024, 4096)
 - Export at full resolution (`--hq true`)
-- Render with `apply_primitive(mask_override)` — masked region differs from unmasked
+- Render after `apply_primitive` with a `mask_spec`-bearing entry — masked region differs spatially from a same-dtstyle uniform render
 - Render after corrupt XMP — surfaced as `darktable_error`, not stack trace
 
 ### Context + session

tests/integration/cli/test_cli_edit.py

@@ -94,6 +94,44 @@ def test_apply_primitive_json_emits_snapshot_hash(
     assert "state_after" in payload
 
 
+def test_apply_primitive_with_mask_spec_routes_through_drawn_mask(
+    runner: CliRunner, cli_workspace_root: Path
+) -> None:
+    """An expressive-baseline mask-bound entry routes through the drawn-mask
+    apply path; the resulting XMP carries masks_history. Coverage gate for
+    the ``vocab_entry.mask_spec is not None`` branch in cli/commands/edit.py
+    (the e2e suite proves the binding actually shapes pixels under real
+    darktable; this proves the dispatch logic works without darktable).
+    """
+    result = runner.invoke(
+        app,
+        [
+            "--json",
+            "--workspace",
+            str(cli_workspace_root),
+            "apply-primitive",
+            "test-image",
+            "--entry",
+            "gradient_top_dampen_highlights",
+            "--pack",
+            "expressive-baseline",
+        ],
+    )
+    assert result.exit_code == ExitCode.SUCCESS.value, result.stdout + result.stderr
+    payload = json.loads(result.stdout.strip().splitlines()[-1])
+    assert payload["status"] == "ok"
+    snapshot_hash = payload["snapshot_hash"]
+
+    from chemigram.core.versioning import ImageRepo
+
+    repo = ImageRepo(cli_workspace_root / "test-image")
+    raw = repo.read_object(snapshot_hash)
+    assert b"masks_history" in raw, (
+        "drawn-mask path should inject darktable:masks_history into the XMP "
+        "for entries with mask_spec (ADR-076)"
+    )
+
+
 def test_apply_primitive_unknown_entry(runner: CliRunner, cli_workspace_root: Path) -> None:
     result = runner.invoke(
         app,

tests/unit/mcp/tools/test_vocab_edit.py

@@ -111,6 +111,73 @@ def test_apply_primitive_unknown_primitive_returns_not_found(
     assert result.error.code == ErrorCode.NOT_FOUND
 
 
+def test_apply_primitive_with_mask_spec_routes_through_drawn_mask(
+    context: ToolContext,
+) -> None:
+    """When entry.mask_spec is set, apply_primitive routes through
+    apply_with_drawn_mask which injects masks_history into the XMP.
+
+    Coverage gate for the mask_spec branch in
+    chemigram.mcp.tools.vocab_edit._apply_primitive — without this, only
+    the e2e suite (requires real darktable) exercises that branch.
+    """
+    from dataclasses import replace as dc_replace
+
+    base = context.vocabulary.lookup_by_name("expo_+0.5")
+    assert base is not None
+    masked = dc_replace(
+        base,
+        name="expo_top_gradient_test",
+        mask_spec={
+            "dt_form": "gradient",
+            "dt_params": {
+                "anchor_x": 0.5,
+                "anchor_y": 0.5,
+                "rotation": 0.0,
+                "compression": 0.5,
+            },
+        },
+    )
+    context.vocabulary._by_name["expo_top_gradient_test"] = masked
+
+    result = _call(
+        "apply_primitive",
+        {"image_id": "test-image", "primitive_name": "expo_top_gradient_test"},
+        context,
+    )
+    assert result.success is True, result.error
+    snapshot_hash = result.data["snapshot_hash"]
+    raw = context.workspaces["test-image"].repo.read_object(snapshot_hash)
+    assert b"masks_history" in raw, (
+        "drawn-mask path should inject darktable:masks_history into the XMP "
+        "when mask_spec is set on the vocab entry (ADR-076)"
+    )
+
+
+def test_apply_primitive_with_invalid_mask_spec_returns_masking_error(
+    context: ToolContext,
+) -> None:
+    """Malformed mask_spec → MASKING_ERROR (not a stack trace through MCP)."""
+    from dataclasses import replace as dc_replace
+
+    base = context.vocabulary.lookup_by_name("expo_+0.5")
+    assert base is not None
+    bad = dc_replace(
+        base,
+        name="expo_bad_mask_test",
+        mask_spec={"dt_form": "not_a_real_form", "dt_params": {}},
+    )
+    context.vocabulary._by_name["expo_bad_mask_test"] = bad
+
+    result = _call(
+        "apply_primitive",
+        {"image_id": "test-image", "primitive_name": "expo_bad_mask_test"},
+        context,
+    )
+    assert result.success is False
+    assert result.error.code == ErrorCode.MASKING_ERROR
+
+
 # --- remove_module ------------------------------------------------------
 
 

vocabulary/starter/README.md

@@ -1,6 +1,6 @@
 # Starter Vocabulary
 
-The vocabulary pack that ships with `pip install chemigram`. **Deliberately small** — five entries, generic by design — so the agent loop works out of the box. Phase 2 grows the vocabulary from real session evidence, not from imagined upfront completeness; the gaps surfaced via `log_vocabulary_gap` are the seed for new entries.
+The vocabulary pack that ships with `pip install chemigram`. **Deliberately small** — four entries, generic by design — so the agent loop works out of the box. Phase 2 grows the vocabulary from real session evidence, not from imagined upfront completeness; the gaps surfaced via `log_vocabulary_gap` are the seed for new entries.
 
 See `docs/concept/04-architecture.md` § 5 (layer model) for the L1/L2/L3 architecture, and `docs/prd/PRD-003-vocabulary-as-voice.md` for the design rationale.
 
@@ -12,9 +12,8 @@ See `docs/concept/04-architecture.md` § 5 (layer model) for the L1/L2/L3 archit
 | `expo_-0.5` | L3 | exposure | — | Lower exposure -0.5 EV (global) |
 | `wb_warm_subtle` | L3 | temperature | — | Subtle warm white balance shift |
 | `look_neutral` | L2 | exposure + temperature | — | Neutral L2 baseline (exposure + warm-subtle WB) |
-| `tone_lifted_shadows_subject` | L3 | exposure | raster (subject) | Shadow lift restricted to the subject mask |
 
-The mask-bound entry references `current_subject_mask` — the agent generates this via `generate_mask(image_id, target="subject")` before applying.
+Mask-bound starter entries are out for now: the original `tone_lifted_shadows_subject` was retired in v1.5.0 alongside the PNG-mask architecture (ADR-076). Drawn-form mask-bound entries (gradient / ellipse / rectangle) live in the `expressive-baseline` pack; the starter pack stays minimal until evidence motivates a starter-level mask-bound primitive.
 
 ## What's not shipped