Skip to content

v1.93.3.0 fix(ship-queue): refuse a head whose required targeted review is missing or failed (GST-966) - #3859

Merged
capy-ai[bot] merged 3 commits into
mainfrom
gst-966-ready-targeted-missing
Nov 2, 2026
Merged

capy-ai[bot] merged 3 commits into
mainfrom
gst-966-ready-targeted-missing

Conversation

@garrytan

@garrytan garrytan commented Nov 2, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 3859,
  "head": "2212c957693e38ab271948224a79bf51bd4782d9",
  "version": "1.92.66.0",
  "base": "main",
  "gate": {
    "focused": {
      "pass": 567,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "3d98b1160c5d77784f7805c1bff7e3163f8d4be2",
  "product_patch_id": "1c3c0f3f18dfc615a362184c25ae046351bb39e5",
  "gstack_version": "1.92.66.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 71,
    "rules": "551486253e156572",
    "base": "69c14b17d57d5eef537dacbd533ee88865a0a00a",
    "registry": "69c14b17d57d5eef537dacbd533ee88865a0a00a",
    "gate_scan": {
      "tagged": 0,
      "head": "2212c957693e38ab271948224a79bf51bd4782d9"
    },
    "reasons": [
      "gate-class",
      "runtime=71"
    ],
    "risk": []
  },
  "pregate": "requires-remote cleared @3d98b1160c5d (7 checks, current for 2212c957693e)",
  "requires_remote": [
    "free-tests.yml/cso-macos-launcher: https://github.com/garrytan/gstack/actions/runs/41428898820",
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/41428898820",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/41428899012",
    "pregate.json/remote_gate: remote-gate tree=3d98b1160c5d tests=25264 receipt=/home/user/.gstack/projects/garrytan-gstack/pregate/runs/20261102T101415Z-3205423-514c/remote/remote.log sha256=5f5cdc68fd20"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md (diff 0c84f4ee1...HEAD; the three updated policy docs plus captain, unattended, pregate)"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 1,
    "deferred": 1,
    "noted": 2,
    "fixed": 0,
    "scope": "frozen",
    "rounds": 2,
    "dispatches": {
      "specialist": 6,
      "red-team": 2
    }
  }
}

What changed

gstack-ship-queue ready, train build, train land and land now refuse a head with QUEUE_RECEIPT_TARGETED_MISSING when the head touches money, gate, auth or secret code and the PR body's /ship receipt has no done targeted pass covering every required class. That covers four cases: no pass recorded, a failed pass, a pass that did not run, or a pass on other classes. All of them share bindShippedReceipt in lib/ship-receipt-depth.ts. receiptTargetedLine becomes receiptTargetedVerdict, which returns the same REVIEW_TARGETED: line plus an ok flag and a message. The line also gains verdict=failed for a recorded failed pass.

A receipt with neither gstack_version nor review_depth predates targeted receipts. It is still accepted as legacy, the same rule receiptDepthVerdict uses, and its line says so. A head that needs no targeted class passes as before. The depth check still runs first and keeps its own code.

The same commit adds the registry entry in lib/result-codes-release.ts, the queue-receipt-targeted-missing troubleshooting anchor, the doctor mapping, updates to docs/ship-policy.md and docs/review-policy.md, and the changelog.d fragment. land and train build print the REVIEW_TARGETED: line with the refusal.

Before and after: ready on an auth head with gstack-evals#140's receipt shape (the new test, run on origin/main 0c84f4e and on this branch):

on main 0c84f4ee1:
  REVIEW_TARGETED: required=auth receipt=legacy verdict=missing
  exit 0 (READY recorded)          expect(legacy.status).toBe(EXIT.refused): Expected 3, Received 0
on this branch 2212c9576:
  REVIEW_TARGETED: required=auth receipt=legacy verdict=missing
  exit 3  the head requires the targeted reader on auth, but the receipt records no targeted pass ... (QUEUE_RECEIPT_TARGETED_MISSING)

Why

GST-966. On gstack-evals#140, gstack-ship-queue ready exited 0 even though the receipt showed REVIEW_TARGETED: required=auth receipt=legacy verdict=missing. The queue only reported the targeted line (GST-257 PR 1 shipped it report-only), so a head whose required targeted reader never ran looked the same as a clean one and could join a train. This is part 1: the queue refuses. Part 2, making /ship always record the targeted pass in the receipt and binding that record to the reviewed patch, is GSTA-167's.

