Correct the --board scope and document the surface gate - #198
Conversation
--board was listed in the global config-precedence ladder alongside --token, --profile and --api-url. Those three are registered on rootCmd as persistent flags; --board is not registered globally at all. Running `fizzy --board X` exits with "unknown flag: --board", which is how this was confirmed rather than by reading the registration. The webhook subcommands declare their own --board, and elsewhere the board is resolved from FIZZY_BOARD or config. FIZZY_BOARD stays in the ladder -- that one is real, handled in internal/config/config.go. The same wrong claim appears in that file's Load() doc comment; correcting source comments is left out of a documentation change. Two gates were undocumented. `make check` is the local gate and notably does not cover the CLI surface. SURFACE.txt is a 145 KB golden snapshot of every command, flag and help string; TestSurfaceSnapshot compares against it and CI runs it through `go test ./...`, so any surface change fails the build until `make surface-snapshot` is rerun and the result committed. Someone adding a flag would otherwise meet this as a mysterious CI failure.
github-actions
Bot
added
the
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 94a3a22a79
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Updates contributor-facing documentation to reflect the actual CLI/config behavior around --board, and to document the CLI surface snapshot gate so contributors understand and can resolve related CI failures.
Changes:
- Removes
--boardfrom the list of global CLI flags in the config precedence ladder. - Adds clarification that
--boardis only declared on webhook subcommands; elsewhere board selection comes fromFIZZY_BOARD/ config viarequireBoard. - Documents the
SURFACE.txt/TestSurfaceSnapshotsurface gate and how to runmake surface-snapshot/make surface-check.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…gate the surface Two of my own claims were wrong. --board is not limited to the webhook subcommands. Around nineteen commands declare it, across the activity, board, card, column and webhook groups (card list, card create, column create, board accesses, board closed and so on). My earlier grep was truncated and only showed webhook.go. What stays true is that it is not global: `fizzy --board X card list` still fails with unknown flag, while `fizzy card list --board X` works. `make check` does run the surface gate. There is no surface-check in its dependency list, but race-test is `go test -race -count=1 ./internal/...`, which includes internal/commands.TestSurfaceSnapshot. Saying the gate was absent would have left someone puzzled by exactly the failure this section exists to explain.
github-actions
Bot
added
bug
There was a problem hiding this comment.
🟢 Ready to approve
The changes are documentation-only and align with the repo’s actual flag registration and Makefile/test gates.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 304b6dac10
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ctural Two more overstatements. Saying board-taking commands fall back via requireBoard was one rule for three behaviours: card create, column create and the webhook commands do call requireBoard and error when nothing is set; card list uses defaultBoard, which falls back but never errors; and activity list has no fallback at all -- it appends the query parameter only when the flag is given, so FIZZY_BOARD does nothing there. SURFACE.txt holds only CMD, SUB, FLAG and ARG records. It carries no Short or Long help text, so claiming the snapshot covers help strings promised a gate that does not exist -- reword help and the test stays green.
There was a problem hiding this comment.
🟢 Ready to approve
Documentation changes align with the current Makefile targets and command/flag behavior (no code changes or risk introduced).
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc96065674
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The Required category listed three entries and covers seventeen. Alongside card create, column create and the webhook subcommands, requireBoard is called by board accesses/closed/postponed/stream and column list/show/update/delete (board.go:432,490,564,638 and column.go:29,91,200,257). Eight commands that error without a board were left unclassified, which is the case someone consults this section to resolve.
There was a problem hiding this comment.
🟢 Ready to approve
Documentation-only update with accurate alignment to existing Make targets and surface snapshot tests, with only a minor wording nit noted.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
Comments suppressed due to low confidence (1)
AGENTS.md:91
- The inline example error for
fizzy --board X ...is missing the flag name; Cobra/pflag reportsunknown flag: --board, which is helpful for readers troubleshooting this exact case.
**`--board` is not a global flag.** `fizzy --board X ...` fails with `unknown flag`.
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 40255307ee
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Removing --board from the CLI-flags layer overcorrected. defaultBoard returns its argument before consulting effectiveConfig().Board (root.go:588-592), so on the nineteen commands that accept it the flag does outrank FIZZY_BOARD and every configured default. Dropping it left the ladder inaccurate for card list, card create and the rest. It is back in layer 1, marked as command-scoped, with the detail below now saying explicitly where it sits relative to env and config.
There was a problem hiding this comment.
🟢 Ready to approve
Documentation changes are consistent with the current flag registrations and the actual make check/CI test commands that run the surface snapshot test.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
|
@codex review |
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
--board was listed in the global config-precedence ladder alongside --token,
--profile and --api-url. Those three are registered on rootCmd as persistent
flags; --board is not registered globally at all. Running
fizzy --board Xexits with "unknown flag: --board", which is how this was confirmed rather
than by reading the registration. The webhook subcommands declare their own
--board, and elsewhere the board is resolved from FIZZY_BOARD or config.
FIZZY_BOARD stays in the ladder -- that one is real, handled in
internal/config/config.go. The same wrong claim appears in that file's Load()
doc comment; correcting source comments is left out of a documentation change.
Two gates were undocumented.
make checkis the local gate and notably doesnot cover the CLI surface. SURFACE.txt is a 145 KB golden snapshot of every
command, flag and help string; TestSurfaceSnapshot compares against it and CI
runs it through
go test ./..., so any surface change fails the build untilmake surface-snapshotis rerun and the result committed. Someone adding aflag would otherwise meet this as a mysterious CI failure.
Checked against
masterat 3ac1de7.Summary by cubic
Fixes config docs:
--boardis per-command (not global) across activity/board/card/column/webhook, and on those commands it ranks aboveFIZZY_BOARDand config in precedence. Clarifies board resolution (lists all 17requireBoardcommands; notesdefaultBoardoncard list;activity listhas no fallback) and documents the surface gate:make checkruns the snapshot test;SURFACE.txtis structural only; refresh withmake surface-snapshotormake surface-checkwhen the CLI surface changes.Written for commit 2129405. Summary will update on new commits.