diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 3ef18a0..1ca5075 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -169,13 +169,19 @@ spelling, while installation enforces additional name grammar and reserved spellings. Consumers must discover those constraints through errors or private implementation. -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. +**Decision:** retain and document the existing declaration rules. Long names use +Unicode lowercase letters and digits separated by single hyphens; numeric names +and names beginning with digits remain allowed. Keep core-owned reserved names +and the optional one-byte short-spelling rules, excluding `-` and reserved `h`. +Do not add ASCII-only or leading-letter restrictions, or automatic rewriting of +invalid names. These rules concern flag names, not supplied values. + +Document the rules once with `FlagMeta` and link related public helpers. This +remediation changes documentation, not runtime validation. 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. +the naming convention's basis and records the accepted direction. Implementation +of the documentation correction remains pending. **Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints). diff --git a/docs/roadmap/audit/remediation-analysis.md b/docs/roadmap/audit/remediation-analysis.md index ee0e3d2..ee06d4c 100644 --- a/docs/roadmap/audit/remediation-analysis.md +++ b/docs/roadmap/audit/remediation-analysis.md @@ -8,7 +8,7 @@ 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 +Existing catalog decisions for F03, F10, 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. @@ -16,8 +16,8 @@ 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 | +| 1 | F10 | Which flag declaration rules should be documented as the intended contract? | Decided: retain and document existing rules; remediation pending | +| 2 | F21 | What narrow diagnostic adaptation API would simplify both integrations? | Adapters compared; recommendation pending agreement | | 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 | @@ -80,11 +80,13 @@ 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. +operator syntax in the CLI reference. This is a documentation remediation; +it does not require a new ADR, parser, or validation framework. -**Decision:** pending agreement. The recommendation does not authorize a change -to validation behavior. +**Decision:** option 1 accepted and recorded in the catalog. Retain the current +long-name grammar, Unicode lowercase and digit support, reservations, and +short-spelling rules. No runtime validation change or name normalization is +selected. F10 remains open until its public documentation is corrected. ## F21 — Shared ConfigKit diagnostic adaptation @@ -98,14 +100,42 @@ links both adapters and the original analysis. 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. +**Analysis:** ckconfig's private `configKitDiagnosticsWithHeading` already +accepts a heading, native sources, and native diagnostic records, and returns +core diagnostics and an explanation. ckprompt duplicates the evidence snapshot, +severity partition, source legend, and delegation to `configkit.WriteDiagnostics`. +Its scope and comparison-side labels can be supplied as the heading; they do not +require another shared options type. See +[ckconfig's adapter](../../../integrations/ckconfig/configkit_adapter.go) and +[ckprompt's adapter](../../../integrations/ckprompt/adapters.go). -**Decision:** helper signature and scope pending analysis and agreement. +**Recommendation:** expose the existing adaptation responsibility through one +narrow ckconfig function and have both integrations use it. An illustrative +signature, not an implemented API, is: + +```go +func AdaptDiagnostics( + heading string, + sources []configkit.SourceInfo, + records []configkit.Diagnostic, +) ([]commandkit.Diagnostic, commandkit.Explanation) +``` + +Retain the existing evidence snapshot and severity treatment, ordering within +each group, source labels, and native record formatting. Return evidence ready +for CLI reporting; do not print immediately, select an invocation outcome, or +load or validate configuration. Callers supply headings and operation-specific +explanations and retain their error causes. Reporter remains responsible for +visibility and delivery. + +Keep scheduling with the callers. The smaller scheduling switches do not +independently justify another public helper. ckprompt already depends on +ckconfig; this introduces no new module dependency or ConfigKit dependency in +core. The public function serves CLI presentation, within the integration's +ownership boundary. Compatibility and migration are not obstacles; clarity and +maintenance cost are the decision criteria. + +**Decision:** recommendation and illustrative API pending agreement. ## F16 — Shared flag consumption