hatch3r 1.6.2 → 1.7.1

package/github-agents/hatch3r-docs-agent.md

@@ -1,9 +1,12 @@
 ---
 name: hatch3r-docs-agent
+type: github-agent
 description: Technical writer who maintains specs, ADRs, and documentation
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 You are an expert technical writer for the project.

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

@@ -1,9 +1,12 @@
 ---
 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: [team, devops]
 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.

package/github-agents/hatch3r-security-agent.md

@@ -1,9 +1,12 @@
 ---
 name: hatch3r-security-agent
+type: github-agent
 description: Security analyst who audits code, rules, and data flows
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 You are an expert security analyst for the project.

package/github-agents/hatch3r-test-agent.md

@@ -1,9 +1,12 @@
 ---
 name: hatch3r-test-agent
+type: github-agent
 description: QA engineer who writes and maintains tests
 # Simplified agent for GitHub Copilot/Codex
 tags: [team, devops]
 quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 
 You are an expert QA engineer for the project.

package/hooks/hatch3r-ci-failure.md

@@ -6,6 +6,7 @@ agent: ci-watcher
 description: Diagnose CI pipeline failures
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Hook: ci-failure → ci-watcher
 

package/hooks/hatch3r-file-save.md

@@ -7,6 +7,7 @@ description: Activate context-specific rules on file save
 globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Hook: file-save → context-rules
 

package/hooks/hatch3r-post-merge.md

@@ -6,6 +6,7 @@ agent: ci-watcher
 description: Check CI pipeline status after merge
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Hook: post-merge → ci-watcher
 

package/hooks/hatch3r-pre-commit.md

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

package/hooks/hatch3r-pre-push.md

@@ -6,6 +6,7 @@ agent: security-auditor
 description: Scan for secrets and security issues before push
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Hook: pre-push → security-auditor
 

package/hooks/hatch3r-session-start.md

@@ -6,6 +6,7 @@ agent: learnings-loader
 description: Load relevant learnings at session start
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Hook: session-start → learnings-loader
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatch3r",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "description": "Battle-tested agentic coding setup framework. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for every major AI coding tool.",
   "type": "module",
   "exports": {
@@ -23,6 +23,13 @@
     "inventory": "tsx scripts/inventory.ts",
     "inventory:check-docs": "tsx scripts/inventory.ts --check-docs",
     "validate:rule-parity": "tsx scripts/validate-rule-parity.ts",
+    "validate:efficiency": "tsx scripts/validate-efficiency-invariants.ts",
+    "validate": "npm run validate:rule-parity && npm run validate:efficiency",
+    "audit:validate-registry": "tsx scripts/validate-finding-registry.ts",
+    "audit:migrate": "tsx scripts/migrate-finding-registry.ts",
+    "audit:archive": "tsx scripts/audit-archive.ts",
+    "audit:find": "tsx scripts/audit-find.ts",
+    "audit:reset": "tsx scripts/clean-audit-workspace.ts",
     "lockfile:check": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https"
   },
   "keywords": [
@@ -82,11 +89,13 @@
     "inquirer": "^13.3.2",
     "ora": "^9.3.0",
     "proper-lockfile": "^4.1.2",
+    "update-notifier": "^7.3.1",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/update-notifier": "^6.0.8",
     "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
     "lockfile-lint": "^5.0.0",

package/prompts/hatch3r-bug-triage.md

@@ -3,6 +3,8 @@ id: hatch3r-bug-triage
 type: prompt
 description: Triage a bug report and suggest investigation steps
 tags: [core]
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # Bug Triage
 

package/prompts/hatch3r-code-review.md

@@ -3,6 +3,8 @@ id: hatch3r-code-review
 type: prompt
 description: Review code changes for quality, security, and correctness
 tags: [core]
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # Code Review
 

package/prompts/hatch3r-pr-description.md

@@ -3,6 +3,8 @@ id: hatch3r-pr-description
 type: prompt
 description: Generate a pull request description from staged changes
 tags: [core]
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
 ---
 # PR Description
 

package/rules/hatch3r-accessibility-standards.md

@@ -5,6 +5,7 @@ description: Accessibility standards covering WCAG 2.2 AA compliance, keyboard n
 scope: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*a11y*,**/*accessibility*"
 tags: [a11y]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Accessibility Standards
 

package/rules/hatch3r-agent-orchestration-detail.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/.agents/**,**/pipeline/**,**/*orchestrat*,**/*agent*"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Agent Orchestration — Extended Reference
 

package/rules/hatch3r-agent-orchestration.md

@@ -5,6 +5,7 @@ description: Mandatory agent delegation, skill loading, and subagent usage direc
 scope: always
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Agent Orchestration
 
@@ -18,6 +19,8 @@ Hatch3r's orchestration uses a **phase-gated pipeline** (Research, Implement, Re
 
 This rule applies to EVERY context without exception: board-pickup (epic, sub-issue, standalone, batch), workflow command (full/quick), plain chat, issue references, and natural language requests. The full sub-agent pipeline is mandatory — never implement code inline without sub-agents.
 
+**"Inline implementation" defined.** Inline implementation means calling any code-writing tool — `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform equivalent — from the orchestrator turn itself, rather than from inside a spawned `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) sub-agent. The only carve-out is `hatch3r-quick-change` for Tier 1 single-line trivial edits per its declared scope.
+
 ## Universal Sub-Agent Pipeline
 
 Every task MUST follow this four-phase pipeline: **Phase 1 — Research** (`hatch3r-researcher`), **Phase 2 — Implement** (`hatch3r-implementer`), **Phase 3 — Review Loop** (`hatch3r-reviewer` + `hatch3r-fixer`), **Phase 4 — Final Quality** (parallel specialists). See Mandatory Delegation Directives below.
@@ -83,6 +86,27 @@ Spawn `hatch3r-implementer` via Task tool for ALL code changes. Never implement
 
 **Implementer prompt enrichment (Tier 2+):** Include `similar-implementation` findings as "Reference Conventions", resolved `requirements-elicitation` answers as "Resolved Requirements", and blast radius data (Tier 3 only).
 
+### Per-Turn Pipeline-State Header
+
+Whenever a tracked task is active at Tier 2 or Tier 3 (deep-context score >= 3), the orchestrator MUST emit a single-line pipeline-state header at the very start of every assistant turn that touches the task. Format:
+
+```
+[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
+```
+
+Examples:
+
+- `[hatch3r-pipeline: phase 1 | last: n/a | next: hatch3r-researcher]`
+- `[hatch3r-pipeline: phase 2 | last: hatch3r-researcher → SUCCESS | next: hatch3r-implementer]`
+- `[hatch3r-pipeline: phase 3 | last: hatch3r-reviewer → PARTIAL | next: hatch3r-fixer]`
+- `[hatch3r-pipeline: phase 3 | last: hatch3r-implementer → SUCCESS | next: user-confirmation]`
+
+A missing header on a tracked Tier >= 2 task is a self-detectable drift signal — the user may halt the turn and request re-grounding. The header also functions as a per-reply cache prime: rendering it forces the orchestrator to re-resolve which phase it is in before choosing tools. Tier 1 tasks, read-only answers, and chat-only iterations do NOT require the header.
+
+### Mandatory Delegation Directive (No Inline Implementation)
+
+Restating with maximum clarity for sub-agent prompt inclusion: the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool from its own turn. The only path for code mutation is the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3). Carve-out: `hatch3r-quick-change` Tier 1 trivial items per its declared scope. No other carve-out exists. Violations are bypass mode (see issue #73) — surface them by halting the turn and re-delegating.
+
 ### Mid-Implementation Research Gap Checkpoint
 
 At the midpoint of Phase 2 (after initial files are modified but before completion), the implementer MUST evaluate whether research gaps exist. This prevents discovering missing context too late in the pipeline.

package/rules/hatch3r-agent-orchestration.mdc

@@ -14,6 +14,8 @@ Hatch3r's orchestration uses a **phase-gated pipeline** (Research, Implement, Re
 
 This rule applies to EVERY context without exception: board-pickup (epic, sub-issue, standalone, batch), workflow command (full/quick), plain chat, issue references, and natural language requests. The full sub-agent pipeline is mandatory — never implement code inline without sub-agents.
 
+**"Inline implementation" defined.** Inline implementation means calling any code-writing tool — `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform equivalent — from the orchestrator turn itself, rather than from inside a spawned `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) sub-agent. The only carve-out is `hatch3r-quick-change` for Tier 1 single-line trivial edits per its declared scope.
+
 ## Universal Sub-Agent Pipeline
 
 Every task MUST follow this four-phase pipeline: **Phase 1 — Research** (`hatch3r-researcher`), **Phase 2 — Implement** (`hatch3r-implementer`), **Phase 3 — Review Loop** (`hatch3r-reviewer` + `hatch3r-fixer`), **Phase 4 — Final Quality** (parallel specialists). See Mandatory Delegation Directives below.
@@ -79,6 +81,27 @@ Spawn `hatch3r-implementer` via Task tool for ALL code changes. Never implement
 
 **Implementer prompt enrichment (Tier 2+):** Include `similar-implementation` findings as "Reference Conventions", resolved `requirements-elicitation` answers as "Resolved Requirements", and blast radius data (Tier 3 only).
 
+### Per-Turn Pipeline-State Header
+
+Whenever a tracked task is active at Tier 2 or Tier 3 (deep-context score >= 3), the orchestrator MUST emit a single-line pipeline-state header at the very start of every assistant turn that touches the task. Format:
+
+```
+[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
+```
+
+Examples:
+
+- `[hatch3r-pipeline: phase 1 | last: n/a | next: hatch3r-researcher]`
+- `[hatch3r-pipeline: phase 2 | last: hatch3r-researcher → SUCCESS | next: hatch3r-implementer]`
+- `[hatch3r-pipeline: phase 3 | last: hatch3r-reviewer → PARTIAL | next: hatch3r-fixer]`
+- `[hatch3r-pipeline: phase 3 | last: hatch3r-implementer → SUCCESS | next: user-confirmation]`
+
+A missing header on a tracked Tier >= 2 task is a self-detectable drift signal — the user may halt the turn and request re-grounding. The header also functions as a per-reply cache prime: rendering it forces the orchestrator to re-resolve which phase it is in before choosing tools. Tier 1 tasks, read-only answers, and chat-only iterations do NOT require the header.
+
+### Mandatory Delegation Directive (No Inline Implementation)
+
+Restating with maximum clarity for sub-agent prompt inclusion: the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool from its own turn. The only path for code mutation is the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3). Carve-out: `hatch3r-quick-change` Tier 1 trivial items per its declared scope. No other carve-out exists. Violations are bypass mode (see issue #73) — surface them by halting the turn and re-delegating.
+
 ### Mid-Implementation Research Gap Checkpoint
 
 At the midpoint of Phase 2 (after initial files are modified but before completion), the implementer MUST evaluate whether research gaps exist. This prevents discovering missing context too late in the pipeline.

package/rules/hatch3r-api-design.md

@@ -5,6 +5,7 @@ description: REST, GraphQL, and gRPC contract patterns covering versioning, auth
 scope: "**/api/**,**/routes/**,**/controllers/**,**/endpoints/**,**/*route*,**/*controller*,**/*endpoint*,**/*handler*,**/graphql/**,**/trpc/**"
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # API Design
 

package/rules/hatch3r-browser-verification.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*.vue,**/*.jsx,**/*.tsx,**/*.svelte,**/components/**,**/*.html,**/*.css,**/*.scss"
 tags: [review]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Browser Verification
 

package/rules/hatch3r-ci-cd.md

@@ -5,6 +5,7 @@ description: CI/CD pipeline standards covering stage gates, deployment strategie
 scope: "**/.github/workflows/**,**/Dockerfile*,**/docker-compose*,**/.gitlab-ci*,**/Jenkinsfile,**/azure-pipelines*,**/.circleci/**,**/deploy/**,**/*pipeline*"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # CI/CD Standards
 

package/rules/hatch3r-code-standards.md

@@ -5,6 +5,7 @@ description: TypeScript typing discipline, naming, file size caps, Result types,
 scope: always
 tags: [core, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Code Standards
 

package/rules/hatch3r-component-conventions.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx"
 tags: [implementation, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Component Conventions
 

package/rules/hatch3r-data-classification.md

@@ -5,6 +5,7 @@ description: Data classification standards covering PII handling, encryption, re
 scope: "**/models/**,**/schemas/**,**/schema*,**/database/**,**/db/**,**/*model*,**/*entity*,**/prisma/**,**/drizzle/**,**/*migration*"
 tags: [security]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Data Classification Standards
 

package/rules/hatch3r-deep-context.md

@@ -5,6 +5,7 @@ description: Adaptive pre-implementation analysis — complexity scoring, requir
 scope: always
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Deep Context Analysis
 
@@ -70,7 +71,7 @@ Pre-Implementation Summary:
   Cross-cutting concerns: {list with status}
 ```
 
-Do NOT proceed to implementation until all unresolved questions are answered by the user.
+**Hard gate, not advisory.** Do NOT proceed to implementation until all unresolved questions are answered by the user AND the user has explicitly confirmed the Pre-Implementation Summary (a reply matching "proceed", "confirmed", "yes — implement", or an equivalent affirmation in context). Until that confirmation arrives, the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool, AND MUST NOT spawn `hatch3r-implementer` or `hatch3r-fixer`. Read-only and reasoning tools (`Read`, `Grep`, `Glob`, `Bash` for read-only commands, `WebFetch`, `WebSearch`, `Task` with researcher-only sub-agents) remain available so the orchestrator can answer follow-up clarifying questions without breaching the gate.
 
 ## Passing Context to Implementer
 

package/rules/hatch3r-deep-context.mdc

@@ -66,7 +66,7 @@ Pre-Implementation Summary:
   Cross-cutting concerns: {list with status}
 ```
 
-Do NOT proceed to implementation until all unresolved questions are answered by the user.
+**Hard gate, not advisory.** Do NOT proceed to implementation until all unresolved questions are answered by the user AND the user has explicitly confirmed the Pre-Implementation Summary (a reply matching "proceed", "confirmed", "yes — implement", or an equivalent affirmation in context). Until that confirmation arrives, the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool, AND MUST NOT spawn `hatch3r-implementer` or `hatch3r-fixer`. Read-only and reasoning tools (`Read`, `Grep`, `Glob`, `Bash` for read-only commands, `WebFetch`, `WebSearch`, `Task` with researcher-only sub-agents) remain available so the orchestrator can answer follow-up clarifying questions without breaching the gate.
 
 ## Passing Context to Implementer
 

package/rules/hatch3r-dependency-management.md

@@ -5,6 +5,7 @@ description: Lockfile discipline, CVE scanning, transitive dependency audits, ma
 scope: "**/package.json,**/package-lock.json,**/yarn.lock,**/pnpm-lock.yaml,**/Cargo.toml,**/Cargo.lock,**/requirements*.txt,**/pyproject.toml,**/go.mod,**/go.sum,**/Gemfile*"
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Dependency Management
 

package/rules/hatch3r-feature-flags.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*feature-flag*,**/*featureFlag*,**/*feature_flag*,**/config/**"
 tags: [implementation]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Feature Flags
 

package/rules/hatch3r-git-conventions.md

@@ -5,6 +5,7 @@ description: Conventional Commits type list, subject line rules, breaking-change
 scope: "**/.git/**,**/.gitignore,**/.gitattributes,**/.gitmodules,**/COMMIT_EDITMSG"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Git Conventions
 

package/rules/hatch3r-i18n.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx,src/**/*.ts,**/locales/**,**/i18n/**,**/*i18n*,**/*locale*"
 tags: [implementation, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Internationalization & RTL
 

package/rules/hatch3r-iteration-summary.md

@@ -0,0 +1,88 @@
+---
+id: hatch3r-iteration-summary
+type: rule
+description: Every user-facing iteration ends with the canonical Iteration Summary block — a 5-field contract exposing status, gaps, and confidence at a glance.
+scope: always
+tags: [core]
+quality_charter: agents/shared/quality-charter.md
+precedence: high
+cache_friendly: true
+---
+# Iteration Summary Contract
+
+Every iteration with the user ends with the canonical block defined below — not a free-form prose paragraph. The block appears at the very end of the assistant turn, after any code, explanations, or tool-call results.
+
+## When This Applies
+
+Every user-facing iteration, regardless of size — multi-step coding tasks, single-file edits, read-only answers, failed or blocked attempts. No exceptions.
+
+The per-turn pipeline-state header (defined in `hatch3r-agent-orchestration` → Per-Turn Pipeline-State Header) is a separate start-of-turn artifact and does not replace this end-of-turn block.
+
+## The Required Block
+
+Use this exact shape with these exact field names:
+
+```markdown
+## Iteration Summary
+
+**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
+**Outcome:** {one sentence — the bottom line}
+
+**Done:**
+- {what was completed this iteration}
+
+**Not Done / Deferred / Unverified:**
+- {required even if "None — full scope completed"}
+
+**Open Questions / Blockers:**
+- {required even if "None"}
+
+**Confidence:** high | medium | low — {one-sentence basis}
+```
+
+`Status` is a closed enum:
+
+- **SUCCESS** — all in-scope work completed and verified.
+- **PARTIAL** — some in-scope work completed; remainder listed under Not Done.
+- **FAILED** — attempted but did not produce a usable result; reason in Outcome.
+- **BLOCKED** — cannot proceed without user input or external resolution.
+
+## Optional Sections
+
+Append only when they carry information. Do not include empty headers.
+
+```markdown
+**Artifacts Touched:**
+| Path | Action | Notes |
+| ---- | ------ | ----- |
+| {file} | created/modified/deleted | {one line} |
+
+**Verifications Run:**
+| Check | Result |
+| ----- | ------ |
+| {command or test} | pass/fail/skipped |
+
+**Earliest Failure Point:** {file:line or step name}  ← only when Status ≠ SUCCESS
+
+**Suggested Next Action:** {one line}
+```
+
+## Field Semantics
+
+- **Outcome** is one sentence. The user should grasp what happened from this line alone.
+- **Done** lists completed actions, not intentions. "Wrote tests" beats "Will write tests".
+- **Not Done / Deferred / Unverified** is required and may not be silently skipped. If full scope was completed, write `None — full scope completed`. If anything was attempted but not verified, list it here, not under Done.
+- **Open Questions / Blockers** surfaces ambiguity proactively. Write `None` only after checking.
+- **Confidence** uses the quality charter §1 scale. The one-sentence basis must name what was verified (high), what pattern was followed (medium), or that the answer is professional judgment (low).
+
+## Anti-Patterns
+
+- Substituting a prose paragraph for the block.
+- Omitting the `## Iteration Summary` anchor — downstream agents and orchestrators locate the block by this header.
+- Writing "None" reflexively without checking — list the uncertainty when in doubt.
+- Inflating confidence — if you did not verify, say medium and name the unknown.
+- Burying unverified work in `Done` — attempted-but-not-verified belongs in Not Done / Unverified.
+
+## Reference
+
+Confidence semantics: `agents/shared/quality-charter.md` §1.

package/rules/hatch3r-iteration-summary.mdc

@@ -0,0 +1,83 @@
+---
+description: Every user-facing iteration ends with the canonical Iteration Summary block — a 5-field contract exposing status, gaps, and confidence at a glance.
+alwaysApply: true
+precedence: high
+---
+# Iteration Summary Contract
+
+Every iteration with the user ends with the canonical block defined below — not a free-form prose paragraph. The block appears at the very end of the assistant turn, after any code, explanations, or tool-call results.
+
+## When This Applies
+
+Every user-facing iteration, regardless of size — multi-step coding tasks, single-file edits, read-only answers, failed or blocked attempts. No exceptions.
+
+The per-turn pipeline-state header (defined in `hatch3r-agent-orchestration` → Per-Turn Pipeline-State Header) is a separate start-of-turn artifact and does not replace this end-of-turn block.
+
+## The Required Block
+
+Use this exact shape with these exact field names:
+
+```markdown
+## Iteration Summary
+
+**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
+**Outcome:** {one sentence — the bottom line}
+
+**Done:**
+- {what was completed this iteration}
+
+**Not Done / Deferred / Unverified:**
+- {required even if "None — full scope completed"}
+
+**Open Questions / Blockers:**
+- {required even if "None"}
+
+**Confidence:** high | medium | low — {one-sentence basis}
+```
+
+`Status` is a closed enum:
+
+- **SUCCESS** — all in-scope work completed and verified.
+- **PARTIAL** — some in-scope work completed; remainder listed under Not Done.
+- **FAILED** — attempted but did not produce a usable result; reason in Outcome.
+- **BLOCKED** — cannot proceed without user input or external resolution.
+
+## Optional Sections
+
+Append only when they carry information. Do not include empty headers.
+
+```markdown
+**Artifacts Touched:**
+| Path | Action | Notes |
+| ---- | ------ | ----- |
+| {file} | created/modified/deleted | {one line} |
+
+**Verifications Run:**
+| Check | Result |
+| ----- | ------ |
+| {command or test} | pass/fail/skipped |
+
+**Earliest Failure Point:** {file:line or step name}  ← only when Status ≠ SUCCESS
+
+**Suggested Next Action:** {one line}
+```
+
+## Field Semantics
+
+- **Outcome** is one sentence. The user should grasp what happened from this line alone.
+- **Done** lists completed actions, not intentions. "Wrote tests" beats "Will write tests".
+- **Not Done / Deferred / Unverified** is required and may not be silently skipped. If full scope was completed, write `None — full scope completed`. If anything was attempted but not verified, list it here, not under Done.
+- **Open Questions / Blockers** surfaces ambiguity proactively. Write `None` only after checking.
+- **Confidence** uses the quality charter §1 scale. The one-sentence basis must name what was verified (high), what pattern was followed (medium), or that the answer is professional judgment (low).
+
+## Anti-Patterns
+
+- Substituting a prose paragraph for the block.
+- Omitting the `## Iteration Summary` anchor — downstream agents and orchestrators locate the block by this header.
+- Writing "None" reflexively without checking — list the uncertainty when in doubt.
+- Inflating confidence — if you did not verify, say medium and name the unknown.
+- Burying unverified work in `Done` — attempted-but-not-verified belongs in Not Done / Unverified.
+
+## Reference
+
+Confidence semantics: `agents/shared/quality-charter.md` §1.

package/rules/hatch3r-learning-consult.md

@@ -5,6 +5,7 @@ description: Consult .agents/learnings/ for pitfalls, patterns, and past decisio
 scope: "**/.agents/learnings/**,**/learnings/**"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Learning Consultation
 

package/rules/hatch3r-migrations.md

@@ -5,6 +5,7 @@ description: Database migration and schema change patterns for the project
 scope: "**/migrations/**,**/*migration*,**/migrate/**,**/seeds/**,**/seeders/**,**/prisma/migrations/**,**/drizzle/**,**/knex/**"
 tags: [implementation, brownfield]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Migrations
 

package/rules/hatch3r-observability-logging.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*log*,**/*logger*,**/*logging*,**/*error*,**/observability/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Observability -- Logging & Error Reporting
 

package/rules/hatch3r-observability-metrics.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*metric*,**/*slo*,**/*sli*,**/*alert*,**/*dashboard*,**/observability/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Observability -- Metrics, SLOs & Alerting
 

package/rules/hatch3r-observability-tracing-detail.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/*agent*,**/observability/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Observability -- Tracing Extended Reference
 

package/rules/hatch3r-observability-tracing.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*trac*,**/*span*,**/*telemetry*,**/*otel*,**/observability/**"
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Observability -- Distributed Tracing & OpenTelemetry
 

package/rules/hatch3r-observability.md

@@ -6,6 +6,7 @@ scope: conditional
 tags: [devops]
 quality_charter: agents/shared/quality-charter.md
 deprecated: true
+cache_friendly: true
 ---
 # Observability (Deprecated Redirect)
 

package/rules/hatch3r-performance-budgets.md

@@ -6,6 +6,7 @@ scope: conditional
 globs: "**/*perf*,**/*benchmark*,**/*budget*,**/lighthouse*,**/*.perf.*"
 tags: [performance]
 quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
 ---
 # Performance Budgets