@sabaiway/agent-workflow-kit 10.2.0 → 10.4.0

package/tools/set-recipe.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // set-recipe.mjs — the WRITER for docs/ai/orchestration.json. The division of labor (AD-025): the AGENT
-// turns plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset <activity>.<slot>`
+// turns plain language into explicit `--set <activity>.<slot>=<value>` / `--unset <activity>.<slot>`
 // ops; the KIT does the deterministic validate → merge → preview → write. The kit ships NO NL parser
 // (stays dependency-free + deterministic) and performs no `all`-magic — the agent expands "both review"
 // into explicit per-activity ops (asking if scope is unclear).
@@ -17,15 +17,25 @@
 // language when narrating. Exit codes: 0 success (an explicit recipe that gracefully degrades is still
 // 0); 2 usage (bad/duplicate op, --write with zero ops); 1 config error (malformed/unreadable config)
 // or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
-// env / home / detect / fs are injectable for host-independent tests.
+// env / home / detect / surveyVehicle / fs are injectable for host-independent tests.
+//
+// It writes every slot of every activity in the registry (carriers.mjs, via recipes.mjs) — the
+// carrier slots and the `routine.parallel` switch included — and resolves each preview against the
+// SAME readiness the recipes advisor composes: detected backends plus the executor-vehicle survey.
 //
 // Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { resolveActivityRecipe, composeActiveRecipeLine } from './recipes.mjs';
