mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-17 05:41:50 +01:00
Merge commit '2f9d11a59d68822c36b3e03fb3e535f48a8ace96' into gst-1196-preflight-timeout
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> # Conflicts: # lib/ship-preflight.ts
This commit is contained in:
commit
a2aee11d15
126 files changed
+6969
-358
No files matched your search
@@ -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
|
||||
|
||||
@@ -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)`),
|
||||
@@ -184,7 +187,7 @@ run from inside a workflow (/ship's docs step running `install.sh --for
|
||||
document-release`, #3571) prints `SELF_UPGRADE: skipped (a gstack run in this
|
||||
session holds a workflow lease on this installation: ... (UPGRADE_BUSY))`,
|
||||
leaves the checkout where the run started and stays ok with `behind=`. Each
|
||||
`gstack-skill-start` renews the lease. On Capy the leased pid is the machine's
|
||||
`gstack-skill-start` renews the lease and records its `SESSION_ID` as an open run; `gstack-skill-end` closes that run, and a lease whose runs are all closed is idle and blocks nothing, so a finished /ship no longer holds the upgrade back (GST-1205). Each run counts for 120 minutes from its own start, whatever other sessions renew. A lease with no recorded run (written without `--run`, or by an older gstack) counts as before. On Capy the leased pid is the machine's
|
||||
long-lived `capy-server`, so the deferral ends when the lease turns 120
|
||||
minutes old, not when the process exits. Every session on the machine runs
|
||||
under that same `capy-server`, so `bin/gstack-upgrade` run by hand also
|
||||
@@ -228,7 +231,7 @@ identities, a taker stalled over 2 minutes between its `mkdir` and its owner
|
||||
rename can be broken and then publish into its successor's lock. While a live process
|
||||
holds the lock, or it cannot be taken at all, `touch` exits 3 without writing
|
||||
(`gstack-skill-start` reports that the session holds no lease) and a reclaim
|
||||
keeps the lease. `bin/gstack-lease list` shows `alive|dead|stale`, and
|
||||
keeps the lease. `bin/gstack-lease list` shows `alive|idle|dead|stale`, and
|
||||
`GSTACK_UPGRADE_FORCE=1` overrides.
|
||||
|
||||
## What the installer does
|
||||
|
||||
+265
-11
@@ -88,9 +88,9 @@ the byte-pinned `/ship` renders in `test/fixtures/golden/`).
|
||||
| `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` forwards its own `--timeout`; without it, and in the `finish` fallback, 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)) |
|
||||
| `run_profiles` | name → `{ workflow, events, jobs, artifact, max_age_hours?, os?, skippable? }`: 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 |
|
||||
| `ship_lanes_from` | maps each exact /ship lane command to `{ profiles, inventory }` or `{ profiles, jobs }`, with optional `aliases` (and, on an inventory entry, an optional `per_file` runner for files CI skipped entirely, see [skipped files](#skipped-files)): the run profiles whose verified runs at HEAD's clean tree carry that lane instead of running it, and either the command listing its test files, which their runs must cover, or the CI jobs that must have succeeded (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
|
||||
@@ -259,7 +259,8 @@ Two stages with separate clocks, both printed:
|
||||
`--allow-repo-commands` the selected guards are listed and the check is
|
||||
`incomplete`. Guards are read from the base branch's copy (or the
|
||||
user-owned file when the base carries none) and cannot be
|
||||
downgraded to warn. See [guards](#guards).
|
||||
downgraded to warn. A guard whose exact command already passed at this tree
|
||||
is not run again ([guard carry](#guard-carry)). See [guards](#guards).
|
||||
|
||||
**Stage 2, test execution:**
|
||||
|
||||
@@ -710,7 +711,22 @@ other gate change. Each profile names the workflow file, the events it
|
||||
accepts, every job that must have passed (each exactly once), and the artifact
|
||||
holding the run's `tree.json`. `max_age_hours` (1–168, default 24) bounds how
|
||||
old the run may be, and `os` (`Linux`, `macOS`, `Windows`) requires
|
||||
`tree.json` to record that runner OS. Each workflow uploads `tree.json` from
|
||||
`tree.json` to record that runner OS. <a id="skippable"></a>`skippable`
|
||||
(`{ jobs, gate, scripts }`, GST-1190) lets named jobs be skipped by a path
|
||||
filter: a skipped job counts only in a `pull_request` run (whose gate diffs
|
||||
against the pull request's base; a push or dispatch gate diffs against the last
|
||||
push, which the branch's push history controls), when the `gate` job (the one
|
||||
whose output decides the skip) succeeded in the same attempt, and the workflow
|
||||
file plus the gate's inputs are byte-identical to `origin/<base>`. Those inputs
|
||||
are the declared `scripts`, which must list every repo file the gate reads,
|
||||
plus every path the gate job's steps name in the base copy of the workflow
|
||||
(also read under the job's `working-directory` and after a `${{ … }}`
|
||||
prefix), plus `package.json` when the gate runs a package script. gstack
|
||||
cannot see what a gate script imports or what a package script runs, so list
|
||||
those files in `scripts`. Otherwise the pull request controlled the skip
|
||||
decision, so the job refuses as `job_skipped` and the lane runs here. A lane
|
||||
whose every named job was skipped this way prints `LANE: <label> not owed: CI
|
||||
skipped at this tree (gate job <name>, workflow unchanged) run=…`. Each workflow uploads `tree.json` from
|
||||
its own job: `run_id`, `run_attempt`, `event`, `sha` (or `head_sha`),
|
||||
`tree` (`git rev-parse HEAD^{tree}` as tested), `files` (every test file the
|
||||
run executed), `tests` (the count) and, with `os`, the runner OS or a list of
|
||||
@@ -737,6 +753,28 @@ once:
|
||||
record (a reuse is never evidence). Its tree equals the tree git computes for
|
||||
the run's head commit. `files` is a list of paths and `tests` a
|
||||
non-negative integer when present; without `tests` the file count stands in.
|
||||
<a id="skipped-files"></a>`skipped_files`, when present, lists the files whose every test skipped on
|
||||
the runner (a Docker image, a drive path or an installed gstack it lacks;
|
||||
GST-1190). A carry treats them as uncovered: the pregate tests stage runs
|
||||
them here. A /ship lane or guard whose inventory names one carries the
|
||||
covered files and runs only the skipped ones here, through the runner its
|
||||
`ship_lanes_from` entry declares as `per_file` (a command with `{files}`,
|
||||
such as `"per_file": "bun test --timeout=30000 {files}"`, the same form as the
|
||||
tests stage's `runner`). That run is recorded under `<label>.skipped`, the
|
||||
`LANE:` line adds `skipped_here=<n> file(s) tests_ran_here=<n>`, and the CI row
|
||||
is written only after it passes with a test count above zero and every carried
|
||||
run still stands (`run_changed` otherwise). A failure there is
|
||||
`skipped_failed` and a run of zero tests is `skipped_zero_run`; either way the
|
||||
whole lane runs here. An entry with no `per_file` refuses as
|
||||
`inventory_skipped`, naming the files, and the lane runs here whole. A partly
|
||||
skipped file ran tests and stays covered. gstack's own Free Tests writer does
|
||||
not emit the list yet: it starts in the same follow-up pull request that
|
||||
declares `per_file` for gstack's `bun run test` lane, so gstack's carry does not
|
||||
change until both switch on together. A `tree.json`
|
||||
without the key (older writers, other repos) is read as before, with every
|
||||
listed file counted as run; add the list to your writer to close that gap.
|
||||
The remote gate's clearance does not use it: that gate runs on a Linux runner
|
||||
like CI, where the same files skip.
|
||||
- No run of the same workflow on that head, or on pregate.json's own head,
|
||||
whose newest attempt started at or after the second this run was created
|
||||
failed, was cancelled or is still running (`run_started_at`, so a red re-run
|
||||
@@ -785,7 +823,7 @@ Then, for the lane:
|
||||
Any API or git error refuses. Each refusal prints `REUSE: refused
|
||||
reason=<code> — …` as `PREGATE_RECEIPT_INVALID`, and a run that fails
|
||||
verification is named with its own reason (`fork_run`, `event_mismatch`,
|
||||
`run_not_success`, `job_missing`, `artifact_mismatch`, `artifact_reused`,
|
||||
`run_not_success`, `job_missing`, `job_skipped`, `artifact_mismatch`, `artifact_reused`,
|
||||
`tree_mismatch`, `newer_run_vetoes`, `run_changed`, `run_stale`,
|
||||
`os_mismatch`, `api_error`, …); the clear-level codes are `base_mismatch`,
|
||||
`no_verified_run`, `tree_mismatch` (runs on different trees),
|
||||
@@ -895,7 +933,8 @@ whose workflow holds a lane this machine runs (gstack's `ci-reuse/free-tests`
|
||||
on Linux), with pregate.json's own head as a further veto head. Its tree must be this tree exactly (no
|
||||
stamp-only substitution). Then:
|
||||
|
||||
- The selected local test files the run's `tree.json` lists count as passed.
|
||||
- The selected local test files the run's `tree.json` lists count as passed,
|
||||
except those in its `skipped_files` ([above](#skipped-files)), which run here.
|
||||
The lanes check records them under `from_run` with the run receipt
|
||||
(`run tree=… tests=… runs=<id>/<attempt> profiles=… heads=… verified=…`) and
|
||||
prints `REUSE: accepted <n> of <m> selected local test file(s) from <receipt>;
|
||||
@@ -933,11 +972,14 @@ it accepts a run only when all of these hold:
|
||||
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`).
|
||||
`tree.json` files cover every file it prints, none of them a file whose every
|
||||
test skipped there (`skipped_files`). A lane mapped by `jobs`
|
||||
instead needs no test count: each named job succeeded in the run's newest
|
||||
attempt. 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.
|
||||
Security and advisory scans, the sealed guard and every other preflight-stage
|
||||
check always run; only test lanes carry, plus guards whose exact command
|
||||
already passed at this tree ([guard carry](#guard-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
|
||||
@@ -986,8 +1028,101 @@ it and the command that lists its test files:
|
||||
}
|
||||
```
|
||||
|
||||
<a id="ship-lanes-jobs"></a>A lane with no test files to list, such as a typecheck or a verify script,
|
||||
names the CI jobs that run it instead (GST-1189). Declare exactly one of
|
||||
`inventory` or `jobs`:
|
||||
|
||||
```json
|
||||
"ship_lanes_from": {
|
||||
"bun run verify": { "profiles": ["ci/test"], "jobs": ["verify", "typecheck"] }
|
||||
}
|
||||
```
|
||||
|
||||
It carries only when every named job concluded `success` in the newest attempt
|
||||
of the verified run at HEAD's tree, read by the same `verifyRun` job check the
|
||||
profile's own `jobs` use. A job that is missing refuses as `job_missing`, a
|
||||
skipped one as `job_skipped`, any other conclusion as `job_not_success`, and a
|
||||
run of another tree as `tree_mismatch`. The receipt reads `ci-carry tree=…
|
||||
jobs=verify,typecheck runs=…`, and the ledger row records the jobs. gbrain run
|
||||
41564913688 (tree `13570abc`) is the case: its verify and typecheck jobs passed
|
||||
at the tree, but no inventory could name their files, so they ran again. The
|
||||
same form replaces fake `check:<command>` entries some repos wrote into
|
||||
`tree.json` to give a typecheck, a doc-freshness check or a lint an inventory
|
||||
(gstack-evals #180): name the job instead. A gstack older than the version that
|
||||
adds `jobs` rejects the key as invalid config, so a repo declaring it should
|
||||
first raise its `min_gstack_version` to that version.
|
||||
|
||||
<a id="ship-lanes-aliases"></a>**Aliases.** A lane is keyed on its exact command, so
|
||||
`env -u ANTHROPIC_API_KEY bun test tests/` never matches a `bun test tests/` key.
|
||||
Declare the other spellings on the entry, read from the base like the rest of
|
||||
the map (GST-1190):
|
||||
|
||||
```json
|
||||
"bun test tests/": { "profiles": ["ci/test"], "inventory": "…", "aliases": ["env -u ANTHROPIC_API_KEY bun test tests/"] }
|
||||
```
|
||||
|
||||
An alias is a second exact command, never a pattern: gstack does not strip env
|
||||
prefixes on its own, because `env -i HOME=… PATH=… bun test tests/` runs in a
|
||||
different environment than the key. An alias that repeats a key or another
|
||||
entry's alias is invalid config. The ledger row binds the command the lane
|
||||
actually ran.
|
||||
|
||||
**What `tests_ran` means on a carried lane.** No carried lane reports the whole
|
||||
run's count. A lane mapped by `inventory` reports how many of its inventory
|
||||
files the runs' `tree.json` covers, labeled as a file count (`tests_ran=14
|
||||
unit=files` on the ledger line, `tests_ran=14 (files)` on the `LANE:` line);
|
||||
alphaclaw's 14-file, 46-test guards lane used to record the run's 9677.
|
||||
`tree.json` has no per-file test counts yet, so the lane's own test count is
|
||||
not available. A lane mapped by `jobs` reports `tests_ran=n/a`. Only the
|
||||
pregate tests stage and `gstack-ci-carry find` without `--command`, which carry
|
||||
the whole run, report its test count.
|
||||
|
||||
**`tree.json` counts from Bun's JUnit.** A writer that builds `tree.json` from
|
||||
Bun's JUnit report must take the root `testsuite` count. Nested `describe`
|
||||
suites repeat the file attribute, so summing every `testsuite` counts tests
|
||||
twice. harness-evals #240's `scripts/ci-tree-json.ts` does it right.
|
||||
|
||||
<a id="prove-a-mapping"></a>**Proving a new mapping.** `ship_lanes_from` is read from `origin/<base>`
|
||||
only, so a branch that adds a mapping cannot carry from it, and running
|
||||
against `--base <PR branch>` fails (`BASE_CONTAINS_HEAD`). Prove it with the dry
|
||||
run instead, once per lane command:
|
||||
|
||||
```bash
|
||||
gstack-ci-carry find --base main --policy-from head --simulate --command 'bun run verify' --allow-repo-commands
|
||||
```
|
||||
|
||||
It reads the branch's own `ship_lanes_from` and `run_profiles`, checks the lane
|
||||
against the verified CI run at this tree exactly as a carry would, and prints
|
||||
`SIMULATION:` at the start of every line (`SIMULATION: CI_CARRY: accepted …` or
|
||||
`SIMULATION: CI_CARRY: none (<reason>)`). It writes no evidence or ledger row
|
||||
and clears no obligation. To check every /ship lane at once, the same dry run
|
||||
takes lane flags: `gstack-ship-preflight --tests-only --base main --policy-from
|
||||
head --simulate --allow-repo-commands --lane 'verify=bun run verify' …` prints `SIMULATION: LANE:
|
||||
<label> would carry run=…`, `SIMULATION: CI_CARRY: none label=<label> (<reason>)`
|
||||
or `not mapped` per lane, runs no lane and no pregate, and exits 0 when every
|
||||
mapped lane would carry. Both dry runs run the branch's inventory commands to
|
||||
check coverage, which is running the branch's code, so both need
|
||||
`--allow-repo-commands`; without it `gstack-ci-carry find --command` stops
|
||||
with a usage error (exit 2), and the preflight dry run prints
|
||||
`inventory_not_allowed` for an inventory-mapped lane. truther's adoption proved its map this way by hand
|
||||
before the dry run existed: run 41585332512 accepted 7 of 7 lanes. A branch's own map never carries,
|
||||
even when the base has no policy at all, because the pull request controls both
|
||||
the map and the CI that would satisfy it. So the first pull request that adopts
|
||||
a mapping pays its full lanes; the carry starts on the pull requests after it
|
||||
merges. `ship_lanes_from` itself needs `min_gstack_version` 1.94.0.0 or later in
|
||||
`.gstack/ship-policy.json`, and `jobs` and `aliases` need the release that ships
|
||||
them. With that floor set, a gstack that has this check but not the key prints
|
||||
`needs gstack >= <version>; upgrade` (`PREGATE_GSTACK_TOO_OLD`) instead of a
|
||||
generic invalid-config error. A gstack released before the check (1.94.0.0
|
||||
included) still reports the unknown key as `PREGATE_CONFIG_INVALID`.
|
||||
|
||||
As a second guard, every `record-ci` row names the policy that mapped it
|
||||
(`origin/<base>@<sha>:.gstack/pregate.json`), and `gstack-evidence carried`, which
|
||||
the ship receipt reads, lists only rows whose policy is `origin/<the receipt's
|
||||
base>`. A row written by a run against another base never lands in a receipt.
|
||||
|
||||
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
|
||||
(see above for what `<n>` counts) 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
|
||||
@@ -1021,6 +1156,8 @@ them (`ci_carried=<lane>:<run>/<attempt>`).
|
||||
--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.
|
||||
`find --policy-from head --simulate` is the dry run in
|
||||
[proving a new mapping](#prove-a-mapping).
|
||||
|
||||
<a id="ci-reuse"></a>
|
||||
### Main pushes reuse the merged pull request's run
|
||||
@@ -1059,6 +1196,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
|
||||
|
||||
@@ -1080,6 +1302,38 @@ guard is a *command* with its own fix line. Older gstack refuses unknown keys
|
||||
that reads them ships. The worked gbrain configuration is in
|
||||
[gbrain worked configs](#gbrain-worked-configs).
|
||||
|
||||
<a id="guard-carry"></a>
|
||||
### A guard that already passed at this tree does not run again
|
||||
|
||||
A guard is skipped as passed when its exact command already passed at this tree
|
||||
(GST-1186). Two sources count, checked in this order:
|
||||
|
||||
1. **CI.** When the base branch's `ship_lanes_from` maps the guard's exact
|
||||
command, the guard is carried from the verified CI run at HEAD's clean tree,
|
||||
through the same `gstack-evidence record-ci` and `findCarry` path a /ship
|
||||
lane uses ([ci-carry](#ci-carry)). It prints `GUARD: <id> carried
|
||||
runs=<id>/<attempt>`, or `GUARD: <id> not owed: CI skipped at this tree …`
|
||||
when every job it maps was skipped by an unchanged gate
|
||||
([skippable](#skippable)). When no run carries, it prints `CI_CARRY: none
|
||||
guard=<id> (<reason>)` and goes on to the ledger.
|
||||
2. **The evidence ledger.** When the newest local ledger row for the exact
|
||||
command at this working tree, under any label, is a counted pass (`tests_ran`
|
||||
above zero under the runtime the guard would launch with, within 24 hours),
|
||||
the guard prints `GUARD: <id> reused label=<L> source=local ts=<ts>`. CI rows
|
||||
never count here: a CI pass counts only through `record-ci`'s live check
|
||||
against the base, so an old CI row does not outlive a refusal.
|
||||
`gstack-evidence passed -- <command>` is the same lookup by hand. A newer
|
||||
failure of the command at that tree vetoes an older pass.
|
||||
|
||||
Anything else runs the guard as before, with the same timeout, stall rule and
|
||||
fix line. This matters for repos whose suites are guards rather than lanes
|
||||
(founderstar declares `check-quick`, `play-through` and `assets` as guards),
|
||||
which otherwise reran every suite /ship had just carried from CI.
|
||||
|
||||
Known limit: `ship_lanes_from` is read from `origin/<base>` only, so the pull
|
||||
request that adds a mapping cannot carry from it. Prove it with the dry run in
|
||||
[proving a new mapping](#prove-a-mapping) until it lands.
|
||||
|
||||
<a id="allowlist"></a>
|
||||
## Allowlist: benign findings the secrets check accepts
|
||||
|
||||
|
||||
+22
-4
@@ -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
|
||||
@@ -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
|
||||
|
||||
+28
-7
@@ -53,12 +53,13 @@ refuses the file (`POLICY_GSTACK_TOO_OLD`). `validate` ends with
|
||||
| `maintainers` | GitHub logins | `[]` | Maintainer set for `/review` contributor mode; empty means repository push permission. |
|
||||
| `stamp_files` | globs | `[]` | The repo's stamp rule: when set, only these files may differ by a stamp (list the version file, manifests, plugin trees and the files holding the PR's own `since:` rows). It applies before every other stamp rule, so a doc `vX` mention outside it is a difference. |
|
||||
| `stamp_patterns` | literal templates | `[]` | At most 16 templates of at most 128 characters, each with exactly one `{version}` slot (`"version": "{version}"`, `since: '{version}'`, `<!-- x-stamp: {version} -->`); matched literally at a version boundary, never as a regex. The restamp writer, its mention scanner and the tree receipt use them beside the built-in forms. |
|
||||
| `stamp_placeholders` | literal placeholders | `[]` | At most 16 one-line literals of at most 32 characters, never `{version}` and never a version (`["TBD"]`). On a line the branch added itself, a placeholder inside a `stamp_patterns` template (`since: 'TBD'` under `since: '{version}'`) may become that template at the new version, and finish's route, the receipt carry and the tree receipt read the change as a stamp. The built-in forms never take a placeholder, and neither does a base line, even one whose text duplicates a branch line. The writer does not fill placeholders: the repo's `restamp_command` does. A newer key: set `min_gstack_version` to the release `gstack-ship-policy validate` names. Empty accepts no placeholder. |
|
||||
| `restamp_command` | command or `null` | `null` | The repo's own restamp, run first in the staging worktree; see [restamp_command](#restamp-command). |
|
||||
| `migrations` | `{ dir, id }` or `null` | `null` | The migration directory and a regex with exactly one capture group for the number in a file name (`"^v(\\d+)-"`); `gstack-pregate regate` reports `MIGRATION_COLLISION`. |
|
||||
| `gate_command` | command or `null` | `null` | The repo's full pre-merge gate. `gstack-ship-queue gate-ahead` and `ready` print it for the caller to run (in the background or in CI); gstack never executes it. Needs `min_gstack_version`. |
|
||||
| `full_e2e` | `true` \| `false` | `false` | `true`: every merge needs a passing full-gate result bound to a tree equal to the merging one modulo stamps; `gstack-ship-queue ready`, `stamp` and `verify` refuse without one (`QUEUE_GATE_MISSING`): a gate-ahead record, or the lane's `--gate-exit 0 --gate-log <file>` from its run on the gated head. Needs `min_gstack_version`. |
|
||||
| `review_scope` | `frozen` \| `diff-plus-blocking` \| `all` | `frozen` | The finding scope of `/ship`'s review loop; see [review_scope](#review-scope). `frozen` fixes the diff on pass 1, files blocking findings in unchanged code as issues, and later passes read only the range since the previous pass. `diff-plus-blocking` is the same but fixes a blocking finding in unchanged code in this PR instead of filing it. `all` is the earlier loop: every finding is fixed on every pass. Needs `min_gstack_version` when not `frozen`. |
|
||||
| `review_exclude_paths` | git glob pathspecs | `[]` | Content files (data, docs, binary, `.log`) `/ship`'s reviewers leave out; read from the base only, with code, gate, config, executable and named-by-code files kept. See [review_exclude_paths](#review-exclude-paths). Needs `min_gstack_version`. |
|
||||
| `review_exclude_paths` | git glob pathspecs | `[]` | Content files `/ship`'s reviewers leave out: data, docs, `.log`, and binaries under a content extension (images, fonts, archives and the like) that do not start with executable magic. Read from the base only. Code (native libraries and every other binary outside the content extensions included), gate paths, agent prose, config, executables, links, `.gstack/` and `.github/` files, gate-tagged, secret-line and named-by-code files stay in review. See [review_exclude_paths](#review-exclude-paths). Needs `min_gstack_version`. |
|
||||
| `min_gstack_version` | version or `null` | `null` | The oldest gstack that may read the file; see the compatibility rule above. |
|
||||
| `docs` | `{ caps: [{ path, max_bytes }] }` or `null` | `null` | Documentation files with a byte cap. `/ship` Step 14.5 runs `gstack-ship-receipt docs-caps --base <base>` (the caps come from `origin/<base>`'s policy, never the branch's copy; `--policy <file>` is for a repository bootstrapping its policy) before the verification gate and prints one `DOCS_CAP: <path> <bytes>/<max> ok\|over` line per cap; any `over` (an absent file counts) exits 1 and blocks the ship until the file is trimmed or the cap raised on the base branch (`DOCS_AUDIT_BLOCKED`). At most 64 caps, each path contained. See [the ship receipt](#ship-receipt). Needs `min_gstack_version`. |
|
||||
| `train` | `{ gate_workflow, free_workflow, full_gate_check, record_artifact, max_size, fill_hours, screen_selection, trial_reservation_usd, land? }`, `{ gates, land, max_size, fill_hours }` or `null` | `null` | Turns on [merge trains](#run-a-merge-train), read from the base revision only. Every field is required and an unknown field is `POLICY_INVALID`: `max_size` 1 to 6, `fill_hours` above 0 and at most 24, `screen_selection` `gstack-paid` \| `none`, `trial_reservation_usd` above 0 and at most 100. A block with `gates` ([any repository](#train-gates)) takes `max_size` 1 to 5 and needs `min_gstack_version` at least `TRAIN_GATES_KEY_VERSION`. `null` keeps the per-PR queue exactly as it is. Needs `min_gstack_version`. |
|
||||
@@ -1287,8 +1288,8 @@ A pattern that matches no changed file is listed as `unmatched=` on the plan lin
|
||||
|
||||
**What is excluded, and what is kept.** A matched file is excluded only when it
|
||||
is content: a data file (JSON, JSONL, CSV, TSV, images), a docs-class file, a
|
||||
`.log` file, or a file git reports as binary (`-\t-` in `--numstat`; readers would only see `Binary files differ`) whose bytes hold a NUL in their first 8,000, so a branch's `.gitattributes` cannot make a text file binary content. A binary file is content even under
|
||||
`config/` or in a skill directory; only `policy-dir`, `gate-path`, `executable`, `link`, `gate-tagged`, or a source or script extension (`code`) keep it.
|
||||
`.log` file, or a binary file: one git reports as binary (`-\t-` in `--numstat`; readers would only see `Binary files differ`) under the branch's attributes or with no attributes from the tree, so a branch's `.gitattributes` cannot make an executable read as text, and whose bytes hold a NUL in their first 8,000, so it cannot make a text file binary content either. A binary file is content only under a known content extension (images, fonts, media, documents, compressed archives, `.bin`, `.dat`, and data blobs such as `.parquet`, `.npy` or `.sqlite`) and only when its bytes do not start with an executable image's magic (ELF, Mach-O including universal binaries, PE, WebAssembly, `#!`). Under those rules it is content even under
|
||||
`config/` or in a skill directory, and only `policy-dir`, `gate-path`, `executable`, `link` or `gate-tagged` keep it. Every other binary file is `code`: source with a NUL, a native library (`.node`, `.so`, `.dylib`, `.dll`), a compiled executable, a key store, a pickle, or a file with no extension.
|
||||
Everything else stays in every reader's diff with one reason code:
|
||||
|
||||
| Reason | Kept because |
|
||||
@@ -1300,8 +1301,8 @@ Everything else stays in every reader's diff with one reason code:
|
||||
| `agent-prose` | it is a skill, section, resolver, template or rule file |
|
||||
| `config` | it is a data-shaped config file (`package.json`, `tsconfig*.json`, `config/`, dotfiles) |
|
||||
| `gate-tagged` | the gate scan tagged one of its hunks |
|
||||
| `code` | it is code or a test, not content; a binary file with a source or script extension (`.js`, `.py`, `.sh`, `.wasm`) counts as code |
|
||||
| `secret-line` | an added line reads a credential (the targeted pass's secret rule) |
|
||||
| `code` | it is code or a test, not content; a binary file outside the content extensions above, or one with executable magic, counts as code |
|
||||
| `secret-line` | an added line reads a credential (the targeted pass's secret rule); for a file git calls binary only because of its attributes, the added lines come from `git diff --text`, which `.gitattributes` cannot change (readers' own diffs still follow the attributes and show the kept file as binary) |
|
||||
| `named-by-code` | a code or test file that stays in review (not docs, a data file, a `.log` or binary, and not itself excluded) names its full repository path, at the head or the merge base |
|
||||
| `consumer-scan-unavailable` | the `git grep` for those names failed, so every candidate is kept; also a live binary file whose bytes could not be read |
|
||||
| `gate-scan-unavailable` | the gate scan failed or did not run at the head, so no hunk's tag is known and every candidate is kept |
|
||||
@@ -1351,11 +1352,15 @@ paths and three hashes). The `digest` hashes the declared patterns and the
|
||||
excluded and kept lists; `source` is provenance only. Write, carry and the queue
|
||||
each recompute the digest at the current base and compare it, so a base merge
|
||||
or a moved base that leaves the patterns and the lists unchanged still carries
|
||||
and binds. A different digest means the reviewers read another selection:
|
||||
and binds. A different digest means the digest write was given (or the receipt recorded) names another selection than the head has now:
|
||||
write refuses with `RECEIPT_INVALID field=review_exclude`, carry with
|
||||
`RECEIPT_CARRY_REFUSED review_exclude changed`, and the queue with
|
||||
`RECEIPT_INVALID field=review_exclude expected=<digest> recorded=<digest>`. The
|
||||
fix is to rerun the review, never a receipt write alone.
|
||||
fix is to rerun the review and write with the digest its `verify` prints. Write
|
||||
checks the digest against the base policy, so a stale selection cannot be
|
||||
recorded by accident, but it does not read the review ledger: a write given the
|
||||
`expected=` digest passes without a review, and only the review run shows that
|
||||
the reviewers read that selection.
|
||||
|
||||
**Adopting it.** (1) Open a PR on the base that adds the patterns and
|
||||
`min_gstack_version` at least `REVIEW_EXCLUDE_KEY_VERSION`, and ship it like any
|
||||
@@ -1503,6 +1508,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 stacked PR whose receipt was written against the base, after its parent landed and the base was merged in, HEAD's product diff exactly the reviewed range from the parent's head | carries (reason `stack parent <sha12> landed`); base context next to the child's hunks is `RECEIPT_CARRY_SCOPED_REVIEW` |
|
||||
| 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
|
||||
@@ -1520,6 +1526,21 @@ since, or a parent that landed with changes the child never merged all leave a
|
||||
different diff and refuse with `RECEIPT_CARRY_PRODUCT_CHANGED`. An older
|
||||
receipt whose parent branch is gone refuses with `RECEIPT_CARRY_REFUSED`.
|
||||
|
||||
**Stacked PRs reviewed against the base (GST-1199).** A child PR that targets
|
||||
the base while stacked has a receipt whose `base` is the base and whose
|
||||
reviewed range holds the parent's hunks too, and the receipt records no stack
|
||||
parent. Once the parent squash-merges and the base is merged into the child,
|
||||
the two heads' product diffs differ by exactly the parent's hunks, which now
|
||||
sit in the base. When they differ, the carry looks for the newest commit inside
|
||||
the reviewed range (the reviewed head excluded, at most 100 commits) whose
|
||||
product change the current base already holds: `git merge-tree` of that commit
|
||||
into the base changes no product path. A conflicted product path never counts,
|
||||
so a parent that never landed is never treated as one, even when the child's
|
||||
merge dropped its change. The comparison then runs from that commit: an equal
|
||||
patch-id carries with reason `stack parent <sha12> landed`, base context next
|
||||
to the child's unchanged hunks is `RECEIPT_CARRY_SCOPED_REVIEW`, and any other
|
||||
difference refuses with `RECEIPT_CARRY_PRODUCT_CHANGED`.
|
||||
|
||||
Since the release that added `review_scope`. A `/ship` receipt names the head it
|
||||
reviewed, so a conflict-only merge of the base or a test-only fix used to
|
||||
invalidate it and cost a full re-run on identical product code.
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+32
-7
@@ -1705,10 +1705,12 @@ session holds a workflow lease on this installation: pid <p> (<age>m
|
||||
<checkout>/bin/gstack-upgrade once the lease is 120 minutes old, or
|
||||
GSTACK_UPGRADE_FORCE=1 <checkout>/bin/gstack-upgrade when no other session uses
|
||||
this checkout (UPGRADE_BUSY))` and leaves the
|
||||
checkout where the run started. Each `gstack-skill-start` renews the lease.
|
||||
checkout where the run started. Each `gstack-skill-start` renews the lease
|
||||
and opens a run that its `gstack-skill-end` closes; a lease whose runs are all
|
||||
closed is idle and never counts (GST-1205).
|
||||
|
||||
**Fix.** Wait for those sessions to finish (`bin/gstack-lease list` shows
|
||||
every lease with its age and `alive|dead|stale`; a holder is named as
|
||||
every lease with its age and `alive|idle|dead|stale`; a holder is named as
|
||||
`pid <p> (<age>m <command>)`), then re-run `bin/gstack-upgrade`. For the
|
||||
session's own run, or a shared-harness lease, re-run once the lease is 120
|
||||
minutes old. When you know no other session uses the checkout, `GSTACK_UPGRADE_FORCE=1 bin/gstack-upgrade`
|
||||
@@ -3340,10 +3342,13 @@ targeted refusal, run the targeted reader on HEAD, `gstack-review-dispatch verif
|
||||
use this code when the receipt's review_exclude digest (or the
|
||||
`--review-exclude <digest>` write was given) is not the digest HEAD has under the
|
||||
base policy's [`review_exclude_paths`](ship-policy.md#review-exclude-paths). The line
|
||||
names `expected=` (now), `recorded=` (what the review read, `none` when it read
|
||||
without exclusion) and `source=` (the base commit). The reviewers read another
|
||||
selection than the one the head now has, so a receipt write alone cannot clear
|
||||
it: rerun `/ship`'s review on the head (`gstack-review-dispatch pass --base <base>`),
|
||||
names `expected=` (now), `recorded=` (the `--review-exclude` argument, or the digest
|
||||
the receipt recorded from it; `none` without one) and `source=` (the base commit).
|
||||
A mismatch proves only that this argument differs from the selection the head has
|
||||
now. Write compares the argument and does not read the review ledger, so the line
|
||||
says nothing about what the readers read, and a write that passes the `expected=` digest clears
|
||||
the field without a review. Do not do that. Rerun
|
||||
`/ship`'s review on the head (`gstack-review-dispatch pass --base <base>`),
|
||||
run `gstack-review-dispatch verify --ledger <ledger>`, which prints
|
||||
`REVIEW_EXCLUDE_RECORD: digest=<d>` from the briefs the readers got, then
|
||||
`gstack-ship-receipt write --pr <n> --review-exclude <d> --body <body>`.
|
||||
@@ -3730,6 +3735,23 @@ the entry is reported as unverified, not `REGEN_STALE`.
|
||||
**Fix.** Run the printed install command (`bun install`, or the one matching the
|
||||
repository's lockfile), then rerun `gstack-regen check` or the pre-gate.
|
||||
|
||||
<a id="pregate-gstack-too-old"></a>
|
||||
### `PREGATE_GSTACK_TOO_OLD`
|
||||
|
||||
**Meaning.** `.gstack/pregate.json` uses a key this gstack does not know, and
|
||||
the same tree's `.gstack/ship-policy.json` sets `min_gstack_version` above this
|
||||
gstack. The key belongs to a newer gstack (one a later release adds), so the
|
||||
line reads `needs gstack >= <version>; upgrade`. The policy still refuses,
|
||||
exactly as `PREGATE_CONFIG_INVALID` would. Only a gstack that has this check
|
||||
prints it; one released before it (1.94.0.0 included) reports the same key as
|
||||
`PREGATE_CONFIG_INVALID`.
|
||||
|
||||
**Fix.** Upgrade gstack on this machine to at least the version named
|
||||
(`bin/gstack-upgrade`, or the session install with `--for <skill>`), then
|
||||
rerun. A repo adopting a new key raises `min_gstack_version` first, so an older
|
||||
gstack that has this check prints this instead of a generic invalid-config
|
||||
error.
|
||||
|
||||
<a id="pregate-config-invalid"></a>
|
||||
### `PREGATE_CONFIG_INVALID`
|
||||
|
||||
@@ -5981,7 +6003,10 @@ the reviewed tree but the base moved under it, so the diff a reviewer would see
|
||||
is not the reviewed one. For a stacked PR retargeted to the base after its
|
||||
parent landed, it means HEAD's product diff against the base is not the range
|
||||
reviewed against the parent branch: the parent has not fully landed, or the
|
||||
branch changed since. The reviewed verdict does not cover HEAD, so the
|
||||
branch changed since. A stacked PR whose receipt was written against the base
|
||||
carries from the newest reviewed commit the base already holds
|
||||
([ship-policy.md](ship-policy.md#receipt-carry)); it refuses here only when no
|
||||
such commit exists or the branch changed since. The reviewed verdict does not cover HEAD, so the
|
||||
receipt is not carried. The refusal names the changed product paths, or for a
|
||||
retargeted stacked PR the parent branch and the base.
|
||||
|
||||
|
||||
+11
-3
@@ -385,9 +385,17 @@ The example above is the full run. The first `next` also takes `--kind`:
|
||||
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. An untracked file whose name looks like a secret (`.env*`,
|
||||
`*.pem`, `*.key`, `id_rsa`, `credentials*`, `*secret*`) is left out with a
|
||||
note, and the `DRAFT:` line names the checkout it diffed (`root=`). The prompt inlines the diff in a fence longer than any tilde
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user