@sabaiway/agent-workflow-kit 1.28.0 → 1.30.0

package/references/hooks/gate-approve.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// gate-approve.mjs — the agent-workflow PreToolUse gate-approval hook. Bundled at
+// references/hooks/gate-approve.mjs; PLACED (copied) by `/agent-workflow-kit hook` to
+// <project>/.claude/hooks/agent-workflow-gates.mjs and wired as a `PreToolUse` "Bash" hook in
+// .claude/settings.json.
+//
+// SELF-CONTAINED by contract: the placed copy must run on machines without the kit — no kit
+// imports, dependency-free, Node >= 18, no side effects on import. Two constants are baked
+// FROZEN COPIES of the velocity-profile.mjs exports (a placed file cannot import the kit):
+// SEEDED_READONLY_CORE ≡ UNIVERSAL_READONLY_ALLOWLIST and RESIDUAL_FORMS ≡
+// RUNTIME_RESIDUAL_FORMS — drift-guarded by the kit's test/gate-hook-core-parity.test.mjs.
+//
+// It reads <project root>/docs/ai/gates.json LIVE on every invocation (AD-035: one declaration,
+// two consumers — editing gates.json never requires re-wiring). The project root resolves from
+// $CLAUDE_PROJECT_DIR (the stdin `cwd` may be a subdirectory), falling back to the stdin `cwd`
+// only when the env is absent.
+//
+// Decision ladder for every Bash PreToolUse call — first match wins:
+//   (a) declared-gate EXACT match → allow. Byte-identical (leading/trailing trim only — no
+//       whitespace collapsing, no quote/glob/variable interpretation, no prefix or pattern
+//       matching: patterns are exactly what made AD-021 auto-seeding fragile) to one declared
+//       gate `cmd`, AND the stdin `cwd` realpath-resolves to the project root (gates run FROM
+//       THE ROOT by contract — the same bytes from a subdirectory resolve relative paths
+//       differently), AND permission_mode is `default`/`acceptEdits` (an allow never loosens
+//       `plan`/`bypassPermissions`).
+//   (b) residual guard → ask. The command's leading tokens match the SEEDED read-only core AND
+//       the command carries a documented runtime residual (output redirection, command
+//       substitution, the bounded `--output` write-flag family) that a settings-level allow
+//       rule cannot see. Most-restrictive-wins: this surfaces a human prompt even where a
+//       seeded allow rule would have silently approved. Detection is deliberately string-level
+//       and conservative (no shell parsing in a dependency-free hook): a quoted metacharacter
+//       may over-ASK, never under-allow. Covers the kit-SEEDED core only, never arbitrary
+//       user-added rules.
+//   (c) everything else → NO decision: exit 0, no output — the normal permission flow proceeds
+//       unchanged. The hook NEVER emits `deny`.
+//
+// Fail-safe invariant, decoupled per function: a DECLARATION anomaly (missing / unreadable /
+// malformed / schema-invalid gates.json) disables ONLY exact-gate approval (a) — the residual
+// guard (b) needs no declaration and keeps running (a broken gates.json must not silently
+// reopen the seeded-allowlist hole). Only an INPUT anomaly (unparseable stdin, non-Bash
+// tool_name) disables the whole hook. EVERY anomaly path exits 0 — never exit 2 (exit 2 is an
+// immediate block; a hook that fires on every Bash call must never become the blocker or the
+// noise — run-gates.mjs already yells about a broken declaration at its own point of use).
+//
+// Trust posture: this hook only removes the PROMPT for commands the human already declared in
+// gates.json — the same trust boundary as run-gates.mjs, which executes those commands with the
+// caller's privileges. gates.json is thereby a privileged file; an invalid declaration approves
+// NOTHING (strict-parse-or-no-decision).
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const HOOK_EVENT_NAME = 'PreToolUse';
+export const BASH_TOOL_NAME = 'Bash';
+export const GATES_REL = 'docs/ai/gates.json';
+export const PROJECT_DIR_ENV = 'CLAUDE_PROJECT_DIR';
+export const DECISION_ALLOW = 'allow';
+export const DECISION_ASK = 'ask';
+// The only modes an `allow` may be emitted under — an allowlist, so an unknown future mode is
+// fenced closed by default. The residual guard (b) is NOT mode-fenced: an `ask` never loosens.
+export const ALLOW_PERMISSION_MODES = Object.freeze(['default', 'acceptEdits']);
+
+// Baked frozen copy of velocity-profile.mjs UNIVERSAL_READONLY_ALLOWLIST (the audited read-only
+// core velocity seeds as settings allow rules). Drift-guarded — never edit here alone.
+export const SEEDED_READONLY_CORE = Object.freeze([
+  'Bash(git status:*)',
+  'Bash(git diff:*)',
+  'Bash(git log:*)',
+  'Bash(git show:*)',
+  'Bash(git ls-files:*)',
+  'Bash(git check-ignore:*)',
+  'Bash(git branch --list:*)',
+  'Bash(npm view:*)',
+  'Bash(npm ls:*)',
+  'Bash(npm outdated:*)',
+  'Bash(ls:*)',
+  'Bash(cat:*)',
+  'Bash(head:*)',
+  'Bash(tail:*)',
+  'Bash(wc:*)',
+  'Bash(readlink:*)',
+  'Bash(which:*)',
+  'Bash(grep:*)',
+]);
+
+// Baked frozen copy of velocity-profile.mjs RUNTIME_RESIDUAL_FORMS (the documented residual a
+// settings-level allow rule cannot see). Drift-guarded — never edit here alone.
+export const RESIDUAL_FORMS = Object.freeze({
+  writeRedirections: Object.freeze(['>', '>>', '1>', '2>', '&>', '>|']),
+  // `$(…)` + backtick + process substitution `<(…)` all RUN a nested command (`>(…)` is caught by
+  // the `>` redirection scan). Bare `<` is input redirection (reads a file — read-only commands may
+  // already do that), so it is deliberately NOT here.
+  commandSubstitutions: Object.freeze(['$(', '`', '<(']),
+  // The `--output` write-flag family, matched as a raw SUBSTRING of the whole command (never a
+  // whitespace-token check): the hook sees the pre-shell command string, so `--output=f`,
+  // `"--output=f"`, `'--output' f`, and `\--output` must all trip it — over-asking on a benign
+  // `--output-indicator` is the safe direction (never under-allow a real write flag through quotes).
+  boundedWriteFlags: Object.freeze(['--output']),
+});
+
+export const RESIDUAL_CLASS_REDIRECTION = 'output redirection';
+export const RESIDUAL_CLASS_SUBSTITUTION = 'command substitution';
+export const RESIDUAL_CLASS_OUTPUT_FLAG = 'a bounded --output write flag';
+
+const EXIT_OK = 0;
+const UTF8 = 'utf8';
+const BASH_ALLOW_PATTERN = /^Bash\((.+):\*\)$/u;
+const WHITESPACE_PATTERN = /\s+/u;
+const GATE_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const GATE_CMD_NEWLINE_PATTERN = /[\r\n]/u;
+const GATE_KEYS = Object.freeze(['id', 'title', 'cmd']);
+const README_KEY = '_README';
+const GATES_KEY = 'gates';
+
+// ── declaration (validation parity with run-gates.mjs) ────────────────────────────────
+
+// Self-contained restatement of run-gates.mjs `validateDeclaration`, at EXACT parity including
+// the optional `_README` string — a declaration the runner accepts is never rejected here (else
+// every template-shaped declaration would approve nothing), and one the runner rejects never
+// approves anything. Returns a boolean shape instead of throwing: anomalies go dark, not loud.
+export const validateDeclarationShape = (parsed) => {
+  const invalid = { ok: false };
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return invalid;
+  for (const key of Object.keys(parsed)) {
+    if (key !== README_KEY && key !== GATES_KEY) return invalid;
+  }
+  if (parsed[README_KEY] !== undefined && typeof parsed[README_KEY] !== 'string') return invalid;
+  if (!Array.isArray(parsed[GATES_KEY])) return invalid;
+  const seenIds = new Set();
+  for (const gate of parsed[GATES_KEY]) {
+    if (gate === null || typeof gate !== 'object' || Array.isArray(gate)) return invalid;
+    for (const key of Object.keys(gate)) {
+      if (!GATE_KEYS.includes(key)) return invalid;
+    }
+    for (const key of GATE_KEYS) {
+      if (typeof gate[key] !== 'string' || gate[key].trim() === '') return invalid;
+    }
+    if (GATE_CMD_NEWLINE_PATTERN.test(gate.cmd)) return invalid;
+    if (!GATE_ID_PATTERN.test(gate.id)) return invalid;
+    if (seenIds.has(gate.id)) return invalid;
+    seenIds.add(gate.id);
+  }
+  return { ok: true, gates: parsed[GATES_KEY] };
+};
+
+// Read + strictly validate the LIVE declaration. Any declaration anomaly returns null — ladder
+// (a) goes dark while the residual guard (b) keeps running (the decoupled fail-safe invariant).
+export const readDeclarationGates = (projectRoot, deps = {}) => {
+  const readFile = deps.readFile ?? readFileSync;
+  if (typeof projectRoot !== 'string' || projectRoot === '') return null;
+  try {
+    const validated = validateDeclarationShape(JSON.parse(readFile(join(projectRoot, GATES_REL), UTF8)));
+    return validated.ok ? validated.gates : null;
+  } catch {
+    return null;
+  }
+};
+
+// ── seeded-core prefix + residual detection (ladder b) ────────────────────────────────
+
+const getAllowCommandPrefix = (pattern) => {
+  const match = pattern.match(BASH_ALLOW_PATTERN);
+  return match ? match[1] : undefined;
+};
+
+const tokenizeCommand = (command) => command.trim().split(WHITESPACE_PATTERN).filter(Boolean);
+
+const CORE_PREFIX_TOKEN_LISTS = Object.freeze(
+  SEEDED_READONLY_CORE.map(getAllowCommandPrefix)
+    .filter(Boolean)
+    .map((prefix) => Object.freeze(tokenizeCommand(prefix))),
+);
+
+// `Bash(git status:*)` approves `git status <anything>` at a word boundary — the guard matches
+// the same way: a core pattern's tokens must be the command's LEADING tokens exactly.
+export const matchSeededCorePrefix = (command) => {
+  const tokens = tokenizeCommand(command);
+  const matched = CORE_PREFIX_TOKEN_LISTS.find(
+    (prefixTokens) =>
+      prefixTokens.length <= tokens.length && prefixTokens.every((token, index) => tokens[index] === token),
+  );
+  return matched ? matched.join(' ') : null;
+};
+
+// String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
+// substring scan (never a whitespace-token check — a token check misses `"--output=f"` / `'>' f`
+// where the quotes are still in the string but the shell will strip them). A quoted metacharacter
+// or write flag may over-ASK, never under-allow (no shell parsing in a dependency-free hook).
+export const detectResidualClasses = (command) => {
+  const classes = [];
+  if (RESIDUAL_FORMS.writeRedirections.some((form) => command.includes(form))) {
+    classes.push(RESIDUAL_CLASS_REDIRECTION);
+  }
+  if (RESIDUAL_FORMS.commandSubstitutions.some((form) => command.includes(form))) {
+    classes.push(RESIDUAL_CLASS_SUBSTITUTION);
+  }
+  if (RESIDUAL_FORMS.boundedWriteFlags.some((flag) => command.includes(flag))) {
+    classes.push(RESIDUAL_CLASS_OUTPUT_FLAG);
+  }
+  return classes;
+};
+
+// ── the decision ladder (pure core) ───────────────────────────────────────────────────
+
+export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gates }) => {
+  const trimmed = command.trim();
+  // (a) declared-gate exact match — all three invariants (declaration valid, cwd = project
+  // root, mode in the allow fence) must hold; otherwise fall through, never error.
+  if (Array.isArray(gates) && cwdIsProjectRoot === true && ALLOW_PERMISSION_MODES.includes(permissionMode)) {
+    const declaredGate = gates.find((gate) => gate.cmd.trim() === trimmed);
+    if (declaredGate !== undefined) {
+      return {
+        permissionDecision: DECISION_ALLOW,
+        permissionDecisionReason: `agent-workflow gates: byte-exact match of declared gate "${declaredGate.id}" (${GATES_REL}), invoked from the project root`,
+      };
+    }
+  }
+  // (b) residual guard — no declaration needed; not mode-fenced (an ask never loosens).
+  const corePrefix = matchSeededCorePrefix(trimmed);
+  if (corePrefix !== null) {
+    const residualClasses = detectResidualClasses(trimmed);
+    if (residualClasses.length > 0) {
+      return {
+        permissionDecision: DECISION_ASK,
+        permissionDecisionReason: `agent-workflow residual guard: read-only-seeded "${corePrefix}" carries ${residualClasses.join(' + ')} — a settings allow rule cannot see runtime shape; confirm by hand`,
+      };
+    }
+  }
+  // (c) no decision — the normal permission flow proceeds unchanged.
+  return null;
+};
+
+// ── stdin-driven main ─────────────────────────────────────────────────────────────────
+
+const resolveRealpath = (maybePath, realpath) => {
+  if (typeof maybePath !== 'string' || maybePath === '') return null;
+  try {
+    return realpath(maybePath);
+  } catch {
+    return null;
+  }
+};
+
+// Parse one PreToolUse stdin payload and run the ladder. Returns the decision object or null
+// (null → no output, exit 0). Injectable deps keep the tests hermetic.
+export const runHook = (rawInput, deps = {}) => {
+  const env = deps.env ?? process.env;
+  const realpath = deps.realpath ?? realpathSync;
+  const parseInput = () => {
+    try {
+      return JSON.parse(rawInput);
+    } catch {
+      return null;
+    }
+  };
+  const input = parseInput();
+  // Input anomaly → the WHOLE hook goes dark (distinct from a declaration anomaly, which only
+  // darkens ladder (a)).
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) return null;
+  if (input.tool_name !== BASH_TOOL_NAME) return null;
+  const command = input.tool_input === null || typeof input.tool_input !== 'object' ? undefined : input.tool_input.command;
+  if (typeof command !== 'string' || command.trim() === '') return null;
+
+  const envRoot = env[PROJECT_DIR_ENV];
+  const projectRoot =
+    typeof envRoot === 'string' && envRoot !== '' ? envRoot : typeof input.cwd === 'string' ? input.cwd : null;
+  const rootReal = resolveRealpath(projectRoot, realpath);
+  const cwdReal = resolveRealpath(input.cwd, realpath);
+  return decideBashCall({
+    command,
+    permissionMode: input.permission_mode,
+    cwdIsProjectRoot: rootReal !== null && cwdReal !== null && rootReal === cwdReal,
+    gates: readDeclarationGates(projectRoot, deps),
+  });
+};
+
+export const formatDecision = (decision) =>
+  JSON.stringify({ hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME, ...decision } });
+
+const readStdin = async () => {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString(UTF8);
+};
+
+export const main = async () => {
+  // Exit 0 on EVERY path — never exit 2 (an immediate block), never a top-level throw: this
+  // fires on every Bash call and must never become the blocker or the noise.
+  try {
+    const decision = runHook(await readStdin());
+    if (decision !== null) process.stdout.write(`${formatDecision(decision)}\n`);
+  } catch {
+    // Deliberately dark: anomalies are the runner's job to report at its own point of use.
+  }
+  return EXIT_OK;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main().then((code) => process.exit(code));

package/references/templates/agent_rules.md

@@ -18,8 +18,9 @@ Every AI agent working on this project **must** adhere to this protocol before w
 ### 1.1. Start of Session
 Read in order, then confirm before starting:
 1. `docs/ai/handover.md` — where we left off.
-2. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
-3. Confirm with the user: *"I'm taking task X. Confirm?"*
+2. `docs/ai/orchestration.json` — the CONFIGURED orchestration recipes (per activity/slot). Honor them: a silent recipe downgrade is a forbidden substitution.
+3. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
+4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
 **Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.

package/references/templates/handover.md

@@ -14,6 +14,7 @@ maxLines: 80
 
 **Last session:** {{DATE}}
 **Branch:** {{BRANCH}}
+**Active recipes:** not recorded yet — paste the configured-recipe line (composed from `docs/ai/orchestration.json`) and refresh it whenever the config changes.
 
 ## What was done last session
 

package/tools/commands.mjs

@@ -119,12 +119,19 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Place bundled cheap-model subagent definitions for mechanical work — sweeps, changelog skeletons, gate triage (Claude Code; opt-in; preview first).',
   },
