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

Plan the audit remediation sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 15:30:02 +00:00
parent d492c77471
commit 118b49ee55
2 changed files with 658 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/roadmap/audit-remediation.md
View File

@@ -1,7 +1,7 @@
# Audit remediation roadmap
Status: ready for implementation planning; no remediation implemented by this
document.
Status: target and decisions finalized; the [implementation plan](implementation.md)
defines the sprint. No remediation is implemented by these documents.
Baseline: `d131999c7c474010a4814bb81601cd32920e6c83`. The
[catalog](audit/catalog.md) contains 27 distinct open findings, five P2 and 22 P3,
@@ -11,8 +11,9 @@ rationale for this roadmap. The implementation is unchanged since the audited
state `db732e3a1de55c844f77870e1c6db683c2685d5d`; subsequent commits recorded
the review and decisions.
This roadmap owns the target, work grouping, dependencies, and completion
criteria. The catalog owns finding status and accepted remediation decisions;
This roadmap owns the target, scope, and completion criteria. The implementation
plan owns ordered stages, dependencies, concrete changes, and verification steps.
The catalog owns finding status and accepted remediation decisions;
the original audit entries own detailed evidence. This is separate from the
older, completed [shared-reporting remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/264b82bd5759f052a3646d57828945a87b7586d3/docs/roadmap/remediation.md), whose findings
are not reopened here. Unselected capabilities in [future work](future.md)
@@ -99,17 +100,14 @@ changes. Do not replace upstream domain behavior or expand validation merely to
simplify implementation. Private helper names and exact signatures are ordinary
implementation choices unless explicitly selected as public API.
## Work required
## Target capabilities and completion evidence
The groups below cover every catalog finding. They are reviewable work areas,
not a requirement to combine all changes in a group into one commit. Record
implementation evidence against each finding rather than treating a refactor
or a passing broad suite as proof that every nearby defect is fixed.
The areas below cover every catalog finding and define the desired end state,
without specifying implementation order. Each finding remains accountable for
its own remedy and evidence; a nearby refactor or passing broad suite alone does
not establish that a defect is fixed.
### 1. Correct outcomes, request ownership, and reporting lifecycle
Prioritize these fixes before maintenance refactors. Move any affected tests
off obsolete closure helpers as needed for F24 so they exercise real finalization.
### Correct outcomes, request ownership, and reporting lifecycle
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -121,22 +119,22 @@ off obsolete closure helpers as needed for F24 so they exercise real finalizatio
| F07 | Clear direct destination references under the existing reporting lock after final presentation. | Closed handles still reject late operations, returned presentation evidence survives, and CommandKit no longer retains writers through those direct fields or closes them. |
F03 and F07 touch the same finalization boundary but fix different problems.
Keep them separately explainable. F20's later bookkeeping extraction must not
Keep them separately explainable. F20's bookkeeping extraction must not
be used as a substitute for either correction.
### 2. Restore examples and completion validation
### Working examples and completion validation
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
| F06 | Remove the completion fixture's collision with core's reserved `format` flag. Use core's flag when testing report selection, or rename the fixture's custom choice flag when testing application completion. Adjust corresponding expectations. | The fixture constructs and generates scripts, and available opt-in shell checks exercise completion rather than failing during installation. |
| F08 | Assign the example's optional scenario argument only when supplied. | Bare `report` runs its `demo` default; an explicitly supplied value still reaches ordinary validation. |
Finish F06 before validating F16. Use the existing completion harness; its
prerequisites and commands belong to the [developer guide](../development.md#shell-completion-validation).
Report any unavailable shell checks accurately instead of treating skipped
checks as passed. This does not select a new platform support matrix.
The existing completion harness remains the validation owner; its prerequisites
and commands belong to the [developer guide](../development.md#shell-completion-validation).
Unavailable shell checks remain distinct from successful checks. This does not
select a new platform support matrix.
### 3. Clarify and simplify integration boundaries
### Clear and narrow integration boundaries
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -156,7 +154,7 @@ For F23, ConfigKit's opaque path is already valid, but the concise report still
needs key-token decoding. Remove revalidation, not that necessary translation.
Use bounded single-pass escape decoding so `~01` becomes `~1`, not `/`.
### 4. Remove obsolete plumbing and consolidate private responsibilities
### Cohesive private responsibilities
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -168,18 +166,17 @@ Use bounded single-pass escape decoding so `~01` becomes `~1`, not `/`.
| F17 | Separate cohesive scope capture/validation and selector attachment work; make operation bindings and discovery inventory construction explicit. | Captured ownership, retained errors, binding identity, discovery, and construction without provider acquisition remain intact. |
| F19 | Extract conversion-error attribution and operand preparation modestly, keeping flag preparation and occurrence ordering together. | Entered spelling, supplied-state distinctions, error identity, application order, and captured replay remain correct without replacing dense reconstruction or the existing merge algorithm. |
Apply the relevant pieces of F24 alongside the work they support, then verify
that the entire finding is addressed. Among the extraction work, favor F20,
then F18 and F17, keeping F19 conservative. Keep related loops together and use
existing prepared types. Tests should continue to protect behavior rather than
the number of helpers, incidental private call sequences, or complexity scores.
F24 covers all identified obsolete entry points. Extractions retain related
loops and existing prepared types; F19 remains conservative. Tests protect
behavior rather than helper counts, incidental private call sequences, or
complexity scores.
For F16, retain execution normalization and failure handling with the parser,
and partial-word handling and suggestions with completion. Keep caller-specific
branches where unification requires extensive modes or special cases. Repair
F06 first; this sharing introduces no new alias-completion behavior.
branches where unification requires extensive modes or special cases. This
sharing introduces no new alias-completion behavior.
### 5. Eliminate repeated alias and diagnostic-path work
### Efficient alias and diagnostic-path traversal
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -188,11 +185,11 @@ F06 first; this sharing introduces no new alias-completion behavior.
| F15 | Query strict descendant sources through that same tree for each existing intermediate resolution path. | Help avoids full-catalog scans for unrelated sources while preserving authoritative resolution, longer overrides, canonical-target checks, suffix deduplication, and output order. |
| F22 | Use a scratch path during declaration validation and format full paths only for emitted diagnostics. | Successful validation avoids eager full-path formatting, while retained issues, error identity, child order, and absent/root-only declaration handling remain correct. |
Implement F14 and F15 as one coordinated change to internal read-only tree
operations. Keep nodes private, captured paths owned correctly, and the existing
F14 and F15 share internal read-only operations on the existing resolver tree,
with private nodes, correctly owned captured paths, and the existing
routing-snapshot lifetime. Root help may still use the complete catalog when
all entries are needed. Do not add a second index, a persistent result cache,
new alias limits, or alias-completion features as part of these fixes.
all entries are needed. No second index, persistent result cache, new alias
limits, or alias-completion features are selected.
Source-level review should establish removal of the identified repeated work;
behavioral checks establish preserved results. No performance threshold or
@@ -200,7 +197,7 @@ benchmark suite is required to justify these remedies. Other routing,
termination-analysis, formatting, and installation costs remain outside those
specific complexity improvements.
### 6. Finish documentation consistency and close findings
### Consistent current guidance and historical navigation
| Finding | Required work | Evidence of the intended result |
| --- | --- | --- |
@@ -208,34 +205,28 @@ specific complexity improvements.
| F26 | Keep a brief module/status orientation in README and link the consumer guide for exact compatibility and installation details. | Volatile compatibility guidance has one canonical owner. |
| F27 | Add a useful forward-only correction identifying the correct pinned consumer-guide section for the historical ckprompt note. | The correction points to the actual section without modifying the published tag, historical note, or hosted release contents. |
Update GoDoc, CLI documentation, examples, and focused internal documentation
with the implementation they describe, rather than postponing those updates
until this last group. Check links and semantic claims. Keep existing audit
evidence available and record each finding's implementation/verification result
in the catalog. A selected remedy alone does not close a finding.
GoDoc, CLI documentation, examples, and focused internal documentation must
describe the implemented boundaries, with valid links and semantic claims.
Existing audit evidence remains available; the catalog records each finding's
implementation/verification result. A selected remedy alone does not close it.
## Verification and module alignment
Use the narrowest existing behavioral checks that cover each change; add focused
regressions for consequential defects where existing checks do not expose them.
Reuse successful results for unchanged content. Remove tests that sustain deleted
machinery while retaining useful contract coverage. Assertions should establish
CommandKit's adaptation and coordination, not independently test upstream domain
correctness or turn private mechanics into public guarantees.
Verification establishes CommandKit's adaptation and coordination, without
independently testing upstream domain correctness or turning private mechanics
into public guarantees. Consequential defects have focused behavioral protection;
useful contract coverage survives deletion of obsolete test machinery. The
implementation plan defines proportionate checks and when to run them.
For F03, use controlled synchronization to reproduce the acceptance/finalization
boundary rather than timing sleeps. A focused race-enabled run can supplement
that check, but a race detector alone cannot establish correct queue ordering.
For F07, inspect unnecessary reference retention without creating a garbage
collection timing promise. Keep ordinary suites deterministic, offline, and
independent of credentials or live model services.
For F03, acceptance/finalization evidence must establish queue ordering; a race
detector alone cannot do so. F07 does not establish a garbage collection timing
promise. Ordinary suites remain deterministic, offline, and independent of
credentials or live model services.
Follow the [developer guide](../development.md#documentation-validation) for
module and workspace test commands. The root suite does not traverse the nested
modules. Validate changed modules during their work, then the combined local
source through the aligned workspace, including representative maintained
consumers and the repaired completion checks where available. Use Go 1.27.0
for this cross-module work as already selected by the repository.
The [developer guide](../development.md#documentation-validation) owns module and
workspace test commands. The root suite does not traverse nested modules.
Evidence covers combined local source, representative maintained consumers,
and available repaired completion checks using the already selected Go 1.27.0.
The independent-module check has a concrete dependency constraint: ckprompt's
new F21 call will not exist in its currently selected ckconfig v0.4.0 dependency.