@dzhechkov/keysarium 1.5.27 → 1.5.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.5.27",
+  "version": "1.5.29",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, reward learning, and Cloud.ru AI Factory mapping (--ai-factory flag)",
   "main": "src/cli.js",
   "bin": {

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -132,7 +132,7 @@ Step                         | S | M | L | XL | Model  | Agentic QE Skill
 0  Complexity Router         | ✓ | ✓ | ✓ | ✓  | haiku  | —                      |
 1  Requirements              | ✓ | ✓ | ✓ | ✓  | sonnet | —                      |
 2  Research                  | - | - | ✓ | ✓  | sonnet | —                      |
-3  ADR + Shift-Left          | - | ✓ | ✓ | ✓  | opus   | shift-left-testing     |
+3  ADR + Shift-Left          | - | ✓ Nygard/ITD | ✓ MADR+Confirmation | ✓ MADR+Confirmation | opus   | shift-left-testing     |
 3.5 QCSD Ideation Swarm     | - | ✓ | ✓ | ✓  | sonnet | qcsd-ideation-swarm    |
 4  DDD                       | - | - | ✓ | ✓  | opus   | —                      |
 5  Architecture              | - | ✓ | ✓ | ✓  | opus   | —                      |
@@ -205,6 +205,8 @@ Execute protocol
 After Step 8 (or Step 9 for L/XL) completes, verify:
 - All mandatory artifacts exist per tier
 - QE checks passed
+- Every generated ADR passes the Step-8 ADR fitness checklist
+- Every ADR Confirmation load-bearing property has a named automated test/fitness check
 - ADR decisions are traceable to code (L/XL)
 - QCSD quality risks are mitigated (M+)
 - Gap detection loop closed with zero remaining gaps
@@ -491,6 +493,12 @@ only the statusline:
 🎓 Learning: {recalled} patterns recalled for this feature, {stored} new stored this run
 ```
 
+**Record the panel at the START of every step, not only at Steps 0/8/9.** The panel shows the last step
+that reported; a pipeline that reports three times per run shows a stale step for most of its life. Emit
+`dz statusline --fa-record --slug <slug> --step "<Step N Name>" --recalled <n> --stored <n>` as the first
+action of each step. The recall/teach counts only change at Steps 0/8/9; the *step label* changes at every
+one of them.
+
 *Honesty note:* the panel is live only insofar as the pipeline records state — it reflects what the
 pipeline actually did with the loop (recalls that ran, stores that landed), not an aspirational count.
 
@@ -581,6 +589,7 @@ npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor
 <promise>[PROMISE_TAG]</promise>
 Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
 🎓 Learning: {recalled} patterns recalled for this feature, {stored} new stored this run
+🚦 Gates: challenge-panel ✓ · claim-check ✓ · discrimination not-run · amendments ✓ · fleet —
 
 [2-3 line summary]
 Artifacts: [list] ✅
@@ -590,3 +599,16 @@ Artifacts: [list] ✅
 • "[feedback]" — adjust
 ═══════════════════════════════════════════════════════
 ```
+
+### The 🚦 Gates line (mandatory, DERIVED — never asserted from memory)
+
+Every checkpoint banner carries a `🚦 Gates:` line listing each gate relevant to the run so far. Symbols:
+`✓` ran and passed · `✗` ran and failed · `not-run` pending · `—` N/A for this tier/slice (say why once).
+Each value is **derived from machine-checkable state** — an artifact's existence, a command's JSON verdict, a
+test result — never from what the orchestrator remembers doing. The line does not make a gate run; it makes
+NOT running one loud: a skipped gate shows as `not-run` by construction instead of being silently forgotten
+(cost-of-detection ladder: the banner is the one surface emitted at EVERY step boundary, so strapping the
+checklist to it is the cheapest way to harden orchestrator judgment). Gate sources: challenge-panel → its
+verdict exists; claim-check → its JSON counts (`high-findings` vs `clean`); discrimination → the
+`dz discrimination-check` aggregate; amendments → every `AM-N` row carries its `→ test` and it was checked;
+fleet → the 09 artifact (L/XL only, else `—`).

package/templates/.claude/skills/feature-adr/modules/00-complexity-router.md

@@ -57,7 +57,7 @@ Load `references/complexity-matrix.md` for the full matrix. Summary:
 | 0 Complexity Router | ✓ | ✓ | ✓ | ✓ |
 | 1 Requirements | ✓ light | ✓ | ✓ | ✓ |
 | 2 Research | - | - | ✓ | ✓ |
-| 3 ADR + Shift-Left | - | ✓ (1 ADR) | ✓ (N ADRs) | ✓ (N ADRs) |
+| 3 ADR + Shift-Left | - | ✓ (1 ADR, Nygard/ITD-light) | ✓ (N ADRs, MADR+Confirmation) | ✓ (N ADRs, MADR+Confirmation) |
 | 3.5 QCSD Ideation Swarm | - | ✓ | ✓ | ✓ |
 | 4 DDD | - | - | ✓ | ✓ |
 | 5 Architecture | - | ✓ light | ✓ | ✓ |
@@ -68,6 +68,13 @@ Load `references/complexity-matrix.md` for the full matrix. Summary:
 
 > Steps 3.5 (M+) and 9 (L/XL) are mandatory — skipping them is a BLOCK per the shard Anti-Patterns.
 
+ADR template weight is part of routing:
+- Summary: S/M -> Nygard/ITD-light; L/XL -> MADR+Confirmation.
+- S: normally skip Step 3; if an ADR is explicitly forced, use Nygard as the lightweight fallback.
+- M: use Nygard/ITD-lightweight ADRs with the invariant core plus drivers, options, rationale, consequences, and Confirmation.
+- L/XL: use full MADR structure with an NHS Wales Confirmation stanza for each significant decision.
+- All generated ADRs must keep the invariant core: Title, Status, Context, Decision, Consequences; one decision per ADR.
+
 ### 5. Calculate Time Budget
 
 | Tier | Total Budget | Distribution |

package/templates/.claude/skills/feature-adr/modules/03-adr.md

@@ -1,12 +1,13 @@
 # Step 3: Architecture Decision Records
 
-> Document each significant architectural decision with context, alternatives, and rationale.
+> Document each significant architectural decision with context, rejected options, consequences, and a named verification method before implementation begins.
 
 ## When
 
 M+ tiers. Depth varies:
-- **M:** 1 ADR for the main decision
-- **L/XL:** N ADRs for each significant decision
+- **S:** skipped by default; if explicitly forced, use Nygard as the lightweight fallback.
+- **M:** 1 Nygard/ITD-light ADR for the main decision, with the invariant core plus drivers, options, rationale, consequences, and Confirmation.
+- **L/XL:** N MADR+Confirmation ADRs, one per significant decision.
 
 Can run **in parallel** with Step 2 (Research) for L/XL tiers.
 
@@ -36,94 +37,164 @@ Scan requirements for decision points:
 | Trade-off | "Consistency vs. availability?" |
 
 For M-tier: pick the SINGLE most impactful decision.
-For L/XL: identify ALL decisions, prioritize by impact.
+For L/XL: identify ALL significant decisions, prioritize by architectural impact, and split them into separate ADRs.
 
-### 2. Draft ADR per Decision
+Reject explainer-masquerading-as-ADR: a document that describes a space but makes no concrete decision is not an ADR.
 
-Use template from `references/adr-template.md`:
+### 2. Choose Template Weight
+
+All ADRs must emit the invariant core:
+- Title
+- Status
+- Context
+- Decision
+- Consequences
+
+Template routing:
+- S forced ADR: Nygard fallback.
+- M: Nygard/ITD-light form with drivers, options, rationale, consequences, and Confirmation.
+- L/XL: MADR structure plus an NHS Wales Confirmation stanza.
+
+The chosen template may be short, but it must still satisfy the Step-8 ADR fitness checklist.
+
+### 3. Enforce File Naming
+
+Create ADRs in `features/<slug>/03_adr/` as:
+
+```text
+NNN-{decision-slug}.md
+```
+
+Slug rules:
+- lowercase kebab-case
+- present-tense imperative verb phrase
+- no dates
+- no ticket numbers
+- no camelCase, snake_case, or spaces
+
+Good examples: `001-choose-event-store.md`, `002-enforce-adr-fitness.md`, `003-format-timestamps.md`.
+
+### 4. Draft ADR per Decision
+
+Use `references/adr-template.md`.
+
+Minimum structure:
 
 ```markdown
-# ADR-{NNN}: {Title}
+# ADR-{NNN}: {decision-shaped title}
 
 ## Status
-Proposed | Accepted | Superseded by ADR-{M}
+proposed - Reversible until {condition}; revisit when {trigger}.
 
 ## Context
-What is the issue that we're seeing that is motivating this decision?
+{Neutral problem context written before the decision. State forces and constraints without selling the chosen option.}
 
 ## Decision Drivers
-- {driver 1}
-- {driver 2}
+1. {Driver D1} (weight: high|medium|low)
+2. {Driver D2} (weight: high|medium|low)
 
 ## Considered Options
-1. {Option A} — {1-line summary}
-2. {Option B} — {1-line summary}
-3. {Option C} — {1-line summary}
+### {Option A}
+Pros:
+- {real strength}
+Cons:
+- {real weakness}
+
+### {Option B}
+Pros:
+- {real strength}
+Cons:
+- {real weakness}
 
 ## Decision
-We chose **{Option X}** because...
+We will {concrete choice with exact names, versions, formats, paths, commands, APIs, or conventions}.
+
+## Rationale
+- D1: {why the chosen option satisfies the driver}
+- D2: {why rejected options lost despite their strengths}
 
 ## Consequences
 ### Positive
-- ...
-### Negative
-- ...
-### Risks
-- ...
-```
+- {benefit}
 
-### 3. Evaluate Alternatives
+### Negative / Accepted Downsides
+- {cost or risk} - Mitigation: {mitigation}
 
-For each ADR, evaluate alternatives using a decision matrix:
+### Follow-up ADRs
+- {ADR-NNN or "None required now"} - {why}
 
-| Criterion | Weight | Option A | Option B | Option C |
-|-----------|--------|----------|----------|----------|
-| Simplicity | 3 | ⭐⭐⭐ | ⭐⭐ | ⭐ |
-| Performance | 2 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
-| Maintainability | 3 | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
-| Team familiarity | 2 | ⭐⭐⭐ | ⭐ | ⭐⭐ |
+### After-action Review
+- Owner: {person/team}
+- Schedule: {about one month after acceptance, or a concrete date if known}
 
-If decision involves complex trade-offs, load `problem-solver-enhanced` for TRIZ analysis.
+## Confirmation
+- Method: {test, review, demo, audit, or fitness function}
+- Monitoring: {ongoing automated check/audit/training}
+- Success metric: {objective pass/fail or numeric metric}
+- Owner: {responsible person/team}
+- Load-bearing property: {the safety property Step 8 must assert has a test}
+- Required automated check: {test file/name, command, or ArchUnit/ArchUnitTS suggestion}
+```
+
+For L/XL ADRs, add a decision matrix or comparison table after Considered Options. Keep per-option pros/cons symmetric.
 
-### 4. Validate Against Requirements
+### 5. Validate Against Requirements
 
 Each ADR must trace back to specific requirements:
 - Which FR-{N} does this decision support?
-- Does the decision satisfy all relevant NFRs?
-- Does the decision respect constraints?
+- Which NFRs does it satisfy?
+- Which constraints does it respect?
+- Which safety property must be tested because the ADR's Confirmation names it?
+
+### 6. Lifecycle Discipline
+
+- Status vocabulary is controlled: `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`.
+- Status must include a reversibility or revisit clause.
+- Supersession mints a NEW ADR and sets the old ADR to `superseded by ADR-{NNN}`; do not edit accepted/rejected ADR content in place.
+- If a living-document amendment is unavoidable, add a dated "arrived after the decision" note instead of silently rewriting the original reasoning.
 
 ## Anti-Patterns
 
 | Anti-Pattern | Detection | Fix |
 |-------------|-----------|-----|
-| Only one alternative | Less than 2 options considered | Require ≥2 alternatives |
+| Explainer masquerading as ADR | Describes a domain but has no concrete Decision | BLOCK; write a decision-shaped ADR |
+| Only one alternative | Less than 2 options considered | Require chosen plus rejected options |
+| Strawman rejected option | Loser has only cons | Add real strengths and fair trade-offs |
 | No consequences | Missing positive/negative analysis | BLOCK until filled |
-| Decision without context | Why is unclear | Add context section |
-| Premature optimization | Choosing complex option for hypothetical scale | Prefer simpler option |
+| Benefits-only consequences | No accepted downside | Add negative outcomes and mitigations |
+| Decision without context | Why is unclear | Add neutral Context before Decision |
+| Vague decision | "use a modern database" | Name exact product/version/format/path/API |
+| Placeholder text | Template hints or TODOs remain | Remove or fill before checkpoint |
+| Supersession in-place | Existing ADR rewritten | Mint a new ADR and link it |
 
 ## Output
 
 Create `features/<slug>/03_adr/` directory with:
-- `001-{decision-slug}.md` for each ADR
-- Each ADR follows the template
+- `NNN-{decision-slug}.md` for each ADR
+- Each ADR follows the template and satisfies the fitness checklist
 
-Set `{ADR_DECISIONS}` variable with list of decisions.
+Set `{ADR_DECISIONS}` variable with list of decisions and their Confirmation load-bearing properties.
 
 ## Checkpoint Format
 
-```
-═══════════════════════════════════════════════════════
-⏸️ STEP 3/8: ADR Complete
+```text
+=======================================================
+STEP 3/8: ADR Complete
 Tier: {COMPLEXITY_TIER}
 
 {N} architectural decisions documented:
-1. ADR-001: {title} → chose {option}
-2. ADR-002: {title} → chose {option}
-
-• "ок" — proceed
-• "пересмотри ADR-{N}" — reconsider decision
-• "добавь ADR для [topic]" — add new decision
-═══════════════════════════════════════════════════════
+1. ADR-001: {title} -> chose {option}; Confirmation: {method}, {metric}, owner {owner}
+2. ADR-002: {title} -> chose {option}; Confirmation: {method}, {metric}, owner {owner}
+
+Fitness readiness:
+- Invariant core present: PASS|FAIL
+- Concrete/testable decisions: PASS|FAIL
+- Confirmation properties named for Step 8: PASS|FAIL
+
+- "ok" - proceed
+- "revise ADR-{N}" - reconsider decision
+- "add ADR for [topic]" - add new decision
+=======================================================
 ```
 
 ## Shift-Left Validation (after ADR creation)
@@ -136,8 +207,14 @@ After all ADRs are drafted, apply **shift-left-testing** protocol (Level 4: Risk
 
 For each ADR decision, run risk analysis:
 
-```
+```text
 ADR-{NNN}: {Title}
+  Confirmation:
+    Method: {verification method}
+    Monitoring: {ongoing monitoring}
+    Success metric: {metric}
+    Owner: {owner}
+    Load-bearing property: {property}
   Testability Questions:
     1. What happens when {chosen option} fails under load?
     2. How do we handle {alternative failure modes}?
@@ -147,6 +224,8 @@ ADR-{NNN}: {Title}
     Given {precondition from ADR context}
     When {action that exercises the decision}
     Then {expected outcome per ADR consequences}
+  Required Automated Check:
+    {test file/name/command or ArchUnit/ArchUnitTS fitness function}
   Risk Level: LOW | MEDIUM | HIGH
 ```
 
@@ -155,24 +234,35 @@ ADR-{NNN}: {Title}
 | Check | Threshold |
 |-------|-----------|
 | All ADRs have testability questions answered | 100% |
-| BDD scenarios generated for non-trivial decisions | ≥1 per ADR |
+| Each ADR has a Confirmation stanza | 100% |
+| Each Confirmation names method, monitoring, success metric, owner | 100% |
+| Each load-bearing property has a proposed automated check | 100% |
+| BDD scenarios generated for non-trivial decisions | >=1 per ADR |
 | No HIGH risk without mitigation documented | 0 unmitigated |
 
-If any ADR has HIGH risk without mitigation → flag at checkpoint for user decision.
+If any ADR has HIGH risk without mitigation, or a Confirmation property with no proposed automated check, flag at checkpoint for user decision.
 
-### Integration with Step 3.5
+### Integration with Step 3.5 and Step 8
 
 The shift-left validation output feeds directly into Step 3.5 (QCSD Ideation Swarm):
 - BDD scenarios become input for the requirements-validator agent
 - Risk analysis feeds the risk-assessor agent
 - Testability questions inform the quality-criteria-recommender
 
+Step 8 must read the Confirmation stanza and assert that the named load-bearing property has a real automated test or fitness function in the shipped code. For architecture dependency/layering/interface rules, suggest ArchUnit or ArchUnitTS.
+
 ## Quality Gates
 
-- [ ] Every ADR has ≥2 alternatives considered
-- [ ] Every ADR has consequences (positive + negative)
-- [ ] Every ADR traces to requirements
-- [ ] Decision matrix used for non-trivial choices
-- [ ] No premature optimization detected
-- [ ] Shift-left testability check passed for all ADRs
-- [ ] BDD scenarios generated for non-trivial ADRs
+- [ ] Every ADR has the invariant core: Title, Status, Context, Decision, Consequences
+- [ ] Every ADR records exactly one decision
+- [ ] Filename slug is kebab-case, imperative, dateless, and ticketless
+- [ ] Status uses controlled vocabulary plus a reversibility clause
+- [ ] Context is neutral and appears before Decision
+- [ ] Decision drivers are ranked or weighted
+- [ ] Considered options include rejected options with symmetric pros/cons
+- [ ] Rationale maps each point to a driver and explains why losers were rejected
+- [ ] Decision is concrete/testable with exact names/versions/formats/paths/APIs
+- [ ] Consequences include positive and negative outcomes/accepted downsides
+- [ ] Consequences link follow-up ADRs and schedule an after-action review
+- [ ] Confirmation names method, monitoring, success metric, owner, load-bearing property, and required automated check
+- [ ] No placeholder text or generation scaffolding remains

package/templates/.claude/skills/feature-adr/modules/03.5-ideation-swarm.md

@@ -119,7 +119,8 @@ After all agents complete, apply decision logic:
 | Critical Risks | > 2 | 1-2 | 0 |
 
 - **NO-GO**: BLOCK. Requirements/ADR need rework. Return to Step 1 or Step 3.
-- **CONDITIONAL**: Proceed with warnings. Pass findings to Steps 6-8 as advisory context.
+- **CONDITIONAL**: Proceed with warnings. Each condition becomes an **amendment row** in a `## Amendments`
+  section (see below) — not loose advisory prose.
 - **GO**: Full confidence. Proceed to Step 6.
 
 ### 5. Synthesis Report
@@ -132,6 +133,26 @@ Generate consolidated `03.5_ideation_report.md` with:
 5. Test ideas (categorized: unit / integration / E2E)
 6. Conditional agent findings (if any)
 7. Recommendations prioritized by risk × impact
+8. `## Amendments` — on a CONDITIONAL verdict, every condition as a fixed-shape row (see below)
+
+### Amendment Confirmation discipline (every amendment is a mini-ADR)
+
+Amendments are where the sharpest design corrections land — and, historically, the least-tested part of a
+run: they arrive as prose AFTER the ADR's Confirmation discipline already ran, so a coder can implement one
+with no test proving it works. Therefore every amendment carries a one-line **Confirmation**, in a fixed,
+machine-checkable shape:
+
+```
+AM-N (source): <change>. Confirmation: <property> → test `test_name` (fails if reverted).
+```
+
+- `source` names where it came from (qcsd | challenge-panel | user-steer).
+- The named test must FAIL if the amendment were reverted/broken (non-vacuous — Step 8 verifies via
+  `dz discrimination-check`).
+- For a **safeguard** amendment (a warning/guard/fallback): the test must prove the safeguard actually
+  **TRIGGERS on a real input** — not merely that its code path exists. A structurally-dead safeguard passes
+  an existence test and never fires in production.
+- A cheap lint holds the shape: every `AM-N` line must contain a `→ test ` token naming a test that exists.
 
 ## Output
 

package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md

@@ -149,6 +149,11 @@ Create `features/<slug>/06_implementation_plan.md` with:
 - Parallel groups
 - Checkpoint schedule
 - Risk assessment (L/XL)
+- `## Amendments` — every correction folded into this plan (a Step-3.5 CONDITIONAL condition, a
+  challenge-panel confirmed finding, a user checkpoint steer) as a fixed-shape row:
+  `AM-N (source): <change>. Confirmation: <property> → test `test_name` (fails if reverted).`
+  A safeguard amendment's named test must prove it TRIGGERS on a real input, not merely that its code
+  path exists. Step 8 verifies every named test exists and is non-vacuous (`dz discrimination-check`).
 
 Set `{IMPL_PLAN}` variable.
 
@@ -169,6 +174,21 @@ Estimated {K} files to create/modify
 ═══════════════════════════════════════════════════════
 ```
 
+## Challenge panel (adversarial plan-gate — before coding)
+
+Before leaving the plan checkpoint for code (especially L/XL), offer the **`challenge-panel`** skill — a
+FRESH adversary (never the plan author) tries to BREAK the plan across the fixed C1-C8 owner questions,
+every P0/P1 is cross-validated, and the verdict is ADVISORY (never an auto-block):
+
+```bash
+dz challenge --plan features/<slug>/06_implementation_plan.md --author <planner-model>
+```
+
+Dispatch the panel on the CROSS-FAMILY model (`--author` prints which): plan by Claude → Codex adversary
+(honest `codex exec`, never a stub); plan by Codex → fresh Claude. Drop any P0/P1 the cross-validator does
+not confirm. A finding the owner accepts can be recorded in `architecture/degradations.md` so C1 stops
+re-flagging it. In the ultracode workflow this врезка runs automatically and returns `challengeVerdict`.
+
 ## Quality Gates
 
 - [ ] Every task has clear done criteria

package/templates/.claude/skills/feature-adr/modules/07-code.md

@@ -31,6 +31,24 @@ Before writing any code:
 - [ ] Identify import patterns and module structure
 - [ ] Identify error handling patterns
 - [ ] Identify test patterns
+- [ ] Plan carries `## Amendments`? → implement every AM-N row AND its named Confirmation test (a
+      safeguard amendment needs a test proving it FIRES on a real input)
+- [ ] Does the diff add I/O (DB/network/file) to a previously-pure path — especially
+      startup/lifespan/health? → name the NEGATIVE resource-down test, or justify N/A
+
+### The I/O-on-pure-path rule (and the fixture-swap smell)
+
+If a change introduces I/O into a path that was previously I/O-free — above all a startup, lifespan, or
+health path — the happy-path test is NOT enough. Also write a **negative resource-down test**: a
+broken/unbound resource handle (dead DB, missing table, exhausted pool) → the path degrades per its
+declared contract — **fail-open** for an advisory feature, **explicit fail-fast** for a load-bearing one.
+Without it, an outage of the resource takes down the whole path (including health checks) for the sake of
+an advisory feature — and healthy test fixtures will hide it.
+
+**Fixture-swap smell:** if making the new code pass required replacing a "broken" test fixture with a
+healthy one — stop. The old fixture was probably a negative control proving the path was I/O-free. Keep
+BOTH tests: the healthy one (new behavior) and the broken one (degradation contract). Never silently
+delete the case that proved the old property.
 
 ### 2. Execute Tasks per Plan
 

package/templates/.claude/skills/feature-adr/modules/08-qe.md

@@ -129,6 +129,59 @@ Choose review mode based on context:
    - 🟡 **WARNING** — should fix, but not blocking (Ramsay mode: "This is RAW")
    - 🔵 **SUGGESTION** — nice to have improvement
 
+### 3.1 ADR Fitness Checklist Gate (M+)
+
+Before final grading, read every generated ADR in `features/<slug>/03_adr/NNN-*.md`.
+
+Fail the ADR gate for any miss:
+
+| Check | Required Evidence |
+|-------|-------------------|
+| Decision-shaped title | Title names one concrete decision, not a vague topic |
+| One decision per ADR | No bundled independent decisions |
+| Filename discipline | `03_adr/NNN-{decision-slug}.md`; slug is lowercase kebab-case, imperative, dateless, ticketless |
+| Status vocabulary | `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded` |
+| Reversibility clause | Status states when/how to revisit or why it is irreversible |
+| Neutral Context before Decision | Context states problem/forces without advocating the chosen solution |
+| Drivers ranked or weighted | Decision Drivers are explicit and prioritized |
+| Considered Options | Chosen and rejected options are present |
+| Symmetric pros/cons | Each option has real strengths and weaknesses; no strawman loser |
+| Rationale maps to drivers | Every rationale point names the driver it satisfies and why rejected options lost |
+| Concrete/testable Decision | Exact names, versions, formats, paths, commands, APIs, or conventions |
+| Negative consequences | Consequences include accepted downsides/risks, not only benefits |
+| Follow-up discipline | Consequences link follow-up ADRs or state none; after-action review is scheduled |
+| Confirmation stanza | Names verification method, monitoring, success metric, and owner |
+| Confirmation-to-test link | The named load-bearing property has a real automated test/fitness check by file/name |
+| No placeholders | No TODO, template hint text, raw prompt/generation scaffold, or empty tail sections |
+
+Reject explainer-masquerading-as-ADR: if the document describes a problem space or technology landscape but has no concrete `Decision`, record a BLOCKER.
+
+The Confirmation-to-test link is load-bearing. If absent, grade no better than C and record a blocker gap; for architecture dependency/layering/interface rules, recommend an ArchUnit or ArchUnitTS fitness function.
+
+### 3b. Amendment Gate (P2 — amendments inherit the Confirmation discipline)
+
+Read the `## Amendments` sections of `03.5_ideation_report.md` and `06_implementation_plan.md` (skip
+silently if absent). For EVERY `AM-N` row verify:
+1. the row contains a `→ test ` token naming a real test (the fixed shape);
+2. the named test **exists** in the suite;
+3. it is **non-vacuous** — include the amendment test files in the SAME
+   `dz discrimination-check --test <f1,f2,...> --base HEAD --json` run as the ADR property test. An
+   amendment test that stays green at pre-feature base proves nothing about its amendment;
+4. a **safeguard** amendment's test proves the safeguard FIRES on a real input (a structurally-dead
+   safeguard passes an existence test and never fires in production).
+
+A missing, unnamed, or vacuous amendment test is a HIGH gap. This closes the distance between "we caught
+the design flaw" (challenge-panel/QCSD) and "we proved the fix works".
+
+### 3c. I/O-on-pure-path + fixture-swap hunt (P5)
+
+In the TEST diff, hunt for replacements of broken/unbound fixtures with healthy ones — the old fixture was
+probably a **negative control** proving a path was I/O-free; each such swap requires a compensating
+negative resource-down test. In the CODE diff, hunt for new I/O (DB/network/file) on previously-pure
+paths — especially startup/lifespan/health: require a negative resource-down test (broken resource → the
+path degrades per its declared contract: fail-open for advisory, explicit fail-fast for load-bearing).
+Missing → HIGH gap.
+
 ### 4. Multi-Agent Review Panel (L/XL)
 
 For L/XL features, spawn 3 parallel review agents using brutal-honesty modes:
