Document flag declaration rules

binding.go

@@ -64,6 +64,7 @@ func OccurrenceFlag[I, V any](meta FlagMeta, parse func(string) (V, error), set
 
 // RenameFlag returns an independent binding with a new long name and no short
 // spelling. Parsing, defaults, completion, requiredness, and setters are retained.
+// The name follows the declaration rules in [FlagMeta].
 func RenameFlag[I any](flag Flag[I], name string) Flag[I] {
 	binding := flag.binding
 	binding.meta.Name = name

command.go

@@ -90,10 +90,14 @@ type Supplied[T any] struct {
 
 // FlagMeta describes a command flag. Required applies when execution prepares
 // the selected command; help reports the metadata without requiring the value.
+// Invalid declarations are reported when installed.
 type FlagMeta struct {
-	// Name is the flag name without leading dashes.
+	// Name is a nonempty long name without leading dashes. It consists of
+	// Unicode lowercase letters or digits in segments separated by single
+	// hyphens; digit-leading and numeric-only names are valid. The names help,
+	// quiet, verbose, debug, progress and format are reserved.
 	Name string
-	// Short is an optional one-byte spelling.
+	// Short is an optional one-byte spelling other than '-' or the reserved 'h'.
 	Short string
 	// Usage briefly describes the flag.
 	Usage string
@@ -352,6 +356,7 @@ func Alias(path, target string) RoutingRule {
 // wherever its canonical target flag is available and contributes nothing on
 // commands without that flag. Identical mappings are accepted; different
 // targets for the same source spelling in this scope are installation errors.
+// Long and short spelling forms follow the grammar described by [FlagMeta].
 func FlagAlias(spelling, target string) RoutingRule {
 	record := &routingRuleRecord{
 		kind:       globalFlagAliasRule,
@@ -368,6 +373,7 @@ func FlagAlias(spelling, target string) RoutingRule {
 // available in the complete installation. Scoped mappings take precedence over
 // application-wide mappings with the same source spelling. Identical mappings
 // are accepted; competing targets in the same scope are installation errors.
+// Long and short spelling forms follow the grammar described by [FlagMeta].
 func FlagAliasFor(commandPath, spelling, target string) RoutingRule {
 	record := &routingRuleRecord{
 		kind:       scopedFlagAliasRule,

docs/roadmap/audit/catalog.md

@@ -1,6 +1,6 @@
 # Consolidated audit catalog
 
-Status: **16 distinct open findings: 16 P3**, consolidated from 30
+Status: **15 distinct open findings: 15 P3**, consolidated from 30
 numbered entries in seven audit documents. Reviewed audit state:
 `db732e3a1de55c844f77870e1c6db683c2685d5d`.
 
@@ -207,6 +207,10 @@ unused explanation-writer requirement in F11.
 
 ## F10 — P3: Public flag metadata omits enforced naming and reserved-spelling rules
 
+**Complete.** FlagMeta documents the existing declaration rules and related
+rename and alias GoDoc refers to them. The prose was checked against the
+installation validator; no runtime rule changed.
+
 `FlagMeta` describes names without leading dashes and an optional short
 spelling, while installation enforces additional name grammar and reserved
 spellings. Consumers must discover those constraints through errors or private
@@ -223,8 +227,7 @@ 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 records the accepted direction. Implementation
-of the documentation correction remains pending.
+the naming convention's basis and records the accepted direction.
 
 **Original:** [13-documentation D2](13-documentation.md#d2--p3-public-flag-metadata-omits-enforced-declaration-constraints).
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Audit remediation implementation plan
 
-Status: in progress; Stages 1–9 complete.
+Status: in progress; Stages 1–10 complete.
 
 Baseline: `d492c7747175c01a53261206c2b4356e53453621`. Before this sprint,
 intervening changes recorded decisions and retired the completed older
@@ -357,6 +357,11 @@ F09, and acquisition-only provider wiring with preserved rendering for F11.
 
 ## Stage 10 — Document the selected flag declaration contract
 
+**Complete.** FlagMeta describes the existing Unicode long-name grammar,
+reserved names and short spellings; rename and alias guidance links to it.
+Reviewed against `validateBindings`, `validFlagName`, and the accepted catalog
+decision. No runtime validation was changed.
+
 Findings: F10. Source: `command.go` FlagMeta and related rename/alias GoDoc.
 
 1. Define long names once with FlagMeta: nonempty Unicode lowercase-letter or