@sabaiway/agent-workflow-kit 10.2.0 → 10.4.0

package/tools/cheap-agents.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
-// cheap-agents.mjs — the onboarding writer behind `/agent-workflow-kit agents`: places the
-// bundled CHEAP-LANE subagent definitions (references/agents/*.md — haiku/low-effort, bounded
-// read-only tools) into a project's .claude/agents/ so mechanical work (sweeps, changelog
-// skeletons, gate triage) stops running on a frontier model by default.
+// cheap-agents.mjs — the onboarding writer behind `/agent-workflow-kit agents`: places the bundled
+// subagent definitions (references/agents/*.md) into a project's .claude/agents/. FOUR vehicles
+// grant NO shell — three ride the cheap lane (haiku/low-effort) so mechanical work (sweeps,
+// changelog skeletons, gate triage) stops running on a frontier model by default, and review-lens
+// is the read-only review opinion. The fifth, `executor`, is the ONE full-tool vehicle: dispatched
+// only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it
+// never commits. `surveyExecutorVehicle` is that vehicle's readiness, for the subagent carrier.
 //
 // The family's second `.claude/` writer, the velocity-profile.mjs writer discipline verbatim:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
@@ -25,29 +28,48 @@
 // state, not an error); 1 precondition STOP (stamp, symlink, missing bundle); 2 usage.
 // Dependency-free, Node >= 22. No side effects on import.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-export const AGENTS_DIR = '.claude/agents';
-export const CLAUDE_DIR = '.claude';
-export const WORKFLOW_STAMP = 'docs/ai/.workflow-version';
-export const EXPECTED_WORKFLOW_VERSION = '3.0.0';
-export const BUNDLED_AGENTS_DIR = resolve(HERE, '..', 'references', 'agents');
+// The READ core, never a second copy: the bundle, the placement plan and the executor survey live
+// there so the read-only advisor graph can reach them without reaching this writer.
+import {
+  AGENTS_DIR,
+  CLAUDE_DIR,
+  WORKFLOW_STAMP,
+  EXPECTED_WORKFLOW_VERSION,
+  UTF8,
+  CHEAP_AGENTS_STAMP,
+  makeCheapAgentsError,
+  readFsDeps,
+  readBundledAgents,
+  readStamp,
+  assertDirSafe,
+  planPlacement,
+} from './cheap-agents-read.mjs';
+
+export {
+  AGENTS_DIR,
+  CLAUDE_DIR,
+  WORKFLOW_STAMP,
+  EXPECTED_WORKFLOW_VERSION,
+  BUNDLED_AGENTS_DIR,
+  CHEAP_AGENTS_STAMP,
+  CHEAP_AGENTS_SYMLINK,
+  CHEAP_AGENTS_BUNDLE,
+  makeCheapAgentsError,
+  readBundledAgents,
+  planPlacement,
+  surveyExecutorVehicle,
+  EXECUTOR_VEHICLE,
+  EXECUTOR_VEHICLE_REL,
+} from './cheap-agents-read.mjs';
 
 const EXIT_OK = 0;
 const EXIT_PRECONDITION = 1;
 const EXIT_USAGE = 2;
-const UTF8 = 'utf8';
-const ERROR_PREFIX = '[agent-workflow-kit]';
-
-export const CHEAP_AGENTS_STAMP = 'CHEAP_AGENTS_STAMP';
-export const CHEAP_AGENTS_SYMLINK = 'CHEAP_AGENTS_SYMLINK';
-export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
 
 // The fallback-lens contract, formalized where it lives (flow-orchestration #15/#3, Phase 4.3):
 // the internal-attestation evaluation consumes this sentence — a lens set claiming a configured