+import {
+  ACTIVITIES,
+  SLOT_RECIPES,
+  EXECUTOR_APPLY,
+  composeReadiness,
+  resolveActivityRecipe,
+  composeActiveRecipeLine,
+} from './recipes.mjs';
 import { loadAutonomy, resolveAutonomy } from './autonomy-config.mjs';
 import {
   CONFIG_REL,
@@ -35,6 +45,7 @@ import {
   parseOp,
   applySetOps,
   serializeConfig,
+  refreshReadme,
   CANON_README,
 } from './orchestration-config.mjs';
 import { writeConfig as writeConfigFs } from './orchestration-write.mjs';
@@ -50,7 +61,7 @@ const parseArgs = (argv) => {
   let write = false;
   let json = false;
   const takeOp = (kind, tok) => {
-    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<recipe>' : ''}`);
+    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<value>' : ''}`);
     const op = parseOp(kind, tok);
     const key = `${op.activity}.${op.slot}`;
     if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each activity.slot at most once`);
@@ -74,12 +85,24 @@ const parseArgs = (argv) => {
 
 // ── effective-recipe resolution per op (degradation honesty) ────────────────────────
 
+// The readiness EVERY resolution here runs against: the detected bridges plus the executor-vehicle
+// survey, composed by the one helper the recipes CLI uses. Detection is a SECONDARY input — a bridge
+// detector throw must NOT block the write (the config write is readiness-independent) and must not
+// cost the CARRIER either: the hook warns, the bridge half floors at not-ready, the vehicle survives.
+const composeReadinessOrWarn = (cwd, deps, warnings) =>
+  composeReadiness(cwd, {
+    ...deps,
+    onDetectError: (err) => warnings.push(
+      `backend detection failed (${(err && err.message) || err}) — treating every bridge as not ready; recipes needing a bridge degrade to solo (the executor vehicle is unaffected).`,
+    ),
+  });
+
 // A single op's before/after value + the effective recipe it resolves to here (vs live readiness).
 // `to` is null for an unset (falls to the computed default). degradedFrom/reason carry the honesty.
-const resolveOp = (op, current, after, detection) => {
+const resolveOp = (op, current, after, readiness) => {
   const from = current?.[op.activity]?.[op.slot] ?? null;
   const to = after?.[op.activity]?.[op.slot] ?? null;
-  const r = resolveActivityRecipe({ config: after ?? {}, readiness: detection, activity: op.activity, slot: op.slot });
+  const r = resolveActivityRecipe({ config: after ?? {}, readiness, activity: op.activity, slot: op.slot });
   return { activity: op.activity, slot: op.slot, from, to, effective: r.recipe, degradedFrom: r.degradedFrom, reason: r.reason };
 };
 
@@ -127,19 +150,40 @@ const buildJson = ({ changed, unchanged, warnings, writtenPath, noop, activeLine
   activeLine: activeLine ?? null,
 });
 
+// The writable surface, rendered FROM the registry — never re-typed as literals, so an activity, a
+// slot or an accepted value added to the table shows up in the help (and in the doc that quotes it).
+const ACTIVITY_LINES = Object.entries(ACTIVITIES)
+  .map(([activity, def]) => `  ${activity} → ${Object.keys(def.slots).join(', ')}`)
+  .join('\n');
+
+const VALUE_LINES = Object.entries(SLOT_RECIPES)
+  .map(([slotType, values]) => `  ${slotType} slots accept ${values.join(' | ')}`)
+  .join('\n');
+
+const QUALIFIED_SLOTS = Object.entries(ACTIVITIES)
+  .flatMap(([activity, def]) => Object.keys(def.slots).map((slot) => `${activity}.${slot}`))
+  .join(', ');
+
 const HELP = `set-recipe — write the per-project orchestration config (docs/ai/orchestration.json).
 
 Usage:
-  node set-recipe.mjs [--set <activity>.<slot>=<recipe>]... [--unset <activity>.<slot>]... [--write] [--json]
+  node set-recipe.mjs [--set <activity>.<slot>=<value>]... [--unset <activity>.<slot>]... [--write] [--json]
 
-  --set    <activity>.<slot>=<recipe>   pin a recipe (fully-qualified; e.g. plan-authoring.review=council)
+  --set    <activity>.<slot>=<value>   pin a value (fully-qualified; e.g. plan-authoring.review=council)
   --unset  <activity>.<slot>            return a slot to its computed default
   --write                               apply the change (default: preview only — writes nothing)
   --json                                machine-readable output
   --help, -h                            this help
 
-Activities/slots: plan-authoring → review;  plan-execution → execute, review
-Recipes:          review accepts solo|reviewed|council;  execute accepts solo|delegated
+Activities and their slots:
+${ACTIVITY_LINES}
+
+Accepted values per slot type:
+${VALUE_LINES}
+
+A carrier slot set to subagent needs the executor vehicle placed in this project — ${EXECUTOR_APPLY};
+without it the slot resolves to solo with the reason stated. routine.parallel is a flag, not a
+recipe: it never degrades.
 
 Previews by default; --write applies via an atomic, symlink/TOCTOU-safe write behind a deployment gate.
 Config writer only: it NEVER runs a backend and NEVER commits. Hand-editing the file stays fully supported.
@@ -152,7 +196,7 @@ Exit codes: 0 success (an explicit recipe that gracefully degrades is still 0);
 
 export const main = (argv, ctx = {}) => {
   const cwd = ctx.cwd ?? process.cwd();
-  const detect = ctx.detect ?? detectBackends;
+  const readinessDeps = { detect: ctx.detect, surveyVehicle: ctx.surveyVehicle };
   const readFile = ctx.readFileSync ?? readFileSync;
   const lstat = ctx.lstatSync ?? lstatSync;
   const writeConfig = ctx.writeConfig ?? writeConfigFs;
@@ -170,23 +214,18 @@ export const main = (argv, ctx = {}) => {
         return { code: 0, stdout: JSON.stringify(buildJson({ changed: [], unchanged: [], warnings: [], writtenPath: null, noop: true }), null, 2), stderr: '' };
       }
       const shown = current == null ? `(no ${CONFIG_REL} yet — computed defaults apply)` : serializeConfig(current).replace(/\n$/, '');
-      const hint = `\nPass --set <activity>.<slot>=<recipe> (preview) then --write to apply. Activities/slots: plan-authoring.review, plan-execution.execute, plan-execution.review.`;
+      const hint = `\nPass --set <activity>.<slot>=<value> (preview) then --write to apply. Activities/slots: ${QUALIFIED_SLOTS}.`;
       return { code: 0, stdout: `${source === 'none' ? '' : `${CONFIG_REL}:\n`}${shown}${hint}`, stderr: '' };
     }
 
-    const after = applySetOps(current, ops, { seedReadme: CANON_README });
+    // The merged config, then the _README refresh: a note that normalize-matches a KNOWN PRIOR canonical
+    // is replaced by the current one on a touched write, while a customized note stays untouched.
+    const after = refreshReadme(applySetOps(current, ops, { seedReadme: CANON_README })).config;
 
-    // Detection is a SECONDARY input — it only refines the EFFECTIVE recipe note. A throw must NOT block
-    // the write (the config write is readiness-independent): treat all backends as not-ready, warn, exit 0.
     const warnings = [];
-    let detection = [];
-    try {
-      detection = detect();
-    } catch (err) {
-      warnings.push(`backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; recipes needing a backend degrade to solo.`);
-    }
+    const readiness = composeReadinessOrWarn(cwd, readinessDeps, warnings);
 
-    const resolved = ops.map((op) => resolveOp(op, current, after, detection));
+    const resolved = ops.map((op) => resolveOp(op, current, after, readiness));
     const changed = resolved.filter((e) => e.from !== e.to);
     const unchanged = resolved.filter((e) => e.from === e.to);
     const noop = changed.length === 0;
@@ -220,7 +259,7 @@ export const main = (argv, ctx = {}) => {
         return { error: (err && err.message) || String(err) };
       }
     })();
-    const activeLine = composeActiveRecipeLine({ config: after, source: CONFIG_REL }, detection, autonomyFacts);
+    const activeLine = composeActiveRecipeLine({ config: after, source: CONFIG_REL }, readiness, autonomyFacts);
     const stdout = json
       ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath, noop: false, activeLine }), null, 2)
       : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody, activeLine });