Proof, failing first. The new ready test, run against origin/main's code, printed the #140 line and exited 0. It expected 3 and received 0 (test/gstack-ship-queue.test.ts:377). On this branch it passes. Function-level smoke probes of receiptTargetedVerdict (the #140 shape, legacy, depth-only, failed, not-run, partial, covered and nothing required) all behave as described above.

Blast radius

  • Code: bindShippedReceipt and receiptTargetedVerdict in lib/ship-receipt-depth.ts, plus one printed line each in lib/ship-queue-land.ts and lib/ship-queue-train.ts. Every caller of bindShippedReceipt now refuses an uncovered head: ready, train build, train land (direct and update), train ready --base-red and land.
  • Who it stops: a receipt that has gstack_version or review_depth but no done targeted pass covering the head's money, gate, auth or secret classes. That is the intended case. Older legacy receipts still pass. Pooled READYs today (v1.92.65.0 fix(review): every reviewer brief opens with the REVIEWED_TREE step (GST-897) #3830, v1.92.63.0 fix(ship): a slot restamp after the docs audit keeps finish's docs check fresh (GST-906) #3834) need no targeted class.
  • Tests: test/gstack-ship-queue.test.ts (new ready case: missing and failed refuse, done and unrequired pass), test/review-targeted.test.ts and test/ship-receipt-depth.test.ts (expectations move from report-only to refusal).
  • Security: no network calls, environment reads, permission changes, workflow, setup or install edits, or new dependencies. It only makes an existing queue check refuse where it used to report.
  • gbrain: gbrain's queue gets the same refusal with the version. Its lanes need a done targeted record in the receipt on targeted-class heads (gstack-review-dispatch verify --targeted-out, then gstack-ship-receipt write --review-targeted @<file>).

Approvals

Date Asked Exact words Outcome Covers Still pending
2026-11-02 GST-966 review round 1: outside-voice#1 (stale targeted record rebound by write) is a CRITICAL in the recorder; defer it to GSTA-167 part 2 (A) or widen scope (B)? “The Captain picked option A. Ship part 1 as it is, with no second round.” (GStack Minder (via GSTA-234)) approved PR for GST-966 only none

Source: gstack-approvals record for gst-966-ready-targeted-missing (display only; not an approval citation).

Pre-Landing Review

REVIEW_LOOP: passes=2 blocking_found=1 deferred=1 noted=2 fixed=0 scope=frozen dispatches=8

Pre-Landing Review: 10 issues (5 in the core pass, 5 from the Step 11 voices): 0 auto-fixed, 0 asked, 3 deferred, 7 noted or listed.
Gate edits: none detected (6 listed, 5 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

The panel: specialist (testing, security, state-machines), Red Team, coverage audit, adversarial-native (claude-opus-5-5) and the outside voice (openai/gpt-6.1-sol). Round 1 ran the full panel (VERIFY: clean, 4 briefs, 4 outputs). CI's typecheck then failed on the new test (two TS2345 errors from the test-type ratchet: the fixture's review_depth.class was a plain string). 2212c95 types it 'code' as const. Round 2 (the R51 cap) reviewed that one-line range with the specialist and the Red Team: NO FINDINGS from both, VERIFY: clean.

Open note: a stale targeted record passes (outside-voice#1, CRITICAL, moved to GSTA-167 part 2)

The outside voice reproduced this on a real CLI fixture:

  1. gstack-review-dispatch verify --targeted-out targeted.json at head H1.
  2. Commit an auth change at H2.
  3. gstack-ship-receipt write --review-targeted @targeted.json rebinds the H1 record to H2's product patch-id through parseReviewTargeted (unchanged code).
  4. bindShippedReceipt, and so ready, reads required=auth receipt=auth verdict=ok, although re-verifying the H1 ledger at H2 reports status=failed.

The fix is to carry the reviewed patch identity in the targeted record and check it, which is the recorder. The Captain moved it to GSTA-167 part 2 (#3855), together with #3853 (/ship's receipt-write commands never pass --review-targeted) and #3854 (write and carry skip the targeted check). This PR is still strictly tighter than main: on main the queue refuses nothing on targeted coverage.

Deferred findings

Blocking findings in code this PR did not change (review scope: frozen); filed as issues and not closed by this PR.

  • Deferred: Deferred review finding: ship/sections/pr-body.md.tmpl:207 — The queue now enforces the targeted pass, but /ship's own r #3853 — CRITICAL ship/sections/pr-body.md.tmpl:207 The queue now enforces the targeted pass, but /ship's own receipt-write step never records one. The exact gstack-ship-receipt write commands in ship/sections/pr-body.md.tmpl:207, ship/DRIVER.md.tmpl:120 and ship/sections/handoff.md.tmpl:12 pass --gate, --pregate, --issues, --review-loop and --docs, but not --review-targeted. adversarial.md.tmpl:6 only says in prose that verify --targeted-out feeds the receipt, and it names no file the write step reads. Also, write (bin/gstack-ship-receipt:222-226) does not fail when the head needs a targeted class and no --review-targeted is given. That is exactly how feat: Completeness Principle — Boil the Lake (v0.6.1) #140 ended up with gstack_version set and receipt=legacy. With this diff, such a receipt is refused with QUEUE_RECEIPT_TARGETED_MISSING at ready, train build and land on every money, gate, auth or secret head. By the diff's own numbers that is about 40 of the last 100 commits. The documented fix (troubleshooting.md#queue-receipt-targeted-missing: 'Run /ship on the head') runs the same write command again and produces the same refused receipt. So lanes that follow /ship literally get stuck in a loop.

Review notes

Below the blocking floor (advisory, informational, test-gap or wording items); recorded here and not fixed in this PR.

  • INFORMATIONAL bin/gstack-ship-receipt:729 Carry checks again that the review depth has not risen, but it does not check targeted coverage. It keeps review_targeted from the old head as it was, while planCarry allows a test-only change (lib/ship-receipt.ts:253) and a scoped-review product change. Test hunks can carry gate-scan tags (review-targeted.ts targetedPatchId: 'a test-only fix that adds a gate hunk changes it'). So a test-only follow-up can make gate a required class while the receipt depth is already full: carry prints CARRY: carried, and then ready refuses QUEUE_RECEIPT_TARGETED_MISSING. Before this diff that mismatch was only reported. The failure is fail-closed, but carry now reports success for a receipt the queue will refuse.
  • INFORMATIONAL lib/ship-queue-train-land.ts:195 Upgrading the queue mid-train halts the train partway through landing. train land binds each slot's receipt again just before merging it (landDirect:172, landUpdate:195). A train built and gated on the previous release, whose pins carry receipts with gstack_version but no review_targeted (the normal output of current /ship, see finding 1), merges its earlier slots. Once the queue runs this release, it refuses the first targeted-class slot after the paid train gate has already passed. That leaves main with part of the train landed and the rest needing /ship again. The changelog has no note about upgrading.

Informational findings, listed and not fixed (rule 23 floor, R51)

  • train land (lib/ship-queue-train-land.ts:173,195) and train ready --base-red (lib/ship-queue-train-ready.ts:198) refuse with the new code but print only the receipt and depth lines, not REVIEW_TARGETED:. The message still names the missing classes. (specialist, adversarial-native#3)
  • A train built on the previous release whose pins carry versioned receipts without a targeted record is refused at train land after earlier slots merged. Drain or check open trains before upgrading. (red-team#4, adversarial-native#3)
  • When the queue's gate scan is unavailable, targetedClasses fails closed to all four classes, and the refusal doesn't say the classes came from a fail-closed input. (red-team#3)
  • carry checks depth but not targeted coverage, so a test-only follow-up can carry a receipt the queue then refuses. This fails closed. (red-team#2, adversarial-native#2, deferred as Deferred review finding: bin/gstack-ship-receipt:729 — write and carry do not check targeted coverage (carry checks dept #3854)
  • Step 11's text in ship/sections/adversarial.md.tmpl reaches "take decision 3" before it says to run the targeted reader. On a light head with tagged test hunks, an agent may skip the reader, and the queue then refuses the receipt. This fails closed. (adversarial-native#1)
  • The legacy branch and the self-reported classes, status and brief_sha keep the depth check's trust model. (adversarial-native#4)
  • Coverage gaps: no test drives the refusal through train build, land or both-checks-fail precedence. (coverage audit)

Documentation

Scope: I audited the diff 0c84f4ee1...HEAD with its staged and unstaged state. That covers the three updated docs (docs/review-policy.md, docs/ship-policy.md, docs/troubleshooting.md), the changelog fragment and lib/ship-receipt-depth.ts. I also searched docs/captain.md, docs/unattended.md, docs/pregate.md, CONTRIBUTING.md, captain/ and capy/ for REVIEW_TARGETED, report-only wording and the receipt depth fields.

Result: Current, with no edits. The updated docs match receiptTargetedVerdict and bindShippedReceipt:

  • verdict=ok|missing|failed.
  • The refusal code is QUEUE_RECEIPT_TARGETED_MISSING, raised after the depth check.
  • It covers ready, train build and land.
  • A head that needs no class passes.
  • The queue-receipt-targeted-missing anchor exists.

None of the other docs searched mention the report-only behavior. Other hits for "targeted" in docs/ (design plans, eval notes) are unrelated.

Debt: docs/ship-policy.md and docs/troubleshooting.md do not say that a receipt with neither gstack_version nor review_depth is accepted as legacy. Only the code and its printed line say so. I did not add it because the brief calls for conservative edits, and it is a small follow-up if you want it. Recording the targeted pass in /ship's receipt write is out of scope.

Test plan

  • Failing first: the new ready case fails on origin/main 0c84f4e (expected 3, received 0) and passes here.
  • Focused lane, 567 tests, 0 fail across 18 files: test/gstack-ship-queue.test.ts, test/ship-queue-*.test.ts (13 files), test/ship-receipt-depth.test.ts, test/review-targeted.test.ts, test/doctor-components.test.ts, test/troubleshooting-anchors.test.ts.
  • bun run typecheck and bun run typecheck:test (814 known diagnostics, none new): exit 0.
  • Remote pregate (Ubicloud, --stage tests) at the frozen tree: 25,264 tests, 0 failed, tree 3d98b1160c5d (head 2212c95), $0.09 (PREGATE_REMOTE), VM destroyed. The macOS and Windows lanes are cleared from this PR's CI runs 41428898820 and 41428899012. PREGATE_VERIFY: ok.
  • Exploratory smoke: 8 function-level probes of receiptTargetedVerdict, all as specified.
  • Docs audit a966-1: current, no edits.

…ing or failed (GST-966)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@trunk-io

trunk-io Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

…l (typecheck:test ratchet)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
garrytan added a commit that referenced this pull request Nov 2, 2026
…hing after the read carries a class (gate scan run), a re-raised blocker is not fixed, verify always clears the stale record, carry names #3859

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@github-actions github-actions Bot changed the title fix(ship-queue): refuse a head whose required targeted review is missing or failed (GST-966) v1.93.3.0 fix(ship-queue): refuse a head whose required targeted review is missing or failed (GST-966) Nov 2, 2026
@capy-ai
capy-ai Bot merged commit 47079fd into main Nov 2, 2026
46 checks passed
capy-ai Bot added a commit that referenced this pull request Nov 2, 2026
…ite/carry run the targeted verdict; fix-check ledgers count (GST-986) (#3887)

* test: GST-986 failing-first cases for the targeted record, receipt write/carry and fix-check counters

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): GST-986 targeted record binds to the read commit; write/carry run the targeted verdict; fix-check ledgers count

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): GST-986 write/carry report fail-closed targeted classes; docs, changelog, adversarial repin (brief bodies unchanged)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: GST-986 review round 1 failing-first: a docs/TODOS commit after the targeted read binds; verify clears a stale --targeted-out

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): GST-986 review round 1: a record binds across class-free commits after the read; verify removes a stale targeted record

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: GST-986 fix-check failing-first: test skip after the read, re-raised blocker, verify early-return cleanup, carry wording

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(ship): GST-986 scoped fix-check batch: record binds only when nothing after the read carries a class (gate scan run), a re-raised blocker is not fixed, verify always clears the stale record, carry names #3859

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: GST-986 carry case runs receiptDepthAtHead under the fixture's private HOME (pregate real-HOME tripwire)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test: GST-986 classify .gstack/tmp/targeted.json as a /ship producer (gstack-clean, from the main merge)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: GST-986 bind a targeted record only to the product patch the reader read

The targeted gate reader at 0715327 found that the classifier-only binding
rule kept a stale record bound when a post-read edit removed an enforcing
line with no money token. Restore main's equal-product-patch check and keep
the gate-scan refusal on top of it. Docs-only binding moves to GST-1031.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant