@sabaiway/agent-workflow-kit 2.1.0 → 3.1.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,9 +54,12 @@ 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';
+import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -97,6 +100,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,
@@ -105,6 +109,7 @@ export const SEVERITIES = Object.freeze({
   'agy-adddir': SEVERITY_OPTIONAL,
   'agy-adddir.invalid-env': SEVERITY_ATTENTION,
   'sandbox-lane': SEVERITY_OPTIONAL,
+  'worktrees-dir': SEVERITY_OPTIONAL,
 });
 // The per-item render tags (frozen presentation data, same language contract as the templates).
 export const SEVERITY_LABELS = Object.freeze({
@@ -152,6 +157,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',
@@ -161,6 +167,7 @@ export const WHATS = Object.freeze({
   'agy-adddir': 'agy-review is placed but AGY_REVIEW_ALLOW_ADDDIR is not set ({file}) — an oversized code review refuses instead of offloading',
   'agy-adddir.invalid-env': 'AGY_REVIEW_ALLOW_ADDDIR is set to an INVALID value ({value}) — refuse-mode applies and the settings file is shadowed while it is set',
   'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
+  'worktrees-dir': 'write access to the worktrees parent dir {dir} is not confirmed — provision may still stop',
 });
 
 // ── the shape contract (D2): registry strings AND composed items stay one line under the cap ────
@@ -205,11 +212,13 @@ 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)',
   'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
   'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
+  'worktrees-dir': 'parallel features — the host-specific write allowance or terminal fallback is surfaced before provision',
 });
 
 // A typed usage failure (exit 2) — the codebase's typed-error idiom (no classes).
