mandrel 1.60.0 → 1.61.0

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

@@ -164,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/runtime-deps/preflight.js

@@ -12,7 +12,7 @@
  */
 
 import fs from 'node:fs';
-import path from 'node:path';
+import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 
 /**
  * Resolve each required package via the injected `resolve` seam and collect
@@ -38,17 +38,17 @@ export function checkRuntimeDeps({ required, resolve }) {
 /**
  * Detect the consumer's package manager from lockfile presence so the
  * remediation message names the right install command. Defaults to `npm`.
- * Mirrors `bootstrap/project-bootstrap.js#detectPackageManager` but stays
- * decoupled (and seam-injectable) so the preflight imports nothing heavy.
+ *
+ * Delegates to the shared `detectPackageManager` helper
+ * (Story #4048 B3 — one implementation per concept). The `exists` seam
+ * is forwarded directly; `null` (no manifest) coerces to `'npm'`.
  *
  * @param {string} root
  * @param {(p: string) => boolean} [exists=fs.existsSync]
  * @returns {'pnpm'|'yarn'|'npm'}
  */
 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';
-  return 'npm';
+  return detectPm(root, exists) ?? 'npm';
 }
 
 /** Map a detected package manager to its install command. */

package/.agents/scripts/lib/worktree/node-modules-strategy.js