+  {
+    key: 'hook',
+    invocation: invocationOf('hook'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Auto-approve your own declared gate commands (docs/ai/gates.json) via a Claude Code hook — exact matches only, previews first (opt-in).',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated) and which one fits this environment.',
+    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.',
   },
   {
     key: 'procedures',
@@ -140,6 +147,20 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the orchestration recipe for an activity from plain language — previews the change, then writes the config when you confirm.',
   },
+  {
+    key: 'review-state',
+    invocation: invocationOf('review-state'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
+  },
+  {
+    key: 'grounding',
+    invocation: invocationOf('grounding'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime
@@ -164,8 +185,8 @@ export const kindOf = (key) => byKey.get(key)?.kind ?? null;
 // (`upgrade`) OR the full slash form (`/agent-workflow-kit upgrade`); the first word is significant
 // and trailing args are ignored. Precise semantics:
 //   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
-//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/uninstall/help)
-//     → that mode
+//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/agents/hook/
+//     gates/set-recipe/uninstall/help) → that mode
 //   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
 export const routeInvocation = (token) => {
   if (token == null) return BARE_INVOCATION_MODE;

package/tools/detect-backends.mjs

@@ -88,6 +88,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -120,6 +121,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
       },
     },
     bin: 'agy',

package/tools/family-registry.mjs

@@ -44,6 +44,10 @@ import {
   readSettingsFile,
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
+// The gate-hook writer's own wired-detection + placed path — reused by the settings survey (one
+// implementation; gate-hook imports only node builtins + velocity-profile, so no cycle).
+import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mjs';
+import { GATES_REL } from './run-gates.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
@@ -438,11 +442,32 @@ export const surveyVelocity = (dir, deps = {}) => {
   }
 };
 
+// gate hook: the opt-in PreToolUse gate-approval hook (Mode: hook) — wired (the settings entry, in
+// EITHER settings file: the hooks contract merges both), the placed hook file, and the gate
+// declaration it consumes. Read-only; the wired-detection is REUSED from the writer (gate-hook.mjs
+// isHookWired — one implementation, never a drifting copy).
+export const surveyGateHook = (dir, deps = {}) => {
+  try {
+    const d = resolve(dir);
+    const exists = deps.exists ?? existsSync;
+    const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
+    const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    return {
+      wired: isHookWired(project.data) || isHookWired(local.data),
+      filePlaced: Boolean(exists(join(d, GATE_HOOK_FILE_REL))),
+      declarationPresent: Boolean(exists(join(d, GATES_REL))),
+    };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
 // the project-scoped settings survey (needs a project dir). Each area is independently localized-on-error.
 export const surveySettings = (dir, deps = {}) => ({
   recipes: surveyRecipes(dir, deps),
   attribution: surveyAttribution(dir, deps),
   velocity: surveyVelocity(dir, deps),
+  hook: surveyGateHook(dir, deps),
 });
 
 // bridges: HOST-scoped (no project needed). Wrapper command NAMES come from FAMILY_MEMBERS[].wrapperCmds