document shape: diagnostics, headingless tables, plus-sigil rows and env-var columns

CHANGELOG.md

@@ -44,6 +44,14 @@ once it reaches a published 0.1.0 release.
 - [S-157] A single-dash long option's bare-word value name inside a no-double-dash table now survives instead of reading as the first word of the description, so `mandible Xvfb` shows `-audit int` and `-fp string`, and `mandible mksquashfs`/`mandible sqfstar` show `-Xstrategy` and `-Xbcj` with their comma-separated value lists.
 - [S-158] A value spec that glues a bracket-optional group directly onto a required angle placeholder now keeps the whole run, so `mandible rustc` shows `-L`'s `[<KIND>=]<PATH>` and `--emit`'s `<TYPE>[=<FILE>]` in full instead of losing the half that doesn't open the run.
 - [S-160] A value spec that swallowed its own alias run's trailing comma no longer hides the spelling behind it, so `mandible biolatpcts-bpfcc` shows `-p, --pcts` instead of a lone `-p`.
+- [S-162] A leading option-rejection diagnostic no longer fuses into the root description, so `mandible fuser` and `mandible nfsidmap` show their real description and usage instead of the tool's own complaint about the probe.
+- [S-163] A `+word` option row and a `+/-name`/`[+-]name` alternation row now reach the tree, the second expanding to its own `+name` and `-name` entities, so `mandible fzf` keeps `+i` and `+s, --no-sort` with the rest of its `Search` group, and `mandible Xvfb` recovers every `+`-prefixed row.
+- [S-164] A root flag group that only repeated the node's own description verbatim is dropped now, so `mandible fc-scan`, `mandible fc-validate`, `mandible grub-macbless` and `mandible lto-dump` no longer show the same sentence twice.
+- [S-165] A headingless option table no longer duplicates into the root description, so `mandible Xvfb` shows its real description once and its whole flag table instead of the same text rendered twice.
+- [S-166] A header row that names its own columns as `Argument`, `Env-variable` and `Description` is now read at those exact offsets, so `mandible qemu-riscv64-static` and the rest of the `qemu-*-static` fleet show a clean description and each flag's own environment variable instead of the two glued together, keep `-cpu` and `-dfilter`'s own value names, and no longer invent an `-E` row from the prose paragraph below the table.
+- [S-163] A `+/-name` alternation row's own expansion no longer collides with an ordinary row documenting the same spelling, and a `+word` row's value column is now borrowed onto its `-word` sibling when the ordinary repair can't recover a bare one, so `mandible Xvfb` keeps one `-render` with its four choices, one `+render`, and the same `name` value on both `+extension` and `-extension`; its `+word` spellings also render in the long column now, beside `-render`, instead of the short column at column 0.
+- [S-168] A colon-introduced list of bare-name choices sitting directly under a placeholder row — or a `+word`/`-word` pair sharing one — now becomes that placeholder's own choices instead of folding into the row's own description, so `mandible Xvfb`'s `+extension`/`-extension` pair shows its 19 run-time-toggleable extension names as choices on both halves.
+- [S-145] A single-dash-long table with no column padding at all now recovers a row's genuine bracketed value one space after its name, so `mandible Xvfb`'s `-render` and `-deferglyphs` keep their own choices instead of losing them outright.
 
 ## [0.7.0] - 2026-09-05
 

corpus/README.md

@@ -291,6 +291,24 @@ no root satisfies this vacuously, the same reasoning `must_not_contain_flags`
 uses. Dropping an entry is a weakening exactly as dropping a
 `must_not_contain_flags` entry is.
 
+### Stating that the root description carries text it must not: `must_not_describe_root`
+
+`must_not_describe` only ever checks a *flag's* own description. Nothing
+before this field could say the *root's* own `description` is
+contaminated — `Xvfb`'s leading option-rejection diagnostic
+(`Unrecognized option: --help`) used to fuse into the root description
+alongside its whole eighty-row option table (docs/shapes.md S-162).
+
+```toml
+must_not_describe_root = ["Unrecognized option"]
+```
+
+Every listed string is checked as a substring of `root.description`,
+whitespace-collapsed to a single space on both sides, `must_describe`'s
+own rule. `cargo xtask corpus` fails when any listed text is still
+present, naming it. Satisfied vacuously by a tree with no root or no
+description at all, the same reasoning `must_not_contain_flags` uses.
+
 ### Stating that a flag group is not an invocation line: `must_not_contain_flag_group_prefixes`
 
 `must_not_contain_flags` and `must_not_contain_usage_text` say nothing

