hatch3r 2.1.1 → 2.2.0

package/dist/content/agents/shared/quality-charter.md

@@ -196,7 +196,7 @@ When an agent produces a service that handles a request, the charter binds it to
 
 Cross-reference: AUDIT Directive 16 (a), CONSTITUTION §2 P2 production-readiness measurement (instrumented-route ratio = 100%), forthcoming D22.
 
-### Data integrity quality (for agent-produced schema and event changes)
+### Data integrity quality (for agent-produced schema, event, and shared-contract changes)
 
 When an agent produces a schema migration, an event-schema change, or a backfill, the charter binds it to these criteria.
 
@@ -205,7 +205,8 @@ When an agent produces a schema migration, an event-schema change, or a backfill
 - **Reversibility:** every forward migration has a documented rollback path; irreversible migrations are flagged and gated on explicit acknowledgement.
 - **Replica-lag awareness:** backfills are idempotent + resumable + throttled to a documented lag budget; reads after writes use primary or wait for replication where consistency is required.
 - **Event-schema compatibility:** event-driven changes declare BACKWARD, FORWARD, or FULL compatibility in a schema registry (Avro / Protobuf / JSON-schema); breaking events bump a major version. Reference `rules/hatch3r-event-schema-evolution.md`.
-- **Verification gate:** a change is not done until the schema diff has been classified against the expand-contract phases and the rollback path has been tested in a non-prod environment.
+- **Shared-contract census:** every mutation of a shared contract (exported symbol, persisted name, wire field, event schema, shared constant — `rules/hatch3r-contract-census.md`) ships a repo-wide consumer census; each consumer is updated, guarded, or justified by name.
+- **Verification gate:** a change is not done until the schema diff has been classified against the expand-contract phases and the rollback path has been tested in a non-prod environment, and — for any shared-contract mutation — the consumer census returns `clean` or `reconciled(N)` with every consumer read at its use site.
 
 Cross-reference: AUDIT Directive 16 (b), CONSTITUTION §2 P2 production-readiness measurement (expand-contract conformance = 100%), forthcoming D22.
 

package/dist/content/agents/shared/quality-specialist-frame.md