@@ -20,6 +20,7 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { detectPackageManager } from '../detect-package-manager.js';
 
 function sleepSync(ms) {
   if (!Number.isFinite(ms) || ms <= 0) return;
@@ -110,10 +111,12 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
   if (strategy === 'pnpm-store') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
-  if (fsLike.existsSync(path.join(wtPath, 'pnpm-lock.yaml'))) {
+  // Shared lockfile probe (Story #4048 B3 — one implementation per concept).
+  const pm = detectPackageManager(wtPath, (p) => fsLike.existsSync(p)) ?? 'npm';
+  if (pm === 'pnpm') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
-  if (fsLike.existsSync(path.join(wtPath, 'yarn.lock'))) {
+  if (pm === 'yarn') {
     return { cmd: 'yarn', args: ['install', '--frozen-lockfile'] };
   }
   return { cmd: 'npm', args: ['ci'] };

package/.agents/workflows/agents-update.md

@@ -1,7 +1,7 @@
 ---
 description: >-
   npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update`
-  (resolve newest non-major version → install → re-materialize `.agents/` →
+  (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
@@ -23,7 +23,7 @@ description: >-
 
 ## Overview
 
-`/agents-update` advances the consumer repo to the newest non-major
+`/agents-update` advances the consumer repo to the newest published
 `mandrel` release, re-materializes `.agents/`, and regenerates the
 flat `.claude/commands/` tree (invoked as `/<name>`) against the new workflow
 set — then reconciles the consumer's own config, harness allowlist, and
@@ -40,11 +40,10 @@ The upgrade contract:
 - **CI honours the committed lockfile.** Consumer CI runs `npm ci` against
   the committed `package-lock.json`, so it installs exactly the version the
   lockfile pins — never "whatever the registry's newest is today."
-- **The major axis is gated.** `mandrel update` refuses to cross a major
-  boundary (e.g. `1.x → 2.0`) without an explicit `--major`, printing a
-  pointer to `docs/upgrade-major.md` and exiting non-zero without touching
-  anything. Routine minor/patch bumps within the current major are never
-  gated.
+- **Majors apply like any other bump.** Mandrel ships hard cutovers
+  (`.agents/rules/git-conventions.md` § Contract Cutovers), so a major
+  crossing is applied directly — the surfaced changelog is the migration
+  guide.
 - **The CLI never commits.** The npm bump rewrites `package.json` /
   `package-lock.json` and leaves them **staged on disk** for operator review;
   `mandrel update` performs no `git add` / `git commit`. Staging and
@@ -55,8 +54,7 @@ The upgrade contract:
   authoritative writer of the generated flat command tree
   (`.claude/commands/`) is
   [`sync-claude-commands.js`](../scripts/sync-claude-commands.js), which
-  prepends the `<!-- AUTO-GENERATED -->` header that
-  `/agents-bootstrap-project` parity-checks. Nothing else copies workflow
+  prepends the `<!-- AUTO-GENERATED -->` header. Nothing else copies workflow
   files.
 
 > **Persona**: `devops-engineer` · **Skills**:
@@ -71,7 +69,7 @@ mandrel update --dry-run
 mandrel update
 ```
 
-`mandrel update --dry-run` resolves the newest non-major version and prints
+`mandrel update --dry-run` resolves the newest published version and prints
 the ordered step plan (`npm-update → runSync → runMigrations → doctor →
 surface changelog`) without invoking any effectful seam — no dependency bump,
 no sync, no migrations, no doctor, nothing written. Read the planned target
@@ -82,23 +80,19 @@ version before applying.
 1. **Resolve target** — the newest published `mandrel` version (via
    the daily freshness cache in `temp/version-check.json`) and the currently
    installed version.
-2. **Major gate** — if the newest version crosses a major boundary, the run
-   declines, prints the `docs/upgrade-major.md` pointer, and exits non-zero
-   without touching anything. Re-run with `--major` only after reviewing that
-   runbook.
-3. **No-op short-circuit** — already on the newest version ⇒ prints
+2. **No-op short-circuit** — already on the newest version ⇒ prints
    `Already up to date` and exits 0.
-4. **Install** — bumps the dependency (default
+3. **Install** — bumps the dependency (default
    `npm install mandrel@<target>`; pass
    `--install-cmd "<pm> <args>"` for a pnpm/yarn workspace). The lockfile
    change is left **staged** for review; the CLI never commits.
-5. **runSync** — re-materializes `.agents/` from the freshly installed
+4. **runSync** — re-materializes `.agents/` from the freshly installed
    payload, which also regenerates the flat `.claude/commands/` tree via
    `sync-claude-commands.js`.
-6. **runMigrations** — applies any version-keyed migration steps for the
+5. **runMigrations** — applies any version-keyed migration steps for the
    crossed range.
-7. **doctor** — runs the check registry to verify the resulting install.
-8. **Surface changelog** — prints the `docs/CHANGELOG.md` section(s) covering
+6. **doctor** — runs the check registry to verify the resulting install.
+7. **Surface changelog** — prints the `docs/CHANGELOG.md` section(s) covering
    the applied range `(current, target]`. Capture this output — Step 4
    reconciles the consumer's own instructions against it.
 
@@ -371,12 +365,6 @@ no-op.
 
 ## Troubleshooting
 
-- **`a newer MAJOR version (X.0.0) is available`** — `mandrel update`
-  hit the major gate and exited non-zero without touching anything. A
-  major crossing is a breaking upgrade. Read `docs/upgrade-major.md`,
-  then re-run `mandrel update --major` only after you have absorbed the
-  migration steps that runbook describes.
-
 - **`doctor reported failures: …`** — the dependency bumped and `.agents/`
   re-materialized, but a doctor check failed (and the run exited
   non-zero). Run `mandrel doctor` for the per-check remedies. The lockfile
@@ -402,9 +390,6 @@ no-op.
 - **Idempotent.** A second `mandrel update` immediately after a successful
   run resolves the same newest version, hits the no-op short-circuit, and
   prints `Already up to date` — exit 0, nothing bumped.
-- **Non-major only by default.** The major axis is gated behind an explicit
-  `--major`; routine minor/patch bumps within the current major apply
-  without a gate.
 - **No auto-commit.** `mandrel update` leaves the lockfile bump staged on
   disk and never runs git. The operator reviews the surfaced changelog and
   writes the commit message (Step 5) — the CLI does not know whether the

package/.agents/workflows/helpers/agents-sync-config.md

@@ -68,8 +68,9 @@ node .agents/scripts/sync-agentrc.js
 The script:
 
 1. Reads `.agentrc.json` from the working directory (`--cwd <path>` to
-   override). When the file is missing, prints a pointer to
-   `/agents-bootstrap-project` and exits 1.
+   override). When the file is missing, prints an error asking the
+   operator to run `mandrel init` (new project) or
+   `node .agents/scripts/bootstrap.js` (existing project) and exits 1.
 2. Validates the parsed config against the framework AJV schema
    (`getAgentrcValidator()`). On any failure, prints a single-line error
    list and exits 1 — the operator must fix the typo / missing required

package/.agents/workflows/plan.md

@@ -58,19 +58,61 @@ commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is now
 an **internal branch switch** inside this router: same skills, same
 helpers, no command hop and no operator re-entry.
 
+## First-run preflight
+
+Before routing to a path helper, run a **first-run preflight** to catch
+common day-0 issues that would silently degrade every downstream task.
+
+### When the preflight fires
+
+The preflight runs when **any** of these is true:
+
+1. One or more `project.docsContextFiles` entries are absent under the
+   configured `docsRoot`.
+2. One or more present `docsContextFiles` still carry the
+   `<!-- MANDREL:STUB -->` marker (i.e. they are un-edited scaffolded stubs).
+3. The last `mandrel doctor` verdict cached in `temp/doctor-result.json`
+   records `"verdict": "unready"`. An **absent** cache file is no signal —
+   doctor may simply never have run; only an explicit recorded unready
+   verdict fires this signal.
+
+### Preflight procedure
+
+1. **Detect the condition.** Check the three signals above. When none is
+   true, skip the preflight entirely — no operator interaction, no delay.
+2. **Offer to flesh out docs.** Summarize the found condition to the
+   operator (e.g. "3 docsContextFiles are missing" or "architecture.md
+   still carries the stub marker") and ask:
+   > *Do you want to flesh out these docs from the codebase before planning?
+   > [y/N]*
+3. **On acceptance.** Walk through each affected file, read relevant
+   codebase artifacts (source files, README, existing docs), and write real
+   content to replace the stub. Then re-run `mandrel doctor` to confirm
+   readiness. If doctor passes, proceed to routing.
+4. **On decline.** Log one line:
+   > *[plan] Proceeding with degraded doc context — planning quality may be
+   > reduced.*
+   Then continue to the normal routing procedure below.
+
+The preflight is **never a hard stop** — declining continues planning with a
+noted degradation. It only fires when there is a genuine signal (missing or
+stubbed docs, or an unready doctor verdict).
+
 ## Procedure
 
 1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
    `--body` must be present; anything else is a usage error naming the four
    forms. A `--body` invocation routes to the story path (no triage).
-2. **Triage (idea path only).** Run the
+2. **First-run preflight.** Run the preflight above. Skip when all signals
+   are clear (healthy project).
+3. **Triage (idea path only).** Run the
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
    seed. Record the verdict in chat (one line).
-3. **Delegate.** Read the selected path helper **in full** and execute it
+4. **Delegate.** Read the selected path helper **in full** and execute it
    from its entry phase, forwarding the absorbed flags. The helper's phase
    numbering, HITL gates, and scripts are unchanged — this router adds no
    phase content.
-4. **Internal returns.** When a path helper would historically have handed
+5. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.
 

package/README.md

@@ -25,37 +25,31 @@ provisions both as part of a cold start (`git init` → `gh repo create --push`
   provisioning, grant the scope with `gh auth refresh -s project` (re-auth
   in the browser when prompted) before running `bootstrap.js`.
 
-See the [Compatibility matrix](docs/upgrade-major.md#compatibility-matrix)
-section of `docs/upgrade-major.md` for the supported OS / Node /
-package-manager combinations.
-
 ## Quickstart
 
-The canonical cold-start path is one command, then two slash
-commands inside Claude Code:
+The canonical cold-start path is one command, then one slash command:
 
 ```bash
-npx mandrel init        # install mandrel → sync → prompt → bootstrap
+npx mandrel init        # install mandrel → sync → prompt → bootstrap → onboarding tail → /plan handoff
 ```
 
 ```text
 # then, inside Claude Code (commands load from .claude/commands/):
-/onboard            # guided first run: stack detect → docs → doctor → /plan
 /plan          # ideation -> PRD/Tech Spec -> Epic with child Stories
 ```
 
 `npx mandrel init` installs `mandrel` (when `./.agents/` is absent),
 materializes it via `mandrel sync`, then asks whether to **configure now**
-(option 1 → runs `node .agents/scripts/bootstrap.js`, forwarding any flags you
-pass) or stop at **just the files** (option 2 → re-run `mandrel init` any time
-to configure). Pass `--assume-yes` for a non-interactive run that proceeds
-straight to configure (and forwards the flag to bootstrap). When `./.agents/`
-is already present (you ran `npm install mandrel` first), `init` skips the
-install/sync and goes straight to the prompt. `/onboard` then walks you from a
-clean checkout to a planned Epic (stack detection, docs scaffolding, a
-`mandrel doctor` readiness gate, and a started `/plan`). Once you have a
-planned Epic, deliver it with `/deliver <id>` (wave loop → validation →
-review → retro → open PR).
+(option 1 → runs `bootstrap.js`, then the onboarding tail: stack detection,
+docs scaffolding offer, `mandrel doctor` readiness gate, and a `/plan`
+handoff) or stop at **just the files** (option 2 → re-run `mandrel init`
+any time to configure). Pass `--assume-yes` for a non-interactive run that
+proceeds straight to configure (and forwards the flag to bootstrap). When
+`./.agents/` is already present (you ran `npm install mandrel` first), `init`
+skips the install/sync and goes straight to the prompt. Once `mandrel init`
+completes, you land at the `/plan` handoff — run `/plan --idea "<seed>"` to
+start planning your first Epic, then deliver it with `/deliver <id>` (wave
+loop → validation → review → retro → open PR).
 
 ### Manual equivalent
 
@@ -108,29 +102,23 @@ npx mandrel update
 
 1. **Resolve** the newest published version (a `npm view mandrel
    version` registry probe) and the currently installed version.
-2. **Major gate** — if the newest version crosses a major boundary
-   (e.g. `1.x → 2.0`), the command declines, prints a pointer to
-   [`docs/upgrade-major.md`](docs/upgrade-major.md), and exits non-zero
-   without touching anything. Re-run with `--major` to apply it.
-3. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
-4. **Install** the target version with the project's package manager —
+2. **No-op short-circuit** — already on the newest version ⇒ nothing to do.
+3. **Install** the target version with the project's package manager —
    auto-detected from the lockfile (`pnpm-lock.yaml` ⇒ pnpm, `yarn.lock` ⇒
    yarn, otherwise npm) so the bump lands in your real lockfile. The
    dependency bump is left **staged** on disk — `mandrel update` performs no
    `git add` / `git commit`, so you review and commit the lockfile change
    yourself.
-5. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
-6. **Migrate** — apply version-keyed migration steps for the crossed range.
-7. **Doctor** — run the check registry to verify the resulting install.
-8. **Surface** the target changelog section.
+4. **Sync** — re-materialize `./.agents/` from the freshly installed payload.
+5. **Migrate** — apply version-keyed migration steps for the crossed range.
+6. **Doctor** — run the check registry to verify the resulting install.
+7. **Surface** the target changelog section.
 
 ### Flags
 
 - `--dry-run` — print the resolved target version and the ordered step
   plan, then exit. No dependency is bumped, no file is written, no seam
   runs.
-- `--major` — apply a major-version crossing that the gate would otherwise
-  refuse. Review [`docs/upgrade-major.md`](docs/upgrade-major.md) first.
 - `--install-cmd "<cmd>"` — override the auto-detected install command. The
   package manager is normally detected from your lockfile
   (`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,