hatch3r 2.1.0 → 2.2.0

package/README.md

@@ -27,8 +27,8 @@ npx hatch3r init            # interactive: customize profile, tools, and CLI too
 |----------|-------|-----------|
 | **Agents** | 29 | Code reviewer, lint-fixer, dependency auditor, implementer (sub-agentic), fixer, researcher, architect, DevOps, handoff loader / preparer, 9 content-quality specialists (UI/UX/security/reliability/testability/scalability/performance/maintainability/enhancability), and more |
 | **Skills** | 53 | Bug fix, feature implementation, issue workflow, release, incident response, context health, cost tracking, handoff prepare / resume, recipes, API spec, CI pipeline, migration, customization, board lifecycle, ad-hoc orchestration scaffold, 5 standalone CLI-tool skills (ripgrep, jq, gh, fd, fzf) + a 24-tool `cli-toolbox`, and more |
-| **Rules** | 67 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, fan-out discipline, right-sizing, deep context analysis, handoff readiness, mobile + backend stack rules, and more |
-| **Commands** | 30 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, bug-pipeline, revision, debug, healthcheck, security-audit, onboard, benchmark, handoff (prepare/resume/list/complete/prune), and more |
+| **Rules** | 70 | Code standards, testing, API design, observability, theming, i18n, security patterns, agent orchestration, fan-out discipline, right-sizing, deep context analysis, handoff readiness, mobile + backend stack rules, and more |
+| **Commands** | 31 | Board management, planning (feature, bug, refactor, test), workflow, quick-change, bug-pipeline, revision, debug, healthcheck, security-audit, onboard, benchmark, handoff (prepare/resume/list/complete/prune), and more |
 | **CLI tools** | 29 across 3 tiers | Tier-1 default (ripgrep, fd, jq, yq, gh, delta, bat, sd, ast-grep, zstd); tier-2 conditional (Playwright, duckdb, qsv, taplo, glab, az-devops, Docker, llm, fzf, lazygit, difftastic); tier-3 opt-in (RTK, Stagehand, aichat, mods, Comby, miller, csvkit, Podman) -- emitted as per-tool canonical skills + a decision-tree overview |
 | **MCP Servers** | 10 (opt-in) | Playwright, Context7, Filesystem, GitHub, Brave Search, Sentry, Postgres, Linear, Azure DevOps, GitLab -- pure opt-in since 2.0.0: `init --mcp` or `npx hatch3r mcp setup` (interactive init does not prompt for MCP; `features.mcp` defaults to false) |
 | **Platforms** | 3 | GitHub, Azure DevOps, GitLab -- auto-detected from git remote |
