mandrel 2.33.0 → 2.35.0

package/.agents/workflows/audit-adrs.md

@@ -0,0 +1,270 @@
+---
+description: >-
+  Audit the decisions log as a live contract — Accepted ADRs whose claims the
+  tree has outgrown, broken supersede chains, structural gaps, and directional
+  changes that landed with no decision recorded. A deliberately-global lens over
+  whichever decisions-log layout the consumer ships.
+---
+
+# Decisions-Log (ADR) Audit
+
+You are a Staff Engineer & Decision Historian verifying that the consumer's
+**decisions log still describes the system that exists**. An ADR is not prose
+that merely rots — it is retrieved as *authority*: agents and humans read an
+`Accepted` decision as the settled answer and do not re-litigate it. So an
+Accepted ADR the tree has outgrown is worse than no ADR at all — it actively
+teaches a wrong contract, and it keeps teaching it until someone supersedes it.
+That is this lens's central target; structural tidiness is the cheap part.
+
+The shared lens machinery — read-only constraint, scope interpretation, report
+envelope + finding-block skeleton, severity scale, self-cross-check, and
+execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-adrs-results.md`. Dimension values:
+`Decision Drift | Supersede-Chain Integrity | Structure & Status Hygiene |
+Missing Decision | Layout Conformance`; the report adds a **Decision Coverage**
+table.
+
+## Applicability & layout detection
+
+**Mandrel ships two first-class decisions-log layouts** (the
+[`core/documentation-and-adrs`](../skills/core/documentation-and-adrs/SKILL.md)
+Policy Capsule is the SSOT), and this lens reads whichever one the consumer
+adopted. **Both layouts keep the same entry file** — `decisions.md` under the
+configured docs root — so its mere presence never identifies the layout. Detect
+in this order, resolving `<docsRoot>` from `project.paths.docsRoot` in
+`.agentrc.json` (default `docs`):
+
+1. **Neither `<docsRoot>/decisions.md` nor `<docsRoot>/decisions/` exists** →
+   the project keeps no decisions log. Emit the not-applicable report below and
+   stop. Never invent a log, and never infer decisions from commit history.
+2. **`decisions.md` only** → **single-file dated-entry layout** (the default).
+   Every ADR body lives in that one file as an append-only entry.
+3. **`decisions.md` + a `decisions/` directory** → read the entry file to tell
+   the two apart. When it is predominantly an **index** (one row or link per
+   ADR pointing into `decisions/`), this is the **index + `decisions/`
+   directory** (MADR-style) layout, and each `decisions/NNNN-*.md` file is an
+   ADR body. When it instead carries full ADR bodies *and* a `decisions/`
+   directory holds further ADRs, the log is a hybrid — conformant **only** when
+   every file under `decisions/` is reachable from the entry file by an
+   index row or an in-entry pointer; otherwise it is a Layout Conformance
+   finding (an unreferenced ADR body is invisible to every reader who starts,
+   as they must, at the entry file).
+4. **`decisions/` only, with no entry file** → a Layout Conformance finding:
+   the entry file is the mandatory-read surface both layouts guarantee, and
+   without it the directory's ADRs are unreachable from the docs context.
+
+**Override.** An operator may pass `--paths <file ...>` (audit specific ADR
+files) or `--dir <path>` (treat that directory as the decisions root) to point
+the lens at a non-conventional location. These flags are the **only** override:
+there is deliberately no `.agentrc.json` key for the decisions-log location, so
+detection stays derived from the skill's two layouts rather than from
+configuration a consumer must maintain.
+
+## Whole-log scope (global lens)
+
+Unlike the change-set-scoped lenses, this lens **always evaluates the whole
+decisions log**, even when the change that triggered it touched one file.
+Decision integrity is a global property: a supersede chain spans entries the
+change set never names, and — the load-bearing case — a code change *elsewhere*
+is exactly what invalidates an Accepted ADR's claims. Narrowing to the change
+set would blind the lens to its primary finding class.
+
+Accordingly this lens declares `"scope": "global"` in
+[`audit-rules.json`](../schemas/audit-rules.json) — the single source of truth
+`resolveLensTier` in
+[`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js) reads —
+and is **exempt from the cross-epic-leak guard** that narrows every other
+lens's evidence to its `changedFiles`. The exemption is scoped to this lens
+only; the guard is not weakened for any other lens.
+
+```text
+{{changedFiles}}
+```
+
+- For this lens, **ignore** the `{{changedFiles}}` block above even when it is
+  populated: the decisions log is evaluated whole regardless. The block is
+  rendered only for envelope-shape parity with the scoped lenses. Do use it,
+  when populated, as a **prioritization hint** — an Accepted ADR whose subject
+  the change set touches is the first one to claim-check — never as a filter on
+  what is audited or reported.
+
+## Execution strategy
+
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy). On a large log, the Decision Drift claim-check
+(Step 2.1) is the one dimension worth fanning out per batch of entries under
+parallel-tooling Rule 3 — merge under the shared self-cross-check.
+
+## Step 1: Deterministic structure sweep first
+
+Run the cheap exact checks before reading any ADR for meaning — they
+de-duplicate the easy findings and give Step 2 its inventory. Adjust the paths
+below to the detected layout (or the `--dir` / `--paths` override):
+
+```bash
+# Entry file + any ADR bodies (single-file layout yields just the entry file).
+ls docs/decisions.md docs/decisions/*.md 2>/dev/null
+
+# Status lines and their spelling — the vocabulary is Accepted / Superseded
+# by … / Deprecated / Reverted (…); anything else is a Structure & Status
+# Hygiene finding.
+grep -rn '^\*\*Status:\*\*\|^- \*\*Status:\*\*' docs/decisions.md docs/decisions/ 2>/dev/null
+
+# Entry headings, for the id/date/uniqueness checks in Step 1's list below.
+grep -n '^## ' docs/decisions.md 2>/dev/null
+
+# Link integrity across the docs surface, including every ADR cross-reference.
+node .agents/scripts/check-doc-links.js
+```
+
+From that output, resolve deterministically — each of these is a
+**Structure & Status Hygiene** finding except where noted:
+
+1. **Canonical sections.** Every ADR carries the canonical set the skill's
+   Policy Capsule names — **Status, Date, Deciders, Context, Decision,
+   (Alternatives Considered), Consequences**. `Alternatives Considered` is
+   optional; a missing `Status`, `Context`, `Decision`, or `Consequences` is a
+   finding, and a missing `Status` is the most severe of them because every
+   other dimension keys off it.
+2. **Status vocabulary.** Each status reads `Accepted`, `Superseded by <ref>`,
+   `Deprecated`, or `Reverted (<date>)` — a reverted decision was **undone**
+   rather than replaced, so unlike a superseded one it has no successor to
+   point at, and its missing `by <ref>` is correct rather than a defect. A
+   free-invented status word — anything outside those four — leaves the entry
+   unclassifiable by this lens and by every reader.
+3. **Unique, stable ids.** No two entries share an id/anchor; MADR files use
+   zero-padded sequential numbering matching their heading id.
+4. **Parseable dates.** Every `Date` parses, and no entry is dated in the
+   future.
+5. **Link integrity.** Report what `check-doc-links.js` finds inside the
+   decisions surface; leave findings outside it to `audit-documentation`.
+
+This lens orchestrates the existing checker only — it adds no new deterministic
+checker script, and the sweep above is inline shell by design.
+
+## Step 2: Evaluation dimensions
+
+### 2.1 Decision Drift — **`Accepted` entries only**
+
+This is the lens's primary value. For each **Accepted** entry, extract its
+load-bearing claims — the scripts, files, directories, commands, flags, config
+keys, contracts, and mechanisms it names as decided — and verify each against
+the current tree, exactly as a documentation claim-check would. Flag an
+Accepted decision whose subject the code has moved past: a named mechanism that
+no longer exists, a contract the implementation has replaced, a path or command
+that resolves to nothing, a constraint the tree now routinely violates.
+
+**Scope this claim-check to Accepted entries and no others.** A `Superseded`
+or `Deprecated` entry is *supposed* to describe a world that no longer exists —
+claim-checking it manufactures findings out of correctly-retired history, and
+on a long log it is also where the cost would go. Superseded and Deprecated
+entries get the chain checks in 2.2 and the structure checks in Step 1, and
+nothing else.
+
+**Remediation is always supersede-or-amend, never silent edit or deletion** —
+the skill's lifecycle rule is that an ADR is superseded in place, never pruned
+or archived. Say which in the finding: amend when the decision still holds and
+only its details moved; supersede when the decision itself no longer describes
+what the project does.
+
+Severity guidance: **High** — an Accepted ADR whose central decision the code
+contradicts (it will be retrieved and believed); **Medium** — an Accepted ADR
+whose supporting details drifted while its decision still holds; **Low** —
+cosmetic staleness (an old path in an aside, a renamed tool in an example).
+
+### 2.2 Supersede-Chain Integrity
+
+The chain is what keeps a retired decision honest, so audit it as a graph:
+
+- **Every supersede reference resolves** to an ADR that exists (a heading
+  anchor in the single-file layout, a file in the directory layout).
+- **No cycles**, and no entry superseding itself.
+- **Index ↔ entry agreement** (directory layout, and any single-file log
+  carrying a summary table): the status in the index row matches the status in
+  the ADR body. A row saying `Accepted` over a body saying `Superseded` is a
+  finding — readers stop at the index.
+- **Partial supersessions name what survives.** An entry recording that *some*
+  rows or clauses are superseded while the rest stand MUST say precisely which;
+  an unscoped "partly superseded" leaves every clause ambiguous.
+- **No two Accepted entries contradict each other** on the same subject. When
+  a later decision silently overrode an earlier one, the earlier is the finding:
+  it was never marked superseded.
+
+### 2.3 Structure & Status Hygiene
+
+Promote the Step 1 sweep's resolved items to findings here. Keep them terse —
+each names the entry and the missing or malformed element.
+
+### 2.4 Missing Decision
+
+The inverse gap: a directional change that landed with **no** decision
+recorded. **Bound the search by date** — inspect history since the newest
+entry's `Date`, not the whole history, or this dimension dominates the lens's
+cost on any mature repository:
+
+```bash
+git log --since=<newest-ADR-date> --pretty='%h %s' -- . | head -50
+```
+
+Flag only **directional** changes — a mechanism retired, a contract cut over, a
+dependency or platform swapped, an architectural seam moved. Routine features,
+fixes, and refactors are not decisions and must not be reported here. When the
+newest entry is recent and nothing directional landed since, record that as a
+single `Info` observation rather than straining for a finding.
+
+### 2.5 Layout Conformance
+
+Report the detection outcomes named in **Applicability & layout detection**: an
+unreferenced ADR body under `decisions/`, a `decisions/` directory with no
+entry file, or an index whose rows and directory contents disagree about which
+ADRs exist.
+
+## Not-applicable report
+
+When the project keeps **no decisions log** (neither the entry file nor the
+directory exists, and no `--paths` / `--dir` override was supplied), emit this
+explicit report instead of empty findings — and stop:
+
+```text
+# Decisions-Log (ADR) Audit Report
+
+## Executive Summary
+
+**Not applicable** — this project keeps no decisions log (no `decisions.md`
+entry file and no `decisions/` directory under the configured docs root), so
+the ADR lens has nothing to inspect and was skipped.
+
+## Detailed Findings
+
+_None — lens not applicable._
+```
+
+## Constraint (lens-specific carve-out)
+
+Read-only over the decisions log and the tree it makes claims about. The single
+write is the report artifact: never edit, supersede, renumber, reformat, or
+delete an ADR — recording that a decision needs superseding is the deliverable,
+and performing the supersession is a separate, human-owned pass. Run
+`check-doc-links.js` in its default read-only mode only. Generic documentation
+staleness outside the decisions surface belongs to
+[`audit-documentation`](audit-documentation.md); architectural boundary
+violations belong to `audit-architecture`. This lens judges whether a *recorded
+decision* still matches the tree — never whether the decision was a good one.
+
+## Report additions
+
+Beyond the shared skeleton (Executive Summary + Detailed Findings from the
+core), this lens's report carries its own title and a Decision Coverage table,
+so a reader can see what was claim-checked versus what was only chain-checked:
+
+```markdown
+# Decisions-Log (ADR) Audit Report
+
+## Decision Coverage
+
+| ADR         | Status                                          | Checked                       |
+| ----------- | ----------------------------------------------- | ----------------------------- |
+| [id, title] | [Accepted · Superseded · Deprecated · Reverted] | [Claims + chain · Chain only] |
+```

