memhog: no description swallow, real values, and the usage operands

CHANGELOG.md

@@ -8,6 +8,10 @@ once it reaches a published 0.1.0 release.
 
 ## [Unreleased]
 
+### Fixed
+
+- [S-176] A single-dash table row with no placeholder column now reads its flag's real value off the tool's own usage line instead of guessing it from the description's first word (`mandible host`, `mandible kpartx`, `mandible numastat`, `mandible savelog`, `mandible memhog`); `mandible memhog` also gains its `size`/`policy`/`nodeset` positionals (S-177) instead of a swallowed root description.
+
 ## [0.8.0] - 2026-09-14
 
 ### Changed

corpus/dbiprof/1.643/expected.snap

@@ -1,6 +1,11 @@
 name: dbiprof
 usage:
 - dbiprof [options] [files]
+positionals:
+- name: files
+  provenance:
+    sources:
+    - help-text
 flags:
 - spellings:
   - -number

corpus/host/9.18.39/expected.snap

@@ -0,0 +1,159 @@
+name: host
+usage:
+- 'Usage: host [-aCdilrTvVw] [-c class] [-N ndots] [-t type] [-W time] [-R number] [-m flag] [-p port] hostname [server]'
+flags:
+- spellings:
+  - -a
+  description: is equivalent to -v -t ANY
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -A
+  value_name: is
+  value_kind: Required
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -c
+  value_name: class
+  value_kind: Required
+  description: specifies query class for non-IN data
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -C
+  description: compares SOA records on authoritative nameservers
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -d
+  description: is equivalent to -v
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -l
+  description: lists all hosts in a domain, using AXFR
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -m
+  value_name: flag
+  value_kind: Required
+  description: set memory debugging flag (trace|record|usage)
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -N
+  value_name: ndots
+  value_kind: Required
+  description: changes the number of dots allowed before root lookup is done
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -p
+  value_name: port
+  value_kind: Required
+  description: specifies the port on the server to query
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -r
+  description: disables recursive processing
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -R
+  value_name: number
+  value_kind: Required
+  description: specifies number of retries for UDP packets
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -s
+  value_name: a
+  value_kind: Required
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -t
+  value_name: type
+  value_kind: Required
+  description: specifies the query type
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -T
+  description: enables TCP/IP mode
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -U
+  value_name: enables
+  value_kind: Required
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -v
+  description: enables verbose output
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -V
+  description: print version number and exit
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -w
+  description: specifies to wait forever for a reply
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -W
+  value_name: time
+  value_kind: Required
+  description: specifies how long to wait for a reply
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - '-4'
+  value_name: use
+  value_kind: Required
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - '-6'
+  value_name: use
+  value_kind: Required
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -i
+  provenance:
+    sources:
+    - help-text-synopsis
+provenance:
+  sources:
+  - help-text
+  confidence: 0.0
+children_filled: true

corpus/host/9.18.39/help.stderr.txt

@@ -0,0 +1,24 @@
+host: illegal option -- -
+Usage: host [-aCdilrTvVw] [-c class] [-N ndots] [-t type] [-W time]
+            [-R number] [-m flag] [-p port] hostname [server]
+       -a is equivalent to -v -t ANY
+       -A is like -a but omits RRSIG, NSEC, NSEC3
+       -c specifies query class for non-IN data
+       -C compares SOA records on authoritative nameservers
+       -d is equivalent to -v
+       -l lists all hosts in a domain, using AXFR
+       -m set memory debugging flag (trace|record|usage)
+       -N changes the number of dots allowed before root lookup is done
+       -p specifies the port on the server to query
+       -r disables recursive processing
+       -R specifies number of retries for UDP packets
+       -s a SERVFAIL response should stop query
+       -t specifies the query type
+       -T enables TCP/IP mode
+       -U enables UDP mode
+       -v enables verbose output
+       -V print version number and exit
+       -w specifies to wait forever for a reply
+       -W specifies how long to wait for a reply
+       -4 use IPv4 query transport only
+       -6 use IPv6 query transport only

corpus/host/9.18.39/meta.toml

