Files
gstack/bin/gstack-skill-gates
T
Garry Tanandcapy-ai[bot] 9e809ab5b1 investigate: opt-in gate that holds root cause before fix, through Bash too (GST-1461) (#4045)
* investigate: opt-in gate that holds root cause before fix, through Bash too (GST-1461)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* investigate gate: posix paths in edit blocks, CI fixes (GST-1461)

- hook: the edit branch computes the repo-relative path once in posix form, so
  the marker and deny text read src/total.ts on Windows too
- lib/review-depth.ts is back to main's pinned bytes; lib/investigate-gate.ts
  keeps its own copy of TEST_PATH
- gstack-skill-gates report: destructure session_id (the pregate secrets scan
  read the old line as a secret-named assignment)
- tests: pin core.autocrlf=false in the git fixtures, skip the symlink swap on
  Windows, give setup-hook-syntax-gate's fixture the shared TypeScript entry a
  shim runs, unit-test excludedReason, and check the smoke's pinned Claude Code
  version against docs/skill-gates.md

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes (GST-1461)

- checkTree saves the bytes a restore replaces in the session directory and
  the block names the copy, so a concurrent editor save is never lost
- a new commit is undone to its newest ancestor that existed before the
  baseline or that a remote-tracking ref holds, not to the baseline HEAD: a
  fix committed on another branch moves that branch back to its own tip,
  and pull/merge of fetched upstream commits is not undone; the block lists
  the commit's other changes left staged
- runGateHook takes the switch reading from its caller, so the
  investigate_gate config key has a literal reader (gstack-config-defaults)
- the slow checkout case gets an explicit 30 s test timeout

Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/red-team#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes, round 2 (GST-1461)

- an amend or rebase of commits from before the baseline on the same branch
  is undone to the baseline HEAD, not to its parent; on a different branch
  the gate blocks but leaves the commit in place
- existedBefore answers reachability with one rev-list call instead of one
  merge-base per ref, so a fix commit in a repo with hundreds of refs is
  still undone inside the 5 s hook deadline

Review-Finding: p2/specialist-batched#1 reader=testing
Review-Finding: p2/red-team#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-05 20:46:19 +00:00

105 lines
5.0 KiB
TypeScript
Executable File

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
* gstack-skill-gates — the opt-in enforcement hooks' helper (GST-1461).
*
* gstack-skill-gates settings --investigate
* Print a Claude Code settings JSON that registers the /investigate gate
* and turns its switch on, for \`claude -p --settings <file>\` or the Agent
* SDK's settings, so a headless run needs no settings.json edit.
* gstack-skill-gates report [--session <id>] [--expect armed] [--json]
* Count fired, blocked, released, observed and error markers per session
* from $GSTACK_STATE_ROOT/skill-gates/<session>/record.json.
*
* Exit codes: 0 ok · 1 usage (SKILL_GATES_USAGE) · 2 GATE_NOT_ARMED (--expect
* armed and a session never fired) · 3 GATE_ERRORED (a session recorded a hook
* error). Docs: docs/skill-gates.md.
*/
import * as fs from 'fs';
import * as path from 'path';
import { gatesRoot, readGateRecord, recordPath, type GateHook, type GateRecord } from '../lib/skill-gates';
const ROOT = path.resolve(import.meta.dir, '..');
const USAGE = 'Usage: gstack-skill-gates settings --investigate\n gstack-skill-gates report [--session <id>] [--expect armed] [--json]';
const HOOKS: Record<string, { env: string; source: GateHook; events: Array<{ event: string; shim: string; matcher?: string }> }> = {
'--investigate': {
env: 'GSTACK_INVESTIGATE_GATE',
source: 'investigate-gate',
events: [
{ event: 'PreToolUse', shim: 'investigate-gate-pre', matcher: 'Edit|Write|MultiEdit|NotebookEdit|Bash' },
{ event: 'PostToolUse', shim: 'investigate-gate-post', matcher: 'Bash' },
{ event: 'PostToolUseFailure', shim: 'investigate-gate-post-failure', matcher: 'Bash' },
{ event: 'Stop', shim: 'investigate-gate-stop' },
],
},
};
function usage(why: string): never {
process.stderr.write(`SKILL_GATES_USAGE: ${why}\n${USAGE}\n`);
process.exit(1);
}
const args = process.argv.slice(2);
if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(`${USAGE}\n`); process.exit(0); }
if (args[0] === 'settings') {
const picked = args.slice(1);
if (!picked.length || picked.some(a => !HOOKS[a])) usage(`settings takes ${Object.keys(HOOKS).join(' ')}`);
const settings: { env: Record<string, string>; hooks: Record<string, unknown[]> } = { env: {}, hooks: {} };
for (const flag of picked) {
const h = HOOKS[flag];
settings.env[h.env] = 'on';
for (const e of h.events) {
(settings.hooks[e.event] ??= []).push({ ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [{ type: 'command', command: path.join(ROOT, 'hosts', 'claude', 'hooks', e.shim), timeout: 10 }] });
}
}
process.stdout.write(`${JSON.stringify(settings, null, 2)}\n`);
process.exit(0);
}
if (args[0] !== 'report') usage('expected settings or report');
const flag = (name: string) => { const i = args.indexOf(name); return i >= 0 ? (args[i + 1] ?? usage(`${name} needs a value`)) : undefined; };
const session = flag('--session');
const expect = flag('--expect');
if (expect !== undefined && expect !== 'armed') usage('--expect takes armed');
const asJson = args.includes('--json');
const records: GateRecord[] = [];
if (session) {
const file = recordPath(session);
if (fs.existsSync(file)) records.push(readGateRecord(file, session));
} else {
let dirs: string[] = [];
try { dirs = fs.readdirSync(gatesRoot()); } catch { /* none yet */ }
for (const d of dirs.sort()) {
const file = path.join(gatesRoot(), d, 'record.json');
if (fs.existsSync(file)) records.push(readGateRecord(file, d));
}
}
const rows = records.flatMap(({ session_id: session, hooks }) => Object.entries(hooks).map(([hook, h]) => {
const runs = Object.values(h!.runs);
return {
session, hook, runs: runs.length, fired: runs.length,
blocked: runs.reduce((n, r) => n + r.blocked, 0), released: runs.filter(r => r.released_at).length,
observed: runs.reduce((n, r) => n + r.observed, 0), errors: h!.errors.length, error_codes: [...new Set(h!.errors.map(e => e.code))],
skipped: Object.keys(h!.skipped ?? {}),
};
}));
if (asJson) process.stdout.write(`${JSON.stringify({ rows }, null, 2)}\n`);
else {
process.stdout.write(`skill gates: ${rows.length} session-hook row(s) under ${gatesRoot()}\n`);
for (const r of rows) {
process.stdout.write(` ${r.session} ${r.hook} fired=${r.fired} blocked=${r.blocked} released=${r.released} observed=${r.observed} errors=${r.errors}${r.error_codes.length ? ` (${r.error_codes.join(',')})` : ''}${r.skipped.length ? ` skipped=${r.skipped.join(',')}` : ''}\n`);
}
}
if (rows.some(r => r.errors > 0)) {
process.stderr.write('GATE_ERRORED: a gate hook recorded an error; its stops and edits were allowed (docs/skill-gates.md#gate-errored)\n');
process.exit(3);
}
if (expect === 'armed' && (session ? !rows.some(r => r.fired > 0) : rows.length === 0 || rows.some(r => r.fired === 0))) {
process.stderr.write('GATE_NOT_ARMED: no fired marker for the expected session; the hooks never engaged (docs/skill-gates.md#gate-not-armed)\n');
process.exit(2);
}