hatch3r 1.8.0 → 2.0.0

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

@@ -63,9 +63,11 @@ 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.
+
 For each dependency level, starting at Level 1:
 
-1. **Spawn one implementer sub-agent per sub-issue in the current level.** Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports.
+1. **Spawn one implementer sub-agent per sub-issue in the current level.** Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports. When worktree isolation is active (per the note above), create one scratch worktree per implementer first and pin each sub-agent to its `.worktrees/pickup-iso-<sub-issue-number>/` path.
 
 2. **Each sub-agent prompt must include:**
    - The sub-issue number, title, full body, and acceptance criteria.
@@ -78,17 +80,19 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
    - Documentation references relevant to this sub-issue.
    - Instruction to follow the hatch3r-implementer agent protocol.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Instruction to use GitHub MCP for issue reads, and follow the project's tooling hierarchy for external knowledge augmentation.
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID; each epic sub-issue gets its own id).
    - 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.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
 4. **Review sub-agent results:**
    - If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, fix manually, retry).
-   - If sub-agents modified overlapping files, review for conflicts and resolve before proceeding.
+   - **When worktree isolation was active for this level** (Step 6c.3-iso, applied per the 6b.3 note): integrate each scratch worktree's file diff back onto the branch via the Step 6b.4 conflict-resolution step, then run `npx hatch3r worktree-cleanup --yes` before advancing.
+   - If sub-agents modified overlapping files (or the isolated integration above surfaced an overlap Step 3 missed), review for conflicts and resolve before proceeding.
 
 5. **Advance to the next dependency level.** Repeat steps 1-4 until all levels are complete.
 
@@ -97,7 +101,7 @@ For each dependency level, starting at Level 1:
 After all sub-agents complete:
 
 1. Run a combined quality check across all changes.
-2. Resolve any cross-sub-issue integration issues.
+2. Resolve any cross-sub-issue integration issues — when isolation ran, this is where each worktree's diff lands on the branch; physically disjoint writes apply cleanly and only Step-3-missed overlaps need manual resolution.
 3. Verify no file conflicts between parallel sub-agent outputs.
 
 ---
@@ -131,11 +135,31 @@ 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.
 
+### 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.
+
+**Isolation gate — `--isolate=auto|on|off` (default `auto`).** Under `auto`, isolate this level when ALL three hold:
+
+1. **Concurrency:** ≥2 implementer sub-agents are dispatched into this level (a single implementer has no peer to collide with — skip isolation).
+2. **Tier:** the run is Tier 2 or Tier 3 batch mode (Step 0 auto-tier or the `--effort` override per `hatch3r-board-pickup` → Effort Override). Tier 1 batches skip isolation — their trivial edits carry low overlap risk and the worktree setup/cleanup cost is not justified.
+3. **Platform writes to the orchestrator's filesystem:** the platform applies sub-agent file edits into the orchestrator's working tree (CLI platforms — e.g. Claude Code Task sub-agents share the orchestrator's tree). Set this condition false for hosted platforms that sandbox each sub-agent in a separate per-agent workspace and merge results outside the orchestrator tree — those platforms already provide disjoint writes, so a second worktree layer adds no isolation.
+
+`--isolate=on` forces isolation whenever ≥2 implementers run (overrides the tier/platform conditions); `--isolate=off` keeps the legacy single-tree path (Step 6c.3 dispatches directly into the orchestrator's tree, relying solely on Step 3 prediction + the Step 6c.4 post-hoc merge). Resolution order: explicit `--isolate` flag wins over the `auto` default.
+
+**When isolation is active for a level, wrap Step 6c.3 dispatch as follows:**
+
+1. **Create one scratch worktree per implementer.** For each issue in the level, run `npx hatch3r worktree-setup pickup-iso-<issue-number> --yes` (the `--yes` flag suppresses the interactive secret-propagation confirmation for the non-interactive orchestrator; review `.worktree-include` first if `.env.*` files are in scope per the command's CWE-552 blast-radius warning). Each worktree lands on a throwaway branch under `.worktrees/pickup-iso-<issue-number>/` and is populated + `hatch3r sync`-ed by the command. These are scratch isolation directories, not per-issue PR branches — the batch keeps its single shared branch (per `hatch3r-board-pickup` Step 5), and changes are integrated back onto it in Step 6c.4.
+2. **Pin each implementer to its worktree.** In the Step 6c.3 per-agent prompt, set the sub-agent's working directory to its `.worktrees/pickup-iso-<issue-number>/` path and instruct it to read, edit, and run tests only within that path. The "do NOT create branches, commits, or PRs" instruction is unchanged — the orchestrator still owns all git operations; the throwaway worktree branch exists only to give `git worktree add` a ref and is never pushed.
+3. **Integrate and clean up after the level returns.** After all implementers in the level return (Step 6c.3 step 3), integrate each worktree's file diff back onto the batch branch in the orchestrator's main tree via the **Step 6c.4 file-conflict resolution protocol** — physically disjoint writes apply cleanly; any genuinely overlapping or semantically conflicting edits Step 3 missed surface there for resolution exactly as in the non-isolated path. Then run `npx hatch3r worktree-cleanup --yes` to remove the scratch worktrees and prune their throwaway branches. On a non-zero `worktree-setup`/`worktree-cleanup` exit, surface the error and **ASK** the user (retry, fall back to `--isolate=off` for the remaining levels, or abort) — never silently drop isolation mid-run.
+
 ### 6c.3. Execute Level-by-Level With Parallel Implementers
 
 For each dependency level, starting at Level 1:
 
-1. **Spawn one hatch3r-implementer sub-agent per issue in the current level.** Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports.
+0. **Resolve worktree isolation for this level** per Step 6c.3-iso. When isolation is active, create the per-implementer scratch worktrees (6c.3-iso step 1) before dispatching, and pin each sub-agent to its worktree path (6c.3-iso step 2). When inactive, dispatch directly into the orchestrator's tree as below.
+
+1. **Sort the level by priority, then spawn one hatch3r-implementer sub-agent per issue.** Within each level, sort issues by priority (`p0` > `p1` > `p2` > `p3`) before dispatching. When the platform concurrency limit caps the level, fill the in-flight pool with the highest-priority issues first and queue the rest for the next dispatch slot as in-flight sub-agents return. Issues within a level are independent for correctness; this ordering only governs which independent issues land first when concurrency is the binding constraint. Use the Task tool with `subagent_type: "generalPurpose"`. Launch as many sub-agents concurrently as the platform supports.
 
 2. **Each sub-agent prompt must include:**
    - The issue number, title, full body, and acceptance criteria.
@@ -147,16 +171,19 @@ For each dependency level, starting at Level 1:
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
    - Documentation references relevant to this issue.
    - Instruction to follow the **hatch3r-implementer agent protocol**.
-   - All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-   - Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+   - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+   - Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
    - Explicit instruction: do NOT create branches, commits, or PRs.
+   - **When worktree isolation is active for this level** (Step 6c.3-iso): the sub-agent's working directory set to its `.worktrees/pickup-iso-<issue-number>/` path, with the instruction to read, edit, and run tests only within that path.
+   - `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID; batch tasks share one id with a per-issue sub-task index).
    - 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.
 
 3. **Await all sub-agents in the current level.** Collect their structured results (files changed, tests written, issues encountered).
 
 4. **Review sub-agent results:**
    - If any sub-agent reports BLOCKED or PARTIAL, **ASK** the user how to proceed (skip, fix manually, retry).
-   - If sub-agents modified overlapping files, review for conflicts and resolve before proceeding.
+   - **When worktree isolation was active for this level** (Step 6c.3-iso): integrate each scratch worktree's file diff back onto the batch branch via the Step 6c.4 file-conflict resolution protocol, then run `npx hatch3r worktree-cleanup --yes` to remove the worktrees and prune their throwaway branches before advancing (6c.3-iso step 3).
+   - If sub-agents modified overlapping files (or the isolated integration above surfaced an overlap Step 3 missed), review for conflicts and resolve before proceeding.
 
 5. **Advance to the next dependency level.** Repeat steps 1-4 until all levels are complete.
 
@@ -183,7 +210,7 @@ After all implementations complete, run the two-stage quality pipeline across th
    - **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: **0 Critical + 0 Warning AND reviewer confidence != low**. If reviewer confidence is low but there are no Critical/Warning findings, trigger a second reviewer pass before exiting the loop; do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
+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.
 
@@ -192,15 +219,15 @@ After all implementations complete, run the two-stage quality pipeline across th
 Launch as many independent sub-agents in parallel as the platform supports.
 
 **Always spawn (mandatory for every code change):**
-- **hatch3r-test-writer** — tests for all code changes across the batch.
-- **hatch3r-security-auditor** — security review of all code changes across the batch.
+- **hatch3r-testability** (CQ5) — verify tests for all code changes across the batch meet the mandate map / coverage floor.
+- **hatch3r-security** (CQ3) — security review of all code changes across the batch.
 
 **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):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-a11y-auditor** — spawn when any issue has `area:ui` or `area:a11y` labels.
-- **hatch3r-perf-profiler** — spawn when any issue has `area:performance` label.
+- **hatch3r-ui** (CQ1) — spawn when any issue has `area:ui` or `area:a11y` labels.
+- **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/{commands → dist/content/commands}/board/pickup-delegation.md

@@ -57,9 +57,10 @@ The implementer sub-agent prompt MUST include:
 - **Blast radius data** from enhanced `codebase-impact` (Tier 3) — transitive dependency trace and API consumer map.
 - Documentation references relevant to this issue.
 - Instruction to follow the **hatch3r-implementer agent protocol**.
-- All `scope: always` rule directives from `.agents/rules/` — subagents do not inherit rules automatically.
-- Relevant learnings from `.agents/learnings/` (from Step 6.pre).
+- All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
+- Relevant learnings from `.hatch3r/learnings/` (from Step 6.pre).
 - Explicit instruction: do NOT create branches, commits, or PRs.
+- `correlation_id` (UUID v4 generated per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID; epic sub-issues get individual ids, batch tasks share one id with a sub-task index).
 - 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.
 
 Await the implementer sub-agent. Collect its structured result (files changed, tests written, issues encountered).
@@ -75,7 +76,7 @@ After implementation completes, run the two-stage quality pipeline. Use the Task
    - **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: **0 Critical + 0 Warning AND reviewer confidence != low**. If reviewer confidence is low but there are no Critical/Warning findings, trigger a second reviewer pass before exiting the loop; do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS.
+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.
 
@@ -84,22 +85,23 @@ After implementation completes, run the two-stage quality pipeline. Use the Task
 Launch as many independent sub-agents in parallel as the platform supports.
 
 **Always spawn (mandatory for every code change):**
-- **hatch3r-test-writer** — tests for all code changes. Unit tests for new logic, regression tests for bug fixes, integration tests for cross-module changes.
-- **hatch3r-security-auditor** — security review of all code changes. Audit data flows, access control, input validation, and secret management.
+- **hatch3r-testability** (CQ5) — verify tests for all 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 all code changes. Audit data flows, access control, input validation, and secret management.
 
 **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):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-a11y-auditor** — spawn when issue has `area:ui` or `area:a11y` labels.
-- **hatch3r-perf-profiler** — spawn when issue has `area:performance` label or changes touch hot paths.
+- **hatch3r-ui** (CQ1) — spawn when issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-performance** (CQ7) — spawn when issue has `area:performance` label or changes touch hot paths.
 
 Each specialist sub-agent prompt MUST include:
 - The agent protocol to follow (e.g., "Follow the hatch3r-reviewer agent protocol").
-- All `scope: always` rule directives from `.agents/rules/` (subagents do not inherit rules automatically).
+- All `scope: always` rule directives from `rules/` (subagents do not inherit rules automatically).
 - The diff or file changes to review.
 - The issue's acceptance criteria.
+- `correlation_id` (UUID v4 per top-level task per `rules/hatch3r-agent-orchestration.md` → Correlation ID).
 - 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.
 
 Await all specialist sub-agents. Apply their feedback (fixes, additional tests, documentation updates) before proceeding to Step 7.

package/{commands → dist/content/commands}/board/pickup-github.md

@@ -56,7 +56,7 @@ Follow the **GitHub Projects V2 Sync** from `commands/board/shared-github.md` fo
 **Create PR:**
 `gh pr create -R {owner}/{repo} --head {branch} --base {base} --title "..." --body "..."` (fall back to `create_pull_request` MCP).
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link PR to epic:**
 `gh issue comment {epic} -R {owner}/{repo} --body "PR: #{pr_number}"` (fall back to `add_issue_comment` MCP).

package/{commands → dist/content/commands}/board/pickup-gitlab.md

@@ -56,7 +56,7 @@ Follow the **GitLab Board Label-Based Sync** from `commands/board/shared-gitlab.
 **Create MR:**
 `glab mr create -R {namespace}/{project} --source-branch {branch} --target-branch {base} --title "..." --description "..."`. Use `Closes #N` syntax in the description for auto-close on merge.
 
-`{base}` = `board.defaultBranch` from `.agents/hatch.json` (fallback: `"main"`).
+`{base}` = `board.defaultBranch` from `.hatch3r/hatch.json` (fallback: `"main"`).
 
 **Link MR to epic:**
 Reference the epic issue number in the MR description. GitLab auto-links MRs to issues mentioned with `Closes #N`.

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

@@ -126,6 +126,7 @@ At the end of an auto session, generate a summary:
 - **Issue update failure:** warn and continue (labels not blocking).
 - **Quality verification failure:** fix before creating PR/MR.
 - **PR/MR creation failure:** present error and manual instructions.
+- **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 (inherited from `hatch3r-workflow`) is ~25 turns, at which point suggest splitting the batch or starting a fresh context with a progress summary of completed and remaining issues.
 
 ---
 

package/{commands → dist/content/commands}/board/pickup-post-impl.md

@@ -118,7 +118,7 @@ After the PR merges and `Closes #N` auto-closes the referenced issue(s), confirm
    ```
    Record the mutation in the run cache under `updated_issues`.
 
-2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.agents/hatch.json`:
+2. **Board state check.** Read `board.workflows.itemClosedEnabled` from `.hatch3r/hatch.json`:
    - **If true:** The V2 built-in "Item closed" workflow has already set the board status to Done. Skip to step 3.
    - **If false or absent:** The workflow is not enabled (board-init should have halted, but this is a defensive fallback). Apply the full **Board Sync Procedure** from `hatch3r-board-shared` for each issue, target status = Done.
 
@@ -142,7 +142,7 @@ After PR creation, capture learnings from this development session.
    - Were any pitfalls discovered that should be avoided next time?
 
 2. If learnings are identified:
-   - Create learning files in `.agents/learnings/` following the learning file format (see `hatch3r-learn` command).
+   - Create learning files in `.hatch3r/learnings/` following the learning file format (see `skills/hatch3r-learn/SKILL.md`).
    - Include the issue number as `source-issue`.
    - Tag with relevant area labels from the issue.
    - **ASK:** "Learnings captured: {list}. Anything else to note? (add more / done)"

package/{commands → dist/content/commands}/board/shared-azure-devops.md

@@ -56,7 +56,7 @@ Use `az devops` / `az boards` / `az repos` CLI. Issues = Work Items. PRs = Pull
 
 ## Azure DevOps Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Organization:** top-level `owner` (maps to Azure DevOps organization name)
 - **Project:** top-level `repo` (maps to Azure DevOps project name)

package/{commands → dist/content/commands}/board/shared-github.md

@@ -56,7 +56,7 @@ Use `gh` CLI and GitHub MCP tools. Issues = GitHub Issues. PRs = Pull Requests.
 
 ## GitHub Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Owner:** top-level `owner` (fallback: `board.owner`)
 - **Repository:** top-level `repo` (fallback: `board.repo`)
@@ -89,7 +89,7 @@ If `board.projectNumber` is not null, verify via `gh project view {board.project
 
 **Status label → Projects v2 option mapping:**
 
-Read the mapping from `board.statusOptions` in `.agents/hatch.json`:
+Read the mapping from `board.statusOptions` in `.hatch3r/hatch.json`:
 
 | Label                | Option ID from hatch.json          |
 | -------------------- | ---------------------------------- |

package/{commands → dist/content/commands}/board/shared-gitlab.md

@@ -49,7 +49,7 @@ GitLab MCP tools are not currently available. All operations use the `glab` CLI.
 
 ## GitLab Context
 
-Derived from `.agents/hatch.json` board config:
+Derived from `.hatch3r/hatch.json` board config:
 
 - **Namespace:** top-level `owner` (GitLab group or user namespace)
 - **Project:** top-level `repo` (GitLab project name)

package/{commands → dist/content/commands}/hatch3r-api-spec.md

@@ -9,15 +9,17 @@ quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
 parallel_tool_default: true
+efficiency_tier: deep
 triage_tiers: [1, 2, 3]
+supports_resume: true
 sub_agents_spawned:
   count: 3
-  rationale: Three-stage pipeline per agentPipeline — researcher scans routes, docs-writer assembles the OpenAPI spec, reviewer validates structure; researcher and reviewer fanned out concurrently around the shared docs-writer dependency.
+  rationale: Three-stage pipeline per agentPipeline — researcher scans routes, docs-writer assembles the OpenAPI spec, reviewer validates structure; researcher and reviewer fanned out concurrently around the shared docs-writer dependency. Cost-dominance per CONSTITUTION §2 P8 — token cost never serializes independent work.
 ---
 
 ## §0 Detect Ambiguity (P8 B1)
 
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). 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.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity (P8 B1). Triggers: contradictory inputs, missing target, unknown convention.
 
 ## Agent Pipeline
 
@@ -28,6 +30,8 @@ Before any action, scan the user's request and provided context for unresolved q
 | 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.
+
 # API Specification Generator — OpenAPI from Code or Code-vs-Spec Drift Detection
 
 Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 specification (`docs/api/`), or take an existing spec and compare it against the live codebase to surface undocumented, stale, or drifted endpoints. The researcher sub-agent scans route definitions, decorators, and handlers; the orchestrator extracts TypeScript types and validation schemas inline; the docs-writer assembles the final spec document; and the reviewer validates structural correctness. AI proposes all outputs; user confirms before any files are written.
@@ -36,7 +40,7 @@ Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 sp
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. Cache any values found (GitHub owner/repo, tooling directives).
 
 **Read the `hatch3r-api-design` rule** if it exists. This rule contains the project's API design conventions (naming, versioning, error shapes, pagination patterns) that the generated spec must conform to.
 
@@ -47,6 +51,14 @@ Take a codebase with HTTP or RPC endpoints and produce a complete OpenAPI 3.1 sp
 3. **Structured output only.** All sub-agent prompts require structured markdown output — no prose dumps.
 4. **Batch schema extraction.** Group types by source file. Read each file once and extract all referenced types in a single pass.
 
+## Confidence Propagation Contract
+
+Every sub-agent delegation prompt in this command MUST include the confidence expression requirement below (verbatim). Sub-agents are invoked with the `quality_charter: agents/shared/quality-charter.md` reference in their frontmatter, but the orchestrator repeats the directive to override runtime prompt defaults per the charter §1 rule.
+
+> 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: the Step 2 framework-detection confidence (already high/medium/low), every endpoint-discovery completeness verdict, and each Step 7 drift classification MUST carry a high/medium/low confidence rating sourced from the researcher or reviewer sub-agent. Endpoints with unresolvable types map to low confidence. Dropping the signal between stages is a gate failure.
+
 ---
 
 ## Workflow
@@ -63,6 +75,25 @@ Classify the request before delegating:
 
 If Tier 1, complete inline and skip the parallel researcher fanout. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline with research and confirm scope with the user before writing the spec.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first sub-agent dispatch (Step 3 endpoint-discovery researcher), surface the cost preview so a full-codebase spec scan is never started blind. Emit the `cost_estimate` block per `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate, calibrated to the Step 0 triage tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <triage tier → Tier 1 inline ~0, Tier 2 ~2 (researcher + docs-writer), Tier 3 up to 3 (+ reviewer)>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 8 output summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+
+### Effort Override (Decision 17)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Effort Override (Decision 17). Misclassification example: a single-endpoint doc tweak scored as Deep, or a full-codebase drift scan scored as Light.
+
 ---
 
 ### Step 1: Gather API Context
@@ -301,6 +332,51 @@ Files Created/Updated:
 - **Respect the project's tooling hierarchy** for knowledge augmentation: project docs → codebase exploration → Context7 MCP → web research.
 - **Spec must be valid.** Never write a spec that fails structural validation. Fix issues before writing.
 
+## Resumability (Decision 27/30)
+
+api-spec is long-running — a Tier 3 full-codebase scan runs the hatch3r-researcher (codebase-analysis mode) over route definitions and handlers (Step 1), then orchestrator-inline TypeScript-schema + validation-schema extraction (Step 2), then hatch3r-docs-writer assembling the OpenAPI 3.1 spec under `docs/api/` (Step 3), then hatch3r-reviewer validating structural correctness in validate mode (Step 4). Per hatch3r's workspace-checkpointed resumability contract, checkpoint progress so an interrupted run re-enters at the last completed step rather than re-running the route scan or re-extracting schemas.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.api-spec-workspace/`; step range the Step 0 → Step 8 progression; `wave` = researcher-batch index in multi-framework detection; snapshot/rollback paths `docs/api/`. Write points: after Step 1 route-scan researcher returns, after Step 2 schema-extraction completes (so endpoint-to-schema map survives a crash), after Step 3 docs-writer spec assembly is confirmed by ASK, after each Step 4 file write under `docs/api/` (so already-generated spec sections survive a crash), after Step 5 reviewer validation returns in validate mode (the drift-classification verdict persists), and after the Step 6 chain handoff in generate mode.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for api-spec: `1` = discovery + route enumeration, `2` = spec generation + schema extraction, `3` = validation + cross-reference verification, `4` = write + iteration-summary. Tier 1 runs are exempt per the Tier 1 exemption.
+
+## 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: OpenAPI/AsyncAPI spec writes, schema files, documentation.
+
+## Iteration Summary (mandatory output)
+
+Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
+
+The 9 sections:
+
+1. **Request** — verbatim restatement of the user's ask in one sentence.
+2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
+3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
+4. **Files Mutated** — list with diff summary (lines added / removed / files created).
+5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
+6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
+7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
+8. **Open Questions / Blockers** — explicit `None` if fully closed.
+9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+
+### Cost Visibility (Decision 24)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+
+## Cost estimate (Decision 24)
+
+This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
+
+- **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the first researcher dispatch (Step 3 endpoint discovery).
+- **Post-execution `cost_actuals` + `delta`** — appended to the Step 8 output summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+
+Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 3` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 0 (inline single-endpoint edit); Tier 2 ≈ 2 (researcher scans routes + docs-writer assembles); Tier 3 up to 3 (researcher + docs-writer + reviewer validation in validate/drift mode). Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
+
 ## Output Templates
 
 ### Spec Header
@@ -329,6 +405,7 @@ servers:
 
 ## Related
 
+- **Skill:** `skills/hatch3r-api-spec/SKILL.md` — the inline single-pass procedure this command's docs-writer (Step 5) and reviewer (Step 6) stages follow; shares `id: hatch3r-api-spec` by the Decision 13 workflow-split (command = multi-agent fan-out, skill = inline procedure). The skill's "Relationship to commands/hatch3r-api-spec.md" section is the canonical handoff record disambiguating the shared id (F16.3-H3).
 - **Rule:** `hatch3r-api-design` — API design conventions the generated spec must follow
 - **Command:** `hatch3r-codebase-map` — structural map that can help scope the API scan
 - **Command:** `hatch3r-project-spec` — project-level specification for API info block context