@sabaiway/agent-workflow-kit 5.0.0 → 5.2.0

package/tools/fs-read-nofollow.mjs

@@ -0,0 +1,128 @@
+// fs-read-nofollow.mjs — the race-free no-follow read primitive (flow-orchestration, Plan 4
+// Phase 2). A LEAF: imports Node built-ins only, owns no write API, no CLI, no side effects on
+// import — extracted from flow-store-read.mjs so consumers on BOTH sides of the flow-record →
+// core-evidence import edge (the receipts reader lives in core-evidence) can share the ONE
+// no-follow read without a cycle. flow-store-read.mjs re-exports everything here, so every
+// existing consumer keeps its import site. Dependency-free, Node >= 22.
+
+import { readFileSync, lstatSync, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
+
+// Local no-follow lstat (null ONLY on a true ENOENT).
+export const lstatNoFollowRead = (path, lstat = lstatSync) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+export const describeNonRegular = (st) =>
+  st.isSymbolicLink() ? 'symlink' : st.isFIFO() ? 'FIFO' : st.isDirectory() ? 'directory' : 'non-regular file';
+
+// fatal: a lossy decode would fold invalid bytes to U+FFFD and silently fork a record's digest.
+// ignoreBOM: a BOM must surface as malformed line 1, not vanish and get rewritten without it.
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const hasOpenFlag = (v) => typeof v === 'number' && v !== 0;
+
+// The ONE race-free read for store/lock bytes: open O_NOFOLLOW|O_NONBLOCK, fstat the DESCRIPTOR,
+// read through it, decode fatally — a pathname swapped after the open cannot change what the fd
+// reads. Without O_NONBLOCK (nonzero-integer check) it fails closed before any open — a FIFO open
+// would block and no check helps a blocked syscall; without only O_NOFOLLOW it lstat-classifies
+// first and binds the open to the observed {dev, ino}. Open failures outside ENOENT/ELOOP/EISDIR
+// fall back to a classification-only lstat (no read ever follows a path-based check). A close
+// failure on an OK read converts to outcome:error (the wrapper below — the bytes-twin discipline);
+// a non-ok outcome keeps its own class and carries the failure as `closeFailure` (the lock
+// holder's custody lane consumes it); consumers get a structured result, never a throw.
+export const readRegularFileNoFollow = (path, io = {}) => {
+  const closeBox = { failure: null };
+  const r = readNoFollowCore(path, io, closeBox);
+  if (closeBox.failure !== null) {
+    if (r.outcome === 'ok') return { outcome: 'error', code: `descriptor close failed (${closeBox.failure}) — fail closed` };
+    return { ...r, closeFailure: closeBox.failure };
+  }
+  return r;
+};
+
+const readNoFollowCore = (path, io, closeBox) => {
+  const consts = io.constants ?? fsConstants;
+  const open = io.open ?? openSync;
+  const fstat = io.fstat ?? fstatSync;
+  const readFd = io.readFile ?? readFileSync;
+  const close = io.close ?? closeSync;
+  const lstat = io.lstat ?? lstatSync;
+  if (!hasOpenFlag(consts.O_NONBLOCK)) {
+    return { outcome: 'error', code: 'this platform exposes no usable O_NONBLOCK open flag — refusing to open (a FIFO would block forever; fail closed)' };
+  }
+  const noFollow = hasOpenFlag(consts.O_NOFOLLOW);
+  let preStat = null;
+  if (!noFollow) {
+    try {
+      preStat = lstatNoFollowRead(path, lstat);
+    } catch (err) {
+      return { outcome: 'error', code: (err && err.code) || (err && err.message) || 'lstat failed' };
+    }
+    if (preStat == null) return { outcome: 'absent' };
+    if (!preStat.isFile()) return { outcome: 'foreign', className: describeNonRegular(preStat), isDirectory: preStat.isDirectory() };
+  }
+  let fd = null;
+  try {
+    fd = open(path, (consts.O_RDONLY ?? 0) | (noFollow ? consts.O_NOFOLLOW : 0) | consts.O_NONBLOCK);
+    const st = fstat(fd);
+    if (!st.isFile()) return { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
+    if (preStat !== null && (st.dev !== preStat.dev || st.ino !== preStat.ino)) {
+      return { outcome: 'error', code: 'the leaf changed identity between lstat and open (fail closed)' };
+    }
+    const bytes = readFd(fd);
+    let content;
+    try {
+      content = typeof bytes === 'string' ? bytes : FATAL_UTF8.decode(bytes);
+    } catch {
+      return { outcome: 'error', code: 'invalid UTF-8 in the file (fail closed)' };
+    }
+    if (io.keepFd) {
+      // While the caller holds this fd the inode cannot be recycled — a later pathname stat
+      // matching {dev, ino} is proof of the same file.
+      const heldFd = fd;
+      fd = null;
+      return { outcome: 'ok', content, dev: st.dev, ino: st.ino, nlink: st.nlink, fd: heldFd, bytes: typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes };
+    }
+    return { outcome: 'ok', content, dev: st.dev, ino: st.ino };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { outcome: 'absent' };
+    if (err && err.code === 'ELOOP') return { outcome: 'foreign', className: 'symlink', isDirectory: false };
+    if (err && err.code === 'EISDIR') return { outcome: 'foreign', className: 'directory', isDirectory: true };
+    try {
+      const st = lstatNoFollowRead(path, lstat);
+      if (st && !st.isFile()) return { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
+    } catch { /* the open error stays the surfaced one */ }
+    return { outcome: 'error', code: (err && err.code) || (err && err.message) || 'read failed' };
+  } finally {
+    if (fd !== null) {
+      try {
+        close(fd);
+      } catch (err) {
+        closeBox.failure = (err && err.code) || (err && err.message) || 'close failed';
+      }
+    }
+  }
+};
+
+// readFileBytesNoFollow(path, io?) → { outcome: 'ok', bytes } | absent | foreign | error — the
+// BYTES twin of the reader above for consumers whose domain is byte offsets (the Phase-4
+// receipt-deadline watermark, the finding-manifest digest domain): keepFd internally so the raw
+// bytes come back, then the fd is closed HERE with a fail-closed close (a close failure becomes
+// an error outcome, never a leak and never a swallowed throw). Balance: one open, one close, on
+// every outcome — pinned by an injectable-io counting test.
+export const readFileBytesNoFollow = (path, io = {}) => {
+  const r = readRegularFileNoFollow(path, { ...io, keepFd: true });
+  if (r.outcome !== 'ok') return r;
+  let closeFailure = null;
+  try {
+    (io.close ?? closeSync)(r.fd);
+  } catch (err) {
+    closeFailure = (err && err.code) || (err && err.message) || 'close failed';
+  }
+  if (closeFailure !== null) return { outcome: 'error', code: `held-descriptor close failed (${closeFailure}) — fail closed` };
+  return { outcome: 'ok', bytes: r.bytes };
+};

package/tools/gates-declaration.mjs

@@ -0,0 +1,184 @@
+// gates-declaration.mjs — the gates.json declaration (load + strict validation) and the canonical
+// checker predicate family (flow Plan 4 Phase 2, FLOW-READ-GRAPH-PURITY / the R10 rider). A LEAF
+// below both run-gates.mjs and flow-store.mjs: run-gates re-exports the public surface (every
+// historical consumer keeps its import site), and the locked subset-attempt factory imports the
+// derivation DIRECTLY — re-deriving the pregate subset itself was blocked exactly by the
+// run-gates↔flow-store import cycle this extraction removes. No CLI, no side effects on import,
+// no fs writes. Dependency-free, Node >= 22.
+
+import { readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fail, loadConfig, CONFIG_REL } from './orchestration-config.mjs';
+
+// The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
+// user can open (the orchestration-config CONFIG_REL idiom).
+export const GATES_REL = 'docs/ai/gates.json';
+
+// Parity: run-gates.mjs EXIT.malformed — its exit-code table stays the CLI authority (pinned by
+// run-gates.test.mjs); this module throws the same tagged shape so the CLI surfaces it unchanged.
+const EXIT_MALFORMED = 5;
+
+const GATE_ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const GATE_KEYS = Object.freeze(['id', 'title', 'cmd']);
+
+// ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
+
+// Validate a parsed gates.json object. Strict: only `_README` (string) + `gates` (array of
+// { id, title, cmd }) are allowed; unknown keys anywhere are rejected loudly — the declaration
+// names WHAT to check, never lanes/models/routing. Returns the validated gates array.
+export const validateDeclaration = (parsed) => {
+  const reject = (reason) => {
+    throw fail(EXIT_MALFORMED, `${GATES_REL}: ${reason}`);
+  };
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    reject('must be a JSON object { "_README"?: string, "gates": [{ id, title, cmd }, ...] }');
+  }
+  for (const key of Object.keys(parsed)) {
+    if (key !== '_README' && key !== 'gates') reject(`unknown top-level key "${key}" (allowed: _README, gates)`);
+  }
+  if (parsed._README !== undefined && typeof parsed._README !== 'string') reject('"_README" must be a string');
+  if (!Array.isArray(parsed.gates)) reject('"gates" must be an array of { id, title, cmd }');
+  const seenIds = new Set();
+  parsed.gates.forEach((gate, index) => {
+    const at = `gates[${index}]`;
+    if (gate === null || typeof gate !== 'object' || Array.isArray(gate)) {
+      reject(`${at}: must be an object { id, title, cmd }`);
+    }
+    for (const key of Object.keys(gate)) {
+      if (!GATE_KEYS.includes(key)) {
+        reject(`${at}: unknown key "${key}" (allowed: id, title, cmd — gates declare WHAT to check, never lane/model/routing)`);
+      }
+    }
+    for (const key of GATE_KEYS) {
+      if (typeof gate[key] !== 'string' || gate[key].trim() === '') {
+        reject(`${at}: "${key}" must be a non-empty string`);
+      }
+    }
+    if (/[\r\n]/.test(gate.cmd)) {
+      reject(`${at}: "cmd" must be ONE bash command line — embedded newlines (a multi-line script) are rejected; chain with && or move the script into a file`);
+    }
+    if (!GATE_ID_RE.test(gate.id)) reject(`${at}: id "${gate.id}" must be kebab-case (lowercase [a-z0-9] groups separated by "-")`);
+    if (seenIds.has(gate.id)) reject(`${at}: duplicate id "${gate.id}"`);
+    seenIds.add(gate.id);
+  });
+  return parsed.gates;
+};
+
+// ── declaration IO ────────────────────────────────────────────────────────────────────
+
+// Load the declaration from <cwd>/docs/ai/gates.json. A truly-absent file is the DISTINCT
+// `missing` outcome (exit 3 upstream, with the recovery named) — never an error throw; anything
+// present-but-unreadable / malformed / schema-invalid throws the loud exit-5 failure. lstat does
+// not follow links, so a dangling symlink reads as present and its read failure surfaces loudly
+// (no-silent-failures Hard Constraint — the loadConfig idiom).
+export const loadDeclaration = (cwd, { readFile = readFileSync, lstat = lstatSync } = {}) => {
+  const full = join(cwd, GATES_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { outcome: 'missing' };
+    throw fail(EXIT_MALFORMED, `${GATES_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(EXIT_MALFORMED, `${GATES_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(EXIT_MALFORMED, `${GATES_REL}: malformed JSON (${err.message})`);
+  }
+  return { outcome: 'loaded', gates: validateDeclaration(parsed) };
+};
+
+// ── the canonical core-check matcher (STRICT full-command shape + realpath anchor) ────
+
+// The canonical core checks a --final declaration must carry (D3(a)), matched as STRICT FULL
+// commands: `node` + ONE (quoted or bare) path token + the exact tool basename + ` --check` +
+// END — and the path token must REALPATH-RESOLVE to the kit's OWN tool (the canonical sibling of
+// this runner). Masked forms (`--check --help`, `--check || true`, prefix commands) never match
+// the shape; a lookalike file that merely carries the basename — whatever it prints — never
+// resolves to the canonical tool. Any form that DOES resolve (bare, relative, absolute, quoted)
+// is accepted, so the anchor adds no false refusals.
+const coreCheckRe = (basename) => new RegExp(`^node\\s+(?:"((?:[^"]*[/\\\\])?${basename})"|((?:[^\\s"]*[/\\\\])?${basename}))\\s+--check$`);
+export const FINAL_CORE_CHECKS = [
+  { name: 'review-state', re: coreCheckRe('review-state\\.mjs'), canonical: fileURLToPath(new URL('./review-state.mjs', import.meta.url)) },
+  { name: 'coverage-check', re: coreCheckRe('coverage-check\\.mjs'), canonical: fileURLToPath(new URL('./coverage-check.mjs', import.meta.url)) },
+];
+export const matchesCanonicalCheck = (check, cmd, projectDir) => {
+  const m = check.re.exec(cmd.trim());
+  if (!m) return false;
+  const token = m[1] ?? m[2];
+  const abs = isAbsolute(token) ? token : join(projectDir, token);
+  try {
+    return realpathSync(abs) === realpathSync(check.canonical);
+  } catch {
+    return false; // unresolvable → never canonical (fail closed)
+  }
+};
+
+// canonicalCheckerGates(gates, projectDir) → every gate that IS the canonical coverage-check. The
+// count is load-bearing twice over: --final refuses more than one (the attestation capability would
+// reach more than one process) and this predicate must refuse the same declaration, or a consumer
+// would advertise final-capability for a declaration --final then rejects.
+export const canonicalCheckerGates = (gates, projectDir) =>
+  gates.filter((g) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], g.cmd, projectDir));
+
+// isFinalCapableDeclaration(gates, projectDir) → whether --final would accept this declaration
+// (every canonical core check present + EXACTLY ONE canonical checker + that checker LAST) — the
+// ONE home consumers (the recommendations guard-install probe, the worktrees report) read instead
+// of re-deriving the rule.
+export const isFinalCapableDeclaration = (gates, projectDir) => {
+  if (!Array.isArray(gates) || gates.length === 0) return false;
+  const missing = FINAL_CORE_CHECKS.filter((c) => !gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
+  if (missing.length > 0) return false;
+  if (canonicalCheckerGates(gates, projectDir).length !== 1) return false;
+  return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
+};
+
+// The review-dependent predicate (#66/P14): a gate is review-dependent iff its cmd IS the plain
+// canonical `--check` invocation of one of the kit's OWN checkers, resolved by realpath — never a
+// project-authored id. A project abstracting the invocation behind its own script declares it in
+// flow.pregateExclude (the mode doc states this plainly).
+const REVIEW_DEPENDENT_CHECKS = ['review-state', 'commit-guard', 'coverage-check', 'flow-check'].map((name) => ({
+  name,
+  re: coreCheckRe(`${name}\\.mjs`),
+  canonical: fileURLToPath(new URL(`./${name}.mjs`, import.meta.url)),
+}));
+
+export const isReviewDependentGate = (gate, projectDir) =>
+  REVIEW_DEPENDENT_CHECKS.some((check) => matchesCanonicalCheck(check, gate.cmd, projectDir));
+
+// ── the pregate subset derivation (#66 / Decision 7 — ONE home for producer and factory) ─────
+
+export const unknownPregateExcludeIds = (gates, exclude) => {
+  const declaredIds = new Set(gates.map((gate) => gate.id));
+  return exclude.filter((id) => !declaredIds.has(id));
+};
+
+// The derived --pre-review subset: the full declaration minus the DERIVED review-dependent gates
+// minus a validated flow.pregateExclude — declaration order preserved.
+export const derivePregateSubsetGates = (gates, exclude, projectDir) =>
+  gates.filter((gate) => !isReviewDependentGate(gate, projectDir) && !exclude.includes(gate.id));
+
+// derivePregateSubsetIds(cwd, io?) → the ordered gate-id array the subsetDigest is allowed to
+// bind, derived from <cwd>'s declaration + orchestration config (the R10 rider consumer: the
+// locked subset-attempt factory re-derives instead of trusting its caller). Throws the loud
+// tagged failure on every underivable state — an underivable subset never mints an attempt.
+export const derivePregateSubsetIds = (cwd, io = {}) => {
+  const declaration = loadDeclaration(cwd, io);
+  if (declaration.outcome === 'missing') {
+    throw fail(EXIT_MALFORMED, `no gate declaration found at ${GATES_REL} — the pregate subset is underivable`);
+  }
+  const { config } = loadConfig(cwd);
+  const exclude = config?.flow?.pregateExclude ?? [];
+  const unknown = unknownPregateExcludeIds(declaration.gates, exclude);
+  if (unknown.length > 0) {
+    throw fail(EXIT_MALFORMED, `${CONFIG_REL} flow.pregateExclude names gate id(s) not declared in ${GATES_REL}: ${unknown.join(', ')} (declared: ${declaration.gates.map((gate) => gate.id).join(', ')})`);
+  }
+  return derivePregateSubsetGates(declaration.gates, exclude, cwd).map((gate) => gate.id);
+};

package/tools/gates-init.mjs

@@ -33,9 +33,10 @@
 //   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
 //     passes the runner's validateDeclaration (this module imports the validator — NEVER the
 //     reverse: run-gates.mjs stays a runner that writes nothing);
-//   • the review-state candidate appears ONLY when docs/ai/orchestration.json DECLARES
-//     reviewed/council on plan-execution.review — the slot the checker enforces — with the
-//     resolved, QUOTED tool path (spaces survive; executes from the project root).
+//   • the review-state candidate appears when docs/ai/orchestration.json DECLARES
+//     reviewed/council on plan-execution.review OR carries a flow block (the P21 trio — under
+//     flow + solo the internal-only arm runs INSIDE review-state), with the resolved, QUOTED
+//     tool path (spaces survive; executes from the project root).
 //
 // Write discipline: preview (dry-run) is the DEFAULT and writes NOTHING — a declined offer leaves
 // the file byte-identical. `--apply` appends EXACTLY the consented entries (`--only <id>`
@@ -61,6 +62,7 @@ const KIT_ROOT = resolve(HERE, '..');
 const TEMPLATE_PATH = join(KIT_ROOT, 'references', 'templates', 'gates.json');
 const REVIEW_STATE_TOOL = join(KIT_ROOT, 'tools', 'review-state.mjs');
 const COVERAGE_CHECK_TOOL = join(KIT_ROOT, 'tools', 'coverage-check.mjs');
+const FLOW_CHECK_TOOL = join(KIT_ROOT, 'tools', 'flow-check.mjs');
 const STAMP_REL = join('docs', 'ai', '.workflow-version');
 
 const EXIT_OK = 0;
@@ -274,20 +276,28 @@ const deriveScripts = (cwd, deps = {}) => {
 export const deriveScriptEntries = (cwd, deps = {}) => deriveScripts(cwd, deps).entries;
 
 // The conditional review-state candidate — keyed on the SLOT the checker enforces
-// (plan-execution.review, tools/review-state.mjs), read via the shared config reader. Offered only
-// when the config DECLARES reviewed/council there; solo configs and a council-on-plan-authoring-only
-// config never see it. The cmd carries the resolved, QUOTED tool path and passes the validator.
+// (plan-execution.review, tools/review-state.mjs), read via the shared config reader. Offered when
+// the config DECLARES reviewed/council there OR carries a flow block (reviewSlotWantsChecker); a
+// plain solo config never sees it. The cmd carries the resolved, QUOTED tool path and passes the
+// validator.
 // Double-quote-unsafe shell metacharacters: inside `"…"` bash still expands `$`, backticks and
 // backslashes, and a `"` breaks the quoting entirely. A candidate cmd is hook-auto-approvable, so a
 // path that cannot be safely double-quoted is WITHHELD with a loud note — never offered wrongly.
 const DQ_UNSAFE_PATH_PATTERN = /["$`\\\r\n]/;
 
+// Under a flow block the offer covers the full checker TRIO whatever the recipe (P21): with flow +
+// a solo recipe the internal-only arm executes INSIDE review-state, so offering flow-check alone
+// would arm half the surface.
+const reviewSlotWantsChecker = (config) => {
+  const declared = config?.['plan-execution']?.review;
+  return declared === 'reviewed' || declared === 'council' || config?.flow != null;
+};
+
 export const reviewStateCandidate = (cwd, deps = {}) => {
   const toolPath = deps.reviewStateTool ?? REVIEW_STATE_TOOL;
   try {
     const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
-    const declared = config?.['plan-execution']?.review;
-    if (declared !== 'reviewed' && declared !== 'council') return { candidate: null, note: null };
+    if (!reviewSlotWantsChecker(config)) return { candidate: null, note: null };
     if (DQ_UNSAFE_PATH_PATTERN.test(toolPath)) {
       return {
         candidate: null,
@@ -314,7 +324,7 @@ export const reviewStateCandidate = (cwd, deps = {}) => {
 };
 
 // The conditional COVERAGE-CHECK candidate (D3(a)) — the SAME consent + conditional rule as the
-// review-state candidate (offered ONLY when plan-execution.review is reviewed/council), keyed on
+// review-state candidate (reviewSlotWantsChecker: reviewed/council OR a flow block), keyed on
 // the same slot, path resolved + QUOTED. Together they are the canonical core pair `run-gates
 // --final` requires (the checker declared LAST — buildOffer appends it last so a whole-offer
 // apply lands final-ready); review-state gates receipt satisfaction, coverage-check verifies the
@@ -323,8 +333,7 @@ export const coverageCheckCandidate = (cwd, deps = {}) => {
   const toolPath = deps.coverageCheckTool ?? COVERAGE_CHECK_TOOL;
   try {
     const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
-    const declared = config?.['plan-execution']?.review;
-    if (declared !== 'reviewed' && declared !== 'council') return { candidate: null, note: null };
+    if (!reviewSlotWantsChecker(config)) return { candidate: null, note: null };
     if (DQ_UNSAFE_PATH_PATTERN.test(toolPath)) {
       return {
         candidate: null,
@@ -350,6 +359,37 @@ export const coverageCheckCandidate = (cwd, deps = {}) => {
   }
 };
 
+// The conditional FLOW-CHECK candidate (P21) — offered ONLY when the orchestration config carries
+// a `flow` block; the same consent + path-quoting discipline as the pair above.
+export const flowCheckCandidate = (cwd, deps = {}) => {
+  const toolPath = deps.flowCheckTool ?? FLOW_CHECK_TOOL;
+  try {
+    const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    if (config?.flow == null) return { candidate: null, note: null };
+    if (DQ_UNSAFE_PATH_PATTERN.test(toolPath)) {
+      return {
+        candidate: null,
+        note:
+          `the flow-check candidate was withheld: the resolved kit path contains shell ` +
+          `metacharacters that do not survive double-quoting (${toolPath}) — declare the gate by hand`,
+      };
+    }
+    return {
+      candidate: {
+        id: 'flow-check',
+        title: 'Flow-store chain state clean for this worktree (flow-orchestration)',
+        cmd: `node "${toolPath}" --check`,
+      },
+      note: null,
+    };
+  } catch (err) {
+    return {
+      candidate: null,
+      note: `orchestration config unreadable (${err.message}) — the flow-check candidate was not evaluated`,
+    };
+  }
+};
+
 // Every --only id must name an OFFERED entry — enforced in BOTH paths (dry-run and apply), before
 // any empty-offer shortcut, so a typo is a loud usage error, never a silent filter or a silent
 // "nothing to offer" success.
@@ -361,18 +401,20 @@ const assertOnlyIdsOffered = (offer, onlyIds = []) => {
   }
 };
 
-// The full offer: script entries + the conditional review-state + coverage-check candidates
-// (coverage-check LAST — the `run-gates --final` declaration-shape rule requires the checker as
-// the last declared gate, so a whole-offer apply is final-ready by construction). Both key on the
-// same slot (plan-execution.review reviewed/council) but gate distinct axes.
+// The full offer: script entries + the conditional review-state / flow-check / coverage-check
+// candidates (coverage-check LAST — the `run-gates --final` declaration-shape rule requires the
+// checker as the last declared gate, so a whole-offer apply is final-ready by construction). The
+// pair keys on plan-execution.review reviewed/council OR a flow block (the P21 trio); flow-check
+// itself appears only under a flow block.
 export const buildOffer = (cwd, deps = {}) => {
   const scripts = deriveScripts(cwd, deps);
   const rs = reviewStateCandidate(cwd, deps);
+  const fc = flowCheckCandidate(cwd, deps);
   const cc = coverageCheckCandidate(cwd, deps);
-  const candidates = [rs.candidate, cc.candidate].filter(Boolean);
+  const candidates = [rs.candidate, fc.candidate, cc.candidate].filter(Boolean);
   return {
     entries: [...scripts.entries, ...candidates],
-    notes: [...scripts.notes, rs.note, cc.note].filter(Boolean),
+    notes: [...scripts.notes, rs.note, fc.note, cc.note].filter(Boolean),
   };
 };
 

package/tools/orchestration-config.mjs

@@ -15,8 +15,8 @@
 //                                                by the _README refresh and the injected-slot refresh.
 //
 // This module performs NO filesystem WRITES — only reads (loadConfig). The single fs-writer lives in
-// orchestration-write.mjs, which procedures.mjs never imports, so "procedures never reaches a writer"
-// is structurally true. Pure-where-possible (fs injectable), dependency-free, Node >= 22. No side
+// orchestration-write.mjs, which procedures.mjs never imports DIRECTLY (the pinned import-split
+// rule). Pure-where-possible (fs injectable), dependency-free, Node >= 22. No side
 // effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
@@ -113,10 +113,94 @@ export const parseOp = (kind, token) => {
 
 // ── config validation (config errors → exit 1) ──────────────────────────────────────
 
+// The accepted `flow` schema version — the SINGLE source both the acceptance check and the refusal
+// message use; future flow-aware releases IMPORT this constant, never re-type it. The wire value is
+// pinned NUMERIC (the string form is a named refusal case).
+export const FLOW_SCHEMA_VERSION = 1;
+
+// The honest lagging-kit contract sentence: what a kit WITHOUT the flow branch does when it meets
+// a `flow` block, and what the now-armed `set-flow` floor can and cannot reach. doc-parity binds
+// it VERBATIM into the procedures and set-flow mode docs, so the admission can never be reworded
+// away: no in-config floor protects a reader that dies on the unknown key itself.
+export const FLOW_LAGGING_KIT_CONTRACT =
+  'a kit predating the `"flow"` key that reads a config carrying one fails this config load loudly (exit `1`, reddening its full gate matrix); the `set-flow` arming path now enforces the declared `kitMinVersion` floor with a null-guarded comparison (an unparseable version never passes), while tolerate-first ordering remains the only protection for readers older than the `"flow"` key itself — no in-config floor can reach a kit that dies on the unknown key';
+
+// ── the closed flow schema-1 surface (P20) — ONE literal fixture for BOTH consumers ─────
+// The structural validator below and the set-flow arming path (Phase 3) walk the SAME closed key
+// set; a drift-guarded named test validates the literal fixture. Shape-only here (#31): every
+// environment floor (tracked-ness, symlink/dir classes, the kit min-version comparison) lives
+// exclusively on the arming path.
+
+export const FLOW_SCHEMA_1_KEYS = Object.freeze([
+  'schema', 'preset', 'candidates', 'councilRounds', 'debtQueue', 'convergenceSummary',
+  'debtQueueExcluded', 'convergenceSummaryExcluded', 'pregateExclude', 'kitMinVersion',
+]);
+export const FLOW_PRESET_VALUES = Object.freeze(['council', 'reviewed', 'internal-only']);
+export const FLOW_CANDIDATE_CLASSES = Object.freeze(['review', 'execution']);
+// The arming path (set-flow, Phase 3) compares kitMinVersion via the null-guarded semver shape
+// characterized in the FLOW-VERSION-FLOORS block of semver-lite.test.mjs (Decision 6).
+export const FLOW_MIN_VERSION_COMPARISON = 'semver-lite null-guarded comparison (FLOW-VERSION-FLOORS characterization)';
+export const FLOW_SCHEMA_1_FIXTURE = Object.freeze({
+  schema: FLOW_SCHEMA_VERSION,
+  preset: 'council',
+  candidates: Object.freeze([
+    Object.freeze({ name: 'codex', class: 'review' }),
+    Object.freeze({ name: 'agy', class: 'review' }),
+  ]),
+  councilRounds: 3,
+  debtQueue: 'docs/debt.md',
+  convergenceSummary: 'docs/convergence.md',
+  debtQueueExcluded: false,
+  convergenceSummaryExcluded: false,
+  pregateExclude: Object.freeze([]),
+  kitMinVersion: '5.1.0',
+});
+
+// The per-key STRUCTURAL checks of the schema-1 flow block (P7/P20) — shape only, loud
+// `path: reason`; every environment floor lives on the set-flow arming path (#31). A failure
+// message, or null when the value fits the key's shape.
+const flowKeyFailure = (key, value) => {
+  if (key === 'preset') {
+    return FLOW_PRESET_VALUES.includes(value) ? null : `must be one of ${FLOW_PRESET_VALUES.join(' | ')} (got ${JSON.stringify(value)})`;
+  }
+  if (key === 'candidates') {
+    if (!Array.isArray(value)) return 'must be an array of typed { name, class } objects (#30)';
+    for (const c of value) {
+      if (c === null || typeof c !== 'object' || Array.isArray(c)) return 'must hold only { name, class } objects';
+      const stray = Object.keys(c).find((k) => k !== 'name' && k !== 'class');
+      if (stray !== undefined) return `candidate objects carry exactly { name, class } — unknown field "${stray}"`;
+      if (typeof c.name !== 'string' || c.name === '') return 'every candidate name must be a non-empty string';
+      if (!FLOW_CANDIDATE_CLASSES.includes(c.class)) return `every candidate class must be one of ${FLOW_CANDIDATE_CLASSES.join(' | ')} (got ${JSON.stringify(c.class)})`;
+    }
+    return null;
+  }
+  if (key === 'councilRounds') {
+    return Number.isInteger(value) && value >= 1 ? null : `must be a positive integer — the #45 refresh-cap source (got ${JSON.stringify(value)})`;
+  }
+  if (key === 'debtQueue' || key === 'convergenceSummary') {
+    return typeof value === 'string' && value.length > 0 ? null : `must be a non-empty repo-relative path string (got ${JSON.stringify(value)})`;
+  }
+  if (key === 'debtQueueExcluded' || key === 'convergenceSummaryExcluded') {
+    return typeof value === 'boolean' ? null : `must be a boolean (the declared-excluded form, #31/#37; got ${JSON.stringify(value)})`;
+  }
+  if (key === 'pregateExclude') {
+    if (!Array.isArray(value) || !value.every((id) => typeof id === 'string' && id.length > 0)) {
+      return `must be an array of non-empty gate-id strings (#47; got ${JSON.stringify(value)})`;
+    }
+    return new Set(value).size === value.length ? null : 'must not carry duplicate gate ids (#47)';
+  }
+  if (key === 'kitMinVersion') {
+    return typeof value === 'string' && value.length > 0 ? null : `must be a non-empty version string — the #54 floor, compared on the arming path via the ${FLOW_MIN_VERSION_COMPARISON} (got ${JSON.stringify(value)})`;
+  }
+  return null; // schema — checked before the key walk
+};
+
 // Validate a parsed orchestration.json object against the schema. Strict: an unknown top-level
 // activity, an unknown slot for an activity, or a recipe invalid-for-slot is an error. All slots are
-// optional. An optional "_README" string key is allowed + ignored (self-documentation). Never a silent
-// fallback — every rejection is a loud `path: reason` (exit 1). Returns the config on success.
+// optional. An optional "_README" string key is allowed + ignored (self-documentation). The
+// versioned "flow" object key validates against the FULL structural schema-1 surface (closed key
+// set + per-key shapes — P7/P20); deep environment floors stay on the set-flow arming path (#31).
+// Never a silent fallback — every rejection is a loud `path: reason` (exit 1). Returns the config on success.
 export const validateConfig = (config) => {
   if (config === null || typeof config !== 'object' || Array.isArray(config)) {
     throw fail(1, `${CONFIG_REL}: must be a JSON object of activity → { slot: recipe }`);
@@ -126,6 +210,23 @@ export const validateConfig = (config) => {
       if (typeof val !== 'string') throw fail(1, `${CONFIG_REL}: "_README" must be a string`);
       continue;
     }
+    if (key === 'flow') {
+      if (val === null || typeof val !== 'object' || Array.isArray(val)) {
+        throw fail(1, `${CONFIG_REL}: "flow" must be a JSON object carrying { "schema": ${FLOW_SCHEMA_VERSION} }`);
+      }
+      if (val.schema !== FLOW_SCHEMA_VERSION) {
+        const got = 'schema' in val ? JSON.stringify(val.schema) : 'absent';
+        throw fail(1, `${CONFIG_REL}: "flow".schema must be the number ${FLOW_SCHEMA_VERSION} (got ${got})`);
+      }
+      for (const [flowKey, flowValue] of Object.entries(val)) {
+        if (!FLOW_SCHEMA_1_KEYS.includes(flowKey)) {
+          throw fail(1, `${CONFIG_REL}: "flow" carries unknown key "${flowKey}" — the schema-1 key set is closed (${FLOW_SCHEMA_1_KEYS.join(', ')})`);
+        }
+        const failure = flowKeyFailure(flowKey, flowValue);
+        if (failure !== null) throw fail(1, `${CONFIG_REL}: "flow".${flowKey} ${failure}`);
+      }
+      continue;
+    }
     const activityDef = ACTIVITIES[key];
     if (!activityDef) {
       throw fail(1, `${CONFIG_REL}: unknown activity "${key}" (known: ${KNOWN_ACTIVITIES()})`);

package/tools/orchestration-write.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // orchestration-write.mjs — the ONLY filesystem WRITER for docs/ai/orchestration.json. It is imported
-// by the set-recipe writer alone; procedures.mjs never imports it, so "the read-only procedures advisor
-// can never reach a writer" is a STRUCTURAL invariant (an import-split test pins it), not just an
-// assertion. Splitting the writer out of the schema/read module keeps the read surface fs-write-free.
+// by the config WRITERS alone (set-recipe, set-flow); procedures.mjs never imports it DIRECTLY —
+// the import-split test pins that direct-import rule. Splitting the writer out of the schema/read
+// module keeps the read surface fs-write-free.
 //
 // The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create
 // tmp + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS, documented) lives in the

package/tools/plan-files.mjs

@@ -0,0 +1,35 @@
+// plan-files.mjs — the in-flight-plan file convention (FLOW-READ-GRAPH-PURITY, flow Plan 4
+// Phase 2). A LEAF: Node built-ins only, read-only fs (one injectable readdir), no CLI, no side
+// effects on import — extracted so the procedures read surface lists plans without importing
+// review-state (whose graph reaches the flow-store write API). review-state re-exports everything
+// here, so every existing consumer keeps its import site. Dependency-free, Node >= 22.
+
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PLANS_REL = 'docs/plans';
+
+// Scratch by the naming convention: EXECUTE-/FEEDBACK- prefixes, or a name carrying PROMPT/prompt/
+// handoff. queue.md is the series index, never a plan.
+export const isScratchPlanName = (name) =>
+  name === 'queue.md' ||
+  name.startsWith('EXECUTE-') ||
+  name.startsWith('FEEDBACK-') ||
+  name.includes('PROMPT') ||
+  name.includes('prompt') ||
+  name.includes('handoff');
+
+// The in-flight plan files: top-level docs/plans/*.md minus queue.md minus scratch. [] when the
+// directory is absent (no plans → nothing in flight). STRING-typed for every consumer.
+export const plansInFlight = (cwd, readdir = readdirSync) => {
+  let entries;
+  try {
+    entries = readdir(join(cwd, PLANS_REL), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md') && !isScratchPlanName(e.name))
+    .map((e) => e.name)
+    .sort();
+};