mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-21 15:43:24 +01:00
fix: pre-landing review fixes (pass 1) and the review-loop budget wording
Two blocking findings from /ship's own pass 1, both reproduced in the QA smoke before the fix: gstack-ship-receipt carry hashed the product diff with git patch-id --stable, which strips whitespace, so a space moved in a reviewed shell line carried as "no product change"; and it classed package.json and every lockfile as release metadata, so a dependency swap carried too. The patch-id is now --verbatim, package.json and VERSION are metadata only while the change is a version stamp (lib/pregate/stamp-only.ts), lockfiles are product unless the policy names them, the test globs name code extensions, a dirty working tree refuses before anything is compared, and a receipt carried twice keeps the reviewed head as carry.from. gstack-review-scope: an unresolvable base is POLICY_SOURCE_UNAVAILABLE instead of a silent working-tree read; --range-base is validated; git runs with core.quotePath=false; range_base is null on pass 1; a blocking finding with no path is fix; category "testing" is a test finding below the floor; defer searches once, files nothing on a failed search and exits 0 unfiled; summary refuses zero matching passes and the receipt write is chained to it with &&; a finding the diff causes elsewhere names the changed line in `cause` and classify follows it. Review-loop budget wording (ideas from tstack's sol-loop and pstack's interrogate, rewritten; NOTICE.md): the blocker / should / nit glossary and two stop rules in Step 9.4, the checklist and docs/review-policy.md; a lead-judgment stage in the finding merge both /review and /ship render. The core read diffs $RANGE_BASE from pass 2 on. Caps and pins re-measured with reasons. Step 7 coverage audit: four tests added in existing files, the --review-loop case moved to its own test (the shared test tripped bun's 5 s default). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
6f5782b5fd
commit
c3e27fc2b8
22 files changed
+807
-153
No files matched your search
+31
-10
@@ -12,9 +12,26 @@ instead of restating it. A one-line crew rule is enough:
|
||||
|
||||
A finding is **blocking** when it is a CRITICAL defect: it would fail a test,
|
||||
break production, or lose data or secrets. Everything else is below the floor:
|
||||
an advisory, an informational item, a test gap, a wording or naming note, a
|
||||
style or simplification suggestion. Below-floor findings are reported, never
|
||||
fixed after pass 1 of a ship, and never earn another review pass.
|
||||
an advisory, an informational item, a test finding (category `testing`: a gap,
|
||||
a weak or flaky test), a wording or naming note, a style or simplification
|
||||
suggestion. Below-floor findings are reported, never fixed after pass 1 of a
|
||||
ship, and never earn another review pass.
|
||||
|
||||
Three words cover every finding, and the loop budgets by them: a **blocker** is
|
||||
the intended case gone wrong (the floor above); a **should** is a real bug a
|
||||
caller will hit inside the intended case (fixed when it is in the diff on pass
|
||||
1, deferred when it is not); a **nit** is the rest (a named note). Two stop
|
||||
rules follow: if a pass's fixes grew the diff past what the request needs, cut
|
||||
that growth first; and the cap approves nothing, so a standing blocker is
|
||||
reported, never waved through.
|
||||
|
||||
Before a merged finding counts, the parent applies lead judgment
|
||||
(`review/sections/review-army.md`, `ship/sections/review-army.md`, stage 4 of
|
||||
the merge): a reviewer whose whole return is nits found nothing; a defect names
|
||||
the call site or input that reaches it, or it is a note; structure for a case
|
||||
nothing takes is advisory; "I would have done it differently" is not a finding;
|
||||
a finding that assumes a rule the repository documents otherwise is dropped with
|
||||
the pointer. Independent agreement between reviewers is the strongest signal.
|
||||
|
||||
Every reviewer prompt gstack dispatches (the core checklist, each specialist,
|
||||
the Red Team, the outside voice) carries this definition: CRITICAL means the
|
||||
@@ -38,12 +55,15 @@ incomplete coverage, which blocks until the reviewer is rerun.
|
||||
finding in code the PR did not change is `defer`: `gstack-review-scope defer`
|
||||
files it as a GitHub issue (one per finding, reused across reruns through an
|
||||
`<!-- gstack-deferred-finding: <fingerprint> -->` marker; `unfiled (<reason>)`
|
||||
when `gh` is unavailable) and the PR body lists it under `## Deferred findings`.
|
||||
when `gh` is unavailable or its search fails, still exit 0) and the PR body
|
||||
lists it under `## Deferred findings`.
|
||||
Below-floor findings outside the diff are `note`, listed under `## Review notes`.
|
||||
2. **Pass 2 and later review only the range since the previous pass.** Each pass
|
||||
saves its head; the next pass diffs `RANGE_BASE..HEAD` for every reviewer and
|
||||
classifies with `--range-base`. Only a blocking finding in that range or in the
|
||||
diff is `fix`; every below-floor finding is a `note`.
|
||||
saves its head; the next pass diffs `RANGE_BASE..HEAD` for every reviewer (the
|
||||
gate scan and QA probes keep the whole candidate) and classifies with
|
||||
`--range-base`. Only a blocking finding in that range or in the diff is `fix`;
|
||||
every below-floor finding is a `note`. A finding the diff causes in code it did
|
||||
not change names the changed line in `cause`, and the locus follows it.
|
||||
3. **Three passes is the cap.** A pass that applies no edits is the exit: the
|
||||
PR ships with its deferred and noted items named in the body. A blocking
|
||||
finding still in `fix` scope on pass 3 stops the run and names the finding
|
||||
@@ -86,9 +106,10 @@ counters, because the reviewed product diff is unchanged.
|
||||
| `all` | everything | fixed in this PR | the whole diff, every finding | 3 fix cycles |
|
||||
|
||||
`diff-plus-blocking` is the fallback for a repository where deferred issues pile
|
||||
up; `all` is the loop as it ran before 1.91.249.0. A value other than `frozen`
|
||||
needs `min_gstack_version` at 1.91.249.0 or later so an older gstack refuses the
|
||||
file by name instead of ignoring the key.
|
||||
up; `all` is the loop as it ran before the key existed. A value other than
|
||||
`frozen` needs `min_gstack_version` at or past the release that added the key
|
||||
(`REVIEW_SCOPE_KEY_VERSION` in `lib/ship-policy.ts`) so an older gstack refuses
|
||||
the file by name instead of ignoring the key.
|
||||
|
||||
## Where this is enforced
|
||||
|
||||
|
||||
+22
-13
@@ -577,7 +577,8 @@ written by the pr-body section of `/ship` after the body is composed.
|
||||
<a id="review-scope"></a>
|
||||
## `review_scope`: how the review loop converges
|
||||
|
||||
Since 1.91.249.0. `/ship` Step 9 runs the pre-landing review in passes and fixes
|
||||
Since the release that added `review_scope` (`REVIEW_SCOPE_KEY_VERSION` in
|
||||
`lib/ship-policy.ts`). `/ship` Step 9 runs the pre-landing review in passes and fixes
|
||||
what it finds between them ([review-policy.md](review-policy.md) is the canonical
|
||||
statement). Under `review_scope: frozen` (the default) the loop converges by
|
||||
construction:
|
||||
@@ -598,7 +599,8 @@ construction:
|
||||
`## Review notes` in the PR body.
|
||||
2. **Pass 2 and later review the range since the previous pass.** Each pass saves
|
||||
`PASS_HEAD`; the next pass sets `RANGE_BASE` to it, diffs `RANGE_BASE..HEAD`
|
||||
for every reviewer (specialists, Red Team, the outside voice) and classifies
|
||||
for every reviewer (the core checklist, specialists, Red Team, the outside
|
||||
voice; the gate scan and QA probes keep the whole candidate) and classifies
|
||||
with `--range-base <sha>`. Only a blocking finding in that range (`locus:
|
||||
fix-range`) or in the diff is `scope: fix`; nothing below the floor earns a
|
||||
pass. `NO FINDINGS` is the expected reviewer result for a clean range, never a
|
||||
@@ -631,16 +633,23 @@ line, and the codes a refusal ends with are
|
||||
<a id="receipt-carry"></a>
|
||||
## Carrying a receipt across a base merge or a test-only fix
|
||||
|
||||
Since 1.91.249.0. 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. `gstack-ship-receipt carry --pr <n> --base <base>`
|
||||
(or `--body <file>`) moves the receipt to HEAD when the receipt's head is an
|
||||
ancestor of HEAD and `git patch-id` of the product diff against the base is the
|
||||
same at both heads. Product means every changed path that is not a test
|
||||
(`test/**`, `**/*.test.*`, `**/*.spec.*`, `spec/**`, `e2e/**` and the other
|
||||
`CARRY_TEST_GLOBS` in `lib/ship-receipt.ts`) or release metadata (`VERSION`,
|
||||
`CHANGELOG.md`, `package.json`, the lockfiles, `agents-digest/**`); a base
|
||||
merge contributes no product change of its own. The carried receipt records
|
||||
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.
|
||||
`gstack-ship-receipt carry --pr <n> --base <base>` (or `--body <file>`) moves
|
||||
the receipt to HEAD when the working tree is clean, the receipt's head is an
|
||||
ancestor of HEAD and `git patch-id --verbatim` of the product diff against the
|
||||
base is the same at both heads (verbatim: whitespace counts, hunk line numbers
|
||||
do not). Product means every changed path that is not test code (`test/**`,
|
||||
`spec/**`, `e2e/**`, `**/*.test.<code ext>`, `**/*.spec.<code ext>` and the
|
||||
other `CARRY_TEST_GLOBS` in `lib/ship-receipt.ts`; an `openapi.spec.yaml` is
|
||||
product) or release metadata (`CHANGELOG.md`, `agents-digest/**`, the paths the
|
||||
policy's `stamp_files`, `stamp_paths`, `release_outputs` and `changelog` name,
|
||||
and `VERSION` or `package.json` only while the change is a version stamp and
|
||||
nothing else: a dependency, a script or a new key makes them product). Lockfiles
|
||||
are product unless the policy names them. A base merge contributes no product
|
||||
change of its own. A receipt carried twice keeps the reviewed head as
|
||||
`carry.from` and adds up the merges and paths. The carried receipt records
|
||||
`carry: { from, reason, product_patch_id, changed_paths, merge_commits,
|
||||
range_diff, covers, reruns }` with the `git range-diff` evidence, prints
|
||||
`CARRY: carried from <old> to <new> (<reason>)` and the `GSTACK_RESULT:
|
||||
@@ -651,7 +660,7 @@ skill=ship status=complete` line, and its summary line ends with
|
||||
A changed product path, or a product patch-id that differs, is
|
||||
[`RECEIPT_CARRY_PRODUCT_CHANGED`](troubleshooting.md#receipt-carry-product-changed)
|
||||
(exit 3; the refusal names the paths), and a receipt whose head is not in HEAD's
|
||||
history (a rebase or force-push) is
|
||||
history (a rebase or force-push) or a working tree with uncommitted changes is
|
||||
[`RECEIPT_CARRY_REFUSED`](troubleshooting.md#receipt-carry-refused): run `/ship`
|
||||
on the new head. `/ship` Step 1 runs the carry check itself when the branch has
|
||||
an open PR, and a `CARRY: carried` result ends that run with the receipt bound
|
||||
|
||||
Reference in new issue
Block a user