Skip to content

v1.94.14.0 fix(review): review_exclude_paths keeps native binaries, NUL-bearing code and attribute-binary secret lines; exact --review-exclude docs (GST-972) - #3902

Merged
capy-ai[bot] merged 11 commits into
mainfrom
capy/reviewexcludepaths-keeps-native
Nov 3, 2026
Merged

capy-ai[bot] merged 11 commits into
mainfrom
capy/reviewexcludepaths-keeps-native

Conversation

@garrytan

@garrytan garrytan commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 3902,
  "head": "b1400587de8891738195ad5193482b2e2ef0fc7e",
  "version": "1.93.33.0",
  "base": "main",
  "gate": {
    "targeted": {
      "pass": 376,
      "fail": 0,
      "skip": 0
    }
  },
  "session_kind": "unattended",
  "head_tree": "b957a29553dbae5ee5a2d5efdc844dce0625c8ad",
  "product_patch_id": "c2ff7413c744c03d7813fcedbfc1e9eac839fea7",
  "gstack_version": "1.93.33.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 112,
    "rules": "b2272efd321ce7cb",
    "base": "e4e9913398e3b11a445bb5706bd387b4be5d38c4",
    "registry": "e4e9913398e3b11a445bb5706bd387b4be5d38c4",
    "gate_scan": {
      "tagged": 0,
      "head": "b1400587de8891738195ad5193482b2e2ef0fc7e"
    },
    "reasons": [
      "gate-class",
      "runtime=112"
    ],
    "risk": []
  },
  "pregate": "requires-remote cleared @b957a29553db (7 checks, current for b1400587de88)",
  "requires_remote": [
    "pregate.json/remote_gate: remote-gate tree=b957a29553db tests=34460 runs=41574670508/1 profiles=ci-reuse/free-tests heads=b1400587de88 verified=2026-11-03T03:57:51.069Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [
      3905,
      3910
    ],
    "flakes": []
  },
  "docs": {
    "status": "blocked",
    "scope": "the PR's 7 files and the review_exclude_paths docs in docs/ship-policy.md, docs/troubleshooting.md, docs/review-policy.md; round-2 edits not re-audited",
    "exception": {
      "accepted_by": "GStack Minder (Captain, GSTA-36)",
      "date": "2026-11-02",
      "via": "Captain reply relayed by the parent lane on GST-972, option A for #3902",
      "reason": "round-2 doc and help-text edits to bin/gstack-ship-receipt, docs/ship-policy.md, docs/troubleshooting.md, lib/review-exclude.ts, lib/ship-receipt-depth.ts and the changelog fragment, read by fix-check fc2, no third audit"
    }
  },
  "review_loop": {
    "passes": 3,
    "blocking_found": 5,
    "deferred": 1,
    "noted": 5,
    "fixed": 1,
    "scope": "frozen",
    "fix_checks": 2,
    "rounds": 5,
    "unrecorded": 4,
    "ledgers_read": 3,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  },
  "review_loop_exception": {
    "accepted_by": "GStack Minder (Captain, GSTA-36)",
    "date": "2026-11-02",
    "via": "Captain reply relayed by the parent lane on GST-972, option A for #3902",
    "reason": "string fix to the carry refusal at bin/gstack-ship-receipt:754 after fix-check fc2: change one string with no behavior change; the acceptance covers it, so it gets no review round and no fix-check",
    "fix_check": {
      "head": "645770c3d15f78afeaae44de598511696f319350",
      "findings": 3,
      "files": [
        "bin/gstack-ship-receipt"
      ]
    }
  }
}

Summary

GST-972 items 2, 3, 5 and 6. Item 1 was dropped because GST-884 covers it. Item 4 waits for GST-1084, because lib/review-depth.ts is pinned.

  • Item 2, the docs say exactly what write checks. --review-exclude is bound to the digest the base policy gives HEAD. It is not bound to the review, because write never reads the ledger. That limit is now stated everywhere the old claim was. Binding the flag to the ledger was not done, because the ledger is a local file the same writer produces, so the binding would still be self-reported, and it would take a larger edit in bin/gstack-ship-receipt, which is the GST-552 lane's file.
  • Item 3, native binaries are code. .node, .so, .dylib and .dll files stay in review. So does any file git reports as binary that starts with ELF, Mach-O, PE, WebAssembly or #! magic, whatever its extension. Round 2 reads git's binary verdict a second time with the branch's attributes switched off (--attr-source=<empty tree>), so a branch diff attribute cannot make git treat an ELF as text and skip the check, and it adds the 64-bit fat Mach-O magic. When git is too old for --attr-source, every matched path is sniffed.
  • Round 2 wording. The carry refusal (RECEIPT_CARRY_REFUSED: review_exclude changed), the write refusal, the queue line, ship-policy.md and the troubleshooting entry now say only that the digest the receipt holds, which came from write's --review-exclude argument, differs from the head's selection. None of them claims anything about what the reviewers read.
  • Item 6, an allowlist replaces the code-extension denylist. A binary file is content only under a known content extension: images, fonts, media, documents, compressed archives, .bin, .dat and data blobs. Every other binary is kept as code.
  • Item 5, attribute-binary files are read as text for the secret-line rule. The rule reads git diff --text --no-textconv --no-ext-diff -U0, one call per 24,000 bytes of literal pathspecs. When a git call fails or its output does not line up with the paths, every file in that chunk is kept.

