Skip to content

ci: require an app-repo commit for an adopted app's wheel-copy change - #31351

Merged
bolichen97 merged 1 commit into
mainfrom
ci/guard-adopted-wheel-copy-drift
Nov 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
ci/guard-adopted-wheel-copy-drift

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A fix to an adopted app can no longer land only in its wheel copy, so a user who adopted the app gets every fix a built-in user gets.

Five former built-ins are pinned in src/kiro_crew/apps/adoption-pins.json. A host that adopted one runs the app repository at the pinned commit and never the wheel copy. Fixes kept landing only in the wheel copy (src/kiro_crew/apps/builtins/<dir>/, website/src/apps/<name>/) after the repository snapshot, for example the papyrus Windows LaTeX probe (#30438) and the file-explorer search truncation fix (#30505). Adopted users silently lost those fixes, and nothing in CI noticed.

Why it matters

Every adopted user runs an older app than a built-in user, with no error and no record of what they are missing. The gap grows with every wheel-only fix, and each one has to be found and ported by hand later (#31343 is that catch-up for the fixes so far).

Not a goal

  • Porting the fixes that already drifted, or bumping the pins (fix(apps): pin the adopted apps at commits carrying the wheel's fixes #31343 does that).
  • Proving the named app-repo commit exists or carries the same change. The gate checks the line's shape and repository; reviewers judge the content.
  • Guarding wheel copies of apps that are not pinned yet. They are still the only copy, so fixing them in place stays fine.

What changed (motivation → approach → change)

A wheel-only fix to a pinned app is lost for adopted users, so the cheapest effective guard sits where the PR body is visible: PR Hygiene. The new .github/scripts/adopted_wheel_copy_check.py step fails a PR that adds or modifies a non-test file in a pinned app's wheel copy, unless the body has one line per changed app naming its app-repo change: App repo: <owner>/<repo>@<sha> or App repo: <owner>/<repo>#<PR>, using the pin row's repository. Deleting wheel-copy files is always allowed, and test files are exempt because they never ship. A name counts as pinned if the merge base, the base tip or the head pins it: a PR cannot drop its own pin to pass, and a branch cut before a pin landed on main is still held to it. The step runs the script from the base ref, like the Sibling sweep and Proof steps, so a branch cannot weaken its own check. Editing the body re-runs the check with no push. AGENTS.md (No built-in apps), the app-kit-platform spec (§33) and docs/ci/ci-and-reviews.md (PR Hygiene) now state the rule.

Backwards compatibility

Compatible: no product code changes, so nothing a user runs behaves differently. For contributors, an open PR that edits a pinned app's wheel copy will fail PR Hygiene on its next run after this merges, until its body gets an App repo: line.

Removes nothing: the only new behaviour is a CI condition on pull requests. The runtime, the pin table and the wheel copies are untouched.

Tests

test/test_adopted_wheel_copy_check.py (25 tests):

  • the real fix(papyrus): probe tectonic.exe/pdflatex.exe in userspace on Windows #30438 and fix(file-explorer): report search as truncated only when matches were dropped #30505 name-status diffs are flagged against the shipped pin table, and pass once the body names the app repo;
  • frontend and added files count; deletions, test files, unpinned built-ins and sibling-prefix paths (papyrus-extra/, papyrusApi.ts) do not;
  • a pin present only at the merge base, only at the base tip, or only at the head still counts; an unreadable pin table fails closed;
  • each changed app needs its own line; bullets, CRLF and slug case are accepted; placeholder, too-short, #0, mid-line, wrong-repo and URL forms are rejected;
  • every pinned app's backend package sits at the path the check derives (builtins/<name with _>/);
  • CLI exit codes, and the body is read as data, never run;
  • wiring: the step sits after the merge-base step, takes PR_BODY from env, diffs the merge base with --no-renames, reads the merge base, base tip and head pin tables, and reads the script from the base ref.
  • the step's one array expansion uses the ${a[@]+"${a[@]}"} form that test/test_workflow_array_expansion_bash32.py requires, so the block also runs under macOS bash 3.2.

Determinism: 5 runs in shuffled order, 25/25 each time. test_flake_pattern_ratchet.py passes. Every test file that names code-review.yml or pr-hygiene passes (1982 tests), the bash 3.2 expansion pin included. The frontend leg could not run on this host (npm E401), and this diff has no frontend change.

Manual verification

Ran the workflow step's exact run: block locally against real commits. With an empty body, 00a0937 (#30438, papyrus) exits 1 and 3adab5e (#30505, file-explorer) exits 1, each naming the line to add. On 665a0e4, the current main tip, which touches no wheel copy, it exits 0. In a scratch repository where only the base tip pins papyrus, a papyrus wheel-copy edit exits 1 with an empty body and 0 with an App repo: line; the same block with the base tip left out of the pin loop exits 0, which is the gap this step closes.

Related Issues

Part of #26967

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 10:54
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 10:54
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 10:54
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 6, 2026
@bolichen97
bolichen97 force-pushed the ci/guard-adopted-wheel-copy-drift branch from 218b977 to b41e66a Compare November 6, 2026 11:45
@bolichen97

Copy link
Copy Markdown
Contributor Author

Round note for head 218b9774a7, now superseded by b41e66af99:

  • Backend Tests (3.12, 6) and Backend Tests (Windows) (8) failed on test/test_workflow_array_expansion_bash32.py::test_no_workflow_expands_an_array_in_a_form_bash_32_rejects. The new step expanded "${pin_files[@]}" in a form that aborts under bash 3.2 with set -u when the array is empty. This PR caused it. Fixed in b41e66a, which uses ${pin_files[@]+"${pin_files[@]}"}. Coverage Gate failed only because those two jobs failed.
  • Design, First Principles, UX, GPT 6.1, Opus 5.5, Sensitive Change Review, Dependency License Gate and Publish readiness signal all failed when the shared installation token hit GitHub's primary rate limit (API rate limit exceeded for installation), so none of them posted a verdict. They run again on the new head, which also brings the branch up to date with main (665a0e4e4a).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision e0dd498b55576df57ff2573454e33604f125e5c7 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e0dd498b55576df57ff2573454e33604f125e5c7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e0dd498

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e0dd498b55576df57ff2573454e33604f125e5c7 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of e0dd498b55576df57ff2573454e33604f125e5c7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns: the gate runs where the PR body is visible, its script is read from the base ref, it checks pins at three revisions, and the limit on what it verifies is stated as a non-goal.

Notes

  • TestShippedTable checks that each pinned app's backend directory is where the gate looks (builtins/<name with _>/), but nothing checks the frontend directory (website/src/apps/<name>/). If a pinned app's UI folder is spelled differently from its pin name, edits to its UI would pass the gate without a check. A one-line assertion would close this.

[DESIGN-REVIEWED] e0dd498

Description read

[DESCRIPTION-READ] 510f8150dfb6fa77d281d4909fe80db2c9533a68c67e55e4ddca458f853bb6ce

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e0dd498b55576df57ff2573454e33604f125e5c7 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The defect is shown by #30438 and #30505, and the gate sits where the PR body can be read. Deleting the wheel copies under #26967 is the actual fix and is still out of scope.

Notes

  • Item 1 — symptom-level: fixes are lost because two copies exist (the wheel copy and the app repo). This gate guards that gap without removing it. Subtraction: delete this step and its test when Move every built-in app out to KiroCrewApps and forbid built-in apps #26967 removes the last pinned wheel copy.
  • Item 6 — duplicate of src/kiro_crew/apps/builtin_adoption_pins.py:59: _REPOSITORY_RE there spells the same github-slug pattern that the new script redefines. Subtraction: import the runtime's regex, as scripts/adoption_pin.py already does, and delete the copy.

What this change ships

Inventory (6 items) — 4 justified

Intent: a fix to an adopted app has to reach users running the app repo as well as wheel users. FIX (a CI guard).

  1. PR Hygiene fails a PR that edits a pinned app's wheel copy unless the body has an App repo: line — symptom-level
  2. A name counts as pinned if the merge base, base tip or head pins it — justified
  3. The gate script is read from the base ref, not from the branch — justified
  4. Deleted files and test files are exempt — justified
  5. AGENTS.md now limits "fixing one in place is fine" to apps that are not pinned — justified
  6. A new copy of the repository-slug regex in a CI script — duplicate of src/kiro_crew/apps/builtin_adoption_pins.py

[FIRST-PRINCIPLES-REVIEWED] e0dd498

Description read

[DESCRIPTION-READ] c03ba4a0a79a676989bd42df65def95862e0cb912aaa810ee869064e18be8a51

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed e0dd498b55576df57ff2573454e33604f125e5c7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e0dd498

Verdict parsed from the review's SHA-scoped output markers for commit e0dd498b55576df57ff2573454e33604f125e5c7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable e0dd498b55576df57ff2573454e33604f125e5c7 false-positive: <reason, 20 to 500 characters>

Once adoption-pins.json pins a former built-in, adopted hosts run the
app's own repository and never the wheel copy, so a change made only to
src/kiro_crew/apps/builtins/<dir>/ or website/src/apps/<name>/ is lost
for them. PR Hygiene now fails such a change unless the body names the
matching app-repo commit or PR on an 'App repo: <owner>/<repo>@<sha>'
line. Deleting the wheel copy and test files stay exempt.

Part of #26967
@bolichen97
bolichen97 force-pushed the ci/guard-adopted-wheel-copy-drift branch from b41e66a to e0dd498 Compare November 6, 2026 12:08
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: pin tables read per revision for the wheel-copy gate

  • Include target-branch pins when checking older PR branches span=1acf088662a4

fixed in e0dd498: the pin loop reads $MERGE_BASE, $BASE_TIP and $HEAD_SHA, so a pin that landed on main after the branch point holds the PR to an App repo: line.
Class swept: every statement of which revisions' pins count (workflow loop and its comment, the script docstring, app-kit-platform spec) now names the base tip; the wiring test pins the three-revision loop and a detection test covers a pin only at the base tip.
Proof: the step's run block in a scratch repo with the pin only at the base tip exits 1 on an empty body and 0 with an App repo: line; the old two-revision loop exits 0 there.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: pin tables read per revision for the wheel-copy gate

  • for rev in "$MERGE_BASE" "$HEAD_SHA"; do span=cfd3150346d5

fixed in e0dd498: $BASE_TIP:$pins_path joins the pin tables (for rev in "$MERGE_BASE" "$BASE_TIP" "$HEAD_SHA"), so an app pinned on main after the branch point is checked.
Class swept: the workflow comment, the script docstring and the app-kit-platform spec say "merge base, the base tip or the head"; the wiring test pins the loop and a detection test covers a base-tip-only pin.
Proof: the run block in a scratch repo with the pin only at the base tip exits 1 on an empty body and 0 with an App repo: line; the old loop exits 0 there.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 6, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

NEEDS_OWNER: the check is safe and does what it says, but it gives no honest way through for a core-side change that has to edit a pinned app's wheel copy and has no app-repository twin.

What it does for users: once an app is pinned for adoption, a fix made only to its wheel copy no longer merges silently. PR Hygiene asks for the matching app-repository commit or PR, so hosts that adopted the app stop quietly missing fixes that built-in hosts get.

Owner question. Some core PRs have to touch a pinned app's wheel copy and have nothing to port. One example is open now: #31431 swaps file-explorer's inline disabled-app test for a new core helper, isAppNotEnabledError, in website/src/apps/file-explorer/FileExplorerPage.tsx. The app repository builds against the SDK and has no such call site. Earlier "make core independent of " refactors (#28032, #28021) were the same kind of change. After this merges, PR Hygiene fails those PRs, and the only ways through are to drop the wheel-copy edit or to write an App repo: line naming a commit that does not carry the change. The script checks only the line's shape and repository (adopted_wheel_copy_check.py:29-31), so the second option passes, and the PR body then states something untrue. Should there be an explicit exemption line with a required reason, for example "App repo: none -- ", or should core refactors that touch a pinned wheel copy be held until the copy is removed under #26967?

Focus checks, all verified against the head:

  • Unrelated PRs are not blocked. Only an added or modified non-test path under src/kiro_crew/apps/builtins// or website/src/apps// of a pinned name is scanned (adopted_wheel_copy_check.py:73-75 and 91-103). Root-level files in website/src/apps (builtinRegistry.ts and the like) and sibling prefixes such as papyrus-extra/ do not match, because both prefixes end in a slash. Deletions and test files are exempt (lines 78-88 and 95). Searching the open PRs found four that touch a pinned wheel copy and would fail on their next run: #31531 (papyrus fix), #31141 (file-explorer feature), #31431 (the core refactor above) and #31343 (the pin bump, which edits each app.json version).
  • Fork PRs are safe. The workflow triggers on pull_request only, with no pull_request_target anywhere in code-review.yml (lines 3-5). Permissions are contents: read (line 7), and checkout uses persist-credentials: false (pr-hygiene job, lines 377-380). No secret reaches the step. The PR body reaches the script through an env variable, never through template interpolation into the run block, and the script only regex-matches it. test_body_is_data_not_code pins that.
  • A branch cannot weaken its own check. The script is read from the base tip with git show whenever the base tip has it (code-review.yml step, new lines 591-596). The pin tables are read at the merge base, the base tip and the head, so a PR cannot drop its own pin to pass. A malformed table at the head fails closed (load_pins raising ValueError, lines 52-69, exit 1 in main). That fails the PR's own author, not anyone else.

Tests: test/test_adopted_wheel_copy_check.py together with test/test_workflow_array_expansion_bash32.py gave 31 passed at this head.

Mutations, one at a time, tree clean after each:

  • In check(), replacing "if slug.lower() not in named:" with "if False:" reddened 9 tests, among them TestRealRegressions::test_30438_papyrus_backend_fix_is_flagged, test_30505_file_explorer_fix_is_flagged, TestDetection::test_a_pin_only_at_the_base_tip_counts and TestCli::test_fail_prints_the_line_to_add.
  • Dropping "$BASE_TIP" from the workflow's pin loop reddened only TestWiring::test_every_revisions_table_and_the_merge_base_diff_are_passed. The base-tip case is therefore covered by a text match on the workflow; no test executes the run block. The PR body says the block was run by hand against real commits. I did not repeat that.

CI on this head: 82 success, 12 skipped, 0 failing. PR Readiness is success. Design and First Principles both PASS. No reviews and no inline threads. The merge-tree against main exits 0.

Source-only: I did not run the step on a real fork PR. The fork-safety claims rest on reading the trigger, permissions and checkout settings.

Follow-ups, whatever the owner decides:

  • Merge order with #31343. That PR edits the five app.json files in the wheel copies. If this lands first, its next PR Hygiene run fails until its body carries one App repo: line per app. The five pinned commits are the natural lines to add, and it is a body edit with no push.
  • A README or other non-code file inside a pinned wheel copy counts as shipped. That is probably intended, but neither the script docstring nor the spec says so.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved by Crew Captain for the on-call: checks green, PR Readiness passed, review lanes clean on this head.

@bolichen97
bolichen97 merged commit 6529854 into main Nov 6, 2026
99 of 107 checks passed
@bolichen97
bolichen97 deleted the ci/guard-adopted-wheel-copy-drift branch November 6, 2026 17:43
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 2026
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.

3 participants