mandrel 1.57.0

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

@@ -0,0 +1,95 @@
+// .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

@@ -0,0 +1,296 @@
+/**
+ * QA context hydrator — Story #3805, Epic #3798 (f1-shared-qa-core).
+ *
+ * Both QA front-ends (`/qa-explore` and `/qa-run-harness`) need to load the
+ * *grounded* surface context for an Epic before they reason about what to test:
+ * the Epic body, its linked context tickets (PRD / Tech Spec / Acceptance
+ * Spec), 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;
+
+/**
+ * The GitHub label prefixes that mark a linked context ticket. The hydrator
+ * resolves `context::prd`, `context::tech-spec`, and `context::acceptance-spec`
+ * references off the Epic body and fetches each one through the port.
+ */
+export const CONTEXT_TICKET_KINDS = Object.freeze([
+  'prd',
+  'tech-spec',
+  'acceptance-spec',
+]);
+
+/**
+ * @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).
+ */
+
+/**
+ * Parse the linked context-ticket issue numbers out of an Epic body.
+ *
+ * Two reference shapes are recognized, both written by the planning workflows:
+ *   - A labelled line: `context::prd #3800` (or `context::tech-spec: #3801`).
+ *   - A "Planning Artifacts" link: `- PRD: #3800`, `- Tech Spec: #3801`,
+ *     `- Acceptance Spec: #3802`.
+ *
+ * Returns a map of kind → issue number for whichever kinds are present. A kind
+ * that appears more than once keeps the first occurrence; an unparseable line
+ * is skipped rather than thrown.
+ *
+ * @param {string} epicBody
+ * @returns {Record<string, number>}
+ */
+export function parseContextTicketRefs(epicBody) {
+  const refs = {};
+  const body = typeof epicBody === 'string' ? epicBody : '';
+
+  // Map the human-readable labels back to canonical kinds.
+  const labelToKind = {
+    prd: 'prd',
+    'tech-spec': 'tech-spec',
+    'tech spec': 'tech-spec',
+    techspec: 'tech-spec',
+    'acceptance-spec': 'acceptance-spec',
+    'acceptance spec': 'acceptance-spec',
+    acceptancespec: 'acceptance-spec',
+  };
+
+  for (const rawLine of body.split('\n')) {
+    const line = rawLine.trim();
+    // Match `context::tech-spec #N`, `Tech Spec: #N`, `- PRD: #N`, etc.
+    const match = line.match(
+      /(?:context::)?([A-Za-z][A-Za-z -]*?)\s*[:#]*\s*#(\d+)/,
+    );
+    if (!match) continue;
+    const key = match[1]
+      .trim()
+      .toLowerCase()
+      .replace(/^context::/, '');
+    const kind = labelToKind[key];
+    if (!kind) continue;
+    const issueNumber = Number(match[2]);
+    if (!Number.isInteger(issueNumber)) continue;
+    if (refs[kind] === undefined) refs[kind] = issueNumber;
+  }
+
+  return refs;
+}
+
+/**
+ * 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 }`.
+ *   - `contextTickets`  — the linked PRD / Tech Spec / Acceptance Spec tickets,
+ *                         keyed by kind, each `{ number, body, labels }`.
+ *   - `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 {{
+ *   epicNumber: 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[] },
+ *   contextTickets: Record<string, {
+ *     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 {
+    epicNumber,
+    githubPort,
+    gitPort,
+    surfaceMap = [],
+    featureRoot,
+    baseRef = DEFAULT_BASE_REF,
+    logMaxCount = DEFAULT_LOG_MAX_COUNT,
+    fsImpl,
+  } = opts ?? {};
+
+  if (!Number.isInteger(epicNumber)) {
+    throw new Error(
+      'hydrateQaContext: `epicNumber` 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(epicNumber);
+  const epic = {
+    number: epicIssue.number,
+    body: epicIssue.body ?? '',
+    labels: Array.isArray(epicIssue.labels) ? [...epicIssue.labels] : [],
+  };
+
+  // Resolve and fetch the linked context tickets off the Epic body.
+  const refs = parseContextTicketRefs(epic.body);
+  const contextTickets = {};
+  for (const kind of CONTEXT_TICKET_KINDS) {
+    const number = refs[kind];
+    if (number === undefined) continue;
+    const issue = await githubPort.fetchIssue(number);
+    contextTickets[kind] = {
+      number: issue.number,
+      body: issue.body ?? '',
+      labels: Array.isArray(issue.labels) ? [...issue.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,
+    contextTickets,
+    featureFiles,
+    implementation,
+    gitLog: Array.isArray(gitLog) ? gitLog : [],
+    baseRef,
+    unverifiedPaths,
+  };
+}

package/.agents/scripts/lib/qa/qa-session.js

@@ -0,0 +1,197 @@
+/**
+ * QA exploratory-session resume helper — Story #3723, Epic #3686.
+ *
+ * A `/qa-explore` run captures observations into a per-session ledger
+ * (one `QaLedgerItem` per line, see `.agents/schemas/qa-ledger.schema.json`
+ * from Story #3716). For an f5-safety resume to work, a later run with the
+ * *same* session-id must read the on-disk ledger, carry forward the still
+ * un-triaged findings as a rolling backlog, and append to — never overwrite —
+ * the existing file.
+ *
+ * This module owns three small seams:
+ *   - {@link resolveSessionId}  — a stable session-id for a run.
+ *   - {@link ledgerPathFor}     — the ledger path under `<tempRoot>/qa/`.
+ *   - {@link readLedger}        — parse an existing ledger into items plus the
+ *                                 un-triaged subset (the rolling backlog).
+ *
+ * {@link resolveQaSession} composes them: it resolves the id and path, reads
+ * any existing ledger, and reports whether the file already existed so the
+ * caller knows to *reuse* rather than re-create it.
+ *
+ * Evidence persisted in the ledger MUST already be scrubbed of secrets and
+ * PII per `.agents/rules/security-baseline.md` (see `lib/qa/redact-evidence.js`)
+ * before it reaches disk; this module only reads what is already there.
+ *
+ * The ledger round-trip is field-preserving: {@link readLedger} parses each
+ * line as a whole `QaLedgerItem` and returns it untouched, so optional fields
+ * such as the Triage `routedTo` finding-to-issue link
+ * (see `.agents/schemas/qa-ledger.schema.json`) survive a read/append cycle
+ * intact rather than being dropped on resume.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { tempRootFrom } from '../config/temp-paths.js';
+
+/** Directory segment (under `tempRoot`) that holds every QA session ledger. */
+export const QA_LEDGER_DIRNAME = 'qa';
+
+/**
+ * Triaged dispositions, mirrored from the `disposition` enum in
+ * `.agents/schemas/qa-ledger.schema.json`. An item carrying any of these has
+ * already been triaged; anything else (absent, null, empty, or unrecognized)
+ * is still part of the rolling backlog.
+ */
+export const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
+
+/**
+ * True when a ledger item has **not** yet been triaged — i.e. its
+ * `disposition` is not one of the canonical triaged values. These items are
+ * the rolling backlog a resume run carries forward.
+ *
+ * @param {{ disposition?: unknown }} item
+ * @returns {boolean}
+ */
+export function isUntriaged(item) {
+  const disposition = item?.disposition;
+  return !TRIAGED_DISPOSITIONS.includes(disposition);
+}
+
+/**
+ * Normalize an arbitrary session label into a filesystem-safe slug. Keeps
+ * alphanumerics, dot, dash, and underscore; collapses everything else to a
+ * single dash. Guards against path traversal so a hostile label can never
+ * escape the `qa/` directory.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function slugifySessionId(raw) {
+  const slug = String(raw)
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '');
+  return slug.length > 0 ? slug : deriveSessionId();
+}
+
+/**
+ * Derive a fresh, stable session-id when the caller supplies none. The id is
+ * date-prefixed for human scannability and suffixed with short entropy so two
+ * runs on the same day never collide.
+ *
+ * @returns {string}
+ */
+function deriveSessionId() {
+  const date = new Date().toISOString().slice(0, 10);
+  const entropy = crypto.randomBytes(4).toString('hex');
+  return `qa-${date}-${entropy}`;
+}
+
+/**
+ * Resolve a stable session-id for a run.
+ *
+ * Precedence: an explicit `sessionId` option wins; otherwise the
+ * `QA_SESSION_ID` environment variable; otherwise a freshly derived id. An
+ * explicit or environment id is slugified so it is safe to use as a filename.
+ *
+ * @param {{ sessionId?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string}
+ */
+export function resolveSessionId(opts = {}) {
+  const explicit = opts.sessionId;
+  if (typeof explicit === 'string' && explicit.trim().length > 0) {
+    return slugifySessionId(explicit);
+  }
+  const fromEnv = (opts.env ?? process.env).QA_SESSION_ID;
+  if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
+    return slugifySessionId(fromEnv);
+  }
+  return deriveSessionId();
+}
+
+/**
+ * The ledger path for a session: `<tempRoot>/qa/<sessionId>.ndjson`.
+ *
+ * @param {string} sessionId A slug-safe session-id (see {@link resolveSessionId}).
+ * @param {object} [config] Resolved config bag (for `project.paths.tempRoot`).
+ * @returns {string}
+ */
+export function ledgerPathFor(sessionId, config) {
+  const slug = slugifySessionId(sessionId);
+  return path.join(tempRootFrom(config), QA_LEDGER_DIRNAME, `${slug}.ndjson`);
+}
+
+/**
+ * Parse a single ndjson line into a ledger item, or `null` when the line is
+ * blank or not valid JSON. Malformed lines are skipped rather than thrown so a
+ * partially-written ledger from a crashed run still resumes.
+ *
+ * @param {string} line
+ * @returns {object | null}
+ */
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and parse an existing ledger from disk.
+ *
+ * Returns the full parsed `items` array plus `untriaged` — the subset whose
+ * disposition is not yet triaged (the rolling backlog). A missing ledger is
+ * not an error: it yields empty arrays and `exists: false`.
+ *
+ * @param {string} ledgerPath
+ * @param {{ fsImpl?: typeof fs }} [opts]
+ * @returns {{ exists: boolean, items: object[], untriaged: object[] }}
+ */
+export function readLedger(ledgerPath, opts = {}) {
+  const fsImpl = opts.fsImpl ?? fs;
+  if (!fsImpl.existsSync(ledgerPath)) {
+    return { exists: false, items: [], untriaged: [] };
+  }
+  const raw = fsImpl.readFileSync(ledgerPath, 'utf8');
+  const items = raw.split('\n').map(parseLine).filter(Boolean);
+  return { exists: true, items, untriaged: items.filter(isUntriaged) };
+}
+
+/**
+ * Resolve a QA exploratory session: a stable session-id, the ledger path
+ * under `<tempRoot>/qa/`, and the current ledger contents (parsed items plus
+ * the un-triaged rolling backlog).
+ *
+ * `reused` is `true` when a ledger already exists for this session-id — the
+ * signal that a resume run must append to, not overwrite, the file.
+ *
+ * @param {{
+ *   sessionId?: string,
+ *   config?: object,
+ *   env?: NodeJS.ProcessEnv,
+ *   fsImpl?: typeof fs,
+ * }} [opts]
+ * @returns {{
+ *   sessionId: string,
+ *   ledgerPath: string,
+ *   reused: boolean,
+ *   items: object[],
+ *   untriaged: object[],
+ * }}
+ */
+export function resolveQaSession(opts = {}) {
+  const sessionId = resolveSessionId({
+    sessionId: opts.sessionId,
+    env: opts.env,
+  });
+  const ledgerPath = ledgerPathFor(sessionId, opts.config);
+  const { exists, items, untriaged } = readLedger(ledgerPath, {
+    fsImpl: opts.fsImpl,
+  });
+  return { sessionId, ledgerPath, reused: exists, items, untriaged };
+}