hatch3r 2.0.0 → 2.1.1

package/dist/content/rules/hatch3r-learning-system.mdc

@@ -97,9 +97,9 @@ Before answering project-specific questions, these agents MUST read `.hatch3r/le
 - `hatch3r-researcher`
 - `hatch3r-fixer`
 
-Bound agents cite consulted entry IDs in the iteration summary's `Open Questions / Blockers` or a dedicated `Consulted Learnings:` line. Citing zero entries when `applies-to` matched is a gate failure visible at audit time.
+Bound agents cite consulted entry IDs in the `consulted` facet of the Iteration Summary's `Learnings:` exception line (`Learnings: consulted <ids> · …` per `rules/hatch3r-iteration-summary.md` → Exception Lines). Citing zero entries when `applies-to` matched is a fired condition with no line — a gate failure visible at audit time.
 
-When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: consultation step is recorded as "no learnings available" in the iteration summary and the agent proceeds.
+When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: the `Learnings:` line stays silent in the Iteration Summary — silence asserts "no learnings available" per the recap contract — and the agent proceeds.
 
 ### Consultation Efficiency
 
@@ -108,7 +108,7 @@ The gate above binds at task start; these heuristics bound its token cost (D6-17
 1. **Scan the INDEX table first.** Read `.hatch3r/learnings/INDEX.md` and match each row's `Topic` + `Applies-To` against the current task; read the full body only for matched rows. Do not read every learning file body.
 2. **Limit surfaced learnings to 5 per consultation.** When more than 5 match, prioritize by `confidence` (high > medium > low) then `created` (recent first).
 3. **Consult once per task.** When an upstream step already consulted for this task (e.g. `hatch3r-board-pickup` Step 6, before delegation), the orchestrator passes the matched learnings to sub-agents as prompt enrichment instead of re-consulting per sub-agent.
-4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — record "no learnings available" and proceed (same recording as the empty-INDEX case above).
+4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — proceed under the same silent default as the empty-INDEX case above.
 
 ### Mid-Task Consult Content Security (ASI06)
 
@@ -122,9 +122,9 @@ The Injection Gate above is the deterministic JS read-path scan; a mid-task cons
 
 The Mandatory Consultation Gate fires once, before work starts (write-then-consult). State-of-art assistants additionally surface knowledge *during* the edit (ambient-teach). To close that gap without runtime support, bound agents surface relevant learnings inline as they touch files:
 
-- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline in the iteration summary BEFORE completing the edit (not only at Step 0).
+- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline — via the `surfaced` facet of the Iteration Summary's `Learnings:` exception line — BEFORE completing the edit (not only at Step 0).
 - **Relevant-learning criteria** (any one qualifies): (1) **path overlap** — the edited path matches the learning's `applies-to` glob; (2) **applies-to match** — an explicit module/path-prefix hit; (3) **semantic overlap** — the edit intent matches the learning `topic` (e.g. editing a retry path while a `topic: retry-backoff` learning exists).
-- **Surfacing format:** add a `Surfaced Learnings:` line to the iteration summary citing the entry IDs and a one-clause why-relevant; cite zero only when none matched.
+- **Surfacing format:** cite the entry IDs in the `surfaced` facet of the Iteration Summary's `Learnings:` exception line with a one-clause why-relevant; when none matched the facet is omitted — silence asserts zero.
 - **Bound agents:** `hatch3r-implementer`, `hatch3r-fixer` (the code-mutating agents whose edits benefit most). This complements — does not replace — the once-per-run Consultation Gate above.
 
 ## Auto-Consolidation
@@ -157,7 +157,7 @@ When a trigger fires:
 
 1. The capturing agent writes a new file `.hatch3r/learnings/<id>.md` with the structured frontmatter and a body paragraph (rule + Why + How to apply).
 2. The agent regenerates `.hatch3r/learnings/INDEX.md` from the directory contents.
-3. The iteration summary records the captured learning ID under `Learnings Captured`.
+3. The Iteration Summary records the captured learning ID in the `captured` facet of the `Learnings:` exception line.
 
 Project-local; learnings never escape the project boundary. The canonical framework repository's `agents/` and `rules/` do not consume project learnings.
 

package/dist/content/rules/hatch3r-reviewer-calibration.md

@@ -64,7 +64,7 @@ Append exactly one record per second pass to `.hatch3r/calibration-log.jsonl` (p
 {"timestamp":"<ISO-8601>","first_pass_verdict":"PASS","second_pass_verdict":"PASS|REQUEST CHANGES","divergent":false,"second_pass_model_class":"different|re-roll","consecutive_clean_count":5,"trigger":"cadence|high-risk"}
 ```
 
