mandrel 1.61.0 → 1.63.0

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

@@ -163,7 +163,7 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the two-package release
+- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
   topology, PAT / npm-token setup, and major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once

package/docs/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.62.0...mandrel-v1.63.0) (2026-06-13)
+
+
+### Added
+
+* **decompose:** set native GitHub blocked-by dependencies from Story depends_on graph (refs [#4067](https://github.com/dsj1984/mandrel/issues/4067)) ([#4068](https://github.com/dsj1984/mandrel/issues/4068)) ([1799659](https://github.com/dsj1984/mandrel/commit/1799659a84b06555c9caa1193aec59113c943b78))
+
+
+### Fixed
+
+* **audit-architecture:** add Impact severity field to Detailed Findings (refs [#4085](https://github.com/dsj1984/mandrel/issues/4085)) ([#4096](https://github.com/dsj1984/mandrel/issues/4096)) ([d72c109](https://github.com/dsj1984/mandrel/commit/d72c109195955eff70d7d926abb36a88e32d3f6e))
+* fix stale architecture.md/README docs and broaden the import-cycle gate scan root ([#4071](https://github.com/dsj1984/mandrel/issues/4071)) ([#4090](https://github.com/dsj1984/mandrel/issues/4090)) ([2e97b45](https://github.com/dsj1984/mandrel/commit/2e97b45f9ed43398dc703dd735394c7483329033))
+
+
+### Performance
+
+* **decompose:** parallelize blocked-by edge creation with bounded concurrentMap (refs [#4082](https://github.com/dsj1984/mandrel/issues/4082)) ([#4094](https://github.com/dsj1984/mandrel/issues/4094)) ([a9f38da](https://github.com/dsj1984/mandrel/commit/a9f38da2d44941a164865a6ad291c2da01ee4ed6))
+
+
+### Changed
+
+* `parseProviderFindings` is a CC-30 ternary thicket ([#4074](https://github.com/dsj1984/mandrel/issues/4074)) ([#4089](https://github.com/dsj1984/mandrel/issues/4089)) ([5ed693c](https://github.com/dsj1984/mandrel/commit/5ed693c3325c05a36251b859be5873ab0378031c))
+* extract shared createDriftDetector skeleton for CRAP and MI drift detectors (refs [#4076](https://github.com/dsj1984/mandrel/issues/4076)) ([#4091](https://github.com/dsj1984/mandrel/issues/4091)) ([e8a81a8](https://github.com/dsj1984/mandrel/commit/e8a81a82307a12c3d6e58275d4c4554b07659f4f))
+* **scripts:** reduce CC of CLI orchestration bodies below the must-fix band (refs [#4075](https://github.com/dsj1984/mandrel/issues/4075)) ([#4093](https://github.com/dsj1984/mandrel/issues/4093)) ([53519de](https://github.com/dsj1984/mandrel/commit/53519de7968e59c08479c886ca3713f53f5c039d))
+* **signals:** hoist shared detector validation preamble into common.js (refs [#4077](https://github.com/dsj1984/mandrel/issues/4077)) ([#4092](https://github.com/dsj1984/mandrel/issues/4092)) ([2f6fe7b](https://github.com/dsj1984/mandrel/commit/2f6fe7b103c208fbd3ea4cfedf63d2a7aa412e24))
+* **single-story-init:** inject spawnSync boundary into makeGhRunner (refs [#4073](https://github.com/dsj1984/mandrel/issues/4073)) ([#4087](https://github.com/dsj1984/mandrel/issues/4087)) ([8fae355](https://github.com/dsj1984/mandrel/commit/8fae35568523e3997d8f7e79580c0cc8e0625072))
+* **story-body:** extract per-section sub-parsers from parse() (refs [#4072](https://github.com/dsj1984/mandrel/issues/4072)) ([#4088](https://github.com/dsj1984/mandrel/issues/4088)) ([aa9e472](https://github.com/dsj1984/mandrel/commit/aa9e47204728da0ab4f547927af251fce6a85b69))
+
+## [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.63.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",