Skip to content

ci: hold a pin pr to the wheel copy its app-repo port started from - #37419

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w7-pin-drift-guard
Nov 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w7-pin-drift-guard

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A pin PR cannot land while the app's wheel copy has changed since the commit its app-repo port started from.

Part of #26967. Three times a pin went stale while its pin PR was open: the wheel copy kept changing on main, the pinned app-repo commit never took the later change, and adopting the pin would have dropped it for every adopted user. PR Hygiene's adopted-wheel-copy step checks a change made to a pinned wheel copy, but nothing checked that a pin PR's pinned commit still matches the wheel copy it lands next to.

Why it matters

The campaign's hard rule is zero impact on current users. A stale pin swaps an adopted host onto a tree that lacks a fix or feature the wheel copy already shipped, silently, at the next restart. Catching it by hand failed three times; the two pin PRs open today (#37411, #36446) both carry drift this check reports (see Manual verification).

Not a goal

  • Checking that the app-repo commit really contains the wheel copy at the base (reviewers and the drift guard in each app repo own that).
  • Any change to the adoption runtime, the pin table, the catalog or a wheel copy.
  • Comparing the PR head: a pin PR changes the wheel copy itself (its app.json version, which a first pin must equal, D12), and the existing App repo: line already covers the PR's own wheel-copy changes.

What changed (motivation → approach → change)

A pin PR now names, per pin row it adds or changes, the core commit its app-repo port started from: Wheel-copy base: <app>@<sha> alone on a line. The PR Hygiene step fails while that app's non-test wheel copy at the base tip differs from the one at the named commit, deletions included. The base tip is the one at the PR's last event: PR Hygiene does not re-run when main moves, so the docs tell whoever approves a pin PR to edit its body (or push) right before approving, which re-runs the check against the current tip. A drift it finds holds the PR until the app repository takes the change, the row is re-pinned and the line names the newer base.

A row counts as changed when the head table's row differs from the merge base's. The comparison is git diff-tree on two trees, which the job's blobless history already holds, and an unreadable base fails closed. The check lives in .github/scripts/adopted_wheel_copy_check.py, still read from the base ref. It reads the base tip from the step's existing BASE_TIP env, so .github/workflows/pr-hygiene.yml changes only its comment; .github/scripts/code-review-history.sh gains one comment line saying a later step now reads history trees. Docs: docs/ci/ci-and-reviews.md and app-kit-platform.md § 33.

Backwards compatibility

Breaking: a PR that adds or changes a row of src/kiro_crew/apps/adoption-pins.json fails PR Hygiene until its body carries a Wheel-copy base: line per changed row and that app's wheel copy at the base tip equals the base's. Writer sweep re-run on origin/main @ f8d7751: the only writers are pin PRs; the one open today is #37411, fixed by a body edit (no push) once its app repo carries the drift reported below. #36446 merged before this guard; merged pin PRs are not re-checked.

Removes nothing: the existing App repo: rule and every other PR Hygiene step are unchanged; only pin PRs gain a requirement.

Tests

test/test_adopted_wheel_copy_check.py:

  • TestPinDriftGuard: an added or changed row needs a base line; an unchanged, dropped or base-tip-only row needs none; each changed row needs its own line; two different bases fail; malformed lines do not count; drift reported by the comparer fails.
  • TestGitCompare (a real git repo in tmp_path): a later wheel-copy change or deletion is reported, test files and sibling paths are not, an unknown base or a missing base tip fails closed.
  • TestCli: the end-to-end red and green against a real repo, the pin PR's own app.json bump is not drift, a missing BASE_TIP fails.
  • TestWiring: the step passes BASE_TIP to the script.

With the script and workflow reverted to origin/main, 17 of the new tests fail. Determinism: the file passed 3 repeats under -n 4 and once in a shuffled order (seed 7, -n0); no clock, sleep, port or network.

Manual verification

Replayed the new script on real history:

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 15, 2026 00:05
@bolichen97
bolichen97 enabled auto-merge (squash) November 15, 2026 00:05
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 84be9225ae040e1b515833f7a6f89080e3f97c77 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 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the check only runs in CI, adds a requirement to pin PRs alone, and a revert undoes it cleanly.

Notes

  • The check is only as fresh as the PR's last event. It "does not re-run when main moves", so it depends on the approver editing the body right before approving. A wheel-copy change that merges between approval and merge still slips through. Running the step on a merge-queue (merge_group) event would close that gap without anyone having to remember.
  • The Wheel-copy base: sha is whatever the author says it is. A stale port can pass by naming the base tip itself. The PR's "Not a goal" accepts this, but the docs should tell reviewers that checking this line against the app repo's own drift guard is their job.

