mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/planning-corpus.js

@@ -1,37 +0,0 @@
-/**
- * planning-corpus.js — corpus-aware context for the standalone-Story
- * planning path (Story #4432).
- *
- * `/plan --seed` drafts a standalone Story from the seed, the body
- * template, and a title-only duplicate scan. This module assembles the
- * inherited context (`corpusContext`) for `story-plan.js`'s
- * `--emit-context` envelope:
- *
- *   1. `docsDigest` — the same per-project docs digest
- *      `orchestration/docs-digest.js` builds for `/deliver` Story
- *      children, reused here so the standalone path gets the same
- *      compact outline instead of re-reading the whole docs set.
- *      `null` when `project.docsContextFiles` is not configured.
- *   2. `relevantSections` — always `[]`. This field previously carried
- *      ranked Tech Spec excerpts mined from open Epics. v2.0.0 removed
- *      the Epic tier, and the provider's Epic-list surface was reduced
- *      to a `return []` stub, which made the entire ranking pipeline a
- *      permanent no-op. The pipeline has been removed; the field is
- *      retained so the envelope shape stays stable for its consumers.
- */
-
-import { buildDocsDigest } from './orchestration/docs-digest.js';
-
-/**
- * Assemble the `corpusContext` field of the story-plan context envelope.
- *
- * @param {{
- *   docsContextFiles?: string[],
- *   docsRoot?: string,
- * }} opts
- * @returns {Promise<{ docsDigest: string|null, relevantSections: Array<object> }>}
- */
-export async function buildCorpusContext({ docsContextFiles, docsRoot }) {
-  const docsDigest = await buildDocsDigest({ docsContextFiles, docsRoot });
-  return { docsDigest, relevantSections: [] };
-}

package/.agents/scripts/lib/qa/coverage-report.js

@@ -1,181 +0,0 @@
-// .agents/scripts/lib/qa/coverage-report.js
-//
-// Render an AC × test-tier coverage matrix to a human-readable markdown
-// report and persist it under `<tempRoot>/qa/`.
-//
-// The matrix shape is produced by `lib/qa/coverage-verdict.js#acceptanceMatrix`
-// — one row per acceptance criterion, each row carrying the per-tier
-// `coverageVerdict` (`{unit, contract, acceptance}` with `present`/`absent`
-// statuses + notes). This module is the presentation + persistence seam:
-//   - {@link renderCoverageReport}  — pure: matrix → markdown string.
-//   - {@link reportPathFor}         — the report path under `<tempRoot>/qa/`.
-//   - {@link writeCoverageReport}   — render + write the markdown to disk.
-//
-// `renderCoverageReport` does no I/O so it stays trivially unit-testable;
-// `writeCoverageReport` accepts an injectable `fsImpl` (default `node:fs`)
-// for the same reason, mirroring `lib/qa/qa-session.js`.
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { tempRootFrom } from '../config/temp-paths.js';
-import { acceptanceMatrix, TIERS } from './coverage-verdict.js';
-
-/** Directory segment (under `tempRoot`) that holds QA coverage reports. */
-export const QA_REPORT_DIRNAME = 'qa';
-
-/** Cell glyph for each verdict status, used in the markdown matrix table. */
-const STATUS_GLYPH = Object.freeze({
-  present: '✅ present',
-  absent: '❌ absent',
-});
-
-/** Title-case a tier name for the table header (`unit` → `Unit`). */
-function tierHeader(tier) {
-  return tier.charAt(0).toUpperCase() + tier.slice(1);
-}
-
-/**
- * Escape the pipe character so a label never breaks the markdown table, and
- * collapse newlines to spaces so a multi-line criterion stays on one row.
- */
-function cell(value) {
-  return String(value ?? '')
-    .replace(/\r?\n/g, ' ')
-    .replace(/\|/g, '\\|')
-    .trim();
-}
-
-/**
- * Resolve the matrix input. Accepts either a pre-built matrix
- * (`{tiers, rows}` from {@link acceptanceMatrix}) or raw criteria (array or
- * keyed object), in which case it is run through {@link acceptanceMatrix}.
- *
- * @param {object|Array} input
- * @returns {{tiers: ReadonlyArray<string>, rows: Array}}
- */
-function resolveMatrix(input) {
-  if (
-    input &&
-    typeof input === 'object' &&
-    !Array.isArray(input) &&
-    Array.isArray(input.rows)
-  ) {
-    return { tiers: input.tiers ?? TIERS, rows: input.rows };
-  }
-  return acceptanceMatrix(input);
-}
-
-/**
- * Render an AC × test-tier coverage matrix to a markdown report string.
- *
- * The report has a title, a one-line summary of how many criteria are fully
- * covered, the matrix table (one row per AC, one column per tier), and a
- * per-criterion notes section explaining each absent tier.
- *
- * @param {{tiers?:ReadonlyArray<string>,rows:Array}|Array|object} input
- *   Either a built matrix (`{tiers, rows}`) or raw criteria to build one from.
- * @param {{ title?: string, generatedAt?: string }} [opts]
- * @returns {string} The markdown report.
- */
-export function renderCoverageReport(input, opts = {}) {
-  const { tiers, rows } = resolveMatrix(input);
-  const title =
-    typeof opts.title === 'string' && opts.title.trim() !== ''
-      ? opts.title.trim()
-      : 'QA Coverage — AC × Test-Tier Matrix';
-
-  const fullyCovered = rows.filter((row) =>
-    tiers.every((tier) => row.verdict[tier]?.status === 'present'),
-  ).length;
-
-  const lines = [];
-  lines.push(`# ${title}`);
-  lines.push('');
-  if (typeof opts.generatedAt === 'string' && opts.generatedAt.trim() !== '') {
-    lines.push(`_Generated: ${opts.generatedAt.trim()}_`);
-    lines.push('');
-  }
-  lines.push(
-    `${rows.length} acceptance criteri${rows.length === 1 ? 'on' : 'a'}, ` +
-      `${fullyCovered} fully covered across all ${tiers.length} tiers.`,
-  );
-  lines.push('');
-
-  // Matrix table.
-  const headerCells = ['Acceptance Criterion', ...tiers.map(tierHeader)];
-  lines.push(`| ${headerCells.join(' | ')} |`);
-  lines.push(`| ${headerCells.map(() => '---').join(' | ')} |`);
-  for (const row of rows) {
-    const acCell = cell(row.label ? `${row.id}: ${row.label}` : row.id);
-    const tierCells = tiers.map((tier) => {
-      const status = row.verdict[tier]?.status ?? 'absent';
-      return STATUS_GLYPH[status] ?? cell(status);
-    });
-    lines.push(`| ${[acCell, ...tierCells].join(' | ')} |`);
-  }
-  lines.push('');
-
-  // Per-criterion notes.
-  lines.push('## Notes');
-  lines.push('');
-  for (const row of rows) {
-    lines.push(
-      `### ${cell(row.id)}${row.label ? ` — ${cell(row.label)}` : ''}`,
-    );
-    for (const tier of tiers) {
-      const v = row.verdict[tier];
-      const status = v?.status ?? 'absent';
-      const note = v?.note ?? '';
-      lines.push(`- **${tierHeader(tier)}** (${status}): ${cell(note)}`);
-    }
-    lines.push('');
-  }
-
-  return `${lines.join('\n').trimEnd()}\n`;
-}
-
-/**
- * The report path under `<tempRoot>/qa/`.
- *
- * @param {string} [fileName] Report file name (default `coverage-report.md`).
- *   Path separators are rejected so a caller cannot escape the `qa/` dir.
- * @param {object} [config] Resolved config bag (for `project.paths.tempRoot`).
- * @returns {string}
- */
-export function reportPathFor(fileName = 'coverage-report.md', config) {
-  const name = String(fileName);
-  if (name.includes('/') || name.includes('\\') || name === '..') {
-    throw new Error(
-      `[coverage-report] file name must not contain path separators; got ${JSON.stringify(name)}`,
-    );
-  }
-  return path.join(tempRootFrom(config), QA_REPORT_DIRNAME, name);
-}
-
-/**
- * Render the matrix to markdown and write it under `<tempRoot>/qa/`, creating
- * the directory if needed. Returns the resolved path and the rendered body.
- *
- * @param {{tiers?:ReadonlyArray<string>,rows:Array}|Array|object} input
- *   Either a built matrix or raw criteria.
- * @param {{
- *   fileName?: string,
- *   config?: object,
- *   title?: string,
- *   generatedAt?: string,
- *   fsImpl?: typeof fs,
- * }} [opts]
- * @returns {{ path: string, markdown: string }}
- */
-export function writeCoverageReport(input, opts = {}) {
-  const fsImpl = opts.fsImpl ?? fs;
-  const markdown = renderCoverageReport(input, {
-    title: opts.title,
-    generatedAt: opts.generatedAt,
-  });
-  const reportPath = reportPathFor(opts.fileName, opts.config);
-  fsImpl.mkdirSync(path.dirname(reportPath), { recursive: true });
-  fsImpl.writeFileSync(reportPath, markdown, 'utf8');
-  return { path: reportPath, markdown };
-}

