@sabaiway/agent-workflow-kit 5.5.0 → 5.7.0

package/tools/ensure-ops.mjs

@@ -0,0 +1,284 @@
+// ensure-ops.mjs — the FOUR upgrade ensure operations, one function each, behind one shared outcome
+// shape. The CLI that orders and runs them is ensure-configs.mjs; this module owns what each ensure
+// DOES and, more importantly, what it is allowed to CLAIM.
+//
+// Why they became code at all: `references/modes/upgrade.md` prescribed each of them as prose an agent
+// was expected to carry out by hand ("create it from the template if missing", "copy the pair from
+// references/scripts/ if missing"). A prescribed state-changing operation with no runnable command is
+// a step that silently varies per session — the feedback item this phase answers.
+//
+// The invariants every op holds (they are what the tests pin):
+//   • CREATE-ONLY seeds. A seed never clobbers: the write is the link-based create-only arm of
+//     atomic-write.mjs, so a file that appears between the probe and the write survives byte-for-byte
+//     and the op says `already-present` rather than reporting a write it did not do.
+//   • The DECISION lives where it already lived. The orchestration `_README` refresh asks
+//     orchestration-config.mjs (refreshReadme / the known-prior canonical set) and writes through
+//     orchestration-write.mjs — the file's one writer. Nothing here re-derives either.
+//   • Every token names a state this run PROVED. `already-present` follows a probe; `skipped-no-node`
+//     names the missing package.json; an ADR-layout read that fails is `adr-layout-unverifiable` and
+//     writes NOTHING (the STRICT survey, fail-closed — the lenient status wrapper reads an unreadable
+//     tree as `none`, which here would mean seeding a rotator beside a store nobody could inspect).
+//   • A failed op is a non-zero signal, never a line that reads like success.
+//
+// Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { CANON_README, CONFIG_REL, SEED_CONFIG, loadConfig, normalizeCanonical, refreshReadme } from './orchestration-config.mjs';
+import { seedConfig, writeConfig } from './orchestration-write.mjs';
+import { lstatNoFollow, writeDocsAiFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
+import { GATES_REL } from './gates-declaration.mjs';
+import { AUTONOMY_REL } from './autonomy-config.mjs';
+import { surveyAdrLayoutStrict } from './family-registry.mjs';
+import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
+
+// The closed vocabulary lives in its own PURE leaf so the read-only doc-parity lint can bind the
+// relayed token set without importing this module's writer graph. Re-exported here because every
+// consumer of the ops also speaks the vocabulary.
+export {
+  ENSURE_OPS,
+  ENSURE_TOKENS,
+  DRY_RUN_TOKENS,
+  FAILURE_CAUSES,
+  RELAYED_ENSURE_TOKENS,
+  SEED_SCRIPTS,
+  WRITE_TOKENS,
+} from './ensure-vocabulary.mjs';
+
+const PACKAGE_JSON = 'package.json';
+const SCRIPTS_DIR = 'scripts';
+
+const outcome = (op, token, lines, failed = false) => {
+  if (!ENSURE_TOKENS.includes(token)) {
+    throw new Error(`[agent-workflow-kit] unknown ensure outcome "${token}" — the token vocabulary is closed`);
+  }
+  return { op, token, failed, lines };
+};
+const ok = (op, token, ...lines) => outcome(op, token, lines, false);
+// A LOUD failure the doc gives its OWN token (today: malformed-preserved — the file is preserved, and
+// that is exactly what the reader must be told).
+const loudToken = (op, token, ...lines) => outcome(op, token, lines, true);
+// Every other LOUD failure: the token is always `failed`, the closed cause word opens the first line.
+const loud = (op, cause, ...lines) => {
+  if (!FAILURE_CAUSES.includes(cause)) {
+    throw new Error(`[agent-workflow-kit] unknown ensure failure cause "${cause}" — the cause vocabulary is closed`);
+  }
+  return outcome(op, 'failed', [`${cause} — ${lines[0]}`, ...lines.slice(1)], true);
+};
+
+// The closed-vocabulary DOOR, exported as a seam so the refusal itself is testable: EVERY outcome in
+// this module is composed through one of these two, and a word outside the closed sets throws here
+// instead of reaching a caller that has no idea how to relay it.
+export const composeOutcome = outcome;
+export const composeFailure = loud;
+
+const causeOf = (err) => String((err && err.message) || err);
+
+// The CLI's catch-all, here rather than there so EVERY outcome in the system — including the one
+// nobody planned for — is composed through the closed vocabulary. A throw that reached here is
+// `unexpected-error`: the cause word is still one of the closed set, and the thrown message follows
+// it (a bare `${op}: …` line would be the one failure in the system that names no cause).
+export const failedOutcome = (op, err) => loud(op, 'unexpected-error', `${op}: ${causeOf(err)}`);
+
+// `already-present` must mean a FILE is there. An lstat that merely finds SOMETHING would let a
+// directory or a symlink named gates.json report a green ensure while the declaration the project
+// needs does not exist — an exit 0 proving nothing (both review backends found this).
+const NODE_KIND = (st) => (st.isSymbolicLink() ? 'a symlink' : st.isDirectory() ? 'a directory' : 'not a regular file');
+const probeSeedTarget = (abs, lstat) => {
+  const st = lstatNoFollow(abs, lstat);
+  if (st === null) return { present: false };
+  return st.isFile() ? { present: true } : { present: true, wrongKind: NODE_KIND(st) };
+};
+
+// A leftover temp file never fails a completed write, and is never silent either.
+const tmpNote = (rel, tmpLeftBehind) =>
+  (tmpLeftBehind ? [`${rel}: the write stands, but its temp file could not be removed — delete it by hand: ${tmpLeftBehind}`] : []);
+
+// ── 1. orchestration.json — seed, or refresh ONLY a still-canonical onboarding note ────────────────
+
+// Which no-change outcome is it? refreshReadme returns `changed: false` for two very different trees:
+// a note that already IS the current canonical, and a note the user rewrote. Reporting both as
+// "already current" would claim the second is something it is not.
+const unchangedNoteToken = (config) =>
+  normalizeCanonical(config?._README ?? '') === normalizeCanonical(CANON_README) ? 'already-current' : 'customized-preserved';
+
+const applyNoteRefresh = (cwd, config, dryRun, deps) => {
+  const { config: next, changed } = refreshReadme(config);
+  if (!changed) {
+    const token = unchangedNoteToken(config);
+    return ok(
+      'orchestration',
+      token,
+      token === 'already-current'
+        ? `${CONFIG_REL}: the onboarding note is the current canonical — nothing written`
+        : `${CONFIG_REL}: the onboarding note carries your own wording — preserved verbatim, nothing written`,
+    );
+  }
+  if (dryRun) return ok('orchestration', 'would-refresh-note', `${CONFIG_REL}: the onboarding note matches a previous canonical and would be refreshed (every recipe you set is kept)`);
+  writeConfig(cwd, next, deps);
+  return ok('orchestration', 'note-refreshed', `${CONFIG_REL}: the onboarding note was refreshed to the current canonical (every recipe you set is kept)`);
+};
+
+// A load failure is not automatically "malformed": a file that VANISHED between the reader's own
+// lstat and its read surfaces as unreadable, and calling that preserved-and-malformed would state
+// two things this run did not observe. Probe once more and classify by what is there NOW.
+const loadFailureOutcome = (cwd, err, lstat, whenSeeding) => {
+  if (lstatNoFollow(join(cwd, CONFIG_REL), lstat) === null) {
+    return loud('orchestration', 'race-unresolved', `${CONFIG_REL}: could not be read and is not there now — something is creating and removing it underneath this run; nothing written, re-run when the tree is settled`);
+  }
+  const where = whenSeeding ? 'appeared while this run was seeding it, and ' : '';
+  return loudToken('orchestration', 'malformed-preserved', `${CONFIG_REL}: ${where}could not be read as the config it must be — preserved untouched, nothing written. ${causeOf(err)}`);
+};
+
+export const ensureOrchestration = ({ cwd, dryRun = false, deps = {} }) => {
+  const read = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  // The KIND comes before the content: a symlink pointing at valid JSON parses fine and would report
+  // `already-current` over a file this ensure would refuse to write through — an exit 0 that proves
+  // nothing about the config the project actually has.
+  const kind = probeSeedTarget(join(cwd, CONFIG_REL), lstat);
+  if (kind.wrongKind) {
+    return loud('orchestration', 'wrong-node-kind', `${CONFIG_REL}: exists but is ${kind.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
+  }
+  let loaded;
+  try {
+    loaded = loadConfig(cwd, read, lstat);
+  } catch (err) {
+    // Malformed / unreadable: preserved untouched, and LOUD — clobbering a file we cannot parse would
+    // destroy hand-authored configuration to fix a note.
+    return loadFailureOutcome(cwd, err, lstat, false);
+  }
+  if (loaded.config !== null) return applyNoteRefresh(cwd, loaded.config, dryRun, deps);
+  if (dryRun) return ok('orchestration', 'would-seed', `${CONFIG_REL}: absent — would be created from the canonical seed`);
+
+  const { created, tmpLeftBehind } = seedConfig(cwd, SEED_CONFIG, deps);
+  const seedNote = tmpNote(CONFIG_REL, tmpLeftBehind);
+  if (created) return ok('orchestration', 'seeded', `${CONFIG_REL}: created from the canonical seed`, ...seedNote);
+  // It appeared between the probe and the write. Nothing was overwritten; read it once more and
+  // report what it now IS, rather than a claim about the file we did not write.
+  let second;
+  try {
+    second = loadConfig(cwd, read, lstat);
+  } catch (err) {
+    return loadFailureOutcome(cwd, err, lstat, true);
+  }
+  if (second.config === null) {
+    return loud('orchestration', 'race-unresolved', `${CONFIG_REL}: something is creating and removing this file underneath this run — nothing written; re-run when the tree is settled`, ...seedNote);
+  }
+  const refreshed = applyNoteRefresh(cwd, second.config, dryRun, deps);
+  return { ...refreshed, lines: [...refreshed.lines, ...seedNote] };
+};
+
+// ── 2/3. gates.json + autonomy.json — seed-if-missing, existing file preserved byte-for-byte ───────
+
+const seedFromTemplate = ({ op, rel, template, noun, cwd, kitRoot, dryRun, deps }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+  const probe = probeSeedTarget(join(cwd, rel), lstat);
+  if (probe.wrongKind) {
+    return loud(op, 'wrong-node-kind', `${rel}: exists but is ${probe.wrongKind} — nothing was written, and this is NOT a usable declaration; resolve it by hand, then re-run`);
+  }
+  if (probe.present) return ok(op, 'already-present', `${rel}: already present — preserved byte-for-byte, nothing written`);
+  if (dryRun) return ok(op, 'would-seed', `${rel}: absent — would be created from the bundled template`);
+  let body;
+  try {
+    body = String(read(join(kitRoot, 'references', 'templates', template), 'utf8'));
+  } catch (err) {
+    return loud(op, 'template-unreadable', `${rel}: the bundled template could not be read, so nothing was written — reinstall the kit. ${causeOf(err)}`);
+  }
+  const { created, tmpLeftBehind } = writeDocsAiFileAtomic(cwd, rel, body, deps, { noun, createOnly: true });
+  return created
+    ? ok(op, 'seeded', `${rel}: created from the bundled template`, ...tmpNote(rel, tmpLeftBehind))
+    : ok(op, 'already-present', `${rel}: appeared while this run was seeding it — the existing file stands, byte-for-byte`, ...tmpNote(rel, tmpLeftBehind));
+};
+
+export const ensureGates = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
+  seedFromTemplate({ op: 'gates', rel: GATES_REL, template: 'gates.json', noun: 'a gate declaration', cwd, kitRoot, dryRun, deps });
+
+export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, deps = {} }) =>
+  seedFromTemplate({ op: 'autonomy', rel: AUTONOMY_REL, template: 'autonomy.json', noun: 'an autonomy policy', cwd, kitRoot, dryRun, deps });
+
+// ── 4. scripts/ — the ADR-cascade enforcement pairs, detect-first ──────────────────────────────────
+
+// A project with no package.json at its root is not where Node enforcement scripts belong. Stated,
+// never silent: the token names the evidence, and the three config ensures still run.
+const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
+
+const OLD_ADR_LAYOUTS = new Set(['old', 'old-unrotated']);
+
+// The scripts ensure copies file by file, so a failure PARTWAY leaves earlier copies in place. Saying
+// so is the difference between a failure the reader can act on and one they read as "nothing happened"
+// — the CLI's summary therefore claims nothing about writes, and this line states the truth per op.
+const partialNote = (lines) => {
+  const copied = lines.filter((line) => line.includes(': copied from the bundled scripts')).length;
+  return copied > 0 ? [`the copying stopped PARTWAY — the ${copied} file(s) named above were already copied and are NOT rolled back`] : [];
+};
+
+export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
+  if (!isNodeProject(cwd, lstat)) {
+    return ok('scripts', 'skipped-no-node', `${SCRIPTS_DIR}/: no ${PACKAGE_JSON} at the project root — the seeded pairs are Node enforcement; nothing written`);
+  }
+  let layout;
+  try {
+    layout = surveyAdrLayoutStrict(cwd, deps);
+  } catch (err) {
+    return loud('scripts', 'adr-layout-unverifiable', `${SCRIPTS_DIR}/: the ADR-store layout could not be read, so nothing was written — a rotator seeded beside an un-migrated store reds the ADR gate. ${causeOf(err)}`);
+  }
+  if (OLD_ADR_LAYOUTS.has(layout)) {
+    return ok(
+      'scripts',
+      'old-adr-layout-migration-instructed',
+      `${SCRIPTS_DIR}/: this project is still on the older ADR layout (${layout}) — nothing written. Run the opt-in /agent-workflow-kit migrate-adr-store (it previews, and never commits); the seed lands on the next upgrade.`,
+    );
+  }
+  const lines = [];
+  let anyCreated = false;
+  for (const name of SEED_SCRIPTS) {
+    const rel = `${SCRIPTS_DIR}/${name}`;
+    const probe = probeSeedTarget(join(cwd, SCRIPTS_DIR, name), lstat);
+    if (probe.wrongKind) {
+      return loud('scripts', 'wrong-node-kind', `${rel}: exists but is ${probe.wrongKind} — that is not the enforcement script this run places`, ...lines, ...partialNote(lines));
+    }
+    if (probe.present) {
+      lines.push(`${rel}: already present — preserved, never overwritten`);
+      continue;
+    }
+    if (dryRun) {
+      lines.push(`${rel}: absent — would be copied from the bundled scripts`);
+      continue;
+    }
+    let body;
+    try {
+      body = String(read(join(kitRoot, 'references', 'scripts', name), 'utf8'));
+    } catch (err) {
+      return loud('scripts', 'bundle-unreadable', `${rel}: the bundled script could not be read — reinstall the kit. ${causeOf(err)}`, ...lines, ...partialNote(lines));
+    }
+    // The WRITE is caught here, not by the CLI's catch-all: a throw that escapes this loop would take
+    // the accumulated lines with it, and the run would report a failure without saying which files it
+    // had already copied.
+    let result;
+    try {
+      result = writeProjectFileCreateOnly(cwd, rel, body, deps, { noun: 'a seeded enforcement script' });
+    } catch (err) {
+      return loud('scripts', 'write-refused', `${rel}: ${causeOf(err)}`, ...lines, ...partialNote(lines));
+    }
+    anyCreated = anyCreated || result.created;
+    lines.push(result.created ? `${rel}: copied from the bundled scripts` : `${rel}: appeared while this run was seeding it — the existing file stands`);
+    lines.push(...tmpNote(rel, result.tmpLeftBehind));
+  }
+  if (dryRun) {
+    const wouldSeed = lines.some((line) => line.includes('would be copied'));
+    return outcome('scripts', wouldSeed ? 'would-seed' : 'already-present', lines, false);
+  }
+  return outcome('scripts', anyCreated ? 'seeded' : 'already-present', lines, false);
+};
+
+// The op table the CLI walks — name → implementation, in ENSURE_OPS order.
+export const ENSURE_IMPLEMENTATIONS = Object.freeze({
+  orchestration: ensureOrchestration,
+  gates: ensureGates,
+  autonomy: ensureAutonomy,
+  scripts: ensureScripts,
+});

package/tools/ensure-vocabulary.mjs

@@ -0,0 +1,71 @@
+// ensure-vocabulary.mjs — the CLOSED vocabulary of the upgrade ensures: which operations exist, which
+// outcome tokens they may print, which cause words may open a failure line, and which of those the
+// mode doc teaches.
+//
+// It is a PURE LEAF (no imports at all) for one reason: the read-only doc-parity lint binds the
+// relayed token set into `references/modes/upgrade.md`, and reading a vocabulary must never drag the
+// ensure implementation — and through it the orchestration WRITER and the atomic-write core — into a
+// read-only tool's import graph. Vocabulary here, behaviour in ensure-ops.mjs.
+
+// The FIXED order the CLI runs them in — the order references/modes/upgrade.md already prescribed.
+export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', 'scripts']);
+
+// Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
+// walks this set), and each has exactly one `would-` counterpart below.
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note']);
+
+// The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
+// token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
+// of and the caller has no idea how to relay. EVERY operational failure prints the ONE token
+// `failed` and names its CAUSE at the head of its detail line — a specific token would read as
+// vocabulary the mode doc never taught (both review backends found exactly that).
+export const ENSURE_TOKENS = Object.freeze([
+  ...WRITE_TOKENS,
+  ...DRY_RUN_TOKENS,
+  'already-current',
+  'already-present',
+  'customized-preserved',
+  'malformed-preserved',
+  'skipped-no-node',
+  'old-adr-layout-migration-instructed',
+  'failed',
+]);
+
+// The closed CAUSE set — the word that opens a `failed` line. Closed for the same reason the tokens
+// are: the doc promises "a failed line names its cause", and this is that list. `unexpected-error`
+// is the honest cause for a throw nobody planned for: the failure is still named, never bare.
+export const FAILURE_CAUSES = Object.freeze([
+  'race-unresolved',
+  'template-unreadable',
+  'bundle-unreadable',
+  'adr-layout-unverifiable',
+  'wrong-node-kind',
+  'write-refused',
+  'unexpected-error',
+]);
+
+// The subset references/modes/upgrade.md enumerates, so the agent relaying an upgrade knows every
+// outcome by name. doc-parity binds each of these into that doc: a reworded doc that drops one fails
+// the check instead of silently teaching an outcome set the tool no longer has. The dry-run pair is
+// deliberately outside it — upgrade never runs the preview.
+export const RELAYED_ENSURE_TOKENS = Object.freeze([
+  'seeded',
+  'note-refreshed',
+  'already-current',
+  'customized-preserved',
+  'malformed-preserved',
+  'already-present',
+  'skipped-no-node',
+  'old-adr-layout-migration-instructed',
+  'failed',
+]);
+
+// The four files the enforcement-script ensure seeds (AD-051's ADR cascade + the tokenizer it needs).
+// Seed nothing else: the other tokenizer-era tests red beside an OLD archiver.
+export const SEED_SCRIPTS = Object.freeze([
+  'archive-decisions.mjs',
+  'archive-decisions.test.mjs',
+  'markdown-blocks.mjs',
+  'markdown-blocks.test.mjs',
+]);

package/tools/flow-check-cores.mjs

@@ -0,0 +1,253 @@
+// flow-check-cores.mjs — the checker's decision cores over the FULL read-results of BOTH stores
+// (flow + core evidence) and the tree context: store health, chain adoption and transition
+// legality, prior-terminal references, worktree scoping, bookkeeping-delta custody and
+// re-attestation, degrade-before-final ordering, armed base motion — and `decideFlowCheck`, the
+// ONE composition every consumer reads. Split out of flow-check.mjs (baseline-practices tranche 1);
+// the CLI, the store reads and the report render stay there.
+//
+// Pure: no store IO and no git of its own — the base-motion inputs arrive as INJECTED resolvers,
+// so flow-check-git-lane.mjs is never imported here. The evidence rungs live one module down
+// (flow-check-rungs.mjs), which also owns the refusal vocabulary both halves share.
+
+import {
+  CHAIN_KIND, validateChainSequence, validateSupersessions, canonicalFlowDigest,
+  authoritativeFlowRecords,
+} from './flow-record.mjs';
+import {
+  walkChainState, validateOpenerReference, resolveRecordReference, isAuthoritativeReferenceTarget,
+} from './flow-store.mjs';
+import {
+  short, shellQuote, writerCommand,
+  collectUnansweredRedRefusals, collectDegradeCoverageRefusals, collectReceiptCoverageRefusals,
+} from './flow-check-rungs.mjs';
+
+// The checker only refuses — park/resume/complete are explicit writer actions (#59). Printed
+// operand shapes: flag values ride the inline --flag='value' form and positionals follow a
+// literal ` -- ` — one shape for EVERY id, so a leading-dash operand stays recoverable.
+const parkRecovery = (planId) =>
+  `recovery (pasteable): ${writerCommand(`park -- ${shellQuote(planId)}`)}`;
+
+// Arms in dependency order; the first failing arm reports, and integrityClean gates the caller's
+// dependent arms (base motion) off a broken chain.
+const planRefusals = (records, chain, planId, owner, advisories) => {
+  if (chain[0].purpose !== 'adoption') {
+    return { integrityClean: false, refusals: [`plan "${planId}": the chain has no content-digest-bound adoption record — a chain starts at adoption binding the plan content digest (#58); the store is append-only, so inspect how this chain was written`] };
+  }
+  const seq = validateChainSequence(chain);
+  if (!seq.ok) return { integrityClean: false, refusals: [`plan "${planId}": illegal transition — ${seq.reason}`] };
+  const state = walkChainState(chain);
+  const referenceIssues = [];
+  for (const { record } of state.openers) {
+    const check = validateOpenerReference(records.slice(0, records.indexOf(record)), record);
+    if (!check.ok) referenceIssues.push(`plan "${planId}": step-opening round (step "${record.stepId}") — ${check.reason}`);
+  }
+  for (const r of chain) {
+    if (r.purpose !== 'refresh') continue;
+    const prefix = records.slice(0, records.indexOf(r));
+    if (resolveRecordReference(prefix, r.refreshedRecord) === undefined) {
+      referenceIssues.push(`plan "${planId}": a refresh's refreshedRecord does not match the store (no earlier record digests to ${short(r.refreshedRecord)}) — a re-attestation binds an existing record`);
+    } else if (!isAuthoritativeReferenceTarget(prefix, r.refreshedRecord)) {
+      referenceIssues.push(`plan "${planId}": a refresh's refreshedRecord targets a superseded record — a re-attestation binds the authoritative latest record of its key (as of the refresh's own raw position)`);
+    }
+  }
+  if (referenceIssues.length > 0) return { integrityClean: false, refusals: referenceIssues };
+  const open = !state.completed && !state.parked && state.mode === 'in-step';
+  if (!open) return { integrityClean: true, refusals: [] };
+  if (chain[0].owner !== owner) {
+    advisories.push(`plan "${planId}": an OPEN chain owned by "${chain[0].owner}" (a foreign worktree) — advisory visibility only, never this tree's refusal (#57)`);
+    return { integrityClean: true, refusals: [] };
+  }
+  return { integrityClean: true, refusals: [`plan "${planId}" has an OPEN chain owned by this worktree ("${owner}"): step "${state.stepId}" is not converged — a commit closes only at a terminal. ${parkRecovery(planId)}`] };
+};
+
+// The custody arm verifies the PERSISTED proof against a bare declaration (#60): the masked
+// recompute must equal fingerprintBefore, and every delta must be re-attested by a SUBSEQUENT
+// chain refresh binding {refreshedRecord, fingerprintBefore = the delta's fingerprintAfter} (#45)
+// — an earlier or fingerprint-mismatched record never satisfies (raw order decides). Satisfaction
+// is STORE-GLOBAL: the locked delta shape carries no chain field, so WHICH chain's refresh cap
+// the re-attestation consumes is the Plan-3 decideCheck arm (#61), not a Plan-2 refusal.
+// The recovery lane needs the invoker's OWN OPEN chains: a refresh is a within-step record, so
+// only such a chain can carry the re-attestation (and its refresh cap is what the mint consumes,
+// #61). A command under a "pasteable" label is always CONCRETE — with no own open chain the
+// recovery states the precondition instead of printing a placeholder command.
+const ownOpenChainPlanIds = (records, owner) =>
+  [...new Set(records.filter((r) => r.kind === CHAIN_KIND).map((r) => r.planId))].filter((planId) => {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === planId);
+    if (chain[0].owner !== owner || chain[0].purpose !== 'adoption' || !validateChainSequence(chain).ok) return false;
+    const state = walkChainState(chain);
+    return !state.completed && !state.parked && state.mode === 'in-step';
+  });
+
+// The ONE per-record custody predicate (Plan 4 Phase 3, round-2 fold): the confinement equality
+// + the mint-only invariants the record-level shape validation cannot see — shared by the
+// gate-time walk below and the writer's terminal move validation, so a forged proof can neither
+// pass the gates nor carry a terminal. → issue string | null.
+export const deltaCustodyIssue = (r) => {
+  if (r.custodyProof.maskedFingerprint !== r.fingerprintBefore) {
+    return `the persisted custody proof does not prove confinement (maskedFingerprint ${short(r.custodyProof.maskedFingerprint)} ≠ fingerprintBefore ${short(r.fingerprintBefore)}) — a bare or tampered declaration never passes; re-mint through mintBookkeepingDelta`;
+  }
+  const proof = r.custodyProof;
+  const mintInvariant = !proof.tracked ? null
+    : proof.preClass !== 'present' ? 'a tracked path with an absent pre-state never mints'
+    : proof.indexDigest === null ? 'a staged deletion (a HEAD entry without an index entry) never mints'
+    : proof.worktreeDigest !== proof.indexDigest ? 'the clean-at-path rule (pre-change worktree bytes = the index entry) never minted this'
+    : null;
+  return mintInvariant === null ? null : `the persisted custody proof violates a mint invariant — ${mintInvariant}; an unmintable proof never passes (fail closed)`;
+};
+
+const deltaRefusals = (records, owner) => {
+  const refusals = [];
+  const openPlanIds = ownOpenChainPlanIds(records, owner);
+  // The re-attestation OBLIGATION binds only AUTHORITATIVE deltas: a superseded same-key delta
+  // never enters classifyDeltaChain and the refresh preflight refuses to reference it, so
+  // demanding its refresh would be exactly the unrecoverable red the plan bans — supersession is
+  // the store's own recovery valve. Custody and mint checks stay RAW-wide (tamper detection).
+  const authoritative = new Set(authoritativeFlowRecords(records));
+  records.forEach((r, i) => {
+    if (r.kind !== 'bookkeeping-delta') return;
+    const custody = deltaCustodyIssue(r);
+    if (custody !== null) {
+      refusals.push(`bookkeeping-delta at ${r.path}: ${custody}`);
+      return;
+    }
+    if (!authoritative.has(r)) return;
+    const digest = canonicalFlowDigest(r);
+    const satisfied = records.some((s, j) => j > i && s.kind === CHAIN_KIND && s.purpose === 'refresh'
+      && s.refreshedRecord === digest && s.fingerprintBefore === r.fingerprintAfter);
+    if (!satisfied) {
+      const recovery = openPlanIds.length > 0
+        ? `recovery (pasteable; choose the chain whose refresh cap this consumes, #61): ${openPlanIds.map((planId) => writerCommand(`refresh --cause='bookkeeping delta re-attestation' --refreshed-record=${digest} -- ${shellQuote(planId)}`)).join('  OR  ')}`
+        : `recovery: no own OPEN chain can carry the re-attestation yet — open the owning plan's step round, then mint the refresh binding --refreshed-record=${digest}`;
+      refusals.push(`bookkeeping-delta at ${r.path}: no satisfying re-attestation — a SUBSEQUENT chain refresh must bind {refreshedRecord: ${short(digest)}, fingerprintBefore: ${short(r.fingerprintAfter)}}; an earlier or fingerprint-mismatched record never satisfies. ${recovery}`);
+    }
+  });
+  return refusals;
+};
+
+// Degrade-before-final (#64), decidable from RAW core-store order and grouped BY FINGERPRINT: a
+// degrade after a final-start at the same fingerprint refuses unless a LATER final-start at that
+// fingerprint completed (its `final` record landed after it). The checker reads raw records,
+// never the authoritative selection (#65).
+const degradeOrderingRefusals = (coreRecords) => {
+  const refusals = [];
+  coreRecords.forEach((r, i) => {
+    if (r.kind !== 'degrade') return;
+    const startedBefore = coreRecords.some((s, j) => j < i && s.kind === 'final-start' && s.fingerprint === r.fingerprint);
+    if (!startedBefore) return;
+    const cured = coreRecords.some((s, j) => j > i && s.kind === 'final-start' && s.fingerprint === r.fingerprint
+      && coreRecords.some((c, k) => k > j && c.kind === 'final' && c.attempt === s.attempt && c.fingerprintBefore === s.fingerprint));
+    if (!cured) {
+      refusals.push(`a core degrade (backend "${r.backend}") landed AFTER a final-start at its fingerprint (${short(r.fingerprint)}) with no later completed re-run at it — degrades mint strictly BEFORE the final run (#64); re-run run-gates.mjs --final on this tree`);
+    }
+  });
+  return refusals;
+};
+
+// #62: base delta ∩ plan surface — disjoint ⇒ re-baseline, intersecting/undecidable ⇒ refresh.
+export const classifyBaseMotion = ({ baseDelta, changedSurface }) => {
+  if (!baseDelta?.ok) {
+    return { motion: 'undecidable', requires: 'refresh', reason: `the base delta is undecidable (${baseDelta?.reason ?? 'no delta supplied'}) — fail closed: a refresh dispatch is REQUIRED (#62)` };
+  }
+  if (!changedSurface?.ok) {
+    return { motion: 'undecidable', requires: 'refresh', reason: `the changed surface is undecidable (${changedSurface?.reason ?? 'no surface supplied'}) — fail closed: a refresh dispatch is REQUIRED (#62)` };
+  }
+  const surface = new Set(changedSurface.paths);
+  const witness = baseDelta.paths.find((p) => surface.has(p));
+  if (witness !== undefined) return { motion: 'intersecting', requires: 'refresh', witness };
+  return { motion: 'disjoint', requires: 're-baseline' };
+};
+
+// In-step base transitions of the LAST segment (lifecycle projection — round revisions collapsed)
+// must land the class the delta requires; boundary and park→resume are exempt (every commit moves
+// HEAD); the tail binds only a live in-step chain.
+const baseMotionRefusals = (chain, planId, owner, motion) => {
+  if (chain[0].owner !== owner) return [];
+  const display = (b) => (b == null ? 'null' : short(b));
+  const refusals = [];
+  const classify = (fromBase, toBase) => classifyBaseMotion({
+    baseDelta: motion.resolveBaseDelta(fromBase, toBase),
+    changedSurface: motion.resolveChangedSurface(),
+  });
+  const requirement = (cls) => (cls.motion === 'disjoint' ? 'the delta is disjoint from the plan surface — re-baseline only, never a dispatch (#40)'
+    : cls.motion === 'intersecting' ? `the delta intersects the plan surface at ${cls.witness}`
+    : cls.reason);
+  const seenRounds = new Set();
+  const lifecycle = chain.filter((r) => {
+    if (r.purpose !== 'round') return true;
+    const key = JSON.stringify([r.cycle, r.stepId, r.round]);
+    if (seenRounds.has(key)) return false;
+    seenRounds.add(key);
+    return true;
+  });
+  const isSegmentStart = (r) => r.purpose === 'resume' || r.purpose === 'unfreeze' || (r.purpose === 'round' && r.opensFrom !== null);
+  const states = [];
+  const walk = { mode: 'boundary', parked: false };
+  for (const r of lifecycle) {
+    states.push({ ...walk });
+    if (r.purpose === 'park') walk.parked = true;
+    else if (r.purpose === 'resume') walk.parked = false;
+    else if (r.purpose === 'converged' || r.purpose === 'complete') walk.mode = 'boundary';
+    else if (r.purpose === 'unfreeze' || (r.purpose === 'round' && walk.mode === 'boundary')) walk.mode = 'in-step';
+  }
+  const segStart = lifecycle.reduce((last, r, i) => (isSegmentStart(r) ? i : last), 0);
+  for (let i = segStart + 1; i < lifecycle.length; i += 1) {
+    const prev = lifecycle[i - 1];
+    const r = lifecycle[i];
+    if (states[i].mode !== 'in-step' || states[i].parked || r.base === prev.base) continue;
+    const cls = classify(prev.base, r.base);
+    if (r.purpose !== cls.requires) {
+      refusals.push(`plan "${planId}": a mid-step base transition (${display(prev.base)} → ${display(r.base)}) landed a "${r.purpose}" record but requires a ${cls.requires} record — ${requirement(cls)}; final gates must re-run after base motion (#62)`);
+      continue;
+    }
+    if (r.purpose === 're-baseline' && r.baseBefore !== prev.base) {
+      refusals.push(`plan "${planId}": the mid-step re-baseline's baseBefore (${display(r.baseBefore)}) does not match the previous record's base (${display(prev.base)}) — a re-baseline binds the actual pre-motion base (#62)`);
+    }
+  }
+  const state = walkChainState(chain);
+  if (state.completed || state.parked || state.mode !== 'in-step') return refusals;
+  const recorded = lifecycle[lifecycle.length - 1].base;
+  if (recorded === motion.currentBase) return refusals;
+  const cls = classify(recorded, motion.currentBase);
+  const recovery = cls.requires === 're-baseline'
+    ? writerCommand(`re-baseline -- ${shellQuote(planId)}`)
+    : writerCommand(`refresh --cause='base motion' --refreshed-record=${canonicalFlowDigest(chain[chain.length - 1])} -- ${shellQuote(planId)}`);
+  const tailRequirement = cls.requires === 're-baseline'
+    ? 'a re-baseline record suffices (the delta is disjoint from the plan surface)'
+    : `a refresh dispatch is REQUIRED (${cls.motion === 'intersecting' ? `the delta intersects the plan surface at ${cls.witness}` : cls.reason})`;
+  refusals.push(`plan "${planId}": the base moved under the armed chain (recorded ${display(recorded)} → current ${display(motion.currentBase)}) and no ${cls.requires} record landed — ${tailRequirement}; final gates must re-run after base motion (#62). recovery (pasteable): ${recovery}`);
+  return refusals;
+};
+
+// decideFlowCheck({ flowRead, coreRead, owner, motion?, evidence?, consumer? }) → { refusals,
+// advisories }. Pure — consumes the FULL read-results of both stores; store health fails closed
+// BEFORE any content judgment. `motion` ({ currentBase, resolveBaseDelta, resolveChangedSurface })
+// arms the Step-1.4 base-motion refusals; `evidence` ({ receipts, tree, backends }) arms the three
+// Phase-1 rungs (#65/#25/#42 — each self-gates on an OWN adoption). Absent inputs keep the decision
+// byte-identical to the Plan-2 checker. `consumer` rides through to the #65 lane split and defaults
+// to the STRICT lane, so a caller that forgets to thread it inherits strictness.
+export const decideFlowCheck = ({ flowRead, coreRead, owner, flowPath = 'the flow store', corePath = 'the core evidence store', motion = null, evidence = null, consumer = 'commit-guard' }) => {
+  const refusals = [];
+  const advisories = [];
+  if (flowRead.readError) refusals.push(`the flow store is unreadable (${flowRead.readError}) — the checker consumes the FULL read-result; inspect ${flowPath} (fail closed)`);
+  else if (flowRead.malformed > 0) refusals.push(`the flow store carries ${flowRead.malformed} malformed line(s) (${flowRead.malformedReasons[0]}) — unknown kinds and broken records fail closed; inspect ${flowPath}`);
+  if (coreRead.readError) refusals.push(`the core evidence store is unreadable (${coreRead.readError}) — inspect ${corePath} (fail closed)`);
+  else if ((coreRead.malformed ?? 0) > 0) refusals.push(`the core evidence store carries ${coreRead.malformed} malformed line(s) (${coreRead.malformedReasons[0]}) — inspect ${corePath} (fail closed)`);
+  if (refusals.length > 0) return { refusals, advisories };
+  const records = flowRead.records;
+  const sup = validateSupersessions(records);
+  if (!sup.ok) refusals.push(`supersession legality: ${sup.reason} — inspect ${flowPath}`);
+  for (const planId of [...new Set(records.filter((r) => r.kind === CHAIN_KIND).map((r) => r.planId))]) {
+    const chain = records.filter((r) => r.kind === CHAIN_KIND && r.planId === planId);
+    const plan = planRefusals(records, chain, planId, owner, advisories);
+    refusals.push(...plan.refusals);
+    if (motion != null && plan.integrityClean) refusals.push(...baseMotionRefusals(chain, planId, owner, motion));
+  }
+  refusals.push(...deltaRefusals(records, owner));
+  refusals.push(...degradeOrderingRefusals(coreRead.records));
+  if (evidence != null) {
+    refusals.push(...collectUnansweredRedRefusals({ flowRecords: records, coreRecords: coreRead.records, currentBase: evidence.tree.base, owner, consumer, currentFingerprint: evidence.tree.fingerprint }));
+    refusals.push(...collectDegradeCoverageRefusals({ flowRecords: records, coreRecords: coreRead.records, tree: evidence.tree, owner, backends: evidence.degradeBackends }));
+    refusals.push(...collectReceiptCoverageRefusals({ flowRecords: records, receipts: evidence.receipts, tree: evidence.tree, owner, backends: evidence.receiptBackends, declaredPaths: evidence.declaredPaths, refreshCap: evidence.refreshCap }));
+  }
+  return { refusals, advisories };
+};