@@ -63,7 +63,7 @@ When the review surface decomposes into independent units (routes, flows, servic
 
 1. **Identify the unit of decomposition.** The specialist file names the unit (route for `hatch3r-ui`, flow for `hatch3r-ux`, security domain for `hatch3r-security`, service or layer for `hatch3r-reliability`, mandate class for `hatch3r-testability`, etc.).
 2. **Spawn one sub-agent per unit via the Task tool.** Provide: unit identifier, the per-unit checklist subset, links to the relevant rules and skills.
-3. **Verify parallel-safety conditions** per `rules/hatch3r-agent-orchestration.md` §Parallel Safety — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+3. **Verify parallel-safety conditions** per `rules/hatch3r-agent-orchestration.md` §Parallel Safety — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 4. **Run unit audits in parallel.** Units are independent under the conditions above.
 5. **Aggregate results** into a single CQ report with per-unit rows; deduplicate findings that recur across units (one report at the shared-component level, not one per consumer).
 6. **Serialize only on dependency edges** — aggregation runs after per-unit measurements complete; cross-unit pattern passes run once per-unit outputs are durable.

package/dist/content/agents/shared/user-question-protocol.md

@@ -16,6 +16,7 @@ This protocol defines how hatch3r agents and commands surface clarifying or tria
 
 - **Ambiguous requirement** — the request maps to two or more reasonable interpretations that produce different code.
 - **Irreversible decision** — deleting data, renaming a public API, dropping a column, force-pushing a branch.
+- **Unattested product decision** — the change deletes or transforms user data, or changes user-visible behavior beyond the issue's acceptance criteria, and no user statement (this session, the issue body, or a linked acceptance criterion) authorizes the choice. An agent-authored code comment, PR description, or reviewer note is not attestation — it is self-certification. Surface the ASK; a sub-agent returns `BLOCKED_AMBIGUITY`; an unattended run records the finding as `escalated` in the findings ledger (`rules/hatch3r-findings-ledger.md`) and exits PARTIAL — fail-closed, mirroring `commands/hatch3r-release.md` → "hold — never auto-publish".
 - **Branching path** — two or more viable approaches with materially different cost, scope, or risk.
 - **Conflicting constraints** — requirements that cannot all hold (e.g., "no new dependencies" and "use library X").
 - **Missing acceptance criteria** — no testable definition of done for the requested change.

package/dist/content/checks/code-quality.md

@@ -50,3 +50,14 @@ Review criteria for evaluating code quality in pull requests.
 - `[RECOMMENDED]` No N+1 query patterns in data fetching code.
 - `[RECOMMENDED]` Large collections use pagination or streaming, not full in-memory loading.
 - `[RECOMMENDED]` Expensive operations (crypto, compression, network) are not performed synchronously in request handlers.
+
+## Decision Provenance
+
+- `[CRITICAL]` Every product-behavior assertion in the diff — a comment, commit message, or PR sentence claiming a choice about user data or user-visible behavior ("acceptable to drop", "users won't need", "safe to overwrite") — cites its source: issue number, acceptance-criterion line, or quoted user reply. An assertion with no citable source is self-certification: verdict REQUEST CHANGES plus an ASK to the user.
+- `[RECOMMENDED]` Migration and data-transform files name the approving decision (issue / acceptance criterion / ADR reference) in the file header comment.
+
+## Shared Contracts and Constants
+
+- `[CRITICAL]` A shared constant (rate, default, threshold, enum value) consumed by more than one feature has exactly one defining module; the diff introduces no second independent definition of the same value, and a changed value is edited at its single owner. Verify by grepping the constant name AND the literal value across the repo.
+- `[CRITICAL]` Every changed shared contract (exported symbol, persisted collection/field name, wire field, event name) has a consumer census in the implementation result: each repo-wide consumer of the old identifier is updated, guarded, or justified by name (`rules/hatch3r-contract-census.md`).
+- `[RECOMMENDED]` An intentional divergence from a shared constant's value carries an inline ADR comment naming the owner constant and the reason for the local value.

package/dist/content/checks/security.md

@@ -59,3 +59,8 @@ Review criteria for evaluating security posture in pull requests.
 
 - `[CRITICAL]` Error responses to clients do not include stack traces, internal paths, or database details.
 - `[RECOMMENDED]` Security-relevant errors (auth failures, permission denials) are logged with the five fields an incident responder needs — timestamp, actor/subject identifier, action attempted, resource, and outcome — and never the secret or credential that was rejected.
+
+## Environment Gating
+
+- `[CRITICAL]` Dangerous capabilities (debug endpoints, seed/reset scripts, auth bypasses, mock modes, destructive CLI verbs) are gated by an allowlist of named non-production environments — never by a `NODE_ENV !== 'production'` (or equivalent) denylist. An unset, misspelled, or unrecognized environment value takes the deny branch.
+- `[RECOMMENDED]` The application asserts at startup that its resolved environment value is a member of a closed known-environment enum and refuses to start on an unrecognized value.

package/dist/content/checks/testing.md

@@ -15,8 +15,10 @@ Review criteria for evaluating test coverage and quality in pull requests.
 - `[CRITICAL]` Every new public function or method has at least one unit test.
 - `[CRITICAL]` Code coverage does not decrease from the base branch. New code must be tested.
 - `[CRITICAL]` Bug fix PRs include a regression test that fails without the fix and passes with it.
+- `[CRITICAL]` E2E and integration inputs are non-degenerate: for each changed behavior, at least one test input activates the computation (non-zero rates/amounts, ≥2 records on merge/dedup paths, non-empty collections at every pipeline stage) and the assertion distinguishes the activated result from the no-op result. Named vectors: `rules/hatch3r-testing.md` → Degenerate-Input Guard.
 - `[RECOMMENDED]` Critical path functions (auth, payments, data mutations) have > 90% branch coverage.
 - `[RECOMMENDED]` Edge cases are explicitly tested: empty inputs, boundary values, error conditions, null/undefined.
+- `[RECOMMENDED]` Coverage claims name behaviors, not counts — "N passing" is evidence only when paired with which changed behaviors those N tests activate.
 
 ## Test Quality
 

package/dist/content/commands/board/pickup-delegation-multi.md

@@ -63,7 +63,7 @@ After the shared epic-level research, score each sub-issue individually and run
 
 ### 6b.3. Execute Level-by-Level With Parallel Sub-Agents
 
-Worktree isolation applies here identically to the batch path: when ≥2 implementers run concurrently in a level on a Tier 2/3 run and the platform writes into the orchestrator's tree, isolate each implementer per **Step 6c.3-iso** (`--isolate=auto|on|off`, default `auto`) and integrate via the merge protocol in Step 6b.4. Sub-issues in an epic share file overlap more often than standalone batch issues, so the missed-overlap risk that isolation removes is higher here.
+Worktree isolation applies here identically to the batch path: when ≥2 implementers run concurrently in a level on a Tier 2/3 run and the platform writes into the orchestrator's tree, isolate each implementer per **Step 6c.3-iso** (`--isolate=auto|on|off`, default `auto`) and integrate via the merge protocol in Step 6b.4. Sub-issues in an epic share file overlap more often than standalone batch issues, so the missed-overlap risk that isolation removes is higher here. Seam constraints apply identically to the epic path when sub-issues share a contract — assign per Step 6c.2 item 4.
 
 For each dependency level, starting at Level 1:
 
@@ -116,7 +116,7 @@ For batches of multiple standalone issues (selected via batch mode in Step 1d or
 2. Group issues by dependency level:
    - **Level 1:** Issues with no dependencies on other issues in the batch (can start immediately). Most standalone issues will be Level 1.
    - **Level N:** Issues that depend on other issues in levels < N.
-3. Within each level, all issues are parallelizable (no mutual dependencies — conflicts were moved to separate levels in Step 3).
+3. Within each level, all issues are parallelizable (no mutual dependencies — conflicts were moved to separate levels in Step 3); levels may be adjusted by the contract-overlap cross-check in Step 6c.2 item 4.
 
 ### 6c.2. Context Gathering (Parallel Researchers)
 
@@ -135,6 +135,13 @@ Unlike epics (which share a single researcher), standalone issues in a batch are
 
 3. **Await all researchers.** Collect structured outputs. Each researcher's output feeds exclusively into its corresponding implementer in Step 6c.3. For Tier 2/3 issues, present elicitation questions to the user and await answers before proceeding.
 
+4. **Contract-overlap cross-check + seam-owner assignment:** union the per-issue Breaking Change Candidates tables; any contract (matching location/symbol/name) appearing in ≥2 issues of the same level is a contract collision that Step 3 item 5 either predicted or missed. Resolve before dispatch:
+   - (a) exactly one issue — the one whose acceptance criteria REQUIRE the contract mutation — becomes the seam owner and lands emitter + all consumer reconciliation in one diff;
+   - (b) every peer issue's Step 6c.3 prompt gains the line `Seam constraint: contract <X> is owned by issue #<N> this batch — consume the current shape; do not mutate it`;
+   - (c) when two issues both require mutating the same contract, move the later one to the next dependency level so it consumes the owner's landed shape (`rules/hatch3r-contract-census.md` → Seam-Owner Protocol).
+
+   Record owner assignments; they are re-checked in Step 6c.4.
+
 ### 6c.3-iso. Optional Worktree Isolation (Parallel Implementers, Filesystem Platforms)
 
 Step 3 collision detection predicts file overlap and moves overlapping issues to sequential levels. That prediction is fallible: a missed overlap (Step 3.4) puts two implementers into the orchestrator's single working tree, where concurrent writes to the same file silently clobber each other before the Step 6c.4 post-hoc merge can run. Worktree isolation converts the *predicted* disjointness into *physical* disjointness — each implementer writes into its own `git worktree`, so two implementers cannot touch the same on-disk file even when Step 3 missed the overlap. The existing Step 6c.4 merge protocol becomes the integration step plus the residual-conflict handler for whatever Step 3 missed.
@@ -169,6 +176,7 @@ For each dependency level, starting at Level 1:
    - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
    - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3).
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
+   - **Seam constraints** from Step 6c.2 item 4 (when assigned).
    - Documentation references relevant to this issue.
    - Instruction to follow the **hatch3r-implementer agent protocol**.
    - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
@@ -195,9 +203,10 @@ After all implementer sub-agents complete across all levels:
 2. **File conflict resolution:** When parallel sub-agents modify the same file, apply this resolution protocol:
    - **Disjoint regions:** Accept both changes (non-overlapping edits to different functions/sections).
    - **Overlapping regions:** If changes touch the same lines or function, merge manually using the sub-agent that modified the larger scope as the base, then apply the smaller-scope change on top. Run tests after merge.
-   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts.
+   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts. A semantic conflict on a contract with an assigned seam owner (Step 6c.2 item 4) means a peer violated its seam constraint — name the violating lane when surfacing.
    - **Prevention:** Step 3 (collision detection) should move file-overlapping issues to sequential dependency levels. Conflicts at this stage indicate a missed overlap in Step 3.4.
-3. Verify no regressions between parallel sub-agent outputs.
+3. **Consumer-census verification per lane:** read each implementer's `Consumer census` field. Any `unreconciled` without a named justification → spawn `hatch3r-fixer` for that lane before the Stage-1 review. Then run the cross-lane check: for every contract a seam owner changed, grep the OTHER lanes' diffs for the old identifier — a peer still emitting or reading the old shape violated its seam constraint; route the reconciliation to the seam owner (one diff owns the contract), never patch it in the merge.
+4. Verify no regressions between parallel sub-agent outputs.
 
 ### 6c.5. Post-Implementation Quality Pipeline
 
@@ -206,13 +215,13 @@ After all implementations complete, run the two-stage quality pipeline across th
 **Stage 1 — Review Loop (sequential):**
 
 1. Spawn **`hatch3r-reviewer`** — code review of ALL changes across the batch. Include the full diff and acceptance criteria for each issue. The reviewer sub-agent output MUST include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 4 can evaluate it deterministically.
-2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes — append the W1 write-ahead rows before the fixer dispatch (`rules/hatch3r-findings-ledger.md` → Write Points). When fixes touch shared or public interfaces, also include:
    - **Blast radius data** from Step 6c.2 (if available) — so the fixer knows which consumers and contracts must be preserved.
    - **Reference conventions** from Step 6c.2 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the confidence-aware gate passes. Evaluate the gate per the canonical **Confidence-Aware Review Gate** in `agents/shared/confidence-gate.md`, passing in the resolved `--confidence-floor` (`any` | `medium` | `high`) routed here from `hatch3r-board-pickup` → Confidence Floor. At the default `any` floor: **0 Critical + 0 Warning AND reviewer confidence != low**; if reviewer confidence is low with no Critical/Warning findings, trigger a second reviewer pass before exiting and do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS. At floor `medium` the pass surface is unchanged; at floor `high` a `medium`-confidence clean verdict also forces a second pass (and any low-confidence finding triggers an ASK) — apply the floor-tier branches from the shared gate, do not collapse them to the `any` row.
    After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
-5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed — the ASK lists the open `finding_id`s with legal closures; reconcile the ledger to the run-exit invariant (W3) on exit (`rules/hatch3r-findings-ledger.md` → W3 loop-exit reconciliation); unattended runs record open findings as `escalated` and exit PARTIAL.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**
 
@@ -225,9 +234,10 @@ Launch as many independent sub-agents in parallel as the platform supports.
 **Always evaluate (spawn when applicable):**
 - **hatch3r-docs-writer** — spawn when any changes affect public APIs, architectural patterns, or user-facing behavior.
 
-**Conditional specialists (spawn when triggered by any issue in the batch):**
+**Triggered specialists (spawn when triggered by any issue in the batch):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-ui** (CQ1) — spawn when any issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-ui** (CQ1, mandatory-on-match) — spawn when any implementer's changed files across the batch match the `hatch3r-ui` row of the specialist trigger table (`shouldTriggerSpecialist` / `SPECIALIST_TRIGGER_TABLE` in `src/pipeline/pipelineContext.ts`; prose mirror: `rules/hatch3r-agent-orchestration.md` → Phase 4 Specialist Trigger Table). A match at Tier 2/3 mandates a dedicated `hatch3r-ui` instance regardless of issue labels — skipping it is a gate failure. `area:ui` / `area:a11y` labels are an early planning signal, not a dispatch gate: their absence never skips a matched specialist.
+- **hatch3r-ux** (CQ2, mandatory-on-match) — spawn when any changed file in the batch matches the `hatch3r-ux` row of the same trigger table (flow / route-transition / modal / error-state files, microcopy/i18n strings). When triggered at Tier 2/3, a dedicated `hatch3r-ux` instance is a hard mandate (never merged into the `hatch3r-ui` spawn).
 - **hatch3r-performance** (CQ7) — spawn when any issue has `area:performance` label.
 
 Await all specialist sub-agents. Apply their feedback before proceeding to Step 7.

package/dist/content/commands/board/pickup-delegation.md

@@ -72,13 +72,13 @@ After implementation completes, run the two-stage quality pipeline. Use the Task
 **Stage 1 — Review Loop (sequential):**
 
 1. Spawn **`hatch3r-reviewer`** — code review of all changes. Include the diff and acceptance criteria in the prompt. The reviewer sub-agent output MUST include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 4 can evaluate it deterministically.
-2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes — append the W1 write-ahead rows before the fixer dispatch (`rules/hatch3r-findings-ledger.md` → Write Points). When fixes touch shared or public interfaces, also include:
    - **Blast radius data** from Step 6a.1 (if available) — so the fixer knows which consumers and contracts must be preserved.
    - **Reference conventions** from Step 6a.1 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the confidence-aware gate passes. Evaluate the gate per the canonical **Confidence-Aware Review Gate** in `agents/shared/confidence-gate.md`, passing in the resolved `--confidence-floor` (`any` | `medium` | `high`) routed here from `hatch3r-board-pickup` → Confidence Floor. At the default `any` floor: **0 Critical + 0 Warning AND reviewer confidence != low**; if reviewer confidence is low with no Critical/Warning findings, trigger a second reviewer pass before exiting and do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS. At floor `medium` the pass surface is unchanged; at floor `high` a `medium`-confidence clean verdict also forces a second pass (and any low-confidence finding triggers an ASK) — apply the floor-tier branches from the shared gate, do not collapse them to the `any` row.
    After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
-5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed — the ASK lists the open `finding_id`s with legal closures; reconcile the ledger to the run-exit invariant (W3) on exit (`rules/hatch3r-findings-ledger.md` → W3 loop-exit reconciliation); unattended runs record open findings as `escalated` and exit PARTIAL.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**
 
@@ -91,9 +91,10 @@ Launch as many independent sub-agents in parallel as the platform supports.
 **Always evaluate (spawn when applicable):**
 - **hatch3r-docs-writer** — spawn when changes affect public APIs, architectural patterns, or user-facing behavior. Skip silently if no documentation impact.
 
-**Conditional specialists (spawn when triggered):**
+**Triggered specialists (spawn when triggered):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-ui** (CQ1) — spawn when issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-ui** (CQ1, mandatory-on-match) — spawn when the implementer's changed files match the `hatch3r-ui` row of the specialist trigger table (`shouldTriggerSpecialist` / `SPECIALIST_TRIGGER_TABLE` in `src/pipeline/pipelineContext.ts`; prose mirror: `rules/hatch3r-agent-orchestration.md` → Phase 4 Specialist Trigger Table). A match at Tier 2/3 mandates a dedicated `hatch3r-ui` instance regardless of issue labels — skipping it is a gate failure. `area:ui` / `area:a11y` labels are an early planning signal, not a dispatch gate: their absence never skips a matched specialist.
+- **hatch3r-ux** (CQ2, mandatory-on-match) — spawn when the changed files match the `hatch3r-ux` row of the same trigger table (flow / route-transition / modal / error-state files, microcopy/i18n strings). When triggered at Tier 2/3, a dedicated `hatch3r-ux` instance is a hard mandate (never merged into the `hatch3r-ui` spawn).
 - **hatch3r-performance** (CQ7) — spawn when issue has `area:performance` label or changes touch hot paths.
 
 Each specialist sub-agent prompt MUST include:

package/dist/content/commands/hatch3r-api-spec.md

@@ -30,7 +30,7 @@ sub_agents_spawned:
 | 3. Spec Generation | `hatch3r-docs-writer` | No | Yes |
 | 4. Validation | `hatch3r-reviewer` | No | Yes (if validate mode) |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # API Specification Generator — OpenAPI from Code or Code-vs-Spec Drift Detection
 

package/dist/content/commands/hatch3r-benchmark.md

@@ -30,7 +30,7 @@ sub_agents_spawned:
 | 3. Analysis | `hatch3r-performance` | No | Yes |
 | 4. Reporting | `hatch3r-docs-writer` | No | If regressions found |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # Performance Benchmark — Run, Compare, and Report on Performance Metrics
 

package/dist/content/commands/hatch3r-board-fill.md

@@ -29,7 +29,7 @@ sub_agents_spawned:
 | 2. Issue Creation | Orchestrator (inline, GitHub MCP) | No | Yes |
 | 3. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out (Step 1 explore sub-agents, the Step 7.9 per-issue reviewer/fixer loops where N issues = N parallel loops) holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out (Step 1 explore sub-agents, the Step 7.9 per-issue reviewer/fixer loops where N issues = N parallel loops) holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 All issue operations MUST follow the Board Sync Enforcement rules defined in `hatch3r-board-shared`.
 
@@ -755,7 +755,7 @@ Per-issue loop, max 4 iterations (spec-class cap). Loop semantics mirror `src/pi
 - `DESIGN_OBJECTION` verdict (the issue's intent itself is broken).
 - Oscillation detected: the set of Critical finding IDs has Jaccard similarity >0.8 across two consecutive iterations (the fixer is editing the wrong line).
 
-Issues that hit forced termination are reported in the Step 7.9 summary with the reviewer's last findings. They remain on the board but are flagged for user attention.
+Issues that hit forced termination are reported in the Step 7.9 summary with the reviewer's last findings. They remain on the board but are flagged for user attention. Additionally append one findings-ledger row per forced-terminated issue (`source: spec-review`, severity Warning, file `issue#<N>`, summary = one-line digest of the last reviewer findings) per `rules/hatch3r-findings-ledger.md` — the board flag survives, and the findings text stops being chat-ephemeral.
 
 #### 7.9e. Summary
 

package/dist/content/commands/hatch3r-board-pickup.md

@@ -37,9 +37,9 @@ Pick up an epic (with all sub-issues), a single sub-issue, a standalone issue, o
 | 3b. Final Quality — Testing | `hatch3r-testability` | Yes | Yes (code changes) |
 | 3c. Final Quality — Security | `hatch3r-security` | Yes | Yes (code changes) |
 | 3d. Final Quality — Docs | `hatch3r-docs-writer` | Yes | When APIs/architecture/UX affected |
-| 3e. Final Quality — Conditional | `hatch3r-lint-fixer`, `hatch3r-ui`, `hatch3r-performance` | Yes | When triggered |
+| 3e. Final Quality — Triggered | `hatch3r-lint-fixer`, `hatch3r-performance` (conditional); `hatch3r-ui`, `hatch3r-ux` (mandatory-on-match — each triggered one MUST spawn as its own dedicated instance at Tier 2/3) | Yes | When triggered |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 ## Browser Automation
 
@@ -253,6 +253,7 @@ When multiple issues are selected as a batch:
 2. **Open PRs/MRs:** Search using platform CLI (see platform sub-file).
 3. **Overlap analysis:** Flag hard collisions (same problem/files), soft collisions (related work), or no collision.
 4. **Intra-batch overlap (batch mode):** Check whether any issues within the batch are likely to touch the same files. If so, move conflicting issues to sequential dependency levels rather than parallel.
+5. **Intra-batch contract overlap (batch mode):** scan each issue's body and linked spec (the brownfield spec's Integration-Surface table when present) for named contracts — endpoint paths, collection/table names, event names, exported symbols, shared constants/config keys. Two issues naming the same contract are a contract collision even when their predicted file sets are disjoint: move them to sequential levels, or mark the pair for seam-owner assignment at Step 6c.2 (`rules/hatch3r-contract-census.md` → Seam-Owner Protocol). This is a first-pass textual signal; the authoritative check is the researcher breaking-change cross-check in Step 6c.2.
 
 **If hard collision:** **ASK** with options: proceed / pick different / wait.
 **If soft collision:** **ASK** to proceed with awareness.
@@ -328,7 +329,7 @@ Use the issue type to select the appropriate hatch3r skill: `type:bug` → the h
 
 Before delegating: scan `.hatch3r/learnings/` for matching `area`/`tags`, include relevant learnings (especially `pitfall` category) in sub-agent context. Skip silently if no learnings directory exists.
 
-**Cross-PR finding memory (D13-SA13.1-F08).** Also scan `.hatch3r/review-findings/` (skip silently if absent) for entries whose `applies-to` glob matches the issue's target files; carry the 5 most-recent matches (by `created` descending) forward into the Step 7a reviewer prompt as a `## Cross-PR Findings` block so the reviewer — which declares `consults_cross_pr_findings: true` — weighs prior same-file findings as organisational memory. After the Step 7a review loop terminates clean, append one `.hatch3r/review-findings/<id>.md` entry per Critical/Warning finding resolved (atomic write via `src/merge/safeWrite.ts`), mirroring the Step 10 learnings-capture pattern.
+**Cross-PR finding memory (D13-SA13.1-F08).** Also scan `.hatch3r/review-findings/` (skip silently if absent) for entries whose `applies-to` glob matches the issue's target files; carry the 5 most-recent matches (by `created` descending) forward into the Step 7a reviewer prompt as a `## Cross-PR Findings` block so the reviewer — which declares `consults_cross_pr_findings: true` — weighs prior same-file findings as organisational memory. After the Step 7a review loop terminates clean, append one `.hatch3r/review-findings/<id>.md` entry per Critical/Warning finding resolved (atomic write via `src/merge/safeWrite.ts`), mirroring the Step 10 learnings-capture pattern — derive the entry from the findings-ledger fold and cite its `finding_id` (`rules/hatch3r-findings-ledger.md` → Store Boundaries).
 
 > **Audit epics:** Audit epics produce findings (issues) rather than code changes — adjust delegation and skip Steps 7-8a if no code changes.
 

package/dist/content/commands/hatch3r-bug-pipeline.md

@@ -29,7 +29,7 @@ Before any action, scan the bug report for unresolved questions in scope, accept
 | 2. Regression-Test + Fix | `hatch3r-implementer` (failing test first, then minimal fix) | Per independent module | Yes |
 | 3. Root-Cause-Depth Review | `hatch3r-reviewer` -> `hatch3r-fixer` (max 4 iterations) | No (sequential) | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # Bug Pipeline — Test-First 3-Phase Fix Delegation
 

package/dist/content/commands/hatch3r-bug-plan.md

@@ -29,7 +29,7 @@ sub_agents_spawned:
 | 2. Document Generation | `hatch3r-docs-writer` (investigation report, ADRs) | Yes | Yes |
 | 3. Todo Generation | Orchestrator (inline) | No | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # Bug Plan — Complex Bug Investigation from Symptom to Board-Ready Fix Items
 

package/dist/content/commands/hatch3r-codebase-map.md

@@ -33,7 +33,7 @@ Analyze an existing codebase to reverse-engineer project documentation across **
 | 2. Document Generation | `hatch3r-docs-writer` (parallel: technical spec, business spec, ADRs, health report) | Yes | Yes |
 | 3. AGENTS.md | `hatch3r-docs-writer` (AGENTS.md generation/rework) | No | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 ---
 

package/dist/content/commands/hatch3r-create.md

@@ -49,7 +49,7 @@ If Tier 1, run Phase 1 with reduced prompts (skip optional dimensions). If Tier
 
 **Parallel-dispatch directive:** When two or more steps below are independent (no shared files, no data dependency), issue all tool calls or sub-agent spawns in a single turn. Sequential dispatch of independent work is a finding under P7 (efficiency charter §P2).
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out (multi-artifact runs spawning one creator per artifact) holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out (multi-artifact runs spawning one creator per artifact) holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 ### Step 0.5: Emit Pre-Execution Cost Preview
 

package/dist/content/commands/hatch3r-debug.md

@@ -44,7 +44,7 @@ Standalone debug-and-fix command that instruments the codebase with strategic de
 | 5b. Review Loop | `hatch3r-reviewer` → `hatch3r-fixer` (max 3) | No | Yes |
 | 5c. Final Quality | `hatch3r-testability` + `hatch3r-security` | Yes | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 ---
 

package/dist/content/commands/hatch3r-design-system-create.md

@@ -0,0 +1,254 @@
+---
+id: hatch3r-design-system-create
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-ui, hatch3r-ux]
+description: "Create a project design system from brand assets or an elicitation dialog — DTCG 2025.10 token emission, 3-tier taxonomy (primitive → semantic → component), OKLCH ramps, dual output design.md + design-tokens.json, gated on WCAG 2.2 AA contrast, 100% theme parity, and 0 dangling aliases."
+argument-hint: "[brand-asset-path]"
+tags: [implementation, ui, design-system, floor:ui-ux]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+efficiency_tier: standard
+triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 4
+  rationale: One hatch3r-researcher extracts palette + convention seeds from brand assets (Tier 2/3 only); one hatch3r-implementer writes design-tokens.json + docs/design.md + emission targets (all file mutation flows through the implementer per the Mandatory Delegation Directive); hatch3r-ui and hatch3r-ux run in parallel as the two mandatory validation gates — read-only over the same generated files with disjoint checklist rows. Research → implement → gate are the only serialization edges; every alias resolves into one token graph, so generation stays single-implementer by shared-state dependency, never by token cost. Cost-dominance per CONSTITUTION §2 P8.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity. Per-command triggers: (a) neither a brand-asset path nor an explicit request for the elicitation dialog is present; (b) the Step 1 detect verdict is `reuse` — an existing system is in scope and overwriting it is irreversible; (c) theme set undeclared (light + dark pair vs + high-contrast third set per `rules/hatch3r-theming.md`); (d) emission target undeclared (DTCG JSON only vs + Tailwind v4 `@theme` vs + CSS custom properties); (e) brand hue count ambiguous (one primary vs primary + secondary + accent — each hue gets its own ramp). Proceed without asking ONLY when the asset-vs-dialog path, theme set, and emission target are all explicit. B1 directive: `rules/hatch3r-clarification-default.md`.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Detect existing design system | Orchestrator (inline; runs `hatch3r-design-system-detect` skill, read-only) | No | Yes |
+| 2. Intake / elicitation + ASK gate | Orchestrator (inline) | No | Yes |
+| 3. Brand/asset research | `hatch3r-researcher` | Per asset class | Tier 2/3 only |
+| 4. Generate tokens + docs | `hatch3r-implementer` | No — single token graph | Yes |
+| 5. Validate CQ1 + CQ2 gates | `hatch3r-ui` + `hatch3r-ux` | Yes | Yes |
+| 6. Docs check + Iteration Summary | Orchestrator (inline) | No | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): Stage 5 runs `hatch3r-ui` and `hatch3r-ux` concurrently — both are read-only over the same generated files, their gate rows are disjoint (contrast/alias/parity vs focus-indicator/target-size), and aggregation is deterministic (union of findings). Stage 3 fans out one researcher per asset class (palette + logo vs screenshot corpus vs Figma/tokens-studio export) when Tier 3 supplies more than one. Stage 4 stays single-implementer: every alias resolves into one token graph — shared mutable state, so the no-parallel-writers condition binds; a dependency edge, not a token-cost serialization.
+
+---
+
+# Design System Create -- Brand Assets or Elicitation Dialog → DTCG Tokens + design.md
+
+Creates a project- or workspace-wide design system from brand assets (logo, brand-color list, screenshots, Figma export, tokens-studio JSON) or, when no assets exist, from a structured elicitation dialog. Dual output: `design-tokens.json` (DTCG Format Module 2025.10 — `$type`/`$value`, `{group.token}` aliases) and `docs/design.md` (principles, palette + OKLCH ramps, taxonomy diagram, theme table, usage examples, embedded Accessibility Report). A run passes only when every blocking row of the Step 5 gate table holds: WCAG 2.2 AA contrast on 100% of semantic fg/bg pairs in every theme, 100% theme parity, 0 dangling aliases, 0 component→primitive direct references.
+
+Use `/hatch3r-design-system-create` when the detect verdict is `create` or `extend`. Use the `hatch3r-design-system-detect` skill alone to inventory an existing system without generating; use the `hatch3r-ui-ux-verify` skill to audit built UI against a system that already exists.
+
+---
+
+## Argument Parsing
+
+Optional positional argument: `<brand-asset-path>` — a file or directory of brand assets.
+
+- If supplied: Step 2 reads assets from that path; the elicitation dialog covers only the intake fields the assets leave unanswered.
+- If omitted: Step 2 runs the full elicitation dialog (primary hue, neutral temperature, density, radius scale, motion preference, theme set).
+
+---
+
+## Step 0: Triage
+
+Classify before delegating, using the Light / Standard / Deep vocabulary in `agents/shared/triage-vocabulary.md` (`triage_tiers: [1, 2, 3]` maps 1 = Light, 2 = Standard, 3 = Deep).
+
+- **Tier 1 (Light)** — complete assets (brand hues + neutral readable without research), a single light + dark pair, detect verdict `create`. No researcher: one `hatch3r-implementer` + the two parallel gates.
+- **Tier 2 (Standard)** — the elicitation dialog is needed (no assets, or assets answer only part of the Step 2 intake table) OR the detect verdict is `extend`. One `hatch3r-researcher` pass over whatever assets exist + implementer + gates.
+- **Tier 3 (Deep)** — Figma/tokens-studio import, multi-brand palette, monorepo (workspace-wide token package), or a third theme (high-contrast). One researcher per asset class in parallel + implementer + gates.
+
+An undeclared theme set or emission target fires the §0 gate before tiering. Classify upward on uncertainty (highest-tier rule, `agents/shared/triage-vocabulary.md`).
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Step 2 ASK gate, emit the cost preview per `rules/hatch3r-cost-visibility.md`:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <0-2 researchers by tier + 1 implementer + 2 validation gates>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>   # 0-2 — only for Figma/tokens-studio field-mapping checks
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 6 Iteration Summary recap per `rules/hatch3r-cost-visibility.md`.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Effort Override. Per-command slot: a complete-assets single-pair run misread as Deep because a stray tokens-studio JSON sits in the repo — force `--effort=light`.
+
+---
+
+## Step 1: Detect First (mandatory, read-only)
+
+Invoke the `hatch3r-design-system-detect` skill inline and consume its Design System Inventory (`.audit-workspace/design-system-inventory.md`). This command never re-implements detection — it reads the inventory's token source, color space, component library, and responsive strategy verbatim and treats them as ground truth for Steps 3–4.
+
+Verdict routing (the inventory's `Verdict:` line):
+
+| Verdict | Route |
+|---------|-------|
+| `reuse` | HALT with an actionable pointer: print the existing token source + component library and exit — this command never overwrites a working design system. To audit it instead, run the `hatch3r-ui-ux-verify` skill. |
+| `extend` | Scope generation to the inventory's gaps only (e.g. missing dark theme, missing component tier, hex → OKLCH migration). Existing token names are read-only inputs; the inventory's canonical token-source location overrides the greenfield default. |
+| `create` | Full pipeline, Steps 2–6. |
+
+If the inventory flags multiple token sources, the run is BLOCKED until the maintainer names the canonical one (the detect skill's reconciliation rule) — writing a new source beside them would break the DTCG single-source-of-truth mandate.
+
+---
+
+## Step 2: Intake / Elicitation + ASK Checkpoint (only mutation gate)
+
+Fill the intake table from `<brand-asset-path>` where the assets answer a field; run the structured dialog for the rest. Cache for the Step 4 implementer prompt.
+
+| Input | Default if unspecified | Notes |
+|-------|------------------------|-------|
+| Brand assets | none → full dialog | logo, brand-color list, screenshots, Figma export, tokens-studio JSON |
+| Brand hue(s) | (required — assets or dialog) | 1–3 hues; each hue gets its own OKLCH ramp |
+| Neutral temperature | pure gray | warm / cool / pure — hue bias of the neutral ramp |
+| Density | comfortable | compact / comfortable / spacious — base of the spacing scale |
+| Radius scale | 4px base | none / 4px / 8px / full-round tiers |
+| Motion | 200ms ease + reduced-motion variant | per `rules/hatch3r-theming.md` |
+| Theme set | light + dark | + high-contrast (≥7:1 text, ≥3:1 non-text) per `rules/hatch3r-theming.md` |
+| Emission target | DTCG JSON | + Tailwind v4 `@theme` / + CSS custom properties, per the detect inventory |
+| Token-source location | `tokens/design-tokens.json` (greenfield) | the inventory's canonical location wins on `extend` |
+
+Present ONE consolidated ASK confirming the intake summary — the only mutation gate:
+
+```
+hatch3r-design-system-create — Tier {1|2|3}, verdict: {create|extend}
+
+Intake summary:
+  brand hues: {n} ({oklch values or dialog answers})
+  neutral: {warm|cool|pure} · density: {…} · radius: {…} · motion: {…}
+  themes: light + dark {+ high-contrast}
+  emission: DTCG JSON {+ @theme} {+ CSS vars}
+  taxonomy: primitive → semantic → component
+  output: {token-source location} + docs/design.md
+```
+
+ASK per `agents/shared/user-question-protocol.md`: `accept` — generate and gate; `edit` — change an intake field first; `skip` — cancel, write nothing. After `accept`, the run is autonomous through Step 6.
+
+---
+
+## Step 3: Token Architecture (+ Tier 2/3 asset research)
+
+**Tier 2/3 research (sub-agent delegation).** Delegate asset analysis to `hatch3r-researcher` via the Task tool — one researcher per asset class, in parallel (read-only per that agent's contract). Brief: extract candidate brand hues as OKLCH, spacing/radius conventions visible in screenshots, and a tokens-studio → DTCG field mapping when an export is present. Findings feed the Step 4 implementer prompt. Tier 1 skips this stage — the assets already answer the intake table.
+
+**Taxonomy (all tiers).** Three tiers, aligned with `rules/hatch3r-theming.md` token layering and `rules/hatch3r-component-conventions.md`:
+
+1. **Primitive** — raw scales, no theme awareness: OKLCH ramps (`gray.100`…`gray.900`, `brand.100`…), spacing, radius, type scale.
+2. **Semantic** — role tokens (`color.surface`, `color.text-primary`, `color.border`, `color.brand`, `color.error/success/warning`) aliasing primitives; the theme-switching layer.
+3. **Component** — `btn.text`, `input.border`, … aliasing semantic tokens only.
+
+**Hard rule:** a component token never references a primitive token directly — every component alias resolves through the semantic tier (blocking row, Step 5). This constraint is what makes theme switching a semantic-tier-only override.
+
+---
+
+## Step 4: Generate (sub-agent delegation)
+
+Delegate to `hatch3r-implementer` via the Task tool. ALL file writes flow through the implementer per the Mandatory Delegation Directive — the orchestrator writes nothing inline.
+
+The implementer prompt MUST include the detect inventory, the confirmed intake, the Step 3 research findings, and this contract:
+
+**OKLCH ramps (per brand hue + neutral):** a lightness ramp per hue (10 steps, L ≈ 0.98 → 0.15); for text-role steps hold L fixed and adjust C/H toward the Step 5 contrast thresholds (the apcach pattern — in OKLCH, contrast tracks ΔL, so L placement is the contrast control). Reduce chroma 10–20% on dark-theme surface ramps per `rules/hatch3r-theming.md`.
+
+**DTCG emission (the token-source file):** Format Module 2025.10 — every token carries `$type` + `$value`; aliases use `{group.token}` syntax; groups mirror the 3-tier taxonomy; default location `tokens/design-tokens.json` on greenfield, the inventory's canonical location on `extend`.
+
+**Themes:** light + dark (+ high-contrast when confirmed) as semantic-tier override sets with IDENTICAL semantic key sets — a key present in one theme and absent in another is a blocking Step 5 failure.
+
+**Adapter emission (per detect inventory):** Tailwind v4 `@theme` block and/or `:root` CSS custom properties are generated FROM the DTCG file (Style Dictionary-compatible naming) — derived outputs, never a second authored source.
+
+**Docs:** `docs/design.md` per the Step 6 contract.
+
+Also include: all `scope: always` rule directives; the confidence expression requirement (verbatim, high/medium/low per `agents/shared/quality-charter.md` §1); the boundary "do NOT create branches, commits, or PRs". Await the structured result; capture `Files changed` and the `Delegation proof ID` per file.
+
+---
+
+## Step 5: Validate (parallel sub-agent gates)
+
+After the implementer returns, delegate `hatch3r-ui` and `hatch3r-ux` via the Task tool in parallel. `hatch3r-ui` owns the contrast, alias, parity, reference, and APCA rows (CQ1 acceptance bar: `agents/hatch3r-ui.md` audit checklist); `hatch3r-ux` owns the focus-indicator and touch-target rows (interaction affordances, CQ2). Each prompt carries the generated file paths + its gate rows:
+
+| Gate | Threshold | Blocking |
+|---|---|---|
+| WCAG 2.2 AA contrast (4.5:1 text / 3:1 large + non-text) | 100% of semantic fg/bg pairs, every theme | Yes |
+| Focus-indicator contrast ≥3:1 | 100% of interactive component tokens | Yes |
+| Touch-target sizing tokens ≥44px | 100% | Yes |
+| Dangling aliases | 0 | Yes |
+| Theme parity (identical semantic key set per theme) | 100% | Yes |
+| Component→primitive direct references | 0 | Yes |
+| APCA (Lc ≥60 body / ≥45 large) | advisory | No — recorded in a11y report |
+
+The 44px sizing-token row sits above the WCAG 2.2 AA SC 2.5.8 floor (24×24 CSS px) — size tokens are authored to the platform-HIG bar so consuming components inherit it. A blocking-row failure routes back through `hatch3r-implementer` (max 1 regeneration pass), then re-gates the failed rows only. A persistent blocking failure ends the run at `PARTIAL` with the system flagged not-merge-ready. APCA readings below Lc 60/45 land in the design.md Accessibility Report — advisory, never a halt.
+
+---
+
+## Step 6: Docs + Iteration Summary
+
+Verify `docs/design.md` (written by the Step 4 implementer) carries: principles (the confirmed intake decisions restated as statements), palette + per-hue OKLCH ramp tables, the 3-tier taxonomy diagram, a theme table (semantic keys × themes), usage examples per emission target, and an embedded Accessibility Report (WCAG pass matrix per theme + the APCA advisory readings). Emit the runtime `sub_agents_spawned: {count, rationale}` block with the actual spawn count per `rules/hatch3r-fan-out-discipline.md`.
+
+### End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: `{token-source location}`, `docs/design.md`, emission-target files — all `via hatch3r-implementer`.
+
+### Iteration Summary (mandatory output)
+
+Close the run with the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`: a 1–2 line recap (status, outcome, files · sub-agents · gates · cost delta) plus every exception line whose firing condition holds — silence asserts the default.
+
+```markdown
+## Iteration Summary
+
+**SUCCESS** — Created 2-theme OKLCH design system (1 brand hue + neutral, 3-tier DTCG tokens); ui + ux gates PASS 6/6 blocking rows.
+files 3 (+486/−0) · sa 4/4 · gates 6/6 · cost Δ−8% tok / Δ+3% min · tier 2
+Not done: APCA Lc 58 on `color.text-secondary` (dark) — advisory, recorded in the design.md Accessibility Report
+Next: import the token file into the build (Tailwind `@theme` / Style Dictionary) and point component authors at docs/design.md.
+```
+
+Status decision rules:
+- **SUCCESS** — tokens + docs written, all blocking gate rows PASS, verdict-scoped outputs complete.
+- **PARTIAL** — generated, but a blocking row failed after the single regeneration pass, or a verification command failed.
+- **FAILED** — the implementer returned BLOCKED; nothing written.
+- **BLOCKED** — detect verdict `reuse`, multiple token sources unreconciled, or an intake contradiction the maintainer must rule on.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping: `1` = detect + intake + confirm, `2` = research + implementer generation, `3` = parallel gates + docs + summary. Tier 1 complete-asset runs are exempt per the Tier 1 exemption.
+
+---
+
+## Error Handling
+
+- **Asset unreadable or unsupported format** — name the supported classes (logo image, brand-color list, screenshots, Figma export, tokens-studio JSON) and fall back to the elicitation dialog for the missing fields; never infer a brand hue from a filename.
+- **Multiple token sources in the detect inventory** — BLOCKED until the maintainer names the canonical source (Step 1).
+- **Researcher returns low-confidence hue extraction** — re-open the ASK with the OKLCH candidates as numbered options (residual-ambiguity re-ask per the frame §0); never silently pick one.
+- **Persistent blocking-gate failure after the regeneration pass** — end at PARTIAL, not-merge-ready flag, gate findings quoted verbatim in the Iteration Summary.
+
+## Guardrails
+
+1. **One ASK gate.** Step 2 is the only user-facing checkpoint; after `accept`, the run proceeds through Step 6 (residual-ambiguity re-asks per frame §0 excepted).
+2. **No commit or push.** Generated files are left staged for human review; git operations are out of scope.
+3. **Detect before create.** Step 1 is never skipped; a `reuse` verdict halts the run — this command never overwrites an existing design system.
+4. **Single authored source.** The DTCG file is the only hand-authored token source; `@theme` / CSS-vars outputs are derived from it and regenerated, never edited in place.
+5. **No raw color values outside the primitive tier.** Semantic and component tokens are aliases only (`rules/hatch3r-theming.md` token layering).
+6. **Both gates are mandatory.** A run is never declared SUCCESS without `hatch3r-ui` AND `hatch3r-ux` PASS on every blocking row they own.
+
+## Resumability (Decision 27/30)
+
+design-system-create serializes on the research → generate → gate edges, so checkpoint at the stage boundary — an interrupted run re-enters at the first incomplete stage rather than regenerating the token file it already wrote.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.design-system-workspace/`; step range the Step 1 → Step 6 progression; `wave` = the researcher-batch index in Step 3, then the regeneration-pass index in Step 5; snapshot/rollback paths the token-source file, `docs/design.md`, and every emission-target file the Step 4 implementer touches. Write points: after the Step 1 inventory read, after the Step 2 accept gate, after each Step 3 researcher return, after the Step 4 implementer return, and after each Step 5 gate verdict.
+
+## References
+
+- [W3C Design Tokens Format Module 2025.10](https://www.designtokens.org/tr/drafts/format/) (accessed 2026-07-08, W3C Design Tokens Community Group, official-docs) — `$type`/`$value` token shape, `{group.token}` alias syntax, group nesting, and the single-source mandate; source for the Step 4 emission contract.
+- [Design Tokens specification reaches first stable version](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/) (accessed 2026-07-08, W3C Design Tokens CG, official-docs) — confirms 2025.10 as the first stable release; the version the emission contract pins.
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) (accessed 2026-07-08, W3C, official-docs) — SC 1.4.3 contrast minimums (4.5:1 / 3:1 large), SC 1.4.11 non-text contrast 3:1, SC 2.5.8 target size 24×24; the Step 5 blocking thresholds and the floor the 44px token row exceeds.
+- [apcach](https://github.com/antiflasher/apcach) (accessed 2026-07-08, named-maintainer library, established-library) — composing OKLCH colors to a target contrast by holding L and adjusting C/H; pattern source for the Step 4 ramp recipe and the APCA advisory row (Lc 60 body / 45 large).
+- [Style Dictionary — DTCG support](https://styledictionary.com/info/dtcg/) (accessed 2026-07-08, Style Dictionary maintainers, established-library) — DTCG-input transform surface and derived multi-platform outputs; basis for the derived-emission (never second-source) guardrail.
+- [uxKero/anydesign](https://github.com/uxKero/anydesign) (accessed 2026-07-08, named maintainer, independent-analysis) — prior art: elicitation-dialog → design-system generation; structural source for the Step 2 dialog field set.
+- [arvindrk/extract-design-system](https://github.com/arvindrk/extract-design-system) (accessed 2026-07-08, named maintainer, independent-analysis) — prior art: palette/spacing extraction from existing assets and screenshots; structural source for the Step 3 researcher brief.
+
+Cross-references: `skills/hatch3r-design-system-detect/SKILL.md` (mandatory Step 1 inventory producer) · `rules/hatch3r-theming.md` (token layering, theme sets, dark-theme chroma reduction) · `rules/hatch3r-component-conventions.md` (how downstream components consume the tokens) · `rules/hatch3r-accessibility-standards.md` (WCAG 2.2 AA criteria behind the Step 5 rows) · `agents/hatch3r-ui.md` (CQ1 acceptance bar).

package/dist/content/commands/hatch3r-feature-plan.md

@@ -29,7 +29,7 @@ sub_agents_spawned:
 | 2. Document Generation | `hatch3r-docs-writer` (spec, ADRs) | Yes | Yes |
 | 3. Todo Generation | Orchestrator (inline) | No | Yes |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # Feature Plan — Single Feature Specification from Idea to Board-Ready Epic