mandrel 1.61.0 → 1.62.0

package/.agents/docs/SDLC.md

@@ -143,6 +143,11 @@ From zero to shipped:
    a halt), re-run `/deliver <epicId>` — the wave loop picks up
    incomplete Stories from the dispatch manifest automatically. Standalone
    Stories (no `Epic: #N` reference) use `/deliver <storyId>` instead.
+   Mixed input — several Epics, or Epics plus standalone Stories — is
+   accepted in one invocation: `/deliver` composes a **sequential segment
+   plan** (the standalone-Story set as one segment, delivered first, then
+   each Epic as its own segment in input order) and executes the segments
+   one at a time through the same two path helpers, never interleaved.
 
 That is the whole happy path. Everything below is **detail** — branching
 conventions, HITL escalation, audit gates — that you only need when the
@@ -664,10 +669,12 @@ side-effects rather than inline calls at phase boundaries; the
 | **Standalone Story — plan**      | `/plan`                                            | Plan a one-off Story that does not belong to an Epic backlog.                                  |
 | **Standalone Story — deliver**   | `/deliver <storyId> [<storyId>...]`                | Deliver one or more standalone Stories authored by `/plan`.                             |
 | **Standalone Story (worker)**    | *helper* `helpers/single-story-deliver <storyId>`        | Per-Story sub-agent called internally by `/deliver`; not an operator slash command.      |
+| **Mixed set**                    | `/deliver <ids...>`                                | Any mix of ≥1 Epics and standalone Stories. The router composes a sequential segment plan — standalone segment first, then Epic segments in input order — delegating each segment to the path helpers above. |
 
-The operator-facing entry points are `/deliver` (for Epics) and
-`/deliver` (for standalone Stories). The `helpers/` layer sits below
-both and is never invoked directly by the operator.
+The single operator-facing entry point is `/deliver` — it routes a lone
+Epic, a standalone-Story set, or a mixed set (via the sequential segment
+plan) to the right path helper(s). The `helpers/` layer sits below it and
+is never invoked directly by the operator.
 
 ### Story-centric branching
 

package/.agents/docs/workflows.md

