@sabaiway/agent-workflow-kit 1.25.0 → 1.27.0

package/tools/commands.mjs

@@ -26,15 +26,19 @@ const BARE_INVOCATION = `/${SKILL_NAME}`;
 const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
 
 // ── kinds ────────────────────────────────────────────────────────────────────────
-// read-only — never writes, never commits, never runs a subscription CLI.
-// writer    — writes files (a project deployment or a settings/skill placement).
-// guarded   — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// read-only    — never writes, never commits, never runs a subscription CLI.
+// writer       — writes files (a project deployment or a settings/skill placement).
+// guarded      — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// project-exec — the kit itself writes nothing, but the mode RUNS the project's own declared
+//                commands with the caller's privileges (the `gates` runner) — honest-tagged so a
+//                user never reads "read-only" on a surface that executes their gate matrix.
 // `writer` and `guarded` are the "acts on the system" kinds; only an explicit known token may reach
 // one (plus the bare bootstrap exception). Garbage routes to `help` (read-only) — see routeInvocation.
 export const READ_ONLY = 'read-only';
 export const WRITER = 'writer';
 export const GUARDED = 'guarded';
-const KINDS = new Set([READ_ONLY, WRITER, GUARDED]);
+export const PROJECT_EXEC = 'project-exec';
+const KINDS = new Set([READ_ONLY, WRITER, GUARDED, PROJECT_EXEC]);
 
 // ── groups (fixed render order) ────────────────────────────────────────────────────
 export const GROUP_ORDER = Object.freeze(['Inspect', 'Configure', 'Orchestrate', 'Lifecycle']);
@@ -87,6 +91,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'List every command, grouped, marking each as read-only or as one that makes changes.',
   },
+  {
+    key: 'gates',
+    invocation: invocationOf('gates'),
+    group: 'Inspect',
+    kind: PROJECT_EXEC,
+    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line.',
+  },
   {
     key: 'setup',
     invocation: invocationOf('setup'),
@@ -101,6 +112,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Seed a read-only command allowlist so routine read-only commands stop prompting (Claude Code; opt-in; preview first).',
   },
+  {
+    key: 'agents',
+    invocation: invocationOf('agents'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Place bundled cheap-model subagent definitions for mechanical work — sweeps, changelog skeletons, gate triage (Claude Code; opt-in; preview first).',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -165,7 +183,12 @@ export const routeInvocation = (token) => {
 
 // ── render ──────────────────────────────────────────────────────────────────────────
 
-const KIND_TAG = { [READ_ONLY]: '[read-only]', [WRITER]: '[writer]   ', [GUARDED]: '[guarded]  ' };
+const KIND_TAG = {
+  [READ_ONLY]: '[read-only]        ',
+  [WRITER]: '[writer]           ',
+  [GUARDED]: '[guarded]          ',
+  [PROJECT_EXEC]: '[runs project cmds]',
+};
 const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
 
 // formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
@@ -175,7 +198,7 @@ export const formatHelp = () => {
   const lines = [
     `${SKILL_NAME} — command index (this list is read-only)`,
     '',
-    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first).',
+    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first) · runs project cmds (executes your own declared commands).',
   ];
   for (const group of GROUP_ORDER) {
     const inGroup = COMMANDS.filter((c) => c.group === group);

package/tools/family-members.mjs

@@ -13,7 +13,8 @@
 // ── the unified registry ───────────────────────────────────────────────────────
 // One entry per family member. `installed` is the detect.installed spec (env + home-relative default
 // + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
-// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `npm` is the install package (null for the bridges — placed by `setup`, and once placed refreshed
+// by `init`/`upgrade` from the kit's bundled copies, never npm);
 // `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
 // Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
 // (release-engineering / release-marketing) are deliberately NOT here — they are not family members

package/tools/family-registry.mjs

@@ -17,10 +17,13 @@
 // side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
 
 import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
+// The ONE dependency-free semver (shared with bin/install.mjs) — the bridge freshness probe compares
+// the placed version against the kit-bundled mirror; null-on-unparseable maps to 'unknown' (INV-B).
+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 } from './engine-source.mjs';
@@ -57,6 +60,10 @@ import {
   VISIBILITY_PUBLIC,
   DISPLAY_NAMES,
   displayOf,
+  FRESH_CURRENT,
+  FRESH_BEHIND,
+  FRESH_UNKNOWN,
+  FRESH_NOT_CHECKED,
 } from './labels.mjs';
 // The capability-adaptive direct-CLI presenter (Plan §4.2/§4.5): the surface detector, the
 // envelope→ViewModel transform, and the plain/ansi renderers. main() composes them; the agent-mediated
@@ -135,7 +142,18 @@ export const classifyMember = (member, deps = {}) => {
   const report = markerPresent ? validate(skillDir) : { result: NOT_INSTALLED };
   const manifestState = classifyState(markerPresent, report, member);
   const installed = manifestState !== NOT_INSTALLED;
-  const version = manifestState === OK ? readVersion(skillDir).version ?? null : null;
+  // Crash-safe version read: readAuthoritativeVersion THROWS on a present-but-unreadable SKILL.md
+  // (stat needs no read permission, readFileSync does — a TOCTOU/EACCES window after validate).
+  // The read-only survey must never crash on it: degrade to null, which the bridge freshness probe
+  // then reports as 'unknown' (INV-B), never as a throw and never as a silent claim.
+  const version = (() => {
+    if (manifestState !== OK) return null;
+    try {
+      return readVersion(skillDir).version ?? null;
+    } catch {
+      return null;
+    }
+  })();
 
   return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
 };
@@ -165,6 +183,51 @@ export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json
 const MEMORY_BEHIND_NOTE =
   "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
 
+// ── the bridge freshness probe (deterministic-first — INV-A / INV-B) ─────────────
+// The bridges are not npm packages: their ONLY delivery channel is the copy bundled inside this kit
+// (`bridges/<name>/`, placed by `/agent-workflow-kit setup`). A placed bridge therefore has exactly
+// one authoritative freshness comparison — its installed version (readAuthoritativeVersion, already
+// on the row) vs the kit-bundled mirror's capability.json. BOTH are local files, so the "never
+// checks npm" invariant holds. The probe sets the internal row field `freshness`
+// ('behind' | 'current' | 'unknown'); refreshOf derives the public refresh block STRUCTURALLY from
+// that field (INV-2 — never parsed from caveat text). INV-B: an unreadable/unparseable version on
+// EITHER side degrades to 'unknown' + a plain-language note — never a false claim in either direction.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// bridges/ ships beside tools/ in both the repo and the installed kit (the setup-backends.mjs
+// resolution), so this resolves in both. Injectable via deps.bundleRoot for tests.
+const BUNDLE_ROOT = resolve(__dirname, '..', 'bridges');
+
+// Crash-safe on the bundled side: an absent / unreadable / malformed bundle manifest → null (INV-B
+// 'unknown'), never a throw — the read-only survey must survive a broken kit install.
+const readBundledBridgeVersion = (name, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const root = deps.bundleRoot ?? BUNDLE_ROOT;
+  try {
+    const manifest = JSON.parse(String(read(join(root, name, 'capability.json'), 'utf8')));
+    return typeof manifest.version === 'string' ? manifest.version : null;
+  } catch {
+    return null;
+  }
+};
+
+const bridgeBehindNote = (display, placed, bundled) =>
+  `the ${display} installed here (v${placed}) is older than the copy bundled with this kit (v${bundled}) — refresh it with \`/agent-workflow-kit setup\`.`;
+// The recovery differs per failing SIDE: `setup` re-places FROM the bundle, so it can repair an
+// unreadable INSTALLED copy but can never repair an unreadable BUNDLED copy — that needs a kit
+// refresh first (the npx installer), then `setup`.
+const bridgeUnknownNote = (display, side, recovery) =>
+  `couldn't compare the ${display} installed here with the copy bundled with this kit (${side}), so its freshness is unknown — ${recovery}.`;
+const UNKNOWN_SIDES = Object.freeze({
+  placed: {
+    side: 'the installed copy has no readable version',
+    recovery: '`/agent-workflow-kit setup` re-places the bundled copy',
+  },
+  bundled: {
+    side: "the kit's bundled copy has no readable version",
+    recovery: 'refresh the kit first (`npx @sabaiway/agent-workflow-kit@latest init`), then `/agent-workflow-kit setup`',
+  },
+});
+
 export const surveyFamily = (deps = {}) =>
   FAMILY_MEMBERS.map((member) => {
     const row = classifyMember(member, deps);
@@ -184,8 +247,30 @@ export const surveyFamily = (deps = {}) =>
     // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
     // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
     if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
-      if (probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps) === 'absent') {
+      const templateProbe = probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps);
+      if (templateProbe === 'absent') {
         row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
+      } else if (templateProbe === 'unknown') {
+        // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
+        row.freshness = FRESH_UNKNOWN;
+      }
+    }
+    // Bridge freshness probe (INV-A / INV-B): only for a provably-OURS placed bridge (manifestState
+    // OK). Compares two LOCAL files; a non-OK / absent bridge is out of scope ('not-checked').
+    if (row.kind === 'execution-backend' && row.manifestState === OK && row.skillDir) {
+      const bundled = readBundledBridgeVersion(row.name, deps);
+      const cmp = compareSemver(row.version, bundled);
+      if (cmp === null) {
+        const { side, recovery } = parseSemver(row.version) === null ? UNKNOWN_SIDES.placed : UNKNOWN_SIDES.bundled;
+        row.freshness = FRESH_UNKNOWN;
+        row.caveats = [...(row.caveats ?? []), bridgeUnknownNote(displayOf(row.name), side, recovery)];
+      } else if (cmp < 0) {
+        row.freshness = FRESH_BEHIND;
+        row.caveats = [...(row.caveats ?? []), bridgeBehindNote(displayOf(row.name), row.version, bundled)];
+      } else {
+        // Equal OR newer-than-bundled → not behind. A newer placed bridge is a Phase-2 concern for
+        // the refresh DRIVER (INV-D never-downgrade skip); the read-only status axis never flags it.
+        row.freshness = FRESH_CURRENT;
       }
     }
     return row;
@@ -376,18 +461,31 @@ export const surveyBridges = (deps = {}) => {
   });
 };
 
-// INV-2 (structural refresh — additive, derived, never parsed from a caveat string). A member is
-// `behind` when it is a refreshable CORE member (memory / engine) carrying a refresh-recommending
-// caveat — surveyFamily attaches caveats ONLY to those two kinds, and today every such caveat is
-// refresh-recommending. `recommend` is composed from the member's npm package in the ONE registry
-// (FAMILY_MEMBERS[].npm), never extracted from the caveat text. The kit (composition-root) + the two
-// bridges (execution-backend) never carry such a caveat, so they derive { behind:false, recommend:null }
-// — gated by the CAVEAT, not by npm-nullness (the kit's npm is non-null; only the bridges are null).
+// INV-2 (structural refresh — additive, derived, never parsed from a caveat string), per KIND:
+//   • memory / engine (REFRESHABLE_KINDS): `behind` ⟷ an OK row carrying a refresh-recommending
+//     caveat (surveyFamily attaches caveats to those kinds only then, and every such caveat is
+//     refresh-recommending); `recommend` is composed from FAMILY_MEMBERS[].npm — never the caveat text.
+//   • execution-backend: `behind` ⟷ the bridge freshness probe's row field (freshness === 'behind');
+//     `recommend` is composed PER-KIND — bridges have npm:null (placed by `setup`, never npx), so the
+//     runnable recovery is `/agent-workflow-kit setup`, never an npx composition.
+//   • composition-root (the kit): no freshness probe exists on this surface (the two-axes doctrine —
+//     kit freshness is the npx installer's axis) → never behind, 'not-checked'.
+// `freshness` is the checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C):
+// behind:false alone cannot distinguish "checked, current" from "could not be checked".
 const REFRESHABLE_KINDS = new Set(['memory-substrate', 'methodology-engine']);
 const npmOf = (name) => FAMILY_MEMBERS.find((m) => m.name === name)?.npm ?? null;
