mandrel 1.69.0 → 1.70.0

package/.agents/scripts/lib/workers/combined-mi-crap-worker.js

@@ -0,0 +1,226 @@
+/**
+ * lib/workers/combined-mi-crap-worker.js — CPU-pool worker entry for the
+ * combined MI + CRAP single-pass scan (`scanAndScoreCombined`).
+ *
+ * One file in, BOTH the maintainability score and the per-method CRAP rows
+ * out — derived from a SINGLE `escomplex.analyzeModule` parse via
+ * `analyzeOnce`. This collapses the two independent worker-pool passes the
+ * full-tree baseline regenerator used to run (the MI worker parsed the AST
+ * once for the module score, the CRAP worker parsed the same file's AST
+ * again for the method rows) into one parse per file.
+ *
+ * The MI score and the CRAP rows have independent skip policies, mirroring
+ * the two separate passes this worker replaces:
+ *   - **MI** never requires coverage. The module score is emitted for every
+ *     file that reads + transpiles + parses. A read failure yields
+ *     `miScore: null` (the host drops the file from the MI map, matching
+ *     `calculateAll`'s `score === null` filter). A transpile failure or a
+ *     parse error yields `miScore: 0` (matching `calculateForFile` /
+ *     `calculateForSource`, which return 0 on transpile-null / parse-error).
+ *   - **CRAP** honours `requireCoverage`. A file with no coverage entry is
+ *     reported as `skippedFileNoCoverage: true` (the host increments its own
+ *     counter and emits no CRAP rows for it) — but the MI score is STILL
+ *     computed and returned, because the MI pass would have scored it.
+ *
+ * Message contract — see lib/cpu-pool.js:
+ *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
+ *                   coverageEntry: object | null } }
+ *         { exit: true }
+ *   OUT : { ok: true, result: {
+ *           relPath,
+ *           miScore: number | null,
+ *           skippedFileNoCoverage: boolean,
+ *           crapRows: Array<{ method, startLine, cyclomatic, coverage, crap }> | null,
+ *           skippedMethodsNoCoverage: number,
+ *         } }
+ *
+ * A read/transpile/parse failure surfaces as `crapRows: null` so the host
+ * loop drops the file's CRAP contribution (matching the crap-worker's
+ * `rows: null` contract) — never aborts the whole scan. On a read failure
+ * `miScore` is `null`; on a transpile/parse failure `miScore` is `0`.
+ */
+
+import fs from 'node:fs';
+import { parentPort } from 'node:worker_threads';
+import { analyzeOnce } from '../crap-utils.js';
+import { transpileIfNeeded } from '../transpile.js';
+
+/**
+ * Pure handler for a single inbound worker message. Exported so unit tests
+ * can exercise every branch (bad-shape rejection, coverage gate, read /
+ * transpile / parse failures, success rows, skipped methods, and the
+ * MI-computed-even-when-coverage-skipped invariant) without spawning a real
+ * `Worker` thread.
+ *
+ * Side effects (fs, transpile, analyzeOnce) are wired through `deps` so
+ * tests pass deterministic stubs.
+ *
+ * @param {unknown} msg
+ * @param {{
+ *   readFile?: (abs: string) => string,
+ *   transpile?: (abs: string, source: string) => string | null,
+ *   analyze?: (source: string, entry: object|null) => {
+ *     miScore: number,
+ *     crapRows: Array<object>,
+ *     parseError: boolean,
+ *   },
+ * }} [deps]
+ * @returns {{kind: 'exit'} | {kind: 'reply', message: object}}
+ */
+export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
+  if (msg && msg.exit === true) return { kind: 'exit' };
+
+  const item = msg?.item;
+  if (
+    !item ||
+    typeof item.abs !== 'string' ||
+    typeof item.relPath !== 'string'
+  ) {
+    return {
+      kind: 'reply',
+      message: {
+        ok: false,
+        error: `bad worker message: ${JSON.stringify(msg)}`,
+      },
+    };
+  }
+  const { abs, relPath, requireCoverage } = item;
+  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const transpile = deps.transpile ?? transpileIfNeeded;
+  const analyze = deps.analyze ?? analyzeOnce;
+
+  // Coverage entry is pre-resolved on the host and attached to the item.
+  // `item.coverageEntry` may be explicitly `null` when the file has no
+  // coverage, or `undefined` when the caller did not supply it (treat as null).
+  const entry = item.coverageEntry ?? null;
+
+  // Read the source once. A read failure means neither MI nor CRAP can be
+  // computed — MI drops (null), CRAP drops (rows null) — matching the two
+  // passes' read-failure contracts (calculateAll → score null; crap worker
+  // → rows null).
+  let source;
+  try {
+    source = readFile(abs);
+  } catch {
+    return {
+      kind: 'reply',
+      message: {
+        ok: true,
+        result: {
+          relPath,
+          miScore: null,
+          skippedFileNoCoverage: false,
+          crapRows: null,
+          skippedMethodsNoCoverage: 0,
+        },
+      },
+    };
+  }
+
+  // TS/TSX → strip-then-analyze. A transpile failure yields miScore 0
+  // (calculateForFile returns 0 when transpileIfNeeded returns null) and a
+  // null CRAP contribution (crap worker returns rows: null).
+  const prepared = transpile(abs, source);
+  if (prepared === null) {
+    return {
+      kind: 'reply',
+      message: {
+        ok: true,
+        result: {
+          relPath,
+          miScore: 0,
+          skippedFileNoCoverage: false,
+          crapRows: null,
+          skippedMethodsNoCoverage: 0,
+        },
+      },
+    };
+  }
+
+  // ONE parse: analyzeOnce derives both the module MI score and the raw
+  // per-method CRAP rows from a single escomplex report. On a parse error it
+  // returns miScore 0 and an empty crapRows with parseError true.
+  const {
+    miScore,
+    crapRows: rawCrapRows,
+    parseError,
+  } = analyze(prepared, entry);
+  if (parseError) {
+    // Parse error: MI scores 0 (parity with calculateForSource's catch →
+    // returns 0), CRAP drops the file (rows null, parity with the crap
+    // worker's calculateCrap-throw branch).
+    return {
+      kind: 'reply',
+      message: {
+        ok: true,
+        result: {
+          relPath,
+          miScore: 0,
+          skippedFileNoCoverage: false,
+          crapRows: null,
+          skippedMethodsNoCoverage: 0,
+        },
+      },
+    };
+  }
+
+  // CRAP coverage gate runs AFTER the parse so the MI score is always
+  // available. When the file has no coverage under requireCoverage, the CRAP
+  // pass would have skipped it at the file level (no rows, counted) — but the
+  // MI pass would still have scored it, so miScore is returned regardless.
+  if (requireCoverage && entry === null) {
+    return {
+      kind: 'reply',
+      message: {
+        ok: true,
+        result: {
+          relPath,
+          miScore,
+          skippedFileNoCoverage: true,
+          crapRows: [],
+          skippedMethodsNoCoverage: 0,
+        },
+      },
+    };
+  }
+
+  const crapRows = [];
+  let skippedMethodsNoCoverage = 0;
+  for (const mr of rawCrapRows) {
+    if (mr.crap === null || mr.coverage === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    crapRows.push({
+      method: mr.method,
+      startLine: mr.startLine,
+      cyclomatic: mr.cyclomatic,
+      coverage: mr.coverage,
+      crap: mr.crap,
+    });
+  }
+  return {
+    kind: 'reply',
+    message: {
+      ok: true,
+      result: {
+        relPath,
+        miScore,
+        skippedFileNoCoverage: false,
+        crapRows,
+        skippedMethodsNoCoverage,
+      },
+    },
+  };
+}
+
+if (parentPort) {
+  parentPort.on('message', (msg) => {
+    const out = handleCombinedMiCrapWorkerMessage(msg);
+    if (out.kind === 'exit') {
+      parentPort.close();
+      return;
+    }
+    parentPort.postMessage(out.message);
+  });
+}

