base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Finalize audit remediation decisions for implementation planning

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 15:09:19 +00:00
parent c7f898e56e
commit d131999c7c
2 changed files with 69 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/roadmap/audit/catalog.md
View File

@@ -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).