@dzhechkov/keysarium 1.5.25 → 1.5.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.5.25",
+  "version": "1.5.28",
   "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": {
@@ -50,4 +50,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

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
@@ -414,6 +416,30 @@ Codex on limit-exhaustion) stays a knob-only behavior; a direct `models.code='co
 'L', models: { code: 'opus', qe: 'codex:gpt-5.6:high', architecture: 'opus', router: 'fable' } } })` —
 Claude writes the code, Codex independently QEs it.
 
+**Usage-adaptive routing (pre-emptive Codex switch under limit pressure).** When routing is opted into,
+the workflow probes Claude SESSION (active 5h-block) and WEEKLY (rolling 7d) usage at EACH phase boundary
+via a minimal `dz usage --json` agent. When either metric is `>= usageThreshold` (default `70`) BEFORE a
+phase launches — OR the probe output is missing (agent-null, which often MEANS the limit was hit) — ALL
+remaining stages switch to `codex:<top>` (design/code/plan at `xhigh`, router/qe/fleet at `high`). When a
+later probe reads BOTH metrics below the threshold (positive numbers, not nulls), the normal Claude+Codex
+mix is RESTORED. Null percentages (unconfigured limits) change NOTHING in either direction. Switched
+stages are tagged ` (usage-switched)` in `modelsUsed`, and every flip is recorded in the result's
+`usageEvents` array (the audit trail — never trust promiseTags for this). Args:
+
+| `args.*` | Default | Effect |
+|---|---|---|
+| `usageAdaptive` | `true` when routing is requested (any `args.models` key or Codex knob); `false` otherwise | `true` forces it on even without other routing; `false` disables all probes (byte-identical to today) |
+| `usageThreshold` | `70` | the `>=` percent (either metric) that triggers the pre-emptive switch |
+| `usageReasoning` | the `OVERRIDE_REASONING` map | per-stage reasoning under the override (merge over the default: design/code/plan → `xhigh`, router/qe/fleet → `high`) |
+
+Configure the limits the probe measures against in `.dz/config.json` — `memory.usage.sessionTokenLimit`
+and `memory.usage.weeklyTokenLimit` (OPTIONAL; absent ⇒ `pct` is `null` and no switch fires). The
+percentages are **ESTIMATES** from local transcript aggregation (there is no official usage API);
+**calibrate** by scaling a limit by `X/100` when a real limit-hit lands at an estimated `X%`.
+**Honest caveat (the wrapper lesson):** at TRUE exhaustion even the Codex dispatch dies because
+`codex:codex-rescue` is a Claude wrapper subagent — so the switch MUST happen BEFORE, which is why the
+70% pre-emptive probe (not just reactive null-detection) is the real defense.
+
 ### Pattern memory loop (self-learning — runs in ALL modes)
 
 **Self-learning is MANDATORY on EVERY `/feature-adr` run — including plain `/feature-adr` without any

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/08-qe.md

@@ -129,6 +129,35 @@ 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.
+
 ### 4. Multi-Agent Review Panel (L/XL)
 
 For L/XL features, spawn 3 parallel review agents using brutal-honesty modes:
@@ -150,6 +179,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 +229,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