package/.agents/workflows/audit-documentation.md

@@ -211,6 +211,23 @@ findings land as actionable, tracked work rather than a report nobody reads.
 Run the deterministic checkers in `--check` mode only; the single write is the
 report artifact. Do not edit any documentation or code.
 
+### Boundary with the ADR lens
+
+**Decision-log semantics belong to [`audit-adrs`](audit-adrs.md)**, not to this
+lens: whether an `Accepted` ADR's claims still match the tree, whether its
+supersede chain resolves, whether the index and the entry bodies agree on a
+status, and whether a directional change landed with no decision recorded. That
+lens reads the whole decisions log as a graph; this one would only ever see the
+decisions file as one more prose doc.
+
+This lens keeps its **generic** coverage of that file — link integrity, command
+and path claims, and the History Bloat / Contradiction / Authority Drift
+categories above — and both lenses may legitimately touch `decisions.md`. When
+a finding turns on an ADR's **status, chain, or decided contract**, leave it to
+`audit-adrs` rather than reporting it here, so the two lenses do not
+double-report the same defect. The History Bloat remediation is unchanged and
+still applies: never prune an ADR by archiving — supersede it in place.
+
 ## Report additions
 
 Beyond the shared skeleton (Executive Summary + Detailed Findings from the

package/.agents/workflows/helpers/deliver-light.md

@@ -131,8 +131,11 @@ answer).
    invoked, not reimplemented.
 
 3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
