mandrel 1.62.0 → 1.64.0

package/docs/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.63.0...mandrel-v1.64.0) (2026-06-14)
+
+
+### Added
+
+* **bootstrap:** polish init/bootstrap preflight + UX copy, drop unused stack detection ([#4113](https://github.com/dsj1984/mandrel/issues/4113)) ([c775418](https://github.com/dsj1984/mandrel/commit/c77541846508047f1101158e67ac2a59c8577101))
+* **cli:** mandrel init banner + Welcome prompt, sync 'Installed' wording ([#4109](https://github.com/dsj1984/mandrel/issues/4109)) ([c516d39](https://github.com/dsj1984/mandrel/commit/c516d3903080c5e6838e833dbddf20ab0d4af1cd))
+
+
+### Fixed
+
+* 2-tier Stories un-initializable: composeStoryBody omits `Epic: #N` when epicId === parentId, blocking the /deliver wave loop ([#4102](https://github.com/dsj1984/mandrel/issues/4102)) ([#4103](https://github.com/dsj1984/mandrel/issues/4103)) ([2431cf6](https://github.com/dsj1984/mandrel/commit/2431cf6e7330b9cf98a7f54b60ba8d3df46f635c))
+* **init:** set terminal:false on readline confirms so the prompt is not erased (refs [#4106](https://github.com/dsj1984/mandrel/issues/4106)) ([#4108](https://github.com/dsj1984/mandrel/issues/4108)) ([e31e767](https://github.com/dsj1984/mandrel/commit/e31e767a6d69519faf120bf08ce55d0272a46416))
+* **init:** use node:readline for confirm prompts so init does not hang (refs [#4106](https://github.com/dsj1984/mandrel/issues/4106)) ([#4107](https://github.com/dsj1984/mandrel/issues/4107)) ([2b56d08](https://github.com/dsj1984/mandrel/commit/2b56d0851f403fd97c86e6097fd9d62446ee2257))
+
+## [1.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.62.0...mandrel-v1.63.0) (2026-06-13)
+
+
+### Added
+
+* **decompose:** set native GitHub blocked-by dependencies from Story depends_on graph (refs [#4067](https://github.com/dsj1984/mandrel/issues/4067)) ([#4068](https://github.com/dsj1984/mandrel/issues/4068)) ([1799659](https://github.com/dsj1984/mandrel/commit/1799659a84b06555c9caa1193aec59113c943b78))
+
+
+### Fixed
+
+* **audit-architecture:** add Impact severity field to Detailed Findings (refs [#4085](https://github.com/dsj1984/mandrel/issues/4085)) ([#4096](https://github.com/dsj1984/mandrel/issues/4096)) ([d72c109](https://github.com/dsj1984/mandrel/commit/d72c109195955eff70d7d926abb36a88e32d3f6e))
+* fix stale architecture.md/README docs and broaden the import-cycle gate scan root ([#4071](https://github.com/dsj1984/mandrel/issues/4071)) ([#4090](https://github.com/dsj1984/mandrel/issues/4090)) ([2e97b45](https://github.com/dsj1984/mandrel/commit/2e97b45f9ed43398dc703dd735394c7483329033))
+
+
+### Performance
+
+* **decompose:** parallelize blocked-by edge creation with bounded concurrentMap (refs [#4082](https://github.com/dsj1984/mandrel/issues/4082)) ([#4094](https://github.com/dsj1984/mandrel/issues/4094)) ([a9f38da](https://github.com/dsj1984/mandrel/commit/a9f38da2d44941a164865a6ad291c2da01ee4ed6))
+
+
+### Changed
+
+* `parseProviderFindings` is a CC-30 ternary thicket ([#4074](https://github.com/dsj1984/mandrel/issues/4074)) ([#4089](https://github.com/dsj1984/mandrel/issues/4089)) ([5ed693c](https://github.com/dsj1984/mandrel/commit/5ed693c3325c05a36251b859be5873ab0378031c))
+* extract shared createDriftDetector skeleton for CRAP and MI drift detectors (refs [#4076](https://github.com/dsj1984/mandrel/issues/4076)) ([#4091](https://github.com/dsj1984/mandrel/issues/4091)) ([e8a81a8](https://github.com/dsj1984/mandrel/commit/e8a81a82307a12c3d6e58275d4c4554b07659f4f))
+* **scripts:** reduce CC of CLI orchestration bodies below the must-fix band (refs [#4075](https://github.com/dsj1984/mandrel/issues/4075)) ([#4093](https://github.com/dsj1984/mandrel/issues/4093)) ([53519de](https://github.com/dsj1984/mandrel/commit/53519de7968e59c08479c886ca3713f53f5c039d))
+* **signals:** hoist shared detector validation preamble into common.js (refs [#4077](https://github.com/dsj1984/mandrel/issues/4077)) ([#4092](https://github.com/dsj1984/mandrel/issues/4092)) ([2f6fe7b](https://github.com/dsj1984/mandrel/commit/2f6fe7b103c208fbd3ea4cfedf63d2a7aa412e24))
+* **single-story-init:** inject spawnSync boundary into makeGhRunner (refs [#4073](https://github.com/dsj1984/mandrel/issues/4073)) ([#4087](https://github.com/dsj1984/mandrel/issues/4087)) ([8fae355](https://github.com/dsj1984/mandrel/commit/8fae35568523e3997d8f7e79580c0cc8e0625072))
+* **story-body:** extract per-section sub-parsers from parse() (refs [#4072](https://github.com/dsj1984/mandrel/issues/4072)) ([#4088](https://github.com/dsj1984/mandrel/issues/4088)) ([aa9e472](https://github.com/dsj1984/mandrel/commit/aa9e47204728da0ab4f547927af251fce6a85b69))
+
 ## [1.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.61.0...mandrel-v1.62.0) (2026-06-12)
 
 

package/lib/cli/init.js

@@ -50,9 +50,10 @@
  *                  for `./.agents/` in the cwd
  *   - `runStep`  — `(cmd, args) => { status }`; runs one install/sync/bootstrap
  *                  step. Defaults to a `spawnSync` runner with `stdio: inherit`.
- *   - `confirm`  — `() => boolean`; reads the operator's yes/no answer (true =
- *                  configure now). Defaults to a synchronous stdin readline
- *                  prompt with yes as the default.
+ *   - `confirm`  — `() => boolean | Promise<boolean>`; reads the operator's
+ *                  yes/no answer (true = configure now). Defaults to a
+ *                  `node:readline` stdin prompt (awaited) with yes as the
+ *                  default.
  *   - `stdout`   — `(s) => void`; defaults to `process.stdout.write`.
  *   - `isTTY`    — boolean; defaults to `process.stdin.isTTY`.
  *   - `exit`     — `(code) => void`; defaults to `process.exit`.
@@ -66,6 +67,7 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 
 // Lazily resolved at runtime so cold-start `npx mandrel init` (where
@@ -119,11 +121,29 @@ const BOOTSTRAP_SCRIPT = path.join('.agents', 'scripts', 'bootstrap.js');
 const SYNC_BIN = path.join('node_modules', PACKAGE_NAME, 'bin', 'mandrel.js');
 
 const PROMPT_TEXT =
-  'The Mandrel .agents package has been copied to your directory.\n' +
-  'Would you like to begin the interactive process to setup your local and ' +
-  'github environments now? [Y/n]: ';
+  '\n' +
+  'Welcome to Mandrel!\n\n' +
+  'Check .agents/README.md for more quick start instructions, flag options, and documentation.\n\n' +
+  'Begin interactive setup? [Y/n]: ';
 
-const FILES_ONLY_HINT = 'Configure any time with: npx mandrel init\n';
+const FILES_ONLY_HINT = 'Setup any time with: npx mandrel init\n';
+
+// ASCII banner printed once at the very top of `mandrel init`, before any
+// install/sync output streams to the terminal. Paste multi-line ASCII art
+// between the fences below. `String.raw` keeps backslashes literal so the art
+// renders exactly as pasted — the only characters to avoid inside are a
+// literal backtick and the `${` sequence. The leading/trailing blank lines
+// frame the art in the terminal.
+const BANNER = String.raw`
+
+   ______  ___             _________           ______
+   ___   |/  /_____ _____________  /______________  /
+   __  /|_/ /_  __ '/_  __ \  __  /__  ___/  _ \_  /
+   _  /  / / / /_/ /_  / / / /_/ / _  /   /  __/  /
+   /_/  /_/  \__,_/ /_/ /_/\__,_/  /_/    \___//_/
+____________________________________________________
+
+`;
 
 // On win32, `npm` resolves to a `.cmd` shim that Node refuses to spawn without
 // a shell after the CVE-2024-27980 hardening; mirror update.js and set
@@ -175,7 +195,7 @@ function buildBootstrapArgs(argv, assumeYes) {
  *   argv?: string[],
  *   exists?: (relPath: string) => boolean,
  *   runStep?: (cmd: string, args: string[]) => { status: number | null },
- *   confirm?: () => boolean,
+ *   confirm?: () => boolean | Promise<boolean>,
  *   stdout?: (s: string) => void,
  *   isTTY?: boolean,
  *   afterBootstrap?: (root: string) => Promise<{ ok?: boolean } | void> | { ok?: boolean } | void,
@@ -260,7 +280,7 @@ export async function planInit({
     proceed = false;
   } else {
     stdout(PROMPT_TEXT);
-    proceed = confirm();
+    proceed = await confirm();
   }
 
   if (proceed) {
@@ -338,23 +358,44 @@ function defaultRunStep(cmd, args) {
 }
 
 /**
- * Default `confirm` seam — synchronous yes/no prompt. Reads one line from stdin
- * and normalizes it to a boolean; any input other than an explicit "no"
- * (`n`/`no`, case-insensitive) — including bare Enter — defaults to `true`
- * (configure), matching the `[Y/n]` convention where yes is the default.
+ * Default `confirm` seam — yes/no prompt read via `node:readline` (mirrors the
+ * prompt mechanism in `bootstrap.js`). Returns on Enter and never blocks
+ * waiting for EOF the way `fs.readFileSync(0)` did — that EOF-blocking read hung
+ * `mandrel init` on an interactive TTY. Any input other than an explicit "no"
+ * (`n`/`no`, case-insensitive) — including bare Enter — resolves to `true`
+ * (configure), matching the `[Y/n]` convention where yes is the default. The
+ * prompt text is written by `planInit` via `stdout`, so the question string
+ * passed here is empty.
  *
- * @returns {boolean}
+ * `terminal: false` is **load-bearing**, not cosmetic: with terminal mode on
+ * (the default when stdout is a TTY) readline emits cursor-control escapes
+ * (`\x1b[1G\x1b[0J` — column-1 + erase-to-end-of-screen) when it takes over the
+ * line, which **erases the `[Y/n]:` prompt already written via `stdout`** — the
+ * operator then sees only the first prompt line and a dead-looking cursor.
+ * Disabling terminal mode leaves the pre-written prompt intact and reads the
+ * line via the TTY's own cooked-mode echo. `createInterface` is injectable so a
+ * test can assert this option is set (regression guard).
+ *
+ * @param {{ createInterface?: typeof readline.createInterface }} [opts]
+ * @returns {Promise<boolean>}
  */
-function defaultConfirm() {
-  let answer = '';
+export async function defaultConfirm({
+  createInterface = readline.createInterface,
+} = {}) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
   try {
-    const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+    const answer = (await rl.question('')).trim().toLowerCase();
+    return answer !== 'n' && answer !== 'no';
   } catch {
-    // No readable line (e.g. stdin closed) → fall through to the default.
-    answer = '';
+    // No readable line (e.g. stdin closed) → default to yes (configure).
+    return true;
+  } finally {
+    rl.close();
   }
-  return answer !== 'n' && answer !== 'no';
 }
 
 /**
@@ -376,6 +417,10 @@ export default async function run(argv = []) {
     return;
   }
 
+  // Banner is the very first output — before the install + sync steps that
+  // planInit kicks off — so it greets the operator on a cold start.
+  process.stdout.write(BANNER);
+
   const result = await planInit({
     argv,
     exists: defaultExists,

package/lib/cli/sync.js

@@ -242,7 +242,7 @@ export function runSync({
       write(`would prune ${path.join('.agents', rel)}\n`);
     }
     write(
-      `✅  Dry run: ${payloadFiles.length} file(s) would be materialized, ${stale.length} stale file(s) would be pruned from ./.agents/\n`,
+      `✅  Dry run: ${payloadFiles.length} file(s) would be installed, ${stale.length} stale file(s) would be pruned from ./.agents/\n`,
     );
     return {
       copied: 0,
@@ -275,10 +275,10 @@ export function runSync({
 
   if (staleFiles.length > 0) {
     write(
-      `✅  Materialized ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,
+      `✅  Installed ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,
     );
   } else {
-    write(`✅  Materialized ${payloadFiles.length} file(s) into ./.agents/\n`);
+    write(`✅  Installed ${payloadFiles.length} file(s) into ./.agents/\n`);
   }
   return {
     copied: payloadFiles.length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",

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

@@ -1,300 +0,0 @@
-/**
- * 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
- * `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
- * are unit-testable in isolation against an in-memory fixture, mirroring
- * the style of `lib/runtime-deps/preflight.js#detectPackageManager`. The
- * default facade reads the real filesystem so callers can point it at a
- * sample-repo fixture directory.
- *
- * Story #3520 (refs #3520).
- */
-
-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
- * this seam so tests can drive it with an in-memory fixture.
- *
- * @typedef {object} FsFacade
- * @property {(p: string) => boolean} exists - Path existence probe.
- * @property {(p: string) => string|null} readFile - UTF-8 read; null when absent/unreadable.
- * @property {(root: string) => string[]} listExtensions - Lowercased source-file extensions (with leading dot) found under root.
- */
-
-const SOURCE_EXTENSIONS = new Set([
-  '.ts',
-  '.tsx',
-  '.js',
-  '.jsx',
-  '.mjs',
-  '.cjs',
-  '.py',
-  '.go',
-  '.rs',
-  '.rb',
-  '.java',
-  '.kt',
-  '.php',
-  '.cs',
-  '.swift',
-]);
-
-const IGNORED_DIRS = new Set([
-  'node_modules',
-  '.git',
-  'dist',
-  'build',
-  'coverage',
-  '.next',
-  '.nuxt',
-  'vendor',
-  'target',
-  '__pycache__',
-  '.venv',
-  'venv',
-]);
-
-/**
- * Map a source-file extension to a primary-language label.
- *
- * @param {string} ext - Lowercased extension including the leading dot.
- * @returns {string|null} Language label, or null when the extension is not a recognized source type.
- */
-function extensionToLanguage(ext) {
-  switch (ext) {
-    case '.ts':
-    case '.tsx':
-      return 'typescript';
-    case '.js':
-    case '.jsx':
-    case '.mjs':
-    case '.cjs':
-      return 'javascript';
-    case '.py':
-      return 'python';
-    case '.go':
-      return 'go';
-    case '.rs':
-      return 'rust';
-    case '.rb':
-      return 'ruby';
-    case '.java':
-      return 'java';
-    case '.kt':
-      return 'kotlin';
-    case '.php':
-      return 'php';
-    case '.cs':
-      return 'csharp';
-    case '.swift':
-      return 'swift';
-    default:
-      return null;
-  }
-}
-
-/**
- * Recursively collect lowercased source-file extensions under `root`,
- * skipping vendored / build / VCS directories. Used by the default
- * filesystem facade; tests inject their own `listExtensions`.
- *
- * @param {string} root - Absolute repository root.
- * @returns {string[]} Extensions (with leading dot, possibly repeated) in traversal order.
- */
-function listExtensionsOnDisk(root) {
-  /** @type {string[]} */
-  const extensions = [];
-  /** @type {string[]} */
-  const stack = [root];
-
-  while (stack.length > 0) {
-    const dir = stack.pop();
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) {
-          continue;
-        }
-        stack.push(path.join(dir, entry.name));
-      } else if (entry.isFile()) {
-        const ext = path.extname(entry.name).toLowerCase();
-        if (ext) extensions.push(ext);
-      }
-    }
-  }
-
-  return extensions;
-}
-
-/**
- * Default filesystem facade backed by `node:fs`. Reads the real disk so
- * callers can point detection at a sample-repo fixture directory.
- *
- * @type {FsFacade}
- */
-export const defaultFsFacade = {
-  exists: (p) => fs.existsSync(p),
-  readFile: (p) => {
-    try {
-      return fs.readFileSync(p, 'utf8');
-    } catch {
-      return null;
-    }
-  },
-  listExtensions: (root) => listExtensionsOnDisk(root),
-};
-
-/**
- * Detect the package manager from lockfile presence. Defaults to `npm`
- * 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) {
-  return detectPm(root, fsFacade.exists);
-}
-
-/**
- * Parse `package.json` into an object, returning `null` when it is
- * absent or unparseable.
- *
- * @param {string} root - Repository root.
- * @param {FsFacade} fsFacade
- * @returns {Record<string, unknown>|null}
- */
-function readPackageJson(root, fsFacade) {
-  const raw = fsFacade.readFile(path.join(root, 'package.json'));
-  if (!raw) return null;
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Detect the test runner from `package.json` dependency declarations and
- * the `test` script. Recognizes vitest, jest, mocha, ava, and the
- * Node.js built-in test runner (`node --test`). Returns `null` when no
- * runner can be inferred.
- *
- * @param {string} root - Repository root.
- * @param {FsFacade} [fsFacade=defaultFsFacade]
- * @returns {'vitest'|'jest'|'mocha'|'ava'|'node-test'|null}
- */
-export function detectTestRunner(root, fsFacade = defaultFsFacade) {
-  const pkg = readPackageJson(root, fsFacade);
-  if (!pkg) return null;
-
-  const deps = {
-    .../** @type {Record<string, unknown>} */ (pkg.dependencies ?? {}),
-    .../** @type {Record<string, unknown>} */ (pkg.devDependencies ?? {}),
-  };
-
-  if (deps.vitest) return 'vitest';
-  if (deps.jest) return 'jest';
-  if (deps.mocha) return 'mocha';
-  if (deps.ava) return 'ava';
-
-  const scripts = /** @type {Record<string, unknown>} */ (pkg.scripts ?? {});
-  const testScript =
-    typeof scripts.test === 'string' ? scripts.test.toLowerCase() : '';
-  if (testScript) {
-    if (testScript.includes('vitest')) return 'vitest';
-    if (testScript.includes('jest')) return 'jest';
-    if (testScript.includes('mocha')) return 'mocha';
-    if (testScript.includes('ava')) return 'ava';
-    if (
-      testScript.includes('node --test') ||
-      testScript.includes('node:test')
-    ) {
-      return 'node-test';
-    }
-  }
-
-  return null;
-}
-
-/**
- * Detect the primary language by tallying source-file extensions and
- * picking the most frequent recognized language. A `tsconfig.json`
- * breaks ties toward TypeScript. Returns `null` when no recognized
- * source files are found.
- *
- * @param {string} root - Repository root.
- * @param {FsFacade} [fsFacade=defaultFsFacade]
- * @returns {string|null}
- */
-export function detectPrimaryLanguage(root, fsFacade = defaultFsFacade) {
-  const extensions = fsFacade.listExtensions(root) ?? [];
-  /** @type {Map<string, number>} */
-  const tally = new Map();
-
-  for (const ext of extensions) {
-    if (!SOURCE_EXTENSIONS.has(ext)) continue;
-    const language = extensionToLanguage(ext);
-    if (!language) continue;
-    tally.set(language, (tally.get(language) ?? 0) + 1);
-  }
-
-  if (tally.size === 0) return null;
-
-  // tsconfig.json is a strong TypeScript signal: nudge the tally so a
-  // mixed JS/TS repo resolves to typescript when the config is present.
-  if (fsFacade.exists(path.join(root, 'tsconfig.json'))) {
-    tally.set('typescript', (tally.get('typescript') ?? 0) + 1);
-  }
-
-  let best = null;
-  let bestCount = -1;
-  for (const [language, count] of tally) {
-    if (count > bestCount) {
-      best = language;
-      bestCount = count;
-    }
-  }
-
-  return best;
-}
-
-/**
- * Inspect a consumer repository and report the inferred stack.
- *
- * @param {string} root - Absolute repository root to inspect.
- * @param {FsFacade} [fsFacade=defaultFsFacade] - Filesystem seam (defaults to real disk).
- * @returns {{ packageManager: 'pnpm'|'yarn'|'bun'|'npm'|null, testRunner: 'vitest'|'jest'|'mocha'|'ava'|'node-test'|null, primaryLanguage: string|null }}
- */
-export function detectStack(root, fsFacade = defaultFsFacade) {
-  if (!root || typeof root !== 'string') {
-    throw new Error('detectStack: root must be a non-empty string path');
-  }
-
-  return {
-    packageManager: detectPackageManager(root, fsFacade),
-    testRunner: detectTestRunner(root, fsFacade),
-    primaryLanguage: detectPrimaryLanguage(root, fsFacade),
-  };
-}