+export const BRIDGE_REFRESH_RECOMMEND = '/agent-workflow-kit setup';
 const refreshOf = (m) => {
+  if (m.kind === 'execution-backend') {
+    const freshness = m.freshness ?? FRESH_NOT_CHECKED;
+    const behind = freshness === FRESH_BEHIND;
+    return { behind, recommend: behind ? BRIDGE_REFRESH_RECOMMEND : null, freshness };
+  }
   const behind = REFRESHABLE_KINDS.has(m.kind) && Boolean(m.caveats?.length);
-  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null };
+  const freshness = REFRESHABLE_KINDS.has(m.kind) && m.manifestState === OK
+    ? m.freshness ?? (behind ? FRESH_BEHIND : FRESH_CURRENT)
+    : FRESH_NOT_CHECKED;
+  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null, freshness };
 };
 
 export const buildEnvelope = (family, project = null, extras = {}) => {
@@ -399,7 +497,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
     };
     if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
-    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend } (INV-2)
+    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend, freshness } (INV-2)
     return entry;
   });
   const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };

package/tools/known-footprint.mjs

@@ -43,6 +43,8 @@ export const KIT_OWN_PATHS = [
   '/scripts/_expect-shim.mjs',
   '/scripts/archive-changelog.mjs',
   '/scripts/archive-changelog.test.mjs',
+  '/scripts/archive-decisions.mjs',
+  '/scripts/archive-decisions.test.mjs',
   '/scripts/archive-issues.mjs',
   '/scripts/archive-issues.test.mjs',
   '/scripts/check-docs-size.mjs',
@@ -59,6 +61,7 @@ export const KIT_OWN_PATHS = [
 // filesystem (expandGlob) to concrete present files before any git probe; never fed to ls-files.
 export const KNOWN_FOOTPRINT = [
   { pattern: '/.claude/skills/', owner: 'Claude Code', type: 'dir', falsePositiveRisk: false, note: 'local-dev skills; absorbs the AD-013 one-off' },
+  { pattern: '/.claude/agents/', owner: 'Claude Code', type: 'dir', falsePositiveRisk: false, note: 'project subagent definitions (incl. the kit-placed cheap-lane vehicles)' },
   { pattern: '/.cursor/rules/', owner: 'Cursor', type: 'dir', falsePositiveRisk: false, note: 'project rule files' },
   { pattern: '/.cursorrules', owner: 'Cursor (legacy)', type: 'file', falsePositiveRisk: true, note: 'legacy single-file rules' },
   { pattern: '/.codeium/', owner: 'Codeium/Windsurf', type: 'dir', falsePositiveRisk: false, note: 'home-scoped launchers live under ~/, out of scope' },

package/tools/labels.mjs

@@ -41,6 +41,19 @@ export const STATE_PUBLIC = Object.freeze({
 // "hidden fence" / marker terms. ('hidden' here is the PUBLIC visibility word, not the internal fence.)
 export const VISIBILITY_PUBLIC = Object.freeze({ visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' });
 
+// ── refresh freshness tokens (PUBLIC — the envelope's installed[].refresh.freshness) ────────────────
+// The checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C): `behind:false`
+// alone cannot distinguish "checked, current" from "could not be checked".
+//   'current' / 'behind' — a freshness probe RAN and concluded (these two are the "checked" scope);
+//   'unknown'            — a probe ran but could not conclude (INV-B: never collapsed to a claim
+//                          in either direction);
+//   'not-checked'        — no freshness probe exists for this member/state (e.g. the kit itself:
+//                          its freshness is the npx installer's axis, never checked here).
+export const FRESH_CURRENT = 'current';
+export const FRESH_BEHIND = 'behind';
+export const FRESH_UNKNOWN = 'unknown';
+export const FRESH_NOT_CHECKED = 'not-checked';
+
 // Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
 // render is deterministic and the agent never invents a label.
 export const DISPLAY_NAMES = Object.freeze({

package/tools/procedures.mjs

@@ -188,6 +188,22 @@ const reviewLoopAdvice = (slots) =>
       ]
     : [];
 
+// The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
+// at the point of use like reviewLoopAdvice paraphrases §9/§4). Rendered UNCONDITIONALLY for
+// every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
+// which fires only when a review backend engages). It may name the kit's own GENERIC L0
+// surfaces (the gate runner, the rotation checks, the cheap-agents vehicles) — point-of-use
+// routing, still project-agnostic (never a project's publish mechanics). Its distinctive tokens
+// are drift-guarded against the canon on both sides (procedures.test.mjs + the engine canon tests).
+const costLanesAdvice = () => [
+  'Cost lanes (orchestration.md §5) — route every step to the cheapest adequate executor:',
+  '  • L0 deterministic script — run the gate matrix as ONE batch: /agent-workflow-kit gates (the project-declared docs/ai/gates.json); rotation headroom: archive-changelog / archive-issues / archive-decisions --check. An exit code beats a model re-read.',
+  '  • L1 cheap subagent (small model, low effort, read-only tools — /agent-workflow-kit agents places the vehicles) — mechanical sweeps, changelog fact-skeletons, gate-failure triage. Extraction/drafting ONLY; the orchestrator verifies the output and owns every conclusion.',
+  '  • L2 subscription bridge (codex / agy) — reviews per the resolved recipe above, on frontier bridge models (quality-first).',
+  '  • L3 frontier — judgment: plan/fold/synthesis, ADR/handover/changelog-entry wording, persuasive copy, go/no-go, real code.',
+  '  • A step with no named guardrail does not move down a lane; red lines never move down (council review models · real code · memory/copy wording · the maintainer approval asks).',
+];
+
 // The verbatim per-backend DRIVING CONTRACT block (M-contract): the exact invocation descriptor(s),
 // the closed flag set, the grounding note, the round-2/continue delta, and the guarded passthrough
 // tiers — every descriptor printed VERBATIM from the registry mirror of the bridge manifest
@@ -224,6 +240,7 @@ const formatHuman = ({ activity, section, slots, warnings }) => {
   }
   const advice = reviewLoopAdvice(slots);
   if (advice.length) lines.push('', ...advice);
+  lines.push('', ...costLanesAdvice());
   if (warnings.length) {
     lines.push('', 'warnings:');
     for (const w of warnings) lines.push(`  ⚠ ${w}`);
@@ -240,6 +257,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
     slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts }]),
   ),
   reviewLoop: reviewLoopAdvice(slots),
+  // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.
+  costLanes: costLanesAdvice(),
   configSource,
   warnings,
 });

package/tools/recipes.mjs

@@ -283,21 +283,43 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
   };
 };
 
+// ── the one-line backend status (deterministic-first: the tool speaks, the agent pastes) ───────────
+
+// composeStatusLine(detection, recommendation) → the ENTIRE one-line backend-status summary the
+// bootstrap/upgrade report footers print. Machine-composed so the agent pastes it verbatim and
+// composes NOTHING factual (this closes the realistic-example contamination class: a session once
+// echoed SKILL.md's canonical example while the detector said otherwise). Display names come from
+// DISPLAY_ALIASES — the ONE alias table the recommendation clause already uses; ordering is the
+// deterministic BACKEND_PRIORITY (codex before agy), independent of detection emission order.
+// Always exactly one line: no part may carry a newline (pinned by tests).
+export const composeStatusLine = (detection, recommendation) => {
+  const backends = [...detection]
+    .sort((a, b) => priorityIndex(a.name) - priorityIndex(b.name))
+    .map((b) => `${DISPLAY_ALIASES[b.name] ?? b.name} ${b.readiness === READY ? '✓' : '✗'} ${b.readiness}`)
+    .join(' · ');
+  return `backends: ${backends} — run /agent-workflow-kit backends · recipes: ${recommendation.clause} — see /agent-workflow-kit recipes`;
+};
+
 // ── report + CLI ─────────────────────────────────────────────────────────────────
 
-// The structured report behind `--json` — the recipes, the recommendation, and a plan per recipe.
-export const buildReport = (detection) => ({
-  recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
-    id,
-    title,
-    role,
-    minBackends,
-    degradesTo,
-    summary,
-  })),
-  recommendation: recommendRecipe(detection),
-  plans: RECIPES.map((r) => planRecipe(r.id, detection)),
-});
+// The structured report behind `--json` — the recipes, the recommendation, a plan per recipe, and
+// (additive) the pasteable one-line backend status composed from the same detection.
+export const buildReport = (detection) => {
+  const recommendation = recommendRecipe(detection);
+  return {
+    recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
+      id,
+      title,
+      role,
+      minBackends,
+      degradesTo,
+      summary,
+    })),
+    recommendation,
+    plans: RECIPES.map((r) => planRecipe(r.id, detection)),
+    statusLine: composeStatusLine(detection, recommendation),
+  };
+};
 
 // formatRecipes(detection) → deterministic human advisor text: the four recipes, the recommendation,
 // and the per-recipe plan for the current environment (degradation reasons + dispatch + notes).
