mandrel 1.60.0 → 1.62.0

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/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