mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/audit-suite/lens-checklist.js

@@ -0,0 +1,212 @@
+/**
+ * lib/audit-suite/lens-checklist.js — distill an `audit-<lens>.md` workflow
+ * body into a compact, drift-gated authoring checklist.
+ *
+ * Epic #4405 (shift-left audit) moves each lens's concerns to the innermost,
+ * write-time tier: instead of an engineer only learning what a lens checks
+ * when `/audit-<lens>` runs, a compact per-lens checklist ships as a committed
+ * build artifact under `.agents/audit-checklists/`. This module is the pure
+ * distillation seam — no IO — so it is unit-testable and the generator
+ * (`generate-lens-checklists.js`) owns only the file read/write/prune and the
+ * `--check` drift gate.
+ *
+ * The distillation is a deterministic transform of the workflow markdown: it
+ * lifts the lens's *concern* labels — the bold lead-ins of the analysis /
+ * evaluation list items — from the audit region of the workflow (everything
+ * before the `Output Requirements` / report-template boundary), skipping the
+ * recurring boilerplate sections (Role, Context, Scope, Execution strategy,
+ * Configuration). When a lens exposes no bold concern items it falls back to
+ * its audit-step headings so every checklist is non-empty. The output is
+ * hard-capped at {@link MAX_CHECKLIST_LINES} lines.
+ *
+ * Pure: no IO, no provider calls, safe to unit-test in isolation.
+ *
+ * @see Story #4408 — per-lens authoring checklists as drift-gated artifacts.
+ */
+
+import { clampSummary, extractFrontmatter } from './frontmatter.js';
+
+// All RegExp instances are built via the constructor (rather than literal
+// `/.../`) so the maintainability engine's AST walker (typhonjs-escomplex) can
+// score this file — see the note in lib/audit-suite/frontmatter.js.
+// biome-ignore-start lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
+const LINE_SPLIT_RE = new RegExp(String.raw`\r?\n`);
+const FRONTMATTER_BLOCK_RE = new RegExp(
+  String.raw`^---\r?\n([\s\S]*?)\r?\n---`,
+);
+const BLOCK_SCALAR_INDICATOR_RE = new RegExp('^[|>][+-]?$');
+const DESCRIPTION_KEY_RE = new RegExp(String.raw`^description\s*:`);
+const INDENTED_LINE_RE = new RegExp(String.raw`^\s+\S`);
+const COLLAPSE_WS_RE = new RegExp(String.raw`\s+`, 'g');
+const HEADING_RE = new RegExp(String.raw`^(#{1,6})\s+(.*\S)\s*$`);
+const BOLD_LEAD_ITEM_RE = new RegExp(
+  String.raw`^\s*(?:[-*+]|\d+\.)\s+\*\*(.+?)\*\*`,
+);
+const STEP_PREFIX_RE = new RegExp(String.raw`^Step\s+\d+\s*[:.]?\s*`, 'i');
+const TRAILING_COLON_RE = new RegExp(String.raw`\s*:\s*$`);
+// A `##` section whose heading opens with one of these is workflow boilerplate,
+// not a lens concern — its list items are skipped during concern extraction.
+const BOILERPLATE_SECTION_RE = new RegExp(
+  String.raw`^(Role|Context & Objective|Scope|Execution strategy|Configuration|Run Context|Target set)\b`,
+  'i',
+);
+// The report-template / output-contract boundary. Everything at or after the
+// first heading matching this is template scaffolding, never a concern.
+const OUTPUT_BOUNDARY_RE = new RegExp(
+  '(Output Requirements|Generate the Report)',
+  'i',
+);
+// biome-ignore-end lint/complexity/useRegexLiterals: typhonjs-escomplex MI workaround
+
+/** Hard cap on generated checklist lines (asserted by the drift test). */
+export const MAX_CHECKLIST_LINES = 40;
+
+/** Fixed header/intro line budget consumed before the checklist items. */
+const HEADER_LINE_BUDGET = 12;
+
+/**
+ * Pure: walk the workflow body once, collecting the lens's concern labels (bold
+ * lead-ins of analysis/evaluation list items) and, as a fallback, its audit
+ * step headings. Extraction stops at the report-template boundary and ignores
+ * boilerplate sections.
+ *
+ * @param {string} content — raw `audit-<lens>.md` markdown.
+ * @returns {{ title: string|null, concerns: string[], stepHeadings: string[] }}
+ */
+export function extractLensConcerns(content) {
+  const lines = String(content ?? '').split(LINE_SPLIT_RE);
+  const concerns = [];
+  const stepHeadings = [];
+  let title = null;
+  let inBoilerplate = false;
+
+  for (const line of lines) {
+    const heading = HEADING_RE.exec(line);
+    if (heading) {
+      const level = heading[1].length;
+      const text = heading[2].trim();
+      if (level === 1) {
+        // First H1 is the lens title; a later H1 opens the report template.
+        if (title === null) {
+          title = text;
+          continue;
+        }
+        break;
+      }
+      if (OUTPUT_BOUNDARY_RE.test(text)) break;
+      if (level === 2) {
+        inBoilerplate = BOILERPLATE_SECTION_RE.test(text);
+        if (!inBoilerplate) {
+          stepHeadings.push(text.replace(STEP_PREFIX_RE, '').trim());
+        }
+      }
+      continue;
+    }
+    if (title === null || inBoilerplate) continue;
+    const item = BOLD_LEAD_ITEM_RE.exec(line);
+    if (item) {
+      const label = item[1].replace(TRAILING_COLON_RE, '').trim();
+      if (label) concerns.push(label);
+    }
+  }
+
+  return { title, concerns, stepHeadings };
+}
+
+/**
+ * Pure: resolve a workflow's `description` to a single clamped line, folding a
+ * YAML block scalar (`description: >-` / `|` with indented continuation lines)
+ * back into one line. `extractFrontmatter` only sees the indicator token
+ * (`>-`) for a block scalar, so this reads the continuation lines directly.
+ *
+ * @param {string} content — raw workflow markdown.
+ * @param {Record<string, string>} fm — parsed frontmatter map.
+ * @returns {string} a single-line description (possibly empty).
+ */
+export function resolveDescription(content, fm) {
+  const raw = (fm.description ?? '').trim();
+  if (raw && !BLOCK_SCALAR_INDICATOR_RE.test(raw)) {
+    return clampSummary(raw).replace(COLLAPSE_WS_RE, ' ');
+  }
+
+  const block = FRONTMATTER_BLOCK_RE.exec(String(content ?? ''));
+  if (!block) return '';
+  const lines = block[1].split(LINE_SPLIT_RE);
+  const start = lines.findIndex((line) => DESCRIPTION_KEY_RE.test(line));
+  if (start === -1) return '';
+  const collected = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (INDENTED_LINE_RE.test(lines[i])) {
+      collected.push(lines[i].trim());
+      continue;
+    }
+    break; // a blank line or a dedented next key ends the scalar.
+  }
+  return clampSummary(collected.join(' ')).replace(COLLAPSE_WS_RE, ' ');
+}
+
+/**
+ * Pure: dedupe a list case-insensitively, preserving first-seen order.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+function dedupePreserveOrder(items) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const key = item.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * Pure: render the authoring checklist for a single lens from its workflow
+ * markdown. The output is deterministic (a pure function of `content`) and
+ * hard-capped at {@link MAX_CHECKLIST_LINES} lines including the trailing
+ * newline, so the same input always regenerates byte-identically.
+ *
+ * @param {string} lens — canonical lens name (e.g. `security`).
+ * @param {string} content — raw `audit-<lens>.md` markdown.
+ * @returns {string} the checklist markdown (ends with a single newline).
+ */
+export function renderLensChecklist(lens, content) {
+  const fm = extractFrontmatter(content);
+  const description = resolveDescription(content, fm);
+  const { title, concerns, stepHeadings } = extractLensConcerns(content);
+  const displayTitle = title || `audit-${lens}`;
+
+  let items = dedupePreserveOrder(concerns);
+  if (items.length === 0) items = dedupePreserveOrder(stepHeadings);
+  if (items.length === 0) items = ['Review the full lens workflow'];
+
+  const header = [
+    '<!-- GENERATED FILE — do not edit by hand.',
+    `     Source of truth: .agents/workflows/audit-${lens}.md`,
+    '     Regenerate: node .agents/scripts/generate-lens-checklists.js',
+    '     Drift is gated by: npm run docs:check',
+    '-->',
+    '',
+    `# ${displayTitle} — authoring checklist`,
+    '',
+    `> ${description || `Self-check your change against the ${lens} lens.`}`,
+    '',
+    "Self-check your change against this lens's concerns before you ship:",
+    '',
+  ];
+
+  // Reserve room for a truncation marker so the cap is never exceeded.
+  const maxItems = MAX_CHECKLIST_LINES - HEADER_LINE_BUDGET;
+  let itemLines;
+  if (items.length > maxItems) {
+    itemLines = items.slice(0, maxItems - 1).map((c) => `- [ ] ${c}`);
+    itemLines.push('- [ ] …see the full lens for the remaining concerns');
+  } else {
+    itemLines = items.map((c) => `- [ ] ${c}`);
+  }
+
+  return `${[...header, ...itemLines].join('\n')}\n`;
+}

