@sabaiway/agent-workflow-kit 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 7.1.0 — `fold-scope`: the fold channel gets a checker that refuses a claim whose reference does not resolve (AD-110)
+
+The engine canon now asks every finding to NAME the invariant its fix enforces before the edit
+(engine **3.1.0**). Prose cannot check that a named invariant is really where you say it is.
+
+- **`tools/fold-scope.mjs` + `tools/fold-scope-cli.mjs`** — the pure rule and its CLI half:
+  `--class in-scope|new-invariant|blocking`, `--claim "<the invariant>"`, `--plan <plan-file>`,
+  `--queue <queue-file>`. Exit 0 for every ACCEPT, non-zero for every REFUSE, one case per arm.
+- **`--plan` and `--queue` are REQUIRED and never defaulted.** A project can have two registers that
+  both look like "the queue" — the planning lifecycle's `docs/plans/queue.md` and a declared
+  `flow.debtQueue` — and a checker that guessed would attest a deferral against the wrong file.
+- **What it refuses**, each naming the lane out of it: an `in-scope` claim matching no acceptance
+  bullet; a `new-invariant` whose invariant IS an acceptance bullet (route to fold); a deferral with
+  no queue row, with several, whose row title carries `DONE`/`CLOSED`, that repeats a field label,
+  that is missing a field (named, including an `origin` that is not a `file:line`), whose claim is
+  not inside the row's `invariant` field, or whose residual exposure is declared live (route to
+  blocking) or declares neither.
+- **`/agent-workflow-kit procedures plan-execution` renders the populated command** — under solo,
+  reviewed AND council, because the rule routes every finding and a Solo project must see the checker
+  too — and NAMES which of the two registers it chose for `--queue`. Every PATH operand goes through
+  the family's shell quoter (bare when the value is already safe, single-quoted when it is not), and
+  the two placeholders are single-quoted literals so their angle brackets and pipe are inert — the
+  line is safe to paste as rendered. `--json` gains an additive `foldScope` array.
+- **Markdown is read through `references/scripts/markdown-blocks.mjs`**, the block model the
+  archivers already use, so fenced examples, heading levels and CRLF are solved once for the family;
+  a document that model refuses is a loud refusal, never a silent empty read.
+
+**Advisory by design:** nothing records that the checker ran, so a skipped or late call is
+indistinguishable from a pre-edit declaration. A fingerprint-bound receipt a gate reads is the next
+slice. Additive throughout — no existing command, flag, output field or exit code changed.
+
 ## 7.0.0 — `/agent-workflow-kit mcp` registers the typed channel in ONE project, and `uninstall` stops reporting an interrupted teardown as a success (AD-108)
 
 > ### ⚠ BREAKING — an `uninstall` run that silently passed can now refuse, and its plan reports more

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '7.0.0'
+  version: '7.1.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/templates/agent_rules.md

@@ -76,6 +76,7 @@ Apply this as part of §2 before any user-facing summary:
 ### 2.6. Planning, review & process-fidelity invariants
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
 - **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.