-`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`.
+`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the `Confidence:` exception line of the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`.
 
 ## Unavailability (visible skip, never silent)
 
@@ -79,6 +79,6 @@ Skip the second pass ONLY when no second model class is available AND the orches
 
 - `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration — the consuming agent body that invokes this contract (accessed 2026-05-28, trust tier: canonical).
 - The across-cycle calibration protocol §Runtime complement (F13.2-F1) — the across-cycle measurement loop this runtime bound complements (accessed 2026-05-28, trust tier: canonical).
-- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence` field (accessed 2026-05-28, trust tier: canonical).
+- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence:` exception line (accessed 2026-05-28, trust tier: canonical).
 - Tian, Z. et al. "Overconfidence in LLM-as-a-Judge: Diagnosis and Confidence-Driven Solution" (arxiv:2508.06225). `https://arxiv.org/abs/2508.06225` (accessed 2026-06-09, peer-reviewed-methodology). Evidence that an LLM judge's predicted confidence significantly overstates realized correctness (the Overconfidence Phenomenon), so a self-reported clean PASS is structurally over-trusted — motivating the out-of-band second pass.
 - Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024 (arxiv:2310.01798). `https://arxiv.org/abs/2310.01798` (accessed 2026-06-06, peer-reviewed-methodology). Evidence that same-model self-critique shares the generator's blind spot, motivating the different-model-class setup recommendation in Action and the lowered safety-class `N=1` second-pass cadence (D23-2).

package/dist/content/rules/hatch3r-reviewer-calibration.mdc

@@ -64,7 +64,7 @@ Append exactly one record per second pass to `.hatch3r/calibration-log.jsonl` (p
 {"timestamp":"<ISO-8601>","first_pass_verdict":"PASS","second_pass_verdict":"PASS|REQUEST CHANGES","divergent":false,"second_pass_model_class":"different|re-roll","consecutive_clean_count":5,"trigger":"cadence|high-risk"}
 ```
 
-`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`.
+`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the `Confidence:` exception line of the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`.
 
 ## Unavailability (visible skip, never silent)
 
@@ -79,6 +79,6 @@ Skip the second pass ONLY when no second model class is available AND the orches
 
 - `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration — the consuming agent body that invokes this contract (accessed 2026-05-28, trust tier: canonical).
 - The across-cycle calibration protocol §Runtime complement (F13.2-F1) — the across-cycle measurement loop this runtime bound complements (accessed 2026-05-28, trust tier: canonical).
-- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence` field (accessed 2026-05-28, trust tier: canonical).
+- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence:` exception line (accessed 2026-05-28, trust tier: canonical).
 - Tian, Z. et al. "Overconfidence in LLM-as-a-Judge: Diagnosis and Confidence-Driven Solution" (arxiv:2508.06225). `https://arxiv.org/abs/2508.06225` (accessed 2026-06-09, peer-reviewed-methodology). Evidence that an LLM judge's predicted confidence significantly overstates realized correctness (the Overconfidence Phenomenon), so a self-reported clean PASS is structurally over-trusted — motivating the out-of-band second pass.
 - Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024 (arxiv:2310.01798). `https://arxiv.org/abs/2310.01798` (accessed 2026-06-06, peer-reviewed-methodology). Evidence that same-model self-critique shares the generator's blind spot, motivating the different-model-class setup recommendation in Action and the lowered safety-class `N=1` second-pass cadence (D23-2).

package/dist/content/rules/hatch3r-tool-currency.md

@@ -61,7 +61,7 @@ Adding a new tool to `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` MUST satisf
 7. **Capability matrix** — `src/adapters/canonical.ts` renders the skill to all 3 adapter outputs (cursor, claude, copilot); the per-adapter render path is tested in `src/__tests__/adapters/{name}.test.ts`.
 8. **Alternative-tool comparison** — the PR body lists at least 2 named alternatives considered (with rejection rationale citing measurable trade-offs); avoids tool-duplication per `rules/hatch3r-anti-duplication.md`.
 9. **Probe binary registration** — the `probe` field on the registry entry names the binary used by `detectInstalled()`; the probe MUST be the exact executable name printed by the install command output (e.g. `rg` for ripgrep, `fd` for fd, `jq` for jq).
-10. **Iteration-summary entry** — the addition emits one row in `rules/hatch3r-iteration-summary.md` §Changes Made with the registry-entry diff link, per the iteration-summary template.
+10. **Iteration-summary entry** — the addition emits one line in the recap-contract Iteration Summary citing the registry-entry diff link, per `rules/hatch3r-iteration-summary.md`.
 
 ## Removing or Demoting a Tool
 

package/dist/content/rules/hatch3r-tool-currency.mdc

@@ -56,7 +56,7 @@ Adding a new tool to `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` MUST satisf
 7. **Capability matrix** — `src/adapters/canonical.ts` renders the skill to all 3 adapter outputs (cursor, claude, copilot); the per-adapter render path is tested in `src/__tests__/adapters/{name}.test.ts`.
 8. **Alternative-tool comparison** — the PR body lists at least 2 named alternatives considered (with rejection rationale citing measurable trade-offs); avoids tool-duplication per `rules/hatch3r-anti-duplication.md`.
 9. **Probe binary registration** — the `probe` field on the registry entry names the binary used by `detectInstalled()`; the probe MUST be the exact executable name printed by the install command output (e.g. `rg` for ripgrep, `fd` for fd, `jq` for jq).
-10. **Iteration-summary entry** — the addition emits one row in `rules/hatch3r-iteration-summary.md` §Changes Made with the registry-entry diff link, per the iteration-summary template.
+10. **Iteration-summary entry** — the addition emits one line in the recap-contract Iteration Summary citing the registry-entry diff link, per `rules/hatch3r-iteration-summary.md`.
 
 ## Removing or Demoting a Tool
 

package/dist/content/skills/hatch3r-adhoc-orchestrate/SKILL.md

@@ -85,7 +85,7 @@ Fan-out scales with task decomposition, not token budget (P8 B2 dominates P7): N
 
 ## Step 4: Emit the End-of-Turn Delegation Attestation Template
 
-Every turn that mutated files at Tier >= 2 emits the attestation block immediately BEFORE the Iteration Summary (beside it, not inside it — the iteration-summary contract stays verbatim), per `rules/hatch3r-agent-orchestration.md` -> End-of-Turn Delegation Attestation:
+Every turn that mutated files at Tier >= 2 emits the attestation block immediately BEFORE the Iteration Summary (beside it, not inside it — the recap contract stays verbatim), per `rules/hatch3r-agent-orchestration.md` -> End-of-Turn Delegation Attestation:
 
 ```
 [hatch3r-delegation-attestation]

package/dist/content/skills/hatch3r-handoff-prepare/SKILL.md

@@ -57,13 +57,13 @@ Populate the 8 required sections in the order defined by the README schema:
 - {decision with one-line rationale}
 
 ## Work Done
-- {bullet from the most recent Iteration Summary block's Done section}
+- {bullet from the most recent Iteration Summary recap's outcome + files facet}
 
 ## Work Remaining
-- {bullet from the Iteration Summary block's Not Done / Deferred / Unverified section}
+- {bullet per the recap's `Not done:` item; absent line ⇒ write "None — full scope completed"}
 
 ## Blockers
-- {bullet from the Iteration Summary block's Open Questions / Blockers section, or "None"}
+- {bullet per the recap's `Blockers:` item; absent line ⇒ write "None"}
 
 ## Next Steps
 1. {ordered, actionable}
@@ -83,7 +83,7 @@ Populate the 8 required sections in the order defined by the README schema:
 --- END USER-TIER CONTENT: handoff ---
 ```
 
-**Provenance constraint:** `Work Done`, `Work Remaining`, and `Blockers` are copied **verbatim** from the session's most recent Iteration Summary block (per `rules/hatch3r-iteration-summary.md`). Do not paraphrase — the contract is exact reuse so loaders can correlate handoff state with prior turn output.
+**Provenance constraint:** `Work Done`, `Work Remaining`, and `Blockers` derive from the session's most recent Iteration Summary per the Handoff Mapping in `rules/hatch3r-iteration-summary.md`: Work Done ← recap outcome + files facet; Work Remaining ← `Not done:` line, absent ⇒ `None — full scope completed`; Blockers ← `Blockers:` line, absent ⇒ `None`. Present lines are copied **verbatim** — do not paraphrase; the contract is exact reuse so loaders can correlate handoff state with prior turn output.
 
 **Hard cap:** body ≤ 51,200 bytes (50 KB). If exceeded:
 

package/dist/content/skills/hatch3r-report/SKILL.md

@@ -167,4 +167,4 @@ Each fired record: `{id, severity, turns:[n,...], evidence, suggestion}`. Consol
 - **Mask obvious secret patterns** (`sk-`, `ghp_`, `xoxb-`, `AIza`, `Bearer `) in any rendered tool_use input — substitute `{REDACTED-{prefix}}`. The transcript may contain ephemeral tokens from user pastes.
 - **Never write outside `.hatch3r/reports/`.** The `--save` target is fixed; do not honor flags or env vars that redirect output to other paths.
 - **Never abort on a malformed record.** Skip-and-count is the contract; aborting would hide the rest of the session from the operator (Silent Failure Contract — surface the skip count rather than swallowing it).
-- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this skill. The report content is not a substitute for the canonical Status / Outcome / Done block.
+- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this skill. The report content is not a substitute for the canonical recap (status + outcome + telemetry facets).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hatch3r",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Agentic coding setup framework audited each release across 24 governance domains. One command to hatch your agent stack -- agents, skills, rules, commands, and MCP for Claude Code, Cursor, and GitHub Copilot.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "inventory": "tsx scripts/inventory.ts",
     "inventory:check-docs": "tsx scripts/inventory.ts --check-docs",
     "validate:rule-parity": "tsx scripts/validate-rule-parity.ts && tsx scripts/validate-rule-pillar-currency.ts",
-    "validate:efficiency": "tsx scripts/validate-efficiency-invariants.ts && tsx scripts/validate-bridge-budget.ts && tsx scripts/validate-fanout-emission.ts && tsx scripts/validate-tag-order.ts && tsx scripts/validate-modes-parity.ts && tsx scripts/validate-governance-currency.ts && tsx scripts/validate-traceability-matrix.ts && tsx scripts/validate-decision-id-consistency.ts && tsx scripts/validate-repo-token-adoption.ts && tsx scripts/validate-verify-gate-literals.ts && tsx scripts/validate-customize-doc-examples.ts && tsx scripts/validate-archive-path-currency.ts && tsx scripts/validate-references-currency.ts && tsx scripts/validate-pricing-currency.ts && tsx scripts/validate-subagent-casing.ts && tsx scripts/validate-governance-total.ts",
+    "validate:efficiency": "tsx scripts/validate-efficiency-invariants.ts && tsx scripts/validate-bridge-budget.ts && tsx scripts/validate-fanout-emission.ts && tsx scripts/validate-tag-order.ts && tsx scripts/validate-modes-parity.ts && tsx scripts/validate-governance-currency.ts && tsx scripts/validate-traceability-matrix.ts && tsx scripts/validate-decision-id-consistency.ts && tsx scripts/validate-repo-token-adoption.ts && tsx scripts/validate-verify-gate-literals.ts && tsx scripts/validate-customize-doc-examples.ts && tsx scripts/validate-archive-path-currency.ts && tsx scripts/validate-references-currency.ts && tsx scripts/validate-pricing-currency.ts && tsx scripts/validate-subagent-casing.ts && tsx scripts/validate-governance-total.ts && tsx scripts/validate-lean-threshold-currency.ts",
     "validate:subagent-casing": "tsx scripts/validate-subagent-casing.ts",
     "validate:references-currency": "tsx scripts/validate-references-currency.ts",
     "validate:pricing-currency": "tsx scripts/validate-pricing-currency.ts",
@@ -64,7 +64,9 @@
     "ai-agents",
     "mcp",
     "skills",
-    "rules"
+    "rules",
+    "typescript",
+    "cli"
   ],
   "author": "hatch3r",
   "license": "MIT",