mandrel 2.34.0 → 2.36.0

package/.agents/scripts/notify.js

@@ -7,16 +7,10 @@
  * Single dispatch entry point for runtime notifications across two
  * independent channels.
  *
- * Lifecycle-bus integration (Epic #2172): under the Wave-7+ runtime,
- * `notify()` is invoked from the `NotifyDispatcher` listener
- * (`lib/orchestration/lifecycle/listeners/notify-dispatcher.js`),
- * which subscribes to lifecycle events and maps `event.severity` →
- * `notify()` payload. Direct inline calls at phase boundaries are no
- * longer the canonical path — listeners on the bus are. See
- * [`docs/LIFECYCLE.md`](../docs/LIFECYCLE.md) for the bus contract,
- * event taxonomy, and the dispatcher's wiring. Direct CLI / library
- * invocations remain supported for one-shot operator commands and the
- * structured-comment back-channel.
+ * Direct inline calls at phase boundaries are the only path: `notify()`
+ * is invoked from the caller that has something to say. Direct CLI /
+ * library invocations are equally supported, for one-shot operator
+ * commands and the structured-comment back-channel.
  *
  * Channels:
  *

package/.agents/skills/core/documentation-and-adrs/SKILL.md

@@ -13,7 +13,7 @@ description:
 - Document the **why**, not the what. Capture context, constraints, alternatives considered, and trade-offs — code already shows what was built.
 - Write an ADR for any decision that would be expensive to reverse (framework choice, data model, auth strategy, API architecture, hosting platform).
 - Mandrel ships **two first-class decisions-log layouts** — pick one at onboarding (see [Decisions-log layouts](reference.md#decisions-log-layouts)): the **single-file dated-entry** `docs/decisions.md` (default; best for small projects) or the **index + `docs/decisions/` directory** (MADR-style, one file per ADR; best once the log outgrows a single file). Either way, the canonical ADR sections are **Status, Date, Deciders, Context, Decision, (Alternatives Considered), Consequences**.
-- Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, or `Deprecated`. Never silently delete an ADR — supersede it.
+- Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, `Deprecated`, or `Reverted (<date>)` — a reverted decision was **undone** rather than replaced, so unlike a superseded one it has no successor to point at. Never silently delete an ADR — supersede it.
 - Do **not** document obvious code; do **not** restate what the code already says. Stale or redundant docs are worse than no docs.
 - Comments explain **non-obvious intent** (the why). If a comment describes what the code does, refactor the code instead.
 - Keep user-facing docs (README, API docs, changelog) updated as part of the change — out-of-date docs are bugs.

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

@@ -38,9 +38,9 @@ union of:
    key for it.
 
 **Generated docs are excluded from per-doc semantic review.** The output of
-`generate-config-docs.js`, `generate-lifecycle-docs.js`, and
-`generate-workflows-doc.js`, and the synced `.claude/commands/` mirrors, are
-generator-owned: hand-editing them is never the remediation. Instead, Step 1
+`generate-config-docs.js` and `generate-workflows-doc.js`, and the synced
+`.claude/commands/` mirrors, are generator-owned: hand-editing them is never
+the remediation. Instead, Step 1
 runs the generators' `--check` mode and emits a **single** "generator output
 dirty" finding when their output is stale — the remediation is "rerun the
 generator", not "edit the doc". Auto-generated changelog files
@@ -79,7 +79,6 @@ are cheap, exact, and de-duplicate the easy findings:
 ```bash
 node .agents/scripts/check-doc-links.js
 node .agents/scripts/generate-config-docs.js --check
-node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
 node .agents/scripts/resolve-doc-tiers.js --json
 ```
@@ -87,8 +86,8 @@ node .agents/scripts/resolve-doc-tiers.js --json
 Fold the results in as findings:
 
 - **Checker failures** (broken links, generator drift) become individual
-  findings with `Category: Link Integrity` (or `Generator Drift` for the
-  lifecycle gate), citing the checker output verbatim.
+  findings with `Category: Link Integrity`, citing the checker output
+  verbatim.
 - **Generator dirtiness** (any `--check` reporting stale output, including
   a stale `.claude/commands/` mirror) becomes **one single finding** with
   `Category: Generator Drift` — never per-line findings — whose
@@ -211,6 +210,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/docs/CHANGELOG.md

@@ -15,6 +15,39 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.36.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.35.0...mandrel-v2.36.0) (2026-08-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* `.agents/scripts/generate-lifecycle-docs.js` is removed from the published payload, and the framework no longer requires a consumer `docs/LIFECYCLE.md`. A consumer that created that file only to stop the generator aborting can delete it as residue — nothing else reads it. A consumer invoking the generator by hand, or chaining it in its own `docs:gen` / `docs:check`, should drop the call. The lifecycle schemas under `.agents/schemas/lifecycle/` still ship unchanged and the emit path is untouched.
+
+### Fixed
+
+* **check-doc-links:** percent-decode relative link targets before the existence check (refs [#5090](https://github.com/dsj1984/mandrel/issues/5090)) ([#5092](https://github.com/dsj1984/mandrel/issues/5092)) ([024afff](https://github.com/dsj1984/mandrel/commit/024afff5aa000ace8e4f8ee2df6bf246acd0ae40))
+* gate auto-merge arming and the merge wait on head-anchored advisory check conclusions ([#5096](https://github.com/dsj1984/mandrel/issues/5096)) ([#5097](https://github.com/dsj1984/mandrel/issues/5097)) ([a6ae194](https://github.com/dsj1984/mandrel/commit/a6ae194349951ab8cc459f9a4d21a46785014ffd))
+* **git-cleanup:** branch the merged-tip skip taxonomy on ancestry instead of SHA inequality ([#5086](https://github.com/dsj1984/mandrel/issues/5086)) ([#5087](https://github.com/dsj1984/mandrel/issues/5087)) ([caf41b0](https://github.com/dsj1984/mandrel/commit/caf41b0a973866ba1035c5c10178eb46e7c1b078))
+
+
+### Changed
+
+* stop requiring consumers to carry docs/LIFECYCLE.md — retire the consumer-side lifecycle doc mirror ([#5089](https://github.com/dsj1984/mandrel/issues/5089)) ([#5091](https://github.com/dsj1984/mandrel/issues/5091)) ([ad16df8](https://github.com/dsj1984/mandrel/commit/ad16df881692fc5dd169bc4f0bcf73191a872345))
+
+## [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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.34.0",
+  "version": "2.36.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -32,8 +32,8 @@
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
-    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
+    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",

package/.agents/scripts/generate-lifecycle-docs.js

@@ -1,237 +0,0 @@
-#!/usr/bin/env node
-/**
- * .agents/scripts/generate-lifecycle-docs.js — Schema-backed lifecycle docs table
- *
- * Renders a bounded region inside `docs/LIFECYCLE.md` from every
- * `.agents/schemas/lifecycle/*.schema.json`. The region is delimited by:
- *
- *     <!-- BEGIN GENERATED:lifecycle-events -->
- *     ...generated table...
- *     <!-- END GENERATED:lifecycle-events -->
- *
- * Columns: | Event | Schema | Description | Required fields |
- *
- *   - Event             = schema filename minus `.schema.json`
- *   - Schema            = relative markdown link to the schema file
- *   - Description       = the schema's top-level `description` property
- *   - Required fields   = comma-joined list from the schema's `required` array
- *                         (rendered as inline code; "—" when empty/absent)
- *
- * Skips `README.md`. The `ledger-record.schema.json` file is a record
- * envelope rather than a lifecycle event, but to keep this generator
- * literal-schema driven we still emit a row for it — the surrounding doc
- * already calls out the distinction.
- *
- * Modes:
- *   (default)  — rewrites the bounded region in place.
- *   --check    — exits 0 when the on-disk region matches the freshly
- *                generated content, exits 1 with a diff hint otherwise.
- *
- * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable
- * failures surface via `throw new Error(...)` so `runAsCli` can map the
- * throw to `process.exit(1)` deterministically (no `Logger.fatal`).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { Logger } from './lib/Logger.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const SCHEMA_DIR = path.join(PROJECT_ROOT, '.agents', 'schemas', 'lifecycle');
-const DOC_PATH = path.join(PROJECT_ROOT, 'docs', 'LIFECYCLE.md');
-const REGION_BEGIN = '<!-- BEGIN GENERATED:lifecycle-events -->';
-const REGION_END = '<!-- END GENERATED:lifecycle-events -->';
-
-/**
- * Read and parse every `*.schema.json` under the lifecycle schema dir, in
- * ASCII-sorted filename order. The sort is intentional — it produces a
- * stable diff regardless of the host filesystem's enumeration order, which
- * is what makes `--check` reliable across platforms.
- *
- * @param {string} dir Absolute path to the schema directory.
- * @returns {Array<{event:string, file:string, description:string, required:string[]}>}
- */
-function readLifecycleSchemas(dir) {
-  if (!fs.existsSync(dir)) {
-    throw new Error(`Lifecycle schema directory not found: ${dir}`);
-  }
-  const entries = fs
-    .readdirSync(dir)
-    .filter((name) => name.endsWith('.schema.json'))
-    .sort();
-  if (entries.length === 0) {
-    throw new Error(`No *.schema.json files found in ${dir}`);
-  }
-  return entries.map((file) => {
-    const abs = path.join(dir, file);
-    const raw = fs.readFileSync(abs, 'utf8');
-    let json;
-    try {
-      json = JSON.parse(raw);
-    } catch (err) {
-      throw new Error(`Failed to parse JSON schema ${file}: ${err.message}`);
-    }
-    const event = file.replace(/\.schema\.json$/, '');
-    const description =
-      typeof json.description === 'string' && json.description.trim().length > 0
-        ? json.description.trim()
-        : '';
-    const required = Array.isArray(json.required) ? [...json.required] : [];
-    return { event, file, description, required };
-  });
-}
-
-/**
- * Escape pipe characters so they survive Markdown table cell parsing.
- *
- * @param {string} text
- * @returns {string}
- */
-function escapeCell(text) {
-  return text.replace(/\|/g, '\\|');
-}
-
-/**
- * Render the bounded-region body (the generated content between the two
- * comment markers, exclusive of the markers themselves).
- *
- * @param {ReturnType<typeof readLifecycleSchemas>} rows
- * @returns {string}
- */
-function renderTable(rows) {
-  const header = '| Event | Schema | Description | Required fields |';
-  const sep = '| --- | --- | --- | --- |';
-  const body = rows.map((row) => {
-    const eventCell = `\`${row.event}\``;
-    const schemaLink = `[\`${row.file}\`](../.agents/schemas/lifecycle/${row.file})`;
-    const description = escapeCell(row.description || '—');
-    const requiredCell =
-      row.required.length === 0
-        ? '—'
-        : row.required.map((field) => `\`${field}\``).join(', ');
-    return `| ${eventCell} | ${schemaLink} | ${description} | ${requiredCell} |`;
-  });
-  // Surround with blank lines so the markers + table read as a separate block.
-  return ['', header, sep, ...body, ''].join('\n');
-}
-
-/**
- * Substitute the bounded region inside `original`. Throws if either marker
- * is missing, or if `BEGIN` appears after `END`. Idempotent — a re-run on
- * the same input yields byte-identical output.
- *
- * @param {string} original
- * @param {string} body Region body, already including leading/trailing blank
- *                      lines (as produced by `renderTable`).
- * @returns {string}
- */
-function spliceRegion(original, body) {
-  const beginIdx = original.indexOf(REGION_BEGIN);
-  const endIdx = original.indexOf(REGION_END);
-  if (beginIdx === -1) {
-    throw new Error(
-      `Missing region marker "${REGION_BEGIN}" in ${DOC_PATH}. ` +
-        'Insert the marker pair before re-running the generator.',
-    );
-  }
-  if (endIdx === -1) {
-    throw new Error(
-      `Missing region marker "${REGION_END}" in ${DOC_PATH}. ` +
-        'Insert the marker pair before re-running the generator.',
-    );
-  }
-  if (endIdx < beginIdx) {
-    throw new Error(
-      `Region markers out of order in ${DOC_PATH}: END appears before BEGIN.`,
-    );
-  }
-  const before = original.slice(0, beginIdx + REGION_BEGIN.length);
-  const after = original.slice(endIdx);
-  return `${before}\n${body}\n${after}`;
-}
-
-/**
- * Build the canonical post-generation file content for `docs/LIFECYCLE.md`.
- *
- * @param {string} schemaDir
- * @param {string} docPath
- * @returns {{ generated: string, original: string }}
- */
-function buildExpected(schemaDir, docPath) {
-  if (!fs.existsSync(docPath)) {
-    throw new Error(`Target doc not found: ${docPath}`);
-  }
-  const original = fs.readFileSync(docPath, 'utf8');
-  const rows = readLifecycleSchemas(schemaDir);
-  const body = renderTable(rows);
-  const generated = spliceRegion(original, body);
-  return { generated, original };
-}
-
-/**
- * @param {string[]} argv
- */
-async function main(argv = process.argv.slice(2)) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      check: { type: 'boolean', default: false },
-    },
-    allowPositionals: false,
-  });
-
-  const { generated, original } = buildExpected(SCHEMA_DIR, DOC_PATH);
-
-  if (values.check) {
-    if (generated === original) {
-      Logger.info(
-        `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} is up to date.`,
-      );
-      return;
-    }
-    const hint =
-      `${path.relative(PROJECT_ROOT, DOC_PATH)} is out of date. ` +
-      'Run `node .agents/scripts/generate-lifecycle-docs.js` to regenerate the bounded region.';
-    throw new Error(hint);
-  }
-
-  if (generated === original) {
-    Logger.info(
-      `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} already current — no write.`,
-    );
-    return;
-  }
-  fs.writeFileSync(DOC_PATH, generated, 'utf8');
-  Logger.info(
-    `generate-lifecycle-docs: wrote bounded region into ${path.relative(PROJECT_ROOT, DOC_PATH)}.`,
-  );
-}
-
-export {
-  buildExpected,
-  REGION_BEGIN,
-  REGION_END,
-  readLifecycleSchemas,
-  renderTable,
-  spliceRegion,
-};
-
-runAsCli(import.meta.url, main, {
-  source: 'generate-lifecycle-docs',
-  usage: {
-    invocation: 'node .agents/scripts/generate-lifecycle-docs.js [--check]',
-    summary:
-      'Regenerate the lifecycle-event table in docs/LIFECYCLE.md from the event schemas. Writes only when the generated content differs.',
-    flags: [
-      [
-        '--check',
-        'Verify the doc is current and fail if stale; write nothing.',
-      ],
-    ],
-  },
-});