@sabaiway/agent-workflow-kit 1.28.0 → 1.30.0

package/tools/gate-hook.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+// gate-hook.mjs — the onboarding writer behind `/agent-workflow-kit hook`: places the bundled
+// PreToolUse gate-approval hook runtime (references/hooks/gate-approve.mjs) to the project's
+// .claude/hooks/agent-workflow-gates.mjs and wires ONE `PreToolUse` "Bash" entry into
+// .claude/settings.json. The hook then auto-approves byte-exact invocations of the gates
+// declared in docs/ai/gates.json (run from the project root) and asks on seeded-read-only
+// commands carrying the documented runtime residual — see the runtime's own header.
+//
+// A separate SIBLING of velocity, deliberately NOT a velocity flag: velocity's test-pinned
+// invariant is "writes ONLY .claude/settings.json", while this writer also places a file. It
+// REUSES the exported velocity machinery (readSettingsFile / resolveEffectiveMode) rather than
+// re-deriving it, and follows the family writer discipline verbatim:
+//   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
+//   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
+//     head (a dry-run stays usable on any project);
+//   • symlink-safe — a symlinked `.claude` / `.claude/hooks` / target file / settings.json is
+//     a STOP on BOTH dry-run and apply (a dry-run never promises a write the apply refuses);
+//   • refuses `bypassPermissions` / unsafe modes in EITHER settings file;
+//   • merge-don't-clobber — foreign hooks/matchers/keys and existing permissions are preserved
+//     semantically; our entry is added idempotently (re-apply never duplicates). The reused
+//     readSettingsFile validates `permissions.*` ONLY, so this writer adds its OWN strict shape
+//     precondition on any existing `hooks` key — a malformed `hooks`/`hooks.PreToolUse[]` shape
+//     is a STOP with ZERO writes, never a merge-through-clobber;
+//   • place-then-wire ORDER — the hook file is placed BEFORE settings are wired (a
+//     wired-but-missing hook would error on every Bash call);
+//   • a target hook file with DIFFERENT content while our entry is NOT wired is a precondition
+//     STOP (no file write, no settings mutation — wiring an unknown script as a PreToolUse hook
+//     is exactly what consent must not slide past); the recovery is named: delete the file to
+//     reseed from the bundle. An identical file is `already current`; an already-wired entry
+//     pointing at a diverged file is REPORTED, never unwired or clobbered (the cheap-agents
+//     preserved-customization discipline — no refresh-in-place, no marker/checksum machinery);
+//   • never writes settings.local.json; never commits.
+//
+// Exit codes: 0 done / dry-run (incl. the report-only diverged-but-wired state); 1 precondition
+// STOP; 2 usage. Dependency-free beyond the kit's own velocity exports, Node >= 18. No side
+// effects on import.
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  CLAUDE_DIR,
+  EXPECTED_WORKFLOW_VERSION,
+  SETTINGS_FILE,
+  SETTINGS_LOCAL_FILE,
+  UNSAFE_BYPASS_MODE,
+  SAFE_DEFAULT_MODES,
+  WORKFLOW_STAMP,
+  readSettingsFile,
+  resolveEffectiveMode,
+} from './velocity-profile.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const BUNDLED_HOOK_PATH = resolve(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
+export const HOOKS_DIR = '.claude/hooks';
+export const HOOK_FILE_REL = `${HOOKS_DIR}/agent-workflow-gates.mjs`;
+export const PRE_TOOL_USE_EVENT = 'PreToolUse';
+export const HOOK_MATCHER = 'Bash';
+// The literal settings fragment (the plan/test fixture): $CLAUDE_PROJECT_DIR is resolved by
+// Claude Code when it runs the hook command, so the entry survives project relocation.
+export const HOOK_COMMAND = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/agent-workflow-gates.mjs"';
+export const HOOK_TIMEOUT_SECONDS = 30;
+
+export const GATE_HOOK_STAMP = 'GATE_HOOK_STAMP';
+export const GATE_HOOK_SYMLINK = 'GATE_HOOK_SYMLINK';
+export const GATE_HOOK_UNSAFE_MODE = 'GATE_HOOK_UNSAFE_MODE';
+export const GATE_HOOK_MALFORMED = 'GATE_HOOK_MALFORMED';
+export const GATE_HOOK_DIVERGED = 'GATE_HOOK_DIVERGED';
+export const GATE_HOOK_BUNDLE = 'GATE_HOOK_BUNDLE';
+
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+const UTF8 = 'utf8';
+const LF = '\n';
+const CRLF = '\r\n';
+const ERROR_PREFIX = '[agent-workflow-kit]';
+const SETTINGS_JSON_INDENT = 2;
+const JSON_NEWLINE_PATTERN = /\n/gu;
+
+const TARGET_PLACE = 'place';
+const TARGET_CURRENT = 'already-current';
+const TARGET_DIVERGED = 'diverged';
+
+const USAGE = `usage: gate-hook [--dry-run | --apply] [--cwd <dir>] [--help]
+
+Places the bundled PreToolUse gate-approval hook to ${HOOK_FILE_REL} and wires ONE
+PreToolUse "Bash" entry into ${SETTINGS_FILE}. Default is --dry-run (a preview; writes
+nothing). --apply writes. The hook auto-approves byte-exact declared gate cmds
+(docs/ai/gates.json, project root) and asks on seeded-read-only commands carrying the
+documented runtime residual. Never writes ${SETTINGS_LOCAL_FILE}; never commits.`;
+
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+export const makeGateHookError = (code, message) =>
+  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'GateHookError', code, exitCode: EXIT_PRECONDITION });
+
+const fsDeps = (deps = {}) => ({
+  exists: deps.exists ?? deps.existsSync ?? existsSync,
+  lstat: deps.lstat ?? deps.lstatSync ?? lstatSync,
+  mkdir: deps.mkdir ?? deps.mkdirSync ?? mkdirSync,
+  readFile: deps.readFile ?? deps.readFileSync ?? readFileSync,
+  writeFile: deps.writeFile ?? deps.writeFileSync ?? writeFileSync,
+});
+
+const lstatNoFollow = (absPath, fs) => {
+  try {
+    return fs.lstat(absPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+const isJsonObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// ── the bundle ────────────────────────────────────────────────────────────────────────
+
+export const readBundledHook = (deps = {}) => {
+  const fs = fsDeps(deps);
+  const bundlePath = deps.bundlePath ?? BUNDLED_HOOK_PATH;
+  try {
+    return fs.readFile(bundlePath, UTF8);
+  } catch (err) {
+    throw makeGateHookError(GATE_HOOK_BUNDLE, `bundled hook runtime unreadable (${err.code ?? err.message}): ${bundlePath} — the kit install is incomplete`);
+  }
+};
+
+// ── preflight (read-only; velocity discipline) ────────────────────────────────────────
+
+const readStamp = (absPath, fs) => {
+  try {
+    if (!fs.exists(absPath)) return null;
+    const stamp = String(fs.readFile(absPath, UTF8)).trim();
+    return stamp.length ? stamp : null;
+  } catch {
+    return null; // unreadable stamp == not a valid deployment stamp (apply STOPs; dry-run reports)
+  }
+};
+
+const assertDirSafe = (absPath, relPath, fs) => {
+  const stat = lstatNoFollow(absPath, fs);
+  if (stat === null) return;
+  if (stat.isSymbolicLink()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${relPath} is a symlink — refusing to write through it`);
+  if (!stat.isDirectory()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${relPath} exists but is not a directory — refusing to write through it`);
+};
+
+const assertSettingsWritable = (absPath, fs) => {
+  const stat = lstatNoFollow(absPath, fs);
+  if (stat !== null && !stat.isFile()) {
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `${SETTINGS_FILE} exists but is not a regular file — refusing to clobber it`);
+  }
+};
+
+// Target plan: place | already-current | diverged. A symlinked / non-regular target is a STOP —
+// never a write-through, never a comparison pretending it is a file.
+const planTarget = (absPath, bundleContent, fs) => {
+  const stat = lstatNoFollow(absPath, fs);
+  if (stat === null) return { action: TARGET_PLACE };
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `${HOOK_FILE_REL} exists but is not a regular file — refusing to touch it`);
+  }
+  return fs.readFile(absPath, UTF8) === bundleContent ? { action: TARGET_CURRENT } : { action: TARGET_DIVERGED };
+};
+
+// The reused readSettingsFile validates permissions.* ONLY — this writer scans and appends
+// inside `hooks`, so any existing `hooks` key must be shape-valid BEFORE a write is planned:
+// a malformed shape is a STOP with zero writes, never a merge-through-clobber.
+const assertHooksShape = (data, relPath) => {
+  if (data === undefined || data.hooks === undefined) return;
+  if (!isJsonObject(data.hooks)) {
+    throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks" must be a JSON object`);
+  }
+  const entries = data.hooks[PRE_TOOL_USE_EVENT];
+  if (entries === undefined) return;
+  if (!Array.isArray(entries)) {
+    throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${PRE_TOOL_USE_EVENT}" must be an array`);
+  }
+  for (const entry of entries) {
+    if (!isJsonObject(entry)) {
+      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: every "hooks.${PRE_TOOL_USE_EVENT}[]" entry must be a JSON object`);
+    }
+    if (entry.hooks !== undefined && (!Array.isArray(entry.hooks) || entry.hooks.some((hook) => !isJsonObject(hook)))) {
+      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${PRE_TOOL_USE_EVENT}[].hooks" must be an array of objects`);
+    }
+  }
+};
+
+// Defensive scan (never throws): used for wired-detection in BOTH settings files — the local file
+// is read-only for this writer, so its shape is never a STOP, just never a false match. An entry
+// counts as OUR wiring only when it targets Bash (matcher "Bash") AND carries a command-type hook
+// running HOOK_COMMAND — a same-command entry under a different matcher (e.g. "Write") is NOT our
+// Bash approval hook, so it must not suppress the merge (else approvals/guard stay inactive while
+// status reports wired).
+export const isHookWired = (data) => {
+  const entries = isJsonObject(data) && isJsonObject(data.hooks) ? data.hooks[PRE_TOOL_USE_EVENT] : undefined;
+  if (!Array.isArray(entries)) return false;
+  return entries.some(
+    (entry) =>
+      isJsonObject(entry) &&
+      entry.matcher === HOOK_MATCHER &&
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some((hook) => isJsonObject(hook) && hook.type === 'command' && hook.command === HOOK_COMMAND),
+  );
+};
+
+export const buildHookSettingsEntry = () => ({
+  matcher: HOOK_MATCHER,
+  hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: HOOK_TIMEOUT_SECONDS }],
+});
+
+// Append our ONE entry; every foreign hook/matcher/key is carried over untouched. Only called
+// when the entry is absent (idempotence lives in the caller's plan, not in dedup-on-write).
+export const mergeHookEntry = (base) => {
+  const root = isJsonObject(base) ? base : {};
+  const hooks = isJsonObject(root.hooks) ? root.hooks : {};
+  const entries = Array.isArray(hooks[PRE_TOOL_USE_EVENT]) ? hooks[PRE_TOOL_USE_EVENT] : [];
+  return { ...root, hooks: { ...hooks, [PRE_TOOL_USE_EVENT]: [...entries, buildHookSettingsEntry()] } };
+};
+
+export const preflightGateHook = ({ cwd }, deps = {}) => {
+  const fs = fsDeps(deps);
+  const projectDir = cwd ?? deps.cwd ?? process.cwd();
+  const bundleContent = readBundledHook(deps);
+  const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
+  const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
+  assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+  assertDirSafe(join(projectDir, HOOKS_DIR), HOOKS_DIR, fs);
+  const target = planTarget(join(projectDir, HOOK_FILE_REL), bundleContent, fs);
+  assertSettingsWritable(join(projectDir, SETTINGS_FILE), fs);
+  const projectSettings = readSettingsFile(join(projectDir, SETTINGS_FILE), { ...deps, cwd: projectDir });
+  const localSettings = readSettingsFile(join(projectDir, SETTINGS_LOCAL_FILE), { ...deps, cwd: projectDir });
+  const { bypassPermissionsPresent, unsafeModePresent } = resolveEffectiveMode(projectSettings.data, localSettings.data);
+
+  if (bypassPermissionsPresent) {
+    throw makeGateHookError(GATE_HOOK_UNSAFE_MODE, `${UNSAFE_BYPASS_MODE} appears in Claude settings - refusing because it auto-approves Bash`);
+  }
+  if (unsafeModePresent) {
+    throw makeGateHookError(
+      GATE_HOOK_UNSAFE_MODE,
+      `an unsafe or unknown permissions.defaultMode is present in Claude settings - accepted modes: ${SAFE_DEFAULT_MODES.join(', ')}`,
+    );
+  }
+  assertHooksShape(projectSettings.data, SETTINGS_FILE);
+
+  const wiredInProject = isHookWired(projectSettings.data);
+  const wiredInLocal = isHookWired(localSettings.data);
+  // Diverged target + our entry NOT wired anywhere = STOP on BOTH dry-run and apply: applying
+  // would wire an unknown script as a PreToolUse hook — exactly what consent must not slide
+  // past. (Diverged + already wired is the user's own standing state: report-only, below.)
+  if (target.action === TARGET_DIVERGED && !wiredInProject && !wiredInLocal) {
+    throw makeGateHookError(
+      GATE_HOOK_DIVERGED,
+      `${HOOK_FILE_REL} exists with DIFFERENT content and is not wired — refusing to wire an unknown script as a PreToolUse hook; delete the file to reseed from the bundle, then re-run`,
+    );
+  }
+
+  return { projectDir, bundleContent, stamp, stampOk, target, projectSettings, localSettings, wiredInProject, wiredInLocal };
+};
+
+// ── the writer ────────────────────────────────────────────────────────────────────────
+
+const formatJson = (data, eol) =>
+  `${JSON.stringify(data, null, SETTINGS_JSON_INDENT).replace(JSON_NEWLINE_PATTERN, eol)}${eol}`;
+
+export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
+  const fs = fsDeps(deps);
+  const preflight = preflightGateHook({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+  const placePlanned = preflight.target.action === TARGET_PLACE;
+  const wirePlanned = !preflight.wiredInProject && !preflight.wiredInLocal;
+  const base = { placePlanned, wirePlanned, ...preflight };
+  if (dryRun) return { wrote: false, dryRun: true, ...base };
+
+  if (!preflight.stampOk) {
+    throw makeGateHookError(
+      GATE_HOOK_STAMP,
+      `not a deployed agent-workflow project at lineage ${EXPECTED_WORKFLOW_VERSION} (found ${preflight.stamp ?? 'none'}) — run init/upgrade first`,
+    );
+  }
+
+  // Place FIRST, then wire — a wired-but-missing hook would error on every Bash call.
+  const hookAbs = join(preflight.projectDir, HOOK_FILE_REL);
+  if (placePlanned) {
+    fs.mkdir(join(preflight.projectDir, HOOKS_DIR), { recursive: true });
+    fs.writeFile(hookAbs, preflight.bundleContent, UTF8);
+  }
+  if (wirePlanned) {
+    // Re-verify the target no-follow immediately BEFORE wiring: preflight read it earlier, and an
+    // external process could have swapped it (or slipped a symlink in) between preflight and now.
+    // Wiring settings to point at an unknown script is exactly what consent must not slide past, so
+    // confirm the on-disk bytes are still the bundle — abort with zero settings mutation otherwise.
+    const onDisk = lstatNoFollow(hookAbs, fs);
+    if (onDisk === null || onDisk.isSymbolicLink() || !onDisk.isFile() || fs.readFile(hookAbs, UTF8) !== preflight.bundleContent) {
+      throw makeGateHookError(
+        GATE_HOOK_DIVERGED,
+        `${HOOK_FILE_REL} changed after preflight — refusing to wire an unknown script as a PreToolUse hook (no settings change made); re-run`,
+      );
+    }
+    const merged = mergeHookEntry(preflight.projectSettings.data ?? {});
+    fs.writeFile(
+      join(preflight.projectDir, SETTINGS_FILE),
+      formatJson(merged, preflight.projectSettings.eol ?? LF),
+      UTF8,
+    );
+  }
+  return { wrote: placePlanned || wirePlanned, dryRun: false, ...base };
+};
+
+// ── report ────────────────────────────────────────────────────────────────────────────
+
+const TRUST_POSTURE_LINE =
+  'trust posture: the hook auto-approves ONLY byte-exact matches of the gate cmds declared in docs/ai/gates.json, invoked from the project root — gates.json is thereby a privileged file (whoever can edit it can get its commands auto-approved); an invalid declaration approves nothing.';
+
+const formatTargetLine = (result) => {
+  if (result.target.action === TARGET_PLACE) return `  - ${HOOK_FILE_REL}: ${result.dryRun ? 'would place' : 'placed'}`;
+  if (result.target.action === TARGET_CURRENT) return `  - ${HOOK_FILE_REL}: already current`;
+  return `  - ${HOOK_FILE_REL}: diverged from the bundle — preserved, never clobbered (already wired; delete the file to reseed from the bundle)`;
+};
+
+const formatSettingsLine = (result) => {
+  if (result.wiredInProject) return `  - ${SETTINGS_FILE}: already wired`;
+  if (result.wiredInLocal) return `  - ${SETTINGS_FILE}: already wired via ${SETTINGS_LOCAL_FILE} — not duplicated`;
+  return `  - ${SETTINGS_FILE}: ${result.dryRun ? 'would wire' : 'wired'} the ${PRE_TOOL_USE_EVENT} "${HOOK_MATCHER}" entry`;
+};
+
+export const formatResult = (result) => {
+  const lines = [
+    result.dryRun
+      ? 'agent-workflow gate hook — DRY RUN (no changes; re-run with --apply)'
+      : 'agent-workflow gate hook — APPLY',
+    formatTargetLine(result),
+    formatSettingsLine(result),
+    TRUST_POSTURE_LINE,
+  ];
+  if (!result.stampOk) {
+    lines.push(`note: no current deployment stamp found (${result.stamp ?? 'none'}) — --apply will refuse until init/upgrade runs.`);
+  }
+  if (!result.dryRun && result.wrote) {
+    lines.push('settings hot-reload: the hook is active for new Bash calls — no session restart needed.');
+    lines.push('hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the placed hook stays out of `git status` (the registry carries /.claude/hooks/).');
+  }
+  return lines.join(LF);
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────
+
+export const parseArgs = (argv) => {
+  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--dry-run') opts.dryRunFlag = true;
+    else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--cwd') {
+      i += 1;
+      if (argv[i] === undefined || argv[i].startsWith('-')) throw fail(EXIT_USAGE, '--cwd needs a directory argument');
+      opts.cwd = argv[i];
+    } else {
+      throw fail(EXIT_USAGE, `unknown argument: ${arg}`);
+    }
+  }
+  if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
+  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd };
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const errlog = deps.errlog ?? console.error;
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    const result = writeGateHook({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps);
+    log(formatResult(result));
+    return EXIT_OK;
+  } catch (err) {
+    errlog(err?.message ?? String(err));
+    if (err?.exitCode === EXIT_USAGE) errlog(USAGE);
+    return err?.exitCode ?? EXIT_PRECONDITION;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exit(main(process.argv.slice(2)));

package/tools/grounding.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// grounding.mjs — the grounded-review facts assembler behind `/agent-workflow-kit grounding`
+// (AD-038). An ungrounded agy review GUESSES (AD-028); the grounding CONTRACT is mechanized
+// (`agy-review --facts @f`, AD-033) but population was a manual chore — this tool emits the two
+// mechanical halves of a facts payload so assembly is a command, not hand-copying:
+//
+//   --constraints        slice the root AGENTS.md `## 🚫 Hard Constraints` section, verbatim
+//                        (exactly-one-match — 0 or >1 headings is a loud STOP, never a guess);
+//   --plan <path>        extract the plan's decision-bearing canonical sections, verbatim + whole:
+//                        `## Approach` (REQUIRED — its "What we are NOT doing" text rides inside;
+//                        it is not a heading in canon) and `## Verification` (REQUIRED — STOP if
+//                        missing), plus `## Decisions (locked)` (optional-if-absent, the engine §7
+//                        heading this release adds); a DUPLICATE heading is always a STOP.
+//
+// Byte budget: the output honors the same AGY_MAX_PROMPT_BYTES contract the agy wrapper enforces
+// (default 120000; the override may only TIGHTEN — above the OS single-argv ceiling ~131000 is
+// rejected, mirroring agy-review.sh), MINUS --reserve-bytes <n> — the artifact share the caller
+// expects `agy-review` to add around these facts. Overflow is TRIMMED tail-first with a loud
+// in-band marker + stderr report (never a silent cut).
+//
+// Catalog honesty: this is a WRITER — `--out <path>` writes a file. Invariant: `--out` accepts
+// only gitignored / out-of-repo scratch destinations and REFUSES a tracked path AND an in-repo
+// not-ignored path (a new untracked file would itself move the review fingerprint the facts are
+// about to ground). stdout is the default. It never commits and never runs a subscription CLI.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync, writeFileSync, lstatSync, realpathSync } from 'node:fs';
+import { resolve, join, relative, isAbsolute, dirname, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { fail } from './orchestration-config.mjs';
+
+// The agy single-argv byte contract (mirrors agy-review.sh — the wrapper is the enforcement home).
+export const DEFAULT_MAX_PROMPT_BYTES = 120000;
+export const ARGV_HARD_MAX = 131000;
+
+export const CONSTRAINTS_HEADING = /^## .*Hard Constraints$/;
+export const PLAN_SECTIONS = [
+  { heading: '## Approach', optional: false },
+  { heading: '## Verification', optional: false },
+  { heading: '## Decisions (locked)', optional: true },
+];
+
+// ── pure section slicing (exactly-one-match; the inject-methodology discipline) ────────
+
+// Slice ONE `## `-level section (its heading line through the line before the next `## ` heading),
+// verbatim. `heading` is a string (trimmed-line equality) or a RegExp over the trimmed line.
+// 0 matches → null when optional, else STOP; >1 matches → always STOP (never guess which).
+export const sliceSection = (text, heading, { optional = false, label = 'document' } = {}) => {
+  const lines = text.split('\n');
+  const matchesAt = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const trimmed = lines[i].trim();
+    if (typeof heading === 'string' ? trimmed === heading : heading.test(trimmed)) matchesAt.push(i);
+  }
+  const shown = typeof heading === 'string' ? heading : String(heading);
+  if (matchesAt.length === 0) {
+    if (optional) return null;
+    throw fail(1, `${label}: required section "${shown}" not found — STOP (nothing sliced)`);
+  }
+  if (matchesAt.length > 1) {
+    throw fail(1, `${label}: section "${shown}" appears ${matchesAt.length} times — must be exactly one; STOP (never guess which)`);
+  }
+  const start = matchesAt[0];
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^## /.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').replace(/\n+$/, '\n');
+};
+
+// ── assembly ───────────────────────────────────────────────────────────────────────
+
+export const assembleGrounding = ({ constraintsText = null, planText = null, planLabel = 'plan' } = {}) => {
+  const parts = [];
+  if (constraintsText != null) {
+    parts.push(sliceSection(constraintsText, CONSTRAINTS_HEADING, { label: 'AGENTS.md' }));
+  }
+  if (planText != null) {
+    for (const { heading, optional } of PLAN_SECTIONS) {
+      const section = sliceSection(planText, heading, { optional, label: planLabel });
+      if (section != null) parts.push(section);
+    }
+  }
+  return parts.join('\n');
+};
+
+// Trim `payload` to `budget` bytes, tail-first, with a loud in-band marker. The budget is a HARD
+// ceiling: when it is smaller than the marker itself, the marker is truncated too (the output may
+// never exceed `budget` — a facts file over the reserved share would push the final wrapper prompt
+// past the argv ceiling; codex R1 finding). Returns { text, trimmedBytes }. Never a silent cut.
+export const trimToBudget = (payload, budget) => {
+  const bytes = Buffer.byteLength(payload, 'utf8');
+  if (bytes <= budget) return { text: payload, trimmedBytes: 0 };
+  const marker = `\n[grounding] TRIMMED: the assembled facts exceeded the byte budget — tail dropped; tighten the sources or raise --reserve-bytes accounting.\n`;
+  const keep = Math.max(0, budget - Buffer.byteLength(marker, 'utf8'));
+  const joined = Buffer.from(payload, 'utf8').subarray(0, keep).toString('utf8').replace(/�+$/, '') + marker;
+  // Hard-cap the final text (covers budget < marker size): byte-slice, then drop any split rune.
+  const text = Buffer.from(joined, 'utf8').subarray(0, budget).toString('utf8').replace(/�+$/, '');
+  return { text, trimmedBytes: bytes - keep };
+};
+
+// ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
+
+const gitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
+};
+
+// STOP unless `outPath` is a safe scratch destination: outside any git work tree, or gitignored
+// inside one. A TRACKED path and an in-repo NOT-ignored path are both refused (a facts file must
+// never enter the tree it grounds — it would move the fingerprint and could be committed). The
+// check runs on the REAL destination, never the lexical path (codex R1 finding): a symlink leaf is
+// refused outright, and the parent directory is realpath-resolved first, so a gitignored or
+// out-of-repo symlink can never route the write onto a tracked/in-repo file. Returns the resolved
+// real path the caller must write to.
+export const assertScratchDestination = (outPath, cwd) => {
+  const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
+  let leaf = null;
+  try {
+    leaf = lstatSync(lexical);
+  } catch {
+    leaf = null; // absent → a fresh file; the parent still gets realpath-checked below
+  }
+  if (leaf?.isSymbolicLink()) {
+    throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
+  }
+  let realParent;
+  try {
+    realParent = realpathSync(dirname(lexical));
+  } catch {
+    throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
+  }
+  const full = join(realParent, basename(lexical));
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (top == null || top.status !== 0) return full; // no git tree → plain scratch, fine
+  const root = top.stdout.replace(/\r?\n$/, '');
+  const rel = relative(root, full);
+  if (rel.startsWith('..') || isAbsolute(rel)) return full; // really outside the work tree → scratch
+  const tracked = gitLine(['ls-files', '--error-unmatch', '--', rel], root);
+  if (tracked != null && tracked.status === 0) {
+    throw fail(1, `--out refuses a TRACKED path (${rel}) — grounding output is scratch; write it to a gitignored path or outside the repo`);
+  }
+  const ignored = gitLine(['check-ignore', '-q', '--', rel], root);
+  if (ignored == null || ignored.status !== 0) {
+    throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
+  }
+  return full;
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────
+
+const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
+
+Usage:
+  node grounding.mjs [--constraints] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
+
+  --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
+                       (exactly one matching heading, else a loud STOP)
+  --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
+                       "## Approach" + "## Verification" (REQUIRED — STOP if missing),
+                       "## Decisions (locked)" when present; a duplicate heading is a STOP
+  --reserve-bytes <n>  the artifact share agy-review will add around these facts — the output
+                       budget becomes AGY_MAX_PROMPT_BYTES − n (loud tail-trim on overflow)
+  --out <path>         write instead of stdout — gitignored / out-of-repo scratch ONLY
+                       (a tracked or in-repo not-ignored path is refused)
+
+Feed the output to the review wrapper: agy-review code --facts @<out>. AGY_MAX_PROMPT_BYTES
+honors the wrapper's contract (default ${DEFAULT_MAX_PROMPT_BYTES}; may only tighten — above the
+OS argv ceiling it is rejected). Writer honesty: --out writes ONE scratch file; nothing else is
+ever written; never commits, never runs a subscription CLI.
+
+Exit codes: 0 success; 2 usage; 1 STOP (missing/duplicate section, unreadable file, refused --out).`;
+
+const parseArgs = (argv) => {
+  let constraints = false;
+  let plan = null;
+  let out = null;
+  let reserve = 0;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--constraints') constraints = true;
+    else if (a === '--plan') {
+      plan = argv[i + 1];
+      if (!plan || plan.startsWith('--')) throw fail(2, '--plan requires a <path>');
+      i += 1;
+    } else if (a === '--out') {
+      out = argv[i + 1];
+      if (!out || out.startsWith('--')) throw fail(2, '--out requires a <path>');
+      i += 1;
+    } else if (a === '--reserve-bytes') {
+      const raw = argv[i + 1];
+      if (!raw || !/^\d+$/.test(raw)) throw fail(2, '--reserve-bytes requires a non-negative integer');
+      reserve = Number(raw);
+      i += 1;
+    } else throw fail(2, `unknown argument: ${a}`);
+  }
+  if (!constraints && plan == null) throw fail(2, 'nothing to assemble — pass --constraints and/or --plan <path>');
+  return { constraints, plan, out, reserve };
+};
+
+const resolveBudget = (env, reserve) => {
+  const raw = env.AGY_MAX_PROMPT_BYTES ?? String(DEFAULT_MAX_PROMPT_BYTES);
+  if (!/^\d+$/.test(raw)) throw fail(2, `AGY_MAX_PROMPT_BYTES='${raw}' is not a non-negative integer`);
+  const max = Number(raw);
+  if (max > ARGV_HARD_MAX) {
+    throw fail(2, `AGY_MAX_PROMPT_BYTES=${max} exceeds the OS single-argv ceiling (~${ARGV_HARD_MAX}) — the override may only tighten (mirrors agy-review)`);
+  }
+  const budget = max - reserve;
+  if (budget <= 0) throw fail(2, `--reserve-bytes ${reserve} leaves no budget under AGY_MAX_PROMPT_BYTES=${max}`);
+  return budget;
+};
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { constraints, plan, out, reserve } = parseArgs(argv);
+    const budget = resolveBudget(env, reserve);
+
+    const readOrStop = (path, label) => {
+      try {
+        return readFileSync(resolve(cwd, path), 'utf8');
+      } catch (err) {
+        throw fail(1, `${label} '${path}' is unreadable (${(err && err.code) || err}) — STOP`);
+      }
+    };
+    const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
+    const planText = plan != null ? readOrStop(plan, 'plan file') : null;
+
+    const payload = assembleGrounding({ constraintsText, planText, planLabel: plan ?? 'plan' });
+    const { text, trimmedBytes } = trimToBudget(payload, budget);
+    const stderr = trimmedBytes > 0
+      ? `[grounding] TRIM: assembled ${Buffer.byteLength(payload, 'utf8')} bytes > budget ${budget} (AGY_MAX_PROMPT_BYTES minus --reserve-bytes ${reserve}) — dropped ${trimmedBytes} tail bytes; the cut is marked in-band.`
+      : '';
+
+    if (out != null) {
+      const realOut = assertScratchDestination(out, cwd);
+      writeFileSync(realOut, text);
+      return { code: 0, stdout: `[grounding] wrote ${Buffer.byteLength(text, 'utf8')} bytes to ${out} — pass it as: agy-review code --facts @${out}`, stderr };
+    }
+    return { code: 0, stdout: text, stderr };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `grounding: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  // Exact writes + a natural exit (codex R2): console.log would append a stray newline to the
+  // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node
+  // flushes. The payload already ends with '\n' (sliceSection normalizes); only a non-payload
+  // message (help / the --out report) gains the terminating newline it lacks.
+  if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+  process.exitCode = r.code;
+}

package/tools/known-footprint.mjs

@@ -62,6 +62,7 @@ export const KIT_OWN_PATHS = [
 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: '/.claude/hooks/', owner: 'Claude Code', type: 'dir', falsePositiveRisk: false, note: 'project hooks (incl. the kit-placed gate-approval hook)' },
   { 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/presentation.mjs

@@ -41,6 +41,7 @@ export const SETTINGS_LABELS = Object.freeze({
   recipes: 'recipes',
   attribution: 'attribution',
   velocity: 'velocity',
+  hook: 'gate hook',
 });
 
 // Glyph sets — Unicode for a capable terminal, an ASCII fallback for a narrow / Windows-legacy one.