hatch3r 2.1.1 → 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.1";
+    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-fixer.md

@@ -100,6 +100,7 @@ Beyond this once-per-run gate, surface relevant learnings *mid-edit* per `rules/
 
 - 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
 
@@ -81,7 +82,7 @@ Then close the run with the recap-contract Iteration Summary per `rules/hatch3r-
 files 1 (+64/−0) · sa 0/0 · gates 6/6 · cost Δ0% tok / Δ0% min · tier 1
 ```
 
-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`.
+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

@@ -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).
 
 ---
 

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

@@ -84,17 +84,18 @@ created: YYYY-MM-DD
 <one-paragraph finding summary + resolution outcome>
 ```
 
-Cite any consulted cross-PR finding ID in the review summary's `Consulted Cross-PR Findings:` line (or `none supplied` when the orchestrator passed no block). This is a read-only consumption surface — the reviewer never writes to `.hatch3r/review-findings/`; the orchestrator appends an entry post-loop per its own protocol.
+Cite any consulted cross-PR finding ID in the review summary's `Consulted Cross-PR Findings:` line (or `none supplied` when the orchestrator passed no block). This is a read-only consumption surface — the reviewer never writes to `.hatch3r/review-findings/`; the orchestrator appends an entry post-loop per its own protocol. The same split governs the write-ahead findings ledger (`.hatch3r/findings/`, `rules/hatch3r-findings-ledger.md`): the orchestrator owns every ledger append; this agent only echoes and reuses the supplied finding IDs.
 
 ## Review Checklist
 
 Verify compliance with `rules/hatch3r-security-patterns.md`, `rules/hatch3r-code-standards.md`, and `rules/hatch3r-testing.md` across all review items:
 
 1. **Correctness:** Does the code do what the issue/spec requires?
+    - **Product-decision attestation (self-certification guard):** scan diff comments, commit messages, and PR text for agent-authored product choices affecting user data or user-visible behavior ("acceptable to drop", "users won't need", "safe to overwrite"); verify each traces to the issue body, an acceptance criterion, or a quoted user reply per `checks/code-quality.md` → Decision Provenance. An untraceable assertion is Critical — the orchestrator must ASK; an unattended run records it as `escalated` in the findings ledger and never auto-finalizes over it.
 2. **Privacy invariants:** No sensitive content in events/cloud data. Metadata allowlisted. Redaction defaults. Sensitive collections deny-all client access.
 3. **Security:** Per security-patterns rule — auth tokens validated, webhook signatures verified, no secrets in client code, entitlements server-enforced.
 4. **Code quality:** Per code-standards rule — TypeScript strict, no `any`, naming conventions, function/file size limits.
-5. **Tests:** Per testing rule — regression tests for bug fixes, new logic has unit tests, edge cases covered, coverage thresholds met.
+5. **Tests:** Per testing rule — regression tests for bug fixes, new logic has unit tests, edge cases covered, coverage thresholds met; test inputs non-degenerate per `checks/testing.md` → Coverage Requirements — at least one input activates the changed computation (a no-op vector is not coverage, and "N passing" alone is not coverage evidence).
 6. **Performance:** No hot-path regressions. Bundle size impact. No per-keystroke cloud writes.
 7. **Accessibility (quick-scan):** Reduced motion respected, WCAG 2.2 AA contrast, keyboard accessible, ARIA attributes present. Full UI/UX conformance — axe-core, WCAG 2.2 AA SC 2.5.8 Target Size / 2.4.11 Focus Not Obscured / 2.5.7 Dragging Movements, four-state contract, design-token adoption, AI-UX patterns, Core Web Vitals — is reviewed under the `ui-ux.review` surface (item 20).
 8. **Dead code:** No unused imports, obsolete comments, or abandoned logic.
@@ -102,7 +103,8 @@ Verify compliance with `rules/hatch3r-security-patterns.md`, `rules/hatch3r-code
     - **Prohibited-fix-pattern cross-check (review-loop integrity):** in a review-loop iteration (iteration ≥ 2), verify the diff introduces none of the five patterns `hatch3r-fixer` is barred from using as fix shortcuts when the prior iteration did not contain them: `eslint-disable`/`@ts-ignore` comments, `as any` casts, `.skip()`/`.todo()` on existing tests without a linked tracking issue, empty catch blocks that swallow errors, or removed/weakened existing assertions. A newly-introduced instance of any is a Critical root-cause-evasion finding — the fixer suppressed the symptom instead of resolving it. Cross-reference: `agents/hatch3r-fixer.md` → Fix Protocol §3 "Prohibited fix patterns". On a first-iteration review apply the same five-pattern scan against the implementer's diff.
 10. **Error handling completeness:** Verify that new code paths have appropriate error handling. Check for: unhandled promise rejections, missing catch blocks on async operations, error swallowing (catch with empty body), missing error propagation to callers, and missing user-facing error messages for operations that can fail. Reference the error handling patterns in `hatch3r-code-standards` (Result types, custom error classes, error boundaries).
     - **Edge-Case Ledger reconciliation (domain correctness):** when a Phase-1 Edge-Case Ledger (`agents/hatch3r-edge-case-analyst.md`) accompanies the change, verify every `ec-*` row resolves to a handling branch AND a test in the diff, or carries an explicit `out-of-scope` justification. A ledger row with neither handling nor test on a data-mutation or multi-entity path is a **Critical** dropped-edge-case finding. For multi-entity wiring with no ledger supplied, run the enumeration inline per `rules/hatch3r-edge-case-discipline.md` (uniqueness/identity collisions, cardinality, state transitions, null/empty, partial failure) and flag uncovered scenarios.
