Record flag naming decision and diagnostic adapter analysis

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).
 

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