Skip to content

P0: Commit a Stop Condition and Round Budget for the Whole-Unit and Local Review Passes #1312

Description

@ptr727

Part of #1311. Priority: now. One pull request.

Rescoped 2026-09-04 after the first attempt, parked unmerged on feature/review-stop-condition and assessed in this #1311 comment and the re-assessment that follows it. That branch wrote the stop rule as roughly 1,200 words of new contract prose across two units and did not converge in twelve rounds. It is superseded by the scope below, is not merged or rebased, and is deleted once this issue's pull request merges.

Why

The whole-unit canonical pass and the local strict review pass have no committed stop condition, so the loop runs until an agent decides on its own to stop, and #1267 measured that it does not converge: PR #1198 ran eight fix-and-re-read rounds where nearly every round's findings were introduced by the previous round's fix. The rule's home is local-strict-review "Disposing of Findings", which is one fourteen-sentence paragraph carrying 40 of #1327's 77 pre-existing findings, so landing the rule beside that paragraph leaves in place the text it contradicts. This issue is therefore also #1311's deletion pilot: the paragraph is rewritten by deletion into a normative block, with the stop rule inside it, and the rewrite is measured.

Scope

  • local-strict-review "Disposing of Findings": replace the paragraph with a short normative block. Each rule is one bold statement of at most two sentences, followed by a marked non-normative "Why:" line. Content, and nothing beyond it:
    • Findings map to pr-review-conduct's five outcomes by pointer, not re-enumerated.
    • Each finding carries a class. introduced: the change wrote, rewrote, or removed the text, or the text should have been written, plus the two carve-outs from The whole-unit review loop has no committed stop condition, so it does not converge #1267, a finding load-bearing for a maintainer decision this change puts, and one showing the change's own edit left a precondition elsewhere false. pre-existing: anything else on text the change did not write. style: a preference between two defensible wordings.
    • The pass closes on one question: does content this change wrote still carry a false or contradictory claim, an instruction that fails when followed literally, or wrong behavior. Introduced is fixed. Pre-existing is filed once and blocks nothing. Style on text already rewritten twice takes the shortest defensible wording and stops.
    • The budget: two rounds of edits per push over the same content, then the remainder goes to the maintainer with its class counts.
    • One sentence keeping the pass mandatory and its findings advisory.
  • local-strict-review "Running It": the Return: line gains the class, and the brief gains one line: for every rule the diff adds or changes, grep the canonical tree for other statements of it and report each that now disagrees.
  • GOVERNANCE.md "Verification Discipline": one bullet of at most three sentences. The stop question is the rule. The class, the bound, and the report line are the Skill's, and the bullet does not restate them.
  • pr-review-conduct "Never exit the loop early": one clause scoping that rule to the PR-hosted loop and naming local-strict-review as the home of the pre-push bound.
  • backlog-burndown: not touched. Its shape is P2 (decision): Decide backlog-burndown's Shape Before Its 23 Open Defects Are Worked One at a Time #1323's decision, and the pointer replacement for its "set a review-round budget" bullet is filed there.

Rules that bind this task

  • The rule text lives in GOVERNANCE.md and the procedure in the Skill. Neither restates the other.
  • The pass stays mandatory and its findings stay advisory. This task changes when the loop ends, not whether it runs.
  • The pilot runs under the rule it writes, from the first round: the stop question and the two-round budget go into every reviewer brief at spawn.
  • The measurement is at most six passes: three whole reads of the rewritten unit plus one diff pass carrying the sweep line, each record carrying --findings, findings classed per round. If the unit has not converged inside that budget, stop, and that is the result.
  • Regenerate the skill mirrors with python3 scripts/build_dist.py, never by hand.

Acceptance

Closes #1267. Relates #1104, #1283, #1327.

Activity

  1. ptr727 commented on Sep 4, 2026

    @ptr727
    OwnerAuthor

    Written and parked unmerged on feature/review-stop-condition (2512fcd, 4f929d4),
    pushed, not opened as a pull request. Full analysis in #1311.

    What the branch contains

    • GOVERNANCE.md "Verification Discipline": one bullet stating what closes a pass, as a
      question about the change rather than a finding count, with the two carve-outs The whole-unit review loop has no committed stop condition, so it does not converge #1267
      names and the rule that a finding on text the change did not write is filed once and
      blocks nothing.
    • local-strict-review "Bounding the Rounds": separates the passes an edit owes, which
      are mechanical and unbounded because the engines refuse a digest no reviewer read, from
      the editing itself, which is bounded at one discretionary round plus three further
      edits, after which the work stops and the maintainer decides. Deletion is the preferred
      remedy. The diff pass's report contract gains a per-finding class, and the
      carried-content reviewer cannot classify its own findings because it is briefed to read
      the unit knowing nothing about the branch, so the dispatching session classes them.
    • backlog-burndown: the second statement of the budget becomes a pointer, and the
      promotion step keeps its own budget for the PR-hosted review loop.

    Why it is parked rather than merged

    The final full-diff review found the change introduces contradictions on four surfaces it
    did not sweep: an edit count becomes a stopping condition against pr-review-conduct's
    "Never exit the loop early"; filing becomes mandatory against the Skill's four
    dispositions, one of which files nothing; newly carried content is filed in one surface
    and fixable in the other; and "findings stay advisory" is narrowed in GOVERNANCE.md and
    left unswept in the Skill. Separately, the Return: line defines introduced as text the
    change touched, so a precondition the change left false in an unedited file comes back
    pre-existing and the push proceeds, which is the category the rule was added to catch.

    The three backlog-burndown edits also left that file worse than they found it, ending in
    a claim about an exception AGENTS.md does not contain.

    What it would take to land

    The four-surface sweep as one change, larger than this issue scoped. The measurement in
    #1311 argues for running the deletion pilot first instead, since a new rule in this corpus
    must agree with roughly four existing statements of its neighbours, and per-unit review is
    scoped to exactly the surface where those contradictions are not.

    #1267 stays open. The stop condition it asks for is written and reviewed, and what it
    does not have is a terminator that survives the per-push reset, which is recorded on the
    branch and in #1311.

    Pre-existing defects the passes found: #1327.

  2. ptr727 commented on Sep 4, 2026

    @ptr727
    OwnerAuthor

    Merged to develop as 4ee4669 (#1330). The curve, the re-plan it prompted, and the sequence going forward are on #1311, and the unit's open findings are items 79 to 87 on #1327. feature/review-stop-condition is deleted as this issue directed. #1267 closes when this promotes to main, since a Closes line on a develop pull request does not fire, and #1104 is answered by the every-push rule plus the two-round budget and is left for the maintainer to close or re-scope.

  3. added
    proseA defect in rule or procedure text
    on Sep 5, 2026
  4. ptr727 commented on Sep 15, 2026

    @ptr727
    OwnerAuthor

    Closing as done in substance: #1330 (merged to develop 2026-09-04) committed the stop rule and the two-round budget in the local-strict-review skill's "Disposing of Findings" without naming this issue, and a develop-targeted closing reference is inert. The remaining question this issue held, what the whole-unit pass owes per PR, is settled by the decision on #1631 (one local diff pass per push, the whole-unit pass moved to a scheduled sweep).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationproseA defect in rule or procedure textskillsAgent skill

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions