@sabaiway/agent-workflow-kit 10.4.0 → 10.5.0

package/tools/plan-shape.mjs

@@ -0,0 +1,348 @@
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+
+export const PLAN_TITLE_PREFIX = '# Plan: ';
+export const PLAN_HEADINGS = Object.freeze([
+  '## Goal and boundary',
+  '## Module ledger',
+  '## Verification',
+  '## Phase: Cleanup',
+  '## Next steps',
+]);
+
+const MAX_PLAN_LINES = 100;
+const MAX_LEDGER_ROWS = 25;
+const MAX_ROW_BYTES = 200;
+const SECTION_CAPS = Object.freeze({
+  '## Goal and boundary': 10,
+  '## Module ledger': 60,
+  '## Verification': 20,
+});
+const CLEANUP_NEXT_CAP = 10;
+const ROW_ID = /^[A-Za-z0-9._-]+$/;
+const VERBS = new Set(['create', 'modify', 'delete']);
+const GLOB_BYTE = /[*?[{]/;
+const TOTAL_LINE = /^total:\s+(~?\d+)\s+→\s+(~?\d+)\s+lines(?:\s+.+)?$/;
+const SPEC_LINE = /docs\/ai\/specs\/|(?:^|\W)(?:not adopted|adopting|nothing spec-covered touched)(?:\W|$)/;
+const TEST_PATH = /(?:^|\/)\S+\.test\.[^/]+$/;
+const EXTENSION_PHASE = /^## Phase: (?!Cleanup\s*$)\S(?:.*\S)?$/;
+const BULLET = /^-\s+\S/;
+
+export const getLineCount = (text) => text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+export const isSweep = (path) => GLOB_BYTE.test(path);
+const endsWithPath = (path, suffix) => path === suffix || path.endsWith(`/${suffix}`);
+export const unique = (items) => [...new Set(items)];
+const getFindingLine = (document, index) => document.frontLines + index + 1;
+const makeFinding = (line, code, message, rowId = null) => ({ line, code, message, rowId });
+const getHeading = (document, text) => document.headings.find((heading) => heading.text === text);
+const getNextSection = (document, heading) => document.headings.find((item) => item.index > heading.index && item.level <= 2);
+const getBodyEnd = (document) => document.lines.length - (document.lines.at(-1) === '' ? 1 : 0);
+const getSectionEnd = (document, heading) => getNextSection(document, heading)?.index ?? getBodyEnd(document);
+const getSectionLines = (document, headingText) => {
+  const heading = getHeading(document, headingText);
+  return heading ? document.lines.slice(heading.index + 1, getSectionEnd(document, heading)) : [];
+};
+const getSectionSpan = (document, headingText) => {
+  const heading = getHeading(document, headingText);
+  return heading ? getSectionEnd(document, heading) - heading.index : 0;
+};
+const getBudget = (value) => {
+  const parsed = /^\d+$/.test(value) ? Number(value) : null;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+};
+const getFigure = (value) => Number(String(value).replace(/^~/, ''));
+const getConcretePaths = (row, facts) => isSweep(row.path) ? facts.expansions?.[row.path] ?? [] : [row.path];
+const getPathFact = (facts, path) => facts.pathFacts?.[path] ?? null;
+const getAnchorPath = (anchor) => anchor.replace(/:[1-9]\d*$/, '');
+const hasPathDefect = (path) => path.startsWith('/') || path.includes('\\') || path.split('/').includes('..');
+const hasRaiseBullet = (verificationBullets, path) => verificationBullets.some((bullet) =>
+  bullet.includes('--write-baseline') && bullet.includes('--reason') && bullet.includes(path));
+
+// fenceContinues (queue-audit's reader): only a NESTED fence continues an open bullet — a column-0
+// fence is a document block and closes it; `gaps` records where an absorbed run sat, so no reader
+// joins text from both sides of a code block into one claim.
+export const bulletBlocks = (lines, fencedLines, from, to, { fenceContinues = false } = {}) => {
+  const indexes = Array.from({ length: Math.max(0, to - from) }, (_, offset) => from + offset);
+  const reduced = indexes.reduce((state, index) => {
+    if (fencedLines.has(index)) {
+      const absorbing = state.absorbing ?? Boolean(fenceContinues && state.current && /^\s+\S/.test(lines[index]));
+      if (!absorbing) return { blocks: state.current ? [...state.blocks, state.current] : state.blocks, current: null, absorbing };
+      const gaps = new Set([...state.current.gaps, state.current.lines.length - 1]);
+      return { blocks: state.blocks, current: { ...state.current, span: state.current.span + 1, gaps }, absorbing };
+    }
+    const line = lines[index];
+    if (BULLET.test(line)) {
+      return {
+        blocks: state.current ? [...state.blocks, state.current] : state.blocks,
+        current: { start: index, lines: [line], span: 1, gaps: new Set() },
+        absorbing: null,
+      };
+    }
+    if (state.current && (line.trim() === '' || /^\s+\S/.test(line))) {
+      return { blocks: state.blocks, current: { ...state.current, lines: [...state.current.lines, line], span: state.current.span + 1 }, absorbing: null };
+    }
+    return { blocks: state.current ? [...state.blocks, state.current] : state.blocks, current: null, absorbing: null };
+  }, { blocks: [], current: null, absorbing: null });
+  return reduced.current ? [...reduced.blocks, reduced.current] : reduced.blocks;
+};
+
+const parseRow = (raw, line) => {
+  const parts = raw.split(' | ').map((part) => part.trim());
+  if (parts.length !== 6) return { raw, line, valid: false, id: parts[0] || null };
+  const [id, verb, path, responsibility, budget, anchor] = parts;
+  const budgetValid = budget === 'n/a' || budget === '—' || getBudget(budget) !== null;
+  const deleteValid = verb === 'delete'
+    ? budget === '—' && anchor === '—'
+    : budget !== '—' && anchor !== '—' && anchor.length > 0;
+  const valid = ROW_ID.test(id) && VERBS.has(verb) && path.length > 0 && responsibility.length > 0 && budgetValid && deleteValid;
+  return {
+    raw,
+    line,
+    valid,
+    id,
+    verb,
+    path,
+    responsibility,
+    budget,
+    budgetLines: getBudget(budget),
+    anchor,
+    anchorPath: anchor === '—' ? null : getAnchorPath(anchor),
+  };
+};
+
+export const parseLedger = (text, suppliedDocument = null) => {
+  const document = suppliedDocument ?? tokenizeMarkdown(String(text ?? ''), 'the plan');
+  const start = getHeading(document, PLAN_HEADINGS[1]);
+  const end = getHeading(document, PLAN_HEADINGS[2]);
+  if (!start || !end || end.index <= start.index) return { rows: [], total: null, entries: [], document };
+  const entries = document.lines.slice(start.index + 1, end.index).map((raw, offset) => ({
+    raw,
+    index: start.index + 1 + offset,
+    line: getFindingLine(document, start.index + 1 + offset),
+  }));
+  const rows = entries.filter((entry) => entry.raw.includes(' | ')).map((entry) => parseRow(entry.raw, entry.line));
+  const totals = entries.filter((entry) => entry.raw.trim().startsWith('total:'));
+  const totalMatch = totals.length === 1 ? TOTAL_LINE.exec(totals[0].raw.trim()) : null;
+  const total = totalMatch ? {
+    line: totals[0].line,
+    beforeRaw: totalMatch[1],
+    afterRaw: totalMatch[2],
+    before: getFigure(totalMatch[1]),
+    after: getFigure(totalMatch[2]),
+  } : null;
+  return { rows, total, totals, entries, document };
+};
+
+const getVerificationBullets = (document) => {
+  const heading = getHeading(document, PLAN_HEADINGS[2]);
+  if (!heading) return [];
+  return bulletBlocks(document.lines, document.fencedLines, heading.index + 1, getSectionEnd(document, heading))
+    .map((block) => block.lines.join('\n').replace(/^\-\s+/, '').replace(/\s+/g, ' ').trim());
+};
+
+const checkHeadings = (text, document) => {
+  const findings = [];
+  const first = document.headings[0];
+  if (!first || first.level !== 1 || !first.text.startsWith(PLAN_TITLE_PREFIX) || first.text.slice(PLAN_TITLE_PREFIX.length).trim() === '') {
+    findings.push(makeFinding(first ? getFindingLine(document, first.index) : 1, 'title', `the first heading must open with "${PLAN_TITLE_PREFIX}" and a non-empty title`));
+  }
+  const secondLevel = document.headings.filter((heading) => heading.level === 2);
+  for (const literal of PLAN_HEADINGS) {
+    const matches = secondLevel.filter((heading) => heading.text === literal);
+    if (matches.length !== 1) findings.push(makeFinding(matches[0] ? getFindingLine(document, matches[0].index) : 1, 'headings', `${literal} must appear exactly once`));
+  }
+  const positions = PLAN_HEADINGS.map((literal) => secondLevel.findIndex((heading) => heading.text === literal));
+  if (positions.every((position) => position >= 0) && positions.some((position, index) => index > 0 && position <= positions[index - 1])) {
+    findings.push(makeFinding(1, 'headings', 'the five plan sections must keep their literal order'));
+  }
+  for (const heading of secondLevel) {
+    if (PLAN_HEADINGS.includes(heading.text)) continue;
+    const verification = positions[2];
+    const cleanup = positions[3];
+    const position = secondLevel.indexOf(heading);
+    if (!EXTENSION_PHASE.test(heading.text) || verification < 0 || cleanup < 0 || position <= verification || position >= cleanup) {
+      findings.push(makeFinding(getFindingLine(document, heading.index), 'headings', `${heading.text} is not an admitted extension phase between Verification and Cleanup`));
+    }
+  }
+  if (getLineCount(text) > MAX_PLAN_LINES) findings.push(makeFinding(1, 'line-cap', `the plan has ${getLineCount(text)} lines; the cap is ${MAX_PLAN_LINES}`));
+  for (const [heading, cap] of Object.entries(SECTION_CAPS)) {
+    const span = getSectionSpan(document, heading);
+    if (span > cap) findings.push(makeFinding(getFindingLine(document, getHeading(document, heading).index), 'section-cap', `${heading} spans ${span} lines; the cap is ${cap}`));
+  }
+  const cleanupNext = getSectionSpan(document, PLAN_HEADINGS[3]) + getSectionSpan(document, PLAN_HEADINGS[4]);
+  if (cleanupNext > CLEANUP_NEXT_CAP) findings.push(makeFinding(1, 'section-cap', `Cleanup and Next steps span ${cleanupNext} lines; their shared cap is ${CLEANUP_NEXT_CAP}`));
+  return findings;
+};
+
+const checkLedgerStructure = (parsed, facts) => {
+  const findings = [];
+  const nonBlank = parsed.entries.filter((entry) => entry.raw.trim() !== '');
+  const rowLines = new Set(parsed.rows.map((row) => row.line));
+  const totalLines = new Set((parsed.totals ?? []).map((total) => total.line));
+  for (const entry of nonBlank) {
+    if (!rowLines.has(entry.line) && !totalLines.has(entry.line)) findings.push(makeFinding(entry.line, 'ledger-line', 'a ledger line must be a six-field row or the total line'));
+  }
+  for (const row of parsed.rows) {
+    if (!row.valid) findings.push(makeFinding(row.line, 'row-grammar', 'the row must carry six valid fields and delete rows alone use — for budget and anchor', row.id));
+  }
+  if (parsed.rows.length > MAX_LEDGER_ROWS) findings.push(makeFinding(parsed.rows[MAX_LEDGER_ROWS].line, 'row-cap', `the ledger has ${parsed.rows.length} rows; the cap is ${MAX_LEDGER_ROWS}`));
+  const ids = new Map();
+  for (const row of parsed.rows.filter((item) => item.id)) {
+    const prior = ids.get(row.id);
+    if (prior) findings.push(makeFinding(row.line, 'duplicate-id', `${row.id} duplicates the row on line ${prior}`, row.id));
+    else ids.set(row.id, row.line);
+  }
+  for (const row of parsed.rows.filter((item) => item.valid)) {
+    const countedBytes = Buffer.byteLength([row.id, row.verb, row.responsibility, row.budget].join(' | '), 'utf8');
+    if (countedBytes > MAX_ROW_BYTES) findings.push(makeFinding(row.line, 'row-bytes', `${row.id} has ${countedBytes} counted bytes; the cap is ${MAX_ROW_BYTES}`, row.id));
+    const contained = !hasPathDefect(row.path) && getPathFact(facts, row.path)?.contained !== false;
+    if (!contained) findings.push(makeFinding(row.line, 'containment', `${row.id} path must be a contained repo-relative POSIX path`, row.id));
+    const anchorContained = row.anchorPath === null || (!hasPathDefect(row.anchorPath) && getPathFact(facts, row.anchorPath)?.contained !== false);
+    if (!anchorContained) findings.push(makeFinding(row.line, 'containment', `${row.id} anchor must be a contained repo-relative POSIX path`, row.id));
+    if (isSweep(row.path) && (row.verb !== 'modify' || !/\([1-9]\d* files\)/.test(row.responsibility))) {
+      findings.push(makeFinding(row.line, 'sweep', `${row.id} sweep must use modify and assert its count as (N files)`, row.id));
+    }
+  }
+  const owners = new Map();
+  for (const row of parsed.rows.filter((item) => item.valid)) {
+    for (const path of getConcretePaths(row, facts)) {
+      const prior = owners.get(path);
+      if (prior) findings.push(makeFinding(row.line, 'duplicate-path', `${path} is owned by both ${prior} and ${row.id}`, row.id));
+      else owners.set(path, row.id);
+    }
+  }
+  const last = nonBlank.at(-1);
+  if (!parsed.total || (parsed.totals ?? []).length !== 1 || last?.line !== parsed.total?.line) {
+    findings.push(makeFinding(last?.line ?? 1, 'total', 'the exact total line must be the last non-blank ledger line'));
+  }
+  const bullets = getVerificationBullets(parsed.document);
+  if (bullets.length === 0) findings.push(makeFinding(getHeading(parsed.document, PLAN_HEADINGS[2]) ? getFindingLine(parsed.document, getHeading(parsed.document, PLAN_HEADINGS[2]).index) : 1, 'acceptance', 'Verification must carry at least one top-level - bullet'));
+  if (!getSectionLines(parsed.document, PLAN_HEADINGS[0]).some((line) => SPEC_LINE.test(line))) {
+    findings.push(makeFinding(getHeading(parsed.document, PLAN_HEADINGS[0]) ? getFindingLine(parsed.document, getHeading(parsed.document, PLAN_HEADINGS[0]).index) : 1, 'governing-spec', 'Goal and boundary must name a governing spec path or the adopted state'));
+  }
+  return findings;
+};
+
+export const resolveAnchorCandidates = (repoFiles, suffix, precedingPaths) => {
+  if (repoFiles.includes(suffix)) return [suffix];
+  const above = unique(precedingPaths.filter((path) => endsWithPath(path, suffix)));
+  return above.length > 0 ? above : unique(repoFiles.filter((path) => endsWithPath(path, suffix)));
+};
+
+const getAnchorCandidates = (row, preceding, facts) => {
+  const suffix = row.anchorPath;
+  if (!suffix || hasPathDefect(suffix)) return [];
+  const precedingPaths = preceding.filter((item) => item.valid).flatMap((item) => getConcretePaths(item, facts));
+  return facts.candidates(suffix, precedingPaths);
+};
+
+const getCurrentLines = (rows, facts, verbs) => rows
+  .filter((row) => row.valid && verbs.has(row.verb) && row.budget !== 'n/a')
+  .flatMap((row) => getConcretePaths(row, facts))
+  .reduce((sum, path) => sum + (getPathFact(facts, path)?.lines ?? 0), 0);
+
+const checkAuthoring = (parsed, facts) => {
+  const findings = [];
+  const bullets = getVerificationBullets(parsed.document);
+  for (const [index, row] of parsed.rows.entries()) {
+    if (!row.valid) continue;
+    const paths = getConcretePaths(row, facts);
+    const expectedKind = row.verb === 'create' ? 'absent' : 'regular';
+    if (paths.length === 0 && isSweep(row.path)) findings.push(makeFinding(row.line, 'kind', `${row.id} sweep resolves to no regular path`, row.id));
+    for (const path of paths) {
+      const observed = getPathFact(facts, path)?.kind ?? 'unknown';
+      if (observed !== expectedKind) findings.push(makeFinding(row.line, 'kind', `${row.id} expects ${expectedKind}, observed ${observed} at ${path}`, row.id));
+    }
+    const anchorCandidates = row.anchorPath ? getAnchorCandidates(row, parsed.rows.slice(0, index), facts) : null;
+    if (anchorCandidates && anchorCandidates.length !== 1) {
+      const count = anchorCandidates.length;
+      findings.push(makeFinding(row.line, 'anchor', `${row.id} anchor resolves to ${count} candidates; make it unique`, row.id));
+    }
+    if (row.verb !== 'delete' && row.budgetLines !== null && !facts.capDeclared) {
+      findings.push(makeFinding(row.line, 'cap-declaration', `${row.id} uses an integer budget but no source-size cap is declared; use n/a`, row.id));
+    }
+    for (const path of paths) {
+      const pathFact = getPathFact(facts, path);
+      if (!pathFact?.inScope) continue;
+      if (row.budget === 'n/a') findings.push(makeFinding(row.line, 'source-budget', `${row.id} is in source scope and cannot use n/a`, row.id));
+      if (row.verb === 'create' && !TEST_PATH.test(path)) {
+        const hasEarlierTest = parsed.rows.slice(0, index).some((prior) => prior.valid && ['create', 'modify'].includes(prior.verb) && TEST_PATH.test(prior.path));
+        if (!hasEarlierTest) findings.push(makeFinding(row.line, 'red-first', `${row.id} needs a create or modify test row above it`, row.id));
+      }
+      const ceiling = row.verb === 'modify' && pathFact.recordedLines != null ? pathFact.recordedLines : facts.cap;
+      if (row.budgetLines !== null && ceiling != null && row.budgetLines > ceiling && !hasRaiseBullet(bullets, row.path)) {
+        findings.push(makeFinding(row.line, 'budget-cap', `${row.id} budget ${row.budgetLines} exceeds ${ceiling}; name a reasoned baseline raise for ${row.path}`, row.id));
+      }
+    }
+    if (row.verb === 'create') {
+      const pathFact = getPathFact(facts, row.path);
+      if (pathFact?.shipped === true && pathFact.pinTest && !parsed.rows.some((candidate) => candidate.valid && candidate.verb === 'modify' && candidate.path === pathFact.pinTest)) {
+        findings.push(makeFinding(row.line, 'package-pin', `${row.id} ships but no modify row owns ${pathFact.pinTest}`, row.id));
+      }
+    }
+  }
+  if (parsed.total) {
+    const current = getCurrentLines(parsed.rows, facts, new Set(['modify', 'delete']));
+    if (parsed.total.before !== current) findings.push(makeFinding(parsed.total.line, 'before-total', `before is ${parsed.total.before}; current counted paths sum to ${current}`));
+  }
+  return { findings, skips: parsed.rows.filter((row) => row.verb === 'create').flatMap((row) =>
+    getPathFact(facts, row.path)?.pinSkip ? [`${row.id}: package pin skipped — ${getPathFact(facts, row.path).pinSkip}`] : []) };
+};
+
+const checkPostState = (parsed, facts) => {
+  const findings = [];
+  for (const row of parsed.rows.filter((item) => item.valid)) {
+    const paths = getConcretePaths(row, facts);
+    if (isSweep(row.path)) {
+      const expected = Number(/\(([1-9]\d*) files\)/.exec(row.responsibility)?.[1]);
+      if (paths.length === 0 || paths.length !== expected) findings.push(makeFinding(row.line, 'sweep-count', `${row.id} expected ${expected} files and resolves to ${paths.length}`, row.id));
+    }
+    for (const path of paths) {
+      const fact = getPathFact(facts, path);
+      const expectedKind = row.verb === 'delete' ? 'absent' : 'regular';
+      if (fact?.kind !== expectedKind) findings.push(makeFinding(row.line, 'post-kind', `${row.id} expects ${expectedKind}, observed ${fact?.kind ?? 'unknown'} at ${path}`, row.id));
+      if (row.verb !== 'delete' && row.budgetLines !== null && fact?.kind === 'regular' && fact.lines > row.budgetLines) {
+        findings.push(makeFinding(row.line, 'post-budget', `${path} has ${fact.lines} lines, above ${row.id} budget ${row.budgetLines}`, row.id));
+      }
+    }
+  }
+  if (parsed.total) {
+    const current = getCurrentLines(parsed.rows, facts, new Set(['create', 'modify']));
+    if (parsed.total.after < current) findings.push(makeFinding(parsed.total.line, 'after-total', `after is ${parsed.total.after}; counted paths sum to ${current}`));
+  }
+  return { findings, skips: [] };
+};
+
+const parseForJudge = (text) => {
+  try {
+    return { parsed: parseLedger(text), error: null };
+  } catch (error) {
+    return { parsed: null, error };
+  }
+};
+
+const judge = (text, facts, stateRules) => {
+  const parsedResult = parseForJudge(text);
+  if (parsedResult.error) {
+    const line = Number(/:(\d+):/.exec(parsedResult.error.message)?.[1] ?? 1);
+    return { findings: [makeFinding(line, 'block-model', parsedResult.error.message)], skips: [], parsed: null };
+  }
+  const parsed = parsedResult.parsed;
+  const structural = [...checkHeadings(String(text ?? ''), parsed.document), ...checkLedgerStructure(parsed, facts)];
+  const state = stateRules ? stateRules(parsed, facts) : { findings: [], skips: [] };
+  const findings = [...structural, ...state.findings].map((finding, index) => ({ ...finding, order: index }))
+    .sort((left, right) => left.line - right.line || left.order - right.order)
+    .map(({ order, ...finding }) => finding);
+  return { findings, skips: state.skips, parsed };
+};
+
+export const checkPlan = (text, facts) => judge(text, facts, checkAuthoring);
+export const verifyPlan = (text, facts) => judge(text, facts, checkPostState);
+export const checkPlanStructure = (text, facts) => judge(text, facts, null);
+
+export const formatFindings = (result, label = 'plan') => {
+  const lines = result.findings.length === 0
+    ? [`plan-shape: ACCEPT — ${label}`]
+    : [`plan-shape: REFUSE — ${label}`, ...result.findings.map((finding) =>
+      `${label}:${finding.line}: ${finding.rowId ? `${finding.rowId}: ` : ''}${finding.code}: ${finding.message}`)];
+  return [...lines, ...result.skips.map((skip) => `plan-shape: SKIP — ${skip}`)].join('\n');
+};

package/tools/procedures.mjs

@@ -35,7 +35,7 @@ import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from '.
 import { plansInFlight, PLANS_REL } from './plan-files.mjs';
 // The family's ONE shell quoter for a RENDERED command operand (bare when the value is already safe,
 // single-quoted otherwise) — the same leaf eight other command renderers here read through.
-import { shellQuoteArg } from './repo-lex.mjs';
+import { shellQuoteArg, isSeedablePathToken, isRenderableLine, escapeForDisplay, isArtifactPathCarriable } from './repo-lex.mjs';
 // The config schema/read core (orchestration-config.mjs, the single config contract): the reader +
 // the SHARED slot/recipe validity, never the fs-writer (orchestration-write.mjs) DIRECTLY — the
 // import-split test pins the direct-import rule.
@@ -47,6 +47,7 @@ import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from
 // structural — test/read-graph-purity.test.mjs pins it).
 import { resolveFlowStorePath, readFlowStore } from './flow-store-read.mjs';
 import { CHAIN_KIND } from './flow-record.mjs';
+import { readRegistration } from './mcp-registration.mjs';
 // The declared source-size practice (D-17 U1), read through the practice's PURE READ core — never
 // source-size-check.mjs, which owns the writer half: this advisor is a read root of
 // test/read-graph-purity.test.mjs, and the core exists so a surface can ask without reaching a writer.
@@ -166,7 +167,7 @@ const resolveAllSlots = ({ activity, config, detection, overrides }) => {
     // planRecipe's drift-guarded dispatch for WHICH backends, then resolve each (backend, role) to its
     // manifest wrapper cmd via the bridge registry — no wrapper name is hand-composed here. A vehicle
     // step is NOT a bridge: it carries its own state and is never looked up in a manifest.
-    const { dispatch } = planRecipe(resolved.recipe, detection);
+    const { dispatch } = resolved.roster ? { dispatch: [] } : planRecipe(resolved.recipe, detection);
     const vehicles = dispatch.filter((d) => d.vehicle != null).map((d) => ({ backend: d.backend, state: d.vehicle }));
     const bridged = dispatch.filter((d) => d.vehicle == null);
     const backends = bridged.map((d) => wrapperCmdFor(d.backend, d.role)).filter(Boolean);
@@ -189,8 +190,9 @@ const resolveAllSlots = ({ activity, config, detection, overrides }) => {
 // carrier-typed slot (registry-driven — no slot name is spelled here), solo when it has none.
 const effectiveCarrier = (slots) => slots.find((s) => s.slotType === 'carrier')?.recipe ?? 'solo';
 
-// An unsatisfiable EXPLICIT override is the only "warning" (loud, flagged for the agent to relay). A
-// graceful config/default degradation is reported as a per-slot reason, not a warning.
+// An unsatisfiable EXPLICIT override is a warning (loud, flagged for the agent to relay); a graceful
+// config/default degradation remains a per-slot reason. Canon/registry slot-skew warnings are
+// collected separately, after the live section is read.
 const collectWarnings = (slots) =>
   slots
     .filter((s) => s.overrideUnsatisfied)
@@ -216,24 +218,34 @@ const backendSetLabel = (backends) =>
       : ` → ${backends[0]}`;
 
 // The review-loop economics block (M1 + M6's firing half) — printed when the activity engages a review
-// backend (a slot resolving reviewed | council) and OMITTED for solo. It paraphrases the procedures.md
+// member: a slot RESOLVING reviewed | council, a roster, or one whose config or override REQUESTED a
+// review recipe and degraded (readiness removes no configured obligation, and the table still judges
+// it); omitted only for a solo nobody asked to be otherwise. It paraphrases the procedures.md
 // Fold + loop step + orchestration §4 canon (no rival rule): the ≤2-round architecture cap, the bar met by RAISING a
 // surviving major to an acceptance invariant (not exhausting prose), backend divergence = the crossover
 // stop, the thin-plan/diff-review carve-out, a self-consistency read before every re-review, and the
 // REQUIRED per-round structured emission {round N · finding-origin tally · per-backend verdict}. Only a
-// review slot can resolve reviewed|council (execute floors at solo|delegated), so gate on the recipe.
+// 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 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),
 // and pointing plan-authoring at it would send rounds of the wrong activity into the code loop's gate.
-const reviewLoopAdvice = (slots, activity) =>
-  slots.some((s) => REVIEW_RECIPES.has(s.recipe))
+// A lens-only roster resolves to `solo` and a fully degraded request resolves to `solo`: both still run
+// a review round, which is why the gate never reads the effective recipe alone.
+const reviewLoopAdvice = (slots, activity, flowArmed = false, plans = []) =>
+  slots.some((s) => s.roster != null || REVIEW_RECIPES.has(s.recipe) || REVIEW_RECIPES.has(s.degradedFrom))
     ? [
         'Review-loop economics (procedures.md Fold + loop · orchestration.md §4) — the review this recipe runs:',
+        CONSULT_LINE,
+        ...(activity === 'plan-execution' && flowArmed ? [ARMED_CONSULT_LINE] : []),
         '  • Cap architecture plan-review at ≤2 rounds; the bar is met by RAISING a surviving major to an acceptance invariant (or handing it to Execute/diff-review), never by exhausting the strictest backend.',
         '  • Backend divergence (one backend grounded-ships while another keeps revising mechanics) IS the crossover stop.',
         '  • Route an all-mechanics/CI or prose-only artifact to a thin plan + diff-review; run a self-consistency read before every re-review.',
         '  • Each round MUST emit {round N · finding-origin tally (first-draft / fold-induced / mechanics) · per-backend verdict} so the crossover is a computed signal.',
+        ...(activity === 'plan-authoring' ? roundRenderAdvice(slots, plans) : []),
         '  • At the cap, classify every surviving blocking finding: fixable-bug (fold ONCE as a red→green test, re-review) / inherent-layer-residual (document + raise to an acceptance criterion) / escalate (the maintainer decides); a minor never forces triage.',
         ...(activity === 'plan-execution'
           ? [
@@ -246,38 +258,119 @@ const reviewLoopAdvice = (slots, activity) =>
 // The grounding pre-step (AD-038, extending the AD-033 verbatim-contract rendering): whenever the
 // resolved dispatch includes agy-review, print the CONCRETE facts-assembly invocation + the
 // --facts form as a copy-paste pre-step — population, not placeholders. Plan-path population rule
-// (the review-state plan-in-flight detector): exactly ONE plan in flight → render it populated;
-// zero or several → the explicit `--plan <path>` placeholder + a one-line discovery caveat. The
+// (the review-state plan-in-flight detector): exactly ONE renderable plan in flight → render it
+// populated; zero, several, or a name a one-line render cannot carry → the explicit placeholder + a
+// one-line discovery caveat; a name the receipt encoder refuses falls back on the receipt-minting
+// or receipt-matching command only (`agy-review plan`, the round table). The
 // suggested --out lives OUTSIDE the repo (/tmp) — grounding.mjs refuses a non-scratch destination.
 // Exported for the bridge-tier byte-parity pin (AD-044 Plan 4): the velocity tier seeds the
 // grounding rule in EXACTLY this rendered spelling — `node "${GROUNDING_TOOL}"` — so seeded and
 // rendered forms can never drift apart.
 export const GROUNDING_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'grounding.mjs');
+export const REVIEW_ROUNDS_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'review-rounds-cli.mjs');
+export const REPO_SEARCH_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'repo-search.mjs');
 const GROUNDING_FACTS_OUT = '/tmp/review-facts.md';
+const MINTS_RECEIPT = Object.freeze({ mintsReceipt: true });
+
+// The round table judges what review-rounds-cli resolves from the config (S27), never this render's
+// override or degradation, so the advisor states that fact beneath the command instead of predicting
+// when the two agree; a bridge-less roster gets the fact that no receipt can exist in the command's place.
+// A requested review recipe renders the command even when every bridge is unavailable here: readiness
+// degradation removes no configured obligation, so the table still has something to say.
+const ROUND_RENDER_FACT_LINE = "  ↳ the table judges the obligation review-rounds-cli resolves from docs/ai/orchestration.json (S27) — the configured recipe, or the computed default for a silent slot — never this run's --override or a degraded recipe; it reads receipts only: a backend that did not run shows as missing (no receipts when none ran), and its degrade record is judged by review-state and core-evidence summary, not here.";
+const ROUND_RENDER_NO_BRIDGE_LINE = "  • Round render: a roster with no bridge mints no receipt, so review-rounds-cli cannot supply this round's verdicts — emit the finding-origin tally plus each lens member's verdict (or silent) directly.";
+const roundRenderAdvice = (slots, plans) => {
+  const review = slots.find((s) => s.slot === 'review');
+  if (review === undefined) return [];
+  const roster = review.roster ?? null;
+  const shouldRenderCommand = roster === null
+    ? (review.backends ?? []).length > 0 || REVIEW_RECIPES.has(review.degradedFrom)
+    : roster.some((row) => row.kind === 'bridge');
+  if (!shouldRenderCommand) return [ROUND_RENDER_NO_BRIDGE_LINE];
+  const lensMembers = (roster ?? []).filter((row) => row.kind === 'lens').map((row) => row.member);
+  const operand = populatedPlan(plans, MINTS_RECEIPT);
+  return [
+    `  • Round render (verdict half of the per-round emission; the finding-origin tally stays the orchestrator's): node ${renderToolPath(REVIEW_ROUNDS_TOOL)} --artifact ${operand ?? '<plan-file>'}`,
+    ...planDiscoveryCaveat(plans, '--artifact', 'populate --artifact with the plan file under review.', operand === null ? ['--artifact'] : []),
+    ROUND_RENDER_FACT_LINE,
+    ...(lensMembers.length > 0 ? [`  ↳ the table carries the bridge verdicts only — add each lens member's verdict (or silent) by hand: ${lensMembers.join(', ')}`] : []),
+  ];
+};
+
+// The ONE plan in flight as a pasteable operand: shell-significant bytes ride shellQuoteArg; a name a
+// one-line render cannot carry is never populated, nor one the receipt encoder refuses (S21) for a
+// command that MINTS or MATCHES a plan receipt: agy-review plan would be refused pre-spend by name, the
+// round table would match no receipt.
+const populatedPlan = (plans, { mintsReceipt = false } = {}) => {
+  if (plans.length !== 1 || !isRenderableLine(plans[0])) return null;
+  if (mintsReceipt && !isArtifactPathCarriable(plans[0])) return null;
+  return shellQuoteArg(`${PLANS_REL}/${plans[0]}`);
+};
+const planDiscoveryCaveat = (plans, flag, noPlanAction, fellBack = []) => {
+  if (plans.length === 0) return [`  ↳ plan discovery: no plan in flight under ${PLANS_REL} — ${noPlanAction}`];
+  if (plans.length > 1) return [`  ↳ plan discovery: ${plans.length} plans in flight under ${PLANS_REL} (${plans.map(escapeForDisplay).join(', ')}) — populate ${flag} with the one under review.`];
+  return fellBack.length === 0
+    ? []
+    : [`  ↳ plan discovery: the plan in flight ${escapeForDisplay(plans[0])} carries a character that either a review receipt or a rendered command cannot carry — ${fellBack.join(' and ')} ${fellBack.length === 1 ? 'stays a placeholder' : 'stay placeholders'}; rename the plan.`];
+};
+
+// The kit-tools tier seeds `Bash(node <abs>/tools/repo-search.mjs:*)` BARE (velocity-profile.mjs
+// deriveKitToolsAllowlist, the same predicate), so a seedable path renders bare — a quoted path is
+// a different prefix and the allow rule is dead. A path the tier could never seed has no rule to
+// match and is single-quoted for a safe paste (double quotes would still expand `$` and backticks).
+const renderToolPath = (abs) => (isSeedablePathToken(abs) ? abs : shellQuoteArg(abs));
+// `registered` is the registration on disk, never the tool's availability in this session — the
+// command line stays as the fallback under the typed form. `toolPath` is a test seam (an unseedable
+// kit path is not constructible from a test against the real checkout).
+const readersSweepAdvice = (activity, registered, toolPath = REPO_SEARCH_TOOL) => {
+  if (activity !== 'plan-authoring') return [];
+  return [
+    'Readers sweep (before the first review) — for every changed config key, registry entry, exported constant, receipt field or canon sentence:',
+    ...(registered ? ['  use: repo_search {"pattern": "<the literal>"} — the kit\'s read-only MCP tool (registration complete; if it is not loaded in this session, the command below)'] : []),
+    `  run: node ${renderToolPath(toolPath)} --pattern <the literal> (a pattern carrying a shell-significant byte goes through --pattern-file <f> instead)`,
+    '  classify every reader as a ledger row, a stated non-goal, or unchanged with its proof',
+  ];
+};
+
+// The canon's own claim — the kit "parses only each section's `Slots:` line" — made true: an installed
+// engine older (or newer) than this kit's registry prints its section verbatim, so the skew is SAID.
+// A section without a Slots line is a customized canon, not a skew: silent. Never the exit code.
+const SLOTS_LINE = /^Slots:[ \t]*(.+?)[ \t]*$/mu;
+const slotSkewWarning = (section, activity) => {
+  const listed = section.match(SLOTS_LINE)?.[1].split(',').map((s) => s.trim()).filter(Boolean);
+  const registry = Object.keys(ACTIVITIES[activity].slots);
+  if (listed == null || listed.join(',') === registry.join(',')) return [];
+  return [`the installed engine's canon lists slots (${listed.join(', ')}) for ${activity} while this kit's registry names (${registry.join(', ')}) — the resolved lines follow the registry; the engine and this kit are out of step — /agent-workflow-kit status names which member is behind: upgrade that one. Tell the user.`];
+};
 const groundingPreStepAdvice = (activity, slots, plans) => {
   if (!slots.some((s) => (s.backends ?? []).includes('agy-review'))) return [];
-  const planArg = plans.length === 1 ? `--plan "${PLANS_REL}/${plans[0]}"` : '--plan <path>';
-  // plan-authoring reviews the plan FILE — when exactly one plan is in flight, the review command
-  // is populated with the same discovered path (a known path never renders a placeholder).
+  const operand = populatedPlan(plans);
+  const planArg = operand === null ? '--plan <path>' : `--plan ${operand}`;
+  const reviewOperand = populatedPlan(plans, MINTS_RECEIPT);
+  // plan-authoring reviews the plan FILE — a plain name in flight renders the review command populated;
+  // the renderability and receipt-carriability fallbacks are the only placeholders a known path produces.
   const reviewForm =
     activity === 'plan-authoring'
-      ? plans.length === 1
-        ? `agy-review plan "${PLANS_REL}/${plans[0]}"`
-        : 'agy-review plan <plan-file>'
+      ? reviewOperand === null
+        ? 'agy-review plan <plan-file>'
+        : `agy-review plan ${reviewOperand}`
       : 'agy-review code';
   // `run:`/`then:` prefixes keep these POPULATED command lines machine-distinguishable from the
   // verbatim contract DESCRIPTORS above (the descriptor drift guard set-equals bare wrapper lines).
-  // Path arguments are double-quoted — a skill dir or plan name with a space must stay copy-pasteable.
+  // The TOOL path stays double-quoted (the bridge tier seeds that exact byte-form); the plan operand
+  // rides shellQuoteArg — bare when safe, single-quoted otherwise.
   const lines = [
     'Grounding pre-step (agy is dispatched — assemble the verified facts BEFORE the review; grounding.mjs slices verbatim, judgment additions stay yours):',
     `  run:  node "${GROUNDING_TOOL}" --constraints --autonomy ${planArg} --out ${GROUNDING_FACTS_OUT}`,
     `  then: ${reviewForm} --facts @${GROUNDING_FACTS_OUT}`,
   ];
-  if (plans.length === 0) {
-    lines.push(`  ↳ plan discovery: no plan in flight under ${PLANS_REL} — substitute the plan file you are reviewing against, or drop --plan for constraints+autonomy facts.`);
-  } else if (plans.length > 1) {
-    lines.push(`  ↳ plan discovery: ${plans.length} plans in flight under ${PLANS_REL} (${plans.join(', ')}) — populate --plan with the one under review.`);
-  }
+  const fellBack = [operand === null ? '--plan' : null, activity === 'plan-authoring' && reviewOperand === null ? 'agy-review plan' : null].filter(Boolean);
+  lines.push(...planDiscoveryCaveat(
+    plans,
+    '--plan',
+    'substitute the plan file you are reviewing against, or drop --plan for constraints+autonomy facts.',
+    fellBack,
+  ));
   return lines;
 };
 
@@ -486,7 +579,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck }) => {
   const lines = [
     section,
     '',
@@ -510,9 +603,10 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if ((flowHalves ?? []).length) lines.push('', ...flowHalves);
   const autonomyBlock = autonomyAdvice(activity, autonomy);
   if (autonomyBlock.length) lines.push('', ...autonomyBlock);
+  if (readersSweep.length) lines.push('', ...readersSweep);
   const grounding = groundingPreStepAdvice(activity, slots, plans);
   if (grounding.length) lines.push('', ...grounding);
-  const advice = reviewLoopAdvice(slots, activity);
+  const advice = reviewLoopAdvice(slots, activity, flowArmed, plans);
   if (advice.length) lines.push('', ...advice);
   if (foldScope.length) lines.push('', ...foldScope);
   if (specCheck.length) lines.push('', ...specCheck);
@@ -525,15 +619,19 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck }) => ({
   activity,
   section,
   slots: Object.fromEntries(
     // `backends: string[]` is the STABLE pre-existing shape (wrapper names) — never repurposed.
     // `contracts` is the ADDITIVE per-dispatch driving-contract field (empty for solo).
-    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts }]),
+    slots.map((s) => [s.slot, {
+      recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts,
+      ...(s.roster ? { roster: s.roster } : {}),
+    }]),
   ),
-  reviewLoop: reviewLoopAdvice(slots, activity),
+  reviewLoop: reviewLoopAdvice(slots, activity, flowArmed, plans),
+  readersSweep,
   // ADDITIVE (AD-038): the populated grounding pre-step, structured (empty when agy is not dispatched).
   groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
@@ -608,7 +706,7 @@ export const main = (argv, ctx = {}) => {
       ),
     });
     const slots = resolveAllSlots({ activity, config, detection, overrides });
-    const warnings = [...detectWarnings, ...collectWarnings(slots)];
+    const warnings = [...detectWarnings, ...collectWarnings(slots), ...slotSkewWarning(section, activity)];
     const plans = plansInFlight(cwd);
     // The autonomy facts (AD-044 Plan 4): resolved levels + red-lines from the policy file. A
     // malformed policy renders LOUDLY in the block AND flips the exit to 1 (config error) — the
@@ -628,13 +726,16 @@ export const main = (argv, ctx = {}) => {
     // The flow armed-halves block (P8): probed ONLY when the config carries a flow block — an
     // unarmed project keeps byte-identical output (human AND JSON) and never pays the store probe.
     const flowProbe = ctx.flowProbe ?? defaultFlowProbe;
-    const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
+    const flowState = config?.flow == null ? null : flowProbe(cwd);
+    const flowHalves = flowState == null ? null : flowHalvesAdvice(config.flow, flowState);
+    const registrationReader = ctx.readRegistration ?? readRegistration;
+    const readersSweep = readersSweepAdvice(activity, activity === 'plan-authoring' && registrationReader(cwd).registered, ctx.repoSearchTool);
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
     const foldScope = foldScopeAdvice(activity, config, plans);
     const specCheck = specCheckAdvice(activity);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope, specCheck });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }