From e1e94eeec7c3cc7bdd507efcc3896c29d8292ab4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 25 Oct 2026 20:17:47 +0000 Subject: [PATCH] Settle audit refactoring scope and defer follow-up work --- docs/development.md | 2 +- docs/releases/v0.6.0.md | 2 +- docs/roadmap/audit.md | 118 ++++++++++++++++++---------------------- docs/roadmap/future.md | 80 ++++++++++++++++++++++++--- 4 files changed, 126 insertions(+), 76 deletions(-) diff --git a/docs/development.md b/docs/development.md index ea408c0..d7c9b5c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -113,7 +113,7 @@ git show 8e91a2b:docs/roadmap/startup-benchmark.md ``` Remaining optimization candidates belong to -[future performance experiments](roadmap/future.md#3-performance-experiments). +[future performance experiments](roadmap/future.md#5-performance-experiments). The completed effective-configuration diff roadmap, implementation plan, and resolved review findings are preserved in Git history at `1c2610c` under diff --git a/docs/releases/v0.6.0.md b/docs/releases/v0.6.0.md index fa9b43d..a0ce871 100644 --- a/docs/releases/v0.6.0.md +++ b/docs/releases/v0.6.0.md @@ -30,7 +30,7 @@ adopts ReleaseKit for source publication, and raises the consumer Go minimum to successful-tag-push completion point remain unchanged; CI is not a gate. - Adopt release policy 1.6, distinguishing the consumer Go minimum from the validation toolchain. Retire completed planning and measurement records into - Git history while preserving [performance candidates](../roadmap/future.md#3-performance-experiments). + Git history while preserving [performance candidates](../roadmap/future.md#5-performance-experiments). ## Compatibility and upgrade diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index 8478588..d127583 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,15 +1,15 @@ # Consolidated Audit Review -Status: initial scope and four localized efficiency improvements selected; -collection-policy and structural-refactoring scope remain under review. -Implementation has not begun. +Status: scope settled; 29 entries selected for implementation planning. +Two refactors are deferred to `future.md`. Implementation has not begun. Consolidated: 2026-10-25. Baseline: `ecd5d5d`. This document consolidates nine sequential audits for maintainer review. It owns their open findings, supporting evidence, proposed remedies, and relationships. -It is not an implementation plan, an acceptance of every recommendation, or a -new set of release gates. The [configuration contract](../config.md), public Go -declarations, and [architecture policy](../policy/architecture.md) continue to +The settled decisions select the remediation roadmap's scope; this document is +not a staged implementation plan or a new set of release gates. The +[configuration contract](../config.md), public Go declarations, and +[architecture policy](../policy/architecture.md) continue to own behavior and guarantees. There are nine distinct reported defects: four from correctness, three from @@ -21,8 +21,9 @@ product fixes. The 35 original numbered findings map to 31 review entries after deduplication and integration of related test work. All findings remain unresolved; the -[settled scope decisions](#settled-scope-decisions) identify the 25 selected -entries. OQ-3 remains open, covering E01/E02 and the four broader refactors. +[settled scope decisions](#settled-scope-decisions) identify the 29 selected +entries. C03 and F07 have moved to `future.md`, with reference entries retained +here for traceability. All three scope questions are settled. 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. @@ -102,12 +103,12 @@ of the groups below is for navigation, not an execution sequence. | A02 and A05 | Make descriptor construction safe before reusing successful dynamic-type eligibility results. | | 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. | +| C02 and deferred C03 | Complete link expansion remediation independently; reconsider glob readability extraction afterward through `future.md`. | | 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. | +| E01, E02, and E03 | Address policy-state costs and responsibility boundaries together, preserving 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. | -| F05 and F07 | Removing unused placement bridges is a bounded cleanup independent of the wider transport refactor. | +| F05 and deferred F07 | Remove unused placement bridges in this scope; reconsider wider transport simplification afterward through `future.md`. | ## A. Schema And Typed Values @@ -335,21 +336,9 @@ outside-root target is needed, and accidental graphs can cause the same work. ### C03. Separate Glob Entry Preparation From Traversal -Type: optional refactor. Priority: medium. Source: complexity 4. - -**Problem and evidence.** The patterned branch of `selectGlobImportCandidates` -in [glob.go](../../internal/engine/glob.go) interleaves component traversal and -union/sorting with hidden/match rules, lexical/access paths, containment, links, -directory eligibility, namespace differences, labels, and candidate construction. -Directory selection already has a named entry-preparation operation. - -**Recommendation and acceptance.** Consider a glob-specific preparation helper -returning an admitted candidate, ordinary skip, or diagnostic. Keep literal -segments, component advancement, union/sorting, exclusions, and requiredness in -the selector. Preserve inspection/error order, budgets, native spelling, and -selected-file validation. Share low-level facts only where semantics agree; -no general visitor framework, discovery-algorithm change, or caching is implied. -C01/C02 can be fixed independently of this readability change. +Deferred under OQ-3. The evidence, proposed scope, and remaining questions now +belong to [future work](future.md#1-separate-glob-entry-preparation-from-traversal), +for consideration after this roadmap's selected work is complete. ## D. Retained History And Unused Evidence @@ -487,7 +476,7 @@ deferred public metadata-copy experiment. ### E03. Clarify Policy Preparation And Merge Evidence Application -Type: optional refactor. Priority: medium. Source: complexity 3. +Type: selected refactor. Priority: medium. Source: complexity 3. **Problem and evidence.** [overlay.go](../../internal/engine/overlay.go) combines claim/declaration preparation, operation resolution, callbacks, diagnostics, @@ -562,7 +551,7 @@ loading workflows or imply that every nil-state/directive context is unused. ### F02. Clarify Active Acquisition And Coordinator Handoffs -Type: optional refactor. Priority: medium. Source: complexity 2. +Type: selected refactor. Priority: medium. Source: complexity 2. **Problem and evidence.** `acquireInput` in [acquisition.go](../../internal/engine/acquisition.go) combines discovery, parsing, @@ -664,24 +653,10 @@ separate analysis. ### F07. Simplify Redundant Facade-To-Engine Transport -Type: optional refactor. Priority: low. Source: complexity 5, excluding F05's -bounded placement-bridge removal. - -**Problem and evidence.** Root conversion, engine facade-transport records, engine -private defaults, decorators, and load normalization provide several mapping -sites for the same import-default fields. Placement likewise uses a record plus -a setter-style bridge. See [conversion.go](../../conversion.go), -[lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go), -[import_spec.go](../../internal/engine/import_spec.go), and -[destination.go](../../internal/engine/destination.go). - -**Recommendation and acceptance.** Consider one engine representation for -import-default input and straightforward construction on existing option/input -records, only if this reduces total concepts and mapping sites. Keep domain-rule -and ownership conversions and separate registration compilation. Preserve -root-owned types/signatures, both loading APIs, invalid-enum validation, -nil-versus-empty patterns, and pointer/slice snapshots. No universal request DTO, -generated mapper, public internal aliases, or adapter framework is proposed. +Deferred under OQ-3. The evidence, proposed scope, and remaining questions now +belong to [future work](future.md#2-simplify-redundant-facade-to-engine-transport), +for consideration after this roadmap's selected work is complete. F05's bounded +removal of unused placement bridges remains selected. ### F08. Index Secret-Failure Location Queries Lazily @@ -814,7 +789,7 @@ Selected stable Kahn ordering, deterministic sorting, exact numeric identity, and the expressly selected registration-overlap check are not reconsidered here. Required detached copies and genuinely expanding output remain legitimate costs. The broader replay, metadata-handoff, cross-load schema-cache, and contributor- -trace experiments stay in [future.md](future.md#3-performance-experiments). +trace experiments stay in [future.md](future.md#5-performance-experiments). Local fixes and removal of proven unused work do not select those experiments. ## Validation Approach For Selected Work @@ -915,9 +890,9 @@ sequence. ### OQ-2. Which Efficiency Candidates Should Accompany Remediation? -**Settled:** include the four localized efficiency improvements below. Decide -E01/E02 together with collection-policy preparation and evidence ownership (E03) -under OQ-3; those two efficiency candidates remain unselected. +**Settled:** include the four localized efficiency improvements below. E01/E02 +are addressed separately with collection-policy preparation and evidence +ownership (E03) under the settled OQ-3 decision. | Selected improvement | Scope and dependency | | --- | --- | @@ -937,25 +912,36 @@ initial scope and avoid optimizing uncommon workloads, but would retain known growth patterns with relatively direct remedies in the four selected cases. The selected approach does not promise a measured startup improvement; practical benefit depends on configuration shape and workload. Broader experiments in -[future.md](future.md#3-performance-experiments) remain deferred. C02's availability +[future.md](future.md#5-performance-experiments) remain deferred. C02's availability fix and A04/D01's existing-budget enforcement remain selected independently. -## Open Questions - ### OQ-3. How Much Structural Refactoring Should Be Selected? -F01's removal of the test-only protocol is already selected under OQ-1. -OQ-2 leaves E01/E02's policy retirement and copying improvements for this decision, -alongside E03's policy preparation and evidence responsibilities. Their distinct -scaling cases must remain visible even if implemented together. +**Settled:** select E01, E02, E03, and F02. Defer C03 and F07 to the first two +entries of [future.md](future.md) for consideration after the rest of this roadmap +is complete. F01's removal of the test-only protocol remains selected under OQ-1. -**Recommendation:** assess active acquisition handoffs (F02) and policy/evidence -ownership (E03), including E01/E02, 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. +| Selected work | Scope | +| --- | --- | +| E01/E02/E03: collection-policy retirement, copying, and evidence ownership | Address the related costs and preparation/application boundaries together, retaining distinct scaling and behavioral acceptance cases. | +| F02: active acquisition and coordinator handoffs | Extract cohesive repeated operations with clear inputs/results while preserving visible phase order and ordinary/layered differences. | -**Alternative:** include all four structural refactors alongside E01/E02 in the -same effort for a more uniform maintenance result. This offers broader readability improvements -but increases review scope and the chance of moving complexity rather than -removing it. Neither approach calls for a new public API, generic framework, or -changes to the established configuration model. +For collection policy, distinguish read-only existing state, policy affected by +incoming declarations or replacements, and the changes/evidence retained by the +assembly. Preserve retirement timing, newly established policy, explicit-mode +persistence, and nested record ownership. A smaller function or fewer copies +alone does not establish success. For acquisition, moving blocks into helpers +that continue sharing mutable surrounding state would not clarify the handoff; +keep the existing loading model and named responsibilities. + +The selected combination offers a focused improvement in efficiency and +maintainability at active ownership boundaries. Including C03/F07 now would +broaden review for more modest readability benefits; neither is necessary for +the selected fixes. They remain plausible follow-up work, not rejected proposals. +Deferring all structural work would reduce immediate change scope but retain the +policy inefficiencies and difficult acquisition handoffs. No new public API, +generic framework, or configuration semantics are selected. + +Together, OQ-1 through OQ-3 select 29 entries. All scope questions are settled; +the next step is to prepare the implementation plan with sequencing and focused +validation. No implementation has been performed by these planning decisions. diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index bc37848..fa90f08 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -1,12 +1,76 @@ -# Potential Future Features +# Potential Future Work -This document lists potential enhancements for consideration in future ConfigKit -releases. Entries are not accepted contracts, implementation plans, or release -commitments. Adopting a candidate requires an explicit design decision and a -separate plan. Significant architectural exclusions and their rationale belong +This document lists potential enhancements and maintenance work for consideration +in future ConfigKit releases. Entries are not accepted contracts, implementation +plans, or release commitments. Adopting a candidate requires an explicit design +decision and a separate plan. Significant architectural exclusions and their rationale belong in ADRs; this document does not maintain a list of rejected proposals. -## 1. Recursive body merging for identified records +## 1. Separate glob entry preparation from traversal + +Status: deferred; consider after the selected work in the +[consolidated audit roadmap](audit.md) is complete. Audit ID: C03. +Original source: complexity finding 4 at +`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: medium. + +The patterned branch of `selectGlobImportCandidates` in +[glob.go](../../internal/engine/glob.go) interleaves component traversal and +union/sorting with hidden/match rules, lexical/access paths, containment, links, +directory eligibility, namespace differences, labels, and candidate construction. +Directory selection already has a named entry-preparation operation. + +Consider a glob-specific preparation helper returning an admitted candidate, +ordinary skip, or diagnostic. Keep literal segments, component advancement, +union/sorting, exclusions, and requiredness in the selector. Preserve inspection +and error order, budgets, native namespace spelling, and selected-file validation. +Share low-level filesystem facts only where semantics agree; the proposal does +not require a general visitor framework, discovery-algorithm change, or caching. +The selected directory-failure and link-resolution fixes do not depend on this +readability refactor. + +### Questions to resolve before implementation + +- After the selected import fixes, does the entry-preparation boundary still + reduce complexity and clarify lexical versus canonical path handling? +- Which low-level operations can be shared with directory selection while + keeping their distinct admission and traversal rules explicit? +- Can existing behavioral tests protect ordering, diagnostics, and resource + accounting without assertions about the new private helper structure? + +## 2. Simplify redundant facade-to-engine transport + +Status: deferred; consider after the selected work in the +[consolidated audit roadmap](audit.md) is complete. Audit ID: F07. +Original source: complexity finding 5 at +`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: low. The unused placement +bridge removal is separately selected as audit F05. + +Root conversion, engine facade-transport records, engine private defaults, +decorators, and load normalization provide several mapping sites for the same +import-default fields. Placement likewise uses a record plus a setter-style +bridge. See [conversion.go](../../conversion.go), +[lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go), +[import_spec.go](../../internal/engine/import_spec.go), and +[destination.go](../../internal/engine/destination.go). + +Consider one engine representation for import-default input and straightforward +construction on existing option/input records, only if this reduces total +concepts and mapping sites. Keep domain-rule and ownership conversions and +separate registration compilation. Preserve root-owned types/signatures, both +loading APIs, invalid-enum validation, nil-versus-empty patterns, and pointer/slice +snapshots. A universal request DTO, generated mapper, public internal aliases, +or adapter framework is not part of this proposal. + +### Questions to resolve before implementation + +- After unused bridges and fields are removed, does the remaining transport + duplication still justify a refactor? +- Which representations can be combined without losing ownership snapshots, + presence distinctions, validation, or root-owned public types? +- Would the proposed construction surface reduce total concepts and conversion + sites, rather than relocate the same work behind another abstraction? + +## 3. Recursive body merging for identified records Status: deferred. The implemented [collection policy](../config.md#strict-document-composition) uses `upsert` to @@ -20,7 +84,7 @@ presence and ordering, and how provenance, history, sensitivity, and resource context follow partially retained records. Any change requires a new decision and implementation plan; this entry does not alter current upsert behavior. -## 2. Required version declarations for selected sources +## 4. Required version declarations for selected sources Status: deferred. PromptKit requested a way to require version declarations on a selected subset of source files while permitting other fragments to omit them. @@ -56,7 +120,7 @@ compatible version or replace final configuration validation. behavior for absent optional inputs and preserve source-local diagnostics, inspection evidence, and existing sensitivity handling. -## 3. Performance experiments +## 5. Performance experiments Status: deferred pending evidence. The completed performance audit identified four internal optimization candidates for separate investigation: