mandrel 1.59.0 → 1.61.0

package/.agents/scripts/hierarchy-gate.js

@@ -3,7 +3,7 @@
 /**
  * .agents/scripts/hierarchy-gate.js — Hierarchy Completeness Gate
  *
- * Walks the Epic's full sub-issue graph (Features → Stories) and verifies
+ * Walks the Epic's full sub-issue graph (Stories) and verifies
  * every descendant is closed. Where the wave gate asks "did the sprint
  * complete what it committed to?" (manifest view), this gate asks "is
  * anything still open under this Epic?" (live GitHub graph view).
@@ -16,14 +16,13 @@
  *     top-level Stories outside the Epic's sub-issue graph.
  *
  * Per ticket type the rule is:
- *   - Features  — must be closed.
  *   - Stories   — must be closed.
  *   - Auxiliary (context::prd, context::tech-spec) — ignored.
  *     These are closed by the operator after the Epic PR merges, so
  *     requiring them closed here would block every Epic.
  *
- * **3-tier hierarchy (Epic #3078).** Mandrel ships only Epic / Feature /
- * Story tickets. `getSubTickets(<storyId>)` returns `[]`; the walk
+ * **2-tier hierarchy (Story #4041).** Mandrel ships only Epic / Story
+ * tickets. `getSubTickets(<storyId>)` returns `[]`; the walk
  * terminates at the Story. Acceptance criteria live inline on the
  * Story body.
  *
@@ -53,7 +52,6 @@ const SUB_TICKET_FETCH_CONCURRENCY = 4;
 function classify(ticket) {
   const labels = ticket.labels ?? [];
   if (labels.includes(TYPE_LABELS.STORY)) return 'story';
-  if (labels.includes(TYPE_LABELS.FEATURE)) return 'feature';
   if (
     labels.includes(CONTEXT_LABELS.PRD) ||
     labels.includes(CONTEXT_LABELS.TECH_SPEC)
@@ -80,7 +78,7 @@ async function collectDescendants(provider, epicId) {
   const out = [];
   // Level-order BFS: each round fetches the whole frontier's children with a
   // bounded-parallel map instead of one awaited round-trip per node. Stories
-  // are 3-tier leaves (no sub-issues by contract), so they are never expanded
+  // are leaves (no sub-issues by contract), so they are never expanded
   // — that skip alone removes the largest class of wasted GraphQL calls.
   let frontier = [epicId];
   while (frontier.length > 0) {
@@ -126,7 +124,7 @@ export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
     process.exit(2);
   }
 
-  const failures = { feature: [], story: [], other: [] };
+  const failures = { story: [], other: [] };
   let auxiliaryDeferred = 0;
   for (const ticket of descendants) {
     const kind = classify(ticket);
@@ -144,15 +142,13 @@ export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
     }
   }
 
-  const totalOpen =
-    failures.feature.length + failures.story.length + failures.other.length;
+  const totalOpen = failures.story.length + failures.other.length;
 
   if (totalOpen > 0) {
     Logger.error(
       `[hierarchy-gate] ❌ Hierarchy-completeness gate FAILED for Epic #${epicId}: ${totalOpen} descendant(s) incomplete.`,
     );
     const sections = [
-      ['feature', 'Features'],
       ['story', 'Stories'],
       ['other', 'Untyped descendants'],
     ];
@@ -163,7 +159,7 @@ export async function runHierarchyGate({ epicId, injectedProvider } = {}) {
         Logger.error(`    - #${item.id} (${item.reason}) — ${item.title}`);
       }
     }
-    Logger.error('\nClose the open descendants and re-run `/epic-deliver`.');
+    Logger.error('\nClose the open descendants and re-run `/deliver`.');
     process.exit(1);
   }
 

package/.agents/scripts/lib/ITicketingProvider.js

@@ -154,7 +154,7 @@ export class ITicketingProvider {
   /**
    * Create a child ticket within an Epic's structural hierarchy.
    *
-   * @param {number} parentId - GitHub Issue number of the immediate structural parent (e.g. Epic, Feature, or Story).
+   * @param {number} parentId - GitHub Issue number of the immediate structural parent (e.g. Epic or Story).
    * @param {{
    *   epicId: number,
    *   title: string,

package/.agents/scripts/lib/audit-suite/selector.js

@@ -60,7 +60,7 @@ export function matchesAnyFilePattern(patterns, files) {
  *   callers MUST pass the requested Epic's own branch ref (e.g.
  *   `refs/heads/epic/<id>`) so the change set is pinned to that Epic's branch
  *   rather than whatever HEAD the shared checkout happens to sit on. Under two
- *   concurrent `/epic-deliver` runs sharing one checkout, diffing against
+ *   concurrent `/deliver` runs sharing one checkout, diffing against
  *   `HEAD` silently resolves the *other* Epic's change set (Story #3362). When
  *   `headRef` cannot be resolved in the repo, the selector returns a
  *   `degraded: true` envelope (or hard-fails in gate-mode) instead of diffing

package/.agents/scripts/lib/audit-to-stories/seed-epic-from-findings.js

@@ -1,7 +1,7 @@
 /**
  * lib/audit-to-stories/seed-epic-from-findings.js
  *
- * Build the `--idea`-shaped seed markdown that `/epic-plan` Phase 1
+ * Build the `--idea`-shaped seed markdown that `/plan` Phase 1
  * consumes when the operator picks the Single-Epic grouping mode.
  *
  * The seed renders the canonical one-pager sections so the idea-refinement
@@ -10,7 +10,7 @@
  *   - Recommended Direction (rollup of recommendations by dimension)
  *   - Key Assumptions (carries the source-report links forward)
  *   - MVP Scope (the proposed Stories, one bullet per group)
- *   - Key Files (explicit file paths so /epic-plan Phase 7 decompose
+ *   - Key Files (explicit file paths so /plan Phase 7 decompose
  *     has concrete anchors)
  *   - Not Doing (out-of-scope items by convention)
  *

package/.agents/scripts/lib/baseline-snapshot.js

@@ -28,8 +28,8 @@ import { calculateAll, scanDirectory } from './maintainability-utils.js';
  * baseline-snapshot.js — per-Epic baseline lifecycle helpers.
  *
  * Story #1396 (Epic #1386). The Epic-snapshot scheme freezes the maintainability
- * and crap baselines at /epic-plan time and reconciles them back to `main`
- * at /epic-deliver time. Two helpers, both pure-ish (deterministic given the
+ * and crap baselines at /plan time and reconciles them back to `main`
+ * at /deliver time. Two helpers, both pure-ish (deterministic given the
  * working tree + injected I/O):
  *
  *   - forkMainToEpic({ epicId, cwd }) — copies the tracked main baselines
@@ -37,20 +37,20 @@ import { calculateAll, scanDirectory } from './maintainability-utils.js';
  *     source content produces the same destination bytes (no fs churn). When
  *     the source baseline is missing, emits a warn through the injected
  *     logger and returns `{ written: false, reason: 'source-missing' }` for
- *     that file — callers (e.g. /epic-plan Phase 7) treat the absence as
+ *     that file — callers (e.g. /plan Phase 7) treat the absence as
  *     non-fatal and stay in `--full-scope` mode.
  *
  *   - regenerateMainFromTree({ cwd }) — re-scores maintainability + crap
  *     against the current working tree and writes the result to the tracked
  *     main baseline paths. Returns `{ didChange, paths }` where `didChange`
  *     is true iff any baseline file's content differs from what's already on
- *     disk. Callers in /epic-deliver use `didChange === false` to skip the
+ *     disk. Callers in /deliver use `didChange === false` to skip the
  *     `baseline-refresh: epic-<id>` commit.
  *
  * Lifecycle note (Story #1467): per-epic ratchet snapshots are ephemeral
  * scratch state under the `temp/epic-<id>/baselines/` namespace, NOT committed
  * artifacts. They inherit the existing per-epic temp-tree cleanup contract —
- * `/epic-deliver` reaps the parent `temp/epic-<id>/` directory on merge, so
+ * `/deliver` reaps the parent `temp/epic-<id>/` directory on merge, so
  * no manual prune is required. Earlier versions of this module wrote under
  * `baselines/epic/<id>/`, which committed them to git and accumulated obsolete
  * snapshots forever.
@@ -103,7 +103,7 @@ export function epicSnapshotPathFor({ epicId, kind, cwd = process.cwd() }) {
  *   - Source baseline missing → returned per-file `{ written: false,
  *     reason: 'source-missing' }`. Logger warn fires once per missing file.
  *     Caller stays in `--full-scope` mode.
- *   - Source unreadable / not parseable → throws. Re-running /epic-plan
+ *   - Source unreadable / not parseable → throws. Re-running /plan
  *     with `--force` after fixing the source recovers.
  *
  * @param {{
@@ -428,7 +428,7 @@ export function commitSnapshotsToEpicBranch({
  * via `delivery.quality.gates.crap.coveragePath`. When coverage is missing and
  * `requireCoverage` is true, the crap regeneration is skipped (didChange stays
  * false for that file) and a warn is emitted — the operator is expected to run
- * `npm run test:coverage` before /epic-deliver if a refresh is anticipated.
+ * `npm run test:coverage` before /deliver if a refresh is anticipated.
  *
  * @param {{
  *   cwd?: string,

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -13,7 +13,7 @@
  * The verification is **static**: we inspect `package.json` for a known BDD
  * runner dependency, and consult a small lookup table of which runners
  * support which pending/skip tag. We do not boot the runner. This keeps
- * `/epic-plan` Phase 7 hermetic and offline.
+ * `/plan` Phase 7 hermetic and offline.
  *
  * **Workspace awareness (Story #2956).** In a pnpm / npm / yarn monorepo the
  * BDD runner is rarely a root devDependency — it lives in the workspace

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -1,5 +1,5 @@
 /**
- * bdd-scenario-scanner.js — Gherkin scenario index for /epic-plan Phase 7.
+ * bdd-scenario-scanner.js — Gherkin scenario index for /plan Phase 7.
  *
  * Story #2637 (sibling to #2634 codebase-snapshot, #2635 spec-freshness,
  * #2636 file-assumption gate). The Acceptance Engineer step of
@@ -7,7 +7,7 @@
  * alone — it never inspects the consumer project's existing `.feature`
  * files. Planned ACs frequently duplicate scenarios that already exist or
  * re-specify behaviour the codebase already proves; the duplication is
- * only discovered (at best) during `/story-deliver` or (at worst) after
+ * only discovered (at best) during `/deliver` or (at worst) after
  * a redundant PR ships.
  *
  * `scanBddScenarios` walks every configured feature root, parses each
@@ -20,7 +20,7 @@
  * have a matching scenario.
  *
  * Determinism is load-bearing: the matcher is keyword-based, not
- * embedding-based, so re-running `/epic-plan` against the same
+ * embedding-based, so re-running `/plan` against the same
  * acceptance spec produces the same disposition annotations.
  */
 

