From 7efc32fc5a9b7ff637c13da8331437e2ff283f60 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 17:32:23 +0900 Subject: [PATCH] docs(agents): record PR-supersession and constant-change review discipline Two rules from mistakes this session actually made and corrected, per the per-session lane split agreed with the other concurrent sessions (peer 3 took verification discipline in #1907; peer 2 has gate/merge mechanics; host 1 has close-time diff comparison and noema concurrency; host 2 has CI failure diagnosis). - Narrowing a PR does not carry its delta. #1871 was closed in favor of #1877 plus #1879; both successors were green, but neither carried the coverage/docstring delta, leaving main's required 100% gate broken until #1883 recovered it. "Each piece works" and "the pieces together cover the original's scope" are different questions. - Compare content, not ancestry. main mixes squash and merge commits (last 200: 153 single-parent, 47 two-parent, counted directly), so `git merge-base --is-ancestor` gives false negatives for squashed deltas and false positives for reverted merge-commit deltas. - Never endorse a timeout or retry constant on a model-invocation path without reading docs/product-goal-directive.md section 8, which accepts more than two hours per model and states speed is not a core consideration. #1889/#1890/#1892 each capped a model step at 900s on real multi-hour-hang evidence and were all reverted (#1891, #1895). Every PR number, the section-8 quotes, the parent-count distribution, and the 100% gate values were verified against the repository directly. An earlier draft of the timeout bullet cited a section number that does not exist and attributed a sentence to that file which appears only in #1891's PR body; both were caught by grepping rather than trusting the summary that introduced them, and that failure is recorded in the text. Full suite: 2883 passed, 1 skipped. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 37 +++++++++++++++++++++++++++++++++++++ CLAUDE.md | 12 ++++++++++++ 2 files changed, 49 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 881e3aabf5..c32fd96961 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,3 +99,40 @@ history, never the organization's actual state. conclusions.** Sessions here share a model and tend to share blind spots. A read-only `codex exec -s read-only -C ""` pass has already caught a factual error in this very section that same-family review missed. +## Supersession and constant-change review + +- When a large PR is narrowed into successors, verify the **union** of those + successors against the original's full diff — not merely that each successor's + own tests pass. `#1871` was closed in favor of `#1877` plus `#1879`; both + successors were green, but neither carried `#1871`'s coverage/docstring delta, + so the required 100% gate stayed broken on `main` until `#1883` recovered it. + "Each piece works" and "the pieces together still cover the original's scope" + are different questions, and only the second one needs a diff against the + original. +- A closure or narrowing is not self-verifying, and neither is a note recording + it. Before treating a supersession as complete, re-run the gate the original + PR existed to fix and confirm it passes on `main` itself from a fresh clone. +- Compare **content**, never ancestry. `main` here mixes squash and merge commits + (over the last 200 commits: 153 single-parent, 47 two-parent), so + `git merge-base --is-ancestor origin/main` is unreliable in *both* + directions: a squashed delta is fully merged yet reports false, while a delta + that arrived via a merge commit and was later reverted still reports true. Use + `git diff ...` against the original, or grep the successor set + for the original's files and symbols. +- Never endorse a timeout, retry budget, or other numeric constant on a + model-invocation path without first reading + [`docs/product-goal-directive.md`](docs/product-goal-directive.md) section 8, + which states that central OpenCode, Strix, and Noema accept taking more than two + hours per model ("중앙 OpenCode, Strix, Noema는 모델당 두 시간 이상 걸릴 수 있음을 + 수용한다") and that speed is not a core consideration, accuracy is + ("속도는 핵심 고려사항이 아니며 정확성을 우선한다"). `#1889`, `#1890`, and `#1892` + each capped a model step at 900 seconds on real evidence of a multi-hour hang, + and all three were reverted (`#1891`, `#1895`). Compelling hang evidence does not + exempt a change from that contract: runner occupancy is repaired at the + admission/continuation boundary or by an explicit provider terminal signal, never + by converting elapsed inference time into a model-failure verdict. +- Verify a citation before you rely on it, including your own. The first draft of + the bullet above cited a section number that does not exist in that file and + attributed a "timeout defaults to null" sentence to it that appears only in + `#1891`'s PR body — both caught by grepping the file instead of trusting the + summary that introduced them. diff --git a/CLAUDE.md b/CLAUDE.md index 550ad5ce80..5c8cdead6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -157,6 +157,18 @@ repeatable compile command. required workflow; skip at job level via a `changed-scope` gate job instead, and always keep one job with no output-dependent `if:` so the run concludes `success` rather than `skipped`. See `docs/doctoring/required-workflow-path-filter-boundary.md`. +- **Narrowing a PR does not carry its delta automatically.** When a large PR is split into + successors, diff the union of the successors against the original before treating the supersession + as complete — each successor passing its own tests does not prove the union still covers the + original's scope. `#1871` → `#1877` + `#1879` silently dropped the coverage/docstring delta and + left the required gate broken on `main` until `#1883`. See AGENTS.md's "Supersession and + constant-change review". +- **Model-path timeouts are policy-fixed, not an engineering judgment call.** `docs/product-goal-directive.md` + section 8 accepts that central OpenCode/Strix/Noema may take more than two hours per model and states + that speed is not a core consideration. `#1889`/`#1890`/`#1892` each added a 900-second cap on genuine + multi-hour-hang evidence and were all reverted (`#1891`, `#1895`). Fix runner occupancy at the + admission/continuation boundary instead; never convert elapsed inference time into a model-failure + verdict. - **Org-wide binding conventions** (permissive licenses only — verify SPDX before adding anything; cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and