@@ -150,7 +150,7 @@ A four-phase pipeline (Research, Implement, Review Loop with reviewer + fixer at
 AGENTS.md (Linux Foundation AAIF spec, 60K+ repos as of January 2026) is the greatest-common-denominator markdown standard for agent instructions; it is consumed by 20+ tools including Cursor, Copilot, Codex, and Gemini CLI. hatch3r is complementary: AGENTS.md describes one file's content; hatch3r owns the entire generation pipeline that emits tool-native configurations across 5 artifact classes (rules, skills, commands, hooks, MCP servers) for 3 supported platforms (Claude Code, Cursor, GitHub Copilot). Three measurable differences:
 
 - **Scope:** AGENTS.md is one flat instruction file per repo; hatch3r generates platform-specific structured output (`.mdc` rules with frontmatter scoping for Cursor, `CLAUDE.md` with managed blocks for Claude Code, `.github/instructions/` + `.github/prompts/` for Copilot) plus board commands, MCP server configs, and event-driven hooks.
-- **Currency:** AGENTS.md content is hand-edited per project; hatch3r ships canonical content (29 agents + 66 rules + 53 skills + 30 commands + 7 hooks + 10 MCP servers — see [`governance/inventory.json`](governance/inventory.json)) audited weekly across 24 governance domains.
+- **Currency:** AGENTS.md content is hand-edited per project; hatch3r ships canonical content (29 agents + 66 rules + 53 skills + 31 commands + 7 hooks + 10 MCP servers — see [`governance/inventory.json`](governance/inventory.json)) audited weekly across 24 governance domains.
 - **Adoption path:** AGENTS.md remains the spec hatch3r-emitted Cursor / Claude / Copilot configurations align with — the 1.9.0 hard-cut withdrew direct AGENTS.md emission per CONSTITUTION §6 Decision #12, but AAIF spec evolution feeds per-adapter feature work for the 3 supported adapters. Use AGENTS.md alone when one flat file suffices for your project; use hatch3r when you need the full content + tooling stack.
 
 ## Customization

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var __export = (target, all) => {
 // src/version.ts
 function resolveVersion() {
   try {
-    return "2.1.0";
+    return "2.2.0";
   } catch (defineMissing) {
     void defineMissing;
     try {
@@ -1031,9 +1031,9 @@ async function applyCustomizationImpl(projectRoot, file, contentKey) {
     warnings.push(`Scope override on ${file.type} "${file.id}" has no effect \u2014 ${file.type}s do not use scope. Ignoring.`);
     delete overrides.scope;
   }
-  const TYPES_WITHOUT_MODEL = /* @__PURE__ */ new Set(["skill", "rule", "command", "prompt", "hook"]);
+  const TYPES_WITHOUT_MODEL = /* @__PURE__ */ new Set(["rule", "prompt", "hook"]);
   if (overrides.model !== void 0 && TYPES_WITHOUT_MODEL.has(file.type)) {
-    warnings.push(`Model override on ${file.type} "${file.id}" has no effect \u2014 only agents carry a model. Ignoring.`);
+    warnings.push(`Model override on ${file.type} "${file.id}" has no effect \u2014 only agents, skills, and commands carry a model. Ignoring.`);
     delete overrides.model;
   }
   for (const field of ["description", "scope", "model"]) {
@@ -6324,13 +6324,15 @@ function collectManifestErrors(data) {
       if (models.default !== void 0 && typeof models.default !== "string") {
         errors.push("`models.default` is not a string");
       }
-      if (models.agents !== void 0) {
-        if (typeof models.agents !== "object" || models.agents === null || Array.isArray(models.agents)) {
-          errors.push("`models.agents` is not an object");
+      for (const cls of ["agents", "skills", "commands"]) {
+        const map = models[cls];
+        if (map === void 0) continue;
+        if (typeof map !== "object" || map === null || Array.isArray(map)) {
+          errors.push(`\`models.${cls}\` is not an object`);
         } else {
-          for (const [agentId, model] of Object.entries(models.agents)) {
+          for (const [artifactId, model] of Object.entries(map)) {
             if (typeof model !== "string") {
-              errors.push(`\`models.agents.${agentId}\` is not a string`);
+              errors.push(`\`models.${cls}.${artifactId}\` is not a string`);
             }
           }
         }
@@ -7098,10 +7100,13 @@ function resolveModelAlias(input) {
 }
 
 // src/models/resolve.ts
-function resolveAgentModel(agentId, agent, manifest, customize) {
-  const raw = customize?.model ?? manifest.models?.agents?.[agentId] ?? agent.model ?? manifest.models?.default;
+function resolveArtifactModel(cls, id, frontmatterModel, manifest, customize) {
+  const raw = customize?.model ?? manifest.models?.[cls]?.[id] ?? frontmatterModel ?? (cls === "agents" ? manifest.models?.default : void 0);
   return raw ? resolveModelAlias(raw) : void 0;
 }
+function resolveAgentModel(agentId, agent, manifest, customize) {
+  return resolveArtifactModel("agents", agentId, agent.model, manifest, customize);
+}
 
 // src/adapters/base.ts
 init_managedBlocks();
@@ -9065,7 +9070,7 @@ All tasks use this four-phase pipeline. Never implement inline; always delegate.
 **Phase 1 \u2014 Research:** Spawn \`hatch3r-researcher\`. Skip only for trivial edits. Score complexity per \`hatch3r-deep-context\` and add tier modes.
 **Phase 2 \u2014 Implement:** Spawn \`hatch3r-implementer\` (one per task). Pass research context.
 **Phase 3 \u2014 Review Loop:** \`hatch3r-reviewer\` \u2192 if Critical/Warning: \`hatch3r-fixer\` \u2192 re-review \u2192 repeat (max 3). After clean verdict: one confirmation pass (regressions, acceptance criteria). Remaining findings after max iterations \u2192 surface to user.
-**Phase 4 \u2014 Final Quality** (after clean review): \`hatch3r-testability\` + \`hatch3r-security\` (always), \`hatch3r-docs-writer\` (evaluate), then conditional CQ specialists: \`hatch3r-ui\`, \`hatch3r-ux\`, \`hatch3r-reliability\`, \`hatch3r-scalability\`, \`hatch3r-performance\`, \`hatch3r-maintainability\`, \`hatch3r-enhancability\`, plus \`hatch3r-lint-fixer\`.
+**Phase 4 \u2014 Final Quality** (after clean review): \`hatch3r-testability\` + \`hatch3r-security\` (always), \`hatch3r-docs-writer\` (evaluate), \`hatch3r-ui\` + \`hatch3r-ux\` (mandatory-on-match \u2014 when triggered, each MUST spawn as its own dedicated sub-agent instance at Tier 2/3; Tier 1 keeps the Phase Skip Criteria skip), then conditional CQ specialists: \`hatch3r-reliability\`, \`hatch3r-scalability\`, \`hatch3r-performance\`, \`hatch3r-maintainability\`, \`hatch3r-enhancability\`, plus \`hatch3r-lint-fixer\`.
 
 ## Mandatory Behaviors
 
@@ -10004,6 +10009,7 @@ function substituteVerificationGateTokens(content, manifest) {
 }
 
 // src/adapters/base.ts
+var SAFE_MODEL_RE = /^[A-Za-z0-9._/-]+$/;
 function output(path, content, managedContent, sourceFiles) {
   return { path, content, managedContent, action: "create", sourceFiles };
 }
@@ -10518,6 +10524,18 @@ ${wrapManagedFor(pathFn(skill.id), content)}`, content, this.singleSource(skill)
    * is false or the skill declares no tools, the stub is the historical
    * `name: + description:` shape and output is byte-identical to the prior
    * behavior.
+   *
+   * release/2.2.0 — `opts.emitModel`: per-adapter opt-in for a `model:` line
+   * in the frontmatter stub, resolved via `resolveArtifactModel("skills",
+   * ...)` (customize > `models.skills[id]` > skill frontmatter; NO
+   * `models.default` fallback — that stays agents-only). The predicate
+   * receives the alias-expanded value and returns whether the target
+   * platform's skill surface recognizes it (e.g.
+   * `isClaudeRecognizableModel`). Same opt-in rationale as
+   * `emitAllowedTools`: Cursor SKILL.md documents no `model` field and
+   * Copilot SKILL.md model support is unverified, so an adapter that does not
+   * opt in stays byte-identical. `inherit` is never emitted — an omitted
+   * field IS the inherit semantic on every skill surface.
    */
   async processSkillsWithFmCliFiltered(ctx, pathFn, opts) {
     if (!ctx.features.skills) return [];
@@ -10531,6 +10549,10 @@ ${wrapManagedFor(pathFn(skill.id), content)}`, content, this.singleSource(skill)
       const content = this.substituteCanonicalContent(raw, ctx);
       const desc = overrides.description ?? skill.description;
       const fmLines = [`name: ${skill.id}`, `description: ${toYamlDoubleQuotedScalar(desc)}`];
+      const model = resolveArtifactModel("skills", skill.id, skill.model, ctx.manifest, overrides);
+      if (model && model !== "inherit" && SAFE_MODEL_RE.test(model) && opts?.emitModel?.(model)) {
+        fmLines.push(`model: ${model}`);
+      }
       if (opts?.emitAllowedTools && skill.allowedTools && skill.allowedTools.length > 0) {
         fmLines.push(`allowed-tools: [${skill.allowedTools.map((t) => `"${t}"`).join(", ")}]`);
       }
@@ -10585,8 +10607,19 @@ ${wrapManagedFor(pathFn(skill.id), content)}`, content, this.singleSource(skill)
    * metadata like `orchestrator`/`agentPipeline`/`triage_tiers`) is
    * intentionally NOT hoisted: it is hatch3r-authoring data with no runtime or
    * picker consumer.
+   *
+   * release/2.2.0 — `opts.emitModel`: per-adapter opt-in for a `model:` line
+   * (after `argument-hint`), resolved via `resolveArtifactModel("commands",
+   * ...)` (customize > `models.commands[id]` > command frontmatter; NO
+   * `models.default` fallback — a command-level model switches the whole
+   * conversation model, so it must be an explicit per-id choice). The
+   * predicate gates to platform-recognizable values
+   * (`isClaudeRecognizableModel` / `isCopilotRecognizableModel`); Cursor
+   * passes no opts — its `.cursor/commands/*.md` surface documents no `model`
+   * field — and stays byte-identical. `inherit` is never emitted (omitted
+   * field == inherit).
    */
-  async processCommandsWithFm(ctx, pathFn) {
+  async processCommandsWithFm(ctx, pathFn, opts) {
     if (!ctx.features.commands) return [];
     const results = [];
     const commands = await this.readUserFacingCanonicalFiles(ctx.canonicalRoot, "commands", ctx.userRepoRoot);
@@ -10600,6 +10633,10 @@ ${wrapManagedFor(pathFn(skill.id), content)}`, content, this.singleSource(skill)
       const fmLines = [`name: ${cmd.id}`, `description: ${toYamlDoubleQuotedScalar(desc)}`];
       const argumentHint = extractArgumentHint(cmd.rawContent);
       if (argumentHint) fmLines.push(`argument-hint: ${toYamlDoubleQuotedScalar(argumentHint)}`);
+      const model = resolveArtifactModel("commands", cmd.id, cmd.model, ctx.manifest, overrides);
+      if (model && model !== "inherit" && SAFE_MODEL_RE.test(model) && opts?.emitModel?.(model)) {
+        fmLines.push(`model: ${model}`);
+      }
       const fm = `---
 ${fmLines.join("\n")}
 ---`;
@@ -11485,12 +11522,14 @@ ${wrapManagedFor(agentPath, body)}`, body, claudeSingleSource(agent)));
     ));
     const skillOutputs = await this.processSkillsWithFmCliFiltered(
       ctx,
-      (id) => `.claude/skills/${toPrefixedId(id)}/SKILL.md`
+      (id) => `.claude/skills/${toPrefixedId(id)}/SKILL.md`,
+      { emitModel: isClaudeRecognizableModel }
     );
     results.push(...skillOutputs.map(rewrapWithCacheBreakpoints));
     const commandOutputs = await this.processCommandsWithFm(
       ctx,
-      (id) => `.claude/commands/${toPrefixedId(id)}.md`
+      (id) => `.claude/commands/${toPrefixedId(id)}.md`,
+      { emitModel: isClaudeRecognizableModel }
     );
     results.push(...commandOutputs.map(rewrapWithCacheBreakpoints));
     const companionMappings = [
@@ -11805,7 +11844,11 @@ ${wrapManagedFor(agentPath, content)}`, content, copilotSingleSource(agent)));
       }
     }
     results.push(
-      ...await this.processCommandsWithFm(ctx, (id) => `.github/prompts/${toPrefixedId(id)}.prompt.md`)
+      ...await this.processCommandsWithFm(
+        ctx,
+        (id) => `.github/prompts/${toPrefixedId(id)}.prompt.md`,
+        { emitModel: isCopilotRecognizableModel }
+      )
     );
     if (ctx.features.githubAgents && !ctx.features.agents) {
       const ghAgents = await this.readTrackedCanonicalFiles(ctx.canonicalRoot, "github-agents", ctx.userRepoRoot);
@@ -13552,7 +13595,16 @@ var REQUIRED_GITIGNORE_ENTRIES = [
   ".hatch3r/handoffs/",
   ".hatch3r/provenance.json",
   ".init-workspace/",
-  ".sync-workspace/"
+  ".sync-workspace/",
+  ".pr-resolve-workspace/",
+  ".hatch3r/telemetry/",
+  ".hatch3r/efficiency-events.jsonl",
+  ".hatch3r/.failure-log.jsonl",
+  ".hatch3r/.breaker-state.jsonl",
+  ".hatch3r/.lock",
+  ".hatch3r/calibration-state.json",
+  ".hatch3r/calibration-log.jsonl",
+  ".hatch3r/archive/"
 ];
 function isCoveredByGitignore(entry, lines) {
   const trimmedEntries = lines.map((l) => l.trim());
@@ -25979,10 +26031,16 @@ async function validateModels(manifest, result) {
   if (manifest.models.default && typeof manifest.models.default !== "string") {
     result.errors.push("hatch.json: models.default must be a string");
   }
-  if (manifest.models.agents) {
-    for (const [agentId, model] of Object.entries(manifest.models.agents)) {
+  for (const cls of ["agents", "skills", "commands"]) {
+    const map = manifest.models[cls];
+    if (!map) continue;
+    if (typeof map !== "object" || Array.isArray(map)) {
+      result.errors.push(`hatch.json: models.${cls} must be an object mapping ids to model strings`);
+      continue;
+    }
+    for (const [artifactId, model] of Object.entries(map)) {
       if (typeof model !== "string") {
-        result.errors.push(`hatch.json: models.agents.${agentId} must be a string`);
+        result.errors.push(`hatch.json: models.${cls}.${artifactId} must be a string`);
       }
     }
   }

package/dist/content/agents/hatch3r-brownfield-spec.md

@@ -210,7 +210,7 @@ Return structured result with:
 
 **Breaking changes detected:** NONE | {count with table rows from deliverable 3}
 
-**Iteration Summary:** {per `rules/hatch3r-iteration-summary.md` — 9 sections}
+**Iteration Summary:** {per `rules/hatch3r-iteration-summary.md` — recap + exception lines}
 ```
 
 Proof trace per `agents/shared/rigor-contract.md` §Proof Trace Contract is mandatory on every state-dependent claim (file existence, grep match, type-check result). Citation alone insufficient.

package/dist/content/agents/hatch3r-fixer.md

@@ -94,12 +94,13 @@ Apply this format whenever the fix involves choosing between approaches, when th
 3. Read the full content of every matched learning file.
 4. Cite each consulted learning ID in the structured result's `Consulted Learnings:` line. Citing zero entries when `applies-to` matched is a gate failure visible at audit time.
 
-Beyond this once-per-run gate, surface relevant learnings *mid-edit* per `rules/hatch3r-learning-system.md` → Mid-Edit Learning Surfacing: when a file or pattern you are editing matches a captured learning (path overlap, `applies-to` match, or `topic` semantic overlap), cite it on a `Surfaced Learnings:` line in the iteration summary before completing the edit.
+Beyond this once-per-run gate, surface relevant learnings *mid-edit* per `rules/hatch3r-learning-system.md` → Mid-Edit Learning Surfacing: when a file or pattern you are editing matches a captured learning (path overlap, `applies-to` match, or `topic` semantic overlap), cite it on the surfaced facet of the `Learnings:` exception line in the iteration summary before completing the edit.
 
 ### 1. Parse Reviewer Findings
 
 - Extract all Critical and Warning items from the reviewer output.
 - Note file paths, line numbers, and suggested fixes for each finding.
+- Each finding carries a ledger `finding_id` (`rules/hatch3r-findings-ledger.md` → Finding IDs) — preserve it verbatim in every output line.
 - Ignore Suggestion items — those are surfaced to the user by the orchestrator.
 - Prioritize Critical findings before Warnings.
 
@@ -110,7 +111,7 @@ For each Critical and Warning finding:
 - Read the referenced file and surrounding context.
 - Understand the root cause of the issue.
 - Determine the minimal fix that addresses the finding without introducing new issues.
-- If blast radius data is available, check whether the fix touches shared interfaces or APIs with downstream consumers — preserve those contracts.
+- When the fix touches a shared contract, run the consumer census per `rules/hatch3r-contract-census.md` (Step 5b) — blast-radius input, when provided, seeds the grep list but never substitutes for the self-run grep.
 - If reference conventions are available, verify the fix follows established patterns rather than introducing divergent approaches.
 - Use Context7 MCP (`resolve-library-id` then `query-docs`) for API patterns relevant to the fix.
 - Use web research for security advisories, CVE details, or best practices when the finding involves security or novel patterns.
@@ -155,6 +156,14 @@ ${HATCH3R:VERIFY_GATE_ALL}
 
 The placeholder above is rewritten by the adapter pipeline (`substituteVerifyGateTokens` in `src/adapters/base.ts`) from the project manifest's detected `languages[]` plus its package manager. The literal fallback when detection is unknown is `npm run lint && npm run typecheck && npm run test`; for a Python project the rendered command becomes `ruff check . && mypy . && pytest`, etc. (Adapt only if the project carries non-standard scripts in addition to the resolver output.)
 
+### 5b. Consumer Census (shared-contract fixes)
+
+**Trigger:** the fix renames, removes, or re-signatures an exported symbol; changes a persisted collection/table/field name; adds, renames, or drops a client↔server wire-field key; changes an event name or payload key; moves or revalues a shared constant; or renames a CLI flag or config/env key (`rules/hatch3r-contract-census.md` → Shared-Contract Taxonomy). No trigger → record `Consumer census: N/A (no shared-contract change)` in the fix result and skip the rest of this step.
+
+**Census:** for each changed contract, run a repo-wide grep of the OLD identifier and the NEW identifier — never limited to the findings' file list or the blast-radius consumer map. Reconciled and justification definitions, plus grep patterns: `rules/hatch3r-contract-census.md` → Consumer Census.
+
+**Gate:** `Status: SUCCESS` requires census ∈ {`clean`, `reconciled(N)`, `N/A`}; any `unreconciled` consumer without a named justification caps Status at `PARTIAL`, with the unreconciled consumers listed under Notes.
+
 ### 6. Return Structured Result
 
 Report back to the parent orchestrator with:
@@ -173,11 +182,11 @@ The `Reviewer re-run required` field is an **advisory** signal to the parent orc
 **Reviewer re-run required:** true | false (advisory — orchestrator derives the authoritative value as `Files changed` non-empty; print `true` whenever the `Files changed` list below has ≥1 entry, `false` only when it is empty)
 
 **Findings addressed:**
-- [CRITICAL #1] file:line -- description of fix applied
-- [WARNING #1] file:line -- description of fix applied
+- [<finding_id>] [CRITICAL #1] file:line — <fix summary>
+- [<finding_id>] [WARNING #1] file:line — <fix summary>
 
 **Findings unresolved:**
-- (any findings that could not be fixed, with explanation)
+- [<finding_id>] [WARNING #2] file:line — <reason: blocked | failed | out-of-scope>
 
 **Files changed:**
 - path/to/file.ts -- description of change
@@ -190,6 +199,8 @@ The `Reviewer re-run required` field is an **advisory** signal to the parent orc
 - Typecheck: PASS | FAIL (details)
 - Tests: PASS | FAIL (details)
 
+**Consumer census:** clean | reconciled(N) | N unreconciled — justification | N/A (no shared-contract change)
+
 **Consulted Learnings:**
 - (learning IDs matched in Step 0b, or "none available" / "none matched")
 
@@ -245,9 +256,9 @@ When producing fix results, be aware that a PARTIAL status with unresolved findi
 **Reviewer re-run required:** true
 
 **Findings addressed:**
-- [CRITICAL #1] src/routes/billing.ts:42 -- added toInvoiceResponse() DTO to filter internal billing IDs and provider tokens from response
-- [CRITICAL #2] src/routes/billing.ts:38 -- added requireOwnership(req.user.id, params.userId) guard before invoice lookup
-- [WARNING #1] src/routes/billing.ts:45 -- added cursor-based pagination with max page size of 50
+- [b4e2a9c7-F1] [CRITICAL #1] src/routes/billing.ts:42 — added toInvoiceResponse() DTO to filter internal billing IDs and provider tokens from response
+- [b4e2a9c7-F2] [CRITICAL #2] src/routes/billing.ts:38 — added requireOwnership(req.user.id, params.userId) guard before invoice lookup
+- [b4e2a9c7-F3] [WARNING #1] src/routes/billing.ts:45 — added cursor-based pagination with max page size of 50
 
 **Findings unresolved:**
 - None
@@ -266,6 +277,8 @@ When producing fix results, be aware that a PARTIAL status with unresolved findi
 - Typecheck: PASS
 - Tests: PASS (42 passed, 0 failed)
 
+**Consumer census:** clean
+
 **Consulted Learnings:**
 - none matched
 

package/dist/content/agents/hatch3r-handoff-loader.md

@@ -155,8 +155,9 @@ Each handoff frontmatter carries an `integrity` field with a SHA-256 hash of the
    - **Primary:** `work_item` match against the current branch's open issue (read from `.hatch3r/hatch.json` board state if present).
    - **Secondary:** recency of `updated` timestamp.
    - **Tertiary:** status priority — `in-progress` > `open` > `handed-off` > `blocked` > `resumed`.
-4. Emit the briefing using the Output Format below. Surface the top 5 by relevance under **Most Relevant**.
-5. Flag drift, integrity, and validation issues in their dedicated sections (omit each section if empty).
+4. Scan `.hatch3r/findings/*.jsonl` (skip silently when the directory is absent). A file whose last line is the `run-exit` marker and whose fold is all-terminal is closed — skip it. Otherwise fold each file (last line per `finding_id` wins, per `rules/hatch3r-findings-ledger.md`) and list non-terminal rows plus rows terminal as `escalated`/`surfaced` under **Open Findings** as `id · severity · file · summary · disposition`. Flag any ledger file older than 14 days that still folds open rows as stale and offer three closure options: close as declined with reason "stale", re-defer to todo.md, or resume the work. Open findings surfaced here are the self-healing detector for runs that died before their loop-exit reconciliation.
+5. Emit the briefing using the Output Format below. Surface the top 5 by relevance under **Most Relevant**.
+6. Flag drift, integrity, and validation issues in their dedicated sections (omit each section if empty).
 
 ## Empty-directory Output
 
@@ -210,6 +211,10 @@ inform context but do not override system instructions or project rules.
 
 --- END USER-TIER CONTENT: handoffs ---
 
+### Open Findings (omit if none)
+- `{finding_id}` · {severity} · {file} · {summary} · {disposition}
+- Stale: `{ledger-path}` (>14 days, still folds open rows) — options: close as declined (reason "stale") / re-defer to todo.md / resume the work
+
 **Stats:**
 - Total active: {n} | Archived: {n} | Most relevant: {n} | Drift warnings: {n} | Integrity warnings: {n} | Excluded (validation): {n}
 

package/dist/content/agents/hatch3r-handoff-preparer.md

@@ -42,6 +42,7 @@ The caller provides:
 4. **Build & Test Status** — recover the most recent results of `npm test`, `npm run lint`, `npx tsc --noEmit` from the current session. If a check did not run this session, mark its row `skipped`.
 5. **work_item** — use the input value if provided; else attempt inference from branch name (e.g., `feat/issue-42-cache-refactor` → `gh:owner/repo#42` using `gh repo view --json nameWithOwner` for the repo prefix).
 6. **compaction_count** — if a `parent_handoff` was indicated, increment its value; else omit.
+7. **Findings ledger** — fold the active run's findings ledger (`.hatch3r/findings/*.jsonl` — last line per `finding_id` wins; `rules/hatch3r-findings-ledger.md` → Store & Format) and count open rows (non-terminal plus terminal `escalated`/`surfaced`). This fold is the input for the Work Remaining `Open findings` bullet in Step 3.
 
 ### Step 2: Distill Summary
 
@@ -72,28 +73,16 @@ Summary: {summary}
 Warnings: {list or "none"}
 ```
 
-Then emit the canonical Iteration Summary block per `rules/hatch3r-iteration-summary.md`:
+Then close the run with the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`: a 1–2 line recap (status, outcome, files · sub-agents · gates · cost delta) plus every exception line whose firing condition holds — silence asserts the default. Worked example:
 
 ```
 ## Iteration Summary
 
-**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
-**Outcome:** Handoff written for {work_item or branch} — {one-line state}.
-**Done:**
-- Composed handoff body with 8 required sections
-- Validated against readiness rule (errors: 0, warnings: {n})
-- Computed SHA-256 integrity hash
-- Wrote atomically to .hatch3r/handoffs/active/{id}.md
-**Not Done / Deferred / Unverified:**
-- {None — full scope completed | list of warnings}
-**Open Questions / Blockers:**
-- None
-**Confidence:** high | medium | low — {basis sentence}
-**impact_horizon:** short | medium | long
-**progress_toward_pillar:** governance.P7+<delta>
+**SUCCESS** — Handoff written for gh:owner/repo#42 at .hatch3r/handoffs/active/2026-07-06_T0910_a3f2c_issue-42.md.
+files 1 (+64/−0) · sa 0/0 · gates 6/6 · cost Δ0% tok / Δ0% min · tier 1
 ```
 
-Per the impact-horizon and pillar-progress emission convention, `impact_horizon` defaults to `medium` (a handoff persists across context windows and can be resumed days later); use `long` for handoffs that capture multi-week initiatives. `progress_toward_pillar` records the pillar-delta on the governance axis — handoff-preparer output advances P7 (Speed & Token Efficiency) because the externalized session-state lets a fresh context window resume without re-deriving prior work.
+Handoff body composition consumes the session's most recent recap via the rule's Handoff Mapping: Work Done ← recap outcome + files facet; Work Remaining ← `Not done:` line, absent ⇒ `None — full scope completed`; Blockers ← `Blockers:` line, absent ⇒ `None`. Open findings ← the Step 1 ledger fold, authoritative at composition time: compose the Work Remaining bullet from the fold's open rows in the recap grammar `Open findings: <finding_id> <sev> — <disposition>; …`, with the last recap's line as cross-check provenance — when it agrees with the fold, copy it verbatim as before; when it is absent or disagrees (stale recap, mid-session interrupt), the fold wins and the bullet notes `(fold-derived; last recap stale or absent)`. Zero open rows ⇒ no bullet.
 
 ## Outputs
 

package/dist/content/agents/hatch3r-implementer.md

@@ -20,7 +20,7 @@ Before any other work, consult `.hatch3r/learnings/INDEX.md` (if present) for pr
 
 This step precedes §0 Detect Ambiguity and supplements the more detailed Step 0b in the Implementation Protocol — the inline Step 0 is the always-on minimum; Step 0b is the structured deep-read against `applies-to` globs.
 
-Beyond this once-per-run gate, surface relevant learnings *mid-edit* per `rules/hatch3r-learning-system.md` → Mid-Edit Learning Surfacing: when a file or pattern you are editing matches a captured learning (path overlap, `applies-to` match, or `topic` semantic overlap), cite it on a `Surfaced Learnings:` line in the iteration summary before completing the edit.
+Beyond this once-per-run gate, surface relevant learnings *mid-edit* per `rules/hatch3r-learning-system.md` → Mid-Edit Learning Surfacing: when a file or pattern you are editing matches a captured learning (path overlap, `applies-to` match, or `topic` semantic overlap), cite it on the surfaced facet of the `Learnings:` exception line in the iteration summary before completing the edit.
 
 ## §0 Detect Ambiguity (P8 B1)
 
@@ -207,6 +207,28 @@ This gate is mandatory when triggered; passing Step 5b screenshot verification d
 
 The Step 5c verdict is a first-class field in the Return Structured Result block below alongside Browser verification.
 
+### 5d. Consumer Census (shared-contract changes)
+
+**Trigger:** the diff renames, removes, or re-signatures an exported symbol; changes a persisted collection/table/field name; adds, renames, or drops a client↔server wire-field key; changes an event name or payload key; moves or revalues a shared constant; or renames a CLI flag or config/env key (`rules/hatch3r-contract-census.md` → Shared-Contract Taxonomy). No trigger → record `Consumer census: N/A (no shared-contract change)` in the structured result and skip the rest of this step.
+
+**Census:** for each changed contract, run a repo-wide grep of the OLD identifier and the NEW identifier — never limited to the lane's `affectedFiles` (consumers live outside the lane's file set by definition):
+
+- String contracts: grep the quoted forms.
+- Wire fields: grep both client and server trees plus fixtures/mocks.
+- Constants: grep the name AND the literal value.
+
+Grep-pattern details live in `rules/hatch3r-contract-census.md` → Consumer Census.
+
+**Reconciled** means the consumer is updated to the new shape in this diff, OR reads through a guard added in this diff (façade-hold null-guard), OR carries a named justification. Valid justifications:
+
+- Consumer owned by another lane's seam (name the lane/issue).
+- Dead code with a linked deletion.
+- Dynamic/reflective access grep cannot resolve (name the mechanism, add a runtime guard).
+
+**Façade lane-exit self-check** — answer verbatim before returning: "Did you delete the field, or null it behind the façade?" A field deleted during a compatibility window fails this check: revert to the hold pattern (`rules/hatch3r-contract-census.md` → Façade Contract-Hold) before returning.
+
+**Gate:** `Status: SUCCESS` requires census ∈ {`clean`, `reconciled(N)`, `N/A`}; any `unreconciled` consumer without a named justification caps Status at `PARTIAL`, with the unreconciled consumers listed under Issues encountered / Notes.
+
 ### 6. Return Structured Result
 
 Report back to the parent orchestrator with:
@@ -230,6 +252,8 @@ The `Delegation proof ID` field below is a short identifier the orchestrator quo
 
 **Edge-Case Ledger status:** N rows — M covered, K out-of-scope (justified), 0 dropped — or `N/A (no ledger / single-entity change)`
 
+**Consumer census:** clean | reconciled(N) | N unreconciled — justification | N/A (no shared-contract change)
+
 **Browser verification:**
 - VERIFIED | SKIPPED (non-UI) | N/A (no browser MCP available)
 - (screenshots or observations if verified)
@@ -281,7 +305,7 @@ Rate every implementation decision, convention-lock choice, and reported result
 
 - **High:** Pattern is established in the codebase (located via `similar-implementation` or direct grep), tests pass, and types narrow as expected. You traced the chosen API call and verified its signature against the source.
 - **Medium:** Follows a documented convention but not all consumers were exercised — for example, an uncommon error path or an edge case not covered by the issue's acceptance criteria.
-- **Low:** Best professional judgment — no reference implementation existed, library behavior was inferred from docs, or a contract change was necessary without verifying every consumer in the blast-radius list. Flag to the reviewer in Notes.
+- **Low:** Best professional judgment — no reference implementation existed, or library behavior was inferred from docs. A shared-contract change with unverified consumers is NOT expressible as low confidence — it fails the Consumer Census gate (Step 5d): reconcile every consumer or record a named justification per `rules/hatch3r-contract-census.md`; `unreconciled` without justification caps Status at PARTIAL.
 
 Surface confidence in the implementation result: use `high` for decisions in the `Notes` section that carry forward into review, `medium`/`low` must be paired with the specific unknown so the reviewer can confirm or challenge.
 
@@ -312,7 +336,7 @@ After this agent completes Phase 2, the orchestrator runs the Phase 3 review loo
 
 After the review loop, Phase 4 specialists run bounded by the orchestrator-honored `max_phase4_parallel` width (default `8` — LLM-honored guidance, not a code-enforced cap). When applicable specialists exceed the bound, the orchestrator batches them by severity priority `CRITICAL → HIGH → MEDIUM → LOW`. Implementer Notes that surface high-risk surfaces (security, perf, a11y, content-quality CQ1-CQ9) help the orchestrator schedule the right specialists into the earliest batch. See `rules/hatch3r-agent-orchestration.md` Phase 4 — Final Quality for batching semantics.
 
-**Phase 4 specialist enumeration** — 9 CQ floor specialists + 4 SSOT specialists (`hatch3r-docs-writer`, `hatch3r-lint-fixer`, `hatch3r-architect`, `hatch3r-devops`) dispatched in parallel per CONSTITUTION §2B (CQ1-CQ9), KDD #22, and `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE` (always/evaluate/conditional modes). The pre-2.0.0 legacy meta-agents were retired in 2.0.0 — their scope is absorbed into the CQ specialists below per CONSTITUTION §6 Decision 12.
+**Phase 4 specialist enumeration** — 9 CQ floor specialists + 4 SSOT specialists (`hatch3r-docs-writer`, `hatch3r-lint-fixer`, `hatch3r-architect`, `hatch3r-devops`) dispatched in parallel per CONSTITUTION §2B (CQ1-CQ9), KDD #22, and `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE` (always/evaluate/conditional/mandatory-on-match modes; a triggered mandatory-on-match specialist — `hatch3r-ui` CQ1 / `hatch3r-ux` CQ2 — MUST spawn as its own dedicated instance at Tier 2/3). The pre-2.0.0 legacy meta-agents were retired in 2.0.0 — their scope is absorbed into the CQ specialists below per CONSTITUTION §6 Decision 12.
 
 - `hatch3r-ui` (CQ1) — dispatch when implementer touches `**/*.{tsx,jsx,vue,svelte}` or `**/components/**` (covers WCAG criteria, ARIA, reduced-motion scope). Surface a UI marker in implementer Notes when these globs are changed so the orchestrator schedules `hatch3r-ui` in the earliest Phase 4 batch.
 - `hatch3r-ux` (CQ2) — dispatch when route handlers, page components, form components, navigation, or empty/error/loading-state surfaces change.
@@ -383,6 +407,8 @@ When encountering errors during implementation, follow these protocols:
 - tests/unit/rateLimiter.test.ts -- 8 tests: burst handling, steady-state, window reset, Redis failure fallback
 - tests/integration/rateLimit.test.ts -- 3 tests: end-to-end 429 response, Retry-After header, rate reset
 
+**Consumer census:** clean
+
 **Browser verification:** SKIPPED (non-UI)
 
 **UI/UX verification gate (Step 5c):**

package/dist/content/agents/hatch3r-maintainability.md

@@ -38,6 +38,7 @@ See `agents/shared/quality-specialist-frame.md` → §0 Detect Ambiguity (P8 B1)
 - Count pattern reuse — grep the diff against existing named patterns (circuit breaker, retry-with-jitter, error handler, idempotency-key handler) and report reused / newly-authored ratio with raw numerator and denominator.
 - Measure cyclomatic complexity per function (ESLint `complexity` rule for JS/TS, radon for Python, lizard for polyglot repos) and list every function above the threshold with its file:line and CCN score.
 - Audit schema and event-schema migrations against the expand-contract pattern (`rules/hatch3r-migrations.md`); reject destructive single-deploy changes and name the missing phase (expand / migrate / contract).
+- Audit in-code contract diffs against the façade contract-hold (`rules/hatch3r-contract-census.md` → Façade Contract-Hold): on a dropped or renamed shared output field, verify the emitted key-set is preserved and the dropped field is hard-nulled behind the façade with consumers on guarded reads; a single-diff hard deletion with live consumers is the in-code analog of a destructive single-deploy migration — reject it and name the missing phase (hold / reconcile / contract-delete).
 - Validate API breaking-change discipline on stable endpoints — run `oasdiff` on OpenAPI 3.x specs, `buf breaking` on protobuf, `graphql-inspector diff` on GraphQL SDL; record the breach rule-id verbatim.
 - Verify ADR presence for architectural-decision-class changes per `rules/hatch3r-code-standards.md` ADR-trigger list; reject decision-class changes lacking a Nygard-format ADR with one of {Proposed, Accepted, Superseded, Deprecated} status.
 - Gate the release on CQ8 criteria; emit `progress_toward_pillar: content-quality.CQ8+<delta>` so the orchestrator can register framework-level progress per `agents/shared/rigor-contract.md` §Impact-Gated Registration.
@@ -60,6 +61,7 @@ Per `rules/hatch3r-right-sizing.md`, calibrate the depth of this vector to the p
 - `hatch3r-reviewer` runs the full CQ8 gate pre-merge — duplication + complexity + pattern-reuse + migration + API-breaking + ADR-presence — and blocks merge on any breach.
 - Schema-change audits — any migration file under `migrations/`, `db/migrations/`, `prisma/migrations/`, or framework-equivalent path triggers an expand-contract conformance scan.
 - API-change audits — any diff touching `openapi.yaml`, `openapi.json`, `*.proto`, or GraphQL SDL triggers the breaking-change CI gate.
+- In-code contract audits — any diff that removes or renames an exported symbol, a persisted collection/field name, a client↔server wire field, or an event name triggers a façade contract-hold conformance scan, regardless of path (extends the migration-glob and API-spec-glob triggers to contract mutations that touch neither).
 - Release-prep audit — the release skill calls this agent as part of the CQ8 floor verification before publishing.
 
 ## Key Files / Key Specs

package/dist/content/agents/hatch3r-researcher.md

@@ -139,7 +139,7 @@ If no breaking changes are detected, set `Breaking changes detected: NONE` in th
 | 1 | api_signature | src/auth/middleware.ts:42 | `verify(token)` | `verify(token, options)` | 3 callers (src/api/*.ts) | high |
 ```
 
-Confidence field uses `high` (direct code evidence), `medium` (evidence from ADR plus partial code trace), or `low` (inferred from spec without code confirmation). The orchestrator uses this block to upgrade the `commands/hatch3r-workflow.md:198` Phase 2 ASK to an explicit breaking-change confirmation listing each row.
+Confidence field uses `high` (direct code evidence), `medium` (evidence from ADR plus partial code trace), or `low` (inferred from spec without code confirmation). The orchestrator uses this block to upgrade the `commands/hatch3r-workflow.md:198` Phase 2 ASK to an explicit breaking-change confirmation listing each row. For `type_shape`, `event_schema`, and `public_interface` rows classed as a field drop or rename, append `remedy: façade contract-hold` to the row's Proposed-shape cell — the orchestrator forwards it into the implementer prompt so the lane preserves the key-set and hard-nulls the field instead of deleting (procedure: `rules/hatch3r-contract-census.md` → Façade Contract-Hold).
 
 ---