package/.agents/scripts/lib/qa/propose-missing-test.js

@@ -1,95 +0,0 @@
-// .agents/scripts/lib/qa/propose-missing-test.js
-//
-// Deterministic missing-test proposal from a coverage verdict.
-//
-// Closes the loop on accuracy (f4-accuracy): given the per-tier coverage
-// verdict produced by `lib/qa/coverage-verdict.js`, name the single tier that
-// should have caught a finding and draft a one-line test suggestion for it.
-//
-// The verdict's pyramid order is unit < contract < acceptance. The cheapest
-// tier that is ABSENT is the one a finding "leaked through" — adding a test
-// there is the lowest-cost way to have caught it — so this helper proposes
-// the *lowest* absent tier. When every tier is present there is no gap to
-// fill, so no proposal is returned.
-//
-// Pure logic, no I/O: no network, no child processes, no filesystem or env
-// reads. The companion process skill is `core/qa-coverage-mapping`.
-//
-// Public API:
-//
-//   proposeMissingTest(coverageVerdict) -> null | {
-//     tier:        'unit' | 'contract' | 'acceptance',
-//     description: string,   // one-line test suggestion
-//   }
-
-import { TIERS } from './coverage-verdict.js';
-
-const ABSENT = 'absent';
-
-/**
- * One-line test-suggestion templates, keyed by tier. Each takes the absent
- * tier's verdict note (which already explains *why* the tier is uncovered)
- * and frames it as an actionable suggestion.
- */
-const DESCRIPTION_BY_TIER = Object.freeze({
-  unit: (note) =>
-    `Add a colocated unit test exercising this surface in isolation — ${note}.`,
-  contract: (note) =>
-    `Add a contract test asserting this surface’s wire shape or boundary — ${note}.`,
-  acceptance: (note) =>
-    `Add an acceptance scenario covering the user-visible journey — ${note}.`,
-});
-
-/**
- * Read the absent-tier note off a verdict entry, falling back to a generic
- * phrase when the entry omits a usable note.
- *
- * @param {{note?:unknown}} entry
- * @returns {string}
- */
-function noteFor(entry) {
-  return typeof entry.note === 'string' && entry.note.trim() !== ''
-    ? entry.note.trim()
-    : 'no test currently covers this tier';
-}
-
-/**
- * Return true when a verdict entry marks its tier ABSENT.
- *
- * @param {unknown} entry
- * @returns {boolean}
- */
-function isAbsent(entry) {
-  return entry !== null && typeof entry === 'object' && entry.status === ABSENT;
-}
-
-/**
- * Propose the single missing test that should have caught a finding.
- *
- * Walks the tiers in pyramid order (unit → contract → acceptance) and returns
- * a proposal for the first ABSENT tier — the lowest-cost gap. Returns `null`
- * when every tier is present (full coverage, nothing to propose).
- *
- * @param {Record<string,{status?:string,note?:string}>} coverageVerdict - The
- *   object produced by `coverageVerdict()` in `lib/qa/coverage-verdict.js`.
- * @returns {null | {tier:string, description:string}}
- */
-export function proposeMissingTest(coverageVerdict) {
-  if (coverageVerdict === null || typeof coverageVerdict !== 'object') {
-    throw new TypeError(
-      'proposeMissingTest: coverageVerdict must be an object',
-    );
-  }
-
-  for (const tier of TIERS) {
-    const entry = coverageVerdict[tier];
-    if (isAbsent(entry)) {
-      return {
-        tier,
-        description: DESCRIPTION_BY_TIER[tier](noteFor(entry)),
-      };
-    }
-  }
-
-  return null;
-}

package/.agents/scripts/lib/qa/qa-context-hydrator.js

