Repository navigation
feat(review): carry direction/baseline axes so the convergence floor can defer a Critical #10301
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
abe7f30
feat(review): carry a Critical's direction/baseline axes and let the …
wenshao 2f1d382
fix(review): read a Critical's axis tags from the claim head slot onl…
wenshao 42743a9
Merge branch 'main' into feat/review-critical-axes
wenshao 02197b3
Merge remote-tracking branch 'origin/main' into feat/review-critical-…
wenshao cbe83ba
fix(review): derive the head-slot axis grammar from the core lists an…
wenshao 0962953
test(review): pin that the deferrable axes never bypass the witness r…
wenshao File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| # Review: Critical direction/baseline axes and the convergence floor (#10291) | ||
|
|
||
| Date: 2026-08-27 | ||
| Issue: #10291 — `Critical` is one bit carrying three axes; add | ||
| direction/baseline fields so the convergence floor can actually floor. | ||
|
|
||
| ## Problem | ||
|
|
||
| The convergence posture (`floor: critical`, from round 6 or on the | ||
| flat-trend signal) is the review loop's only damper, and on #9659 it stopped | ||
| damping at round 17: new Criticals per round ran 7, 5, 3, 5, 4, 1, 6 over | ||
| rounds 17–23 with near-zero false positives. The floor could filter nothing | ||
| because the `Critical` class collapsed three orthogonal merge decisions into | ||
| one bit — which way the defect fails, what it is measured against, how often | ||
| it triggers. Of the ~25 findings the issue classified (31 new in all across | ||
| the seven rounds), about 6 certified falsely (a wrong result presented as | ||
| correct); the other ~19 were fail-closed corners on defenses | ||
| added in earlier rounds, most of them zero-regression against the merge base | ||
| (before the PR, a sparse checkout had no incremental review either). | ||
|
|
||
| ## Design | ||
|
|
||
| ### Two fields, one deferral shape | ||
|
|
||
| Findings gain two optional enum fields, stated by the Step 4 verifier off the | ||
| witness that confirmed the finding: | ||
|
|
||
| - `direction`: `certifies-falsely` (the code produces a wrong result it | ||
| presents as correct — a wrong output, a silent corruption, a bypassed | ||
| check, a decision over state nobody read) | `fails-closed` (refuses, | ||
| wedges, crashes or degrades to its own absence without a wrong result). | ||
| - `baseline`: `regression` (the merge base handles the trigger correctly; the | ||
| change breaks it — the A/B's base arm is correct) | `new-surface` (the | ||
| failing path does not exist at the merge base — the change adds the | ||
| feature, defense or branch the defect lives in). | ||
|
|
||
| At a floor resolved to `critical` (explicit, `auto` from round 6, or `auto` | ||
| with `flatRounds` at its bar), **a Critical that is `fails-closed` AND | ||
| `new-surface` is recorded, not requested** — a typed deferral like a | ||
| Suggestion's. Every other Critical posts: `certifies-falsely` at either | ||
| baseline, `regression` in either direction, and any Critical with a missing | ||
| or self-contradicting axis. The rounds-2–5 code-age rule never touches a | ||
| Critical. The issue's optional third axis (trigger frequency) is not | ||
| carried. | ||
|
|
||
| Replaying #9659 under the rule: the ~6 certification-direction findings | ||
| still block, the ~19 fail-closed corners route to follow-up, and the loop | ||
| plausibly settles around round 19 instead of 23. | ||
|
|
||
| ### Carriers | ||
|
|
||
| | Surface | Form | Reader | | ||
| | -------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | ||
| | Findings artifact (`qwen review findings`) | `direction` / `baseline` enums, refused when misspelled | report, `report_findings`, the compose state | | ||
| | `report_findings` tool (core) | same optional enums in the schema | TUI / Web Shell / ACP display (pass-through) | | ||
| | Drafted Critical comment | claim-line bracket tags `[fails-closed] [new-surface]` beside the id, copied from the artifact | `floorEnforcedReroute` (backstop), `buildLedger` (marker) — claim line only | | ||
| | Typed deferral entry (`deferredSuggestions`) | `severity: "Critical"` + both axes | `splitDeferralChannel` — deferred only when licensed | | ||
| | Ledger marker | `d: 'c' \| 'f'`, `b: 'r' \| 'n'` per finding; unknown values normalise to absent | next round's side-file work-list table (`Critical (fails-closed, new-surface)`), autofix tooling (#9907) | | ||
|
|
||
| ### The licence | ||
|
|
||
| The Critical split reads the ENFORCEMENT resolution of the floor | ||
| (`criticalFloorInEffect`), computed once per compose and threaded to the | ||
| ledger build, the body composer and the mechanism-health check. A Critical | ||
| entry arriving when the floor is not in effect is relocated into the body | ||
| Criticals and posts — the fail-toward-posting direction every arm of the | ||
| floor takes. A deferred Critical never caps, never withholds the anchor, | ||
| leaves the work list, and — on its first deferral — joins the closure mint | ||
| by the id its title carries, so the successor-chain sentinel does not read | ||
| it as a fix. A re-deferral bears an id the previous posted work list never | ||
| held, fails the mint's membership leg, and that round's mint fails closed | ||
| (absence never reads as a fix, at the cost of that round's true closures); | ||
| carrying the round's deferred ids in the marker would let a re-deferral | ||
| join by them and is left for a follow-up. | ||
|
|
||
| ### Trust boundaries | ||
|
|
||
| - Tags are read off the claim line's head slot only — the machine tokens | ||
| before the title, like `[probe]`: a title that merely quotes a tag is | ||
| prose, the body's tail is writable surface, and a forged pair in either | ||
| would otherwise defer a drafted Critical. | ||
| - An axis carrying both of its tags reads as unclassified — the backstop | ||
| never guesses a blocker out of the posting set. | ||
| - The marker fields decide nothing in code; a spelling this version does not | ||
| know is normalised away (like the stand-in flag `k`), never used to reject | ||
| the entry. | ||
| - The verifier is told to omit an axis its witness cannot settle. The | ||
| artifact and the typed channel refuse a misspelled axis rather than | ||
| silently reading it as absent (which would post a deferrable blocker | ||
| without anyone seeing the drop). | ||
|
|
||
| ### Disclosure | ||
|
|
||
| - The deferral list line names a deferred Critical and its tags: | ||
| `src/sparse.ts:12 — [review] Critical [fails-closed] [new-surface] …`. | ||
| - The deferral header adds why: "N Critical(s) among them are deferred by | ||
| their axes — fails-closed on new surface, …". Bilingual. | ||
| - The floor-enforcement note and `submit`'s stderr line count moved | ||
| Suggestions and moved Criticals separately. | ||
| - The verdict line says "N finding(s) deferred" (was "non-Critical | ||
| finding(s)"). | ||
| - The relocation note reads "a Critical is deferred only as fails-closed on | ||
| new surface at a critical floor; this one posts". | ||
|
|
||
| ## Implementation outline | ||
|
|
||
| 1. `core/tools/report-findings.ts`: `FINDING_DIRECTIONS`, `FINDING_BASELINES`, | ||
| schema fields, pass-through; `ReportedFinding` type; core exports. | ||
| 2. `cli/commands/review/findings.ts`: `DIRECTIONS`/`BASELINES`, `Finding` | ||
| fields, strict validation, round-trip, terminal render. | ||
| 3. `cli/commands/review/lib/ledger.ts`: `LedgerFinding.d`/`.b`, normalisation, | ||
| `axesOf` renderer. | ||
| 4. `cli/commands/review/compose-review.ts`: axis-tag readers, typed-entry | ||
| axes, licensed split, Critical reroute arm (seam counts adjusted per | ||
| severity), ledger stamping via `readClaim`, disclosures, verdict wording, | ||
| `deferrableFindingsInline`. | ||
| 5. `submit.ts` (stderr wording), `pr-context.ts` (work-list table), | ||
| `lib/agent-briefs.ts` (verify brief states the axes). | ||
| 6. SKILL.md / posting.md (the model-side contract), DESIGN.md. | ||
|
|
||
| ## Explicitly not done | ||
|
|
||
| - **No trigger-frequency axis.** Named optional in the issue; a "corner" is a | ||
| judgement no witness settles. | ||
| - **No auto-filed issues.** `submit` is the only write path; a deferred | ||
| Critical's record is the posted deferral line and the artifact's | ||
| `D<round>-<n>` entry, and filing the follow-up issue stays with the author. | ||
| - **No Web Shell rendering.** The renderer ignores the new fields; nothing | ||
| it displays is decided by them. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.