@@ -57,95 +79,24 @@ export const FALLBACK_LENS_ADDITIONAL_ONLY = 'review-lens is an ADDITIONAL read-
 
 const USAGE = `usage: cheap-agents [--dry-run | --apply] [--cwd <dir>] [--help]
 
-Places the bundled READ-ONLY subagent definitions into the project's ${AGENTS_DIR}/. No vehicle
-grants a shell: three ride a cheap model (haiku/low) for mechanical work — extraction sweeps,
-changelog fact-skeletons, gate triage — and review-lens is a read-only REVIEW vehicle on a
-review-capable model. Default is --dry-run (a preview; writes nothing). --apply writes.
+Places the bundled subagent definitions into the project's ${AGENTS_DIR}/. Four vehicles grant NO
+shell: three ride a cheap model (haiku/low) for mechanical work — extraction sweeps, changelog
+fact-skeletons, gate triage — and review-lens is a read-only REVIEW vehicle on a review-capable
+model. The fifth, executor, is the ONE full-tool vehicle: dispatched only for a bounded execution,
+authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and
+it never commits.
+Default is --dry-run (a preview; writes nothing). --apply writes.
 An existing file with DIFFERENT content is preserved and reported, never overwritten.`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
-export const makeCheapAgentsError = (code, message) =>
-  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'CheapAgentsError', code, exitCode: EXIT_PRECONDITION });
-
-const fsDeps = (deps = {}) => ({
-  exists: deps.exists ?? existsSync,
-  lstat: deps.lstat ?? lstatSync,
+const writeFsDeps = (deps = {}) => ({
   mkdir: deps.mkdir ?? mkdirSync,
-  readFile: deps.readFile ?? readFileSync,
   writeFile: deps.writeFile ?? writeFileSync,
-  readdir: deps.readdir ?? readdirSync,
 });
 
-const lstatNoFollow = (absPath, fs) => {
-  try {
-    return fs.lstat(absPath);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-};
-
-// ── the bundle (the kit's own references/agents/) ─────────────────────────────────────
-
-export const readBundledAgents = (deps = {}) => {
-  const fs = fsDeps(deps);
-  const bundleDir = deps.bundleDir ?? BUNDLED_AGENTS_DIR;
-  let names;
-  try {
-    names = fs.readdir(bundleDir);
-  } catch (err) {
-    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `bundled agents dir unreadable (${err.code ?? err.message}): ${bundleDir}`);
-  }
-  const templates = names
-    .filter((name) => name.endsWith('.md'))
-    .sort()
-    .map((name) => ({ name, content: fs.readFile(join(bundleDir, name), UTF8) }));
-  if (templates.length === 0) {
-    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `no bundled agent templates found in ${bundleDir} — the kit install is incomplete`);
-  }
-  return templates;
-};
-
-// ── preflight (velocity discipline: symlink-safe, stamp read, no writes) ──────────────
-
-const readStamp = (absPath, fs) => {
-  try {
-    if (!fs.exists(absPath)) return null;
-    const stamp = String(fs.readFile(absPath, UTF8)).trim();
-    return stamp.length ? stamp : null;
-  } catch {
-    return null; // unreadable stamp == not a valid deployment stamp (apply STOPs; dry-run reports)
-  }
-};
-
-const assertDirSafe = (absPath, relPath, fs) => {
-  const stat = lstatNoFollow(absPath, fs);
-  if (stat === null) return { absent: true };
-  if (stat.isSymbolicLink()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} is a symlink — refusing to write through it`);
-  if (!stat.isDirectory()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} exists but is not a directory — refusing to write through it`);
-  return { absent: false };
-};
-
-// Per-template placement plan: place | already-current | customized-preserved (never clobbered).
-export const planPlacement = (templates, projectDir, deps = {}) => {
-  const fs = fsDeps(deps);
-  return templates.map((template) => {
-    const rel = `${AGENTS_DIR}/${template.name}`;
-    const abs = join(projectDir, AGENTS_DIR, template.name);
-    const stat = lstatNoFollow(abs, fs);
-    if (stat === null) return { ...template, rel, abs, action: 'place' };
-    if (stat.isSymbolicLink() || !stat.isFile()) {
-      throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${rel} exists but is not a regular file — refusing to touch it`);
-    }
-    const existing = fs.readFile(abs, UTF8);
-    if (existing === template.content) return { ...template, rel, abs, action: 'already-current' };
-    return { ...template, rel, abs, action: 'customized-preserved' };
-  });
-};
-
 export const preflightCheapAgents = ({ cwd }, deps = {}) => {
-  const fs = fsDeps(deps);
+  const fs = readFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
   const templates = readBundledAgents(deps);
   const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
@@ -159,7 +110,7 @@ export const preflightCheapAgents = ({ cwd }, deps = {}) => {
 // ── the writer ────────────────────────────────────────────────────────────────────────
 
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
-  const fs = fsDeps(deps);
+  const fs = writeFsDeps(deps);
   const preflight = preflightCheapAgents({ cwd }, deps);
   if (dryRun) return { wrote: false, dryRun: true, ...preflight };
 
@@ -186,8 +137,8 @@ const ACTION_LABEL = {
 export const formatResult = (result) => {
   const lines = [
     result.dryRun
-      ? 'agent-workflow read-only subagents — DRY RUN (no changes)'
-      : 'agent-workflow read-only subagents — APPLY',
+      ? 'agent-workflow subagent vehicles — DRY RUN (no changes)'
+      : 'agent-workflow subagent vehicles — APPLY',
   ];
   for (const item of result.plan) {
     const verb = result.dryRun && item.action === 'place' ? 'would place' : ACTION_LABEL[item.action];
@@ -197,8 +148,9 @@ export const formatResult = (result) => {
     lines.push(`note: no current deployment stamp found (${result.stamp ?? 'none'}) — --apply will refuse until init/upgrade runs.`);
   }
   lines.push(
-    'the vehicles are Claude Code subagents with READ-ONLY tools and NO shell — so a fan-out can never turn into a wave of approval prompts.',
-    `three ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY} Writing code and running gates stay on your main lane.`,
+    'four vehicles are Claude Code subagents with READ-ONLY tools and NO shell — so a fan-out can never turn into a wave of approval prompts.',
+    `three of those ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY}`,
+    'executor is the one FULL-TOOL vehicle: dispatched only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it never commits.',
   );
   // A preview must print the EXACT command that applies it. The advisor renders this dry-run as an
   // item's one-liner, and that flow's contract is "run the printed command, no improvisation" — a

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('agents'),
     group: 'Configure',
     kind: WRITER,
-    oneLine: 'Place bundled READ-ONLY subagent definitions, none of them granted a shell — three cheap-model ones for mechanical work (sweeps, changelog skeletons, gate triage) and a review lens (Claude Code; opt-in; preview first).',
+    oneLine: 'Place the bundled subagent vehicles: four read-only ones, none granted a shell — three cheap-model ones for mechanical work (sweeps, changelog skeletons, gate triage) and a review lens — plus the one full-tool executor that carries bounded slices you verify (Claude Code; opt-in; preview first).',
   },
   {
     key: 'hook',
@@ -180,7 +180,7 @@ const CATALOG = [
     invocation: invocationOf('recipes'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated), which one fits this environment, and the configured per-activity line to paste at session start.',
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated / Subagent), which one fits this environment, and the configured per-activity line to paste at session start.',
   },
   {
     key: 'procedures',
@@ -341,7 +341,7 @@ const TUNE_TAIL = Object.freeze([
   '',
   'Tune — opt-in accelerators (consent-first: every writer previews before writing; nothing runs without your yes)',
   `  ${BARE_INVOCATION} velocity      routine read-only commands stop prompting (incl. the --kit-tools tier for the kit's own read-only tools)`,
-  `  ${BARE_INVOCATION} agents        shell-free subagents: cheap ones take the mechanical work, a review lens gives an extra read-only opinion`,
+  `  ${BARE_INVOCATION} agents        subagent vehicles: four read-only (cheap ones take the mechanical work, a review lens gives another opinion) + the one full-tool executor that carries bounded slices you verify`,
   `  ${BARE_INVOCATION} gates         run your declared gates (docs/ai/gates.json) as one batch; its guide also offers the consent-gated seeding preview — writes only on your yes`,
   `  ${BARE_INVOCATION} hook          auto-approve exactly your declared gate commands (byte-exact matches only)`,
   `  ${BARE_INVOCATION} set-recipe    put a ready review backend to work on plans and diffs`,

package/tools/direct-run.mjs

@@ -56,6 +56,12 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   // Named by references/modes/mcp.md as the read half the advisor and uninstall ask. It only ever
   // REPORTS; the command that acts on what it reports is the mode itself.
   'mcp-registration.mjs': '/agent-workflow-kit mcp',
+  // Named by references/modes/set-recipe.md as the activity/slot registry; the command that shows
+  // the recipes it defines, resolved for this environment, is the recipes advisor.
+  'carriers.mjs': '/agent-workflow-kit recipes',
+  // The READ core of the subagent-vehicle surface: it sits one name away from the writer
+  // references/modes/agents.md DOES name, and reaching for it is reaching for the agents mode.
+  'cheap-agents-read.mjs': '/agent-workflow-kit agents',
 });
 
 // The frozen refusal line. One line, names the module, names the command.

package/tools/doc-parity.mjs

@@ -72,6 +72,8 @@ import { RELAYED_ENSURE_TOKENS, RELAYED_FAILURE_CAUSES } from './ensure-vocabula
 // The MCP registration's four public strings. Imported from the READ-ONLY leaf, never from the
 // writer: a read-only lint must not pull the atomic-write core into its import graph.
 import { ENABLED_KEY as MCP_ENABLED_KEY, MCP_JSON_REL, SERVER_NAME as MCP_SERVER_NAME, allowRulesFor } from './mcp-registration.mjs';
+// The spec-adoption state tokens the status mode doc must name (contract: kit/spec-adoption).
+import { ADOPTION_STATES, SPEC_ADOPTION_LANE } from './spec-adoption.mjs';
 
 const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
@@ -86,6 +88,7 @@ const RECEIPT_DEADLINE_DOC = 'references/modes/receipt-deadline.md';
 const GATES_DOC = 'references/modes/gates.md';
 const MCP_DOC = 'references/modes/mcp.md';
 const UNINSTALL_DOC = 'references/modes/uninstall.md';
+const STATUS_DOC = 'references/modes/status.md';
 // One literal for the dispatch mode doc: the structure leaf already names it as the file it anchors
 // its table in, and a second copy here is exactly the drift this lint exists to catch.
 const DISPATCH_DOC = ADVISOR_MATRIX_DOC;
@@ -236,6 +239,11 @@ export const BINDINGS = Object.freeze([
   valueBinding('mcp-enabled-key', MCP_ENABLED_KEY, `\`${MCP_ENABLED_KEY}\``, [MCP_DOC, UNINSTALL_DOC]),
   valueBinding('mcp-server-name', MCP_SERVER_NAME, `\`"${MCP_SERVER_NAME}"\``, [MCP_DOC, UNINSTALL_DOC]),
   ...allowRulesFor().map((rule) => valueBinding(`mcp-allow-rule:${rule}`, rule, `\`${rule}\``, [MCP_DOC, UNINSTALL_DOC])),
+  // The spec-adoption state tokens: status.md renders a plain phrase per token, so the doc must name
+  // every token the survey can answer — a fifth state added to the leaf with no phrase fails here.
+  // The decline lane rides both the status line and the advisor item, so both docs name it.
+  ...ADOPTION_STATES.map((state) => valueBinding(`spec-adoption:${state}`, state, `\`${state}\``, [STATUS_DOC])),
+  valueBinding('spec-adoption-lane', SPEC_ADOPTION_LANE, `--lane ${SPEC_ADOPTION_LANE}`, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/ensure-ops.mjs

@@ -16,8 +16,8 @@
 //   • 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
+//   • Every token names a state this run PROVED. `already-present` follows a probe; `skipped-no-node-evidence`
+//     names every Node probe that answered absent; 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.
@@ -34,6 +34,7 @@ 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';
+import { NODE_EVIDENCE, describeNodeProbes, probeNodeEvidence } from './node-evidence.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
@@ -49,7 +50,6 @@ export {
   WRITE_TOKENS,
 } from './ensure-vocabulary.mjs';
 
-const PACKAGE_JSON = 'package.json';
 const SCRIPTS_DIR = 'scripts';
 
 const outcome = (op, token, lines, failed = false) => {
@@ -204,9 +204,19 @@ export const ensureAutonomy = ({ cwd, kitRoot, dryRun = false, 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.
-export const isNodeProject = (cwd, lstat) => lstatNoFollow(join(cwd, PACKAGE_JSON), lstat) !== null;
+// The Node-evidence refusal every ensure that places Node scripts shares (contract: kit/node-evidence):
+// null when Node provably runs here, else the ONE outcome the caller returns — a stated skip naming the
+// probes that answered absent, or a fail-closed failure when a probe could not be read.
+export const nodeEvidenceRefusal = (op, cwd, lstat) => {
+  const evidence = probeNodeEvidence(cwd, lstat);
+  if (evidence.state === NODE_EVIDENCE.UNREADABLE) {
+    return loud(op, 'node-evidence-unverifiable', `${SCRIPTS_DIR}/: whether Node runs here could not be read (${evidence.error}), so nothing was written — resolve it by hand, then re-run`);
+  }
+  if (evidence.state === NODE_EVIDENCE.NONE) {
+    return ok(op, 'skipped-no-node-evidence', `${SCRIPTS_DIR}/: no Node evidence in this tree — probed ${describeNodeProbes(evidence)}, no regular file present; the seeded pairs are Node enforcement, so nothing written`);
+  }
+  return null;
+};
 
 const OLD_ADR_LAYOUTS = new Set(['old', 'old-unrotated']);
 
@@ -221,9 +231,8 @@ const partialNote = (lines) => {
 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`);
-  }
+  const refusal = nodeEvidenceRefusal('scripts', cwd, lstat);
+  if (refusal) return refusal;
   let layout;
   try {
     layout = surveyAdrLayoutStrict(cwd, deps);

package/tools/ensure-specs.mjs

@@ -26,7 +26,7 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { writeContainedFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
 import { classifyDeployedScript } from './script-priors.mjs';
-import { composeFailure, composeOutcome, isNodeProject, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+import { composeFailure, composeOutcome, nodeEvidenceRefusal, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
 
 const OP = 'specs';
 const SCRIPTS_DIR = 'scripts';
@@ -159,9 +159,8 @@ const renderStoreRoot = (kitRoot, read, today) => {
 export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFileSync;
-  if (!isNodeProject(cwd, lstat)) {
-    return ok('skipped-no-node', [`${SCRIPTS_DIR}/: no package.json at the project root — the spec reader and checker are Node scripts; nothing written`]);
-  }
+  const refusal = nodeEvidenceRefusal(OP, cwd, lstat);
+  if (refusal) return refusal;
   const survey = (name) => surveyScript({ cwd, kitRoot, name, read, lstat });
   const reader = READER_PAIR.map(survey);
   const checker = CHECKER_PAIR.map(survey);

package/tools/ensure-vocabulary.mjs

@@ -31,7 +31,7 @@ export const ENSURE_TOKENS = Object.freeze([
   'already-present',
   'customized-preserved',
   'malformed-preserved',
-  'skipped-no-node',
+  'skipped-no-node-evidence',
   'old-adr-layout-migration-instructed',
   'failed',
 ]);
@@ -44,6 +44,9 @@ export const FAILURE_CAUSES = Object.freeze([
   'template-unreadable',
   'bundle-unreadable',
   'adr-layout-unverifiable',
+  // A Node probe (package.json, a kit-seeded script) failed with anything but ENOENT: whether Node runs
+  // here is unproven, so the ensures that place Node scripts write nothing (contract: kit/node-evidence).
+  'node-evidence-unverifiable',
   'wrong-node-kind',
   'write-refused',
   'unexpected-error',
@@ -75,7 +78,7 @@ export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'customized-preserved',
   'malformed-preserved',
   'already-present',
-  'skipped-no-node',
+  'skipped-no-node-evidence',
   'old-adr-layout-migration-instructed',
   'failed',
 ]);

package/tools/family-registry.mjs

@@ -28,7 +28,7 @@ import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
-import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
+import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
 import { loadConfig } from './orchestration-config.mjs';
@@ -52,9 +52,10 @@ import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mj
 // writer, which pulls in the atomic-write core) so the status survey stays a pure reader.
 import { settingsSnapshot } from './bridge-settings-read.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
-// The cheap-agents writer's own bundle reader + placement planner — reused by the settings survey
-// (one implementation, never a drifting copy; cheap-agents imports only node builtins, no cycle).
-import { readBundledAgents, planPlacement } from './cheap-agents.mjs';
+// The cheap-agents READ core's bundle reader, placement planner and executor-vehicle survey —
+// reused by the settings survey (one implementation, never a drifting copy; the read core imports
+// only node builtins, no cycle).
+import { readBundledAgents, planPlacement, surveyExecutorVehicle, EXECUTOR_VEHICLE, assertDirSafe, readFsDeps, CLAUDE_DIR, AGENTS_DIR } from './cheap-agents-read.mjs';
 // The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
 // forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
 // nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
@@ -82,6 +83,8 @@ import {
 import { detectSurface } from './surface.mjs';
 import { toViewModel } from './view-model.mjs';
 import { render } from './renderers.mjs';
+// The feature-spec adoption state (contract: kit/spec-adoption) — read-only leaves, no cycle.
+import { ADOPTION, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
 
 // ── manifestState values — re-export the EXACT public subset family-registry exported before B1 ─────
 // (the 7 state constants + DISPLAY_NAMES) so every existing importer (uninstall.mjs, the test suites)
@@ -428,9 +431,33 @@ const surveyAdrLayout = (dir, deps) => {
   }
 };
 
+// The spec-adoption survey, LENIENT for the read-only view — two facts, each failing on its own: a
+// survey that throws becomes the `unreadable` state with its reason, and an ack read that throws
+// keeps the store state and carries `declineError` beside `declined: false` — the status line still
+// renders, never a crash, never a silent "not adopted" and never a decline it could not read.
+const surveySpecs = (dir, deps) => {
+  const survey = (() => {
+    try {
+      return surveySpecAdoption(dir, deps);
+    } catch (err) {
+      return { state: ADOPTION.UNREADABLE, live: 0, draft: 0, reason: localizeError(err) };
+    }
+  })();
+  const decline = (() => {
+    if (survey.state === ADOPTION.ADOPTED) return { declined: false, declineError: null };
+    try {
+      return { declined: readDeclineAck(dir, deps), declineError: null };
+    } catch (err) {
+      return { declined: false, declineError: localizeError(err) };
+    }
+  })();
+  return { state: survey.state, live: survey.live, draft: survey.draft, reason: survey.reason, ...decline };
+};
+
 // surveyProject → the deploy axis for a target project dir: the per-member deployment stamps, whether
-// docs/ai/ exists, the ADR-store layout, and whether the hidden-mode fence is present. Pure (fs reads
-// only, all injectable), no git subprocess — the read-only `status` view must never mutate or spawn.
+// docs/ai/ exists, the ADR-store layout, the spec-adoption state, and whether the hidden-mode fence is
+// present. Pure (fs reads only, all injectable), no git subprocess — the read-only `status` view must
+// never mutate or spawn.
 export const surveyProject = (projectDir, deps = {}) => {
   const exists = deps.exists ?? existsSync;
   const dir = resolve(projectDir);
@@ -445,7 +472,7 @@ export const surveyProject = (projectDir, deps = {}) => {
     }
   })();
   const deployed = stamps.some((s) => s.version != null) || docsAiPresent;
-  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, deps), hiddenFence: hasHiddenFence(dir, deps), stamps };
+  return { dir, deployed, docsAiPresent, adrLayout: surveyAdrLayout(dir, deps), specs: surveySpecs(dir, deps), hiddenFence: hasHiddenFence(dir, deps), stamps };
 };
 
 // ── report ───────────────────────────────────────────────────────────────────────
@@ -460,9 +487,6 @@ export const surveyProject = (projectDir, deps = {}) => {
 // consumes THIS, never the human table verbatim. An envelope-shape test pins its shape so later phases
 // (the settings/visibility block) can't silently break the Phase-2 version consumer.
 
-// STATE_PUBLIC (internal→public token map) + DISPLAY_NAMES + displayOf now live in labels.mjs (B1) —
-// imported at the top of this file. They are used below exactly as before.
-
 // ── the settings survey (Phase 3) — read-only, honest, localized-on-error ──────────
 // Each sub-survey returns a small user-safe object OR a single `{ error }` field (a localized message,
 // never a crash): a malformed/unreadable file in ONE area must not break the rest of `status`. The
@@ -501,19 +525,21 @@ export const surveyVisibility = (dir, deps = {}) => {
 };
 
 // orchestration recipes: the EFFECTIVE recipe per slot (config · default · effective), engine-free —
-// shared loadConfig + resolveActivityRecipe + the read-only backend detector. A malformed config → a
-// localized error field; a detection failure floors at solo (a corrupt bridge must not break the view).
+// shared loadConfig + resolveActivityRecipe + the ONE readiness composition (detected backends +
+// the executor vehicle). A malformed config → a localized error field; a detection failure floors
+// at solo (a corrupt bridge must not break the view) but is surfaced as `detectError`, so the
+// render says "couldn't check backends" instead of letting a real solo-default look identical.
 export const surveyRecipes = (dir, deps = {}) => {
-  // A detector failure floors recipes at solo (mirrors procedures) but is surfaced as `detectError`, so
-  // the render says "couldn't check backends" instead of letting a real solo-default look identical.
   const { detection, error: detectError } = detectSafe(deps);
+  const projectDir = resolve(dir);
+  const readiness = composeReadiness(projectDir, { ...deps, detect: () => detection });
   try {
-    const { config, source } = loadConfig(resolve(dir), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const { config, source } = loadConfig(projectDir, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
     const activities = {};
     for (const [activity, def] of Object.entries(ACTIVITIES)) {
       activities[activity] = {};
       for (const slot of Object.keys(def.slots)) {
-        const r = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot });
+        const r = resolveActivityRecipe({ config: config ?? {}, readiness, activity, slot });
         activities[activity][slot] = { recipe: r.recipe, source: r.source, degradedFrom: r.degradedFrom ?? null };
       }
     }
@@ -590,14 +616,34 @@ export const surveyGateHook = (dir, deps = {}) => {
 };
 
 // cheap agents: the kit-placed .claude/agents/ vehicles (Mode: agents) — how many of the bundled
-// cheap-lane definitions are present in the project. A customized copy counts as PLACED (it exists;
-// the writer preserves it) — the welcome-mat agents rung keys on zero placed. Read-only; REUSES the
-// writer's own bundle reader + placement planner (cheap-agents.mjs — one implementation).
+// definitions are present in the project, plus the ONE full-tool vehicle's own state. A customized
+// copy counts as PLACED (it exists; the writer preserves it) — the welcome-mat agents rung keys on
+// zero placed, so the counts span every vehicle, the executor included. The executor state comes
+// from the read core's survey (the subagent carrier's one instrument — one implementation), which
+// answers a state instead of throwing; its reason rides along when it carries one.
 export const surveyCheapAgents = (dir, deps = {}) => {
   try {
+    const projectDir = resolve(dir);
     const templates = readBundledAgents(deps);
-    const plan = planPlacement(templates, resolve(dir), deps);
-    return { bundled: templates.length, placed: plan.filter((p) => p.action !== 'place').length };
+    const vehicle = (deps.surveyVehicle ?? surveyExecutorVehicle)(projectDir, deps);
+    // The executor is judged by its own survey (which answers a state where the placement plan
+    // would throw); the plan covers the read-only vehicles, so a broken executor never hides them,
+    // and it never follows a symlinked ancestor — the writer's own guard refuses first.
+    const executor = { executor: vehicle.state, ...(vehicle.reason ? { executorReason: safeLine(vehicle.reason) } : {}) };
+    try {
+      const fs = readFsDeps(deps);
+      assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+      assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
+      const plan = planPlacement(templates.filter((t) => t.name !== EXECUTOR_VEHICLE), projectDir, deps);
+      return {
+        bundled: templates.length,
+        readOnly: templates.filter((t) => t.name !== EXECUTOR_VEHICLE).length,
+        placed: plan.filter((p) => p.action !== 'place').length + (['placed', 'customized'].includes(vehicle.state) ? 1 : 0),
+        ...executor,
+      };
+    } catch (err) {
+      return { error: localizeError(err), ...executor };
+    }
   } catch (err) {
     return { error: localizeError(err) };
   }
@@ -683,6 +729,9 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       deployed: project.deployed,
       docsAi: project.docsAiPresent,
       adrLayout: project.adrLayout, // 'old' | 'old-unrotated' | 'migrated' | 'none' — a user-safe token, never a raw path
+      // { state: not-adopted | adopting | adopted | unreadable, live, draft, reason, declined, declineError }
+      // — an envelope predating the field omits it (the view-model reads that as unknown, never as a state).
+      ...(project.specs ? { specs: project.specs } : {}),
       // member + display + version only — never the internal stamp FILENAME (s.file).
       deployStamps: project.stamps.map((s) => ({ member: s.name, display: displayOf(s.name), version: s.version ?? null })),
     };

package/tools/flow-check.mjs

@@ -29,8 +29,7 @@ import {
   resolveReceiptsPath, readReceipts, computeTreeFingerprint,
 } from './core-evidence.mjs';
 import { loadConfig } from './orchestration-config.mjs';
-import { requiredBackendsForConfiguredRecipe, DISPLAY_ALIASES } from './recipes.mjs';
-import { detectBackends } from './detect-backends.mjs';
+import { requiredBackendsForConfiguredRecipe, DISPLAY_ALIASES, composeReadiness } from './recipes.mjs';
 import { decideFlowCheck } from './flow-check-cores.mjs';
 import { short } from './flow-check-rungs.mjs';
 import {
@@ -116,11 +115,7 @@ export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', pr
     let readiness = [];
     let detectionFailed = false;
     if (configFailure == null && config?.['plan-execution']?.review == null) {
-      try {
-        readiness = detectBackends();
-      } catch {
-        detectionFailed = true;
-      }
+      readiness = composeReadiness(top, { ...probes, onDetectError: () => { detectionFailed = true; } });
     }
     const obligations = configFailure == null
       ? requiredBackendsForConfiguredRecipe({ config, readiness, detectionFailed })

package/tools/inject-methodology.mjs

@@ -86,10 +86,14 @@ 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.',
   // engine 2.1.0 — the pre-canon-rewrite pointer (vocabulary + plan-then-execute wording, with the communication contract).
   '> **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).',
 ];
 export const KNOWN_PRIOR_ORCH_SLOT = [
   // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).
   '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs.',
+  // engine 4.2.0 — the four-recipe pointer with the read-at-start clause, before the Subagent carrier joined the list.
+  '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs. At the start of a planning/execution session, read your standing recipe preference in `docs/ai/orchestration.json` — set it in plain language with `/agent-workflow-kit set-recipe` (previews first; hand-edit stays supported).',
 ];
 
 // A slot descriptor bundles everything the generic engine needs to operate on ONE marker pair.

package/tools/lens-region.mjs

@@ -62,7 +62,10 @@ Apply this as part of §2 before any user-facing summary:
 - **No condescension, no filler.** Own a miss plainly and fix it in the same message.
 - **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.`;
-export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE];
+// The canon that shipped between the closing-state-block contract and the contradicted-skip bullet.
+const COMMS_PRIOR_STATE_BLOCK = `${COMMS_PRIOR_PLAIN_LANGUAGE}
+- **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.`;
+export const COMMS_PRIORS = [COMMS_PRIOR_PRE_AD054, COMMS_PRIOR_AD054, COMMS_PRIOR_PLAIN_LANGUAGE, COMMS_PRIOR_STATE_BLOCK];
 
 const stripCr = (line) => (line.endsWith('\r') ? line.slice(0, -1) : line);
 const isBoundary = (bareLine) => bareLine === '---' || /^#{2,3} /.test(bareLine);