diff --git a/bin/gstack-checks b/bin/gstack-checks index 574743a6c..58c03499b 100755 --- a/bin/gstack-checks +++ b/bin/gstack-checks @@ -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 [options] +const USAGE = `Usage: gstack-checks [options] detect list the checks run would execute and whether they are trusted (reads files only) detect --for health /health's dimensions: DIMENSION (), or DIMENSION none @@ -18,6 +19,9 @@ const USAGE = `Usage: gstack-checks [options] CHECK PASS|FAIL|ZERO_RUN|UNMAPPED|TOO_BROAD|ENV|TIMEOUT|INCOMPLETE status READY_FOR_SHIP when the last run passed every check at this tree, else NOT_READY; runs nothing + quick [--timeout ] the pre-commit pass: run's checks and tests with no consent prompt, ending with one line, + VERIFY PASS|FAIL|skipped: ; untrusted commands, no pregate context or + verify_before_commit=off skip instead of stopping; exit 1 only on FAIL --base 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 { + 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 { 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 { 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); diff --git a/bin/gstack-config b/bin/gstack-config index ed96fcae5..d3a4a4d29 100755 --- a/bin/gstack-config +++ b/bin/gstack-config @@ -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 \ diff --git a/changelog.d/verify-quick-check-before-commit.md b/changelog.d/verify-quick-check-before-commit.md new file mode 100644 index 000000000..2090aca55 --- /dev/null +++ b/changelog.d/verify-quick-check-before-commit.md @@ -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: `. 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. diff --git a/docs/skills.md b/docs/skills.md index e7b44cb05..8e7d8147d 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -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=` 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: `. 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` diff --git a/lib/checks.ts b/lib/checks.ts index 20b050111..c2289e482 100644 --- a/lib/checks.ts +++ b/lib/checks.ts @@ -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: ` 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); diff --git a/test/gstack-checks.test.ts b/test/gstack-checks.test.ts index b42ba7cbb..539afe49c 100644 --- a/test/gstack-checks.test.ts +++ b/test/gstack-checks.test.ts @@ -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 = {}) => 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 diff --git a/test/gstack-config-defaults.test.ts b/test/gstack-config-defaults.test.ts index f49e59dbd..4b5bf92f8 100644 --- a/test/gstack-config-defaults.test.ts +++ b/test/gstack-config-defaults.test.ts @@ -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 }); diff --git a/verify/SKILL.md b/verify/SKILL.md index 619e582fe..470fa0ecf 100644 --- a/verify/SKILL.md +++ b/verify/SKILL.md @@ -21,6 +21,26 @@ allowed-tools: +## 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: `: 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 diff --git a/verify/SKILL.md.tmpl b/verify/SKILL.md.tmpl index 2bd61cbda..76a59534d 100644 --- a/verify/SKILL.md.tmpl +++ b/verify/SKILL.md.tmpl @@ -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: `: 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