mandrel 1.59.0 → 1.61.0

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

@@ -205,7 +205,7 @@ const GITHUB_SCHEMA = {
 };
 
 // ---------------------------------------------------------------------------
-// planning.* — inputs to /epic-plan
+// planning.* — inputs to /plan
 // ---------------------------------------------------------------------------
 
 /**
@@ -224,7 +224,7 @@ const PLANNING_CONTEXT_SCHEMA = {
 
 /**
  * Story #2634 — `planning.codebaseSnapshot` controls the structural
- * view of the consumer repo threaded into `/epic-plan` Phase 7 spec
+ * view of the consumer repo threaded into `/plan` Phase 7 spec
  * authoring. Absent / partial entries resolve to defaults inside
  * `lib/codebase-snapshot.js#resolveSnapshotConfig` — the schema only
  * enforces shape (correct enum value, well-formed glob arrays).
@@ -287,7 +287,7 @@ const PLANNING_SCHEMA = {
 };
 
 // ---------------------------------------------------------------------------
-// delivery.* — /epic-deliver + story-deliver consume. The full block of
+// delivery.* — /deliver + story-deliver consume. The full block of
 // per-key sub-schemas lives in `config-settings-schema-delivery.js` (refs
 // #3457); DELIVERY_SCHEMA is imported above and referenced unchanged below.
 // ---------------------------------------------------------------------------

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/duplicate-search.js

@@ -1,7 +1,7 @@
 /**
  * duplicate-search.js — Cross-Epic Duplicate Detection
  *
- * Used by `/epic-plan` Phase 2 (s-plan-ideation) to surface open Epics
+ * Used by `/plan` Phase 2 (s-plan-ideation) to surface open Epics
  * whose scope overlaps with a sharpened one-pager before a new Epic is
  * created. Returns ranked candidates with an overlap score and URL so
  * the host LLM can pause for HITL confirmation.

package/.agents/scripts/lib/dynamic-workflow/capability.js

@@ -26,7 +26,7 @@
  *
  * Both paths MUST emit the identical per-lens report contract
  * (`{{auditOutputDir}}/<lens>-results.md`), so downstream consumers
- * (`/epic-deliver` Phase 4 epic-audit, `audit-to-stories`) are agnostic to
+ * (`/deliver` Phase 4 epic-audit, `audit-to-stories`) are agnostic to
  * which path produced it.
  *
  * ## Why this is capability-degradation, not a contract shim

package/.agents/scripts/lib/epic-plan-clarity.js

@@ -10,7 +10,7 @@
  * Verdict rule: `clear` requires **both** (a) ≥ 4 of 5 canonical sections
  * present, **and** (b) the **Acceptance Criteria** section present. The
  * Acceptance-Criteria requirement is load-bearing: a downstream
- * `/epic-deliver` start gate and the close-time acceptance-spec reconciler
+ * `/deliver` start gate and the close-time acceptance-spec reconciler
  * both assume the Epic carries acceptance criteria, so a gate that passed an
  * Epic with no Acceptance Criteria (the pre-Story-#3910 `≥ 4 of 5` behaviour)
  * advertised a clarity guarantee it did not provide. AC is now a required

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -1,5 +1,5 @@
 /**
- * epic-plan-ideation.js — Phase 3/4 helpers for /epic-plan
+ * epic-plan-ideation.js — Phase 3/4 helpers for /plan
  *
  * Phase 3: render an Epic body from a sharpened ideation one-pager
  * using the canonical template at `.agents/templates/epic-from-idea.md`.

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 {

package/.agents/scripts/lib/feedback-loop/memory-freshness.js

@@ -1,5 +1,5 @@
 /**
- * memory-freshness.js — walker + verifier for the `/epic-plan` Phase 0
+ * memory-freshness.js — walker + verifier for the `/plan` Phase 0
  * memory-freshness pre-flight. Story #2557 / Epic #2547. Tech Spec #2550.
  *
  * Walks every `.md` file under a memory directory (typically

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -1,6 +1,6 @@
 /**
  * prior-feedback-fetcher.js — gh-CLI-backed fetcher for open meta feedback
- * issues that feed the `/epic-plan` Phase 0 planner context.
+ * issues that feed the `/plan` Phase 0 planner context.
  *
  * Story #2554 / Epic #2547. Tech Spec #2550 specifies that the fetcher MUST
  * return open issues carrying the `meta::framework-gap` and

package/.agents/scripts/lib/findings/classify-finding.js

@@ -51,7 +51,7 @@ export const FINDING_CLASSES = Object.freeze([
 /**
  * Class → label-set routing table. Each class maps to exactly one label set.
  * `tooling-dx` is the framework-gap path: it carries `meta::framework-gap` so
- * the `/epic-plan` Phase 0 feedback fetcher surfaces it to the planner.
+ * the `/plan` Phase 0 feedback fetcher surfaces it to the planner.
  */
 const CLASS_TO_LABELS = Object.freeze({
   'product-bug': [FOCUS_LABELS.PRODUCT],

package/.agents/scripts/lib/findings/promote-finding.js

@@ -5,8 +5,8 @@
  * tail of the exploratory-QA Triage path: once an operator has dispositioned a
  * session's ledger items (see `.agents/schemas/qa-ledger.schema.json` and
  * `lib/qa/qa-session.js`), the still-untriaged backlog is clustered and each
- * cluster is promoted to a follow-up ticket — a single Story (via `/story-plan`)
- * for a tight, one-deliverable cluster, or an Epic (via `/epic-plan --idea`) for
+ * cluster is promoted to a follow-up ticket — a single Story (via `/plan`)
+ * for a tight, one-deliverable cluster, or an Epic (via `/plan --idea`) for
  * a broad cluster that spans multiple coverage surfaces. Each contributing
  * ledger item then has the resulting `routedTo` issue link written back onto it
  * so a resume run sees the item as filed rather than re-promoting it.
@@ -23,7 +23,7 @@
  * Pure orchestration: **no network I/O lives here.** Every GitHub side-effect
  * (issue search, ticket creation) flows through INJECTED PORTS so the unit test
  * runs with no network. Production wires the ports to the GitHub provider /
- * `/story-plan` / `/epic-plan` surfaces; tests pass in-memory stubs.
+ * `/plan` / `/plan` surfaces; tests pass in-memory stubs.
  */
 
 import { fingerprintFinding, routeFinding } from './route-finding.js';
@@ -40,8 +40,8 @@ export const PROMOTION_TARGETS = Object.freeze({
 
 /**
  * A cluster of more than this many distinct coverage surfaces is broad enough
- * to warrant an Epic (`/epic-plan --idea`) rather than a single Story
- * (`/story-plan`). One or two surfaces is a tight, single-deliverable cluster.
+ * to warrant an Epic (`/plan --idea`) rather than a single Story
+ * (`/plan`). One or two surfaces is a tight, single-deliverable cluster.
  */
 const EPIC_COVERAGE_THRESHOLD = 2;
 
@@ -159,8 +159,8 @@ export function clusterLedgerItems(items) {
 /**
  * Decide a cluster's promotion target. A cluster that spans more than
  * {@link EPIC_COVERAGE_THRESHOLD} distinct coverage surfaces is broad enough to
- * warrant an Epic (`/epic-plan --idea`); otherwise it is a single-deliverable
- * Story (`/story-plan`).
+ * warrant an Epic (`/plan --idea`); otherwise it is a single-deliverable
+ * Story (`/plan`).
  *
  * @param {{ coverages: string[] }} cluster
  * @returns {'story'|'epic'}
@@ -233,7 +233,7 @@ function routedToLink(issue, kind) {
  *      shared `routeFinding` against existing Issues (via the injected search
  *      port). This dedups against work already filed.
  *   2. On a `new` decision, open the follow-up ticket through the injected
- *      `createStory` (`/story-plan`) or `createEpic` (`/epic-plan --idea`) port,
+ *      `createStory` (`/plan`) or `createEpic` (`/plan --idea`) port,
  *      chosen by {@link targetForCluster}. On any other decision, link back to
  *      the matched Issue rather than creating a duplicate.
  *   3. Stamp the resolved `routedTo` link onto every contributing ledger item
@@ -250,9 +250,9 @@ function routedToLink(issue, kind) {
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
  *   Optional semantic candidate search, forwarded to `routeFinding`.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createStory
- *   Opens a single Story (`/story-plan`) for a tight cluster.
+ *   Opens a single Story (`/plan`) for a tight cluster.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createEpic
- *   Opens an Epic (`/epic-plan --idea`) for a broad cluster.
+ *   Opens an Epic (`/plan --idea`) for a broad cluster.
  * @returns {Promise<{
  *   promotions: Array<{
  *     clusterKey: string,

package/.agents/scripts/lib/label-constants.js

@@ -76,7 +76,6 @@ export function isValidTransition(fromState, toState) {
 
 export const TYPE_LABELS = {
   EPIC: 'type::epic',
-  FEATURE: 'type::feature',
   STORY: 'type::story',
 };
 
@@ -104,7 +103,7 @@ export const CONTEXT_LABELS = {
 export const CONTEXT_ACCEPTANCE_SPEC = CONTEXT_LABELS.ACCEPTANCE_SPEC;
 
 /**
- * Acceptance-axis labels for opt-out signalling on Stories and Features that
+ * Acceptance-axis labels for opt-out signalling on Stories that
  * intentionally have no acceptance-spec coverage. Separate namespace from
  * `context::` because it expresses absence rather than a linked context
  * ticket.
@@ -120,7 +119,7 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
  * loop). `meta::framework-gap` is applied to issues that surface a defect or
  * missing capability in the framework itself; `meta::consumer-improvement`
  * is applied to issues that surface improvements to a consumer project
- * (workflow tweaks, ergonomic asks, doc polish). The `/epic-plan` Phase 0
+ * (workflow tweaks, ergonomic asks, doc polish). The `/plan` Phase 0
  * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
  * issues carrying either label and surfaces them to the planner so retro
  * signals are routed into durable substrates rather than lost in chat.
@@ -133,7 +132,7 @@ export const META_LABELS = {
 /**
  * Planning-axis labels (Epic #2880 F7). Currently scoped to the
  * `planning::healthcheck-waived` operator-applied waiver, which is the
- * documented escape hatch for the `/epic-plan` Phase 10 readiness
+ * documented escape hatch for the `/plan` Phase 10 readiness
  * healthcheck (`epic-plan-healthcheck.js`). The persist half of
  * `epic-plan-decompose.js` refuses to flip an Epic to `agent::ready`
  * when the healthcheck returned `ok: false` unless this label is

package/.agents/scripts/lib/label-taxonomy.js

@@ -53,15 +53,10 @@ export const LABEL_TAXONOMY = [
     color: LABEL_COLORS.TYPE,
     description: 'Epic-level work item',
   },
-  {
-    name: TYPE_LABELS.FEATURE,
-    color: LABEL_COLORS.TYPE,
-    description: 'Feature under an Epic',
-  },
   {
     name: TYPE_LABELS.STORY,
     color: LABEL_COLORS.TYPE,
-    description: 'User story under a Feature',
+    description: 'User story under an Epic',
   },
 
   // Agent State
@@ -75,7 +70,7 @@ export const LABEL_TAXONOMY = [
     name: AGENT_LABELS.READY,
     color: LABEL_COLORS.AGENT,
     description:
-      'Parking state — frozen dispatch manifest exists; awaiting local /epic-deliver',
+      'Parking state — frozen dispatch manifest exists; awaiting local /deliver',
   },
   {
     name: AGENT_LABELS.EXECUTING,
@@ -120,7 +115,7 @@ export const LABEL_TAXONOMY = [
     description: 'Acceptance Specification (Gherkin scenarios)',
   },
 
-  // Acceptance axis — explicit opt-out signal for Stories/Features that
+  // Acceptance axis — explicit opt-out signal for Stories that
   // intentionally have no acceptance-spec coverage.
   {
     name: ACCEPTANCE_LABELS.N_A,
@@ -169,8 +164,8 @@ export const STATUS_FIELD_OPTIONS = ['Todo', 'In Progress', 'Done'];
  *
  * GitHub's GraphQL surface does not expose a public `createProjectV2View`
  * mutation, so bootstrap creates these via the REST Projects V2 views
- * endpoint best-effort and falls back to documenting the filter strings in
- * `docs/project-board.md` when the endpoint is unavailable.
+ * endpoint best-effort; when the endpoint is unavailable the views must be
+ * configured manually in the GitHub Projects UI.
  *
  * @type {Array<{ name: string, filter: string, groupBy: string,
  *   layout?: 'table'|'board'|'roadmap' }>}

package/.agents/scripts/lib/onboard/detect-stack.js

@@ -1,11 +1,12 @@
 /**
- * detect-stack.js — Consumer stack detection for `/onboard`
+ * detect-stack.js — Consumer stack detection for `mandrel init`
  *
  * Inspects a consumer repository root and reports the package manager,
  * test runner, and primary language it can infer from on-disk signals
  * (lockfiles, `package.json` contents, and source-file extensions). The
- * guided `/onboard` flow (Feature #3514) uses this to tell the operator
- * what it found before scaffolding missing `docsContextFiles`.
+ * `mandrel init` configure-path tail (Feature #3514, Story #4045) uses
+ * this to tell the operator what it found before scaffolding missing
+ * `docsContextFiles`.
  *
  * The detection functions are seam-injectable: each takes an injected
  * filesystem facade (`exists` / `readFile` / `listExtensions`) so they
@@ -19,6 +20,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 
 /**
  * Filesystem facade. Pure detection logic talks to disk only through
@@ -163,18 +165,16 @@ export const defaultFsFacade = {
  * when no lockfile is found but a `package.json` exists, and `null` when
  * the repo has no Node manifest at all.
  *
+ * Delegates to the shared `detectPackageManager` helper
+ * (Story #4048 B3 — one implementation per concept). The `fsFacade.exists`
+ * seam is forwarded directly.
+ *
  * @param {string} root - Repository root.
  * @param {FsFacade} [fsFacade=defaultFsFacade]
  * @returns {'pnpm'|'yarn'|'bun'|'npm'|null}
  */
 export function detectPackageManager(root, fsFacade = defaultFsFacade) {
-  const { exists } = fsFacade;
-  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;
+  return detectPm(root, fsFacade.exists);
 }
 
 /**

package/.agents/scripts/lib/onboard/init-tail.js

@@ -0,0 +1,218 @@
+/**
+ * init-tail.js — post-bootstrap onboarding tail for `mandrel init`.
+ *
+ * Called by `mandrel init` after `bootstrap.js` completes successfully on
+ * the "configure now" path. Sequences the four phases that walk an operator
+ * from a freshly bootstrapped project to a ready-to-plan workspace:
+ *
+ *   Phase 1 — Detect the consumer stack (lib/onboard/detect-stack.js).
+ *   Phase 2 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
+ *   Phase 3 — Run `mandrel doctor` as a readiness gate.
+ *   Phase 4 — Print the /plan handoff next-step text.
+ *
+ * The whole tail is idempotent: re-running after an already-onboarded project
+ * re-detects, re-checks, and re-offers scaffolding without duplicating stubs
+ * (the scaffolder only writes genuinely absent files) and without modifying
+ * anything (doctor is read-only).
+ *
+ * Injectable seams: `runDoctor`, `stdout`, `confirmScaffold`, and `isTTY`
+ * allow the unit suite to drive every branch without real I/O.
+ *
+ * Story #4045 (refs #4045).
+ */
+
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { detectStack } from './detect-stack.js';
+import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
+
+// ---------------------------------------------------------------------------
+// Phase text constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Text printed at the end of the init tail to hand the operator off to /plan.
+ *
+ * @type {string}
+ */
+export const PLAN_HANDOFF_TEXT =
+  '\n✅  Mandrel is ready. Start your first Epic:\n\n' +
+  '    /plan --idea "<one-line description of what you want to build>"\n\n' +
+  'Or, if you already have a `type::epic` Issue open:\n\n' +
+  '    /plan <epicId>\n';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a stack-detection result as a human-readable report line.
+ *
+ * @param {{ packageManager: string|null, testRunner: string|null, primaryLanguage: string|null }} stack
+ * @returns {string}
+ */
+function formatStackReport(stack) {
+  const pm = stack.packageManager ?? '(unknown)';
+  const runner = stack.testRunner ?? '(unknown)';
+  const lang = stack.primaryLanguage ?? '(unknown)';
+  return (
+    '\n[init] Stack detection:\n' +
+    `  Package manager : ${pm}\n` +
+    `  Test runner     : ${runner}\n` +
+    `  Primary language: ${lang}\n`
+  );
+}
+
+/**
+ * Format a list of missing docs as a human-readable report (no prompt).
+ *
+ * @param {string[]} missing
+ * @returns {string}
+ */
+function formatMissingList(missing) {
+  if (missing.length === 0) return '';
+  const list = missing.map((f) => `  • ${f}`).join('\n');
+  return (
+    '\n[init] The following docsContextFiles are missing — agents load\n' +
+    'these before every task:\n' +
+    `${list}\n`
+  );
+}
+
+/** Prompt text shown only on a TTY when asking to scaffold. */
+const SCAFFOLD_PROMPT = '\nScaffold stubs now? [y/N]: ';
+
+/**
+ * Synchronous y/N read from stdin (fd 0). Returns `false` on any read error
+ * or when the user enters something other than `y` / `yes`.
+ *
+ * @returns {boolean}
+ */
+function syncConfirm() {
+  let answer = '';
+  try {
+    const buf = fs.readFileSync(0, 'utf8');
+    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+  } catch {
+    answer = '';
+  }
+  return answer === 'y' || answer === 'yes';
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the post-bootstrap init tail.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.root] - Project root (defaults to `process.cwd()`).
+ * @param {(msg: string) => void} [opts.stdout] - Output sink (defaults to
+ *   `process.stdout.write` bound to `process.stdout`).
+ * @param {() => boolean} [opts.confirmScaffold] - Read the operator's y/N
+ *   answer for the scaffold offer. Returns `true` to scaffold. In non-TTY
+ *   contexts defaults to `false` (no write without operator confirmation).
+ * @param {(extraArgs?: string[]) => { status: number|null }} [opts.runDoctor]
+ *   - Run `mandrel doctor`; injectable for tests.
+ * @param {boolean} [opts.isTTY] - Whether stdin is a TTY (defaults to
+ *   `Boolean(process.stdin.isTTY)`).
+ * @returns {{
+ *   stack: { packageManager: string|null, testRunner: string|null, primaryLanguage: string|null },
+ *   scaffoldResult: object,
+ *   doctorStatus: number,
+ *   ok: boolean,
+ * }}
+ */
+export function runInitTail({
+  root,
+  stdout = (s) => process.stdout.write(s),
+  confirmScaffold,
+  runDoctor,
+  isTTY,
+} = {}) {
+  const projectRoot = root ?? process.cwd();
+  const tty = isTTY ?? Boolean(process.stdin.isTTY);
+
+  // When confirmScaffold is explicitly injected (e.g. from tests), always use
+  // it. When using the default, auto-decline on non-TTY so the scaffolder
+  // never writes unattended.
+  const usingDefaultConfirm = confirmScaffold == null;
+  const confirmFn = confirmScaffold ?? (() => syncConfirm());
+
+  // Default doctor runner — spawns `mandrel doctor` via the locally installed
+  // bin; inherits stdio so the report streams to the terminal.
+  const mandrelBin = path.join(
+    projectRoot,
+    'node_modules',
+    'mandrel',
+    'bin',
+    'mandrel.js',
+  );
+  const defaultRunDoctor = (extraArgs = []) =>
+    defaultSpawnSync(process.execPath, [mandrelBin, 'doctor', ...extraArgs], {
+      cwd: projectRoot,
+      stdio: 'inherit',
+    });
+
+  const doctorFn = runDoctor ?? defaultRunDoctor;
+
+  // --- Phase 1: Detect the stack -------------------------------------------
+  let stack;
+  try {
+    stack = detectStack(projectRoot);
+  } catch {
+    stack = { packageManager: null, testRunner: null, primaryLanguage: null };
+  }
+  stdout(formatStackReport(stack));
+
+  // --- Phase 2: Offer to scaffold missing docsContextFiles -----------------
+  const preview = scaffoldDocs({ root: projectRoot, write: false });
+  let scaffoldResult = preview;
+
+  if (preview.missing.length === 0) {
+    stdout('\n[init] All docsContextFiles are present.\n');
+  } else {
+    stdout(formatMissingList(preview.missing));
+    // On non-TTY without an injected confirm, auto-decline so the scaffolder
+    // never writes unattended. On TTY (or with an injected confirm seam), show
+    // the prompt and consult the confirm function.
+    const canPrompt = tty || !usingDefaultConfirm;
+    if (canPrompt) stdout(SCAFFOLD_PROMPT);
+    const accepted = canPrompt ? confirmFn() : false;
+    if (accepted) {
+      scaffoldResult = scaffoldDocs({ root: projectRoot, write: true });
+      if (scaffoldResult.created.length > 0) {
+        stdout(
+          `[init] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
+            `Each carries a \`${STUB_MARKER}\` marker — replace placeholder ` +
+            'content before planning.\n',
+        );
+      }
+    } else {
+      stdout(
+        '[init] Scaffolding declined. docsContextFiles are still missing — ' +
+          'agents will load degraded context until you create them.\n',
+      );
+    }
+  }
+
+  // --- Phase 3: Readiness gate (mandrel doctor) ----------------------------
+  stdout('\n[init] Running mandrel doctor…\n');
+  const doctorResult = doctorFn();
+  const doctorStatus = doctorResult?.status ?? 1;
+
+  if (doctorStatus !== 0) {
+    stdout(
+      '\n[init] ❌  Doctor check failed. Resolve the remedies above and\n' +
+        'then re-run: mandrel init\n',
+    );
+    return { stack, scaffoldResult, doctorStatus, ok: false };
+  }
+
+  // --- Phase 4: Handoff to /plan -------------------------------------------
+  stdout(PLAN_HANDOFF_TEXT);
+  return { stack, scaffoldResult, doctorStatus, ok: true };
+}

package/.agents/scripts/lib/onboard/scaffold-docs.js

@@ -24,6 +24,15 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_ROOT = path.resolve(__dirname, '../../..');
 const DOCS_TEMPLATE_DIR = path.join(AGENT_ROOT, 'templates', 'docs');
 
+/**
+ * Deterministic marker written into every scaffolded stub. The `/plan`
+ * first-run preflight (and any tooling that wants to detect unedited stubs)
+ * keys off this exact string — do not change it without a hard cutover.
+ *
+ * @type {string}
+ */
+export const STUB_MARKER = '<!-- MANDREL:STUB -->';
+
 /**
  * Build the generic placeholder stub for a docsContextFile that has no
  * dedicated template. Derives a human-readable title from the filename.
@@ -39,8 +48,9 @@ function genericStub(fileName) {
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
   return (
+    `${STUB_MARKER}\n` +
     `# ${title}\n\n` +
-    '> **Stub generated by guided onboarding.** This file is one of the\n' +
+    '> **Stub generated by `mandrel init`.** This file is one of the\n' +
     '> `project.docsContextFiles` mandatory-reads — agents load it before\n' +
     '> every task. Replace this placeholder with real content.\n'
   );
@@ -48,7 +58,9 @@ function genericStub(fileName) {
 
 /**
  * Read the dedicated template body for a docsContextFile, or fall back to the
- * generic stub when no template ships for that name.
+ * generic stub when no template ships for that name. Either path prepends the
+ * {@link STUB_MARKER} so the `/plan` first-run preflight can detect un-edited
+ * stubs regardless of whether a dedicated template was used.
  *
  * @param {string} fileName
  * @param {import('node:fs')} fsImpl
@@ -57,7 +69,10 @@ function genericStub(fileName) {
 function stubContentFor(fileName, fsImpl) {
   const templatePath = path.join(DOCS_TEMPLATE_DIR, fileName);
   if (fsImpl.existsSync(templatePath)) {
-    return fsImpl.readFileSync(templatePath, 'utf8');
+    const body = fsImpl.readFileSync(templatePath, 'utf8');
+    // Prepend the marker only when absent (idempotent; the template files
+    // themselves are kept marker-free so they read cleanly as documentation).
+    return body.startsWith(STUB_MARKER) ? body : `${STUB_MARKER}\n${body}`;
   }
   return genericStub(fileName);
 }

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -152,7 +152,7 @@ export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
 /**
  * Build the per-criterion acceptance-eval signal payload for the retro /
  * feedback substrate. Carries which acceptance items needed rework and the
- * round count so `/epic-plan` Phase 0 feedback fetch and the retro can
+ * round count so `/plan` Phase 0 feedback fetch and the retro can
  * surface acceptance churn. PII-free by construction — it carries only
  * acceptance-item indices, verdicts, and the terminal decision.
  *