[DESIGN-REVIEWED] 84be922

Description read

[DESCRIPTION-READ] 09be410f6460869c615c51555bf25ac5ddf8af64a91de6ecbf2511cedeaa2c90

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 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 84be9225ae040e1b515833f7a6f89080e3f97c77 — 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 description names three stale pins as the defect, and the new drift guard runs inside the existing PR Hygiene step and reads its existing BASE_TIP input.

What this change ships

Inventory (6 items) — 6 justified

Intent: stop a pin PR from landing an app-repo commit that is missing wheel-copy changes made on main since its port started. This is an ADDITION (a CI gate).

  1. A PR that adds or changes a pin row must now carry one Wheel-copy base: <app>@<sha> line for each changed row. — justified
  2. PR Hygiene fails such a PR while the app's non-test wheel copy at the base tip differs from the copy at the named base, deletions included. — justified
  3. A missing BASE_TIP, or a base commit that cannot be read, fails the check instead of passing it. — justified
  4. Two different base lines for the same app fail the check. — justified
  5. The docs tell whoever approves a pin PR to edit its body (or push) right before approving, so the check re-runs against the current tip. — justified
  6. A comment in code-review-history.sh now says later steps read history trees. — justified

[FIRST-PRINCIPLES-REVIEWED] 84be922

Description read

[DESCRIPTION-READ] db718a6205bdb4574de1e6c81e05528179ce75d4902f1bba2261184f787f5b42

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 84be922

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

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 84be922

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

@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

Adds a pin drift guard to PR Hygiene: PRs that add or change an adoption-pins.json row must name a Wheel-copy base: <app>@<sha> per changed row. The step fails while the app's non-test wheel copy at the base tip differs from the copy at that commit. It uses git diff-tree --name-only, which works on the blobless history, and it fails closed on a missing BASE_TIP, an unreadable commit or an unreadable table. The script is still read from the base ref, the sha is checked as hex and paths go after --, so no PR content reaches git as an option. Unchanged, dropped and base-tip-only rows are exempt, and the pin PR's own app.json bump is not counted as drift. Unit, real-git and CLI tests cover the new behaviour. The remaining window (main moving after the last PR event, with no merge queue) is acknowledged and documented with a manual step; it is a limit of the PR Hygiene design, not a defect in this code.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 84be9225ae · 410 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97
bolichen97 force-pushed the feat/w7-pin-drift-guard branch from 68cf0f5 to a05e70c Compare November 15, 2026 00:42
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
resolution: narrowed the claim to what the event-driven check enforces; no push-triggered workflow

  • span=7818d10f0bb8 docs promise a wheel-copy change landing while a pin PR is open reds it

fixed in a05e70c: took the review's second option. Every statement of the class now says the check holds against the base tip at the PR's last event, that nothing re-runs it when main moves, and that whoever approves a pin PR edits the body (or pushes) right before approving to re-run it against the current tip.
Sites swept (git grep "while (a|the) pin PR is open|landing while"): docs/ci/ci-and-reviews.md, the pr-hygiene.yml step comment, app-kit-platform.md "A pin is held to the wheel copy it was ported from", and the adopted_wheel_copy_check.py docstring; code-review-history.sh's comment makes no such promise and is unchanged. The PR body's What changed was rewritten to match.
A main-push re-run plus a base-sha-bound readiness verdict is new CI surface beyond this PR's goal, as the GPT lane's adjudication of the same class also concluded.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
resolution: narrowed the documented guarantee; the refresh mechanism stays out of scope

  • span=1517bbb30a97 Base advances leave the pin-drift gate green

fixed in a05e70c by narrowing: the script docstring, workflow comment, CI doc and spec no longer claim a later main change reds an open pin PR. They state the check compares the base tip at the PR's last event, and that a pin PR's approver edits the body (or pushes) right before approving, which re-runs it against the current tip (pr-hygiene.yml hears edited and synchronize).
A push-to-main re-run of every open pin PR plus a readiness verdict bound to the base sha is new cross-workflow surface for a race between two rare events; the adjudication on this head downgraded it as disproportionate, and a missed change is recoverable with a follow-up pin PR.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Round note for a05e70c (rebased onto main 3397952).

Re the code-change approver's two points on 68cf0f5: both are the stale-base class the Opus lane raised. It is fixed by narrowing the claims, not by adding a re-run on main: the CI doc, the pr-hygiene.yml step comment, app-kit-platform.md and the script docstring now say the check holds against the base tip at the PR's last event, and that whoever approves a pin PR edits the body (or pushes) right before approving, which re-runs it against the current tip. Dispositions: #issuecomment-6886779504 (Opus), #issuecomment-6886779685 (GPT).

Backend Tests (3.12) shards 1/2/8 and Coverage Gate on the previous head: these are the unowned main red from #36640 vs #29423 (the row-scrub tests), not this diff, which touches no backend code. The fix is #37423 (auto-merge armed, not merged yet). This branch will be rebased onto it once it lands.

@bolichen97
bolichen97 force-pushed the feat/w7-pin-drift-guard branch from a05e70c to 413c945 Compare November 15, 2026 01:02
A pin went stale three times while its pin PR was open, because the
wheel copy kept changing on main and the pinned app-repo commit never
took the later change. PR Hygiene's adopted-wheel-copy step now asks a
PR that adds or changes a pin row for a 'Wheel-copy base: <app>@<sha>'
line per changed row and fails while that app's non-test wheel copy at
the base tip differs from the one at the named base, so the change has
to reach the app repository and the pin before the PR can land.
@bolichen97
bolichen97 force-pushed the feat/w7-pin-drift-guard branch from 413c945 to 84be922 Compare November 15, 2026 01:17
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed: TestGitCompare no longer calls os.chdir span=bfb84e4c9b7d

Fixed in 84be922. TestGitCompare now enters the repo through a class fixture that calls monkeypatch.chdir(wheel_repo), which pytest reverts on teardown; _drift no longer touches the working directory.
Class swept: process-global state mutated by a test (cwd, os.environ, sys.path) in this PR's test and script. git grep -nE 'os\.chdir|os\.environ\[.*\] *=|os\.putenv|sys\.path\.(insert|append)' finds no other site; TestCli only builds a copied child env.
Proof: the file passes 3 repeats under -n 4 and one seeded shuffled order (seed 7, -n0); test_flake_pattern_ratchet.py passes.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

Green-age note for head 84be922: green_age.py reports STALE only on a same-directory overlap (docs/system-specs/modules/metrics.md, which this PR does not edit; it edits app-kit-platform.md beside it). Proven against fresh origin/main 2092903: the commit cherry-picks cleanly, scripts/docs-lint.sh passes, and test_adopted_wheel_copy_check.py, test_pr_hygiene_guidance.py and test_code_review_history_fetch.py pass (85 passed). No push, so the current readiness stays valid.

@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.

Approve on 84be922. This PR makes PR Hygiene hold a pin PR until the app's wheel copy on main still matches the core commit its app-repo port started from, so a stale pin can no longer drop a wheel-copy fix for adopted users. The new check acts only on PRs that add or change a row of the pin table, so unrelated PRs are not affected. It fails closed when the base tip is missing, the named commit cannot be read, or the table is unreadable. The workflow still runs on pull_request with read-only contents permission, the PR body reaches the script only as an environment variable, the script is still read from the base ref, and the named commit is checked as lower-case hex before it reaches git. The script names no specific app. The CI doc and the owning spec changed in the same commit. All 43 tests in the touched test file pass, and seven mutations of the new logic each turned at least one named test red. One non-blocking follow-up: the spec says the named commit must be in the head's or the base tip's history, but the job's history is a partial clone, so git fetches an unknown full commit id from the repository on demand. This adds no bypass, because a named commit passes only when its wheel copy equals the base tip's, which naming the base tip already allows. The spec sentence and the history script's "later steps never fetch" comment should be corrected. The other limit, that the check sees the base tip only as of the PR's last event, is documented with a manual step for the approver. Decisive lines: .github/scripts/adopted_wheel_copy_check.py:166-171 (changed_rows), .github/scripts/adopted_wheel_copy_check.py:195-215 (git_wheel_copy_drift fails closed), .github/scripts/adopted_wheel_copy_check.py:218-246 (check_bases), .github/scripts/adopted_wheel_copy_check.py:259-292 (main), .github/workflows/pr-hygiene.yml:12-17 and 253-275, docs/system-specs/modules/app-kit-platform.md:7304-7320

@bolichen97
bolichen97 merged commit 94d0c32 into main Nov 15, 2026
154 of 156 checks passed
@bolichen97
bolichen97 deleted the feat/w7-pin-drift-guard branch November 15, 2026 02:50
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026

@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.

Reviewed head 84be922. The new pin drift guard runs the related tests green, and the new tests fail when the script is reverted. I also replayed the guard on real history: a pin row whose named base comes before the app's latest wheel-copy change is held, an up-to-date base passes, and an unknown commit or a missing base line fails closed. Only hex commit ids from the body reach git, paths come after the separator, and the script is still read from the base ref, so a branch cannot weaken its own check. The re-run-before-approving limit is documented and is a design choice, not a defect, so nothing blocks.

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