Repository navigation
ci: require every PR to reference a triaged issue - #16241
Conversation
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The bootstrap skip only helps this PR's own unenrolled run, is dead after merge, and duplicates the Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: make every PR trace to an issue that triage has already reached a verdict on, enforced by CI (ADDITION).
[FIRST-PRINCIPLES-REVIEWED] bb7b146 Description read[DESCRIPTION-READ] 551637e8e5dd61fbb6af6ee196503ed9be0d2221dc5cd3738948e331b46085eb That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The description is cut off inside Watch
[DESIGN-REVIEWED] bb7b146 Description read[DESCRIPTION-READ] a1ce96db53f672fe4241fbfa27df9ab5d85fd75c9038183d96dd38a2e3685d5f 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
ef8ad7d to
df71a3b
Compare
|
|
|
|
|
|
|
|
|
|
df71a3b to
c1e32b5
Compare
|
|
|
|
|
|
|
Nothing stopped a feature or fix from being built on impulse, reviewed on its own terms and merged with no record of why it exists or whether triage agreed it should. Issues already carry that record (needs-triage in, one verdict label out, written by the maintainer-operated Kiro Crew auto-pipeline); PRs never consulted it. Add issue-gate.yml as a PR Readiness lane: the visible PR body must declare an issue of this repository with a GitHub closing trailer, read through .github/scripts/issue_gate_refs.py -- an adapter onto the prepare-pr pr_status.py grammar, so the gate and the local NOTICE always agree -- and every declared issue must be a real issue, not closed as not planned, free of needs-triage and carrying a triage verdict label. Bot authors are skipped with a notice; a maintainer-applied `issue-gate: waived` label (production fire, release PR) waives the rule with a warning. Reads fail closed under the runner's default bash -e; edited/labeled re-run the check without a push. pr-readiness.yml enrols the lane, since PR Readiness is the one required status. Document the gate in docs/ci/ci-and-reviews.md (naming the system that writes the verdict labels and the shared grammar), add the issue-first step to CONTRIBUTING, name the waiver on the release version-drop PR, and stop prepare-pr calling the issue link advisory. Closes #16064
99e5c40 to
bb7b146
Compare
|
|
|
|
|
|
|
PR Readiness reads main's lane list, which waits on an Issue Gate check. Issue Gate is a pull_request workflow, so GitHub reads it from the PR's merge ref, and release/0.8.0 has no issue-gate.yml. Every PR into the release branch therefore waits on a check that never starts. Copy .github/workflows/issue-gate.yml from main unchanged. Its grammar script is read from a checkout of the default branch at run time, so the workflow file is the only piece the release branch needs. Source: origin/main 2359397 (file last changed there in #16740; introduced by #16241, #16634, #16697). Fixes #16868
Problem / Motivation
Goal: Every pull request traces to an issue that triage has already read, enforced by CI rather than by habit.
Nothing stops a fix from being built on impulse and merged with no record of why it exists or whether triage agreed. Issues carry that record (
needs-triagein, one verdict label out), but no PR check consults it. #15731 and #15741 solving the same Welcome-screen problem two ways, each without an issue, is the shape this prevents.Why it matters
Without the gate, "someone agreed to this work" is unverifiable at review time, and AI-lane and human rounds go to PRs whose premise was never triaged. With it, such a PR is red before anyone reads the diff, and the fix is a one-line body edit, not a push.
Not a goal
needs-triagepast the 24h expectation; the triage pipeline runs outside.github/and the overdue sweep is filed as ci: alarm in-repo when an issue sits in needs-triage past 24h #16308.issue-triage.ymlor to the auto-pipeline that writes the verdict labels.merge_grouprun:PR Readinessis the one required status.What changed (motivation → approach → change)
Goal → a deterministic readiness lane that reads the PR body with the repository's issue-reference grammar and the referenced issues' labels →
.github/workflows/issue-gate.yml+.github/scripts/issue_gate_refs.py:issue_gate_refs.py, an adapter onto the grammarprepare-pr/scripts/pr_status.pyexports as its one public entry point,declared_issue_numbers(body, repo). The reading: a line that starts (<=3 columns, optional bullet) with a closing verb (Closes/Fixes/Resolves) or a non-closingRefs/Part of, plus#N/OWNER/REPO#N/ a github.com issue URL, after HTML comments, fenced blocks (unclosed ones through end of body) and inline code are masked; every reference on that line counts and the rest is free (Fixes #123 (the Windows half)). Template hints,>-quoted or inline-code examples, four-column code lines, mid-sentence mentions and bare#Ndo not count. Only this repository counts; URLs only on github.com (a rule inside the grammar; the adapter adds nothing).pr_status.py's NOTICE path answers a different question (why the host resolved no closure) with its own whole-line, closing-only classifier, and no longer accepts ano linked issue:opt-out the gate would reject. The three verdict-label names are pinned byTestLabelContract. More than 20 distinct declared issues is a finding, not 20+ API reads.base.sha, since a stacked PR's base may predate the gate) and runs the adapter from there, so a PR cannot rewrite the grammar that judges it; nothing from the PR's tree is executed. Bootstrap: a default branch without the script (before this merges) is skipped with a notice, never filled by running PR code.not_planned, free ofneeds-triage, carrying one ofauto-fixable,needs-investigation,needs-human. One bad reference fails the PR; the job summary lists each problem and how to go green (once triage lands, any body edit re-runs the check -- the fork-author path).dependabot[bot]author (notice;github-actions[bot]is not exempted because this repository leaves "Allow GitHub Actions to create and approve pull requests" off); the maintainer-appliedissue-gate: waivedlabel (warning), for a production fire or a release PR.bash -e; every verdict-bearing exit status goes throughif.pr-readiness.ymlgainsissue-gate.yml|Issue Gatein its lane specs (besideCode Review: both run onpull_requestwith no base filter and a read token, so forks and stacked PRs included), inMONITORED_LANESand in itsworkflow_runlist. That is what makes a red here red the PR; the branch ruleset requires onlyPR Readiness.opened / synchronize / reopened / edited / labeled / unlabeled; body read from the API at run time;ubuntu-latest.Docs in the same commit: new
issue-gate.ymlsection + Shape-tree entry + lane rosters indocs/ci/ci-and-reviews.md(names the maintainer-operated Kiro Crew auto-pipeline as the writer of the verdict labels, the enrolment path, the shared grammar and what a stall looks like);CONTRIBUTING.mdgains the "Start from an issue" step and saysCloses #Ncloses on merge whilePart of #Nleaves the issue open;docs/build/release.mdnames the waiver label for the version-drop PR;prepare-pr/SKILL.mdno longer calls the issue link "advisory, not a gate";pr_status.pygains the publicdeclared_issue_numbers()(4 tests; theno linked issue:opt-out and its tests are gone).Backwards compatibility
Breaking: a PR whose body declares no triaged issue reds
PR Readinessonce this merges. Who watches for a stall of the label writer until #16308's overdue sweep lands: the maintainer who operates the auto-pipeline; the symptom is loud (every new PR red onIssue Gatenamingneeds-triage); the per-PR fallback is theissue-gate: waivedlabel; and if the pipeline is down past the 24h triage expectation, that same maintainer turns the gate off by deleting theissue-gate.yml|Issue Gateline from the lane specs inpr-readiness.yml(one-line PR, waived) until it is back. Writer sweep on origin/main @ 0777838 (grep -rn 'gh pr create' .github/workflows/): humans, theprepare-prskill (updated here), and three scheduled workflows --test-durations.yml:171,add-contributor.yml:381,memory-benchmark.yml:337-- whosegh pr createis refused in this repository, so a maintainer opens the PR from the compare link; each generated body and each compare-link notice now carriesPart of #16362(the standing tracking issue for workflow-generated PRs). The waiver label does not serve those PRs: it is the logged exception for a fire or a release PR, and a weekly PR that takes it would make the exception routine, whilePart of #16362is the rule itself (the work those PRs are for) with nothing to bypass.dependabot.yml-generated PRs are exempt in the workflow; the release version-drop PR uses the waiver label (docs/build/release.md).deferred-findingissues filed from accept-and-defer dispositions must now also carryneeds-triage(prepare-pr deferral contract) so the pipeline's intake sees them. Open PRs at merge time need aCloses #N/Part of #Nline added to their body (an edit, no push). Theno linked issue: <why>opt-out thatpr_status.pyused to accept is removed: a line the gate rejects cannot silence the local NOTICE.Reader:
src/kiro_crew/apps/builtins/auto_improvement/profiles/github_repo/pr_recipe.py:draft-- app -- posts an agent-written draft PR body to whichever repository the operator points it at; here that draft is red until it declares the issue the improvement is for, the same rule every author meets, so the recipe is not changed.Nothing else is removed or renamed: no label, workflow, path or public function.
Tests
test/test_issue_gate_refs.py(new, 45 cases) pins the adapter to the reference grammar on the shapes that have fooled a grep: template HTML-comment hint, unclosed fence, fence closed by a longer run, inline code,Related to/see/Addresses/ bare#N,Discloses/Unfixed/prefixes(also in the free tail of a declaring line:unresolved: #2), the non-closingRefs/Part ofcounting without closing, another repository'sowner/repo#Nand URL, a URL on a non-github.com host (andgithub.com.evil.example); the pinned verdict/pending label names (TestLabelContract); the line-start reading (Fixes #123 (the Windows half)and every reference on a declaring line count; a>-quoted line, a four-column nested list item and a mid-sentence mention do not); plus the CLI contract (one number per line, exit 0 on no declaration, 3 on an impossible number, 4 above the 20-issue ceiling, 2 on usage).run:block executed locally underbash -e(the runner's default) against a stubbedgh apiand the real grammar script, ten cases: template comment + inline code +Discloses+Refs+Part of+kirodotdev/KiroCrew#100in prose → red "declares no issue"; unclosed fence → red;Closes #100→ green;Fixes kirodotdev/KiroCrew#100+ issue URL +Closes other/repo#5→ green on fix: run app-install copytree off the event loop and stop following symlinks #100 only;Fixes #101withneeds-triage→ red naming the label; mixed body naming a PR, a not-planned issue and a non-existent number → red listing all three (the 404 branch runs under-e); impossible number → red "malformed"; three 502s → red naming the read;dependabot[bot]→ notice, green;issue-gate: waived→ warning, green.Frontend Tests (1)/(2)are red on this PR's rounds 1 and 2 onhoverVariantPolicy.test.ts(WelcomeViewDECORATIVEentry names a class fix(chat): keep floating composer chrome off the transcript and hero #15820 removed) andSessionActionsMenu.duplicate.test.tsx, both last touched by fix(website): gate hover so iOS taps land on the first try #14807 onmain; this diff touches nowebsite/file.Frontend Coverage MergeandCoverage Gateare red behind them.test/test_pr_readiness_evaluate.py+test/test_pr_readiness_publish.py(the readiness step scripts with the new lane),test/test_ai_review_workflows.py,test/test_ci_fleet_routing_expression_parity.py,test/test_prepare_pr_status.pygreen locally (1558 passed);scripts/docs-lint.sh, black/isort/flake8/mypy on the touched Python green.Closes #999examples in this body); the shared grammar is what replaced that grep.Manual verification
This PR's own body declares
Closes #16064, triagedneeds-human; round 3 (merge-ref grammar) passed on it. From round 4 the grammar is read from the default branch, which has none yet, so the gate reports the bootstrap notice on this PR and starts enforcing on the first PR opened after merge. Readiness enrolment is in the diff; no post-merge branch-protection step is needed.Related Issues
Closes #16064
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Maintainer follow-up after merge
issue-gate: waivedlabel (the gate reads it; absence is harmless).