hatch3r 1.8.0 → 2.0.0

package/{commands → dist/content/commands}/revision/revision-delegation.md

@@ -42,14 +42,14 @@ For Tier 2/3: cache researcher output (reference conventions, blast radius data)
 |-----------------|-----------|----------|
 | Bugs, missing features, error handling, logic fixes | `hatch3r-implementer` | hatch3r-implementer agent protocol |
 | Dead code, unused imports, type fixes, lint errors | `hatch3r-lint-fixer` | hatch3r-lint-fixer agent protocol |
-| Missing tests, insufficient coverage | `hatch3r-test-writer` | hatch3r-test-writer agent protocol |
+| Missing tests, insufficient coverage | `hatch3r-testability` | hatch3r-testability agent protocol |
 
 ### Blast-Radius-Aware Grouping
 
 When multiple findings affect the same file or module, batch them to a single sub-agent to avoid cross-agent file conflicts:
 
 1. Build a file-to-findings map from all [FIX NOW] items.
-2. Findings in the same file go to the same sub-agent instance, even if they span categories (use the highest-priority specialist: implementer > lint-fixer > test-writer).
+2. Findings in the same file go to the same sub-agent instance, even if they span categories (use the highest-priority specialist: hatch3r-implementer > hatch3r-lint-fixer > hatch3r-testability).
 3. Findings in disjoint files can run in parallel sub-agents.
 4. If findings span independent areas within the same specialist type, spawn one sub-agent per area to parallelize.
 
@@ -63,17 +63,18 @@ Each sub-agent prompt MUST include:
 
 1. The specific findings to address (file paths, line numbers, descriptions, expected behavior).
 2. Instruction to follow the corresponding agent protocol (e.g., "Follow the hatch3r-implementer agent protocol").
-3. All `scope: always` rule directives from `.agents/rules/` — sub-agents do not inherit rules automatically.
+3. All `scope: always` rule directives from `rules/` — sub-agents do not inherit rules automatically.
 4. Acceptance criteria from linked issues (if available from Step 1b).
-5. Relevant learnings from `.agents/learnings/` (if found in Step 1d).
+5. Relevant learnings from `.hatch3r/learnings/` (if found in Step 1d).
 6. Explicit instruction: do NOT create branches, commits, or PRs.
 7. Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
-8. Revision-specific constraint: "You are fixing existing code, not implementing new features. Stay within the architecture established by the original implementation."
+8. `correlation_id` (UUID v4 generated per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID) — the sub-agent echoes it in logs, outputs, and status reports for cross-phase attribution.
+9. Revision-specific constraint: "You are fixing existing code, not implementing new features. Stay within the architecture established by the original implementation."
 
 **When Tier 2/3 research was performed (6.pre):**
 
-9. Reference conventions from `similar-implementation` output — triggers the implementer's Convention Lock step.
-10. Blast radius data from `codebase-impact` output (Tier 3) — transitive dependency trace informing which consumers and contracts the fix must preserve.
+10. Reference conventions from `similar-implementation` output — triggers the implementer's Convention Lock step.
+11. Blast radius data from `codebase-impact` output (Tier 3) — transitive dependency trace informing which consumers and contracts the fix must preserve.
 
 ---
 

package/{commands → dist/content/commands}/revision/revision-modes.md

@@ -61,6 +61,51 @@ Revision Session Report:
 
 ---
 
+## Review-Only Mode (D13-SA13.1-F2)
+
+When invoked with `--review-only`, revision becomes a **read-only code-review surface**: it runs the reviewer against the change set and emits the structured review report, but mutates nothing — no fix implementation, no commit, no push, no learnings write. This is the standalone "review this code, no changes" entry that fills development-workflow activity (3) Code review (`governance/audit/domains/D13-human-ai-collaboration.md` §13.1) — the only other code-facing surfaces (`hatch3r-pr-resolve`, the default `hatch3r-revision` flow) both mutate.
+
+### Behavior Changes in Review-Only Mode
+
+| Step | Normal Mode | Review-Only Mode |
+|------|-------------|------------------|
+| Step 1 Context Reconstruction | Run | Run (diff scope is the review target) |
+| Step 2 Context validation | ASK user | ASK user (confirm review target only) |
+| Step 3 User feedback interview | ASK user for feedback | Skip — the agent is the reviewer, not the interviewer |
+| Step 4 Proactive leftover scan | Run | Run (read-only; findings feed the report, not a fix queue) |
+| Step 5 Findings consolidation + routing | Suggest FIX NOW / DEFER | Consolidate into the report; no routing (nothing is fixed) |
+| Step 6 Fix implementation | Delegate to fixers | **Skipped** — no `hatch3r-implementer` / `hatch3r-fixer` / `hatch3r-lint-fixer` spawn |
+| Step 7 Quality verification | Stage 1 review loop -> Stage 2 specialists | **Single `hatch3r-reviewer` pass only** — no fixer, no re-review loop, no Stage 2 mutation specialists |
+| Step 8 Commit and push | `git add` / `commit` / `push` | **Skipped** — zero git mutation |
+| Step 9 Merge readiness | Verdict + board housekeeping | Emit the review report (see below); no PR-body write, no board mutation |
+| Step 10 Capture learnings | Write `.hatch3r/learnings/` | **Skipped** — no learnings file written |
+
+The single reviewer pass still carries the Confidence Propagation Contract: the reviewer's high/medium/low confidence is surfaced verbatim in the report. The `--confidence-floor` knob is inert in review-only mode (it gates the second-pass/fix loop, which does not run); state that in the report header rather than silently dropping it. `--review-only` and `--auto` are independent — `--auto` only relaxes ASK checkpoints, so `--review-only --auto` runs the read-only review with Step 2 auto-proceeding when a PR + linked issues are found.
+
+### Activation
+
+```
+/hatch3r revision --review-only
+```
+
+### Review Report
+
+In place of the Step 9 merge-readiness assessment, emit a read-only report:
+
+```
+Review-Only Report:
+  Branch: {branch}
+  Diff: {files_changed} files changed (+{additions} / -{deletions})
+  Reviewer confidence: {high/medium/low}
+  Confidence floor: inert (review-only — no fix loop to gate)
+  Critical ({n}): {finding} — {file:line}
+  Warning ({n}):  {finding} — {file:line}
+  Suggestion ({n}): {finding} — {file:line}
+  No changes were made. Run /hatch3r revision (without --review-only) to fix.
+```
+
+---
+
 ## Error Handling
 
 > Platform-specific CLI commands: see `commands/board/shared-{platform}.md` for fallback chains
@@ -68,10 +113,10 @@ Revision Session Report:
 - **Git diff failure**: If `git diff` fails (e.g., no commits on branch, detached HEAD), **ASK** the user for the correct branch or base ref.
 - **No changes detected**: If the diff is empty, inform the user and exit. There is nothing to revise.
 - **PR/issue fetch failure**: Retry once using the platform CLI. If retry fails, proceed without PR/issue context. Work from the diff alone. Warn the user that acceptance criteria are unavailable.
-- **Sub-agent failure**: Retry once. If the retry fails, fall back to direct implementation for that finding.
+- **Sub-agent failure**: Per the shared sub-agent-failure clause in `rules/hatch3r-agent-orchestration.md` -> Cross-Phase Error Propagation: retry once, then re-spawn `hatch3r-fixer` with the failure context for that finding, then `BLOCKED_OTHER` + ASK. Never fall back to inline implementation (issue #73 bypass mode).
 - **Quality check failure after 2 retries**: Present the specific failures and **ASK** the user whether to proceed with a partial fix commit or continue debugging.
 - **Push failure**: Present the error. Common fixes: `git push -u origin {branch}` for new branches, `git pull --rebase` for diverged branches.
-- **Context degradation (>25 turns)**: Suggest starting a fresh chat with a progress summary. The revision command is designed for fresh contexts — it can be re-run.
+- **Context degradation**: per the canonical Context-Degradation Policy (`rules/hatch3r-agent-orchestration-detail.md` -> Context-Degradation Policy) — compress at `>50%` context window, restart at `>75%` (the coarse turn-count fallback is ~25 turns). The revision command is designed for fresh contexts — at the restart threshold, suggest a fresh chat with a progress summary; it can be re-run.
 - **Board sync failure** (when board context exists): Warn and continue. Board sync is advisory in revision — it does not block the fix pipeline.
 
 ---
@@ -82,11 +127,11 @@ Revision Session Report:
 - **Never skip the proactive scan (Step 4)** — even if the user reports no issues. Agents leave leftovers.
 - **Always run quality checks (Step 7)** before committing. Never commit code that fails lint, typecheck, or tests.
 - **Stay within the revision scope.** Fix what was reported and what the scan found. Do not refactor unrelated code, add new features, or expand beyond the original implementation's intent.
-- **Always commit and push** at the end of a revision cycle. The user invoked this command to get fixes merged — do not exit without committing (unless the user explicitly abandons).
+- **Always commit and push** at the end of a revision cycle. The user invoked this command to get fixes merged — do not exit without committing (unless the user explicitly abandons, or `--review-only` is active, in which case there is nothing to commit).
 - **Respect the original implementation's architecture.** Revision fixes issues within the existing patterns. If the architecture itself is flawed, note it as a finding but do not restructure — suggest a separate refactor instead.
 - **One sub-agent per concern.** Delegate to specialist sub-agents based on finding type. Do not ask the implementer to also fix lint issues or write tests.
 - **Git safety.** Never force-push. Never rewrite history. Always create new commits for revision changes.
-- **This command composes existing hatch3r agents** — it does not replace them. The reviewer, implementer, lint-fixer, and test-writer agents handle the actual work.
+- **This command composes existing hatch3r agents** — it does not replace them. The reviewer, implementer, lint-fixer, and hatch3r-testability agents handle the actual work.
 - **Critical findings default to FIX NOW.** If the user overrides this, execute the Critical Deferral Protocol (Step 5b): structured warning with specific risk, require written rationale, record in todo.md with `Critical-deferred` tag, and flag for elevated triage in board-fill. The user is never blocked — rationale adds accountability, not a veto.
 - **Deferred findings go to `todo.md`, not directly to GitHub/GitLab/Azure DevOps issues.** The board-fill pipeline handles triage, epic creation, dependency analysis, and readiness assessment. Revision does not shortcut this process.
 - **Always format deferred items as a single epic block** in `todo.md`, regardless of count. This groups them together during the next board-fill run.

package/{commands → dist/content/commands}/revision/revision-quality.md

@@ -38,18 +38,20 @@ Run an iterative review loop (max 3 iterations) until 0 Critical + 0 Warning fin
 
 The reviewer prompt MUST include:
 - The diff of all changes made (use `git diff` on the working tree).
-- All `scope: always` rule directives from `.agents/rules/`.
+- All `scope: always` rule directives from `rules/`.
 - Iteration number and previous findings (if not the first iteration).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+- `correlation_id` (UUID v4 generated per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID) — the sub-agent echoes it in logs, outputs, and status reports for cross-phase attribution.
 
 **When Tier 2/3 research was performed** (from Step 6.pre):
 - Include blast radius data so the reviewer can verify fixes preserve dependent consumers and contracts.
 - Include reference conventions so the reviewer can verify fixes follow established patterns.
 
-2. Process reviewer output (confidence-aware gate):
+2. Process reviewer output 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-revision` → Confidence Floor. At the default `any` floor:
    - If **0 Critical + 0 Warning AND reviewer confidence != low:** review loop is clean. Proceed to Stage 2.
    - If **0 Critical + 0 Warning AND reviewer confidence == low:** trigger a second reviewer pass before exiting. Do not proceed to Stage 2 until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
-   - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them. When fixes touch shared or public interfaces, include blast radius data and reference conventions in the fixer prompt. Then re-run the reviewer (next iteration).
+   - **Floor tightening:** at floor `medium` the pass surface above is unchanged; at floor `high` a `medium`-confidence clean verdict also triggers a second pass (and any low-confidence finding triggers an ASK). Apply the floor-tier branches from the shared gate — do not collapse `medium`/`high` to the `any` row.
+   - If Critical or Warning findings remain: spawn `hatch3r-fixer` sub-agent to address them. The fixer prompt MUST include `correlation_id` (UUID v4 generated per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID) — the sub-agent echoes it in logs, outputs, and status reports for cross-phase attribution. When fixes touch shared or public interfaces, include blast radius data and reference conventions in the fixer prompt. Then re-run the reviewer (next iteration).
 
 3. If 3 iterations complete and findings remain, **ASK** the user whether to proceed or fix manually.
 
@@ -65,8 +67,8 @@ After the review loop is clean, spawn specialist agents in parallel via the Task
 
 ### Always Spawn (Mandatory for Code Changes)
 
-- **`hatch3r-test-writer`** — write or update tests for code changes. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
-- **`hatch3r-security-auditor`** — security review of code changes. Audit data flows, access control, input validation, and secret management.
+- **`hatch3r-testability`** (CQ5) — verify tests for code changes meet the mandate map / coverage floor. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
+- **`hatch3r-security`** (CQ3) — security review of code changes. Audit data flows, access control, input validation, and secret management.
 
 ### Always Evaluate (Spawn When Applicable)
 
@@ -75,17 +77,18 @@ After the review loop is clean, spawn specialist agents in parallel via the Task
 ### Conditional Specialists (Spawn When Triggered)
 
 - **`hatch3r-lint-fixer`** — spawn when lint errors are present after fix implementation (Step 6 lint-fixer may have missed errors introduced by other sub-agents).
-- **`hatch3r-a11y-auditor`** — spawn when the diff includes UI component changes (`area:ui` or `area:a11y` label on linked issues, or component/style files in the diff).
-- **`hatch3r-perf-profiler`** — spawn when the diff includes hot-path changes (`area:performance` label on linked issues, or changes to database queries, API handlers, rendering loops).
+- **`hatch3r-ui`** (CQ1) — spawn when the diff includes UI component changes (`area:ui` or `area:a11y` label on linked issues, or component/style files in the diff).
+- **`hatch3r-performance`** (CQ7) — spawn when the diff includes hot-path changes (`area:performance` label on linked issues, or changes to database queries, API handlers, rendering loops).
 
 ### Specialist Prompt Requirements
 
 Each specialist sub-agent prompt MUST include:
-- The agent protocol to follow (e.g., "Follow the hatch3r-test-writer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (sub-agents do not inherit rules automatically).
+- The agent protocol to follow (e.g., "Follow the hatch3r-testability agent protocol").
+- All `scope: always` rule directives from `rules/` (sub-agents do not inherit rules automatically).
 - The diff or file changes to review.
 - The linked issue's acceptance criteria (if available).
 - Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+- `correlation_id` (UUID v4 generated per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID) — the sub-agent echoes it in logs, outputs, and status reports for cross-phase attribution.
 
 Await all specialist sub-agents. Apply their feedback (fixes, additional tests, documentation updates). Re-run quality gates (7a) if changes were made.
 

package/dist/content/commands/shared/orchestration-frame.md

@@ -0,0 +1,119 @@
+---
+id: hatch3r-orchestration-frame
+type: shared-context
+description: Single source of truth for cross-cutting orchestrator-command boilerplate — checkpoint contract, cost-estimate block, and Per-Turn Pipeline-State Header. Cited by long-running commands via a one-line pointer instead of restating the blocks.
+tags: [orchestration, reference]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+
+# Orchestration Frame (shared command boilerplate)
+
+> Last updated: 2026-06-09
+> Pillars: P4 (Lean Coverage, primary — kills the ~30-file restatement of these six blocks), P7 (Speed & Token Efficiency, supporting — static cacheable frame).
+
+Six cross-cutting blocks recur near-verbatim across the `commands/hatch3r-*.md` orchestrators (§0 Detect Ambiguity ×30, Confidence Propagation Contract ×26, checkpoint contract ×28, Per-Turn Pipeline-State Header ×29, End-of-Turn Delegation Attestation ×30, `cost_estimate` block ×30 at the D22-4 measurement). This file is their single source of truth. A command cites the block it needs with a one-line pointer and supplies only its per-command slots (ambiguity triggers, workspace directory, step range, doc directories, phase mapping, mutated-file list). The authoritative rule for each block is named in its section; this frame is the command-facing restatement, not a competing definition.
+
+Citation template (drop into the command where the block used to live):
+
+```
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → {§0 Detect Ambiguity | Confidence Propagation Contract | Checkpoint Contract | Cost Estimate | Per-Turn Pipeline-State Header | End-of-Turn Delegation Attestation}. Per-command slot: <the one varying detail — trigger list, workspace dir, phase mapping, mutated-file list, …>.
+```
+
+`<…>` slots below are the only text a command varies; everything outside them is invariant and lives here.
+
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Authoritative rule: `rules/hatch3r-clarification-default.md` (B1 directive); framework-dev mirror `.claude/rules/clarification-default.md`. This is the orchestrator-context body — commands run in the main conversation, so they invoke the platform-native question tool directly (unlike Task-tool sub-agents, which return `BLOCKED_AMBIGUITY` per `agents/shared/clarification-default-block.md`).
+
+Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
+
+Per-command slot: an optional one-line trigger list naming the command's domain-specific ambiguities (e.g. for `hatch3r-auth-scaffold`: "which flow(s) to scaffold, the OIDC issuer, public vs confidential client"). The inline trigger line at the citation site is the single source of truth for that command's triggers; this frame keeps no parallel table.
+
+---
+
+## Confidence Propagation Contract
+
+Authoritative rule: `agents/shared/quality-charter.md` §1 (confidence expression). Every sub-agent delegation prompt in a command MUST include the confidence expression requirement below verbatim. Sub-agents carry the `quality_charter` reference in frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per charter §1.
+
+> Confidence expression requirement: rate every recommendation and finding as high/medium/low confidence per the quality charter (`agents/shared/quality-charter.md`). High = verified against current code. Medium = pattern-based, not fully verified. Low = best judgment, recommend human review.
+
+Downstream propagation: every ASK checkpoint that reports verification quality, every gate that evaluates a sub-agent verdict, and every output block that surfaces `<readiness-kind>` readiness MUST carry a high/medium/low confidence rating sourced from the upstream sub-agent. Dropping the signal between stages is a gate failure.
+
+Per-command slot: `<readiness-kind>` (e.g. plan / spec / merge / map / fix readiness) plus any command-specific propagation points (statistical-significance verdicts, severity classifications, market-research caveats) that carry the signal.
+
+---
+
+## Effort Override (Decision 17)
+
+Authoritative contract: hatch3r's universal `--effort` override ("User overridable via `--effort` flag", CONSTITUTION §6 Decision 17). Auto-tiering can misclassify (a single-module change scored Deep, or a cross-cutting one scored Light); the override is the recovery path. The invariant body:
+
+- `--effort=light|standard|deep` forces the named tier, bypassing the command's Step 0 auto-classification.
+- The override wins over the auto-detected tier; record both the auto-detected tier and the override in the run context so the Cost Estimate block reports the budget delta.
+- No override passed → the auto-classification stands.
+
+Per-command slot: a one-line misclassification example in the command's own domain (e.g. "a single-endpoint doc tweak scored as Deep").
+
+---
+
+## Checkpoint Contract
+
+Authoritative module: `src/pipeline/checkpoint.ts`. Restated here for long-running planning commands (feature-plan, bug-plan, test-plan, migration-plan, refactor-plan, and peers) so an interrupted run re-enters at the last completed step instead of re-running its full fan-out.
+
+1. **Workspace + file:** write `<workspace-dir>/checkpoint.json` via `writeCheckpoint()` (atomic temp+rename through `src/merge/safeWrite.ts`; a SIGKILL mid-write leaves the prior checkpoint or no file, never a partial record). Schema (`schemaVersion: 1`): `phase` (the `<step-range>` progression), `wave` (`<wave-semantics>`, e.g. researcher-batch index across the parallel modes), `status` (`in-progress` | `passed` | `failed`), and `meta` `{ baselineSha, lastPassedGateN, registrySha, timestamp, <slug-or-version-fields> }`.
+2. **Write points:** after each milestone the command declares — context lock, scope ASK, each fan-out batch return, each synthesis ASK confirmation, each file write under `<doc-dirs>`, and the optional chain-to-`hatch3r-board-fill` handoff — so already-generated artifacts survive a crash and are not regenerated on resume. Commands list their own ordered write points.
+3. **`--resume` invocation:** `<command-name> --resume` calls `readCheckpoint()` then `verifyResumability(workspace, currentSha)`. Baseline drift fails closed (the repo or any path under `<doc-dirs>` / `todo.md` changed since the checkpoint) — re-run from scratch or rebase to the checkpoint baseline. A `failed` status halts for operator triage before resuming.
+4. **Snapshot rollback:** pre-mutation snapshots of every path under `<doc-dirs>` and `todo.md` land in `.hatch3r/snapshots/<session-id>/`; `hatch3r rollback --session=<id>` reverts this run's writes. Diff preview precedes every file write per Decision 30.
+
+If `--resume` is passed with no checkpoint, `verifyResumability` returns `drift: "no checkpoint found"` — treat as a cold start.
+
+---
+
+## Cost Estimate
+
+Authoritative rule: `rules/hatch3r-cost-visibility.md`; primitives: `src/pipeline/observability.ts::buildCostBlock` (actuals) and `src/pipeline/costEstimator.ts` (estimate). CONSTITUTION §6 Decision 24/29.
+
+**Pre-execution `cost_estimate`** — emit before the first sub-agent dispatch (5-field schema):
+
+```yaml
+cost_estimate:
+  expected_sa_count: <int>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>      # 0 when no research is needed
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+`expected_sa_count` is calibrated from the command's frontmatter `sub_agents_spawned.count` × the tier heuristic in `rules/hatch3r-cost-visibility.md` → Pre-Execution Estimate. Each command supplies its own per-tier numbers (e.g. `<tier1-count>` / `<tier2-count>` / `<tier3-count>`).
+
+**Post-execution `cost_actuals` + `delta`** — call `buildCostBlock` again with actuals; both land in the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2. Deltas beyond 25% absolute value carry `flagged_for_review: true`. Field contract + delta semantics: `rules/hatch3r-cost-visibility.md`.
+
+---
+
+## Per-Turn Pipeline-State Header
+
+Authoritative rule: `rules/hatch3r-agent-orchestration.md` → Per-Turn Pipeline-State Header. For Tier 2 and Tier 3 runs, emit the header at the start of every assistant turn that touches the task. Tier 1, read-only, and chat-only turns are exempt.
+
+```
+[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
+```
+
+Phase mapping is per-command — each command maps phases `1`–`4` onto its own steps (e.g. `<phase-mapping>`: intake/decomposition → sub-agent dispatch → synthesis → write + iteration-summary). A missing header on a tracked Tier ≥ 2 task is a self-detectable drift signal; the user may halt and re-ground.
+
+---
+
+## End-of-Turn Delegation Attestation
+
+Authoritative rule: `rules/hatch3r-agent-orchestration.md` → End-of-Turn Delegation Attestation. Every turn that mutated files at Tier 2 or Tier 3 emits this block immediately before the Iteration Summary, quoting verbatim each spawned sub-agent's `delegation_proof_id`:
+
+```
+[hatch3r-delegation-attestation]
+files_mutated_this_turn:
+  - <relative path>: via <hatch3r-agent-name> (proof: <delegation_proof_id>)
+mutating_subagent_invocations: <integer>
+inline_edits_by_orchestrator: none
+```
+
+Unattributable rows are a self-declared P8 B2 violation — halt and queue re-delegation next turn. The block sits beside the Iteration Summary, not inside it, preserving the iteration-summary contract verbatim.

package/{github-agents → dist/content/github-agents}/hatch3r-docs-agent.md

@@ -1,9 +1,9 @@
 ---
 name: hatch3r-docs-agent
 type: github-agent
-description: Technical writer who maintains specs, ADRs, and documentation
+description: 'Technical writer who maintains specs, ADRs, and documentation'
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -11,6 +11,26 @@ cache_friendly: true
 
 You are an expert technical writer for the project.
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the brief for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (which docs, whether a spec section may be restructured, which stable IDs apply). If any are found, ask via the platform-native question surface per `agents/shared/user-question-protocol.md` — for GitHub Copilot/Codex cloud agents, that surface is a PR comment or issue clarification. Do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-file, single-concern, and the brief alone is testable.
+
+### Plain-Text Fallback Template (D5-M6)
+
+When the runtime has no platform-native question tool (GitHub Copilot/Codex cloud agents post to a PR comment or issue body — plain Markdown), emit the question using this exact shape:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules: 2-4 numbered options, each with a one-line trade-off; the `Default if no response:` line is mandatory and names the safest reversible choice. Do not silent-pick — if no default was emitted with the question, return `BLOCKED_AMBIGUITY` in the structured result instead of guessing.
+
 ## Your Role
 
 - You read code from `src/` and backend directories and update documentation in `docs/`.

package/dist/content/github-agents/hatch3r-lint-agent.md

@@ -0,0 +1,66 @@
+---
+name: hatch3r-lint-agent
+type: github-agent
+description: 'Code quality enforcer who fixes style, formatting, and type issues'
+# Simplified agent for GitHub Copilot/Codex
+tags: [devops, ctx:team-only]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+You are a code quality engineer for the project.
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the brief for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (which files or lint rulesets are in scope, whether an exported symbol may be renamed, whether a style fix risks altering behavior). If any are found, ask via the platform-native question surface per `agents/shared/user-question-protocol.md` — for GitHub Copilot/Codex cloud agents, that surface is a PR comment or issue clarification. Do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-file, single-concern, and the brief alone is testable.
+
+### Plain-Text Fallback Template (D5-M6)
+
+When the runtime has no platform-native question tool (GitHub Copilot/Codex cloud agents post to a PR comment or issue body — plain Markdown), emit the question using this exact shape:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules: 2-4 numbered options, each with a one-line trade-off; the `Default if no response:` line is mandatory and names the safest reversible choice. Do not silent-pick — if no default was emitted with the question, return `BLOCKED_AMBIGUITY` in the structured result instead of guessing.
+
+## Your Role
+
+- You fix ESLint errors, Prettier formatting, TypeScript strict mode violations, and naming convention issues.
+- You identify and remove dead code, unused imports, and obsolete comments.
+- You never change code logic — only style and structure.
+- Your output: clean, consistently formatted code that passes all lint checks.
+
+## Project Knowledge
+
+- **Conventions (adapt to project):**
+  - Functions: camelCase
+  - Types/Interfaces: PascalCase
+  - Constants: SCREAMING_SNAKE
+  - Component files: PascalCase.vue (or project equivalent)
+  - Logic files: camelCase.ts
+  - No `any` types (use `unknown` + type guards)
+  - No `// @ts-ignore` without linked issue
+  - Max function length: 50 lines
+  - Max file length: 400 lines
+  - Cyclomatic complexity: ≤ 10
+
+## Commands You Can Use
+
+- Lint check: `npm run lint`
+- Auto-fix: `npm run lint:fix`
+- Type check: `npm run typecheck`
+- Run tests (to verify no behavior change): `npm run test`
+
+## Boundaries
+
+- **Always:** Run `npm run lint:fix`, then `npm run typecheck`, then `npm run test` to verify
+- **Ask first:** Before renaming exported symbols that might be used across modules
+- **Never:** Change code logic or behavior, add new features, modify test assertions, remove code that has side effects

package/{github-agents → dist/content/github-agents}/hatch3r-security-agent.md

@@ -1,9 +1,9 @@
 ---
 name: hatch3r-security-agent
 type: github-agent
-description: Security analyst who audits code, rules, and data flows
+description: 'Security analyst who audits code, rules, and data flows'
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [devops, floor:security, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -11,6 +11,26 @@ cache_friendly: true
 
 You are an expert security analyst for the project.
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the brief for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (which threat model or trust boundary applies, whether a security rule may be loosened, which collections or endpoints are in scope). If any are found, ask via the platform-native question surface per `agents/shared/user-question-protocol.md` — for GitHub Copilot/Codex cloud agents, that surface is a PR comment or issue clarification. Do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-file, single-concern, and the brief alone is testable.
+
+### Plain-Text Fallback Template (D5-M6)
+
+When the runtime has no platform-native question tool (GitHub Copilot/Codex cloud agents post to a PR comment or issue body — plain Markdown), emit the question using this exact shape:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules: 2-4 numbered options, each with a one-line trade-off; the `Default if no response:` line is mandatory and names the safest reversible choice. Do not silent-pick — if no default was emitted with the question, return `BLOCKED_AMBIGUITY` in the structured result instead of guessing.
+
 ## Your Role
 
 - You audit database security rules, API endpoints, event metadata, and data flows.

package/{github-agents → dist/content/github-agents}/hatch3r-test-agent.md

@@ -1,9 +1,9 @@
 ---
 name: hatch3r-test-agent
 type: github-agent
-description: QA engineer who writes and maintains tests
+description: 'QA engineer who writes and maintains tests'
 # Simplified agent for GitHub Copilot/Codex
-tags: [team, devops]
+tags: [review, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -11,6 +11,26 @@ cache_friendly: true
 
 You are an expert QA engineer for the project.
 
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the brief for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (which behavior is under test, whether an existing test may be modified or deleted, which coverage target applies). If any are found, ask via the platform-native question surface per `agents/shared/user-question-protocol.md` — for GitHub Copilot/Codex cloud agents, that surface is a PR comment or issue clarification. Do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-file, single-concern, and the brief alone is testable.
+
+### Plain-Text Fallback Template (D5-M6)
+
+When the runtime has no platform-native question tool (GitHub Copilot/Codex cloud agents post to a PR comment or issue body — plain Markdown), emit the question using this exact shape:
+
+```
+**Question:** <one-sentence question stating the choice>
+
+1. <Option A> — <one-line rationale or trade-off>
+2. <Option B> — <one-line rationale or trade-off>
+3. <Option C> — <one-line rationale or trade-off>
+
+Default if no response: <option number, e.g., 2>
+```
+
+Rules: 2-4 numbered options, each with a one-line trade-off; the `Default if no response:` line is mandatory and names the safest reversible choice. Do not silent-pick — if no default was emitted with the question, return `BLOCKED_AMBIGUITY` in the structured result instead of guessing.
+
 ## Your Role
 
 - You write unit tests, integration tests, contract tests, and E2E tests.

package/{hooks → dist/content/hooks}/hatch3r-ci-failure.md

@@ -4,7 +4,7 @@ type: hook
 event: ci-failure
 agent: ci-watcher
 description: Diagnose CI pipeline failures
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -22,7 +22,7 @@ When this hook fires, the assigned agent should:
 4. For test failures: identify the specific failing test(s), expected vs. actual values, and the source file(s) involved.
 5. For build/type errors: extract the compiler error message and the source location.
 6. Produce a root-cause hypothesis with a concrete suggested fix (code change, config change, or retry recommendation for flaky failures).
-7. If the failure matches a known pattern from `.agents/learnings/`, reference the relevant learning.
+7. If the failure matches a known pattern from `.hatch3r/learnings/`, reference the relevant learning.
 
 ## Expected Output
 
@@ -33,7 +33,7 @@ A structured diagnostic report containing:
 - **Root cause**: Concise explanation of why the failure occurred.
 - **Error excerpt**: The relevant log output (truncated to key lines).
 - **Suggested fix**: Specific, actionable remediation steps.
-- **Related learnings**: Links to any matching entries in `.agents/learnings/` (if applicable).
+- **Related learnings**: Links to any matching entries in `.hatch3r/learnings/` (if applicable).
 
 ## Configuration
 

package/{hooks → dist/content/hooks}/hatch3r-file-save.md

@@ -5,7 +5,7 @@ event: file-save
 agent: context-rules
 description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -17,7 +17,7 @@ Activate context-specific rules when a file is saved, applying relevant coding s
 
 When this hook fires, the assigned agent should:
 
-1. Determine the saved file's path and match it against the project's rule definitions in `.agents/rules/`.
+1. Determine the saved file's path and match it against the project's rule definitions in `rules/`.
 2. Load all rules where `scope: always` applies, plus any rules with glob patterns matching the saved file's path.
 3. Evaluate the saved file's contents against the loaded rules — check for convention violations, pattern mismatches, or missing required elements (e.g., missing error handling in API routes, missing accessibility attributes in components).
 4. If violations are found, surface them as inline warnings or suggestions (not blocking — file-save hooks should be non-disruptive).
@@ -31,5 +31,5 @@ When this hook fires, the assigned agent should:
 ## Configuration
 
 - **Globs**: Controlled by the `globs` frontmatter field. Adjust to match your project's source file extensions.
-- **Rule sources**: Reads from `.agents/rules/`. Rules with matching `globs` or `scope: always` are activated.
-- **Debounce**: To avoid excessive processing during rapid saves, the agent debounces with a 2-second window (configurable via `debounceMs`).
+- **Rule sources**: Reads from `rules/`. Rules with matching `globs` or `scope: always` are activated.
+- **Debounce**: To avoid excessive processing during rapid saves, the agent debounces with a 2-second window (configurable via `debounceMs`). Coalescing is trailing-edge — within the debounce window the most-recent save wins and the hook fires once, `debounceMs` after the last save event; intermediate saves in the window do not fire.

package/{hooks → dist/content/hooks}/hatch3r-post-merge.md

@@ -4,7 +4,7 @@ type: hook
 event: post-merge
 agent: ci-watcher
 description: Check CI pipeline status after merge
-tags: [core]
+tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-commit.md

@@ -5,7 +5,7 @@ event: pre-commit
 agent: lint-fixer
 description: Auto-fix lint and formatting issues before commit
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
-tags: [core]
+tags: [implementation]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---

package/{hooks → dist/content/hooks}/hatch3r-pre-push.md

@@ -1,16 +1,16 @@
 ---
-id: pre-push-security-auditor
+id: pre-push-security
 type: hook
 event: pre-push
-agent: security-auditor
+agent: security
 description: Scan for secrets and security issues before push
-tags: [core]
+tags: [floor:security]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
-# Hook: pre-push → security-auditor
+# Hook: pre-push → security
 
-Activate the security-auditor agent before pushing to scan for accidentally committed secrets, API keys, credentials, and other security-sensitive content.
+Activate the security agent before pushing to scan for accidentally committed secrets, API keys, credentials, and other security-sensitive content.
 
 ## Agent Behavior
 
@@ -29,6 +29,6 @@ When this hook fires, the assigned agent should:
 
 ## Configuration
 
-- **Allowlist**: Add known false positives to `.agents/security/secret-allowlist.json` (patterns or file paths to ignore).
-- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.agents/security/custom-patterns.json`.
+- **Allowlist**: Add known false positives to `.hatch3r/security/secret-allowlist.json` (patterns or file paths to ignore).
+- **Pattern extensions**: The agent uses built-in patterns for common secret types. Add project-specific patterns via `.hatch3r/security/custom-patterns.json`.
 - **Scope**: By default, scans only the diff of outgoing commits. Set `scanFullHistory: true` to scan all files (slower, useful for initial audits).