@sabaiway/agent-workflow-kit 11.2.0 → 12.1.0

package/tools/now-plan-facts.mjs

@@ -0,0 +1,129 @@
+import { spawnSync } from 'node:child_process';
+import { join, posix } from 'node:path';
+import { computeWorkingState, coverageQualifierFor, describeMissingReviewAttestation } from './core-evidence.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER, stripGitLocationEnv, withGitPath } from './git-env.mjs';
+import { PLANS_REL, plansInFlight } from './plan-files.mjs';
+import { isSweep, parseLedger, unique } from './plan-shape.mjs';
+import { buildFacts, expandPatterns } from './plan-shape-facts.mjs';
+
+const VERIFICATION = '## Verification';
+const NUL = String.fromCharCode(0);
+const STAGED_ARGV = Object.freeze(['diff', '--cached', '--name-only', '-z', '--no-renames']);
+const IGNORE_ARGV = Object.freeze(['check-ignore', '-z', '--stdin']);
+
+const detailOf = (result) => {
+  const stderr = String(result.stderr ?? '').trim();
+  return stderr ? ` (${stderr})` : '';
+};
+
+// Every spawn outcome is named — an error, a signal, an unaccepted status, a throw — never an empty success read as "nothing is staged".
+export const readGitPaths = (argv, { cwd, env, spawn = spawnSync, input, accept = [0] }) => {
+  const label = `git ${argv[0]}`;
+  const runEnv = withGitPath({ ...stripGitLocationEnv(env), LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' });
+  const result = (() => {
+    try {
+      return spawn('git', argv, { cwd, env: runEnv, input, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+    } catch (error) {
+      throw new Error(`${label} threw synchronously (${error?.message ?? error})`);
+    }
+  })();
+  if (result === null || typeof result !== 'object') throw new Error(`${label} returned no result`);
+  if (result.error) throw new Error(`${label} could not run (${result.error.code ?? result.error.message ?? result.error})`);
+  if (result.signal) throw new Error(`${label} was killed by ${result.signal}`);
+  if (!accept.includes(result.status)) throw new Error(`${label} exited ${result.status}${detailOf(result)}`);
+  return String(result.stdout ?? '').split(NUL).filter(Boolean);
+};
+
+const refused = (path, parseError) => ({ path, parsed: null, parseError, rows: [] });
+
+const readPlanEntry = (cwd, name) => {
+  const path = `${PLANS_REL}/${name}`;
+  const read = readRegularFileNoFollow(join(cwd, PLANS_REL, name));
+  if (read.outcome !== 'ok') return refused(path, `${path} is not a readable regular file (${read.className ?? read.code ?? read.outcome})`);
+  try {
+    const parsed = parseLedger(read.content);
+    const verification = parsed.document.headings.find(({ text }) => text === VERIFICATION);
+    return verification
+      ? { path, parsed, parseError: null, rows: [] }
+      : refused(path, `${path} carries no "${VERIFICATION}" heading, so its ledger cannot be located`);
+  } catch (error) {
+    return refused(path, `${path} cannot be parsed (${error?.message ?? error})`);
+  }
+};
+
+const describeCurrency = ({ state, detail }) => detail ? `${state} (${detail})` : state;
+const toVerdict = ({ backend, summary }) => {
+  const missing = describeMissingReviewAttestation(summary);
+  return { backend, line: `${backend}: ${missing ?? `${summary.receipt.verdict} (attesting, ${summary.receipt.timestamp})`}` };
+};
+
+const describeFinalRun = (record) => {
+  if (!record) return null;
+  const qualifier = coverageQualifierFor(record);
+  return {
+    status: String(record.status).toUpperCase(),
+    gates: Array.isArray(record.results) ? `${record.results.filter(({ ok }) => ok === true).length}/${record.results.length}` : 'unknown',
+    fingerprintBefore: record.fingerprintBefore,
+    timestamp: record.timestamp,
+    coverage: qualifier ? qualifier.replace(/^ \u2014 /, '') : `coverage=${record.coverage ?? 'unknown'}`,
+  };
+};
+
+// The summary's review half, mapped ONCE: the tree block and the per-row red-proof annotation read the same records.
+export const readSummaryFacts = (summary) => ({
+  redProofs: summary.redProofs.map((record) => ({ path: record.file, currency: describeCurrency(record.currency) })),
+  receipts: { path: summary.receiptsPath, verdicts: summary.verdicts.map(toVerdict), finalRun: describeFinalRun(summary.finalRun) },
+});
+
+// A sweep row is judged as a SET: presence from the expansion on disk, each changed-set flag from the glob over that FULL git set (a deleted member still counts), exclusion only when every member is excluded.
+// git names a path in one spelling; a ledger may write `./src/a.mjs` or `src//a.mjs`, so every lookup uses the canonical form.
+const canonical = (path) => posix.normalize(path).replace(/\/$/, '');
+const matchesAny = (pattern, paths) => expandPatterns(paths, [pattern])[pattern].length > 0;
+const sweepEvidenceFor = (pattern, expansions, sets) => {
+  const members = expansions[pattern] ?? [];
+  return {
+    pathFact: members.length > 0 ? { kind: 'sweep', members: members.length } : { kind: 'absent' },
+    staged: matchesAny(pattern, sets.staged),
+    unstaged: matchesAny(pattern, sets.unstaged),
+    untracked: matchesAny(pattern, sets.untracked),
+    excluded: members.length > 0 && members.every((member) => sets.excluded.includes(member)),
+  };
+};
+// `path` is the canonical form every reader of the row's evidence keys on; a row the ledger grammar refused carries none.
+const hasPath = (row) => typeof row.path === 'string' && row.path.length > 0;
+const evidenceFor = (row, pathFacts, expansions, sets) => {
+  if (!hasPath(row)) return { path: null, pathFact: null, staged: false, unstaged: false, untracked: false, excluded: false };
+  const path = canonical(row.path);
+  if (isSweep(path)) return { path, ...sweepEvidenceFor(path, expansions, sets) };
+  return {
+    path,
+    pathFact: pathFacts[path] ?? null,
+    staged: sets.staged.includes(path),
+    unstaged: sets.unstaged.includes(path),
+    untracked: sets.untracked.includes(path),
+    excluded: sets.excluded.includes(path),
+  };
+};
+
+export const gatherPlanFacts = ({ cwd, env = process.env, deps = {} }) => {
+  const entries = plansInFlight(cwd, deps.readdir).map((name) => readPlanEntry(cwd, name));
+  const ledgerPaths = unique(entries.flatMap(({ parsed }) => (parsed ? parsed.rows : []))
+    .filter(hasPath)
+    .map(({ path }) => canonical(path)));
+  const { pathFacts, expansions } = buildFacts(cwd, { paths: ledgerPaths });
+  const concretePaths = unique([...ledgerPaths.filter((path) => !isSweep(path)), ...Object.values(expansions).flat()]);
+  const working = computeWorkingState(cwd, { env });
+  if (working === null) throw new Error(`the working state of ${cwd} is not decidable`);
+  const staged = readGitPaths(STAGED_ARGV, { cwd, env, spawn: deps.spawn });
+  const excluded = concretePaths.length === 0
+    ? []
+    : readGitPaths(IGNORE_ARGV, { cwd, env, spawn: deps.spawn, accept: [0, 1], input: `${concretePaths.join(NUL)}${NUL}` });
+  const changed = { staged, unstaged: working.unstagedPaths, untracked: working.untrackedPaths };
+  const sets = { staged, unstaged: changed.unstaged, untracked: changed.untracked, excluded };
+  const plans = entries.map((entry) => ({
+    ...entry,
+    rows: (entry.parsed?.rows ?? []).map((row) => ({ row, raw: row.raw, evidence: evidenceFor(row, pathFacts, expansions, sets) })),
+  }));
+  return { plans, pathFacts, changed, excluded };
+};

package/tools/now-render.mjs

@@ -0,0 +1,162 @@
+import { glyphsFor } from './presentation.mjs';
+import { visibleLength } from './renderers.mjs';
+import { foldQueue, isWithheld, judgeRow, derivePhase } from './now-status.mjs';
+
+const BLOCK_TITLE = Object.freeze({ now: 'NOW', steps: 'STEPS', queue: 'QUEUE', campaign: 'CAMPAIGN' });
+const STATUS_GLYPH = Object.freeze({
+  landed: 'present',
+  'in progress': 'note',
+  pending: 'missing',
+  unjudged: 'unknown',
+});
+const SGR = Object.freeze({ bold: '\x1b[1m', reset: '\x1b[0m' });
+
+const getHeading = (title, color) => color ? `${SGR.bold}${title}${SGR.reset}` : title;
+const getStepName = (step) => step?.row ? `${step.row.id} · ${step.row.path}` : step?.name ?? 'none';
+const getRedProof = (tree, path) => isWithheld(tree) ? null : tree.redProofs.find((proof) => proof.path === path) ?? null;
+
+const getPlanView = (plan, tree) => {
+  if (!plan.parsed) return { path: plan.path, parseError: plan.parseError, phase: null, rows: [] };
+  const rows = plan.rows.map(({ row, raw, evidence }) => judgeRow({ ...row, raw }, {
+    ...evidence,
+    redProof: getRedProof(tree, evidence.path),
+  }));
+  return { path: plan.path, parseError: plan.parseError, phase: derivePhase(plan.parsed, rows), rows };
+};
+
+const getPhaseMarker = (step) => step?.row
+  ? { row: { id: step.row.id, path: step.row.path } }
+  : step ? { name: step.name } : null;
+const getPhaseView = (phase) => ({
+  name: phase.name,
+  current: getPhaseMarker(phase.current),
+  next: getPhaseMarker(phase.next),
+  inProgress: phase.inProgress,
+});
+
+const getPlanBlocks = (plans, tree) => {
+  if (isWithheld(plans)) return { plans: plans, steps: plans };
+  const entries = plans.entries.map((plan) => getPlanView(plan, tree));
+  return {
+    plans: { entries: entries.map(({ path, parseError, phase }) => ({ path, parseError, phase: phase ? getPhaseView(phase) : null })) },
+    steps: { entries: entries.map(({ path, parseError, rows }) => ({ path, parseError, rows })) },
+  };
+};
+
+export const toNowViewModel = (facts) => {
+  const planBlocks = getPlanBlocks(facts.plans, facts.tree);
+  const plans = isWithheld(planBlocks.plans) ? planBlocks.plans : planBlocks.plans.entries;
+  const tree = isWithheld(facts.tree) ? facts.tree : { ...facts.tree };
+  const now = isWithheld(plans) && isWithheld(tree)
+    ? { withheld: [...new Set([plans.withheld, tree.withheld])].join(' \u00b7 ') }
+    : { plans, tree };
+  const queue = isWithheld(facts.queue)
+    ? facts.queue
+    : { path: facts.queue.path, ...foldQueue(facts.queue.rows) };
+  return { now, steps: planBlocks.steps, queue, campaign: isWithheld(facts.campaign) ? facts.campaign : { ...facts.campaign } };
+};
+
+const getWithheldLines = (title, block, color) => [getHeading(title, color), `${title} — WITHHELD: ${block.withheld}`];
+const getAnnotationText = (annotation) => annotation.kind === 'red-proof'
+  ? `red-proof ${annotation.text}`
+  : annotation.text;
+const getStatusTail = (step) => {
+  const detail = step.detail ? ` (${step.detail})` : '';
+  const annotations = step.annotations.map((annotation) => ` (${getAnnotationText(annotation)})`).join('');
+  return ` [${step.evidenceSource}]${detail}${annotations}`;
+};
+
+const renderNowBlock = (block, color, glyph) => {
+  if (isWithheld(block)) return getWithheldLines(BLOCK_TITLE.now, block, color);
+  const lines = [getHeading(BLOCK_TITLE.now, color)];
+  if (isWithheld(block.plans)) lines.push(`  plans \u2014 WITHHELD: ${block.plans.withheld}`);
+  else if (block.plans.length === 0) lines.push('  no plan in flight');
+  for (const plan of isWithheld(block.plans) ? [] : block.plans) {
+    lines.push(`  plan: ${plan.path}`);
+    if (plan.parseError) {
+      lines.push(`    ${glyph.unknown} could not parse: ${plan.parseError}`);
+      continue;
+    }
+    lines.push(`    phase: ${plan.phase.name}`);
+    lines.push(`    current: ${getStepName(plan.phase.current)}`);
+    lines.push(`    next: ${getStepName(plan.phase.next)}`);
+    for (const step of plan.phase.inProgress) lines.push(`    ${glyph.note} in progress: ${getStepName(step)} — ${step.status}${getStatusTail(step)}`);
+  }
+  const tree = block.tree;
+  if (isWithheld(tree)) {
+    lines.push(`  tree \u2014 WITHHELD: ${tree.withheld}`);
+    return lines;
+  }
+  const clean = tree.clean === null ? 'unknown' : tree.clean ? 'clean' : 'changed';
+  lines.push(`  tree: ${tree.fingerprint} · ${clean}`);
+  for (const verdict of tree.verdicts) lines.push(`    ${glyph.note} ${verdict.line}`);
+  lines.push(tree.finalRun
+    ? `    final run: ${tree.finalRun.status} ${tree.finalRun.gates} gates · ${tree.finalRun.fingerprintBefore} · ${tree.finalRun.timestamp} · ${tree.finalRun.coverage}`
+    : '    final run: none');
+  for (const proof of tree.redProofs) lines.push(`    red-proof: ${proof.path} · ${proof.currency}`);
+  return lines;
+};
+
+const renderStepsBlock = (block, color, glyph) => {
+  if (isWithheld(block)) return getWithheldLines(BLOCK_TITLE.steps, block, color);
+  const lines = [getHeading(BLOCK_TITLE.steps, color)];
+  if (block.entries.length === 0) lines.push('  no steps — no plan in flight');
+  for (const plan of block.entries) {
+    lines.push(`  plan: ${plan.path}`);
+    if (plan.parseError) {
+      lines.push(`    WITHHELD: ${plan.parseError}`);
+      continue;
+    }
+    for (const step of plan.rows) {
+      lines.push(`    ${glyph[STATUS_GLYPH[step.status]]} ${getStepName(step)} — ${step.status}${getStatusTail(step)}`);
+    }
+  }
+  return lines;
+};
+
+const renderQueueBlock = (block, color) => {
+  if (isWithheld(block)) return getWithheldLines(BLOCK_TITLE.queue, block, color);
+  const counts = Object.entries(block.counts).map(([klass, count]) => `${klass} ${count}`).join(' · ');
+  const lines = [getHeading(BLOCK_TITLE.queue, color), `  ${block.path} · ${block.total} rows · ${counts}`];
+  for (const bucket of block.buckets) {
+    const domain = bucket.order === 'priority' ? 'priority' : 'archive';
+    const bucketCounts = Object.entries(bucket.counts).map(([klass, count]) => `${klass} ${count}`).join(' · ');
+    lines.push(`  ${domain} · ${bucket.label} · ${bucketCounts}`);
+    for (const row of bucket.rows) lines.push(`  ${domain} · ${bucket.label} · ${bucket.order} ${row.position}: ${row.name} — ${row.klass}`);
+  }
+  return lines;
+};
+
+const getFigure = (value) => value === null || value === undefined ? 'not recorded' : String(value);
+const renderCampaignBlock = (block, color) => {
+  if (isWithheld(block)) return getWithheldLines(BLOCK_TITLE.campaign, block, color);
+  const lines = [getHeading(BLOCK_TITLE.campaign, color), `  state: ${block.state}`];
+  if (block.state !== 'absent') {
+    lines.push(`  caps: ${block.maxLines} lines · ${block.maxLineBytes} bytes per line`);
+    lines.push(`  roots: ${block.roots} · recorded files: ${getFigure(block.recordedFiles)} · aggregate lines: ${getFigure(block.aggregateLines)}`);
+  }
+  return lines;
+};
+
+const padLine = (line, width) => {
+  const visible = visibleLength(line);
+  return line === '' || visible >= width ? line : line + ' '.repeat(width - visible);
+};
+
+export const renderNow = (vm, surface = {}) => {
+  if (surface.mode === 'json') return '';
+  const color = surface.mode === 'ansi' && Boolean(surface.color);
+  const glyph = glyphsFor(Boolean(surface.ascii));
+  const lines = [
+    ...renderNowBlock(vm.now, color, glyph),
+    '',
+    ...renderStepsBlock(vm.steps, color, glyph),
+    '',
+    ...renderQueueBlock(vm.queue, color),
+    '',
+    ...renderCampaignBlock(vm.campaign, color),
+  ];
+  return surface.mode === 'ansi'
+    ? lines.map((line) => padLine(line, surface.width ?? 80)).join('\n')
+    : lines.join('\n');
+};

package/tools/now-status.mjs

@@ -0,0 +1,145 @@
+import { bulletBlocks, isSweep } from './plan-shape.mjs';
+import { canonicalHeading } from './queue-audit.mjs';
+import { CARRY_WORK, CLASSES, leadMarkers, titleOf } from './queue-audit-rows.mjs';
+
+export const NOW_STATUS = Object.freeze({
+  LANDED: 'landed',
+  IN_PROGRESS: 'in progress',
+  PENDING: 'pending',
+  UNJUDGED: 'unjudged',
+});
+
+export const NOW_ANNOTATION = Object.freeze({
+  CLAIM: 'claim',
+  ANOMALY: 'anomaly',
+  RED_PROOF: 'red-proof',
+});
+
+const EVIDENCE_SOURCE = Object.freeze({
+  PATH: 'path fact',
+  CHANGED: 'changed set',
+  EXCLUSION: 'exclusion fact',
+});
+const PHASE_PREFIX = '## Phase: ';
+const PRIORITY_HEADING = canonicalHeading('## Pending / backlog');
+
+export const isWithheld = (block) => typeof block?.withheld === 'string';
+const CHECKED_TASK = /(?:^|\s)\[[xX]\](?:\s|$)/;
+
+const getResponsibility = (raw) => String(raw ?? '').split(' | ')[3] ?? '';
+const getJudgedProse = (raw) => titleOf([getResponsibility(raw)]).judged;
+
+export const readProseClaim = (raw) => {
+  const prose = getJudgedProse(raw);
+  return CHECKED_TASK.test(prose) || leadMarkers(prose).length > 0 ? 'done' : null;
+};
+
+const getChangedDetail = ({ staged, unstaged, untracked }) => {
+  const parts = [staged ? 'staged' : null, unstaged ? 'unstaged' : null, untracked ? 'untracked' : null].filter(Boolean);
+  return parts.join(', ');
+};
+
+const getPathDecision = (row, evidence) => {
+  const pathFact = evidence.pathFact;
+  if (!pathFact) return { status: NOW_STATUS.UNJUDGED, detail: 'path fact unavailable', evidenceSource: EVIDENCE_SOURCE.PATH };
+  const present = pathFact.kind !== 'absent';
+  if (row.verb === 'create') {
+    return { status: present ? NOW_STATUS.LANDED : NOW_STATUS.PENDING, detail: null, evidenceSource: EVIDENCE_SOURCE.PATH };
+  }
+  if (row.verb === 'delete') {
+    return { status: present ? NOW_STATUS.PENDING : NOW_STATUS.LANDED, detail: null, evidenceSource: EVIDENCE_SOURCE.PATH };
+  }
+  if (!present) return { status: NOW_STATUS.PENDING, detail: 'post-state unmet', evidenceSource: EVIDENCE_SOURCE.PATH };
+  return {
+    status: NOW_STATUS.UNJUDGED,
+    detail: evidence.excluded === true ? 'excluded from git here, no changed-set evidence' : 'no base-motion reader',
+    evidenceSource: EVIDENCE_SOURCE.EXCLUSION,
+  };
+};
+
+const getAnnotations = (row, evidence, status) => {
+  const claim = readProseClaim(row.raw) && status !== NOW_STATUS.LANDED
+    ? [{ kind: NOW_ANNOTATION.CLAIM, text: 'claimed done' }]
+    : [];
+  const overBudget = row.budgetLines && evidence.pathFact?.kind === 'regular' && evidence.pathFact.lines > row.budgetLines
+    ? [{ kind: NOW_ANNOTATION.ANOMALY, text: `over budget ${evidence.pathFact.lines}/${row.budgetLines}` }]
+    : [];
+  const redProof = evidence.redProof
+    ? [{ kind: NOW_ANNOTATION.RED_PROOF, text: evidence.redProof.currency ?? String(evidence.redProof) }]
+    : [];
+  return [...claim, ...overBudget, ...redProof];
+};
+
+// A set has no single post-state, so a sweep row is reduced only under modify: the verb refuses it before any evidence arm.
+const SWEEP_VERB_REFUSAL = Object.freeze({ status: NOW_STATUS.UNJUDGED, detail: 'a sweep row is judged as a set only under modify', evidenceSource: EVIDENCE_SOURCE.PATH });
+
+export const judgeRow = (row, evidence = {}) => {
+  const changed = Boolean(evidence.staged || evidence.unstaged || evidence.untracked);
+  const decision = isSweep(row.path) && row.verb !== 'modify'
+    ? SWEEP_VERB_REFUSAL
+    : changed
+      ? { status: NOW_STATUS.IN_PROGRESS, detail: getChangedDetail(evidence), evidenceSource: EVIDENCE_SOURCE.CHANGED }
+      : getPathDecision(row, evidence);
+  return { row, ...decision, annotations: getAnnotations(row, evidence, decision.status) };
+};
+
+const getPhaseSteps = (parsed, heading) => {
+  const document = parsed.document;
+  const next = document.headings.find((candidate) => candidate.index > heading.index && candidate.level <= heading.level);
+  const end = next?.index ?? document.lines.length;
+  return bulletBlocks(document.lines, document.fencedLines, heading.index + 1, end).map((block) => ({
+    name: block.lines.join(' ').replace(/^-\s+/, '').replace(/\s+/g, ' ').trim(),
+    status: NOW_STATUS.UNJUDGED,
+    detail: 'no evidence reader',
+    evidenceSource: null,
+    annotations: [],
+  }));
+};
+
+const getMarkers = (name, steps) => {
+  const currentIndex = steps.findIndex(({ status }) => status !== NOW_STATUS.LANDED && status !== NOW_STATUS.IN_PROGRESS);
+  return {
+    name,
+    steps,
+    inProgress: steps.filter(({ status }) => status === NOW_STATUS.IN_PROGRESS),
+    current: currentIndex < 0 ? null : steps[currentIndex],
+    next: currentIndex < 0 ? null : steps[currentIndex + 1] ?? null,
+  };
+};
+
+export const derivePhase = (parsed, judged) => {
+  const complete = judged.length > 0 && judged.every(({ status }) => status === NOW_STATUS.LANDED);
+  if (!complete) return getMarkers('ledger', judged);
+  const verification = parsed.document.headings.find(({ text }) => text === '## Verification');
+  const heading = parsed.document.headings.find(({ index, text }) => index > verification.index && text.startsWith(PHASE_PREFIX));
+  const steps = heading ? getPhaseSteps(parsed, heading) : [];
+  return getMarkers(heading ? heading.text.slice(PHASE_PREFIX.length) : 'Cleanup', steps);
+};
+
+const getBucketKey = (buckets) => JSON.stringify(buckets ?? []);
+const getBucketLabel = (buckets) => buckets.length === 0
+  ? 'document'
+  : buckets.map(({ text, line }) => `${text} (line ${line})`).join(' > ');
+const isPriorityBucket = (buckets) => buckets.some(({ level, text }) => level === 2 && canonicalHeading(text) === PRIORITY_HEADING);
+const getCounts = (rows) => Object.fromEntries(CLASSES.map((klass) => [klass, rows.filter((row) => row.klass === klass).length]));
+
+export const foldQueue = (rows) => {
+  const folded = rows.reduce((buckets, row) => {
+    const path = row.buckets ?? [];
+    const key = getBucketKey(path);
+    const found = buckets.find((bucket) => bucket.key === key);
+    const entry = {
+      name: row.name || `unnamed (line ${row.line})`,
+      line: row.line,
+      klass: row.klass,
+      evidence: row.evidence,
+      position: (found?.rows.length ?? 0) + 1,
+    };
+    const entries = CARRY_WORK.has(row.klass) ? [...(found?.rows ?? []), entry] : found?.rows ?? [];
+    return found
+      ? buckets.map((bucket) => bucket.key === key ? { ...bucket, sourceRows: [...bucket.sourceRows, row], rows: entries } : bucket)
+      : [...buckets, { key, path, label: getBucketLabel(path), order: isPriorityBucket(path) ? 'priority' : 'position', sourceRows: [row], rows: entries }];
+  }, []);
+  const buckets = folded.map(({ key, sourceRows, ...bucket }) => ({ ...bucket, counts: getCounts(sourceRows) }));
+  return { buckets, counts: getCounts(rows), total: rows.length };
+};

package/tools/plan-shape-facts.mjs

@@ -120,7 +120,7 @@ const compileGlob = (pattern) => {
   }
 };
 
-const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
+export const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
   const compiled = compileGlob(pattern);
   if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
   return [pattern, repoFiles.filter((path) => compiled.test(path))];

package/tools/procedures.mjs

@@ -232,7 +232,8 @@ const backendSetLabel = (backends) =>
 // review slot can resolve or request reviewed|council (execute floors at solo|delegated), so the gate
 // reads the recipe, the requested recipe and the roster.
 const REVIEW_RECIPES = new Set(['reviewed', 'council']);
-const CONSULT_LINE = '  • Before every fold of a finding raised by a review member (a bridge backend or a placed lens): ASK that member whether the proposed fold solves it and adds no new problem; WAIT for its answer, READ it, then edit only as accepted or corrected — agy: agy-review --continue --decided @f --focus "Finding: <finding>. Proposed fold: <exact fold>. Does this proposed fold solve the finding and add no new problem? Reply accept, or correct with exact replacement text."; codex: fresh codex-review plan <consult-brief> written before the working tree changes; a placed lens: re-dispatch the same lens vehicle with the finding and the proposed fold. A self-review finding, or any finding when no review member ran, is folded directly — the exemption is the finding\'s ORIGIN, never the recipe word on the slot line.';
+const CONSULT_LINE = '  • Before every fold of a finding raised by a review member (a bridge backend or a placed lens): ASK that member whether the proposed fold solves it and adds no new problem; WAIT for its answer, READ it, then edit only as accepted or corrected — agy: agy-review --continue --decided @f --focus "Finding: <finding>. Proposed fold: <exact fold>. Does this proposed fold solve the finding and add no new problem? If this finding is the second case against the same check, reply with the replacement invariant, not an added case. ' +
+  'Reply accept, or correct with exact replacement text."; codex: fresh codex-review plan <consult-brief> with the same payload written before the working tree changes; a placed lens: re-dispatch the same lens vehicle with the same payload. A self-review finding, or any finding when no review member ran, is folded directly — the exemption is the finding\'s ORIGIN, never the recipe word on the slot line.';
 const ARMED_CONSULT_LINE = '  • ARMED pre-fold sequence for a bridge-raised finding: the round is open → dispatch that bridge\'s consult with a nonce → WAIT and READ → fold accepted or corrected → flow-writer consult-attestation <planId> --backend <id> --nonce <n> --proposed-fix-digest <the-sha256-of-the-fold-text> → then edit. A lens-raised finding re-dispatches the lens without a nonce, WAIT and READ, then edit as accepted or corrected — it mints no manifest and no attestation — only its per-round participation rides its internal-attestation.';
 // activity-aware (AD-046): the triage classification vocabulary rides EVERY review-backed activity;
 // the LEDGER pointer renders ONLY for plan-execution — the ledger is plan-execution-scoped (AD-045),

package/tools/queue-audit-cli.mjs

@@ -5,8 +5,9 @@
 // and the rules file had reached the source-size cap. Read-only: it reads the file it is pointed at
 // and writes nothing. Dependency-free, Node >= 22.
 //
-// Exit codes: 0 accept; 1 refuse (a terminal/record row still listed, or a cap breach); 2 usage —
-// a missing/unknown flag, a flag with no value, an unreadable path, or a section that is not there.
+// Exit codes: 0 accept; 1 refuse (a terminal/record row still listed, a cap breach, or — when and
+// only when `--require-names` is named — a row whose name is not a sentence); 2 usage — a
+// missing/unknown flag, a flag with no value, an unreadable path, or a section that is not there.
 
 import { readFileSync } from 'node:fs';
 import { fail } from '../references/scripts/markdown-blocks.mjs';
@@ -17,7 +18,7 @@ const HELP = `queue-audit — classify the backlog queue's rows (agent-workflow
 
 Usage:
   node queue-audit-cli.mjs --report <queue-file> [--section "## Pending / backlog (newest)"]
-  node queue-audit-cli.mjs --check  <queue-file> [--section "…"] [--max-rows N] [--max-row-lines N]
+  node queue-audit-cli.mjs --check  <queue-file> [--section "…"] [--max-rows N] [--max-row-lines N] [--require-names]
 
 --report  one tab-separated line per row: file line, class, row length, title, the literal evidence.
           Deterministic — this is the manifest a deletion is driven by, never a regex guess.
@@ -25,6 +26,10 @@ Usage:
           carries work (live, parked and ambiguous alike), or when more rows than the row cap carry
           work. Ambiguous rows are reported and never refuse on their own: a row that contradicts
           itself, or names a status word outside a status position, is settled by a human.
+--require-names  the opt-in a project adds once its rows are named: a row whose name is not a plain
+          sentence refuses with exit 1 instead of printing a note. Without it every name finding is
+          a NOTE and the verdict is byte for byte what it was, so a queue that has not migrated is
+          never bricked by an upgrade it did not ask for.
 
 Classes: ${CLASSES.join(' · ')}. Defaults: --max-rows ${DEFAULTS.maxRows}, --max-row-lines ${DEFAULTS.maxRowLines}.
 
@@ -44,7 +49,7 @@ const parseArgv = (argv) => {
   // makes `--check <dirty-file> --help` exit 0 — the gate's refusal replaced by a help page, which
   // is the same bypass a second mode flag would be, reached by a flag nobody reads as dangerous.
   if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) return { mode: 'help' };
-  const options = { mode: null, path: null, section: null };
+  const options = { mode: null, path: null, section: null, requireNames: false };
   // Every option here is a SINGLETON. A repeat used to win silently: a second `--section` moved the
   // domain the report covers and a softer `--max-rows` moved the ratchet, both without a word — and
   // both in the direction that lets a queue keep rows a check would have refused.
@@ -69,6 +74,9 @@ const parseArgv = (argv) => {
       once(arg);
       options.section = valueOf(argv, index, arg);
       index += 1;
+    } else if (arg === '--require-names') {
+      once(arg);
+      options.requireNames = true;
     } else if (arg === '--max-rows' || arg === '--max-row-lines') {
       once(arg);
       const value = Number(valueOf(argv, index, arg));
@@ -79,12 +87,11 @@ const parseArgv = (argv) => {
   }
   if (!options.mode) throw fail(2, 'one of --report or --check is required — run with --help');
   if (!options.path) throw fail(2, `${`--${options.mode}`} takes a queue file path`);
-  // A cap named beside `--report` used to be accepted and then ignored, and the run still exited 0 —
-  // so an operator who meant to ask a question about the caps was told nothing and read the silence
-  // as an answer. The caps belong to `--check`; naming one here is a usage error, not a no-op.
-  const capsInReport = ['--max-rows', '--max-row-lines'].filter((flag) => seen.has(flag));
-  if (options.mode === 'report' && capsInReport.length) {
-    throw fail(2, `${capsInReport.join(' and ')} ${capsInReport.length > 1 ? 'are' : 'is'} a --check option — --report lists every row and judges no cap`);
+  // A check-only option named beside `--report` used to be accepted and then ignored, and the run
+  // still exited 0. Those options belong to `--check`; naming one here is usage, not a no-op.
+  const checkOnlyInReport = ['--max-rows', '--max-row-lines', '--require-names'].filter((flag) => seen.has(flag));
+  if (options.mode === 'report' && checkOnlyInReport.length) {
+    throw fail(2, `${checkOnlyInReport.join(' and ')} ${checkOnlyInReport.length > 1 ? 'are' : 'is'} a --check option — --report lists every row and judges no check-only rule`);
   }
   return options;
 };