mandrel 1.60.0 → 1.61.0

package/.agents/README.md

@@ -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 `/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
@@ -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
@@ -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/) |
@@ -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
@@ -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-*`, `/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.
 
 ---
 

package/.agents/docs/SDLC.md

@@ -225,9 +225,7 @@ graph LR
 
     subgraph Phase0 ["Phase 0: Bootstrap"]
         direction TB
-        Z["👤 npx mandrel init<br/>(install → sync → prompt → bootstrap.js)"]:::manual
-        Z2["👤 /onboard (guided first run)"]:::manual
-        Z --> Z2
+        Z["👤 npx mandrel init<br/>(install → sync → prompt → bootstrap.js → onboarding tail → /plan handoff)"]:::manual
     end
 
     subgraph Phase1 ["Phase 1: Initiation"]
@@ -257,7 +255,7 @@ graph LR
         H["🤖 Auto-merge armed → PR lands when checks pass<br/>(👤 operator may disarm to merge manually)"]:::agentic
     end
 
-    Z2 --> A
+    Z --> A
     A --> C
     D --> E
     G --> H
@@ -304,9 +302,11 @@ files-only so the GitHub provisioning never runs unattended. `bootstrap.js`:
    promotion gate.
 
 When `.agents/` is already materialized you can run the bootstrap directly
-(`node .agents/scripts/bootstrap.js`). After bootstrap, run **`/onboard`**
-inside Claude Code for the guided first run — stack detection, docs
-scaffolding, a `mandrel doctor` readiness gate, and a started `/plan`.
+(`node .agents/scripts/bootstrap.js`). The guided first-run steps (stack
+detection, docs scaffolding, `mandrel doctor` readiness gate, and `/plan`
+handoff) are now part of `mandrel init`'s configure path — run
+`mandrel init` again to pick them up if you bootstrapped via the script
+directly.
 
 > [!NOTE] Bootstrap runs once per repository. It is safe to re-run — existing
 > labels, fields, and branch-protection entries are preserved; missing ones
@@ -1403,8 +1403,7 @@ For Stories already in flight, use one of the three options above.
 
 | Command                                          | Purpose                                                                                                                                                                      |
 | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 `/plan` handoff.                                          |
+| `npx mandrel init`                               | Cold-start command — install `mandrel` (if absent), `mandrel sync`, bootstrap.js (provisions repo + Projects V2 board, labels, branch protection), then onboarding tail (stack detection, docs scaffolding, doctor gate, `/plan` handoff). |
 | `/plan`                                     | Ideation entry — sharpen idea, search duplicates, open Epic, then PRD + Tech Spec + decomposition.                                                                            |
 | `/plan --idea "<seed>"`                     | Same ideation entry with pre-supplied seed.                                                                                                                                   |
 | `/plan <epicId>`                            | Existing-Epic mode — PRD + Tech Spec + decomposition for an Epic Issue already opened.                                                                                       |

package/.agents/docs/configuration.md

@@ -376,7 +376,7 @@ branch protection on the base branch.
 
 | Field            | Required | Default | Purpose                                                                 |
 | ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
-| `enforce`        | No       | `true`  | When `true`, `node .agents/scripts/bootstrap.js` calls `ensureMainBranchProtection(...)`. |
+| `enforce`        | No       | `true`  | When `true`, `node .agents/scripts/bootstrap.js` calls `applyBranchProtection(...)`. |
 | `requiredChecks` | No       | `[]`    | Array of `{ name, cmd[] }` entries used both as required-status-check expectations on the PR and as local close-validation gate invocations. |
 
 Each `requiredChecks` entry takes the shape:
@@ -770,14 +770,14 @@ the lint ratchet, and the CRAP/MI gates.
 
 | File                              | Owner                                | Refresh                                                                |
 | --------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
-| `baselines/lint.json`             | `lint-baseline.js`                   | `node .agents/scripts/lint-baseline.js --refresh`                       |
+| `baselines/lint.json`             | `lint-baseline.js`                   | `node .agents/scripts/lint-baseline.js capture`                       |
 | `baselines/crap.json`             | `update-crap-baseline.js`            | `npm run crap:update`                                                   |
 | `baselines/maintainability.json`  | `update-maintainability-baseline.js` | `npm run maintainability:update`                                        |
 
 These files are the contract. They are read by every gate (Story close, push
 hook, CI) and are regenerated only via tagged `baseline-refresh:` commits
 with a non-empty body. The convention is operator-enforced; see the CRAP
-section of [`docs/quality-gates.md`](../../docs/quality-gates.md) for the policy.
+section of [`quality-gates.md`](quality-gates.md) for the policy.
 
 Paths are configured in `delivery.quality.gates.<tier>.baselinePath`. The
 default values match the canonical layout above; override only when a
@@ -1024,6 +1024,63 @@ move and the allowlist response in the same diff.
 
 ---
 
+## CLI subcommand quick-reference
+
+`mandrel --help` prints the full subcommand list. Each subcommand that
+mutates state supports `--dry-run` to preview without writing. The table
+below covers every dispatch-visible subcommand:
+
+| Subcommand | What it does | Key flags |
+| ---------- | ------------ | --------- |
+| `init` | Install and configure mandrel in the current project. | `--assume-yes`, `--skip-github`, `--dry-run` |
+| `sync` | Re-materialize `.agents/` from the installed package payload. | `--dry-run`, `--force` |
+| `sync-commands` | Rebuild `.claude/commands/` from `.agents/workflows/`. | — |
+| `doctor` | Run readiness checks and report 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 sources. | `--json` |
+| `uninstall` | Reverse a recorded install using the install ledger. | `--include-github`, `--dry-run` |
+
+### `mandrel explain`
+
+Prints every resolved config key — its effective value, its source layer
+(`[agentrc]` or `[default]`), and a one-line description. Secret-shaped
+values are shown as `<redacted>`. Useful when debugging unexpected behavior
+caused by config layering.
+
+```bash
+mandrel explain          # human-readable report
+mandrel explain --json   # JSON report for scripting
+```
+
+### `mandrel sync-commands`
+
+Regenerates the flat `.claude/commands/` tree from `.agents/workflows/`. The
+bootstrap wires a `UserPromptSubmit` hook so this runs automatically on every
+Claude Code prompt; manual invocations are only needed when the hook is absent
+or the commands/ tree is manually deleted.
+
+```bash
+mandrel sync-commands
+```
+
+### `mandrel uninstall`
+
+Reverses a recorded install using the install ledger
+(`.agents/.install-manifest.json`). Restoration is marker-based and
+non-destructive: operator-authored content that pre-existed the install
+is preserved; only install-created files and framework additions are removed.
+GitHub-side state is never acted on automatically; it is surfaced as a
+manual checklist.
+
+```bash
+mandrel uninstall                  # reverse all local mutations
+mandrel uninstall --dry-run        # preview without writing
+mandrel uninstall --include-github # acknowledge GitHub-side follow-ups
+```
+
+---
+
 ## Cross-references
 
 - JSON Schema mirror —
@@ -1035,6 +1092,6 @@ move and the allowlist response in the same diff.
 - Bootstrap script —
   [`bootstrap.js`](../scripts/bootstrap.js)
 - Quality gates runbook (CRAP onboarding, MI ratchet, lint ratchet) —
-  [`docs/quality-gates.md`](../../docs/quality-gates.md)
+  [`quality-gates.md`](quality-gates.md)
 - Activation pointers (slash commands, personas, skills) —
   [`.agents/README.md`](../README.md)