package/tools/fold-scope-cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// The CLI half of the finding-scope checker: argv and fs, no rule (the rule is fold-scope.mjs).
+//
+// `--plan` and `--queue` are REQUIRED and never defaulted. A project has two registers that can both
+// look like "the queue" - the planning lifecycle's docs/plans/queue.md and a declared
+// flow.debtQueue - and a checker that guessed would attest a deferral against the wrong file. The
+// procedures advisor renders this command already populated, and NAMES which register it chose.
+//
+// Read-only: reads the two files it is pointed at, writes nothing, records nothing (advisory).
+// Dependency-free, Node >= 22.
+//
+// Exit codes: 0 ACCEPT; 1 a matrix REFUSE; 2 usage - a missing/unknown flag, an unreadable path, or
+// a refusal about the arguments themselves (an unknown or absent --class, an absent --claim).
+
+import { readFileSync } from 'node:fs';
+import { isDirectRun } from './direct-run.mjs';
+import { CLASSES, ROW_FIELDS, decideFoldScope } from './fold-scope.mjs';
+
+const HELP = `fold-scope — declare a finding's SCOPE before the edit (agent-workflow family).
+
+Usage:
+  node fold-scope-cli.mjs --class <${CLASSES.join('|')}> --claim "<the invariant>" \\
+                          --plan <plan-file> --queue <queue-file>
+
+Every finding NAMES the invariant its fix enforces, BEFORE the edit. Where that invariant already
+lives decides the arm, and this checker refuses a claim whose reference does not resolve:
+
+  in-scope       the claim matches WITHIN ONE \`- \` bullet under the plan's ## Verification
+                 (those bullets ARE the acceptance criteria) -> fold here.
+  new-invariant  the claim matches NO acceptance bullet AND exactly one queue row carries all five
+                 fields (${ROW_FIELDS.join(', ')}), its residual exposure
+                 declared "not live" -> the narrow fix ships now, only the generalization defers.
+  blocking       no correct narrow fix exists -> the phase does not close. There is no queue arm.
+
+--plan and --queue are required and never defaulted: guessing the register would attest a deferral
+against the wrong file. The check is advisory — nothing records that it ran, so a skipped or late
+call is indistinguishable from a pre-edit declaration.
+
+Exit codes: 0 ACCEPT; 1 REFUSE; 2 usage (missing/unknown flag, unreadable path, bad --class/--claim).`;
+
+const FLAGS = ['class', 'claim', 'plan', 'queue'];
+
+const parseArgs = (argv) => {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg.indexOf('=');
+    const name = arg.startsWith('--') ? arg.slice(2, eq === -1 ? undefined : eq) : null;
+    if (!name || !FLAGS.includes(name)) throw new Error(`unexpected argument "${arg}" (flags: ${FLAGS.map((f) => `--${f}`).join(', ')})`);
+    if (eq !== -1) {
+      opts[name] = arg.slice(eq + 1);
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('--')) throw new Error(`--${name} requires a value`);
+    opts[name] = value;
+    i += 1;
+  }
+  for (const name of ['plan', 'queue']) {
+    if (!opts[name]) throw new Error(`--${name} is required and is never defaulted — name the file this claim is checked against`);
+  }
+  return opts;
+};
+
+// main(argv, deps) -> { code, stdout, stderr }. Never calls process.exit itself (the direct-run
+// guard does), and never reads anything the caller did not point it at.
+export const main = (argv, deps = {}) => {
+  const read = deps.readFileSync ?? readFileSync;
+  if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    return { code: 2, stdout: '', stderr: `fold-scope: ${err.message}` };
+  }
+  const text = {};
+  for (const name of ['plan', 'queue']) {
+    try {
+      text[name] = read(opts[name], 'utf8');
+    } catch (err) {
+      return { code: 2, stdout: '', stderr: `fold-scope: --${name} "${opts[name]}" is unreadable — ${(err && err.message) || err}` };
+    }
+  }
+  const decided = decideFoldScope({ cls: opts.class, claim: opts.claim, planText: text.plan, queueText: text.queue });
+  return { code: decided.exit, stdout: decided.lines.join('\n'), stderr: '' };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.code);
+}

package/tools/fold-scope.mjs

@@ -0,0 +1,307 @@
+// The finding-scope rule as a checker — the half prose cannot do (the engine canon: procedures.md,
+// plan-execution step 5). A finding NAMES the invariant its fix enforces BEFORE the edit; WHERE that
+// invariant already lives decides the disposition, and this module REFUSES a claim whose reference
+// does not resolve:
+//
+//   in-scope       the claim matches WITHIN ONE acceptance bullet of the plan -> fold here.
+//   new-invariant  the claim matches NO acceptance bullet AND one OPEN queue row carries the claim in
+//                  its invariant field and all five fields (invariant, origin as file:line, narrow
+//                  fix, proof, residual exposure) with that exposure declared NOT live -> the narrow
+//                  fix ships now, only the generalization defers.
+//   blocking       no correct narrow fix exists -> the phase does not close; there is no queue arm.
+//
+// Markdown is read through the family's ONE block model (references/scripts/markdown-blocks.mjs, the
+// module the archivers already read through): fenced regions, ATX headings at 0-3 columns of indent,
+// CRLF and the backtick-info-string rule are ITS problem, not a second hand-rolled grammar here. A
+// document it refuses is a loud refusal, never a silent empty read.
+//
+// ADVISORY in this slice: nothing records that it ran, so a skipped or late call is
+// indistinguishable from a pre-edit declaration. A fingerprint-bound receipt a gate reads is next.
+//
+// Pure string functions - every input is text; the CLI half (fold-scope-cli.mjs) owns the fs.
+// Dependency-free, Node >= 22.
+
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+
+export const CLASSES = ['in-scope', 'new-invariant', 'blocking'];
+export const ROW_FIELDS = ['invariant', 'origin', 'narrow fix', 'proof', 'residual exposure'];
+export const ACCEPTANCE_HEADING = '## Verification';
+// The canon says a deferral row carries "the origin `file:line`". Anchored at the start of the value
+// and a POSITIVE line number, so "file.mjs:12junk" and "file.mjs:0" are not one; trailing context
+// after the token is fine, because the canon asks the row to CARRY a file:line, not to carry nothing
+// else.
+const ORIGIN_SHAPE = /^\S+:[1-9]\d*(\s|$)/;
+// A closed row is not a live deferral. Narrow on purpose: the row TITLE carrying one of these
+// literals refuses fail-closed; the general per-project status grammar is queued, not guessed here.
+const CLOSED_MARKERS = ['DONE', 'CLOSED'];
+const ORIGIN_MISSING = 'origin (the canon requires a file:line)';
+const BULLET = /^-\s+\S/;
+
+const normalize = (s) => String(s ?? '').replace(/\r/g, '').replace(/\s+/g, ' ').trim();
+const contains = (haystack, needle) => normalize(haystack).toLowerCase().includes(needle);
+
+// The ONE bullet scan both readers use, over the block model's lines. A fenced region is a quotation
+// AND a boundary: it closes the block it interrupts, so text past a fence can never join the bullet
+// before it (which would let a far-side literal satisfy a near-side claim). A `-` plus any whitespace
+// run opens a block; a blank or indented line continues it; any other unindented line closes it.
+// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them.
+const bulletBlocks = (lines, fencedLines, from, to) => {
+  const blocks = [];
+  let current = null;
+  const close = () => {
+    if (current) blocks.push(current);
+    current = null;
+  };
+  for (let index = from; index < to; index += 1) {
+    if (fencedLines.has(index)) {
+      close();
+      continue;
+    }
+    const line = lines[index];
+    if (BULLET.test(line)) {
+      close();
+      current = [line];
+    } else if (current && (line.trim() === '' || /^\s+\S/.test(line))) {
+      current.push(line);
+    } else {
+      close();
+    }
+  }
+  close();
+  return blocks;
+};
+
+// extractAcceptance(planText) -> the top-level bullets under `## Verification`, each collapsed to one
+// line. Per the planning canon those bullets ARE the acceptance criteria and they are the WHOLE list.
+// ONE heading recognizer decides both ends: the section opens on the block model's `## Verification`
+// heading and closes at the next heading of level 1 or 2, so a level-3 subheading stays INSIDE (which
+// is what "in this section" means) and a 4-space line, being an indented code block rather than a
+// heading, neither opens nor closes it. A Verification with no bullets declares NO criteria.
+export const extractAcceptance = (planText) => {
+  const { lines, headings, fencedLines } = tokenizeMarkdown(String(planText ?? ''), 'the plan');
+  const open = headings.find((heading) => heading.text.trim() === ACCEPTANCE_HEADING);
+  if (!open) return [];
+  const next = headings.find((heading) => heading.index > open.index && heading.level <= 2);
+  return bulletBlocks(lines, fencedLines, open.index + 1, next ? next.index : lines.length)
+    .map((block) => normalize(block.join('\n').replace(/^-\s+/, '')))
+    .filter(Boolean);
+};
+
+// ONE question per pattern: this one asks whether the line CARRIES a label, never whether the value
+// behind it is any good. Requiring a non-empty value here made an empty repeat invisible, so a row
+// could repeat a label and still be admitted; the value is judged downstream, where "" is missing.
+const FIELD_LINE = new RegExp(`^\\s*(?:[-*]\\s+)?(${ROW_FIELDS.map((f) => f.replace(' ', '\\s+')).join('|')})\\s*:\\s*(.*)$`, 'i');
+
+// The labelled fields of one row, folding CONTINUATION lines into the value they belong to (a wrapped
+// invariant read to its first line only would refuse a legitimate deferral). A REPEATED label is
+// recorded and REFUSED, never resolved by keeping the first value: a row saying "not live" and then
+// "live" would otherwise be accepted as not-live, which is the contradiction this fails closed on.
+const parseFields = (block) => {
+  const values = {};
+  let open = null;
+  for (const line of block.split('\n')) {
+    const match = line.match(FIELD_LINE);
+    if (match) {
+      open = match[1].toLowerCase().replace(/\s+/g, ' ');
+      values[open] = [...(values[open] ?? []), match[2].trim()];
+    } else if (open && /^\s+\S/.test(line) && !BULLET.test(line.trim())) {
+      values[open][values[open].length - 1] += ` ${line.trim()}`;
+    } else {
+      open = null;
+    }
+  }
+  const fields = {};
+  for (const label of ROW_FIELDS) fields[label] = values[label]?.[0] ?? null;
+  return { fields, values, duplicates: ROW_FIELDS.filter((label) => (values[label] ?? []).length > 1) };
+};
+
+// The disposition a residual exposure declares. Exactly TWO forms declare the negative: "not live"
+// and "not-live", each a standalone token on both sides — so "not--live", "not - live",
+// "not-live-ish" and "maybe-not-live" declare nothing. EVERY not-live span is removed before the
+// positive is looked for, malformed ones included: the `live` inside a botched negative is not a
+// declaration of the positive, and reading it as one would route the author to blocking over a row
+// that only needs re-wording. A standalone bare `live` then decides, and a row carrying both a
+// declared negative and a real positive is a contradiction that fails closed as live.
+const NEGATIVE_SPAN = /(?<![-\w])not[\s-]*live(?![-\w])/g;
+const DECLARED_NEGATIVE = /(?<![-\w])not(?:\s+|-)live(?![-\w])/;
+const LIVE_TOKEN = /(?<![-\w])live(?![-\w])/;
+const exposureOf = (value) => {
+  const text = String(value ?? '').toLowerCase();
+  const declaredNegative = DECLARED_NEGATIVE.test(text);
+  if (LIVE_TOKEN.test(text.replace(NEGATIVE_SPAN, ' '))) return 'live';
+  return declaredNegative ? 'not-live' : null;
+};
+
+const topLevelRows = (queueText) => {
+  const { lines, fencedLines } = tokenizeMarkdown(String(queueText ?? ''), 'the queue');
+  return bulletBlocks(lines, fencedLines, 0, lines.length).map((block) => block.join('\n'));
+};
+
+const EMPTY_ROW = () => ({ found: false, matches: 0, fields: {}, missing: [...ROW_FIELDS], duplicates: [], exposure: null, closed: null, claimInInvariant: false });
+
+// findDebtRow(queueText, claim) -> the ONE queue row FOR this invariant, its fields and its
+// disposition. Discovery prefers the row whose INVARIANT field carries the claim; the whole-block
+// match is only the fallback, and it exists so a row that carries the claim but no invariant field is
+// still FOUND and its missing field can be named. Zero and several matches are both "not found" with
+// the count: a deferral names ONE row, and guessing which is the unresolved reference this refuses.
+export const findDebtRow = (queueText, claim) => {
+  const needle = normalize(claim).toLowerCase();
+  if (!needle) return EMPTY_ROW();
+  const rows = topLevelRows(queueText).map((block) => ({ block, ...parseFields(block) }));
+  // EVERY recorded value of `invariant` is a candidate key, not just the first: a claim sitting in a
+  // repeated label would otherwise be invisible here and resolve to some OTHER row.
+  const owns = (r) => (r.values.invariant ?? []).some((v) => contains(v, needle));
+  const byInvariant = rows.filter(owns);
+  const hits = byInvariant.length ? byInvariant : rows.filter((r) => contains(r.block, needle));
+  // A candidate that repeats a label cannot be reasoned about at all, so the refusal comes BEFORE the
+  // row is resolved — ahead of the ambiguity count and ahead of every field judgement.
+  const broken = [...new Set(hits.flatMap((r) => r.duplicates))];
+  if (broken.length) return { ...EMPTY_ROW(), matches: hits.length, duplicates: broken };
+  if (hits.length !== 1) return { ...EMPTY_ROW(), matches: hits.length };
+  const { block, fields, duplicates } = hits[0];
+  const missing = ROW_FIELDS.filter((label) => !fields[label]);
+  if (fields.origin && !ORIGIN_SHAPE.test(fields.origin)) missing.push(ORIGIN_MISSING);
+  return {
+    found: true,
+    matches: 1,
+    block,
+    fields,
+    missing,
+    duplicates,
+    exposure: exposureOf(fields['residual exposure']),
+    closed: CLOSED_MARKERS.find((marker) => block.split('\n')[0].includes(marker)) ?? null,
+    claimInInvariant: owns(hits[0]),
+  };
+};
+
+const verdict = (kind, code, exit, claim, lines) => ({
+  verdict: kind,
+  code,
+  exit,
+  lines: [`fold-scope: ${kind} ${code}${claim ? ` — "${claim}"` : ''}`, ...lines],
+});
+const accept = (code, claim, lines) => verdict('ACCEPT', code, 0, claim, lines);
+const refuse = (code, claim, lines, exit = 1) => verdict('REFUSE', code, exit, claim, lines);
+
+const FIVE_FIELDS = ROW_FIELDS.join(', ');
+
+// A document read is the ONE place a throw is expected: the block model REFUSES an unclosed fence and
+// an ambiguous leading `---` rather than guessing, and its message names the file and line.
+const read = (fn) => {
+  try {
+    return { value: fn() };
+  } catch (err) {
+    return { error: (err && err.message) || String(err) };
+  }
+};
+const unreadable = (claim, message) => refuse('document-unreadable', claim, [
+  `  ${message}`,
+  '  a document that cannot be read as markdown is never guessed around — fix it, then re-run.',
+], 2);
+
+// decideFoldScope({ cls, claim, planText, queueText }) -> { verdict, code, exit, lines }.
+// Exit 0 for every ACCEPT, 1 for every matrix REFUSE, 2 for a refusal about the ARGUMENTS themselves
+// (an unknown or absent class, an absent claim, an unreadable document) - the CLI prints the lines
+// and returns the code.
+export const decideFoldScope = ({ cls, claim, planText, queueText } = {}) => {
+  const claimText = normalize(claim);
+  if (!CLASSES.includes(cls)) {
+    return refuse('class-unknown', typeof cls === 'string' ? cls : '', [
+      `  --class must be one of: ${CLASSES.join(', ')} — there is no default arm.`,
+      '  name the invariant the fix would enforce, then say where it already lives.',
+    ], 2);
+  }
+  if (!claimText) {
+    return refuse('claim-absent', '', [
+      '  --claim carries the invariant the fix would enforce, as a literal.',
+      '  a finding with no named invariant has no scope to decide.',
+    ], 2);
+  }
+  if (cls === 'blocking') {
+    return accept('blocking', claimText, [
+      '  no correct narrow fix exists, so the phase does not close.',
+      '  there is no deferral arm here: fix it in this phase, or the phase stays open.',
+    ]);
+  }
+  const criteria = read(() => extractAcceptance(planText));
+  if (criteria.error) return unreadable(claimText, criteria.error);
+  const acceptance = criteria.value;
+  const needle = claimText.toLowerCase();
+  const matched = acceptance.find((bullet) => contains(bullet, needle)) ?? null;
+  if (cls === 'in-scope') {
+    return matched
+      ? accept('in-scope', claimText, [
+          `  matched acceptance bullet: ${matched}`,
+          '  fold here: the invariant is already required by this plan. Fold the finding as a red->green test and re-review.',
+        ])
+      : refuse('in-scope-unmatched', claimText, [
+          `  no acceptance bullet of the plan carries this literal (${acceptance.length} bullet(s) read).`,
+          '  the lane: ship the NARROW fix for the found site (red first, then green); the generalization defers only as',
+          `  --class new-invariant, once a queue row carries ${FIVE_FIELDS}. With no correct narrow fix, --class blocking.`,
+        ]);
+  }
+  if (matched) {
+    return refuse('new-invariant-already-accepted', claimText, [
+      `  the invariant IS an acceptance bullet: ${matched}`,
+      '  route to the fold arm: --class in-scope. Already-required work is never a deferral.',
+    ]);
+  }
+  const found = read(() => findDebtRow(queueText, claimText));
+  if (found.error) return unreadable(claimText, found.error);
+  const row = found.value;
+  if (row.duplicates.length) {
+    return refuse('new-invariant-row-duplicate-field', claimText, [
+      `  a candidate queue row declares more than once: ${row.duplicates.join(', ')}.`,
+      '  a repeated label is not resolved by keeping the first value — a row that says both "not live"',
+      '  and "live" declares a contradiction, and a claim hidden in a repeat would resolve to another row.',
+      '  Delete the duplicate so the row states ONE value per field.',
+    ]);
+  }
+  if (row.matches > 1) {
+    return refuse('new-invariant-row-ambiguous', claimText, [
+      `  ${row.matches} queue rows carry this literal — a deferral names ONE row.`,
+      '  narrow the claim to the invariant statement of the row you mean.',
+    ]);
+  }
+  if (!row.found) {
+    return refuse('new-invariant-row-absent', claimText, [
+      '  no queue row carries this literal.',
+      `  a deferral owes a row carrying all five fields: ${FIVE_FIELDS}, that exposure declared NOT live.`,
+      '  if the exposure IS live, this is not a deferral at all — it is --class blocking.',
+    ]);
+  }
+  if (row.closed) {
+    return refuse('new-invariant-row-closed', claimText, [
+      `  the queue row title carries "${row.closed}" — a closed row is not a live deferral.`,
+      '  re-open that row, or write a new one for the invariant this finding names.',
+    ]);
+  }
+  if (row.missing.length) {
+    return refuse('new-invariant-row-incomplete', claimText, [
+      `  the queue row is missing: ${row.missing.join(', ')}.`,
+      '  a row short of a field is a note, not a deferral — write the field, then re-run.',
+    ]);
+  }
+  if (!row.claimInInvariant) {
+    return refuse('new-invariant-claim-not-invariant', claimText, [
+      `  the row carries this literal, but NOT in its invariant field: ${row.fields.invariant}`,
+      '  a deferral is keyed on the invariant the row states — quote that, or write the row this finding needs.',
+    ]);
+  }
+  if (row.exposure === 'live') {
+    return refuse('new-invariant-exposure-live', claimText, [
+      `  the residual exposure is declared LIVE: ${row.fields['residual exposure']}`,
+      '  a live defect in shipped behaviour is never deferred — route to --class blocking.',
+    ]);
+  }
+  if (row.exposure === null) {
+    return refuse('new-invariant-exposure-undeclared', claimText, [
+      `  the residual exposure declares neither "live" nor "not live": ${row.fields['residual exposure']}`,
+      '  silence is not a declaration — state the disposition in the row.',
+    ]);
+  }
+  return accept('new-invariant', claimText, [
+    `  the queue row carries all five fields and declares its residual exposure NOT live: ${row.fields.origin}`,
+    '  the narrow fix ships in this phase; ONLY the generalization defers.',
+  ]);
+};