@@ -292,7 +301,7 @@ const probeSandboxProvision = ({ root, deps, add, skip }) => {
     const variant = plan.tuple ? 'sandbox-provision.installable' : 'sandbox-provision';
     const reason = truncatedTo(oneLineOf(p.reason), templateBudget(WHATS[variant]) - (plan.tuple ? String(plan.tuple).length : 0));
     // The doctor reads process.cwd() (deployment-gated) and takes no --cwd flag — the one-liner
-    // pins the target project via a cd prefix (codex R2, Segment B).
+    // pins the target project via a cd prefix (Segment B).
     add('sandbox-provision', fillTemplate(WHATS[variant], { reason, tuple: plan.tuple }), `cd ${q(root)} && node ${q(toolPath('autonomy-doctor.mjs'))}`);
   } catch (err) {
     skip('sandbox-provision', err);
@@ -301,7 +310,7 @@ const probeSandboxProvision = ({ root, deps, add, skip }) => {
 
 const probeReviewRecipe = ({ root, deps, add, skip }) => {
   try {
-    // The VALIDATED reader (codex R2, Segment B): a schema-invalid config (unknown activity/slot,
+    // The VALIDATED reader (Segment B): a schema-invalid config (unknown activity/slot,
     // bad recipe) throws here and becomes a stated skip — raw JSON.parse would silently ignore it.
     const { config } = loadConfig(root, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
     const detection = detectBackends(deps);
@@ -325,14 +334,14 @@ const probeGates = ({ root, deps, add, skip }) => {
     const sg = surveyGateHook(root, deps);
     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
+    // An ABSENT file and the seeded-EMPTY list are equally undeclared (Segment B); the
+    // 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 +352,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
@@ -412,7 +471,7 @@ const probeMasksItem = ({ root, deps, add, skip }) => {
     if (!needsMasksApply(p)) return;
     const variant = p.staleReal.length > 0 ? 'sandbox-masks.stale-real' : 'sandbox-masks';
     // A stale-real-only fence (EMPTY derivation over a non-empty block) makes the plain --apply
-    // REFUSE — the exact one-liner must carry --clear there (codex R1, Segment B).
+    // REFUSE — the exact one-liner must carry --clear there (Segment B).
     const apply = p.masks.length === 0 && p.staleReal.length > 0 ? `${p.applyCmd} --clear` : p.applyCmd;
     add('sandbox-masks', fillTemplate(WHATS[variant], { n: p.masks.length, m: p.staleReal.length }), apply);
   } catch (err) {
@@ -425,7 +484,7 @@ const probeAgyAdddir = ({ deps, add, skip }) => {
     const probePlaced = deps.findWrapper ?? ((cmd) => findOnPath(cmd, deps).state === 'present');
     if (!probePlaced('agy-review')) return;
     // Configured means a VALID boolean value (the wrapper validates and falls back to the default
-    // on garbage — presence alone proves nothing; codex R3). An explicit valid 0 is a user CHOICE
+    // on garbage — presence alone proves nothing). An explicit valid 0 is a user CHOICE
     // (refuse mode) — respected, never nagged. env > file, the wrappers' own precedence.
     const isValidBool = (v) => v === '0' || v === '1';
     const env = deps.getenv ?? process.env;
@@ -626,7 +685,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane', 'read-lane']);
+export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane', 'read-lane', 'worktrees-dir']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -683,6 +742,28 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
   }
 };
 
+// The worktrees-dir arming item (parallel feature worktrees): fires when the resolved worktrees
+// parent dir (docs/ai/worktrees.json parentDir, else the repo's own parent) is not confirmed
+// writable by a trusted host signal. The provision preflight remains the real create+delete test.
+const probeWorktreesDir = ({ root, deps, add, skip }) => {
+  try {
+    const config = loadWorktreesConfig(root, deps);
+    const parent = config.parentDir == null ? dirname(root) : resolve(root, config.parentDir);
+    // the SAME canonical derivation the provision preflight probes (worktrees.mjs) — an absent
+    // configured dir resolves to its nearest existing ancestor, never a false denial
+    const probeDir = resolveProbeDir(parent, deps);
+    if (deps.canWriteDir?.(probeDir) === true) return;
+    const dir = truncatedTo(oneLineOf(probeDir), templateBudget(WHATS['worktrees-dir']));
+    add(
+      'worktrees-dir',
+      fillTemplate(WHATS['worktrees-dir'], { dir }),
+      `HAND-APPLY: add ${JSON.stringify(probeDir)} to sandbox.filesystem.allowWrite in .claude/settings.json on settings-native hosts; on harness-managed hosts grant this dir for the session or use the provision terminal fallback`,
+    );
+  } catch (err) {
+    skip('worktrees-dir', err);
+  }
+};
+
 // ── assembly (frozen presentation order) ─────────────────────────────────────────────────────────
 const PROBES = Object.freeze([
   probeVelocityItems,
@@ -690,11 +771,13 @@ const PROBES = Object.freeze([
   probeSandboxProvision,
   probeReviewRecipe,
   probeGates,
+  probeCommitGuard,
   probeReadLane,
   probeFamilyFreshness,
   probeMasksItem,
   probeAgyAdddir,
   probeSandboxLane,
+  probeWorktreesDir,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
@@ -737,7 +820,7 @@ export const formatRecommendations = ({ items, skips }) => {
   const verdict = composeVerdict({ attention, optional: items.length - attention, skipped: skips.length });
   if (verdict == null) {
     // The flow-optimal claim renders ONLY when every probe ran and none fired — an empty item
-    // list beside skipped checks would falsely attest optimality (codex R1, Segment B).
+    // list beside skipped checks would falsely attest optimality (Segment B).
     lines.push(RECOMMENDATIONS_EMPTY_LINE);
     return lines.join('\n');
   }

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';
@@ -35,6 +35,9 @@ const ATTRIBUTION = [
   { re: /reviewed by (claude|codex|chatgpt|gpt|gemini|copilot|cursor|the (ai|model|agent))/i, label: 'AI review attribution' },
   { re: /authored[- ]by[: ][^\n]{0,40}\b(claude|chatgpt|gemini|copilot)\b/i, label: 'AI authorship attribution' },
 ];
+const REVIEWER_IDENTITY = [
+  { re: /\b(?:agy|codex)(?:\s+|-)r\d+(?:(?:\+|\/)r?\d+)*(?:-[a-z0-9]+)*\b/i, label: 'reviewer-round identity' },
+];
 
 const allowlistCovers = (matched, allowlist) =>
   allowlist.some((term) => matched.toLowerCase().includes(term.toLowerCase()));
@@ -49,6 +52,10 @@ export const scanText = (text, { allowlist = ALLOWLIST } = {}) => {
         findings.push({ line: idx + 1, kind: 'attribution', detail: `${label}: "${m[0]}"` });
       }
     }
+    for (const { re, label } of REVIEWER_IDENTITY) {
+      const m = line.match(re);
+      if (m) findings.push({ line: idx + 1, kind: 'reviewer-identity', detail: `${label}: "${m[0]}"` });
+    }
   });
   return findings;
 };
@@ -83,7 +90,7 @@ export const scanPaths = (paths, opts = {}) => {
   return report;
 };
 
-const main = (argv) => {
+export const main = (argv) => {
   const reportOnly = argv.includes('--report');
   const paths = argv.filter((a) => a !== '--report');
   if (paths.length === 0) {
@@ -93,7 +100,7 @@ const main = (argv) => {
   const report = scanPaths(paths);
   for (const r of report) console.log(`[${r.kind}] ${r.file}:${r.line} — ${r.detail}`);
   if (report.length === 0) {
-    console.log('[release-scan] clean — no AI attribution found.');
+    console.log('[release-scan] clean — no AI attribution or reviewer-round identity found.');
     return;
   }
   console.log(`\n[release-scan] ${report.length} finding(s).`);

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';