package/tools/spec-adoption.mjs

@@ -0,0 +1,71 @@
+// spec-adoption.mjs — which of the four adoption states the feature-spec store is in, and whether the layer
+// was declined. Contract: docs/ai/specs/kit/spec-adoption.md. The census and the per-document read are
+// spec-check's own exported seam; this module walks nothing of its own. Read-only, Node >= 22.
+
+import { join } from 'node:path';
+import { SPEC_SCHEMA } from '../references/scripts/spec-schema.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { probe as probePath, realpath as realpathOf, list as listDir } from './spec-check-cli.mjs';
+import { walkStore, readClosure } from './spec-check.mjs';
+import { ACKS_SPEC_ADOPTION_KEY, factFingerprint, readAckValue } from './ack-store.mjs';
+
+export const ADOPTION = Object.freeze({
+  NOT_ADOPTED: 'not-adopted',
+  ADOPTING: 'adopting',
+  ADOPTED: 'adopted',
+  UNREADABLE: 'unreadable',
+});
+export const ADOPTION_STATES = Object.freeze(Object.values(ADOPTION));
+
+export const STORE_DIR_REL = SPEC_SCHEMA.storePrefix.slice(0, -1);
+export const SPEC_ADOPTION_LANE = 'spec-adoption';
+export const DECLINE_FACT = `spec-adoption:declined:${SPEC_SCHEMA.storePrefix}`;
+
+const CONTRACT_KIND = 'spec';
+const LIVE = 'live';
+const DRAFT = 'draft';
+const RETIRED = 'retired';
+
+const DEFAULT_IO = Object.freeze({ read: readRegularFileNoFollow, probe: probePath, realpath: realpathOf, list: listDir });
+
+const verdict = (state, counts = { live: 0, draft: 0, retired: 0 }, reason = null) => Object.freeze({ state, ...counts, reason });
+
+// surveySpecAdoption(root, deps) -> { state, live, draft, retired, reason }. `deps.io` overrides the four
+// IO primitives (tests); every other answer comes from the store bytes through the one reader.
+export const surveySpecAdoption = (root, deps = {}) => {
+  const io = { ...DEFAULT_IO, ...(deps.io ?? {}) };
+  const dirState = io.probe(join(root, STORE_DIR_REL));
+  if (dirState === 'absent') return verdict(ADOPTION.NOT_ADOPTED);
+  if (dirState !== 'dir') return verdict(ADOPTION.UNREADABLE, undefined, `${STORE_DIR_REL} is ${dirState === 'file' ? 'a file' : dirState}, not a directory`);
+  const rootReal = io.realpath(root);
+  if (rootReal === null) return verdict(ADOPTION.UNREADABLE, undefined, 'the project root does not resolve');
+  const findings = [];
+  const ctx = { io, at: (rel) => (rel === '' ? root : `${root}/${rel}`), rootReal, add: (rule, path, message) => findings.push({ rule, path, message }) };
+  const closure = walkStore(ctx).map((path) => ({ path, roles: ['present'] }));
+  const docs = findings.length === 0 ? readClosure(closure, ctx) : new Map();
+  if (findings.length > 0) return verdict(ADOPTION.UNREADABLE, undefined, `${findings[0].path}: ${findings[0].message}`);
+  const counts = { live: 0, draft: 0, retired: 0 };
+  for (const doc of docs.values()) {
+    if (doc.verdict?.kind !== CONTRACT_KIND) continue;
+    if (doc.verdict.status === LIVE) counts.live += 1;
+    else if (doc.verdict.status === DRAFT) counts.draft += 1;
+    else if (doc.verdict.status === RETIRED) counts.retired += 1;
+  }
+  return verdict(counts.live > 0 ? ADOPTION.ADOPTED : ADOPTION.ADOPTING, counts);
+};
+
+export const declineFingerprint = () => factFingerprint(DECLINE_FACT);
+
+// True when the store's decline is recorded; the guarded reader's refusals propagate to the caller.
+export const readDeclineAck = (root, deps = {}) => readAckValue(root, deps, ACKS_SPEC_ADOPTION_KEY) === declineFingerprint();
+
+const plural = (n, noun) => `${n} ${noun}`;
+
+// The one status line body, per state (the caller prefixes its own label).
+export const describeAdoption = ({ state, live, draft, reason }, { declined = false } = {}) => {
+  const suffix = declined && state !== ADOPTION.ADOPTED ? ' — declined' : '';
+  if (state === ADOPTION.NOT_ADOPTED) return `not adopted${suffix}`;
+  if (state === ADOPTION.ADOPTING) return `adopting (${plural(draft, 'draft')})${suffix}`;
+  if (state === ADOPTION.ADOPTED) return `adopted (${plural(live, 'live')}, ${plural(draft, 'draft')})`;
+  return `could not be read — ${reason}`;
+};

package/tools/spec-check.mjs

@@ -87,7 +87,7 @@ const refusal = (message) => ({ verdict: 'REFUSE', exit: 2, findings: [], docume
 // Every document of the closure, read ONCE: probe, then (only for a regular file) the descriptor-
 // bound read and the reader verdict. Containment of the containing directory is decided BEFORE the
 // read, so a directory that resolves outside the root is never opened through.
-const readClosure = (closure, ctx) => {
+export const readClosure = (closure, ctx) => {
   const { io, at, rootReal, add } = ctx;
   const docs = new Map();
   for (const { path, roles } of closure) {
@@ -247,7 +247,7 @@ const judgeListing = (doc, docs, add) => {
 // FINDING, never an empty directory quietly walked past: an incomplete census that reported a clean
 // store would be the one answer this lane must never give. A directory is contained BEFORE it is
 // listed, and a non-regular `.md` sitting in the store is stated rather than skipped.
-const walkStore = (ctx) => {
+export const walkStore = (ctx) => {
   const { io, at, rootReal, add } = ctx;
   const found = [];
   const stack = [STORE_DIR];

package/tools/upgrade-runlist.mjs

@@ -44,7 +44,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
       'customized-preserved',
       'malformed-preserved',
       'already-present',
-      'skipped-no-node',
+      'skipped-no-node-evidence',
       'old-adr-layout-migration-instructed',
       'failed',
     ],

package/tools/view-model.mjs

@@ -54,7 +54,11 @@ const recipesVm = (r) => {
   if (r.error) return { error: r.error };
   const pairs = [];
   for (const [activity, slots] of Object.entries(r.activities ?? {})) {
-    for (const [slot, v] of Object.entries(slots)) pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe });
+    // source + degradedFrom ride along: an effective recipe alone cannot tell a chosen value from a
+    // computed default, nor a degrade from a configuration that really names the resolved recipe.
+    for (const [slot, v] of Object.entries(slots)) {
+      pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe, source: v.source ?? null, degradedFrom: v.degradedFrom ?? null });
+    }
   }
   return { pairs, detectError: r.detectError ?? null };
 };
@@ -76,8 +80,18 @@ const velocityVm = (v) => {
 
 const agentsVm = (a) => {
   if (!a) return null;
-  if (a.error) return { error: a.error };
-  return { bundled: a.bundled ?? 0, placed: a.placed ?? 0 };
+  if (a.error) return { error: a.error, executor: a.executor ?? null, executorReason: a.executorReason ?? null };
+  const bundled = a.bundled ?? 0;
+  return {
+    bundled,
+    placed: a.placed ?? 0,
+    // The envelope counts the read-only vehicles; an envelope predating the executor field bundled
+    // only read-only ones.
+    readOnly: a.readOnly ?? (a.executor == null ? bundled : Math.max(bundled - 1, 0)),
+    // null = an envelope predating the field (unknown), never a state.
+    executor: a.executor ?? null,
+    executorReason: a.executorReason ?? null,
+  };
 };
 
 const hookVm = (h) => {
@@ -114,6 +128,8 @@ const projectVm = (p) =>
         deployed: p.deployed,
         docsAi: p.docsAi,
         adrLayout: p.adrLayout ?? null,
+        // null = an envelope predating the field (unknown), never a state.
+        specs: p.specs ?? null,
         deployStamps: (p.deployStamps ?? []).map((st) => ({ display: st.display, version: st.version ?? null })),
         visibility: visibilityVm(p.visibility),
         settings: settingsVm(p.settings),