fix(cli): keep root flags aligned

[sj0618]

Summary

• share one root launch flag table between fast help, shell completion, and the launch command
• advertise the working --fork and --worktree flags while removing retired extension/skill flags
• reject unknown root options instead of silently dropping typos, with -- preserving dash-prefixed prompt text
• exercise every advertised flag against its runtime parser in a parity regression test

Verification

• bun --cwd=packages/coding-agent run check
• 169 focused CLI/startup/worktree tests passed
• 24 root-help/parity tests passed again after rebasing onto current upstream/dev

Fixes #4023

[Yeachan-Heo]

Signed CI census review — GJC, 2026-08-09

Disposition: cancelled plan run plus superseded history; bounded hold. Dev CI run 31289298287 was cancelled by sj0618 while Guard released CHANGELOG history was running; the subsequent evidence/aggregate failures are expected fallout from that cancellation, not evidence of a product failure. The head is now two commits behind current dev (bd80cbcf5e257b3fb2701e67bb148990f70f73f2).

Smallest repair lane: rebase codex/fix-cli-root-flag-drift onto current dev and start one fresh Dev CI run. Do not rerun the cancelled historical SHA. No source changes were made from this review worktree.

[Yeachan-Heo]

REQUEST_CHANGES

Red-team review of exact head 7cfc2dc1c9af65f5ff32e248ada4ae134eb982dc against live dev 95c00d09e7f68fc39469c185a4019385f331676b found blocking root-CLI regressions:

1. -wfeature/demo and -w=feature/demo are accepted by parseLaunchWorktreeMode but rejected by the new exact-token check in packages/coding-agent/src/cli/args.ts; add full launch-route coverage.
2. --worktree -- --modle @prompt.md consumes -- in parseLaunchWorktreeMode, so the second parser rejects a literal prompt after worktree preparation. Preserve the delimiter.
3. Retired --extension, --hook, -e, --skills, and related flags are silently ignored; e.g. --extension /tmp/policy.js turns the path into a prompt. Fail explicitly rather than silently changing execution semantics.
4. -- does not protect root --help/--version fast paths or gjc launch -- --help; stop fast-path scans at the delimiter.
5. --worktree is advertised as optional-value behavior but its shared string descriptor renders/generates a required argument.

The PR is also behind live dev (merge base 4474e3f8; current dev is not an ancestor). Its only required check is failing at Affected path validation / Fail closed on producer and live dependency results; I am not attributing that red result to this PR until it is rebased and CI reruns. Linked issue #4023 remains open, so its closure claim is not yet satisfied.

Focused parity/completion tests pass locally (9/9). Broader CLI tests are blocked by the review worktree's missing/mismatched native addon, not counted as PR failures.

— GJC red-team review

[Yeachan-Heo]

OWNER_CONFIRMATION_REQUIRED

Maintainer repair published to the permitted PR branch at 095a8bb574dda3161beb0cb01396d79cd1b80b29, rebased on current dev 95c00d09e7f68fc39469c185a4019385f331676b. It fixes the blocking compact -w forms, preserves -- through worktree routing, rejects retired extension/skill flags, stops help/version fast paths at --, and marks --worktree's completion argument optional.

Local verification: 29 focused CLI/root-flag/completion/worktree tests passed; Biome check passed. Package typecheck is blocked by pre-existing missing generated src/internal-urls/docs-index.generated files; broader CLI checks are unavailable until the native addon is rebuilt. GitHub checks for this new head are still queued/in progress, and the PR remains mergeable_state: unstable; do not merge yet. The prior red affected-path check was not attributed to this PR. Linked issue #4023 remains open pending a green merged resolution.

— GJC red-team review

[Yeachan-Heo]

REQUEST_CHANGES

Fresh red-team QA on repaired head 4a1ece1abf72d62ac46331994203b44c4db90f12 found additional root-routing P1s:

1. gjc --worktree help treats the valid branch name help as root help; --model help, --resume help, and --list-models help have the same value-boundary bug.
2. gjc --worktree stats --version sees the valid option value stats as a subcommand and misses the direct version fast path.
3. gjc -- --fixture demo invokes fixture-report instead of preserving literal prompt text; gjc --model --fixture demo also bypasses missing-value validation.

Also fix the help/completion drift for value-optional --resume and --list-models, and add invocation-level coverage. The preceding repair remains clean locally (29 focused tests and Biome), but this head is not merge-ready.

— GJC red-team review

[Yeachan-Heo]

REQUEST_CHANGES

Final red-team review of 8ddaf7eb found unresolved fast-path precedence defects: gjc --model --fixture demo, gjc --worktree --fixture demo, and gjc -w --fixture demo bypass parser-owned missing-value errors into fixture reporting; fast help/version also fails to skip documented short aliases (-w help, -r help) and parser-accepted @ values (--model @model-ref help). Update the shared fast scanner to resolve long/short aliases with parser-consistent value consumption and decline fixture routing after invalid/missing option values. Add invocation-level coverage.

— GJC red-team review

[Yeachan-Heo]

MERGE_READY

[Yeachan-Heo]

BOUNDED_OWNER_HOLD — exact-head review completed for 00a6c5803c18a3e231d96ae190cea7ab13a896af.

The implementation diff and parser/worktree/completion contracts were inspected; the prior root-routing findings are addressed at this SHA. Automated review history contains no unaddressed automated line comments. The head descends from its recorded PR base 95c00d09e7f68fc39469c185a4019385f331676b, and the completed Dev CI evidence for this SHA reports 21 successful checks (5 explicitly skipped platform/deployment checks).

This is not MERGE_READY / LGTM against live dev: after refresh, origin/dev is 427cef2a82fe15d790b63c9f0872f32c8b632d2d; it is not an ancestor of this head, and GitHub currently reports mergeable=CONFLICTING, mergeStateStatus=DIRTY. The PR is cross-repository, so no branch mutation was performed. Owner action is bounded to rebasing/resolving against the live dev tip and obtaining checks for the resulting exact head; that new SHA requires re-review.

Local mutation-teeth were not run because /tmp is full (448 KiB free) and Git could not materialize an isolated exact-head worktree. This does not alter the merge-conflict hold.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Signed exact-head adversarial review — GJC, 2026-08-09

REQUEST_CHANGES for 3e1ee8b6e20a1f25d36733a6cbd876c8eed73500.

P1 — compact -w launch routing remains broken when a root fast flag follows the compact worktree token. rootFlagDescriptor() in packages/coding-agent/src/cli.ts:224-230 recognizes only an exact short token (-w); it does not recognize parser-accepted -wfoo or -w=foo. Consequently hasRootFastFlag() at :254-261 does not consume the compact token/value. Because runCli() evaluates root help/version at :467-480 before default-launch/worktree routing, gjc -wfeature/demo help renders root help instead of launching the feature/demo worktree with prompt help; gjc -w=feature/demo --version similarly takes the root version fast path. This reopens the historical combined-worktree-token launch-routing blocker.

cli-root-flags.test.ts currently proves parseArgs() and parseLaunchWorktreeMode() separately, but not this pre-routing runCli() behavior. Extend the shared fast scanner to consume both compact forms parser/worktree routing accepts and add invocation-level help/version regression coverage.

The delimiter preservation, retired extension/hook/skills rejection, help/version delimiter boundary, and optional-value completion/help descriptor changes were inspected and are present. GitHub reports this exact head CLEAN/MERGEABLE with 22 successful and no pending/failed checks. Current dev #4103 overlaps only packages/coding-agent/CHANGELOG.md and merges cleanly; that does not repair this defect.

Contributor sj0618 has read permission and the head is an external fork. Per external-PR policy, no contributor-branch mutation was made from this review; repair and re-review are required on a new exact head.

[Yeachan-Heo]

Signed exact-head review — GJC, 2026-08-09

MERGE_READY for c2204426828093003382d1a180537e69e46bf569.

The compact worktree repair is rebased on current dev a5f8f34d1d54bb0537856cccb354eaefd9fd25b2. The shared root fast-path scanner now treats exactly the selector forms accepted by launch worktree routing (--worktree, -w, --worktree=…, -w=…, and -w…) as a launch boundary. This prevents root help/version from preempting compact worktree routing without consuming unrelated short flags.

Invocation-level coverage verifies both compact forms through launch help and command version behavior, preserves a literal delimiter into worktree validation, and retains root version behavior for an unrelated short flag. The prior exact-head blockers remain addressed: compact forms, delimiter preservation, retired extension/hook/skills rejection, delimiter-aware help/version, and optional-value help/completion parity.

Exact-head Dev CI 31327820051 is terminal: 22 successful checks, 0 failures/pending; five platform/deployment checks are intentionally skipped. It includes CLI command-surface/root-flag/worktree/completion/utils tests, coding-agent check/type build, CLI smoke, install methods, native build, Darwin tab-worker smoke, virtual integration, evidence aggregation, and state gates. No automated review comments were posted for this head. GitHub reports CLEAN and mergeable.

External contributor branch repair was limited to the permitted maintainer-modifiable PR branch. No merge was performed from this session.

[Yeachan-Heo]

Signed exact-base refresh review — GJC, 2026-08-09

MERGE_READY for 8c0858faecebbad1f01b831646e164b7b0a3ff78.

This is the existing maintainer-modifiable external branch, rebased without source conflict onto current dev 2e8965065a56d692b7401357e9ad26dd39a724c1 (#4110). The #4110 GC changes have no source-path overlap with the root CLI implementation or its invocation tests. Remote ancestry is proven; GitHub reports this exact head CLEAN and mergeable.

The compact -w/-w= fast-path repair and all prior #4023 contracts remain intact. Exact-head Dev CI 31329534863 is terminal: 22 successful checks, 0 failures/pending, and 5 intentional platform/deployment skips. It includes CLI command-surface/root-flag/worktree/completion/utils coverage, coding-agent check/type build, CLI smoke, install methods, native build, Darwin tab-worker smoke, virtual integration, evidence aggregation, and state gates. No automated line comments or final-head review findings remain.

No duplicate PR or merge was created from this session.