Skip to content

feat(prepare-pr): freeze a PR's goal sections at open - #14181

Merged
bolichen97 merged 1 commit into
mainfrom
feat/pr-intent-freeze
Sep 27, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/pr-intent-freeze

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A PR's stated goal stays fixed from the moment it opens, so the review loop judges every later change against that goal instead of against its own growth.

The prepare-pr loop rewrites the whole PR body every round to match the diff. Its intent lived in a separate <!-- prepare-pr-intent --> comment that many PRs never got. So each round the body's "why" drifted to describe whatever the loop had just added. Reviewers and the every-third-round retrospective then read that drifted text as the intent, and absorbed the loop's own mechanisms into it. PRs grew round after round with nothing left to measure the growth against.

Why it matters

Agent-driven PRs on this repo routinely run ten or more review rounds. Without a fixed goal, each round can widen the PR and still look "in scope", so maintainers get large diffs that no longer match what was asked for, and review cost keeps climbing.

Not a goal

  • An "Intent Lock" check or an /intent approve command that detects edits to the frozen sections. That lands in a later PR.
  • Changing the first-principles review lanes (first-principles-review.yml, fork-first-principles-review.yml).
  • Updating the maintainer-side auto-approval cron, which keeps its own copy of the required-section list outside this repository.
  • Back-filling the new sections into already-open PRs.

What changed (motivation → approach → change)

Every PR body now opens with a frozen goal: a one-sentence **Goal:** line, ## Why it matters and ## Not a goal. Agents never rewrite those three, the review loop measures the whole diff against them, and PR Hygiene blocks a PR that lacks them.

