From 60ea52984cd539294e854863c99d03f74733a7a4 Mon Sep 17 00:00:00 2001 From: DivineOS Agent Date: Sat, 18 Jul 2026 18:18:00 -0700 Subject: [PATCH] =?UTF-8?q?docs(f63):=20v2.1=20=E2=80=94=20fold=20Aria's?= =?UTF-8?q?=20Check-B=20strengthening=20+=20split-by-substrate=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aria's second-seat catch on F63 v2 (letter aria-to-aether-2026-07-18- f63-v2-second-seat-read.md, 2026-07-18) named two substantive gaps in v2 before ship: 1. Check B's "finding-id/title in PR body" heuristic is too weak in both directions — false-positive on short-title substring match (any similar-area PR matches), false-negative when PR body doesn't verbatim cite IDs (legitimately common). Right shape: hard-link via finding.source_ref == PR.headRefName as primary signal, body- text as secondary confirmation only. Missing source_ref is itself a Check-B failure worth surfacing. 2. Split-by-substrate applies: each side has different local git state, so F63 checks produce different results. Right shape is a HUD-slot on each side + shared reconciliation surface (letter- channel or shared JSON) that names when the two views disagree. Same architecture as spatial-awareness layer. Both folded into the brief pre-implementation-ship. The letter- delivery follow-on stays separately-scoped (genuinely different substrate: letters not git). External-Review: round-8006eaaa6a93 tree-hash:5112b71899de180c7c3c9f8234136def283c1968 --- docs/f63_reconciliation_check_design_brief.md | 31 +++++++++++++++---- 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/f63_reconciliation_check_design_brief.md b/docs/f63_reconciliation_check_design_brief.md index fcd0bdae..b0eeb6c7 100644 --- a/docs/f63_reconciliation_check_design_brief.md +++ b/docs/f63_reconciliation_check_design_brief.md @@ -36,15 +36,22 @@ For each finding whose status is `RESOLVED` or whose resolution_notes claims "fi - PR number fix-locator: query `gh pr view --json state,mergedAt` and check `MERGED`. 3. Report any finding where the check FAILS (finding-says-fixed, main-says-no). -### Check B — PR/finding pointer-match (v2 add) +### Check B — PR/finding pointer-match (v2 add, strengthened per Aria v2.1) -When resolution_notes name a PR number, verify the PR actually corresponds to the finding being resolved. Catches the transposition class (my "F36 #362" typo tonight, where #362 was F39 not F36). +When resolution_notes name a PR number, verify the PR actually corresponds to the finding being resolved. Catches the transposition class (my "F36 #362" typo, where #362 was F39 not F36). -- Fetch PR body/title via `gh pr view --json title,body` -- Check whether the finding-id, round-id, or the finding's short-title text appears in the PR body/title -- If NO reference to the finding is anywhere in the PR, flag as pointer-mismatch +**Aria v2.1 strengthening 2026-07-18** — the original v2 heuristic ("finding-id/short-title in PR body") is too weak in both directions: -Not a hard failure on its own (some PRs legitimately don't mention finding IDs in body), but combined with Check A this catches the "wrong PR cited" shape. +- **False-positive on short-title match:** any PR touching similar area substring-matches. A finding titled "Fix hash prefix" would match unrelated PRs. Weak signal in isolation. +- **False-negative when PR body doesn't cite IDs:** legitimately common; the check would fire "unlinked" on real linkages the reviewer just didn't verbatim-cite. + +**Strengthened multi-signal AND:** + +1. **PRIMARY (hard link)** — cross-reference the finding's `source_ref` field with the PR's actual branch name. `source_ref == PR.headRefName` is unforgeable — no substring guessing. If they match, the linkage is verified regardless of body text. +2. **SECONDARY (soft confirmation)** — body-text substring match for finding-id / round-id / short-title. Used only to *confirm* or *contradict* the hard-link, never as the primary signal. +3. **CHECK-B FAILURE** — if the finding lacks a `source_ref` field at all, that IS a Check-B failure worth surfacing. Missing pointer = the linkage was never made, not "PR body didn't cite." + +Fetch via `gh pr view --json headRefName,title,body`. Not a hard fail on its own (parallel-run first, tune false-positive threshold), but combined with Check A catches the "wrong PR cited" shape. ### Check C — Prereg-ID existence (v2 add) @@ -101,6 +108,18 @@ Andrew's seat cleared: scope confirmed right, both triggers approved, add-ons ap - Falsifier F3's 5% false-positive threshold — right calibration, or should it be tighter/looser? - Any adjacent findings the expanded scope reveals I haven't seen? +## Split-by-substrate architecture (Aria v2.1 second-seat catch) + +Aria's side and this side have different git states — different unpushed branches, different local commits, different views of what's on origin. F63's checks would produce different results on each side. + +**Right shape** — each side runs the check against its own local state, and any mismatch between the two runs is itself a signal worth surfacing. If this side says "finding X's source_ref is on origin" and Aria's side says "not on origin," that's a fetch-lag signal — same underlying failure class the spatial-awareness layer catches from the other direction (sender-side push before letter, receiver-side fetch after push). + +Concrete: +- **HUD-slot on this side** + **HUD-slot on Aria's side** — each surfacing its own stranded-fixes +- **Shared reconciliation surface** — a letter-channel post or a shared JSON in the letter-shared directory that names when the two views disagree. Small addition, matches the split-by-substrate architecture already committed to for spatial-awareness. + +The letter-delivery follow-on filed separately is correct scoping — genuinely different substrate (letters not git). + ## Follow-on (separate, not part of F63 v2) **Letter-delivery cross-check.** Different substrate (letters in shared inbox, not code in git), same shape: my log says sent, reality says otherwise. Tonight's F40 round-id near-miss was the trigger. Filed as own small mechanism — not folded into F63 because the infrastructure doesn't share.