package/.agents/scripts/lib/audit-suite/selector.js

@@ -16,6 +16,7 @@
  * mapping. All rule-matching lives here.
  */
 
+import { readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import picomatch from 'picomatch';
@@ -62,6 +63,141 @@ export function isGlobalLens(lens) {
   return GLOBAL_LENS_ALLOWLIST.includes(lens);
 }
 
+/**
+ * The canonical concern-ownership tiers a lens can declare via its
+ * `scope` field in [`audit-rules.json`](../../../schemas/audit-rules.json).
+ * This frozen tuple is the single source of truth for the tier vocabulary the
+ * schema's `scope` enum enforces and {@link resolveLensTier} returns:
+ *
+ *   - `local`      — decidable from a single Story's diff; verified at
+ *                    write-time and Story-scope review, not re-run at Epic close.
+ *   - `cumulative` — only decidable across the Epic's combined diff; verified
+ *                    at Epic close.
+ *   - `global`     — evaluates a whole-product property regardless of the diff;
+ *                    verified at Epic close, exempt from change-set narrowing.
+ *
+ * @type {readonly ['local', 'cumulative', 'global']}
+ */
+export const LENS_TIERS = Object.freeze(['local', 'cumulative', 'global']);
+
+/**
+ * Resolve the concern-ownership tier a lens declares in `audit-rules.json`.
+ * This is the pure read-side of the `scope` field (Epic #4405, Story #4407)
+ * that replaced the former `alwaysRun` special case: every downstream tier —
+ * write-time checklist threading, Story-scope review, the Epic-close roster
+ * split — routes off this one field instead of a maintained prose constraint.
+ *
+ * Deterministic given the on-disk manifest: it reads the same
+ * `audit-rules.json` that {@link selectAudits} consumes (resolved through the
+ * project's configured `schemasRoot`), looks up the lens, and returns its
+ * `scope`. It takes no ticket, runs no git, and has no side effects.
+ *
+ * @param {string} lens Lens key registered in `audit-rules.json`
+ *   (e.g. `audit-clean-code`).
+ * @returns {'local' | 'cumulative' | 'global'} The lens's declared tier.
+ * @throws {Error} When `lens` is not registered in the manifest, or the
+ *   manifest cannot be read, or the registered entry carries a scope outside
+ *   {@link LENS_TIERS}.
+ */
+/**
+ * Read and parse the `audit-rules.json` manifest synchronously from the
+ * project's configured `schemasRoot`. Shared by the synchronous, ticket-free
+ * readers ({@link resolveLensTier}, {@link selectLocalLenses}) so the path
+ * resolution and read-failure handling live in one place rather than being
+ * duplicated per reader.
+ *
+ * @returns {{ audits?: Record<string, object> }} Parsed manifest.
+ * @throws {Error} When the manifest cannot be read or parsed.
+ */
+function readAuditRulesSync() {
+  const { agentSettings } = resolveConfig();
+  const rulesPath = path.join(
+    PROJECT_ROOT,
+    getPaths({ agentSettings }).schemasRoot,
+    'audit-rules.json',
+  );
+  try {
+    return JSON.parse(readFileSync(rulesPath, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `audit-suite: failed to read audit-rules from ${rulesPath}: ${err.message}`,
+    );
+  }
+}
+
+export function resolveLensTier(lens) {
+  const rulesData = readAuditRulesSync();
+
+  const entry = rulesData.audits?.[lens];
+  if (!entry) {
+    throw new Error(
+      `resolveLensTier: unknown lens '${lens}' — not registered in audit-rules.json`,
+    );
+  }
+
+  const { scope } = entry;
+  if (!LENS_TIERS.includes(scope)) {
+    throw new Error(
+      `resolveLensTier: lens '${lens}' declares invalid scope '${scope}'; expected one of ${LENS_TIERS.join(', ')}`,
+    );
+  }
+
+  return scope;
+}
+
+/**
+ * Select the LOCAL-tier lenses whose `filePatterns` triggers match a change
+ * set. This is the Story-scope roster used by the maker-blind story-close
+ * review (Epic #4405, Story #4409): a lens is selected iff
+ * `resolveLensTier(lens) === 'local'` **and** the pure
+ * {@link matchesAnyFilePattern} matcher hits at least one of `changedFiles`
+ * against the lens's registered `triggers.filePatterns`.
+ *
+ * This deliberately does **not** call {@link selectAudits}: `selectAudits`
+ * unions in keyword-matched and gate-scoped lenses and has no per-tier gate,
+ * so it would widen the roster beyond the local, footprint-matched set the
+ * shift-left Story-scope tier owns. A local lens with a universal
+ * `filePatterns` glob (e.g. `audit-clean-code`, whose sole pattern matches
+ * every path) matches every change set here, so its concern is verified at
+ * BOTH innermost tiers — the
+ * write-time checklist threading and this Story-scope lens pass — and excluded
+ * from Epic close (a local lens is dropped by {@link selectEpicCloseLenses}).
+ * A local lens with an empty `filePatterns` list matches nothing here, so a
+ * diff matching no local lens's patterns yields an empty roster and adds no
+ * lens work.
+ *
+ * Pure over its injected seams: `injectedRules` skips the disk read of the
+ * manifest and `resolveLensTierFn` overrides the tier resolver, so callers can
+ * exercise the selection without touching the filesystem. Selection order
+ * follows the manifest's declaration order, which is deterministic.
+ *
+ * @param {{
+ *   changedFiles?: string[],
+ *   injectedRules?: { audits?: Record<string, object> },
+ *   resolveLensTierFn?: typeof resolveLensTier,
+ * }} [params]
+ * @returns {string[]} The matched local-lens identifiers, in manifest order.
+ */
+export function selectLocalLenses({
+  changedFiles,
+  injectedRules,
+  resolveLensTierFn = resolveLensTier,
+} = {}) {
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  if (files.length === 0) return [];
+
+  const rules = injectedRules ?? readAuditRulesSync();
+  const selected = [];
+  for (const [lens, entry] of Object.entries(rules.audits ?? {})) {
+    if (resolveLensTierFn(lens) !== 'local') continue;
+    const patterns = entry?.triggers?.filePatterns ?? [];
+    if (matchesAnyFilePattern(patterns, files)) {
+      selected.push(lens);
+    }
+  }
+  return selected;
+}
+
 /**
  * Resolve the consumer's navigability route globs from the resolved config.
  * Reads `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the
@@ -264,11 +400,6 @@ export async function selectAudits({
     const gateMatch = triggers.gates?.includes(gate);
     if (!gateMatch) continue;
 
-    if (triggers.alwaysRun) {
-      selectedAudits.push(auditName);
-      continue;
-    }
-
     const keywords = triggers.keywords || [];
     let keywordMatch = false;
     for (const kw of keywords) {