corpus/Xvfb/audit-seed10/expected.snap → corpus/Xvfb/audit-seed/expected.snap

@@ -1,18 +1,16 @@
 name: Xvfb
-description: 'Unrecognized option: --help use: X [:<display>] [option] -a # default pointer acceleration (factor) -ac disable access control restrictions -audit int set audit trail level -auth file select authorization file -br create root window with black background +bs enable any backing store support -bs disable any backing store support +byteswappedclients Allow clients with endianess different to that of the server -byteswappedclients Prohibit clients with endianess different to that of the server -c turns off key-click c # key-click volume (0-100) -cc int default color visual class -nocursor disable the cursor -core generate core dump on fatal error -displayfd fd file descriptor to write display number to when ready to connect -dpi int screen resolution in dots per inch -dpms disables VESA DPMS monitor control -deferglyphs [none|all|16] defer loading of [no|all|16-bit] glyphs -f # bell base (0-100) -fakescreenfps # fake screen default fps (1-600) -fp string default font path -help prints message with these options +iglx Allow creating indirect GLX contexts -iglx Prohibit creating indirect GLX contexts (default) -I ignore all remaining arguments -ld int limit data space to N Kb -lf int limit number of open files to N -ls int limit stack space to N Kb -nolock disable the locking mechanism -maxclients n set maximum number of clients (power of two) -nolisten string don''t listen on protocol -listen string listen on protocol -noreset don''t reset after last client exists -background [none] create root window with no background -reset reset after last client exists -p # screen-saver pattern duration (minutes) -pn accept failure to listen on all ports -nopn reject failure to listen on all ports -r turns off auto-repeat r turns on auto-repeat -render [default|mono|gray|color] set render color alloc policy -retro start with classic stipple and cursor -s # screen-saver timeout (minutes) -seat string seat to run on -t # default pointer threshold (pixels/t) -terminate [delay] terminate at server reset (optional delay in sec) -tst disable testing extensions ttyxx server started from init on /dev/ttyxx v video blanking for screen-saver -v screen-saver without video blanking -wr create root window with white background -maxbigreqsize set maximal bigrequest size +xinerama Enable XINERAMA extension -xinerama Disable XINERAMA extension -dumbSched Disable smart scheduling and threaded input, enable old behavior -schedInterval int Set scheduler interval in msec -sigstop Enable SIGSTOP based startup +extension name Enable extension -extension name Disable extension -query host-name contact named host for XDMCP -broadcast broadcast for XDMCP -multicast [addr [hops]] IPv6 multicast for XDMCP -indirect host-name contact named host for indirect XDMCP -port port-num UDP port number to send messages to -from local-address specify the local address to connect from -once Terminate server after one session -class display-class specify display class to send in manage -cookie xdm-auth-bits specify the magic cookie for XDMCP -displayID display-id manufacturer display ID for request [+-]accessx [ timeout [ timeout_mask [ feedback [ options_mask] ] ] ] -ardelay set XKB autorepeat delay -arinterval set XKB autorepeat interval -screen scrn WxHxD set screen''s width, height, depth -pixdepths list-of-int support given pixmap depths +/-render turn on/off RENDER extension support(default on) -linebias n adjust thin line pixelization -blackpixel n pixel value for black -whitepixel n pixel value for white -fbdir directory put framebuffers in mmap''ed files in directory -shmem put framebuffers in shared memory (EE) Fatal server error: (EE) Unrecognized option: --help (EE)'
+description: 'use: X [:<display>] [option]'
 flags:
 - spellings:
   - -a
   value_name: '#'
   value_kind: Required
-  group: 'use: X [:<display>] [option]'
   description: default pointer acceleration (factor)
   provenance:
     sources:
     - help-text
 - spellings:
   - -ac
-  group: 'use: X [:<display>] [option]'
   description: disable access control restrictions
   provenance:
     sources:
@@ -21,7 +19,6 @@ flags:
   - -audit
   value_name: int
   value_kind: Required
-  group: 'use: X [:<display>] [option]'
   description: set audit trail level
   provenance:
     sources:
@@ -30,24 +27,34 @@ flags:
   - -auth
   value_name: file
   value_kind: Required
-  group: 'use: X [:<display>] [option]'
   description: select authorization file
   provenance:
     sources:
     - help-text
 - spellings:
   - -br
-  group: 'use: X [:<display>] [option]'
   description: create root window with black background
   provenance:
     sources:
     - help-text
+- spellings:
+  - +bs
+  description: enable any backing store support
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -bs
   description: disable any backing store support
   provenance:
     sources:
     - help-text
+- spellings:
+  - +byteswappedclients
+  description: Allow clients with endianess different to that of the server
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -byteswappedclients
   description: Prohibit clients with endianess different to that of the server
@@ -102,6 +109,8 @@ flags:
     - help-text
 - spellings:
   - -deferglyphs
+  value_name: '[none|all|16]'
+  value_kind: Optional
   description: defer loading of [no|all|16-bit] glyphs
   provenance:
     sources:
@@ -134,6 +143,12 @@ flags:
   provenance:
     sources:
     - help-text
+- spellings:
+  - +iglx
+  description: Allow creating indirect GLX contexts
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -iglx
   description: Prohibit creating indirect GLX contexts (default)
@@ -248,6 +263,8 @@ flags:
     - help-text
 - spellings:
   - -render
+  value_name: '[default|mono|gray|color]'
+  value_kind: Optional
   description: set render color alloc policy
   provenance:
     sources:
@@ -314,6 +331,12 @@ flags:
   provenance:
     sources:
     - help-text
+- spellings:
+  - +xinerama
+  description: Enable XINERAMA extension
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -xinerama
   description: Disable XINERAMA extension
@@ -340,11 +363,59 @@ flags:
   provenance:
     sources:
     - help-text
+- spellings:
+  - +extension
+  value_name: name
+  value_kind: Required
+  choices:
+  - Generic Event Extension
+  - MIT-SHM
+  - XTEST
+  - SECURITY
+  - XINERAMA
+  - XFIXES
+  - RENDER
+  - RANDR
+  - COMPOSITE
+  - DAMAGE
+  - MIT-SCREEN-SAVER
+  - DOUBLE-BUFFER
+  - RECORD
+  - DPMS
+  - X-Resource
+  - XVideo
+  - XVideo-MotionCompensation
+  - SELinux
+  - GLX
+  description: Enable extension
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -extension
   value_name: name
   value_kind: Required
-  description: 'Disable extension Only the following extensions can be run-time enabled/disabled: Generic Event Extension MIT-SHM XTEST SECURITY XINERAMA XFIXES RENDER RANDR COMPOSITE DAMAGE MIT-SCREEN-SAVER DOUBLE-BUFFER RECORD DPMS X-Resource XVideo XVideo-MotionCompensation SELinux GLX'
+  choices:
+  - Generic Event Extension
+  - MIT-SHM
+  - XTEST
+  - SECURITY
+  - XINERAMA
+  - XFIXES
+  - RENDER
+  - RANDR
+  - COMPOSITE
+  - DAMAGE
+  - MIT-SCREEN-SAVER
+  - DOUBLE-BUFFER
+  - RECORD
+  - DPMS
+  - X-Resource
+  - XVideo
+  - XVideo-MotionCompensation
+  - SELinux
+  - GLX
+  description: Disable extension
   provenance:
     sources:
     - help-text
@@ -364,6 +435,8 @@ flags:
     - help-text
 - spellings:
   - -multicast
+  value_name: '[addr [hops]'
+  value_kind: Optional
   description: IPv6 multicast for XDMCP
   provenance:
     sources:
@@ -422,30 +495,48 @@ flags:
   provenance:
     sources:
     - help-text
+- spellings:
+  - +accessx
+  value_name: '[ timeout [ timeout_mask [ feedback [ options_mask] ] ] ]'
+  value_kind: Optional
+  description: enable/disable accessx key sequences
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -accessx
+  value_name: '[ timeout [ timeout_mask [ feedback [ options_mask] ] ] ]'
+  value_kind: Optional
+  description: enable/disable accessx key sequences
+  provenance:
+    sources:
+    - help-text
 - spellings:
   - -ardelay
-  group: enable/disable accessx key sequences
   description: set XKB autorepeat delay
   provenance:
     sources:
     - help-text
 - spellings:
   - -arinterval