@@ -150,6 +203,7 @@ After review findings are compiled, run a gap check:
 ITERATION {N}:
   1. Check: Every FR-{N} from requirements → has passing test or verification
   2. Check: Every ADR decision → reflected in code
+  2a. Check: Every ADR Confirmation load-bearing property → has a named automated test/fitness check
   3. Check: Every critical risk from QCSD → has mitigation in code
   4. Check: Every 🔴 BLOCKER → has fix plan
 
@@ -199,6 +253,11 @@ Compile all findings into a structured report:
 ## Review Findings
 {list of findings with severity}
 
+## ADR Fitness Checklist
+| ADR | Fitness | Confirmation Test Evidence | Gaps |
+|-----|---------|----------------------------|------|
+| ADR-001 | PASS/FAIL | {test file/name or missing} | {none or blocker} |
+
 ## Acceptance Criteria
 {FR-N status table}
 

package/templates/.claude/skills/feature-adr/references/adr-template.md

@@ -1,102 +1,158 @@
 # ADR Template
 
-Use this template for every Architecture Decision Record.
+Use this template for every Architecture Decision Record generated by feature-adr.
+
+Template weight:
+- S forced ADR: Nygard fallback.
+- M: Nygard/ITD-light with drivers, options, rationale, consequences, and Confirmation.
+- L/XL: MADR structure plus NHS Wales Confirmation.
+
+Every ADR must keep the invariant core: Title, Status, Context, Decision, Consequences. Record exactly one decision per ADR.
 
 ---
 
 ```markdown
-# ADR-{NNN}: {Short Title of Decision}
+# ADR-{NNN}: {Decision-shaped title}
 
 ## Status
 
-{Proposed | Accepted | Deprecated | Superseded by ADR-{M}}
+proposed - Reversible until {condition}; revisit when {trigger}.
 
-## Date
-
-{YYYY-MM-DD}
+Allowed status values: `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`.
 
 ## Context
 
-{What is the issue that we're seeing that is motivating this decision or change?
-Describe the forces at play — technical, business, political, social.
-Describe the problem space, not the solution.}
+{Neutral problem statement written before the decision. Describe the forces, constraints, requirements, team context, and trade-offs without advocating the chosen option.}
 
 ## Decision Drivers
 
-- {driver 1: e.g., "Team has no experience with technology X"}
-- {driver 2: e.g., "Feature requires sub-100ms latency"}
-- {driver 3: e.g., "Must integrate with existing auth system"}
+1. {Driver D1} (weight: high|medium|low; traces to FR/NFR/constraint)
+2. {Driver D2} (weight: high|medium|low; traces to FR/NFR/constraint)
+3. {Driver D3} (weight: high|medium|low; traces to FR/NFR/constraint)
 
 ## Considered Options
 
-### Option 1: {Name}
+### {Option A}
+
+{Short description.}
 
-{1-2 paragraph description of this option}
+Pros:
+- {Real strength}
+- {Real strength}
 
-- ✅ {Pro 1}
-- ✅ {Pro 2}
-- ❌ {Con 1}
-- ❌ {Con 2}
+Cons:
+- {Real weakness}
+- {Real weakness}
 
-### Option 2: {Name}
+### {Option B}
 
-{1-2 paragraph description}
+{Short description.}
 
-- ✅ {Pro 1}
-- ❌ {Con 1}
+Pros:
+- {Real strength}
+- {Real strength}
 
-### Option 3: {Name} (optional)
+Cons:
+- {Real weakness}
+- {Real weakness}
 
-{1-2 paragraph description}
+### {Option C, optional}
 
-- ✅ {Pro 1}
-- ❌ {Con 1}
+{Short description.}
+
+Pros:
+- {Real strength}
+
+Cons:
+- {Real weakness}
 
 ## Decision Matrix
 
-| Criterion | Weight | Option 1 | Option 2 | Option 3 |
-|-----------|--------|----------|----------|----------|
-| {Criterion 1} | {1-5} | {1-5} | {1-5} | {1-5} |
-| {Criterion 2} | {1-5} | {1-5} | {1-5} | {1-5} |
-| {Criterion 3} | {1-5} | {1-5} | {1-5} | {1-5} |
-| **Weighted Total** | | **{sum}** | **{sum}** | **{sum}** |
+Use for non-trivial M decisions and all L/XL decisions.
+
+| Driver | Weight | Option A | Option B | Option C |
+|--------|--------|----------|----------|----------|
+| D1 | high | {score/rationale} | {score/rationale} | {score/rationale} |
+| D2 | medium | {score/rationale} | {score/rationale} | {score/rationale} |
+| D3 | low | {score/rationale} | {score/rationale} | {score/rationale} |
 
 ## Decision
 
-We chose **{Option N}** because {1-2 sentence rationale linking back to decision drivers}.
+We will {concrete, testable choice with exact names, versions, formats, paths, commands, APIs, or conventions}.
+
+## Rationale
+
+- D1: {Why the chosen option best satisfies this driver.}
+- D2: {Why the chosen option best satisfies this driver.}
+- Rejected {Option B}: {Why it lost despite its real strengths.}
 
 ## Consequences
 
 ### Positive
-- {Positive consequence 1}
-- {Positive consequence 2}
+- {Positive consequence}
+- {Positive consequence}
 
-### Negative
-- {Negative consequence 1 — with mitigation strategy}
+### Negative / Accepted Downsides
+- {Negative consequence or accepted downside} - Mitigation: {mitigation}
+- {Risk with likelihood/impact if relevant} - Mitigation: {mitigation}
 
-### Risks
-- {Risk 1} — Mitigation: {how to mitigate}
-- {Risk 2} — Mitigation: {how to mitigate}
+### Follow-up ADRs
+- {ADR-NNN: title, or "None required now"} - {why}
 
-## Links
+### After-action Review
+- Owner: {person/team}
+- Schedule: {about one month after acceptance, or a concrete date if known}
+- Review question: Did the expected benefits and accepted downsides match reality?
 
-- Requirement: FR-{N}
-- Related: ADR-{M} (if any)
-```
+## Confirmation
 