@@ -320,20 +342,37 @@ export const formatRecipes = (detection) => {
   return lines.join('\n');
 };
 
+// The full argv vocabulary — anything else rejects LOUDLY. The old parse silently routed unknown
+// args into the multi-line human render; with `--status-line` (whose output is pasted as fact) a
+// mistyped flag masquerading as a mode would be a silent failure, so the parse is strict now.
+const KNOWN_ARGS = new Set(['--help', '-h', '--json', '--status-line']);
+
 const main = (argv) => {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log(`recipes — read-only orchestration-recipe advisor for the agent-workflow family.
 
 Usage:
-  node recipes.mjs [--json]
+  node recipes.mjs [--json | --status-line]
 
 Lists the four recipes (Solo / Reviewed / Council / Delegated) and, from the read-only backend
-detector, plans + recommends one for the current environment. Detection only — never writes, never
-commits, never runs a subscription CLI.`);
+detector, plans + recommends one for the current environment. --status-line prints exactly ONE
+line — the machine-composed backend-status summary the bootstrap/upgrade reports paste verbatim.
+--json emits the structured report (incl. the same line as \`statusLine\`); the two are mutually
+exclusive. Detection only — never writes, never commits, never runs a subscription CLI.`);
     return;
   }
+  const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
+  if (unknown !== undefined) {
+    console.error(`[agent-workflow-kit] unknown argument: ${unknown}`);
+    process.exit(1);
+  }
+  if (argv.includes('--json') && argv.includes('--status-line')) {
+    console.error('[agent-workflow-kit] --json and --status-line are mutually exclusive — pick one output');
+    process.exit(1);
+  }
   const detection = detectBackends();