@@ -1,217 +0,0 @@
-/**
- * QA context hydrator — Story #3805, Epic #3798 (f1-shared-qa-core).
- *
- * Both QA front-ends (`/qa-explore` and `/qa-run`) need to load the
- * *grounded* surface context for an Epic before they reason about what to test:
- * the Epic body (which carries the folded Tech Spec sections and
- * Acceptance Table — Story #4324 retired the separate context tickets),
- * the project's `.feature` files, the implementation files the surface
- * map points at, and a slice of recent git history. Today a front-end that
- * trusts in-code comments ("this handler lives at …") can be wrong — the path
- * may have moved, or never existed on the base branch at all. This hydrator
- * removes that guesswork: it assembles every surface into one context object
- * and **verifies every surface-map path against the base ref (`main`)**,
- * marking any path absent on `main` as *unverified* rather than trusting it.
- *
- * ## No-network seam
- *
- * Every GitHub and git access flows through an **injected port** so the unit
- * test runs with no network and no real repository:
- *   - {@link GithubPort}  — `fetchIssue(number) → { number, body, labels }`.
- *   - {@link GitPort}     — `existsOnRef(path, ref) → boolean` and
- *                           `recentLog({ maxCount }) → LogEntry[]`.
- *   - `fsImpl`            — only used to enumerate `.feature` files; defaults
- *                           to `node:fs`.
- *
- * The hydrator never reaches the network itself; a caller in production wires
- * ports backed by `gh` / `git`, while a test wires in-memory fakes. This
- * mirrors the injected-seam style already used across `lib/qa/` (see
- * `qa-session.js`'s `fsImpl` and `redact-evidence.js`).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** The base ref every surface-map path is verified against. */
-export const DEFAULT_BASE_REF = 'main';
-
-/** How many recent commits the hydrator pulls into the context object. */
-export const DEFAULT_LOG_MAX_COUNT = 20;
-
-/**
- * @typedef {object} GithubPort
- * @property {(issueNumber: number) => Promise<{
- *   number: number,
- *   body: string,
- *   labels?: string[],
- * }>} fetchIssue Fetch one issue's body + labels.
- */
-
-/**
- * @typedef {object} GitPort
- * @property {(filePath: string, ref: string) => boolean | Promise<boolean>}
- *   existsOnRef True when `filePath` is tracked on `ref` (e.g. `main`).
- * @property {(opts: { maxCount: number }) =>
- *   Array<{ sha: string, subject: string }>
- *   | Promise<Array<{ sha: string, subject: string }>>}
- *   recentLog Recent commit log, newest first.
- */
-
-/**
- * @typedef {object} SurfaceMapEntry
- * @property {string} path Repo-relative implementation file path.
- * @property {string} [note] Free-form provenance note (e.g. a code comment).
- */
-
-/**
- * Enumerate the `.feature` files under `featureRoot`, returning repo-relative
- * POSIX-style paths sorted for determinism. A missing root yields an empty
- * array (a project that has not authored features is not an error).
- *
- * @param {string | undefined} featureRoot
- * @param {{ fsImpl?: typeof fs }} [opts]
- * @returns {string[]}
- */
-export function collectFeatureFiles(featureRoot, opts = {}) {
-  const fsImpl = opts.fsImpl ?? fs;
-  if (!featureRoot || !fsImpl.existsSync(featureRoot)) return [];
-
-  const found = [];
-  const walk = (dir) => {
-    const entries = fsImpl.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (entry.isFile() && entry.name.endsWith('.feature')) {
-        found.push(full.split(path.sep).join('/'));
-      }
-    }
-  };
-  walk(featureRoot);
-  return found.sort();
-}
-
-/**
- * Verify each surface-map entry against the base ref. An entry whose path is
- * tracked on `baseRef` is `verified: true`; an entry absent on the base ref is
- * `verified: false` — the surface map (or the code comment it came from) named
- * a path that does not exist on `main`, so the front-end must treat it as
- * unverified rather than trusting it.
- *
- * @param {SurfaceMapEntry[]} surfaceMap
- * @param {GitPort} gitPort
- * @param {string} baseRef
- * @returns {Promise<Array<{
- *   path: string,
- *   note: string | null,
- *   verified: boolean,
- * }>>}
- */
-export async function verifySurfaceMap(surfaceMap, gitPort, baseRef) {
-  const entries = Array.isArray(surfaceMap) ? surfaceMap : [];
-  const verified = [];
-  for (const entry of entries) {
-    const filePath = typeof entry === 'string' ? entry : entry?.path;
-    if (!filePath) continue;
-    const exists = await gitPort.existsOnRef(filePath, baseRef);
-    verified.push({
-      path: filePath,
-      note: typeof entry === 'object' && entry?.note ? entry.note : null,
-      verified: Boolean(exists),
-    });
-  }
-  return verified;
-}
-
-/**
- * Hydrate the QA context object for an Epic.
- *
- * Assembles, in one object:
- *   - `epic`            — the Epic's `{ number, body, labels }`. The body is
- *                         the single planning document (ideation sections +
- *                         folded Tech Spec sections + Acceptance Table).
- *   - `featureFiles`    — repo-relative paths of the project's `.feature` files.
- *   - `implementation`  — the verified surface map (each entry carries
- *                         `verified` against the base ref).
- *   - `gitLog`          — recent commits, newest first.
- *   - `baseRef`         — the ref every path was verified against.
- *   - `unverifiedPaths` — the subset of surface-map paths absent on `baseRef`.
- *
- * Every GitHub and git access flows through the injected ports, so this runs
- * with no network when the ports are fakes.
- *
- * @param {{
- *   ticketNumber: number,
- *   githubPort: GithubPort,
- *   gitPort: GitPort,
- *   surfaceMap?: SurfaceMapEntry[],
- *   featureRoot?: string,
- *   baseRef?: string,
- *   logMaxCount?: number,
- *   fsImpl?: typeof fs,
- * }} opts
- * @returns {Promise<{
- *   epic: { number: number, body: string, labels: string[] },
- *   featureFiles: string[],
- *   implementation: Array<{ path: string, note: string | null, verified: boolean }>,
- *   gitLog: Array<{ sha: string, subject: string }>,
- *   baseRef: string,
- *   unverifiedPaths: string[],
- * }>}
- */
-export async function hydrateQaContext(opts) {
-  const {
-    ticketNumber,
-    githubPort,
-    gitPort,
-    surfaceMap = [],
-    featureRoot,
-    baseRef = DEFAULT_BASE_REF,
-    logMaxCount = DEFAULT_LOG_MAX_COUNT,
-    fsImpl,
-  } = opts ?? {};
-
-  if (!Number.isInteger(ticketNumber)) {
-    throw new Error(
-      'hydrateQaContext: `ticketNumber` is required and must be an integer',
-    );
-  }
-  if (!githubPort || typeof githubPort.fetchIssue !== 'function') {
-    throw new Error(
-      'hydrateQaContext: `githubPort.fetchIssue` is required (inject a port)',
-    );
-  }
-  if (
-    !gitPort ||
-    typeof gitPort.existsOnRef !== 'function' ||
-    typeof gitPort.recentLog !== 'function'
-  ) {
-    throw new Error(
-      'hydrateQaContext: `gitPort` must expose `existsOnRef` and `recentLog`',
-    );
-  }
-
-  const epicIssue = await githubPort.fetchIssue(ticketNumber);
-  const epic = {
-    number: epicIssue.number,
-    body: epicIssue.body ?? '',
-    labels: Array.isArray(epicIssue.labels) ? [...epicIssue.labels] : [],
-  };
-
-  const featureFiles = collectFeatureFiles(featureRoot, { fsImpl });
-  const implementation = await verifySurfaceMap(surfaceMap, gitPort, baseRef);
-  const gitLog = await gitPort.recentLog({ maxCount: logMaxCount });
-  const unverifiedPaths = implementation
-    .filter((entry) => !entry.verified)
-    .map((entry) => entry.path);
-
-  return {
-    epic,
-    featureFiles,
-    implementation,
-    gitLog: Array.isArray(gitLog) ? gitLog : [],
-    baseRef,
-    unverifiedPaths,
-  };
-}

package/.agents/scripts/lib/signals/detectors/index.js

@@ -1,14 +0,0 @@
-/**
- * Detectors barrel (Epic #1721 / Story #1771 / Task #1774).
- *
- * Single import surface for every signal detector. Detector Stories
- * (rework in #1771, retry in #1768) re-export from here so callers
- * (`lib/orchestration/detectors-phase.js`) only ever import from one
- * place. The Epic #1769 hotspot detector was retired in the Epic #4406
- * signal-contract cutover (no live emitter, no consumer).
- *
- * @module lib/signals/detectors
- */
-
-export { detectRetry } from './retry.js';
-export { detectRework } from './rework.js';