mandrel 2.38.0 → 2.40.0

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -20,7 +20,10 @@ import path from 'node:path';
 import { normalizeSeverity } from '../findings/severity.js';
 
 const KEY_LINE = /^\s*-\s*\*\*([^:*]+):\*\*\s*(.*)$/;
-const HEADING_FINDING = /^###\s+(.+?)\s*$/;
+const HEADING_FINDING = /^(#{3,4})\s+(.+?)\s*$/;
+const SEVERITY_KEY_LINE = /^\s*-\s*\*\*(?:severity|impact)\s*:\*\*/i;
+const TALLY_LINE =
+  /severity\s+tally\s*:?\**\s*critical\s+(\d+)\s*\/\s*high\s+(\d+)\s*\/\s*medium\s+(\d+)\s*\/\s*low\s+(\d+)/i;
 const HEADING_SECTION = /^##\s+(.+?)\s*$/;
 const PATH_HINT =
   /(?<![\w/])([A-Za-z0-9_./\\@-]+\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env))(?![\w])/g;
@@ -238,7 +241,11 @@ function splitFindingBlocks(reportText) {
     const findingMatch = HEADING_FINDING.exec(line);
     if (findingMatch) {
       if (current) blocks.push(current);
-      current = { title: findingMatch[1].trim(), bodyLines: [] };
+      current = {
+        level: findingMatch[1].length,
+        title: findingMatch[2].trim(),
+        bodyLines: [],
+      };
       continue;
     }
 
@@ -249,6 +256,88 @@ function splitFindingBlocks(reportText) {
   return blocks;
 }
 
+/**
+ * Does this block carry the axis line that makes it a finding rather than a
+ * section header? The skeleton mandates `Severity` (or its `Impact` alias), so
+ * its absence is the signal that a heading is organisational.
+ *
+ * @param {{ bodyLines: string[] }} block
+ * @returns {boolean}
+ */
+function carriesSeverity(block) {
+  return block.bodyLines.some((line) => SEVERITY_KEY_LINE.test(line));
+}
+
+/**
+ * Resolve `###` headings that are **grouping headers** rather than findings.
+ *
+ * Several lenses nest their findings one level deeper — a `###` per dimension
+ * (`### Perceivable`), each holding `####` finding blocks. Read flat, that
+ * report parsed as one severity-less finding per dimension with no files and
+ * no recommendation, and `--auto` filed those empties (Story #5144). The rule
+ * this applies: a `###` heading that carries no `Severity:`/`Impact:` line and
+ * is followed by `####` headings is a grouping header — its `####` children
+ * are emitted as findings and the header itself never is.
+ *
+ * A `###` heading that DOES carry the axis line keeps the previous behaviour:
+ * its `####` sub-sections fold back into its own body rather than splitting
+ * into phantom findings, so existing flat reports parse exactly as before.
+ *
+ * @param {Array<{ level: number, title: string, bodyLines: string[] }>} blocks
+ * @returns {Array<{ level: number, title: string, bodyLines: string[] }>}
+ */
+function foldGroupingHeaders(blocks) {
+  const out = [];
+  let parent = null;
+  for (const block of blocks) {
+    if (block.level <= 3) {
+      parent = block;
+      out.push(block);
+      continue;
+    }
+    if (!parent) {
+      out.push(block);
+      continue;
+    }
+    if (carriesSeverity(parent)) {
+      parent.bodyLines.push(`#### ${block.title}`, ...block.bodyLines);
+      continue;
+    }
+    parent.isGroupingHeader = true;
+    out.push(block);
+  }
+  return out.filter((block) => !block.isGroupingHeader);
+}
+
+/**
+ * Read the machine-readable severity tally the report envelope mandates in its
+ * `## Executive Summary`:
+ *
+ * ```text
+ * Severity tally: Critical 0 / High 2 / Medium 1 / Low 0
+ * ```
+ *
+ * The line is what lets a consumer cross-check what the lens says it found
+ * against what the parser actually extracted — a parse that silently drops
+ * findings is otherwise indistinguishable from a clean report. `Info` is never
+ * counted (the severity scale already excludes it from scheduled work).
+ *
+ * @param {string} markdown — full report text.
+ * @returns {{ critical: number, high: number, medium: number, low: number }|null}
+ *   `null` when the report declares no tally at all.
+ */
+export function parseSeverityTally(markdown) {
+  if (typeof markdown !== 'string') return null;
+  const match = TALLY_LINE.exec(markdown);
+  if (!match) return null;
+  return {
+    critical: Number(match[1]),
+    high: Number(match[2]),
+    medium: Number(match[3]),
+    low: Number(match[4]),
+  };
+}
+
 function parseBlockFields(bodyLines) {
   const fields = {};
   let activeKey = null;
@@ -302,7 +391,7 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
   }
 
   const fallbackDimension = inferDimensionFromReportName(sourceReport);
-  const blocks = splitFindingBlocks(markdown);
+  const blocks = foldGroupingHeaders(splitFindingBlocks(markdown));
 
   return blocks.map((block) => {
     const fields = parseBlockFields(block.bodyLines);
@@ -357,6 +446,8 @@ export function parseAuditReports(reports, { repoRoot } = {}) {
 }
 
 export const __testing = {
+  carriesSeverity,
+  foldGroupingHeaders,
   normaliseSeverity,
   extractFilePaths,
   normaliseTitle,

package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js

@@ -18,6 +18,7 @@
  */
 
 import { SEVERITIES } from '../findings/severity.js';
+import { formatEpicGrouping } from './epic-grouping-directive.js';
 import {
   renderFingerprintFooter,
   renderSemanticKeyFooter,
@@ -137,6 +138,10 @@ function formatKeyAssumptions(sourceReports) {
  * @param {string[]} params.sourceReports — list of source report paths.
  * @returns {string}
  */
+/**
+ * @param {{ groups: object[], findings: object[], sourceReports: object[] }} opts
+ * @returns {string} The `/mandrel-plan` seed one-pager.
+ */
 export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   if (
     !Array.isArray(groups) ||
@@ -152,6 +157,7 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   const scope = formatMVPScope(groups);
   const files = formatKeyFiles(groups);
   const assumptions = formatKeyAssumptions(sourceReports);
+  const grouping = formatEpicGrouping(groups);
 
   return [
     '# Idea Seed: Audit Remediation',
@@ -176,6 +182,10 @@ export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
     '',
     files,
     '',
+    '## Grouping',
+    '',
+    grouping,
+    '',
     '## Not Doing',
     '',
     '- Findings with severity below the operator-selected threshold.',

package/.agents/scripts/lib/changed-files.js

@@ -122,13 +122,98 @@ export function getChangedFiles({
   return parseNameOnlyStdout(res.stdout);
 }
 
+/**
+ * A full-length hex object id, as `git rev-parse` prints it. Used to reject
+ * anything that is not a resolved commit — a stubbed git interface in a test
+ * answers every `gitSpawn` with the same canned stdout, and a file list must
+ * never be mistaken for a merge head.
+ */
+const OBJECT_ID_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+
+/**
+ * Resolve the commit an in-progress merge is merging **in**, or `null` when no
+ * merge is in progress.
+ *
+ * Story #5131. `git diff --cached` with no commit argument diffs the index
+ * against `HEAD`, and during a merge `HEAD` is still the pre-merge tip — so a
+ * base-sync merge commit (`git merge --no-edit origin/<base>`, which
+ * `single-story-close`'s base-sync phase tells the operator to run by hand)
+ * put every file the base branch had landed into the staged scope. The
+ * pre-commit MI/CRAP gate then blocked the resolution commit for deltas
+ * belonging to already-landed, already-gated work, with no remedy: the preview
+ * is a delta against the baseline, not a baseline comparison, so no baseline
+ * refresh could silence it.
+ *
+ * Two details are load-bearing:
+ *
+ *   - **Ask git, never the filesystem.** `.git` is a *file*, not a directory,
+ *     in the linked worktrees this repo delivers from, so an
+ *     `existsSync('.git/MERGE_HEAD')` probe would be silently inert exactly
+ *     where deliveries happen. `rev-parse --verify` resolves the ref through
+ *     git's own worktree-aware lookup.
+ *   - **`--verify` fails closed on an octopus merge.** It refuses a
+ *     `MERGE_HEAD` naming more than one head, which lands here as `null` — the
+ *     pre-#5131 behaviour. Narrowing the scope wrongly would hide a real
+ *     regression; widening it only restores the status quo.
+ *
+ * Never throws: a merge is either detectable or it is not, and an
+ * undetectable one must degrade to the plain cached diff rather than fail the
+ * gate.
+ *
+ * @param {object} [params]
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {ReturnType<typeof createGitInterface>} [params.git]
+ * @returns {string | null} The merge head's object id, or `null`.
+ */
+export function resolveMergeHead({ cwd = process.cwd(), git } = {}) {
+  const gitIface = git ?? createGitInterface({});
+  let res;
+  try {
+    res = gitIface.gitSpawn(cwd, 'rev-parse', '-q', '--verify', 'MERGE_HEAD');
+  } catch {
+    return null;
+  }
+  if (res?.status !== 0) return null;
+  const sha = (res.stdout ?? '').trim();
+  return OBJECT_ID_RE.test(sha) ? sha : null;
+}
+
+/**
+ * Read the index file list against an explicit base, shared by
+ * `getStagedFiles` and `resolvePreviewScope` so the merge head is resolved
+ * once per scope resolution rather than once per caller.
+ *
+ * @param {object} params
+ * @param {string} params.cwd
+ * @param {ReturnType<typeof createGitInterface>} params.git
+ * @param {string | null} params.mergeHead
+ * @returns {string[]}
+ */
+function stagedFilesAgainst({ cwd, git, mergeHead }) {
+  const args = ['diff', '--name-only', '--cached'];
+  if (mergeHead) args.push(mergeHead);
+  const res = git.gitSpawn(cwd, ...args);
+  if (res.status !== 0) {
+    const detail = res.stderr || res.stdout || `exit ${res.status}`;
+    throw new Error(`[staged] unable to read cached diff: ${detail}`);
+  }
+  return parseNameOnlyStdout(res.stdout);
+}
+
 /**
  * Resolve paths in the index (staged for commit). Used by `quality-preview
  * --staged` so pre-commit gates score only the commit payload, not unstaged
  * working-tree edits.
  *
  * Semantics:
- *   - Runs `git diff --name-only --cached`.
+ *   - Runs `git diff --name-only --cached`, which diffs the index against
+ *     `HEAD`.
+ *   - **During a merge**, diffs the index against `MERGE_HEAD` instead
+ *     (Story #5131), so the scope is the merging branch's own contribution
+ *     plus its conflict resolutions — not the base branch's incoming work.
+ *     `git merge-base HEAD MERGE_HEAD` would *not* do: diffing the index
+ *     against the fork point re-admits everything the base branch landed since
+ *     it, which is the whole defect.
  *   - Returns forward-slash-normalized repo-relative paths.
  *   - Non-zero git exit throws — staged mode must not silently widen scope.
  *
@@ -139,12 +224,11 @@ export function getChangedFiles({
  */
 export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
   const gitIface = git ?? createGitInterface({});
-  const res = gitIface.gitSpawn(cwd, 'diff', '--name-only', '--cached');
-  if (res.status !== 0) {
-    const detail = res.stderr || res.stdout || `exit ${res.status}`;
-    throw new Error(`[staged] unable to read cached diff: ${detail}`);
-  }
-  return parseNameOnlyStdout(res.stdout);
+  return stagedFilesAgainst({
+    cwd,
+    git: gitIface,
+    mergeHead: resolveMergeHead({ cwd, git: gitIface }),
+  });
 }
 
 /**
@@ -154,6 +238,11 @@ export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
  * is ignored. Otherwise a `changedSinceRef` limits to that three-dot diff;
  * when both are absent the caller runs in full-repo mode (`scopeSet: null`).
  *
+ * In `staged` scope, `diffRef` carries the in-progress merge head when there
+ * is one (Story #5131) and `null` otherwise, so a caller can tell the operator
+ * *why* the scope narrowed. `scope` stays `'staged'` either way — the merge is
+ * a property of the base the index is read against, not a different mode.
+ *
  * @param {object} [params]
  * @param {boolean} [params.staged=false]
  * @param {string | null} [params.changedSinceRef=null]
@@ -172,8 +261,10 @@ export function resolvePreviewScope({
   git,
 } = {}) {
   if (staged) {
-    const files = getStagedFiles({ cwd, git });
-    return { scopeSet: new Set(files), scope: 'staged', diffRef: null };
+    const gitIface = git ?? createGitInterface({});
+    const mergeHead = resolveMergeHead({ cwd, git: gitIface });
+    const files = stagedFilesAgainst({ cwd, git: gitIface, mergeHead });
+    return { scopeSet: new Set(files), scope: 'staged', diffRef: mergeHead };
   }
   if (changedSinceRef) {
     try {

package/.agents/scripts/lib/config-settings-schema.js

@@ -622,6 +622,17 @@ const PLANNING_SCHEMA = {
 // qa.* — Agent-driven QA harness contract (Epic #3214)
 // ---------------------------------------------------------------------------
 
+// The per-environment sign-in seam. `{ urlTemplate }` is a dev
+// impersonation route; `{ skill }` names a skill by its tier-relative id
+// (e.g. `stack/qa/acme-sso`), resolved against the payload skills root and
+// then the consumer-writable `.agents/local/skills/` zone (Story #5135).
+//
+// No default anywhere in this file may name a skill id: the framework ships
+// no sign-in skill, so any id baked into an inventory value would be a
+// dangling pointer a consumer copies verbatim — the exact defect #5134
+// reported. The `{ skill }` arm is taught in prose (`.agents/README.md`
+// § "Expose a `signInSeam`"), and `resolveQaEnvironment` fails loudly on an
+// id that resolves under neither root.
 const QA_SIGN_IN_SEAM_SCHEMA = {
   oneOf: [
     {
@@ -654,9 +665,13 @@ const QA_PERSONAS_SCHEMA = {
   description:
     'Personas the QA-harness sign-in seam accepts. Two accepted shapes: (1) a plain array of persona names — the honest shape for a `urlTemplate` dev-impersonation seam, where the persona name is the sole input the workflow consumes; (2) the object-map form keyed by persona name, where each entry carries per-persona auth material (`credentialRef` or `signInSkill`) consulted only under a skill-based or credential-based seam.',
   // Inventory value: an illustrative map showing both per-persona shapes.
+  // Inventory value: illustrative credential references, not resolvable
+  // ones. It deliberately does NOT illustrate the `signInSkill` arm — a
+  // skill id in a shipped default is a dangling pointer (see
+  // QA_SIGN_IN_SEAM_SCHEMA above); that arm is taught in prose instead.
   default: {
     admin: { credentialRef: 'QA_ADMIN_CREDENTIAL' },
-    member: { signInSkill: 'stack/qa/sign-in-member' },
+    member: { credentialRef: 'QA_MEMBER_CREDENTIAL' },
   },
   oneOf: [
     {
@@ -703,11 +718,11 @@ const QA_PERSONAS_SCHEMA = {
 const QA_ENVIRONMENTS_SCHEMA = {
   type: 'object',
   description:
-    'Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, its own per-environment sign-in seam (the same url-template/skill union as the top-level seam), and an optional `allowWrites` gate. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.',
+    'Deployment targets the QA harness can run against (Epic #4326). A map keyed by environment name (e.g. `local`, `staging`), each carrying its own `baseUrl`, an optional per-environment sign-in seam, and an optional `allowWrites` gate. `signInSeam` is the union `{ urlTemplate }` (a dev impersonation route) or `{ skill }` (a skill id such as `stack/qa/acme-sso`, resolved against `.agents/skills/` then the consumer-writable `.agents/local/skills/` zone, and rejected loudly by resolveQaEnvironment when it resolves under neither); omit it entirely for a target with no sign-in seam. resolveQaEnvironment selects one environment per invocation by name or by raw-URL origin match against `baseUrl`; `allowWrites` defaults to true only for the `local` environment. Replaces the retired top-level single `signInSeam`.',
   // Inventory value: an illustrative two-environment map, not a resolvable
-  // default. The QA harness is opt-in and every value here is
-  // project-specific; the entry exists so `mandrel explain` can show the
-  // expected shape.
+  // default. `staging` deliberately carries NO `signInSeam` — that is the
+  // honest shape for a deployed target with no dev sign-in seam, and it
+  // shows the field is optional (Story #5135).
   default: {
     local: {
       baseUrl: 'http://localhost:3000',
@@ -715,7 +730,6 @@ const QA_ENVIRONMENTS_SCHEMA = {
     },
     staging: {
       baseUrl: 'https://staging.example.test',
-      signInSeam: { skill: 'stack/qa/sign-in' },
       allowWrites: false,
     },
   },
@@ -727,7 +741,11 @@ const QA_ENVIRONMENTS_SCHEMA = {
       signInSeam: QA_SIGN_IN_SEAM_SCHEMA,
       allowWrites: { type: 'boolean' },
     },
-    required: ['baseUrl', 'signInSeam'],
+    // `signInSeam` is OPTIONAL (Story #5135). An environment that resolves no
+    // seam is a state the QA workflows already branch on — they drive the
+    // unauthenticated surface and record the gap — so requiring it made an
+    // honestly seamless remote target undeclarable.
+    required: ['baseUrl'],
     additionalProperties: false,
   },
 };