@dzhechkov/harness-core 0.4.2 → 0.4.4

package/src/backlog.ts

@@ -91,6 +91,9 @@ export type DedupAction = 'duplicate' | 'related' | 'new';
 /** Pure output of the classifier (04) — consumed by capture. */
 export interface DedupVerdict {
   readonly action: DedupAction;
+  /** Ids excluded from VECTOR candidacy because their text was edited without a re-embed yet. A
+   * consumer must read this before treating a `new` verdict as "compared against everything". */
+  readonly staleExcluded?: string[];
   /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
   readonly cosine: number;
   readonly matchedId: string | undefined;
@@ -593,6 +596,160 @@ export function transitionIdeas(
   return { ok: true, dryRun, changes, errors: [], written: true };
 }
 
+/* ── Edit a captured idea's TEXT (idea 1fde7bf6) ─────────────────────────────────────────────
+ *
+ * Why this verb exists at all: editing the store by hand does NOT re-embed the record, so its dedup
+ * vector keeps describing the OLD text and later duplicate checks run against something the record
+ * no longer says. The verb owns the text change; the CALLER owns the re-embed (it is async and needs
+ * the vector tier). Between the two, the record carries `embedStale` — see ADR-001: the guard against
+ * a stale vector lives where the HARM would be (the dedup verdict), not where the failure happened.
+ * ────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Where an edit's PREVIOUS text is preserved. An edit destroys text and `reopen` cannot undo it the
+ * way it undoes `drop`, so the old text is appended here before the store is rewritten. */
+export function editsLogPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'backlog', 'edits.jsonl');
+}
+
+export interface EditReport {
+  readonly ok: boolean;
+  readonly dryRun: boolean;
+  readonly id?: string;
+  readonly previousText?: string;
+  readonly newText?: string;
+  readonly errors: string[];
+  readonly written: boolean;
+}
+
+/**
+ * Replace or extend ONE idea's text. Mirrors `transitionIdeas`' line discipline exactly: the file is
+ * split without discarding anything, every untouched line — including a line the parser cannot read —
+ * goes back BYTE-FOR-BYTE, and only the matched record's line is re-serialised. The store holds
+ * dozens of records; a whole-file JSON round-trip would reformat all of them to change one.
+ */
+export function editIdea(
+  projectRoot: string,
+  prefix: string,
+  opts: { text?: string; append?: string; dryRun?: boolean; nowIso?: string } = {},
+): EditReport {
+  const dryRun = opts.dryRun === true;
+  const hasText = typeof opts.text === 'string' && opts.text !== '';
+  const hasAppend = typeof opts.append === 'string' && opts.append !== '';
+  if (hasText && hasAppend) {
+    return { ok: false, dryRun, errors: ['--text and --append are mutually exclusive — pick one'], written: false };
+  }
+  if (!hasText && !hasAppend) {
+    return { ok: false, dryRun, errors: ['nothing to do: give --text "<new text>" or --append "<more text>"'], written: false };
+  }
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) {
+    return { ok: false, dryRun, errors: ['no backlog store — nothing captured yet (dz backlog add "<idea>")'], written: false };
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (e) {
+    return { ok: false, dryRun, errors: [`cannot read ${path}: ${(e as Error).message}`], written: false };
+  }
+
+  // Same line discipline as transitionIdeas: nothing is discarded, corrupt lines are left alone.
+  const lines = raw.split('\n');
+  const parsed: { index: number; obj: Record<string, unknown>; id: string }[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (typeof obj.id === 'string' && obj.id !== '') parsed.push({ index: i, obj, id: obj.id });
+    } catch {
+      /* corrupt line — left byte-for-byte as-is */
+    }
+  }
+
+  if (!isSafeId(prefix)) {
+    return { ok: false, dryRun, errors: [`refusing an unsafe idea id: ${JSON.stringify(prefix)}`], written: false };
+  }
+  const res = resolveIdPrefix(parsed.map((p) => p.id), prefix);
+  if (res.kind === 'not-found') {
+    return { ok: false, dryRun, errors: [`no idea matches ${prefix} — run dz backlog list to see the ids`], written: false };
+  }
+  if (res.kind === 'ambiguous') {
+    return { ok: false, dryRun, errors: [`ambiguous prefix ${prefix} — matches ${res.matches.join(', ')}; give more characters`], written: false };
+  }
+  const entries = parsed.filter((p) => p.id === res.id);
+  if (entries.length > 1) {
+    // Deciding on the first line while rewriting one is how the sibling verb grew its twin bug.
+    return { ok: false, dryRun, errors: [`${res.id} appears ${entries.length}× in the store (duplicate lines; resolve the duplicate by hand)`], written: false };
+  }
+  const entry = entries[0]!;
+  const previousText = typeof entry.obj.text === 'string' ? (entry.obj.text as string) : '';
+  const newText = hasText ? (opts.text as string) : `${previousText}${previousText === '' ? '' : ' '}${opts.append as string}`;
+  if (newText === previousText) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+  if (dryRun) {
+    return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: false };
+  }
+
+  // Only `text` changes, plus the stale marker. Every other field is carried through untouched.
+  entry.obj.text = newText;
+  entry.obj.embedStale = true;
+  lines[entry.index] = JSON.stringify(entry.obj);
+
+  const nowIso = opts.nowIso ?? new Date().toISOString();
+  const logPath = editsLogPath(projectRoot);
+  try {
+    mkdirSync(join(projectRoot, '.dz', 'backlog'), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify({ id: res.id, previousText, newText, ts: nowIso })}\n`);
+  } catch (e) {
+    // The trail is the ONLY copy of the previous text. Refuse rather than destroy it untraceably.
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`edit log write failed, store left untouched: ${(e as Error).message}`], written: false };
+  }
+
+  const tmp = `${path}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* best-effort litter cleanup */ }
+    return { ok: false, dryRun, id: res.id, previousText, newText, errors: [`store write failed: ${(e as Error).message}`], written: false };
+  }
+  return { ok: true, dryRun, id: res.id, previousText, newText, errors: [], written: true };
+}
+
+/** Clear the stale marker after a successful re-embed. Separate from `editIdea` because the re-embed
+ * is async and belongs to the caller; a marker cleared without a re-embed would be a lie. */
+export function clearEmbedStale(projectRoot: string, id: string): boolean {
+  const path = ideasPath(projectRoot);
+  if (!existsSync(path)) return false;
+  let raw: string;
+  try { raw = readFileSync(path, 'utf-8'); } catch { return false; }
+  const lines = raw.split('\n');
+  let touched = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = (lines[i] ?? '').trim();
+    if (trimmed === '') continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      if (obj.id === id && obj.embedStale === true) {
+        delete obj.embedStale;
+        lines[i] = JSON.stringify(obj);
+        touched = true;
+      }
+    } catch { /* corrupt line — left alone */ }
+  }
+  if (!touched) return false;
+  const tmp = `${path}.tmp-clear-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join('\n'));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    try { unlinkSync(tmp); } catch { /* best-effort */ }
+    return false;
+  }
+}
+
 /* ── Store privacy (idea ec4cd60d): raw ideas are prompt-class PRIVATE content, like recall-usage.jsonl. ── */
 
 export type GitignoreAction = 'created' | 'appended' | 'already-covered' | 'user-opted-out' | 'skipped';
@@ -741,6 +898,11 @@ export interface DedupCandidate {
   readonly id: string;
   readonly cosine: number;
   readonly containment?: number;
+  /** Set when the record's text was edited but its vector has not been rewritten yet (ADR-001,
+   * idea 1fde7bf6). Such a candidate is excluded from VECTOR candidacy — its cosine describes text
+   * the record no longer has. The exact-text net still applies: the marker degrades SIMILARITY,
+   * never IDENTITY. */
+  readonly embedStale?: boolean;
 }
 
 /**
@@ -762,10 +924,18 @@ export function classifyDedup(
   // HIGH-4: a non-finite cosine (NaN/±Infinity) sorts unpredictably and can shove a real 0.97 duplicate
   // out of the top slot → misclassified NEW. Drop non-finite candidates BEFORE sorting/banding (the
   // recurring repo `Number.isFinite` lesson).
-  const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
+  // A record whose text was edited but whose vector has not been rewritten is EXCLUDED from vector
+  // candidacy — the same treatment a non-finite cosine gets, and for the same reason: the number does
+  // not describe the record. ADR-001: the guard sits where the HARM would be (this verdict, days after
+  // the edit) rather than where the failure happened (the edit's own output, which nobody re-reads).
+  const staleExcluded = candidates.filter((c) => c.embedStale === true).map((c) => c.id);
+  const sorted = candidates
+    .filter((c) => c.embedStale !== true)
+    .filter((c) => Number.isFinite(c.cosine))
+    .sort((a, b) => b.cosine - a.cosine);
   const top = sorted[0];
   const exactTextOnly = opts.exactTextOnly === true;
-  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly };
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly, staleExcluded };
   const bands = new Map(sorted.map((c) => [c.id, dedupPairBand(c.cosine, c.containment, cfg)]));
   if (bands.get(top.id) === 'duplicate') {
     return {
@@ -775,6 +945,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       ...(top.containment !== undefined ? { containment: top.containment } : {}),
     };
   }
@@ -794,6 +965,7 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: [],
       exactTextOnly,
+      staleExcluded,
       subsetMatch: true,
       ...(subset.containment !== undefined ? { containment: subset.containment } : {}),
       ...demoted,
@@ -810,11 +982,12 @@ export function classifyDedup(
       topMatchId: top.id,
       relatedIds: related.map((c) => c.id),
       exactTextOnly,
+      staleExcluded,
       ...topContainment,
       ...demoted,
     };
   }
-  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment };
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly, ...topContainment , staleExcluded };
 }
 
 /** Injectable deps so the production dedup path is testable without a live agentdb. */

package/src/index.ts

@@ -34,6 +34,7 @@ export * from './operations.js';
 export * from './workflows.js';
 // loop-designer (feature loop-designer): loop-plan/1 schema + generator + lint + trace planes.
 export * from './loop-plan.js';
+export * from './loop-plan-graph.js';
 export * from './loop-render.js';
 // loop-lint: EXPLICIT export list (QE round-2 G14) — `dominators`, the deliberately-WEAKER
 // analysis kept in src/loop-lint.ts solely as AM-1's mutation seam, is NOT part of the published
@@ -53,6 +54,7 @@ export {
   type LintOptions,
 } from './loop-lint.js';
 export * from './loop-trace.js';
+export * from './trace-bundle.js';
 export { BLOBS as LOOP_BLOBS, LOOP_BLOB_NAMES, BLOB_COVERAGE_MANIFEST } from './loop-blobs.generated.js';
 export type { LoopBlob } from './loop-blobs.generated.js';
 export * from './sign.js';
@@ -491,6 +493,7 @@ export * from './session-retro.js';
 export * from './feature-adr-setup.js';
 export * from './challenge-panel.js';
 export * from './routing-outcomes.js';
+export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';

package/src/loop-blobs.generated.ts

@@ -32,6 +32,7 @@ export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver",
  * tracked dz-backlog item, deliberately NOT claimed here. */
 export const BLOB_COVERAGE_MANIFEST: { coveredWorkflows: string[] } = {
   "coveredWorkflows": [
+    ".claude/workflows/cfr-pipeline.js",
     ".claude/workflows/feature-adr.js",
     ".claude/workflows/health-advisor.js",
     "packages/@dzhechkov/skills-feature-adr/templates/.claude/workflows/feature-adr.js"

package/src/loop-lint.ts

@@ -41,7 +41,7 @@ export interface LintRun {
   verdict: LintVerdict;
   mode: LintMode;
   findings: LintFinding[];
-  /** Per-rule verdict map (17 rules — every rule reports, none silently skipped). */
+  /** Per-rule verdict map (18 rules — every rule reports, none silently skipped). */
   rules: Record<string, LintSeverity>;
 }
 
@@ -62,6 +62,7 @@ export const LINT_RULES = [
   'pause-wired',
   'dispatch-by-deliverable',
   'no-agent-outside-runstep',
+  'tool-perimeter-declared',
   'size-budget',
 ] as const;
 export type LintRuleId = (typeof LINT_RULES)[number];
@@ -563,6 +564,58 @@ function ruleNoAgentOutsideRunstep(ctx: Ctx): LintFinding[] {
   return out;
 }
 
+/** The `<server>:<capability>` grammar a declared perimeter entry must match (ADR-002 §1). Two or
+ * more colon-separated lowercase segments — a bare `gitlab` names a server with no capability and
+ * is exactly the shape that reads as "everything on that server". */
+export const TOOL_PERIMETER_ENTRY_RE = /^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$/;
+
+/**
+ * `tool-perimeter-declared` (cfr-pipeline ADR-002) — every DISPATCHING step (`agent`|`gate`)
+ * declares its MCP tool perimeter, well-formed and without duplicates, and the rendered contract
+ * line agrees with the declared array.
+ *
+ * GENERIC by construction: it knows nothing about GitLab, Jira, Wiki or JSM — only that a
+ * dispatching step must SAY what it may touch. **Absence FLAGS: silence is never permission.**
+ * `tools: []` is the correct, meaningful declaration for a step that touches no external tool.
+ *
+ * SEVERITY IS STAGED (checkpoint amendment 2, overriding ADR-002 §Rationale-5's FAIL-everywhere
+ * stance): WARN by default, FAIL only under `--require-plan`. That keeps the published 0.4.x lint
+ * contract of harness-core/harness-cli non-breaking while still making the rule a hard gate
+ * exactly where cfr-pipeline runs it. Plan-less scripts report `inconclusive` (`no-plan-binding`)
+ * like every other plan-anchored rule — never a silent pass.
+ */
+function ruleToolPerimeterDeclared(ctx: Ctx): LintFinding[] {
+  if (ctx.projection === null) return noPlan('tool-perimeter-declared');
+  const sev: LintSeverity = ctx.mode === 'require-plan' ? 'fail' : 'warn';
+  const out: LintFinding[] = [];
+  for (const f of ctx.projection.facts) {
+    if (f.kind !== 'agent' && f.kind !== 'gate') continue;
+    if (f.tools === null) {
+      out.push({ rule: 'tool-perimeter-declared', severity: sev, message: `dispatching step ${f.id} declares no \`tools\` perimeter — absence FLAGS: silence is never permission (declare \`tools: []\` if the step touches no external tool)`, anchor: f.id });
+      continue;
+    }
+    const seen = new Set<string>();
+    for (const entry of f.tools) {
+      if (!TOOL_PERIMETER_ENTRY_RE.test(entry)) {
+        out.push({ rule: 'tool-perimeter-declared', severity: sev, message: `step ${f.id}: tool perimeter entry "${entry}" does not match <server>:<capability> (${String(TOOL_PERIMETER_ENTRY_RE)}) — a malformed entry cannot be matched against a real server inventory`, anchor: f.id });
+      }
+      if (seen.has(entry)) {
+        out.push({ rule: 'tool-perimeter-declared', severity: sev, message: `step ${f.id}: tool perimeter entry "${entry}" is declared twice — a duplicate hides a copy/paste of the wrong stage's perimeter`, anchor: f.id });
+      }
+      seen.add(entry);
+    }
+    // script cross-check: the rendered contract line must agree with the DECLARED array — a plan
+    // edit that never re-rendered would otherwise pass on the plan half alone.
+    if (f.tools.length > 0) {
+      const expected = 'declared MCP tool allowlist (plan tools): ' + f.tools.join(', ') + ' — use NOTHING outside it.';
+      if (!ctx.script.includes(expected)) {
+        out.push({ rule: 'tool-perimeter-declared', severity: sev, message: `step ${f.id}: the rendered script carries no contract line matching the declared perimeter [${f.tools.join(', ')}] — the script is stale against the plan, or the perimeter is decorative`, anchor: f.id });
+      }
+    }
+  }
+  return out;
+}
+
 function ruleSizeBudget(ctx: Ctx): LintFinding[] {
   const n = ctx.lines.length;
   if (n > SIZE_BUDGET_WARN_LINES) {
@@ -623,6 +676,7 @@ export function lint(scriptText: string, opts: LintOptions = {}): LintRun {
   run('pause-wired', () => rulePauseWired(ctx));
   run('dispatch-by-deliverable', () => ruleDispatchByDeliverable(ctx));
   run('no-agent-outside-runstep', () => ruleNoAgentOutsideRunstep(ctx));
+  run('tool-perimeter-declared', () => ruleToolPerimeterDeclared(ctx));
   run('size-budget', () => ruleSizeBudget(ctx));
 
   const severities = Object.values(rules);

package/src/loop-plan-graph.ts

@@ -0,0 +1,132 @@
+/**
+ * loop-plan-graph (idea d25a3c8a) — the COMPLETENESS leg of loop-plan/1's closed-world checking.
+ *
+ * What existed before this module (the round-7 cross-family reviewer's ONE not-met bar item,
+ * SIGNOFF's "B-not-A reason 1"): `KNOWN_KEYS === INJECT` and the honesty test's `SCANNED` roster
+ * all compare artifacts DOWNSTREAM of FIELD_DOMAINS — equality proves the rosters are consistent
+ * with each other, never that they are COMPLETE against the interface source. The reviewer's
+ * constructive counterexample: declare `LoopStep.extra?: ExtraPolicy`, add only the parent
+ * `{t:'record'}` domain entry, and `extra: { enabeld: true }` escapes every check while every
+ * equality guard stays green — "a new record kind cannot escape is unproven and demonstrably
+ * false" (verbatim). The shipped mitigation was a documented four-step extension discipline — a
+ * layer-4 instruction, exactly the layer the cost-of-detection ladder says such a check must not
+ * live on.
+ *
+ * THE FIX (this module, layer 1): walk the interface graph from `LoopPlan` in the SOURCE TEXT,
+ * transitively collect every reachable named interface, and let the honesty test require that the
+ * reachable set is exactly the wired set. An interface reachable from LoopPlan but absent from the
+ * wiring fails BY CONSTRUCTION, naming itself — no memory, no discipline, no fourth manual step.
+ *
+ * PURE: operates on source text handed in by the caller; no fs, no clock. That is what lets the
+ * acceptance test run the reviewer's counterexample against a SABOTAGED COPY of the source and
+ * require a red, while the real source stays green.
+ */
+
+/** One parsed field: its name and the DECLARED interface names its type text references. */
+export interface GraphField {
+  readonly field: string;
+  readonly refs: readonly string[];
+}
+
+/** interface name → its fields (index signatures like `[xKey: \`x-${string}\`]` are excluded:
+ * they open no named-interface edge and are the extension escape hatch by design). */
+export type InterfaceGraph = ReadonlyMap<string, readonly GraphField[]>;
+
+/** Brace-matched interface extraction. A regex-only scan truncates at the first nested brace
+ * (inline object fields are everywhere in this file), so bodies are cut by depth counting. */
+export function parseInterfaceGraph(source: string): InterfaceGraph {
+  const names = new Set<string>();
+  const headRe = /(?:^|\n)\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/g;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) names.add(m[1]!);
+
+  const graph = new Map<string, GraphField[]>();
+  headRe.lastIndex = 0;
+  for (let m = headRe.exec(source); m !== null; m = headRe.exec(source)) {
+    const name = m[1]!;
+    const open = source.indexOf('{', m.index + m[0].length);
+    if (open === -1) continue;
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < source.length; i += 1) {
+      const ch = source[i];
+      if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) { close = i; break; }
+      }
+    }
+    if (close === -1) continue;
+    const body = source.slice(open + 1, close);
+
+    // Split the body into top-level entries at depth 0 (`;` inside an inline `{...}` must not cut).
+    const entries: string[] = [];
+    let entry = '';
+    let d = 0;
+    for (const ch of body) {
+      if (ch === '{' || ch === '(' || ch === '<' || ch === '[') d += 1;
+      else if (ch === '}' || ch === ')' || ch === '>' || ch === ']') d -= 1;
+      if (ch === ';' && d === 0) { entries.push(entry); entry = ''; continue; }
+      entry += ch;
+    }
+    if (entry.trim() !== '') entries.push(entry);
+
+    const fields: GraphField[] = [];
+    for (const raw of entries) {
+      // strip comments, then match `readonly? name?: TYPE`
+      const text = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '').trim();
+      if (text === '' || text.startsWith('[')) continue; // index signature — by-design escape hatch
+      const fm = /^(?:readonly\s+)?([A-Za-z_$][\w$]*)\s*\??:\s*([\s\S]+)$/.exec(text);
+      if (fm === null) continue;
+      const typeText = fm[2]!;
+      const refs = new Set<string>();
+      const idRe = /[A-Za-z_$][\w$]*/g;
+      for (let im = idRe.exec(typeText); im !== null; im = idRe.exec(typeText)) {
+        if (names.has(im[0]) && im[0] !== name) refs.add(im[0]);
+      }
+      fields.push({ field: fm[1]!, refs: [...refs] });
+    }
+    graph.set(name, fields);
+  }
+  return graph;
+}
+
+/** Every interface reachable from `root` (inclusive), via any field's declared-interface refs —
+ * arrays, unions and nullables all count: `LoopStep[]`, `RetryProfile | null` open the same edge. */
+export function reachableInterfaces(graph: InterfaceGraph, root: string): string[] {
+  const seen = new Set<string>();
+  const queue = [root];
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    if (seen.has(name) || !graph.has(name)) continue;
+    seen.add(name);
+    for (const f of graph.get(name)!) for (const ref of f.refs) if (!seen.has(ref)) queue.push(ref);
+  }
+  return [...seen].sort();
+}
+
+export interface GraphWiringReport {
+  readonly ok: boolean;
+  /** Reachable from the root but NOT in the wired roster — each one is exactly the reviewer's
+   * counterexample: a record kind whose key space is open while every equality guard stays green. */
+  readonly unwired: string[];
+  readonly reachable: string[];
+  /** Wired but no longer reachable — a stale roster entry (the reverse rot). */
+  readonly stale: string[];
+}
+
+/** The completeness check the equality guards could not perform: reachable(source) vs wired. */
+export function checkGraphWiring(source: string, wired: readonly string[], root = 'LoopPlan'): GraphWiringReport {
+  const graph = parseInterfaceGraph(source);
+  const reachable = reachableInterfaces(graph, root);
+  const wiredSet = new Set(wired);
+  const reachableSet = new Set(reachable);
+  const unwired = reachable.filter((n) => !wiredSet.has(n));
+  // The wired roster (KNOWN_KEYS) legitimately mixes interface names with INLINE-record FIELD names
+  // (`artifacts`, `budget`, `checkpointing`, …) — those are the inlineSubFields machinery's
+  // business, not this check's. Staleness is judged only for entries that ARE declared interfaces
+  // in this source: a declared-but-unreachable interface in the roster is real rot; an inline field
+  // name is not an interface and must not be reported as one (caught on the first live run: five
+  // false stale entries, all inline fields).
+  const stale = [...wiredSet].filter((n) => graph.has(n) && !reachableSet.has(n)).sort();
+  return { ok: unwired.length === 0 && stale.length === 0, unwired, reachable, stale };
+}

package/src/loop-plan.ts

@@ -115,6 +115,20 @@ export interface LoopStep {
    * exec fingerprint in two review rounds; see roadmap. */
   checkpoint?: boolean;
   budget?: { maxAgents: number };
+  /**
+   * DECLARED MCP tool perimeter for this dispatching step (cfr-pipeline ADR-002).
+   *
+   * A `<server>:<capability>` allowlist (`^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$`, checked by the
+   * `tool-perimeter-declared` lint rule, not by the schema — the schema owns only the TYPE).
+   * ENACTED by `stepPromptAssembly`: a non-empty array renders a fixed contract line into the
+   * step's prompt, so the perimeter is COMMUNICATED to the agent rather than decorative. An empty
+   * array is meaningful and is the correct value for a step that touches no external tool.
+   *
+   * HONESTY, said once and never softened elsewhere: this is a DECLARATION, not enforcement.
+   * `agent()` exposes no tool restriction; real enforcement lives at the MCP server. No document
+   * may call this a sandbox.
+   */
+  tools?: string[];
   /** Dispatch route. v1 NARROWING (QE round 6): only 'inline' is enacted — 'codex-wrapper' and
    * 'codex-exec' are VALIDATED-AWAY (ENACT-DISPATCH). The fire-and-forget wrapper returns a stub
    * that reads as a clean result, and codex-exec had no live-proven enactment here; see roadmap. */
@@ -328,6 +342,7 @@ export const FIELD_DOMAINS: Record<string, FieldDomain> = {
   'LoopStep.cache': { t: 'record' },
   'LoopStep.checkpoint': { t: 'boolean' },
   'LoopStep.budget': { t: 'record' },
+  'LoopStep.tools': { t: 'string[]' },
   'LoopStep.dispatch': { t: 'enum', values: ['inline', 'codex-wrapper', 'codex-exec'] },
   'LoopStep.pauseState': { t: 'string' },
   'artifacts.reads': { t: 'string[]' },
@@ -389,22 +404,20 @@ export const FIELD_DOMAINS: Record<string, FieldDomain> = {
 // domain entry fails the honesty test; adding it WITH one makes it known here automatically. There
 // is exactly one roster, and it is the source's.
 //
-// WHAT THIS DOES AND DOES NOT PROVE (QE round-7, the cross-family reviewer's ONE not-met bar item,
-// CONCEDED). PROVEN, and tested: every record path CURRENTLY WIRED here is closed — no key of any
-// present-day spelling reaches the plan without a diagnostic, and the accepted roster is the
-// source's, not a second hand-list. NOT PROVEN, and it would be an overclaim to say otherwise: that
-// a record kind added in the FUTURE is closed AUTOMATICALLY. Three things remain hand-bounded —
-// (a) the honesty test's `SCANNED` names the interfaces it scans, (b) the fuzz's `INJECT` names the
-// injection sites, and (c) `checkKeys`' parser DESCENT names which nested records it walks. The
-// reviewer's constructive counterexample: declare `LoopStep.extra?: ExtraPolicy` with only a
-// `LoopStep.extra: {t:'record'}` domain entry and an `ExtraPolicy { enabled?: boolean }` interface —
-// unless someone ALSO hand-adds ExtraPolicy's own domains, the descent, `SCANNED` and `INJECT`, then
-// `extra: { enabeld: true }` escapes closed-world checking WHILE the equality assertions stay green.
-// That is a future-extension / proof-maintenance hole, not an input bypass that works today.
+// WHAT THIS PROVES (updated 2026-08-17, idea d25a3c8a — the round-7 not-met bar item is now MET).
+// PROVEN, and tested: every record path wired here is closed, the accepted roster is the source's,
+// AND the roster is COMPLETE against the interface graph: `loop-plan-graph.ts` walks the interfaces
+// reachable from LoopPlan in this file's SOURCE and the honesty test requires reachable == wired ==
+// SCANNED. The reviewer's constructive counterexample (`LoopStep.extra?: ExtraPolicy` with a
+// parent-only domain entry) is the ACCEPTANCE TEST: it goes red naming ExtraPolicy, by
+// construction, before any hand step. Still out of scope, said plainly: interfaces referenced only
+// through type ALIASES are followed one identifier deep (the graph collects declared-interface
+// names from the field's type text); an alias chain that hides an interface behind a non-interface
+// alias would need the alias declared in this file to be walked.
 //
-// EXTENSION DISCIPLINE (the manual step the derivation does not perform for you). When you add a
-// NEW nested record-typed field, do ALL FOUR in the same change, or the key space it opens is not
-// closed: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
+// EXTENSION CONVENIENCE (no longer load-bearing — the graph-completeness test reddens on a missed
+// step by construction; this list just tells you what the red means). When you add a NEW nested
+// record-typed field: 1) add `<NewIface>.<field>` entries to FIELD_DOMAINS for every field of the new interface
 // (not just the `{t:'record'}` entry on its PARENT); 2) add the new interface to the honesty test's
 // `SCANNED`; 3) add an `INJECT` site for it in the closed-world fuzz; 4) descend into it in
 // `checkKeys`. A structural fix that derives 2–4 from the interface graph — so a new record kind is
@@ -537,6 +550,9 @@ export const STEP_FIELD_KINDS: Record<string, readonly StepKind[]> = {
   budget: ALL_KINDS, // budget is an ACCOUNTING weight — summed into the rendered budget guard for every kind
   prompt: DISPATCHING_KINDS,
   artifacts: DISPATCHING_KINDS,
+  // the perimeter rides the PROMPT, so it enacts exactly where a prompt is dispatched — `tools`
+  // on a fanout/join/pause step would be an unperformed promise (KIND-1 rejects it).
+  tools: DISPATCHING_KINDS,
   model: DISPATCHING_KINDS,
   deliverable: DISPATCHING_KINDS,
   idempotent: DISPATCHING_KINDS,
@@ -1277,6 +1293,9 @@ export interface LintProjection {
     dispatch: DispatchRoute;
     cacheable: boolean;
     writes: string[];
+    /** DECLARED tool perimeter, or `null` when the step declares none (ADR-002: absence FLAGS —
+     * silence is never permission, so `null` and `[]` must stay distinguishable here). */
+    tools: string[] | null;
   }[];
   pauses: { state: string; resumeArg: string }[];
   checkpointingEnabled: boolean;
@@ -1347,6 +1366,7 @@ export function toLintProjection(plan: LoopPlan): LintProjection {
       dispatch: s.dispatch ?? 'inline',
       cacheable: s.cacheable === true,
       writes: s.artifacts?.writes ?? [],
+      tools: Array.isArray(s.tools) ? [...s.tools] : null,
     };
   });
 

package/src/loop-render.ts

@@ -199,6 +199,14 @@ function stepPromptAssembly(s: LoopStep, plan: LoopPlan): string[] {
     const fileNote = (s.deliverable ?? 'return-value') === 'file' ? '; your deliverable is the written file(s), not your reply' : '';
     lines.push(`  ${jsString('declared outputs (plan artifacts.writes): ' + writes.join(', ') + ' — write them' + fileNote + '. The loop verifies they land.')},`);
   }
+  // ENACTS LoopStep.tools (cfr-pipeline ADR-002): the declared perimeter is COMMUNICATED to the
+  // agent in FIXED wording, so its presence is greppable by a layer-1 test. The second sentence is
+  // not decoration — it is the honesty clause the whole feature rests on: a declaration is not
+  // enforcement, and every environment this ships into today serves the tools as labeled stubs.
+  const tools = s.tools ?? [];
+  if (tools.length > 0) {
+    lines.push(`  ${jsString('declared MCP tool allowlist (plan tools): ' + tools.join(', ') + ' — use NOTHING outside it. In this environment every one of these is a labeled STUB, not a live integration; enforcement lives at the MCP server, not here.')},`);
+  }
   if (s.kind === 'gate') {
     lines.push(`  ${jsString('GATE PROTOCOL (kind: ' + (gateCfg?.kind ?? 'gate') + '): end your reply with exactly one line "GATE: PASS" or "GATE: FAIL" — the loop PARSES this verdict and never synthesizes one.')},`);
   }