hatch3r 1.8.0 → 2.0.0

package/{commands → dist/content/commands}/hatch3r-migration-plan.md

@@ -4,20 +4,22 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-architect, hatch3r-docs-writer]
 description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
-tags: [planning, brownfield]
+tags: [planning, ctx:brownfield-only]
 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: Two parallel hatch3r-researcher modes (changelog-analysis + breaking-change-inventory) in Step 3 followed by a hatch3r-architect for codebase impact mapping and a hatch3r-docs-writer for the plan; serialization only on the research → impact-mapping dependency edge.
+  rationale: Two parallel hatch3r-researcher modes (changelog-analysis + breaking-change-inventory) in Step 3 followed by a hatch3r-architect for codebase impact mapping and a hatch3r-docs-writer for the plan; serialization only on the research → impact-mapping dependency edge. 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
 
@@ -27,6 +29,8 @@ Before any action, scan the user's request and provided context for unresolved q
 | 2. Impact Analysis | `hatch3r-architect` | No | Yes |
 | 3. Plan Generation | `hatch3r-docs-writer` | 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.
+
 # Migration Plan — Dependency or Framework Upgrade from Assessment to Phased Execution
 
 Take a dependency or framework upgrade target and produce a complete migration plan (`docs/migrations/`), rollback procedures for each phase, and structured `todo.md` entries ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (dependency changelog analysis, breaking change inventory) followed by an architect for codebase impact mapping, then a docs-writer for plan generation. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
@@ -35,7 +39,7 @@ Take a dependency or framework upgrade target and produce a complete migration p
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -46,6 +50,12 @@ Take a dependency or framework upgrade target and produce a complete migration p
 
 ---
 
+## Confidence Propagation Contract
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Confidence Propagation Contract. Readiness kind: plan.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
@@ -60,6 +70,25 @@ Classify the migration request before delegating:
 
 If Tier 1, run a condensed pipeline that skips the architect when no breaking changes exist. If Tier 2, run the standard pipeline below. If Tier 3, run the full pipeline including incremental-vs-direct trade-off analysis and confirm phasing with the user before writing files.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first researcher dispatch (Step 3), surface the cost preview so a multi-researcher migration-planning run 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 ~1, Tier 2 ~3, Tier 3 up to 3>
+  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 iteration 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 minor version bump scored as Deep, or a framework migration scored as Light.
+
 ---
 
 ### Step 1: Gather Migration Target
@@ -101,7 +130,7 @@ After the migration brief is confirmed, probe for missing context. Analyze the b
    - **Bundle/binary size**: Are there known size regressions in the target version?
    - **Type system**: Does the upgrade introduce stricter types or remove type exports?
 
-Skip dimensions that the migration brief already addresses clearly.
+Skip dimensions that the migration brief already addresses with a stated answer.
 
 **ASK:** "Before research begins, I have {N} questions to confirm coverage of all migration dimensions:
 {numbered question list — each with the dimension label and why the answer matters}
@@ -343,6 +372,53 @@ If yes, instruct the user to invoke the `hatch3r-board-fill` command. Board-fill
 
 ---
 
+## Resumability (Decision 27/30)
+
+migration-plan is long-running — a Tier 3 multi-major-version or framework migration fans out two parallel hatch3r-researcher modes (dependency-changelog, breaking-change-inventory) in Step 3, then runs hatch3r-architect for codebase impact mapping (Step 4) and hatch3r-docs-writer for phased plan generation (Step 5). 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 changelog research and re-deriving the breaking-change inventory.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.migration-plan-workspace/`; step range the Step 0 → Step 8 progression; `wave` = researcher-batch index across the 2 parallel modes; snapshot/rollback paths `docs/migrations/`, `docs/adr/`, and `todo.md`. Write points: after Step 1 migration-target context locks, after Step 2 scope ASK, after the Step 3 two-researcher fan-out returns, after Step 4 architect impact-mapping returns, after Step 5 docs-writer plan synthesis is confirmed by ASK, after each Step 6 file write (`docs/migrations/`, `docs/adr/`), after Step 7 todo.md phased-entry generation, and after the optional Step 8 chain-to-`hatch3r-board-fill` handoff.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for migration-plan: `1` = source/target intake + scope detection, `2` = researcher sub-agent dispatch (consumer enumeration, expand-contract phasing), `3` = plan synthesis + rollback drafting, `4` = plan 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: plan document, phase specs, rollback scripts.
+
+## 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.
+- **Post-execution `cost_actuals` + `delta`** — appended to the iteration 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 ≈ 1 (two researchers, architect skipped when no breaking changes); Tier 2 ≈ 3 (two parallel researchers + architect, docs-writer); Tier 3 up to 3 (same fan-out, deeper changelog + incremental-vs-direct analysis). 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`.
+
+---
+
 ## Error Handling
 
 - **No changelog available:** Fall back to git diff of the source repository between version tags. If unavailable, rely on community migration guide researcher output only and warn the user that the breaking change inventory may be incomplete.

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

