cli: refuse every global flag no verb can honor #151

Merged

natsukium merged 3 commits from docs/global-flag-matrix-136 into main 2026-09-06 02:43:43 +09:00

Conversation 0 Commits 3 Files changed 8 +476 -94

natsukium commented 2026-09-06 02:35:22 +09:00

Owner

Copy link

Fixes #136.

Three verb forms silently dropped a global flag: felis --version answers
before dispatch and ignored all four, while completions and __mangen
ignored the carrier flags (--host, --socket, --ssh-arg). They now
refuse what they cannot honor, exit 2, like every other verb that neither
reads nor forwards a global. The per-arm checks move into
verb_refusing_carrier, a twin of verb_reading_no_config; both are
exhaustive over Cmd, so a new verb cannot land without deciding its cells,
and a table-driven test walks every verb form against every global.

Doc cascade: docs/reference/cli.md gains a placement matrix stating every
verb/flag cell (forwarded, read, dials, refused) plus the frontend and
completions paragraphs that were only implicit; docs/reference/control-surfaces.md
points at the matrix; CHANGELOG.md records the three newly refused forms;
skills/felis/SKILL.md records that felis --version refuses the globals.

Verified: just check green (fmt, clippy, nextest, deny, proto-compat);
reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Deferred

• A docs/explanation twin for the placement matrix — the plan named only the
  two reference pages; the matrix is normative lookup material with no new
  argument, so doc-cascade's default-to-no-record gate applies.
• test: the new matrix test collapses three distinct global flags into one
  carrier bucket — the per-flag distinction for __complete-sessions
  (--socket dials vs --host/--ssh-arg give no candidates) is already
  pinned end-to-end by pre-existing, untouched tests in cli_sessions.rs;
  refactoring the new table-driven unit test's granularity goes beyond issue
  #136's criteria, since the real behavior is not unguarded.
• test: the frontend row in the matrix table test never parses a global flag
  combined with the verb — the finding's own verification shows that parse +
  refuse combination is already pinned end-to-end in cli_sessions.rs,
  matching the round-1 precedent where a sibling asymmetry finding was
  deferred on the same grounds; fixing it would duplicate coverage rather
  than close a gap.

Fixes #136. Three verb forms silently dropped a global flag: `felis --version` answers before dispatch and ignored all four, while `completions` and `__mangen` ignored the carrier flags (`--host`, `--socket`, `--ssh-arg`). They now refuse what they cannot honor, exit `2`, like every other verb that neither reads nor forwards a global. The per-arm checks move into `verb_refusing_carrier`, a twin of `verb_reading_no_config`; both are exhaustive over `Cmd`, so a new verb cannot land without deciding its cells, and a table-driven test walks every verb form against every global. Doc cascade: `docs/reference/cli.md` gains a placement matrix stating every verb/flag cell (forwarded, read, dials, refused) plus the `frontend` and `completions` paragraphs that were only implicit; `docs/reference/control-surfaces.md` points at the matrix; `CHANGELOG.md` records the three newly refused forms; `skills/felis/SKILL.md` records that `felis --version` refuses the globals. Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Deferred - A docs/explanation twin for the placement matrix — the plan named only the two reference pages; the matrix is normative lookup material with no new argument, so doc-cascade's default-to-no-record gate applies. - test: the new matrix test collapses three distinct global flags into one carrier bucket — the per-flag distinction for `__complete-sessions` (`--socket` dials vs `--host`/`--ssh-arg` give no candidates) is already pinned end-to-end by pre-existing, untouched tests in `cli_sessions.rs`; refactoring the new table-driven unit test's granularity goes beyond issue #136's criteria, since the real behavior is not unguarded. - test: the frontend row in the matrix table test never parses a global flag combined with the verb — the finding's own verification shows that parse + refuse combination is already pinned end-to-end in `cli_sessions.rs`, matching the round-1 precedent where a sibling asymmetry finding was deferred on the same grounds; fixing it would duplicate coverage rather than close a gap.

natsukium added 3 commits 2026-09-06 02:35:22 +09:00

cli: refuse every global flag no verb can honor ... dd766dbdb5

Three forms dropped a global on the floor: `felis --version` answers
before any dispatch and ignored all four, while `completions` and
`__mangen` ignored the carrier. A silently dropped flag leaves a user
believing felis honored it, which is why `--config` and the carrier are
refused elsewhere already; these three now refuse for the same reason.

The per-arm carrier checks move into `verb_refusing_carrier`, a twin of
`verb_reading_no_config`. Both are exhaustive over `Cmd`, so a new verb
cannot be added without deciding its cells, and the matrix test walks
every verb form against every global.

`--version`'s own coverage test named its socket with `--socket`, which
is now refused beside the flag; it names it through `FELIS_SOCKET`
instead, since the test is about what the report touches.

Refs #136

docs: freeze the global-flag placement matrix per verb ... 86262dcd74

"Global options" stated the four flags but not, per verb, whether one
is forwarded, read here, dialed, or refused, so a reader could only
infer the answer from the paragraphs that happened to mention it. The
matrix states every cell, which is what makes "no verb ignores a
global" checkable rather than a claim.

Refs #136

skills: record that felis --version refuses the globals ... 3279fd8506

The product-shipped skill told agents the flag dials nothing but not
that a global beside it is now an exit 2, so a scripted
`felis --socket … --version` would look like a felis bug.

Refs #136

natsukium merged commit 3279fd8506 into main 2026-09-06 02:43:43 +09:00

natsukium deleted branch docs/global-flag-matrix-136 2026-09-06 02:43:43 +09:00

natsukium referenced this pull request 2026-09-08 01:39:59 +09:00

[v0.1/CLI Args Review] CLI 引数のリリース前設計レビュー #55

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!151

No description provided.