mandrel 1.82.0 → 1.84.0

package/.agents/scripts/lib/findings/severity.js

@@ -5,8 +5,8 @@
  * the shared findings core previously each declared their own severity list —
  * `classify-finding.js` (`[unknown, low, medium, high, critical]`),
  * `promote-finding.js` (`SEVERITY_RANK` over `[critical … info]`), and the
- * `qa-finding` / `qa-ledger` JSON schemas (`[critical, high, medium, low,
- * info]`). Because `severity` is a `fingerprintFinding` identity field
+ * `qa-ledger` JSON schema (`[critical, high, medium, low, info]`). Because
+ * `severity` is a `fingerprintFinding` identity field
  * (`route-finding.js`), the same finding could hash to different SHAs depending
  * on which path normalised its severity, silently weakening dedup. This module
  * collapses all three onto one enum + one normaliser so the fingerprint is
@@ -14,9 +14,8 @@
  *
  * The canonical order is `critical | high | medium | low | info`, highest →
  * lowest, and it MUST match the `severity` enum in
- * `.agents/schemas/qa-ledger.schema.json` (and the mirrored `qa-finding`
- * schema). Pure module: no I/O, no module-level state beyond the frozen
- * constants.
+ * `.agents/schemas/qa-ledger.schema.json`. Pure module: no I/O, no
+ * module-level state beyond the frozen constants.
  */
 
 /**
@@ -24,7 +23,7 @@
  * This is the ONLY definition of the severity vocabulary in the findings core;
  * `classify-finding.js` and `promote-finding.js` re-export / import it rather
  * than re-declaring their own list. Mirrors the `severity` enum in
- * `qa-ledger.schema.json` / `qa-finding.schema.json`.
+ * `qa-ledger.schema.json`.
  */
 export const SEVERITIES = Object.freeze([
   'critical',

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -8,12 +8,69 @@
  */
 
 import { resolveBundleSizeEnvOverrides } from '../../../baselines/env-overrides.js';
-import { checkKernelVersion } from '../../../baselines/kernel.js';
+import {
+  checkKernelVersion,
+  getKindModule,
+} from '../../../baselines/kernel.js';
 import * as reader from '../../../baselines/reader.js';
 import { Logger } from '../../../Logger.js';
+import { isIgnoredByGlobs } from '../../../maintainability-utils.js';
 import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
 import { applyFloors, flattenBreaches } from './floors.js';
 
+/**
+ * Defense-in-depth against an `ignoreGlobs`-poisoned baseline (Epic #4326
+ * incident). The generation path already drops `ignoreGlobs`-matched files
+ * before they reach `rows` (both the canonical `buildDefaultMaintainabilityScorer`
+ * and the story-close `buildKindScorer`), so a freshly-generated baseline's
+ * `rollup["*"]` never includes an ignored file. But the floor check trusts the
+ * *stored* `rollup["*"]`: if a baseline is poisoned by some other route — a
+ * stale branch's older tooling, a hand-edit, a future generation bug — an
+ * ignored file's metric can still drag the global floor axis (e.g.
+ * maintainability `min`) below its floor and block every downstream close.
+ *
+ * This recomputes the global `*` aggregate over the baseline rows that are NOT
+ * matched by the gate's `ignoreGlobs`, using the kind's own canonical
+ * `rollup()` aggregator, so the floor axis reflects only the files the gate is
+ * meant to police. It is a **no-op for a correctly-generated baseline** (no
+ * ignored file is present in `rows`, so the filtered set is identical and the
+ * stored `rollup["*"]` is returned unchanged) and only affects the `*`
+ * component the incident poisons; named-component rollups are left as stored.
+ * The compare/regression stage is untouched — this only reshapes the floor
+ * input. All three `ignoreGlobs`-configured gates (maintainability, crap,
+ * duplication) are `path`-keyed, so the shared path matcher applies uniformly.
+ *
+ * Kept module-local (not exported): the poison-exclusion behaviour is covered
+ * end-to-end through `evaluateKind` by the `check-baselines.min-floor` suite,
+ * so there is no external consumer to justify widening the surface.
+ *
+ * @param {{ kind: string, baseline: { rollup?: object, rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
+ * @returns {object} the effective rollup to feed the floor check
+ */
+function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
+  const rollup = baseline?.rollup;
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return rollup;
+  const rows = baseline?.rows;
+  if (!Array.isArray(rows) || rows.length === 0) return rollup;
+  let mod;
+  try {
+    mod = getKindModule(kind);
+  } catch {
+    return rollup;
+  }
+  if (mod?.keyField !== 'path' || typeof mod.rollup !== 'function')
+    return rollup;
+  const kept = rows.filter((row) => {
+    const p = row?.path;
+    return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
+  });
+  // Nothing ignored is present → the stored rollup already excludes ignored
+  // files (the correct-baseline fast path); return it untouched.
+  if (kept.length === rows.length) return rollup;
+  const recomputed = mod.rollup(kept);
+  return { ...rollup, '*': recomputed?.['*'] ?? rollup?.['*'] };
+}
+
 function loadHeadBaseline(kind, cwd, configPath) {
   try {
     return { baseline: reader.load(kind, { cwd, configPath }) };
@@ -100,7 +157,13 @@ export async function evaluateKind({
   const headLoad = loadHeadBaseline(kind, cwd, configPath);
   if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
   const baseline = headLoad.baseline;
-  const findings = applyFloors(kind, baseline.rollup, gateBlock.floors ?? {});
+  const floorRollup = rollupExcludingIgnored({
+    kind,
+    baseline,
+    ignoreGlobs: gateBlock.ignoreGlobs,
+    cwd,
+  });
+  const findings = applyFloors(kind, floorRollup, gateBlock.floors ?? {});
   const breaches = flattenBreaches(findings);
   const cmp = await evaluateCompare({ kind, gateBlock, scope, cwd });
   const rawCompare = runCompareStage(baseline, cmp);

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -27,7 +27,7 @@ import {
   PROJECT_ROOT,
   resolveConfig,
 } from '../config-resolver.js';
-import { stripEpicSection } from '../epic-body-sections.js';
+import { sliceEpicBodyForDelivery } from '../epic-body-sections.js';
 import { Logger } from '../Logger.js';
 import {
   buildEnvelope,
@@ -233,6 +233,71 @@ export function extractStorySections(body) {
   return { acceptance, verify };
 }
 
+/**
+ * Remove one `## <heading>` section (heading line through the last line
+ * before the next `## ` heading, or EOF) from a Story body. Byte-preserving
+ * outside the removed span. No-op when the heading is absent. Case- and
+ * whitespace-tolerant to match `extractSectionList`.
+ *
+ * @param {string} body
+ * @param {string} heading
+ * @returns {string}
+ */
+function stripSection(body, heading) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  const pattern = new RegExp(
+    `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+    'mi',
+  );
+  const startMatch = body.match(pattern);
+  if (!startMatch || startMatch.index == null) return body;
+  const start = startMatch.index;
+  const afterHeading = start + startMatch[0].length;
+  const rest = body.slice(afterHeading);
+  const nextHeading = rest.search(/^##\s+/m);
+  const end = nextHeading === -1 ? body.length : afterHeading + nextHeading;
+  const before = body.slice(0, start).replace(/\n+$/, '\n');
+  const after = body.slice(end).replace(/^\n+/, '');
+  return (before + after).replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+/**
+ * Strip the inline `## Acceptance Criteria` / `## Acceptance` and `## Verify`
+ * sections from a Story body. Used to build the `taskInstructions` section
+ * when the dedicated `acceptanceCriteria` / `verificationCommands` envelope
+ * sections already carry those lists — so the binding acceptance/verify
+ * content appears exactly once in the hydrated envelope rather than being
+ * duplicated between the dedicated sections and the full task body.
+ *
+ * Each heading group is stripped only when its own dedicated section was
+ * emitted (`acceptance` gates `## Acceptance Criteria` + `## Acceptance`;
+ * `verify` gates `## Verify`). This keeps the strip symmetric with what was
+ * reproduced elsewhere in the envelope: a `## Verify` section that carried no
+ * bullets (so no dedicated `verificationCommands` section fired) is left
+ * intact in `taskInstructions` rather than being silently dropped. Both flags
+ * default to `true` so a no-argument call preserves the original
+ * strip-everything behaviour.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: boolean, verify?: boolean }} [opts]
+ * @returns {string}
+ */
+export function stripStorySectionsForTaskInstructions(
+  body,
+  { acceptance = true, verify = true } = {},
+) {
+  if (typeof body !== 'string' || body.length === 0) return body ?? '';
+  let out = body;
+  if (acceptance) {
+    out = stripSection(out, 'Acceptance Criteria');
+    out = stripSection(out, 'Acceptance');
+  }
+  if (verify) {
+    out = stripSection(out, 'Verify');
+  }
+  return out;
+}
+
 /**
  * Detect whether the dispatched unit is a 2-tier Story (Story is the
  * leaf, carries inline acceptance/verify) vs. a 4-tier Task (Task is
@@ -371,16 +436,15 @@ async function buildHierarchySections(task, provider, epicId, agentSettings) {
       try {
         const t = await provider.getTicket(item.id);
         provenance.push(ticketSnapshot(t, retrievedAt));
-        // Hydration section-elision guardrail (Story #4324): the Epic
-        // body's ## Acceptance Table managed section is authoring/close
-        // machinery — never delivery context. Strip it before it reaches
-        // a story agent's prompt so per-story prompt size stays flat
-        // versus the pre-fold baseline (the old acceptance-spec ticket
-        // was never hydrated either).
+        // Hydration section-slicing guardrail (Story #4340): the Epic body
+        // is sliced down to only the sections a delivery story agent acts
+        // on — Goal / Non-Goals / User Stories / Tech Spec (plus any
+        // operator-authored section, fail-open). Ideation / authoring /
+        // close machinery (## Context, ## Scope, ## Acceptance Criteria,
+        // and the ## Acceptance Table managed region) is dropped so
+        // per-story prompt size stays flat versus the pre-fold baseline.
         const body =
-          item.key === 'Epic'
-            ? stripEpicSection(t.body ?? '', 'acceptanceTable')
-            : t.body;
+          item.key === 'Epic' ? sliceEpicBodyForDelivery(t.body ?? '') : t.body;
         return `### ${item.key}: ${t.title} (#${t.id})\n\n${body}\n`;
       } catch (err) {
         const detail = err?.message ? `: ${err.message}` : '';
@@ -485,9 +549,16 @@ function buildStaticSections(
     }
   }
 
+  // Track which dedicated section(s) were emitted so taskInstructions drops
+  // only the inline sections that were actually reproduced elsewhere in the
+  // envelope — keeping each binding acceptance/verify item present exactly
+  // once, without dropping a bulletless section that has no dedicated twin.
+  let acceptanceEmitted = false;
+  let verifyEmitted = false;
   if (isTwoTierStoryTask(task)) {
     const { acceptance, verify } = extractStorySections(task.body ?? '');
     if (acceptance.length > 0) {
+      acceptanceEmitted = true;
       sections.push({
         name: 'acceptanceCriteria',
         priority: DEFAULT_SECTION_PRIORITIES.acceptanceCriteria,
@@ -499,6 +570,7 @@ function buildStaticSections(
       });
     }
     if (verify.length > 0) {
+      verifyEmitted = true;
       sections.push({
         name: 'verificationCommands',
         priority: DEFAULT_SECTION_PRIORITIES.verificationCommands,
@@ -511,11 +583,24 @@ function buildStaticSections(
     }
   }
 
+  // When a dedicated acceptance/verify section carries that list, strip the
+  // matching inline heading(s) from the task body so they are not duplicated
+  // in taskInstructions. Each group is gated on its own section: an inline
+  // section with no dedicated twin (e.g. a bulletless `## Verify`) is left
+  // intact. When neither fired, taskInstructions is byte-identical to the
+  // full body.
+  const taskBody =
+    acceptanceEmitted || verifyEmitted
+      ? stripStorySectionsForTaskInstructions(task.body ?? '', {
+          acceptance: acceptanceEmitted,
+          verify: verifyEmitted,
+        })
+      : task.body;
   sections.push({
     name: 'taskInstructions',
     priority: DEFAULT_SECTION_PRIORITIES.taskInstructions,
     elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.taskInstructions,
-    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${task.body}`,
+    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${taskBody}`,
     source: { kind: 'ticket', ref: String(task.id) },
   });
 

package/.agents/scripts/lib/orchestration/doc-reader.js

@@ -4,6 +4,35 @@ import { getPaths } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
 import { applyBudget } from './planning-context-budget.js';
 
+/**
+ * Read an explicit list of doc files relative to `docsRoot`, returning one
+ * `{ name, path, content }` object per file that exists and reads cleanly.
+ * Missing or unreadable files are skipped silently (mirrors
+ * {@link readDocsFromRoot}'s per-file try/catch). Order is preserved from the
+ * input list. This is the shared read/normalize seam the per-Epic docs digest
+ * builds on (Story #4338) so there is a single home for the fs read path.
+ *
+ * @param {{ files: string[], docsRoot?: string }} args
+ * @returns {Promise<Array<{ name: string, path: string, content: string }>>}
+ */
+export async function readDocFiles({ files, docsRoot } = {}) {
+  const list = Array.isArray(files) ? files : [];
+  const root =
+    typeof docsRoot === 'string' && docsRoot.length > 0 ? docsRoot : '.';
+  const reads = list.map(async (name) => {
+    const full = path.join(root, name);
+    try {
+      const stat = await fs.promises.stat(full);
+      if (!stat.isFile()) return null;
+      const content = await fs.promises.readFile(full, 'utf-8');
+      return { name, path: name, content };
+    } catch (_e) {
+      return null;
+    }
+  });
+  return (await Promise.all(reads)).filter(Boolean);
+}
+
 async function readDocsFromRoot(docsRoot, settings) {
   const explicit =
     Array.isArray(settings.docsContextFiles) &&

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -0,0 +1,134 @@
+/**
+ * docs-digest.js — per-Epic docs digest builder (Story #4338).
+ *
+ * `/deliver` story sub-agents previously re-read every file in
+ * `project.docsContextFiles` on every Story, re-paying the full docs payload
+ * per child. This module produces a single **digest** — one compact markdown
+ * outline per configured doc — that the parent threads into every child prompt
+ * once. The digest gives each child enough shape (path, size, heading outline
+ * with line numbers, and the first paragraph under each `##` section) to decide
+ * which full files to pull on demand, instead of ingesting the whole set up
+ * front.
+ *
+ * The heavy lifting of reading + normalizing doc bodies is delegated to
+ * `doc-reader.js` (`readDocFiles`), keeping a single home for the fs read path.
+ */
+
+import { readDocFiles } from './doc-reader.js';
+
+/**
+ * Level-2 / level-3 markdown heading matcher. Mirrors the outline granularity
+ * the planning-context budget already uses so the two surfaces agree on what a
+ * "section" is.
+ */
+const HEADING_RE = /^(#{2,3})\s+(.+?)\s*$/;
+
+function byteLen(s) {
+  if (s == null) return 0;
+  return Buffer.byteLength(String(s), 'utf-8');
+}
+
+/**
+ * Extract the heading outline (level + text + 1-based line number) from a
+ * markdown body. Line numbers let a child jump straight to the section it
+ * needs when it pulls the full file.
+ *
+ * @param {string} content
+ * @returns {Array<{ level: number, text: string, line: number }>}
+ */
+function extractOutline(content) {
+  if (!content) return [];
+  const lines = String(content).split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = HEADING_RE.exec(lines[i]);
+    if (m) out.push({ level: m[1].length, text: m[2], line: i + 1 });
+  }
+  return out;
+}
+
+/**
+ * The first non-empty paragraph that follows a given heading line, up to the
+ * next heading or a blank-line paragraph break. Returns '' when the section
+ * has no prose (e.g. a heading immediately followed by a sub-heading).
+ *
+ * @param {string[]} lines full doc split into lines
+ * @param {number} headingLine 1-based line of the heading
+ * @returns {string}
+ */
+function firstParagraphAfter(lines, headingLine) {
+  const para = [];
+  for (let i = headingLine; i < lines.length; i++) {
+    const line = lines[i];
+    if (HEADING_RE.test(line)) break;
+    if (line.trim() === '') {
+      if (para.length > 0) break;
+      continue;
+    }
+    para.push(line.trim());
+  }
+  return para.join(' ').trim();
+}
+
+/**
+ * Render one doc's digest section: path + byte size, then a bulleted heading
+ * outline where each `##` bullet carries the first paragraph beneath it.
+ *
+ * @param {{ path: string, content: string }} doc
+ * @returns {string} markdown block
+ */
+function renderDocSection(doc) {
+  const content = typeof doc.content === 'string' ? doc.content : '';
+  const lines = content.split(/\r?\n/);
+  const outline = extractOutline(content);
+  const size = byteLen(content);
+
+  const parts = [`### \`${doc.path}\` (${size} bytes)`, ''];
+  if (outline.length === 0) {
+    parts.push('_No `##`/`###` headings._', '');
+    return parts.join('\n');
+  }
+
+  for (const h of outline) {
+    const indent = h.level === 3 ? '  ' : '';
+    parts.push(`${indent}- L${h.line} \`${'#'.repeat(h.level)}\` ${h.text}`);
+    if (h.level === 2) {
+      const para = firstParagraphAfter(lines, h.line);
+      if (para) parts.push(`${indent}  ${para}`);
+    }
+  }
+  parts.push('');
+  return parts.join('\n');
+}
+
+/**
+ * Build the per-Epic docs digest markdown from the configured docs context
+ * files. Missing files are skipped silently (the read seam returns only the
+ * files it could stat + read). Returns `null` when there is nothing to digest
+ * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
+ * `docsDigestPath` rather than writing an empty file.
+ *
+ * @param {{ docsContextFiles?: string[], docsRoot?: string }} args
+ * @returns {Promise<string|null>} the digest markdown, or null when there are
+ *   no files to digest.
+ */
+export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
+  const files = Array.isArray(docsContextFiles) ? docsContextFiles : [];
+  if (files.length === 0) return null;
+
+  const docs = await readDocFiles({ files, docsRoot });
+  if (docs.length === 0) return null;
+
+  const header = [
+    '# Docs digest',
+    '',
+    'Per-Epic outline of the project docs context set. Each entry lists the',
+    'file path, byte size, and its heading outline (with line numbers) plus',
+    'the first paragraph under each `##` section. Read the full file on demand',
+    'when a section looks relevant — do **not** ingest the whole set per Story.',
+    '',
+  ].join('\n');
+
+  const sections = docs.map(renderDocSection).join('\n');
+  return `${header}\n${sections}`.replace(/\n+$/, '\n');
+}

package/.agents/scripts/lib/orchestration/story-close/baseline-attribution/phases/refresh-commit.js

@@ -32,6 +32,7 @@ import { Logger as DefaultLogger } from '../../../../Logger.js';
 import {
   calculateAll as defaultCalculateAll,
   scanDirectory as defaultScanDirectory,
+  isIgnoredByGlobs as isIgnoredByGlobsMi,
 } from '../../../../maintainability-utils.js';
 
 /**
@@ -101,7 +102,20 @@ export function buildKindScorer({
           const underTarget = targetAbsDirs.some(
             (root) => abs === root || abs.startsWith(`${root}${path.sep}`),
           );
-          if (underTarget) sourceList.push(abs);
+          // Apply `ignoreGlobs` here too — the full-scope walk drops
+          // ignore-matched files via `scanDirectory`, so the diff-scope path
+          // must do the same or an ignored-but-changed file (e.g. one matched
+          // by `config-settings-schema*.js`) enters `rows` and drags the
+          // `rollup["*"].min` below the maintainability floor. This mirrors the
+          // canonical `buildDefaultMaintainabilityScorer` (refresh-service.js,
+          // Story #4293); the story-close auto-refresh routes through this
+          // scorer, not that one, so the fix has to live here too.
+          if (
+            underTarget &&
+            !isIgnoredByGlobsMi(abs, miIgnoreGlobs, effectiveCwd)
+          ) {
+            sourceList.push(abs);
+          }
         }
       }
       const scores = await calculateAll(sourceList);

package/.agents/scripts/lib/qa/console-allowlist.js

@@ -19,10 +19,11 @@
  *
  * The emitted finding aligns with the `F#` finding shape from Tech Spec #3285
  * (`{ id, classification, surface, symptom, likelyRootCause, disposition,
- * acceptance, evidence: { console[], network[] } }`). Finding-shape *schema*
- * validation (`qa-finding.schema.json`) is a sibling Story; this module only
- * produces the console-derived subset and leaves richer enrichment
- * (likely-root-cause heuristics, drafting) to later layers.
+ * acceptance, evidence: { console[], network[] } }`). This module produces the
+ * console-derived subset; `/qa-run` (Story #4330) maps each such finding onto a
+ * `QaLedgerItem` (`qa-ledger.schema.json`) before routing it through the shared
+ * classify/route/dedup/promote core, leaving richer enrichment
+ * (likely-root-cause heuristics, drafting) to those later layers.
  */
 
 /**