mandrel 1.57.0

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

@@ -0,0 +1,300 @@
+/**
+ * detect-stack.js — Consumer stack detection for `/onboard`
+ *
+ * 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`.
+ *
+ * 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';
+
+/**
+ * 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.
+ *
+ * @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;
+}
+
+/**
+ * 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),
+  };
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Guided-onboard doc scaffolder (Epic #3438 Story #3519).
+ *
+ * Detects which of the project's configured `project.docsContextFiles` are
+ * absent under the resolved docs root, and — on acceptance — scaffolds a stub
+ * for each missing file. Stubs are seeded from a dedicated template under
+ * `.agents/templates/docs/<name>` when one ships; otherwise a generic
+ * placeholder stub is written so the mandatory-read never resolves to a
+ * missing file.
+ *
+ * The detection pass is side-effect free: callers can preview the missing set
+ * (`scaffoldDocs({ write: false })`) before deciding whether to scaffold.
+ *
+ * @module lib/onboard/scaffold-docs
+ */
+
+import fsDefault from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getPaths, resolveConfig } from '../config-resolver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// scripts/lib/onboard/ → scripts/lib/ → scripts/ → .agents/
+const AGENT_ROOT = path.resolve(__dirname, '../../..');
+const DOCS_TEMPLATE_DIR = path.join(AGENT_ROOT, 'templates', 'docs');
+
+/**
+ * Build the generic placeholder stub for a docsContextFile that has no
+ * dedicated template. Derives a human-readable title from the filename.
+ *
+ * @param {string} fileName - e.g. `data-dictionary.md`
+ * @returns {string}
+ */
+function genericStub(fileName) {
+  const base = fileName.replace(/\.[^.]+$/, '');
+  const title = base
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+  return (
+    `# ${title}\n\n` +
+    '> **Stub generated by guided onboarding.** 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'
+  );
+}
+
+/**
+ * Read the dedicated template body for a docsContextFile, or fall back to the
+ * generic stub when no template ships for that name.
+ *
+ * @param {string} fileName
+ * @param {import('node:fs')} fsImpl
+ * @returns {string}
+ */
+function stubContentFor(fileName, fsImpl) {
+  const templatePath = path.join(DOCS_TEMPLATE_DIR, fileName);
+  if (fsImpl.existsSync(templatePath)) {
+    return fsImpl.readFileSync(templatePath, 'utf8');
+  }
+  return genericStub(fileName);
+}
+
+/**
+ * Detect missing docsContextFiles and, on acceptance, scaffold stubs.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.root] - Project root to resolve config + docs root
+ *   against. Defaults to the resolver's `PROJECT_ROOT`.
+ * @param {string[]} [opts.docsContextFiles] - Override the configured list
+ *   (primarily for tests). Falls back to `project.docsContextFiles`.
+ * @param {string} [opts.docsRoot] - Override the resolved docs-root directory
+ *   name (relative to `root`). Falls back to `project.paths.docsRoot`.
+ * @param {boolean} [opts.write=true] - When `false`, only detect (no files are
+ *   created). When `true` (acceptance), scaffold each missing file.
+ * @param {import('node:fs')} [opts.fs] - Injectable fs implementation.
+ * @returns {{
+ *   docsRoot: string,
+ *   docsContextFiles: string[],
+ *   missing: string[],
+ *   present: string[],
+ *   created: string[],
+ * }}
+ */
+export function scaffoldDocs(opts = {}) {
+  const fsImpl = opts.fs ?? fsDefault;
+  const write = opts.write !== false;
+
+  const config = resolveConfig({ cwd: opts.root, ctx: { fs: fsImpl } });
+  const projectRoot = path.resolve(opts.root ?? process.cwd());
+
+  const docsContextFiles =
+    opts.docsContextFiles ?? config.project.docsContextFiles ?? [];
+  const docsRootName = opts.docsRoot ?? getPaths(config).docsRoot;
+  const docsRootAbs = path.resolve(projectRoot, docsRootName);
+
+  const present = [];
+  const missing = [];
+  for (const fileName of docsContextFiles) {
+    const target = path.join(docsRootAbs, fileName);
+    if (fsImpl.existsSync(target)) {
+      present.push(fileName);
+    } else {
+      missing.push(fileName);
+    }
+  }
+
+  const created = [];
+  if (write && missing.length > 0) {
+    fsImpl.mkdirSync(docsRootAbs, { recursive: true });
+    for (const fileName of missing) {
+      const target = path.join(docsRootAbs, fileName);
+      // Guard against nested paths whose parent dir is absent.
+      fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+      fsImpl.writeFileSync(target, stubContentFor(fileName, fsImpl), 'utf8');
+      created.push(fileName);
+    }
+  }
+
+  return {
+    docsRoot: docsRootAbs,
+    docsContextFiles,
+    missing,
+    present,
+    created,
+  };
+}

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

