mandrel 1.68.0 → 1.70.0

package/.agents/workflows/agents-update.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update`
+  npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update`
   (resolve newest published version → install → re-materialize `.agents/` →
   migrate → doctor → surface changelog) as the single mechanical step, then
   walks the operator through the judgment wraparound the CLI deliberately
@@ -15,7 +15,7 @@ description: >-
 > **Upgrade owner.** The mechanical upgrade is owned end to end by the
 > [`mandrel update`](../../lib/cli/update.js) CLI under the npm distribution
 > model (`mandrel`, #3436/#3437). This workflow wraps that CLI: it
-> runs `mandrel update`, then walks the operator through the
+> runs `npx mandrel update`, then walks the operator through the
 > **distribution-agnostic judgment steps** the CLI deliberately does **not**
 > perform — config reconciliation, the Epic #1386 quality-gate installs, the
 > permission-allowlist refresh, the consumer-side changelog reconciliation,
@@ -60,22 +60,105 @@ The upgrade contract:
 > **Persona**: `devops-engineer` · **Skills**:
 > `core/ci-cd-and-automation`, `core/documentation-and-adrs`
 
+**Invocation form.** In a consumer project `mandrel` is a local
+devDependency at `node_modules/.bin/mandrel` and is **not** on `PATH`, so a
+bare `mandrel <subcommand>` fails with `command not found` before any of the
+hardened CLI logic ([`lib/cli/update.js`](../../lib/cli/update.js)) runs.
+Every **runnable** command in this workflow therefore uses the
+`npx mandrel <subcommand>` form, matching [`README.md`](../../README.md).
+Prose that names the CLI as a noun (e.g. "`mandrel update`'s sync step")
+refers to the binary by name, not as a command to type — run it via the form
+Step 0 selects. The exception is a project where `mandrel` is installed
+**globally**: there, the bare form works and Step 0 says so.
+
+## Step 0 — Detect the install state and pick the invocation form
+
+Before running the updater, detect how `mandrel` resolves in this project and
+route to the matching invocation form. Run from the consumer repo root:
+
+```bash
+# 1. Globally installed and on PATH?
+command -v mandrel
+# 2. Installed as a local devDependency?
+ls node_modules/.bin/mandrel 2>/dev/null || npm ls mandrel
+```
+
+Three real states, three routes:
+
+| State                                   | Detection                                                              | Invocation form                                                   |
+| --------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Global install (on `PATH`)**          | `command -v mandrel` prints a path                                     | Bare `mandrel <subcommand>` works.                                |
+| **Local devDependency (not on `PATH`)** | `command -v mandrel` is empty; `node_modules/.bin/mandrel` exists      | Use `npx mandrel <subcommand>` (resolves the local bin).          |
+| **Not installed**                       | `command -v mandrel` empty **and** `node_modules/.bin/mandrel` absent  | Run `npm install -D mandrel` first, then `npx mandrel`.           |
+
+The common consumer case is **local devDependency** — `npx mandrel` is the
+default form the rest of this workflow uses. On a global install you may drop
+the `npx` prefix; on a fresh project, install the package first. The `npx`
+form is harmless on a global install too (it prefers the local bin and falls
+back to a one-off fetch), so when unsure, use `npx mandrel`.
+
+## Step 0.5 — First-run preflight (before any bump)
+
+Before running the updater, run the first-run preflight. It catches three
+day-0 failure modes — **wrong project**, a **dirty git index**, and being
+**offline** — before `npx mandrel update` bumps anything. Run from the
+consumer repo root:
+
+```bash
+node .agents/scripts/agents-update-preflight.js
+```
+
+The preflight runs three checks and prints a JSON envelope
+(`{ ok, blocked, findings[] }`) on stdout plus a human-readable report:
+
+| Check              | Severity            | What it verifies                                                                                                                                                       |
+| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **consumer-shape** | **blocker** (exit 2) | `package.json` lists `mandrel` as a dependency **and** a `.agents/` directory exists. Hard-stops in the framework repo itself or any non-consumer project.             |
+| **dirty-index**    | warn-only           | The git index has no pre-existing staged changes. `mandrel update` leaves the lockfile staged and Step 5 would otherwise sweep unrelated staged files into the commit. |
+| **offline**        | warn-only           | The npm registry is reachable (`npm ping`), so the version probe in Step 1 will not fail with a confusing offline error.                                               |
+
+Severity follows framework preflight conventions (cf.
+[`epic-deliver-preflight.js`](../scripts/epic-deliver-preflight.js), the
+`story-close` preflight): the **consumer-shape** check is a hard stop — the
+script exits `2` and you MUST NOT proceed until it is resolved; **dirty-index**
+and **offline** are warn-only and never block the run.
+
+Routing:
+
+- **Exit 0, `ok: true`** — all checks passed; proceed to Step 1.
+- **Exit 0 with warnings** (`blocked: false`, non-empty `findings[]`) —
+  review the warnings. For **dirty-index**, unstage unrelated changes
+  (`git restore --staged <path>`) so they are not swept into the
+  `chore: update mandrel` commit. For **offline**, restore connectivity
+  before the version probe. Then proceed.
+- **Exit 2, `blocked: true`** — the consumer-shape check failed. Stop. You
+  are not in a Mandrel consumer project (wrong directory, the framework repo
+  itself, or a project that never ran `mandrel sync`). `cd` into the consumer
+  repo, or bootstrap one with `npm install -D mandrel && npx mandrel sync`,
+  then re-run the preflight.
+
+> **Scope.** The preflight is a **workflow-layer** guard; it deliberately
+> lives outside [`lib/cli/update.js`](../../lib/cli/update.js), which stays
+> git-free and side-effect-scoped. It composes cleanly with the Step 0
+> invocation-form detection above — Step 0 picks *how* to call the updater;
+> Step 0.5 verifies it is *safe* to call it at all.
+
 ## Step 1 — Run the updater
 
 Preview first, then apply. From the consumer repo root:
 
 ```bash
-mandrel update --dry-run
-mandrel update
+npx mandrel update --dry-run
+npx mandrel update
 ```
 
-`mandrel update --dry-run` resolves the newest published version and prints
-the ordered step plan (`npm-update → runSync → runMigrations → doctor →
+`npx mandrel update --dry-run` resolves the newest published version and
+prints the ordered step plan (`npm-update → runSync → runMigrations → doctor →
 surface changelog`) without invoking any effectful seam — no dependency bump,
 no sync, no migrations, no doctor, nothing written. Read the planned target
 version before applying.
 
-`mandrel update` (no flags) runs the live cycle:
+`npx mandrel update` (no flags) runs the live cycle:
 
 1. **Resolve target** — the newest published `mandrel` version (via
    the daily freshness cache in `temp/version-check.json`) and the currently
@@ -130,6 +213,86 @@ mandrel update — planned upgrade v1.44.0 → v1.46.0
 Dry run: no files written, no dependency bumped.
 ```
 
+## Step 2.5 — Partial-upgrade recovery (**blocker — resolve before Step 5**)
+
+`mandrel update` runs its post-install phases in order — **install** →
+**sync** → **sync-commands** → **migrate** → **doctor** — and the install
+phase bumps `package.json` / `package-lock.json` and leaves the change
+**staged on disk** *before* any of the later phases run. By deliberate
+design the CLI **never rolls back the install on failure** (the lockfile
+bump is left staged for the operator — see the Out-of-Scope note in
+[`lib/cli/update.js`](../../lib/cli/update.js)). So when a post-install
+phase exits non-zero, you land in a **partially-upgraded state**:
+
+- The lockfile bump to the new version is **already staged**, *and*
+- `.agents/` may be **half-materialized** (sync failed midway), the flat
+  `.claude/commands/` tree may be **out of sync** (sync-commands failed), a
+  version-keyed migration may have **partially applied** (migrate failed), or
+  the post-upgrade state failed validation (doctor failed).
+
+This is the dangerous case the whole workflow exists to guard: the operator
+is now **one `git commit` away** (Step 5) from recording a broken
+half-upgrade as "done". `mandrel update` prints the per-phase manual remedy
+to **stderr**, but a line buried in stderr is easy to scroll past and commit
+right over. **Treat any post-install phase failure as an explicit blocker:
+do not proceed to Step 5 (commit) until the failed phase is recovered and a
+clean re-run reports success.**
+
+When `npx mandrel update` exits non-zero, identify which phase failed (the
+CLI's stderr names it) and run the matching manual remedy from the consumer
+repo root. These commands match the hint strings
+[`lib/cli/update.js`](../../lib/cli/update.js) emits verbatim — it is the
+single source of truth, kept in lockstep with this table by the
+`agents-update-recovery-drift` contract test
+([`tests/bootstrap/agents-update-recovery-drift.test.js`](../../tests/bootstrap/agents-update-recovery-drift.test.js)):
+
+| Failed phase      | Manual remedy                                            |
+| ----------------- | ------------------------------------------------------- |
+| **sync**          | `npx mandrel sync`                                       |
+| **sync-commands** | `npm run sync:commands`                                  |
+| **migrate**       | `npx mandrel migrate --from <cur> --to <target>`        |
+| **doctor**        | `npx mandrel doctor` (then apply the per-check remedies) |
+
+The exact stderr the CLI prints per failed phase — quoted verbatim from
+[`lib/cli/update.js`](../../lib/cli/update.js) so the table above can never
+drift from what the operator actually sees:
+
+- **sync** — the .agents/ materialization may be incomplete. Run `mandrel
+  sync` manually to restore.
+- **sync-commands** — the .claude/commands/ tree may be out of sync. Run `npm
+  run sync:commands` manually to restore.
+- **migrate** — some migrations for v\<cur\> → v\<target\> may not have
+  applied. Run `mandrel migrate --from <cur> --to <target>` manually to retry.
+- **doctor** — upgraded to v\<target\> but doctor reported failures. → Run
+  `mandrel doctor` for remedies.
+
+> **`<cur>` / `<target>`** are the installed and resolved-newest version
+> strings the CLI printed in Step 1 (e.g. `--from 1.44.0 --to 1.46.0`).
+> Substitute the real values the failing run reported.
+
+Recovery sequence:
+
+1. **Run the matching remedy** for the failed phase from the table above.
+2. **Re-run `npx mandrel update`.** It is idempotent — the install already
+   landed, so a clean re-run short-circuits the bump and re-drives the
+   post-install phases. Repeat the per-phase remedy until the run reports
+   `✅  Updated to v<target>. The lockfile bump is staged for review.` (or
+   `✅  Already up to date`).
+3. **Only then proceed** to Step 3. The staged lockfile bump is safe to
+   commit (Step 5) once — and only once — the post-install phases have all
+   gone green.
+
+> **Why not auto-rollback / `mandrel update --resume`?** A `--resume` flag
+> that re-enters the cycle at the failed phase was **evaluated and
+> deferred** (Story #4172, Out of Scope). The per-phase manual remedies
+> above fully cover recovery: each failed phase has an exact, idempotent
+> command, and re-running `npx mandrel update` already short-circuits the
+> completed install and re-drives the remaining phases — so a dedicated
+> resume entrypoint would add a parallel code path without covering any
+> recovery case the manual remedies miss. If a future change makes the
+> phases expensive enough that re-driving completed ones is wasteful,
+> revisit `--resume` then; today it is unnecessary.
+
 ## Step 3 — Reconcile `.agentrc.json` against the new defaults
 
 A framework bump can add or reshape fields in
@@ -177,22 +340,18 @@ framework version sees `no-change` everywhere here.
 Run from the consumer repo root:
 
 ```bash
-node -e "
-  Promise.all([
-    import('./.agents/scripts/lib/bootstrap/quality-bootstrap.js'),
-    import('./.agents/scripts/lib/bootstrap/baselines-layout-migration.js'),
-  ]).then(([qb, bm]) => {
-    const root = process.cwd();
-    const quality = qb.applyQualityBootstrap({ projectRoot: root });
-    const baselines = bm.migrateBaselinesLayout({
-      baselinesDir: require('node:path').join(root, 'baselines'),
-      repoRoot: root,
-    });
-    console.log(JSON.stringify({ quality, baselines }, null, 2));
-  });
-"
+node .agents/scripts/apply-quality-bootstrap.js
 ```
 
+The script (Story #4171) replaced the prior inline `node -e` heredoc — a
+shell-fragile, untested block that silently drifted whenever the two helper
+signatures moved (see
+[`apply-quality-bootstrap.js`](../scripts/apply-quality-bootstrap.js)). It
+runs the same two installs in order against `process.cwd()` —
+`applyQualityBootstrap` then `migrateBaselinesLayout` — and prints the same
+`{ quality, baselines }` JSON envelope to stdout. It is idempotent: a second
+run is a no-op beyond reporting `no-change` on every install path.
+
 The four `quality-bootstrap` outcomes:
 
 1. **`helper`** — copies
@@ -329,6 +488,14 @@ response."
 
 ## Step 5 — Commit the bump
 
+> **Blocker check before you commit.** The staged lockfile bump is only safe
+> to commit once every post-install phase has gone green. If `npx mandrel
+> update` exited non-zero, you are in a partially-upgraded state — resolve it
+> via [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5)
+> (run the per-phase remedy, re-run the updater to success) **before** running
+> the `git commit` below. Committing over a half-upgrade records a broken
+> state as "done".
+
 `mandrel update` leaves the dependency bump **staged on disk** but never
 commits. After reviewing the surfaced changelog, any `.agentrc.json`
 reconciliation diff from Step 3, the `.claude/settings.json` allowlist
@@ -359,7 +526,7 @@ no-op.
 > distribution `.agents/` is a
 > materialized directory rebuilt from the installed package — whether the
 > consumer commits the regenerated `.agents/` tree, or treats it as a
-> gitignored install artifact rebuilt by `mandrel sync`, depends on the
+> gitignored install artifact rebuilt by `npx mandrel sync`, depends on the
 > consumer's own vendoring policy. Stage the `.agents/` / `.claude/`
 > changes here only if the project commits its materialized tree.
 
@@ -367,21 +534,31 @@ no-op.
 
 - **`doctor reported failures: …`** — the dependency bumped and `.agents/`
   re-materialized, but a doctor check failed (and the run exited
-  non-zero). Run `mandrel doctor` for the per-check remedies. The lockfile
-  bump is already staged; fix the doctor finding (often a missing
-  bootstrap install — Step 3.5 — or a stale `.agentrc.json` — Step 3)
-  before committing in Step 5.
+  non-zero). This is one shape of the **partial-upgrade** failure mode —
+  the lockfile bump is already staged, so it is a **blocker** you MUST
+  resolve before the commit step (see
+  [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5)).
+  Run `npx mandrel doctor` for the per-check remedies; fix the doctor
+  finding (often a missing bootstrap install — Step 3.5 — or a stale
+  `.agentrc.json` — Step 3), re-run `npx mandrel update` until it reports
+  success, and only then commit in Step 5.
+
+- **A post-install phase failed (`sync` / `sync-commands` / `migrate`)** —
+  the install bumped the lockfile but a later phase exited non-zero, leaving
+  a partially-upgraded tree. Do not commit. Run the matching per-phase
+  remedy and re-run the updater per
+  [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5).
 
 - **Install command failed / `npm install … exited <n>`** — the npm
   install step could not bump the dependency (network hiccup, registry
   auth gap, or a peer-dependency conflict). Resolve the underlying npm
-  error and re-run `mandrel update`; it is idempotent — a clean re-run
+  error and re-run `npx mandrel update`; it is idempotent — a clean re-run
   resumes from the resolve step and short-circuits if the install already
   landed.
 
 - **Wrong package manager** — the default install is `npm install`. For a
   pnpm or yarn workspace, pass the package manager explicitly:
-  `mandrel update --install-cmd "pnpm add mandrel@<target>"`.
+  `npx mandrel update --install-cmd "pnpm add mandrel@<target>"`.
   The registry probe always stays on `npm view` (a PM-agnostic query); only
   the install seam honours the override.
 

package/.agents/workflows/deliver.md

@@ -21,8 +21,8 @@ path selection only — all phase content lives in the two path helpers:
   close-validation, epic-audit, code-review, retro, finalize, watch,
   auto-merge gate, cleanup).
 - [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the
-  standalone multi-Story path (`stories-wave-tick.js` wave plan, operator
-  confirmation, parallel fan-out to
+  standalone multi-Story path (`stories-wave-tick.js` continuous ready-set
+  loop, operator confirmation, parallel fan-out to
   [`helpers/single-story-deliver`](helpers/single-story-deliver.md)).
 
 ## Input matrix (authoritative)
@@ -100,13 +100,16 @@ plans).
 /deliver <id> <id> … --dep <from>:<to> --concurrency <n> --yes
 ```
 
-behaves exactly as the retired multi-Story command did: the same
-`stories-wave-tick.js` wave plan, the same operator confirmation gate
-(suppressed by `--yes`), and the same parallel fan-out — one Agent call per
-Story per wave, capped by the resolved `concurrencyCap` — to
-[`helpers/single-story-deliver`](helpers/single-story-deliver.md). The
-parallelism lives **inside** the standalone segment; segments themselves
-remain strictly sequential.
+preserves the retired multi-Story command's full surface — the same flags,
+the same operator confirmation gate (suppressed by `--yes`), and the same
+parallel fan-out to
+[`helpers/single-story-deliver`](helpers/single-story-deliver.md) — but
+schedules through `stories-wave-tick.js`'s **continuous ready-set loop**
+(the shared `selectReadySet` core) rather than a static wave plan: each
+Story dispatches the instant its own dependencies are done, capped by the
+resolved global `concurrencyCap` and guarded against file-overlap
+co-dispatch, exactly as the Epic path is. The parallelism lives **inside**
+the standalone segment; segments themselves remain strictly sequential.
 
 ## Procedure