-  group: enable/disable accessx key sequences
   description: set XKB autorepeat interval
   provenance:
     sources:
     - help-text
 - spellings:
   - -screen
-  group: enable/disable accessx key sequences
   description: set screen's width, height, depth
   provenance:
     sources:
     - help-text
 - spellings:
   - -pixdepths
-  group: enable/disable accessx key sequences
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - +render
+  description: turn on/off RENDER extension support(default on)
   provenance:
     sources:
     - help-text

corpus/Xvfb/audit-seed/meta.toml

@@ -0,0 +1,76 @@
+# Xvfb rejects `--help`, prints a leading diagnostic line, then a headingless
+# table of over eighty option rows with no recognized heading at all. Three
+# defects shared one specimen: the leading diagnostic (S-162), `+word` and
+# `+/-name`/`[+-]name` rows (S-163), and the headingless table landing in the
+# root description (S-165). All three are fixed.
+#
+# Round 11 repaired four further defects on this same specimen: the
+# `+/-render` alternation row used to collide with the ordinary `-render`
+# row, losing its four choices (S-163); `+extension`/`-extension` used to
+# read different value columns for the same `name` placeholder (S-163);
+# the colon-introduced list of run-time-toggleable extension names used to
+# fold into `-extension`'s own description instead of becoming `name`'s
+# choices, shared by both halves of the pair (S-168); and `+word` spellings
+# used to render in the wrong column (mandible-tui, not this fixture).
+
+[bless]
+provenance = "agent"
+
+[tool]
+name = "Xvfb"
+version = "audit-seed"
+platform = "ubuntu-24.04"
+captured_with = "frozen capture, round 10 W5"
+
+[[capture]]
+argv = ["Xvfb", "--help"]
+stdout = "help.stdout.txt"
+stderr = "help.stderr.txt"
+
+[contract]
+expected_framework = "generic"
+min_status = "ok"
+# The leading diagnostic never survives into the root description (S-162).
+must_not_describe_root = ["Unrecognized option", "disable access control restrictions"]
+# `+word` (S-163 rule 1) and the alternation-sigil rows (S-163 rules 2/3)
+# all reach the tree, both halves each. `+extension`/`-extension` reach it
+# too, each exactly once (round 11's collision-avoidance rule).
+must_contain_flags = ["+bs", "-bs", "+accessx", "-accessx", "+render", "-render", "+extension", "-extension", "-audit", "-auth", "-fp", "-help"]
+# Neither the `use:` usage-label line nor `[+-]accessx`'s own wrapped
+# description survives as a fabricated group heading (S-164/S-165).
+must_not_contain_flag_group_prefixes = ["use: X", "Enable/disable accessx", "enable/disable accessx"]
+
+[contract.must_describe]
+# The headingless table no longer duplicates into the root description
+# (S-165): each flag keeps its own row's own description.
+"-a" = "default pointer acceleration"
+# The `+/-render` alternation row's own expansion never overwrites the
+# ordinary `-render` row's own description (round 11, S-163).
+"-render" = "set render color alloc policy"
+"+render" = "turn on/off RENDER extension support"
+# The colon-introducer line is gone from `-extension`'s description, not
+# folded in (S-168).
+"-extension" = "Disable extension"
+"+extension" = "Enable extension"
+
+[contract.must_value_name]
+# The `+/-render` collision never costs `-render` its own four-choice
+# bracket value (round 11, S-163).
+"-render" = "default"
+# Bare-word single-dash-long-table values (S-157): each used to read as a
+# boolean, its value name absorbed into the row's own description column.
+"-audit" = "int"
+"-auth" = "file"
+"-fp" = "string"
+# `+extension` and `-extension` read the same value column (round 11,
+# S-163): both name the placeholder `name`, never a garbled swallowed tail.
+"-extension" = "name"
+"+extension" = "name"
+
+[contract.must_attach_choices]
+# The colon-introduced list of run-time-toggleable extensions (S-168)
+# becomes `name`'s own choices, shared by both halves of the
+# `+extension`/`-extension` pair — never folded into `-extension`'s
+# description.
+"-extension" = ["Generic Event Extension", "MIT-SHM", "GLX"]
+"+extension" = ["Generic Event Extension", "MIT-SHM", "GLX"]