@@ -0,0 +1,173 @@
+/**
+ * Acceptance self-eval decision core (Story #3819).
+ *
+ * Pure, I/O-free reducer that turns one round's critic verdict plus the
+ * resolved round cap into the loop's next action. The CLI wrapper
+ * (`acceptance-eval.js`) owns the file reads, schema validation, signal
+ * emission, and ticket transitions; this module owns the *decision* so it
+ * can be unit-tested in isolation.
+ *
+ * ## The three terminal actions
+ *
+ *   - `proceed`  — every criterion is `met`. The Story may flip to
+ *                  `closing`.
+ *   - `redraft`  — at least one criterion is `partial`/`unmet` AND the
+ *                  current round is below the cap. The agent reworks the
+ *                  flagged criteria and re-runs the eval pass.
+ *   - `block`    — at least one criterion is `partial`/`unmet` AND the
+ *                  current round has reached (or somehow exceeded) the cap.
+ *                  The Story escalates to `agent::blocked`; it never
+ *                  silently proceeds to close.
+ *
+ * ## The undisableable cap
+ *
+ * `maxRounds` arrives already clamped by `lib/config/acceptance-eval.js`
+ * into `[1, ceiling]`, but this reducer defends the invariant a second
+ * time: a non-positive or non-integer cap is coerced to 1, so there is no
+ * input — config or verdict — that yields an unbounded `redraft` chain.
+ * When `round >= effectiveCap` and criteria remain unmet, the only
+ * possible action is `block`.
+ */
+
+/**
+ * Verdicts that clear a criterion. Anything else (`partial`, `unmet`, or
+ * an unrecognised value) is treated as not-yet-met and triggers rework.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const MET_VERDICTS = Object.freeze(new Set(['met']));
+
+/**
+ * Coerce a candidate cap to a positive integer ≥ 1. This is the
+ * last-line guard against an open loop: any degraded cap falls back to a
+ * single round rather than an unbounded one.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+function effectiveCap(value) {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    return 1;
+  }
+  return value;
+}
+
+/**
+ * Partition a verdict's criteria into met and not-met buckets, preserving
+ * order and capturing the evidence for the not-met items (used to compose
+ * the blocker comment and the per-criterion signal).
+ *
+ * @param {Array<{ index?: number, criterion?: string, verdict?: string, evidence?: string }>} criteria
+ * @returns {{
+ *   metCount: number,
+ *   notMet: Array<{ index: number, criterion: string, verdict: string, evidence: string }>,
+ * }}
+ */
+function partitionCriteria(criteria) {
+  const list = Array.isArray(criteria) ? criteria : [];
+  const notMet = [];
+  let metCount = 0;
+  list.forEach((c, i) => {
+    const verdict = typeof c?.verdict === 'string' ? c.verdict : 'unmet';
+    if (MET_VERDICTS.has(verdict)) {
+      metCount += 1;
+      return;
+    }
+    notMet.push({
+      index: Number.isInteger(c?.index) ? c.index : i,
+      criterion: typeof c?.criterion === 'string' ? c.criterion : '',
+      verdict,
+      evidence: typeof c?.evidence === 'string' ? c.evidence : '',
+    });
+  });
+  return { metCount, notMet };
+}
+
+/**
+ * Decide the next loop action from a single round's verdict.
+ *
+ * @param {object} args
+ * @param {{ round?: number, criteria?: Array<object> }} args.verdict
+ *   A verdict already validated against the acceptance-eval-verdict schema.
+ * @param {number} args.maxRounds
+ *   The resolved (already-clamped) redraft ceiling from
+ *   `getAcceptanceEval(config).maxRounds`.
+ * @returns {{
+ *   decision: 'proceed' | 'redraft' | 'block',
+ *   round: number,
+ *   cap: number,
+ *   totalCriteria: number,
+ *   metCount: number,
+ *   notMet: Array<{ index: number, criterion: string, verdict: string, evidence: string }>,
+ *   capReached: boolean,
+ * }}
+ */
+export function decideAcceptanceEval({ verdict, maxRounds }) {
+  const cap = effectiveCap(maxRounds);
+  const round =
+    Number.isInteger(verdict?.round) && verdict.round >= 1 ? verdict.round : 1;
+  const { metCount, notMet } = partitionCriteria(verdict?.criteria);
+  const totalCriteria = metCount + notMet.length;
+  const allMet = notMet.length === 0;
+  const capReached = round >= cap;
+
+  let decision;
+  if (allMet) {
+    decision = 'proceed';
+  } else if (capReached) {
+    decision = 'block';
+  } else {
+    decision = 'redraft';
+  }
+
+  return {
+    decision,
+    round,
+    cap,
+    totalCriteria,
+    metCount,
+    notMet,
+    capReached,
+  };
+}
+
+/**
+ * Build the per-criterion acceptance-eval signal payload for the retro /
+ * feedback substrate. Carries which acceptance items needed rework and the
+ * round count so `/epic-plan` Phase 0 feedback fetch and the retro can
+ * surface acceptance churn. PII-free by construction — it carries only
+ * acceptance-item indices, verdicts, and the terminal decision.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {number | null} args.epicId
+ * @param {ReturnType<typeof decideAcceptanceEval>} args.outcome
+ * @param {string} [args.phase]
+ * @returns {object} The signal record (sans `ts`, which the caller stamps).
+ */
+export function buildAcceptanceEvalSignal({
+  storyId,
+  epicId,
+  outcome,
+  phase = 'implement',
+}) {
+  return {
+    kind: 'acceptance-eval',
+    epicId: epicId ?? null,
+    storyId,
+    phase,
+    source: { tool: 'acceptance-eval.js' },
+    details: {
+      decision: outcome.decision,
+      round: outcome.round,
+      cap: outcome.cap,
+      totalCriteria: outcome.totalCriteria,
+      metCount: outcome.metCount,
+      reworkedCount: outcome.notMet.length,
+      reworkedCriteria: outcome.notMet.map((c) => ({
+        index: c.index,
+        verdict: c.verdict,
+      })),
+    },
+  };
+}