mandrel 1.59.0 → 1.61.0

package/.agents/README.md

@@ -4,10 +4,10 @@ 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 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).
+`/plan` and `/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.
+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 → 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.
@@ -42,9 +42,9 @@ 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.
 
-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.
+After it completes, `mandrel init` runs the onboarding tail automatically —
+stack detection, docs scaffolding offer, a `mandrel doctor` readiness gate,
+and a printed `/plan` handoff — so you land at planning in one command.
 
 ### Manual Install
 
@@ -112,7 +112,7 @@ 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`,
+`mandrel` to the newest published version, re-runs `mandrel sync`,
 applies version-keyed migrations, and verifies the install with
 `mandrel doctor`. The lockfile bump is left **staged for you to review and
 commit** (the command performs no `git` mutation):
@@ -122,12 +122,9 @@ npx mandrel update           # update → sync → migrate → doctor
 npx mandrel update --dry-run # preview the target version + ordered steps
 ```
 
-A **major** crossing (e.g. `1.x → 2.0`) is **gated**: Mandrel lives on the
-1.x line under release-please `always-bump-minor`, so a major is a deliberate
-operator decision. `mandrel update` refuses a major bump, points at the
-[`docs/upgrade-major.md`](../docs/upgrade-major.md) runbook, and exits
-without touching anything — re-run with `--major` to adopt it. Minor and
-patch bumps are never gated. Migrations can also be run on their own:
+Major crossings are applied like any other bump — Mandrel ships hard
+cutovers, so the release notes in the surfaced changelog are the migration
+guide. Migrations can also be run on their own:
 
 ```bash
 npx mandrel migrate --from <version> --to <version> [--dry-run]
@@ -143,6 +140,61 @@ workflow fragments there rather than editing synced files in place.
 
 ---
 
+## CLI subcommand reference
+
+Run `mandrel --help` for a subcommand list. Each subcommand supports
+`--dry-run` (where noted) to preview without writing.
+
+| Subcommand | Purpose | Key flags |
+| ---------- | ------- | --------- |
+| `init` | Install + configure mandrel in the current project (cold-start). | `--assume-yes`, `--skip-github`, `--dry-run` |
+| `sync` | Re-materialize `.agents/` from the installed package payload. | `--dry-run` |
+| `sync-commands` | Regenerate `.claude/commands/` from `.agents/workflows/`. | — |
+| `doctor` | Run readiness checks and print per-check remedies. | — |
+| `update` | Upgrade mandrel to the newest published version. | `--dry-run`, `--install-cmd` |
+| `migrate` | Apply version-keyed migrations for a version range. | `--from`, `--to`, `--dry-run` |
+| `explain` | Print resolved config values with their sources. | `--json` |
+| `uninstall` | Reverse a recorded install using the install ledger. | `--include-github`, `--dry-run` |
+
+### `mandrel explain`
+
+Prints every resolved `.agentrc.json` config key — its effective value, the
+source layer it came from (`[agentrc]` or `[default]`), and a one-line
+meaning. Secret-shaped keys are redacted. Useful for debugging unexpected
+behavior when multiple config sources overlap.
+
+```bash
+mandrel explain            # human-readable config report
+mandrel explain --json     # same report as JSON
+```
+
+### `mandrel sync-commands`
+
+Regenerates the flat `.claude/commands/` projection from `.agents/workflows/`.
+The bootstrap wires a `UserPromptSubmit` hook that runs this automatically on
+every Claude Code prompt submission, so manual runs are rarely needed.
+
+```bash
+mandrel sync-commands      # rebuild .claude/commands/
+```
+
+### `mandrel uninstall`
+
+Reverses a recorded install using the install ledger
+(`.agents/.install-manifest.json`). Each ledger entry is a
+mutation-manifest record; uninstall walks reversible entries and undoes
+exactly what the install applied, without touching pre-existing operator
+content. GitHub-side state (labels, branch protection, Projects board)
+requires manual reversal and is surfaced as a follow-up checklist.
+
+```bash
+mandrel uninstall                      # reverse all local install mutations
+mandrel uninstall --dry-run            # preview what would be reversed
+mandrel uninstall --include-github     # acknowledge GitHub-side manual steps
+```
+
+---
+
 ## Automatic system-prompt wiring
 
 The bootstrap wires the framework system prompt into a project-root
@@ -187,11 +239,11 @@ For non-interactive (CI) installs, pass `--owner`, `--repo`, and
 After bootstrap, every Mandrel command is generated into a flat
 `.claude/commands/` tree by `npm run sync:commands` (the UserPromptSubmit hook
 keeps it current) and loads as a bare `/<command>` slash command — e.g.