package/.agents/scripts/providers/github/issues.js

@@ -99,6 +99,54 @@ export class IssuesGateway {
     return issues.filter((issue) => !issue?.pull_request);
   }
 
+  /**
+   * Search issues by a free-text query via the REST search API
+   * (`GET /search/issues`). Deliberately REST, **not** GraphQL: transient
+   * GraphQL 401s are a known failure mode in this repo (the dedup port that
+   * consumes this method must not silently no-op on an auth blip), so the
+   * search rides the same `gh api` REST surface + transient-retry shim as
+   * every other read here.
+   *
+   * The caller (`audit-to-stories.js` `loadProvider()`) passes a 40-char
+   * fingerprint sha as the query so the search resolves the handful of
+   * issues whose fingerprint footer carries that sha; `route-finding.js`
+   * then confirms identity against the footer. Both open and closed issues
+   * are returned (no `state:` qualifier is appended) so a closed-fingerprint
+   * match can surface as `regression-of-closed`.
+   *
+   * Returns the trimmed `[{ number, state, body }]` projection the dedup
+   * port expects. `state` is normalised to the REST lowercase form
+   * (`open` / `closed`).
+   *
+   * @param {{ query: string, owner?: string, repo?: string }} params
+   * @returns {Promise<Array<{ number: number, state: string, body: string }>>}
+   * @field-manifest GET /search/issues: total_count, items[number, state, body]
+   */
+  async searchIssues({ query, owner, repo } = {}) {
+    if (typeof query !== 'string' || query.trim().length === 0) {
+      throw new Error('searchIssues: a non-empty query string is required');
+    }
+    const scopeOwner = owner ?? this.owner;
+    const scopeRepo = repo ?? this.repo;
+    // Constrain the search to this repo and to issues (not PRs). The
+    // fingerprint sha is the free-text term; GitHub matches it against the
+    // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
+    const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
+    const q = `${query.trim()} ${qualifiers.join(' ')}`;
+    const endpoint = `/search/issues?q=${encodeURIComponent(q)}`;
+    const result = await withTransientRetry(
+      () => this._gh.api({ method: 'GET', endpoint }),
+      { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
+    );
+    const json = parseApiJson(result);
+    const items = Array.isArray(json?.items) ? json.items : [];
+    return items.map((item) => ({
+      number: item.number,
+      state: item.state ?? 'open',
+      body: item.body ?? '',
+    }));
+  }
+
   /**
    * List Epic-typed issues. Filter shape preserved from the old code.
    *

package/.agents/scripts/providers/github.js

@@ -98,6 +98,7 @@ export class GitHubProvider extends ITicketingProvider {
  */
 const DELEGATIONS = [
   ['graphql', 'issues.ghGraphql'],
+  ['searchIssues', 'issues.searchIssues'],
   ['listIssuesByLabel', 'issues.listIssuesByLabel'],
   ['getEpics', 'issues.getEpics'],
   ['getEpic', 'issues.getEpic'],

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/README.md

@@ -69,6 +69,26 @@ explicit `npx mandrel sync` above is the belt-and-suspenders step for
 `--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
 time to confirm the install is healthy.
 
+> **pnpm users — hoist mandrel's runtime deps.** The materialized
+> `./.agents/scripts/*.js` run from your project root and resolve their
+> third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
+> npm and yarn hoist transitive deps there automatically; pnpm's default
+> isolated layout does **not** — it keeps them in the `.pnpm` virtual store,
+> so the framework scripts (and `mandrel doctor`'s `runtime-deps` check)
+> cannot see them. Add the following to your `.npmrc` before installing:
+>
+> ```ini
+> # Lift mandrel's runtime deps to the top-level node_modules so the
+> # materialized .agents/scripts can resolve them.
+> shamefully-hoist=true
+> ```
+>
+> Prefer a surgical alternative? Replace `shamefully-hoist` with a scoped
+> `public-hoist-pattern[]=` line per package listed in
+> `.agents/runtime-deps.json` (`ajv`, `ajv-formats`, `js-yaml`, `minimatch`,
+> `picomatch`, `string-argv`, `typhonjs-escomplex`). If `mandrel doctor`
+> reports `runtime-deps missing: …`, this is the fix.
+
 `bootstrap.js` is interactive on a TTY and auto-accepts the
 owner/repo/base branch/operator handle it can infer from your local
 `git remote` and `git config user.name` — you only get prompted for

package/docs/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.69.0...mandrel-v1.70.0) (2026-06-16)
+
+
+### Added
+
+* **agents-update:** add a first-run preflight before the updater (refs [#4170](https://github.com/dsj1984/mandrel/issues/4170)) ([#4177](https://github.com/dsj1984/mandrel/issues/4177)) ([82d30c6](https://github.com/dsj1984/mandrel/commit/82d30c6877d567d8272e1f433da00797a71bdeb9))
+* **agents-update:** make partial-upgrade recovery a first-class workflow step (refs [#4172](https://github.com/dsj1984/mandrel/issues/4172)) ([#4179](https://github.com/dsj1984/mandrel/issues/4179)) ([9959fd8](https://github.com/dsj1984/mandrel/commit/9959fd8e480067b1c35d25c9e37f8be0908f9a9e))
+
+
+### Fixed
+
+* /audit-to-stories: fix silent-no-op dedup (GitHubProvider.searchIssues missing) + junk audit:: label derivation ([#4195](https://github.com/dsj1984/mandrel/issues/4195)) ([#4207](https://github.com/dsj1984/mandrel/issues/4207)) ([d4fed9b](https://github.com/dsj1984/mandrel/commit/d4fed9b6a3077c6c9371ec00debae5c422ac89c6))
+* **agents-update:** invoke mandrel via npx and detect install state (refs [#4169](https://github.com/dsj1984/mandrel/issues/4169)) ([#4174](https://github.com/dsj1984/mandrel/issues/4174)) ([9aab7ba](https://github.com/dsj1984/mandrel/commit/9aab7ba3f2c425a5ecaf16e1008078538093a985))
+* **bootstrap:** relax owner/repo under --skip-github so non-interactive init works in a fresh dir ([#4181](https://github.com/dsj1984/mandrel/issues/4181)) ([e560116](https://github.com/dsj1984/mandrel/commit/e560116aa33178f182752558e7d646c2cb7cdeb4))
+* **deps:** bump markdownlint-cli2 0.18.1 -> 0.22.1, force patched js-yaml/markdown-it (refs [#4187](https://github.com/dsj1984/mandrel/issues/4187)) ([#4200](https://github.com/dsj1984/mandrel/issues/4200)) ([9fe1e09](https://github.com/dsj1984/mandrel/commit/9fe1e09daf91fab0ca5d44d5a701cd2576406a5b))
+* **install-matrix:** hoist mandrel runtime deps in pnpm legs so doctor is honest ([#4180](https://github.com/dsj1984/mandrel/issues/4180)) ([5e7aca7](https://github.com/dsj1984/mandrel/commit/5e7aca7d48b9ab9d0ddd5c157a28bea8978fb90a))
+
+
+### Performance
+
+* **baselines:** collapse the two escomplex passes in full-tree regen into one (refs [#4192](https://github.com/dsj1984/mandrel/issues/4192)) ([#4205](https://github.com/dsj1984/mandrel/issues/4205)) ([4f971c3](https://github.com/dsj1984/mandrel/commit/4f971c36723521058322b346980d6e1822c9d35d))
+* **doctor:** short-circuit payload-drift on statSync size mismatch (refs [#4193](https://github.com/dsj1984/mandrel/issues/4193)) ([#4204](https://github.com/dsj1984/mandrel/issues/4204)) ([a85c050](https://github.com/dsj1984/mandrel/commit/a85c0501a02ff346024fa9d8c9aa48046999f08c))
+
+
+### Changed
+
+* **agents-update:** extract quality-bootstrap heredoc into a tested script (refs [#4171](https://github.com/dsj1984/mandrel/issues/4171)) ([#4178](https://github.com/dsj1984/mandrel/issues/4178)) ([032ecf7](https://github.com/dsj1984/mandrel/commit/032ecf70f5840ad5291c0bcdb6b11a9d23bec1be))
+* **baselines:** triage dead-export allowlist 198 -> 185 (refs [#4184](https://github.com/dsj1984/mandrel/issues/4184)) ([#4197](https://github.com/dsj1984/mandrel/issues/4197)) ([2a39e61](https://github.com/dsj1984/mandrel/commit/2a39e616bb9a843325bf151d8f057f85a43fcd95))
+* **renderers:** table-drive flat section ladders to lower CC ceilings (refs [#4186](https://github.com/dsj1984/mandrel/issues/4186)) ([#4201](https://github.com/dsj1984/mandrel/issues/4201)) ([36df937](https://github.com/dsj1984/mandrel/commit/36df9370d8e9cdef8f6bc47d0341ef8425314222))
+* **update:** retire No-Shim in-process path and extract pure planUpdate (refs [#4182](https://github.com/dsj1984/mandrel/issues/4182)) ([#4198](https://github.com/dsj1984/mandrel/issues/4198)) ([d5ed325](https://github.com/dsj1984/mandrel/commit/d5ed32560d98fa43d6103789efac530f16244a91))
+* **wave-runner:** decompose tick() into coordinator + phases (refs [#4183](https://github.com/dsj1984/mandrel/issues/4183)) ([#4196](https://github.com/dsj1984/mandrel/issues/4196)) ([0d7a6b4](https://github.com/dsj1984/mandrel/commit/0d7a6b4326b60ec3f2dd58a0798c8a37b6117d9c))
+
 ## [1.69.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.68.0...mandrel-v1.69.0) (2026-06-16)