----
+- Method: {How the decision is verified: automated test, fitness function, review, demo, audit}
+- Monitoring: {How compliance is monitored over time}
+- Success metric: {Objective pass/fail or numeric metric}
+- Owner: {responsible person/team}
+- Load-bearing property: {The safety property Step 8 must assert has a test}
+- Required automated check: {test file/name, command, or ArchUnit/ArchUnitTS suggestion}
 
-## ADR Numbering
+## Links
 
-- Start from 001 for each feature
-- Use kebab-case slugs: `001-choose-database-engine.md`
-- Keep sequential within a feature, no gaps
+- Requirement: FR-{N} / NFR-{N}
+- Related ADRs: {ADR links, typed if relevant: Refines, Supersedes, Superseded by, Follow-up}
+- Evidence: {research, code path, benchmark, external source}
+```
 
-## ADR Quality Checklist
+---
 
-- [ ] At least 2 options considered
-- [ ] Every option has both pros and cons
-- [ ] Decision matrix used for non-trivial decisions
-- [ ] Consequences include both positive AND negative
-- [ ] Risks have mitigation strategies
-- [ ] Links to requirements present
+## ADR Numbering and Slugs
+
+- Start from 001 for each feature.
+- Keep numbers sequential within a feature, no gaps.
+- Use `NNN-{decision-slug}.md`.
+- The slug must be lowercase kebab-case, present-tense imperative, dateless, and ticketless.
+- Good: `001-choose-database-engine.md`, `002-enforce-adr-fitness.md`, `003-format-timestamps.md`.
+- Bad: `001-database.md`, `001-ADR-1234-database.md`, `001-2026-07-08-database.md`.
+
+## ADR Fitness Checklist
+
+- [ ] Title is decision-shaped and records one decision only
+- [ ] Status is one of `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`
+- [ ] Status includes a reversibility or revisit clause
+- [ ] Context is neutral and appears before Decision
+- [ ] Decision drivers are ranked/weighted
+- [ ] Considered options include chosen and rejected options
+- [ ] Every option has symmetric pros and cons
+- [ ] Rationale maps each point to a stated driver
+- [ ] Rationale explains why rejected options lost
+- [ ] Decision is concrete/testable with exact names, versions, formats, paths, commands, APIs, or conventions
+- [ ] Consequences include positive and negative outcomes/accepted downsides
+- [ ] Consequences link follow-up ADRs or explicitly say none
+- [ ] Consequences schedule an after-action review
+- [ ] Confirmation names verification method, monitoring, success metric, and owner
+- [ ] Confirmation names the load-bearing property and required automated check
+- [ ] No placeholder text, raw prompt text, or template hints remain
+- [ ] The document is not an explainer masquerading as an ADR
+
+## Lifecycle
+
+- Supersession mints a new ADR and links it; do not edit accepted/rejected ADR content in place.
+- If an amendment is unavoidable, add a dated note that the information arrived after the decision.
+- Rejected ADRs must record why the option was rejected to avoid re-litigating it.

package/templates/.claude/skills/feature-adr/references/complexity-matrix.md

@@ -64,6 +64,8 @@
 
 ## Step Activation by Tier
 
+ADR template weight: S/M -> Nygard/ITD-light; L/XL -> MADR+Confirmation.
+
 ### Tier S (Score 6-8)
 
 ```