-`/epic-plan`, `/story-plan`, `/story-deliver`, `/audit-security`. The
+`/plan`, `/plan`, `/deliver`, `/audit-security`. The
 commands load in every Claude Code environment. The [SDLC guide](docs/SDLC.md) walks
 an end-to-end Epic; standalone Stories pair
-[`/story-plan`](workflows/story-plan.md) (idea → drafted Story
-Issue) with [`/story-deliver`](workflows/story-deliver.md) (Story Issue → merged
+[`/plan`](workflows/helpers/plan-story.md) (idea → drafted Story
+Issue) with [`/deliver`](workflows/helpers/deliver-stories.md) (Story Issue → merged
 PR).
 
 ---
@@ -209,9 +261,10 @@ a single vendored manifest that ships inside the bundle:
 - **[`runtime-deps.json`](runtime-deps.json)** — the single source of
   truth. Its `dependencies` block lists the **required** packages (`ajv`,
   `ajv-formats`, `js-yaml`, `minimatch`, `picomatch`, `string-argv`,
-  `typescript`, `typhonjs-escomplex`); its `optionalDependencies` block
-  lists packages used only behind graceful-degradation paths (`chokidar`
-  for `quality:watch`, `@commitlint/load` for commit-subject sizing).
+  `typhonjs-escomplex`); its `optionalDependencies` block lists packages
+  used behind graceful-degradation paths (`typescript` for TS-source
+  scoring in the maintainability engine, `chokidar` for `quality:watch`,
+  `@commitlint/load` for commit-subject sizing).
 
 **How a consumer satisfies them:** `bootstrap` (above) merges the required
 set into your `package.json` `dependencies` and runs your package manager's
@@ -233,7 +286,7 @@ in `runtime-deps.json`.
 
 ## Ticket Hierarchy
 
-Mandrel uses a **3-tier hierarchy**, (Epic → Feature → Story) with inline `acceptance[]` / `verify[]` on story bodies.
+Mandrel uses a **2-tier hierarchy** (Epic → Story) with inline `acceptance[]` / `verify[]` on story bodies.
 
 See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execution-model implications.
 
@@ -244,7 +297,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | Path | Purpose |
 | ---- | ------- |
 | [`instructions.md`](instructions.md) | Primary system prompt loaded by the host AI tool. |
