From 45b8b46d6ec7d1d04de454206e51d4dc803a7103 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 20:28:45 +0000 Subject: [PATCH 01/34] =?UTF-8?q?docs(audit):=20R3=20deferral=20anti-patte?= =?UTF-8?q?rn=20audit=20(PROPOSAL=20=E2=80=94=20Director-authored)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Surfaces the broader anti-pattern class around cost-lens Miss dissolution (operator-ratified 2026-05-11). Grep-verified ~1600+ instances of deferral-via-wrapper-variant in v3 compiler production surface across 13 categories (Option, panic!, .expect(), NotYetImplemented, DescentUnknown, ArrowBody::Pending, _ => catch-alls, etc.). Per operator-directive: "Miss should go away entirely; if something in substrate defines a Miss it should fail and be investigated asap" — extended to whole anti-pattern class. Each category dissolution path proposed. Tagged for PM (deep-wolf-155) + Mgr ratification: scope, sequencing, PR-template ratchet authoring authority. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- ...-deferral-anti-pattern-audit-2026-05-11.md | 181 ++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md new file mode 100644 index 00000000000..30bdcf34573 --- /dev/null +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -0,0 +1,181 @@ +# R3 Deferral Anti-Pattern Audit — 2026-05-11 + +**Status:** PROPOSAL (Director-authored) +**Audience:** PM (deep-wolf-155) + standing Mgrs (Substrate / PB / Verification + future Mgrs) for ratification and dispatch +**Audit basis:** operator-directive 2026-05-11 — "by default, let these fail, would NOT invent a Miss case to support them; default is reject construction entirely. Miss should go away entirely; if something in substrate defines a Miss it should fail and be investigated asap." + +## §0. Why this audit + +The cost-lens `Lookup::Miss` discussion surfaced a broader class problem: **deferral-via-wrapper-variant**. The pattern: when a substrate function can't or won't decide an answer, it returns a wrapper variant (Miss / None / Unknown / Unparsed / Pending / NotYetImplemented / etc.) that the caller must handle. This is "better than silently passing" but is itself a deferral of the real design decision. + +Operator framing: deferral wrappers should not exist by default. Two acceptable outcomes: + +1. **Construction makes the case impossible** — the substrate shape doesn't permit constructing programs / data that would land in the deferral arm. The wrapper variant dissolves; the type narrows. +2. **Fail-closed Diagnostic** at the boundary — if the case is reachable from user input, surface a typed Diagnostic at the input boundary (per `feedback_fail_closed_discipline`), not a silently-Maybe-typed wrapper that callers can mishandle. + +Anything else is **slacking on the design decision**. Operator notes this is "something I want to snuff out in R3" and "should really be escalated/caught during review." + +## §1. Anti-pattern survey — counts at HEAD `origin/main` + +Grep-verified instances. Each instance is a site where the substrate admits "I don't have a structural answer for this case." + +| # | Anti-pattern | Sites | Notes | +|---|---|---|---| +| 1 | `Option` returns in substrate `dag.rs` | **83** | Pure deferral surface — every caller must handle None. | +| 2 | `panic!` calls in production src | **244** | Should be typed Diagnostics, not runtime panics. | +| 3 | `.expect(...)` calls in production src | **665** | Assumes success; same fail-shape as panic. | +| 4 | `.unwrap()` calls in production src | **35** | Same shape as expect; less explicit. | +| 5 | Catch-all `_ =>` match arms | **406** | Each one admits non-exhaustiveness of the matched enum. | +| 6 | `todo!() / unimplemented!() / unreachable!()` macros | **43** | Explicit "I haven't decided this." | +| 7 | Opaque error types (`Result<*, String>`, `Box`) | **69** | Erases the structural shape of failure. | +| 8 | `ClaimResult::NotYetImplemented` | **21** (9 src + 12 tests) | Explicit "gate exists, substrate doesn't." | +| 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). | +| 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | "We don't know if this descends" — same shape as `SameArgumentCall` Miss. | +| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | "Proof construction failed but maybe just incomplete" — Miss-shape. | +| 12 | `ArrowBody::Pending` / `LensSurfacePending` | 4 enum variants | In-progress states baked into the substrate type. | +| 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — admits "we know this isn't covered yet" without enforcing dissolution. | + +**Aggregate:** ≈1600+ instances of deferral-shape patterns in the v3 compiler's production surface. The cost-lens `Miss` work is one specific case in a much larger class. + +## §2. Why each instance is "slacking" + +Not every instance is equally bad. The taxonomy: + +### §2.1 Pure deferral (must dissolve) + +Cases where the wrapper variant captures "I don't have an answer" and the answer is required for correctness: + +- `Lookup::Miss` — already committed to R3 dissolution per operator-ratified 2026-05-11. See §3.1. +- `DescentEvidence::DescentUnknown` — same shape; should also dissolve. See §3.2. +- `EvidenceUnknown / EvidenceIncomplete` in descent residual — same shape; see §3.3. +- Empty-list-as-Miss in generated code — see §3.4. +- `ClaimResult::NotYetImplemented` — explicit deferral of gate execution. See §3.5. +- `ArrowBody::Pending` / `LensSurfacePending` — in-progress baked into the substrate, meaning the substrate type allows "I'm half-built" as a valid state. See §3.6. + +### §2.2 Boundary tools used in interior (must convert to typed) + +Cases where Rust's standard "this might fail" tools (`Option`, `Result`, `panic!`, `.expect()`) are used INSIDE the substrate rather than only at the user-input boundary: + +- 83 `Option` returns in `dag.rs` +- 244 `panic!` calls +- 665 `.expect()` calls +- 35 `.unwrap()` calls +- 69 opaque `Result<*, String>` / `Box` +- 406 catch-all `_ =>` match arms +- 43 `todo!() / unimplemented!() / unreachable!()` macros + +These are "Rust idiom" abuse: the language offers these tools because real software has boundaries, but using them inside the substrate (vs. at the boundary) treats every internal function as if it were the boundary. Per `feedback_fail_closed_discipline` (C-8: every detectable problem is a Diagnostic), the substrate's internal flows should be total (typed-impossible to fail) or surface a typed Diagnostic at the boundary, not paper-over via runtime panic. + +### §2.3 Tracking-only artifacts (must promote or carve) + +- `structural_coverage_gap_*` named gates — these are R3 ledger rows that admit "we know this isn't covered" without forcing the dissolution decision. Either they're load-bearing (must close in R3) or they're not (must be explicitly carved out and post-R3-scheduled). + +## §3. R3-close dissolutions (per-category direction) + +### §3.1 Cost-lens `Lookup::Miss` — **ALREADY RATIFIED 2026-05-11** + +5 sub-cases; see Director ratification message to Substrate Mgr at warm-wolf-698. Net: `Lookup` type collapses to `SymbolicCost`. + +### §3.2 `DescentEvidence::DescentUnknown` — proposed dissolution + +Currently: lattice bottom for "we can't prove descent." Same shape as `SameArgumentCall` Miss. + +Proposal: remove `DescentUnknown` variant from `DescentEvidence` enum. Construction of recursive Transform that can't be proven `Strict` or `NonIncreasing` becomes a compile-time Diagnostic. Lattice collapses from 3 variants to 2 (`Strict | NonIncreasing`). + +Consumer impact: `merge_evidence`, `join_evidence`, `evidence_rank`, etc. in `dag.rs` (already retired in earlier work) — surviving consumers must drop the `DescentUnknown` arms. + +### §3.3 Descent-execution-proof residual `EvidenceUnknown / EvidenceIncomplete` — proposed dissolution + +Currently: `DescentResidual = EvidenceUnknown(NonStrictEvidence) | EvidenceIncomplete`. The work to narrow from 4 to 2 was good, but the residual itself is still a Miss-shape. + +Proposal: if descent execution can't complete, that's a typed compile-time Diagnostic at the producer's surface. Replace the residual carrier with `Result` where `DescentExecutionDiagnostic` is a concrete error type (not a Maybe-coverage Maybe-incomplete wrapper). + +### §3.4 Empty-list `[] => Lookup::Miss` in generated code (4 sites) + +Per operator framing on cost lens Case 5: lookups should not fail silently. Either use typed-key references (cost-table-with-guaranteed-presence) or fail-closed Diagnostic. Default for `lookup_cost([])` is `Diagnostic`, not `ConstantCost(0)`. Affects `lens_cost_symbolic_generated.rs` (3 sites) + `infer_helpers_generated.rs` (1 site). + +### §3.5 `ClaimResult::NotYetImplemented` (21 sites) — per-gate disposition + +Each `NotYetImplemented` is a gate-tier deferral. For R3 close: + +- **Tier-1**: If the gate is in §1.8 R3-load-bearing scope (96 enumerated), the `NotYetImplemented` must be replaced with a real predicate evaluator OR the gate must be explicitly carved post-R3. +- **Tier-2**: Audit each of the 21 sites and route to corresponding Mgr (Verification owns most via TestRunner; lower.rs + test_runner.rs predicate sites). + +Per `feedback_construction_over_ratchets` — `NotYetImplemented` is a textual ratchet that should dissolve when the predicate substrate lands. + +### §3.6 `ArrowBody::Pending` / `LensSurfacePending` — in-progress states in substrate + +`ArrowBody::Pending` is a `Behavior::Transform.body` variant indicating "this function hasn't been lowered yet." It's a transitional state baked into the substrate type. Consequence: every walker / lens that processes Transform bodies has to handle `Pending` (paper-over). + +Proposal: substrate-shape redesign — separate `UnresolvedSignature` (pre-lowering) from `ResolvedTransform` (post-lowering). The lowering pipeline transforms the former into the latter. Walkers / lenses operate on `ResolvedTransform` only. Pending becomes unrepresentable at the post-lowering substrate type level. + +### §3.7 Boundary-tool-in-interior cleanup (1100+ sites) — per-Mgr-canvas audit + +Volume too large for a single dispatch. Recommend Mgr-canvas authoring per file: +- Substrate Mgr (warm-wolf-698): `dag.rs` 83 `Option` returns audit → typed accessor cleanup +- Substrate Mgr: 244 `panic!` calls audit → typed Diagnostic conversion +- Substrate Mgr: 665 `.expect()` calls audit → similar +- PB Mgr (warm-dove-618): emit-path `unreachable!()` macros audit +- Verification Mgr (post-respawn): `_ =>` catch-all audit (406 sites) + +Per-file canvas authoring expected; not a single PR. + +### §3.8 `structural_coverage_gap_*` ratchets — promote or carve + +10+ named gates in `ROADMAP.md` and worker briefs. Each should be reviewed: +- Load-bearing for R3: close in R3 cycle +- Not load-bearing: explicit carve to post-R3 (no silent tracking) + +## §4. Process implication — why review didn't catch this + +Operator notes: "this is me slacking — things like this should really be escalated/caught during review." Review-tier process gap. + +Proposal: extend the PR review checklist (per `feedback_pre_authored_brief_queue` discipline) with **explicit anti-pattern callouts**: + +1. Does this PR add a new `Option` return in substrate-tier code? → flag for typed-accessor / fail-closed Diagnostic review. +2. Does this PR add a new `panic!` / `.expect()` / `.unwrap()` in production code? → flag for Diagnostic-conversion review. +3. Does this PR add a new enum variant whose name contains `Unknown / Pending / Missing / Incomplete / Maybe`? → flag for construction-impossibility review. +4. Does this PR add a `NotYetImplemented` predicate? → flag for substrate-readiness review. +5. Does this PR add a new `_ =>` catch-all in an enum match? → flag for exhaustiveness review. + +These checklist items belong in `.github/PULL_REQUEST_TEMPLATE.md` (or whichever PR description ratchet is canonical). Per `feedback_construction_over_ratchets`: prefer structural enforcement (lint rule) over textual checklist, but checklist is a transitional state until lints land. + +## §5. Sequencing recommendation + +R3-close commitment scope (per operator-directive 2026-05-11): + +1. **§3.1 (cost-lens Miss)** — RATIFIED, dispatched to Substrate Mgr 2026-05-11. +2. **§3.2 (DescentUnknown)** — propose same-batch dispatch with §3.1 (same Substrate-tier work). +3. **§3.3 (descent-execution-proof residual)** — propose same-batch dispatch. +4. **§3.4 (empty-list-as-Miss)** — generated-code regen needed; folds into §3.1 + §3.5 dispatch. +5. **§3.5 (NotYetImplemented audit)** — per-gate Mgr-tier dispatch; recommend Verification Mgr re-spawn (currently archived per overnight cascade) authors the audit. +6. **§3.6 (ArrowBody::Pending)** — larger substrate-shape work; PB Mgr or Substrate Mgr canvas decides. +7. **§3.7 (boundary-tool-in-interior)** — per-file Mgr-canvas authoring; spread across Mgrs. +8. **§3.8 (structural_coverage_gap)** — promote/carve audit; PM-coordinated. +9. **§4 (review-process)** — PM authors the PR-template ratchet update; cross-Mgr coordination. + +## §6. Open questions for PM ratification + +1. Is §3.6 (ArrowBody::Pending dissolution) R3-load-bearing or post-R3? It's a substantial substrate-shape change; pragmatically may need carve-out. +2. Is §3.7 (1100+ boundary-tool sites) realistic for R3 timeline? Or should it be a "no new instances" ratchet with cleanup deferred? +3. Does §4 (PR-template ratchet) need a Verification Mgr re-spawn first, or can PM author standalone? +4. Should §3.8 (structural_coverage_gap audit) be folded into the standing Debt-Paydown Mgr cadence (silent-ram-834 — if alive) or stand alone? + +## §7. Related memories / references + +- `feedback_construction_over_ratchets` — model first, violations dissolve; never heuristic-patch. +- `feedback_state_space_vs_behavioral_invariants` — type enforcement > API enforcement. +- `feedback_decidability_invariant` — all `.dag` code must be decidable. +- `feedback_fail_closed_discipline` — C-8: every detectable problem is a Diagnostic; no warnings, no silent Nones, no panics. +- `feedback_coproduct_dissolution` — coproducts are categorical compression; dissolve into coordinates. +- `feedback_no_textual_enforcement_bridges` — never propose grep/regex as interim enforcement. +- INVARIANTS.md §C-8 (fail-closed discipline). + +## §8. Ratification asks + +Per PM disposition request: + +- (a) Ratify §3 dissolution directions per category — or surface alternatives. +- (b) Ratify §4 PR-template ratchet authoring authority (PM vs. Verification Mgr). +- (c) Ratify §5 sequencing — same-batch vs. staged. +- (d) Author or delegate §3.7 per-Mgr-canvas audit dispatch. From 2ce36684318a139cb5733827043f87478c5a620a Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 16:51:33 -0400 Subject: [PATCH 02/34] WIP: gunbc Director --- ...-deferral-anti-pattern-audit-2026-05-11.md | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 30bdcf34573..5f56c4e3b1d 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -21,7 +21,7 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | # | Anti-pattern | Sites | Notes | |---|---|---|---| -| 1 | `Option` returns in substrate `dag.rs` | **83** | Pure deferral surface — every caller must handle None. | +| 1 | `Option` returns in substrate `dag.rs` | **83** | Triage candidates — but **not** uniformly Miss-class. Per `modeling-discipline.md:41-50` + `CODING.md:95-97`, `Option` is **allowed when absence is a legitimate non-error state**. Miss-class violation = `None`-on-error without a diagnostic write. The 83 sites need per-call audit: which are error-None (Miss-class, must dissolve) vs legitimate-absence (compliant). Don't bulk-convert. | | 2 | `panic!` calls in production src | **244** | Should be typed Diagnostics, not runtime panics. | | 3 | `.expect(...)` calls in production src | **665** | Assumes success; same fail-shape as panic. | | 4 | `.unwrap()` calls in production src | **35** | Same shape as expect; less explicit. | @@ -52,19 +52,20 @@ Cases where the wrapper variant captures "I don't have an answer" and the answer - `ClaimResult::NotYetImplemented` — explicit deferral of gate execution. See §3.5. - `ArrowBody::Pending` / `LensSurfacePending` — in-progress baked into the substrate, meaning the substrate type allows "I'm half-built" as a valid state. See §3.6. -### §2.2 Boundary tools used in interior (must convert to typed) +### §2.2 Boundary tools used in interior — **triage candidates, NOT uniform "abuse"** -Cases where Rust's standard "this might fail" tools (`Option`, `Result`, `panic!`, `.expect()`) are used INSIDE the substrate rather than only at the user-input boundary: +**Correction per openai-pro review**: the original framing called all 1100+ sites "Rust idiom abuse." That overgeneralized. Per `modeling-discipline.md:41-50` and `CODING.md:95-97`, `Option` / `Result` are explicitly **allowed** when absence/failure is a meaningful structural state. The violation pattern is `None`-on-error without a diagnostic write, and runtime panics in production substrate flow (vs. legitimate panics in regen binaries / bootstrap / boundary tooling). -- 83 `Option` returns in `dag.rs` -- 244 `panic!` calls -- 665 `.expect()` calls -- 35 `.unwrap()` calls -- 69 opaque `Result<*, String>` / `Box` -- 406 catch-all `_ =>` match arms -- 43 `todo!() / unimplemented!() / unreachable!()` macros +Triage candidates (per-site audit, not bulk-conversion): -These are "Rust idiom" abuse: the language offers these tools because real software has boundaries, but using them inside the substrate (vs. at the boundary) treats every internal function as if it were the boundary. Per `feedback_fail_closed_discipline` (C-8: every detectable problem is a Diagnostic), the substrate's internal flows should be total (typed-impossible to fail) or surface a typed Diagnostic at the boundary, not paper-over via runtime panic. +- 83 `Option` returns in `dag.rs` — classify: error-None (must dissolve) vs legitimate-absence (compliant per `modeling-discipline.md:49-50`). +- 244 `panic!` calls — classify: boundary-tooling (regen, bootstrap, setup; legitimate) vs interior substrate flow (must dissolve to typed Diagnostic per C-8). +- 665 `.expect()` / 35 `.unwrap()` calls — same as panic: per `CODING.md:307-309`, panics/unwraps in library code are contract violations; the boundary subset (regen entrypoints) is acceptable. +- 69 opaque `Result<*, String>` / `Box` — erases structural failure shape; Mgr-canvas audit per consumer. +- 406 catch-all `_ =>` match arms — each one needs review: does it admit non-exhaustiveness, or is it deliberate fall-through (e.g., default-arm for an open enum)? +- 43 `todo!() / unimplemented!() / unreachable!()` macros — explicit deferral; per-site disposition. + +The Mgr-canvas audit (§3.7) should be a **per-file production-flow inventory** with each candidate classified by "boundary tooling vs interior substrate flow" before any conversion work. Counts are scope-signals for canvas authoring, not ratchet targets. ### §2.3 Tracking-only artifacts (must promote or carve) @@ -76,13 +77,22 @@ These are "Rust idiom" abuse: the language offers these tools because real softw 5 sub-cases; see Director ratification message to Substrate Mgr at warm-wolf-698. Net: `Lookup` type collapses to `SymbolicCost`. -### §3.2 `DescentEvidence::DescentUnknown` — proposed dissolution +### §3.2 `DescentEvidence::DescentUnknown` — requires authority-update precondition (NOT direct dissolution) + +**Correction per openai-pro review**: my original framing ("same shape as Miss; remove the variant") conflated a Miss-class deferral with a fail-closed lattice bottom. They're different. `INVARIANTS.md:63-66` currently establishes: + +> `DescentEvidence` = `Strict | NonIncreasing | DescentUnknown`, with `BoundedLattice` top = `Strict`, bottom = `DescentUnknown` (fail-closed), meet = conservative branch merge, join = optimistic branch merge. + +`DescentUnknown` as fail-closed bottom is a load-bearing lattice element, not a Miss surface. Per `feedback_construction_over_ratchets`: the dissolution question is whether the design intent still wants a 3-variant lattice (with `DescentUnknown` as conservative bottom for branch-merge semantics) or a 2-variant lattice (with construction-time rejection of programs that can't prove `Strict` or `NonIncreasing`). + +**Revised proposal**: dispatch the design question to PM + Substrate Mgr for ratification BEFORE substrate change: -Currently: lattice bottom for "we can't prove descent." Same shape as `SameArgumentCall` Miss. +1. **(a) Keep 3-variant lattice; redirect Miss-shape concerns**: `DescentUnknown` stays as the fail-closed merge bottom (per current INVARIANTS authority). What dissolves is **construction**: programs that lower to `DescentEvidence::DescentUnknown` at a callsite become compile-time Diagnostic at the producer side — the lattice element survives, but reaching it during well-typed program execution is impossible. Producer-side path-narrowing, not lattice-shape change. +2. **(b) Collapse to 2-variant lattice**: requires explicit `INVARIANTS.md` authority update first. PM-tier ratification: is `DescentUnknown` truly redundant once construction-time rejection lands, or is the conservative-branch-merge bottom still needed for sound lattice composition (joins of partial program fragments)? -Proposal: remove `DescentUnknown` variant from `DescentEvidence` enum. Construction of recursive Transform that can't be proven `Strict` or `NonIncreasing` becomes a compile-time Diagnostic. Lattice collapses from 3 variants to 2 (`Strict | NonIncreasing`). +**Pre-dispatch requirement**: PM ratification on (a) vs (b). Until ratified, no worker dispatch on this dissolution. This is the discipline gap operator called out — review-tier should catch "audit doc proposes substrate-shape change before authority-doc update" before it lands. -Consumer impact: `merge_evidence`, `join_evidence`, `evidence_rank`, etc. in `dag.rs` (already retired in earlier work) — surviving consumers must drop the `DescentUnknown` arms. +Consumer impact (either path): `merge_evidence`, `join_evidence`, `evidence_rank`, etc. in `dag.rs` (the older versions were already retired in earlier Cluster K work) — surviving consumers need to align with whichever path PM ratifies. ### §3.3 Descent-execution-proof residual `EvidenceUnknown / EvidenceIncomplete` — proposed dissolution From d2d97965bff9e6319316c0ee9f00336ab9318bfe Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 20:52:18 +0000 Subject: [PATCH 03/34] =?UTF-8?q?docs(audit):=20address=20openai-pro=20REQ?= =?UTF-8?q?UEST=5FCHANGES=20=E2=80=94=20narrow=20Miss-class=20scope;=20rec?= =?UTF-8?q?oncile=20DescentUnknown=20authority?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per openai-pro review (#2708 c#4425020297, verdict REQUEST_CHANGES): 3 valid blocking findings addressed: 1. LAYER MODEL — §3.2 DescentEvidence::DescentUnknown removal conflated Miss-class deferral with fail-closed lattice bottom (INVARIANTS.md:63-66). Reframed: dissolution requires PM-tier ratification on (a) keep 3-variant lattice + construction-side narrowing OR (b) authority update first + 2-variant collapse. No worker dispatch until PM ratifies. 2. INVARIANTS + modeling-discipline — §1 row 1, §2.2 paragraph: "all 83 Option = pure deferral" overgeneralized. Per modeling-discipline.md:41-50 + CODING.md:95-97, Option is allowed when absence is meaningful. Reframed as triage candidates with per-site classification (error-None = Miss-class; legitimate-absence = compliant); explicit "don't bulk-convert." 3. CODING.md — §4 review checklist phrased as "flag for conversion" which conflicts with CODING.md:307-309 (Option/Result OK when meaningful). Reframed as "flag for justification": reviewer asks, author justifies; non-compliant cases convert, compliant wrappers survive. §0 framing also clarified: Miss-class deferral ≠ all Option; per-site classification required; bulk-conversion would itself be a discipline violation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../r3-deferral-anti-pattern-audit-2026-05-11.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 5f56c4e3b1d..0ef54b8039c 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -8,13 +8,15 @@ The cost-lens `Lookup::Miss` discussion surfaced a broader class problem: **deferral-via-wrapper-variant**. The pattern: when a substrate function can't or won't decide an answer, it returns a wrapper variant (Miss / None / Unknown / Unparsed / Pending / NotYetImplemented / etc.) that the caller must handle. This is "better than silently passing" but is itself a deferral of the real design decision. -Operator framing: deferral wrappers should not exist by default. Two acceptable outcomes: +Operator framing: deferral wrappers should not exist by default. Two acceptable outcomes for **Miss-class deferral**: 1. **Construction makes the case impossible** — the substrate shape doesn't permit constructing programs / data that would land in the deferral arm. The wrapper variant dissolves; the type narrows. 2. **Fail-closed Diagnostic** at the boundary — if the case is reachable from user input, surface a typed Diagnostic at the input boundary (per `feedback_fail_closed_discipline`), not a silently-Maybe-typed wrapper that callers can mishandle. Anything else is **slacking on the design decision**. Operator notes this is "something I want to snuff out in R3" and "should really be escalated/caught during review." +**Scope qualifier (per openai-pro review 2026-05-11)**: "Miss-class deferral" ≠ "all `Option` returns." Per `modeling-discipline.md:41-50` + `CODING.md:95-97`, `Option` is **explicitly allowed when absence is a legitimate non-error state**. The Miss-class violation pattern is: `None`-on-error without a diagnostic write, panics in interior substrate flow (not boundary tooling), construction-time deferral surfaces ("Unknown/Pending/Missing" variants that capture "I haven't decided this yet"). Compliant wrappers — legitimate-absence `Option`, fail-closed lattice bottoms, deliberate-default catch-alls — survive. Per-site classification required; bulk conversion would itself be a discipline violation. + ## §1. Anti-pattern survey — counts at HEAD `origin/main` Grep-verified instances. Each instance is a site where the substrate admits "I don't have a structural answer for this case." @@ -140,16 +142,18 @@ Per-file canvas authoring expected; not a single PR. Operator notes: "this is me slacking — things like this should really be escalated/caught during review." Review-tier process gap. -Proposal: extend the PR review checklist (per `feedback_pre_authored_brief_queue` discipline) with **explicit anti-pattern callouts**: +Proposal: extend the PR review checklist (per `feedback_pre_authored_brief_queue` discipline) with **anti-pattern justification callouts** — flag for JUSTIFICATION review, not for "convert by default": -1. Does this PR add a new `Option` return in substrate-tier code? → flag for typed-accessor / fail-closed Diagnostic review. -2. Does this PR add a new `panic!` / `.expect()` / `.unwrap()` in production code? → flag for Diagnostic-conversion review. -3. Does this PR add a new enum variant whose name contains `Unknown / Pending / Missing / Incomplete / Maybe`? → flag for construction-impossibility review. +1. Does this PR add a new `Option` return in substrate-tier code? → flag for **justification**: is absence a meaningful structural state (compliant per `modeling-discipline.md:49-50` + `CODING.md:95-97`), or is it error-None deferring a diagnostic write? Reviewer asks; author justifies; non-compliant cases convert. +2. Does this PR add a new `panic!` / `.expect()` / `.unwrap()` in **library / substrate-flow** code (not in regen/bootstrap entrypoints)? → flag for Diagnostic-conversion review per `CODING.md:307-309`. +3. Does this PR add a new enum variant whose name contains `Unknown / Pending / Missing / Incomplete / Maybe`? → flag for **construction-impossibility OR fail-closed-lattice review**: is the variant a deferral surface (must dissolve) or a load-bearing lattice element (compliant per `INVARIANTS.md` authority)? 4. Does this PR add a `NotYetImplemented` predicate? → flag for substrate-readiness review. -5. Does this PR add a new `_ =>` catch-all in an enum match? → flag for exhaustiveness review. +5. Does this PR add a new `_ =>` catch-all in an enum match? → flag for **exhaustiveness OR deliberate-default review**: is the enum closed (catch-all admits non-exhaustiveness) or open (catch-all is the default arm)? These checklist items belong in `.github/PULL_REQUEST_TEMPLATE.md` (or whichever PR description ratchet is canonical). Per `feedback_construction_over_ratchets`: prefer structural enforcement (lint rule) over textual checklist, but checklist is a transitional state until lints land. +**The discipline shift**: from "deferral wrappers must die" to "deferral wrappers require explicit justification at construction." Compliant wrappers (legitimate-absence Option, fail-closed-lattice bottoms, deliberate-default catch-alls) survive; deferral-wrapper-as-design-laziness gets caught at review. + ## §5. Sequencing recommendation R3-close commitment scope (per operator-directive 2026-05-11): From f2c3d08699dadbc327814c1eb8eb69f8873af7cf Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 20:58:54 +0000 Subject: [PATCH 04/34] =?UTF-8?q?docs(audit):=20address=20codex=20REQUEST?= =?UTF-8?q?=5FCHANGES=20=E2=80=94=20eliminate=20internal=20authority=20con?= =?UTF-8?q?tradictions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per codex review (#2708 c#4425182*, verdict REQUEST_CHANGES): 2 valid blocking findings addressed: 1. §1 table — rows 2-7 stated definitive violations ("should be typed Diagnostics", "admits non-exhaustiveness", "explicit 'I haven't decided this'") while §2.2 later correctly narrowed these to per-site triage. Two conflicting authorities within the same brief violated INVARIANTS P2 single-authority discipline. Fix: table notes now reflect the triage framing (boundary tooling vs interior substrate flow per CODING.md 307-309; closed-enum vs deliberate-default catch-alls; etc.). Rows 9-13 tagged with explicit cross-references to §3 disposition. 2. §5 sequencing — proposed §3.2 (DescentUnknown) same-batch dispatch with §3.1, but §3.2 itself blocked dispatch on PM ratification of path (a) vs (b). Fix: §5 now explicitly marks §3.2 + §3.6 as PM-blocked authority gates; only path (a) ratification would enable same-batch with §3.1; path (b) requires INVARIANTS.md edit landing first. Authority-gate summary appended. Also relabeled §2.1 "Pure deferral" → "Miss-class deferral" and removed DescentUnknown from the auto-classified list (consistent with §3.2 gate). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- ...-deferral-anti-pattern-audit-2026-05-11.md | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 0ef54b8039c..01cb4409072 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -24,18 +24,18 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | # | Anti-pattern | Sites | Notes | |---|---|---|---| | 1 | `Option` returns in substrate `dag.rs` | **83** | Triage candidates — but **not** uniformly Miss-class. Per `modeling-discipline.md:41-50` + `CODING.md:95-97`, `Option` is **allowed when absence is a legitimate non-error state**. Miss-class violation = `None`-on-error without a diagnostic write. The 83 sites need per-call audit: which are error-None (Miss-class, must dissolve) vs legitimate-absence (compliant). Don't bulk-convert. | -| 2 | `panic!` calls in production src | **244** | Should be typed Diagnostics, not runtime panics. | -| 3 | `.expect(...)` calls in production src | **665** | Assumes success; same fail-shape as panic. | -| 4 | `.unwrap()` calls in production src | **35** | Same shape as expect; less explicit. | -| 5 | Catch-all `_ =>` match arms | **406** | Each one admits non-exhaustiveness of the matched enum. | -| 6 | `todo!() / unimplemented!() / unreachable!()` macros | **43** | Explicit "I haven't decided this." | -| 7 | Opaque error types (`Result<*, String>`, `Box`) | **69** | Erases the structural shape of failure. | -| 8 | `ClaimResult::NotYetImplemented` | **21** (9 src + 12 tests) | Explicit "gate exists, substrate doesn't." | -| 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). | -| 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | "We don't know if this descends" — same shape as `SameArgumentCall` Miss. | -| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | "Proof construction failed but maybe just incomplete" — Miss-shape. | -| 12 | `ArrowBody::Pending` / `LensSurfacePending` | 4 enum variants | In-progress states baked into the substrate type. | -| 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — admits "we know this isn't covered yet" without enforcing dissolution. | +| 2 | `panic!` calls in production src | **244** | Triage candidates — boundary tooling (regen/bootstrap entrypoints) is legitimate per `CODING.md:307-309`; interior substrate-flow panics dissolve to typed Diagnostic per C-8. Per-site classification (§2.2). | +| 3 | `.expect(...)` calls in production src | **665** | Same boundary-vs-interior triage as #2 per `CODING.md:307-309`. | +| 4 | `.unwrap()` calls in production src | **35** | Same boundary-vs-interior triage as #2. | +| 5 | Catch-all `_ =>` match arms | **406** | Triage — distinguishes closed-enum non-exhaustiveness (must dissolve) from deliberate default-arm on open enums or terminal "shouldn't happen" arms paired with explicit Diagnostic. Per-site review. | +| 6 | `todo!() / unimplemented!() / unreachable!()` macros | **43** | Triage — `unreachable!()` paired with an invariant proof is legitimate; `todo!()` / `unimplemented!()` are explicit deferrals. Per-site disposition (§2.2). | +| 7 | Opaque error types (`Result<*, String>`, `Box`) | **69** | Triage candidate — erases structural failure shape at the type level; Mgr-canvas audit per consumer to determine which warrant typed-Diagnostic conversion. | +| 8 | `ClaimResult::NotYetImplemented` | **21** (9 src + 12 tests) | Explicit gate-deferral — per-gate disposition (§3.5): substrate-land OR R3-carve. | +| 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). Miss-class; ratified for R3 dissolution per operator 2026-05-11. | +| 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | **Authority-conflicting per `INVARIANTS.md:63-66`** — currently load-bearing as BoundedLattice fail-closed bottom. **Requires PM ratification before classification** (Miss-class vs lattice-element); see §3.2. | +| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | Miss-shape candidate; see §3.3. | +| 12 | `ArrowBody::Pending` / `LensSurfacePending` | 4 enum variants | In-progress states baked into the substrate type; see §3.6 — substantial substrate-shape change, R3-load-bearing-ness needs PM ratification. | +| 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — per §3.8, each promotes (R3-load-bearing) or carves (post-R3); not classified as deferral by default. | **Aggregate:** ≈1600+ instances of deferral-shape patterns in the v3 compiler's production surface. The cost-lens `Miss` work is one specific case in a much larger class. @@ -43,16 +43,16 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d Not every instance is equally bad. The taxonomy: -### §2.1 Pure deferral (must dissolve) +### §2.1 Miss-class deferral Cases where the wrapper variant captures "I don't have an answer" and the answer is required for correctness: - `Lookup::Miss` — already committed to R3 dissolution per operator-ratified 2026-05-11. See §3.1. -- `DescentEvidence::DescentUnknown` — same shape; should also dissolve. See §3.2. -- `EvidenceUnknown / EvidenceIncomplete` in descent residual — same shape; see §3.3. +- `EvidenceUnknown / EvidenceIncomplete` in descent residual — Miss-shape candidate; see §3.3. - Empty-list-as-Miss in generated code — see §3.4. - `ClaimResult::NotYetImplemented` — explicit deferral of gate execution. See §3.5. -- `ArrowBody::Pending` / `LensSurfacePending` — in-progress baked into the substrate, meaning the substrate type allows "I'm half-built" as a valid state. See §3.6. +- `ArrowBody::Pending` / `LensSurfacePending` — in-progress states baked into substrate type; **substantive substrate-shape change** — see §3.6. +- `DescentEvidence::DescentUnknown` — **NOT auto-classified as Miss-class**. Currently load-bearing as BoundedLattice fail-closed bottom per `INVARIANTS.md:63-66`. Requires PM ratification before classification; see §3.2. ### §2.2 Boundary tools used in interior — **triage candidates, NOT uniform "abuse"** @@ -156,18 +156,20 @@ These checklist items belong in `.github/PULL_REQUEST_TEMPLATE.md` (or whichever ## §5. Sequencing recommendation -R3-close commitment scope (per operator-directive 2026-05-11): +R3-close commitment scope (per operator-directive 2026-05-11). **Dispatch order respects authority gates established in §3 — items requiring PM-tier authority update are explicitly blocked until that update lands.** 1. **§3.1 (cost-lens Miss)** — RATIFIED, dispatched to Substrate Mgr 2026-05-11. -2. **§3.2 (DescentUnknown)** — propose same-batch dispatch with §3.1 (same Substrate-tier work). -3. **§3.3 (descent-execution-proof residual)** — propose same-batch dispatch. +2. **§3.2 (DescentUnknown)** — **BLOCKED on PM ratification of path (a) vs (b)** per §3.2. No dispatch until PM decides whether substrate keeps 3-variant lattice + construction-side narrowing, or authority update precedes 2-variant collapse. Same-batch with §3.1 only valid under path (a); path (b) requires `INVARIANTS.md:63-66` edit landing first. +3. **§3.3 (descent-execution-proof residual)** — propose same-batch dispatch with §3.1 once §3.2 path is ratified (the residual carrier sits downstream of `DescentEvidence` shape). 4. **§3.4 (empty-list-as-Miss)** — generated-code regen needed; folds into §3.1 + §3.5 dispatch. 5. **§3.5 (NotYetImplemented audit)** — per-gate Mgr-tier dispatch; recommend Verification Mgr re-spawn (currently archived per overnight cascade) authors the audit. -6. **§3.6 (ArrowBody::Pending)** — larger substrate-shape work; PB Mgr or Substrate Mgr canvas decides. -7. **§3.7 (boundary-tool-in-interior)** — per-file Mgr-canvas authoring; spread across Mgrs. +6. **§3.6 (ArrowBody::Pending)** — larger substrate-shape work; **R3-load-bearing-ness needs PM ratification before dispatch** (may need post-R3 carve). +7. **§3.7 (boundary-tool-in-interior)** — per-file Mgr-canvas authoring; spread across Mgrs. Each canvas owns its per-site classification (boundary tooling vs interior substrate flow) before any conversion work. 8. **§3.8 (structural_coverage_gap)** — promote/carve audit; PM-coordinated. 9. **§4 (review-process)** — PM authors the PR-template ratchet update; cross-Mgr coordination. +**Authority-gate summary**: items 2 (DescentUnknown) and 6 (ArrowBody::Pending) are explicitly PM-blocked until authority disposition. Items 1/3/4/5/7/8/9 may dispatch on the standing Mgr-canvas authority once R3-scope-ratified. + ## §6. Open questions for PM ratification 1. Is §3.6 (ArrowBody::Pending dissolution) R3-load-bearing or post-R3? It's a substantial substrate-shape change; pragmatically may need carve-out. From fac3b4157d5cfbcbbc392b9364608018dd64582c Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:07:37 +0000 Subject: [PATCH 05/34] =?UTF-8?q?docs(audit):=20address=20inline=20blockin?= =?UTF-8?q?g=20=E2=80=94=20reconcile=20=C2=A73.3=20DescentResidual=20with?= =?UTF-8?q?=20Director-ratified=20=CE=B3-shape?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per inline review finding at docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md:101 (2026-05-11T21:03:41Z): > "BLOCKING: §3.3 reclassifies the Director-ratified terminal DescentResidual > as Miss-shape without reconciling the current termination.dag authority, > which violates P1 modeling faithfulness and locked-decision discipline." Valid finding. The `DescentResidual = EvidenceUnknown(NonStrictEvidence) | EvidenceIncomplete` shape was Director-ratified via the illegal-states-unrepresentable rationale in docs/briefs/r3-substrate-descent-execution-proof-worker.md (gunbc#828 issuecomment-4395060514). The audit incorrectly conflated the analyzer's runtime-failure surface with a Miss-class design-laziness deferral. Same pattern as the prior §3.2 DescentUnknown correction (openai-pro REQUEST_CHANGES): - §3.3 reframed: no direct dissolution proposed; instead, pre-dispatch requirement to read existing authority + produce grep-verified reason + PM ratification. - §1 table row 11: tagged "authority-conflicting per Director-ratified γ-shape — compliant as written today." - §2.1: removed residual from Miss-class auto-classified list; appended to the "NOT auto-classified" entries alongside DescentUnknown. - §5 sequencing: §3.3 now authority-blocked (same as §3.2 + §3.6); cannot same-batch with §3.1 until reconciliation lands. Authority-gate footer updated. Pattern: every authority-conflicting dissolution proposal must (a) start from grep-verified read of existing authority, (b) name the specific authority doc affected, (c) require PM ratification before dispatch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- ...-deferral-anti-pattern-audit-2026-05-11.md | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 01cb4409072..299980f8f39 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -33,7 +33,7 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | 8 | `ClaimResult::NotYetImplemented` | **21** (9 src + 12 tests) | Explicit gate-deferral — per-gate disposition (§3.5): substrate-land OR R3-carve. | | 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). Miss-class; ratified for R3 dissolution per operator 2026-05-11. | | 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | **Authority-conflicting per `INVARIANTS.md:63-66`** — currently load-bearing as BoundedLattice fail-closed bottom. **Requires PM ratification before classification** (Miss-class vs lattice-element); see §3.2. | -| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | Miss-shape candidate; see §3.3. | +| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | **Authority-conflicting per `docs/briefs/r3-substrate-descent-execution-proof-worker.md` Director-ratified γ-shape** — compliant as written today. See §3.3 corrected disposition. | | 12 | `ArrowBody::Pending` / `LensSurfacePending` | 4 enum variants | In-progress states baked into the substrate type; see §3.6 — substantial substrate-shape change, R3-load-bearing-ness needs PM ratification. | | 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — per §3.8, each promotes (R3-load-bearing) or carves (post-R3); not classified as deferral by default. | @@ -48,11 +48,11 @@ Not every instance is equally bad. The taxonomy: Cases where the wrapper variant captures "I don't have an answer" and the answer is required for correctness: - `Lookup::Miss` — already committed to R3 dissolution per operator-ratified 2026-05-11. See §3.1. -- `EvidenceUnknown / EvidenceIncomplete` in descent residual — Miss-shape candidate; see §3.3. - Empty-list-as-Miss in generated code — see §3.4. - `ClaimResult::NotYetImplemented` — explicit deferral of gate execution. See §3.5. - `ArrowBody::Pending` / `LensSurfacePending` — in-progress states baked into substrate type; **substantive substrate-shape change** — see §3.6. - `DescentEvidence::DescentUnknown` — **NOT auto-classified as Miss-class**. Currently load-bearing as BoundedLattice fail-closed bottom per `INVARIANTS.md:63-66`. Requires PM ratification before classification; see §3.2. +- `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual — **NOT auto-classified as Miss-class**. Compliant per Director-ratified γ-shape at `docs/briefs/r3-substrate-descent-execution-proof-worker.md` (ratification at gunbc#828 #issuecomment-4395060514). Any dissolution proposal requires authority-reconciliation precondition; see §3.3 corrected disposition. ### §2.2 Boundary tools used in interior — **triage candidates, NOT uniform "abuse"** @@ -96,11 +96,20 @@ The Mgr-canvas audit (§3.7) should be a **per-file production-flow inventory** Consumer impact (either path): `merge_evidence`, `join_evidence`, `evidence_rank`, etc. in `dag.rs` (the older versions were already retired in earlier Cluster K work) — surviving consumers need to align with whichever path PM ratifies. -### §3.3 Descent-execution-proof residual `EvidenceUnknown / EvidenceIncomplete` — proposed dissolution +### §3.3 Descent-execution-proof residual `EvidenceUnknown / EvidenceIncomplete` — requires authority-reconciliation precondition (NOT direct dissolution) -Currently: `DescentResidual = EvidenceUnknown(NonStrictEvidence) | EvidenceIncomplete`. The work to narrow from 4 to 2 was good, but the residual itself is still a Miss-shape. +**Correction per inline review finding 2026-05-11**: my original framing called the residual "Miss-shape" and proposed replacing the carrier without reconciling against the **Director-ratified residual shape** at `docs/briefs/r3-substrate-descent-execution-proof-worker.md:20-27` (per `r3-program-plan.md` Q-EVAL-Descent-Termination-Contract ratification at gunbc#828 #issuecomment-4395060514). That violates P1 modeling-faithfulness + locked-decision discipline. -Proposal: if descent execution can't complete, that's a typed compile-time Diagnostic at the producer's surface. Replace the residual carrier with `Result` where `DescentExecutionDiagnostic` is a concrete error type (not a Maybe-coverage Maybe-incomplete wrapper). +Currently: `DescentResidual = EvidenceUnknown(NonStrictEvidence) | EvidenceIncomplete`, where the prior 4→2-variant narrowing was specifically the **Director-ratified illegal-states-unrepresentable rationale** (making `EvidenceUnknown(Strict)` unconstructible via the typed `NonStrictEvidence` subset). The residual is not a Miss-class deferral — it's a typed witness of "descent execution attempted, here's why we don't have a per-path Strict witness." The "Miss-shape" framing in my original audit conflated the analyzer's runtime-failure surface with a design-laziness deferral. + +**Pre-dispatch requirement**: any further dissolution proposal on this carrier MUST start from a grep-verified read of: +- `dsl/std/termination.dag` (substrate carrier authority) +- `docs/briefs/r3-substrate-descent-execution-proof-worker.md` (Director-ratified γ-shape rationale) +- `r3-program-plan.md` Q-EVAL-Descent-Termination-Contract (ratification commit) + +And produce: (i) a concrete reason why the existing typed-residual shape is insufficient (i.e., what dispatch-level harm follows from keeping it); (ii) which authority doc would need amendment (if any); (iii) PM ratification before any worker dispatch. + +**As written today**, the residual is compliant per existing Director ratification. The audit was wrong to label it Miss-class. ### §3.4 Empty-list `[] => Lookup::Miss` in generated code (4 sites) @@ -160,7 +169,7 @@ R3-close commitment scope (per operator-directive 2026-05-11). **Dispatch order 1. **§3.1 (cost-lens Miss)** — RATIFIED, dispatched to Substrate Mgr 2026-05-11. 2. **§3.2 (DescentUnknown)** — **BLOCKED on PM ratification of path (a) vs (b)** per §3.2. No dispatch until PM decides whether substrate keeps 3-variant lattice + construction-side narrowing, or authority update precedes 2-variant collapse. Same-batch with §3.1 only valid under path (a); path (b) requires `INVARIANTS.md:63-66` edit landing first. -3. **§3.3 (descent-execution-proof residual)** — propose same-batch dispatch with §3.1 once §3.2 path is ratified (the residual carrier sits downstream of `DescentEvidence` shape). +3. **§3.3 (descent-execution-proof residual)** — **BLOCKED on authority-reconciliation** per §3.3 corrected disposition. The carrier is compliant per Director-ratified γ-shape at `docs/briefs/r3-substrate-descent-execution-proof-worker.md`. Any dissolution requires reading the existing authority + producing a grep-verified reason the typed-residual shape is insufficient, then PM ratification. No same-batch dispatch with §3.1. 4. **§3.4 (empty-list-as-Miss)** — generated-code regen needed; folds into §3.1 + §3.5 dispatch. 5. **§3.5 (NotYetImplemented audit)** — per-gate Mgr-tier dispatch; recommend Verification Mgr re-spawn (currently archived per overnight cascade) authors the audit. 6. **§3.6 (ArrowBody::Pending)** — larger substrate-shape work; **R3-load-bearing-ness needs PM ratification before dispatch** (may need post-R3 carve). @@ -168,7 +177,7 @@ R3-close commitment scope (per operator-directive 2026-05-11). **Dispatch order 8. **§3.8 (structural_coverage_gap)** — promote/carve audit; PM-coordinated. 9. **§4 (review-process)** — PM authors the PR-template ratchet update; cross-Mgr coordination. -**Authority-gate summary**: items 2 (DescentUnknown) and 6 (ArrowBody::Pending) are explicitly PM-blocked until authority disposition. Items 1/3/4/5/7/8/9 may dispatch on the standing Mgr-canvas authority once R3-scope-ratified. +**Authority-gate summary**: items 2 (DescentUnknown), 3 (descent-execution-proof residual), and 6 (ArrowBody::Pending) are explicitly authority-blocked until reconciliation. Items 1/4/5/7/8/9 may dispatch on the standing Mgr-canvas authority once R3-scope-ratified. ## §6. Open questions for PM ratification From 0c07f7a78b7b7e3f9ae729d01a1a3b00c5024dac Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:09:38 +0000 Subject: [PATCH 06/34] =?UTF-8?q?docs(audit):=20address=20inline=20blockin?= =?UTF-8?q?g=20=E2=80=94=20=C2=A73.6=20ArrowBody=20location=20was=20factua?= =?UTF-8?q?lly=20wrong?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per inline review finding at docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md:120 (2026-05-11T21:03:41Z): > "BLOCKING: ArrowBody::Pending is stored on TypeConnective::Arrow.body/ > ResolvedArrow, not Behavior::Transform.body, so §3.6 aims the redesign > at the wrong substrate boundary under P2 facts-flow-forward." Verified at HEAD: - ArrowBody enum at src/v3/compiler/src/dag.rs:1092 - Used in TypeConnective::Arrow { body, .. } patterns (bootstrap.rs:288 etc.) - All ArrowBody::Unparsed sites in bootstrap_generated.rs are inside TypeConnective::Arrow { body: ArrowBody::Unparsed(...), .. } Original §3.6 claim that ArrowBody is on Behavior::Transform.body was wrong. Actual location is declaration-tier type-connective (Declaration.connective = TypeConnective::Arrow { body: ArrowBody::Pending }). Fix: §3.6 reframed. The substrate-shape question is at the declaration-tier type-connective layer, NOT Behavior::Transform. The "paper-over" cost is at the type-connective-walking layer; Behavior walkers already see only resolved bodies. Revised proposal: PM ratification on R3-load-bearing-ness + Substrate Mgr canvas on partition-vs-sum-with-Pending design question, citing M1_DESIGN.md authority + per-walker impact analysis. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../r3-deferral-anti-pattern-audit-2026-05-11.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 299980f8f39..9ea7aa50fb8 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -126,9 +126,16 @@ Per `feedback_construction_over_ratchets` — `NotYetImplemented` is a textual r ### §3.6 `ArrowBody::Pending` / `LensSurfacePending` — in-progress states in substrate -`ArrowBody::Pending` is a `Behavior::Transform.body` variant indicating "this function hasn't been lowered yet." It's a transitional state baked into the substrate type. Consequence: every walker / lens that processes Transform bodies has to handle `Pending` (paper-over). +**Correction per inline review finding 2026-05-11**: my original framing said `ArrowBody::Pending` is on `Behavior::Transform.body`. That's **factually wrong**. Verified via grep at HEAD: +- `ArrowBody` enum lives at `src/v3/compiler/src/dag.rs:1092` +- It's used at `TypeConnective::Arrow { body, .. }` (see `bootstrap.rs:288`) — i.e., on the **type-connective `Arrow` carrier** that lives on `Declaration.connective`, NOT on `Behavior::Transform.body`. +- All `ArrowBody::Unparsed(...)` literal sites in `bootstrap_generated.rs` are inside `TypeConnective::Arrow { body: ArrowBody::Unparsed(...), .. }` patterns. -Proposal: substrate-shape redesign — separate `UnresolvedSignature` (pre-lowering) from `ResolvedTransform` (post-lowering). The lowering pipeline transforms the former into the latter. Walkers / lenses operate on `ResolvedTransform` only. Pending becomes unrepresentable at the post-lowering substrate type level. +So the proposed dissolution (separate `UnresolvedSignature` from `ResolvedTransform`) targets the wrong substrate boundary. The actual boundary is **declaration-tier type-connective**: a `Declaration` whose `connective: TypeConnective::Arrow { body: ArrowBody::Pending }` has had its signature parsed but the body hasn't been lowered to a `Behavior` yet. Walkers that operate on `Behavior::Transform` already see only resolved bodies; the "paper-over" cost is at the type-connective-walking layer, not the Behavior walker layer. + +**Revised proposal**: the substrate-shape question is whether the declaration-tier `TypeConnective::Arrow.body` should be a sum that includes `Pending` (allowing pre-lowering declarations to coexist with post-lowering ones), or whether two separate substrate types should partition the pre-/post-lowering states. This decision lives in the v3 dag substrate authority (`src/v3/M1_DESIGN.md` + `dag.rs`), is substantial substrate-shape work, and per `feedback_substrate_shape_belongs_in_mgr_canvas` belongs in a Substrate Mgr canvas with PM ratification on R3-load-bearing-ness. + +**Pre-dispatch requirement**: PM ratification on R3-load-bearing-ness; Substrate Mgr canvas authoring on the partition-vs-sum-with-Pending design question, citing `M1_DESIGN.md` authority + per-walker impact (which walkers/lenses actually touch the type-connective layer vs only Behavior). ### §3.7 Boundary-tool-in-interior cleanup (1100+ sites) — per-Mgr-canvas audit From c43670e43cf40db5e5ce60d3a189f7c712912796 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:10:56 +0000 Subject: [PATCH 07/34] =?UTF-8?q?docs(audit):=20address=20inline=20blockin?= =?UTF-8?q?g=20=E2=80=94=20LensSurfacePending=20is=20terminal,=20not=20in-?= =?UTF-8?q?progress?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per inline review finding at docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md:37 (2026-05-11T21:03:41Z): > "BLOCKING: LensSurfacePending is a terminal ParallelismUnsupportedKind in > the effects substrate, not an in-progress substrate state, so grouping it > with ArrowBody::Pending needs explicit authority reconciliation before > dispatch under P1 modeling faithfulness." Verified at HEAD: src/v3/compiler/src/dag/effects.rs:197 places LensSurfacePending as a variant of ParallelismUnsupportedKind, explicitly marked 🟢 TERMINAL in code comments. It's an explicit unsupported-reason payload for the parallelism lens, NOT a transitional in-progress state. The "Pending" suffix is misleading. Fix: removed LensSurfacePending from §3.6 (which only covers true pre-lowering transitional state ArrowBody::Pending). Updated §1 table row 12 + §2.1 Miss-class list to explicitly NOT auto-classify it. Removed scope contradiction. Pattern continues from prior corrections: every classification in the audit needs grep-verified factual grounding. Misleading variant names ("Pending" suffix on terminal carriers) are themselves a discipline gap. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) --- .../r3-deferral-anti-pattern-audit-2026-05-11.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 9ea7aa50fb8..2fb69bbf9c1 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -34,7 +34,7 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). Miss-class; ratified for R3 dissolution per operator 2026-05-11. | | 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | **Authority-conflicting per `INVARIANTS.md:63-66`** — currently load-bearing as BoundedLattice fail-closed bottom. **Requires PM ratification before classification** (Miss-class vs lattice-element); see §3.2. | | 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | **Authority-conflicting per `docs/briefs/r3-substrate-descent-execution-proof-worker.md` Director-ratified γ-shape** — compliant as written today. See §3.3 corrected disposition. | -| 12 | `ArrowBody::Pending` / `LensSurfacePending` | 4 enum variants | In-progress states baked into the substrate type; see §3.6 — substantial substrate-shape change, R3-load-bearing-ness needs PM ratification. | +| 12 | `ArrowBody::Pending` | declaration-tier substrate variant | Pre-lowering transitional state on `TypeConnective::Arrow.body`; see §3.6. **Note**: `LensSurfacePending` (originally lumped here) is explicitly **terminal** per `dag/effects.rs:197` (a `ParallelismUnsupportedKind` variant — terminal unsupported-reason payload, NOT a Pending-shape in-progress state). Misleading suffix; do not classify as Miss-class deferral. | | 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — per §3.8, each promotes (R3-load-bearing) or carves (post-R3); not classified as deferral by default. | **Aggregate:** ≈1600+ instances of deferral-shape patterns in the v3 compiler's production surface. The cost-lens `Miss` work is one specific case in a much larger class. @@ -50,7 +50,8 @@ Cases where the wrapper variant captures "I don't have an answer" and the answer - `Lookup::Miss` — already committed to R3 dissolution per operator-ratified 2026-05-11. See §3.1. - Empty-list-as-Miss in generated code — see §3.4. - `ClaimResult::NotYetImplemented` — explicit deferral of gate execution. See §3.5. -- `ArrowBody::Pending` / `LensSurfacePending` — in-progress states baked into substrate type; **substantive substrate-shape change** — see §3.6. +- `ArrowBody::Pending` — pre-lowering transitional state on declaration-tier `TypeConnective::Arrow.body`; **substantive substrate-shape change** — see §3.6. +- `LensSurfacePending` — **NOT auto-classified as Miss-class**. Per `dag/effects.rs:197` (🟢 TERMINAL), this is a `ParallelismUnsupportedKind` variant — terminal unsupported-reason payload, not a Pending-shape in-progress state. Misleading suffix; do not dissolve. - `DescentEvidence::DescentUnknown` — **NOT auto-classified as Miss-class**. Currently load-bearing as BoundedLattice fail-closed bottom per `INVARIANTS.md:63-66`. Requires PM ratification before classification; see §3.2. - `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual — **NOT auto-classified as Miss-class**. Compliant per Director-ratified γ-shape at `docs/briefs/r3-substrate-descent-execution-proof-worker.md` (ratification at gunbc#828 #issuecomment-4395060514). Any dissolution proposal requires authority-reconciliation precondition; see §3.3 corrected disposition. @@ -124,7 +125,13 @@ Each `NotYetImplemented` is a gate-tier deferral. For R3 close: Per `feedback_construction_over_ratchets` — `NotYetImplemented` is a textual ratchet that should dissolve when the predicate substrate lands. -### §3.6 `ArrowBody::Pending` / `LensSurfacePending` — in-progress states in substrate +### §3.6 `ArrowBody::Pending` — pre-lowering transitional state at declaration-tier + +**Scope correction per inline review finding 2026-05-11**: `LensSurfacePending` (originally lumped here) is **terminal**, not in-progress. Per `src/v3/compiler/src/dag/effects.rs:197`, `LensSurfacePending` is a variant of `ParallelismUnsupportedKind` (explicitly marked 🟢 TERMINAL in code comments), representing an explicit unsupported-reason payload for the parallelism lens. The "Pending" suffix is misleading; the variant is a terminal classification ("this case is not supported, here's the named reason"), not a transitional state. It does NOT belong in this section and is removed. + +The remainder of this section applies to `ArrowBody::Pending` only. + + **Correction per inline review finding 2026-05-11**: my original framing said `ArrowBody::Pending` is on `Behavior::Transform.body`. That's **factually wrong**. Verified via grep at HEAD: - `ArrowBody` enum lives at `src/v3/compiler/src/dag.rs:1092` From 0af402fd058d647e30530b04ce52cde2a0b88101 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:16:46 +0000 Subject: [PATCH 08/34] =?UTF-8?q?docs(audit):=20address=20cursor=20NON-BLO?= =?UTF-8?q?CKING=20table=20nits=20=E2=80=94=20rows=20#10/#11=20misattribut?= =?UTF-8?q?ed=20conflict?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per cursor APPROVE_WITH_COMMENTS review at sha 0c07f7a78 (2026-05-11T21:08:35Z): > Row 10/11 phrase 'Authority-conflicting per X' but the cited authority X is > exactly where the standing design is *defined*. The real tension is between > the operator's Miss-elimination directive and that existing authority text, > not 'conflict' within or stated by those authorities themselves. Fix: reframe rows #10/#11 to name the standing authority + locate the tension correctly: - Row 10 (DescentUnknown): standing authority is INVARIANTS.md fail-closed bottom; tension is with operator directive (not within the invariant). - Row 11 (DescentResidual): standing authority is Director-ratified γ-shape; carrier is compliant; my prior audit framing was the conflict, corrected in §3.3. NON-BLOCKING per reviewer but legitimate clarity improvement; reviewer's verdict was APPROVE_WITH_COMMENTS. --- docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 2fb69bbf9c1..9cad13bc477 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -32,8 +32,8 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | 7 | Opaque error types (`Result<*, String>`, `Box`) | **69** | Triage candidate — erases structural failure shape at the type level; Mgr-canvas audit per consumer to determine which warrant typed-Diagnostic conversion. | | 8 | `ClaimResult::NotYetImplemented` | **21** (9 src + 12 tests) | Explicit gate-deferral — per-gate disposition (§3.5): substrate-land OR R3-carve. | | 9 | `Lookup::Miss` variant in generated code | **4 sites** | Empty-list-as-Miss pattern in `lens_cost_symbolic_generated.rs` (3) + `infer_helpers_generated.rs` (1). Miss-class; ratified for R3 dissolution per operator 2026-05-11. | -| 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | **Authority-conflicting per `INVARIANTS.md:63-66`** — currently load-bearing as BoundedLattice fail-closed bottom. **Requires PM ratification before classification** (Miss-class vs lattice-element); see §3.2. | -| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | **Authority-conflicting per `docs/briefs/r3-substrate-descent-execution-proof-worker.md` Director-ratified γ-shape** — compliant as written today. See §3.3 corrected disposition. | +| 10 | `DescentEvidence::DescentUnknown` | substrate lattice bottom | Standing authority: `INVARIANTS.md:63-66` defines this as `BoundedLattice` fail-closed bottom. **Tension** with operator's Miss-elimination directive (2026-05-11) — not internal to the invariant. **Requires PM ratification** to resolve (Miss-class deferral vs load-bearing lattice element); see §3.2. | +| 11 | `EvidenceUnknown / EvidenceIncomplete` in descent_execution_proof residual | substrate residual carrier | Standing authority: `docs/briefs/r3-substrate-descent-execution-proof-worker.md` Director-ratified γ-shape (`r3-program-plan.md` Q-EVAL-Descent-Termination-Contract). **Compliant as written today.** My original audit framing (Miss-class) conflicted with this authority; corrected disposition in §3.3 — any further dissolution requires authority-reconciliation precondition. | | 12 | `ArrowBody::Pending` | declaration-tier substrate variant | Pre-lowering transitional state on `TypeConnective::Arrow.body`; see §3.6. **Note**: `LensSurfacePending` (originally lumped here) is explicitly **terminal** per `dag/effects.rs:197` (a `ParallelismUnsupportedKind` variant — terminal unsupported-reason payload, NOT a Pending-shape in-progress state). Misleading suffix; do not classify as Miss-class deferral. | | 13 | `structural_coverage_gap_*` named gates | **10+** | Tracking-only ratchets — per §3.8, each promotes (R3-load-bearing) or carves (post-R3); not classified as deferral by default. | From f2e3db051badcd3dcd63fc024b2d3e4f385e0624 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:26:31 +0000 Subject: [PATCH 09/34] =?UTF-8?q?docs(audit):=20tighten=20CODING.md=20cita?= =?UTF-8?q?tions=20=E2=80=94=20boundary=20roles=20at=20:311-321,=20not=20:?= =?UTF-8?q?307-309?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per cursor APPROVE_WITH_COMMENTS finding at sha 0af402fd0 (2026-05-11T21:24:39Z): > The notes point boundary-tooling legitimacy at CODING.md:307-309, but those > lines only state the narrow 'Hidden panic surface' rule (library avoids > contract-violation panics/unwrap()). The explicit Bootstrap and > Code-generation binaries edge roles appear under 'When impurity is > acceptable' beginning around CODING.md:311 (table ~317-321). Fix: split the citation so: - CODING.md:307-309 covers the contract-violation-in-library rule (interior substrate-flow panics dissolve to typed Diagnostic per C-8). - CODING.md:311-321 covers the boundary roles legitimacy (Build script / Code-generation binaries / Bootstrap entries in the impurity-acceptable table). Updated table rows #2/#3 (lines 27-28), §2.2 prose (line 66), and §4 review checklist (line 171). NON-BLOCKING per reviewer; landing as documentation hygiene. --- docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index 9cad13bc477..ad9872944f6 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -24,8 +24,8 @@ Grep-verified instances. Each instance is a site where the substrate admits "I d | # | Anti-pattern | Sites | Notes | |---|---|---|---| | 1 | `Option` returns in substrate `dag.rs` | **83** | Triage candidates — but **not** uniformly Miss-class. Per `modeling-discipline.md:41-50` + `CODING.md:95-97`, `Option` is **allowed when absence is a legitimate non-error state**. Miss-class violation = `None`-on-error without a diagnostic write. The 83 sites need per-call audit: which are error-None (Miss-class, must dissolve) vs legitimate-absence (compliant). Don't bulk-convert. | -| 2 | `panic!` calls in production src | **244** | Triage candidates — boundary tooling (regen/bootstrap entrypoints) is legitimate per `CODING.md:307-309`; interior substrate-flow panics dissolve to typed Diagnostic per C-8. Per-site classification (§2.2). | -| 3 | `.expect(...)` calls in production src | **665** | Same boundary-vs-interior triage as #2 per `CODING.md:307-309`. | +| 2 | `panic!` calls in production src | **244** | Triage candidates — boundary tooling (regen/bootstrap entrypoints) is legitimate per `CODING.md:311-321` ("When impurity is acceptable" — Build script / Code-generation binaries / Bootstrap roles in table); interior substrate-flow panics are contract violations per `CODING.md:307-309` and dissolve to typed Diagnostic per C-8. Per-site classification (§2.2). | +| 3 | `.expect(...)` calls in production src | **665** | Same boundary-vs-interior triage as #2 — boundary role legitimacy from `CODING.md:311-321`; interior contract-violation rule at `CODING.md:307-309`. | | 4 | `.unwrap()` calls in production src | **35** | Same boundary-vs-interior triage as #2. | | 5 | Catch-all `_ =>` match arms | **406** | Triage — distinguishes closed-enum non-exhaustiveness (must dissolve) from deliberate default-arm on open enums or terminal "shouldn't happen" arms paired with explicit Diagnostic. Per-site review. | | 6 | `todo!() / unimplemented!() / unreachable!()` macros | **43** | Triage — `unreachable!()` paired with an invariant proof is legitimate; `todo!()` / `unimplemented!()` are explicit deferrals. Per-site disposition (§2.2). | @@ -63,7 +63,7 @@ Triage candidates (per-site audit, not bulk-conversion): - 83 `Option` returns in `dag.rs` — classify: error-None (must dissolve) vs legitimate-absence (compliant per `modeling-discipline.md:49-50`). - 244 `panic!` calls — classify: boundary-tooling (regen, bootstrap, setup; legitimate) vs interior substrate flow (must dissolve to typed Diagnostic per C-8). -- 665 `.expect()` / 35 `.unwrap()` calls — same as panic: per `CODING.md:307-309`, panics/unwraps in library code are contract violations; the boundary subset (regen entrypoints) is acceptable. +- 665 `.expect()` / 35 `.unwrap()` calls — same as panic: per `CODING.md:307-309`, panics/unwraps in library code are contract violations; the boundary subset (regen / build-script / bootstrap entrypoints) is acceptable per `CODING.md:311-321` ("When impurity is acceptable" table). - 69 opaque `Result<*, String>` / `Box` — erases structural failure shape; Mgr-canvas audit per consumer. - 406 catch-all `_ =>` match arms — each one needs review: does it admit non-exhaustiveness, or is it deliberate fall-through (e.g., default-arm for an open enum)? - 43 `todo!() / unimplemented!() / unreachable!()` macros — explicit deferral; per-site disposition. @@ -168,7 +168,7 @@ Operator notes: "this is me slacking — things like this should really be escal Proposal: extend the PR review checklist (per `feedback_pre_authored_brief_queue` discipline) with **anti-pattern justification callouts** — flag for JUSTIFICATION review, not for "convert by default": 1. Does this PR add a new `Option` return in substrate-tier code? → flag for **justification**: is absence a meaningful structural state (compliant per `modeling-discipline.md:49-50` + `CODING.md:95-97`), or is it error-None deferring a diagnostic write? Reviewer asks; author justifies; non-compliant cases convert. -2. Does this PR add a new `panic!` / `.expect()` / `.unwrap()` in **library / substrate-flow** code (not in regen/bootstrap entrypoints)? → flag for Diagnostic-conversion review per `CODING.md:307-309`. +2. Does this PR add a new `panic!` / `.expect()` / `.unwrap()` in **library / substrate-flow** code (not in the boundary roles listed at `CODING.md:311-321` — Build script / Code-generation binaries / Bootstrap)? → flag for Diagnostic-conversion review per `CODING.md:307-309`. 3. Does this PR add a new enum variant whose name contains `Unknown / Pending / Missing / Incomplete / Maybe`? → flag for **construction-impossibility OR fail-closed-lattice review**: is the variant a deferral surface (must dissolve) or a load-bearing lattice element (compliant per `INVARIANTS.md` authority)? 4. Does this PR add a `NotYetImplemented` predicate? → flag for substrate-readiness review. 5. Does this PR add a new `_ =>` catch-all in an enum match? → flag for **exhaustiveness OR deliberate-default review**: is the enum closed (catch-all admits non-exhaustiveness) or open (catch-all is the default arm)? From 5e004ca296b6555e7714e17f8d8afa3acbebb68d Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:49:45 +0000 Subject: [PATCH 10/34] =?UTF-8?q?docs(audit):=20add=20=C2=A73.8.1=20concre?= =?UTF-8?q?te=2010-entry=20NON=5FTEST=20inventory=20per=20velocity-walk?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per PM ratification (msg_45457c77 in response to Director ask msg_048fdfa6): empirical-grounding-strengthens-the-case path. §3.8 currently treats structural_coverage_gap audit as abstract pattern; with zesty-boar-261's velocity-walk diagnostic (gunbc#846 c#4425420798) producing a 9 NON_TEST + 1 FRAGMENTS enumerated inventory over the 7d window pre-2026-05-11, §3.8 graduates from speculative to grounded. Adds §3.8.1 with: - 10-entry table: file path + LOC + adjacent-lane/dissolution-path mapping - Total 2,171 LOC; omni_shape_b_openapi.rs identified as ~40% of class - Audit implication: per-file promote-or-carve discipline applies - Per-PR review state-space framing (Director conformance read flags absent dissolution-path mapping) - Re-audit cadence note (this is window-relative intro composition, not full main §3.8 audit; per feedback_intro_rate_not_residual_share) Citations grep-verified at HEAD eed86ffc9: all 9 NON_TEST files exist with stated LOC; FRAGMENTS entry confirmed in sg0_census_test.rs:688-691. --- ...-deferral-anti-pattern-audit-2026-05-11.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md index ad9872944f6..0a285d4b63d 100644 --- a/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md +++ b/docs/audit/r3-deferral-anti-pattern-audit-2026-05-11.md @@ -161,6 +161,35 @@ Per-file canvas authoring expected; not a single PR. - Load-bearing for R3: close in R3 cycle - Not load-bearing: explicit carve to post-R3 (no silent tracking) +### §3.8.1 Concrete inventory (per velocity-walk 7d window 2026-05-04 → 2026-05-11) + +Per Debt-Paydown Mgr's velocity-walk diagnostic (gunbc#846 c#4425420798; zesty-boar-261 msg_6774c4c1 + format-fix msg_9182e746), the introduction-class composition over the 7d window pre-2026-05-11 (anchor `04fa1ed47` → HEAD `eed86ffc9`) included **9 NON_TEST + 1 FRAGMENTS genuinely-net-new compiler-surface entries** matching the §3.7/§3.8 pattern ("we did it in Rust because the substrate path wasn't ready yet"). Per PM read at gunbc#828: "every one is a 'we did it in Rust because the substrate path wasn't ready yet' pattern, which is exactly what §3.7 boundary-tools cleanup + §3.8 structural-coverage-gap audit are designed to catch." + +This is the **concrete observable** that grounds §3.8 from abstract pattern to enumerated audit target. + +| # | File | LOC | Adjacent lane / dissolution path | +|---|---|---:|---| +| 1 | `src/v3/compiler/src/omni_shape_b_openapi.rs` | 842 | cross_target_coverage substrate or emit-spec extdeps (highest-signal single dissolution target — ~40% of class LOC) | +| 2 | `src/v3/compiler/src/enforced_lens_application.rs` | 400 | T-LensProducer-Retirement adjacent; lens-application substrate landing | +| 3 | `src/v3/compiler/src/r3_fc_lane2_loop_witness.rs` | 278 | Free-Consequences gate dissolution (transient demo evidence) | +| 4 | `src/v3/compiler/src/emit/collection_ops_method_contract.rs` | 183 | cross_target_coverage substrate or emit-spec extdeps | +| 5 | `src/v3/compiler/src/cost_basis_declaration.rs` | 165 | T-CostLens-Composition (#37/#40/#70 lineage) | +| 6 | `src/v3/compiler/src/memory_peak_cost.rs` | 132 | T-CostLens-Composition adjacent | +| 7 | `src/v3/compiler/src/complexity_lattice.rs` | 109 | Lens-substrate (complexity dimension); aligned with `ComplexitySummary` lifecycle | +| 8 | `src/v3/compiler/src/lens_t_las_carrier.rs` | 53 | T-LAS lens-application substrate landing | +| 9 | `src/v3/compiler/src/bin/regen_tokenize.rs` | 9 | gate #7 PB-1 bin-shim lineage (`.dag`-driven regen) | +| 10 | `src/v3/compiler/src/lens_testgen_body.txt` (FRAGMENTS) | — | gate #6 sub-gate 2 lineage (per PR #2680 retirement path) | + +**Total**: 2,171 LOC across 9 NON_TEST files + 1 FRAGMENTS file. Grep-verified at HEAD `eed86ffc9` (2026-05-11). + +**Audit implication**: each entry has a named adjacent lane / dissolution path. §3.8's promote-or-carve discipline applies per-file: +- **Load-bearing for R3**: dissolution lane must close within R3 cycle. If R3 close is reached with the entry still present, the file's adjacent gate hasn't closed. +- **Not load-bearing**: file must be explicitly carved post-R3 with the adjacent gate carve, not silently tracked. + +The 10-entry set is the **per-PR review state-space for Director-tier discipline** (per audit §4 + §6 process implication): any future PR extending one of these files, refactoring within the same pattern, or — worst case — adding a same-pattern net-new sibling file (e.g., `complexity_lattice_v2.rs`) must surface the relevant dissolution-path mapping in the PR body. Director conformance read flags absent dissolution-path mapping as a §3.8 violation. + +**Re-audit cadence**: this inventory should be re-baselined per major velocity-walk window. Window-relative intro-class composition diverges from R3-close residual-inventory composition (per `feedback_intro_rate_not_residual_share`); the 7d window here captures the load-bearing slice of recent introduction-rate but does NOT enumerate the full §3.8 audit set on main. A full-main §3.8 audit (scoping all `EXPECTED_HAND_AUTHORED_NON_TEST` entries against their adjacent lanes) is post-R3-process work and out of scope for this audit doc. + ## §4. Process implication — why review didn't catch this Operator notes: "this is me slacking — things like this should really be escalated/caught during review." Review-tier process gap. From 64776ea121003464a2606bf5ea38eb580d51beff Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:54:44 +0000 Subject: [PATCH 11/34] docs(briefs): Director scaffold-fill for Cluster M Phase 3 reflected-Dag + DimensionReport bulk-port worker briefs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per feedback_pre_authored_brief_queue + feedback_director_mgr_energy_input (Director energy INTO system until real workflow substrate exists). Verification Mgr (clever-tern-670) status pass (msg_755c3f43) identified Phase 3 dissolution-rate bottleneck as Mgr-tier brief-authoring bandwidth on the two biggest unauthored classes: - Reflected-Dag structural assertion family (~25-30 entries; 16 seed-named) - Generic DimensionReport / runner-discipline family (~20-25 entries; 10 seed-named) These ~50 entries combined are roughly half of the #84 EXPECTED_HAND_AUTHORED_TEST partition (116 entries on origin/main eed86ffc9). Authoring scaffolds + Mgr finalization + dispatch should land bulk-port PRs within 7-10 days, with velocity-tripwire arrow (12.7:1 intros:dissolves at gunbc#846 c#4425420798) flipping intra-week. Authority split per Director msg_eb2372c7 to PM: - Director: scaffold shape (this commit) — locked-design citations, substrate carrier references at exact lines, Phase-2 pattern site refs, hard constraints, STOP-and-escalate criteria, decomposition recommendations. - Verification Mgr: finalization — complete inventory (Mgr-fill placeholders marked throughout), per-entry classification, pilot selection, dispatch. Substrate citations grep-verified via Verification Mgr msg_755c3f43: - ProgramGenerator/ProgramShape/Quantifier/QuantifiedTestClaim/SuiteClaim: src/v3/std/verification.dag:118-133 + :379-402 (carriers landed) - TestSuite.claims still List: verification.dag:404-407 (staged trigger at :394-399) — Reflected-Dag class CONSUMER-GATED on this flip - Phase-2 pattern: t_pb_b_1_dag_runner_test.rs:257-357 (R3_GATE_87_CEMENTING_REGEN_SUITES, run_suite_all_pass_with_expected_claim_names) - Receipt discipline: r3_gate_87_lens_cementing_regen_receipts_test.rs:13-24 + :122-132 - DimensionReport class NOT consumer-gated (Phase-2 pattern is the load-bearing predicate, not full #87 PASSING, per feedback_construction_over_ratchets) --- ...class-generic-dimreport-bulkport-worker.md | 122 ++++++++++++++++++ ...-84-class-reflected-dag-bulkport-worker.md | 110 ++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 docs/briefs/r3-v-cluster-m-84-class-generic-dimreport-bulkport-worker.md create mode 100644 docs/briefs/r3-v-cluster-m-84-class-reflected-dag-bulkport-worker.md diff --git a/docs/briefs/r3-v-cluster-m-84-class-generic-dimreport-bulkport-worker.md b/docs/briefs/r3-v-cluster-m-84-class-generic-dimreport-bulkport-worker.md new file mode 100644 index 00000000000..e48ad86d65c --- /dev/null +++ b/docs/briefs/r3-v-cluster-m-84-class-generic-dimreport-bulkport-worker.md @@ -0,0 +1,122 @@ +# R3 Cluster M Phase 3 — Generic DimensionReport / Runner-Discipline Family Bulk-Port Worker Brief + +**Status:** DIRECTOR-SCAFFOLD (authored under standing authority per `feedback_director_mgr_energy_input` 2026-05-11; awaiting Mgr-tier finalization). **NOT CONSUMER-GATED** — Phase-2 runner-side TestClaim pattern landed via PR #2639 (CONSUMER_LANDED; full #87 PASSING not required for this class per `feedback_construction_over_ratchets` ratification at Director msg_eb2372c7). + +**Owner:** worker TBD on dispatch. **Coordinator:** R3 Verification Mgr (`clever-tern-670`). **Authority chain:** Director scaffold-fill (zesty-bear-812 msg_eb2372c7) → Verification Mgr finalization → auto-spawn dispatch. + +**Authority (cite-and-execute):** +- Phase 3 coordinator: [`r3-v-cluster-m-84-bulkport-coordinator.md`](r3-v-cluster-m-84-bulkport-coordinator.md) §2 row "Generic DimensionReport / runner-discipline family" +- Locked design: [`docs/design-tests-as-data-completeness.md`](../design-tests-as-data-completeness.md) §3 migration audit + §5 cementing + §6 implementation order +- Phase-2 pattern site (load-bearing reference): `src/v3/compiler/tests/integration/t_pb_b_1_dag_runner_test.rs:257-357` (`R3_GATE_87_CEMENTING_REGEN_SUITES`, derived inventory, `run_suite_all_pass_with_expected_claim_names`) +- Phase-2 receipt-discipline site: `src/v3/compiler/tests/integration/r3_gate_87_lens_cementing_regen_receipts_test.rs:13-24` (P5 receipt discipline) + `:122-132` (registry names match fixture inventory) +- Associated `.dag` harnesses: `src/v3/compiler/tests/dag/t_r3_gate_87_cementing_regen_*.dag` +- Census authority: `src/v3/compiler/tests/integration/sg0_census_test.rs:573-583` (free-consequences batches), `:639-655` (TC1/TC2/TC3 Pattern-A DimensionReport), `:584-587` (paired Rust receipt) +- Director Ask 4 ratification: strict-zero close + +--- + +## §0. Scope + +Migrate the **generic DimensionReport / runner-discipline family** — Rust integration tests that wrap `.dag` `TestClaim` evaluation via the runner-side discipline (suite enumeration, derived inventory, expected-claim-names match) — to extend the Phase-2 pattern landed at PR #2639 across the full DimensionReport surface. + +**Seed inventory (10 of estimated 20-25 entries; Mgr finalizes full list)** per Verification Mgr msg_755c3f43: + +Primary census anchors: `sg0_census_test.rs:573-583` (free-consequences), `:639-655` (TC1/TC2/TC3 Pattern-A), `:584-587` (paired Rust receipt), runner-side at `t_pb_b_1_dag_runner_test.rs:257-357`. + +| # | File (under `src/v3/compiler/tests/integration/`) | Class shape | +|---|---|---| +| 1 | `r3_free_consequences_first_batch_test.rs` | Free-Consequences DimensionReport | +| 2 | `r3_free_consequences_second_batch_test.rs` | Free-Consequences DimensionReport | +| 3 | `tc1_substrate_lens_eta_equivalence_deferred_test.rs` | TC1 Pattern-A DimensionReport (deferred) | +| 4 | `tc1_substrate_lens_eta_equivalence_strict_fire_test.rs` | TC1 Pattern-A DimensionReport (strict-fire) | +| 5 | `tc2_church_rosser_strict_fire_test.rs` | TC2 Pattern-A DimensionReport (strict-fire) | +| 6 | `tc3_strong_normalization_deferred_test.rs` | TC3 Pattern-A DimensionReport (deferred) | +| 7 | `tc3_strong_normalization_strict_fire_test.rs` | TC3 Pattern-A DimensionReport (strict-fire) | +| 8 | `test_runner_test.rs` | Runner-discipline framework | +| 9 | `t_pb_b_1_dag_runner_test.rs` | Runner-side #87 table pattern (Phase-2 reference; **may stay as runner-side scaffolding** — see §3.2) | +| 10 | `r3_gate_87_lens_cementing_regen_receipts_test.rs` | Phase-2 receipt-discipline reference (**likely stays** as Phase-2 pattern site) | + +**[Mgr-fill]: full 20-25 entry list** — runner-discipline framework entries (test_runner_test.rs lineage) and remaining TC4-TC7 / TC-X DimensionReport tests fill the residual. + +## §1. Migration pattern (extend Phase-2 PR #2639 receipt) + +Phase-2 pattern at `t_pb_b_1_dag_runner_test.rs:257-357` established the canonical shape: +1. `.dag` declares the `TestClaim` (e.g., `cementing_regen_cost_target_realization_runs_all_pass`) +2. Runner-side derives inventory from `.dag` suite enumeration +3. `run_suite_all_pass_with_expected_claim_names(...)` evaluates the suite + checks registry names match fixture inventory +4. Receipt-discipline at `r3_gate_87_lens_cementing_regen_receipts_test.rs:13-24` proves P5 receipt parity + +**Worker action per entry**: +- Extract the DimensionReport assertion from the hand-Rust test +- Express as `.dag` `TestClaim` under `src/v3/compiler/tests/dag/` (matching the `t_r3_gate_87_cementing_regen_*.dag` shape) +- Add the suite to the runner-side enumeration (extending the `R3_GATE_87_CEMENTING_REGEN_SUITES` pattern with a class-appropriate constant — `R3_FREE_CONSEQUENCES_SUITES`, `R3_TC_DIMREPORT_SUITES`, etc.) +- Delete the hand-Rust `_test.rs` file +- Update SG-0 census (remove entry from `EXPECTED_HAND_AUTHORED_TEST`) + +**[Mgr-fill]: per-entry migration shape detail** — TC1/TC2/TC3 deferred-vs-strict-fire variants may share suite enumeration; Free-Consequences first/second-batch may bundle. + +## §2. Phase-2 pattern reuse vs extension + +The Phase-2 pattern landed for the **cementing-test family** (#87 lineage). This brief extends it to the DimensionReport class. Two extension axes: + +**(a) Mechanical extension** (most entries): same `run_suite_all_pass_with_expected_claim_names` shape; new `_SUITES` constant per class; `.dag` `TestClaim` matches existing fixture inventory pattern. + +**(b) Suite-enumeration extension** (some entries): if the runner-side derived inventory needs to grow beyond `R3_GATE_87_CEMENTING_REGEN_SUITES`, the suite-enumeration discipline itself extends. This is **runner-substrate work** — escalate to coordinator if scope exceeds mechanical extension. + +## §3. Hard constraints + +1. **Phase-2 pattern is the load-bearing predicate** — do not invent a new TestClaim or runner discipline. If the existing pattern doesn't cover an entry's assertion shape, STOP and escalate. + +2. **Two entries likely STAY as runner-side scaffolding** (not migrated; the framework itself): + - `t_pb_b_1_dag_runner_test.rs` — the runner framework that hosts all the migrated suites (this file is the consumer; cannot port itself) + - `r3_gate_87_lens_cementing_regen_receipts_test.rs` — Phase-2 receipt-discipline reference + + These entries should be flagged in the Mgr-finalization step as "Cluster M scope expansion required" — they need a separate decision per Director Ask 4 ratification (NOT closure-allowed; if they cannot migrate, the scope expands to find a path, NOT carve). + +3. **Hand-Rust budget: zero net** (subject to §3.2). Each migration deletes a `_test.rs` file. The 2 framework-class entries (§3.2) are out-of-scope for THIS bulk-port; they need substrate-shape resolution. + +4. **`.dag` TestClaim under `src/v3/compiler/tests/dag/`** matching the `t_r3_gate_87_cementing_regen_*.dag` naming convention (e.g., `t_r3_free_consequences_first_batch.dag`, `t_r3_tc1_strict_fire.dag`). + +5. **Behavioral fidelity** — DimensionReport assertion verdicts must match. Lane-Mgr signoff (Free-Consequences lane / TC-class lane) on the PR. + +6. **No closure-allowed carve-outs** per Director Ask 4. If §3.2 framework entries cannot migrate, that's a Coordinator escalation, not a per-test exception. + +## §4. Acceptance + +The bulk-port PR-set is acceptable when: +- `EXPECTED_HAND_AUTHORED_TEST` SG-0 census decreases by **N** (one per migrated entry; 18-23 for full class minus the 2 framework entries from §3.2) +- Each migrated entry has a corresponding `.dag` `TestClaim` under `tests/dag/` evaluating to the same Pass/Fail verdict as the original Rust assertion +- Runner-side suite enumeration constants extend cleanly (no parallel suite-enumeration mechanisms introduced) +- Receipt-discipline (per Phase-2 pattern) preserved +- Lane-Mgr signoff on behavioral fidelity +- 2 framework-class entries (§3.2) explicitly noted in PR body as scope-expansion candidates + +## §5. Decomposition + +Recommended split (subject to Mgr judgment): +- **Pilot** (1-2 entries): pick the most Phase-2-pattern-uniform (e.g., `tc1_substrate_lens_eta_equivalence_strict_fire_test.rs` — Pattern-A DimensionReport, single suite); validate mechanical extension shape +- **TC-family wave** (5-7 entries): TC1/TC2/TC3 deferred + strict-fire variants in parallel; shared suite enumeration likely +- **Free-Consequences wave** (2-4 entries): first/second-batch pairing; possibly bundles with TC-X residuals +- **Long-tail / runner-discipline wave** (remaining): escalate per §3.2 framework decisions +- **Framework decision** (2 entries from §3.2): coordinator-tier escalation; NOT in mechanical bulk-port scope + +## §6. STOP and escalate + +Escalate via dashboard-message to Verification Mgr if: +- An entry's assertion shape can't extend Phase-2 pattern mechanically (substrate gap) +- Runner-side suite enumeration would need to gain a new discipline (out-of-scope substrate work) +- Framework entries (§3.2) need migration path — Coordinator decides on scope expansion vs runner-side scaffolding hold +- A `.dag` TestClaim cannot express the DimensionReport assertion +- SG-0 census wouldn't decrease + +Do not push a workaround PR for any of these. + +--- + +**Mgr-finalization checklist** (before flipping to PRE-AUTH DISPATCH-READY): +- [ ] Complete 20-25 entry inventory (sweep TC4-TC7 / TC-X DimensionReport residuals; runner-discipline framework files) +- [ ] Per-entry classification: mechanical extension vs framework-scope-expansion +- [ ] §3.2 framework-entries decision — Coordinator escalation path determined +- [ ] Pilot dispatch selection (1-2 entries; recommend TC1 strict-fire as canonical mechanical extension) + +**End of scaffold.** Director-tier shape established + Phase-2 pattern citations grounded in PR #2639 / `t_pb_b_1_dag_runner_test.rs` / `r3_gate_87_*` references; Mgr fills inventory + per-entry classification + pilot selection. diff --git a/docs/briefs/r3-v-cluster-m-84-class-reflected-dag-bulkport-worker.md b/docs/briefs/r3-v-cluster-m-84-class-reflected-dag-bulkport-worker.md new file mode 100644 index 00000000000..1e412503919 --- /dev/null +++ b/docs/briefs/r3-v-cluster-m-84-class-reflected-dag-bulkport-worker.md @@ -0,0 +1,110 @@ +# R3 Cluster M Phase 3 — Reflected-Dag Structural Assertion Family Bulk-Port Worker Brief + +**Status:** DIRECTOR-SCAFFOLD (authored under standing authority per `feedback_director_mgr_energy_input` 2026-05-11; awaiting Mgr-tier finalization). **CONSUMER-GATED** on `TestSuite.claims` flip from `List` → `List` (staged trigger at `src/v3/std/verification.dag:394-399`); substrate carriers are landed (per Verification Mgr `clever-tern-670` msg_755c3f43). + +**Owner:** worker TBD on dispatch. **Coordinator:** R3 Verification Mgr (`clever-tern-670`). **Authority chain:** Director scaffold-fill (zesty-bear-812 msg_eb2372c7) → Verification Mgr finalization → auto-spawn dispatch. + +**Authority (cite-and-execute):** +- Phase 3 coordinator: [`r3-v-cluster-m-84-bulkport-coordinator.md`](r3-v-cluster-m-84-bulkport-coordinator.md) §2 row "Reflected-Dag structural assertion family" +- Locked design: [`docs/design-tests-as-data-completeness.md`](../design-tests-as-data-completeness.md) §2.1 (ProgramGenerator consumer pattern) + §3 migration audit + §6 implementation order +- Substrate carriers (landed): `src/v3/std/verification.dag:118-133` (`ProgramGenerator`, `ProgramShape`); `src/v3/std/verification.dag:379-402` (`Quantifier`, `QuantifiedTestClaim`, `SuiteClaim`) +- Census authority: `src/v3/compiler/tests/integration/sg0_census_test.rs` (line ranges in §0 below) +- Director Ask 4 ratification: strict-zero close (no closure-allowed exceptions); SG-0 `EXPECTED_HAND_AUTHORED_TEST` = 0 +- Sequencing plan: [`docs/audit/r3-cluster-m-sequencing-plan-2026-05-09.md`](../audit/r3-cluster-m-sequencing-plan-2026-05-09.md) §5.2 + +--- + +## §0. Scope + +Migrate the **reflected-Dag structural assertion family** — Rust integration tests that observe structural facts (filename existence, std/ row authority, substrate carrier shape, bootstrap reflection) — to `.dag` TestClaim form so the assertion becomes data not code. + +**Seed inventory (16 of estimated 25-30 entries; Mgr finalizes full list)** per Verification Mgr msg_755c3f43: + +Primary census comment blocks: `sg0_census_test.rs:370-378` (`cross_target_coverage_carrier_test`), `461-528` (lens/method/projection family), adjacent reflected/std rows at `622-632` + `659-667`. + +| # | File (under `src/v3/compiler/tests/integration/`) | Reflection target | +|---|---|---| +| 1 | `cross_target_coverage_carrier_test.rs` | substrate carrier shape | +| 2 | `lens_substrate_carrier_test.rs` | lens-substrate carrier | +| 3 | `method_registry_test.rs` | method-registry authority | +| 4 | `method_template_contract_test.rs` | method-template contract | +| 5 | `pb_method_template_projection_test.rs` | PB method-template projection | +| 6 | `services_carrier_shape_test.rs` | service carrier shape | +| 7 | `sg1_tokenize_authority_test.rs` | tokenize authority row | +| 8 | `sg2_parse_authority_test.rs` | parse authority row | +| 9 | `sg2c1_parse_tables_authority_test.rs` | parse-tables authority | +| 10 | `sg2c5_soft_keyword_ident_test.rs` | soft-keyword identifier | +| 11 | `sg3_lower_parse_surface_stack_test.rs` | lower parse-surface stack | +| 12 | `sg3_surface_reflection_consumer_test.rs` | surface-reflection consumer | +| 13 | `sg6_hand_authored_census_test.rs` | hand-authored census (self-referential) | +| 14 | `sg7_prep_variant_payload_freshness_test.rs` | prep variant-payload freshness | +| 15 | `timing_lens_substrate_carrier_test.rs` | timing-lens substrate carrier | +| 16 | `value_body_substrate_mirror_isomorphism_test.rs` | value-body substrate-mirror isomorphism | + +**[Mgr-fill]: full 25-30 entry list** — L1/M1/M2 substrate/lens migration tests likely round out the class; second-pass sweep required before final dispatch. + +## §1. Migration pattern + +Each test asserts a **structural fact** that can be re-expressed as a `TestClaim` consuming the landed `ProgramGenerator` / `ProgramShape` / `QuantifiedTestClaim` substrate (post-`TestSuite.claims` flip). + +Migration shape per locked design §2.1: +- Identify the structural observable (e.g., "every `lens_*.dag` declares a `LensRegistryEntry`") +- Express as `QuantifiedTestClaim` with appropriate `Quantifier` (`ForAll` / `Exists`) +- Wrap the test program as `ProgramShape` via `ProgramGenerator` +- Replace hand-Rust `assert_eq!`/`assert!` with the `.dag` `TestClaim` evaluation + +Each entry's specific migration shape **[Mgr-fill]** — depends on which structural axis the test observes. + +## §2. CONSUMER-GATED status + +Per Verification Mgr status pass (msg_755c3f43): +- ✓ `ProgramGenerator`, `ProgramShape`, `Quantifier`, `QuantifiedTestClaim`, `SuiteClaim` carriers **landed** in `src/v3/std/verification.dag` +- ✗ `TestSuite.claims` field still typed `List` (not `List`) at `verification.dag:404-407`; staged trigger at `:394-399` +- ✗ Bootstrap verification of full wrapper/runner path exists in `m1_5_verification_test.rs:81-111` but full consumer pipeline not yet flipped + +**Worker action**: STOP and PING via dashboard-message to Verification Mgr if migration of a specific entry requires the `List` consumer path before it lands. The first 1-2 entries should be dispatched as **pilots** to validate the migration pattern under the current substrate state; full-class parallel dispatch waits for the consumer-flip event. + +## §3. Hard constraints + +1. **No new substrate carriers.** Use the landed `ProgramGenerator` / `ProgramShape` / `Quantifier` / `QuantifiedTestClaim` / `SuiteClaim` set. New carrier requests STOP-and-PING to Coordinator. +2. **Hand-Rust budget: zero.** Each migration deletes a `_test.rs` file (SG-0 decrement = `-N`). Net positive hand-Rust additions are a worker-stop signal. +3. **`.dag` TestClaim under `src/v3/compiler/tests/dag/`** — the migrated test lives in `.dag` form. +4. **No closure-allowed carve-outs** (per Director Ask 4 ratification). If a specific entry cannot migrate, escalate as Cluster M scope expansion (substrate-shape ask), NOT as a per-test exception. +5. **Behavioral fidelity required**: each migration preserves the exact structural assertion behavior. Lane-Mgr signoff per Phase 3 coordinator §0 (Verification Mgr coordinates; lane Mgrs review fidelity). + +## §4. Acceptance + +The bulk-port PR-set is acceptable when: +- `EXPECTED_HAND_AUTHORED_TEST` SG-0 census decreases by **N** (one per migrated entry; 25-30 for full class) +- Each migrated entry has a corresponding `.dag` `TestClaim` evaluating to the same Pass/Fail verdict as the original Rust assertion +- Lane-Mgr (per-test-owning lane) signs off on behavioral fidelity in the PR +- No new substrate carriers introduced +- The deleted `_test.rs` paths are removed from `EXPECTED_HAND_AUTHORED_TEST` in the same PR + +## §5. Decomposition + +Recommended split (subject to Mgr judgment per Phase 3 dispatch latency observations): +- **Pilot wave** (3-5 entries): pick the most reflective-shape-uniform tests (e.g., `sg1_tokenize_authority_test.rs`, `sg2_parse_authority_test.rs`, `sg2c1_parse_tables_authority_test.rs` — SG-row authority assertions follow a single pattern) +- **Class wave** (10-15 entries): parallel-dispatch by sub-axis (carrier-shape vs row-authority vs reflection-consumer) +- **Long-tail** (remaining): per-entry escalation review if migration requires substrate shape + +## §6. STOP and escalate + +Escalate via dashboard-message to Verification Mgr if: +- A migration requires the `TestSuite.claims = List` consumer path before consumer-flip event +- A migration requires a new substrate carrier +- A `.dag` TestClaim cannot express the structural assertion (substrate gap) +- A migration triggers behavioral drift (lane-Mgr signoff fails) +- SG-0 census wouldn't decrease (net-zero or positive delta) — this means migration shape is wrong + +Do not push a workaround PR for any of these. + +--- + +**Mgr-finalization checklist** (before flipping to PRE-AUTH DISPATCH-READY): +- [ ] Complete the 25-30 entry inventory (sweep L1/M1/M2 substrate/lens migration tests) +- [ ] Per-entry assertion-shape classification (carrier-shape vs row-authority vs reflection-consumer) +- [ ] Pilot wave selection (3-5 entries) + first-PR dispatch +- [ ] Confirm consumer-flip event timeline with Substrate Mgr (`warm-wolf-698`) for the post-pilot waves + +**End of scaffold.** Director-tier shape established; Mgr fills inventory + per-entry detail + pilot selection. From 04c5b0895f7c6a1b9bcbbba7cad8be504fb9f6cd Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 22:55:51 +0000 Subject: [PATCH 12/34] docs(briefs): Director scaffold-fill for R3 CI Layer 2 path-conditional gating MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per PM ratification at gunbc#828 c4425726922 + Director ratification msg_a77c7f42 (Verification Mgr routing per feedback_parallel_representation_debt coherence). Bridge-debt with named dissolution trigger: when gate ci_uses_provable_minimal_affected_set_selection lands, the affected-set Introspect-lens output (canvas PR #2713) replaces the bridge's required_paths_regex column. Brief covers: - §0 scope: extend PR #2718's changes job, do not parallel - §1 mechanism: per-group skip_* boolean outputs + STEP-level if: on v3 - §2 inventory sources (slow-test-exemptions.txt + /tmp/v3-test-timings.log + NEW per-group required-paths mapping) - §3 per-dimension structural target — every entry has dimension: Dimension field matching lens enum (parallel-representation-debt prevention) - §4 hard constraints (8 invariants) - §5 acceptance - §6 decomposition (Mgr-fill recommendation: cost_lens pilot first) - §7 STOP-and-escalate criteria - §8 bridge-debt + dissolution path explicit Verification Mgr (clever-tern-670) fills inventory + per-group regex + dispatch. Director scaffold preserves coherence; Mgr finalizes per feedback_director_mgr_energy_input. --- ...-layer-2-path-conditional-gating-worker.md | 223 ++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md new file mode 100644 index 00000000000..c4029b2c2ea --- /dev/null +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -0,0 +1,223 @@ +# R3 CI Layer 2 — Per-test path-conditional gating worker brief + +**Status:** DIRECTOR-SCAFFOLD (authored under standing authority per `feedback_director_mgr_energy_input` 2026-05-11; awaiting Verification Mgr finalization). **Bridge-debt** with named dissolution trigger. + +**Owner:** worker TBD on dispatch. **Coordinator:** R3 Verification Mgr (`clever-tern-670`). **Authority chain:** PM ratification (msg_45457c77 + GitHub inbox c4425726922) → Director ratification (msg_a77c7f42; routing Verification Mgr per parallel-representation-debt coherence) → Verification Mgr finalization → auto-spawn dispatch. + +**Authority (cite-and-execute):** +- **Operator escalation**: Brian's CI-up-to-1-hour framing at gunbc#846 2026-05-11 ("their CI is up to 1 hour ... not happening" — re v3 ratchet attempt context) +- **Layer 1 prior art**: PR #2718 `ci(layer1): skip v3 job on docs-only PRs via changes-filter` — the `changes` job mechanism this brief EXTENDS (not parallels) +- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `affected_dimensions.contains(group.dimension)` +- **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 enum (`value | cost | complexity | effect | refinement`) — every Layer 2 path-mapping entry MUST carry a `dimension:` field matching this enum to prevent schema divergence from future lens output +- **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): + - (a) `scripts/slow-test-exemptions.txt` — 78 active entries (curated >2s ratchet exemption list) + - (b) `/tmp/v3-test-timings.log` — empirical per-test wall-time captured by every CI run via `--report-time` (consumed by `scripts/check-test-timeout.sh`, wired at `.github/workflows/ci.yml:405-424`) + - (c) NEW per-group required-paths mapping (the deliverable; bridge-debt artifact) + +--- + +## §0. Scope + +Extend PR #2718's `changes` job with per-test-group `skip_*` boolean outputs derived from the same `changed`-files list and per-group required-paths regex. Wire `v3` STEP-level `if:` predicates to skip individual test groups whose path-dependencies are unaffected by the PR's diff. + +**Not in scope**: a parallel CI gate mechanism; new path-classification source-of-truth (must reuse PR #2718's `gunbc-quick` `changes` job). + +**Single source of truth invariant**: all path classification flows from one `changes` job. Layer 1 produces `code: bool`; Layer 2 grows additional outputs (`skip_lens: bool`, `skip_emit: bool`, `skip_parser: bool`, ...) on the same job. No second `gunbc-quick` job. No `actions/cache`-fork. No parallel diff mechanism. + +## §1. Mechanism (extend PR #2718, do not parallel) + +**Layer 1 baseline** (per PM pre-stage): +```yaml +# .github/workflows/ci.yml (post-#2718) +changes: + runs-on: gunbc-quick + timeout-minutes: 3 + outputs: + code: ${{ steps.diff.outputs.code }} + steps: + - + - + - +``` + +**Layer 2 extension**: same `changes` job grows per-group outputs: +```yaml +changes: + outputs: + code: ${{ steps.diff.outputs.code }} + skip_lens: ${{ steps.classify.outputs.skip_lens }} + skip_emit: ${{ steps.classify.outputs.skip_emit }} + skip_parser: ${{ steps.classify.outputs.skip_parser }} + skip_cost: ${{ steps.classify.outputs.skip_cost }} + # ... per-group entries per Mgr-fill inventory + steps: + - + - id: classify + run: | + # for each group in per-group-required-paths-table: + # skip_ = "true" if (changed files ∩ required_paths) is empty else "false" + # push events short-circuit all skip_* to "false" +``` + +`v3` job consumes via STEP-level `if:`: +```yaml +v3: + needs: [changes] + if: ${{ needs.changes.outputs.code == 'true' || github.event_name == 'push' }} + steps: + - + - name: cost-lens integration + if: ${{ needs.changes.outputs.skip_cost_lens != 'true' }} + run: cargo test -p v3-compiler --test integration cost_lens_* + - name: emit-target integration + if: ${{ needs.changes.outputs.skip_emit != 'true' }} + run: cargo test -p v3-compiler --test integration *_emit_* + # ... per-group test invocations +``` + +**Job-level `code` flag retained**: docs-only PRs still skip the entire `v3` job (~67min → 0min). Layer 2 makes the granularity finer for code PRs whose changed-paths affect only some groups. + +## §2. Inventory sources + per-group table shape + +Per-group mapping table (the deliverable): + +``` +(group_name, dimension, required_paths_regex, test_pattern) +``` + +Where: +- `group_name` — short identifier (e.g., `cost_lens`, `emit_target`, `parser_grammar`) +- `dimension: Dimension` — value | cost | complexity | effect | refinement (load-bearing — matches future lens output enum) +- `required_paths_regex` — regex over changed file paths; if no changed file matches, skip this group +- `test_pattern` — `cargo test` arg pattern selecting the group's tests + +**Inventory derivation** (Mgr-fill from 3 sources): + +(a) **`scripts/slow-test-exemptions.txt`** — start with the 78 active >2s entries. Each entry already has citation discipline; group by `_test.rs` file-area prefix. + +(b) **`/tmp/v3-test-timings.log` empirical** — last N CI runs aggregated → top-K slowest groups by file-area. Cross-validates (a) and surfaces non-exempted slow tests. + +(c) **NEW per-group required-paths mapping** — for each group, hand-author the required-paths regex by examining which `src/v3/*` files the group's tests transitively depend on. This is the bridge-debt artifact; dissolves when the affected-set lens lands. + +**Starting template** (PM pre-staged skeleton to be attached if/when available): +``` +cost_lens | cost | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens_* +complexity_lens | complexity | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens_* +emit_target | effect | ^(src/v3/extdeps/.*|src/v3/compiler/src/emit/.*|src/v3/compiler/src/omni_shape_.*\.rs)$ | emit_target_* +parser_grammar | refinement | ^(src/v3/parser/.*|src/v3/compiler/src/parser.*\.rs|src/v3/compiler/src/lower.*\.rs)$ | parser_grammar_* +# ... etc per Mgr-fill +``` + +**[Mgr-fill]**: full per-group table — exhaustive coverage of `scripts/slow-test-exemptions.txt` 78 entries grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. + +## §3. Per-dimension structural target — `feedback_parallel_representation_debt` prevention + +The Layer 2 path-mapping is bridge-debt by design. The dissolution is the affected-set Introspect-lens (canvas PR #2713 by `clever-tern-670`, locked-design `docs/design-affected-set-lens.md`). When the lens lands, the dissolution is: + +```yaml +# Post-dissolution (after ci_uses_provable_minimal_affected_set_selection gate) +changes: + steps: + - id: lens + run: | + cargo run -p v3-compiler --bin affected_set_lens -- \ + --pr-diff origin/main...HEAD \ + --output /tmp/affected.json + - id: classify + run: | + # per-group skip_* derived from lens output, not path-regex + for group in cost_lens emit_target parser_grammar ...; do + dim="${group_dimension[$group]}" + if jq -e ".affected_dimensions | contains([\"$dim\"])" /tmp/affected.json; then + echo "skip_$group=false" >> $GITHUB_OUTPUT + else + echo "skip_$group=true" >> $GITHUB_OUTPUT + fi + done +``` + +**The `(group_name, dimension)` mapping survives the dissolution** — only the `required_paths_regex` column gets retired (replaced by lens-provided per-dimension affected-set). For this to work, **every Layer 2 path-mapping entry MUST have a `dimension:` field matching the lens enum exactly**. + +This is the parallel-representation-debt prevention. If Layer 2's group-classification diverges from the lens's dimension axis (e.g., Layer 2 groups by file-area but lens groups by dimension), dissolution becomes a schema-migration rather than a column-retirement. + +**Hard constraint**: no group entry without a `dimension:` field matching the lens enum. If a group doesn't fit one of the 5 dimensions cleanly, escalate to Coordinator — that's a substrate-shape question, not a Layer 2 design choice. + +## §4. Hard constraints + +1. **Single source of truth for path classification** — the `changes` job (one job, one diff, one classifier). NO parallel `gunbc-quick` job; NO duplicate `git diff` invocation; NO per-group diff fork. +2. **STEP-level `if:` on `v3`, not separate jobs** — keeps `v3`'s `needs:` graph and required-check name stable. `self_host_ratchet` `if:` widening from PR #2718 remains unchanged. +3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. +4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; dissolves when `ci_uses_provable_minimal_affected_set_selection` gate lands and lens output replaces `required_paths_regex` column." +5. **Dimension field on every group entry** — no group without `dimension: ` field. Substrate-shape questions on dimension assignment escalate. +6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). +7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. +8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). + +## §5. Acceptance + +The Layer 2 PR-set is acceptable when: + +- `changes` job grows per-group `skip_*` outputs (no parallel job created) +- `v3` step-level `if:` predicates wired for each group +- Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) +- Every group entry has `dimension: ` field matching `docs/design-affected-set-lens.md` §2 enum +- Self-test: a docs-only PR still triggers Layer 1 (entire `v3` skip — `code=false`); a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups; a `push` to main runs everything +- PR body explicitly states bridge-debt + dissolution trigger +- `self_host_ratchet` required-check name remains green via existing PR #2718 `if:` widening +- No new hand-Rust files; no SG-0 census changes +- Empirical validation against `/tmp/v3-test-timings.log` last-N runs: median per-group skip-rate captured + expected CI-time savings projected + +## §6. Decomposition (Mgr-fill) + +Recommended split (subject to Mgr judgment + PM pre-staged skeleton availability): + +- **Pilot wave** (1-2 groups; ~2 hours): pick the highest-signal pair (e.g., `cost_lens` + `parser_grammar` — large slow-test surface, well-bounded path-dependencies). Validates the per-group `skip_*` output + STEP-level `if:` mechanism on `v3`. +- **Class wave** (5-8 groups; ~1 day): parallel-dispatch per top-K groups from empirical timings. Each group's PR is bounded; reviewer can verify required-paths regex against test deps. +- **Long-tail wave** (remaining groups + edge-case path-regex tuning): per-group escalation if path-classification accuracy issues surface. + +**Pilot ordering recommendation**: start with `cost_lens` because the affected-set lens canvas (PR #2713) is also `cost_lens`-aware; validates the dimension-mapping invariant against locked-design §2 enum directly. + +## §7. STOP and escalate + +Escalate via dashboard-message to Verification Mgr (`clever-tern-670`) if: + +- A test group can't be cleanly assigned a single `Dimension` (substrate-shape question, not a Layer 2 design choice) +- The `changes` job exceeds 3-minute cap once Layer 2 classification logic added (mechanism-shape question) +- Required-paths regex authoring produces false-negatives (test skipped that should have run) in self-test — escalate to widen regex, NOT to disable group classification +- `self_host_ratchet` `if:` widening breaks when interacting with per-step `if:` — coordinate with PR #2718 author for the predicate composition +- Layer 2 dissolution shape (when affected-set lens lands) doesn't match the `(group_name, dimension)` schema — substrate-shape question, escalate to Substrate Mgr coordinator + +Do not push a workaround PR for any of these. + +## §8. Bridge-debt + dissolution path + +**This brief produces a bridge.** Per BridgeLedgerZero discipline + `feedback_bridge_debt_window_cadence`, every bridge has a named dissolution trigger: + +- **Bridge**: per-group `required_paths_regex` table (hand-authored, file-path-substring-based) +- **Dissolution trigger**: gate `ci_uses_provable_minimal_affected_set_selection` lands ⇒ affected-set Introspect-lens output replaces `required_paths_regex` column +- **Surviving artifact post-dissolution**: `(group_name, dimension)` mapping — the dimension column remains as the lens consumer; only path-regex column retires + +Cite the dissolution path in every Layer 2 PR body. When the gate lands, a single follow-up PR retires the bridge and the brief is done. + +--- + +**Mgr-finalization checklist** (before flipping to PRE-AUTH DISPATCH-READY): + +- [ ] Complete per-group inventory (sources (a)+(b); table column (c)) — recommend PM pre-staged skeleton if/when available +- [ ] Per-group `dimension:` assignments validated against `docs/design-affected-set-lens.md` §2 enum +- [ ] Per-group `required_paths_regex` tested against 3-5 representative recent PRs for false-positive/false-negative rate +- [ ] Pilot wave selection (recommend `cost_lens` first per §6) +- [ ] Coordination ack from PR #2718 author on `self_host_ratchet` `if:` interaction shape + +**End of scaffold.** Director-tier shape established; Verification Mgr fills inventory + per-group regex + pilot selection + dispatch. + +--- + +## Authority footer + +- **Operator directive**: gunbc#846 c4425420798 (CI mitigation urgent escalation 2026-05-11) +- **Layer 1 PR**: gunbc#2718 +- **PM ratification**: gunbc#828 c4425726922 (GitHub inbox fallback — dashboard-message service flap) +- **Director ratification**: dashboard-message msg_a77c7f42 (Verification Mgr routing per `feedback_parallel_representation_debt` coherence) +- **Locked design**: `docs/design-affected-set-lens.md` (canvas at gunbc#2713) +- **Phase 3 scaffold pattern reference**: `docs/briefs/r3-v-cluster-m-84-class-reflected-dag-bulkport-worker.md` + `docs/briefs/r3-v-cluster-m-84-class-generic-dimreport-bulkport-worker.md` (Director scaffold-fill pattern; commit landed via PR #2708 squash) From e661374d45eff67fa8f0106f84f3db6e6bbb59ed Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 22:59:00 +0000 Subject: [PATCH 13/34] =?UTF-8?q?docs(briefs):=20fix=20Layer=202=20YAML=20?= =?UTF-8?q?naming=20inconsistency=20(skip=5Fcost=20=E2=86=92=20skip=5Fcost?= =?UTF-8?q?=5Flens)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per cursor APPROVE_WITH_COMMENTS at sha 04c5b0895 (review 9701): > The changes outputs define skip_cost, but the v3 step's if: uses > needs.changes.outputs.skip_cost_lens. That disagrees with the same brief's > post-dissolution sketch (skip_$group with cost_lens → skip_cost_lens, lines > 129-134). Not a formal invariant breach by itself, but it is easy for an > implementer to copy the wrong name and get an always-on/off step. Fix: normalize the example YAML outputs block to match the if: lines and the post-dissolution sketch. Naming convention: skip_ where matches the per-group table's group_name column verbatim (no abbreviation). Updated all 4 example outputs: skip_lens → skip_complexity_lens (was vague; tied to specific group) skip_emit → skip_emit_target (matches starting template at §2) skip_parser → skip_parser_grammar (matches starting template) skip_cost → skip_cost_lens (matches if: line + post-dissolution sketch) Also added an inline comment documenting the naming convention so future copy-paste from the example stays mechanically correct. --- ...r3-ci-layer-2-path-conditional-gating-worker.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index c4029b2c2ea..d040b5bcdb0 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -45,17 +45,19 @@ changes: changes: outputs: code: ${{ steps.diff.outputs.code }} - skip_lens: ${{ steps.classify.outputs.skip_lens }} - skip_emit: ${{ steps.classify.outputs.skip_emit }} - skip_parser: ${{ steps.classify.outputs.skip_parser }} - skip_cost: ${{ steps.classify.outputs.skip_cost }} + skip_cost_lens: ${{ steps.classify.outputs.skip_cost_lens }} + skip_emit_target: ${{ steps.classify.outputs.skip_emit_target }} + skip_parser_grammar: ${{ steps.classify.outputs.skip_parser_grammar }} + skip_complexity_lens: ${{ steps.classify.outputs.skip_complexity_lens }} # ... per-group entries per Mgr-fill inventory + # naming convention: skip_ where matches the + # per-group table's group_name column verbatim (no abbreviation). steps: - - id: classify run: | # for each group in per-group-required-paths-table: - # skip_ = "true" if (changed files ∩ required_paths) is empty else "false" + # skip_ = "true" if (changed files ∩ required_paths) is empty else "false" # push events short-circuit all skip_* to "false" ``` @@ -70,7 +72,7 @@ v3: if: ${{ needs.changes.outputs.skip_cost_lens != 'true' }} run: cargo test -p v3-compiler --test integration cost_lens_* - name: emit-target integration - if: ${{ needs.changes.outputs.skip_emit != 'true' }} + if: ${{ needs.changes.outputs.skip_emit_target != 'true' }} run: cargo test -p v3-compiler --test integration *_emit_* # ... per-group test invocations ``` From bca2166249817eccb8eed20feae71cacde45371f Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 23:01:41 +0000 Subject: [PATCH 14/34] docs(briefs): cite PM pre-staged Mgr-fill template (PR #2721) + converge pilot recommendation on Cluster B MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per PM msg_bba47649 — pre-staged Mgr-fill template landed as PR #2721 (docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md, 220 lines). Two scaffold updates: 1. §2 (inventory sources): replaced 'PM pre-staged skeleton to be attached if/when available' speculative reference with explicit cite-and-link to the landed template doc. Describes what the PM template provides: - All 78 slow-test-exemptions.txt entries grouped into 9 clusters (A-I) - (test_pattern, dimension, required_paths_regex) skeleton table - 12 [Mgr-fill] placeholders for substrate-lens / R3-V L4/L7 / R1C-E / free-consequences cross-target tracing 2. §6 (decomposition): converged my prior cost_lens-first pilot recommendation with PM's Cluster B recommendation — these are the same family (Lane 2 Stage 2d symbolic cost = cost-lens). Updated wording to reflect Cluster naming + cross-citation to PM template's Cluster B detail. Added [Mgr-fill] placeholder resolution wave to decomposition. Inline sketch table retained as illustrative; defer to PM template for actual starting inventory. --- ...-layer-2-path-conditional-gating-worker.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index d040b5bcdb0..8cfbdb5a742 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -101,7 +101,15 @@ Where: (c) **NEW per-group required-paths mapping** — for each group, hand-author the required-paths regex by examining which `src/v3/*` files the group's tests transitively depend on. This is the bridge-debt artifact; dissolves when the affected-set lens lands. -**Starting template** (PM pre-staged skeleton to be attached if/when available): +**Starting template — PM pre-staged Mgr-fill reference doc**: [`docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md`](r3-ci-layer-2-pm-prestaged-mgr-fill-template.md) (landed via PR #2721; 220 lines). + +The PM template provides: +- **All 78 `scripts/slow-test-exemptions.txt` entries** grouped into 9 clusters (A–I) by module prefix +- **`(test_pattern, dimension, required_paths_regex)` skeleton table** with every row carrying a `dimension:` field matching the lens enum verbatim +- **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single `cost` dimension, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family. +- **12 `[Mgr-fill]` placeholders** marking where consumer-tracing exceeded PM bandwidth (substrate-lens deps, R3-V L4/L7, R1C-E `.dag` wrapper, free-consequences cross-target). These are the Mgr-tier sub-classification decisions. + +Inline sketch (illustrative — defer to the PM template for the actual starting inventory): ``` cost_lens | cost | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens_* complexity_lens | complexity | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens_* @@ -171,14 +179,13 @@ The Layer 2 PR-set is acceptable when: ## §6. Decomposition (Mgr-fill) -Recommended split (subject to Mgr judgment + PM pre-staged skeleton availability): +Recommended split (subject to Mgr judgment + PM pre-staged Cluster B recommendation): -- **Pilot wave** (1-2 groups; ~2 hours): pick the highest-signal pair (e.g., `cost_lens` + `parser_grammar` — large slow-test surface, well-bounded path-dependencies). Validates the per-group `skip_*` output + STEP-level `if:` mechanism on `v3`. -- **Class wave** (5-8 groups; ~1 day): parallel-dispatch per top-K groups from empirical timings. Each group's PR is bounded; reviewer can verify required-paths regex against test deps. +- **Pilot wave** (1 cluster; ~2 hours): **Cluster B (Lane 2 Stage 2d symbolic cost)** per PM template recommendation — high confidence, single `cost` dimension, ~6 tests. Converges with my prior `cost_lens`-first recommendation; Cluster B IS the cost-lens family in the PM grouping. Validates per-group `skip_*` output + STEP-level `if:` mechanism on `v3` + dimension-mapping invariant against locked-design §2 enum. +- **Class wave** (5-8 clusters; ~1 day): parallel-dispatch per remaining PM Clusters A/C-I from empirical timings. Each cluster's PR is bounded; reviewer can verify required-paths regex against test deps + dimension assignment against lens enum. +- **`[Mgr-fill]` placeholder resolution** (12 entries per PM template): per-entry escalation as consumer-tracing surfaces substrate-lens deps / R3-V L4/L7 / R1C-E `.dag` wrapper / free-consequences cross-target shapes. These may bundle with the corresponding cluster waves or stand alone. - **Long-tail wave** (remaining groups + edge-case path-regex tuning): per-group escalation if path-classification accuracy issues surface. -**Pilot ordering recommendation**: start with `cost_lens` because the affected-set lens canvas (PR #2713) is also `cost_lens`-aware; validates the dimension-mapping invariant against locked-design §2 enum directly. - ## §7. STOP and escalate Escalate via dashboard-message to Verification Mgr (`clever-tern-670`) if: From a1604a8db7898ad5365e9d6b32538cd301cc9709 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 19:13:28 -0400 Subject: [PATCH 15/34] WIP: gunbc Director --- ...-layer-2-path-conditional-gating-worker.md | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 8cfbdb5a742..acaa9d9ba54 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -7,8 +7,8 @@ **Authority (cite-and-execute):** - **Operator escalation**: Brian's CI-up-to-1-hour framing at gunbc#846 2026-05-11 ("their CI is up to 1 hour ... not happening" — re v3 ratchet attempt context) - **Layer 1 prior art**: PR #2718 `ci(layer1): skip v3 job on docs-only PRs via changes-filter` — the `changes` job mechanism this brief EXTENDS (not parallels) -- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `affected_dimensions.contains(group.dimension)` -- **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 enum (`value | cost | complexity | effect | refinement`) — every Layer 2 path-mapping entry MUST carry a `dimension:` field matching this enum to prevent schema divergence from future lens output +- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `(affected_dimensions ∩ group.dimensions) ≠ ∅` (set-intersection-non-empty, per locked-design §2 union semantics — NOT singular `.contains()` membership) +- **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - (a) `scripts/slow-test-exemptions.txt` — 78 active entries (curated >2s ratchet exemption list) - (b) `/tmp/v3-test-timings.log` — empirical per-test wall-time captured by every CI run via `--report-time` (consumed by `scripts/check-test-timeout.sh`, wired at `.github/workflows/ci.yml:405-424`) @@ -84,12 +84,12 @@ v3: Per-group mapping table (the deliverable): ``` -(group_name, dimension, required_paths_regex, test_pattern) +(group_name, dimensions, required_paths_regex, test_pattern) ``` Where: - `group_name` — short identifier (e.g., `cost_lens`, `emit_target`, `parser_grammar`) -- `dimension: Dimension` — value | cost | complexity | effect | refinement (load-bearing — matches future lens output enum) +- `dimensions: Set` — non-empty subset of `{value, cost, complexity, effect, refinement}` per `docs/design-affected-set-lens.md` §2 union semantics. Single-element sets `{cost}` are valid for single-dim groups; multi-dim consumers MUST list all dimensions they read (e.g., LBP demonstration: `{complexity, cost}`). Empty set is invalid — escalate per §7. - `required_paths_regex` — regex over changed file paths; if no changed file matches, skip this group - `test_pattern` — `cargo test` arg pattern selecting the group's tests @@ -105,8 +105,8 @@ Where: The PM template provides: - **All 78 `scripts/slow-test-exemptions.txt` entries** grouped into 9 clusters (A–I) by module prefix -- **`(test_pattern, dimension, required_paths_regex)` skeleton table** with every row carrying a `dimension:` field matching the lens enum verbatim -- **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single `cost` dimension, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family. +- **`(test_pattern, dimensions, required_paths_regex)` skeleton table** with every row carrying a `dimensions:` field of type `Set` per locked-design §2 union semantics (PM template post-fix at `dedcf69a4`) +- **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single-element set `{cost}`, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family with singleton `{cost}` dimensions. - **12 `[Mgr-fill]` placeholders** marking where consumer-tracing exceeded PM bandwidth (substrate-lens deps, R3-V L4/L7, R1C-E `.dag` wrapper, free-consequences cross-target). These are the Mgr-tier sub-classification decisions. Inline sketch (illustrative — defer to the PM template for the actual starting inventory): @@ -120,7 +120,7 @@ parser_grammar | refinement | ^(src/v3/parser/.*|src/v3/compiler/src/parser. **[Mgr-fill]**: full per-group table — exhaustive coverage of `scripts/slow-test-exemptions.txt` 78 entries grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. -## §3. Per-dimension structural target — `feedback_parallel_representation_debt` prevention +## §3. Per-dimensions structural target — `feedback_parallel_representation_debt` prevention (set semantics per locked-design §2) The Layer 2 path-mapping is bridge-debt by design. The dissolution is the affected-set Introspect-lens (canvas PR #2713 by `clever-tern-670`, locked-design `docs/design-affected-set-lens.md`). When the lens lands, the dissolution is: @@ -135,10 +135,14 @@ changes: --output /tmp/affected.json - id: classify run: | - # per-group skip_* derived from lens output, not path-regex + # per-group skip_* derived from lens output, not path-regex. + # Set semantics per locked-design §2: skip iff (affected ∩ group.dimensions) is empty. for group in cost_lens emit_target parser_grammar ...; do - dim="${group_dimension[$group]}" - if jq -e ".affected_dimensions | contains([\"$dim\"])" /tmp/affected.json; then + dims_json="${group_dimensions[$group]}" # JSON array, e.g., '["cost"]' or '["complexity","cost"]' + # (affected_dimensions ∩ group.dimensions) ≠ ∅ → run; otherwise skip + if jq -e --argjson dims "$dims_json" \ + '.affected_dimensions | any(. as $d | $dims | contains([$d]))' \ + /tmp/affected.json; then echo "skip_$group=false" >> $GITHUB_OUTPUT else echo "skip_$group=true" >> $GITHUB_OUTPUT From efacecd9491615b4704171dec82182d80e8d8f89 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 23:14:37 +0000 Subject: [PATCH 16/34] =?UTF-8?q?docs(briefs):=20fix=20singular=20dimensio?= =?UTF-8?q?n=20=E2=86=92=20Set=20per=20PM=20caught=20semantic?= =?UTF-8?q?=20violation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PM (msg_ab551c52) surfaced codex RC on template PR #2721 (review #9707): singular 'dimension:' field violates locked-design §2 union semantics. A multi-dim consumer (e.g., LBP demonstration reading both complexity + cost) declared with singular dimension: cost would be silently skipped when only complexity changes — fail-open violation against P3. PM fixed their template at dedcf69a4: dimension → dimensions (Set), union-formula clarified, multi-dim rows expanded. This brief had the same singular semantics; absorbed the fix per PM recommendation so Verification Mgr inherits coherent dim-set semantic across both authority chain artifacts (brief + template). Changes: - §0 authority bullet: contains(single) → (∩ ≠ ∅) intersection-non-empty; dimension: Dimension → dimensions: Set - §2 table column rename + type spec + union semantics note + multi-dim consumer guidance - §2 starting template citation updated to reflect post-fix template at dedcf69a4 - §3 section header renamed; substantive paragraph explaining WHY Set not Dimension (cites PM caught violation + P3 fail-open framing) - §3 YAML example: jq script updated to set-intersection check - §4.5 hard constraint: dimensions: Set with members from enum; empty set invalid - §5 acceptance: every group has dimensions: Set; multi-dim fidelity language - §6 pilot description: 'singleton {cost} dimensions' phrasing; class wave reviewer-check language updated - §7 STOP: added multi-dim escalation path; explicit warning against defaulting to singleton {primary} - §8 surviving artifact: (group_name, dimensions) — set-typed column survives - inline illustrative table: explicit set-literal notation with multi-dim row example (lbp_demonstration: {complexity, cost}) Same authority chain absorbs cleanly: brief (primary) + template (data attachment) now both set-typed; Verification Mgr inherits coherent semantic. --- ...-layer-2-path-conditional-gating-worker.md | 32 +++++++++++-------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index acaa9d9ba54..2721c8aa916 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -109,12 +109,13 @@ The PM template provides: - **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single-element set `{cost}`, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family with singleton `{cost}` dimensions. - **12 `[Mgr-fill]` placeholders** marking where consumer-tracing exceeded PM bandwidth (substrate-lens deps, R3-V L4/L7, R1C-E `.dag` wrapper, free-consequences cross-target). These are the Mgr-tier sub-classification decisions. -Inline sketch (illustrative — defer to the PM template for the actual starting inventory): +Inline sketch (illustrative — defer to the PM template for the actual starting inventory). Note `dimensions` column is `Set`; singletons shown as `{cost}`, multi-dim consumers as `{complexity, cost}`: ``` -cost_lens | cost | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens_* -complexity_lens | complexity | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens_* -emit_target | effect | ^(src/v3/extdeps/.*|src/v3/compiler/src/emit/.*|src/v3/compiler/src/omni_shape_.*\.rs)$ | emit_target_* -parser_grammar | refinement | ^(src/v3/parser/.*|src/v3/compiler/src/parser.*\.rs|src/v3/compiler/src/lower.*\.rs)$ | parser_grammar_* +cost_lens | {cost} | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens_* +complexity_lens | {complexity} | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens_* +lbp_demonstration | {complexity, cost} | ^(src/v3/lenses/(cost|complexity)\.dag|src/v3/compiler/src/.*lbp.*\.rs)$ | lbp_* # multi-dim +emit_target | {effect} | ^(src/v3/extdeps/.*|src/v3/compiler/src/emit/.*|src/v3/compiler/src/omni_shape_.*\.rs)$ | emit_target_* +parser_grammar | {refinement} | ^(src/v3/parser/.*|src/v3/compiler/src/parser.*\.rs|src/v3/compiler/src/lower.*\.rs)$ | parser_grammar_* # ... etc per Mgr-fill ``` @@ -150,11 +151,13 @@ changes: done ``` -**The `(group_name, dimension)` mapping survives the dissolution** — only the `required_paths_regex` column gets retired (replaced by lens-provided per-dimension affected-set). For this to work, **every Layer 2 path-mapping entry MUST have a `dimension:` field matching the lens enum exactly**. +**The `(group_name, dimensions)` mapping survives the dissolution** — only the `required_paths_regex` column gets retired (replaced by lens-provided per-dimension affected-set). For this to work, **every Layer 2 path-mapping entry MUST have a `dimensions:` field of type `Set` with members from the lens enum exactly**. This is the parallel-representation-debt prevention. If Layer 2's group-classification diverges from the lens's dimension axis (e.g., Layer 2 groups by file-area but lens groups by dimension), dissolution becomes a schema-migration rather than a column-retirement. -**Hard constraint**: no group entry without a `dimension:` field matching the lens enum. If a group doesn't fit one of the 5 dimensions cleanly, escalate to Coordinator — that's a substrate-shape question, not a Layer 2 design choice. +**Why `Set` not `Dimension`** (per PM caught semantic violation 2026-05-11 via codex RC on template PR #2721, fixed at `dedcf69a4`): `docs/design-affected-set-lens.md` §2 defines `affected_set` as a **union** over `Set`, not single-match. A multi-dim consumer (e.g., LBP demonstration reading both `complexity` + `cost`) declared with singular `dimension: cost` would be silently skipped when only `complexity` changes — a fail-open violation against P3. The set type makes the union semantics structurally faithful. + +**Hard constraint**: no group entry without a `dimensions:` field of type `Set` with members from the lens enum. Single-element sets like `{cost}` are valid for single-dim groups. Empty set is invalid. If a group doesn't fit any of the 5 dimensions cleanly, escalate to Coordinator — that's a substrate-shape question, not a Layer 2 design choice. ## §4. Hard constraints @@ -162,7 +165,7 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 2. **STEP-level `if:` on `v3`, not separate jobs** — keeps `v3`'s `needs:` graph and required-check name stable. `self_host_ratchet` `if:` widening from PR #2718 remains unchanged. 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. 4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; dissolves when `ci_uses_provable_minimal_affected_set_selection` gate lands and lens output replaces `required_paths_regex` column." -5. **Dimension field on every group entry** — no group without `dimension: ` field. Substrate-shape questions on dimension assignment escalate. +5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). @@ -174,7 +177,7 @@ The Layer 2 PR-set is acceptable when: - `changes` job grows per-group `skip_*` outputs (no parallel job created) - `v3` step-level `if:` predicates wired for each group - Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) -- Every group entry has `dimension: ` field matching `docs/design-affected-set-lens.md` §2 enum +- Every group entry has `dimensions: Set` field (non-empty subset of `docs/design-affected-set-lens.md` §2 enum); set semantics preserve multi-dim consumer fidelity per locked-design union - Self-test: a docs-only PR still triggers Layer 1 (entire `v3` skip — `code=false`); a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups; a `push` to main runs everything - PR body explicitly states bridge-debt + dissolution trigger - `self_host_ratchet` required-check name remains green via existing PR #2718 `if:` widening @@ -185,8 +188,8 @@ The Layer 2 PR-set is acceptable when: Recommended split (subject to Mgr judgment + PM pre-staged Cluster B recommendation): -- **Pilot wave** (1 cluster; ~2 hours): **Cluster B (Lane 2 Stage 2d symbolic cost)** per PM template recommendation — high confidence, single `cost` dimension, ~6 tests. Converges with my prior `cost_lens`-first recommendation; Cluster B IS the cost-lens family in the PM grouping. Validates per-group `skip_*` output + STEP-level `if:` mechanism on `v3` + dimension-mapping invariant against locked-design §2 enum. -- **Class wave** (5-8 clusters; ~1 day): parallel-dispatch per remaining PM Clusters A/C-I from empirical timings. Each cluster's PR is bounded; reviewer can verify required-paths regex against test deps + dimension assignment against lens enum. +- **Pilot wave** (1 cluster; ~2 hours): **Cluster B (Lane 2 Stage 2d symbolic cost)** per PM template recommendation — high confidence, singleton `dimensions: {cost}`, ~6 tests. Converges with my prior `cost_lens`-first recommendation; Cluster B IS the cost-lens family in the PM grouping. Validates per-group `skip_*` output + STEP-level `if:` mechanism on `v3` + set-typed `dimensions` invariant against locked-design §2. +- **Class wave** (5-8 clusters; ~1 day): parallel-dispatch per remaining PM Clusters A/C-I from empirical timings. Each cluster's PR is bounded; reviewer can verify required-paths regex against test deps + `dimensions:` set assignment against lens enum (must include ALL dimensions the consumer reads, not just primary). - **`[Mgr-fill]` placeholder resolution** (12 entries per PM template): per-entry escalation as consumer-tracing surfaces substrate-lens deps / R3-V L4/L7 / R1C-E `.dag` wrapper / free-consequences cross-target shapes. These may bundle with the corresponding cluster waves or stand alone. - **Long-tail wave** (remaining groups + edge-case path-regex tuning): per-group escalation if path-classification accuracy issues surface. @@ -198,7 +201,8 @@ Escalate via dashboard-message to Verification Mgr (`clever-tern-670`) if: - The `changes` job exceeds 3-minute cap once Layer 2 classification logic added (mechanism-shape question) - Required-paths regex authoring produces false-negatives (test skipped that should have run) in self-test — escalate to widen regex, NOT to disable group classification - `self_host_ratchet` `if:` widening breaks when interacting with per-step `if:` — coordinate with PR #2718 author for the predicate composition -- Layer 2 dissolution shape (when affected-set lens lands) doesn't match the `(group_name, dimension)` schema — substrate-shape question, escalate to Substrate Mgr coordinator +- Layer 2 dissolution shape (when affected-set lens lands) doesn't match the `(group_name, dimensions)` schema — substrate-shape question, escalate to Substrate Mgr coordinator +- A group consumer reads multi-dim but it's unclear which dimensions are load-bearing — escalate to Coordinator for dimension-set assignment (do NOT default to singleton `{primary}`; that's the fail-open shape PM caught in template review) Do not push a workaround PR for any of these. @@ -208,7 +212,7 @@ Do not push a workaround PR for any of these. - **Bridge**: per-group `required_paths_regex` table (hand-authored, file-path-substring-based) - **Dissolution trigger**: gate `ci_uses_provable_minimal_affected_set_selection` lands ⇒ affected-set Introspect-lens output replaces `required_paths_regex` column -- **Surviving artifact post-dissolution**: `(group_name, dimension)` mapping — the dimension column remains as the lens consumer; only path-regex column retires +- **Surviving artifact post-dissolution**: `(group_name, dimensions)` mapping — the `dimensions: Set` column remains as the lens consumer; only path-regex column retires Cite the dissolution path in every Layer 2 PR body. When the gate lands, a single follow-up PR retires the bridge and the brief is done. @@ -217,7 +221,7 @@ Cite the dissolution path in every Layer 2 PR body. When the gate lands, a singl **Mgr-finalization checklist** (before flipping to PRE-AUTH DISPATCH-READY): - [ ] Complete per-group inventory (sources (a)+(b); table column (c)) — recommend PM pre-staged skeleton if/when available -- [ ] Per-group `dimension:` assignments validated against `docs/design-affected-set-lens.md` §2 enum +- [ ] Per-group `dimensions: Set` assignments validated against `docs/design-affected-set-lens.md` §2 union semantics — multi-dim consumers MUST list all dimensions they read (no silent-skip on non-primary dim changes) - [ ] Per-group `required_paths_regex` tested against 3-5 representative recent PRs for false-positive/false-negative rate - [ ] Pilot wave selection (recommend `cost_lens` first per §6) - [ ] Coordination ack from PR #2718 author on `self_host_ratchet` `if:` interaction shape From 2b6ce321f09273f826461f28d575ab5f0bf2e964 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 23:31:39 +0000 Subject: [PATCH 17/34] docs(briefs): fix boolean polarity inversion + add polarity invariant per openai-pro RC on template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PM (msg_9a188e22) surfaced openai-pro BLOCKING re-review (#9721) on template PR #2721 at 93080af4 — caught load-bearing boolean polarity inversion: brief stated skip_* formula as (affected ∩ row.dimensions) ≠ ∅ (skip when intersection NON-empty) while CI consumer wires if: skip != 'true' (run when skip is false). Net effect: literal-following Mgr/worker would wire the gate to silently skip AFFECTED tests when intersection is non-empty. TESTING.md + Boundary Discipline violation. PM fixed template at 262f42d7d (4 sites inverted; explicit polarity table added at §1/§3/§4/§5). Same risk on this brief (#2719) at the post-dissolution mapping site I authored when absorbing the prior dim-set fix at efacecd94. Fix: §0 authority bullet (line 10, the inversion site): before: 'skip_* flags become (∩ ≠ ∅)' [INVERTED — fail-open] after: 'skip_* flags become skip_ = (∩ = ∅)' [canonical] + explicit polarity check note + carrier-vs-contract explanation + skip-form / run-form equivalence stated §3 substantive paragraph (after Set WHY): added Polarity invariant block citing PM's caught inversion + 262f42d7d fix + explicit warning that skip = (∩ ≠ ∅) is the canonical fail-open boolean-polarity bug pattern. §4 hard constraint #5 (dimensions field): added inline Polarity invariant restating the canonical skip-form + run-form equivalent + 'never invert' clause. §5 acceptance: added 'Polarity check passes' criterion enumerating the acceptable forms + naming the inverted form as the fail-open pattern to reject in review. Self-test text clarified: cost-dimension groups run, other-dimension groups skip (verifies correct polarity in actual gate). YAML example at §3 (lines 139-149) was already polarity-correct (skip iff intersection empty; skip=true when intersection empty) so unchanged. Single-pass absorption per PM recommendation — both brief and template now lockstep on polarity semantics. Verification Mgr inherits both files without polarity mismatch in finalization. --- .../r3-ci-layer-2-path-conditional-gating-worker.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 2721c8aa916..33312594b59 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -7,7 +7,7 @@ **Authority (cite-and-execute):** - **Operator escalation**: Brian's CI-up-to-1-hour framing at gunbc#846 2026-05-11 ("their CI is up to 1 hour ... not happening" — re v3 ratchet attempt context) - **Layer 1 prior art**: PR #2718 `ci(layer1): skip v3 job on docs-only PRs via changes-filter` — the `changes` job mechanism this brief EXTENDS (not parallels) -- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `(affected_dimensions ∩ group.dimensions) ≠ ∅` (set-intersection-non-empty, per locked-design §2 union semantics — NOT singular `.contains()` membership) +- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `skip_ = (affected_dimensions ∩ group.dimensions) = ∅` (skip when **intersection is EMPTY** = group's dimensions unaffected; equivalently `run = (intersection ≠ ∅)`). **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: empty-intersection ⇒ unaffected ⇒ skip; non-empty intersection ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. - **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - (a) `scripts/slow-test-exemptions.txt` — 78 active entries (curated >2s ratchet exemption list) @@ -159,6 +159,8 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi **Hard constraint**: no group entry without a `dimensions:` field of type `Set` with members from the lens enum. Single-element sets like `{cost}` are valid for single-dim groups. Empty set is invalid. If a group doesn't fit any of the 5 dimensions cleanly, escalate to Coordinator — that's a substrate-shape question, not a Layer 2 design choice. +**Polarity invariant** (per PM caught inversion 2026-05-11 via openai-pro RC #9721 on template PR #2721, fixed at `262f42d7d`): the carrier name is `skip_`. CI consumer wires `if: skip_ != 'true'` (i.e., RUN when `skip` is false). The dissolution formula MUST therefore be `skip = (affected ∩ group.dimensions) = ∅` (skip when intersection is **empty** = group's dimensions unaffected). The inverted form `skip = (∩ ≠ ∅)` is a fail-open boolean-polarity bug: it would silently skip AFFECTED groups when the intersection is non-empty. Skip-form is canonical (matches carrier name); run-form `run = (∩ ≠ ∅)` is the equivalent run-carrier statement. Any acceptance-criterion / YAML example / formula citation in this brief or its Mgr-fill output MUST use the canonical skip-form (empty intersection) or the equivalent run-form (non-empty intersection) — never invert. + ## §4. Hard constraints 1. **Single source of truth for path classification** — the `changes` job (one job, one diff, one classifier). NO parallel `gunbc-quick` job; NO duplicate `git diff` invocation; NO per-group diff fork. @@ -166,6 +168,7 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. 4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; dissolves when `ci_uses_provable_minimal_affected_set_selection` gate lands and lens output replaces `required_paths_regex` column." 5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. + **Polarity invariant**: `skip_ = (affected ∩ group.dimensions) = ∅` (skip when intersection EMPTY = unaffected). Run-equivalent: `run = (intersection ≠ ∅)`. Never invert — `skip = (∩ ≠ ∅)` is the canonical fail-open boolean-polarity bug pattern (silently skips affected groups). Carrier name matches contract: `skip_*` flag is true when group is unaffected. 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). @@ -178,7 +181,8 @@ The Layer 2 PR-set is acceptable when: - `v3` step-level `if:` predicates wired for each group - Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) - Every group entry has `dimensions: Set` field (non-empty subset of `docs/design-affected-set-lens.md` §2 enum); set semantics preserve multi-dim consumer fidelity per locked-design union -- Self-test: a docs-only PR still triggers Layer 1 (entire `v3` skip — `code=false`); a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups; a `push` to main runs everything +- **Polarity check passes**: every YAML / formula / acceptance-text reference to the dissolution formula uses canonical skip-form `skip = (∩ = ∅)` or equivalent run-form `run = (∩ ≠ ∅)`. Inverted form `skip = (∩ ≠ ∅)` is the fail-open bug pattern; reject in review. +- Self-test: a docs-only PR still triggers Layer 1 (entire `v3` skip — `code=false`); a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups (cost-dimension groups run; other-dimension groups skip); a `push` to main runs everything - PR body explicitly states bridge-debt + dissolution trigger - `self_host_ratchet` required-check name remains green via existing PR #2718 `if:` widening - No new hand-Rust files; no SG-0 census changes From 13b0db9cfca47283ff700c398c7a07ca44b63191 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 19:38:45 -0400 Subject: [PATCH 18/34] WIP: gunbc Director --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 33312594b59..65e9208c0a9 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -201,7 +201,7 @@ Recommended split (subject to Mgr judgment + PM pre-staged Cluster B recommendat Escalate via dashboard-message to Verification Mgr (`clever-tern-670`) if: -- A test group can't be cleanly assigned a single `Dimension` (substrate-shape question, not a Layer 2 design choice) +- A test group can't be cleanly assigned a non-empty `Set` from the locked-design §2 enum (substrate-shape question, not a Layer 2 design choice). **Do NOT default to a singleton `{primary}` to bypass this** — that's the fail-open multi-dim collapse pattern §3 Polarity invariant + §4 hard constraint #5 explicitly forbid. If the group genuinely reads multiple dimensions and you can't enumerate them confidently, escalate. - The `changes` job exceeds 3-minute cap once Layer 2 classification logic added (mechanism-shape question) - Required-paths regex authoring produces false-negatives (test skipped that should have run) in self-test — escalate to widen regex, NOT to disable group classification - `self_host_ratchet` `if:` widening breaks when interacting with per-step `if:` — coordinate with PR #2718 author for the predicate composition From 558280e9ff21df4b53adf9bdd07ddad9c7511672 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 23:48:15 +0000 Subject: [PATCH 19/34] =?UTF-8?q?docs(briefs):=20align=20=C2=A70=20example?= =?UTF-8?q?=20names=20with=20=C2=A71=20naming=20convention=20(cursor=20exp?= =?UTF-8?q?loratory)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per cursor APPROVE exploratory observation on PR #2719 sha 13b0db9cf (review #9732): §0 line 25 illustrative outputs used abbreviated names (skip_lens / skip_emit / skip_parser) while §1 line 53-54 establishes strict 'skip_' naming convention matching the per-group table verbatim. Non-policy violation per cursor but tightening avoids ambiguity for implementer. Fix: replace abbreviated names with full-form (skip_cost_lens / skip_emit_target / skip_parser_grammar) + cross-reference §1 naming convention in the same sentence. Brief now consistent across all naming sites. --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 65e9208c0a9..fda8680f974 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -22,7 +22,7 @@ Extend PR #2718's `changes` job with per-test-group `skip_*` boolean outputs der **Not in scope**: a parallel CI gate mechanism; new path-classification source-of-truth (must reuse PR #2718's `gunbc-quick` `changes` job). -**Single source of truth invariant**: all path classification flows from one `changes` job. Layer 1 produces `code: bool`; Layer 2 grows additional outputs (`skip_lens: bool`, `skip_emit: bool`, `skip_parser: bool`, ...) on the same job. No second `gunbc-quick` job. No `actions/cache`-fork. No parallel diff mechanism. +**Single source of truth invariant**: all path classification flows from one `changes` job. Layer 1 produces `code: bool`; Layer 2 grows additional outputs (`skip_cost_lens: bool`, `skip_emit_target: bool`, `skip_parser_grammar: bool`, ...) on the same job — each output named `skip_` matching the per-group table's `group_name` column verbatim per §1 naming convention. No second `gunbc-quick` job. No `actions/cache`-fork. No parallel diff mechanism. ## §1. Mechanism (extend PR #2718, do not parallel) From 0d3b44be061b73a9c2e77cb93f9388eb8c775e81 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 00:04:06 +0000 Subject: [PATCH 20/34] docs(briefs): add P3 fail-closed shared-infrastructure full-run bucket per codex BLOCKING MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex REQUEST_CHANGES on PR #2719 at sha 52c6cf0f (review #9744): Line 102 narrowed required-paths inventory to 'src/v3/*' deps only; the illustrative table at lines 114-118 followed that shape. A PR that changes shared test infrastructure or selection machinery outside src/v3/* (.github/workflows/ci.yml, scripts/*, Cargo.lock, rust-toolchain.toml, etc.) would be classified as 'unaffected' for every per-group regex and silently skip tests whose behavior actually changed. That's the fail-open boundary class P3 forbids + TESTING.md behavior-driven discipline violation. Real correctness issue in the proposed mechanism, not just an implementation detail. Fix: add shared-infrastructure full-run fail-closed bucket as the join-point that catches inter-group / cross-cutting changes: §2 (inventory sources): added 'Shared-infrastructure full-run fail-closed bucket' subsection with explicit mechanism — changes job computes force_full_run = (any changed file matches shared-infra regex); when true, all per-group skip_* short-circuit to false. Regex spec: ^(\.github/.*|scripts/.*|Cargo\.(toml|lock)|rust-toolchain\.toml| \.cargo/.*|build\.rs)$. Names the structural rationale: per-group regexes cover ONLY their own src/v3/* deps; the full-run trigger is the join-point. Fail-closed by construction. §4 hard constraint #9 (new): formalizes the invariant + 'never collapse the full-run trigger into per-group regexes' (structural fail-open shape). §5 acceptance: added 'Shared-infrastructure full-run check passes' as separate criterion + self-test case (c) — a PR touching only .github/workflows/ci.yml or Cargo.lock or scripts/check-test-timeout.sh MUST run all test groups. Expanded self-test from 3 to 4 cases (a/b/c/d). §2 added [Mgr-fill]: validate shared-infra regex against representative recent PRs. Single-pass absorption; brief now P3 fail-closed at the cross-cutting boundary. --- ...i-layer-2-path-conditional-gating-worker.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index fda8680f974..5438a9c5a46 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -101,6 +101,20 @@ Where: (c) **NEW per-group required-paths mapping** — for each group, hand-author the required-paths regex by examining which `src/v3/*` files the group's tests transitively depend on. This is the bridge-debt artifact; dissolves when the affected-set lens lands. +**Shared-infrastructure full-run fail-closed bucket** (per codex P3 BLOCKING finding 2026-05-12 review #9744): per-group regexes by themselves are NOT sufficient — a PR that changes shared test infrastructure or selection machinery OUTSIDE `src/v3/*` (e.g., `.github/workflows/ci.yml`, `scripts/*`, harness code, `Cargo.toml`/`Cargo.lock`, `rust-toolchain.toml`, `.cargo/config.toml`) would be classified as "unaffected" for every per-group regex and silently skip tests whose behavior actually changed. That's the fail-open boundary class P3 forbids. + +**Mechanism**: the `changes` job MUST gate ALL `skip_*` flags to `false` (force full-run) when any changed file matches the shared-infrastructure regex: + +``` +^(\.github/.*|scripts/.*|Cargo\.(toml|lock)|rust-toolchain\.toml|\.cargo/.*|build\.rs)$ +``` + +Equivalently in step output: `force_full_run = (any changed file ∈ shared-infrastructure regex)`; when `force_full_run = true`, all per-group `skip_*` outputs short-circuit to `false`. Composes with the `code=true|false` Layer 1 gate (docs-only PRs already skip everything via Layer 1; this constraint applies only to code PRs). + +The shared-infrastructure regex MUST be hand-authored at the **changes job level**, not delegated to per-group regexes — every group entry's regex covers ONLY its own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. This is fail-closed by construction: a missing per-group regex entry doesn't matter when shared-infra changes; everything runs. + +**[Mgr-fill]**: validate the shared-infra regex against representative recent PRs that touched `.github/workflows/ci.yml` / `scripts/*` / `Cargo.lock` and confirm those PRs would have `force_full_run = true`. + **Starting template — PM pre-staged Mgr-fill reference doc**: [`docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md`](r3-ci-layer-2-pm-prestaged-mgr-fill-template.md) (landed via PR #2721; 220 lines). The PM template provides: @@ -172,6 +186,7 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). +9. **Shared-infrastructure full-run fail-closed bucket** (P3 invariant; per codex BLOCKING #9744 absorption). Per §2 mechanism: `force_full_run = (any changed file matches shared-infra regex)` short-circuits all per-group `skip_*` to `false`. The regex covers at minimum `.github/*`, `scripts/*`, `Cargo.{toml,lock}`, `rust-toolchain.toml`, `.cargo/*`, `build.rs`. Per-group regexes cover ONLY their own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. **Never collapse the full-run trigger into per-group regexes** — that's the structural fail-open shape. ## §5. Acceptance @@ -182,7 +197,8 @@ The Layer 2 PR-set is acceptable when: - Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) - Every group entry has `dimensions: Set` field (non-empty subset of `docs/design-affected-set-lens.md` §2 enum); set semantics preserve multi-dim consumer fidelity per locked-design union - **Polarity check passes**: every YAML / formula / acceptance-text reference to the dissolution formula uses canonical skip-form `skip = (∩ = ∅)` or equivalent run-form `run = (∩ ≠ ∅)`. Inverted form `skip = (∩ ≠ ∅)` is the fail-open bug pattern; reject in review. -- Self-test: a docs-only PR still triggers Layer 1 (entire `v3` skip — `code=false`); a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups (cost-dimension groups run; other-dimension groups skip); a `push` to main runs everything +- **Shared-infrastructure full-run check passes** (P3 fail-closed): `force_full_run = (any changed file matches shared-infra regex)` is implemented at the `changes` job level; when true, all `skip_*` outputs short-circuit to `false`. Self-test: a PR touching ONLY `.github/workflows/ci.yml` or `Cargo.lock` or `scripts/check-test-timeout.sh` MUST run all test groups (not just the ones whose `src/v3/*` regexes coincidentally match). +- Self-test (4 cases): (a) docs-only PR triggers Layer 1 (entire `v3` skip — `code=false`); (b) a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups (cost-dimension groups run; other-dimension groups skip); (c) a code PR touching only `.github/workflows/ci.yml` triggers ALL test groups via `force_full_run` (P3 fail-closed for shared infra); (d) a `push` to main runs everything - PR body explicitly states bridge-debt + dissolution trigger - `self_host_ratchet` required-check name remains green via existing PR #2718 `if:` widening - No new hand-Rust files; no SG-0 census changes From 5af2bad9577c1475a2eac153801ab0316e6c33fd Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 20:14:50 -0400 Subject: [PATCH 21/34] WIP: gunbc Director --- ...-layer-2-path-conditional-gating-worker.md | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 5438a9c5a46..4ccaa451290 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -70,11 +70,19 @@ v3: - - name: cost-lens integration if: ${{ needs.changes.outputs.skip_cost_lens != 'true' }} - run: cargo test -p v3-compiler --test integration cost_lens_* + run: cargo test -p v3-compiler --test integration cost_lens - name: emit-target integration if: ${{ needs.changes.outputs.skip_emit_target != 'true' }} - run: cargo test -p v3-compiler --test integration *_emit_* + run: cargo test -p v3-compiler --test integration emit # ... per-group test invocations + # IMPORTANT (per openai-pro P3 BLOCKING #9749 absorption): the positional + # argument to `cargo test` after `--test integration` is libtest's + # test-name SUBSTRING filter, NOT a glob. `cost_lens` matches all tests + # whose name CONTAINS "cost_lens"; `cost_lens_*` would be treated as a + # literal substring (with the `*`) and match zero tests — silent skip. + # NEVER use shell-glob syntax (`*`, `?`, etc.) in the positional filter. + # If precision beyond substring is needed, use `--exact` with the + # specific test name OR script-side enumeration via cargo metadata. ``` **Job-level `code` flag retained**: docs-only PRs still skip the entire `v3` job (~67min → 0min). Layer 2 makes the granularity finer for code PRs whose changed-paths affect only some groups. @@ -91,7 +99,7 @@ Where: - `group_name` — short identifier (e.g., `cost_lens`, `emit_target`, `parser_grammar`) - `dimensions: Set` — non-empty subset of `{value, cost, complexity, effect, refinement}` per `docs/design-affected-set-lens.md` §2 union semantics. Single-element sets `{cost}` are valid for single-dim groups; multi-dim consumers MUST list all dimensions they read (e.g., LBP demonstration: `{complexity, cost}`). Empty set is invalid — escalate per §7. - `required_paths_regex` — regex over changed file paths; if no changed file matches, skip this group -- `test_pattern` — `cargo test` arg pattern selecting the group's tests +- `test_pattern` — `cargo test` positional **test-name substring filter** (NOT a glob; libtest's filter is substring-based per `cargo test --help`). Example: `cost_lens` matches all tests whose name contains the literal substring "cost_lens". **Never use shell-glob syntax** (`*`, `?`) in this field — those characters would be treated as literal substring characters and silently match zero tests (fail-open per openai-pro P3 BLOCKING #9749). If precision beyond substring is needed, use `--exact` with the specific test name or enumerate via cargo metadata. **Inventory derivation** (Mgr-fill from 3 sources): @@ -106,9 +114,11 @@ Where: **Mechanism**: the `changes` job MUST gate ALL `skip_*` flags to `false` (force full-run) when any changed file matches the shared-infrastructure regex: ``` -^(\.github/.*|scripts/.*|Cargo\.(toml|lock)|rust-toolchain\.toml|\.cargo/.*|build\.rs)$ +^(\.github/.*|scripts/.*|Cargo\.(toml|lock)|rust-toolchain\.toml|\.cargo/.*|build\.rs|src/v3/compiler/tests/integration/common/.*|src/v3/compiler/tests/integration/sg0_census_test\.rs|src/v3/compiler/tests/integration/test_runner_test\.rs|src/v3/compiler/tests/integration/t_pb_b_1_dag_runner_test\.rs|src/v3/compiler/tests/integration/integration\.rs|src/v3/compiler/tests/integration\.rs)$ ``` +**Harness/test-selection-machinery arms** (per openai-pro P3 BLOCKING #9749 absorption): the regex includes the named harness-code class explicitly — `tests/integration/common/*` (shared test utilities), `sg0_census_test.rs` (census authority), `test_runner_test.rs` (runner framework), `t_pb_b_1_dag_runner_test.rs` (suite enumeration framework), and the integration test entry points. Worker MUST add any new harness-class file to this regex before merging the file. **A harness-class file MUST never appear in a per-group `required_paths_regex` — it always triggers full-run.** + Equivalently in step output: `force_full_run = (any changed file ∈ shared-infrastructure regex)`; when `force_full_run = true`, all per-group `skip_*` outputs short-circuit to `false`. Composes with the `code=true|false` Layer 1 gate (docs-only PRs already skip everything via Layer 1; this constraint applies only to code PRs). The shared-infrastructure regex MUST be hand-authored at the **changes job level**, not delegated to per-group regexes — every group entry's regex covers ONLY its own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. This is fail-closed by construction: a missing per-group regex entry doesn't matter when shared-infra changes; everything runs. @@ -125,12 +135,13 @@ The PM template provides: Inline sketch (illustrative — defer to the PM template for the actual starting inventory). Note `dimensions` column is `Set`; singletons shown as `{cost}`, multi-dim consumers as `{complexity, cost}`: ``` -cost_lens | {cost} | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens_* -complexity_lens | {complexity} | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens_* -lbp_demonstration | {complexity, cost} | ^(src/v3/lenses/(cost|complexity)\.dag|src/v3/compiler/src/.*lbp.*\.rs)$ | lbp_* # multi-dim -emit_target | {effect} | ^(src/v3/extdeps/.*|src/v3/compiler/src/emit/.*|src/v3/compiler/src/omni_shape_.*\.rs)$ | emit_target_* -parser_grammar | {refinement} | ^(src/v3/parser/.*|src/v3/compiler/src/parser.*\.rs|src/v3/compiler/src/lower.*\.rs)$ | parser_grammar_* +cost_lens | {cost} | ^(src/v3/lenses/cost\.dag|src/v3/std/algebra\.dag|src/v3/compiler/src/lens_cost_.*\.rs)$ | cost_lens +complexity_lens | {complexity} | ^(src/v3/lenses/complexity\.dag|src/v3/compiler/src/lens_complexity_.*\.rs)$ | complexity_lens +lbp_demonstration | {complexity, cost} | ^(src/v3/lenses/(cost|complexity)\.dag|src/v3/compiler/src/.*lbp.*\.rs)$ | lbp # multi-dim +emit_target | {effect} | ^(src/v3/extdeps/.*|src/v3/compiler/src/emit/.*|src/v3/compiler/src/omni_shape_.*\.rs)$ | emit +parser_grammar | {refinement} | ^(src/v3/parser/.*|src/v3/compiler/src/parser.*\.rs|src/v3/compiler/src/lower.*\.rs)$ | parser # ... etc per Mgr-fill +# test_pattern is libtest SUBSTRING filter — no globs; `cost_lens` matches every test name containing "cost_lens". ``` **[Mgr-fill]**: full per-group table — exhaustive coverage of `scripts/slow-test-exemptions.txt` 78 entries grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. From 187c33af6a282d60c678e64de496119a4cad47f2 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 00:15:17 +0000 Subject: [PATCH 22/34] =?UTF-8?q?docs(briefs):=20fix=20two=20openai-pro=20?= =?UTF-8?q?BLOCKINGs=20=E2=80=94=20harness-arm=20in=20shared-infra=20regex?= =?UTF-8?q?=20+=20cargo=20test=20substring=20not=20glob?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit openai-pro REQUEST_CHANGES on PR #2719 at sha 0d3b44be (review #9749 + manual c4426188322): BLOCKING #1 (P3 Fail-Closed): brief at line 104 names 'harness code' as a class to catch in full-run regex but the actual regex at line 109 had no harness/test-selection arm. Harness-only changes (e.g., to tests/integration/common/* or sg0_census_test.rs) would miss both full-run regex AND per-group regexes — silent skip. BLOCKING #2 (TESTING.md fail-closed CI): test_pattern field documented as 'cargo test arg pattern' but examples used glob-looking syntax (cost_lens_*, *_emit_*). Cargo positional test arg is a libtest SUBSTRING filter, not a glob. Worker following the brief literally would produce a step that runs zero intended tests + exits successfully — silent skip converting 'selected group tested' into 'selected group filtered out.' Fixes: #1 (harness arm in shared-infra regex): - §2 mechanism: extended regex to include src/v3/compiler/tests/integration/common/.*, sg0_census_test.rs, test_runner_test.rs, t_pb_b_1_dag_runner_test.rs, integration.rs, integration test entry points - §2 new paragraph naming the harness/test-selection-machinery arms explicitly + hard rule: harness-class files MUST never appear in a per-group required_paths_regex - §4 hard constraint #9: extended invariant to include harness class with explicit file list - §5 acceptance: extended self-test case (c) to include harness-class example (common/cached_compile.rs) + explicit verification list #2 (cargo test substring, not glob): - §1 YAML examples: cost_lens_* → cost_lens; *_emit_* → emit; added IMPORTANT comment explaining libtest substring semantics + forbidding glob syntax - §2 test_pattern column spec: re-documented as 'libtest test-name SUBSTRING filter (NOT a glob)' with cost_lens example + glob forbiddance + --exact alternative - §2 inline illustrative table: cost_lens_* → cost_lens (and others); added trailing comment naming substring semantics - §4 new hard constraint #10: test_pattern is substring filter not glob; self-test that the value substitutes verbatim into cargo test and runs positive number of tests - §5 acceptance: new 'test_pattern substring-filter check passes' criterion with empirical pilot-wave validation requirement Brief now P3 fail-closed at both the boundary (shared-infra full-run including harness) AND the selector (substring filter that workers can copy verbatim without silent zero-test execution). Single-absorption pass; awaiting fresh review at new HEAD. --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 4ccaa451290..f884b0d6819 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -197,7 +197,8 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). -9. **Shared-infrastructure full-run fail-closed bucket** (P3 invariant; per codex BLOCKING #9744 absorption). Per §2 mechanism: `force_full_run = (any changed file matches shared-infra regex)` short-circuits all per-group `skip_*` to `false`. The regex covers at minimum `.github/*`, `scripts/*`, `Cargo.{toml,lock}`, `rust-toolchain.toml`, `.cargo/*`, `build.rs`. Per-group regexes cover ONLY their own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. **Never collapse the full-run trigger into per-group regexes** — that's the structural fail-open shape. +9. **Shared-infrastructure full-run fail-closed bucket** (P3 invariant; per codex BLOCKING #9744 + openai-pro BLOCKING #9749 absorption). Per §2 mechanism: `force_full_run = (any changed file matches shared-infra regex)` short-circuits all per-group `skip_*` to `false`. The regex covers at minimum: `.github/*`, `scripts/*`, `Cargo.{toml,lock}`, `rust-toolchain.toml`, `.cargo/*`, `build.rs`, AND the **harness/test-selection-machinery class** — `tests/integration/common/*`, `sg0_census_test.rs`, `test_runner_test.rs`, `t_pb_b_1_dag_runner_test.rs`, and integration test entry points. Per-group regexes cover ONLY their own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. **Never collapse the full-run trigger into per-group regexes** — that's the structural fail-open shape. **A harness-class file MUST never appear in a per-group `required_paths_regex`** — its appearance in a changed-file list always triggers full-run. +10. **`test_pattern` is libtest SUBSTRING filter, NOT a glob** (per openai-pro BLOCKING #9749 absorption). The positional argument to `cargo test ... --test integration ` is libtest's test-name substring filter. `cost_lens` matches all tests whose name CONTAINS "cost_lens" literally. Glob characters (`*`, `?`) are treated as literal substring characters and would silently match zero tests. **Never use shell-glob syntax in the `test_pattern` field.** If precision beyond substring is needed, use `--exact` with the specific test name OR enumerate via cargo metadata. Self-test: a worker should be able to copy the `test_pattern` value verbatim into `cargo test -p v3-compiler --test integration ` and have it run a positive number of intended tests. ## §5. Acceptance @@ -208,7 +209,8 @@ The Layer 2 PR-set is acceptable when: - Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) - Every group entry has `dimensions: Set` field (non-empty subset of `docs/design-affected-set-lens.md` §2 enum); set semantics preserve multi-dim consumer fidelity per locked-design union - **Polarity check passes**: every YAML / formula / acceptance-text reference to the dissolution formula uses canonical skip-form `skip = (∩ = ∅)` or equivalent run-form `run = (∩ ≠ ∅)`. Inverted form `skip = (∩ ≠ ∅)` is the fail-open bug pattern; reject in review. -- **Shared-infrastructure full-run check passes** (P3 fail-closed): `force_full_run = (any changed file matches shared-infra regex)` is implemented at the `changes` job level; when true, all `skip_*` outputs short-circuit to `false`. Self-test: a PR touching ONLY `.github/workflows/ci.yml` or `Cargo.lock` or `scripts/check-test-timeout.sh` MUST run all test groups (not just the ones whose `src/v3/*` regexes coincidentally match). +- **Shared-infrastructure full-run check passes** (P3 fail-closed): `force_full_run = (any changed file matches shared-infra regex)` is implemented at the `changes` job level; when true, all `skip_*` outputs short-circuit to `false`. Self-test: a PR touching ONLY `.github/workflows/ci.yml` or `Cargo.lock` or `scripts/check-test-timeout.sh` or `src/v3/compiler/tests/integration/common/cached_compile.rs` (harness-class) MUST run all test groups (not just the ones whose `src/v3/*` regexes coincidentally match). Harness class explicitly verified: any change to `sg0_census_test.rs` / `test_runner_test.rs` / `t_pb_b_1_dag_runner_test.rs` / `tests/integration/common/*` triggers full-run. +- **`test_pattern` substring-filter check passes** (P3 fail-closed): no `test_pattern` value contains glob characters (`*`, `?`); each value, when substituted into `cargo test -p v3-compiler --test integration ` and executed locally, runs a positive number of intended tests. Self-test: pilot wave PR validates this empirically — run the cost-lens group's `test_pattern` and confirm `running N tests` output shows N ≥ expected group cardinality. - Self-test (4 cases): (a) docs-only PR triggers Layer 1 (entire `v3` skip — `code=false`); (b) a code PR touching only `src/v3/lenses/cost.dag` triggers ONLY the cost-related test groups (cost-dimension groups run; other-dimension groups skip); (c) a code PR touching only `.github/workflows/ci.yml` triggers ALL test groups via `force_full_run` (P3 fail-closed for shared infra); (d) a `push` to main runs everything - PR body explicitly states bridge-debt + dissolution trigger - `self_host_ratchet` required-check name remains green via existing PR #2718 `if:` widening From dac81c69b6517e9365e96b49e23473da28d1613a Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 00:18:44 +0000 Subject: [PATCH 23/34] =?UTF-8?q?docs(briefs):=20reframe=20PM=20template?= =?UTF-8?q?=20citation=20per=20codex=20P1/P2=20=E2=80=94=20template=20is?= =?UTF-8?q?=20on=20PR=20#2721,=20NOT=20yet=20landed=20on=20main?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex REQUEST_CHANGES on PR #2719 (review #9754): Line 128 named docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md as a 'landed' starting authority, but git ls-tree origin/main returns no blob and git ls-files returns nothing. A worker following this brief would be sent to a non-existent source of truth — INVARIANTS P1/P2 authority-grounding violation in a dispatch document. Verified at HEAD: - git ls-tree origin/main -- docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md → empty - gh pr view 2721 → state=OPEN, mergedAt=null - Template lives on PR #2721's branch only Fix: reframe the template citation to acknowledge PR #2721 is open-not-landed. - 'landed via PR #2721' → 'open as PR #2721 ... NOT yet landed on main' - Added codex BLOCKING citation + verification receipt (git ls-tree result) - Added explicit authority caveat: Verification Mgr finalization MUST coordinate merge sequencing — (a) merge #2721 first, OR (b) read from PR #2721 branch until it merges - Named PM (deep-wolf-155) as PR #2721 author + cross-link for merge coordination - Cited sha 262f42d7d (PR #2721 post-fix state per PM msg_125e3aa5) Brief now accurately grounded on the actual file location (PR #2721 branch) with merge-sequencing guidance for Mgr finalization. Authority chain honest about in-flight vs landed state. --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index f884b0d6819..d0a6fd9a609 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -125,9 +125,11 @@ The shared-infrastructure regex MUST be hand-authored at the **changes job level **[Mgr-fill]**: validate the shared-infra regex against representative recent PRs that touched `.github/workflows/ci.yml` / `scripts/*` / `Cargo.lock` and confirm those PRs would have `force_full_run = true`. -**Starting template — PM pre-staged Mgr-fill reference doc**: [`docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md`](r3-ci-layer-2-pm-prestaged-mgr-fill-template.md) (landed via PR #2721; 220 lines). +**Starting template — PM pre-staged Mgr-fill reference doc**: `docs/briefs/r3-ci-layer-2-pm-prestaged-mgr-fill-template.md` (open as **PR #2721** at https://github.com/gunb-ai/gunbc/pull/2721; **NOT yet landed on `main`** — verified via codex BLOCKING #9754 absorption 2026-05-12: `git ls-tree origin/main -- ...` returned no blob; file lives only on PR #2721's branch until merge). 220 lines. -The PM template provides: +**Authority caveat per codex P1/P2 catch**: this brief cites the template as the inventory data attachment, but the cited path will be unresolvable on a worker checkout of `main` until PR #2721 merges. Verification Mgr finalization MUST coordinate the merge sequencing: either (a) merge PR #2721 first so the template is on `main` before Mgr-fill starts, OR (b) read the template from PR #2721's branch (e.g., `gh pr view 2721 --repo gunb-ai/gunbc` or checking out `origin/<2721-branch>`) until it merges. Cross-link: PR #2721 author is PM (`deep-wolf-155`); merge coordination is PM-routable. + +The PM template provides (per PR #2721 review-state at sha `262f42d7d` — post fix): - **All 78 `scripts/slow-test-exemptions.txt` entries** grouped into 9 clusters (A–I) by module prefix - **`(test_pattern, dimensions, required_paths_regex)` skeleton table** with every row carrying a `dimensions:` field of type `Set` per locked-design §2 union semantics (PM template post-fix at `dedcf69a4`) - **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single-element set `{cost}`, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family with singleton `{cost}` dimensions. From c02ef5442ccbb283960a4c55874a3514fd1f5693 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 20:55:27 -0400 Subject: [PATCH 24/34] WIP: gunbc Director --- .../r3-ci-layer-2-path-conditional-gating-worker.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index d0a6fd9a609..0542762f798 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -7,7 +7,13 @@ **Authority (cite-and-execute):** - **Operator escalation**: Brian's CI-up-to-1-hour framing at gunbc#846 2026-05-11 ("their CI is up to 1 hour ... not happening" — re v3 ratchet attempt context) - **Layer 1 prior art**: PR #2718 `ci(layer1): skip v3 job on docs-only PRs via changes-filter` — the `changes` job mechanism this brief EXTENDS (not parallels) -- **Bridge-debt → dissolution trigger**: `docs/design-affected-set-lens.md` §5 (affected-set Introspect-lens R3 close-blocking gate) — when `ci_uses_provable_minimal_affected_set_selection` gate lands, Layer 2's hand-authored path-mapping table dissolves and per-group `skip_*` flags become `skip_ = (affected_dimensions ∩ group.dimensions) = ∅` (skip when **intersection is EMPTY** = group's dimensions unaffected; equivalently `run = (intersection ≠ ∅)`). **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: empty-intersection ⇒ unaffected ⇒ skip; non-empty intersection ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. +- **Bridge-debt → dissolution lifecycle (R4-bounded, NOT R3 close)**: per `docs/design-affected-set-lens.md:3` ("**Status**: R4 wishlist (R4.B Introspect-lens saturation lane)") + `:354` ("§5. CI integration sketch (**deferred to R4 full delivery**)") + `:366` ("**Out of scope here**: implementation of the CI integration. The prototype demonstrates the lens output; the CI integration is R4 full-delivery work"). Layer 2's hand-authored path-mapping table dissolves when **R4.B's CI integration delivery** lands the affected-set lens consumer in the `changes` job (currently no ROADMAP authority for a gate named `ci_uses_provable_minimal_affected_set_selection`; that name was a Director-tier placeholder and has been removed per Brian's P5 catch at PR #2719 c#4426351828). **R4 owner**: R4.B saturation lane (no concrete dispatch yet; lane is wishlist per `docs/design-affected-set-lens.md:3`). **R3-tactical framing**: Layer 2 is an R3-cycle CI mitigation bridge whose dissolution lifecycle is bounded by R4 lens-CI delivery, NOT by R3 close. Acknowledged explicitly per Brian's BLOCKING #1 absorption 2026-05-12. +- **Post-dissolution selection semantics (canonical 2-step join per design §5)**: when the lens ships, per-group `skip_*` flags compute via the canonical join: + - **NodeRef intersection**: `(group.testclaim_references ∩ lens.affected_node_refs) ≠ ∅` (per `docs/design-affected-set-lens.md:359`: "intersect aggregate affected-set with TestClaim references") + - **Dimension intersection**: `(group.dimensions ∩ lens.changed_dimensions) ≠ ∅` (per same line: "selection keeps TestClaims whose asserted-dimensions intersect with changed-dimensions") + - **Run condition**: both ≠ ∅ ⇒ run; either ∅ ⇒ skip. Canonical formula: `run = (refs ∩ nodes) ≠ ∅ ∧ (group.dims ∩ changed.dims) ≠ ∅`; equivalently `skip = ¬run = (refs ∩ nodes) = ∅ ∨ (group.dims ∩ changed.dims) = ∅`. + - **Bridge coarseness acknowledgment**: Layer 2's bridge operates at file-path-regex level, NOT TestClaim-reference level. The `required_paths_regex` column is a path-side proxy for the NodeRef-intersection step; bridge over-approximates the canonical (runs MORE tests than canonical would). That's fail-closed-safe direction but structurally coarser — the brief MUST be explicit about this gap. Per Brian's BLOCKING #2 absorption 2026-05-12: the surviving post-dissolution schema MUST include `group.testclaim_references: Set` (or equivalent group-to-NodeRef-membership) as a third column, NOT just `(group_name, dimensions)`. +- **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: NodeRef-empty OR dim-empty ⇒ unaffected ⇒ skip; both non-empty ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. - **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - (a) `scripts/slow-test-exemptions.txt` — 78 active entries (curated >2s ratchet exemption list) From 540113f6c2fd41d96d09d83912666ab76e1fdc7e Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 00:57:27 +0000 Subject: [PATCH 25/34] =?UTF-8?q?docs(briefs):=20absorb=203=20BLOCKING=20f?= =?UTF-8?q?indings=20(Brian=20+=20codex)=20=E2=80=94=20R4=20lifecycle=20re?= =?UTF-8?q?frame=20+=20canonical=202-step=20+=20count=20fix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brian inline BLOCKING #1 + codex BLOCKING #1 (P5 dissolution-trigger authority): brief framed dissolution as R3 close-blocking gate 'ci_uses_provable_minimal_affected_set_selection' but docs/design-affected-set-lens.md:3 = 'R4 wishlist', :354 = 'CI integration sketch (deferred to R4 full delivery)', :366 = 'CI integration is R4 full-delivery work'. No ROADMAP authority exists for the cited gate name — that was Director-tier speculation. Brian inline BLOCKING #2 + codex BLOCKING #2 (Facts Flow Forward / surviving schema): §3 post-dissolution sketch only encoded dimension intersection, silently dropping NodeRef intersection. Canonical 2-step per design §5:359 requires BOTH (TestClaim.refs ∩ affected_nodes) ≠ ∅ AND (TestClaim.dims ∩ changed.dims) ≠ ∅. Reducing surviving schema to (group_name, dimensions) too early. codex non-blocking: slow-test-exemptions.txt count cited as 78 (PM template value); actual is 80 at 2026-05-12T00:50Z (verified locally: grep -v '^#' ... | grep -v '^$' | wc -l = 80). Fixes (single absorption pass): §0 'Bridge-debt → dissolution lifecycle' bullet: - Reframed from 'R3 close-blocking gate' to 'R4-bounded dissolution lifecycle (NOT R3 close)' with explicit citation of design doc :3 + :354 + :366. Names R4.B as R4 owner. Removes the speculative gate name. Names Brian's BLOCKING #1 absorption. §0 NEW 'Post-dissolution selection semantics (canonical 2-step join)' bullet: explicit NodeRef + dimension joins per design :359; run formula; skip formula; bridge coarseness acknowledgment (path-regex over-approximates canonical lens; fail-closed-safe but coarser). Names Brian's BLOCKING #2 absorption. §0 polarity check bullet: updated skip-form to reflect 2-step (NodeRef-empty OR dim-empty ⇒ unaffected ⇒ skip). §2 inventory source (a): count 78 → 80 at 3 sites (replace_all), with explanation that count grows over time + Mgr re-runs grep at finalization rather than relying on stale citations. §2 table column spec: added 'testclaim_references' as 5th column. Cited Brian's BLOCKING #2; explains bridge-tier proxy vs post-dissolution proxy. §2 [Mgr-fill]: extended to require testclaim_references computation per canonical 2-step. §3 YAML post-dissolution sketch: rewrote classify step to compose BOTH NodeRef AND dimension intersections via jq + cite Brian's BLOCKING #2 absorption inline. Header comment names R4.B authority and acknowledges no current ROADMAP gate ID. §4 #4 PR-body bridge-debt template: reworded from 'R3 close-blocking gate' to 'R4.B Introspect-lens saturation lane CI integration delivery; NOT R3 close-blocking.' §8 surviving artifact: corrected from (group_name, dimensions) to (group_name, dimensions, testclaim_references) per canonical; cited Brian's BLOCKING #2. Removed all references to 'ci_uses_provable_minimal_affected_set_selection' as a current ROADMAP gate name; replaced with R4.B owning-lane references + explicit acknowledgment of authority gap. Brief now P5-honest: dissolution trigger is checkable (R4.B owning lane) even if no concrete gate ID yet; surviving schema preserves both lens join inputs per canonical algorithm. --- ...-layer-2-path-conditional-gating-worker.md | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 0542762f798..f07b0777e72 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -16,7 +16,7 @@ - **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: NodeRef-empty OR dim-empty ⇒ unaffected ⇒ skip; both non-empty ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. - **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - - (a) `scripts/slow-test-exemptions.txt` — 78 active entries (curated >2s ratchet exemption list) + - (a) `scripts/slow-test-exemptions.txt` — 80 active entries (verified `grep -v "^#" scripts/slow-test-exemptions.txt | grep -v "^$" | wc -l` = 80 as of 2026-05-12; PM template citation at PR #2721 of "78" is stale by 2 entries) (curated >2s ratchet exemption list) - (b) `/tmp/v3-test-timings.log` — empirical per-test wall-time captured by every CI run via `--report-time` (consumed by `scripts/check-test-timeout.sh`, wired at `.github/workflows/ci.yml:405-424`) - (c) NEW per-group required-paths mapping (the deliverable; bridge-debt artifact) @@ -98,9 +98,11 @@ v3: Per-group mapping table (the deliverable): ``` -(group_name, dimensions, required_paths_regex, test_pattern) +(group_name, dimensions, required_paths_regex, testclaim_references, test_pattern) ``` +**`testclaim_references` column added per Brian's BLOCKING #2 absorption 2026-05-12**: the canonical 2-step selection algorithm per `docs/design-affected-set-lens.md:359` requires `Set` membership AND `Set` intersection. Dropping the NodeRef step (as my prior post-dissolution sketch did) silently violates Facts Flow Forward. Each group entry MUST compute a `testclaim_references: Set` value (union of TestClaim references across the group's tests; sourced from `tests/dag/*` TestClaim authorities at Mgr-fill time). Bridge tier proxy is `required_paths_regex` (file-path-coarse); post-dissolution proxy is `testclaim_references` (NodeRef-precise). + Where: - `group_name` — short identifier (e.g., `cost_lens`, `emit_target`, `parser_grammar`) - `dimensions: Set` — non-empty subset of `{value, cost, complexity, effect, refinement}` per `docs/design-affected-set-lens.md` §2 union semantics. Single-element sets `{cost}` are valid for single-dim groups; multi-dim consumers MUST list all dimensions they read (e.g., LBP demonstration: `{complexity, cost}`). Empty set is invalid — escalate per §7. @@ -152,14 +154,17 @@ parser_grammar | {refinement} | ^(src/v3/parser/.*|src/v3/compiler/sr # test_pattern is libtest SUBSTRING filter — no globs; `cost_lens` matches every test name containing "cost_lens". ``` -**[Mgr-fill]**: full per-group table — exhaustive coverage of `scripts/slow-test-exemptions.txt` 78 entries grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. +**[Mgr-fill]**: full per-group table — exhaustive coverage of current `scripts/slow-test-exemptions.txt` entries (count grows; Mgr re-runs `grep -v "^#" ... | grep -v "^$" | wc -l` at finalization rather than relying on stale citations; 80 at 2026-05-12T00:50Z) grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. **Also required per Brian's BLOCKING #2 absorption**: each group entry must compute `testclaim_references: Set` (union of TestClaim references across group's tests) for the canonical 2-step selection join post-dissolution. Bridge-tier proxy is `required_paths_regex`; post-dissolution proxy is `testclaim_references` populated from `tests/dag/*` TestClaim authorities. ## §3. Per-dimensions structural target — `feedback_parallel_representation_debt` prevention (set semantics per locked-design §2) The Layer 2 path-mapping is bridge-debt by design. The dissolution is the affected-set Introspect-lens (canvas PR #2713 by `clever-tern-670`, locked-design `docs/design-affected-set-lens.md`). When the lens lands, the dissolution is: ```yaml -# Post-dissolution (after ci_uses_provable_minimal_affected_set_selection gate) +# Post-dissolution (after R4.B CI integration delivery per design-affected-set-lens.md §5) +# NOTE per Brian's BLOCKING #1 absorption: no current ROADMAP gate name; R4.B is the +# owning lane (wishlist status per design doc :3). Mgr re-cites a concrete gate ID +# once R4.B ROADMAP authority lands the actual gate. changes: steps: - id: lens @@ -167,15 +172,23 @@ changes: cargo run -p v3-compiler --bin affected_set_lens -- \ --pr-diff origin/main...HEAD \ --output /tmp/affected.json + # lens output: {affected_node_refs: Set, affected_dimensions: Set, per_dim: {dim: Set}} - id: classify run: | - # per-group skip_* derived from lens output, not path-regex. - # Set semantics per locked-design §2: skip iff (affected ∩ group.dimensions) is empty. + # Canonical 2-step selection per docs/design-affected-set-lens.md:359: + # 'intersect aggregate affected-set with TestClaim references; keep + # TestClaims whose asserted-dimensions intersect with changed-dimensions'. + # Per-group skip_* = NOT (NodeRef-intersection AND dim-intersection). for group in cost_lens emit_target parser_grammar ...; do - dims_json="${group_dimensions[$group]}" # JSON array, e.g., '["cost"]' or '["complexity","cost"]' - # (affected_dimensions ∩ group.dimensions) ≠ ∅ → run; otherwise skip - if jq -e --argjson dims "$dims_json" \ - '.affected_dimensions | any(. as $d | $dims | contains([$d]))' \ + dims_json="${group_dimensions[$group]}" # e.g., '["cost"]' or '["complexity","cost"]' + refs_json="${group_testclaim_refs[$group]}" # Set union over group's TestClaims + # run iff BOTH (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅ + # skip = ¬run = either intersection is ∅ + # (Brian BLOCKING #2 absorption: dimension-only check would silently drop NodeRef-step + # and violate Facts Flow Forward per design §5 canonical algorithm.) + if jq -e --argjson dims "$dims_json" --argjson refs "$refs_json" \ + '(.affected_dimensions | any(. as $d | $dims | contains([$d]))) + and (.affected_node_refs | any(. as $n | $refs | contains([$n])))' \ /tmp/affected.json; then echo "skip_$group=false" >> $GITHUB_OUTPUT else @@ -199,7 +212,7 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 1. **Single source of truth for path classification** — the `changes` job (one job, one diff, one classifier). NO parallel `gunbc-quick` job; NO duplicate `git diff` invocation; NO per-group diff fork. 2. **STEP-level `if:` on `v3`, not separate jobs** — keeps `v3`'s `needs:` graph and required-check name stable. `self_host_ratchet` `if:` widening from PR #2718 remains unchanged. 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. -4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; dissolves when `ci_uses_provable_minimal_affected_set_selection` gate lands and lens output replaces `required_paths_regex` column." +4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; lifecycle bounded by R4.B Introspect-lens saturation lane CI integration delivery (per `docs/design-affected-set-lens.md` §5). NOT R3 close-blocking. When R4.B CI integration lands, lens output replaces `required_paths_regex` column and bridge retires." 5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. **Polarity invariant**: `skip_ = (affected ∩ group.dimensions) = ∅` (skip when intersection EMPTY = unaffected). Run-equivalent: `run = (intersection ≠ ∅)`. Never invert — `skip = (∩ ≠ ∅)` is the canonical fail-open boolean-polarity bug pattern (silently skips affected groups). Carrier name matches contract: `skip_*` flag is true when group is unaffected. 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). @@ -252,8 +265,8 @@ Do not push a workaround PR for any of these. **This brief produces a bridge.** Per BridgeLedgerZero discipline + `feedback_bridge_debt_window_cadence`, every bridge has a named dissolution trigger: - **Bridge**: per-group `required_paths_regex` table (hand-authored, file-path-substring-based) -- **Dissolution trigger**: gate `ci_uses_provable_minimal_affected_set_selection` lands ⇒ affected-set Introspect-lens output replaces `required_paths_regex` column -- **Surviving artifact post-dissolution**: `(group_name, dimensions)` mapping — the `dimensions: Set` column remains as the lens consumer; only path-regex column retires +- **Dissolution trigger** (R4-bounded per Brian BLOCKING #1 absorption): R4.B Introspect-lens saturation lane delivers CI integration per `docs/design-affected-set-lens.md` §5 ⇒ affected-set lens output replaces `required_paths_regex` column. **No current ROADMAP gate name exists** for this dissolution; the prior placeholder `ci_uses_provable_minimal_affected_set_selection` was Director-tier speculation and has been removed throughout this brief. Mgr re-cites concrete gate ID once R4.B authority lands one. +- **Surviving artifact post-dissolution** (corrected per Brian's BLOCKING #2 absorption 2026-05-12): `(group_name, dimensions, testclaim_references)` mapping — BOTH `dimensions: Set` AND `testclaim_references: Set` columns survive as lens consumers per the canonical 2-step selection join (`docs/design-affected-set-lens.md:359`). Only the `required_paths_regex` column retires; `testclaim_references` replaces it as the NodeRef-precise version of group-tests-membership. Surviving schema is 3 columns, not 2. Cite the dissolution path in every Layer 2 PR body. When the gate lands, a single follow-up PR retires the bridge and the brief is done. From ee36b11886eaf6ae1c71a5d73d24928976306053 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 00:59:19 +0000 Subject: [PATCH 26/34] =?UTF-8?q?docs(briefs):=20reconcile=20=C2=A73=20sub?= =?UTF-8?q?stantive=20+=20=C2=A77=20STOP=20with=20=C2=A70/=C2=A78=20?= =?UTF-8?q?=E2=80=94=20surviving=20schema=20is=203-column=20(cursor=20inte?= =?UTF-8?q?rnal-consistency=20catch)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cursor REQUEST_CHANGES on PR #2719 sha 540113f6c (review #9767): Two internal contradictions surfaced from my partial absorption of Brian's BLOCKING #2: (a) §3 substantive paragraph still said '(group_name, dimensions) mapping survives the dissolution — only required_paths_regex column gets retired' contradicting §0 + §8 which were updated to 3-column (group_name, dimensions, testclaim_references). (b) §7 STOP bullet referenced 'Layer 2 dissolution shape doesn't match (group_name, dimensions) schema' — 2-column framing, same contradiction. Fix: §3 substantive paragraph (around the parallel-representation-debt rationale): - 2-column → 3-column framing - both dimensions AND testclaim_references must be authored - cite design §:359 canonical 2-step join - cite cursor internal-consistency catch alongside Brian's BLOCKING #2 §7 STOP escalation bullet: - (group_name, dimensions) → (group_name, dimensions, testclaim_references) + cite canonical 2-step join Verified via grep: all remaining references are within meta-statements explicitly documenting the removal (line 10 + line 268); no live references remain. All appearances are either in updated 3-column contexts or in meta-statements referencing the absorption (line 15 catch citation). Brief now internally coherent across §0, §3, §7, §8 on: - dissolution trigger (R4.B owning lane, NOT removed-gate-name) - surviving schema (3 columns including testclaim_references) - canonical 2-step join semantics --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index f07b0777e72..04177cc9e55 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -197,7 +197,7 @@ changes: done ``` -**The `(group_name, dimensions)` mapping survives the dissolution** — only the `required_paths_regex` column gets retired (replaced by lens-provided per-dimension affected-set). For this to work, **every Layer 2 path-mapping entry MUST have a `dimensions:` field of type `Set` with members from the lens enum exactly**. +**The `(group_name, dimensions, testclaim_references)` mapping survives the dissolution** (corrected per Brian's BLOCKING #2 absorption + cursor internal-consistency catch 2026-05-12) — only the `required_paths_regex` column gets retired (replaced by `testclaim_references: Set` as the NodeRef-precise version of group-tests-membership). **Both** `dimensions: Set` AND `testclaim_references: Set` columns survive as lens consumers per the canonical 2-step selection join at `docs/design-affected-set-lens.md:359`. For this to work, **every Layer 2 path-mapping entry MUST have a `dimensions:` field of type `Set` AND a `testclaim_references:` field of type `Set`, with members sourced from the lens enum + `tests/dag/*` TestClaim authorities exactly**. This is the parallel-representation-debt prevention. If Layer 2's group-classification diverges from the lens's dimension axis (e.g., Layer 2 groups by file-area but lens groups by dimension), dissolution becomes a schema-migration rather than a column-retirement. @@ -255,7 +255,7 @@ Escalate via dashboard-message to Verification Mgr (`clever-tern-670`) if: - The `changes` job exceeds 3-minute cap once Layer 2 classification logic added (mechanism-shape question) - Required-paths regex authoring produces false-negatives (test skipped that should have run) in self-test — escalate to widen regex, NOT to disable group classification - `self_host_ratchet` `if:` widening breaks when interacting with per-step `if:` — coordinate with PR #2718 author for the predicate composition -- Layer 2 dissolution shape (when affected-set lens lands) doesn't match the `(group_name, dimensions)` schema — substrate-shape question, escalate to Substrate Mgr coordinator +- Layer 2 dissolution shape (when R4.B CI integration lands) doesn't match the `(group_name, dimensions, testclaim_references)` schema per canonical 2-step join — substrate-shape question, escalate to Substrate Mgr coordinator - A group consumer reads multi-dim but it's unclear which dimensions are load-bearing — escalate to Coordinator for dimension-set assignment (do NOT default to singleton `{primary}`; that's the fail-open shape PM caught in template review) Do not push a workaround PR for any of these. From 487d17504ae7929a5839f35c29b0e21bfd41ee5e Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 01:18:59 +0000 Subject: [PATCH 27/34] =?UTF-8?q?docs(briefs):=20fix=20stale=2078=20invent?= =?UTF-8?q?ory=20references=20at=20=C2=A72=20lines=20114=20+=20141=20per?= =?UTF-8?q?=20openai-pro=20BLOCKING?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit openai-pro REQUEST_CHANGES on PR #2719 sha 8ae7938a (review #9779): Brief had stale '78 active >2s entries' at line 114 + 'All 78 ... entries' at line 141, despite §0 line 19 + §2 line 157 stating live count is 80 and Mgr should re-run count at finalization. A worker following §2 literally could build the gating table from stale 78-entry basis, omitting 2 slow-test entries — fail-open shape against the brief's own P3 fail-closed contract (under-inventory = exemption falls in neither per-group regex nor full-run bucket = silently skipped). Fix: §2 inventory source (a) (line 114): replaced 'start with the 78 active >2s entries' with 'start with the current live count of active >2s entries (Mgr MUST re-run grep ... | wc -l at finalization; 80 at 2026-05-12T00:50Z but count grows; do NOT cite the stale 78 from PM template PR #2721 or any earlier reference)'. Added 'fail-closed completeness invariant' inline: every active exemption MUST appear in either a per-group required_paths_regex OR the harness/shared-infra full-run bucket; no exemption left unclassified. §2 PM template description (line 141): 'All 78 entries' → 'PM-grouped entries (PM template snapshot was 78 at template authoring time; live count grows — Mgr re-verifies via wc -l at finalization, NOT this stale historical reference)'. Added note that the 9-cluster taxonomy survives count growth; Mgr maps new entries to existing clusters or escalates if a new cluster surface emerges. Brief is now internally consistent on inventory-count freshness: - §0 line 19: live 80 with verification command - §2 line 114: re-run command at finalization; explicit do-not-cite-78 instruction - §2 line 141: PM template snapshot historical; live count grows - §2 line 157 (Mgr-fill): re-run grep, don't trust stale citations 12th distinct review-class catch this polish cycle: inventory-citation freshness as fail-closed completeness invariant. --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 04177cc9e55..7cec493d144 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -111,7 +111,7 @@ Where: **Inventory derivation** (Mgr-fill from 3 sources): -(a) **`scripts/slow-test-exemptions.txt`** — start with the 78 active >2s entries. Each entry already has citation discipline; group by `_test.rs` file-area prefix. +(a) **`scripts/slow-test-exemptions.txt`** — start with the **current live count** of active >2s entries (Mgr MUST re-run `grep -v '^#' scripts/slow-test-exemptions.txt | grep -v '^$' | wc -l` at finalization time; 80 at 2026-05-12T00:50Z but count grows over time; do NOT cite the stale "78" from PM template PR #2721 or any earlier reference). Each entry already has citation discipline; group by `_test.rs` file-area prefix. **Fail-closed completeness invariant** (per openai-pro BLOCKING #9779 absorption 2026-05-12): under-inventory is the fail-open shape — every active exemption MUST appear in either a per-group `required_paths_regex` row OR the harness/shared-infra full-run bucket. No exemption left unclassified. (b) **`/tmp/v3-test-timings.log` empirical** — last N CI runs aggregated → top-K slowest groups by file-area. Cross-validates (a) and surfaces non-exempted slow tests. @@ -138,7 +138,7 @@ The shared-infrastructure regex MUST be hand-authored at the **changes job level **Authority caveat per codex P1/P2 catch**: this brief cites the template as the inventory data attachment, but the cited path will be unresolvable on a worker checkout of `main` until PR #2721 merges. Verification Mgr finalization MUST coordinate the merge sequencing: either (a) merge PR #2721 first so the template is on `main` before Mgr-fill starts, OR (b) read the template from PR #2721's branch (e.g., `gh pr view 2721 --repo gunb-ai/gunbc` or checking out `origin/<2721-branch>`) until it merges. Cross-link: PR #2721 author is PM (`deep-wolf-155`); merge coordination is PM-routable. The PM template provides (per PR #2721 review-state at sha `262f42d7d` — post fix): -- **All 78 `scripts/slow-test-exemptions.txt` entries** grouped into 9 clusters (A–I) by module prefix +- **PM-grouped `scripts/slow-test-exemptions.txt` entries** (PM template snapshot was 78 entries at template authoring time; live count grows — Mgr re-verifies via `wc -l` at finalization, NOT this stale historical reference) grouped into 9 clusters (A–I) by module prefix. The 9-cluster taxonomy survives even as new entries land; Mgr maps new entries to existing clusters or escalates if a new cluster surface emerges. - **`(test_pattern, dimensions, required_paths_regex)` skeleton table** with every row carrying a `dimensions:` field of type `Set` per locked-design §2 union semantics (PM template post-fix at `dedcf69a4`) - **Pilot recommendation: Cluster B** (Lane 2 Stage 2d symbolic cost — high confidence, single-element set `{cost}`, ~6 tests). Note: my §6 recommendation was `cost_lens` first — these converge; Cluster B IS the cost-lens family with singleton `{cost}` dimensions. - **12 `[Mgr-fill]` placeholders** marking where consumer-tracing exceeded PM bandwidth (substrate-lens deps, R3-V L4/L7, R1C-E `.dag` wrapper, free-consequences cross-target). These are the Mgr-tier sub-classification decisions. From a834c95d4344fa0a559662963717fed55af6ce37 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 01:19:45 +0000 Subject: [PATCH 28/34] =?UTF-8?q?docs(briefs):=20=C2=A75=20acceptance=20re?= =?UTF-8?q?quires=20testclaim=5Freferences=20explicitly=20per=20codex=20BL?= =?UTF-8?q?OCKING=20#9780?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit codex REQUEST_CHANGES on PR #2719 sha 8ae7938a (review #9780): Finding #1 (stale 78 at lines 114 + 141) already fixed at prior commit 487d17504; codex finding overlaps with openai-pro #9779 absorbed before. Finding #2 (new): §5 acceptance at line 228 only required dimensions: Set on each group entry, NOT testclaim_references: Set, even though the brief makes that column load-bearing at: - §0 line 104 (post-dissolution selection canonical 2-step) - §3 line 178 (substantive paragraph: 3-column surviving schema) - §8 line 269 (surviving artifact 3-column) A Mgr reading §5 acceptance literally could call PR-set 'done' with dimensions-only column population — that's the dimensions-only closeout codex flags as facts-flow-forward violation. Fix: §5 acceptance adds new explicit criterion: 'Every group entry has testclaim_references: Set field' with explicit citation chain (design §:359 + Brian BLOCKING #2 + codex BLOCKING #9780). Includes bridge-tier-proxy vs post-dissolution-proxy note. Includes 'Dimensions-only acceptance closeout is rejected: P2 facts-flow-forward requires both lens-join inputs.' §5 acceptance now coherent with §0/§3/§8 on the 3-column surviving schema; no path to 'done' that skips testclaim_references. 13th distinct review-class catch this polish cycle: acceptance-vs-substantive-text divergence on load-bearing fields. --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 7cec493d144..b5fedc29966 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -229,6 +229,7 @@ The Layer 2 PR-set is acceptable when: - `v3` step-level `if:` predicates wired for each group - Per-group path-mapping table cites all 3 inventory sources (a)(b)(c) - Every group entry has `dimensions: Set` field (non-empty subset of `docs/design-affected-set-lens.md` §2 enum); set semantics preserve multi-dim consumer fidelity per locked-design union +- **Every group entry has `testclaim_references: Set` field** (per canonical 2-step join at `docs/design-affected-set-lens.md:359` + Brian's BLOCKING #2 absorption + codex BLOCKING #9780 absorption 2026-05-12) — populated from `tests/dag/*` TestClaim authorities at Mgr-fill time. NodeRef-precise version of group-tests-membership; survives the dissolution alongside `dimensions`. Bridge-tier proxy is `required_paths_regex` (file-path-coarse); post-dissolution, `testclaim_references` replaces the regex column in the 3-column surviving schema. **Dimensions-only acceptance closeout is rejected**: P2 facts-flow-forward requires both lens-join inputs. - **Polarity check passes**: every YAML / formula / acceptance-text reference to the dissolution formula uses canonical skip-form `skip = (∩ = ∅)` or equivalent run-form `run = (∩ ≠ ∅)`. Inverted form `skip = (∩ ≠ ∅)` is the fail-open bug pattern; reject in review. - **Shared-infrastructure full-run check passes** (P3 fail-closed): `force_full_run = (any changed file matches shared-infra regex)` is implemented at the `changes` job level; when true, all `skip_*` outputs short-circuit to `false`. Self-test: a PR touching ONLY `.github/workflows/ci.yml` or `Cargo.lock` or `scripts/check-test-timeout.sh` or `src/v3/compiler/tests/integration/common/cached_compile.rs` (harness-class) MUST run all test groups (not just the ones whose `src/v3/*` regexes coincidentally match). Harness class explicitly verified: any change to `sg0_census_test.rs` / `test_runner_test.rs` / `t_pb_b_1_dag_runner_test.rs` / `tests/integration/common/*` triggers full-run. - **`test_pattern` substring-filter check passes** (P3 fail-closed): no `test_pattern` value contains glob characters (`*`, `?`); each value, when substituted into `cargo test -p v3-compiler --test integration ` and executed locally, runs a positive number of intended tests. Self-test: pilot wave PR validates this empirically — run the cost-lens group's `test_pattern` and confirm `running N tests` output shows N ≥ expected group cardinality. From 403833e43c50d3b31e9be740cbe72d1526bb1ea6 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 01:36:32 +0000 Subject: [PATCH 29/34] docs(briefs): fix polarity-bullet dimensions-only residuals per cursor catch on #2725 review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cursor APPROVE_WITH_COMMENTS on PR #2725 (review #9799) but finding applies to PR #2719's brief — lines 208 + 217 Polarity invariant bullets restated post-dissolution skip/run formula via dimensions-only, conflicting with the canonical 2-step join correctly stated at §3 substantive paragraph (line 200) + §3 YAML sketch (line 178-188) + §5 acceptance (line 231-232). Real residual from partial absorption (same class as catch #11 cursor internal-consistency: when canonical algorithm gets corrected, polarity bullets need parallel update). Fix: update §3 Polarity invariant paragraph + §4 hard constraint #5 Polarity invariant sub-bullet to compose BOTH NodeRef AND dimension intersections per canonical 2-step join: run = (refs ∩ nodes) ≠ ∅ AND (dims ∩ dims) ≠ ∅ skip = ¬run = either intersection ∅ Explicitly names TWO fail-open bug patterns: (a) inversion (skip = (∩ ≠ ∅)) and (b) dimension-only collapse (drops NodeRef-step). Bridge-tier over-approximation note preserved (bridge runs more tests than canonical; fail-closed-safe direction). 14th distinct review-class catch this polish cycle: polarity-vs-canonical- join-coupling — when canonical algorithm gets updated, polarity bullets need parallel update to compose both intersections, not just dimensions. --- ...-ci-layer-2-path-conditional-gating-worker.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index b5fedc29966..b34814d3d5b 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -205,7 +205,19 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi **Hard constraint**: no group entry without a `dimensions:` field of type `Set` with members from the lens enum. Single-element sets like `{cost}` are valid for single-dim groups. Empty set is invalid. If a group doesn't fit any of the 5 dimensions cleanly, escalate to Coordinator — that's a substrate-shape question, not a Layer 2 design choice. -**Polarity invariant** (per PM caught inversion 2026-05-11 via openai-pro RC #9721 on template PR #2721, fixed at `262f42d7d`): the carrier name is `skip_`. CI consumer wires `if: skip_ != 'true'` (i.e., RUN when `skip` is false). The dissolution formula MUST therefore be `skip = (affected ∩ group.dimensions) = ∅` (skip when intersection is **empty** = group's dimensions unaffected). The inverted form `skip = (∩ ≠ ∅)` is a fail-open boolean-polarity bug: it would silently skip AFFECTED groups when the intersection is non-empty. Skip-form is canonical (matches carrier name); run-form `run = (∩ ≠ ∅)` is the equivalent run-carrier statement. Any acceptance-criterion / YAML example / formula citation in this brief or its Mgr-fill output MUST use the canonical skip-form (empty intersection) or the equivalent run-form (non-empty intersection) — never invert. +**Polarity invariant** (per PM caught inversion 2026-05-11 via openai-pro RC #9721 + cursor APPROVE_WITH_COMMENTS on #2725 2026-05-12 catching dimensions-only residual): the carrier name is `skip_`. CI consumer wires `if: skip_ != 'true'` (i.e., RUN when `skip` is false). **Post-dissolution, the dissolution formula is the CANONICAL 2-STEP JOIN per `docs/design-affected-set-lens.md:359` — BOTH NodeRef AND dimension intersections required**: + +``` +run = (group.testclaim_references ∩ lens.affected_node_refs) ≠ ∅ + AND (group.dimensions ∩ lens.changed_dimensions) ≠ ∅ +skip = ¬run = (refs ∩ nodes) = ∅ OR (dims ∩ dims) = ∅ +``` + +**The dimensions-only form `skip = (affected ∩ group.dimensions) = ∅` is INCOMPLETE** — it silently drops the NodeRef-intersection step, violating Facts Flow Forward (catch #9 absorption). Both inversion (`skip = (∩ ≠ ∅)` instead of `=∅`) and dimension-only collapse are fail-open bug patterns. + +**Bridge-tier note**: at bridge stage (pre-dissolution), per-group `skip_*` derives from `(changed-files ∩ required_paths_regex) = ∅` — a path-side proxy for the canonical 2-step (over-approximates: bridge runs MORE tests than canonical because regex coverage > NodeRef precision). Bridge-tier skip-form remains canonical (empty intersection) but operates on a coarser carrier than post-dissolution. + +Any acceptance-criterion / YAML example / formula citation in this brief or its Mgr-fill output MUST use the canonical skip-form (empty intersection) AND, post-dissolution, the full 2-step conjunction — never invert + never collapse to dimensions-only. ## §4. Hard constraints @@ -214,7 +226,7 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. 4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; lifecycle bounded by R4.B Introspect-lens saturation lane CI integration delivery (per `docs/design-affected-set-lens.md` §5). NOT R3 close-blocking. When R4.B CI integration lands, lens output replaces `required_paths_regex` column and bridge retires." 5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. - **Polarity invariant**: `skip_ = (affected ∩ group.dimensions) = ∅` (skip when intersection EMPTY = unaffected). Run-equivalent: `run = (intersection ≠ ∅)`. Never invert — `skip = (∩ ≠ ∅)` is the canonical fail-open boolean-polarity bug pattern (silently skips affected groups). Carrier name matches contract: `skip_*` flag is true when group is unaffected. + **Polarity invariant** (post-cursor catch on #2725 review 2026-05-12): post-dissolution `run = (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅`; `skip = ¬run = either intersection ∅`. Bridge-tier proxy `skip = (changed-files ∩ required_paths_regex) = ∅` over-approximates canonical (runs more tests; fail-closed-safe). **Two fail-open bug patterns to reject in review**: (a) inversion `skip = (∩ ≠ ∅)` instead of `= ∅`; (b) dimension-only collapse `skip = (dims ∩ dims) = ∅` dropping the NodeRef-intersection step. Carrier name matches contract: `skip_*` flag is true when group is unaffected (both lens-join inputs are empty). 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). From 813ef7473437d33780f5acdf12913a34527fb18f Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 21:57:52 -0400 Subject: [PATCH 30/34] WIP: gunbc Director --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index b34814d3d5b..b0529cdd2e8 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -226,7 +226,7 @@ Any acceptance-criterion / YAML example / formula citation in this brief or its 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. 4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; lifecycle bounded by R4.B Introspect-lens saturation lane CI integration delivery (per `docs/design-affected-set-lens.md` §5). NOT R3 close-blocking. When R4.B CI integration lands, lens output replaces `required_paths_regex` column and bridge retires." 5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. - **Polarity invariant** (post-cursor catch on #2725 review 2026-05-12): post-dissolution `run = (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅`; `skip = ¬run = either intersection ∅`. Bridge-tier proxy `skip = (changed-files ∩ required_paths_regex) = ∅` over-approximates canonical (runs more tests; fail-closed-safe). **Two fail-open bug patterns to reject in review**: (a) inversion `skip = (∩ ≠ ∅)` instead of `= ∅`; (b) dimension-only collapse `skip = (dims ∩ dims) = ∅` dropping the NodeRef-intersection step. Carrier name matches contract: `skip_*` flag is true when group is unaffected (both lens-join inputs are empty). + **Polarity invariant** (post-cursor catch on #2725 review 2026-05-12): post-dissolution `run = (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅`; `skip = ¬run = either intersection ∅`. Bridge-tier proxy `skip = (changed-files ∩ required_paths_regex) = ∅` over-approximates canonical (runs more tests; fail-closed-safe). **Two fail-open bug patterns to reject in review**: (a) inversion `skip = (∩ ≠ ∅)` instead of `= ∅`; (b) dimension-only collapse `skip = (dims ∩ dims) = ∅` dropping the NodeRef-intersection step. Carrier name matches contract: `skip_*` flag is true when group is unaffected — i.e., **either** lens-join input is empty (`(refs ∩ nodes) = ∅` OR `(dims ∩ changed_dims) = ∅`). The "both lens-join inputs empty" framing is **stricter than canonical** and would itself be a fail-closed (run when canonical says skip) bug if implemented literally — reject in review. 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). @@ -289,6 +289,7 @@ Cite the dissolution path in every Layer 2 PR body. When the gate lands, a singl - [ ] Complete per-group inventory (sources (a)+(b); table column (c)) — recommend PM pre-staged skeleton if/when available - [ ] Per-group `dimensions: Set` assignments validated against `docs/design-affected-set-lens.md` §2 union semantics — multi-dim consumers MUST list all dimensions they read (no silent-skip on non-primary dim changes) +- [ ] **Per-group `testclaim_references: Set` populated** (per Brian BLOCKING #2 absorption + codex non-blocking improvement #9817; required for canonical 2-step join post-dissolution; sourced from `tests/dag/*` TestClaim authorities at Mgr-fill time; P2 facts-flow-forward gate) - [ ] Per-group `required_paths_regex` tested against 3-5 representative recent PRs for false-positive/false-negative rate - [ ] Pilot wave selection (recommend `cost_lens` first per §6) - [ ] Coordination ack from PR #2718 author on `self_host_ratchet` `if:` interaction shape From 61c38d4472e51079f07a807d4c7688518564304d Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 02:07:51 +0000 Subject: [PATCH 31/34] =?UTF-8?q?docs(briefs):=20fix=20(dims=20=E2=88=A9?= =?UTF-8?q?=20dims)=20typos=20to=20(dims=20=E2=88=A9=20changed=5Fdims)=20p?= =?UTF-8?q?er=20cursor=20#9821=20+=20harmonize=20line=20216=20notation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cursor APPROVE_WITH_COMMENTS on #2719 review #9821: notation slip at lines 213 + 229 — '(dims ∩ dims) = ∅' is self-intersection (always trivially the set itself if non-empty) and doesn't match the canonical formula '(dims ∩ changed_dims) = ∅' stated at line 211-212. Workers copying the shorthand could encode the wrong predicate (always-empty if changed_dims absent / never-empty if treated as identity). Fixes: Line 213 (canonical 2-step join boxed formula): (dims ∩ dims) → (dims ∩ changed_dims) matching the 'AND' clause at line 212. Line 229 fail-open pattern (b) dimension-only collapse: 'skip = (dims ∩ dims) = ∅' → 'skip = (dims ∩ changed_dims) = ∅ (using ONLY the dimension intersection clause, dropping the NodeRef-intersection step from the canonical conjunction)'. Explanatory framing added. Line 216 exploratory: 'skip = (affected ∩ group.dimensions) = ∅' → 'skip = (dims ∩ changed_dims) = ∅ (i.e., using ONLY the dimension intersection clause...)'. Harmonized with §3 canonical notation (dims/changed_dims throughout); reduced reader-friction per cursor's exploratory observation. 20th distinct review-class catch this polish cycle: self-intersection-notation-shorthand-vs-canonical — when shorthand '(X ∩ X)' is used instead of the canonical '(X1 ∩ X2)' join expression, it's notation-class fail-open (workers may copy literally and lose the distinction between the operand sets). --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index b0529cdd2e8..d89687b33b3 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -210,10 +210,10 @@ This is the parallel-representation-debt prevention. If Layer 2's group-classifi ``` run = (group.testclaim_references ∩ lens.affected_node_refs) ≠ ∅ AND (group.dimensions ∩ lens.changed_dimensions) ≠ ∅ -skip = ¬run = (refs ∩ nodes) = ∅ OR (dims ∩ dims) = ∅ +skip = ¬run = (refs ∩ nodes) = ∅ OR (dims ∩ changed_dims) = ∅ ``` -**The dimensions-only form `skip = (affected ∩ group.dimensions) = ∅` is INCOMPLETE** — it silently drops the NodeRef-intersection step, violating Facts Flow Forward (catch #9 absorption). Both inversion (`skip = (∩ ≠ ∅)` instead of `=∅`) and dimension-only collapse are fail-open bug patterns. +**The dimensions-only form `skip = (dims ∩ changed_dims) = ∅` (i.e., using ONLY the dimension intersection clause from the canonical conjunction) is INCOMPLETE** — it silently drops the NodeRef-intersection step `(refs ∩ nodes) = ∅`, violating Facts Flow Forward (catch #9 absorption). Both inversion (`skip = (∩ ≠ ∅)` instead of `= ∅`) and dimension-only collapse are fail-open bug patterns. **Bridge-tier note**: at bridge stage (pre-dissolution), per-group `skip_*` derives from `(changed-files ∩ required_paths_regex) = ∅` — a path-side proxy for the canonical 2-step (over-approximates: bridge runs MORE tests than canonical because regex coverage > NodeRef precision). Bridge-tier skip-form remains canonical (empty intersection) but operates on a coarser carrier than post-dissolution. @@ -226,7 +226,7 @@ Any acceptance-criterion / YAML example / formula citation in this brief or its 3. **No new `actions/cache` keys or workflow-tier infrastructure** — Layer 2 is path-regex + boolean output; nothing more. 4. **Bridge-debt acknowledgment in every PR**: each PR landing a Layer 2 group must include in body: "Bridge-debt; lifecycle bounded by R4.B Introspect-lens saturation lane CI integration delivery (per `docs/design-affected-set-lens.md` §5). NOT R3 close-blocking. When R4.B CI integration lands, lens output replaces `required_paths_regex` column and bridge retires." 5. **`dimensions: Set` field on every group entry** — non-empty subset of the lens enum per locked-design §2 union semantics. Single-element sets valid for single-dim groups; multi-dim consumers MUST list all dimensions they read. Substrate-shape questions on dimension assignment escalate. - **Polarity invariant** (post-cursor catch on #2725 review 2026-05-12): post-dissolution `run = (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅`; `skip = ¬run = either intersection ∅`. Bridge-tier proxy `skip = (changed-files ∩ required_paths_regex) = ∅` over-approximates canonical (runs more tests; fail-closed-safe). **Two fail-open bug patterns to reject in review**: (a) inversion `skip = (∩ ≠ ∅)` instead of `= ∅`; (b) dimension-only collapse `skip = (dims ∩ dims) = ∅` dropping the NodeRef-intersection step. Carrier name matches contract: `skip_*` flag is true when group is unaffected — i.e., **either** lens-join input is empty (`(refs ∩ nodes) = ∅` OR `(dims ∩ changed_dims) = ∅`). The "both lens-join inputs empty" framing is **stricter than canonical** and would itself be a fail-closed (run when canonical says skip) bug if implemented literally — reject in review. + **Polarity invariant** (post-cursor catch on #2725 review 2026-05-12): post-dissolution `run = (refs ∩ affected_node_refs) ≠ ∅ AND (dims ∩ affected_dimensions) ≠ ∅`; `skip = ¬run = either intersection ∅`. Bridge-tier proxy `skip = (changed-files ∩ required_paths_regex) = ∅` over-approximates canonical (runs more tests; fail-closed-safe). **Two fail-open bug patterns to reject in review**: (a) inversion `skip = (∩ ≠ ∅)` instead of `= ∅`; (b) dimension-only collapse `skip = (dims ∩ changed_dims) = ∅` (using ONLY the dimension intersection clause, dropping the NodeRef-intersection step from the canonical conjunction). Carrier name matches contract: `skip_*` flag is true when group is unaffected — i.e., **either** lens-join input is empty (`(refs ∩ nodes) = ∅` OR `(dims ∩ changed_dims) = ∅`). The "both lens-join inputs empty" framing is **stricter than canonical** and would itself be a fail-closed (run when canonical says skip) bug if implemented literally — reject in review. 6. **No closure-allowed carve-outs**: Layer 2's lifetime is bounded by the affected-set lens dissolution. If a group can't be path-classified accurately, it stays in the `code=true` full-run bucket (no special carve). 7. **Push events short-circuit to full-run** — `github.event_name == 'push'` bypasses ALL skip_* flags (run everything on main). Matches Layer 1. 8. **Hand-Rust budget: zero**. Layer 2 lives entirely in `.github/workflows/ci.yml` + an optional path-mapping data file (e.g., `scripts/ci-path-classification.yaml` or inline in the workflow). From e2c4f12adbc5faa4d8f31b111016dfae5a95e976 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Mon, 11 May 2026 22:23:26 -0400 Subject: [PATCH 32/34] WIP: gunbc Director --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index d89687b33b3..270ff7d70da 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -16,7 +16,7 @@ - **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: NodeRef-empty OR dim-empty ⇒ unaffected ⇒ skip; both non-empty ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. - **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - - (a) `scripts/slow-test-exemptions.txt` — 80 active entries (verified `grep -v "^#" scripts/slow-test-exemptions.txt | grep -v "^$" | wc -l` = 80 as of 2026-05-12; PM template citation at PR #2721 of "78" is stale by 2 entries) (curated >2s ratchet exemption list) + - (a) `scripts/slow-test-exemptions.txt` — curated >2s ratchet exemption list. **Mgr-finalization MUST recompute live count** via `grep -v "^#" scripts/slow-test-exemptions.txt | grep -v "^$" | wc -l` at finalization (count fluctuates per hot-fix arcs — e.g., #2723 added cuts; PM template citation at PR #2721 of "78" is historical and stale). Do not cite snapshot integers in this brief — they rot between authoring and Mgr-fill (cursor BLOCKING #9832 absorption 2026-05-12: "80" snapshot already drifted to 84 between authoring and reviewer-fire). - (b) `/tmp/v3-test-timings.log` — empirical per-test wall-time captured by every CI run via `--report-time` (consumed by `scripts/check-test-timeout.sh`, wired at `.github/workflows/ci.yml:405-424`) - (c) NEW per-group required-paths mapping (the deliverable; bridge-debt artifact) @@ -111,7 +111,7 @@ Where: **Inventory derivation** (Mgr-fill from 3 sources): -(a) **`scripts/slow-test-exemptions.txt`** — start with the **current live count** of active >2s entries (Mgr MUST re-run `grep -v '^#' scripts/slow-test-exemptions.txt | grep -v '^$' | wc -l` at finalization time; 80 at 2026-05-12T00:50Z but count grows over time; do NOT cite the stale "78" from PM template PR #2721 or any earlier reference). Each entry already has citation discipline; group by `_test.rs` file-area prefix. **Fail-closed completeness invariant** (per openai-pro BLOCKING #9779 absorption 2026-05-12): under-inventory is the fail-open shape — every active exemption MUST appear in either a per-group `required_paths_regex` row OR the harness/shared-infra full-run bucket. No exemption left unclassified. +(a) **`scripts/slow-test-exemptions.txt`** — start with the **current live count** of active >2s entries (Mgr MUST re-run `grep -v '^#' scripts/slow-test-exemptions.txt | grep -v '^$' | wc -l` at finalization time; do NOT cite stale snapshot integers from this brief or any earlier reference — the count fluctuates per hot-fix arcs). Each entry already has citation discipline; group by `_test.rs` file-area prefix. **Fail-closed completeness invariant** (per openai-pro BLOCKING #9779 absorption 2026-05-12): under-inventory is the fail-open shape — every active exemption MUST appear in either a per-group `required_paths_regex` row OR the harness/shared-infra full-run bucket. No exemption left unclassified. (b) **`/tmp/v3-test-timings.log` empirical** — last N CI runs aggregated → top-K slowest groups by file-area. Cross-validates (a) and surfaces non-exempted slow tests. @@ -154,7 +154,7 @@ parser_grammar | {refinement} | ^(src/v3/parser/.*|src/v3/compiler/sr # test_pattern is libtest SUBSTRING filter — no globs; `cost_lens` matches every test name containing "cost_lens". ``` -**[Mgr-fill]**: full per-group table — exhaustive coverage of current `scripts/slow-test-exemptions.txt` entries (count grows; Mgr re-runs `grep -v "^#" ... | grep -v "^$" | wc -l` at finalization rather than relying on stale citations; 80 at 2026-05-12T00:50Z) grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. **Also required per Brian's BLOCKING #2 absorption**: each group entry must compute `testclaim_references: Set` (union of TestClaim references across group's tests) for the canonical 2-step selection join post-dissolution. Bridge-tier proxy is `required_paths_regex`; post-dissolution proxy is `testclaim_references` populated from `tests/dag/*` TestClaim authorities. +**[Mgr-fill]**: full per-group table — exhaustive coverage of current `scripts/slow-test-exemptions.txt` entries (count fluctuates per hot-fix arcs; Mgr re-runs `grep -v "^#" ... | grep -v "^$" | wc -l` at finalization rather than relying on stale snapshot integers in this brief) grouped + empirical top-K from timings log + per-group required-paths regex tested against representative diffs. **Also required per Brian's BLOCKING #2 absorption**: each group entry must compute `testclaim_references: Set` (union of TestClaim references across group's tests) for the canonical 2-step selection join post-dissolution. Bridge-tier proxy is `required_paths_regex`; post-dissolution proxy is `testclaim_references` populated from `tests/dag/*` TestClaim authorities. ## §3. Per-dimensions structural target — `feedback_parallel_representation_debt` prevention (set semantics per locked-design §2) From 9fe5e131ba1d862c744ee2581757d790c57cad8a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 12 May 2026 02:25:39 +0000 Subject: [PATCH 33/34] docs(briefs): remove residual fixed-count wording Co-authored-by: Brian Searls --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 270ff7d70da..04027d9d7f5 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -16,7 +16,7 @@ - **Polarity check**: carrier name is `skip_*`; CI consumer wires `if: skip_ != 'true'` (run when skip=false). Skip-form is canonical: NodeRef-empty OR dim-empty ⇒ unaffected ⇒ skip; both non-empty ⇒ affected ⇒ run. Set-intersection semantics per locked-design §2 union — NOT singular `.contains()` membership. - **Per-dimension structural target**: `docs/design-affected-set-lens.md` §2 (affected_set defined as union over `Set`) — every Layer 2 path-mapping entry MUST carry a `dimensions:` field of type `Set` (members drawn from `value | cost | complexity | effect | refinement`). Single-element sets like `{cost}` are valid for single-dimension groups; multi-dim consumers (e.g., LBP demonstration reading both `complexity` + `cost`) get expanded sets. Prevents schema divergence from future lens output AND silent-skip on multi-dim consumers when only the non-primary dim changes. - **Slow-test inventory sources** (per PM pre-stage at #828 c4425726922): - - (a) `scripts/slow-test-exemptions.txt` — curated >2s ratchet exemption list. **Mgr-finalization MUST recompute live count** via `grep -v "^#" scripts/slow-test-exemptions.txt | grep -v "^$" | wc -l` at finalization (count fluctuates per hot-fix arcs — e.g., #2723 added cuts; PM template citation at PR #2721 of "78" is historical and stale). Do not cite snapshot integers in this brief — they rot between authoring and Mgr-fill (cursor BLOCKING #9832 absorption 2026-05-12: "80" snapshot already drifted to 84 between authoring and reviewer-fire). + - (a) `scripts/slow-test-exemptions.txt` — curated >2s ratchet exemption list. **Mgr-finalization MUST recompute live count** via `grep -v "^#" scripts/slow-test-exemptions.txt | grep -v "^$" | wc -l` at finalization (count fluctuates per hot-fix arcs — e.g., #2723 added cuts; PM template citation at PR #2721 of "78" is historical and stale). Do not cite snapshot integers in this brief — they rot between authoring and Mgr-fill (cursor BLOCKING #9832 absorption 2026-05-12: prior in-brief fixed-count wording had already drifted by review time). - (b) `/tmp/v3-test-timings.log` — empirical per-test wall-time captured by every CI run via `--report-time` (consumed by `scripts/check-test-timeout.sh`, wired at `.github/workflows/ci.yml:405-424`) - (c) NEW per-group required-paths mapping (the deliverable; bridge-debt artifact) From bb56c573643d8187708d8bf3dd7ea81948932a70 Mon Sep 17 00:00:00 2001 From: Brian Searls Date: Tue, 12 May 2026 02:44:16 +0000 Subject: [PATCH 34/34] fix(#2719): parity fix for openai-pro BLOCKING regex finding on #2725 The shared Layer 2 brief lives on both #2719 + #2725 branches; openai-pro caught the regex hole on #2725 (root-anchored Cargo.toml/build.rs misses crate-local manifests + build scripts). Cross-branch parity required to avoid revert-on-merge when one branch lands first. Applied (.*/)?Cargo\.(toml|lock) and (.*/)?build\.rs same as #2725 absorption commit. Added explanatory paragraph cross-referencing the openai-pro finding. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md index 04027d9d7f5..394c3a660bb 100644 --- a/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md +++ b/docs/briefs/r3-ci-layer-2-path-conditional-gating-worker.md @@ -122,11 +122,13 @@ Where: **Mechanism**: the `changes` job MUST gate ALL `skip_*` flags to `false` (force full-run) when any changed file matches the shared-infrastructure regex: ``` -^(\.github/.*|scripts/.*|Cargo\.(toml|lock)|rust-toolchain\.toml|\.cargo/.*|build\.rs|src/v3/compiler/tests/integration/common/.*|src/v3/compiler/tests/integration/sg0_census_test\.rs|src/v3/compiler/tests/integration/test_runner_test\.rs|src/v3/compiler/tests/integration/t_pb_b_1_dag_runner_test\.rs|src/v3/compiler/tests/integration/integration\.rs|src/v3/compiler/tests/integration\.rs)$ +^(\.github/.*|scripts/.*|(.*/)?Cargo\.(toml|lock)|rust-toolchain\.toml|\.cargo/.*|(.*/)?build\.rs|src/v3/compiler/tests/integration/common/.*|src/v3/compiler/tests/integration/sg0_census_test\.rs|src/v3/compiler/tests/integration/test_runner_test\.rs|src/v3/compiler/tests/integration/t_pb_b_1_dag_runner_test\.rs|src/v3/compiler/tests/integration/integration\.rs|src/v3/compiler/tests/integration\.rs)$ ``` **Harness/test-selection-machinery arms** (per openai-pro P3 BLOCKING #9749 absorption): the regex includes the named harness-code class explicitly — `tests/integration/common/*` (shared test utilities), `sg0_census_test.rs` (census authority), `test_runner_test.rs` (runner framework), `t_pb_b_1_dag_runner_test.rs` (suite enumeration framework), and the integration test entry points. Worker MUST add any new harness-class file to this regex before merging the file. **A harness-class file MUST never appear in a per-group `required_paths_regex` — it always triggers full-run.** +**Crate-local build metadata** (per openai-pro P3 BLOCKING review on PR #2725 absorption 2026-05-12 — parity fix to #2719): the regex MUST match `Cargo.toml`/`Cargo.lock`/`build.rs` at ANY depth, not just workspace-root. The project has crate-local manifests + build scripts (e.g., `src/v3/compiler/Cargo.toml`, `src/v3/compiler/build.rs` per `CODING.md:319`); a root-only anchored regex (`^Cargo\.(toml|lock)$`) would miss these and silently skip tests for crate-local manifest/build-script changes — fail-open boundary class P3 forbids. The `(.*/)?` non-capturing optional path prefix on those alternates above matches both root-level (e.g., `Cargo.lock`) AND any-depth crate-local (e.g., `src/v3/compiler/Cargo.toml`, `src/v3/compiler/build.rs`). + Equivalently in step output: `force_full_run = (any changed file ∈ shared-infrastructure regex)`; when `force_full_run = true`, all per-group `skip_*` outputs short-circuit to `false`. Composes with the `code=true|false` Layer 1 gate (docs-only PRs already skip everything via Layer 1; this constraint applies only to code PRs). The shared-infrastructure regex MUST be hand-authored at the **changes job level**, not delegated to per-group regexes — every group entry's regex covers ONLY its own `src/v3/*` deps; the full-run trigger is the join-point that catches inter-group / cross-cutting changes. This is fail-closed by construction: a missing per-group regex entry doesn't matter when shared-infra changes; everything runs.