Require independent review and codify agent workflow safeguards

[mchwang]

Summary

• require a clean independent-agent full-diff review before every Copilot review request or re-request
• make review evidence exact-base/head scoped and invalidate it after any change
• codify task resumption, ownership, validation-evidence, external-status, stacked-PR, and instruction-synchronization rules
• mirror the shared operating rules in AGENTS.md and CLAUDE.md

Validation

• git diff --check origin/main...HEAD
• committed Review readiness sections match textually
• committed workflow blocks from Task resumption and ownership through Instruction synchronization match textually
• documentation-only change; no product tests run

Review record

Self-review 1

• reviewer: author
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• findings: none
• changed: none
• declined: none
• regression evidence: mirrored-section checks and git diff --check pass

Independent-agent review 1 (clean; authorizes first Copilot request)

• reviewer: separate read-only review agent
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• findings: none
• changed: none
• declined hypotheses:
  • separator blank line before the following AGENTS.md section is a formatting boundary, not divergent rule text
  • the new repository-specific mandatory docs-review rule intentionally supersedes the broader prior preference to skip independent review for small documentation changes
  • CI need not be green before a Copilot request; the rule requires its current state to be reported
• regression evidence: full current diff reviewed; mirrored blocks match; git diff --check passes

Pre-Copilot request status (round 1)

• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• CI at request: push-triggered test passed; PR-triggered test in progress
• mergeability: MERGEABLE; merge state UNSTABLE because CI was pending
• unresolved review threads: 0
• deferred follow-up issues: none
• latest clean independent-agent review: round 1 on the same exact base/head pair

Copilot review round 1

• reviewer: copilot-pull-request-reviewer
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• finding: the durable PR record omitted CI, mergeability and unresolved-thread status before the request
• changed: added the complete pre-request status packet above; no repository files or commits changed
• declined: none
• regression evidence: PR body read-back includes every status field required by Review readiness

Review-lesson classification

• Copilot round 1 finding: covered by the new Review readiness rule requiring current head, CI state, mergeability, unresolved threads, deferred follow-ups and the latest exact-pair independent review before each Copilot request; no additional rule is needed
• independent-agent round 1: no findings to classify

Deferred follow-ups

• none

Independent-agent review 2 (not authorizing a Copilot re-request)

• reviewer: separate read-only review agent
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• repository-file findings: none after full three-dot PR-diff and synthetic-merge verification
• process observation: at review time, the valid Copilot thread had not yet been replied to or resolved
• changed afterward: replied with the durable-record remediation and resolved the thread; no repository files or commits changed
• declined hypothesis: a two-tip comparison initially appeared to reverse PR Mark H4b issue trust work complete #141 architecture updates; withdrawn because the GitHub three-dot PR diff contains only AGENTS.md and CLAUDE.md, and synthetic merge tree 0d4726148abe07b8e004504de6da8463da19c19a preserves both Mark H4b issue trust work complete #141 files byte-for-byte
• regression evidence: git diff origin/main...HEAD, gh pr diff 142 --name-only, synthetic merge-tree comparison, PR-body read-back, and unresolved-thread count

Review-lesson classification addendum

• independent round 2 unresolved-thread observation: covered by the standing review-loop rule requiring a reply and resolution for each valid thread
• independent round 2 two-dot comparison hypothesis: one-off reviewer command-selection error; recorded here because it was withdrawn after three-way merge reproduction and requires no repository rule
• a clean independent round after the thread resolution is still required before another Copilot request

Independent-agent review 3 (clean; authorizes Copilot request round 2)

• reviewer: separate read-only review agent
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• findings: none
• changed: none
• declined hypotheses:
  • two-tip documentation differences are not PR changes; three-dot diff and synthetic merge preserve PR Mark H4b issue trust work complete #141
  • PR-body-only evidence updates do not change the repository base/head pair
  • Copilot round 1 remains correctly recorded as a finding round rather than relabeled clean
• regression evidence: full three-dot diff reviewed; git diff --check passes; both CI runs green; thread reply/resolution and lesson classifications verified

Pre-Copilot request status (round 2)

• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• CI: both test runs completed successfully
• mergeability: MERGEABLE; merge state CLEAN
• unresolved review threads: 0
• deferred follow-up issues: none
• latest clean independent-agent review: round 3 on the same exact base/head pair

Copilot review round 2 (clean)

• reviewer: copilot-pull-request-reviewer
• exact base/head: 017cafef7d7aa3d40de73eb3dad9ac98bc70bbc5 / 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• findings: none; approval recommended with 0 open findings
• changed: none after this review
• declined: none
• regression evidence: Copilot reports the round-1 finding resolved; the only review thread remains resolved

Final validation

• validated head: 5acf8c0cbfc866d55c1c707ba47ffffd32b2d513
• CI typecheck: passed
• current non-Docker suite: 69 test files, 1,828 tests passed
• current browser suite: 81 tests passed
• required CI checks: 2 of 2 successful
• documentation checks: git diff --check and mirrored-section comparisons passed
• mergeability: MERGEABLE; merge state CLEAN
• unresolved review threads: 0

Final review-lesson audit

• Copilot round 1 missing-status finding: covered by the Review readiness pre-request status rule added in this reviewed head
• independent round 2 unresolved-thread observation: covered by the standing review-loop reply-and-resolve rule
• independent round 2 two-dot comparison hypothesis: one-off command-selection error, withdrawn after three-dot diff and synthetic-merge evidence; no new rule warranted
• self-review 1, independent rounds 1 and 3, and Copilot round 2 produced no findings
• all valid findings are resolved and classified; no additional AGENTS.md update or follow-up issue is required

[Copilot]

🟡 Changes recommended

The review request omits required CI, mergeability, and unresolved-thread status.

1 open finding

• Missing CI, mergeability, and unresolved-thread status · New

What changed in this PR

Codifies stricter review and workflow safeguards across repository agent instructions.

Changes:

• Requires clean, exact-head independent reviews before Copilot review.
• Adds workflow, validation, status, and stacked-PR safeguards.
• Keeps shared instructions textually synchronized.

File	Description
AGENTS.md	Expands repository-wide agent workflow rules.
CLAUDE.md	Mirrors the shared operating rules.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The documentation changes are consistent, complete, and textually synchronized.

0 open findings

1 resolved since last review

• Missing CI, mergeability, and unresolved-thread status

🧠 Review effort: Balanced