@@ -73,6 +75,7 @@ Skipped: 2, 3, 4, 5
 
 **Step adaptations:**
 - Step 1: 3-5 bullet requirements, no formal document
+- Step 3: skipped by default; if explicitly forced, use Nygard as the lightweight fallback
 - Step 6: Inline in conversation, no separate file
 - Step 8: Smoke tests only — does it compile? Do existing tests pass?
 
@@ -84,7 +87,7 @@ Skipped: 2, 4, 9
 ```
 
 **Step adaptations:**
-- Step 3: Single ADR for the main architectural decision
+- Step 3: Single Nygard/ITD-light ADR for the main architectural decision; keep the invariant core plus drivers, options, rationale, consequences, and Confirmation
 - Step 3.5: QCSD ideation swarm — 3 core agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 5: Component diagram only, no full C4
 
@@ -97,7 +100,7 @@ Parallel groups: (2,3) and (4,5); Step 3.5 runs after Step 3, Step 9 after Step
 
 **Step adaptations:**
 - Step 2: Research analogues in codebase and external patterns
-- Step 3: Multiple ADRs for each significant decision
+- Step 3: Multiple MADR+Confirmation ADRs for each significant decision
 - Step 3.5: QCSD ideation swarm — 3-9 parallel agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 4: Bounded contexts + ubiquitous language
 - Step 5: Full C4 (Context + Container + Component)
@@ -113,6 +116,7 @@ Parallel groups: (2,3), (4,5 — after 3.5), (7 per module)
 
 **Step adaptations:**
 - All steps at full depth
+- Step 3: Full MADR+Confirmation ADRs; one decision per ADR with typed follow-up links
 - Step 3.5: QCSD ideation swarm — 3-9 parallel agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 7: Multiple parallel agents, one per module/domain
 - Step 8: Full QE — unit + integration + e2e + performance + security review