Design and decisions: docs/request-for-change/rfc-pr-goal-freeze.md (status in-progress, merged in #14265).

Part Change
.github/PULL_REQUEST_TEMPLATE.md Empty **Goal:** line under Problem / Motivation, new ## Not a goal, and a top note: the first three sections are frozen; everything from What changed down tracks the diff.
AGENTS.md "PR goal is frozen": agents never edit the three on their own; a finding outside the goal is rebutted or deferred, but a defect in code this PR adds or changes is always fixed.
.github/scripts/pr-description-check.sh One rule set: the required headings, now with ## Not a goal, plus a filled **Goal:** line under Problem / Motivation. The failure names the missing part and links the template on main.
PR Hygiene (code-review.yml) and fork-pr-description.yml Both run that script. PR Hygiene fails on it, which blocks PR Readiness for same-repo and fork PRs alike. docs/ci/ci-and-reviews.md lists it as PR Hygiene's fourth check.
prepare-pr skill The intent comment is gone; the three sections are the intent and are copied verbatim each round. The retrospective judges the full origin/<base>...HEAD diff against them and may rule "revert to <head sha> and redo via a smaller path". pr_findings.py --rounds prints the Goal line.

No same-repo required-headings check existed before. The fork check said so and left same-repo PRs unchecked. PR Hygiene was the closest same-repo check, so the rule joined it there rather than as a new workflow. The rules moved into a shared script so the two checks cannot drift. The fork workflow reads it through a sparse checkout of the base branch, never the fork.

Backwards compatibility

Breaking: PR Hygiene now fails any PR whose body lacks ## Not a goal or a filled **Goal:** line, and the fork check reports the same. Writer sweep on origin/main @ 67f79c3: the only in-repo PR-body writer is prepare-pr, which scaffolds from the template and is updated here. Every open PR body predates the change, so each fails on its next push or body edit. The fix is a body edit with no push, since PR Hygiene runs on edited. Dependabot PRs are skipped. The off-repo auto-approval cron still uses the old list, so a fork's runs may be approved while its description check is red; PR Hygiene still blocks it.

Tests

  • test/test_fork_pr_description_workflow.py runs the shared script for real: missing Goal line, empty scaffold, Goal in the wrong section, fenced or indented Goal, a subheading, and the shipped template failing until its Goal is filled. It also pins the base-only sparse checkout, the contents: read permission, and PR Hygiene running the same script for every PR.
  • test/test_prepare_pr_rounds_view.py checks --rounds prints the Goal line redacted, reads an empty or absent one as missing, and that the skill no longer names the intent comment.

Manual verification

N/A — unit coverage sufficient: the check logic is shell executed by the tests, and the skill change is prose pinned by its tests.

Related Issues

no linked issue: requested directly by the maintainer.

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

@iamwhatever
iamwhatever requested review from a team and buluoray September 26, 2026 08:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 6a77b5b65669eb70b19b1b503898f976bdf420c0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the fork lane post-merge: fork-pr-description.yml's new base checkout only runs on a real fork PR, and this PR says manual verification N/A.

Suggestions

  • pr_findings.py's GOAL_LINE_RE matches a **Goal:** anywhere in the body (any section, inside fences), unlike the shell scanner — reuse the section/fence discipline or note the looser contract, so the two readers of "the frozen goal" can't disagree.

[DESIGN-REVIEWED] 6a77b5b

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 6a77b5b65669eb70b19b1b503898f976bdf420c0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6a77b5b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6a77b5b65669eb70b19b1b503898f976bdf420c0: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 6a77b5b65669eb70b19b1b503898f976bdf420c0 — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

A memory-index owner-only change (memory.py, vector_memory.py, windows-install.md, a new test file) rides along undeclared — and base tip 4f35e56 (#14204) already ships it.

Not justified as shipped

  • Item 10 — duplicate of 4f35e5696 fix(memory): make the FTS index and its sidecars owner-only (#14204) on the base: the description's ## What changed table names five parts and none touches memory, yet the diff adds MemoryStore._restrict_index_files, the _index_owner_only latch, test/test_memory_index_owner_only.py and two doc edits — the exact change the base's tip commit merged as fix(memory): make the FTS index and its sidecars owner-only #14204. If it is byte-identical it nets to nothing at merge; if it has drifted, this PR silently rewrites a fix that landed through its own review.
    Subtraction: rebase onto current main so the four memory-side files drop out of this branch's diff entirely.
    Clears when: the rebased origin/main...HEAD diff no longer touches src/kiro_crew/memory.py, src/kiro_crew/vector_memory.py, docs/guides/windows-install.md or test/test_memory_index_owner_only.py.

Every product-shape item here (the same-repo blocking gate, the reversed "Fork-only by design" rule, the prepare-pr revert verdict, the cost imposed on open PRs) is covered by docs/request-for-change/rfc-pr-goal-freeze.md, in-progress on the base list, whose text names each one — decided, not relitigated. The rewritten pin in test_it_never_checks_out_fork_code (was: no uses steps at all) is declared in the description and replaced by a stricter exact-with assertion.

What this change ships

Inventory (10 items) — 9 justified

Intent: a PR's goal is written once at open and every later review round is judged against it — an ADDITION (new gate plus process change).

  1. PR template now opens with a frozen **Goal:** line, ## Not a goal, and a freeze note — justified
  2. Same-repo PRs are now blocked by PR Hygiene when the body lacks the required sections or a filled Goal line — justified
  3. The fork description check newly requires ## Not a goal and a filled Goal line — justified
  4. The description rules moved from inline workflow shell into one script both checks run — justified
  5. The fork workflow now checks out the base's copy of that script (contents: read added) — justified
  6. AGENTS.md rule: agents never edit the three frozen sections on their own — justified
  7. prepare-pr drops the <!-- prepare-pr-intent --> comment; the frozen sections are the intent, copied verbatim each round — justified
  8. The retrospective gains a "revert to <head sha> and redo" verdict — justified
  9. pr_findings.py --rounds prints the PR body's Goal line, redacted — justified
  10. The FTS memory index and sidecars are chmodded owner-only — undeclared, rides along, duplicate of base commit 4f35e56 (fix(memory): make the FTS index and its sidecars owner-only #14204)

[FIRST-PRINCIPLES-REVIEWED] 6a77b5b

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6a77b5b

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6a77b5b65669eb70b19b1b503898f976bdf420c0: <one-sentence reason>

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

Copy link
Copy Markdown
Contributor Author

self-added: no

  • fixed — fork checkout allowlist admits repository: span=b8f40594130c

Fixed in 2770bbe: the test now asserts the checkout's whole with mapping equals the base-only sparse checkout, so neither ref nor repository can be added without a red test.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • fixed — Backwards-compatibility exclusion assertion went vacuous span=994c2d39a5eb

Fixed in 2770bbe: the assertion now reads .github/scripts/pr-description-check.sh, where the required-section list lives.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 26, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • fixed — CI spec still lists three PR Hygiene checks span=16dc68ebc817

Fixed in 2770bbe: docs/ci/ci-and-reviews.md names the shared description check and says all four checks are blocking.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 26, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted — Goal line outside Problem / Motivation selected as frozen goal span=0041a66bcd4a

Not a defect in practice: --rounds prints the FIRST **Goal:** line, and the template puts it as the first line of the first section, so an earlier stray line needs an author to write one above the template.
The enforced rule lives in pr-description-check.sh, which is section- and fence-scoped; --rounds is a read-only display and a mismatch only shows a different sentence to the operator.
Scoping the display parser would duplicate the checker's section/fence scanner in Python; that cost is out of this PR's minimal goal.

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

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted — frozen sections are protected only by prose span=b69f36cfc794

Out of this PR's goal by design: the body's Not a goal lists the edit-detecting "Intent Lock" check as a later PR, and the maintainer who requested this PR scoped it that way.
This PR ships the contract (template, AGENTS.md, skill) and the presence gate; the comparison against the at-open body is the next PR stacked on this branch.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • needs-a-decision — new blocking PR Hygiene rule has no recorded maintainer decision span=c8069dad6f38

@iamwhatever: this PR makes PR Hygiene block every PR without ## Not a goal and a filled **Goal:** line (Breaking, see the body). You requested it; please record the decision with /ai-review override first-principles 2770bbe676e96dfcd6bc96fdf4743c93f7be4afd: <decision> or say if an RFC should land first.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted — headings or Goal inside an HTML comment count as present span=35b5d910b3fe

Not a new defect: the heading scan is the fork check's existing presence-only scanner, moved unchanged, and its stated limit is presence, not quality; an HTML-commented heading already passed on main.
Reaching it needs the author to write the sections inside a comment on purpose, which only games their own description gate; the template's own guidance lines are indented 5 spaces and the Goal scaffold is empty, so a verbatim template still fails.
Comment-block tracking would add parser machinery beyond this PR's minimal goal.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • rebutted — new required sections red every already-open PR on its next event span=dd53eec12443

Deliberate and declared: the maintainer asked for a BLOCKING rule, and the body's Backwards compatibility section records it as Breaking with this exact consequence.
The remedy costs no push: PR Hygiene runs on edited, so adding the two parts to the description re-runs the check; the failure names the missing part and links the template on main. Dependabot PRs are skipped.
A grandfathering date or flag would add a mechanism beyond this PR's minimal goal.

@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 Sep 26, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved (#14138 regenerated settingsRegistry.gen.ts, the cause of the inherited Frontend Tests reds) since this head was pushed (2770bbe -> c1283ed on 7b2da39); CI re-running.

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

Copy link
Copy Markdown
Contributor Author

self-added: no

  • needs-a-decision — every PR gated on the frozen goal, reversing fork-only span=1093177765fb

@iamwhatever: this is the product-shape change you requested; only a maintainer record clears it. Post /ai-review override first-principles c1283ed9dcbd4c9262a5b180991ca16ee83eb4f5: <decision>, or say if an RFC should land first.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no

  • needs-a-decision — prepare-pr intent comment replaced by frozen body sections span=de7fddb43dba

@iamwhatever: this is the product-shape change you requested; only a maintainer record clears it. Post /ai-review override first-principles c1283ed9dcbd4c9262a5b180991ca16ee83eb4f5: <decision>, or say if an RFC should land first.

Pearcekieser added a commit to Pearcekieser/KiroCrew that referenced this pull request Sep 27, 2026
kirodotdev#14181 left the skill at 68015 bytes, so test_slim_skills_do_not_regrow_duplicate_guidance_or_wire_model_ids fails on main. Drop the duplicate 'never edit the goal' clause; the frozen-goal paragraph already says only the user may edit it.
Pearcekieser added a commit to Pearcekieser/KiroCrew that referenced this pull request Sep 27, 2026
kirodotdev#14181 left the skill at 68015 bytes, so test_slim_skills_do_not_regrow_duplicate_guidance_or_wire_model_ids fails on main. Drop the duplicate 'never edit the goal' clause; the frozen-goal paragraph already says only the user may edit it.
iamwhatever pushed a commit that referenced this pull request Sep 27, 2026
…on (#14049)

* feat(session-control): session_create takes a model for the new session

spawn_run and spawn_continue already take a per-run model, but session_create
had no way to pick one, so a conductor opening worker sessions could not put
them on a different model than the default. Add an optional model argument:
held to the spawn_run model-id charset by the schema, refused with
model_rejected by the same guard the dashboard model picker runs, pinned on
the slot with the pick-generation bump a human pick gets, and recorded in the
persist-at-birth metadata so an idle child keeps it across a restart.

* fix(prepare-pr): trim SKILL.md back under its 68000-byte ceiling

#14181 left the skill at 68015 bytes, so test_slim_skills_do_not_regrow_duplicate_guidance_or_wire_model_ids fails on main. Drop the duplicate 'never edit the goal' clause; the frozen-goal paragraph already says only the user may edit it.
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.

2 participants