Skip to content

ship-receipt write: every docs audit in one /ship run binds the reviewed digest (GST-1616) - #4071

Merged
capy-ai[bot] merged 5 commits into
mainfrom
gst-1616-two-docs-audits
Nov 6, 2026
Merged

capy-ai[bot] merged 5 commits into
mainfrom
gst-1616-two-docs-audits

Conversation

@garrytan

@garrytan garrytan commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 4071,
  "head": "442511afda228d305bdc3055b78d94983689346d",
  "version": "1.96.0.0",
  "base": "main",
  "gate": {
    "test": {
      "pass": 1606,
      "fail": 0,
      "skip": 6
    },
    "targeted": {
      "pass": 57,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "test",
      "run": 42236068585,
      "attempt": 1,
      "tree": "c2de9bae269a574144e6c4407ab6a4ae8afd4c5e"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "c2de9bae269a574144e6c4407ab6a4ae8afd4c5e",
  "product_patch_id": "7c0a561592793f3e0231e00128bd08593c2231bb",
  "gstack_version": "1.96.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 224,
    "rules": "70895942bb8a8ee2",
    "base": "1a06afdc19b18904c005495fec2af79f40800565",
    "registry": "1a06afdc19b18904c005495fec2af79f40800565",
    "gate_scan": {
      "tagged": 0,
      "head": "442511afda228d305bdc3055b78d94983689346d"
    },
    "reasons": [
      "gate-class",
      "runtime=224"
    ],
    "risk": [],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @c2de9bae269a (7 checks, current for 442511afda22)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42236068585/attempts/1",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/42234163780/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=c2de9bae269a tests=35908 skipped=111 runs=42236068585/1 profiles=ci-reuse/free-tests heads=442511afda22 verified=2026-11-06T14:48:39.359Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [
      4071
    ],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/, README.md, AGENTS.md, CONTRIBUTING.md; branch change 937b360..442511a (16 files)"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 1,
    "deferred": 0,
    "noted": 4,
    "fixed": 4,
    "scope": "frozen",
    "fix_checks": 1,
    "rounds": 3,
    "ledgers_read": 4,
    "unbound": 2,
    "dispatches": {
      "specialist": 6,
      "red-team": 2
    }
  },
  "ruled_notes": [
    {
      "finding": "test/gstack-docs-candidate.test.ts:177:testing",
      "head": "918ab93d8c962562d86a6c8b558a4647d65d12bb",
      "by": "Captain GStack Minder (GSTA-36), 2026-11-06",
      "reason": "every supported runner passes --timeout=30000, under which the test takes 2.7 s and passed 10/10",
      "at": "2026-11-06T14:28:22.435Z",
      "approval": "a-a93292b75af3"
    }
  ]
}

What changed

gstack-ship-receipt write now accepts the reviewed review_exclude digest when one /ship run audited its docs twice, as long as every change to the selection since the review is a file one of that run's audits edited.

Before: gbrain #8678 (review_exclude_paths docs/** and goldens) reviewed at digest e1b230d6. Audit 1 edited and committed an excluded docs file the PR hadn't touched. Then came a base merge and a restamp, DOCS went stale, and audit 3 edited another file. write --review-exclude e1b230d6 --docs-post <a3-post> --docs-pre <a3> refused RECEIPT_INVALID field=review_exclude because only audit 3's files were reset, so audit 1's file stayed in the selection. The only way out was HEAD's digest, which skips review of the delta.

After: the same sequence binds the reviewed digest and prints REVIEW_EXCLUDE_DOCS_AUDIT: … files=<both audits' files> audits=a1,a3.

How

  • The post snapshot carries the run's earlier audits (bin/gstack-docs-candidate). snapshot --run <invocation record> saves run_id. --pre <Prepare snapshot> on a post snapshot records edited, meaning each file the audit changed along with its content before and after. --carry <earlier -post.json> saves that audit, plus anything it carried, as earlier. A carried snapshot from another run, one with no edited, one with the same audit id, or one whose HEAD is not an ancestor is refused.
  • Write resets every file the run's audits edited (writeExcludeBinds, carriedAudits in lib/ship-receipt-docs.ts). Each carried file under a pattern that changed since its audit's HEAD is reset to its content before the first audit that edited it. This happens only when HEAD, or the last audit's Prepare snapshot for a file it edited again, holds what the last audit that touched it left. Write checks the run id again on every carried entry. Everything else stays as GST-1429 left it: the digest comparison, the treatment check (excluded or named-by-code only), and the rule that every other file is selected the same way on both sides.
  • Why carry-forward rather than several --docs-pre/--docs-post pairs. Write keeps the single pair /ship already passes. The run binding is enforced where the list is built and again at write. With pairs, each snapshot would still need a run id to stop a lane from importing another run's audit.
  • /ship prose. Step 14.5's Prepare passes --run, and its post snapshot adds --pre, plus --carry on a re-audit. Step 19 passes the last audit's pair. The docsync fixture interface now accepts those flags.

Blast radius

The docs-audit exception on receipt write, and the snapshot record, which gains the optional run_id, edited and earlier fields. compare ignores the new fields. Snapshots taken without the new flags behave as before. lib/ship-receipt-depth.ts had to change, because writeExcludeBinds is where the reset is built. The record parsing went into lib/ship-receipt-docs.ts.

Tests

Written to fail first, in test/review-exclude.test.ts under "two docs audits in one /ship run (GST-1616)":

  • The #8678 shape (audit, base merge, restamp, re-audit) binds with the reviewed digest. The same run without --carry still refuses, as on main.
  • A non-audit file committed between the audits still refuses, and so does a later edit to the file audit 1 edited.
  • Another run's snapshot is refused by snapshot --carry, and a forged earlier entry is refused by write.

test/gstack-docs-candidate.test.ts checks the edited record and the --carry refusals.

Closes GST-1616.

Pre-Landing Review

REVIEW_LOOP: passes=2 blocking_found=1 deferred=0 noted=4 fixed=4 scope=frozen unbound=2 ledgers_read=4 fix_checks=1 dispatches=8

  • Pass 1 (full): 3 informational findings, all fixed (bd3f012, 918ab93).
  • Pass 2 (full, range b5898e6..918ab93) and Step 11 voices: the outside voice (GPT-6.1 Sol) found that 918ab93's retry without the oldest carried audits dropped a carried audit's integrity refusal, so an unreviewed edit to a doc that code names could bind. Reproduced, fixed in b9c5fa8 (only the reconstruction digest mismatch retries), with the repro as a must-refuse test. One owner-granted fix-check (approval a-5c2faf47346f) found nothing at the floor.

Ruled note: test/gstack-docs-candidate.test.ts:177:testing at 918ab93 ruled by Captain GStack Minder (GSTA-36), 2026-11-06 at 2026-11-06T14:28:22.435Z: every supported runner passes --timeout=30000, under which the test takes 2.7 s and passed 10/10 (approval a-a93292b75af3)

Gate edits: none detected (5 listed, 3 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)

Review notes

Below the blocking floor; recorded here and not fixed in this PR.

  • bin/gstack-ship-receipt:121: the --docs-post usage and docs/ship-policy.md#review-exclude-paths do not describe write's retry without the oldest carried audits, or the reset of a carried file the re-audit edited again.
  • lib/ship-receipt-depth.ts:435: when a shorter carried list binds, the REVIEW_EXCLUDE_DOCS_AUDIT line names no dropped audit.
  • test/review-exclude.test.ts: refusal rows assert only the first attempt's reason.
  • lib/ship-receipt-depth.ts:436: the failure path rebuilds once per carried audit, and each rebuild leaves an unreachable commit (one or two per run).
  • lib/ship-receipt-depth.ts:399 (fix-check): an excluded file edited between audits and re-reviewed now refuses where 918ab93 bound it (fails closed).
  • lib/ship-receipt-depth.ts:442 (fix-check): a non-integrity refusal on a shorter list also ends the retry loop (fails closed).

Documentation

Current: no documentation edits were needed. docs/ship-policy.md, docs/troubleshooting.md, docs/review-policy.md and the ship section templates match the new flags (audit d1-4071).

Evals

E2E Evals run 42221461917 at b5898e6: 25/25 passed, 0 failed, 0 flaky reruns, $12.43. Reused as evidence for the final head: the selection at b9c5fa8 is the same 25 cases on 23 shards.

Issues

Refs #4071
Refs gbrain#8678
Refs review-p1r/red-team#1
Refs review-p1r/red-team#2
Refs review-p1r/specialist-batched#1
Refs review-p2/outside-voice#1

Approvals

Approved: yes (record r-5641b59b4612). The full approval record stays private: this repository is public or its visibility is unknown.

Open in Capy

…T-1616)

When Step 14.5 audits twice in one /ship run (an audit, then a base merge and
restamp, then the re-audit), receipt write reset only the last audit's files,
so a file the first audit edited and committed stayed in the review_exclude
selection and write refused the reviewed digest (gbrain #8678).

gstack-docs-candidate snapshot now takes --run (the invocation record), --pre
on a post snapshot (records the files the audit edited, before and after) and
--carry (the run's earlier post snapshot, refused from another run). Write
resets every file the run's audits edited to its content before them when HEAD
holds what the last of them left; a file no audit edited, an edit after an
audit and a carried audit of another run still refuse.

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

trunk-io Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 2 commits November 6, 2026 13:43
…audit chain (Step 7 coverage, GST-1616)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: review-p1r/specialist-batched#1 reader=testing
Review-Finding: review-p1r/red-team#1 reader=red-team
Review-Finding: review-p1r/red-team#2 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
garrytan and others added 2 commits November 6, 2026 14:19
…usal (GST-1616)

918ab93 retried writeExcludeBinds with shorter carried-audit lists on any
failure, so an unreviewed edit to a file a carried audit edited (one code
names, so the selection digest did not move) bound once that audit was
dropped (outside voice on #4071). Only the reconstruction digest mismatch
retries now; an edit after an audit, a file changed between audits and a
foreign HEAD end the check. The repro is a test that must refuse.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: review-p2/outside-voice#1 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai
capy-ai Bot marked this pull request as ready for review November 6, 2026 14:52
@capy-ai
capy-ai Bot merged commit 1077095 into main Nov 6, 2026
67 checks passed
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