Skip to content

docs: align governance plan with accepted design v1.4 - #2701

Merged
codeforester merged 2 commits into
mainfrom
documentation/2700-20261121-align-the-governance-plan-and-design-header-with-accepted-de
Nov 21, 2026
Merged

codeforester merged 2 commits into
mainfrom
documentation/2700-20261121-align-the-governance-plan-and-design-header-with-accepted-de

Conversation

@codeforester

Copy link
Copy Markdown
Collaborator

Summary

Fixes #2700

Validation

  • git diff --check — passed.
  • pytest -q tests/test_documentation_links.py — 1 passed.
  • AC 6 stale-phrase search in both files — no matches.
  • Diff reviewed: only the scoped lines in docs/governance/IMPLEMENTATION-PLAN.md and docs/governance/DESIGN.md changed.

@codeforester codeforester left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Review round 1 at ffa95d78

Verdict: Changes needed at ffa95d7

Provenance: author Codex; reviewer Claude Code (Opus 5.5, claude-opus-5-5), in a session with no Codex context. I checked the single commit (+17 −16 in the two scoped files) against #2700's Expected behavior and acceptance criteria, and every cited design section at this head.

Verified

  • AC 1 (design header): L3, L5 and the last sentence of §0 changed as specified. No other DESIGN.md line changed.
  • AC 2 (plan header):
    • version 4.3, 21 November 2026;
    • the Companion line names v1.4, accepted through PR #2699;
    • the introduction and the Plan-review issues line record #2695/#2696 and #2700.
  • AC 3 (citations): each cited section says what the plan attributes to it, except the escalation part of L21 (F1).
    • L19 → §5.2;
    • L21 → §§8.5 and 8.6;
    • L23 → §§13.3 and 14.3, plus §6.1 for reviewer independence;
    • §7.2 step 3 → §8.5;
    • §7.2 step 5 → §14.6 (Stage 1 review mode) and Appendix E 21.
  • Removed restatements: the rewritten L21 and L23 no longer restate several rules, and the cited sections cover each one. This follows the issue's approach of citing the design rather than restating it.
    • full-head-SHA verdicts, fresh review after a push, and the base-only exception: §8.5;
    • the different-tool defaults and no same-tool fallback: §6.1;
    • verdict provenance: §13.3.
  • AC 4 (§10):
    • the Dependabot item is gone;
    • the view item points to §10.3's PROPOSED method with scratch-Project verification;
    • the #2555 item points to O14 in §21.
  • AC 5: the Step 3 completion note is present, and the brief is untouched.
  • AC 6: none of the five stale phrases appears in either file.
  • #2665 running list: marks Step 3 complete, adds #2700/#2701, and adds both Step 7 items.
  • Hosted checks at this head: 20 passed, 3 pending (Moving provider source-checkout suite, BATS tests, Ubuntu source-checkout suite), 1 skipped (Hosted release-train readback), 0 failing.

Remaining

  1. F1 (inline, L21): escalation is cited to §8.5, which covers only disputes. Restore the unchanged sentence.

Outside this PR's contract

I swept the whole plan and found more lines that v1.4 superseded but #2700's table missed. That was my miss as the issue's author. It isn't a defect in this PR, which implements the approved scope exactly; Expected behavior 5 rules out other edits.

  • L277: "Design v1.4 must decide whether to exempt Dependabot's generated python:uv label…". §10.3 and Appendix E 21 decided this. After this PR removes the §10 item, the plan treats it as both decided and pending.
  • L186 and L316 (#2673 row): "implement the writer decided in design v1.4". v1.4 defers post-reconciler writer ownership to O15. L186 also says:
    • "unless the reviewed v1.4 design proves their contracts equivalent", though the number of ledgers is open as O14;
    • "while author and reviewer share one account", though from Stage 1 only the author agent and maintainer share codeforester (§14.3).
  • L123 and L260: still cite "the accepted v1.3 design" and "the accepted v1.3 document contract".
  • L134: "unless the v1.4 design amendment explicitly adopts it", though v1.4 didn't adopt it.

Widening #2700's scope would return it to Triage under §5.4, so Ramesh decides between widening #2700 and a follow-up issue.

Round 2 checks F1 and the final hosted checks.

Claude Code (Opus 5.5, claude-opus-5-5), reviewing from Ramesh's account at Ramesh's request.

Comment thread docs/governance/IMPLEMENTATION-PLAN.md Resolved

@codeforester codeforester left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Review round 2 at d29c9288

Verdict: Approved at d29c928

Provenance: author Codex; reviewer Claude Code (Opus 5.5, claude-opus-5-5), in a session with no Codex context.

  • F1: fixed. The only commit since ffa95d78 changes one line in docs/governance/IMPLEMENTATION-PLAN.md:
    • it restores "Disputes, unavailable required reviewers, and unresolved findings at the limit go to the maintainer" word for word from main;
    • it narrows the §8.5 pointer to finding responses, verification, thread resolution and freshness, which §8.5 does cover.
  • Thread: I replied Fixed at d29c9288ad33cf00d5b2ed34e8444110800b3c57 in F1's thread. Under DESIGN §8.5, the author agent resolves it now.
  • Acceptance criteria: AC 1–6 still hold at this head. The fix touches no other line, and none of the AC 6 phrases has returned.
  • Hosted checks at this head: 24 passed, Hosted release-train readback skipped, none failing.
  • Outside this PR: Ramesh decided the six other plan lines that v1.4 superseded (listed in round 1) go to a separate follow-up issue, not #2700.

Merging is Ramesh's decision. Before merging, confirm Codex has resolved the F1 thread (§8.6 manual gate).

Claude Code (Opus 5.5, claude-opus-5-5), reviewing from Ramesh's account at Ramesh's request.

@codeforester
codeforester merged commit 6bdec49 into main Nov 21, 2026
25 checks passed
@codeforester
codeforester deleted the documentation/2700-20261121-align-the-governance-plan-and-design-header-with-accepted-de branch November 21, 2026 18:13
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.

Align the governance plan and design header with accepted design v1.4

1 participant