mandrel 1.58.0 → 1.59.0

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

@@ -0,0 +1,226 @@
+---
+description: Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report.
+---
+
+# Documentation Staleness & Completeness Audit
+
+## Role
+
+Staff Engineer & Documentation Steward
+
+## Context & Objective
+
+You are auditing the repository's primary prose documentation to verify it
+is **up to date and complete**. Prose docs rot silently: commands get
+renamed, scripts move, described workflows change shape, and
+version/topology claims go stale. The deterministic gates
+(`check-doc-links.js`, `check-lifecycle-doc-drift.js`,
+`validate-docs-freshness.js`) catch broken links, drift against generators,
+and Epic-scoped freshness — they cannot tell whether the prose still
+describes how the code actually behaves. That semantic verification is this
+lens's job.
+
+## Target set (config-driven union)
+
+The audit target set is **not** "all markdown in the repo". Build it as the
+union of:
+
+1. **`project.docsContextFiles`** from `.agentrc.json` (each entry resolved
+   against `project.paths.docsRoot`, default `docs/`; skip absent files
+   silently).
+2. **`delivery.docsFreshness.paths`** from `.agentrc.json`.
+3. **Conventional anchors:** the root `README.md`, `AGENTS.md` /
+   `CLAUDE.md`, `CONTRIBUTING.md` (when present), and top-level `docs/*.md`
+   (non-recursive).
+4. **An explicit `--paths` override** — when the operator invokes the lens
+   with `--paths <file ...>`, add those files to the union. This is the
+   escape hatch for everything outside 1–3; there is no dedicated config
+   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
+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
+(`docs/CHANGELOG.md`, release-please-owned) are likewise excluded from
+semantic review beyond Step 1's deterministic checks.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to the intersection of the target-set union and
+  those files — plus any target-set doc whose claims describe code in the
+  change set (a renamed script invalidates every doc that references it).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full target-set audit defined in the remaining steps.
+
+## Execution strategy (dual-path)
+
+This lens runs along one of two execution paths. Both emit the **identical**
+report contract (Step 3); downstream consumers (`/epic-deliver` Phase 4
+epic-audit, `audit-to-stories`) are agnostic to which path produced it.
+
+- **Orchestrated (dynamic-workflow) path.** When Claude Code's
+  [dynamic workflows](https://code.claude.com/docs/en/workflows) are
+  available, the saved project workflow
+  `.claude/workflows/audit-documentation.workflow.js` fans the semantic
+  dimensions below out as parallel read-only subagents — each agent walks
+  the full target set per doc for its dimension — runs an **adversarial
+  verify** stage (an independent agent re-checks every stale-claim finding
+  against the current code and drops claims it cannot reproduce — doc
+  staleness is notoriously false-positive-prone), then synthesises the
+  Step 3 report. The orchestrator derives its per-dimension prompts from
+  *this* markdown at run time — the lens stays the single source of truth;
+  the script does not fork a second copy of the spec. Step 1's
+  deterministic checkers still run in the calling session (the analysis
+  subagents are read-only and cannot execute them); their results are
+  passed to the workflow as the `deterministicFindings` input and folded
+  into the synthesis.
+- **Sequential (single-pass) path.** When dynamic workflows are unavailable,
+  follow Steps 1–3 below turn-by-turn exactly as before. This is the default
+  fallback and changes nothing about the existing behaviour.
+
+**Strategy selection** is computed by
+[`lib/dynamic-workflow/capability.js`](../scripts/lib/dynamic-workflow/capability.js)
+(`selectAuditStrategy`). The orchestrated path is chosen only when the runtime
+is Claude Code, `disableWorkflows` is not set (settings.json **or**
+`CLAUDE_CODE_DISABLE_WORKFLOWS`), and the Claude Code version meets the
+research-preview floor (`>= 2.1.154`). Any other runtime, a disabled setting,
+or an older version degrades gracefully to the sequential path.
+
+> **Capability degradation, not a contract shim.** This dual path is **not**
+> covered by the No-Shim / hard-cutover rule in
+> [`git-conventions.md`](../rules/git-conventions.md). That rule forbids
+> running two shapes of the *same contract* side by side. Here there is **one**
+> report contract; only the *execution strategy* is selected from a runtime
+> capability — the same pattern the protocol already endorses for live-docs
+> fallback in [`instructions.md` §1.C/§1.D](../instructions.md). The full
+> capability-degradation rationale lives in the
+> [`capability.js`](../scripts/lib/dynamic-workflow/capability.js) module
+> docstring; the orchestrated-run evidence and per-lens cost/precision gate
+> verdicts live in [`docs/roadmap.md`](../../docs/roadmap.md) (Part 3 —
+> Dynamic-Workflow Orchestration).
+
+**Forcing a path (for testing).** Set `MANDREL_AUDIT_STRATEGY=sequential` to
+verify the fallback path with the feature notionally disabled, or
+`MANDREL_AUDIT_STRATEGY=orchestrated` to pin the dynamic path. To exercise the
+real disable signals instead, set `CLAUDE_CODE_DISABLE_WORKFLOWS=1` (env) or
+`disableWorkflows: true` in `.claude/settings.json` and re-run the lens — both
+degrade to the sequential path.
+
+## Step 1: Deterministic Signal First
+
+> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+
+Run the existing deterministic checkers before any semantic reading — they
+are cheap, exact, and de-duplicate the easy findings:
+
+```bash
+node .agents/scripts/check-doc-links.js
+node .agents/scripts/check-lifecycle-doc-drift.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
+```
+
+Fold the results in as findings:
+
+- **Checker failures** (broken links, lifecycle drift) become individual
+  findings with `Category: Link Integrity` (or `Generator Drift` for the
+  lifecycle gate), 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
+  remediation is "rerun `npm run docs:gen` / `npm run sync:commands` and
+  commit the regenerated output".
+
+This lens orchestrates the existing checkers only; it does not add new
+deterministic checker scripts.
+
+## Step 2: Semantic Claim Verification & Completeness
+
+For every doc in the target set (minus the generated exclusions), verify
+its claims against the code — read the doc, extract its testable claims,
+and check each one:
+
+1. **Command & Script References:** Every referenced npm script exists in
+   `package.json`; every referenced CLI command and
+   `node .agents/scripts/<name>.js` invocation resolves to a real script
+   with the documented flags.
+2. **Path & Module References:** Every referenced file path, directory, and
+   module name exists at the stated location (account for moves and
+   renames).
+3. **Workflow & Contract Descriptions:** Described workflows, label
+   taxonomies (`agent::*`, `type::*`, `meta::*`), branch shapes
+   (`story-<id>`, `epic/<id>`), and artifact contracts match how the
+   current scripts actually behave — read the implementation when the
+   prose makes a behavioural claim.
+4. **Version & Topology Claims:** Version numbers, package names, release
+   topology, CI gate names, and tool-matrix claims are current.
+5. **Completeness:** Major surfaces with no documentation coverage in the
+   target set — workflows under `.agents/workflows/`, operator-facing
+   scripts under `.agents/scripts/`, and config keys in
+   `.agents/schemas/agentrc.schema.json` that no target-set doc mentions.
+   Report material gaps, not an exhaustive index.
+
+Severity guidance: **High** = the doc instructs something that no longer
+works (wrong command, deleted script, contract mismatch); **Medium** =
+materially outdated description or missing coverage of a major surface;
+**Low** = cosmetic drift, stale examples, tone/format inconsistencies.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-documentation-results.md`, using the exact
+template below.
+
+```markdown
+# Documentation Audit Report
+
+## Executive Summary
+
+[Overview of documentation health (High/Medium/Low confidence that the docs
+match the code), the deterministic-gate verdicts, and primary drift themes.]
+
+## Target Set Coverage
+
+| Doc    | Source                                                                | Verdict                         |
+| ------ | --------------------------------------------------------------------- | ------------------------------- |
+| [path] | [docsContextFiles · docsFreshness · anchor · --paths] | [Current · Drifted · Excluded (generated)] |
+
+## Detailed Findings
+
+[For every gap identified, use the following strict structure:]
+
+### [Short Title of the Issue]
+
+- **Category:** [Broken Instruction | Stale Description | Missing Coverage | Generator Drift | Link Integrity]
+- **Impact:** [High | Medium | Low]
+- **Current State:** [The doc, the exact claim, and what the code actually
+  does — cite file paths and lines on both sides]
+- **Recommendation & Rationale:** [The specific doc edit (or generator
+  rerun) and why it restores accuracy]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this doc fix independently]`
+```
+
+## Constraint
+
+This workflow is **read-only** with respect to the repository: run the
+deterministic checkers in `--check` mode only, and do not edit any
+documentation or code. The single write is the report artifact. Provide the
+analysis and remediation prompts; do not apply changes.

package/.agents/workflows/epic-deliver.md

@@ -297,32 +297,25 @@ NDJSON line to `temp/epic-<epicId>/lifecycle.ndjson`; the matching
 after the Agent return is recorded in § 2c.
 
 Each Agent call's prompt must (1) name the Story + Epic ids, (2)
-instruct the child to invoke `helpers/epic-deliver-story <storyId>`, (3) state the
-**return contract** below, (4) remind the child of the
-**non-interactive contract** (no clarifying questions; transition to
-`agent::blocked` and exit if stuck), (5) ask the child to suppress
-per-Story chat relay and include its **terminal** `renderedBody` in the
-JSON return, and (6) require the child to emit a `story.heartbeat`
-lifecycle event at least once per Story-level phase transition via
-`node .agents/scripts/story-phase.js` (or whenever it stalls on a
-long-running step), and if it cannot make progress to transition
-to `agent::blocked` rather than fall silent. The pairing of
+instruct the child to invoke `helpers/epic-deliver-story <storyId>`
+(whose Step 4 defines the child's return shape), (3) remind the child
+of the **non-interactive contract** (no clarifying questions;
+transition to `agent::blocked` and exit if stuck), (4) ask the child to
+suppress per-Story chat relay, and (5) require the child to emit a
+`story.heartbeat` lifecycle event at least once per Story-level phase
+transition via `node .agents/scripts/story-phase.js` (or whenever it
+stalls on a long-running step), and if it cannot make progress to
+transition to `agent::blocked` rather than fall silent. The pairing of
 `story.heartbeat` and `agent::blocked` is what lets the §2e Idle
 Watchdog distinguish a working child from a dead one; a silent child
 with no recent heartbeat and no blocker label is the failure mode the
 watchdog is built to catch.
 
-```json
-{
-  "storyId": <number>,
-  "status": "done" | "blocked" | "failed",
-  "phase": "init|implementing|closing|blocked|done",
-  "branchDeleted": <boolean>,
-  "blockerCommentId": <string|null>,
-  "detail": <string|undefined>,
-  "renderedBody": <string|undefined>
-}
-```
+There is **no per-child JSON return-parsing ceremony** for the parent
+to enforce. GitHub state is the contract: `epic-execute-record-wave.js`
+(§ 2c, mode B) treats each child's raw return text as a best-effort
+hint and reconciles any unparseable, empty, or missing return directly
+from the Story's live labels and comments (Story #3907).
 
 **Sub-agent dispatch.** `Agent` calls emit no `model:` argument by
 default — children inherit from the `general-purpose` sub-agent
@@ -349,8 +342,8 @@ node .agents/scripts/epic-execute-record-wave.js \
 # `<inline-json>` shape: [{ "storyId": <n>, "returnText": "<raw text>" }]
 ```
 
-**Prefer mode B** when the host LLM can't fully verify every child's
-return is a parseable envelope. The CLI reconciles parse failures from
+**Mode B is the default path** — pipe the raw return texts through
+without inspecting them. The CLI reconciles parse failures from
 GitHub, aggregates terminal status, appends to `state.waves[]`,
 re-renders `epic-run-progress`, and prints
 `{ status, nextAction, renderedBody, ... }`. Print `renderedBody`

package/.agents/workflows/epic-plan.md

@@ -14,7 +14,7 @@ Director / Architect
 
 You are the master orchestrator for the v5 Epic-Centric ticketing pipeline. Your
 goal is to transform a high-level Epic into a fully decomposed, ready-to-execute
-backlog of Features, Stories, and Tasks.
+backlog of Features and Stories.
 
 `/epic-plan` is the unified planning entry point. It delegates to the two
 phase helpers — [`helpers/epic-plan-spec.md`](helpers/epic-plan-spec.md) and

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

@@ -120,21 +120,17 @@ tri-state carries one of three values:
 
 ### Step 0.6 — Initial `story-run-progress` snapshot
 
-Re-read the `story-init` comment, apply the install tri-state, and upsert
-the initial snapshot (`phase: "init"`):
-
-```bash
-node .agents/scripts/story-deliver-prepare.js --story <storyId> --cwd .
-```
-
-The CLI runs the install command when `dependenciesInstalled === 'false'`
-(default `npm ci`; override with `--install-cmd "<cmd>"`).
-
-The CLI's stdout JSON envelope carries a `renderedBody` field — the markdown
-body that was upserted onto the Story ticket. **Relay it verbatim to chat**
-so operators see the initial progress block before the first commit lands.
-Do the same after every transition in Step 1 / Step 3 (the body is the
-Story-level rollup the parent `/epic-deliver` aggregator reads).
+Story #4017 inlined the former standalone prepare CLI into
+`story-init.js`: Step 0's init run already applied the install tri-state
+in-process (retrying the install command when
+`dependenciesInstalled === 'false'`, default `npm ci`) and rendered the
+initial snapshot (`phase: "init"`). There is no separate command to run.
+
+The Step 0 result envelope carries a `prepare.renderedBody` field — the
+markdown body for the initial Story-phase table. **Relay it verbatim to
+chat** so operators see the initial progress block before the first commit
+lands. Do the same after every transition in Step 1 / Step 3 (the body is
+the Story-level rollup the parent `/epic-deliver` aggregator reads).
 
 ---
 
@@ -301,19 +297,12 @@ When run as a sub-agent, return one JSON object:
 > (`delivery.maxTokenBudget` elision).
 
 `branchDeleted` is sourced from the `branchDeleted` field of the
-`story-close.js` result envelope, which is `branchCleanup.localDeleted &&
-branchCleanup.remoteDeleted`. It is **independent** of `worktreeReap.status`.
-Specifically, when `worktreeReap.status === 'stale-registry-entry'` — a
-Windows-only outcome where the worktree directory was removed and the local
-branch was deleted but `git worktree list` still shows the entry — the
-close still reports `branchDeleted: true` because the branch was honestly
-deleted; a pending-cleanup entry is recorded so the next post-close drain
-(or the next plan-time sweep) clears the stale `.git/worktrees/<name>/`
-registry entry. Treat `stale-registry-entry` as operationally complete
-when computing your return contract: `status: 'done'` is appropriate when
-all Tasks are closed and `branchDeleted: true`, regardless of whether
-`worktreeReap.status` is `'removed'`, `'removed-after-drain'`, or
-`'stale-registry-entry'`.
+`story-close.js` result envelope. It is **independent** of
+`worktreeReap.status` — every reap outcome the close reports (including
+the Windows-only `stale-registry-entry`, which queues a pending-cleanup
+entry for the next drain) is operationally complete. `status: 'done'` is
+appropriate when the Story is closed and `branchDeleted: true`,
+regardless of the reap status.
 
 `renderedBody` is the **most recent** `renderedBody` returned by
 `story-phase.js` (typically the `phase: 'done'` snapshot at close,

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

@@ -632,5 +632,6 @@ safe.
 
 ## See also
 
-- [`/story-deliver`](../story-deliver.md) — Epic-attached Story execution.
+- [`/story-deliver`](../story-deliver.md) — several standalone Stories at
+  once (dependency-aware waves).
 - [`/epic-deliver`](../epic-deliver.md) — full Epic wave loop.

package/.agents/workflows/onboard.md

@@ -46,9 +46,10 @@ genuinely missing, and `mandrel doctor` is read-only).
 ## Prerequisites
 
 1. Mandrel installed and bootstrapped into the project. The zero-to-installed
-   path is `npx create-mandrel`, which installs the `mandrel`
-   package, runs `mandrel sync` to materialize the `.agents/` bundle, and then
-   execs `.agents/scripts/bootstrap.js` to provision the project (labels,
+   path is `npx mandrel init`, which installs the `mandrel`
+   package (when absent), runs `mandrel sync` to materialize the `.agents/`
+   bundle, and then — on the **configure now** prompt option — execs
+   `.agents/scripts/bootstrap.js` to provision the project (labels,
    board, `.agentrc.json` seed). `/onboard` runs **after** that bootstrap
    completes — it does not invoke `bootstrap.js` itself, so the coupling is
    indirect: bootstrap owns first-time provisioning, `/onboard` owns the

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

@@ -277,7 +277,7 @@ duplication on the files the Story already touched:
   must be reverted.
 - **Advisory, not a gate.** This stage does **not** introduce a new
   close-validation gate and does **not** change the semantics of the existing
-  [close-validation](../scripts/lib/close-validation.js) chain (typecheck,
+  [close-validation](../scripts/lib/close-validation/runner.js) chain (typecheck,
   lint, test, format, maintainability, coverage, crap). The canonical gates
   remain the single source of pass/fail at close; the refactor stage only adds
   an extra behaviour-preserving cleanup commit when enabled.

package/README.md

@@ -31,11 +31,11 @@ package-manager combinations.
 
 ## Quickstart
 
-The canonical cold-start path is one launcher command, then two slash
+The canonical cold-start path is one command, then two slash
 commands inside Claude Code:
 
 ```bash
-npx create-mandrel        # install mandrel → sync → bootstrap
+npx mandrel init        # install mandrel → sync → prompt → bootstrap
 ```
 
 ```text
@@ -44,18 +44,23 @@ npx create-mandrel        # install mandrel → sync → bootstrap
 /epic-plan          # ideation -> PRD/Tech Spec -> Epic/Feature/Story hierarchy
 ```
 
-`create-mandrel` installs `mandrel`, materializes `./.agents/` via
-`mandrel sync`, and runs `node .agents/scripts/bootstrap.js` for you,
-forwarding any flags you pass. `/onboard` then walks you from a clean
-checkout to a planned Epic (stack detection, docs scaffolding, a
+`npx mandrel init` installs `mandrel` (when `./.agents/` is absent),
+materializes it via `mandrel sync`, then asks whether to **configure now**
+(option 1 → runs `node .agents/scripts/bootstrap.js`, forwarding any flags you
+pass) or stop at **just the files** (option 2 → re-run `mandrel init` any time
+to configure). Pass `--assume-yes` for a non-interactive run that proceeds
+straight to configure (and forwards the flag to bootstrap). When `./.agents/`
+is already present (you ran `npm install mandrel` first), `init` skips the
+install/sync and goes straight to the prompt. `/onboard` then walks you from a
+clean checkout to a planned Epic (stack detection, docs scaffolding, a
 `mandrel doctor` readiness gate, and a started `/epic-plan`). Once you have a
 planned Epic, deliver it with `/epic-deliver <id>` (wave loop → validation →
 review → retro → open PR).
 
 ### Manual equivalent
 
-If you prefer to drive the three steps `create-mandrel` wraps by hand, run
-them from your project root:
+If you prefer to drive the steps `mandrel init` wraps by hand, run them from
+your project root:
 
 ```bash
 npm install mandrel   # pin an exact, provenance-signed version