@@ -4,20 +4,31 @@ type: command
 orchestrator: true
 agentPipeline: [hatch3r-researcher, hatch3r-docs-writer]
 description: Generate a comprehensive onboarding guide for a new developer joining the project -- spawn parallel researchers to analyze codebase structure, architecture, and conventions, then produce a tailored onboarding document with setup instructions, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet.
-tags: [brownfield, team]
+tags: [planning, ctx:brownfield-only]
 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 parallel hatch3r-researcher modes (codebase-overview, architecture-mapping, conventions-extraction) in Step 3 followed by one hatch3r-docs-writer to assemble the tailored onboarding guide; researchers fan out in a single Task batch.
+  rationale: Three parallel hatch3r-researcher modes (codebase-overview, architecture-mapping, conventions-extraction) in Step 3 followed by one hatch3r-docs-writer to assemble the tailored onboarding guide; researchers fan out in a single Task batch. 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.
+Before any action, scan the user's request and provided context for unresolved questions. Apply 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. Default behavior on no response: lowest-blast-radius reversible option per `agents/shared/user-question-protocol.md`.
+
+**Triggers for this command:**
+- Developer role unspecified (frontend / backend / fullstack / devops / general) — guide content materially diverges per role.
+- Experience level unspecified (junior / mid / senior / staff) — depth + assumed knowledge tailoring differs.
+- Focus areas absent — guide either targets specific modules or covers all surfaces.
+- Output format ambiguous — markdown vs GitHub issue vs Notion changes write path.
+- Team context dimensions in Step 1b unanswered — guide either includes the section or omits it; do not invent team norms.
+
+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. If a question goes unanswered, the gate never deadlocks: as the orchestrator, apply the declared `Default if no response:` option and log it in Iteration Summary §8; if a spawned sub-agent hits the trigger or no default line was emitted, return Status `BLOCKED_AMBIGUITY` with the rendered question rather than silent-picking — per `agents/shared/user-question-protocol.md` → Operationalising Default-if-no-Response.
 
 ## Agent Pipeline
 
@@ -27,6 +38,8 @@ Before any action, scan the user's request and provided context for unresolved q
 | 2. Setup Verification | Orchestrator (inline) | No | Yes |
 | 3. Guide Generation | `hatch3r-docs-writer` | 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.
+
 # Onboarding Guide Generator — Tailored Developer Onboarding from Codebase Analysis to Ready-to-Work Guide
 
 Take a new developer's role, experience level, and focus areas and produce a comprehensive onboarding guide covering project setup, architecture, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet. Spawns parallel researcher sub-agents (codebase overview, architecture mapping, conventions extraction) to analyze the project from multiple angles before generating a tailored guide document. AI proposes all outputs; user confirms before any files are written. Adapts depth and focus to the developer's experience level and role.
@@ -35,7 +48,7 @@ Take a new developer's role, experience level, and focus areas and produce a com
 
 ## Shared Context
 
-**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations, it establishes patterns and context (GitHub owner/repo, tooling directives) that provide project metadata useful for the onboarding guide. Cache any values found.
+**Read the `hatch3r-board-shared` skill at the start of the run** if it exists. While this command does not perform board operations, it establishes patterns and context (GitHub owner/repo, tooling directives) that provide project metadata useful for the onboarding guide. Cache any values found.
 
 ## Token-Saving Directives
 
@@ -45,6 +58,12 @@ Take a new developer's role, experience level, and focus areas and produce a com
 
 ---
 
+## Confidence Propagation Contract
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Confidence Propagation Contract. Readiness kind: guide.
+
+---
+
 ## Workflow
 
 Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
@@ -59,6 +78,25 @@ Classify the onboarding-guide request before delegating:
 
 If Tier 1, run the reduced researcher set and skip experience-level depth tailoring. If Tier 2, run the standard pipeline below. If Tier 3, expand researcher depth and confirm guide sections with the user before generating the document.
 
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the first researcher dispatch (Step 1), surface the cost preview so a multi-researcher onboarding run 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 ~1, Tier 2 ~3, Tier 3 up to 3 at deep depth>
+  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 iteration 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 small project scored as Deep, or a large monorepo scored as Light.
+
 ---
 
 ### Step 1: Gather Context
@@ -117,11 +155,11 @@ Answer these now, or say 'skip' for any where you'd rather I omit that section f
    - `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` — project metadata, scripts, dependencies
    - `.env.example` — environment variable template
    - `docs/` — any existing documentation
-   - `.agents/rules/` — coding standards and conventions
-   - `.agents/learnings/` — team learnings and institutional knowledge
+   - `rules/` — coding standards and conventions
+   - `.hatch3r/learnings/` — team learnings and institutional knowledge
    - CI config (`.github/workflows/`, `.gitlab-ci.yml`, etc.) — CI/CD pipeline
 2. Scan the top-level directory structure to understand project organization.
-3. If `.agents/learnings/` exists, scan for learnings relevant to onboarding, common mistakes, and gotchas. Match by area and tags.
+3. If `.hatch3r/learnings/` exists, scan for learnings relevant to onboarding, common mistakes, and gotchas. Match by area and tags.
 4. Present a context summary:
 
 ```
@@ -131,7 +169,7 @@ Context Loaded:
   Package manifest: {type — with N scripts, M dependencies}
   Env template:     {found / not found}
   Docs:             {N} files in docs/ ({key ones listed})
-  Rules:            {N} files in .agents/rules/ ({areas covered})
+  Rules:            {N} files in rules/ ({areas covered})
   Learnings:        {N} relevant learnings
   CI:               {type — N workflows}
   Gaps:             {list any missing context — e.g., "no CONTRIBUTING.md", "no .env.example"}
@@ -280,6 +318,53 @@ Recommended Follow-ups:
 
 ---
 
+## Resumability (Decision 27/30)
+
+onboard is long-running — a Tier 3 staff-level guide for a large monorepo fans out three parallel hatch3r-researcher modes (codebase-overview, architecture-mapping, conventions-extraction) in Step 3, then assembles a tailored onboarding guide via hatch3r-docs-writer covering project setup, architecture walkthrough, coding conventions, key workflows, tribal knowledge, and a quick-reference cheat sheet. 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 three-researcher fan-out and regenerating the guide.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.onboard-workspace/`; step range the Step 0 → Step 7 progression; `wave` = researcher-batch index across the 3 parallel modes; snapshot/rollback paths the onboarding-guide target path. Write points: after Step 1 developer-role + experience-level context locks, after Step 2 setup verification, after the Step 3 three-researcher fan-out returns, after Step 4 guide-section ASK is confirmed, after each Step 5 guide section is generated (so already-generated sections survive a crash and are not regenerated on resume), after Step 6 guide assembly is confirmed by ASK, and after Step 7 file write to the onboarding-guide path.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping for onboard: `1` = repo discovery + maturity assessment, `2` = explore sub-agent dispatch + module survey, `3` = onboarding-guide synthesis, `4` = guide 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: onboarding-guide doc, area map, quick-start scripts.
+
+## 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.
+- **Post-execution `cost_actuals` + `delta`** — appended to the iteration 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 ≈ 1 (codebase-overview researcher only); Tier 2 ≈ 3 (codebase-overview + architecture + conventions); Tier 3 = 3 at deep depth. 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`.
+
+---
+
 ## Error Handling
 
 - **Sub-agent failure:** Retry the failed sub-agent once. If it fails again, generate the affected guide sections from available context (README, package manifest, directory structure) and note reduced accuracy. ASK the user how to proceed.
@@ -287,7 +372,7 @@ Recommended Follow-ups:
 - **Multiple languages/frameworks:** Generate setup sections for each language/framework detected. Organize by language with shared prerequisites listed first. Note which parts of the codebase use which stack.
 - **Missing credentials or access documentation:** Never invent or guess credentials. Include placeholder sections marked `[ACTION REQUIRED]` with instructions on who to contact for access. Flag each missing credential in the Recommended Follow-ups.
 - **File write failure:** Report the error and provide the full guide content so the user can create the file manually.
-- **Missing project context:** If no shared board context or `.agents/hatch.json` exists, proceed without board context — this command does not require board configuration.
+- **Missing project context:** If no shared board context or `.hatch3r/hatch.json` exists, proceed without board context — this command does not require board configuration.
 - **Empty or minimal codebase:** If the project has fewer than 10 source files, generate a condensed guide without the architecture and tribal knowledge sections. Note that the guide will be more useful after the project matures.
 - **Conflicting documentation:** If README instructions conflict with actual project structure or scripts, flag both versions in the guide and note the discrepancy for the developer to verify.
 
@@ -369,3 +454,9 @@ Recommended Follow-ups:
 - **Command:** `hatch3r-codebase-map` — deeper architecture documentation
 - **Command:** `hatch3r-project-spec` — full project specification
 - **Skill:** `hatch3r-feature` — standard feature development workflow (referenced in guide)
+
+## References
+
+- `agents/shared/user-question-protocol.md` (B1 gate — applies at §0 Detect Ambiguity above plus every mid-workflow ASK checkpoint per Finding D7-M14)
+- `agents/shared/quality-charter.md` §1, §3, §7, §8 (confidence, ambiguity, measurable criteria)
+- `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation, Mandatory Delegation Directive)

