v1.94.14.0 stamp: merge main d69ba2c6fb into #3902 (land)

This commit is contained in:
garrytan committed 2026-11-03 10:52:58 +00:00
commit 101201dba4
174 files changed
+8357 -425

No files matched your search

+11 -1
View File
@@ -1696,7 +1696,17 @@ the core skills, drives `/browse` on gstack's own browser, and runs the short
test list in its last step, where each file's reason sits beside it.
`test/windows-native-workflows.test.ts` keeps that list Windows-safe and fast.
The curated suite below runs nightly on main and on dispatch, never on a PR.
Windows checks run by path. `windows-scoped-tests.yml` (Windows Scoped Tests)
runs on every PR, and when the diff touches path, file-name or process code (the
filter is described at the top of the workflow), one `windows-latest` job runs
the PR's changed test files that are in the curated subset below. Its
`windows-scoped-tests` check passes when nothing is in scope, and a red run
blocks its PR. `windows-setup-e2e.yml` skips its Windows jobs when the only
install change is `package.json`'s version line. Both filters are pinned by
`test/windows-path-scope-workflow.test.ts`. To rerun chosen Windows-safe files on
a branch, dispatch `windows-scoped-tests.yml` with `-f files='<file> <file>'`.
The full curated suite below runs nightly on main and on dispatch, never on a PR.
`windows-free-tests.yml` plans on Linux (`--windows-only --ci-plan --shards 6
--shard-jobs $WINDOWS_FREE_JOBS`), runs one strict serial shard per
`windows-latest` job
+7 -6
View File
@@ -135,9 +135,8 @@ alone is not an ask.
A lane that builds something plans first. Its first act after the session-start install
check, before any product code, is a `/autoplan` run on its brief, sized to the work. The
phases run in order, CEO, then design, then DX, then eng, with design and DX only when the
scope has them, and a fix the exemptions below don't cover gets a short run (`--no-ui --no-dx --max-rounds 1`, with
`--estimate-usd` set so a small `--spend-cap` still seats its attempts), not no run. On Capy the
full run's phases run in order, CEO, then design, then DX, then eng, with design and DX only when the
scope has them. A bug fix gets no plan review and a feature gets the lean run (both below). On Capy the
unattended loop is `autoplan/DRIVER.md` in the gstack checkout. New functionality a lane
takes on part-way, scope its brief did not name, gets its own plan and its own ask before
the lane builds it. In the rules file this is rule 24 of the
@@ -183,9 +182,11 @@ flaky pass's repairs, slot stamps, CHANGELOG-only conflict resolves and a size o
cap re-pinned under the controller's written grant need no plan. Two kinds of fix are exempt
too: an S1 emergency (a broken install or upgrade, a red main, a security bug), and a fix
from a problem list that was already diagnosed and audited, where that list is the plan.
Every other fix, a one-line bug fix included, gets a one-round, eng-only plan: the short
run above, with the CEO phase closed before its voices are dispatched
(`gstack-autoplan close --out <run dir> --phase ceo --deferred "eng-only fix plan" --by agent:<thread>`).
Any other bug fix is exempt too (R65; the brief's reason is `bug fix (R65)`): `gstack-autoplan next --kind fix` prints
`AUTOPLAN: not needed (bug fix; R65)` and writes nothing, and the PR carries the bug's
proof, a repro on current main or a failing test written first. A feature gets the lean
run, `--kind feature`: one reviewer reading the plan and the draft code together, one gate
revision and no carry check (docs/unattended.md). `--full` brings back the full run.
A crew may add exemptions
in its rules file with the owner's words and date; it does not remove these. The brief
says which applies, `Plan: required | approved: <run> | exempt: <reason>`, so an
+4 -1
View File
@@ -42,7 +42,10 @@ no host profile, so a workflow started there is refused (`INSTALL: fail verdict
— … (review-voice certifies only the read-only helpers); fix: run
GSTACK_CAPY_ROOT=<root> bash <root>/capy/skill/gstack/scripts/install.sh --for
<skill> …`). A review-voice check never replaces an ok verdict that a fuller
install wrote for the same HEAD and project. The reverse is an in-place
install wrote for the same HEAD and project. Nor does one run from another
project shadow the session's own verdict: when the verdict for the current
project is a review-voice one, admission reads the session's launched
`GSTACK_INSTALL_VERDICT` instead (GST-1161). The reverse is an in-place
upgrade: a reviewer later asked to run a workflow runs the same installer
`--for <skill>`, which reuses the checkout (`upgrading the review-voice
install in place to --for <skill> (same checkout ...; no second clone)`),
+3 -1
View File
@@ -22,7 +22,9 @@ dropped), so a command with quotes or `$` never passes through a shell string;
1. `--plan-file <file>`: an operator-given file, read from disk.
2. Otherwise `price_file` in `.gstack/pregate.json` as committed on
`origin/<base>` (`--base`, default origin/HEAD's branch): a repo-relative
`origin/<base>` (`--base`, default origin/HEAD's branch unless it names the
checked-out branch, its upstream or HEAD's commit, then the PR's base, the
remote's live HEAD, `main` or `master`): a repo-relative
path whose bytes are read from the **HEAD commit** (`git show HEAD:<path>`),
never from the working tree.
+3 -1
View File
@@ -66,7 +66,9 @@ unless the command says it is a smoke run.
## Which copy is read
By default the reviewed copy is read: `git show origin/<base>:.gstack/eval-models.json`
(`--base`, default origin/HEAD's branch). A branch cannot loosen the rules it
(`--base`, default origin/HEAD's branch unless it names the checked-out branch,
its upstream or HEAD's commit, then the PR's base, the remote's live HEAD, `main`
or `master`). A branch cannot loosen the rules it
is checked against. When the working-tree copy differs, an
`EVAL_MODELS_NOTE:` line says so. `--models-from head` lints with the working-tree copy
instead. Use it for the PR that adds or changes the file; the source label
+8 -5
View File
@@ -188,11 +188,14 @@ digest's first line shows its gstack version; re-copy it after upgrading.
For Codex, setup reads the top-level `model` from
`${CODEX_HOME:-~/.codex}/config.toml` and generates the matching behavioral
profile, falling back to `gpt-6-astra` when no usable model is configured.
`gpt-5.6-sol` automatically receives bounded-scope instructions that
finish the requested lake without expanding into adjacent cleanup or speculative
hardening. The Sol profile is exact-match only: dated snapshots and other 5.6
variants get the generic GPT profile, and setup warns on near-misses like
`gpt-5.6-sol-2026-08-01`. Override detection with `./setup --host codex --model <id>` — the
The current OpenAI tiers are `gpt-6-astra` (frontier), `gpt-6.1-sol` (smart, the
default eval tier) and `gpt-6-luna` (lowest cost); `gpt-6.1-sol`
and `gpt-6-luna` get the generic GPT profile. Only `gpt-5.6-sol` receives the
bounded-scope instructions that finish the requested lake without expanding into
adjacent cleanup or speculative hardening, because that patch was measured on 5.6
Sol; extending it to `gpt-6.1-sol` waits for its own scope eval. The Sol profile is
exact-match only: dated snapshots and other 5.6 variants get the generic GPT
profile, and setup warns on near-misses like `gpt-5.6-sol-2026-08-01`. Override detection with `./setup --host codex --model <id>` — the
override applies to that run only; set `model` in your Codex `config.toml` to
make it stick across upgrades. After changing your Codex model, rerun
`./setup --host codex` to regenerate the skills.
+221 -7
View File
@@ -85,11 +85,12 @@ the byte-pinned `/ship` renders in `test/fixtures/golden/`).
| `serial_patterns` | test-file globs the `lanes` check runs one process per file, apart from the unit files (default `**/*.serial.test.*`) |
| `sealed` | sealed or eval output that must never reach a public destination; read by the pre-push hook and `gstack-pregate sealed` (see [sealed output](#sealed)) |
| `price_file` | repo-relative path of the paid gate's call-plan data file (`GSTACK_EVAL_CALLS v1`); `gstack-eval-plan price-gate` prices from it and never executes anything ([docs/eval-calls.md](eval-calls.md)) |
| `stall_timeout_s` | seconds a test command may print nothing before its process group is killed and the check is `incomplete` (`PREGATE_STALLED`); default 300, `0` disables; `--stall-timeout` overrides; the `--remote` gate is exempt (see [supervision](#supervision)) |
| `stall_timeout_s` | seconds a test command may print nothing while using under a tenth of one CPU before its process group is killed and the check is `incomplete` (`PREGATE_STALLED`); default 300, `0` disables; `--stall-timeout` overrides; the `--remote` gate is exempt (see [supervision](#supervision)) |
| `timeout_s` | seconds each runner process may take (the unit-file group, each serial file, each guard without its own `timeout_s`, and the remote gate's deadline) when `--timeout` is not passed; 1 to 3600, default 600. `gstack-ship-preflight` and the `finish` fallback run pregate without `--timeout`, so this is how a repo with long lanes sets theirs |
| `remote_gate` | the repo's remote test gate command; under 8 cores the local test tier becomes a `requires-remote` obligation naming it, and `--remote` runs it (see [remote gate](#remote-gate)) |
| `run_profiles` | name → `{ workflow, events, jobs, artifact, max_age_hours?, os? }`: the GitHub Actions runs `clear --run` verifies as evidence on the identical tree; a profile named after a lane (`free-tests.yml/macos-named-regressions`) clears that lane (see [run evidence](#run-evidence)). `--from-run` and the main-push reuse job verify runs against them too ([from-run](#from-run), [CI reuse](#ci-reuse)) |
| `remote_gate_runs` | `{ profiles, inventory, skipped? }`: the run profiles that together clear `pregate.json/remote_gate`, the command that prints the remote gate's test files, one per line, which their runs must cover, and an optional command that prints which selected files the gate itself never runs (see [run evidence](#run-evidence)) |
| `ship_lanes_from` | maps each exact /ship lane command to `{ profiles, inventory }`: the run profiles whose verified runs at HEAD's clean tree carry that lane instead of running it, and the command listing its test files, which their runs must cover (see [CI carry](#ci-carry)); read from the base branch only |
| `allowlist` | `[{ finding, paths?, pattern?, reason }]`: benign findings the `secrets` check accepts and names as allowlisted, by gstack-redact finding id or non-secret category, path globs and a pattern anchored at the finding; never `env.value` (see [allowlist](#allowlist)) |
Only the `origin/<base>` copy or the user-owned file below is honoured, so a
@@ -173,7 +174,7 @@ The list lives in its own file, not in `pregate.json`, because older pregate rea
```
gstack-pregate [--stage preflight|tests|all] [--only <check,..>] [--allow-repo-commands] [--policy-from base|head]
[--timeout <s>] [--stall-timeout <s>] [--remote --spend-cap <usd>] [--run <id>] [--from-run <id|url>] [--explain] [--json]
[--timeout <s>] [--stall-timeout <s>] [--remote --spend-cap <usd>] [--run <id>] [--from-run <id|url>] [--no-ci-carry] [--explain] [--json]
gstack-pregate verify | clear --remote <workflow.yml/job> --run-url <url> | lanes | validate | init
```
@@ -459,10 +460,17 @@ test-tier command:
a one-file run (each serial file) reports its file from the launch for any
runner. Other runners (node --test, vitest, jest, pytest, playwright test, flutter test, dart test, cargo test) get heartbeats
only. A heartbeat follows each 60 s with no progress line;
- is killed as **stalled** when its log does not grow for the stall timeout
(`--stall-timeout <s>`, else `stall_timeout_s`, else 300; `0` disables): the
check is `incomplete` with `PREGATE_STALLED` and names the last file
started; the next serial file still runs. The `--remote` gate is exempt: a
- is killed as **stalled** when its log does not grow and its process group
stays under a tenth of one CPU for the stall timeout (`--stall-timeout <s>`, else
`stall_timeout_s`, else 300; `0` disables): the check is `incomplete` with
`PREGATE_STALLED` and names the last file started; the next serial file
still runs. The group counts as busy when its CPU time, sampled each second,
grew by at least a tenth of the wall time, so a quiet suite that is working
(FOUN-63: a parallel `check.sh` silent for 9 minutes) is not killed, while
a hang that waits on nothing is. A hang that keeps burning CPU is left to
the timeout. Linux reads `/proc` (exited children's time included once
reaped); macOS and other BSDs read `ps -S`; a failed read skips that
sample. Windows reads no CPU time here and uses log growth alone. The `--remote` gate is exempt: a
gate that waits on CI is quiet by design, so only its timeout bounds it, and
its heartbeats add `; last output: <the gate's last line>`;
- is killed as **timed out** when that runner process reaches its timeout
@@ -486,8 +494,15 @@ the selected local files as a `requires-remote` obligation with the command to
run, `pregate.json/remote_gate` (the declared command) or
`test_backend/<backend>` (gstack's `scripts/ubicloud/ubi-runner.sh run --src
<repo> -- '<runner> <files>'`). Without either, the tier runs locally under
the supervision above. Close the obligation one of three ways:
the supervision above. Close the obligation one of four ways:
- by default, when the base declares `remote_gate_runs`, let CI clear it: the
tests stage clears it on its own from a verified run at this exact tree
([CI carry](#ci-carry)), and the uncleared obligation's detail names that
route first (`push, then gstack-ci-carry wait --base <base> and rerun
gstack-pregate --allow-repo-commands`, the whole pregate, so the record keeps
its preflight checks) and the VM only as the opt-in (under `--no-ci-carry` it
names the VM route); or
- after running it, `gstack-pregate clear --remote pregate.json/remote_gate
--receipt <file>` with the gate's output, validated as `--remote` validates it
(a run URL is refused, `PREGATE_RECEIPT_INVALID` for a bad receipt; a receipt
@@ -900,6 +915,113 @@ as a usage error. It changes nothing in the preflight stage: with `--stage all`
the preflight checks, the secrets scan included, run as before, and
`--stage tests` runs no preflight check in that invocation, with or without it.
<a id="ci-carry"></a>
### CI carry: pregate and /ship use CI's run instead of running again (GSTA-258)
CI is the one full test run. When a verified run already passed at the exact
tree being tested, pregate's tests stage and /ship's test lanes use it instead
of running the suite a second time. `lib/ci-carry.ts` `findCarry` decides, and
it accepts a run only when all of these hold:
- The working tree is HEAD's committed tree (the `gstack-wtree` fingerprint
equals `HEAD^{tree}`), read before the lookup and again after it. A dirty
tree, an untracked file or an edit made during the lookup never carries.
- The newest of HEAD's runs (up to 10) under each named profile passes
`verifyRun` above: same-repository head (a fork run never counts), the
profile's workflow, event and jobs, the newest attempt, no newer red or
running run on HEAD, within `max_age_hours`, and a `tree.json` naming HEAD's
tree. A `pull_request` run counts only when the pull request already
contained its base.
- Every run executed tests, and with an inventory command, the runs'
`tree.json` files cover every file it prints. Each run is read once more
afterward (`run_changed`).
Security and advisory scans, the sealed guard, guards and every preflight-stage
check always run; only test lanes carry.
**The tests stage.** Without `--from-run`, when the base branch declares
`run_profiles`, `gstack-pregate` looks up the newest verified run at HEAD under
the profiles `--from-run` would use and applies it as `--from-run` does: the
selected local files its `tree.json` lists count as passed, and only the rest
run. On a small machine a selection the run covers records no remote gate
obligation. It prints `CI_CARRY: accepted <receipt>` or `CI_CARRY: none
(<reason>)` on stderr; `--no-ci-carry` skips the lookup.
When files are left over, the remote gate obligation still clears from the
same run when the base declares `remote_gate_runs` naming that run's profile:
the run must pass every `clear --run` check, with the carried files counted
as selected files. So a remainder of only files the gate's `skipped` command
names (gstack's paid evals, which the gate itself reports as
`PREGATE_REMOTE_PAID_ONLY` with `tests=0`) clears with `skipped=<n>` in the
receipt instead of becoming an obligation nothing can clear. The line is
`CI_CARRY: cleared pregate.json/remote_gate <receipt>`, or `CI_CARRY:
pregate.json/remote_gate stays uncleared (<reason>)` when a check refuses, for
example a gate inventory file missing from the run's `tree.json`.
**gstack's own gate.** gstack's `.gstack/pregate.json` declares
`remote_gate_runs` with the `ci-reuse/free-tests` profile, so on gstack a green
Free Tests run at the same tree is how the remote gate obligation clears, and
the Ubicloud VM (`gstack-pregate --stage tests --remote`) is an opt-in for when
no such run exists. The order after a push: wait for Free Tests
(`gstack-ci-carry wait --base main`), then `gstack-pregate
--allow-repo-commands`. A `pull_request` run tests GitHub's merge commit, so on
a branch that does not contain the base tip it tested another tree and
`CI_CARRY` says `none (no_verified_run: … tree_mismatch)`: dispatch Free Tests
on the branch
(`gh workflow run free-tests.yml --ref <branch>`), which tests HEAD's own tree,
and wait again. The preflight stage (generated-file freshness, secrets, strays
and the other mechanical checks) and the sealed guard are unchanged and always
run here. The macOS and Windows lane
obligations still clear with `gstack-pregate clear --remote <lane> --run-url
<url>` from their CI runs.
**/ship lanes: `ship_lanes_from`.** A lane carries only when the base branch's
`.gstack/pregate.json` maps its exact command (the evidence ledger binds the
command's sha256; a label alone never carries) to the profiles whose runs carry
it and the command that lists its test files:
```json
"ship_lanes_from": {
"bun run test": { "profiles": ["ci-reuse/free-tests"], "inventory": "bun --no-env-file --config=/dev/null run scripts/test-free-shards.ts --list | sed -n 's/^ //p'" }
}
```
A carried lane prints `LANE: <label> carried run=<id>/<attempt> tests_ran=<n>`
and writes an explicit CI-sourced ledger row (`gstack-evidence record-ci
--label <label> --base <base> -- <command>`, which finds and verifies the run
itself, so no caller hands it run ids or a test count: `source: "ci"`, its runs
and profiles, the run's finish time as `ts`, bound to the clean tree), never a
fictitious local run. `gstack-evidence check` grades it
like any row and names `source=ci runs=…`, so `finish`'s FRESH check and the
24-hour age limit apply to the CI run's own time. A mapped lane that cannot
carry prints `CI_CARRY: none label=<label> (<reason>)` and runs here. Every
other lane runs through `gstack-evidence run --reuse`: the newest row for its
label, command and working tree is reused when it passed with a counted run
under the same runtime (bun and node versions, OS, architecture, runner image)
within 24 hours; a newer failure on that tree vetoes an older pass, and the
reused copy keeps the original timestamp. The cache is this machine's ledger
only; across machines, CI is the trust boundary.
**Finish, push and accept.** `gstack-ship-release finish` commits the release
metadata, so the stamped tree has no CI run yet. A mapped lane that is not
already FRESH is deferred (`EVIDENCE: DEFERRED`), and the pregate runs only its
preflight stage on the stamped tree, written to its own file so the full
`.gstack/tmp/pregate.json` stays in place until `accept` replaces it. `gstack-ship-release push --early` (the
Phase 2 push that lets CI run beside the review) runs the secrets scan and the
sealed guard before it pushes. After the final push,
`gstack-ship-release accept --base <base> --lane …` waits (bounded by `--wait`)
for the run at the pushed HEAD, stops on a red or still-running run, carries
each mapped lane from the green run at that exact tree, reuses or runs the rest,
checks every lane FRESH and reruns the pregate there, whose tests stage carries
the same run. `gstack-ship-receipt write` records the carried runs as
`ci_carried: [{ lane, run, attempt, tree }]`, and the `SHIP_RECEIPT:` line names
them (`ci_carried=<lane>:<run>/<attempt>`).
**`gstack-ci-carry`.** `find [--profile <name>]… [--command <exact lane command>
--allow-repo-commands]` prints the verdict for HEAD; `wait [--timeout <s>]`
polls the newest run at HEAD until it completes (run it in the background) and
prints `CI_WAIT: green|red|running|none`, then `find`'s verdict on green.
<a id="ci-reuse"></a>
### Main pushes reuse the merged pull request's run
@@ -937,6 +1059,91 @@ and without it every push falls back to the full run. Windows Free Tests now
runs nightly and by hand only (docs/support-tiers.md), never on a push, so its
`reuse` job is always skipped and every nightly run takes the strict path.
<a id="flaky-exception"></a>
## Owner-granted flaky exception
A timing flake in a test file the pull request never touched can keep a remote
gate obligation red: the rerun hits the same 5 s timeout on a loaded runner,
and nothing in the diff can fix it. `clear --flaky-exception` lets the owner
accept named cases for one head, on the run's own records:
```bash
gstack-pregate clear --remote pregate.json/remote_gate --run <id|url> \
--flaky-exception "test/docsync-fault-interface-legacy.test.ts::rejects legacy-third" \
--pr <n> --allow-repo-commands
```
The first call checks everything below and then refuses with
`reason=grant_needed`, printing the exact `gstack-approvals add` command to run
once the owner says yes: its `--scope` is `flaky-exception:<sha256>`, a digest of
the repository, PR, head, tree, lane, every run with its attempt, and the sorted
cases. Record the owner's exact words in that row, then rerun the same clear with
`--grant <the row id>`. The obligation clears only when all of this holds:
- **Every failure is named from the run's own records.** A red run uploads no
`tree.json`, so the clear reads the strict shard runner's artifacts instead
(`free-plan`, `free-result-<n>` and `free-test-shard-logs-<n>` in
`free-tests.yml`; the `windows-` names in `windows-free-tests.yml`; any other
workflow refuses with `no_shard_results`). Every job of the attempt is
reconciled: only the shard jobs (`free-suite (<n>)`) and the aggregate that
needs them may fail, every job the profile requires must pass, and any other
failed or cancelled job refuses (`unnamed_failure`). Every planned shard needs
its result; a missing result, a timed-out shard or a missing summary is
`shard_incomplete`. A failure the runner could not attribute to a test file,
an unhandled error between tests, or a `(fail)` line in a failed shard's log
that its result does not record refuses. A retry that passed is a recovered
flake; a retry that failed again keeps its own failures.
- **The cases are exactly the failures.** At most three, written as
`<test file>::<test name>` the way the run printed them. A failure no
`--flaky-exception` names refuses (`unnamed_failure`), and so does a named
case that did not fail (`case_not_failed`). The refusal lists the run's
failures in that form.
- **The files are not the PR's business.** A named file in the PR's diff
(`case_in_diff`), or one the import graph reaches from any changed path
(`case_in_closure`, lib/pregate/import-graph.ts with the base branch's
`dependencies`), refuses. The closure follows imports only: a test that reads a
changed doc, template or workflow through the file system is not reached, so
required CI stays the check on it. A paid test file (`case_paid`) and a
security test (`case_security`: a file name with cso, secrets, gitleaks, sealed,
redact or redaction, osv, security, sanitize or inject) are never excepted. Security scans themselves are pregate checks and CI jobs,
not test cases, so no exception can reach them.
- **One head, one grant.** The runs must have tested pregate.json's own head and
tree, with no stamp-only substitution (`head_mismatch`); the PR must be open with
that head (`pr_mismatch`); no newer run of the workflow may exist on the head
(`newer_run`), and the run may not move to another attempt during the check
(`run_changed`). The grant row must carry this exception's scope
(`grant_mismatch` otherwise), record `approved` (`grant_not_approved`) and be
the owner's words, not an agent's (`grant_not_owner`). That last check reads
the row's `by` field, which `gstack-approvals add --by` takes as written, so it
only catches a row honestly labeled `agent:`. The record is as trustworthy as
whoever writes it, the same as every gstack approval. A new head needs a new
run and a new grant; a grant is never rebound: `ready` and the ship receipt
refuse an exception granted for another PR or head, even when the tree matches.
pregate.json records the grant under `exceptions` (lane, repository, PR, head,
tree, runs, cases, grant id, who said it, their words and the binding), and the
obligation's receipt adds `exception=<grant> cases=<n>` to the usual run fields.
The verdict becomes `pass-with-exception`. `verify` re-checks offline that each
exception receipt has its entry, bound to this head and tree, with a binding that
still matches its fields, and prints
`PREGATE: pass-with-exception (<cases>; grant <id>)`. `gstack-ship-queue ready`
accepts it and prints one `FLAKY_EXCEPTION:` line per exception in the READY
block, and `gstack-ship-receipt write` records `flaky_exception` (lane, runs,
cases, grant, who).
**Pregate only.** The exception clears the pregate obligation and nothing else.
It never waives a red required CI check: `ready` still needs every required check
green at the exact head, so a red Free Tests check on the pull request needs its
own rerun to pass. Changing that contract is a separate decision for the owner.
**Why not `base_red`.** `base_red` (docs/ship-policy.md#base-red) proves a
failure belongs to the base by reproducing it there, at the base head and at the
PR head. A timing flake usually passes on the base (the 2026-11-02 docsync case
passed in 3.5 s on main and failed at 5 s on the PR's tree), so `base_red`
returns `IN_BRANCH` and refuses. The exception path asks a different question:
not "is the base broken?" but "is every failure named, outside this PR, and
accepted by the owner?"
<a id="guards"></a>
## Guards and the lane-done rule
@@ -1015,6 +1222,13 @@ those, each with its scope and its reason:
end the outer string (GST-738). The pre-push hook sees only added lines,
so it scans Python and Dart lines without this exemption and may still warn
(MEDIUM, non-blocking) on them.
- The first argument of a lookup call (`get`, `getenv`, `read`, `load`,
`loads`, `open`, `pop`, `fetch`) that is a lowercase file name
(`files.get("key.json")`) or a snake_case key of two or three words
(`resp.json().get("access_token")`) is a name, not a credential (GST-1064).
Any other call's literal (`make_password("orange_monkey_pass")`), a later
argument or fallback (`os.getenv("SECRET_KEY", "orange_monkey_pass")`) and a
kebab passphrase still report.
The `secrets` row says `N allowlisted (<ids>)` and lists each allowlisted
finding with the entry (`allowlisted env.kv (evals/receipts/t1.json, added line
+3 -1
View File
@@ -139,7 +139,9 @@ harness-generic; only the thread and the PR tool are Capy.
default branch.
4. **Run `/ship` unattended** with the `GSTACK_LAUNCH` assignments
exported: it runs the pregate (on a machine under 8 cores the test tier
needs `gstack-pregate --stage tests --remote`, about $0.06 on a Ubicloud VM
clears from a verified CI run at the pushed tree when the base declares
`remote_gate_runs` ([CI carry](pregate.md#ci-carry)); otherwise it needs
`gstack-pregate --stage tests --remote`, about $0.06 on a Ubicloud VM
or free locally for small selections), both reviews, the gate-integrity
list, the docs audit, and writes the ship receipt into the PR body
(`gstack-ship-receipt write --pr <n>`). With `queue_mode:
+41 -14
View File
@@ -174,9 +174,12 @@ applies no edits is its exit too.
`gstack-review-plan --base <base>` classifies the diff, picks a **depth** and prints
the reviewers the next step dispatches: `REVIEW_CLASS:`, `REVIEW_DEPTH: <d>
runtime_lines=<n> rules=<hash> reasons=<…> codes=<…>`, `GATE_SCAN: tagged=<n>|unavailable
head=<sha>`, one `DEPTH_ERROR:` per input that failed closed, one `DISPATCH:` per reviewer
head=<sha>`, `REVIEW_BASE: <ref> <sha12>` (the base the diff was taken against: a bare
`--base main` reads `origin/main` when it shares history with HEAD, and a local `main` that lags
it is named on stderr), one `DEPTH_ERROR:` per input that failed closed, one `DISPATCH:` per reviewer
with its effort and a shell-quoted `DIFF_CMD:` (plus `DIFF_EXCLUDE: <name> none` when it
reads everything), one `SKIP:` per reviewer left out, and `--json` with the same fields.
reads everything), one `SKIP:` per reviewer left out, and `--json` with the same fields (the
base as `base`).
A plan that fails closed to full exits 0; a diff git cannot list exits 1.
**Classes** are unchanged. A mixed diff takes its most restrictive class: **docs**
@@ -204,7 +207,7 @@ elements and RDF metadata, CSS made of declarations only (no `@` rule and no
function but a same-file `url(#id)`, which closes `@import`, `image-set()`,
`image()`, `element()` and every other CSS load), no backslash escape, every
`href` a same-file `#` reference or an inline raster image, no event handler and no
entity declaration, and no DOCTYPE but a bare `<!DOCTYPE svg>` or W3C's own SVG DTD, read after character references are decoded; anything else, a
entity declaration, and no DOCTYPE but a bare `<!DOCTYPE svg>` or W3C's own SVG DTD, read after character references are decoded. A `<style>` element's text is read as written. Any `&` in it keeps the SVG code, its comments are read as CSS, an opening tag it cannot read as quoted `name="value"` pairs keeps the SVG code, and only ASCII whitespace may come before the `>` of either tag, so no character-reference `</style>`, comment that only an HTML parser ends early, quoted `>` or Unicode space can hide CSS. A non-ASCII character in an element or attribute name, such as a `gé:` prefix, keeps the SVG code too (GST-940); anything else, a
script or `foreignObject` included, keeps it code. More than
2,000 data paths keep every one code; a `git grep` failure is `consumer_scan_failed`
and fails the depth closed. The scan first lists the files that contain a candidate's
@@ -252,7 +255,7 @@ line that can run code (a script or `foreignObject` element, an event handler, a
rules are coarse on purpose and parse no import clause or call arguments;
`test/review-risk-linear.test.ts` holds each of them under 100 ms on
200,000-character hostile lines, its anchor followed by a long run of the
characters it repeats included. `test/review-risk-redos.test.ts` (GST-898) holds every risk pattern, R51's `rm` and `rmSync` rules included, under 100 ms on 100,000-character hostile lines. An `rmSync(` call with more than 500 characters before the first `)` after it counts as security on its own. **data** is user data: a path naming pii, gdpr, ccpa, privacy,
characters it repeats included. `test/review-risk-redos.test.ts` (GST-898) holds every risk pattern, R51's `rm` and `rmSync` rules included, under 100 ms on 100,000-character hostile lines. An `rmSync(` or `rm(` call (`fs.rm`, `fs.promises.rm` or an imported `rm`) counts as security when `recursive: true` follows within 500 characters, whatever the arguments hold (a `path.join(...)` first argument or a `)` in a comment included) and also when a formatter split a new call across lines, which is read over the file's changed lines joined (GST-942; an edit to one line of an existing split call is read on its own); a call with more than 500 characters before the first `)` after it counts on its own. **data** is user data: a path naming pii, gdpr, ccpa, privacy,
personal, account, customer, cookie, persistence, storage or database, or a line
that drops a table or column, deletes rows or bulk-deletes records. Auth scope,
migrations and deleted code paths were already gate class. `RISK_RULES` hashes
@@ -384,7 +387,7 @@ and matching is token-bounded: `costume` never reads as cost.
|---|---|
| money | a path segment naming cost, spend, budget, ledger, billing, price, fee or invoice; or a changed line with an identifier ending in `_usd` or `Usd`, any `spend_cap` spelling, or a call to a paid provider `lib/pricing.ts` prices |
| gate | a hunk the gate scan tagged: a relaxed threshold, a skipped test, a loosened check |
| auth | `SCOPE_AUTH` from `gstack-diff-scope`, on a code path with an auth, session, jwt, permission or role token in its name; a data file named for sessions (`recovered-sessions.jsonl`) outside a config location does not set `SCOPE_AUTH` |
| auth | `SCOPE_AUTH` from `gstack-diff-scope`, on a code path with an auth, session, jwt, permission or role token in its name; a data file named for sessions (`recovered-sessions.jsonl`) outside a config location does not set `SCOPE_AUTH`, and `SCOPE_AUTH` fails safe: any name token containing auth sets it (`auth.ts`, `/auth/`, `oauth`, `useAuth.ts`, `nextauthmiddleware.ts`) except the authorship words `author`, `authors`, `authored`, `authoring`, `authorship`, `authority`, `authorities`, `coauthor` and `coauthors` |
| secret | a secrets, credentials, keychain or token path, or a changed line that reads a key-named environment variable (`OPENAI_API_KEY`, `GH_TOKEN`) or a credential store |
An input the classifier cannot read (the diff, `gstack-diff-scope`, the gate
@@ -493,6 +496,21 @@ through the docs stage. A path outside that scope and a gate-edited test still
route as behavior, with `--reviewed-base` (as /ship passes it) so does a file
too large for the scoped review, and without the record nothing changes.
A completed fix-check is a review, not an owner acceptance (GST-1130). Finish
reads the newest `review-fix-check` row from `gstack-review-read`. When it is a
completed clean read on committed content (freshness `CURRENT` against its own
tree) whose commit is on the branch, whose `range_base` is a branch commit
holding the reviewed tree, and for which an approved `review_loop_grant` in
`gstack-approvals` names a stop head inside `range_base..commit`, each code or test path inside `range_base..commit`
that is unchanged since routes as `fix_checked=` in `ROUTE:` and is listed on a
`FIX_CHECK: reviewed` line, a gate-edited test included. Authored docs keep the
stage 2.2 recheck, and a path edited after the fix-check still routes by the
rules above. Any other row prints
`FIX_CHECK: not counted (<reason>)` and changes nothing. `gstack-review-log`
refuses a `review-fix-check` row without boolean `completed` and `converged`,
before it consumes the start token, because without them the row reads
`UNVERIFIED` and finish cannot count it.
The receipt's summary line prints `passes=<n> blocking_found=<k> deferred=<m>`,
which is what a scorecard tracks (target: a median of 1 pass per PR). A
receipt carried across a base merge or a test-only fix
@@ -601,22 +619,30 @@ ones, and the arm lost blockers. `bin/gstack-review-dispatch` closes both ends:
second line for the same field starts another: `Severity` sets its label (a label leading the finding stays its floor),
`Blocks: yes` makes it CRITICAL and `Blocks: no` never lowers it; an inline
`Blocks: yes` is CRITICAL too, and with no finding above it is one. The native
adversarial voice's FIXABLE collects as CRITICAL (normalizer v2, GSTA-167) unless collect `--manifest` names this
ledger's pass and its plan is the code or docs class with only `runtime=<n>` depth reasons (no `risk:`, `error:`,
`history:` or `floor:` reason). On such a plan a native finding's own `Severity` field decides and FIXABLE beside it
raises nothing once it also states `Blocks: no`; a native FIXABLE finding without `Blocks: no`, with no `Severity` field,
or whose field names only FIXABLE or INVESTIGATE still collects as CRITICAL (GST-987). An unnumbered, unlabeled bullet with no file:line
adversarial voice's FIXABLE collects as CRITICAL (normalizer v2, GSTA-167), except that on every class a native
finding that states `Blocks: no` and one `Severity` field collects at that field (GST-1031 ruling A); a native FIXABLE
finding without `Blocks: no`, with no `Severity` field, or whose field names only FIXABLE or INVESTIGATE still collects
as CRITICAL. On a code or docs plan with only `runtime=<n>` depth reasons (collect `--manifest` naming this ledger's
pass; GST-987) FIXABLE also raises nothing through a label heading or a leading tag. A numbered finding heading keeps
every unlabeled line under it (located or numbered bullets, a bold subheading, a located paragraph) until its
`Severity` or `Blocks` line comes, so those fields never split off as a second record (GST-1031). An unnumbered, unlabeled bullet with no file:line
under a paragraph finding whose Severity or Blocks line has not come yet is that finding's detail, so the field line after it
lands on the finding; a numbered item is its own finding.
A negated severity word still collects at its label ("found nothing CRITICAL", "No P0/P1 issues"), so a reader's
closing summary is a known phantom: it stays at that label in the judged set, lead judgment can fold it only into a
finding at least as severe, and it counts toward what blocks. GST-766 skipped negated labels and lost
closing summary is a known phantom: it collects at that label. When it is a summary candidate (no lead label, no
`Severity` or `Blocks` field, and no file:line or exception clause in any sentence naming a label: "so nothing is
CRITICAL", "the test covers the CRITICAL fix"), collect marks it `summary_candidate` and lead judgment may lower it
with a reason, which judge records as `dismissed` (GST-1031); otherwise lead judgment can fold it only into a finding
at least as severe, and it counts toward what blocks. GST-766 skipped negated labels and lost
real blockers named in an exception clause ("No CRITICAL issues except the token leak in log.ts:3"); GSTA-167
reverted that. Each prose finding's line also
records the Severity and Blocks its own text states as `stated`, beside the collected label and never in its place;
a classified finding that carries `stated` shows it in its deferred-review issue next to the label ("CRITICAL (the
reviewer wrote Severity: Low, Blocks: no)"). /ship's Step 9.4 does not copy `stated` into its findings file yet: that
instruction lives in a reviewer brief that changes only after a no-loss replay. What blocks is unchanged.
instruction lives in a reviewer brief that changes only after a no-loss replay. A CRITICAL whose own text writes the
field `Blocks: no` (colon required, and no `Blocks: yes`) is not counted as a blocker by the ledger count, nor by the
review-log count or classify when the finding carries `stated` (GST-1031); lead judgment that raises such a line above
its label counts it again.
A phantom finding costs a fold; a lost one costs the gate.
A reply with no finding counts as a review only with the clean marker its own brief asks for: `NO FINDINGS` alone on a
line for the specialists, the batched specialist, the targeted reader, the Red Team and fix-check, the `Recommendation:`
@@ -690,7 +716,8 @@ ones, and the arm lost blockers. `bin/gstack-review-dispatch` closes both ends:
working directory) and stops when that is another checkout or cannot be read: run /ship in the thread's own checkout.
A start directory outside any checkout, such as a multi-repo workspace root, holds no tree to review by mistake and
dispatches. Step 11's voices take the `adversarial-review` start
token by default, and a `logStart` list without it stops before anything runs.
token by default, and a `logStart` list without it stops before anything runs. Decision 3.5's fix-check pass turns a
`review` start into `review-fix-check`, so its row is never a pass (GST-1031).
## Where this is enforced
+2 -1
View File
@@ -1507,6 +1507,7 @@ receipt when the base moves:
| a rebase or force-push onto a tree the receipt covers, product diff against the new base unchanged | carries (`carry.ancestry: rewritten`) |
| any other rebase or force-push | a fresh /ship (`RECEIPT_CARRY_TREE_MISMATCH`) |
| a stacked PR whose parent landed (squash or merge), retargeted to the base with the base merged in, HEAD's product diff exactly the one reviewed against the parent branch | carries (reason `stack parent <branch> landed`) |
| a stamp on the branch's own rows in a stamp file the branch also changed as product: every changed line at a branch-added position, the file's mode unchanged, the base not touching it, the rest of the product diff unchanged | carries (reason `a stamp on the branch's own rows (<file>)`) |
**Stacked PRs (#3570).** A child PR's receipt is written against its parent
branch, so its `base` names that branch and its `product_patch_id` is the
@@ -1677,7 +1678,7 @@ Stages, each journaled in `.gstack/tmp/restamp-journal.json`:
1. **version**: `gstack-version-bump write --version <X>` in the staging worktree (VERSION, the manifest, npm lockfiles); skipped when `restamp_command` owns the version. The manifest gets the npm-valid three-part form, except when the policy lists it in `stamp_paths` or `stamp_files` and its copy at the base holds four parts (gbrain's convention): then it keeps the full version (`--manifest-form full`) and the stage detail says so.
2. **release_tool**: the policy command, under the contract below.
3. **changelog**: the PR's `[Unreleased]` or old-version section moves to the top under `<X>`, above its predecessor's entry. A duplicate heading the PR introduces (`CHANGELOG_DUPLICATE_HEADING`: the headings are counted against the base's CHANGELOG at `origin/<base>` and at the fork point, so a version the base already heads twice passes as long as the PR adds no further copy) and a top entry that is not `<X>` (`CHANGELOG_TOP_MISMATCH`) are errors; the section being re-headed itself may exist only once.
4. **stamp_paths**: exact `(was X)`, `since: X` and `vX` rewrites, plus every `stamp_patterns` template, within `stamp_paths` and `stamp_files`. A quote around X in the first two forms is part of the form and is kept as written: `since: 'X'`, `since: "X"`, `(was 'X')` and `(was "X")` move like the bare ones (the shape of a quoted source row such as gbrain's `{ since: '0.60.468.0', … }`), an opened quote must close right after X (`since: '1.2.3-beta'` and `since: '1.2.3"` are not the form, in the writer and in the tree receipt alike), and `vX` already accepts a quote before the `v`. Which X moves is decided by provenance. The branch's own tentative stamp (its VERSION when it moved past base) and `--was <X>`, when given, are each rewritten on every line of every stamp file. Beyond that, only lines the branch itself added are read, by their position in the file (`git diff --unified=0` from the fork point), so a base line with the same text, or a CRLF checkout whose diff is LF-normalized, is told apart: a stamp-form mention there of a version newer than the version at the branch's fork point is a tentative stamp and moves (this is what finds a quoted row after a lost slot and a merge of the base, since the base's release is newer than the fork point), and so does one of the fork-point version itself (a row the branch wrote at the version it forked from instead of a next version is its own stale stamp; a branch-added mention older than the fork point stays), and when the branch has no stamp of its own because its VERSION equals the base's and its fork point is the base itself (a branch rebased onto the base after it reached X, or one never stamped) a mention of the base version on a line it added is its stale stamp and moves too, while the same version on a line the base already carries is the base's release and stays. The stage detail names both counts per file (`VERSION equals base X, so X moved only on lines this branch added and stayed on the base's own lines (<file>: N moved, M kept)`), so the stamp commit shows which lines moved and why. A line the base added since the fork point is the base's even when that diff shows it (a merge of the base on the branch, committed or still staged, brings every line the base added since the fork into the diff from the fork point, main's own release keys included): it is left out, the detail says `N line(s) the base added since the fork point are the base's, not this branch's, and stay (<file>: N)`, and a base diff git cannot run refuses the stage (`POLICY_SOURCE_UNAVAILABLE`, `cannot diff <since>..<base> for the stamp_paths stage`) rather than reading as an empty set that would move the base's lines again. The rule reads line ownership, not meaning: a branch-added line inside `stamp_paths` that means the base's own release in a stamp form (`Requires vX or later` written on a branch forked at X) moves with it, which the `--dry-run` diff and the per-file counts show before anything is written; write such a reference outside a stamp form, or keep that file out of `stamp_paths`. `--was X` is the opposite tool: it rewrites X everywhere, the base's own lines included, and re-heads the CHANGELOG section `## [X]`. Only the repo's own version width counts, so a 3-digit dependency pin in a 4-digit repo is never a candidate. The checks that accept a stamp commit read the same bound as the writer (`stampOnlyLine` with the branch's side in `lib/stamp-only.ts`): the tree receipt behind `stamp`, `verify` and the gate-ahead replay, the merge train's stamp and verify checks (each reading the slot's predecessor, the gated commit's first parent, as the base), and finish's route each take a moved version on a line the branch added at or above the fork-point version, and on any other line at or above the gated head's VERSION. A base line whose text duplicates a line the branch added gets the branch's bound too, because the checks match branch lines by text, not position (GST-979). The /ship receipt carry can still refuse the move (`RECEIPT_CARRY_PRODUCT_CHANGED`), and when the branch keeps its VERSION claim, carry and finish still route the move as behavior (GST-980).
4. **stamp_paths**: exact `(was X)`, `since: X` and `vX` rewrites, plus every `stamp_patterns` template, within `stamp_paths` and `stamp_files`. A quote around X in the first two forms is part of the form and is kept as written: `since: 'X'`, `since: "X"`, `(was 'X')` and `(was "X")` move like the bare ones (the shape of a quoted source row such as gbrain's `{ since: '0.60.468.0', … }`), an opened quote must close right after X (`since: '1.2.3-beta'` and `since: '1.2.3"` are not the form, in the writer and in the tree receipt alike), and `vX` already accepts a quote before the `v`. Which X moves is decided by provenance. The branch's own tentative stamp (its VERSION when it moved past base) and `--was <X>`, when given, are each rewritten on every line of every stamp file. Beyond that, only lines the branch itself added are read, by their position in the file (`git diff --unified=0` from the fork point), so a base line with the same text, or a CRLF checkout whose diff is LF-normalized, is told apart: a stamp-form mention there of a version newer than the version at the branch's fork point is a tentative stamp and moves (this is what finds a quoted row after a lost slot and a merge of the base, since the base's release is newer than the fork point), and so does one of the fork-point version itself (a row the branch wrote at the version it forked from instead of a next version is its own stale stamp; a branch-added mention older than the fork point stays), and when the branch has no stamp of its own because its VERSION equals the base's and its fork point is the base itself (a branch rebased onto the base after it reached X, or one never stamped) a mention of the base version on a line it added is its stale stamp and moves too, while the same version on a line the base already carries is the base's release and stays. The stage detail names both counts per file (`VERSION equals base X, so X moved only on lines this branch added and stayed on the base's own lines (<file>: N moved, M kept)`), so the stamp commit shows which lines moved and why. A line the base added since the fork point is the base's even when that diff shows it (a merge of the base on the branch, committed or still staged, brings every line the base added since the fork into the diff from the fork point, main's own release keys included): it is left out, the detail says `N line(s) the base added since the fork point are the base's, not this branch's, and stay (<file>: N)`, and a base diff git cannot run refuses the stage (`POLICY_SOURCE_UNAVAILABLE`, `cannot diff <since>..<base> for the stamp_paths stage`) rather than reading as an empty set that would move the base's lines again. The rule reads line ownership, not meaning: a branch-added line inside `stamp_paths` that means the base's own release in a stamp form (`Requires vX or later` written on a branch forked at X) moves with it, which the `--dry-run` diff and the per-file counts show before anything is written; write such a reference outside a stamp form, or keep that file out of `stamp_paths`. `--was X` is the opposite tool: it rewrites X everywhere, the base's own lines included, and re-heads the CHANGELOG section `## [X]`. Only the repo's own version width counts, so a 3-digit dependency pin in a 4-digit repo is never a candidate. The checks that accept a stamp commit read the same bound as the writer (`stampOnlyLine` with the branch's side in `lib/stamp-only.ts`): the tree receipt behind `stamp`, `verify` and the gate-ahead replay, the merge train's stamp and verify checks (each reading the slot's predecessor, the gated commit's first parent, as the base), the /ship receipt carry, and finish's route each take a moved version on a line the branch added at or above the fork-point version, and on any other line at or above the gated head's VERSION. A branch line is named by its position in the gated file, so a base line whose text duplicates a line the branch added keeps the gated head's bound (GST-979). When the stamp keeps the VERSION (a slot that keeps its claim), only the branch's own lines may move, so a base line moved by hand is refused. The carry follows a stamp on the branch's own rows in a stamp file the branch also changed as product when every changed line of that file sits at a branch-added position, the file keeps its mode, the base did not touch it and the rest of the product diff is unchanged (`a stamp on the branch's own rows` in the carry reason, GST-980).
5. **mirror**: tier 2; declared and validated, reported as not run.
6. **apply**: every changed file is written to the branch only after all stages validated, each against the fingerprinted preimage; a file edited meanwhile is `RESTAMP_CONFLICT` and the applied writes roll back (rollback refuses to overwrite a file whose bytes differ from the recorded postimage).
+182
View File
@@ -0,0 +1,182 @@
# Skill routing and skill contracts
Two opt-in Claude Code hooks that help a model actually run gstack's skills (GST-1088). Both are **off by default**, and with both off nothing changes.
- **Skill routing** (`skill_routing`, a UserPromptSubmit hook). When a prompt matches an installed skill's `triggers:`, the hook adds one line of context naming that skill, for example "this request fits /investigate. Run /investigate with the Skill tool before you start".
- **Skill contracts** (`skill_contracts`, a Stop hook). A skill can declare the outputs that must exist before it is done. When the model tries to stop without them, the hook blocks once and names what is missing.
## Turn them on or off
Each switch resolves in this order, and the first one set wins:
1. The `./setup` flag: `--skill-routing` / `--no-skill-routing` and `--skill-contracts` / `--no-skill-contracts` (also `--skill-routing=on|off`). A flag is saved to config, so it survives upgrades.
2. The environment: `GSTACK_SKILL_ROUTING` and `GSTACK_SKILL_CONTRACTS` (`on` or `off`). Not saved.
3. Config: `gstack-config set skill_routing on|off` and `gstack-config set skill_contracts on|off`.
4. The default: off.
`on` also accepts yes, true and 1; `off` accepts no, false and 0. Setup warns about any other value, uses off for that run, and does not save it.
Setup registers a hook only when its switch is on, prints one line the first time it registers it, and removes the registration when the switch is off (or with `--no-team`). The hooks also read the switch every time they run, so this takes effect on the next prompt without re-running setup:
gstack-config set skill_contracts off
gstack-config set skill_routing off
The off switch is for people. The text the Stop hook shows the model never mentions it.
## Host support
| Host | Routing hook | Contract Stop hook | Notes |
|---|---|---|---|
| Claude Code | yes | yes | Registered in `~/.claude/settings.json` by `./setup` |
| Codex, OpenCode, Cursor and other hosts | no | no | No hook support. `gstack-skill-contract check` still works on a Claude Code transcript |
## Routing
The hook scores the prompt against the `triggers:` list in each installed `SKILL.md` (`~/.claude/skills/*/SKILL.md`, or `$CLAUDE_CONFIG_DIR/skills`). It makes no model call and no network request, and the same prompt always gets the same answer.
- A trigger scores 1 when its whole phrase appears in the prompt. Otherwise it scores the share of its content words (common words dropped, light stemming, so "failing" matches "fails") that the prompt contains. A trigger with one content word counts only on its whole phrase, unless that word has five or more letters and is not a question word.
- Only /investigate, /review, /qa and /verify route. In the d7 check (PR #3912), scoring every installed skill's triggers sent 17 of 32 non-fit Terminal-Bench prompts to some skill at 0.66; routing only these four sends 4. The other skills wait for their own trigger review.
- The skill with the best score routes when it reaches the threshold, 0.66: both words of a two-word trigger, or two of three.
- Prompts that start with `/` (you already picked a skill) and prompts over 8,000 characters (pasted logs) are never routed.
- The injected line names its source and its off switch, and asks the model to tell you in one sentence that gstack routed the request.
### Dry run
`gstack-skill-route --explain` shows what the hook would do, with the switch on or off. It never injects anything.
$ gstack-skill-route --explain "this test fails, fix it"
switch: skill_routing off (default)
threshold: 0.66
skills: 65 scanned in /home/you/.claude/skills
candidates:
1.00 /investigate "fix this bug" (2 words)
0.67 /ios-fix "fix this ios bug" (2 words)
route: /investigate
hint: gstack skill routing (UserPromptSubmit hook; ...
Add `--json` for a machine-readable answer, or `--threshold <n>` to see another cutoff. `GSTACK_SKILL_ROUTE_HINT=name|step|contract` picks the hint wording the d6 pilot compares: the skill name only (default), plus the skill's first step, or plus its contract.
### Routing log
Every decision is one line in `$GSTACK_STATE_ROOT/hooks/skill-route.log`: the session, the event (`routed`, `no-route` with its reason, or an error) and, for errors, `failures=<n>` for that session. The log never holds prompt text. On any error the hook prints nothing and exits 0; it never blocks a prompt.
## Contracts
### Schema (version 1)
A skill declares its contract in its `SKILL.md` frontmatter:
contract: { version: 1, items: [ { id, kind, ... } ] }
Every item has an `id` (lowercase letters, digits, `.`, `_`, `-`) and a `kind`, plus optional `fix` (the action the block text names) and `summary` (the phrase the routing hint's contract variant uses). At most 20 items.
| kind | Fields | Met when |
|---|---|---|
| `report_labels` | `heading`, `labels[]` | The last assistant message containing the heading has a `Label: value` line for every label, and no value is empty or a placeholder (`[...]`, `<...>`, TBD, TODO, `...`, or a template like `DONE \| BLOCKED`) |
| `check_after_last_edit` | optional `match` (regular expression) | No Edit, Write, MultiEdit or NotebookEdit happened, or a Bash test or repro command ran after the last one. By default a command counts when, with quoted text removed, one of its parts (split on `&&`, `\|\|`, `;`, `\|`) starts with a test runner, build tool or interpreter (bun, npm, pytest, go, cargo, make, node, python, curl, ...) or a script whose name says test, spec, repro, check, verify or lint, directly or behind a wrapper (`bundle exec rspec`, `uv run pytest`, `docker compose run app pytest`, `xvfb-run npm test`, `bash scripts/test.sh`). `git commit --no-verify`, `cat test/a.test.ts` and the shell's `test -f` do not count |
| `selected_specialists_dispatched` | optional `marker`, `empty_marker` | The selection line was printed in an assistant message or a Bash result (never a fetched page or file), its names are plain (letters, digits, spaces, `_`, `.`, `-`, at most 40 characters), and each specialist it names has an Agent dispatch that mentions it. The marker is literal text in which a whole-word N stands for a number; the default is `Dispatching N specialists:`. N = 0 (`Dispatching 0 specialists: (small diff)`) or a "specialists skipped" line means zero specialists were selected, which passes. Text in parentheses is not a name (`Dispatching 1 specialists: State Machines (small diff)` selects State Machines) |
| `agent_dispatch` | `match` (regular expression, case-insensitive), optional `marker` | The `marker` line (literal text, like /review's `Dispatching adversarial pass: native`) was printed and an Agent dispatch follows it; otherwise, as the fallback, an Agent dispatch's description or prompt matches `match` |
A run the skill ended early counts as met: a final `STATUS: BLOCKED` (for /investigate, `Status: BLOCKED` in its DEBUG REPORT) or a final message with a line that starts "Nothing to review" (/review's early exit).
The checker's default marker strings live in one table, `DEFAULT_MATCHERS` in `lib/skill-contract.ts`; a skill's own `marker`, `empty_marker` or `match` overrides them.
Items are checked against one run of the skill: from its last load to the end of the session, or to its next load when `report` re-checks an earlier run. A load is a Skill tool call, a typed `/name` command, or a Read of its `SKILL.md` under a `skills/` directory (reading the source in a gstack checkout is not a load). A run recorded `met`, `met_waived` or `met_after_block` stays that way, so a later unrelated turn in the same session is never blocked by it.
### Worked example
contract:
version: 1
items:
- id: debug-report
kind: report_labels
heading: DEBUG REPORT
labels: [Symptom, Root cause, Fix, Evidence]
- id: repro-after-fix
kind: check_after_last_edit
A session loads /investigate, edits `src/auth.ts` and answers "Fixed: the null check was missing." with no report and no test run. The Stop hook blocks once with:
SKILL_CONTRACT_UNMET investigate (contract v1): missing debug-report, repro-after-fix. Fix: debug-report: print the DEBUG REPORT with real values for Symptom, Root cause, Fix, Evidence; repro-after-fix: run the test or repro again after your last edit and show its result. If an item truly does not apply, run gstack-skill-contract waive <item> --reason "<why>" (this session only; counted as a miss for follow). This blocks once.
The model runs `bun test`, prints the DEBUG REPORT, and stops. The record reads `met_after_block`.
### When the Stop hook checks
The hook checks the most recently loaded skill that declares a contract, and only when the turn is a final one:
- the last assistant message has a STATUS line (`STATUS: DONE`, `Status: DONE_WITH_CONCERNS`, `**Status:** BLOCKED` and the like), or
- the session is headless or unattended (`gstack-session-kind`), or
- the turn does not end on a question to the user (a last paragraph ending in "?", an AskUserQuestion call, or `NEEDS_CONTEXT`).
So an interactive session that pauses to ask a question is never blocked. When Claude Code says a Stop hook already continued this turn (`stop_hook_active`), the hook never blocks: after its own block it records the result (`met_after_block` or `miss`). It also allows the stop while Agent dispatches are still running (no result yet, or launched in the background with no completion notice naming that agent), because their outputs may still arrive. Because Claude Code can fire Stop before the turn's last message reaches the transcript file, the hook reads the payload's `last_assistant_message` as the turn's final text.
It blocks at most once per skill run. If the model stops again with the contract still unmet, the stop is allowed and the run is recorded as a miss.
### Records
Each Claude Code session has one record, `$GSTACK_STATE_ROOT/skill-contracts/<session id>.json`, written atomically (mode 0600) before any block. Each skill run in it has an outcome: `met`, `met_waived`, `blocked`, `met_after_block` or `miss`. The hook's decisions also go to `$GSTACK_STATE_ROOT/hooks/skill-contract.log`.
## Commands
### check
gstack-skill-contract check --transcript <path> --skill <name> [--skill-file <SKILL.md>] [--json]
A pure function of a Claude Code transcript (the JSONL a hook payload's `transcript_path` names, under `~/.claude/projects/`). The contract comes from the installed skill's frontmatter, or from `--skill-file`. It prints each item as met, missing or waived. The model never records anything itself, so evals can run the same check on their own transcripts.
### report
gstack-skill-contract report [--json] [--session <id>]
Lists misses by skill and item, then each missed run. A miss is a run that was blocked and never fixed, stopped again unmet, or met only through a waiver. A run still marked `blocked` is re-checked against its transcript when the file is still there, so a run fixed after its block reads `fixed_after_block`, not a miss.
### waive
gstack-skill-contract waive <item> --reason "<why>" [--skill <name>]
The escape for an item that truly does not apply (a docs-only change has nothing to test). It is stateless: it checks its arguments and prints an acknowledgement. `check` finds the waiver by reading this Bash call in the transcript, for this session only, and a waived item still counts as a miss for follow. A waive call that failed, has no reason, or names another skill does not count.
## Exit codes and errors
`gstack-skill-contract` exit codes are stable.
<a id="exit-0-met"></a>
### 0: met (SKILL_CONTRACT_MET)
`check`: every item is met or waived. `report` and `waive`: done.
<a id="exit-1-unmet"></a>
### 1: unmet (SKILL_CONTRACT_UNMET)
At least one item is missing. Text output starts with the same line the Stop hook would block with. Do what each item's Fix says, or waive an item that does not apply.
<a id="exit-2-usage"></a>
### 2: usage (SKILL_CONTRACT_USAGE)
A missing or malformed argument: `check` without `--transcript` and `--skill`, `waive` without an item id or `--reason`, or an item the named skill's contract does not have. `gstack-skill-route` uses 2 the same way (SKILL_ROUTE_USAGE).
<a id="state-error"></a>
<a id="exit-3-state-error"></a>
### 3: state error (SKILL_CONTRACT_STATE_ERROR)
A file could not be read or written: the transcript is missing or over 32 MiB, the session record is corrupt, or the state root is not writable. The Stop hook fails open on these and prints one stderr line:
gstack-skill-contract: SKILL_CONTRACT_STATE_ERROR <path>: <cause>; stop allowed, miss not recorded (see docs/skill-routing-and-contracts.md#state-error)
The stop goes through and nothing is recorded. Fix the named path: make `$GSTACK_STATE_ROOT` writable, or delete a corrupt `skill-contracts/<session>.json` (it only holds this session's outcomes). An invalid contract block in a skill's frontmatter is reported the same way, naming that `SKILL.md`. A hook that runs past its 5 second deadline also fails open here.
<a id="exit-4-unknown-shape"></a>
### 4: unknown transcript shape (SKILL_CONTRACT_UNKNOWN_SHAPE)
The file is not a Claude Code transcript this checker understands (no user or assistant records, or message content that is neither text nor a block list), for example after a Claude Code format change. The Stop hook fails open with a state error line and adds one to `$GSTACK_STATE_ROOT/hooks/skill-contract.canary.json`. A rising canary count means the parser needs an update.
<a id="exit-5-no-contract"></a>
### 5: no contract (SKILL_CONTRACT_NO_CONTRACT)
No installed skill has that name, its `SKILL.md` declares no contract, or the contract block is invalid (the message names the problem, such as an unsupported version or an unknown kind).
<a id="exit-6-not-loaded"></a>
### 6: not loaded (SKILL_CONTRACT_NOT_LOADED)
The transcript never loads the skill, so there is nothing to check.
+1 -1
View File
@@ -755,7 +755,7 @@ A lot of branches die when the interesting work is done and only the boring rele
1. **`## What changed`**: one to three captioned before/after images from `gstack-pr-shots` or a UI screenshot, highest-signal first, with a collapsed text version under each.
2. **`## Why`**: two or three sentences. The first states the problem in the person's words (the issue, the message, the failing run), then the cause and the user-visible effect.
3. **`## Blast radius`**: what else the change touches and the one fact that makes that safe, with the evidence-ladder rung that fact reached (a test that exercises the shared path, a grep over every caller, a measured run). A change to a shared helper, a generated file, a selection list or a policy default always has one; a leaf fix says so in one line.
4. **`## Approvals`**: the table from `gstack-approvals render`, verbatim.
4. **`## Approvals`**: the output of `gstack-approvals render`, verbatim. On a private repository that is the table; on a public repository, or one whose visibility gh cannot read, it is only `Approved: yes|no (record <id>)`, because GitHub keeps every earlier version of a PR description.
Before the body is composed, `gstack-prose-lint` reads the Why, Summary and Blast radius drafts (`--sections 'Why,Summary,Blast radius' --gate`) and the CHANGELOG entry (`--base origin/<base> --gate`), and a `PROSE_LINT_FOUND` line names the sentence to rewrite; the rest of the body is advisory. The Captain's merge-ask template (`captain/templates/merge-ask.md`) carries the same four sections, so a READY report and its PR say the same thing.
+2 -1
View File
@@ -18,7 +18,7 @@ That is the whole promise. Other skills, optional parts such as `/cso`'s native
## What we stop doing
- No Windows-only or Gemini-only features, parity work, tuning or polish.
- No new Windows or Gemini CI jobs or eval cells. Windows CI tuning stops.
- No new Windows or Gemini CI jobs or eval cells, apart from the path-scoped Windows checks under Windows CI below (ship-90-90 plan D). Other Windows CI tuning stops.
- A Windows-only or Gemini-only report that doesn't break install, startup or a core workflow closes as won't fix ([triage rules](triage.md#closing-an-issue)), with a link to this page. A report that does break one of them gets a small fix.
## Windows CI
@@ -26,6 +26,7 @@ That is the whole promise. Other skills, optional parts such as `/cso`'s native
- `windows-smoke` is the required Windows check on pull requests.
- The six-shard Windows free suite (the `Windows Free Tests` workflow, `windows-free-tests`) runs nightly on main, or when someone starts it by hand, and never blocks a pull request.
- A red nightly run gets a fix only when it shows an install, startup or core-workflow break.
- Windows checks run by path (ship-90-90 plan D, approved 2026-11-03): `Windows Scoped Tests` runs a pull request's changed Windows-safe test files on one Windows job only when it touches path, file-name or process code (a red run blocks that pull request, like any failed check), and `Windows Setup E2E` runs only when install files change (a version-only `package.json` change doesn't count).
## What doesn't change
+9 -5
View File
@@ -146,7 +146,9 @@ record. Another successful fetch alone cannot certify corrupted history.
Outside reviews send your diff, plan or question to a second AI provider. Their
verdict comes from `lib/outside-review-result.ts`, which prints
`VERDICT: clean|findings|unverified|unavailable`. A `findings` verdict with a
`VERDICT: clean|findings|unverified|unavailable`. When given an events file, it
also prints `OUTSIDE_USAGE:` with the token counters Codex reported, or
`OUTSIDE_USAGE: unknown` when it reported none. A `findings` verdict with a
P0 or P1 finding blocks exactly like a native P0/P1. `unverified` and
`unavailable` are missing coverage: /ship and /review continue, show the gap in
the readiness dashboard and the PR body, and never count it as a pass.
@@ -3920,14 +3922,14 @@ the lane log, then rerun or split the selection. A tool missing from PATH is
<a id="pregate-stalled"></a>
### `PREGATE_STALLED`
**Meaning.** A test command the lanes check (or a guard) launched wrote nothing to its log for the stall timeout (default 300 s,
**Meaning.** A test command the lanes check (or a guard) launched wrote nothing to its log, and its process group used under a tenth of one CPU (Windows: log growth alone), for the stall timeout (default 300 s,
`stall_timeout_s` in the base branch's `.gstack/pregate.json` or the user-owned file, or
`--stall-timeout`). pregate killed its process group and names the last test
file started. The check is incomplete, never pass.
**Fix.** Open the printed log, find the hang in the named file (a blocked
child, a server that never exits, a synchronous wait), fix it and rerun
`gstack-pregate --stage tests`. A test that is legitimately quiet for longer
`gstack-pregate --stage tests`. A test that legitimately waits quietly for longer
needs a larger `--stall-timeout`; `0` disables the stall kill and leaves only
`--timeout`. The `--remote` gate never stalls: it is bounded by `--timeout`
(else `timeout_s`), so a gate that waits on CI needs a timeout long enough for
@@ -5990,8 +5992,10 @@ retargeted stacked PR the parent branch and the base.
conflict-only base merge, a test-only change, release metadata, a registered
output the pregate's regen check proved, a rebase onto a covered tree with
the recorded product diff, a stacked PR's retarget once its parent fully
landed on the base, or base context next to unchanged hunks after a clean
scoped review ([`RECEIPT_CARRY_SCOPED_REVIEW`](#receipt-carry-scoped-review)), which the
landed on the base, a stamp on the branch's own rows in a stamp file it also
changed as product (every changed line at a branch-added position, the mode
unchanged, the base not touching the file), or base context next to unchanged
hunks after a clean scoped review ([`RECEIPT_CARRY_SCOPED_REVIEW`](#receipt-carry-scoped-review)), which the
`carry` object in the carried receipt records with the product patch-id and
the range-diff evidence ([unattended.md](unattended.md#the-terminal-line)).
+62 -4
View File
@@ -216,8 +216,9 @@ review-log row is the same row every Step 11 pass writes
(the outside provider that reviewed, with the model recorded, for the
cross-family subagent; `codex` for completed Codex CLI output, as
`ship/sections/adversarial.md` prescribes),
`outside_provider` (the provider the host would have used, as the generated
prose names it), `outside_status` (`completed` for a finished outside pass;
`outside_provider` (on Capy, `host-subagent`, with `outside_model`, both copied
from the pass program's `OUTSIDE_RECORD:` line; elsewhere the provider the
generated prose names), `outside_status` (`completed` for a finished outside pass;
`unavailable` when neither the CLI nor a subagent completed, the cause on the
`gstack-outside-voice run:` stderr line and in `<out>.meta.json` rather than
in the row; `disabled` under
@@ -237,7 +238,16 @@ when `input.models['outside-voice']` is empty and the lane model is
rounds ran. Any other lane must name a model. An outside voice from the same
provider as the lane model or the native voice stops the pass (`STOP:`) before
either voice is created, including on a rerun, and each outside voice prints an
`OUTSIDE_VOICE:` line saying whether it is the certified configuration.
`OUTSIDE_VOICE:` line saying whether it is the certified configuration. An
outside voice still running with no output after `input.stuckMs` (20 minutes by
default) is stopped, and one that stops or fails without leaving findings, or
finishes empty, is collected as unavailable coverage (`COLLECT_UNAVAILABLE:`)
instead of stopping the pass, so Step 11 goes on to judge the native voice. A
stopped or failed outside voice whose reply holds findings is collected like any
finished one, so its findings are kept; one whose reply holds none is unavailable. That outside voice then gets its own
row (`source: "host-subagent"`, `status: "unavailable"`, `completed` and
`converged` false, written without `--finish` before the native row), so a
missing voice never reads as converged or as an unavailable Codex CLI.
### The carry across a base merge or a test-only fix
@@ -337,7 +347,7 @@ in about a hundred lines, generated from the code.
```bash
AP=bin/gstack-autoplan
$AP next --out <dir> --plan <plan.md> [--ui|--no-ui] [--developer-tool] [--no-dx] [--light] [--spend-cap <usd>]
$AP next --out <dir> --plan <plan.md> --full [--ui|--no-ui] [--developer-tool] [--no-dx] [--light] [--spend-cap <usd>]
# PHASE: ceo snapshot=<sha> order=ceo,design,dx,eng
# SCOPE: ui=yes (...) dx=yes (detected: ...) source=ui:detected,dx:detected
# DRIVER: <root>/autoplan/DRIVER.md
@@ -353,6 +363,54 @@ and, when CLI flags differ from the plan's marker, `SCOPE_PIN: add <!--
gstack-autoplan-scope: … --> as the first line of <file>`; gstack never writes
the plan.
### Kinds: fix, feature and full (R65)
The example above is the full run. The first `next` also takes `--kind`:
- **`--kind fix`**: a bug fix gets no plan review. `gstack-autoplan next --kind fix`
prints `AUTOPLAN: not needed (bug fix; R65)`, a `PROOF:` line and
`GSTACK_RESULT: skill=autoplan status=skipped run=-`, exits 0 and writes
nothing (no `--out` or `--plan` needed; `--json` prints one object with
`status: "skipped"`). `run --kind fix` does the same before any paid call.
An `--out` that already holds a run is refused. The PR still owes the bug's
proof: a repro on current main or a failing test written first.
- **`--kind feature`**, the default for an unattended run on Capy
(`GSTACK_CAPY=1`) that names no kind, is the lean run. The run is the `eng`
phase alone with one native reviewer, whose prompt merges the CEO and Eng
lenses (Design and DX only when scope detects them) and always asks "Any
outside terms, licences or rights involved?". The reviewer reads the draft
code with the plan: `git diff` from the merge base with `--base <ref>`
(default `origin/HEAD`), untracked files included and the run directory
left out, written into the phase's snapshot directory as `draft.diff` and
hashed into `run.json` (`phases.eng.draft`) and the `phase_opened` journal
row. With no code yet, the run says so: `DRAFT: none (<why>)`. A git
command that fails is `DRAFT: none (draft capture failed: …)`, never a
partial draft. The draft goes to a model provider, so a file whose name
looks like a secret (the whole `.env*` family, `.envrc` included, `*.pem`,
`*.key`, `*.p12`, `id_rsa` and the other SSH private keys, `.netrc`,
`.npmrc`, `.pgpass`, `*credentials*`, `*secret*`) is never read, tracked or
untracked, and is left out with a note; so is either side of a rename or
copy git detects in the branch's commits or staged changes. A secret moved
without `git add`, copied unchanged, or renamed and heavily edited reaches
the draft under its new name, guarded only by the content check. Every other file's patch goes
through the redact engine (`lib/redact-engine.ts`), so a key in an ordinary
file reaches the reviewer as `<REDACTED-…>`; a patch it can't redact safely
is left out with a note. The `DRAFT:` line names the checkout it diffed (`root=`). The prompt inlines the diff in a fence longer than any tilde
run inside it, cut at 100,000 bytes (`shown=` on the `DRAFT:` line) with a
note asking the reviewer to name what it didn't see. The reviewer's
line after INPUT names the draft (`DRAFT: <sha256>` or `DRAFT: none`), or
submit refuses the result with `RESULT_RECEIPT_MISSING`. A hand-run record
bound with `--attest` has no receipt at all, so its deviation says the
draft was not bound. `run`, which pays for both voices, stays the full run
unless `--kind feature` asks for the lean one. There is no outside
voice, `--max-rounds` defaults to 1, carry-forward is off, and the gate has
one revision: `revise --incorporates` applies the owner's accepted changes
without re-review (`APPLIED: … (lean run: one gate revision; …)`) and
approves. The gate and `gstack-owner-brief render --captain` relay work as
in the full run. A paid-eval prereg counts as a feature.
- **`--full`** restores every phase and both voices. Off Capy, and in an
interactive session, the default stays full; `--ceo-only` stays its own run.
1. **Dispatch each `ATTEMPT:`.** The native voice is a subagent on the parent's
own model given the prompt file; the outside voice is a subagent on another
model family, or `bin/gstack-outside-voice run --runner codex-cli|api