Security read: there are no network calls, environment reads, permission changes, workflow, setup or dependency edits. The new code runs local git diff calls with the existing timeout and buffer.

Files shared with sibling lanes: bin/gstack-ship-receipt (help text and two refusal strings) and lib/ship-receipt-depth.ts (one comment and the excludeMismatch message) are on GST-552's list.

Failing first

Four new tests in test/review-exclude.test.ts failed on main 14d7414 (0 pass, 4 fail; on main the three exclusion tests got kept_files: [], and the docs test found the over-claim after the write with the expected= digest succeeded). After the fix the whole file passes (19/19). Logs: captain-gstack-minder/handoffs/GSTA-202/evidence-GST-972/.

Security read

No network calls, environment reads, permission changes, workflow, setup or dependency edits. The new code runs one local git diff --text per attribute-binary matched file, with the existing timeout and buffer.

Follow-up (not in this PR)

The named-by-code consumer scan uses git grep -I, which honors .gitattributes: a branch that marks a consumer code file binary hides it from the scan, so the data file it names is excluded instead of kept as named-by-code. The code file itself stays in review and the .gitattributes edit shows in the diff.

Files shared with sibling lanes

bin/gstack-ship-receipt (help text only) and lib/ship-receipt-depth.ts (one comment and the excludeMismatch message) are on the GST-552 lane's list.

Refs GST-972

Open in Capy

What changed

The four GST-972 tests fail on main and pass on this branch. The image render failed on this machine (PR_SHOTS_RENDER_FAILED: the bundled browser would not start), so this is the text version. Round 2 added a fifth test (a branch .gitattributes that makes git read an ELF as text cannot get it excluded; fat64 Mach-O is native): it is red at bf48ff6 and green at 645770c.

Before/after as text: The four GST-972 tests fail on main and pass on this branch
--- Before · before.txt · captured output
+++ After · after.txt · captured output
+$ bun test test/review-exclude.test.ts -t <the 4 GST-972 tests>   # PR head bf48ff6
+(pass) the receipt binds the selection the reviewers read > write binds --review-exclude to the base policy, not to a review, and no description claim
+(pass) a branch cannot hide code under a base pattern > native binaries are code: .node, .so, .dylib, .dll and executable images under a content exten
+(pass) a branch cannot hide code under a base pattern > a NUL-bearing file is binary content only under a known content extension; code and key files 
+(pass) a branch cannot hide code under a base pattern > a branch .gitattributes marking receipts binary cannot get a credential-line file excluded: th
+ 4 pass
+ 0 fail
-$ bun test test/review-exclude.test.ts -t <the 4 GST-972 tests>   # main 14d7414
-(fail) the receipt binds the selection the reviewers read > write binds --review-exclude to the base policy, not to a review, and no description claim
-(fail) a branch cannot hide code under a base pattern > native binaries are code: .node, .so, .dylib, .dll and executable images under a content exten
-(fail) a branch cannot hide code under a base pattern > a NUL-bearing file is binary content only under a known content extension; code and key files 
-(fail) a branch cannot hide code under a base pattern > a branch .gitattributes marking receipts binary cannot hide a credential line: the keep rule r
- 0 pass
- 4 fail
 

Why

The Captain's rule for GST-972 was "the docs must not over-claim what a gate stops". gstack-ship-receipt's help, the troubleshooting entry, ship-policy.md and the queue's refusal line all said a receipt write alone cannot clear field=review_exclude. But write takes the digest from --review-exclude and never reads the review ledger, so passing the refusal's own expected= digest clears it. That text now says what the check does. Separately, three kinds of code or secrets could still be excluded from review under a base review_exclude_paths pattern: native binaries, NUL-bearing source with an extension that was not on the list, and a credential line in a file a branch marks binary through .gitattributes. All three now stay in review. Round 2 closes the gap the outside voice found (#3910): a branch diff attribute could make git read an ELF as text, so the magic check never ran.

Blast radius

reviewExclude feeds the plan, dispatch, the receipt write, carry and the queue. All of them call the same function, so they agree on one digest. A repository whose base declares review_exclude_paths will now see more files kept (unknown-extension binaries, native libraries, key stores) and a different digest. Readers will also be asked to read more. That is fail-closed and needs a fresh review on such branches (evidence: test/review-exclude.test.ts 20/20 at b140058, plus the CI free tier dispatched on the branch head, run 41574670508 at tree b957a29). Repositories without the key are unchanged: reviewExclude returns none before any of the new code runs.

Approvals

No approvals recorded for branch capy/reviewexcludepaths-keeps-native.

Test Coverage

Each of the 4 changed runtime files has a changed test naming it (gstack-ship-preflight --audit: Coverage deterministic). The four new tests are red on main 14d7414 and green at bf48ff6.
The round-2 test is red at bf48ff6 and green at 645770c (logs: evidence-GST-972/round2-failing-first-bf48ff6.log, round2-after-fix.log).
Tests ran: targeted 376

Pre-Landing Review

REVIEW_LOOP: passes=3 blocking_found=5 deferred=1 noted=5 fixed=1 scope=frozen unrecorded=4 ledgers_read=3 fix_checks=2 dispatches=4
Review-loop exception: accepted by GStack Minder (Captain, GSTA-36) 2026-11-02 via Captain reply relayed by the parent lane on GST-972, option A for #3902: string fix to the carry refusal at bin/gstack-ship-receipt:754 after fix-check fc2: change one string with no behavior change; the acceptance covers it, so it gets no review round and no fix-check (fix-check at 645770c, 3 findings)
Gate edits: none detected (GATE_SCAN tagged=0 at bf48ff6)
Outside review: openai/gpt-6.1-sol at high reasoning (outside the certified medium configuration) returned one High finding. It is deferred as #3910, see below.

The pass-1 plan was full depth for the gate class: specialists (testing, security, state-machines) found nothing. The Red Team found 2 issues. #1 (CRITICAL, outside the diff): readers' own diffs still show an attribute-binary kept file as binary. It is deferred as #3905, and the changelog says so. #2 (INFORMATIONAL): one git call per file. It is fixed by batching. The one fix-check found 2 INFORMATIONAL notes, listed below. Step 11 voices: the native adversarial pass found nothing blocking, and its own severities were Medium or Low (its FIXABLE lines were collected as CRITICAL, so they count in unrecorded). The outside voice found #3910. Round 2 was one fix round the Captain granted (approval a-6124918f3402) for #3910 and the item-2 wording: one scoped fix-check (fc2) read the fix hunks at 645770c and returned 3 INFORMATIONAL notes, listed below. The carry-refusal string it flagged was then fixed under the exception above. The two later pass-2 rows are the plan's NEXT: done (round cap 2 reached) for the Step 14.5 config-row edit and a test-only type fix. Nobody read those two edits. unrecorded=4 counts the Step 11 voice findings that have no path:line for the rows to pair with: #3910 (deferred) and adversarial-native FIXABLE 3 to 5 (below).

Deferred findings

Review notes

  • fix-check, lib/review-exclude.ts:179: a file-to-symlink typechange on an attribute-binary path prints two sections, so the whole chunk is kept as consumer-scan-unavailable. This fails closed.
  • fix-check, lib/review-exclude.ts:177: a user diff.orderFile reorders sections, so the chunk is kept (fails closed). Plan and receipt machines with different configs could then compute different digests. Pinning with -O/dev/null is the follow-up.
  • adversarial-native: BINARY_CONTENT_EXT still allows .zip, .npz and .h5, which can hold code (Medium). A NUL-bearing .dat skips the secret-line check (Medium). The section split also breaks on \r, which fails closed (Low). The text diff over-reads files that are already kept (Low). REVIEW_EXCLUDE_KEY_VERSION was not raised, so a mixed-version writer and queue fail closed (Low).
  • fix-check fc2, docs/ship-policy.md:61: the key row does not name the consumer-scan-unavailable and gate-scan-unavailable kept reasons (KEPT_REASONS, lib/review-exclude.ts:41). Files with those reasons are kept as well. Open note.
  • fix-check fc2, lib/review-exclude.ts:282: on git older than 2.40 (no --attr-source, for example Apple's Xcode git) the fallback sniffs every matched path, symlinks and gitlinks included. Those land as consumer-scan-unavailable instead of link. The file is still kept, but the digest can then differ by git version, so a receipt written on git 2.40+ and checked on 2.39 refuses with field=review_exclude when a submodule or a directory symlink sits under a pattern. The suggested fix is to skip modes 120000/160000 in the fallback. Open note.
  • fix-check fc2, bin/gstack-ship-receipt:754: the carry refusal still said the reviewers read another selection. Fixed in b140058 under the review-loop exception.
  • adversarial-native: the write still clears field=review_exclude without a review (Medium). That was item 2's finding, and this PR documents it rather than changing the control.

Exploratory QA

No interactive surface changed. The behavior is covered by the fixture tests above.

Design Review

No frontend files changed, so design review was skipped.

Eval Results

No prompt-related files changed, so evals were skipped.

Plan Completion

Plan completion audit: not run (no plan is bound to this branch and no docs/designs/ file matches). The brief was GST-972 items 2, 3, 5 and 6, and all four are done.

Issues

Refs #3905
Refs #3910

TODOS

No TODO items completed in this PR.

Documentation

Scope: Mode edit, branch capy/reviewexcludepaths-keeps-native against main. I read the 7-file PR diff and the review_exclude_paths sections of docs/ship-policy.md (key table row, the excluded-and-kept rules, the reason table and the receipt-digest paragraph), docs/troubleshooting.md (field=review_exclude, REVIEW_DIFF_TOO_LARGE fix list) and docs/review-policy.md (readers under review_exclude_paths, module pointers). I also read the changelog fragment and the receipt help text in bin/gstack-ship-receipt. The working tree was clean when I looked, so there were no staged, unstaged or untracked files to add. Result: Current, with no edits. The PR already updated the docs for native-magic binaries, the content-extension allowlist, git diff --text for attribute-only binaries, and the receipt-write wording. They match lib/review-exclude.ts: BINARY_CONTENT_EXT, NATIVE_MAGIC and the secret-line rule. A grep found no stale references to the removed source/script-extension rule. docs/review-policy.md makes no claims about binary classification. Debt: I did not run the docs-caps check (not in the Steps 1-4 and 6 scope). I did not verify the docs against the full test run.

Documentation: blocked. The round-2 edits came after audit docs-gst972-2, and the audit budget allows no third audit, so they were not re-audited. The fix-check fc2 read them.
Documentation exception: accepted by GStack Minder (Captain, GSTA-36) 2026-11-02 via Captain reply relayed by the parent lane on GST-972, option A for #3902: round-2 doc and help-text edits to bin/gstack-ship-receipt, docs/ship-policy.md, docs/troubleshooting.md, lib/review-exclude.ts, lib/ship-receipt-depth.ts and the changelog fragment, read by fix-check fc2, no third audit

Test plan

  • bun test test/review-exclude.test.ts test/troubleshooting-anchors.test.ts test/gstack-ship-policy.test.ts test/module-size-ratchet.test.ts: 376 pass, 0 fail (finish lane at b140058)
  • bun run typecheck and bun run typecheck:test: no errors, no new diagnostics (round 2, 645770c)
  • Free Tests dispatched on the branch head b140058: run 41574670508
  • Windows Smoke dispatched on the branch head b140058: run 41574673484

…code and attribute-binary secret lines; exact --review-exclude docs (GST-972)

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

trunk-io Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

…tial scan flags

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
attributeBinaryLines reads attribute-binary files in one git diff per argument-byte chunk instead of one per file (red-team#2). The changelog and ship-policy row say readers' own diffs still show such a kept file as binary (red-team#1, deferred as #3905).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
garrytan and others added 8 commits November 3, 2026 02:16
…ibute-text files are #3910

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>
…ones (Step 14.5 audit)

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

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

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…l binary, whatever .gitattributes says; exact review_exclude docs (GST-972 round 2)

bytesBinary reads git diff --numstat with attributes from the empty tree, so a branch's '*.png diff -binary' cannot make an ELF read as text and skip the magic check (#3910). Adds 64-bit universal Mach-O magic. ship-policy's key row lists every kept class; troubleshooting and the write/queue refusal lines say a review_exclude mismatch compares the --review-exclude argument, not the review ledger.

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

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@github-actions github-actions Bot changed the title fix(review): review_exclude_paths keeps native binaries, NUL-bearing code and attribute-binary secret lines; exact --review-exclude docs (GST-972) v1.94.14.0 fix(review): review_exclude_paths keeps native binaries, NUL-bearing code and attribute-binary secret lines; exact --review-exclude docs (GST-972) Nov 3, 2026
@capy-ai
capy-ai Bot merged commit 8d276f9 into main Nov 3, 2026
49 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