package/tools/procedures.mjs

@@ -31,6 +31,9 @@ import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from '.
 // The plan-in-flight detector (AD-038) — imported from the plan-files.mjs LEAF (read-only fs by
 // construction); the WRITER-capable grounding.mjs is only NAMED in rendered text, never imported.
 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';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
 // is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
 // (orchestration-write.mjs) DIRECTLY — the import-split test pins the direct-import rule.
@@ -298,6 +301,24 @@ const autonomyAdvice = (activity, facts) => {
   ];
 };
 
+// The finding-scope block (procedures.md plan-execution step 5) — plan-execution ONLY and
+// UNCONDITIONAL: the rule routes EVERY finding, review-backed or not, so gating it on REVIEW_RECIPES
+// (which gates only the loop economics above) would hide it from every Solo project. The canon
+// section is printed VERBATIM above, so this block never re-states the rule — it carries only what
+// the canon cannot: the POPULATED checker command, and which of the two registers `--queue` names.
+export const FOLD_SCOPE_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'fold-scope-cli.mjs');
+const foldScopeAdvice = (activity, config, plans) => {
+  if (activity !== 'plan-execution') return [];
+  const declared = config?.flow?.debtQueue ?? null;
+  const queue = declared ?? `${PLANS_REL}/queue.md`;
+  const plan = plans.length === 1 ? `${PLANS_REL}/${plans[0]}` : '<plan-file>';
+  return [
+    'Finding scope (procedures.md plan-execution step 5) — the rule is the section above; this is the checker it names:',
+    `  • node ${shellQuoteArg(FOLD_SCOPE_TOOL)} --class '<in-scope|new-invariant|blocking>' --claim '<the invariant>' --plan ${shellQuoteArg(plan)} --queue ${shellQuoteArg(queue)}`,
+    `  • --queue is ${declared ? `${declared}, the declared flow.debtQueue` : `${queue}, the planning lifecycle queue (no flow.debtQueue is declared)`}. Advisory: nothing records that it ran, so a skipped or late call is indistinguishable from a pre-edit declaration.`,
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -445,7 +466,7 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => {
   const lines = [
     section,
     '',
@@ -464,6 +485,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if (grounding.length) lines.push('', ...grounding);
   const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
+  if (foldScope.length) lines.push('', ...foldScope);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -473,7 +495,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -486,6 +508,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
   costLanes: costLanesAdvice(),
+  // ADDITIVE (the fold channel): the finding-scope block, structured (empty outside plan-execution).
+  foldScope,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
   // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
@@ -574,9 +598,10 @@ export const main = (argv, ctx = {}) => {
     const flowProbe = ctx.flowProbe ?? defaultFlowProbe;
     const flowHalves = config?.flow == null ? null : flowHalvesAdvice(config.flow, flowProbe(cwd));
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
+    const foldScope = foldScopeAdvice(activity, config, plans);
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, declaredPractice, foldScope });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }