diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 839c62e..bbf3c4b 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -15,9 +15,11 @@ and request isolation lead; blocked validation, resource retention, and consumer contracts precede scaling and maintainability work; editorial and historical navigation issues follow. -The [remediation analysis](remediation-analysis.md) tracks unresolved choices -and recommendations for sequential discussion. Accepted conclusions are recorded -in this catalog; analysis alone does not select a remedy. +The [remediation analysis](remediation-analysis.md) records the completed design +review and its rationale. All choices identified for discussion have been +resolved; no further product or architectural decision is required before +implementation planning. Accepted conclusions are recorded in this catalog; +all 27 findings still require remediation and validation. Three pairs describe the same underlying issue: correctness C2/concurrency N2, correctness C4/concurrency N3, and complexity M6/responsibility R1. Other @@ -306,9 +308,12 @@ ckconfig's `captureSuite` interleaves scope and selector capture, validation, comparison-binding renaming, binding attachment, operation unions, and discovery inventory. Several partially populated collections must be understood together. -Extract cohesive private phases over the existing prepared types, keeping -related loops together. Preserve retained error order, declaration ownership, -scope and binding identity, and metadata-only construction. +**Decision:** extract cohesive scope capture/validation and selector attachment +responsibilities, and make operation bindings and discovery inventory +construction explicit. Use existing prepared types and keep related loops +together. Preserve retained error order, declaration ownership, scope and binding +identity, and metadata-only construction. Do not create new intermediate records +or a helper for each loop merely to shorten the function. **Original:** [03-complexity M1](03-complexity.md#m1--p3-scope-capture-combines-several-compilation-phases). @@ -319,10 +324,12 @@ combinations, help selection, capabilities, pointer parsing, plan assembly, ordinary inputs, and independent comparison inputs. Understanding one operation requires reasoning through irrelevant submodes. -Separate operation options, shared selection, and comparison preparation with -small private functions. Preserve the ordering of checks, input factories, -binding application, state construction, and acquisition; no generic operation -engine is needed. +**Decision:** separate operation-specific option checks, shared scope/capability +selection, and comparison input preparation with small private functions. Keep +the overall sequence explicit, including explain's help path, aggregate checks +before input construction, independent comparison sides, and input checks before +shared state creation and acquisition. Extract flag groups where this clarifies +their purpose; no generic operation engine or rule registry is selected. **Original:** [03-complexity M2](03-complexity.md#m2--p3-configuration-preflight-mixes-shared-and-operation-specific-rules). @@ -333,9 +340,13 @@ spelling, occurrence identities, application order, required flags, operands, and prepared callbacks. Captured binding replay depends on those shared identities across another code path. -Extract cohesive error translation, flag/occurrence preparation, and argument -preparation. Retain the selected dense reconstruction and heap merge, binding -identity, conversion-before-factory ordering, and error identity. +**Decision:** make small extractions for conversion-error attribution and operand +preparation. Keep flag preparation, occurrence identity, and order reconstruction +together; that block may remain in the orchestration function if extraction +requires excessive plumbing. Retain dense reconstruction, the captured-replay +heap merge, binding identity, supplied-state distinctions, conversion before +input factories, and error identity. No new state containers or replay framework +are selected. **Original:** [03-complexity M4](03-complexity.md#m4--p3-typed-preparation-combines-conversion-provenance-and-replay-assembly). @@ -346,10 +357,18 @@ setup, render-versus-write error classification, and first-error retention. Maintaining the same presentation policy in two branches increases the chance of drift. -Extract a private helper under the existing reporting lock. Keep -visibility/discard selection, headings, delivery observations, callback -ordering, and non-reentrancy explicit. This refactor does not itself fix -deferred-message loss or writer retention. +**Decision:** extract one private detail-rendering helper under the existing +reporting lock, returning rendering and writing errors separately. Callers retain +visibility/discard selection, headings, delivery observations, and terminal +timing. Preserve callback order, hidden-detail execution, sticky writer failures, +and non-reentrancy; add no locks or interchangeable rendering machinery. + +Keep this refactor separately reviewable from F03 and F07; it does not itself +fix deferred-message loss or writer retention. After correctness repairs, favor +F20, then F18 and F17, while keeping F19 modest. All four use private functions +and existing types, with no intended public API or CLI behavior change. The +[F17–F20 analysis](remediation-analysis.md#f17f20--proportionate-private-extractions) +records the accepted scope; implementation remains pending. **Original:** [03-complexity M7](03-complexity.md#m7--p3-terminal-and-ordinary-messages-duplicate-detail-rendering-mechanics). diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md index 7a1eb0e..4358087 100644 --- a/docs/roadmap/audit/remediation-analysis.md +++ b/docs/roadmap/audit/remediation-analysis.md @@ -1,14 +1,15 @@ # Audit remediation analysis -Status: discussion in progress; no implementation changes made. +Status: remediation decisions agreed; ready for implementation planning. No +implementation changes made. -This document owns analysis of unresolved remediation choices, in the discussion -order below. The [catalog](catalog.md) owns the findings, accepted remediation +This document records analysis of the remediation choices reviewed in the +discussion order below. The [catalog](catalog.md) owns the findings, accepted remediation decisions, and their status. Original audits retain detailed evidence. Record accepted conclusions in the catalog and mark the corresponding discussion here decided; a decision does not close a finding before implementation. -Existing catalog decisions for F03, F10, F11, F13–F16, and F21 remain selected. In +Existing catalog decisions for F03, F10, F11, and F13–F21 remain selected. In particular, performance testing is not a prerequisite for F13–F15, and F14 and F15 are to be designed together. CommandKit is pre-release with no consumers; consumer compatibility and migration are not constraints on these choices. @@ -20,7 +21,7 @@ Straightforward correctness repairs need not wait for this discussion sequence. | 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Decided: shared public ckconfig helper; remediation pending | | 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Decided: shared internal mechanics, separate caller policies; remediation pending | | 4 | F14–F15 | How should both operations reuse source-prefix processing? | Decided: reuse existing resolver tree; remediation pending | -| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Functions reviewed; individual recommendations pending agreement | +| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Decided: bounded private extractions, conservative F19; remediation pending | ## F10 — Flag declaration naming @@ -96,7 +97,7 @@ without introducing a broader diagnostics framework? **Evidence:** [catalog F21](catalog.md#f21--p3-both-integrations-maintain-the-same-configkit-diagnostic-adaptation) links both adapters and the original analysis. -**Options to examine:** a narrow public ckconfig helper returning existing core +**Options considered:** a narrow public ckconfig helper returning existing core diagnostics and an explanation, or retaining private implementations if the shared API adds more complexity than it removes. @@ -147,7 +148,7 @@ completion retain their different handling of incomplete input? **Evidence:** [catalog F16](catalog.md#f16--p3-parsing-and-completion-duplicate-flag-consumption-grammar). -**Options to examine:** a small neutral consumption primitive or deliberate +**Options considered:** a small neutral consumption primitive or deliberate retention of duplication where a shared helper needs extensive caller modes. **Analysis:** execution's `interpretFlagTokens` in @@ -198,7 +199,7 @@ structure without parallel indexes or changed routing semantics? **Evidence:** [catalog F14](catalog.md#f14--p3-discovery-context-preparation-repeatedly-rebuilds-shared-prefixes) and [F15](catalog.md#f15--p3-alias-help-scans-the-entire-source-catalog-for-each-intermediate-route). -**Options to examine:** traversal and descendant lookup through the existing +**Options considered:** traversal and descendant lookup through the existing alias source structure, or one shared private index if the existing structure cannot serve both operations simply. @@ -257,7 +258,7 @@ adding records, phases, or configurable mechanisms merely to shorten functions? [F19](catalog.md#f19--p3-typed-input-preparation-mixes-conversion-provenance-and-replay-assembly), and [F20](catalog.md#f20--p3-reporter-message-paths-duplicate-detail-rendering-bookkeeping). -**Options to examine:** cohesive functions over existing private types, or +**Options considered:** cohesive functions over existing private types, or retaining related code together where extraction only adds indirection. These are maintenance improvements, not newly established incorrect CLI @@ -347,5 +348,26 @@ each resulting diff by whether responsibilities are easier to follow and existing behavioral coverage still protects the selected contracts. Tests should not freeze new helper boundaries or incidental private call order. -**Decision:** all four recommendations pending agreement; no refactoring has -been implemented. +**Decision:** all four bounded extraction recommendations and the sequencing +guidance above are accepted and recorded in the catalog. F19 remains deliberately +conservative. No refactoring has been implemented. + +## Readiness for implementation planning + +The discussion sequence is complete. No unresolved product or architectural +choice identified in this review blocks preparation of the implementation plan. +The catalog's 27 findings remain open until their remedies are implemented and +validated. + +The plan can assign work units, dependencies, and proportionate verification. +Routine details such as private helper signatures, the public diagnostic +helper's final name, and the completion fixture's replacement flag are ordinary +implementation choices within the accepted scope. Preserve the recorded +boundaries; revisit a decision only if concrete implementation evidence exposes +a conflict or a materially different tradeoff. + +Keep F14–F15 together, repair F06 before validating F16, and coordinate the +reporter work in F03, F07, F20, and the relevant parts of F24 without obscuring +their separate purposes. Validation should distinguish the aligned workspace +from independent modules. No implementation plan or production changes are +included in this analysis update.