package/dist/content/commands/hatch3r-pack-install.md

@@ -0,0 +1,243 @@
+---
+id: hatch3r-pack-install
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-security, hatch3r-pack-installer]
+description: "Walk the user through the pack trust-model gate (tier + signature + body-scan + capability declaration), confirm the trust posture, then delegate the verified install to hatch3r-pack-installer."
+argument-hint: "<pack-source>"
+tags: [devops, supply-chain, ctx:brownfield-only]
+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: 2
+  rationale: One trust-verification pass (hatch3r-security, CQ3 supply-chain gate) then one install pass (hatch3r-pack-installer); the install depends on a clean verification verdict, so the two run on a dependency edge, not in parallel — per CONSTITUTION §2 P8 token cost never serializes independent work, but a true dependency does.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+Before any action, scan the request 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. Pack-install ambiguity triggers: which pack source is meant (npm spec, git URL, local path) when more than one resolves, whether the user accepts the pack's declared capability set, and whether an `--allow-untrusted` override is intended for an unsigned source. Installing a pack writes third-party content into the repo — an unsigned-pack override is irreversible-by-effect, so the trust posture is always confirmed at the Step 3 gate before any install runs.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Resolve pack | Orchestrator (inline) | No | Yes |
+| 2. Trust verification | `hatch3r-security` | No | Yes |
+| 3. Trust gate + ASK | Orchestrator (inline) | No | Yes |
+| 4. Install | `hatch3r-pack-installer` | No | When the gate clears |
+| 5. Iteration Summary | Orchestrator (inline) | No | Yes |
+
+**Parallel-safety note** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): Stages 2 and 4 are a dependency chain — the install consumes the verification verdict — so they run sequentially. This is a true dependency edge, not a cost-driven serialization (P8 B2).
+
+---
+
+# Pack Install — Trust Gate, then Delegated Install
+
+Drives `hatch3r add <pack>` through the trust contract in the hatch3r trust model (https://docs.hatch3r.com/docs/reference/trust-model) before any pack content lands in the repo. Resolves the pack reference, runs the supply-chain verification gate via `hatch3r-security`, presents the trust posture as one consolidated ASK, then delegates the verified atomic write to `hatch3r-pack-installer`.
+
+Use `hatch3r-pack-install` when installing a third-party (marketplace / git-URL / local) pack. Canonical content shipped with the npm package does not flow through this command — it installs via `hatch3r init` / `hatch3r sync`.
+
+> **Status note:** The hatch3r trust model (https://docs.hatch3r.com/docs/reference/trust-model) §1 marks the trust contract SPEC ONLY — `hatch3r add` is a placeholder today (`src/cli/commands/add.ts`). This command's orchestration contract lands the moment `hatch3r add` is wired up; until then it documents the gate sequence the install path will run.
+
+---
+
+## Argument Parsing
+
+Positional argument: `<pack-source>` (required) — an npm spec, a git URL, or a local path.
+Optional flag: `--allow-untrusted` — bypass the signature gate for an unsigned source. Surfaced at the Step 3 ASK; never applied silently.
+
+If `<pack-source>` is absent, halt with the actionable error in Step 1c.
+
+---
+
+## Workflow
+
+Execute these steps in order. The only ASK gate is Step 3; after the user confirms the trust posture, run autonomously through Step 5.
+
+## Step 0: Triage
+
+Classify the install before delegating, calibrated to pack-install against the Light/Standard/Deep tiers in `agents/shared/triage-vocabulary.md`:
+
+- **Tier 1 (Light)** — a single canonical-tier npm pack carrying provenance, a small declared write set (≤5 files), and no capability escalation: one `hatch3r-security` verify pass (Step 2), then the Step 4 install. Step 3 confirms a clean posture in one ASK.
+- **Tier 2 (Standard)** — a marketplace or git-URL pack, a moderate write set, a declared capability set inside the authorized envelope, signature present: the full trust gate plus a capability/tool-footprint cross-check, then install.
+- **Tier 3 (Deep)** — any of: an unsigned source, an `--allow-untrusted` request, a capability set that escalates the declared tool footprint, or a pack writing >20 files or touching multiple adapter surfaces: the full pipeline run under the sandbox-install posture (trust model §1.3, https://docs.hatch3r.com/docs/reference/trust-model) with an explicit irreversibility confirmation at the Step 3 gate.
+
+**Classify upward on uncertainty:** an unverifiable signature or an undeclared capability classifies at Tier 3, never down — the missing signal is treated as the higher-risk reading.
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Step 2 `hatch3r-security` dispatch, emit the cost preview per `rules/hatch3r-cost-visibility.md`, calibrated to the Step 0 tier:
+
+```yaml
+cost_estimate:
+  expected_sa_count: 2
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>   # 0 unless a transparency-log / advisory lookup is needed
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 5 Iteration Summary; `--effort=light|standard|deep` (Decision 17) forces the tier — record both the auto-classified tier and the override.
+
+## Step 1: Resolve the Pack
+
+#### 1a. Classify the source
+
+- npm spec (`name@version`) → npm-published tier; verification uses `npm audit signatures`.
+- git URL → non-npm tier; require a 40-char commit SHA pin (trust model §2.2, https://docs.hatch3r.com/docs/reference/trust-model); verification uses `cosign verify-blob`.
+- local path → non-npm tier; cosign-signed `pack-manifest.json` + SHA-256 manifest expected.
+
+#### 1b. Read the manifest
+
+Read the pack's `pack-manifest.json` (§5.1): `pack_id`, `version`, `hatch3r_min_version`, `required_capabilities`, `tool_footprint`, `declared_tools`, `signing`, `review_queue`. A missing or malformed manifest is a halt (exit 1) with the specific missing field.
+
+#### 1c. Halt on missing source
+
+If no `<pack-source>` was supplied, halt verbatim (P1 actionable-error contract, `.claude/rules/cli-ux-standards.md`):
+
+```
+No pack source supplied.
+
+To install a pack:
+  /hatch3r-pack-install <npm-spec | git-url | local-path>
+
+Example:
+  /hatch3r-pack-install @acme/hatch3r-react-pack@1.2.0
+```
+
+Exit code 2 (usage error).
+
+## Step 2: Trust Verification (delegated)
+
+Spawn `hatch3r-security` via the Task tool with `subagent_type: "generalPurpose"`. The prompt MUST include:
+
+1. The resolved pack reference + source tier from Step 1.
+2. The full `pack-manifest.json` from Step 1b.
+3. The trust-contract checklist to verify (cite the hatch3r trust model, https://docs.hatch3r.com/docs/reference/trust-model): signature (§2.1 npm-provenance OR §2.2 cosign-keyless), body scan against DENY_PATTERNS (§3.1), lifecycle-script ban (§4.1), capability + tool-footprint declaration (§5.2–§5.4).
+4. All `scope: always` rule directives from `rules/`.
+5. The confidence expression requirement (verbatim): rate every finding high/medium/low per `agents/shared/quality-charter.md` — high = signature + scan verified clean; medium = pattern match without verified exploit; low = heuristic, recommend human review.
+
+`hatch3r-security` returns its `PASS | FINDINGS | CRITICAL` verdict (map to canonical severity via `agents/shared/severity-mapping.md`), the signature-verification evidence, and the body-scan result.
+
+## Step 3: Trust Gate + ASK (only mutation gate)
+
+Present one consolidated trust posture, then ASK before any install runs.
+
+```
+Pack: {pack_id}@{version-or-SHA}  ({npm | git | local} tier)
+
+Trust posture:
+  signature:        {PASS | FAIL}  — {npm audit signatures | cosign verify-blob evidence}
+  body scan:        {0 hits | matched: <pattern>}
+  lifecycle scripts:{none | BANNED: <name>}
+  capabilities:     {required_capabilities} — {within authorized set? yes/no}
+  tool footprint:   {within declared caps? yes/no}
+  review queue:     {submission_id | none}
+
+hatch3r-security verdict: {PASS | FINDINGS | CRITICAL} (confidence: {high|medium|low})
+```
+
+#### 3a. ASK (only gate)
+
+> Reviewed the trust posture for {pack_id}@{version}. Proceed with install?
+>
+> 1. `install` — apply the pack (only when signature PASS and verdict is not CRITICAL).
+> 2. `install --allow-untrusted` — apply despite a signature FAIL or absent signature (records the override in the manifest; install only under a sandbox per trust-model §1.3).
+> 3. `abort` — do not install.
+>
+> Default if no response: 3 (abort — lowest-blast-radius; an unverified pack is a supply-chain attack vector).
+
+Gate rules:
+- A `CRITICAL` verdict from `hatch3r-security` (e.g., a DENY_PATTERNS body-scan hit, a banned lifecycle script) blocks `install`. Only `abort` or an explicit `install --allow-untrusted` with written user rationale may proceed, and a body-scan hit is never overridable — re-route to `abort`.
+- A signature FAIL is overridable only via option 2 with explicit confirmation; record the override and the user's rationale for the manifest install record.
+- After the user confirms `install`, the run is autonomous through Step 5.
+
+## Step 4: Install (delegated)
+
+Spawn `hatch3r-pack-installer` via the Task tool with `subagent_type: "generalPurpose"`. The prompt MUST include:
+
+1. The resolved + pinned pack reference from Step 1.
+2. The `hatch3r-security` verification verdict + evidence from Step 2 (so the installer re-verifies at write time rather than trusting a stale check).
+3. The user's Step 3 decision, including any `--allow-untrusted` override + rationale.
+4. All `scope: always` rule directives from `rules/`.
+5. The confidence expression requirement (verbatim, as in Step 2).
+6. Explicit: preview the write set as a dry-run before the first write; apply atomically; roll back every written path on any failure; run `hatch3r verify` post-apply.
+
+`hatch3r-pack-installer` returns `COMPLETE | BLOCKED`, the write-set table, the manifest install record, and the rollback state. Quote its per-file `delegation_proof_id` in the Step 5 attestation.
+
+## Step 5: Iteration Summary
+
+Emit the canonical 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).
+
+```markdown
+## Iteration Summary
+
+**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
+**Outcome:** {one sentence — e.g., "Installed @acme/hatch3r-react-pack@1.2.0; signature PASS, 0 scan hits, 4 files written."}
+
+**Done:**
+- Trust verification: hatch3r-security → {verdict}
+- Install: hatch3r-pack-installer → {COMPLETE | BLOCKED}
+
+**Not Done / Deferred / Unverified:**
+- (or: `None — pack installed and verified`)
+
+**Open Questions / Blockers:**
+- (or: `None`)
+
+**Confidence:** {high | medium | low} — {one-sentence basis from the install + verification verdicts}
+
+**Artifacts Touched:**
+| Path | Action | Notes |
+| ---- | ------ | ----- |
+| {adapter path} | created / merged | managed block |
+
+**Verifications Run:**
+| Check | Result |
+| ----- | ------ |
+| signature (npm audit signatures / cosign verify-blob) | pass |
+| body scan (scanForDeniedPatterns) | 0 hits |
+| hatch3r verify (post-apply drift) | 0 drift |
+
+**Suggested Next Action:** {one line — e.g., "Run /hatch3r-capability-discover to see the newly installed pack artifacts."}
+```
+
+Status decision rules:
+- **SUCCESS** — signature PASS, scan clean, install COMPLETE, `hatch3r verify` zero drift.
+- **PARTIAL** — install COMPLETE but a non-blocking advisory surfaced (e.g., marketplace takedown notice on a different version).
+- **FAILED** — install returned BLOCKED and rolled back; repo unchanged.
+- **BLOCKED** — cannot proceed without user input (CRITICAL verdict without an authorized override, or `--allow-untrusted` rationale not provided).
+
+---
+
+## Sub-agent fan-out contract
+
+This command emits the `sub_agents_spawned` field declared in frontmatter (`count: 2`) per `rules/hatch3r-fan-out-discipline.md`. The two sub-agents (`hatch3r-security` verification, then `hatch3r-pack-installer` install) run on a dependency edge — the install consumes the verification verdict — so serialization here is dependency-driven, not cost-driven. Per CONSTITUTION §2 P8 B2, token cost is never a valid reason to serialize independent work; this serialization is valid only because a true dependency exists.
+
+## 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: pack content written to the repo.
+
+## Resumability (Decision 27/30)
+
+pack-install is checkpoint-light: Steps 1-3 (resolve, verify, trust gate) are read-only, and Step 4 is a single atomic install. The temp+rename write set (`src/merge/safeWrite.ts`) is itself the resumability unit — a SIGKILL mid-install leaves the repo at its pre-install state with no partial pack — so a resumed run re-runs from the trust gate.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.pack-install-workspace/`; step range the Step 1 → Step 5 progression; `wave` = the fan-out batch index; snapshot/rollback paths the command's output paths. Write points: after Step 1 resolution, after the Step 2 verification verdict, after the Step 3 trust decision, and after the Step 4 installer return. Recording the trust decision means a resume does not re-prompt for a confirmed posture.
+
+## Guardrails
+
+1. **One ASK gate.** Step 3 is the only user-facing checkpoint. After confirmation the run proceeds through Steps 4–5 without further prompting.
+2. **No silent override.** `--allow-untrusted` is never applied without explicit Step 3 confirmation + recorded rationale.
+3. **Body-scan hits are non-overridable.** A DENY_PATTERNS match (§3.1) routes to `abort` regardless of override flags.
+4. **Re-verify at write time.** Step 4 passes the verification evidence to the installer, which re-runs the signature check at write time to close any time-of-check/time-of-use gap.
+5. **Atomic install or full rollback.** A failed apply reverts every written path; the repo is never left in a partial-pack state.
+6. **No canonical packs.** This command installs third-party packs only; canonical content flows through `hatch3r init` / `hatch3r sync`.
+
+## References
+
+- [SLSA Build Track Levels (L0–L3)](https://slsa.dev/spec/v1.0/levels) (accessed 2026-06-02, OpenSSF / SLSA, official-docs; v1.0 superseded by current line) — the provenance → signing → isolation ladder this command's trust gate maps onto: L1 documented provenance, L2 signed provenance from a hosted build (the npm-provenance / cosign tier this command verifies), L3 tamper-resistant isolated builds. Source for framing the signature gate as the L2 floor for third-party packs.
+- [npm Supply Chain Security in 2026: What Your Package Manager Does (and Doesn't) Protect You From](https://mondoo.com/blog/npm-supply-chain-security-package-manager-defenses-2026) (accessed 2026-06-02, Mondoo, independent-analysis) — 2026 synthesis of npm provenance + trusted-publishing coverage and gaps (signature proves CI-built, not publish-authorized; lifecycle-script and stolen-credential surfaces remain). Source for the lifecycle-script ban + non-overridable body-scan posture this command enforces ahead of any install write.