Answer

I diagnosed this in the actual repo (github.com/deployBunker/bunker, cloned to /workspace/bunker) and verified the fix end-to-end (reproduced the failing gate, applied the change, re-ran it green).

Fix: docs flag registry misses flagGrammar map-literal specs

Root cause

The docs-drift gate (cmd/docs-drift, driven by internal/docscheck) derives the per-command long-flag registry from source, not from a running binary. internal/docscheck/flags.go only knew two registration shapes:

• reFlagCall — cobra registrations like cmd.Flags().StringVar(&x, "server", …).
• reFlagPeel — manual peel cases like case rest[i] == "--detach":.

bunker exec, bunker run, and bunker env (all DisableFlagParsing) now declare their authoritative accepted-flag surface in a flagGrammar spec map:

// internal/cli/exec.go
execGrammar := flagGrammar{name: "exec", specs: map[string]flagGrammarSpec{
    "--server":  {apply: func(v string) error { serverName = v; return nil }},
    "--session": {apply: func(v string) error { sessionID = v; return nil }},
    ...
}}

--session (exec/run), --preset (run), and the peeled --config/--daemon-config exist only as map keys — no cobra Flags() call, no case peel. collectFlagLiterals never recorded them, leaving the registry incomplete:

exec = [base64 exec-cap raw script server stdin timeout]
run  = [detach env name server timeout]

The real-tree gate then flagged already-correct docs in docs/exec-audit.md (GAP-095):

docs/exec-audit.md:307: docs-flag-surface: --session is not a flag of `bunker exec` …; accept: --base64 --exec-cap --raw --script --server --stdin --timeout
docs/exec-audit.md:308: docs-flag-surface: --session is not a flag of `bunker run` …; accept: --detach --env --name --server --timeout

Exact fix

File: internal/docscheck/flags.go

1. Add a third registration regex:

// reFlagSpec matches the map-literal spec table of a flagGrammar
// (exec, run, env): `"--session": {apply: func(…) …}`. Those peel-style
// commands key their accepted-flag surface by the full flag name, and the
// table — not the cobra registration — is authoritative; a registry that
// does not read it reports a documented `--session` as unknown.
reFlagSpec = regexp.MustCompile(`"(--[A-Za-z0-9][A-Za-z0-9-]*)"\s*:\s*\{apply:`)

1. Collect it in collectFlagLiterals, next to the peel loop:

for _, m := range reFlagPeel.FindAllStringSubmatch(body, -1) {
    addFlagName(into, strings.TrimPrefix(m[1], "--"))
}
for _, m := range reFlagSpec.FindAllStringSubmatch(body, -1) {
    addFlagName(into, strings.TrimPrefix(m[1], "--"))
}

The \s*:\s*\{apply: anchor is tied to the first struct field (flagGrammarSpec starts with apply), so a map literal that merely looks like a flag key cannot inflate the registry.

1. Added regression test TestFlagsForReadsFlagGrammarSpecTables in internal/docscheck/flags_test.go, asserting a flag declared only as a specs: map key is collected.

Verification

gofmt -l internal/docscheck/      # no output
go test ./internal/docscheck/ -count=1
go run ./cmd/docs-drift

Observed go run ./cmd/docs-drift:

docs OK: README/CHANGELOG/docs match v0.2.0 (35 released commands, 208 commit(s) after the tag)
  released: [agent-tools audit connect cp deploy destroy env exec fs guard heartbeat homes host-provision info key linger list metrics mount registry renew restart run spawn ssh start status stop subid-migrate surface systemd tunnel umount use version]

Before the fix, TestRealDocsPassFlagSurface failed on docs/exec-audit.md:307-308; after the fix both pass with no marker, and all docscheck tests are green. (The real-tree tests need release tags — in a shallow/tag-less checkout they skip; in CI they run.)

The solution file was written to /workspace/solution.md.

# Evidence
- Problem class: regex-source-flag-registry-misses-map-literal-flag-shape
- Model: openrouter/deepseek/deepseek-v4.1-flash
- Solved: 2026-10-09T17:46:47.401Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "regex-source-flag-registry-misses-map-literal-flag-shape", "provider": "openrouter", "solved_at": "2026-10-09T17:46:47.403Z", "version": ""}