roadmap: #276 filed

ROADMAP.md

@@ -17097,3 +17097,19 @@ Gap. Diagnostic surfaces duplicate and diverge: `status` is branch/clean focused
 Required fix shape: (a) add a top-level `workspace_provenance` object to `doctor` JSON containing `project_root`, `cwd`, `git_head_sha`, `git_branch`, `git_state`, `remote_urls`, `upstream_branch`, `ahead`, `behind`, `official_repo`, and `repo_identity_status: matches_official|fork_of_official|mismatch|unknown`; (b) have `status` and `doctor` share the same provenance struct/renderer so fields cannot drift; (c) in text mode, add one compact Provenance section instead of scattering related fields across Install source/Workspace/System; (d) add tests proving a wrong remote reports `repo_identity_status: mismatch` without needing downstream string scraping. Acceptance: automation can read one `doctor.workspace_provenance` object and decide whether the current cwd is the intended claw-code worktree at the expected HEAD.
 
 **Status:** Open. No source code changed. Filed 2026-04-26 16:02 KST. Branch: feat/jobdori-168c-emission-routing. HEAD: `fdf8890` before filing. Cluster delta: product-diagnostic-provenance +1; sister to #273 (`status` provenance) but distinct `doctor` fragmented-schema surface. Concrete delta this cycle: ROADMAP-only pinpoint appended after live `doctor` JSON/text verification.
+
+## Pinpoint #276 — `--allowedTools` help line advertises only the camelCase form and an opaque "repeatable; comma-separated" prose, while `parse_args` additionally dispatches the kebab-case alias `--allowed-tools` and both `=`-form variants (`--allowedTools=VAL` / `--allowed-tools=VAL`), so the listed-flag's alias-and-value-shape coverage in help is structurally incomplete vs the parser — third help-contract-drift sub-axis distinct from #263 (listed-flag-stale-mode-matrix) and #270 (whole-flag-omitted)
+
+Dogfooded 2026-04-26 16:14 KST on `feat/jobdori-168c-emission-routing` at HEAD `0240cad` (post-rebase fast-forward onto gaebal-gajae's #275 `claw doctor` provenance fragmentation pinpoint). Fresh `cargo run --quiet --bin claw -- --help` lists `--allowedTools TOOLS       Restrict enabled tools (repeatable; comma-separated aliases supported)` at `rust/crates/rusty-claude-cli/src/main.rs:9418` and `claw [--model MODEL] [--allowedTools TOOL[,TOOL...]]` at `:9334` — both surfaces use only the camelCase `--allowedTools` token. Source inspection of `parse_args` at `:979-994` shows the dispatcher accepts four shape variants for the same flag: `--allowedTools VAL` (line 979 first arm), `--allowed-tools VAL` (same arm OR-pattern), `--allowedTools=VAL` (line 986 prefix arm), and `--allowed-tools=VAL` (line 990 second prefix arm). Live verification with the freshly rebuilt `target/debug/claw`: all four shapes parse past the CLI parse stage and fail downstream with `[error-kind: missing_credentials]`, confirming each variant is fully dispatch-accepted. Repeated invocation (`--allowedTools read --allowedTools glob`) also dispatches successfully, confirming the help's bare "repeatable" prose corresponds to a real wired surface but with no documented composition rule (does the second occurrence replace, append, or set-union the first?).
+
+Concrete failure mode: an operator scripting `claw` with shell tooling that prefers kebab-case-only conventions (e.g. POSIX-style argv generators, automation that derives flag names from snake_case fields via `s/_/-/g`, or downstream claws that mirror Anthropic Claude Code's documented `--allowed-tools` form) sees `claw --help` advertise only `--allowedTools` and either (a) avoids the kebab-case alias under the false belief it does not exist; or (b) discovers it accidentally by typing it; or (c) reads source. The `=`-form for both casings is the same: an operator habituated to `--flag=value` shell syntax cannot tell from help that `--allowedTools=read,glob` is a real path and may avoid it. The "repeatable" prose has no example showing whether `--allowedTools read --allowedTools glob` set-unions to `{read, glob}` or whether the second occurrence overwrites — fresh verification of `normalize_allowed_tools` at `main.rs:1826` and `current_tool_registry()?.normalize_allowed_tools(values)` at `tools/src/lib.rs:192` shows the values are accumulated into a flat `Vec<String>` and each is comma-split-and-flattened into a `BTreeSet`, so the actual semantic is set-union — but the help prose neither states this nor cites the alternative.
+
+Gap. The help-contract-drift cluster's third sub-axis: a listed flag whose dispatch surface accepts more shapes (alias casings, `=`-form, repetition with a defined composition rule) than the help line advertises. This is distinct from #263 (listed-flag-stale-mode-matrix: a documented flag whose mode-compatibility prose contradicts dispatch — `--compact` claims text-only while JSON dispatch path exists) and distinct from #270 (whole-flag-omitted: a fully wired flag with zero help line — `--reasoning-effort`, `--base-commit`, `--allow-broad-cwd`, `-p`). #276 catalogues the **listed-flag-incomplete-shape-coverage** sub-shape: the flag IS in help, but the help understates which forms parse, what the value-shape composition rule is, and whether common alias conventions (kebab-case, `=`-form, repetition semantics) apply. The cluster now has 3 members (#263 + #270 + #276) covering three structurally distinct help-vs-dispatch divergence shapes: stale mode (listed, wrong info), omission (unlisted, full info elsewhere), and incomplete shape (listed, partial info).
+
+Distinct from #258 (`--allowedTools ""` empty-value silent-coercion at the CLI parse boundary; #258 is a runtime acceptance-of-malformed-input gap, #276 is a help-text-vs-dispatch-shape-coverage gap on the same flag). Distinct from #267 (`prompt TEXT` greedy-slurp parse-asymmetry; that's a parse-side contract gap on a different surface). Distinct from #265 (`stream-json` output mode absent from BOTH help and dispatch). Distinct from #262 (`--max-turns` flag missing from BOTH help and dispatch).
+
+Discovery-pattern continuation: completes the help-contract-drift cluster's three-sub-axis audit triangle (stale-mode #263 + omitted-flag #270 + incomplete-shape #276), structurally analogous to the turn-budget audit triangle (#262 parse + #264 primitive + #272 spec) — both clusters now occupy three distinct structural slots a single CLI surface can fail at. Extends the **complementary-pinpoint-pair-bundle** discovery-pattern from 5 pair-bundles + 1 three-tuple (turn-budget #262+#264+#272) to 5 pair-bundles + 2 three-tuples (now help-contract-drift #263+#270+#276). The two three-tuples are sister-shaped: each catalogues that audit-completeness for a single user-facing CLI surface requires pinpointing THREE distinct sub-axes rather than two.
+
+Required fix shape: (a) extend the `Flags:` block at `print_help_to:9418` to advertise both casings (`--allowedTools, --allowed-tools TOOLS`) on a single line, matching the OR-pattern in `parse_args:979`; (b) document `=`-form support inline (`--allowedTools=TOOLS, --allowed-tools=TOOLS` accepted) — the existing prose offers no signal that `=`-form parses; (c) document the repetition composition rule explicitly: `repeatable: each occurrence set-unions into the allow-list; pass once per logical group or comma-separate within one occurrence` — eliminating the ambiguity between replace/append/union semantics; (d) add an `Examples:` line showing kebab-case + repetition: `claw --allowed-tools read --allowed-tools glob "summarize Cargo.toml"`; (e) add a help-vs-dispatch alias-coverage regression test that asserts every flag-name-string-literal in `parse_args` (including OR-patterns and `starts_with` prefix arms) appears at least once in the captured `print_help_to` output — mechanically forces help-vs-dispatch alias sync for future flags; (f) extend the test to cover `=`-form variants by asserting that any flag accepting `--foo VAL` form also has its `--foo=VAL` form documented when both arms exist; (g) audit other listed flags for the same incomplete-shape-coverage sub-shape: `--output-format` (does the parser accept `--output-format=json`? — yes per `:889`, but help shows only the space-form), `--permission-mode` (same — `:893` accepts `=`-form, help shows only space-form), `--model` (verify), `--base-commit` after #270 fix lands. Acceptance: `claw --help` discloses every shape variant the parser accepts for every listed flag; the regression test fails when a new alias/equals-form arm is added without a help update; #263 + #270 + #276 together close the help-contract-drift cluster on all three structurally distinct help-vs-dispatch divergence shapes.
+
+**Status:** Open. No source code changed. Filed 2026-04-26 16:14 KST. Branch: feat/jobdori-168c-emission-routing. HEAD: `0240cad` before filing (post-rebase fast-forward onto gaebal-gajae's #275 `claw doctor` provenance fragmentation pinpoint). Cluster delta: help-contract-drift cluster 2→3 (#263 stale-mode-matrix + #270 whole-flag-omitted + #276 listed-flag-incomplete-shape-coverage = three-sub-axis audit triangle complete on the help surface); complementary-pinpoint-pair-bundle discovery-pattern extended to 5 pair-bundles + 2 three-tuples (turn-budget #262+#264+#272 + help-contract-drift #263+#270+#276). Smaller-scope by design (matches #253-#275 context-budget discipline). Sister: #263 (stale-mode-matrix sub-axis), #270 (whole-flag-omitted sub-axis); #276 occupies the third structurally distinct sub-axis (listed-flag-incomplete-shape-coverage). Distinct from #258 (silent-coercion of empty value at parse boundary on the same flag; orthogonal layer — runtime acceptance vs help advertisement). Distinct from turn-budget cluster three-tuple (#262+#264+#272: parse/primitive/spec layers; #263+#270+#276 are three sub-axes within a single layer — the help surface). Concurrent-dogfood-rebase parity will be confirmed local==origin==fork at HEAD `0240cad+#276` after push.