-11. **Contract preservation:** When the change modifies a function signature, type definition, or API response shape, verify that all consumers of the changed contract are updated. Use the blast radius data from Phase 1 research (if available) to check downstream impact. Flag missing consumer updates as Critical.
+11. **Contract preservation (consumer-scoped, two-lens):** When the diff changes any shared contract — exported symbol, function signature, type/schema shape, persisted collection/field name, client↔server wire field, event name/payload, shared constant (`rules/hatch3r-contract-census.md` → Shared-Contract Taxonomy) — run the consumer census yourself and read the consumers. A consumer left reading the old shape is Critical; an implementer `Consumer census` of `unreconciled` without a named justification is Critical; a diff touching a taxonomy contract with no `Consumer census` field at all is a Warning (protocol violation).
+    - **Consumer-scoped review procedure:** (a) extract every changed contract from the diff; (b) grep the repo for each contract's OLD and NEW identifier — Phase 1 blast-radius data, when present, seeds the list but never substitutes for the self-run grep; (c) open and read each consumer at its use site, both sides of every seam — serializer AND deserializer for a wire field, exporter AND importers for a store symbol, writer AND readers for a persisted name; (d) for a field drop or rename, verify the façade contract-hold: emitted key-set preserved, dropped field hard-nulled, consumers on guarded reads (`rules/hatch3r-contract-census.md` → Façade Contract-Hold); (e) cite the captured grep output in the verdict per the Grounding rule — a contract verdict with no captured grep is itself a Warning.
 ### Domain review surfaces (items 12-20): gate-vs-specialist split + grounding rule
 
 Items 12-20 are **gate criteria**, not the deep enforcement bodies. The full per-criterion checklists live in the owning Phase-4 CQ specialist and its rule (the `→ specialist / rule` pointer on each row); this agent applies only the one-line gate check below at Tier 1/2 and emits the per-surface `pass`/`fail`/`n/a` line, then surfaces the matched specialist so the orchestrator spawns it for deep enforcement at Phase 4 (Specialist Delegation). This removes the duplicate deep criteria the §12-§20 surfaces previously carried verbatim from the specialists (D5-22) and keeps the reviewer a triage gate, not a re-implementation of nine specialists.
@@ -139,6 +141,10 @@ Organize feedback as:
 - **Warning** -- Should fix (quality, performance, test gaps)
 - **Suggestion** -- Consider improving (readability, naming, patterns)
 
+Each severity section renders as a findings table with `ID` as its FIRST column (`| ID | # | File:Line | Issue | Suggestion |` — see Example).
+
+**Finding IDs.** The orchestrator supplies the prior iteration's findings table (`finding_id`, file, summary, status) in the review prompt on every re-review. Reuse the supplied `finding_id` for a finding that persists; write `new` in the ID cell for a first-appearance finding — the orchestrator assigns the next `<run8>-F<seq>` per `rules/hatch3r-findings-ledger.md` → Finding IDs. Identity heuristic when uncertain: same file + same defect class = same ID. Below the tables emit `Resolved since last iteration: <id, id, … | none>`.
+
 Include specific file paths and line references. Propose fixes where possible. Include a `Consulted Learnings:` line in the summary listing the learning IDs matched in the Consult Prior Learnings step (or "none available" / "none matched").
 
 ## Key Specs
@@ -256,7 +262,7 @@ Accurate severity classification directly affects loop termination. Over-classif
 
 After the loop exits clean, 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`. Severities propagated from this review (Critical / Warning / Suggestion → CRITICAL / HIGH / MEDIUM in the orchestration vocabulary) feed the orchestrator's batch scheduling — accurate classification here directly affects which specialists land in the first Phase 4 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 any file matches `**/*.{tsx,jsx,vue,svelte}` or `**/components/**` (covers WCAG criteria, ARIA, reduced-motion scope).
 - `hatch3r-ux` (CQ2) — dispatch when UX flow files (route handlers, page components, form components, navigation, empty/error/loading states) are touched.
@@ -287,7 +293,7 @@ Surface matched specialist names alongside the review verdict so the orchestrato
 
 ## Wall-Clock Advisory
 
-This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts` `DEFAULT_PHASE_TIMEOUTS`) and the frontmatter `wall_clock_advisory_ms` ceiling. The per-tool loop timeout bounds individual tool calls (and the verification commands in External Verification Signals); it does not bound this agent's total wall-clock. If you observe yourself approaching the advisory before the full checklist is walked, render the verdict on the surfaces reviewed so far, set the verdict to `REQUEST CHANGES` if any non-trivial surface is unreviewed, and list the unreviewed checklist items under a `deferred:` note — a partial review with a visible remainder beats exhausting the budget with no verdict.
+This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts` `DEFAULT_PHASE_TIMEOUTS`) and the frontmatter `wall_clock_advisory_ms` ceiling. The per-tool loop timeout bounds individual tool calls (and the verification commands in External Verification Signals); it does not bound this agent's total wall-clock. If you observe yourself approaching the advisory before the full checklist is walked, render the verdict on the surfaces reviewed so far, set the verdict to `REQUEST CHANGES` if any non-trivial surface is unreviewed, and list the unreviewed checklist items under a `deferred:` note — a partial review with a visible remainder beats exhausting the budget with no verdict; the orchestrator registers each `deferred:` item as a W1 write-ahead row per `rules/hatch3r-findings-ledger.md` → Write Points, so an unreviewed surface survives the session.
 
 <rules>
 
@@ -318,16 +324,18 @@ This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts`
 
 ### Critical
 
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | src/routes/billing.ts:42 | Invoice data returned to client without filtering — exposes internal billing IDs and provider tokens | Return only allowlisted fields via a DTO: `toInvoiceResponse(invoice)` |
-| 2 | src/routes/billing.ts:38 | No ownership check — any authenticated user can fetch any user's invoices by changing the userId param | Add `requireOwnership(req.user.id, params.userId)` guard |
+| ID | # | File:Line | Issue | Suggestion |
+|----|---|-----------|-------|------------|
+| new | 1 | src/routes/billing.ts:42 | Invoice data returned to client without filtering — exposes internal billing IDs and provider tokens | Return only allowlisted fields via a DTO: `toInvoiceResponse(invoice)` |
+| new | 2 | src/routes/billing.ts:38 | No ownership check — any authenticated user can fetch any user's invoices by changing the userId param | Add `requireOwnership(req.user.id, params.userId)` guard |
 
 ### Warning
 
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | src/routes/billing.ts:45 | No pagination — `findAll()` will return unbounded results for users with many invoices | Add cursor-based pagination with max page size of 50 |
+| ID | # | File:Line | Issue | Suggestion |
+|----|---|-----------|-------|------------|
+| new | 1 | src/routes/billing.ts:45 | No pagination — `findAll()` will return unbounded results for users with many invoices | Add cursor-based pagination with max page size of 50 |
+
+Resolved since last iteration: none
 
 ### Summary
 

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

@@ -15,7 +15,7 @@ parallel_tool_default: true
 browser_capability: opt-in
 wall_clock_advisory_ms: 600000
 phase_4_trigger:
-  mode: conditional
+  mode: mandatory-on-match
   conditions:
     - UI component files modified
     - Design-token or theme files modified

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

@@ -15,7 +15,7 @@ parallel_tool_default: true
 browser_capability: opt-in
 wall_clock_advisory_ms: 600000
 phase_4_trigger:
-  mode: conditional
+  mode: mandatory-on-match
   conditions:
     - Flow / route-transition / modal / error-state files modified
     - Microcopy or i18n strings modified

package/dist/content/agents/shared/cq-specialist-roster.md

@@ -7,14 +7,14 @@ cache_friendly: true
 ---
 # CQ Specialist Roster
 
-The single source of the 9-row CQ1-CQ9 specialist trigger table. The `hatch3r-implementer`, `hatch3r-reviewer`, and `hatch3r-fixer` agents each point here from their `## Specialist Delegation` section instead of re-inlining the table; `agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md` are the specialist bodies. The id-set and trigger-mode (always/evaluate/conditional) authority for fan-out remains `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE`; this file is the human-readable trigger-glob roster that mirrors it. `scripts/validate-specialist-roster.ts` (`checkCqTriggerTableParity`) treats this file as the reference copy and fails CI if any of the three agents re-inlines a divergent CQ row instead of pointing here.
+The single source of the 9-row CQ1-CQ9 specialist trigger table. The `hatch3r-implementer`, `hatch3r-reviewer`, and `hatch3r-fixer` agents each point here from their `## Specialist Delegation` section instead of re-inlining the table; `agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md` are the specialist bodies. The id-set and trigger-mode (always/evaluate/conditional/mandatory-on-match) authority for fan-out remains `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE`; this file is the human-readable trigger-glob roster that mirrors it. `hatch3r-ui` (CQ1) and `hatch3r-ux` (CQ2) carry mode `mandatory-on-match`: when their trigger matches, each MUST spawn as its own dedicated sub-agent instance at deep-context Tier 2/3 (skipping a triggered one is a gate failure); Tier 1 keeps the Phase Skip Criteria skip. `scripts/validate-specialist-roster.ts` (`checkCqTriggerTableParity`) treats this file as the reference copy and fails CI if any of the three agents re-inlines a divergent CQ row instead of pointing here.
 
 At a quality gate, the orchestrator MAY delegate to one or more of the 9 CQ specialists via the Task tool when the change touches a CQ-axis surface. Trigger conditions and the specialist roster (CONSTITUTION §6 Decision 13 wiring):
 
 | CQ Pillar | Specialist | Trigger |
 |-----------|------------|---------|
 | CQ1 UI | `hatch3r-ui` | Files matching `**/*.{tsx,jsx,vue,svelte}` or `**/components/**` |
-| CQ2 UX | `hatch3r-ux` | Route handlers, page components, form components, navigation, empty/error/loading states |
+| CQ2 UX | `hatch3r-ux` | Route handlers, page components, form components, navigation, empty/error/loading states, microcopy or i18n strings changed, locale-catalog files (`locales/` / `i18n/`) |
 | CQ3 Security | `hatch3r-security` | `src/auth/**`, `.github/workflows/*.yml`, OAuth/OIDC config, SBOM/provenance scripts, release-pipeline, dependency manifest/lockfile, DB rules/data flows/privacy invariants |
 | CQ4 Reliability | `hatch3r-reliability` | Service handlers, OTel instrumentation, SLO files, RFC 9457 error responses |
 | CQ5 Testability | `hatch3r-testability` | Parsers, payment flows, RPC contracts, AI feature handlers, test files |