-  if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
+  if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection)));
+  else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
   else console.log(formatRecipes(detection));
 };
 

package/tools/renderers.mjs

@@ -34,7 +34,18 @@ const renderMembers = (vm, { color, glyph }) => {
   // refresh.behind drives a HEADLINE COUNT only — the recovery command stays in the verbatim notes
   // above (the direct CLI never dedupes, never re-prints it). Omitted when nothing is behind.
   if (vm.headline.behind > 0) {
-    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above).`);
+    // A mixed behind+unknown state must not swallow the unknown count (INV-B): append it here so an
+    // uncheckable member never disappears behind the refresh headline.
+    const unknownTail = vm.headline.unknown > 0 ? ` · ${vm.headline.unknown} could not be checked` : '';
+    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above)${unknownTail}.`);
+  } else if (vm.headline.unknown > 0) {
+    // INV-B × INV-C: an uncheckable member BLOCKS the all-current verdict — state the split, never a
+    // blanket freshness claim in either direction.
+    lines.push(`  freshness: ${vm.headline.checked} member(s) checked and current · ${vm.headline.unknown} could not be checked.`);
+  } else if (vm.headline.checked > 0) {
+    // INV-C: the zero-behind verdict is composed by the TOOL, scoped to what was actually checked —
+    // the agent has no gap to fill with an "everything is fresh" gloss.
+    lines.push(`  freshness: all ${vm.headline.checked} checked member(s) are current.`);
   }
   return lines;
 };