mandrel 1.63.0 → 1.65.0

package/.agents/workflows/qa-explore.md

@@ -296,19 +296,62 @@ For each untriaged ledger item:
    `searchIssues` port to the GitHub provider (querying both open and closed
    Issues).
 
-3. **Decide the disposition** with the operator: `file` (promote to a
-   follow-up ticket with the classified labels + fingerprint footer), `defer`
-   (carry forward to a later session as backlog), or `dismiss` (non-actionable).
-   Record the chosen `disposition` back onto the ledger item.
+3. **Decide the disposition** with the operator: `file` (promote through
+   `/plan` — never a raw GitHub Issue), `defer` (carry forward to a later
+   session as backlog), or `dismiss` (non-actionable). Record the chosen
+   `disposition` back onto the ledger item.
 
-4. **Gate:** any ticket-filing or label mutation is a write — confirm each one
-   with the operator before it happens. Capture stayed read-only precisely so
-   that every state change lands here, deliberately and confirmed.
+4. **Promote the `file`-dispositioned findings through `/plan`** via
+   [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) — the
+   same cluster/size/route/file path `/qa-assist` and `/audit-to-stories`
+   consume. Never hand-roll the clustering, sizing, or promotion in prose:
+
+   ```js
+   import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
+   const { promotions } = await promoteFindings(ledgerItems, {
+     searchIssues, // GitHub provider, open + closed
+     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
+     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+   });
+   ```
+
+   - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
+     `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
+     distinct coverage surfaces routes to `createStory`; **>2** routes to
+     `createEpic`. The workflow introduces no new sizing, clustering, or dedup
+     logic — `route-finding.js` / `promote-finding.js` remain the single
+     implementation.
+   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
+     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5b notes shape; redaction already ran in Capture), **stamp the
+     cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
+     chain `/plan --from-notes <seed>`. The footer must survive into the issue
+     body the Story create path writes — it round-trips through
+     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
+     deterministic round-trip test under `tests/`) so a later `routeFinding`
+     dedups the same finding instead of re-filing it.
+   - **`createEpic` (`/plan --idea`)** — carry the cluster's
+     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
+     `/plan --idea <seed>`. **Known limitation (not solved here):**
+     per-child-Story fingerprint propagation through full Epic decomposition is
+     *not* guaranteed — the fingerprint is carried in the Epic seed only; the
+     child Stories `/plan` spawns from that seed are not individually
+     footer-stamped.
+   - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
+     finding flows through `promoteFindings` → `/plan`; only `defer` and
+     `dismiss` skip the `/plan` handoff.
+
+5. **Gate:** any ticket-filing, seed write, `/plan` invocation, or label
+   mutation is a write — confirm each one with the operator before it happens.
+   Capture stayed read-only precisely so that every state change lands here,
+   deliberately and confirmed. The plan→deliver hard stop is preserved: each
+   `/plan` chain pauses at its own HITL gates and never auto-delivers.
 
 After triage, write the updated dispositions back to the ledger (still under
 `temp/qa/`), and summarize: items captured, the driving method used, classes,
-routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), filed
-tickets, and the deferred rolling backlog that a resumed session will pick up.
+routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), the
+Stories (`/plan --from-notes`) and Epics (`/plan --idea`) promoted, and the
+deferred rolling backlog that a resumed session will pick up.
 
 ---
 
@@ -343,8 +386,31 @@ tickets, and the deferred rolling backlog that a resumed session will pick up.
   ([`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js)),
   missing-test ([`propose-missing-test.js`](../scripts/lib/qa/propose-missing-test.js)),
   classification ([`classify-finding.js`](../scripts/lib/findings/classify-finding.js)),
-  and dedup/route ([`route-finding.js`](../scripts/lib/findings/route-finding.js))
-  are deterministic — never re-derive them in prose.
+  dedup/route ([`route-finding.js`](../scripts/lib/findings/route-finding.js)),
+  and cluster/size/promote
+  ([`promote-finding.js`](../scripts/lib/findings/promote-finding.js)) are
+  deterministic — never re-derive them in prose.
+- **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
+  finding is promoted via `promoteFindings`, which chains into
+  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-explore`
+  never opens a bare GitHub Issue for a `file` finding. The cluster's
+  `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
+  `routeFinding` dedups it.
 - **Resume safely.** A reused session appends and carries the un-triaged
   backlog forward via [`qa-session.js`](../scripts/lib/qa/qa-session.js); it
   never overwrites a prior ledger.
+
+## See also
+
+- [`/plan`](plan.md) — the planning pipeline `/qa-explore` Triage chains into
+  for a `file`-dispositioned finding (`--from-notes` for a Story, `--idea` for
+  an Epic). The plan→deliver hard stop is preserved across the handoff.
+- [`/qa-assist`](qa-assist.md) — the human-led sibling that enriches a single
+  operator observation and triages through the same `/plan` handoff.
+- [`/audit-to-stories`](audit-to-stories.md) — the precedent for the
+  findings → `/plan` handoff and the shared fingerprint-footer dedup contract.
+- [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) /
+  [`route-finding.js`](../scripts/lib/findings/route-finding.js) — the shared
+  cluster/size/promote and dedup/route/fingerprint-footer helpers. There is no
+  second clustering, sizing, or dedup implementation.

package/docs/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.65.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.64.0...mandrel-v1.65.0) (2026-06-14)
+
+
+### Added
+
+* Epic [#4118](https://github.com/dsj1984/mandrel/issues/4118) ([#4127](https://github.com/dsj1984/mandrel/issues/4127)) ([d24a1f7](https://github.com/dsj1984/mandrel/commit/d24a1f7d3fc36d20015890fbadd7d08caa1d506b))
+* **qa:** route /qa-assist and /qa-explore triage into /plan (refs [#4115](https://github.com/dsj1984/mandrel/issues/4115)) ([#4116](https://github.com/dsj1984/mandrel/issues/4116)) ([de2a211](https://github.com/dsj1984/mandrel/commit/de2a211089104edd1cb76f77d668b0219a041c3e))
+
+## [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)
 
 

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.63.0",
+  "version": "1.65.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -85,6 +85,7 @@
     "lint-staged": "^17.0.4",
     "markdownlint-cli2": "^0.18.1",
     "memfs": "^4.57.2",
+    "node-pty": "^1.0.0",
     "typescript": ">=5.0.0"
   },
   "dependencies": {

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),
-  };
-}