@sabaiway/agent-workflow-kit 2.1.0 → 3.0.0

package/tools/recipes.mjs

@@ -12,14 +12,14 @@
 // Invariants (the backends/status posture): pure (no fs/network/CLI in planRecipe/recommendRecipe),
 // read-only, NEVER runs a subscription CLI. The kit only surfaces/selects/plans a recipe — the
 // orchestrator (the main agent) executes it via the bridge skills and always makes the single commit;
-// a backend is advisory or delegated, never autonomous. Dependency-free, Node >= 18.
+// a backend is advisory or delegated, never autonomous. Dependency-free, Node >= 22.
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 // The host-level bridge-settings snapshot (fact-only, best-effort). READ-ONLY core only — never the
 // writer — so this read-only advisor never pulls in the atomic-write core.
-import { settingsSnapshot } from './bridge-settings-read.mjs';
+import { settingsSnapshot, DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
 import {
   detectBackends,
   wrapperCmdFor,
@@ -298,7 +298,50 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
 // 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, settings = null, autonomy = null) => {
+// composeConfiguredPosture(ctx) → the CONFIGURED dispatch posture (strip-the-kit D5), rendered
+// from the bundled manifests' VALIDATED posture pins overlaid with the ACTIVE bridge-settings —
+// today only the codex tier knob (bridge-settings stays model/effort-free by design, so this
+// surface can never carry a settings-file model claim). Returns null when NO bundled bridge
+// declares a posture block (a pre-D5 bundle keeps every surface byte-identical). Best-effort:
+// a corrupt bundle degrades to null — the posture segment is a footer fact, never a gate.
+export const composeConfiguredPosture = (ctx = {}) => {
+  try {
+    const bundleRoot = ctx.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
+    const read = ctx.readFile ?? readFileSync;
+    const parts = [];
+    for (const name of BACKEND_PRIORITY) {
+      let manifest;
+      try {
+        manifest = JSON.parse(String(read(join(bundleRoot, name, 'capability.json'), 'utf8')));
+      } catch {
+        return null; // an unreadable/corrupt manifest is CORRUPTION — a partial posture would lie
+      }
+      if (!Object.hasOwn(manifest, 'posture')) continue; // a pre-D5 bridge — legitimate absence
+      const posture = manifest.posture;
+      // The FULL closed shape (the validator/receipt-predicate twin): a present-but-invalid
+      // block nulls the WHOLE render — fail closed to silence, never a partial/mangled line.
+      const invalid =
+        posture === null || typeof posture !== 'object' || Array.isArray(posture) ||
+        typeof posture.model !== 'string' || posture.model.length === 0 ||
+        (Object.hasOwn(posture, 'effort') && (typeof posture.effort !== 'string' || posture.effort.length === 0)) ||
+        (Object.hasOwn(posture, 'tier') && posture.tier !== null && (typeof posture.tier !== 'string' || posture.tier.length === 0)) ||
+        Object.keys(posture).some((k) => !['model', 'effort', 'tier'].includes(k));
+      if (invalid) return null;
+      const seg = [`model=${posture.model}`];
+      if (Object.hasOwn(posture, 'effort')) seg.push(`effort=${posture.effort}`);
+      if (Object.hasOwn(posture, 'tier')) {
+        const knob = (ctx.settings?.active ?? []).find((s) => s.key === 'CODEX_SERVICE_TIER' && s.bridge === name);
+        seg.push(knob ? `tier=${knob.value} (bridge-settings)` : `tier=${posture.tier ?? 'standard'}`);
+      }
+      parts.push(`${DISPLAY_ALIASES[name] ?? name} ${seg.join(' ')}`);
+    }
+    return parts.length ? parts.join(' · ') : null;
+  } catch {
+    return null;
+  }
+};
+
+export const composeStatusLine = (detection, recommendation, settings = null, autonomy = null, posture = null) => {
   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}`)
@@ -315,7 +358,10 @@ export const composeStatusLine = (detection, recommendation, settings = null, au
   // suffix precedent). Fact-only: effective per-activity levels + the render-sync state; an absent
   // policy says "computed defaults" honestly; a malformed policy surfaces LOUDLY, never omitted.
   const autonomySegment = autonomy == null ? '' : ` · autonomy: ${oneLine(formatAutonomySegment(autonomy))}`;
-  return base + suffix + autonomySegment;
+  // The D5 posture segment: rendered ONLY when the caller supplies the composed pins-derived
+  // posture (composeConfiguredPosture) — an omitted/null param keeps the line byte-identical.
+  const postureSegment = posture == null ? '' : ` · posture: ${oneLine(posture)}`;
+  return base + suffix + autonomySegment + postureSegment;
 };
 
 // The one-segment autonomy renderer behind composeStatusLine's 4th param.
@@ -425,7 +471,7 @@ export const composeActiveRecipeLine = ({ config, source } = {}, detection, auto
 
 // 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, settings = null, autonomy = null) => {
+export const buildReport = (detection, settings = null, autonomy = null, posture = null) => {
   const recommendation = recommendRecipe(detection);
   return {
     recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
@@ -440,7 +486,7 @@ export const buildReport = (detection, settings = null, autonomy = null) => {
     plans: RECIPES.map((r) => planRecipe(r.id, detection)),
     // The SAME autonomy facts the --status-line surface renders — the --json envelope must never
     // expose a stale machine-composed status line (codex R1, Segment B).
-    statusLine: composeStatusLine(detection, recommendation, settings, autonomy),
+    statusLine: composeStatusLine(detection, recommendation, settings, autonomy, posture),
   };
 };
 
@@ -512,8 +558,13 @@ exclusive. Detection only — never writes, never commits, never runs a subscrip
       console.error(`[agent-workflow-kit] ${err.message}`);
       return err.exitCode ?? 1;
     }
-  } else if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection), settingsSnapshot(), await composeAutonomyFacts(process.cwd())));
-  else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection, settingsSnapshot(), await composeAutonomyFacts(process.cwd())), null, 2));
+  } else if (argv.includes('--status-line')) {
+    const snapshot = settingsSnapshot();
+    console.log(composeStatusLine(detection, recommendRecipe(detection), snapshot, await composeAutonomyFacts(process.cwd()), composeConfiguredPosture({ settings: snapshot })));
+  } else if (argv.includes('--json')) {
+    const snapshot = settingsSnapshot();
+    console.log(JSON.stringify(buildReport(detection, snapshot, await composeAutonomyFacts(process.cwd()), composeConfiguredPosture({ settings: snapshot })), null, 2));
+  }
   else console.log(formatRecipes(detection));
   return 0;
 };

package/tools/recommendations.mjs

@@ -28,9 +28,9 @@
 // Read-only: never writes, never commits, never runs a subscription CLI. The reused probes are all
 // exported read-only surfaces of their owning tools (velocity/autonomy/doctor/backends/recipes/
 // registry/sandbox-masks); the sandbox-masks and settings probes may run read-only git queries.
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -54,6 +54,8 @@ import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 import { surveyFamily, surveyGateHook } from './family-registry.mjs';
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
+import { isFinalCapableDeclaration } from './run-gates.mjs';
+import { resolveGitHooksPath } from './commit-guard.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { DEFAULT_BUNDLE_ROOT, SETTINGS_FILENAME, settingsPath, parseSettings, duplicateKeys } from './bridge-settings-read.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
@@ -97,6 +99,7 @@ export const SEVERITIES = Object.freeze({
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gate-hook': SEVERITY_OPTIONAL,
+  'commit-guard': SEVERITY_OPTIONAL,
   'read-lane': SEVERITY_OPTIONAL,
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
@@ -152,6 +155,7 @@ export const WHATS = Object.freeze({
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
+  'commit-guard': 'the gate matrix is final-run-capable but no commit-guard arms the pre-commit hook — a commit needs no green receipt yet',
   'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
   'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
@@ -205,6 +209,7 @@ export const BENEFITS = Object.freeze({
   'review-recipe': 'review coverage — the review recipe you configured actually runs instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
+  'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
@@ -326,13 +331,13 @@ const probeGates = ({ root, deps, add, skip }) => {
     if (sg.error) throw new Error(sg.error);
     if (sg.declarationPresent && sg.declaredGates === null) throw new Error(sg.declarationError ?? 'gates.json present but unreadable');
     // An ABSENT file and the seeded-EMPTY list are equally undeclared (codex R2, Segment B); the
-    // apply is the consent-gated seeder PREVIEW (it proposes entries from the project's own
+    // apply is the consent-gated gates-init PREVIEW (it proposes entries from the project's own
     // scripts and writes only on an explicit yes) — never the runner.
     if (!sg.declarationPresent || sg.declaredGates === 0) {
-      // The seeder writes ONLY with --apply and consent is per-entry (--only) — the apply field
-      // stays a PURE executable command (run-exactly-as-rendered feeds it to the shell); the
-      // two-step preview semantics live in WHAT, never as prose appended to the command.
-      add('gates-declaration', fillTemplate(WHATS['gates-declaration'], {}), `node ${q(toolPath('seed-gates.mjs'))} --cwd ${q(root)}`);
+      // gates-init writes ONLY with --apply — the apply field stays a PURE executable command
+      // (run-exactly-as-rendered feeds it to the shell); the two-step preview semantics live in
+      // WHAT, never as prose appended to the command.
+      add('gates-declaration', fillTemplate(WHATS['gates-declaration'], {}), `node ${q(toolPath('gates-init.mjs'))} --cwd ${q(root)}`);
       return;
     }
     if (sg.declaredGates > 0 && !sg.wired) {
@@ -343,6 +348,56 @@ const probeGates = ({ root, deps, add, skip }) => {
   }
 };
 
+// The D10 consumer surface: once the declaration is FINAL-capable (the canonical core checks
+// present, the checker LAST — the run-gates helper is the one home of that rule), offer the
+// consented commit-guard install — for a MANAGED guardless pre-commit hook AND for an absent one
+// alike; an UNMANAGED hook is a loud skip (manual merge, never an overwrite offer); a
+// non-final-capable declaration gets NO offer (an armed guard over a matrix that cannot mint a
+// receipt would block every commit).
+const INSTALLER_MARKER_RE = /:install-git-hooks\.mjs$/m;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// Convergence needs the EXACT canonical armed line the installer writes — full-line anchored on
+// the kit's OWN resolved guard path. A commented-out line or a lookalike path (fake-commit-guard)
+// must never read as armed (that would suppress the offer and leave commits unguarded).
+const canonicalGuardLineRe = () => new RegExp(`^node "${escapeRe(toolPath('commit-guard.mjs'))}" --check$`, 'm');
+const probeCommitGuard = ({ root, deps, add, skip }) => {
+  try {
+    const read = deps.readFile ?? readFileSync;
+    const gatesRaw = (() => {
+      try {
+        return String(read(join(root, 'docs', 'ai', 'gates.json'), 'utf8'));
+      } catch {
+        return null;
+      }
+    })();
+    if (gatesRaw === null) return; // undeclared — the gates-declaration item owns that story
+    const gates = JSON.parse(gatesRaw).gates;
+    if (!isFinalCapableDeclaration(gates, root)) return; // no receipt to guard yet — no offer
+    const installer = join(root, 'scripts', 'install-git-hooks.mjs');
+    if (!(deps.exists ?? existsSync)(installer)) {
+      skip('commit-guard', new Error('the hook installer (scripts/install-git-hooks.mjs) is not deployed — run upgrade first'));
+      return;
+    }
+    const hooksPath = (deps.gitHooksPath ?? resolveGitHooksPath)(root);
+    if (hooksPath === null) return; // not a git tree — nothing to hook
+    const hook = (() => {
+      try {
+        return String(read(join(hooksPath, 'pre-commit'), 'utf8'));
+      } catch {
+        return null;
+      }
+    })();
+    if (hook !== null && canonicalGuardLineRe().test(hook)) return; // armed — converged (managed or not)
+    if (hook !== null && !INSTALLER_MARKER_RE.test(hook)) {
+      skip('commit-guard', new Error('an UNMANAGED pre-commit hook exists — merge the guard line by hand (the installer refuses to overwrite it)'));
+      return;
+    }
+    add('commit-guard', fillTemplate(WHATS['commit-guard'], {}), `node ${q(installer)} --commit-guard ${q(toolPath('commit-guard.mjs'))}`);
+  } catch (err) {
+    skip('commit-guard', err);
+  }
+};
+
 // The read-lane offer (AD-055 Part II, Help-through-Recommendations): once the gate hook is PLACED
 // and WIRED, offer to enable the opt-in read-only compound lane. Mutually exclusive with the
 // gate-hook item BY CONSTRUCTION — that item keys on `!wired`, this one on `wired` — so an unplaced
@@ -690,6 +745,7 @@ const PROBES = Object.freeze([
   probeSandboxProvision,
   probeReviewRecipe,
   probeGates,
+  probeCommitGuard,
   probeReadLane,
   probeFamilyFreshness,
   probeMasksItem,

package/tools/release-scan.mjs

@@ -8,7 +8,7 @@
 // tripping the (narrow) attribution rules. Only the TEST is self-excluded (it holds attribution
 // fixtures); the scanner source contains no attribution construction, so it is scanned normally.
 //
-// Pure `scanText` for unit fixtures; `scanPaths`/CLI for the release tree. Dependency-free, Node >= 18.
+// Pure `scanText` for unit fixtures; `scanPaths`/CLI for the release tree. Dependency-free, Node >= 22.
 
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, extname, basename, resolve } from 'node:path';

package/tools/renderers.mjs

@@ -5,7 +5,7 @@
 // the JSON mode is handled by the caller (it prints the envelope, not a render). The renderers do
 // LAYOUT + GLYPHS only — phrasing + headline counts already live in the ViewModel.
 //
-// Pure, no side effects, Node >= 18.
+// Pure, no side effects, Node >= 22.
 
 import { BLOCK_TITLES, SETTINGS_LABELS, glyphsFor, NO_DEPLOYMENT } from './presentation.mjs';