When Claude Code runs /verify before a commit, it now gets a quick check instead of the full fix loop (GST-3150) (#4508)

When Claude Code calls /verify on its own right before `git commit`,
gstack now runs one quick check-only command that ends in a single
`VERIFY PASS`, `VERIFY FAIL` or `VERIFY skipped: ` line; typing /verify
still runs the full skill.

Why: since Claude Code 2.1.286 any skill named `verify` is run before
every commit, so gstack's fix loop, its first-run notices and a hard
stop in repos with no remote landed on ordinary commits.

Nothing to do; `gstack-config set verify_before_commit off` turns the
check off.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/specialist-batched#1 reader=specialist-batched
Review-Finding: p1/specialist-batched#2 reader=specialist-batched
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-19 06:06:43 +00:00
1 parent 5afef04e31
commit b702243859
9 files changed
+177 -7

No files matched your search

+31 -4
View File
@@ -4,9 +4,10 @@
*/
import { spawnSync } from 'node:child_process';
import { cancelActive } from '../lib/pregate/supervise';
import { MAX_FAIL_LINES, TESTS, healthDimensions, isTrusted, ledgerPath, load, nothingToRun, readLedger, recordTrust, runChecks, status, type Loaded } from '../lib/checks';
import { MAX_FAIL_LINES, TESTS, healthDimensions, isTrusted, ledgerPath, load, nothingToRun, quickLine, readLedger, recordTrust, runChecks, status, type Loaded } from '../lib/checks';
import { readConfigKey } from '../lib/state-root';
const USAGE = `Usage: gstack-checks <detect|trust|run|status> [options]
const USAGE = `Usage: gstack-checks <detect|trust|run|status|quick> [options]
detect list the checks run would execute and whether they are trusted (reads files only)
detect --for health /health's dimensions: DIMENSION <name> <command> (<source>), or DIMENSION <name> none
@@ -18,6 +19,9 @@ const USAGE = `Usage: gstack-checks <detect|trust|run|status> [options]
CHECK <name> PASS|FAIL|ZERO_RUN|UNMAPPED|TOO_BROAD|ENV|TIMEOUT|INCOMPLETE <secs>
status READY_FOR_SHIP when the last run passed every check at this tree, else NOT_READY;
runs nothing
quick [--timeout <s>] the pre-commit pass: run's checks and tests with no consent prompt, ending with one line,
VERIFY PASS|FAIL|skipped: <what>; untrusted commands, no pregate context or
verify_before_commit=off skip instead of stopping; exit 1 only on FAIL
--base <branch> the branch pregate selects against (default: origin/HEAD's branch, else main)
@@ -41,10 +45,32 @@ function loadOrRefuse(root: string, args: string[], timeoutMs: number): Loaded |
return l;
}
const QUICK_RED_LINES = 10;
async function quick(root: string | null, args: string[], timeoutMs: number): Promise<number> {
const skip = (why: string) => { process.stdout.write(`VERIFY skipped: ${why}\n`); return 0; };
if (readConfigKey('verify_before_commit') === 'off') return skip('verify_before_commit is off (gstack-config set verify_before_commit on)');
if (!root) return skip('not inside a git repository');
const l = load(root, flag(args, '--base'), timeoutMs);
if ('refused' in l) {
const code = /\(([A-Z_]+)\)\s*$/.exec(l.refused)?.[1];
const ref = /\((origin\/\S+) is not a resolvable commit\)/.exec(l.refused)?.[1];
return skip(`${ref ? `no ${ref} to compare against (no remote, or it is not fetched)` : l.refused.replace(/^gstack-checks: /, '').split(':')[0]}, so no checks ran${code ? ` (${code})` : ''}`);
}
if (nothingToRun(l)) return skip('the repo declares no checks or tests');
if (!isTrusted(root, l.set)) return skip("the repo's check commands are not trusted yet; type /verify once to review them");
for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => { cancelActive(); process.exit(signal === 'SIGINT' ? 130 : 143); });
const { outcomes } = await runChecks(l, { root, timeoutMs });
const { line, red } = quickLine(outcomes);
for (const o of red) for (const text of o.lines.slice(-QUICK_RED_LINES)) process.stdout.write(` | ${text}\n`);
process.stdout.write(line + '\n');
return red.length ? 1 : 0;
}
async function main(argv: string[]): Promise<number> {
const [verb, ...args] = argv;
if (!verb || verb === '--help' || verb === '-h') { process.stdout.write(USAGE); return verb ? 0 : 64; }
if (!['detect', 'trust', 'run', 'status'].includes(verb)) { process.stderr.write(USAGE); return 64; }
if (!['detect', 'trust', 'run', 'status', 'quick'].includes(verb)) { process.stderr.write(USAGE); return 64; }
const mode = flag(args, '--for');
if (args.includes('--for')) {
if (verb !== 'detect' || mode !== 'health') { process.stderr.write(USAGE); return 64; }
@@ -54,9 +80,10 @@ async function main(argv: string[]): Promise<number> {
return 0;
}
const root = repoRoot();
if (!root) { process.stderr.write('gstack-checks: not inside a git repository\n'); return 3; }
if (!root && verb !== 'quick') { process.stderr.write('gstack-checks: not inside a git repository\n'); return 3; }
const timeoutS = Number(flag(args, '--timeout') ?? 600);
if (!Number.isFinite(timeoutS) || timeoutS <= 0) { process.stderr.write('gstack-checks: --timeout needs a positive number of seconds\n'); return 64; }
if (verb === 'quick') return quick(root, args, timeoutS * 1000);
const l = loadOrRefuse(root, args, timeoutS * 1000);
if (!l) return 3;
const trusted = isTrusted(root, l.set);
+14 -2
View File
@@ -93,6 +93,11 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
# # false = short names /qa, /ship
# disabled_skills: # comma-separated skills to leave unregistered,
# # e.g. make-pdf,pair-agent ("" = all enabled)
# verify_before_commit: on # on | off. on: when the agent runs /verify right
# # before a commit (Claude Code asks it to), /verify
# # runs a quick check-only pass. off: that pass prints
# # "VERIFY skipped" and runs nothing. Typing /verify
# # yourself always runs the full skill.
#
# ─── Writing style (V1) ──────────────────────────────────────────────
# explain_level: default # default = jargon-glossed, outcome-framed prose
@@ -334,6 +339,7 @@ lookup_default() {
update_check) echo "true" ;;
update_channel) echo "auto" ;; # auto | stable | main — bin/gstack-update-channel.sh resolves auto (docs/releases.md)
skill_prefix) echo "false" ;;
verify_before_commit) echo "on" ;; # on | off — off: /verify's pre-commit quick pass runs nothing (lib/checks.ts)
explain_level) echo "default" ;;
plan_mode_preamble) echo "on" ;; # on | off — off drops the plan-mode preamble on the next ./setup (#3168)
claude_loadout) echo "full" ;; # a modules/loadouts.json name — written by ./setup --loadout (docs/loadouts.md)
@@ -975,6 +981,12 @@ $_gstack_legacy_root"
echo "Error: design_detector '$VALUE' not recognized. Valid values: auto, off. Existing value left unchanged." >&2
exit 1
fi
# verify_before_commit: gstack-checks quick skips only on the literal "off",
# so a typo such as "of" would silently leave the pre-commit pass on.
if [ "$KEY" = "verify_before_commit" ] && [ "$VALUE" != "on" ] && [ "$VALUE" != "off" ]; then
echo "Error: verify_before_commit '$VALUE' not recognized. Valid values: on, off. Existing value left unchanged." >&2
exit 1
fi
# cross_project_learnings: empty get is the first-run prompt sentinel.
# Skills enable only on the literal "true". A typo must not persist — that
# keeps the feature off and suppresses the prompt. Reject, like
@@ -1155,7 +1167,7 @@ $_gstack_legacy_root"
skill_prefix explain_level plan_mode_preamble claude_loadout \
codex_reviews autoplan_shadow autoplan_shadow_model gstack_contributor skip_eng_review workspace_root \
artifacts_sync_mode artifacts_sync_mode_prompted artifacts_sync_removals plan_tune_hooks \
timeline_stop_hook design_detector design_detector_install_prompted memorable_recall \
timeline_stop_hook design_detector design_detector_install_prompted memorable_recall verify_before_commit \
browse_extension_id ship_measure_rule_trials ship_measure_behavior_panels \
ship_measure_judge_outputs ship_measure_ask_per_trial_usd ship_measure_budget_usd \
ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
@@ -1181,7 +1193,7 @@ $_gstack_legacy_root"
skill_prefix explain_level plan_mode_preamble claude_loadout \
codex_reviews autoplan_shadow autoplan_shadow_model gstack_contributor skip_eng_review workspace_root \
artifacts_sync_mode artifacts_sync_mode_prompted artifacts_sync_removals plan_tune_hooks \
timeline_stop_hook design_detector design_detector_install_prompted memorable_recall \
timeline_stop_hook design_detector design_detector_install_prompted memorable_recall verify_before_commit \
browse_extension_id ship_measure_rule_trials ship_measure_behavior_panels \
ship_measure_judge_outputs ship_measure_ask_per_trial_usd ship_measure_budget_usd \
ship_measure_max_rounds ship_measure_sweep_cases ship_measure_sweep_budget_usd ship_rerun_backend test_backend \
@@ -0,0 +1 @@
- **When Claude Code runs /verify right before a commit, it now gets a quick check instead of the full fix loop (GST-3150).** Claude Code 2.1.286 and later tell the model to run any skill named `verify` before every commit that isn't docs-only or tests-only, so gstack's /verify was starting its whole build-and-fix workflow, first-run notices included, on ordinary commits. Now that call runs one command, `gstack-checks quick`: the repo's existing checks (typecheck, lint) and the tests /ship would pick for the change, with no code edits, no new tests and no questions, ending in one line: `VERIFY PASS`, `VERIFY FAIL`, or `VERIFY skipped: <reason>`. A repo with no `origin` remote, check commands you haven't approved yet (type /verify once in that repo to review and approve them), or nothing to run is skipped and the commit goes ahead; a failure makes the model stop and ask you before committing. Typing /verify yourself still runs the full skill. To turn the pre-commit check off, run `gstack-config set verify_before_commit off`; to stop Claude Code from asking for it at all, install with `./setup --prefix`, which names the skill /gstack-verify.
+2
View File
@@ -670,6 +670,8 @@ The skill no longer installs, and `./setup` removes an existing gstack-owned `in
It asks once before running any repo command (`gstack-checks trust`) and asks again when a command changes. A touched file no test covers is `UNMAPPED`, a selection that ran zero tests is `ZERO_RUN`, and neither counts as green. A missing tool or service is reported, not worked around. It stops after five runs or when the same failure comes back twice, and asks for a focused failing test and a root-cause trace before another fix to a stubborn red. When everything passes, `gstack-checks status` prints `READY_FOR_SHIP tree=<tree>` without rerunning anything, and you run `/ship`. It never reviews, bumps versions, pushes or opens a PR.
Since Claude Code 2.1.286, any installed skill named `verify` makes Claude Code tell the model to run it right before each `git commit` (except docs-only and tests-only commits). When the model calls `/verify` that way, without you typing it or asking for checks, it gets a quick check-only pass instead of the loop: one `gstack-checks quick` call that runs the same checks and selected tests, edits nothing, adds no tests, asks nothing and skips gstack's startup steps, then ends with one line, `VERIFY PASS`, `VERIFY FAIL` or `VERIFY skipped: <reason>`. A skip (no `origin` to select tests against, commands you haven't trusted yet, nothing declared) lets the commit go ahead; a `FAIL` makes the model stop and ask you before committing. The arguments `quick` or `pre-commit` ask for the same pass. `gstack-config set verify_before_commit off` turns the pass into an immediate `VERIFY skipped`; installing with `./setup --prefix` (`/gstack-verify`) removes Claude Code's instruction altogether.
---
## `/qa`
+16
View File
@@ -12,6 +12,11 @@
* caller passes --allow-repo-commands.
* status: reads the last run's ledger; READY_FOR_SHIP only when every check
* passed at the current tree and command set. It runs nothing.
* quick: the pass /verify runs when the agent calls it right before a commit
* (GST-3150). Same checks and selection as run, but it never asks for consent:
* an untrusted command set, a missing policy source or the verify_before_commit
* switch ends it with one `VERIFY skipped: <reason>` line, and a not-run result
* (ENV, TIMEOUT, UNMAPPED, TOO_BROAD) is named, never a red.
*/
import { createHash } from 'node:crypto';
import * as fs from 'node:fs';
@@ -314,6 +319,17 @@ export async function runChecks(l: Loaded, o: RunOptions): Promise<{ outcomes: O
return { outcomes: final, ledger };
}
/** The quick pass's last line: FAIL on a red, PASS when something passed and nothing is red, else skipped. */
export function quickLine(outcomes: readonly Outcome[]): { line: string; red: Outcome[] } {
const red = outcomes.filter(o => o.verdict === 'FAIL' || o.verdict === 'ZERO_RUN' || o.verdict === 'INCOMPLETE');
const passed = outcomes.filter(o => o.verdict === 'PASS');
const notRun = outcomes.filter(o => o.verdict !== 'PASS' && !red.includes(o)).map(o => `${o.name} ${o.verdict}`);
const secs = (outcomes.reduce((sum, o) => sum + o.ms, 0) / 1000).toFixed(1);
if (red.length) return { red, line: `VERIFY FAIL: ${red.map(o => `${o.name} ${o.verdict === 'FAIL' ? o.detail : o.verdict}`).join(', ')}${red[0].log ? `; log ${red[0].log}` : ''}` };
if (!passed.length) return { red, line: `VERIFY skipped: nothing ran to a result (${notRun.join(', ') || 'no checks'})` };
return { red, line: `VERIFY PASS: ${passed.map(o => o.name).join(', ')} in ${secs}s${notRun.length ? ` (not run: ${notRun.join(', ')})` : ''}` };
}
/** READY_FOR_SHIP only when the ledger is for this tree and command set and every check and the tests passed. */
export function status(l: Loaded, ledger: Ledger | null): { ready: boolean; line: string } {
const tree = l.ctx.wtree.slice(0, 12);
+55 -1
View File
@@ -9,7 +9,7 @@ import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { declaredVerify, healthStack, manifestChecks, testVerdict } from '../lib/checks';
import { declaredVerify, healthStack, manifestChecks, quickLine, testVerdict, type Outcome } from '../lib/checks';
import type { CheckResult } from '../lib/pregate/types';
import { BASE_PREGATE, ROOT, cleanup, commit, makeFixtureRepo, runBin, write, type FixtureRepo } from './helpers/pregate-fixture';
@@ -101,6 +101,21 @@ describe('testVerdict', () => {
});
});
describe('quickLine', () => {
// Value: protects=the pre-commit line is red on a zero-run or incomplete selection and never green when nothing reached a result;
// fails_when=ZERO_RUN/INCOMPLETE leave the red set, or an all-ENV/TIMEOUT run reads VERIFY PASS; why_new=the fixture test only
// reaches PASS, FAIL and UNMAPPED; seam=none; no_claim=the wording after the VERIFY token
test('classifies red, not-run and passed outcomes', () => {
const o = (name: string, verdict: Outcome['verdict']): Outcome => ({ name, verdict, ms: 100, detail: 'exit 1', lines: [] });
expect(quickLine([o('typecheck', 'ENV'), o('tests', 'TIMEOUT')])).toEqual({ red: [], line: 'VERIFY skipped: nothing ran to a result (typecheck ENV, tests TIMEOUT)' });
expect(quickLine([]).line).toBe('VERIFY skipped: nothing ran to a result (no checks)');
expect(quickLine([o('typecheck', 'PASS'), o('tests', 'ZERO_RUN')]).line).toMatch(/^VERIFY FAIL: tests ZERO_RUN/);
expect(quickLine([o('tests', 'INCOMPLETE')]).red.map(r => r.name)).toEqual(['tests']);
expect(quickLine([o('typecheck', 'FAIL')]).line).toBe('VERIFY FAIL: typecheck exit 1');
expect(quickLine([o('typecheck', 'PASS'), o('tests', 'TOO_BROAD')]).line).toBe('VERIFY PASS: typecheck in 0.2s (not run: tests TOO_BROAD)');
});
});
describe('gstack-checks on a fixture repo', () => {
// Value: protects=nothing runs before consent, including pregate's selection manifest command, and any change to a check or a
// selection command needs consent again; fails_when=an untrusted or edited command executes; why_new=the boundary is new;
@@ -187,6 +202,45 @@ describe('gstack-checks on a fixture repo', () => {
expect(moved.status).toBe(1);
}, 60_000);
// Value: protects=the pass Claude Code triggers before a commit never asks for consent, never stops on a missing remote and ends
// with one VERIFY line, red only on a real failure; fails_when=an untrusted command runs, a no-remote repo exits non-zero, an
// unmapped file blocks a commit, or the off switch still runs checks; why_new=quick is new (GST-3150); seam=pregate's real
// selection and the fixture's selection marker; no_claim=the wording after the VERIFY token
test('quick: the pre-commit pass skips instead of stopping and ends with one line', () => {
const s = setup();
const quick = (env: Record<string, string> = {}) => s.checks(['quick'], env);
const last = (out: string) => out.trim().split('\n').at(-1) ?? '';
commit(s.repo, { 'lib/util.js': 'exports.add = (a, b) => b + a;\n' });
const untrusted = quick();
expect(untrusted.status).toBe(0);
expect(untrusted.out).toMatch(/^VERIFY skipped: .*not trusted/);
expect(fs.existsSync(s.mark)).toBe(false);
expect(s.checks(['trust']).status).toBe(0);
const green = quick();
expect(green.status).toBe(0);
expect(last(green.out)).toMatch(/^VERIFY PASS: typecheck, tests in [\d.]+s$/);
write(s.repo.work, 'lib/util.js', 'exports.add = (a, b) => a - b;\n');
const red = quick();
expect(red.status).toBe(1);
expect(last(red.out)).toMatch(/^VERIFY FAIL: tests /);
write(s.repo.work, 'lib/util.js', 'exports.add = (a, b) => b + a;\n');
write(s.repo.work, 'lib/orphan.js', 'exports.lonely = () => 2;\n');
const unmapped = quick();
expect(unmapped.status).toBe(0);
expect(last(unmapped.out)).toMatch(/^VERIFY PASS: typecheck in [\d.]+s \(not run: tests UNMAPPED\)$/);
const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-checks-noremote-'));
dirs.push(bare);
expect(spawnSync('git', ['init', '-q'], { cwd: bare, timeout: 30_000 }).status).toBe(0);
write(bare, 'calc.py', 'def add(a, b):\n return a + b\n');
const noRemote = runBin(s.repo, 'gstack-checks', ['quick'], {}, bare);
expect(noRemote.status).toBe(0);
expect(noRemote.out).toMatch(/^VERIFY skipped: no origin\/\S+ to compare against .*\(POLICY_SOURCE_UNAVAILABLE\)\n$/);
expect(spawnSync('bash', [path.join(ROOT, 'bin/gstack-config'), 'set', 'verify_before_commit', 'off'], { env: { ...process.env, ...s.repo.env }, encoding: 'utf8', timeout: 30_000 }).status).toBe(0);
const off = quick();
expect(off.status).toBe(0);
expect(off.out).toStartWith('VERIFY skipped: verify_before_commit is off');
}, 60_000);
// Value: protects=a selection that runs zero tests is not green; fails_when=exit 0 with no test counted reads PASS; why_new=the
// verdict is new; seam=pregate's runner summary (a bats stub printing an empty TAP plan); no_claim=node --test, which counts
// each file as a test, so an empty file there is not a zero run
+18
View File
@@ -322,6 +322,24 @@ describe('design_detector (auto|off, rejecting validator)', () => {
});
});
describe('verify_before_commit (on|off, rejecting validator)', () => {
// Value: protects=a typo cannot silently leave /verify's pre-commit pass on, and list/defaults show the switch; fails_when=the
// validator or a KEY loop entry is dropped; why_new=the key is new (GST-3150); seam=none; no_claim=gstack-checks' reading of it
test('rejects a typo, round-trips on/off and is listed', () => {
const run = (...args: string[]) => spawnSync('bash', [CONFIG_BIN, ...args], { encoding: 'utf-8', timeout: 30_000, env: { ...process.env, GSTACK_STATE_ROOT: STATE } });
expect(get('verify_before_commit')).toEqual({ out: 'on', code: 0 });
const bad = run('set', 'verify_before_commit', 'of');
expect(bad.status).toBe(1);
expect(bad.stderr).toContain("verify_before_commit 'of' not recognized");
expect(get('verify_before_commit').out).toBe('on');
for (const verb of ['list', 'defaults']) expect(run(verb).stdout).toMatch(/verify_before_commit:\s+on/);
expect(run('set', 'verify_before_commit', 'off').status).toBe(0);
expect(get('verify_before_commit').out).toBe('off');
expect(run('set', 'verify_before_commit', 'on').status).toBe(0);
expect(get('verify_before_commit').out).toBe('on');
});
});
describe('skill_routing and skill_contracts (on|off, default SWITCH_DEFAULT)', () => {
test('get, list and defaults report SWITCH_DEFAULT for both', () => {
for (const key of ['skill_routing', 'skill_contracts'] as const) expect(get(key)).toEqual({ out: SWITCH_DEFAULT[key], code: 0 });
+20
View File
@@ -21,6 +21,26 @@ allowed-tools:
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
## Right before a commit: the quick pass
Use only this section when you started /verify yourself because you are about
to run `git commit` (Claude Code asks for /verify before every commit), and the
user has not typed /verify or asked you to verify or run the checks in this
conversation. The arguments `quick` or `pre-commit` mean the same. When the
user typed /verify, skip this section and run the full skill below.
Skip the preamble and everything after this section: edit nothing, add no
tests, ask nothing. Run one command with a Bash timeout of 10 minutes:
```bash
"$HOME/.claude/skills/gstack/bin/gstack-checks" quick
```
It ends with one line. `VERIFY PASS: …` or `VERIFY skipped: <reason>`: go on
with the commit, and mention /verify only by quoting that line. `VERIFY FAIL:
…` (exit 1): don't commit over it; quote the line and the failing output to
the user and ask whether to fix it first or commit anyway.
## Preamble (run first)
```bash
+20
View File
@@ -23,6 +23,26 @@ allowed-tools:
- AskUserQuestion
---
## Right before a commit: the quick pass
Use only this section when you started /verify yourself because you are about
to run `git commit` (Claude Code asks for /verify before every commit), and the
user has not typed /verify or asked you to verify or run the checks in this
conversation. The arguments `quick` or `pre-commit` mean the same. When the
user typed /verify, skip this section and run the full skill below.
Skip the preamble and everything after this section: edit nothing, add no
tests, ask nothing. Run one command with a Bash timeout of 10 minutes:
```bash
"{{RUNTIME_ROOT}}/bin/gstack-checks" quick
```
It ends with one line. `VERIFY PASS: …` or `VERIFY skipped: <reason>`: go on
with the commit, and mention /verify only by quoting that line. `VERIFY FAIL:
…` (exit 1): don't commit over it; quote the line and the failing output to
the user and ask whether to fix it first or commit anyway.
{{PREAMBLE}}
# /verify — build, check, fix, repeat