-| [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/epic-plan` and `/epic-deliver`. |
+| [`docs/SDLC.md`](docs/SDLC.md) | Operator process for `/plan` and `/deliver`. |
 | [`starter-agentrc.json`](starter-agentrc.json) | Bootstrap delta-seed copied to the consumer repo root as `.agentrc.json`. |
 | [`agentrc-reference.json`](docs/agentrc-reference.json) | Exhaustive editor reference enumerating every schema key with its framework default. |
 | [`personas/`](personas/) | Role-specific behavior packs selected by task persona or explicit user instruction. |
@@ -268,7 +321,7 @@ See [`docs/SDLC.md` § Ticket hierarchy](docs/SDLC.md) for the diagram and execu
 | The Epic planning and delivery process | [`docs/SDLC.md`](docs/SDLC.md) |
 | The system prompt loaded by your AI tool | [`instructions.md`](instructions.md) |
 | Every `.agentrc.json` key, default, and override | [`docs/configuration.md`](docs/configuration.md) (under `.agents/`) |
-| Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`docs/quality-gates.md`](../docs/quality-gates.md) |
+| Quality-gate runbooks (CRAP, MI, lint, friction) plus the baseline envelope, component model, and writer/reader contract | [`.agents/docs/quality-gates.md`](docs/quality-gates.md) |
 | Slash-command workflow definitions | [`workflows/`](workflows/) |
 | Render the signals span-tree (debug helper) | [`workflows/helpers/signals.md`](workflows/helpers/signals.md) |
 | Persona behavior packs | [`personas/`](personas/) |
@@ -445,7 +498,7 @@ sessions, `gh auth login` is sufficient.
 ## Self-Healing Checks
 
 `scripts/lib/checks/` is the discovery-based registry of named checks
-consumed by preflight guards (`/epic-deliver`, `/story-close`, `npm test`),
+consumed by preflight guards (`/deliver`, `/story-close`, `npm test`),
 the `diagnose.js` ad-hoc viewer, and the retro surface. Use one check per
 file. The runner (`index.js`) loads checks at process start and filters by
 scope at each call site.
@@ -504,8 +557,8 @@ envelope, every gate reads through one shared module
 and every refresher writes through one shared writer
 ([`.agents/scripts/lib/baselines/writer.js`](scripts/lib/baselines/writer.js)).
 
-See the [Baseline reference](../docs/quality-gates.md#baseline-reference)
-section of `docs/quality-gates.md` for the full reference: envelope shape,
+See the [Baseline reference](docs/quality-gates.md#baseline-reference)
+section of `.agents/docs/quality-gates.md` for the full reference: envelope shape,
 per-kind axes, component model, path canonicalisation, writer/reader
 contract, kernel-version friction, and — most relevant to consumers — the
 **floor override** path. Consumers add a `floors` block
@@ -569,7 +622,7 @@ Schema conventions:
 ## Code review providers (pluggable chain)
 
 `runCodeReview()` (invoked at the end of `helpers/epic-deliver-story`,
-`helpers/single-story-deliver`, and `/epic-deliver`'s `delivery.code-review`
+`helpers/single-story-deliver`, and `/deliver`'s `delivery.code-review`
 state) loads its review backend through a pluggable registry. Two configuration shapes are supported:
 
 - **Legacy single provider** — `delivery.codeReview.provider: "native"`
@@ -721,7 +774,7 @@ falls from minutes to under a second.
 ## Multi-developer coordination
 
 Two operators can drive the same repository at once — one running
-`/epic-deliver <id>`, another running `/single-story-deliver <id>`, or two
+`/deliver <id>`, another running `/single-story-deliver <id>`, or two
 operators on the same Epic from separate clones. The framework keeps those
 runs from clobbering one another with **two distinct coordination layers**.
 They solve different problems and must not be confused:
@@ -763,7 +816,7 @@ yanks the claim back from whoever legitimately took over.
 
 **Where it's wired:**
 
-- **`/epic-deliver`** acquires the lease on the **Epic** ticket during its
+- **`/deliver`** acquires the lease on the **Epic** ticket during its
   prepare phase, before any mutating git work
   ([`epic-deliver-lease-guard.js`](scripts/lib/orchestration/epic-deliver-lease-guard.js)).
   A live foreign claim refuses the run; pass `--steal` to override and
@@ -776,7 +829,7 @@ yanks the claim back from whoever legitimately took over.
   ([`single-story-lease-guard.js`](scripts/lib/orchestration/single-story-lease-guard.js)).
   The standalone path requires `github.operatorHandle` to be set — without
   an operator identity the lease has no owner to record.
-- **`/epic-plan`** acquires the lease on the **Epic** ticket before Phase 7
+- **`/plan`** acquires the lease on the **Epic** ticket before Phase 7
   (spec) and releases it after Phase 8 (decompose)
   ([`epic-plan-lease-guard.js`](scripts/lib/orchestration/epic-plan-lease-guard.js)).
   Because planning emits no `story.heartbeat` (heartbeats are a
@@ -790,22 +843,11 @@ yanks the claim back from whoever legitimately took over.
 
 ## Root config vs distributed templates
 
-Three `.agentrc`-shaped files live in this repository and are easy to
-confuse:
-
-| File                              | Audience                          | Role                                                                                                                              |
-| --------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `.agentrc.json` (repo root)       | The framework dogfooding itself   | Live config used when running `/epic-*`, `/story-deliver` against this repo. Exercises the framework end-to-end. |
-| `.agents/starter-agentrc.json`    | Downstream consumer repos         | Bootstrap delta-seed a consumer copies via `cp .agents/starter-agentrc.json .agentrc.json`. Minimum schema-required keys.        |
-| `.agents/docs/agentrc-reference.json`       | Operators and reviewers           | Exhaustive editor reference enumerating every schema key with its framework default. Not a copy target.                          |
-
-The three files share a schema; where they legitimately diverge (target
-dirs, repo identifiers, version-file pointer) is documented in
-[`docs/configuration.md` § Root dogfood vs distributed template](docs/configuration.md#root-dogfood-vs-distributed-template).
-Edit `agentrc-reference.json` when a framework default changes; edit
-`starter-agentrc.json` only when the bootstrap seed itself needs new
-schema-required keys; edit the root `.agentrc.json` for changes that
-only affect this repo's own dogfood runs.
+Three `.agentrc`-shaped files live in this repository and serve different
+audiences. Their roles, audiences, and the keys where they legitimately
+diverge are documented in
+[`docs/configuration.md` § Root dogfood vs distributed templates](docs/configuration.md#root-dogfood-vs-distributed-templates)
+— that section is the canonical single home for this table.
 
 ---