From 23c1976ef1ee5a88a585901984da22a9187fee91 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 25 Oct 2026 20:12:12 +0000 Subject: [PATCH] Settle the initial audit remediation scope --- docs/roadmap/audit.md | 55 +++++++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index 1478031..da2bca7 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,6 +1,7 @@ # Consolidated Audit Review -Status: review pending; implementation scope has not been selected. +Status: initial scope selected; efficiency and structural-refactoring scope +remain under review. Implementation has not begun. Consolidated: 2026-10-25. Baseline: `ecd5d5d`. This document consolidates nine sequential audits for maintainer review. It owns @@ -18,7 +19,9 @@ are attached to the defects they protect rather than counted as additional product fixes. The 35 original numbered findings map to 31 review entries after deduplication -and integration of related test work. All entries remain open and unselected. +and integration of related test work. All findings remain unresolved; the +[settled scope decision](#oq-1-what-should-the-first-implementation-scope-include) +identifies the selected work. OQ-2 and OQ-3 remain open. Their medium/low priorities retain the original assessments; those labels do not imply severity certification or implementation order. IDs remain stable as work is selected or completed. @@ -99,7 +102,7 @@ of the groups below is for navigation, not an execution sequence. | B01 and B02 | Panic cleanup must close callback state and the owned host root independently. Neither fix substitutes for the other. | | C01 and its filesystem tests | Strengthen error/handle assertions while adding failure-phase regressions, using one shared test owner. | | C02 and C03 | Link expansion correctness is independent of optional glob readability extraction. Do not make the latter a prerequisite. | -| D01, D02, and D03 | Remove confirmed unused copies where selected, then account for the complete retained graph. Removing one unused tree does not fix the remaining omissions. | +| D01, D02, and D03 | Remove the confirmed unused copies, then account for the complete retained graph. Removing one unused tree does not fix the remaining omissions. | | E01, E02, and E03 | Consider policy-state costs and responsibility boundaries together, but preserve separate scaling and behavioral acceptance cases. | | F01 and F02 | Removing the test-only acquisition mode does not by itself simplify active lifecycle handoffs. | | F04, F09, and F12 | Replace useful facade ownership/query coverage before deleting disconnected or representation-coupled scaffolding. | @@ -879,22 +882,37 @@ not extra fixes. | deadcode 7 | [F03](#f03-retire-the-parallel-test-only-import-directive-parser) | | deadcode 8 | [F01](#f01-remove-the-test-only-eager-acquisition-mode), duplicate of complexity 1 | -## Open Questions +## Settled Scope Decisions ### OQ-1. What Should The First Implementation Scope Include? -**Recommendation:** select all nine reported defects with their regression -coverage, plus the bounded cleanup and test improvements where their evidence -holds on the implementation baseline. The unused history copies deserve early -coordination with D01, and callback context/root closure deserve independent -acceptance within the same work area. Keep fixes reviewable and distinct even -when delivered in one sprint. +**Settled:** include all nine reported defects with their regression coverage, +the bounded cleanup, and the identified independent test improvements. -**Alternative:** deliver defect fixes first, then handle cleanup and independent -test improvements in a separate effort. This produces a smaller initial scope -and simpler attribution, but retains known redundant work and can revisit the -same files/tests. Cleanup should not delay a consequential fix merely to achieve -a tidier overall structure. +| Selected work | Finding IDs | +| --- | --- | +| Reported defects and accompanying regression coverage | A01–A04, B01–B02, C01–C02, D01 | +| Removal of unused copies, evidence, helpers, fields, and test-only production paths | D02–D04, F01, F03–F06 | +| Public coverage and stronger or less redundant test assertions | F09–F12 | + +This selects 21 review entries. Reconfirm cleanup evidence on the implementation +baseline before removal, and preserve distinct behavioral protection when +replacing tests. Coordinate unused history copies with D01's retained-graph +accounting; verify callback-state closure and host-root closure independently. +Keep fixes and cleanup in focused, reviewable commits, even if delivered in one +sprint. Cleanup must not delay a consequential fix. + +The combined scope restores existing contracts and removes demonstrated +maintenance burden while avoiding repeated work at the same ownership and test +boundaries. Delivering defects first and cleanup separately would reduce the +initial review surface, but would retain redundant work and revisit those +boundaries. The combined approach is selected. + +The six efficiency candidates and four broader structural refactors remain +unselected pending OQ-2 and OQ-3. This decision does not select new public behavior +or establish an implementation sequence. + +## Open Questions ### OQ-2. Which Efficiency Candidates Should Accompany Remediation? @@ -913,9 +931,10 @@ resource budgets. Broader experiments in `future.md` remain separately deferred. ### OQ-3. How Much Structural Refactoring Should Be Selected? -**Recommendation:** accept F01's removal of the test-only protocol as bounded -cleanup; assess active acquisition handoffs (F02) and policy/evidence ownership -(E03) with their affected fixes before selecting a wider extraction. Leave glob +F01's removal of the test-only protocol is already selected under OQ-1. + +**Recommendation:** assess active acquisition handoffs (F02) and policy/evidence +ownership (E03) with their affected fixes before selecting a wider extraction. Leave glob entry extraction (C03) and transport simplification (F07) optional unless a concrete design reduces concepts and clarifies ownership.