From 730c1e4758ab141db81b8cecee15c04911e8da5e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 16 Nov 2026 01:24:50 +0000 Subject: [PATCH] Record detailed processing progress decision --- docs/roadmap/audit/assessment.md | 66 ++++++++++++++++---------------- docs/roadmap/audit/catalog.md | 8 +++- 2 files changed, 40 insertions(+), 34 deletions(-) diff --git a/docs/roadmap/audit/assessment.md b/docs/roadmap/audit/assessment.md index d0af8a9..bf2c8e6 100644 --- a/docs/roadmap/audit/assessment.md +++ b/docs/roadmap/audit/assessment.md @@ -1,17 +1,10 @@ # Audit assessment and decision register -**Reviewed baseline:** `faba8ab` (2026-11-15). **Status:** assessment complete; -remediation not implemented. D1 was resolved on 2026-11-15 and the architecture -policy updated; the focused cleanup audit is complete and implementation remains -pending. D2 was resolved on 2026-11-15: callers own report destination isolation; -the operator-documentation update remains pending. D3 was resolved on the same -date: native admission semantics remain in place; local scheduling improvements -await implementation planning. D4 was also resolved on 2026-11-15: improve -input memory use without introducing an application-level input-size limit. -D5 was resolved on the same date: retain best-effort debug capture and operator -ownership of retention and cleanup; efficiency improvements remain pending. -D6 was also resolved on 2026-11-15: retain full repair conversation history and -per-correction limits, without aggregate budgets or context reduction at this time. +**Reviewed baseline:** `faba8ab` (2026-11-15). **Status:** assessment and policy +decisions complete. D1–D7 were resolved on 2026-11-15 and are recorded below. +The D1 architecture-policy update and focused cleanup audit are complete; +application remediation and the associated operator-documentation updates +remain pending. This document owns classification, recommended scope, and pending decisions for the [catalog](catalog.md). The source audits retain their evidence; their suggested remedies are not approved requirements. @@ -45,8 +38,8 @@ when substantial restructuring is appropriate. **Ready** means suitable for implementation planning within the stated scope, not implemented or validated by this document. **Investigate** denotes technical -work the agent can undertake without a product decision. **D7** identifies -the remaining substantive choice; D1–D6 are recorded below as resolved. **Closed** +work the agent can undertake without a product decision. D1–D7 are resolved; +there are no remaining open decisions in this register. **Closed** denotes no remediation for the specified scope. Mixed entries deliberately separate ready work from decisions and exclusions. @@ -132,7 +125,7 @@ behavior from proposed extensions. | [54. Centralize transcript cloning](catalog.md#54-centralize-transcript-cloning) | A, M, T | Ready | Deep copying belongs with the transcript model. Preserve nil versus explicitly empty mutable slices in the shared clone, both caller copy boundaries, and current external encoding. Verify independence using fixtures not constructed by the same clone. This internal fidelity choice needs no product decision. | | [55. Assemble built-in modules at the composition boundary](catalog.md#55-assemble-built-in-modules-at-the-composition-boundary) | A | Ready | Production built-in assembly belongs at composition; the runner already accepts a factory. Move construction while keeping the configuration catalog dependency-light and retaining override seams. Package layout is an implementation choice, not a product decision. | | [56. Merge shared prompt variables once per model call](catalog.md#56-merge-shared-prompt-variables-once-per-model-call) | E, M | Ready | Processing loads the same shared values twice. Merge once while preserving processing and inspection's different precedence and the protected-term default. Do not accidentally weaken operator prompt-definition replacement support or invent new shared-variable precedence. | -| [57. Clarify what the inherited progress flag does in processing](catalog.md#57-clarify-what-the-inherited-progress-flag-does-in-processing) | M; P | Ready for clarification; D7 | The standard flag is exposed without processing events. Accurate help/documentation can proceed, preserving standard command acceptance. Adding a processing progress stream is a user-visible feature: D7 selects scope. Any standard help/capability gap belongs in CommandKit rather than local replacement routing. | +| [57. Clarify what the inherited progress flag does in processing](catalog.md#57-clarify-what-the-inherited-progress-flag-does-in-processing) | M, A, T; P approved | Ready under resolved D7 | Add processing progress through CommandKit’s reporter. An operator selecting --progress wants relatively detailed updates: emit meaningful stage/chunk, proposal, validation, and repair activity as available, rather than only coarse stage summaries. CommandKit owns reporting-mode precedence and stream routing; preserve transcript stdout. Exact event granularity and wording are implementation choices. Request upstream support for any standard reporter gap rather than building a parallel reporting system. | | [58. Test registered validator roles and embedded assets through their behavior](catalog.md#58-test-registered-validator-roles-and-embedded-assets-through-their-behavior) | T, M | Ready | Registry tests duplicate representation assertions and prompt-count checks can miss substitutions. Check required identities, effective roles, preparability, schema identity, and protective copies at their actual owners. Do not replace them with prompt wording or private implementation assertions. | | [59. Consolidate overlapping normalization fixtures](catalog.md#59-consolidate-overlapping-normalization-fixtures) | T, M | Ready | Two fixtures protect the same nonmerge outcome. Consolidate their meaningful assertions, keeping distinct normalization behavior and independent input expectations. Coordinate with #51 so copied parser conversion is not retained in the tests. | | [60. Focus integration tests on decoded artifacts and independent output choices](catalog.md#60-focus-integration-tests-on-decoded-artifacts-and-independent-output-choices) | T | Ready | Decoded artifact identities and evidence associations are the contract; escaping and repeated large fixtures are incidental. Keep one full repair/filter/later-failure attribution scenario and use smaller independent-output fixtures. Remove masking assertions identified in the D1 audit without losing role selection, successive text, output-choice, and failure coverage. | @@ -311,26 +304,35 @@ quality. Neither change follows from the audit finding alone. Revisit these options only if production evidence demonstrates a need, through a separate policy decision. -## Open Decisions +## Resolved D7: emit detailed processing progress through CommandKit -D7 is the only remaining open decision. Its resolution must not delay the -independent ready portions of the catalog. +**Accepted:** 2026-11-15. **Applies to:** #57. +**Status:** feature approved; implementation pending. -### D7. Should this remediation add processing progress events? +Emit processing progress through CommandKit's existing reporter, driven by real +processing lifecycle events. An operator who expressly selects `--progress` is +requesting relatively detailed information. Provide useful updates throughout +processing, including stage and chunk activity and proposal, validation, and +repair work where available; do not limit the feature to coarse stage summaries +merely to minimize output. Include work identities and observed completion counts +where they help the operator follow the run. Exact wording and event granularity +remain implementation choices. -**Applies to:** #57. +CommandKit continues to own reporting-mode precedence and stream routing. +Preserve stdout for transcript output and respect the effective mode when +`--progress` is combined with other reporting flags. Audita supplies processing +events rather than implementing a separate output-mode or progress system. +Use available upstream execution events where appropriate; request upstream +support for a material reporter gap instead of adding a local workaround. -**Recommendation:** add a small useful processing progress stream through -CommandKit's existing reporter, driven by real stage/chunk lifecycle events. -Keep stdout for transcript output and let CommandKit own reporting-mode -precedence. This would make the inherited flag useful without inventing a second -reporting system. Exact wording and event granularity are implementation choices. +Retaining an accepted flag with no processing updates was considered and is not +selected: progress is useful for long-running jobs, and the maintainer expressly +approved adding it. Update CLI/operations documentation when implementation +lands. Verify representative real lifecycle updates, native reporting-mode +behavior, and transcript-output integrity without testing incidental wording. -**Alternative:** retain standard flag acceptance and accurately clarify that -processing currently supplies no progress events. This is smaller and avoids -new event plumbing, but leaves the advertised capability unhelpful for long jobs. -If standard help cannot express availability, request the improvement upstream. +## Decision completion -**Why approval:** emitting a new stream of user-facing processing information is -a feature addition, not removal of dead code. Documentation clarification can -proceed independently. +All seven decisions are resolved. Implementation planning can proceed using the +entry assessments and accepted scopes above. Technical investigations and +measurements remain where identified; they are not unresolved product decisions. diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 7f9901e..b4bff85 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -535,8 +535,12 @@ for inspection. ### 57. Clarify what the inherited progress flag does in processing -`process` advertises progress messages but supplies no producer. Define its -behavior or clarify process help while preserving acceptance for existing scripts. +`process` advertises progress messages but supplies no producer. **Resolved D7:** +add processing progress through CommandKit's reporter. Operators selecting +`--progress` want relatively detailed updates; expose meaningful stage/chunk, +proposal, validation, and repair activity as available, rather than only coarse +stage summaries. CommandKit owns mode precedence and stream routing; preserve +transcript stdout. Exact wording and event granularity are implementation choices. [Dead code §10](12-deadcode.md#10-resolve-the-inherited-progress-flag-for-process) ## Test maintenance and dead code