diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index a9e9a9c..3ef18a0 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -15,6 +15,10 @@ 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. + Three pairs describe the same underlying issue: correctness C2/concurrency N2, correctness C4/concurrency N3, and complexity M6/responsibility R1. Other related findings remain distinct where they concern different failure modes or @@ -169,6 +173,10 @@ Document the implemented rules once with `FlagMeta` and link related public helpers. Preserve accepted Unicode lowercase letters and digits; changing validation would require a separate decision. +The [F10 analysis](remediation-analysis.md#f10--flag-declaration-naming) reviews +the naming convention's basis and recommends retaining the existing rules; +agreement on that precise contract is pending. + **Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints). ## F11 — P3: Explanation providers must implement an unused text writer diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md new file mode 100644 index 0000000..ee0e3d2 --- /dev/null +++ b/docs/roadmap/audit/remediation-analysis.md @@ -0,0 +1,164 @@ +# Audit remediation analysis + +Status: discussion in progress; 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 +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, F11, and F13–F15 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. +Straightforward correctness repairs need not wait for this discussion sequence. + +| Order | Findings | Question | Discussion status | +| --- | --- | --- | --- | +| 1 | F10 | Which flag declaration rules should be documented as the intended contract? | Evidence reviewed; recommendation pending agreement | +| 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Concrete API analysis pending | +| 3 | F16 | Which flag-consumption facts can parsing and completion usefully share? | Boundary analysis pending | +| 4 | F14–F15 | How should both operations reuse source-prefix processing? | Joint design pending; remediation selected | +| 5 | F17–F20 | Which private extractions materially simplify the existing code? | Individual extraction review pending | + +## F10 — Flag declaration naming + +**Question:** should remediation document the existing naming rules, or change +them first? This concerns names declared by applications, not the contents of +operator-supplied flag values. + +**Evidence:** [catalog F10](catalog.md#f10--p3-public-flag-metadata-omits-enforced-naming-and-reserved-spelling-rules) +and [documentation audit D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints). +`FlagMeta`, `validateBindings`, and `validFlagName` in +[command.go](../../../command.go) establish the documentation gap and current +validation. Shared reporting spellings are defined in +[commandmeta](../../../internal/commandmeta/metadata.go). + +The historical accepted grammar ADR explicitly selected lowercase names with +hyphen-separated words. It is available at commit +`82128463cd9649a426da7c5e3f3ce33bd37cdd9f`, path +`docs/adr/0006-command-grammar.md`; the same commit's +`docs/roadmap/initial.md` carried that direction into implementation. This +supports the broad naming convention, but does not independently establish every +character-level detail of the current validator. Historical records provide +context; they do not replace the current canonical API documentation. + +Current long names consist of nonempty groups of Unicode lowercase letters or +digits separated by single hyphens. Names may start with digits or consist +entirely of digits. Uppercase letters, underscores, dots, and leading, trailing, +or repeated hyphens are rejected. Examples: + +| Declaration name | Current result | +| --- | --- | +| `max-tokens`, `profile2`, `2fa`, `123`, `équipe` | Accepted, subject to ordinary collision checks | +| `maxTokens`, `max_tokens`, `max.tokens`, `max--tokens`, `-profile`, `profile-` | Rejected | + +Core reserves `help`, `quiet`, `verbose`, `debug`, `progress`, and `format` for +its own flags. A short spelling is optional; when present it is one byte, +cannot be `-`, and cannot be the reserved help spelling `h`. The long-name +lowercase rule does not apply to short spellings. Declaration defects are +reported at installation, before command execution. + +**Options:** + +1. Retain and document the current rules. This makes the shared convention + explicit without introducing new validation or conversion machinery. +2. Relax the stylistic restrictions, allowing application names such as + `maxTokens` or `max_tokens` while preserving core reservations and necessary + parsing constraints. This gives applications more naming freedom but weakens + the common vocabulary; its precise supported grammar would need selection. +3. Tighten the rules, for example to ASCII names beginning with a letter. This + creates a narrower convention but removes currently accepted names without + an identified operator benefit. + +**Recommendation:** option 1. Retain lowercase, hyphen-separated long names, +including current Unicode lowercase and digit support. Keep core reservations +and the existing short-spelling rules. Recommend readable names without banning +numeric names or adding an ASCII-only restriction. Do not automatically rewrite +invalid names or accept alternate spellings through normalization. + +Document the exact declaration contract once in `FlagMeta` GoDoc and link related +helpers, including `RenameFlag` and flag-alias declarations, as applicable. Keep +operator syntax in the CLI reference. This is a documentation remediation if +selected; it does not require a new ADR, parser, or validation framework. + +**Decision:** pending agreement. The recommendation does not authorize a change +to validation behavior. + +## F21 — Shared ConfigKit diagnostic adaptation + +**Question:** what concrete helper, if any, removes duplicated CLI adaptation +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 +diagnostics and an explanation, or retaining private implementations if the +shared API adds more complexity than it removes. + +**Preliminary recommendation:** compare a concrete signature against both +callers, including heading/side labels, evidence snapshots, and error identity. +Keep operation-specific explanations and scheduling with their existing owners. +The smaller scheduling switches do not independently justify another public +helper. Compatibility and migration are not obstacles; clarity and maintenance +cost are the decision criteria. + +**Decision:** helper signature and scope pending analysis and agreement. + +## F16 — Shared flag consumption + +**Question:** which consumption facts can be shared while execution and +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 +retention of duplication where a shared helper needs extensive caller modes. + +**Preliminary recommendation:** share mechanics only; keep normalization, +failure provenance, and partial-word completion in their current owners. Repair +F06's completion fixture before validating this refactor. Review a concrete +boundary before selecting an abstraction. + +**Decision:** pending boundary analysis and agreement. + +## F14–F15 — Joint source-prefix design + +**Question:** how can discovery preparation and help lookup reuse one source +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 +alias source structure, or one shared private index if the existing structure +cannot serve both operations simply. + +**Preliminary recommendation:** prefer reuse; preserve classification, +authoritative resolution, deduplication, and ordering. Select the concrete +traversal and ownership together. No performance test is required to justify +remediation; correctness validation remains appropriate. + +**Decision:** joint remediation selected in the catalog; concrete design pending. + +## F17–F20 — Proportionate private extractions + +**Question:** which proposed extractions make responsibilities clearer without +adding records, phases, or configurable mechanisms merely to shorten functions? + +**Evidence:** catalog entries [F17](catalog.md#f17--p3-configuration-scope-capture-combines-several-compilation-phases), +[F18](catalog.md#f18--p3-configuration-preflight-interleaves-shared-and-operation-specific-rules), +[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 +retaining related code together where extraction only adds indirection. + +**Preliminary recommendation:** review each extraction separately. F20 has a +concrete shared rendering/error policy; keep its refactor distinct from F03's +correctness repair. For F17–F19, make meaningful responsibilities and required +ordering visible without treating incidental private sequences as contracts. + +**Decision:** individual extraction choices pending review.