mandrel 1.60.0 → 1.61.0

package/.agents/docs/workflows.md

@@ -25,11 +25,11 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (27)
+## Commands (26)
 
 | Command | Description |
 | --- | --- |
-| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update` (resolve newest non-major 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 leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
+| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `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 leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
@@ -51,7 +51,6 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/git-merge-pr` | Analyze, validate, resolve conflicts, and merge a given pull request by number. |
 | `/git-pr-all` | Stage all outstanding changes, commit, push to a feature branch, and open a pull request with native auto-merge enabled. |
 | `/git-push` | Commit all outstanding changes then push to the remote repository. |
-| `/onboard` | Guided first-run onboarding for a freshly installed Mandrel. Detects the consumer stack, offers to scaffold any missing docsContextFiles, runs `mandrel doctor` as a readiness gate, and hands off to a started /plan. The whole path is designed to take about 15 minutes from a clean checkout to a planned Epic. |
 | `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
 | `/qa-assist` | Human-led QA assist loop — ingest one operator observation, enrich it with repro + root-cause (file:line) + a coverage verdict, ask clarifying questions when it is ambiguous, and append a redacted ledger item to a persistent, resumable rolling session under temp/qa/ |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |

package/.agents/runtime-deps.json

@@ -7,12 +7,12 @@
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
     "string-argv": "^0.3.2",
-    "typescript": ">=5.0.0",
     "typhonjs-escomplex": "^0.1.0"
   },
   "optionalDependencies": {
     "@commitlint/load": "^21.0.0",
     "chokidar": "^5.0.0",
-    "jscpd": "^4.0.0"
+    "jscpd": "^4.0.0",
+    "typescript": ">=5.0.0"
   }
 }

package/.agents/scripts/README.md

@@ -87,7 +87,7 @@ when Stryker itself fails to run.
 - [`/docs/architecture.md`](../../docs/architecture.md) — system
   architecture; the "Key Scripts" section lists the standard
   orchestration entrypoints.
-- [`/docs/quality-gates.md`](../../docs/quality-gates.md) — coverage,
+- [`.agents/docs/quality-gates.md`](../docs/quality-gates.md) — coverage,
   CRAP, and maintainability baselines + floors.
 - `package.json` `scripts` — the canonical list of standard CLIs
   (`test`, `verify`, `coverage:update`, …).

package/.agents/scripts/agents-bootstrap-github.js

@@ -15,13 +15,7 @@
  * @see docs/v5-implementation-plan.md Sprint 1C
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
 import { applyBranchProtection } from './lib/bootstrap/branch-protection.js';