package/.agents/scripts/lib/bootstrap/baselines-layout-migration.js

@@ -15,7 +15,7 @@
  *
  * All three shapes are relocated under `<repoRoot>/temp/epic/<id>/baselines/`,
  * where they inherit the existing per-epic temp-tree cleanup contract:
- * `/epic-deliver` reaps `temp/epic/<id>/` on merge, so the ratchet snapshots
+ * `/deliver` reaps `temp/epic/<id>/` on merge, so the ratchet snapshots
  * are ephemeral scratch state — never committed, no manual prune.
  *
  * The main-tracked `baselines/{maintainability,crap}.json` files are NOT

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -7,7 +7,7 @@
  *   - `enforce_admins: true` — admins do not bypass the prGate suite.
  *   - `required_pull_request_reviews.required_approving_review_count: 0` —
  *     CI is the gate; the operator monitors and iterates the open PR
- *     to green via `/epic-deliver`'s Phase 7 watch loop.
+ *     to green via `/deliver`'s Phase 7 watch loop.
  *
  * Behaviour rules
  * ---------------

package/.agents/scripts/lib/bootstrap/ci-workflow-template.js

@@ -14,7 +14,7 @@
  *      `--full-scope` so a self-diff doesn't degrade to "no files in diff".
  *
  *   2. **Pass `--epic-ref` where the firing site is Epic-aware.** Inside
