mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/doc-tiers.js

@@ -0,0 +1,291 @@
+/**
+ * Doc-tier resolver (Story #4438, Epic #4430 — Context Economy).
+ *
+ * Pure functions that classify the repository's documentation into the four
+ * read-tiers Mandrel's context model recognizes, each entry carrying its
+ * on-disk byte size so a byte budget can ratchet against it:
+ *
+ *   - `alwaysLoaded`  — `CLAUDE.md` plus the transitive closure of its
+ *                       `@`-import references (`@AGENTS.md`,
+ *                       `@.agents/instructions.md`, the persona, the always-on
+ *                       rules, …). This is the context every session re-pays
+ *                       on every subagent spawn (instructions.md § 4), so it is
+ *                       the primary budget the context-budget ratchet gates.
+ *   - `mandatoryRead` — the resolved `project.docsContextFiles` set (prefixed
+ *                       by `project.paths.docsRoot`), existing files only. This
+ *                       is the `docsContextFiles` half the Epic AC gates; it
+ *                       skips silently when the set is unconfigured or its
+ *                       files are absent.
+ *   - `digestVisible` — the situational **Conditional Reads** docs from
+ *                       instructions.md § 3 (`docs/style-guide.md`,
+ *                       `docs/web-routes.md`) — surfaced only when a task
+ *                       touches UI/routing, i.e. visible through the docs
+ *                       digest rather than always read. Existing files only.
+ *   - `onDemand`      — the on-demand `.agents/rules/*.md` set (instructions.md
+ *                       § 1.F): every rule file that is **not** part of the
+ *                       always-on core already captured in `alwaysLoaded`.
+ *
+ * A file that could appear in more than one tier is kept in its **highest**
+ * tier only (alwaysLoaded > mandatoryRead > digestVisible > onDemand), so the
+ * four arrays partition the doc set with no double-counting.
+ *
+ * The closure is discovered by parsing `@`-import references and following
+ * them recursively (cycle-safe via a visited set). A candidate `@`-token only
+ * counts as an import when it resolves to an existing repo file, which
+ * naturally filters prose mentions (`@[USERNAME]`, `noreply@example.com`,
+ * backtick-wrapped `` `@`-imported `` phrasing).
+ *
+ * Security (security-baseline § 5 — Data Leakage & Logging): every function
+ * emits only repo-relative paths and byte counts — never file contents.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Basename of the always-loaded entry document (the root of the closure).
+ * @type {string}
+ */
+const ENTRY_DOC = 'CLAUDE.md';
+
+/**
+ * Always-on core rule files (instructions.md § 1.F). These live in the
+ * `alwaysLoaded` closure (imported by `CLAUDE.md`); every other
+ * `.agents/rules/*.md` file is `onDemand`.
+ * @type {string[]}
+ */
+const ALWAYS_ON_RULES = ['security-baseline.md', 'git-conventions.md'];
+
+/**
+ * Conditional-read docs (instructions.md § 3 — "Conditional Reads"), resolved
+ * against `project.paths.docsRoot`. Present in the `digestVisible` tier when
+ * they exist.
+ * @type {string[]}
+ */
+const CONDITIONAL_DOCS = ['style-guide.md', 'web-routes.md'];
+
+/**
+ * Match `@`-import tokens: an `@` at start-of-line or after whitespace,
+ * followed by a path token that stops at whitespace or common closing
+ * punctuation. The resolved-file existence check downstream is the real
+ * filter; this regex only harvests candidates.
+ */
+const IMPORT_RE = /(?:^|\s)@([^\s'"`)\]}>,]+)/gm;
+
+/**
+ * Default fs surface — a small subset of `node:fs` so callers can inject a
+ * fixture double in tests without touching the real filesystem.
+ * @typedef {{
+ *   existsSync: (p: string) => boolean,
+ *   readFileSync: (p: string, enc: string) => string,
+ *   statSync: (p: string) => { size: number },
+ * }} FsLike
+ */
+
+/**
+ * Parse the raw `@`-import specifiers from a source document. A trailing `.`
+ * or `:` (sentence punctuation) is trimmed so `@AGENTS.md.` still resolves.
+ *
+ * @param {string} source
+ * @returns {string[]} raw specifiers in first-seen order
+ */
+export function parseImportSpecifiers(source) {
+  const specs = [];
+  for (const m of String(source ?? '').matchAll(IMPORT_RE)) {
+    let spec = m[1];
+    // Strip trailing sentence punctuation that the greedy class allowed in.
+    while (spec.length > 0 && (spec.endsWith('.') || spec.endsWith(':'))) {
+      spec = spec.slice(0, -1);
+    }
+    if (spec.length > 0) specs.push(spec);
+  }
+  return specs;
+}
+
+/**
+ * Convert an absolute path to a repo-relative, posix-separated id.
+ *
+ * @param {string} root absolute repo root
+ * @param {string} abs absolute path
+ * @returns {string}
+ */
+function toRepoRel(root, abs) {
+  return path.relative(root, abs).split(path.sep).join('/');
+}
+
+/**
+ * Build a `{ path, bytes }` entry for a repo file, or `null` when it does not
+ * exist. `path` is repo-relative posix; `bytes` is the on-disk byte size.
+ *
+ * @param {string} root absolute repo root
+ * @param {string} rel repo-relative path
+ * @param {FsLike} fs
+ * @returns {{ path: string, bytes: number } | null}
+ */
+function fileEntry(root, rel, fs) {
+  const abs = path.resolve(root, rel);
+  if (!fs.existsSync(abs)) return null;
+  let bytes = 0;
+  try {
+    bytes = fs.statSync(abs).size;
+  } catch {
+    return null;
+  }
+  return { path: toRepoRel(root, abs), bytes };
+}
+
+/**
+ * Resolve the always-loaded closure: `CLAUDE.md` plus every file reachable by
+ * recursively parsing `@`-import references. Cycle-safe (a visited set keyed
+ * by repo-relative path). Nested imports resolve relative to the importing
+ * file's directory (Claude Code `@`-import semantics). Non-resolving `@`-tokens
+ * are ignored, so prose mentions never pollute the closure.
+ *
+ * @param {string} root absolute repo root (where `CLAUDE.md` lives)
+ * @param {{ fs?: FsLike }} [opts]
+ * @returns {Array<{ path: string, bytes: number }>} sorted by path; empty when
+ *   `CLAUDE.md` is absent
+ */
+export function resolveAlwaysLoadedClosure(root, { fs = nodeFs } = {}) {
+  const entryAbs = path.resolve(root, ENTRY_DOC);
+  if (!fs.existsSync(entryAbs)) return [];
+
+  const visited = new Set();
+  const entries = new Map();
+  const queue = [entryAbs];
+
+  while (queue.length > 0) {
+    const abs = queue.shift();
+    const rel = toRepoRel(root, abs);
+    if (visited.has(rel)) continue;
+    visited.add(rel);
+
+    if (!fs.existsSync(abs)) continue;
+    let bytes = 0;
+    let source = '';
+    try {
+      bytes = fs.statSync(abs).size;
+      source = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    entries.set(rel, { path: rel, bytes });
+
+    const dir = path.dirname(abs);
+    for (const spec of parseImportSpecifiers(source)) {
+      const targetAbs = path.resolve(dir, spec);
+      const targetRel = toRepoRel(root, targetAbs);
+      if (!visited.has(targetRel) && fs.existsSync(targetAbs)) {
+        queue.push(targetAbs);
+      }
+    }
+  }
+
+  return [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Read the resolved `project.docsContextFiles` list from a config object,
+ * prefixed by `project.paths.docsRoot`. Mirrors the `contextDocs` half of
+ * `resolveDocList` in `validate-docs-freshness.js` (new-shape first, legacy
+ * top-level fallback).
+ *
+ * @param {object} config resolved config (`resolveConfig()` output)
+ * @returns {string[]} repo-relative posix doc paths (existence not yet checked)
+ */
+export function docsContextPaths(config) {
+  const project = config?.project ?? config;
+  const contextDocs = Array.isArray(project?.docsContextFiles)
+    ? project.docsContextFiles
+    : Array.isArray(config?.docsContextFiles)
+      ? config.docsContextFiles
+      : [];
+  const docsRoot =
+    project?.paths?.docsRoot ?? config?.paths?.docsRoot ?? 'docs';
+  return contextDocs.map((f) => path.posix.join(docsRoot, f));
+}
+
+/**
+ * Resolve the four documentation read-tiers, each entry `{ path, bytes }`,
+ * partitioned so no path appears in more than one tier (highest tier wins).
+ *
+ * @param {object} config resolved config (`resolveConfig()` output)
+ * @param {{ root?: string, fs?: FsLike }} [opts]
+ * @returns {{ tiers: {
+ *   alwaysLoaded: Array<{ path: string, bytes: number }>,
+ *   mandatoryRead: Array<{ path: string, bytes: number }>,
+ *   digestVisible: Array<{ path: string, bytes: number }>,
+ *   onDemand: Array<{ path: string, bytes: number }>,
+ * } }}
+ */
+export function resolveDocTiers(
+  config,
+  { root = process.cwd(), fs = nodeFs } = {},
+) {
+  const claimed = new Set();
+  const collect = (relPaths) => {
+    const out = [];
+    for (const rel of relPaths) {
+      const entry = fileEntry(root, rel, fs);
+      if (!entry) continue;
+      if (claimed.has(entry.path)) continue;
+      claimed.add(entry.path);
+      out.push(entry);
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  };
+
+  // 1. always-loaded: CLAUDE.md @-import closure. Pre-claim its paths first so
+  //    a lower tier never re-lists a closure member.
+  const alwaysLoaded = resolveAlwaysLoadedClosure(root, { fs });
+  for (const e of alwaysLoaded) claimed.add(e.path);
+
+  // 2. mandatory-read: resolved docsContextFiles (existing files only).
+  const docsRoot =
+    config?.project?.paths?.docsRoot ?? config?.paths?.docsRoot ?? 'docs';
+  const mandatoryRead = collect(docsContextPaths(config));
+
+  // 3. digest-visible: situational Conditional-Read docs.
+  const digestVisible = collect(
+    CONDITIONAL_DOCS.map((f) => path.posix.join(docsRoot, f)),
+  );
+
+  // 4. on-demand: every .agents/rules/*.md that is not an always-on core rule
+  //    (the always-on ones already live in the alwaysLoaded closure).
+  const onDemand = collect(listOnDemandRules(root, fs));
+
+  return { tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } };
+}
+
+/**
+ * List the on-demand rule files (repo-relative posix): every `.agents/rules/
+ * *.md` whose basename is not an always-on core rule. Returns [] when the
+ * rules directory is absent.
+ *
+ * @param {string} root absolute repo root
+ * @param {FsLike} fs
+ * @returns {string[]}
+ */
+function listOnDemandRules(root, fs) {
+  const rulesDir = path.resolve(root, '.agents', 'rules');
+  let names;
+  try {
+    names = fs.readdirSync(rulesDir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith('.md') && !ALWAYS_ON_RULES.includes(n))
+    .map((n) => path.posix.join('.agents', 'rules', n))
+    .sort();
+}
+
+/**
+ * Sum the `bytes` of every entry in a tier array.
+ *
+ * @param {Array<{ bytes: number }>} entries
+ * @returns {number}
+ */
+export function tierTotalBytes(entries) {
+  return (entries ?? []).reduce((sum, e) => sum + (e?.bytes ?? 0), 0);
+}

package/.agents/scripts/lib/epic-body-sections.js

@@ -54,9 +54,12 @@ export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
 
 /**
  * Regex matching the Tech Spec's required opening heading (same variants
- * `spec-section-validator.js` accepts).
+ * `spec-section-validator.js` accepts). Exported so it is the single
+ * source of truth for this pattern — `spec-section-validator.js`,
+ * `epic-plan-clarity.js`, and `consolidation-precondition.js` all import
+ * it rather than each carrying their own copy.
  */
-const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
+export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
 
 /**
  * @param {'techSpec'|'acceptanceTable'} kind

package/.agents/scripts/lib/epic-merge-lock.js

@@ -237,3 +237,86 @@ export function releaseEpicMergeLock(handle, fsImpl = fs) {
     if (err.code !== 'ENOENT') throw err;
   }
 }
+
+const LOCK_FILE_PREFIX = 'epic-';
+const LOCK_FILE_SUFFIX = '.merge.lock';
+
+// Extract the epic id from a lock filename, or `null` when `entry` isn't a
+// `epic-*.merge.lock` file. Split out of `findForeignActiveEpicLock` so
+// that function stays a flat filter+map instead of a nested-conditional
+// loop body (Story #4460).
+function parseLockFileEpicId(entry) {
+  if (
+    !entry.startsWith(LOCK_FILE_PREFIX) ||
+    !entry.endsWith(LOCK_FILE_SUFFIX)
+  ) {
+    return null;
+  }
+  return entry.slice(
+    LOCK_FILE_PREFIX.length,
+    entry.length - LOCK_FILE_SUFFIX.length,
+  );
+}
+
+// Read `<dir>/<entry>`'s lock meta and report it only when the recorded
+// pid is still alive — a foreign lock whose pid is dead (or whose meta is
+// unreadable/corrupt) is stale debris, not an active holder, mirroring the
+// pid-liveness half of `tryStealStale`'s heuristic.
+function readLiveLock(dir, entry, otherEpicId, fsImpl, killFn) {
+  const filePath = path.join(dir, entry);
+  const meta = readLockMeta(filePath, fsImpl);
+  if (!meta || !isProcessRunning(meta.pid, killFn)) return null;
+  return {
+    epicId: otherEpicId,
+    filePath,
+    pid: meta.pid,
+    acquiredAt: meta.acquiredAt,
+  };
+}
+
+/**
+ * Scan the shared common `.git/` dir for a *different* epic's live
+ * merge lock (Story #4460 — cross-epic shared-checkout guard).
+ *
+ * `acquireEpicMergeLock` only ever contends against locks for the *same*
+ * `epicId` (its own lock filename). This helper is the cross-epic
+ * counterpart: it lists every `epic-*.merge.lock` file in the common
+ * gitdir, skips the caller's own `epicId` namespace, and returns the
+ * first foreign lock whose recorded `pid` is still alive.
+ *
+ * @param {number|string} epicId Caller's own epic id (excluded from the scan).
+ * @param {{
+ *   repoRoot: string,
+ *   fsImpl?: object,
+ *   killFn?: (pid:number, signal:number)=>void,
+ * }} opts
+ * @returns {{ epicId: string, filePath: string, pid: number, acquiredAt: number }|null}
+ */
+export function findForeignActiveEpicLock(
+  epicId,
+  { repoRoot, fsImpl = fs, killFn = process.kill.bind(process) } = {},
+) {
+  if (!repoRoot) {
+    throw new Error('findForeignActiveEpicLock: repoRoot is required');
+  }
+  const dir = resolveGitCommonDir(repoRoot, fsImpl);
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir);
+  } catch {
+    return null;
+  }
+
+  const foreignEntries = entries
+    .map((entry) => ({ entry, otherEpicId: parseLockFileEpicId(entry) }))
+    .filter(
+      ({ otherEpicId }) =>
+        otherEpicId !== null && String(otherEpicId) !== String(epicId),
+    );
+
+  for (const { entry, otherEpicId } of foreignEntries) {
+    const live = readLiveLock(dir, entry, otherEpicId, fsImpl, killFn);
+    if (live) return live;
+  }
+  return null;
+}

package/.agents/scripts/lib/epic-plan-clarity.js

@@ -40,6 +40,8 @@
  * Pure ESM, no I/O.
  */
 
+import { DELIVERY_SLICING_RE } from './epic-body-sections.js';
+
 const SECTION_RE = {
   context:
     /^##\s+(?:Context(?:\s+&\s+Problem)?|Background|Problem(?:\s+Statement)?)\s*$/im,
@@ -69,7 +71,7 @@ export const SECTION_NAMES = Object.freeze([
  * `spec-section-validator.js`.
  */
 const PLANNING_SECTION_RE = {
-  deliverySlicing: /^##\s+(?:Delivery\s+)?Slicing\s*$/im,
+  deliverySlicing: DELIVERY_SLICING_RE,
   acceptanceTable: /^##\s+Acceptance\s+Table\s*$/im,
 };
 

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -1,7 +1,15 @@
 /**
  * audit-results-graduator.js — Auto-graduate non-blocking audit findings
- * from the Epic's `audit-results` structured comment into routed GitHub
- * follow-up issues. Story #2615 / Epic #2586.
+ * from the Epic's unified `verification-results` structured comment into
+ * routed GitHub follow-up issues. Story #2615 / Epic #2586.
+ *
+ * Story #4411 (Epic #4405) unified the former `audit-results` and
+ * `code-review` structured-comment contracts into one `verification-results`
+ * contract: this graduator now reads the shared
+ * {@link VERIFICATION_RESULTS_MARKER} comment rather than the retired
+ * audit-results structured-comment marker. The lens-aware finding
+ * parser, the `audit-results::<severity>` + `domain::<lens>` label shape,
+ * and the audit idempotency marker are unchanged.
  *
  * As of Story #3845 / Epic #3823 the spawn helper, the path/idempotency
  * probes, the `gh issue create` filer, the toggle reader, and the
@@ -12,8 +20,8 @@
  * title / body shape, and the audit idempotency marker. Behaviour is
  * identical to the pre-consolidation graduator.
  *
- *   - Read the `audit-results` structured comment off the Epic ticket
- *     via the injected provider (`getTicketComments`).
+ *   - Read the unified `verification-results` structured comment off the
+ *     Epic ticket via the injected provider (`getTicketComments`).
  *   - For each non-blocking finding (severity high/medium/low/suggestion
  *     — i.e. anything that is NOT a 🔴 Critical Blocker), check that
  *     the cited file still exists in the merged tree.
@@ -38,23 +46,22 @@
  */
 
 import {
+  contentFingerprint,
   graduate,
   makeIsAutoFileEnabled,
-  probePathExists,
+  NO_VERIFICATION_RESULTS_COMMENT_REASON,
+  VERIFICATION_RESULTS_MARKER,
 } from './graduator-core.js';
 
 /**
  * Resolve the toggle from the resolved agentrc config. Defaults to `true`
- * — the feature is opt-out, not opt-in (mirrors codeReviewAutoFile).
+ * — the feature is opt-out, not opt-in.
  *
  * @param {object|undefined|null} config
  * @returns {boolean}
  */
 export const isAutoFileEnabled = makeIsAutoFileEnabled('auditResultsAutoFile');
 
-// Re-export the shared path probe so existing importers keep working.
-export { probePathExists };
-
 /**
  * Severity → label mapping. Only non-blocking severities have a route;
  * 🔴 Critical Blocker is explicitly filtered out upstream.
@@ -79,9 +86,12 @@ function metaSourceLabel(source) {
 }
 
 /**
- * Build the idempotency marker for a given epicId / finding index. An
- * HTML comment so it survives markdown rendering without leaking into
- * the visible body, but stays indexable via `gh search`.
+ * Build the **legacy** idempotency marker for a given epicId / finding
+ * index. Superseded by the content-hash marker
+ * ({@link buildContentMarker}) at the Story #4415 cutover, but still
+ * probed for so follow-ups filed before the cutover are recognized and
+ * not re-filed. An HTML comment so it survives markdown rendering without
+ * leaking into the visible body, but stays indexable via `gh search`.
  *
  * @param {number} epicId
  * @param {number} index — zero-based finding ordinal within the Epic.
@@ -91,6 +101,26 @@ export function buildIdempotencyMarker(epicId, index) {
   return `<!-- audit-results-followup: epic-${epicId}-finding-${index} -->`;
 }
 
+/**
+ * Build the content-hash idempotency marker embedded in freshly filed
+ * follow-up bodies. Derived from the finding's `lens|path|summary` triple
+ * so the marker is stable across sibling insert/remove/reorder churn in
+ * the source `audit-results` comment (Story #4415). An HTML comment so it
+ * survives markdown rendering but stays indexable via `gh search`.
+ *
+ * @param {number} epicId
+ * @param {{ lens?: string, path?: string, summary?: string }} finding
+ * @returns {string}
+ */
+export function buildContentMarker(epicId, finding) {
+  const fp = contentFingerprint({
+    category: finding.lens,
+    path: finding.path,
+    title: finding.summary,
+  });
+  return `<!-- audit-results-followup: epic-${epicId}-${fp} -->`;
+}
+
 /**
  * Parse the rendered audit-results markdown into a list of findings.
  * The format produced by `epic-audit.md` Step 4 groups findings under
@@ -98,6 +128,13 @@ export function buildIdempotencyMarker(epicId, index) {
  * emoji and embeds the cited path inside backticks. 🔴 critical findings
  * are filtered out (they're blocking — the Epic stops on those).
  *
+ * Findings the Phase 4 remediation loop already fixed on-branch are
+ * rendered under a **"Fixed on-branch"** heading (Story #4399) with a ✅
+ * prefix so they no longer parse as open findings. As a belt-and-suspenders
+ * guard the parser also skips every line inside a Fixed-on-branch section
+ * outright, so a remediated 🟡 Medium never spawns a ghost follow-up issue
+ * even if its line retains its original severity emoji.
+ *
  * Pure. Exported so the parser can be unit-tested in isolation.
  *
  * @param {string} body
@@ -109,18 +146,25 @@ export function parseFindings(body) {
   const lines = body.split(/\r?\n/);
   let idx = 0;
   let lens = 'unknown';
+  let inFixedSection = false;
   for (const rawLine of lines) {
     const trimmed = rawLine.trim();
     if (trimmed.length === 0) continue;
 
-    // Detect a lens heading. We accept any heading-prefixed line that
-    // names a known audit family (`audit-*`).
-    const lensMatch = trimmed.match(/^#{2,6}\s+(audit-[a-z0-9-]+)/i);
-    if (lensMatch) {
-      lens = lensMatch[1];
+    // Any markdown heading resets the Fixed-on-branch guard and, when it
+    // names a known audit family (`audit-*`), sets the active lens. A
+    // "Fixed on-branch" heading opens a section whose entries never
+    // graduate (Story #4399).
+    const headingMatch = trimmed.match(/^#{2,6}\s+(.+)$/);
+    if (headingMatch) {
+      inFixedSection = /fixed on-branch/i.test(headingMatch[1]);
+      const lensMatch = headingMatch[1].match(/^(audit-[a-z0-9-]+)/i);
+      if (lensMatch) lens = lensMatch[1];
       continue;
     }
 
+    if (inFixedSection) continue;
+
     let severity = null;
     if (trimmed.startsWith('🔴')) {
       // Critical Blocker — skip; never graduates.
@@ -180,10 +224,12 @@ export async function graduateAuditResults(opts = {}) {
     spec: {
       fnName: 'graduateAuditResults',
       isAutoFileEnabled,
-      commentMarker: '<!-- claude-managed: audit-results -->',
-      noCommentReason: 'no-audit-results-comment',
+      commentMarker: VERIFICATION_RESULTS_MARKER,
+      noCommentReason: NO_VERIFICATION_RESULTS_COMMENT_REASON,
       parseFindings,
-      buildIdempotencyMarker,
+      buildContentMarker,
+      buildLegacyMarker: buildIdempotencyMarker,
+      crossRepoCommentAttrs: { graduator: 'audit-results' },
       decorateRecord: (record, finding) => {
         record.lens = finding.lens;
         return record;