@@ -0,0 +1,75 @@
+# `host --help` writes only its getopt complaint to stdout... no, to
+# stderr: `host: illegal option -- -` (S-162's own shape, already
+# stripped), then a single-dash option table with no column gap
+# anywhere and no placeholder column. Every row reads its description's
+# first bare word as a fabricated value before this fixture's fix.
+#
+# Fixed by reading each flag's real value from `host`'s own usage line
+# (`Usage: host [-aCdilrTvVw] [-c class] [-N ndots] [-t type] [-W time]
+# [-R number] [-m flag] [-p port] hostname [server]`), the same grammar
+# and bundle logic `extract_usage_flags` already uses everywhere else:
+# `-c`/`-N`/`-t`/`-W`/`-R`/`-m`/`-p` each keep the spaced placeholder
+# usage names them (`class`/`ndots`/`type`/`time`/`number`/`flag`/`port`)
+# and gain their real description; every bundle member
+# (`-a`/`-C`/`-d`/`-l`/`-r`/`-T`/`-v`/`-V`/`-w`) is read boolean, per the
+# bundle `[-aCdilrTvVw]`, and also gains its real description.
+#
+# Honest residual, deliberately not claimed here: `-A`, `-s`, `-U`, `-4`
+# and `-6` are named in NO usage line at all (not in the bundle, not in
+# their own bracket group), so the fix has no evidence for them and
+# leaves them exactly as broken as before: a fabricated value guessed
+# from their own description's first word, and no description recovered.
+# `must_not_contain_flags` below is not the tool for stating that; it is
+# recorded here in prose since the corpus contract has no "known still
+# wrong" field.
+#
+# `-i` also appears in the tree, undescribed: the usage bundle
+# `[-aCdilrTvVw]` names it but no option row documents it. Pre-existing
+# behaviour (spec [M-15], usage-derived flags), not something this fix
+# changed.
+
+[bless]
+provenance = "agent"
+
+[tool]
+name = "host"
+version = "9.18.39"
+platform = "ubuntu-24.04"
+captured_with = "manual capture per corpus/README.md step 2 (TERM=dumb NO_COLOR=1 COLUMNS=100 LC_ALL=C.UTF-8); bind9-host 1:9.18.39-0ubuntu0.24.04.7"
+
+[[capture]]
+argv = ["host", "--help"]
+stdout = "help.txt"
+stderr = "help.stderr.txt"
+exit_code = 1
+
+[contract]
+# `mandible --doctor host` reports framework: unidentified.
+expected_framework = "generic"
+
+[contract.must_describe]
+"-a" = "is equivalent to -v -t ANY"
+"-C" = "compares SOA records on authoritative nameservers"
+"-c" = "specifies query class for non-IN data"
+"-d" = "is equivalent to -v"
+"-l" = "lists all hosts in a domain, using AXFR"
+"-m" = "set memory debugging flag (trace|record|usage)"
+"-N" = "changes the number of dots allowed before root lookup is done"
+"-p" = "specifies the port on the server to query"
+"-r" = "disables recursive processing"
+"-R" = "specifies number of retries for UDP packets"
+"-t" = "specifies the query type"
+"-T" = "enables TCP/IP mode"
+"-v" = "enables verbose output"
+"-V" = "print version number and exit"
+"-w" = "specifies to wait forever for a reply"
+"-W" = "specifies how long to wait for a reply"
+
+[contract.must_value_name]
+"-c" = "class"
+"-N" = "ndots"
+"-t" = "type"
+"-W" = "time"
+"-R" = "number"
+"-m" = "flag"
+"-p" = "port"

corpus/lsof/4.95.0/expected.snap

@@ -1,5 +1,8 @@
 name: lsof
-description: 'lsof: -e not followed by a file system path: "lp" lsof 4.95.0 Defaults in parentheses; comma-separated set (s) items; dash-separated ranges. Anyone can list all files; /dev warnings disabled; kernel ID check disabled.'
+description: |-
+  lsof: -e not followed by a file system path: "lp" lsof 4.95.0 Defaults in parentheses; comma-separated set (s) items; dash-separated ranges.
+
+  Anyone can list all files; /dev warnings disabled; kernel ID check disabled.
 usage:
 - 'usage: [-?abhKlnNoOPRtUvVX] [+|-c c] [+|-d s] [+D D] [+|-E] [+|-e s] [+|-f[gG]] [-F [f]] [-g [s]] [-i [i]] [+|-L [l]] [+m [m]] [+|-M] [-o [o]] [-p s] [+|-r [t]] [-s [p:s]] [-S [t]] [-T [t]] [-u s] [+|-w] [-x [fl]] [--] [names]'
 flags:
@@ -152,6 +155,7 @@ flags:
   - -F
   value_name: f
   value_kind: Optional
+  description: select fields; -F? for help
   provenance:
     sources:
     - help-text

corpus/memhog/2.0.18/expected.snap

@@ -0,0 +1,46 @@
+name: memhog
+description: 'Policies: preferred-many local interleave membind preferred default'
+usage:
+- memhog [-fFILE] [-rNUM] [-H] size[kmg] [policy [nodeset]]
+positionals:
+- name: size
+  required: true
+  provenance:
+    sources:
+    - help-text
+- name: policy
+  provenance:
+    sources:
+    - help-text
+- name: nodeset
+  provenance:
+    sources:
+    - help-text
+flags:
+- spellings:
+  - -f
+  value_name: FILE
+  value_kind: Required
+  description: mmap is backed by FILE
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -r
+  value_name: NUM
+  value_kind: Required
+  description: repeat memset NUM times
+  provenance:
+    sources:
+    - help-text
+- spellings:
+  - -H
+  description: disable transparent hugepages
+  provenance:
+    sources:
+    - help-text
+provenance:
+  sources:
+  - help-text
+  confidence: 0.0
+children_filled: true