Skip to content

ship finish: a Godot UID sidecar added after review binds with no reader; base-declared test_code (GST-1604) - #4063

Merged
capy-ai[bot] merged 9 commits into
mainfrom
capy/gst-1604-uid-sidecar
Nov 6, 2026
Merged

capy-ai[bot] merged 9 commits into
mainfrom
capy/gst-1604-uid-sidecar

Conversation

@garrytan

@garrytan garrytan commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner
{
  "schema_version": 1,
  "pr": 4063,
  "head": "f8f220e6f3794df928d5e0c1db39422aa29f04ec",
  "version": "1.96.0.0",
  "base": "main",
  "gate": {
    "focused": {
      "pass": 233,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "tests",
      "run": 42222590559,
      "attempt": 1,
      "tree": "97749931c04f06e8cb20520553f4d46e029f6385"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "97749931c04f06e8cb20520553f4d46e029f6385",
  "product_patch_id": "dc6e323001afd52ee12e8de2e92978170a32e2df",
  "gstack_version": "1.96.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 239,
    "rules": "70895942bb8a8ee2",
    "base": "ff65fb0c482fa2e8a87da0639ac8d5e41d81dc6c",
    "registry": "ff65fb0c482fa2e8a87da0639ac8d5e41d81dc6c",
    "gate_scan": {
      "tagged": 0,
      "head": "f8f220e6f3794df928d5e0c1db39422aa29f04ec"
    },
    "reasons": [
      "gate-class",
      "risk:security",
      "runtime=239"
    ],
    "risk": [
      "security"
    ],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @97749931c04f (7 checks, current for f8f220e6f379)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42222590559/attempts/1",
    "windows-smoke.yml/windows-smoke: https://github.com/garrytan/gstack/actions/runs/42222590562/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=97749931c04f tests=35923 skipped=111 runs=42222590559/1 profiles=ci-reuse/free-tests heads=f8f220e6f379 verified=2026-11-06T13:42:30.258Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "README.md and docs/ (138 files inventoried) plus the branch's changed docs, templates and changelog fragment against base 63489d06 at f8f220e"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 2,
    "deferred": 0,
    "noted": 5,
    "fixed": 5,
    "scope": "frozen",
    "fix_checks": 4,
    "rounds": 6,
    "ledgers_read": 9,
    "dispatches": {
      "specialist": 6,
      "red-team": 2
    }
  }
}
{"head":"f8f220e6f3794df928d5e0c1db39422aa29f04ec","version":"1.96.0.0","gstack_version":"1.96.0.0","review_loop":{"passes":2,"blocking_found":2,"deferred":0,"noted":5,"fixed":5,"scope":"frozen","fix_checks":4,"rounds":6,"ledgers_read":9,"dispatches":{"specialist":6,"red-team":2}},"depth":"full"}

What changed

finish now routes a Godot UID sidecar added after review with no reader, and the base can declare its own test globs

finish now routes a Godot UID sidecar added after review with no reader, and the base can declare its own test globs.

Before/after as text: finish now routes a Godot UID sidecar added after review with no reader, and the base can declare its own test globs
--- Before · docs/ship-policy.md § `test_code` and Godot UID sidecars after review at 05114c8 · source text (section not present before)
+++ After · docs/ship-policy.md § `test_code` and Godot UID sidecars after review on this branch · source text
+## `test_code` and Godot UID sidecars after review
+founderstar#611 (GST-1604) hit two gaps after the owner's granted fix-check.
+CI forced one more `scripts/ui/cutscene.gd` edit, which the owner accepted
+under the review-loop exception. Lint then wanted
+`tests/cutscene_check.gd.uid`, the UID sidecar of a test script the PR added
+before review. `finish` routed the sidecar as behavior, so a one-line random
+id cost another fix-check or a fresh /ship. GDScript tests also match none of
+the built-in test globs, so an edit to `tests/*_check.gd` after review routed
+as behavior too.
+
+**`test_code`.** A base policy can declare its own test files:
+
+```json
+"test_code": ["tests/**/*.gd"]
+```
+
+`finish` then routes a matching file changed after review like a built-in
+test file. It takes the scoped reader of its test hunks, and a removed or
+gate-tagged line still routes as behavior. The globs are read from the base
+only, so a branch that declares them changes nothing until the declaration
+lands.
+
+**Godot UID sidecars.** Godot 4.4 and later write `<file>.uid` beside each
+script or shader they give a UID. The file is one line,
+`uid://<id>`, where `<id>` is a random non-negative 63-bit number in base 34
+over `a`–`y` and `0`–`8` (Godot's alphabet skips `z` and `9`, GH-83843),
+followed by a newline. A reader has nothing to read in it, and no generator
+reproduces it. So `finish`, with `--reviewed-base`, proves each `.uid` that
+would route as behavior and routes it as `sidecar=<n>` on `ROUTE:`, with no
+reader, when all of these hold:
+
+- the branch adds it after review: the path is absent at the reviewed tree
+  and at the current base, since a changed UID re-identifies the script for
+  every `uid://` reference to it;
+- its sibling (the path without `.uid`) is a regular file now, and one the
+  reviewed range added or modified (present at the reviewed tree), or one the
+  review-loop exception (`finish --review-loop-exception`) accepted; a sibling that is declared `test_code` follows the same rule;
+- it is a regular, non-executable file (mode `100644`, never a symlink) whose
+  whole content is `uid://<id>` with an optional trailing `\n`: the id
+  canonical (no leading `a` digit unless it is `a`), at most 13 digits and at
+  most 2^63−1 (`d4n4ub6itg400`);
+- no other file in the current tree declares the same `uid://<id>`: another
+  `.uid` holding it, a `[gd_scene]` or `[gd_resource]` header, or an
+  `.import` file's `uid=` line. A copied sidecar would give two resources one
+  UID; a scene that only references the script by it (`[ext_resource … uid=]`)
+  doesn't count;
+- neither it nor its sibling matches the base policy's
+  [`review_exclude_paths`](#review-exclude-paths) or `readers.forbid_paths`,
+  since no reader saw an excluded script.
+
+Each proven sidecar prints `UID_SIDECAR: <path> (beside <sibling>)`. Any other
+`.uid` keeps its old route, usually behavior, and `finish` prints
+`ROUTE_SIDECAR_REFUSED: <path> <reason>`
+([troubleshooting](troubleshooting.md#route-sidecar-refused)). A `.import` file
+is never a candidate: its `[remap]` and `[params]` sections vary by importer,
+so nothing pins its content as tightly. A `.uid` a landed stack parent ships
+isn't a candidate either. `finish` records the proven sidecars with the
+mechanical retakes, and `gstack-ship-receipt write` copies them into the
+receipt's `mechanical` list as `Godot UID sidecar: <path> (beside <sibling>)`.
+With `--body` it refuses a PR body that doesn't carry each of those lines
+word for word.

Why

founderstar#611 committed tests/cutscene_check.gd.uid after the owner's granted fix-check, and no finish route took it, so a one-line random id cost another fix-check or a fresh /ship. finish now proves such a sidecar and routes it with no reader, and a base policy can name its GDScript test files under test_code so they get the scoped test reader instead of a behavior route.

Blast radius

The change touches finish's route (lib/ship-release.ts, lib/ship-mechanical.ts), the patch classifier (lib/ship-patch.ts), the policy keys, the receipt's mechanical list and the pr-body template. It is safe because every proof failure keeps the old behavior route and prints a ROUTE_SIDECAR_REFUSED: reason, which the focused lane exercised (script ran: 233 tests, 0 fail, at 265d868 and again at f8f220e after the base merge).

Approvals

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

Summary

Godot 4 writes a <file>.uid beside every script, and a lint step can ask for one after review is done. Before this PR, finish routed that file as behavior and stopped the ship. finish now proves each such .uid (added after review, beside a reviewed or exception-accepted regular file, one canonical uid://<id> line, mode 100644, no other declaration of the same UID in the tree, nothing excluded from review) and counts it as sidecar=<n> on ROUTE:. Anything else keeps its route with a refusal reason. The receipt lists each proven sidecar and refuses a PR body that leaves one out. The new base-only test_code policy key lets a project declare test globs that the built-in globs miss, and a declared glob never matches .gstack/ or .github/. The review rounds hardened the proof (utf8 path decoding, readers.forbid_paths, UID uniqueness) and narrowed the UID holders to real declarations. The Windows curation list excludes the new test file, since bin shebang spawns fail on windows-latest (run 42205201312).

Test Coverage

Coverage: 87% (13 of 15 paths), from the Step 7 audit (audit only, no tests written by the audit).
Tests: test/ship-uid-sidecar.test.ts is new, with 10 tests, failing first on main with the #611 STOP.
Gaps: the docsFresh test_code branch in lib/ship-release.ts has no test (review note below), and the stack-parent refusal path prints no reason (review note below).
Tests ran: focused 233

Pre-Landing Review

Pass 1 (full panel, p1) found 3 issues, all fixed in b0d3849: the sidecar path decode used latin1 instead of utf8 (red-team), the sidecar proof ignored readers.forbid_paths (security), and docsFresh dropped a declared test_code path (testing). Pass 2 (p2, range 7e7b248) left 1 note. The Step 11 outside voice and adversarial pass (v1, native plus openai/gpt-6.1-sol) found 2 CRITICAL issues, both fixed in c25c5de: a declared test_code glob could match .github/ or .gstack/ paths, and the proof did not check that the UID was unique in the tree (the adversarial reader raised both as duplicates). It also left 3 notes. Fix-check fc1 (c25c5de) found nothing. Fix-check fc2 (7f0ecb8, the UID-holder narrowing) left 1 informational note: CRLF copies of a sidecar are not caught as holders. Fix-check fc3 (b0d3849..265d868) found nothing. After the owner's rule-19 merge of main (f8f220e), fix-check fc4 read only the conflict resolution in docs/ship-policy.md, lib/ship-policy-keys.ts and lib/ship-policy.ts, which keeps both this PR's test_code key and #4065's ci_record_timeout_s key, and found nothing. Its review-log row is recorded with range b0d3849..f8f220e, so finish counts fc3's and fc4's reads together. Two tooling workarounds carried fc4, both disclosed here: the planner was run with --last full (as GSTA-337 did for fc2 and fc3), because after a fix-check it plans a stop even with a recorded grant; and the fc4 review-log row was logged a second time with range b0d3849..f8f220e after the first row (range 265d868) was not counted, since finish binds only a row whose range starts at the reviewed tree. fc4's reader saw only the merge resolution, so that row stands for fc3's and fc4's reads combined, not for one reader of the whole range.

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

Review-loop exceptions: the owner (GStack Minder, 2026-11-06, via GSTA-36) granted four scoped fix-checks after the round cap: fc1 (approval a-e50129433f76), fc2 on the 7f0ecb8 narrowing (a-739f87c51600), fc3 on git diff b0d3849..HEAD after the owner's own pr-body template order (a-533fa23de622), and fc4 on the merge resolution after the owner's rule-19 merge (a-da5b8ee99f78).

Gate edits: none detected (1 listed, 0 read)

Outside review: pass (openai/gpt-6.1-sol, v1). Its 2 blocking findings were fixed in c25c5de.

Review notes

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

  • INFORMATIONAL lib/ship-release.ts:432 docsFresh now carries a declared test_code path as a test, but no test exercises that branch
  • INFORMATIONAL lib/ship-release.ts:334 under a landed stack parent the child's own .uid files are never candidates and print no ROUTE_SIDECAR_REFUSED reason
  • INFORMATIONAL bin/gstack-ship-receipt:274 the receipt refusal for an unlisted sidecar line still points at finish's MECHANICAL: lines, not UID_SIDECAR:
  • INFORMATIONAL lib/ship-sidecar.ts:52 entry() runs ls-tree without --full-tree, so finish run from a subdirectory refuses every sidecar with a misleading reason (safe failure)
  • INFORMATIONAL lib/ship-sidecar.ts:59 CRLF copies of a sidecar are not caught as UID holders

Exploratory QA

Target: gstack-ship-release finish sidecar routing and uidSidecars (lib/ship-sidecar.ts), on isolated temp fixtures only. Checkpoint 002 failed before the fix: scripts/menü.gd.uid routed as proven beside an excluded sibling (the p1 red-team finding, replayed). Checkpoints 003 and 004 passed after the utf8 fix. Verdict: pass, with no open required checks. Limit: the 300 s smoke budget expired before revalidation, so 003 and 004 ran as revalidation with --timeout-ms.

Design Review

No frontend files changed — design review skipped.

Eval Results

Evals not run in this /ship: the 113 selected behavioral eval probes for this diff were left to the release gate.

Review bot comments

No review bot comments.

Scope Drift

Scope Check: CLEAN

Plan Completion

No plan file: this is a bug fix with a failing-first test (test/ship-uid-sidecar.test.ts fails on main with the #611 STOP).

Issues

Refs p1/red-team#1
Refs p1/specialist-batched#1
Refs p1/specialist-batched#2
Refs v1/outside-voice#1
Refs v1/outside-voice#2

Verification Results

Step 8.1 obligations: 1 PASS (the #611 repro binds with no reader at 265d868, test/ship-uid-sidecar.test.ts), 0 FAIL, 0 BLOCKED. The full free suite was not run locally; CI at f8f220e carried it (run 42222590559, green).

TODOS

No TODO items completed in this PR.

Documentation

Status: current. No documentation edits were needed.

Scope: base 63489d0, head f8f220e on capy/gst-1604-uid-sidecar, with no staged, unstaged or untracked content. Reviewed the changed hunks of the committed docs (docs/ship-policy.md, docs/troubleshooting.md, ship/sections/pr-body.md and its .tmpl, and the changelog.d fragment) against lib/ship-sidecar.ts and lib/ship-policy.ts. The .uid regex, the ROUTE_SIDECAR_REFUSED reasons and the test_code key match the code.

Documentation health:
docs/ship-policy.md [Current] (test_code row, UID sidecar section match code)
docs/troubleshooting.md [Current] (route-sidecar-refused entry matches code)
ship/sections/pr-body.md + .tmpl [Current] (in sync)
changelog.d/capy-gst-1604-uid-sidecar.md [Current] (not modified)
docs/review-policy.md [Current, with a gap] (see debt)
TODOS.md [Skipped] (not touched in ship-owned mode)

Documentation coverage:
UID sidecar route: reference ✅ (ship-policy.md, troubleshooting.md), how-to ❌, tutorial ❌, explanation ✅ (ship-policy.md section)
test_code key: reference ✅, how-to ✅ (inline example), tutorial ❌, explanation ✅

Documentation debt: docs/review-policy.md Bounded post-review edits lists the bounded kinds but not the sidecar route or test_code (common gap; the explanation quadrant would fill it). One ambiguous clause in docs/ship-policy.md about a sibling declared test_code needs author confirmation.

Diagram drift: none found.

Test plan

  • focused (bun test over the 10 sidecar, route, policy, size-ratchet, tripwire, shard and Windows workflow files, launch vars unset, TMPDIR=/var/tmp/gst1604-lane): 233 pass, 0 fail at f8f220e (tree 97749931c04f)
  • bun test test/parity-suite.test.ts: 2 pass
  • guards at tree 97749931c04f (f8f220e): typecheck, skill-size, parity-suite, context-budget, module-size, goldens, conflict-markers passed; regen fresh
  • tests (bun run test): carried from CI at f8f220e (run 42222590559, 1610 files; the 111 remote-gate files and the macos-named-regressions and windows-smoke lanes cleared from runs 42222590559 and 42222590562). Every pull_request check is green at f8f220e: 33 passed, 0 failed, 12 skipped. The earlier shard 10/8 failures (runs 42207455885 and 42217554157) were the test/ship-queue-land-direct.test.ts isolation bug that GST-1613 (63489d0) fixed on main; this branch picked it up in the merge.
  • gstack-ship-release accept at f8f220e carried the tests lane (EVIDENCE FRESH, run 42222590559) but never exited 0: its final pregate rerun resets the macos-named-regressions and windows-smoke clears and stops. Both were re-cleared from runs 42222590559 and 42222590562, and gstack-pregate verify passed for tree 97749931c04f before the receipt write.
  • docs audit d3 was a third attempt (the documentation section allows two), run on the Captain's instruction after the merge changed docs/ship-policy.md. It made no edits and skipped the banned-terms check and the CHANGELOG/VERSION consistency check.
  • /ship budget (observe mode): the run ended at 93.7M capy tokens against its 90M token cap. No stop printed because no budget note ran between 70.9M (the fc4 note) and close; the lane's own $15 credit cap held.
  • Sibling trial merges: ship-receipt write: every docs audit in one /ship run binds the reviewed digest (GST-1616) #4071 (b5898e6) merges clean, and the merged tree passes typecheck and test/ship-uid-sidecar.test.ts plus test/gstack-ship-policy.test.ts (31 pass). feat(skills): skill-scoped R56 cuts for /investigate and /review, plus /review blocker proof (GST-1088 lane C, candidate) #3922 (9386a27) and fix(outside-review): a check-results sign-off keeps the no-findings conclusion (#3469) #3641 (8963f29) share only docs/troubleshooting.md, which auto-merges; both already conflict with origin/main in files this PR does not touch, so no merged-tree typecheck or tests ran for them.
  • cso-macos-launcher flake, not rerun: at 265d868 the check failed one test, mutation lock > two concurrent add-events in the settings hook, which this PR does not touch. It was not rerun at that tree and has no flaky-ledger entry, so it is unconfirmed as a flake; the check is green at f8f220e.

🤖 Generated with Claude Code

…der; base-declared test_code globs (GST-1604)

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 7 commits November 6, 2026 10:49
…spawns fail on windows-latest, run 42205201312)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/specialist-batched#2 reader=testing
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…aths never declared test code)

Review-Finding: v1/outside-voice#1 reader=outside-voice
Review-Finding: v1/outside-voice#2 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…never a scene that references the script (GST-1604)

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

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…D (GST-1604)

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

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

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

# Conflicts:
#	docs/ship-policy.md
#	lib/ship-policy-keys.ts
#	lib/ship-policy.ts
@capy-ai
capy-ai Bot marked this pull request as ready for review November 6, 2026 13:45
@capy-ai
capy-ai Bot merged commit 1a06afd into main Nov 6, 2026
46 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