- *      `/story-deliver` the close-validation chain already threads
+ *      `/deliver` the close-validation chain already threads
  *      `--epic-ref epic/<id>`; on CI the equivalent surface is the PR's
  *      base branch. The template wires `--epic-ref ${EPIC_REF}` through an
  *      env var the workflow computes from `github.head_ref` (story-N
@@ -28,6 +28,9 @@
  * @module bootstrap/ci-workflow-template
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
+
 /**
  * @typedef {object} CiTemplateOptions
  * @property {string} [nodeVersion='22'] - Node major to install via setup-node.
@@ -169,3 +172,46 @@ ${crapBlock}`;
  * path without re-deriving it.
  */
 export const CI_WORKFLOW_RELATIVE_PATH = '.github/workflows/ci.yml';
+
+/**
+ * Render the stabilized-quality-gates CI workflow template into a project
+ * checkout. Idempotent on the byte level: when `.github/workflows/ci.yml`
+ * already matches the rendered template, no write occurs and the action is
+ * `unchanged`. When the file is absent the action is `created`. When the
+ * file exists with operator-authored differences the helper preserves it
+ * and returns `custom-workflow-skip` along with the rendered body so the
+ * bootstrap caller (or `/agents-update`) can offer a side-by-side diff.
+ *
+ * Network-free; safe to invoke under tests with a tmp `projectRoot`.
+ *
+ * Moved from `agents-bootstrap-github.js` to this module so it lives
+ * alongside `renderCiWorkflow` and `CI_WORKFLOW_RELATIVE_PATH`
+ * (Story #4048 B2 — dead-code deletion from the bootstrap entry point).
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - Repo root (must contain or accept
+ *   `.github/workflows/`).
+ * @param {object} [args.template] - Forwarded to `renderCiWorkflow`.
+ * @param {boolean} [args.write=true] - When `false`, the helper computes
+ *   the would-be action without touching disk. Used by the
+ *   bootstrap CLI's dry-run mode.
+ * @returns {{ action: 'created'|'unchanged'|'custom-workflow-skip',
+ *             path: string, rendered: string }}
+ */
+export function ensureCiWorkflow(args) {
+  const projectRoot = args.projectRoot;
+  const rendered = renderCiWorkflow(args.template);
+  const target = path.join(projectRoot, CI_WORKFLOW_RELATIVE_PATH);
+  if (!fs.existsSync(target)) {
+    if (args.write !== false) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, rendered, 'utf8');
+    }
+    return { action: 'created', path: target, rendered };
+  }
+  const existing = fs.readFileSync(target, 'utf8');
+  if (existing === rendered) {
+    return { action: 'unchanged', path: target, rendered };
+  }
+  return { action: 'custom-workflow-skip', path: target, rendered };
+}

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -112,8 +112,8 @@ export function buildManualInstructions({ stagePaths, baseBranch }) {
     `  git push -u origin ${baseBranch}`,
     '',
     'Story delivery runs in git worktrees that check out tracked files only,',
-    'so the .agents/ wiring MUST be committed before any /story-deliver or',
-    '/epic-deliver run — otherwise the worktree has no scripts and breaks.',
+    'so the .agents/ wiring MUST be committed before any /deliver or',
+    '/deliver run — otherwise the worktree has no scripts and breaks.',
   ].join('\n');
 }
 

package/.agents/scripts/lib/bootstrap/gh-preflight.js

@@ -38,14 +38,12 @@ const GH_SCOPES_UNREADABLE_NOTE =
  * Framework runtime deps the consumer must have installed in
  * `node_modules/` before this script reaches the dynamic
  * `config-resolver` import. `ajv` is the sentinel — if it cannot
- * resolve, the operator skipped `/agents-bootstrap-project` (or its
- * Step 2c/2d dependency-install never ran). The list mirrors the floor
- * in `agents-bootstrap-project.md` Step 2c; keep them in sync.
+ * resolve, the framework runtime dependencies are not installed.
  */
 const REQUIRED_RUNTIME_DEPS = Object.freeze(['ajv']);
 
 const RUNTIME_DEPS_HINT =
-  'Run `/agents-bootstrap-project` (or `node .agents/scripts/agents-bootstrap-project.js` when present) to merge the framework runtime dependencies into your package.json and install them, then re-run this command.';
+  'Run `mandrel init` (for a fresh project) or `npm install mandrel` (for an existing one) to install the framework runtime dependencies, then re-run this command.';
 
 /**
  * Default runner: synchronously execs `gh <args>` and returns
@@ -273,12 +271,12 @@ function classifyProjectScopes(scopeLine) {
 /**
  * Preflight the framework's runtime dependencies before dynamic-importing
  * `config-resolver.js` (which transitively pulls in `ajv` via
- * `config-settings-schema.js`). A fresh consumer who skipped
- * `/agents-bootstrap-project` will not have `ajv` installed, and the
- * raw `ERR_MODULE_NOT_FOUND` from the dynamic import is opaque. This
+ * `config-settings-schema.js`). A consumer who has not installed the
+ * framework runtime deps will not have `ajv` available, and the raw
+ * `ERR_MODULE_NOT_FOUND` from the dynamic import is opaque. This
  * preflight converts that into a {@link MissingRuntimeDepsError} that
- * names the missing packages and points the operator at the right
- * workflow.
+ * names the missing packages and points the operator at the correct
+ * remediation (`mandrel init` / `npm install mandrel`).
  *
  * The `resolver` seam lets tests inject a stub without touching the real
  * module graph; production uses `import.meta.resolve(specifier)`.

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -150,7 +150,17 @@ export function buildMutationManifest(ctx = {}) {
 
   // --- repo-config ------------------------------------------------------
   // Local repository configuration files the bootstrap seeds or extends.
+  // Also includes git-init, which is the most irreversible local mutation
+  // the bootstrap performs (B1 — uninstall ledger must record it).
   entries.push(
+    {
+      phaseGroup: PHASE_GROUPS.REPO_CONFIG,
+      target: rel('.git'),
+      action: 'run',
+      detail:
+        'Initialize the local git repository (git init + first commit) when absent. No-op when already a git repo.',
+      reversible: false,
+    },
     {
       phaseGroup: PHASE_GROUPS.REPO_CONFIG,
       target: rel('package.json'),
@@ -209,6 +219,16 @@ export function buildMutationManifest(ctx = {}) {
         ? `${ctx.answers.owner}/${ctx.answers.repo}`
         : 'the GitHub repository';
     entries.push(
+      {
+        // B1: GitHub repo creation is the most irreversible remote mutation —
+        // record it so the uninstall ledger always lists it.
+        phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
+        target: `${repoSlug} (repo)`,
+        action: 'create',
+        detail:
+          'Create the GitHub repository (gh repo create --source=. --push) when absent. No-op when already pushed.',
+        reversible: false,
+      },
       {
         phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
         target: `${repoSlug} labels`,
@@ -238,7 +258,7 @@ export function buildMutationManifest(ctx = {}) {
         target: `${repoSlug} merge methods`,
         action: 'configure',
         detail:
-          'Set the allowed pull-request merge methods to the framework stance.',
+          'Set the allowed pull-request merge methods to the framework stance (squash-only, auto-merge enabled).',
         reversible: false,
       },
     );

package/.agents/scripts/lib/bootstrap/merge-methods.js

@@ -17,10 +17,13 @@
  * No drift (live settings already match the target): no-op, returns
  * `{ status: 'unchanged' }`.
  *
- * Drift (any field differs from the target stance): routes the proposed
- * payload through `hitlConfirm`. On approval, PATCH is issued. On
- * decline or non-TTY (the gate returns false), the module returns
- * `{ status: 'skipped', reason: 'hitl-declined' }` without writing.
+ * Drift (any field differs from the target stance): when a `hitlConfirm`
+ * gate is supplied, the proposed payload routes through it — on approval
+ * the PATCH is issued; on decline the module returns
+ * `{ status: 'skipped', reason: 'hitl-declined' }` without writing (a loud
+ * decline, never silent). When NO gate is supplied (non-TTY, no operator
+ * present — Story #4045 A4), the framework stance is default-applied with
+ * an explicit log line.
  */
 
 export const TARGET_MERGE_METHODS = Object.freeze({
@@ -81,20 +84,32 @@ export async function applyMergeMethods({
     return { status: 'unchanged' };
   }
 
-  const approved =
-    typeof hitlConfirm === 'function'
-      ? await hitlConfirm({
-          summary:
-            'Repo merge-method settings diverge from the framework hands-off-pipeline stance.',
-          current,
-          proposed: target,
-        })
-      : false;
-  if (!approved) {
+  let approved;
+  if (typeof hitlConfirm === 'function') {
+    approved = await hitlConfirm({
+      summary:
+        'Repo merge-method settings diverge from the framework hands-off-pipeline stance.',
+      current,
+      proposed: target,
+    });
+    if (!approved) {
+      log(
+        '[bootstrap] Merge methods: HITL declined — leaving operator settings ' +
+          'untouched. Note: auto-merge will remain disabled until the merge-method ' +
+          'settings match the framework stance (allow_squash_merge: true, ' +
+          'allow_auto_merge: true, delete_branch_on_merge: true).',
+      );
+      return { status: 'skipped', reason: 'hitl-declined', diff };
+    }
+  } else {
+    // Non-TTY: no operator present to confirm. Default-apply the framework
+    // stance and log explicitly so the consequence is never silent.
     log(
-      '[bootstrap] Merge methods: drift detected; HITL declined / non-TTY — leaving operator settings untouched.',
+      '[bootstrap] Merge methods: non-TTY — applying framework stance automatically ' +
+        '(allow_squash_merge, allow_auto_merge, delete_branch_on_merge). ' +
+        'To opt out, pass a hitlConfirm gate or set github.mergeMethods overrides in .agentrc.json.',
     );
-    return { status: 'skipped', reason: 'hitl-declined', diff };
+    approved = true;
   }
 
   try {

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -1,6 +1,5 @@
 /**
- * bootstrap/project-bootstrap — deterministic port of the
- * `/agents-bootstrap-project` workflow (Story #2074, hard cutover).
+ * bootstrap/project-bootstrap — deterministic project bootstrap steps.
  *
  * Each exported `ensure*` function is one step of the bootstrap. Every step
  * is idempotent and additive — re-running on an already-bootstrapped clone
@@ -16,6 +15,8 @@ import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
 import { PHASE_GROUPS, previewMutationManifest } from './manifest.js';
 import { applyQualityBootstrap } from './quality-bootstrap.js';
@@ -61,8 +62,8 @@ export const GITIGNORE_BLOCKS = Object.freeze({
     block:
       '\n# Project-scoped MCP config carries secrets — keep out of git.\n.mcp.json\n',
   },
-  // Story #3894: `.env` holds real secrets (`/onboard` instructs operators to
-  // put `GITHUB_TOKEN` here). It MUST be ignored by default so a cold-start
+  // Story #3894: `.env` holds real secrets (`mandrel init` instructs operators
+  // to put `GITHUB_TOKEN` here). It MUST be ignored by default so a cold-start
   // provision never stages/pushes it. The pattern matches a bare `.env` (with
   // an optional trailing slash) but deliberately NOT `.env.example`, the
   // committed placeholder that `security-baseline.md` § Secrets Management
@@ -112,7 +113,23 @@ function writeJson(p, obj, fsImpl = fs) {
   fsImpl.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
 }
 
-/** Matches root `package.json` `engines.node`. */
+/**
+ * The minimum Node.js patch version mandrel requires.
+ *
+ * Rationale: `22.22.1` is the Node 22 LTS patch that ships with the
+ * `node:sqlite` built-in (`--experimental-sqlite` removed from flag
+ * requirement in 22.5.0, but the module stabilised at 22.22.1 per the
+ * Node 22 LTS changelog). Pinning to this patch prevents silent failures on
+ * older 22.x installs that lack the built-in. CI exercises `node-version: 22`
+ * which resolves to the latest 22.x (always ≥ 22.22.1 in the current GHA
+ * environment), so CI validates the contract without exercising the exact
+ * patch floor — the floor is enforced at install time, not in CI.
+ *
+ * Single source of truth: `registry.js` and any other consumer MUST import
+ * this constant rather than duplicating it.
+ *
+ * Matches `package.json` `engines.node` (`>=22.22.1 <25`).
+ */
 export const REQUIRED_NODE_FLOOR = '22.22.1';
 export const REQUIRED_NODE_CEILING_MAJOR = 25;
 
@@ -152,16 +169,18 @@ export function checkNodeVersion(version = process.versions.node) {
 
 /**
  * Detect the package manager based on lockfile presence. Defaults to
- * `npm` when no lock is found.
+ * `npm` when no lock is found (including the `null` case from the shared
+ * helper where no Node manifest exists at all).
+ *
+ * Delegates to the shared `detectPackageManager` helper
+ * (Story #4048 B3 — one implementation per concept).
  *
  * @param {string} projectRoot
  * @param {typeof fs} [fsImpl]
+ * @returns {'pnpm'|'yarn'|'npm'}
  */
 export function detectPackageManager(projectRoot, fsImpl = fs) {
-  if (fsImpl.existsSync(path.join(projectRoot, 'pnpm-lock.yaml')))
-    return 'pnpm';
-  if (fsImpl.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
-  return 'npm';
+  return detectPm(projectRoot, (p) => fsImpl.existsSync(p)) ?? 'npm';
 }
 
 /**
@@ -328,7 +347,9 @@ export async function validateAgentrc(ctx) {
   if (!fsImpl.existsSync(schemaModule)) {
     return { ok: false, errors: ['config-settings-schema.js not found'] };
   }
-  const mod = await import(`file://${schemaModule.replace(/\\/g, '/')}`);
+  // pathToFileURL handles Windows drive letters and percent-encoding
+  // correctly (same fix as commit 2e3d210b in lib/transpile.js).
+  const mod = await import(pathToFileURL(schemaModule).href);
   const validate = mod.getAgentrcValidator();
   const data = readJsonIfExists(
     path.join(ctx.projectRoot, '.agentrc.json'),

package/.agents/scripts/lib/codebase-snapshot.js

@@ -1,7 +1,7 @@
 /**
  * codebase-snapshot.js — Bounded structural view of the consumer repo.
  *
- * Story #2634 (sibling to #2635 spec-freshness). `/epic-plan` Phase 7
+ * Story #2634 (sibling to #2635 spec-freshness). `/plan` Phase 7
  * authors PRD + Tech Spec from documentation alone — `architecture.md`,
  * `data-dictionary.md`, `decisions.md`, `patterns.md`. When those docs
  * drift from the real source tree, the Architect persona cites modules

package/.agents/scripts/lib/config/explain.js

@@ -113,7 +113,7 @@ const KEY_MEANINGS = Object.freeze({
 
   // planning.*
   'planning.maxTickets':
-    'Upper bound on tickets a single /epic-plan run may create.',
+    'Upper bound on tickets a single /plan run may create.',
   'planning.context.maxBytes':
     'Byte budget for the planning-context payload before summary mode kicks in.',
   'planning.context.summaryMode':

package/.agents/scripts/lib/config/runners.js

@@ -29,7 +29,7 @@ export const DEFAULT_DECOMPOSER = Object.freeze({
  * host has adequate parallel-agent quota, operators should raise
  * `delivery.deliverRunner.concurrencyCap` — wall-clock time falls
  * proportionally to the extra concurrency. The safe default is a tuning
- * knob, not a performance ceiling. See `epic-deliver.md` § Phase 2b and
+ * knob, not a performance ceiling. See `helpers/deliver-epic.md` § Phase 2b and
  * `agentrc-reference.json` `delivery.deliverRunner.concurrencyCap` for details.
  *
  * **`verifyConcurrencyCap`** (Epic #3019 Tech Spec §1.4 / Story #3024) is a
@@ -44,7 +44,7 @@ const DEFAULT_DELIVER_RUNNER = Object.freeze({
 });
 
 /**
- * Default auto-fix loop ceilings for /epic-deliver Phase 4 (epic-audit)
+ * Default auto-fix loop ceilings for /deliver Phase 4 (epic-audit)
  * and Phase 5 (code-review). Operators override via
  * `delivery.epicAudit.*` and `delivery.codeReview.*` in `.agentrc.json`
  * (Story #2611, Epic #2586).

package/.agents/scripts/lib/config/runtime.js

@@ -77,7 +77,7 @@ export function resolveWorkingPath({
 
 /**
  * One-shot environment-aware runtime resolution. Returns the trio of runtime
- * signals consumed across `/epic-deliver`: whether worktree isolation is on
+ * signals consumed across `/deliver`: whether worktree isolation is on
  * for this process, the session id for claim labels, and whether we're in a
  * Claude Code web session. Each signal also records its **source** so the
  * `story-init` startup log can name why the value is what it is.

package/.agents/scripts/lib/config/sync-agentrc.js

@@ -69,7 +69,7 @@ export function syncAgentrc(opts) {
       status: 'missing-config',
       changes: [],
       errors: [
-        `No .agentrc.json at ${configPath}. Run /agents-bootstrap-project first.`,
+        `No .agentrc.json at ${configPath}. Run \`mandrel init\` (new project) or \`node .agents/scripts/bootstrap.js\` to create it.`,
       ],
       configPath,
       wrote: false,

package/.agents/scripts/lib/config/temp-paths.js

@@ -44,7 +44,7 @@
  * parent of `git rev-parse --git-common-dir`) rather than `process.cwd()`.
  * Without this, a story child that `cd`s into `.worktrees/story-<id>/` before
  * calling `story-phase.js` would append `story.heartbeat` records to
- * `<worktree>/temp/epic-N/lifecycle.ndjson`, while the `/epic-deliver` host
+ * `<worktree>/temp/epic-N/lifecycle.ndjson`, while the `/deliver` host
  * (running from the main checkout) reads the main-checkout copy — so the
  * idle-watchdog never sees heartbeats and the Epic-lease guard silently
  * reclaims live foreign claims (the audit-#3513 bug class). Anchoring the
@@ -335,7 +335,7 @@ export const epicPerfReportPath = (eid, config) =>
 
 /**
  * `temp/epic-<eid>/epic-perf-report.json` — canonical JSON snapshot of
- * the `epic-perf-report` payload persisted at /epic-deliver close
+ * the `epic-perf-report` payload persisted at /deliver close
  * (Epic #3019 / Story #3029 / Task #3040). When present alongside the
  * `epic-perf-report` structured comment, the report is discoverable
  * from the file system without round-tripping the ticketing provider,

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -203,7 +203,7 @@ const MERGE_WATCH_SCHEMA = {
 };
 
 /**
- * `delivery.epicAudit` — bounded-retry knobs for /epic-deliver Phase 4
+ * `delivery.epicAudit` — bounded-retry knobs for /deliver Phase 4
  * (epic-audit). `maxFixAttempts` caps how many times the auto-fix loop
  * retries a single finding (Story #2611, Epic #2586). `maxFixScopeFiles`
  * caps how many files a single auto-fix may touch before escalating to
@@ -237,7 +237,7 @@ const CI_DELIVERY_SCHEMA = {
 // Story #2899 (Epic #2880) — `delivery.preflight.*` thresholds consumed
 // by `epic-deliver-preflight.js`. When any value is exceeded the CLI
 // surfaces a breach in its envelope and the workflow flips the Epic to
-// `agent::blocked` (see /epic-deliver Phase 1 prelude).
+// `agent::blocked` (see /deliver Phase 1 prelude).
 const PREFLIGHT_SCHEMA = {
   type: 'object',
   properties: {

package/.agents/scripts/lib/config-settings-schema-quality.js

@@ -102,7 +102,7 @@ export const QUALITY_SCHEMA = {
 
 /**
  * `delivery.codeReview` — sibling to `delivery.epicAudit`. Same bounded
- * retry + scope cap, applied to /epic-deliver Phase 5 (code-review).
+ * retry + scope cap, applied to /deliver Phase 5 (code-review).
  */
 export const CODE_REVIEW_SCHEMA = {
   type: 'object',