Plan the reliability and maintainability sprint

This commit is contained in:
2026-11-16 03:24:06 +00:00
parent 1d32e9bad5
commit d226bdd697
2 changed files with 570 additions and 40 deletions

View File

@@ -15,10 +15,10 @@ detail through CommandKit.
This roadmap organizes the accepted audit remediation around that target state.
The [assessment](audit/assessment.md) owns the disposition of individual findings
and the rationale for decisions D1–D7; the [catalog](audit/catalog.md) links to
their evidence. The coverage appendix below maps that evidence to this plan.
their evidence. The coverage appendix below maps that evidence to the target areas.
Earlier source-audit remedies remain proposals where the assessment supersedes
them. This document specifies outcomes and dependencies; a later implementation
plan will choose reviewable changes, concrete APIs, and scheduling mechanics.
them. This document specifies the target state and accepted scope. The
[implementation plan](implementation.md) owns the sequence and verification.
The current application already has native library integration, preflight,
ordered module execution, partial-success validation, bounded correction repair,
@@ -163,6 +163,9 @@ identity.
application, and the module barrier. Reduce avoidable within-stage waiting
without introducing independent whole-pipeline chunk traversal. Retain completed
proposal evidence on interruption even when an earlier section is unfinished.
Preserve section- and response-ordered serialized proposal indices. If
measured waiting warrants earlier validation, use local candidate references
during processing and assign serialized indices at ordered collection.
PromptKit's configured rejection remains valid; the old scheduling-dependent
choice of rejected chunks is not a compatibility requirement.
- Retain only the state needed by active processing and selected outputs. Keep
@@ -228,8 +231,9 @@ can discard usable decisions because of irrelevant extra references.
end-time sorting criterion. Build growing text/category state incrementally,
preserving exact joins, category order, and the current token estimate.
- Satisfy feasible explicit chunk count and maximum-size constraints before
optimizing balance. Choose a proportionate deterministic algorithm and retain
the configured budgets and current balancing objective. Keep accepted
optimizing balance. Preserve the single-segment exception above the token
maximum. Use a proportionate deterministic algorithm and retain the
configured budgets and current balancing objective. Keep accepted
compatibility settings, including `chunking.min_section_tokens`, even where
they are not active partition targets.
- Give validator applicability and decision meaning one owner and one runtime
@@ -339,9 +343,10 @@ boundary that the fixes should follow.
- Classify invalid processing selections and genuinely infeasible chunk requests
according to the existing input-error contract; retain runtime classification
for I/O and cancellation. Trace delegated inspection failures to Audita's
loader or the upstream integration, then fix the responsible owner. An upstream
defect should be addressed upstream rather than through replacement command
routing.
loader or the upstream integration. The pinned ckprompt catalog handler
classifies malformed prompt configuration as an operational failure. Fix
that classification upstream while keeping native command routing.
Processing progress can use CommandKit's existing reporter independently.
- Surface actionable native setup detail, including the configured missing
credential requirement and available role/profile context, while preserving
typed causes and failure classification. Remove CLI substitution of errors,
@@ -412,38 +417,6 @@ checks for unchanged content. Link/example/whitespace checks accompany relevant
documentation changes. Do not substitute coverage percentages or a collection
of test counts for evidence of the selected outcomes.
## Sequencing and implementation planning
| Stage | Reviewable outcome | Dependencies and rationale |
| --- | --- | --- |
| A. Simplify evidence and publication | Direct serialization and credential-plumbing removal; clear required-output/debug ownership; destination, failed-report, and cleanup fixes. | Removes obsolete constraints before building shared writers. Preserve useful tests while deleting their old mechanisms. |
| B. Establish domain correctness and shared owners | Parsing, normalization, chunking, protection, decision reconciliation, and shared model/configuration helpers. | Pure domain work can proceed alongside A. Establish authoritative decisions and data shapes before changing orchestration around them. |
| C. Consolidate operation and stage lifecycle | One proposal handoff, typed failure facts, explicit stage completion and repair branches, checked-plan reuse, faithful report/ledger projection. | Uses the shared domain and diagnostic boundaries; moves useful coverage off obsolete execution paths. |
| D. Bound local work and retain only needed state | Bounded preparation/dispatch, active result draining, output-sensitive retention, and measured efficiency improvements. | Build on C's explicit ownership so narrowing queues does not deadlock producers or discard evidence. Optimize independent domain scans as their owners are established. |
| E. Complete operator feedback and verification | Detailed native progress, actionable setup/input errors, canonical docs, streamlined integration tests, and release-bootstrap correction. | Progress consumes the real lifecycle from C/D. Error ownership investigation and the independent bootstrap fix can start earlier. Tests and docs accompany every stage; this stage closes integration gaps. |
This is a dependency order, not a requirement for five large commits. The later
implementation plan should split coherent fixes and supporting refactors into
reviewable units. Significant refactoring is appropriate when it improves the
selected ownership or resource behavior; an audit number is not a commit boundary.
Resolve these engineering details during planning/implementation:
- Select and measure the local work/result window, including nested validation
and repair interactions. No exact worker count or new operator setting is
prescribed by this roadmap.
- Identify the owner of delegated inspection classification and verify the
available CommandKit reporting hooks. If an upstream change is required, record
its concrete dependency and adopt the supporting release before that integration;
independent work can continue.
- Measure aggregate repair and debug costs using existing observations or focused
instrumentation. Improve local representations while preserving full history,
configured repair limits, and requested self-contained artifacts.
These are technical investigations within resolved scope. No significant product
decision remains open. A concrete discovery requiring a substantive policy change
should be brought back for discussion rather than silently expanding this roadmap.
## Completion and audit coverage
The roadmap is complete when the target behaviors above are implemented and