-import {
-  CI_WORKFLOW_RELATIVE_PATH,
-  renderCiWorkflow,
-} from './lib/bootstrap/ci-workflow-template.js';
 import {
   compareSemver,
   MIN_GH_VERSION,
@@ -55,7 +49,7 @@ import {
 import { createProvider } from './lib/provider-factory.js';
 
 const PROJECTS_DOC_POINTER =
-  'See docs/project-board.md for the manual Projects V2 setup checklist.';
+  'Configure the board views manually in the GitHub Projects UI.';
 
 /**
  * Detect that an error is a not-found / 404 signal across the surfaces
@@ -266,106 +260,6 @@ async function ensureProjectFields(provider, project, log) {
   return fields;
 }
 
-/**
- * Create or additively-merge branch protection on `baseBranch` (typically
- * `main`) so the `delivery.quality.prGate.checks` suite is required
- * before merge. Behaviour rules:
- *
- *   - `enforceBranchProtection: false` → skip, log the opt-out, return a
- *     `{ status: 'skipped' }` summary.
- *   - `prGate.checks` empty or absent → skip with a clear log, since there
- *     is nothing to enforce.
- *   - Existing protection rule → preserve every existing required-check
- *     context and append only the missing prGate names.
- *   - No existing rule → create a fresh one carrying just the prGate
- *     contexts plus minimal sensible defaults (strict status checks).
- *
- * Errors (insufficient scopes, repo permission denied, etc.) are logged
- * and return a `{ status: 'failed' }` summary so the bootstrap CLI
- * surfaces a non-fatal warning rather than aborting the entire run —
- * matching how the project-board provisioning steps degrade.
- */
-async function ensureMainBranchProtection(
-  provider,
-  { baseBranch, prGate },
-  log,
-) {
-  if (prGate?.enforceBranchProtection === false) {
-    log(
-      `[bootstrap] Branch protection on '${baseBranch}': skipped (delivery.quality.prGate.enforceBranchProtection=false).`,
-    );
-    return { status: 'skipped', reason: 'opt-out' };
-  }
-
-  const checkNames = (prGate?.checks ?? [])
-    .map((c) => c?.name)
-    .filter((n) => typeof n === 'string' && n.length > 0);
-  if (checkNames.length === 0) {
-    log(
-      `[bootstrap] Branch protection on '${baseBranch}': skipped (no prGate.checks configured).`,
-    );
-    return { status: 'skipped', reason: 'no-checks' };
-  }
-
-  try {
-    const result = await provider.setBranchProtection(baseBranch, {
-      contexts: checkNames,
-    });
-    const verb = result.created ? 'Created' : 'Updated';
-    const addedSuffix = result.added.length
-      ? ` (added: ${result.added.join(', ')})`
-      : ' (all required checks already present)';
-    log(
-      `[bootstrap] Branch protection on '${baseBranch}': ${verb} rule${addedSuffix}.`,
-    );
-    return { status: result.created ? 'created' : 'merged', ...result };
-  } catch (err) {
-    log(
-      `[bootstrap] Branch protection on '${baseBranch}': failed — ${err.message}. Proceeding without it.`,
-    );
-    return { status: 'failed', reason: err.message };
-  }
-}
-
-/**
- * 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`.
- *
- * @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 };
-}
-
 /**
  * Run the idempotent bootstrap sequence.
  *
@@ -397,6 +291,7 @@ export function ensureCiWorkflow(args) {
  *   github?: object,
  *   baseBranch?: string,
  *   githubAdminApproved?: boolean,
+ *   isTTY?: boolean,
  * }} [opts] - `githubAdminApproved` MUST be `true` for any GitHub mutation to
  *   occur; any other value (absent / `false`) is treated as "not approved"
  *   and the run is a verified no-op.
@@ -463,12 +358,12 @@ export async function runBootstrap(config, opts = {}) {
   // Consumer-facing bootstrap promotes the framework's CI-gates-only
   // stance: branch protection with enforce_admins + 0-approval-count and
   // the squash-only merge-method allowlist. Behavior-shifting drift on
-  // either step routes through the HITL confirm gate — non-TTY runs abort
-  // with a clear stderr message rather than silently apply.
+  // branch protection routes through the HITL confirm gate — non-TTY runs
+  // abort with a clear stderr message rather than silently apply. The
+  // merge-method step differs by design (Story #4045 A4): non-TTY without an
+  // assume override default-applies the framework stance with an explicit
+  // log line (see mergeMethodsHitlConfirm below).
   //
-  // The legacy `ensureMainBranchProtection` helper is preserved (re-
-  // exported below) so the Epic #1142 Story #1157 contract tests stay
-  // green; `applyBranchProtection` is its consumer-parity successor.
   // Post-reshape: bootstrap reads from the new `project` + `github` blocks
   // exclusively. The legacy "agent settings" opt was removed in Epic #2880.
   const projectCfg = opts.project ?? config.project ?? {};
@@ -493,10 +388,22 @@ export async function runBootstrap(config, opts = {}) {
     hitlConfirm,
     log,
   });
+
+  // Merge-methods gate (Story #4045 A4): under non-TTY without an explicit
+  // assume override there is no operator to consult, and the default HITL
+  // gate declines every non-TTY prompt — which would make applyMergeMethods'
+  // documented non-TTY default-apply branch unreachable. Skip the gate in
+  // that case so the merge-method stance default-applies with its explicit
+  // log line. Interactive runs (and explicit --assume-yes/--assume-no, and
+  // injected gates) keep the loud confirm/decline behaviour.
+  const stdoutIsTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+  const mergeMethodsHitlConfirm =
+    opts.hitlConfirm ??
+    (stdoutIsTTY || opts.assumeYes || opts.assumeNo ? hitlConfirm : undefined);
   const mergeMethods = await applyMergeMethods({
     provider,
     settings,
-    hitlConfirm,
+    hitlConfirm: mergeMethodsHitlConfirm,
     log,
   });
 
@@ -539,8 +446,9 @@ async function main() {
   }
 
   // Preflight runtime deps before the dynamic config-resolver import so
-  // a green-field consumer who skipped `/agents-bootstrap-project` gets
-  // a workflow hint instead of a raw `ERR_MODULE_NOT_FOUND`.
+  // a consumer who hasn't installed framework runtime deps yet gets a
+  // clear hint (`run mandrel init` or `npm install mandrel`) instead of
+  // a raw `ERR_MODULE_NOT_FOUND`.
   try {
     await preflightRuntimeDeps();
   } catch (err) {
@@ -569,7 +477,6 @@ async function main() {
     process.exit(1);
   }
 
-  const installWorkflows = process.argv.includes('--install-workflows');
   // Epic #1235 Story 5 — flags let CI / non-interactive callers pin the
   // HITL gate's answer deterministically. The bootstrap is non-interactive
   // by default in non-TTY contexts (the gate returns false and aborts);
@@ -594,7 +501,6 @@ async function main() {
 
   try {
     const result = await runBootstrap(config, {
-      installWorkflows,
       project: config.project,
       github: config.github,
       assumeYes,
@@ -617,12 +523,10 @@ async function main() {
   }
 }
 
-// Re-export internal helpers for test consumers (no production caller imports them).
 // Re-export the gh-preflight surface so existing test consumers can keep
 // importing it from this module after the Story #3349 split.
 export {
   compareSemver,
-  ensureMainBranchProtection,
   isApiAccessNotFoundError,
   MIN_GH_VERSION,
   parseGhVersion,

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

@@ -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/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/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/detect-package-manager.js

@@ -0,0 +1,72 @@
+/**
+ * detect-package-manager — shared lockfile-probe helper (Story #4048 B3).
+ *
+ * Five independent copies of this lockfile probe existed across the codebase:
+ *   - `lib/cli/update.js#detectPackageManager`
+ *   - `lib/bootstrap/project-bootstrap.js#detectPackageManager`
+ *   - `lib/runtime-deps/preflight.js#detectPackageManager`
+ *   - `lib/onboard/detect-stack.js#detectPackageManager`
+ *   - `lib/worktree/node-modules-strategy.js#selectInstallCommand` (inline)
+ *
+ * This module is the single authoritative implementation. It uses the
+ * strictest semantics from the prior copies: detects `bun` in addition to
+ * pnpm/yarn/npm, returns `null` when the directory has no Node manifest at
+ * all (not even `package.json`), and optionally reports `workspaceRoot` for
+ * pnpm (the `update.js` caller's unique requirement).
+ *
+ * All callers must handle `null` explicitly — it means the directory carries
+ * no recognizable Node toolchain, so callers that need a concrete fallback
+ * should coerce: `detectPm(root) ?? 'npm'`.
+ *
+ * Injectable seams: the `exists` parameter replaces `fs.existsSync` so
+ * callers can drive the function with an in-memory fixture in unit tests.
+ *
+ * Builtins only — this module runs before third-party packages are
+ * guaranteed to be present and is also imported from the worktree and
+ * runtime-deps preflight guards.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Detect the package manager from lockfile and manifest presence.
+ *
+ * Precedence: `pnpm-lock.yaml` > `yarn.lock` > `bun.lockb` >
+ * `package-lock.json` > `package.json` (npm without a lockfile yet) > `null`.
+ *
+ * @param {string} root - Absolute directory to probe (consumer project root).
+ * @param {(p: string) => boolean} [exists=fs.existsSync] - Path existence probe.
+ * @returns {'pnpm'|'yarn'|'bun'|'npm'|null}
+ */
+export function detectPackageManager(root, exists = fs.existsSync) {
+  if (exists(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (exists(path.join(root, 'yarn.lock'))) return 'yarn';
+  if (exists(path.join(root, 'bun.lockb'))) return 'bun';
+  if (exists(path.join(root, 'package-lock.json'))) return 'npm';
+  if (exists(path.join(root, 'package.json'))) return 'npm';
+  return null;
+}
+
+/**
+ * Detect the package manager and whether the directory is a pnpm workspace
+ * root. The `workspaceRoot` flag is `true` only for pnpm when
+ * `pnpm-workspace.yaml` is present alongside the lockfile — the signal that
+ * `pnpm add` must carry `-w` to target the workspace-root manifest.
+ *
+ * Used by `lib/cli/update.js` which needs both pieces of information to
+ * construct the correct install command.
+ *
+ * @param {string} root - Absolute directory to probe.
+ * @param {(p: string) => boolean} [exists=fs.existsSync] - Path existence probe.
+ * @returns {{ packageManager: 'pnpm'|'yarn'|'bun'|'npm', workspaceRoot: boolean }}
+ */
+export function detectPackageManagerWithWorkspace(
+  root,
+  exists = fs.existsSync,
+) {
+  const pm = detectPackageManager(root, exists) ?? 'npm';
+  const workspaceRoot =
+    pm === 'pnpm' && exists(path.join(root, 'pnpm-workspace.yaml'));
+  return { packageManager: pm, workspaceRoot };
+}

package/.agents/scripts/lib/errors/index.js

@@ -52,10 +52,10 @@ export class GhVersionError extends Error {
 /**
  * Raised when a framework runtime dependency (e.g. `ajv`) cannot be
  * resolved from the consumer's `node_modules/`. Surfaces during the
- * `/agents-bootstrap-github` preflight to redirect operators to
- * `/agents-bootstrap-project`, which is the workflow responsible for
- * merging and installing the framework's runtime deps. `missing` carries
- * the package specifiers that failed to resolve so the CLI can render an
+ * `agents-bootstrap-github` preflight to redirect operators to the
+ * correct remediation (`mandrel init` for new projects, or
+ * `npm install mandrel` for existing ones). `missing` carries the
+ * package specifiers that failed to resolve so the CLI can render an
  * actionable hint.
  */
 export class MissingRuntimeDepsError extends Error {