@@ -44,7 +44,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
 | `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --idea or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, then routes to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
+| `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, composes a sequential segment plan over any mix of Epics and standalone Stories, then delegates each segment to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
 | `/explain` | Walk the operator through a code change until they genuinely understand it. Targets a PR, a branch, or the working-tree diff, then drives the `core/knowledge-transfer` skill (restate-first, why-ladder, mastery gates, persistent checklist) with an operator-controlled stop at every checkpoint. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-commit-all` | Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push). |

package/.agents/workflows/deliver.md

@@ -1,17 +1,19 @@
 ---
 description:
   Unified delivery entry point. Inspects the ticket type(s) and
-  Epic-reference state of the supplied IDs, then routes to the Epic wave
-  loop or the standalone multi-Story fan-out — preserving every flag and
-  the parallel-delivery contract of the retired commands.
+  Epic-reference state of the supplied IDs, composes a sequential segment
+  plan over any mix of Epics and standalone Stories, then delegates each
+  segment to the Epic wave loop or the standalone multi-Story fan-out —
+  preserving every flag and the parallel-delivery contract of the retired
+  commands.
 ---
 
-# /deliver [Epic ID] | [Story IDs...]
+# /deliver [Epic IDs...] | [Story IDs...]
 
 ## Role
 
-Router. `/deliver` owns input classification and path selection only — all
-phase content lives in the two path helpers:
+Router. `/deliver` owns input classification, segment-plan composition, and
+path selection only — all phase content lives in the two path helpers:
 
 - [`helpers/deliver-epic.md`](helpers/deliver-epic.md) — the full Epic
   delivery loop (preflight, wave loop fanning out
@@ -30,20 +32,67 @@ reference) before routing:
 
 | Input | Route |
 | --- | --- |
-| Exactly one `type::epic` ID | **Epic path** — run [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9 unchanged. |
-| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3. |
-| Any Story carrying an `Epic: #N` reference | **Error**, naming the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
-| Mixed Epic + Story IDs, or more than one Epic | **Error**: separate invocations — one `/deliver <epicId>` per Epic, one `/deliver <id> [<id>...]` for the standalone set. |
-
-## Flags (forwarded per path)
+| Exactly one `type::epic` ID | **Epic path** — run [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9 unchanged (single-segment plan; no confirmation prompt). |
+| One or more `type::story` IDs, none carrying an `Epic: #N` reference | **Standalone path** — run [`helpers/deliver-stories.md`](helpers/deliver-stories.md) Phases 0–3 (single-segment plan; no confirmation prompt). |
+| Any combination of ≥1 `type::epic` IDs and ≥0 standalone `type::story` IDs | **Segment plan** — compose and execute the sequential segment plan below. |
+| Any Story carrying an `Epic: #N` reference (alone or mixed into an otherwise-valid set) | **Error**, naming every affected ID and the fix: `Story #<id> belongs to Epic #<n> — run /deliver <n>`. |
+
+Per-ID classification is unchanged: fetch the `type::*` label and probe the
+body for an `Epic: #N` reference before routing. Never guess a route.
+
+## Segment plan (mixed / multi-Epic input)
+
+When the supplied IDs span more than one Epic, or mix Epics with standalone
+Stories, the router composes a **segment plan** and executes the segments
+**strictly sequentially**:
+
+1. **Standalone segment first** (when any standalone Story IDs are
+   present): the full standalone-Story set forms **one** segment,
+   delivered via [`helpers/deliver-stories.md`](helpers/deliver-stories.md)
+   Phases 0–3 unchanged. It runs first because it is fast, each Story
+   merges to `main` independently, and each subsequent Epic segment's
+   Phase 7.0 base-sync then integrates those merges naturally instead of
+   the Epic PR opening behind base.
+2. **Epic segments in input order**: each `type::epic` ID forms its own
+   segment, delivered via
+   [`helpers/deliver-epic.md`](helpers/deliver-epic.md) Phases 1–9
+   unchanged.
+
+Sequential execution is a deliberate design decision: the Epic path assumes
+a single main checkout (prepare's checkout guard, Phase 7.0
+`git checkout epic/<id>`), holds a per-Epic lease, serializes same-machine
+sessions via `epic-merge-lock.js`, and constrains dispatch to one wave at a
+time. Segments are never interleaved or parallelized; running them one at a
+time keeps both helpers' machinery untouched.
+
+**Confirmation gate.** When the composed plan has more than one segment,
+present it to the operator before dispatching — the segments, the IDs in
+each, and the execution order — and wait for confirmation. `--yes`
+suppresses this prompt. Single-segment plans route directly with today's
+behavior (no new prompt; the standalone path's own Phase 1 confirmation
+still applies as before).
+
+**Failure policy.** A segment that ends non-complete (blocked, failed, or
+halted at a gate) **stops the run** — no subsequent segment dispatches.
+Report the terminal state: which segments completed, which segment halted
+(and why), and which segments never started. Name the resume command:
+re-running `/deliver` with the same IDs — both path helpers short-circuit
+already-done work (the Epic path resumes idempotently from its checkpoint;
+merged standalone Stories no-op).
+
+## Flags (scoped per segment)
 
 | Path | Flags |
 | --- | --- |
 | Epic | `--skip-epic-audit`, `--skip-code-review`, `--skip-retro`, `--full-retro`, `--steal`, `--as <handle>` |
 | Story | `--dep <from>:<to>`, `--yes`, `--concurrency <n>` |
 
-A flag passed to the wrong path is reported once as a no-op warning and
-ignored — never an error.
+In a segment plan, Epic-path flags apply to **every** Epic segment;
+Story-path flags apply to the standalone segment. `--yes` additionally
+suppresses the router's segment-plan confirmation gate above. A flag with
+no applicable segment in the plan is reported once as a no-op warning and
+ignored — never an error (the existing convention, restated for segment
+plans).
 
 **Multi-Story parallel contract (preserved verbatim).**
 
@@ -55,31 +104,43 @@ 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).
+[`helpers/single-story-deliver`](helpers/single-story-deliver.md). The
+parallelism lives **inside** the standalone segment; segments themselves
+remain strictly sequential.
 
 ## Procedure
 
 1. **Parse args.** At least one positive-integer ID is required.
 2. **Classify.** Fetch each ticket's labels + body and apply the input
-   matrix above. Refuse ambiguous input with the matrix's error messages —
-   never guess a route.
-3. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry phase, forwarding the absorbed flags. The helper's phase
-   numbering, watchdogs, gates, and scripts are unchanged — this router
-   adds no phase content.
+   matrix above. Any Epic-attached Story ID is a hard error naming the
+   affected IDs and the fix — never guess a route.
+3. **Compose the segment plan.** Standalone-Story set (when present) as
+   one segment, then one segment per Epic ID in input order. For a
+   multi-segment plan, present it and wait for operator confirmation
+   (`--yes` suppresses).
+4. **Execute segments sequentially.** For each segment in order, read the
+   selected path helper **in full** and execute it from its entry phase,
+   forwarding the segment's scoped flags. The helper's phase numbering,
+   watchdogs, gates, and scripts are unchanged — this router adds no phase
+   content. Stop on the first non-complete segment per the failure policy.
+5. **Report.** On completion (or halt), summarize per-segment outcomes and,
+   when halted, the resume command.
 
 ## Constraints
 
-- `/deliver` requires a planned ticket: an Epic at `agent::ready` (the
-  Epic helper's preflight enforces this) or well-formed standalone Stories.
-  Planning happens in [`/plan`](plan.md); the plan-review gate between the
-  two commands is a hard boundary.
+- `/deliver` requires planned tickets: Epics at `agent::ready` (the
+  Epic helper's preflight enforces this, per segment) or well-formed
+  standalone Stories. Planning happens in [`/plan`](plan.md); the
+  plan-review gate between the two commands is a hard boundary.
 - The router performs no git or label mutations itself; the path helpers
   own every script invocation.
+- Segments execute strictly sequentially — never interleave a standalone
+  Story fan-out with an Epic wave loop, and never run two Epic segments
+  concurrently.
 
 ## See also
 
 - [`/plan`](plan.md) — the unified planning entry point.
 - [`helpers/deliver-epic.md`](helpers/deliver-epic.md) /
   [`helpers/deliver-stories.md`](helpers/deliver-stories.md) — the path
-  helpers.
+  helpers, delegated to per segment.

package/.agents/workflows/helpers/deliver-epic.md

@@ -14,9 +14,14 @@ description: >-
 
 ## Overview
 
-`/deliver` is the **single SDL execution command** in the 5.40 surface.
-It opens a PR against `main` and auto-merges when every signal certifies a
-clean run; otherwise it falls back to the operator-merges-button path.
+This helper is the **Epic delivery path** behind `/deliver` — the router
+delegates to it once per Epic ID, either as the sole route (single-Epic
+input) or as one **Epic segment** of the sequential segment plan `/deliver`
+composes over mixed Epic / standalone-Story input (Epic segments run in
+input order, after the standalone segment; see
+[`deliver.md`](../deliver.md)). Each invocation opens a PR against `main`
+and auto-merges when every signal certifies a clean run; otherwise it falls
+back to the operator-merges-button path.
 
 ```text
 /deliver <epicId>
@@ -32,8 +37,10 @@ clean run; otherwise it falls back to the operator-merges-button path.
   → Phase 9 — cleanup              (BranchCleaner + Cleaner lifecycle listeners on epic.cleanup.start / epic.merge.armed; fire via lifecycle-emit → epic.merge.armed)
 ```
 
-The argument is always an Epic ID (`type::epic`). Story IDs go to
-[`/deliver`](deliver-stories.md) (standalone) or the
+The argument is always a single Epic ID (`type::epic`) — multi-Epic or
+mixed input is segmented by the `/deliver` router before this helper runs.
+Story IDs go to
+[`helpers/deliver-stories`](deliver-stories.md) (standalone) or the
 [`helpers/epic-deliver-story`](epic-deliver-story.md) helper
 (Epic-attached, invoked by this workflow's fan-out); Tasks are not directly
 executable.

package/.agents/workflows/helpers/deliver-stories.md

@@ -11,10 +11,14 @@ description: >-
 
 ## Overview
 
-`/deliver` is the **operator-facing multi-Story delivery command**. It
-takes one or more Story IDs, builds a dependency-aware wave plan, optionally
-confirms it with the operator, and fans out one Agent call per Story per wave
-— parallel within each wave, serialised across waves.
+This helper is the **standalone multi-Story delivery path** behind
+`/deliver`. The router delegates to it whenever the supplied IDs include
+standalone Stories — either as the sole route (Story-only input) or as the
+**standalone segment** of a mixed segment plan (run first, before any Epic
+segments; see [`deliver.md`](../deliver.md)). It takes one or more Story
+IDs, builds a dependency-aware wave plan, optionally confirms it with the
+operator, and fans out one Agent call per Story per wave — parallel within
+each wave, serialised across waves.
 
 ```text
 /deliver 101 102 103
@@ -33,11 +37,13 @@ confirms it with the operator, and fans out one Agent call per Story per wave
 | 1+ standalone Stories (no `Epic: #N` in body) | `/deliver <id> [<id>...]` |
 | Exactly one standalone Story (lighter path) | `/single-story-deliver <id>` |
 | Epic-attached Stories (have `Epic: #N`) | `/deliver <epicId>` |
+| Mixed Epics + standalone Stories | `/deliver <ids...>` — the router composes a sequential segment plan; this helper delivers the standalone segment first |
 
-`/deliver` **refuses** Stories that carry an `Epic: #N` reference in
+This helper **refuses** Stories that carry an `Epic: #N` reference in
 their body. Those Stories belong to an Epic's dispatch manifest and must flow
-through `/deliver`. Use `/single-story-deliver` for a single Epic-free
-Story when you want the leaner one-story path without wave machinery.
+through `/deliver <epicId>`. Use `/single-story-deliver` for a single
+Epic-free Story when you want the leaner one-story path without wave
+machinery.
 
 > **Concurrency cap.** The cap is resolved **deterministically in code** by
 > `stories-wave-tick.js` (Phase 1a) — the same `resolveConfig` + `getRunners`

package/.agents/workflows/plan.md

@@ -126,6 +126,8 @@ stubbed docs, or an unready doctor verdict).
 
 ## See also
 
-- [`/deliver`](deliver.md) — the unified delivery entry point.
+- [`/deliver`](deliver.md) — the unified delivery entry point. Accepts a
+  single Epic, one or more standalone Stories, or any mix of ≥1 Epics and
+  standalone Stories — mixed sets compose a sequential segment plan.
 - [`helpers/plan-epic.md`](helpers/plan-epic.md) /
   [`helpers/plan-story.md`](helpers/plan-story.md) — the path helpers.

package/docs/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.61.0...mandrel-v1.62.0) (2026-06-12)
+
+
+### Added
+
+* /deliver composes a sequential segment plan over mixed Epic and standalone-Story ID sets (refs [#4062](https://github.com/dsj1984/mandrel/issues/4062)) ([#4063](https://github.com/dsj1984/mandrel/issues/4063)) ([a83d29e](https://github.com/dsj1984/mandrel/commit/a83d29e032b7f6b6846d7988f071d6b6416df2f9))
+
+
+### Fixed
+
+* make mandrel update no-op short-circuit drift-aware (refs [#4065](https://github.com/dsj1984/mandrel/issues/4065)) ([#4066](https://github.com/dsj1984/mandrel/issues/4066)) ([693f1cf](https://github.com/dsj1984/mandrel/commit/693f1cf5bf8fd7d29fed910659708ffceb7a54cb))
+
 ## [1.61.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.60.0...mandrel-v1.61.0) (2026-06-12)
 
 

package/lib/cli/registry.js

@@ -483,7 +483,7 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
  * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
-function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
+export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   const getCwd = cwd ?? (() => process.cwd());
   const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
   const projectRoot = getCwd();

package/lib/cli/update.js

@@ -12,7 +12,10 @@
  * ## Ordered cycle (happy path)
  *
  *   1. resolve target version (newest published) and the current version
- *   2. no-op short-circuit — already on the newest version ⇒ nothing to do
+ *   2. drift-aware short-circuit — version check gates on installed version AND
+ *      materialized `.agents/` state (Story #4065). When already on newest AND
+ *      no drift: nothing to do (true no-op). When already on newest BUT drift
+ *      detected: skip npm-update/migrations, run sync + sync-commands to heal.
  *   3. install        — bump the dependency (lockfile bump left STAGED).
  *      The package manager is auto-detected from the lockfile in the project
  *      root: `pnpm-lock.yaml` ⇒ `pnpm add -D …` (with `-w` at a
@@ -85,6 +88,11 @@
  *   - `argv`                — subcommand args (after `mandrel update`)
  *   - `currentVersion`      — the installed `mandrel` version string
  *   - `resolveTargetVersion`— async, returns the newest published version
+ *   - `checkDrift`          — sync or async, returns `true` when `.agents/`
+ *                             differs from the installed payload. Used by the
+ *                             drift-aware no-op short-circuit (Story #4065).
+ *                             Defaults to `() => !runAgentsDrift().ok`, which
+ *                             reuses the same `agents-drift` doctor signal.
  *   - `npmUpdate`           — async, performs the dependency bump (no git);
  *                             receives `(target, { installCmd })`
  *   - `spawnPhase`          — async, spawns a post-install phase from the new
@@ -140,7 +148,7 @@ import { fileURLToPath } from 'node:url';
 import { detectPackageManagerWithWorkspace } from '../../.agents/scripts/lib/detect-package-manager.js';
 import { runInstallCommand } from '../../.agents/scripts/lib/install-cmd-parser.js';
 import { runMigrations as defaultRunMigrations } from '../migrations/index.js';
-import { registry } from './registry.js';
+import { registry, runAgentsDrift } from './registry.js';
 import { runSync as defaultRunSync } from './sync.js';
 import { isStale } from './version-check.js';
 import { compareVersions } from './version-helpers.js';
@@ -761,6 +769,7 @@ function parseInstallCmdFlag(argv) {
  *   currentVersion?: string | (() => string),
  *   resolveTargetVersion?: () => (string | Promise<string>),
  *   npmUpdate?: (version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>,
+ *   checkDrift?: () => (boolean | Promise<boolean>),
  *   spawnPhase?: (phase: string, args: string[], opts: { binPath: string, cwd: string, write: (s: string) => void, writeErr: (s: string) => void }) => Promise<{ ok: boolean, stdout: string, stderr: string }> | { ok: boolean, stdout: string, stderr: string },
  *   runSync?: typeof defaultRunSync,
  *   runMigrations?: typeof defaultRunMigrations,
@@ -773,7 +782,7 @@ function parseInstallCmdFlag(argv) {
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
- *   action: 'updated' | 'dry-run' | 'up-to-date' | 'doctor-failed',
+ *   action: 'updated' | 'resynced' | 'dry-run' | 'up-to-date' | 'doctor-failed',
  *   currentVersion: string,
  *   targetVersion: string | null,
  *   stepsRun: string[],
@@ -785,6 +794,7 @@ export async function runUpdate({
   currentVersion,
   resolveTargetVersion,
   npmUpdate,
+  checkDrift,
   spawnPhase,
   runSync = defaultRunSync,
   runMigrations = defaultRunMigrations,
@@ -811,16 +821,112 @@ export async function runUpdate({
   const target = String(await resolveTargetVersion());
 
   // --- No-op short-circuit --------------------------------------------------
-  // Already on (or ahead of) the newest version: nothing to apply.
+  // Already on (or ahead of) the newest version: check whether .agents/ is
+  // actually materialized to the installed payload (agents-drift). When drift
+  // is present, fall through to a sync-only heal path even though the package
+  // version is unchanged. Only emit "Already up to date" when the version is
+  // current AND the payload matches (Story #4065).
   if (compareVersions(target, current) <= 0) {
-    write(`✅  Already up to date (v${current} is the newest version).\n`);
+    // Resolve the drift probe: prefer the injected checkDrift seam (unit-test
+    // friendly); fall back to the production runAgentsDrift helper.
+    const driftProbe =
+      typeof checkDrift === 'function'
+        ? checkDrift
+        : () => !runAgentsDrift().ok;
+    const hasDrift = await driftProbe();
+
+    if (!hasDrift) {
+      write(`✅  Already up to date (v${current} is the newest version).\n`);
+      return {
+        ok: true,
+        action: 'up-to-date',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun: [],
+        dryRun,
+      };
+    }
+
+    // Drift detected while version is already current — heal by re-syncing
+    // without bumping the package (no npm-update, no migrations needed since
+    // the installed version did not change).
+    if (dryRun) {
+      write(
+        `mandrel update — drift detected, sync heal planned (v${current} is already current)\n`,
+      );
+      write(
+        '  1. runSync        — re-materialize .agents/ from installed payload\n',
+      );
+      write(
+        '  2. sync-commands  — regenerate .claude/commands/ from .agents/workflows/\n',
+      );
+      write('Dry run: no files written.\n');
+      return {
+        ok: true,
+        action: 'dry-run',
+        currentVersion: current,
+        targetVersion: target,
+        stepsRun: [],
+        dryRun: true,
+      };
+    }
+
+    write(
+      `Healing .agents/ drift (v${current} is already current, but .agents/ is stale)…\n`,
+    );
+    const stepsRun = [];
+
+    const useReExec = typeof spawnPhase === 'function';
+
+    if (useReExec) {
+      const projectRoot = cwd();
+      const binPath = resolveNewBinPath(projectRoot);
+
+      const syncResult = await spawnPhase('sync', [], {
+        binPath,
+        cwd: projectRoot,
+        write,
+        writeErr,
+      });
+      if (!syncResult.ok) {
+        throw new Error(
+          `mandrel update: \`mandrel sync\` from installed binary exited non-zero — ` +
+            'the .agents/ materialization may be incomplete. ' +
+            'Run `mandrel sync` manually to restore.',
+        );
+      }
+      stepsRun.push('runSync');
+
+      const syncCommandsResult = await spawnPhase('sync-commands', [], {
+        binPath,
+        cwd: projectRoot,
+        write,
+        writeErr,
+      });
+      if (!syncCommandsResult.ok) {
+        throw new Error(
+          `mandrel update: \`mandrel sync-commands\` from installed binary exited non-zero — ` +
+            'the .claude/commands/ tree may be out of sync. ' +
+            'Run `npm run sync:commands` manually to restore.',
+        );
+      }
+      stepsRun.push('sync-commands');
+    } else {
+      // In-process backward-compat path.
+      runSync({ argv: [] });
+      stepsRun.push('runSync');
+    }
+
+    write(
+      `✅  Healed .agents/ drift (v${current}). The materialized payload is now current.\n`,
+    );
     return {
       ok: true,
-      action: 'up-to-date',
+      action: 'resynced',
       currentVersion: current,
       targetVersion: target,
-      stepsRun: [],
-      dryRun,
+      stepsRun,
+      dryRun: false,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",