mandrel 1.58.0 → 1.59.0

package/.agents/README.md

@@ -1,58 +1,62 @@
-# Mandrel — `.agents/`
-
-This is the framework payload (`.agents/`) consumed by host repos. It ships
-inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
-npm package and is materialized into a consumer's `./.agents/` directory by
-`mandrel sync`. It carries a system prompt, a baseline rule pack, a
-two-tier skill library, a slash-command workflow set, and the
-orchestration engine that runs Epic → Feature → Story plans on
-GitHub. The framework version is the version of the installed
-[`mandrel`](https://www.npmjs.com/package/mandrel) npm
-package — run `npm ls mandrel` (or read `package.json`), not a
-count here.
+# Mandrel Framework
 
-> **Ticket hierarchy.** Mandrel uses a **3-tier hierarchy**
-> (Epic → Feature → Story) with inline `acceptance[]` / `verify[]` on
-> Story bodies. See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the
-> diagram and execution-model implications.
+An opinionated workflow framework for AI coding assistants built on
+Epic-centric GitHub orchestration. Planning, execution, and state all live natively in GitHub Issues, Labels, and Projects V2.
 
-This is the only README inside the distributed `.agents/` bundle. It
-explains what each part of the bundle is for and captures the
-cross-directory authoring conventions. The process narrative for
+This is the consumer README inside the distributed `.agents/` bundle. It explains what each part of the bundle is for and captures the cross-directory authoring conventions. The process narrative for
 `/epic-plan` and `/epic-deliver` stays in [`docs/SDLC.md`](docs/SDLC.md).
 
+The framework payload (`.agents/`) is consumed by host repos. It ships inside the [`mandrel`](https://www.npmjs.com/package/mandrel)
+npm package and is materialized into a consumer's `./.agents/` directory by `mandrel sync`. It carries a system prompt, a baseline rule pack, a two-tier skill library, a slash-command workflow set, and the orchestration engine that runs Epic → Feature → Story plans on GitHub.
+
+The framework version is the version of the installed [`mandrel`](https://www.npmjs.com/package/mandrel) npm package — run `npm ls mandrel` (or read `package.json`), not a
+count here.
+
 ---
 
 ## Activation
 
-### Cold start — `npx create-mandrel`
+### All-in-one Install
 
-The canonical cold-start path is a single launcher command, run from the
-root of your project (the folder does **not** need to be a git repo yet):
+From an **empty or existing** local directory, run:
 
 ```bash
-npx create-mandrel        # install mandrel → mandrel sync → bootstrap.js
+npx mandrel init        # install (if absent) → prompt: configure now, or just the files
 ```
 
-`create-mandrel` installs `mandrel`, materializes `./.agents/` via
-`mandrel sync` (skipping the install when `.agents/` already exists), and
-finishes by running `node .agents/scripts/bootstrap.js`, forwarding any flags
-you pass. After it completes, run **`/onboard`** inside Claude Code for the
-guided first run — stack detection, docs scaffolding, a `mandrel doctor`
-readiness gate, and a started `/epic-plan` handoff.
+`mandrel init` first **installs the framework if `./.agents/` is absent** —
+`npm install mandrel --ignore-scripts` followed by an explicit `mandrel sync`,
+so the materialization is a single deterministic step rather than a
+postinstall-then-init double sync. When `./.agents/` already exists from a prior install, it skips straight to the prompt — the one subcommand is idempotent across both entry points.
+
+It then shows a **two-option prompt**:
+
+1. **Configure now** — runs `node .agents/scripts/bootstrap.js`, forwarding any
+   passthrough flags unchanged, to wire the project and GitHub side (creates the
+   GitHub repo + Projects board).
+2. **Just the files** — stops after materialization and prints a re-run hint
+   (`mandrel init`) so you can configure later.
 
-The remainder of this section documents the manual steps `create-mandrel`
-wraps, for operators who prefer to drive them by hand.
+`--assume-yes` skips the prompt and configures non-interactively (the flag is
+also forwarded to `bootstrap.js`); a non-TTY run without `--assume-yes` defaults
+to **files-only**, so the side-effecting GitHub provisioning never runs
+unattended.
 
-### Manual cold start — install the npm package
+After it completes, run **`/onboard`** inside Claude Code for the guided first
+run — stack detection, docs scaffolding, a `mandrel doctor` readiness gate, and
+a started `/epic-plan` handoff.
+
+### Manual Install
+
+This section documents the manual steps `mandrel init` wraps, for operators who prefer to drive them by hand.
+
+#### Mandrel Package
 
 From an **empty or existing** project that does not yet have `.agents/`,
 install the package and materialize the framework payload:
 
 ```bash
 npm install mandrel
-# pnpm add mandrel
-# yarn add mandrel
 ```
 
 Installing `mandrel` pins an exact, provenance-signed version in
@@ -69,13 +73,43 @@ npx mandrel sync --dry-run # preview the planned copies, write nothing
 npx mandrel doctor         # confirm the install is healthy
 ```
 
-Then run the bootstrap to wire the project and GitHub side:
+#### Bootstrap Config
 
-```bash
-node .agents/scripts/bootstrap.js
-```
+To wire the local directory and GitHub, run `npx mandrel init` again or use the bootstrapper directly: `node .agents/scripts/bootstrap.js`
+
+The bootstrap pipeline, in order:
+
+1. **Preflight gate (runs first, before any mutation).** A single
+   fail-before-mutate check confirms Node is at the required major
+   version, `git` is on `PATH`, the command is running inside a git work
+   tree, and — unless `--skip-github` is set — that the `gh` CLI is
+   installed and authenticated. If any check fails the bootstrap prints
+   each failing check's remedy and halts with exit 1 **before** touching
+   a single file or making a GitHub call, so a half-configured repo is
+   never left behind.
+2. **Resolve answers (owner / repo / base branch / operator handle /
+   project number).** Defaults are inferred from the local `git remote`
+   and config (no network calls). Each value is resolved through a
+   priority chain: CLI flag → environment variable
+   (`GH_OWNER`, `GH_REPO`, …) → silently-accepted inferred default →
+   interactive picker → free-text prompt → `--assume-yes` default.
+3. **Project-side mutations.** Seeds `.agentrc.json` from
+   [`starter-agentrc.json`](starter-agentrc.json), merges the framework's
+   runtime dependencies into `package.json`, runs the install, wires the
+   command-sync hook (the UserPromptSubmit hook that regenerates the flat
+   `.claude/commands/` tree so every `/<command>` loads), wires the system
+   prompt (see below), gitignores derived artefacts, and runs the
+   quality-gates installer.
+4. **GitHub-side mutations.** Creates the label taxonomy, Project V2
+   fields, branch protection, and merge-method settings. Skipped with
+   `--skip-github`.
 
-### Upgrading and local additions
+The bootstrap is idempotent — safe to re-run; an already-configured
+clone produces zero file mutations.
+
+---
+
+## Upgrading and local additions
 
 Once installed, the ongoing upgrade path is **`mandrel update`** — it bumps
 `mandrel` to the newest non-major version, re-runs `mandrel sync`,
@@ -107,53 +141,9 @@ the consumer-owned space `mandrel sync` never copies into nor prunes and the
 drift check treats as sanctioned, so keep project-specific skills and local
 workflow fragments there rather than editing synced files in place.
 
-### Run the unified bootstrap directly
-
-When `.agents/` is already materialized, run the bootstrap straight from the
-host repo root:
-
-```bash
-node .agents/scripts/bootstrap.js
-# bootstrap also seeds a discoverable npm alias, so after the first run:
-npm run bootstrap
-```
-
-The bootstrap adds an `npm run bootstrap` script to the consumer's
-`package.json` (pointing at `node .agents/scripts/bootstrap.js`) the
-first time it runs — an operator-defined `bootstrap` script always wins,
-so the seed is skipped when the key already exists.
-
-The bootstrap pipeline, in order:
-
-1. **Preflight gate (runs first, before any mutation).** A single
-   fail-before-mutate check confirms Node is at the required major
-   version, `git` is on `PATH`, the command is running inside a git work
-   tree, and — unless `--skip-github` is set — that the `gh` CLI is
-   installed and authenticated. If any check fails the bootstrap prints
-   each failing check's remedy and halts with exit 1 **before** touching
-   a single file or making a GitHub call, so a half-configured repo is
-   never left behind.
-2. **Resolve answers (owner / repo / base branch / operator handle /
-   project number).** Defaults are inferred from the local `git remote`
-   and config (no network calls). Each value is resolved through a
-   priority chain: CLI flag → environment variable
-   (`GH_OWNER`, `GH_REPO`, …) → silently-accepted inferred default →
-   interactive picker → free-text prompt → `--assume-yes` default.
-3. **Project-side mutations.** Seeds `.agentrc.json` from
-   [`starter-agentrc.json`](starter-agentrc.json), merges the framework's
-   runtime dependencies into `package.json`, runs the install, wires the
-   command-sync hook (the UserPromptSubmit hook that regenerates the flat
-   `.claude/commands/` tree so every `/<command>` loads), wires the system
-   prompt (see below), gitignores derived artefacts, and runs the
-   quality-gates installer.
-4. **GitHub-side mutations.** Creates the label taxonomy, Project V2
-   fields, branch protection, and merge-method settings. Skipped with
-   `--skip-github`.
-
-The bootstrap is idempotent — safe to re-run; an already-configured
-clone produces zero file mutations.
+---
 
-### Automatic system-prompt wiring
+## Automatic system-prompt wiring
 
 The bootstrap wires the framework system prompt into a project-root
 `CLAUDE.md` automatically, so there is no manual "load the system prompt"
@@ -170,7 +160,9 @@ If your AI tool is not Claude Code, load
 [`instructions.md`](instructions.md) verbatim through that tool's own
 system-prompt mechanism (`.cursorrules`, Custom Instructions, etc.).
 
-### Interactive repo / project pickers
+---
+
+## Interactive repo / project pickers
 
 When the bootstrap runs interactively (a TTY, and `--assume-yes` is not
 set), the **repo** and **project-number** questions render a live,
@@ -202,7 +194,9 @@ an end-to-end Epic; standalone Stories pair
 Issue) with [`/story-deliver`](workflows/story-deliver.md) (Story Issue → merged
 PR).
 
-### Runtime dependencies
+---
+
+## Runtime dependencies
 
 The framework scripts under `.agents/scripts/` import a small set of
 third-party npm packages at runtime. The materialized `./.agents/` tree
@@ -237,6 +231,14 @@ in `runtime-deps.json`.
 
 ---
 
+## Ticket Hierarchy
+
+Mandrel uses a **3-tier hierarchy**, (Epic → Feature → Story) with inline `acceptance[]` / `verify[]` on story bodies.
+
+See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execution-model implications.
+
+---
+
 ## Contents
 
 | Path | Purpose |

package/.agents/docs/SDLC.md

@@ -225,7 +225,7 @@ graph LR
 
     subgraph Phase0 ["Phase 0: Bootstrap"]
         direction TB
-        Z["👤 npx create-mandrel<br/>(install → sync → bootstrap.js)"]:::manual
+        Z["👤 npx mandrel init<br/>(install → sync → prompt → bootstrap.js)"]:::manual
         Z2["👤 /onboard (guided first run)"]:::manual
         Z --> Z2
     end
@@ -272,15 +272,19 @@ wire the framework system prompt, and create the GitHub labels, Projects V2
 fields, and (when enabled) main-branch protection the orchestration engine
 depends on.
 
-The canonical cold-start path is a single launcher command:
+The canonical cold-start path is a single command:
 
 ```bash
-npx create-mandrel
+npx mandrel init
 ```
 
-`create-mandrel` installs `mandrel`, materializes `./.agents/` via
-`mandrel sync`, and runs `node .agents/scripts/bootstrap.js`, forwarding any
-flags you pass. `bootstrap.js`:
+`mandrel init` installs `mandrel` (when `./.agents/` is absent), materializes
+`./.agents/` via `mandrel sync`, then presents a two-option prompt: **configure
+now** (option 1 → runs `node .agents/scripts/bootstrap.js`, forwarding any flags
+you pass) or **just the files** (option 2 → re-run `mandrel init` any time to
+configure later). `--assume-yes` skips the prompt and proceeds straight to
+configure (and is forwarded to bootstrap); a non-TTY run without it defaults to
+files-only so the GitHub provisioning never runs unattended. `bootstrap.js`:
 
 1. **Provisions a cold start.** Initializes the local git repo (with a first
    commit) when absent, creates the GitHub repo (`gh repo create --source=.
@@ -1404,7 +1408,7 @@ For Stories already in flight, use one of the three options above.
 
 | Command                                          | Purpose                                                                                                                                                                      |
 | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `npx create-mandrel`                             | Cold-start launcher — install `mandrel`, `mandrel sync`, then run `bootstrap.js` (provisions repo + Projects V2 board, labels, branch protection).                  |
+| `npx mandrel init`                               | Cold-start command — install `mandrel` (if absent), `mandrel sync`, then prompt to run `bootstrap.js` (provisions repo + Projects V2 board, labels, branch protection).        |
 | `/onboard`                                       | Guided first run after bootstrap — stack detection, docs scaffolding, `mandrel doctor` readiness gate, started `/epic-plan` handoff.                                          |
 | `/epic-plan`                                     | Ideation entry — sharpen idea, search duplicates, open Epic, then PRD + Tech Spec + decomposition.                                                                            |
 | `/epic-plan --idea "<seed>"`                     | Same ideation entry with pre-supplied seed.                                                                                                                                   |

package/.agents/docs/workflows.md

@@ -25,7 +25,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (28)
+## Commands (29)
 
 | Command | Description |
 | --- | --- |
@@ -34,6 +34,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
 | `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
+| `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
 | `/audit-lighthouse` | Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report |
 | `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |

package/.agents/schemas/audit-rules.json

@@ -73,6 +73,26 @@
       "triggers": { "gates": ["gate4"] },
       "substitutionKeys": []
     },
+    "audit-documentation": {
+      "triggers": {
+        "gates": ["gate1", "gate3"],
+        "keywords": [
+          "documentation",
+          "docs",
+          "readme",
+          "changelog",
+          "runbook",
+          "stale docs"
+        ],
+        "filePatterns": [
+          "**/*.md",
+          "docs/**",
+          ".agents/docs/**",
+          ".agents/workflows/**"
+        ]
+      },
+      "substitutionKeys": []
+    },
     "audit-dependencies": {
       "triggers": {
         "gates": ["gate1", "gate3"],

package/.agents/scripts/acceptance-eval.js

@@ -61,6 +61,7 @@ import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
   decideAcceptanceEval,
+  deriveAcceptanceEvalRound,
 } from './lib/orchestration/acceptance-eval-decision.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -152,17 +153,33 @@ function parseCliArgs(argv) {
  * @param {object} args.verdict — validated verdict object.
  * @param {object} args.config — resolved `.agentrc.json`.
  * @param {boolean} args.emitSignal
+ * @param {number} [args.round] — explicit round override (tests). When
+ *   absent, the round is derived by counting prior `acceptance-eval`
+ *   signals in the Story's `signals.ndjson` (Story #4019); the verdict's
+ *   self-reported `round` is never load-bearing for the cap.
  * @param {object} [deps]
  * @param {Function} [deps.appendSignalFn]
+ * @param {Function} [deps.deriveRoundFn]
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
-  { storyId, epicId, verdict, config, emitSignal },
+  { storyId, epicId, verdict, config, emitSignal, round },
   deps = {},
 ) {
-  const { appendSignalFn = appendSignal } = deps;
+  const {
+    appendSignalFn = appendSignal,
+    deriveRoundFn = deriveAcceptanceEvalRound,
+  } = deps;
   const { maxRounds } = getAcceptanceEval(config);
-  const outcome = decideAcceptanceEval({ verdict, maxRounds });
+  const resolvedRound =
+    Number.isInteger(round) && round >= 1
+      ? round
+      : deriveRoundFn({ epicId: epicId ?? null, storyId, config });
+  const outcome = decideAcceptanceEval({
+    verdict,
+    maxRounds,
+    round: resolvedRound,
+  });
 
   let signalEmitted = false;
   if (emitSignal) {

package/.agents/scripts/assert-branch.js

@@ -20,11 +20,9 @@
  */
 
 import { fileURLToPath } from 'node:url';
-
-import { PROJECT_ROOT } from './lib/config-resolver.js';
 import { gitSpawn } from './lib/git-utils.js';
-
 import { Logger } from './lib/Logger.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 export function assertBranch(expected, { cwd = PROJECT_ROOT } = {}) {
   if (!expected || typeof expected !== 'string') {
     return { ok: false, reason: 'missing --expected <branch>' };

package/.agents/scripts/bootstrap.js

@@ -1353,7 +1353,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   // the failure is surfaced, not silently rolled back), but they MUST NOT
   // exit 0. `executeGithubBootstrap` records `report.github.error` instead
   // of throwing; detect it here and exit non-zero with a distinct final
-  // status line so `create-mandrel` and CI see the failure (Story #3898).
+  // status line so `mandrel init` and CI see the failure (Story #3898).
   const githubError = result.state?.report?.github?.error;
   if (githubError) {
     Logger.error(