-   `npm test` once in the worktree, then run the bounded acceptance self-eval
-   loop ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
+   the full suite once in the worktree **so close can credit it** — the
+   crediting invocation and the freshness contract are
+   [`deliver-story.md`](deliver-story.md) Step 1.3, unchanged here — then run
+   the bounded acceptance self-eval loop
+   ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
    on `story-<id>` with `(refs #<storyId>)`.
 
 4. **Diff backstop.** Before close, re-check the ACTUAL diff:

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -233,12 +233,34 @@ runs maker-blind at Story-scope review inside the close subprocess. The
 dispatch step produces `checklistPath` from the Story's predicted footprint
 before it spawns the worker — see [`/deliver`](../deliver.md).
 
-**Pre-eval full-suite discipline (spine step 5).** Repo-invariant guards —
+**Pre-eval full-suite discipline (spine step 1.3).** Repo-invariant guards —
 drift-guard and schema tests living outside the Story's scoped greps — are
 the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
 the cost of one pre-eval full-suite run.
 
+**Run it so close can credit it.** Close skips a gate that already passed at
+the current HEAD, but a bare `npm test` deposits no such record — the suite
+then runs twice per delivery, once here and once in the close gate chain.
+Pick the invocation by the same predicate `close-validation/gates.js` uses to
+choose its test gate:
+
+```bash
+# CRAP gate enabled (default) + a `test:coverage` script — writes the stamp
+# the close `coverage-capture` gate reads:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — the evidence record the close `test` gate reads. <workCwd> must
+# be ABSOLUTE and the runner exactly `npm test`: both sides hash
+# {cmd, args, cwd}, so a relative path or a wrapper misses the credit.
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+The credit expires the moment it stops describing the tree: evidence is keyed
+on HEAD, the capture stamp on a content digest of `crap.targetDirs`. A
+self-eval fix — or any commit — invalidates it and close re-runs the suite for
+real, so this never trades away the gate.
+
 **Conflict with `main` mid-implementation** → resolve as you would any branch
 rebase. There is no `epic/<id>` intermediate, so the rebase base is `main`
 directly.

package/.agents/workflows/helpers/deliver-story.md

@@ -75,9 +75,11 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
 2. Implement and commit on the Story branch, iterating with quick advisory
    gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
-3. Run `npm test` once in the worktree **before Step 1a**: repo-invariant
+3. Run the full suite once in the worktree **before Step 1a**: repo-invariant
    guards outside the Story's scoped greps are the failure class that bounces
-   deliveries. Fix and commit first, then run the self-eval loop.
+   deliveries. Fix and commit first, then run the self-eval loop. Run it **so
+   Step 3 credits it** — a bare `npm test` records nothing, so close re-runs
+   the identical suite (reference § Step 1, "Pre-eval full-suite discipline").
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 

package/docs/CHANGELOG.md

@@ -15,6 +15,31 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.35.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.34.0...mandrel-v2.35.0) (2026-08-28)
+
+
+### Added
+
+* add /audit-adrs — global decisions-log audit lens (decision drift, supersede-chain integrity, structure, missing decisions) ([#5072](https://github.com/dsj1984/mandrel/issues/5072)) ([#5073](https://github.com/dsj1984/mandrel/issues/5073)) ([5757e6a](https://github.com/dsj1984/mandrel/commit/5757e6ae3da471713dcdb4ac8b6d8093ea36d6f4))
+
+
+### Fixed
+
+* **adrs:** add Reverted to the ADR status vocabulary and pin it to the skill (refs [#5078](https://github.com/dsj1984/mandrel/issues/5078)) ([#5083](https://github.com/dsj1984/mandrel/issues/5083)) ([d498575](https://github.com/dsj1984/mandrel/commit/d49857573725d8241d7083ad4579583b47af4935))
+* **audit-rules:** register a deploy-runtime sensitive-path class (refs [#5069](https://github.com/dsj1984/mandrel/issues/5069)) ([#5070](https://github.com/dsj1984/mandrel/issues/5070)) ([da7f9f3](https://github.com/dsj1984/mandrel/commit/da7f9f3969aa14afa45a89d1ee4973248268a7cd))
+* **findings:** union the fingerprint lookup with the semantic pass in routeFinding (refs [#5079](https://github.com/dsj1984/mandrel/issues/5079)) ([#5082](https://github.com/dsj1984/mandrel/issues/5082)) ([fd82de3](https://github.com/dsj1984/mandrel/commit/fd82de3496b4fe02cf29bead27957ce82ef7a0b2))
+* fix coverage-capture freshness: derive the scorable-source extension set from the CRAP scanner and fail closed when discovery finds nothing ([#5076](https://github.com/dsj1984/mandrel/issues/5076)) ([#5081](https://github.com/dsj1984/mandrel/issues/5081)) ([09f89c0](https://github.com/dsj1984/mandrel/commit/09f89c0bd39adde9936ebd6c47fb4c2a5c3ee4cd))
+
+## [2.34.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.33.0...mandrel-v2.34.0) (2026-08-27)
+
+
+### Fixed
+
+* **baselines:** weight the mutation rollup by mutant count and gate the migration (refs [#5058](https://github.com/dsj1984/mandrel/issues/5058)) ([#5062](https://github.com/dsj1984/mandrel/issues/5062)) ([a645d30](https://github.com/dsj1984/mandrel/commit/a645d3085450b4dae39ae5d0a9b9844014535f84))
+* **coverage:** describe incrementalCoverage honestly, drop inert forwarding (refs [#5065](https://github.com/dsj1984/mandrel/issues/5065)) ([#5066](https://github.com/dsj1984/mandrel/issues/5066)) ([04ff450](https://github.com/dsj1984/mandrel/commit/04ff450cb1774a1faa0b4f901f1e09261b0ae00a))
+* delivery lifecycle: credit the Step 1 full-suite run to close and enable incremental coverage by default ([#5063](https://github.com/dsj1984/mandrel/issues/5063)) ([#5064](https://github.com/dsj1984/mandrel/issues/5064)) ([39b1ea4](https://github.com/dsj1984/mandrel/commit/39b1ea421c9a8a43f35ad4c8cbc082e1f2ead8c4))
+* **plan-persist:** re-carry audit provenance onto dependent Stories (refs [#5056](https://github.com/dsj1984/mandrel/issues/5056)) ([#5060](https://github.com/dsj1984/mandrel/issues/5060)) ([548cc8a](https://github.com/dsj1984/mandrel/commit/548cc8a46afc5b643452060cc3a03bf71a874b89))
+
 ## [2.33.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.32.0...mandrel-v2.33.0) (2026-08-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.33.0",
+  "version": "2.35.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",