@sabaiway/agent-workflow-kit 11.0.0 → 11.2.0

package/references/templates/decisions.md

@@ -13,7 +13,7 @@ maxLines: 500
 > consequences, newest at the bottom. Link related ADRs with `[[AD-XXX]]`; retrieval is by the
 > `AD-NNN` id (filename), grep over the flat store, or the `[[AD-NNN]]` supersession chain.
 
-> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically; no cap is ever raised and there is no monolithic ledger.
+> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically where the enforcement scripts are deployed (installed on a yes); no cap is ever raised and there is no monolithic ledger.
 
 ## AD-001 — Adopt AI-agent memory system (`docs/ai/`)
 
@@ -22,7 +22,7 @@ maxLines: 500
 
 **Context.** Multi-session AI work loses context between runs. Without a structured handover, each new session re-reads code, re-discovers decisions, and repeats past mistakes.
 
-**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via a pre-commit hook. Deployed via the `agent-workflow-kit` skill.
+**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via the deployed scripts + pre-commit hook (offered on every project, installed on a yes). Deployed via the `agent-workflow-kit` skill.
 
 **Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + one-file-per-ADR archival keep every record scannable as the decision history grows without bound.
 

package/references/templates/orchestration.json

@@ -1,5 +1,5 @@
 {
-  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option never goes away. Three activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review) and 'routine' (slots carrier, parallel). A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize), or an explicit roster array such as [\"codex-review\", \"agy-review\", \"review-lens\"] in hand-edit form; an 'execute' slot accepts solo | delegated | subagent (you implement / a backend runs a bounded sub-task / a full-tool frontier subagent carries a bounded slice you verify); the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' accept solo | subagent. 'routine.parallel' is a flag rather than a recipe: it accepts on | off and decides whether file-disjoint subagent slices dispatch concurrently. The default below is 'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. 'subagent' needs the executor vehicle placed in this project — the composition root's `agents` writer places it; without it the slot resolves to solo with the reason stated. Remove a slot's line, or a whole activity block (or run `set-recipe --unset <activity>.<slot>`), to fall back to the computed default: reviewed when a review backend is ready and otherwise solo for a review slot, solo for author, fold, execute and carrier, on for parallel. Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment. Strict JSON — no comments.",
+  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option never goes away. Four activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review), 'routine' (slots carrier, parallel) and 'feedback-triage' (slot review). A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize), or an explicit roster array such as [\"codex-review\", \"agy-review\", \"review-lens\"] in hand-edit form; an 'execute' slot accepts solo | delegated | subagent (you implement / a backend runs a bounded sub-task / a full-tool frontier subagent carries a bounded slice you verify); the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' accept solo | subagent. 'routine.parallel' is a flag rather than a recipe: it accepts on | off and decides whether file-disjoint subagent slices dispatch concurrently. Every slot seeded below is 'solo' — no execution backend required. A slot the seed leaves silent takes the computed default stated further down: 'feedback-triage.review' is reviewed as soon as a review backend is ready (solo until then); 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' stay 'solo', and 'routine.parallel' stays 'on'. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. 'subagent' needs the executor vehicle placed in this project — the composition root's `agents` writer places it; without it the slot resolves to solo with the reason stated. Remove a slot's line, or a whole activity block (or run `set-recipe --unset <activity>.<slot>`), to fall back to the computed default: reviewed when a review backend is ready and otherwise solo for a review slot, solo for author, fold, execute and carrier, on for parallel. Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment. Strict JSON — no comments.",
   "plan-authoring": {
     "review": "solo"
   },

package/tools/carriers.mjs

@@ -15,6 +15,7 @@ export const ACTIVITIES = {
   'plan-authoring': { slots: { author: 'carrier', fold: 'carrier', review: 'review' }, policy: true },
   'plan-execution': { slots: { execute: 'execute', review: 'review' }, policy: true },
   routine: { slots: { carrier: 'carrier', parallel: 'switch' }, policy: false },
+  'feedback-triage': { slots: { review: 'review' }, policy: false },
 };
 
 export const POLICY_ACTIVITIES = Object.fromEntries(

package/tools/feedback-record-cli.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// Feedback-record filesystem and argv shell. Governing contract:
+// docs/ai/specs/kit/feedback-triage.md.
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readFileBytesNoFollowCapped } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, stripGitLocationEnv, withGitPath } from './git-env.mjs';
+import { assertScratchDestination, DEFAULT_MAX_PROMPT_BYTES, trimToBudget } from './grounding.mjs';
+import { judgeAnchors, parseRecord, ratchetLine, REFUSALS, renderExcerpts, renderRows } from './feedback-record.mjs';
+
+const RECORD_MAX_BYTES = 1024 * 1024;
+export const EXCERPTS_FRAMING_RESERVE_BYTES = 4096;
+const GATES_REL = 'docs/ai/gates.json';
+const QUEUE_GATE_TOKEN = 'queue-audit-cli.mjs';
+const MODE_FLAGS = Object.freeze(['--check', '--rows']);
+const FATAL_PARSE_REFUSALS = Object.freeze(REFUSALS.slice(0, 4));
+const FINDING_NAMES = Object.freeze({
+  anchorPath: 'anchor-path', anchorDirty: 'anchor-dirty', gitLocation: 'git-location',
+  headMismatch: 'head-mismatch', excerptsDestination: 'excerpts-destination',
+  excerptsBudget: 'excerpts-budget', excerptsWrite: 'excerpts-write', exists: 'EEXIST',
+});
+const GIT_ENV_LOCALE = 'C';
+const GIT_OPTIONAL_LOCKS_DISABLED = '0';
+const EXCLUSIVE_CREATE_FLAG = 'wx';
+const EMPTY_ANSWER_OK = new Set(['status', 'ls-files']);
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+const readValue = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('--')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+
+const parseArgv = (argv) => {
+  const options = { mode: null, record: null, excerpts: null };
+  const seen = new Set();
+  for (const [index, arg] of argv.entries()) {
+    if (seen.has(index)) continue;
+    if (MODE_FLAGS.includes(arg)) {
+      if (options.mode !== null) throw fail(2, 'name exactly one of --check or --rows');
+      options.mode = arg.slice(2);
+      options.record = readValue(argv, index, arg);
+      seen.add(index + 1);
+    } else if (arg === '--excerpts') {
+      if (options.excerpts !== null) throw fail(2, '--excerpts was given twice');
+      options.excerpts = readValue(argv, index, arg);
+      seen.add(index + 1);
+    } else throw fail(2, `unknown argument: ${arg}`);
+  }
+  if (options.mode === null) throw fail(2, 'one of --check or --rows is required');
+  if (options.excerpts !== null && options.mode !== 'check') throw fail(2, '--excerpts is available only with --check');
+  return options;
+};
+
+const decodeBytes = (bytes) => {
+  try { return FATAL_UTF8.decode(bytes); }
+  catch { return null; }
+};
+const countLines = (text) => text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+const getHeadLine = (text) => Math.max(1, text.split('\n').findIndex((line) => line.replace(/\r$/u, '').startsWith('Head: ')) + 1);
+const formatFinding = (record, finding) =>
+  `${String(record).replace(/[\r\n]+/gu, ' ')}:${finding.line}: ${finding.name}: ${String(finding.message).replace(/[\r\n]+/gu, ' ')}`;
+const reportFindings = (record, findings, error) => {
+  for (const finding of findings) error(formatFinding(record, finding));
+  return findings.length === 0 ? 0 : 1;
+};
+
+const readRecord = (recordPath, io) => {
+  const result = readFileBytesNoFollowCapped(recordPath, RECORD_MAX_BYTES, io);
+  if (result.outcome !== 'ok') {
+    const reason = result.outcome === 'over-cap' ? `over the ${RECORD_MAX_BYTES}-byte cap` : result.code ?? result.className ?? result.outcome;
+    throw fail(2, `cannot read regular feedback record ${recordPath}: ${reason}`);
+  }
+  const text = decodeBytes(result.bytes);
+  if (text === null) throw fail(2, `cannot read regular feedback record ${recordPath}: invalid UTF-8`);
+  return { bytes: result.bytes, text };
+};
+
+const isContained = (root, target) => {
+  const rel = relative(root, target);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+};
+const inspectAnchors = (claims, cwd, io) => {
+  const anchors = claims.flatMap((claim) => claim.anchors);
+  const paths = [...new Set(anchors.map((anchor) => anchor.path))];
+  const facts = Object.create(null);
+  const texts = Object.create(null);
+  const targets = Object.create(null);
+  const findings = [];
+  const resolvedRoot = (() => {
+    try { return { root: realpathSync(cwd), reason: null }; }
+    catch (err) { return { root: null, reason: err?.code ?? err?.message ?? String(err) }; }
+  })();
+  if (paths.length === 0) return { anchors, facts, texts, targets, paths, findings, root: resolvedRoot.root };
+  if (resolvedRoot.root === null) {
+    for (const path of paths) {
+      facts[path] = { kind: 'regular', lines: Number.MAX_SAFE_INTEGER };
+      for (const anchor of anchors.filter((candidate) => candidate.path === path)) {
+        findings.push({ name: FINDING_NAMES.anchorPath, line: anchor.line, path, message: `the working directory cannot be resolved (${resolvedRoot.reason})` });
+      }
+    }
+    return { anchors, facts, texts, targets, paths, findings, root: resolvedRoot.root };
+  }
+  for (const path of paths) {
+    const occurrences = anchors.filter((anchor) => anchor.path === path);
+    const full = resolve(cwd, path);
+    const parent = (() => {
+      try { return realpathSync(dirname(full)); }
+      catch { return null; }
+    })();
+    if (parent === null) {
+      facts[path] = { kind: 'absent' };
+      continue;
+    }
+    const target = join(parent, basename(full));
+    if (!isContained(resolvedRoot.root, target)) {
+      facts[path] = { kind: 'regular', lines: Number.MAX_SAFE_INTEGER };
+      for (const anchor of occurrences) findings.push({ name: FINDING_NAMES.anchorPath, line: anchor.line, path, message: `anchor resolves outside the working tree: ${path}` });
+      continue;
+    }
+    const result = readFileBytesNoFollowCapped(target, RECORD_MAX_BYTES, io);
+    if (result.outcome === 'absent' || result.outcome === 'foreign') {
+      facts[path] = { kind: result.outcome === 'absent' ? 'absent' : 'other' };
+    } else if (result.outcome === 'over-cap' || result.outcome === 'error') {
+      const reason = result.outcome === 'over-cap' ? `over the ${RECORD_MAX_BYTES}-byte cap` : result.code ?? 'read failed';
+      facts[path] = { kind: 'unreadable', reason };
+    } else {
+      const text = decodeBytes(result.bytes);
+      if (text === null) facts[path] = { kind: 'unreadable', reason: 'invalid UTF-8' };
+      else {
+        facts[path] = { kind: 'regular', lines: countLines(text) };
+        texts[path] = text;
+        targets[path] = target;
+      }
+    }
+  }
+  return { anchors, facts, texts, targets, paths, findings, root: resolvedRoot.root };
+};
+
+const runGit = (spawn, cwd, env, args) => {
+  const options = {
+    cwd, env: withGitPath({
+      ...stripGitLocationEnv(env), LC_ALL: GIT_ENV_LOCALE, GIT_OPTIONAL_LOCKS: GIT_OPTIONAL_LOCKS_DISABLED,
+    }),
+    encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, windowsHide: true,
+  };
+  const attempted = (() => {
+    try { return { result: spawn('git', args, options), error: null }; }
+    catch (err) { return { result: null, error: `git threw synchronously (${err?.message ?? err})` }; }
+  })();
+  if (attempted.error !== null) return { error: attempted.error };
+  const result = attempted.result;
+  if (result == null || typeof result !== 'object') return { error: 'the git runner returned no result' };
+  if (result.error) return { error: `git could not run (${result.error.code ?? result.error.message ?? result.error})` };
+  if (result.signal) return { error: `git ${args[0]} was killed by ${result.signal}` };
+  const stderr = String(result.stderr ?? '').trim();
+  if (result.status !== 0) return { error: `git ${args[0]} exited ${result.status}${stderr ? ` (${stderr})` : ''}` };
+  const stdout = String(result.stdout ?? '');
+  if (stdout.length === 0 && !EMPTY_ANSWER_OK.has(args[0])) return { error: `git ${args[0]} answered nothing` };
+  return { stdout };
+};
+
+const parseDirtyPaths = (stdout) => stdout.split('\0').filter(Boolean).map((entry) => entry.slice(3));
+
+const inspectGit = ({ cwd, env, spawn, head, headLine, anchors }) => {
+  const findings = [];
+  const location = resolveGitLocation(cwd, { spawn, env });
+  if (location.state !== 'work-tree') {
+    return { findings: [{ name: FINDING_NAMES.gitLocation, line: headLine, message: `${location.state}: "${location.cause ?? 'unknown cause'}"` }], top: null };
+  }
+  const checkout = runGit(spawn, cwd, env, ['rev-parse', 'HEAD']);
+  if (checkout.error) return { findings: [{ name: FINDING_NAMES.gitLocation, line: headLine, message: checkout.error }], top: null };
+  const actualHead = checkout.stdout.trim();
+  if (actualHead === '') findings.push({ name: FINDING_NAMES.gitLocation, line: headLine, message: 'git rev-parse HEAD answered nothing' });
+  else if (actualHead.toLowerCase() !== head.toLowerCase()) findings.push({ name: FINDING_NAMES.headMismatch, line: headLine, message: `record head ${head} does not match checkout head ${actualHead}` });
+  const resolvedTop = (() => {
+    try { return { value: realpathSync(location.top), error: null }; }
+    catch (err) { return { value: null, error: err?.code ?? err?.message ?? String(err) }; }
+  })();
+  if (resolvedTop.error !== null) {
+    return { findings: [...findings, { name: FINDING_NAMES.gitLocation, line: headLine, message: `the work-tree top cannot be resolved (${resolvedTop.error})` }], top: location.top };
+  }
+  const top = resolvedTop.value;
+  const rels = Object.fromEntries(Object.keys(anchors.targets).map((path) => [
+    path, relative(top, resolve(anchors.root, path)).split(sep).join('/'),
+  ]));
+  if (Object.keys(rels).length === 0) return { findings, top: location.top };
+  const pathspecs = Object.values(rels).map((rel) => `:(literal)${rel}`);
+  const status = runGit(spawn, location.top, env, ['status', '--porcelain', '-z', '--untracked-files=all', '--ignored=traditional', '--', ...pathspecs]);
+  if (status.error) return { findings: [...findings, { name: FINDING_NAMES.gitLocation, line: headLine, message: `${FINDING_NAMES.anchorDirty} cannot be judged: ${status.error}` }], top: location.top };
+  const dirty = new Set(parseDirtyPaths(status.stdout));
+  const listing = runGit(spawn, location.top, env, ['ls-files', '-v', '-z', '--', ...pathspecs]);
+  if (listing.error) return { findings: [...findings, { name: FINDING_NAMES.gitLocation, line: headLine, message: `${FINDING_NAMES.anchorDirty} cannot be judged: ${listing.error}` }], top: location.top };
+  const listed = new Map();
+  for (const entry of listing.stdout.split('\0').filter(Boolean)) {
+    listed.set(entry.slice(2), entry[0]);
+  }
+  for (const path of Object.keys(rels)) {
+    const rel = rels[path];
+    const tag = listed.get(rel);
+    const message = tag === undefined
+      ? `anchor is not tracked at the stamped HEAD: ${path}`
+      : tag !== 'H'
+        ? `the index conceals the working tree for ${path} (ls-files tag ${tag})`
+        : dirty.has(rel)
+          ? `anchor differs from the stamped HEAD: ${path}`
+          : null;
+    if (message === null) continue;
+    for (const anchor of anchors.anchors.filter((candidate) => candidate.path === path)) {
+      findings.push({ name: FINDING_NAMES.anchorDirty, line: anchor.line, path, message });
+    }
+  }
+  return { findings, top: location.top };
+};
+
+const readRatchet = (cwd, rows) => {
+  const path = join(cwd, GATES_REL);
+  const parsed = (() => {
+    try { return { value: JSON.parse(readFileSync(path, 'utf8')), error: null }; }
+    catch (err) { return { value: null, error: err }; }
+  })();
+  if (parsed.error?.code === 'ENOENT') return `ratchet: ${GATES_REL} is absent`;
+  if (parsed.error) return `ratchet: ${GATES_REL} cannot be read (${parsed.error.message})`;
+  const gate = Array.isArray(parsed.value?.gates)
+    ? parsed.value.gates.find((entry) => typeof entry?.cmd === 'string' && entry.cmd.includes(QUEUE_GATE_TOKEN))
+    : null;
+  return gate ? ratchetLine(gate.cmd, rows) : `ratchet: gate carrying ${QUEUE_GATE_TOKEN} is absent`;
+};
+
+const writeExcerpts = ({ options, cwd, recordBytes, anchors, error }) => {
+  const destination = (() => {
+    try { return { value: assertScratchDestination(options.excerpts, cwd), error: null }; }
+    catch (err) { return { value: null, error: err }; }
+  })();
+  if (destination.error) {
+    error(`${FINDING_NAMES.excerptsDestination}: ${String(destination.error.message ?? destination.error).replace(/^--out/u, '--excerpts')}`);
+    return 2;
+  }
+  const budget = DEFAULT_MAX_PROMPT_BYTES - recordBytes - EXCERPTS_FRAMING_RESERVE_BYTES;
+  if (budget <= 0) return reportFindings(options.record, [{ name: FINDING_NAMES.excerptsBudget, line: 1, message: 'the record leaves no byte budget for excerpts' }], error);
+  const payload = renderExcerpts(anchors.anchors, anchors.texts, budget);
+  const trimmed = trimToBudget(payload, budget);
+  if (trimmed.trimmedBytes > 0 && !/^[^\n]/u.test(trimmed.text)) {
+    return reportFindings(options.record, [{ name: FINDING_NAMES.excerptsBudget, line: 1, message: `the ${budget}-byte budget leaves no excerpt line beside the trim marker` }], error);
+  }
+  const written = (() => {
+    try { writeFileSync(destination.value.path, trimmed.text, { flag: EXCLUSIVE_CREATE_FLAG }); return null; }
+    catch (err) { return err; }
+  })();
+  if (written === null) return 0;
+  const name = written.code === FINDING_NAMES.exists ? FINDING_NAMES.exists : FINDING_NAMES.excerptsWrite;
+  return reportFindings(options.record, [{ name, line: 1, message: written.message ?? String(written) }], error);
+};
+
+export const main = (argv, deps = {}) => {
+  const cwd = deps.cwd ?? process.cwd();
+  const env = deps.env ?? process.env;
+  const spawn = deps.spawn ?? spawnSync;
+  const log = deps.log ?? console.log;
+  const error = deps.error ?? console.error;
+  const io = deps.io ?? {};
+  const now = deps.now ?? (() => new Date());
+  const options = (() => {
+    try { return { value: parseArgv(argv), error: null }; }
+    catch (err) { return { value: null, error: err }; }
+  })();
+  if (options.error) { error(options.error.message); return options.error.exitCode ?? 2; }
+  const loaded = (() => {
+    try { return { value: readRecord(resolve(cwd, options.value.record), io), error: null }; }
+    catch (err) { return { value: null, error: err }; }
+  })();
+  if (loaded.error) { error(loaded.error.message); return loaded.error.exitCode ?? 2; }
+  const parsed = parseRecord(loaded.value.text);
+  if (parsed.refusals.some((finding) => FATAL_PARSE_REFUSALS.includes(finding.name))) {
+    return reportFindings(options.value.record, parsed.refusals, error);
+  }
+  const anchors = inspectAnchors(parsed.claims, cwd, io);
+  const git = inspectGit({ cwd, env, spawn, head: parsed.head, headLine: getHeadLine(loaded.value.text), anchors });
+  const findings = [
+    ...parsed.refusals,
+    ...anchors.findings,
+    ...judgeAnchors(parsed.claims, anchors.facts),
+    ...git.findings,
+  ];
+  if (reportFindings(options.value.record, findings, error) !== 0) return 1;
+  if (options.value.mode === 'rows') {
+    const rows = renderRows(parsed, { date: now().toISOString().slice(0, 10), recordPath: options.value.record });
+    for (const row of rows) log(row);
+    log(readRatchet(git.top, rows));
+  }
+  if (options.value.excerpts !== null) {
+    return writeExcerpts({ options: options.value, cwd, recordBytes: loaded.value.bytes.length, anchors, error });
+  }
+  return 0;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/feedback-record.mjs

@@ -0,0 +1,243 @@
+// Feedback-record grammar and pure judgments. Governing contract:
+// docs/ai/specs/kit/feedback-triage.md.
+
+const REFUSAL_NAMES = Object.freeze({
+  title: 'title', source: 'source', head: 'head', table: 'table', rowCells: 'row-cells',
+  claimId: 'claim-id', anchorGrammar: 'anchor-grammar', anchorPath: 'anchor-path',
+  verdict: 'verdict', disposition: 'disposition', anchorAbsent: 'anchor-absent',
+  anchorUnreadable: 'anchor-unreadable', anchorLine: 'anchor-line',
+});
+export const VERDICTS = Object.freeze(['confirmed', 'corrected', 'refuted', 'works-as-designed']);
+export const REFUSALS = Object.freeze(Object.values(REFUSAL_NAMES));
+
+const TITLE_PREFIX = '# Feedback: ';
+const SOURCE_PREFIX = 'Source: ';
+const HEAD_PREFIX = 'Head: ';
+const CLAIMS_HEADING = '## Claims';
+const NOTES_HEADING = '## Notes';
+const TABLE_HEADER = '| # | Claim | Evidence | Verdict | Disposition |';
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu;
+const ANCHOR = /^`([^`,\s]+):([1-9][0-9]*)(?:-([1-9][0-9]*))?`$/u;
+const ROW_ID = '[A-Z0-9][A-Z0-9-]*';
+const QUEUE = new RegExp(`^queue (${ROW_ID})$`, 'u');
+const ALREADY_QUEUED = new RegExp(`^already-queued (${ROW_ID})$`, 'u');
+const REASONED_DISPOSITION = /^(?:declined|folded): (.+)$/u;
+const LINE_JOINER = '\n';
+
+const makeRefusal = (name, line, message) => ({ name, line, message });
+const getLineNumber = (lines, index) => Math.min(index + 1, Math.max(lines.length, 1));
+const findNextContent = (lines, start) => {
+  const index = lines.findIndex((line, offset) => offset >= start && line.trim() !== '');
+  return index === -1 ? lines.length : index;
+};
+const makeFatalResult = (record, name, line, message) => ({
+  ...record, claims: [], refusals: [makeRefusal(name, line, message)],
+});
+
+const splitCells = (line) => {
+  if (!line.startsWith('|') || !line.endsWith('|')) return null;
+  const body = line.slice(1, -1);
+  const parsed = Array.from(body).reduce((state, byte, index) => {
+    if (state.skip) state.skip = false;
+    else if (byte === '\\' && body[index + 1] === '|') { state.cell += '|'; state.skip = true; }
+    else if (byte === '|') { state.cells.push(state.cell.trim()); state.cell = ''; }
+    else state.cell += byte;
+    return state;
+  }, { cells: [], cell: '', skip: false });
+  return [...parsed.cells, parsed.cell.trim()];
+};
+
+const parsesDelimiter = (line) => {
+  const cells = splitCells(line);
+  return cells?.length === 5 && cells.every((cell) => /^-{3,}$/u.test(cell));
+};
+
+const RECORD_STATES = Object.freeze([
+  { name: REFUSAL_NAMES.title, fixed: true, accepts: (line) => line.startsWith(TITLE_PREFIX) && line.slice(TITLE_PREFIX.length).trim() !== '', assigns: (record, line) => { record.title = line.slice(TITLE_PREFIX.length); }, message: `line 1 must be ${TITLE_PREFIX}<title>` },
+  { name: REFUSAL_NAMES.source, accepts: (line) => line.startsWith(SOURCE_PREFIX) && line.slice(SOURCE_PREFIX.length).trim() !== '', assigns: (record, line) => { record.source = line.slice(SOURCE_PREFIX.length); }, message: `expected ${SOURCE_PREFIX}<one line>` },
+  { name: REFUSAL_NAMES.head, accepts: (line) => line.startsWith(HEAD_PREFIX) && OBJECT_ID.test(line.slice(HEAD_PREFIX.length)), assigns: (record, line) => { record.head = line.slice(HEAD_PREFIX.length); }, message: `expected ${HEAD_PREFIX}<object id>` },
+  { name: REFUSAL_NAMES.table, accepts: (line) => line === CLAIMS_HEADING, assigns: () => {}, message: `expected ${CLAIMS_HEADING}` },
+  { name: REFUSAL_NAMES.table, accepts: (line) => line === TABLE_HEADER, assigns: () => {}, message: `expected ${TABLE_HEADER}` },
+  { name: REFUSAL_NAMES.table, accepts: parsesDelimiter, assigns: () => {}, message: 'expected a five-cell table delimiter' },
+]);
+
+const hasUnsafePath = (path) =>
+  path.startsWith('/') || path.includes('\\') || path.split('/').includes('..');
+
+const parseAnchors = (value, line) => {
+  const tokens = value.split(/,\s*/u);
+  if (tokens.length === 0 || tokens.some((token) => token === '')) {
+    return { refusal: makeRefusal(REFUSAL_NAMES.anchorGrammar, line, 'Evidence must name one or more backticked anchors') };
+  }
+  const anchors = [];
+  for (const token of tokens) {
+    const match = ANCHOR.exec(token);
+    if (!match || match[1].includes('|')) {
+      return { refusal: makeRefusal(REFUSAL_NAMES.anchorGrammar, line, `invalid anchor grammar: ${token}`) };
+    }
+    const [, path, startText, endText] = match;
+    if (hasUnsafePath(path)) {
+      return { refusal: makeRefusal(REFUSAL_NAMES.anchorPath, line, `anchor path is not repository-relative: ${path}`) };
+    }
+    const start = Number(startText);
+    const end = endText === undefined ? start : Number(endText);
+    if (start > end) {
+      return { refusal: makeRefusal(REFUSAL_NAMES.anchorGrammar, line, `anchor range starts after it ends: ${token}`) };
+    }
+    anchors.push({ path, start, end, line });
+  }
+  return { anchors };
+};
+
+const parsesDisposition = (value) =>
+  QUEUE.test(value) || ALREADY_QUEUED.test(value) || REASONED_DISPOSITION.test(value);
+
+const parseClaim = (lineText, line, expectedId) => {
+  const cells = splitCells(lineText);
+  if (cells?.length !== 5) {
+    return { refusal: makeRefusal(REFUSAL_NAMES.rowCells, line, 'claim row must contain exactly five cells') };
+  }
+  const [idText, claim, evidence, verdict, disposition] = cells;
+  if (idText !== String(expectedId)) {
+    return { refusal: makeRefusal(REFUSAL_NAMES.claimId, line, `claim id must be ${expectedId}, got ${idText || '(empty)'}`) };
+  }
+  const parsedAnchors = parseAnchors(evidence, line);
+  if (parsedAnchors.refusal) return parsedAnchors;
+  if (!VERDICTS.includes(verdict)) {
+    return { refusal: makeRefusal(REFUSAL_NAMES.verdict, line, `unknown verdict: ${verdict || '(empty)'}`) };
+  }
+  if (!parsesDisposition(disposition)) {
+    return { refusal: makeRefusal(REFUSAL_NAMES.disposition, line, `invalid disposition: ${disposition || '(empty)'}`) };
+  }
+  return {
+    claim: { id: expectedId, claim, anchors: parsedAnchors.anchors, verdict, disposition, line },
+  };
+};
+
+export const parseRecord = (text) => {
+  const lines = String(text).split('\n').map((line) => line.replace(/\r$/u, ''));
+  const record = { head: null, title: null, source: null, claims: [], refusals: [] };
+  const structure = RECORD_STATES.reduce((state, spec) => {
+    if (state.refusal !== null) return state;
+    const index = spec.fixed ? 0 : findNextContent(lines, state.index + 1);
+    const line = lines[index] ?? '';
+    if (!spec.accepts(line)) return { index, refusal: makeRefusal(spec.name, getLineNumber(lines, index), spec.message) };
+    spec.assigns(record, line);
+    return { index, refusal: null };
+  }, { index: -1, refusal: null });
+  if (structure.refusal !== null) {
+    return makeFatalResult(record, structure.refusal.name, structure.refusal.line, structure.refusal.message);
+  }
+  const delimiterIndex = structure.index;
+  const table = lines.slice(delimiterIndex + 1).reduce((state, lineText, offset) => {
+    const line = delimiterIndex + offset + 2;
+    if (state.notes || state.fatal !== null) return state;
+    if (state.done) {
+      if (lineText.trim() === '') return state;
+      if (lineText === NOTES_HEADING) return { ...state, notes: true };
+      return {
+        ...state,
+        fatal: makeRefusal(
+          REFUSAL_NAMES.table,
+          line,
+          `the claims table ended at line ${state.endedLine}; only ${NOTES_HEADING} or the end of the record may follow`,
+        ),
+      };
+    }
+    if (lineText === NOTES_HEADING) return { ...state, done: true, notes: true };
+    if (lineText.trim() === '') return { ...state, done: true, endedLine: line };
+    const parsed = parseClaim(lineText, delimiterIndex + offset + 2, state.expectedId);
+    return {
+      expectedId: state.expectedId + 1,
+      done: false,
+      notes: false,
+      endedLine: null,
+      fatal: null,
+      claims: parsed.claim ? [...state.claims, parsed.claim] : state.claims,
+      refusals: parsed.refusal ? [...state.refusals, parsed.refusal] : state.refusals,
+    };
+  }, { expectedId: 1, done: false, notes: false, endedLine: null, fatal: null, claims: [], refusals: [] });
+  if (table.fatal !== null) {
+    return makeFatalResult(record, table.fatal.name, table.fatal.line, table.fatal.message);
+  }
+  if (table.claims.length === 0 && table.refusals.length === 0) {
+    return makeFatalResult(record, REFUSAL_NAMES.table, delimiterIndex + 1, 'the claims table carries no row');
+  }
+  record.claims = table.claims;
+  record.refusals = table.refusals;
+  return record;
+};
+
+export const judgeAnchors = (claims, facts) => {
+  const findings = [];
+  for (const claim of claims) {
+    for (const anchor of claim.anchors) {
+      const fact = Object.hasOwn(facts, anchor.path) ? facts[anchor.path] : { kind: 'absent' };
+      if (fact.kind === 'absent' || fact.kind === 'other') {
+        findings.push({ name: REFUSAL_NAMES.anchorAbsent, line: anchor.line, path: anchor.path, message: `anchor is absent or not a regular file: ${anchor.path}` });
+      } else if (fact.kind === 'unreadable') {
+        findings.push({ name: REFUSAL_NAMES.anchorUnreadable, line: anchor.line, path: anchor.path, message: `anchor cannot be read: ${anchor.path} (${fact.reason ?? 'unknown reason'})` });
+      } else if (anchor.end > fact.lines) {
+        findings.push({ name: REFUSAL_NAMES.anchorLine, line: anchor.line, path: anchor.path, message: `anchor line ${anchor.end} exceeds ${fact.lines} lines in ${anchor.path}` });
+      }
+    }
+  }
+  return findings;
+};
+
+const rendersAnchor = (anchor) => `${anchor.path}:${anchor.start}${anchor.end === anchor.start ? '' : `-${anchor.end}`}`;
+
+const makeRange = (start, end) => ({
+  [Symbol.iterator]: () => {
+    const state = { next: start };
+    return {
+      next: () => state.next > end
+        ? { done: true }
+        : { done: false, value: state.next++ },
+    };
+  },
+});
+
+export const renderExcerpts = (anchors, texts, budget) => {
+  const rendered = [];
+  const state = { bytes: 0 };
+  const sources = new Map();
+  for (const anchor of anchors) {
+    if (!sources.has(anchor.path)) {
+      const text = Object.hasOwn(texts, anchor.path) ? texts[anchor.path] : '';
+      sources.set(anchor.path, String(text ?? '').split(LINE_JOINER));
+    }
+    const sourceLines = sources.get(anchor.path);
+    for (const number of makeRange(anchor.start, anchor.end)) {
+      const line = `${anchor.path}:${number}: ${sourceLines[number - 1] ?? ''}`;
+      state.bytes += Buffer.byteLength(line, 'utf8') + (rendered.length === 0 ? 0 : Buffer.byteLength(LINE_JOINER));
+      rendered.push(line);
+      if (state.bytes > budget) return rendered.join(LINE_JOINER);
+    }
+  }
+  return rendered.join(LINE_JOINER);
+};
+
+export const renderRows = (record, { date, recordPath }) => {
+  const ids = [];
+  for (const claim of record.claims) {
+    const id = QUEUE.exec(claim.disposition)?.[1];
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  return ids.map((id) => {
+    const claims = record.claims.filter((claim) => QUEUE.exec(claim.disposition)?.[1] === id);
+    return [
+      `- [ ] ${id}: ${claims[0].claim} (${date})`,
+      ...claims.map((claim) => `  - ${claim.claim}; verdict ${claim.verdict}; evidence ${claim.anchors.map(rendersAnchor).join(', ')}`),
+      `  - record: ${recordPath}`,
+      `  - head: ${record.head}`,
+    ].join('\n');
+  });
+};
+
+export const ratchetLine = (gateCmd, newRows) => {
+  const match = /(?:^|\s)--max-rows\s+([0-9]+)(?=\s|$)/u.exec(String(gateCmd));
+  if (!match) return 'ratchet: queue-audit --max-rows is absent from the gate command';
+  const current = Number(match[1]);
+  return `ratchet: queue-audit --max-rows ${current} \u2192 ${current + newRows.length}`;
+};

package/tools/inject-methodology.mjs

@@ -88,6 +88,8 @@ export const KNOWN_PRIOR_METHODOLOGY_SLOT = [
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
   // engine 4.2.0 — the two-activity pointer, before `routine` joined the named activities.
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
+  // engine 4.6.0 — the three-activity pointer, before feedback-triage joined the named activities.
+  '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution, routine) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
 ];
 export const KNOWN_PRIOR_ORCH_SLOT = [
   // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).

package/tools/orchestration-readme.mjs

@@ -50,12 +50,22 @@ const ROSTER_README = V3_README.replace(
   "a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize), or an explicit roster array such as [\"codex-review\", \"agy-review\", \"review-lens\"] in hand-edit form",
 );
 
-export const CANON_README = ROSTER_README
+const FOLD_README = ROSTER_README
   .replace("'plan-authoring' (slots author, review)", "'plan-authoring' (slots author, fold, review)")
   .replace("the carrier slots 'plan-authoring.author' and 'routine.carrier'", "the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier'")
   .replace('solo for author, execute and carrier', 'solo for author, fold, execute and carrier');
 
-export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README]);
+const FOUR_README = FOLD_README.replace(
+  "Three activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review) and 'routine' (slots carrier, parallel).",
+  "Four activities are configured independently, and so is each slot within them: 'plan-authoring' (slots author, fold, review), 'plan-execution' (slots execute, review), 'routine' (slots carrier, parallel) and 'feedback-triage' (slot review).",
+);
+
+export const CANON_README = FOUR_README.replace(
+  "The default below is 'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required.",
+  "Every slot seeded below is 'solo' — no execution backend required. A slot the seed leaves silent takes the computed default stated further down: 'feedback-triage.review' is reviewed as soon as a review backend is ready (solo until then); 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier' stay 'solo', and 'routine.parallel' stays 'on'.",
+);
+
+export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README, FOLD_README, FOUR_README]);
 
 export const refreshReadme = (config) => {
   if (config == null || typeof config !== 'object' || Array.isArray(config)) return { config, changed: false };