From 94a3a22a7956abfab2c37d7d404be3e80906f8a0 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 29 Jul 2026 02:03:10 -0700 Subject: [PATCH 1/5] Correct the --board scope and document the surface gate --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. --- AGENTS.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a49cc735..ce9bae00 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,7 +80,7 @@ E2E environment variables: ## Configuration The CLI reads config from multiple sources with this priority: -1. CLI flags (`--token`, `--profile`, `--api-url`, `--board`) +1. CLI flags (`--token`, `--profile`, `--api-url`) 2. Environment variables (`FIZZY_TOKEN`, `FIZZY_PROFILE`, `FIZZY_API_URL`, `FIZZY_BOARD`) 3. Named profile settings (base URL, board from `~/.config/fizzy/config.json`) 4. Local project config (`.fizzy.yaml`) @@ -88,6 +88,21 @@ The CLI reads config from multiple sources with this priority: `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`. +**`--board` is not a global flag.** `fizzy --board X ...` fails with `unknown flag`. +The webhook subcommands declare their own `--board`; everywhere else the board comes +from `FIZZY_BOARD` or the `board` key in config, resolved by `requireBoard`. + ## Authentication Token-based via personal access tokens. Run `fizzy setup` for interactive configuration or `fizzy auth login` to save a token directly. + +## Checks + +`make check` runs `fmt-check vet lint tidy-check race-test`. It does **not** include the +CLI surface gate. + +`SURFACE.txt` at the repository root is a golden snapshot of every command, flag and +help string. `TestSurfaceSnapshot` compares against it, and CI's `go test ./...` runs +that test, so any change to the CLI surface fails the build until the snapshot is +refreshed. Regenerate with `make surface-snapshot` (or check it alone with +`make surface-check`) and commit the result in the same PR as the surface change. From 304b6dac108e9b69b385b3658209b6ba6e6bec00 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 29 Jul 2026 11:21:02 -0700 Subject: [PATCH 2/5] Review fix: --board is declared far more widely, and make check does 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. --- AGENTS.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce9bae00..8038baf2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -89,8 +89,10 @@ The CLI reads config from multiple sources with this priority: `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`. **`--board` is not a global flag.** `fizzy --board X ...` fails with `unknown flag`. -The webhook subcommands declare their own `--board`; everywhere else the board comes -from `FIZZY_BOARD` or the `board` key in config, resolved by `requireBoard`. +It is declared per-command, by around nineteen of them across the activity, board, +card, column and webhook groups — so `fizzy card list --board X` works while +`fizzy --board X card list` does not. Commands that take a board but were not given +one fall back to `FIZZY_BOARD` or the `board` key in config, via `requireBoard`. ## Authentication @@ -98,11 +100,13 @@ Token-based via personal access tokens. Run `fizzy setup` for interactive config ## Checks -`make check` runs `fmt-check vet lint tidy-check race-test`. It does **not** include the -CLI surface gate. +`make check` runs `fmt-check vet lint tidy-check race-test`. There is no `surface-check` +in that list, but the surface gate still runs: `race-test` is +`go test -race -count=1 ./internal/...`, which includes +`internal/commands.TestSurfaceSnapshot`. `SURFACE.txt` at the repository root is a golden snapshot of every command, flag and -help string. `TestSurfaceSnapshot` compares against it, and CI's `go test ./...` runs -that test, so any change to the CLI surface fails the build until the snapshot is -refreshed. Regenerate with `make surface-snapshot` (or check it alone with -`make surface-check`) and commit the result in the same PR as the surface change. +help string, and that test compares against it. So a change to the CLI surface fails +both `make check` and CI until the snapshot is refreshed. Regenerate with +`make surface-snapshot` (or run the gate alone with `make surface-check`) and commit +the result in the same PR as the surface change. From dc960656740f1a4a2a2a2266cc07d7af62ebc4ef Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 29 Jul 2026 11:25:39 -0700 Subject: [PATCH 3/5] Review fix: board fallback varies by command, and SURFACE.txt is structural 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. --- AGENTS.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8038baf2..5f3373d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,8 +91,14 @@ The CLI reads config from multiple sources with this priority: **`--board` is not a global flag.** `fizzy --board X ...` fails with `unknown flag`. It is declared per-command, by around nineteen of them across the activity, board, card, column and webhook groups — so `fizzy card list --board X` works while -`fizzy --board X card list` does not. Commands that take a board but were not given -one fall back to `FIZZY_BOARD` or the `board` key in config, via `requireBoard`. +`fizzy --board X card list` does not. What happens when you omit it varies by command: + +- **Required** (`card create`, `column create`, the webhook commands): `requireBoard` + falls back to `FIZZY_BOARD` or the `board` key in config, and errors if neither is set. +- **Defaulted** (`card list`): `defaultBoard` applies the same fallback but does not + error — an empty board just goes unset. +- **Optional filter** (`activity list`): no fallback at all. The board query parameter is + added only when the flag is given, so `FIZZY_BOARD` has no effect there. ## Authentication @@ -105,8 +111,10 @@ in that list, but the surface gate still runs: `race-test` is `go test -race -count=1 ./internal/...`, which includes `internal/commands.TestSurfaceSnapshot`. -`SURFACE.txt` at the repository root is a golden snapshot of every command, flag and -help string, and that test compares against it. So a change to the CLI surface fails +`SURFACE.txt` at the repository root is a golden snapshot of the CLI's *structure* -- +`CMD`, `SUB`, `FLAG` and `ARG` records -- and that test compares against it. It does not +capture `Short`/`Long` help text or flag descriptions, so rewording help leaves the +snapshot green. So a change to the CLI surface fails both `make check` and CI until the snapshot is refreshed. Regenerate with `make surface-snapshot` (or run the gate alone with `make surface-check`) and commit the result in the same PR as the surface change. From 40255307eec6d2230293389053e01846394a48e2 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 29 Jul 2026 12:06:15 -0700 Subject: [PATCH 4/5] Review fix: name every command that requires a board 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. --- AGENTS.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5f3373d7..d428b409 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,12 +93,15 @@ It is declared per-command, by around nineteen of them across the activity, boar card, column and webhook groups — so `fizzy card list --board X` works while `fizzy --board X card list` does not. What happens when you omit it varies by command: -- **Required** (`card create`, `column create`, the webhook commands): `requireBoard` - falls back to `FIZZY_BOARD` or the `board` key in config, and errors if neither is set. -- **Defaulted** (`card list`): `defaultBoard` applies the same fallback but does not - error — an empty board just goes unset. -- **Optional filter** (`activity list`): no fallback at all. The board query parameter is - added only when the flag is given, so `FIZZY_BOARD` has no effect there. +- **Required** — `requireBoard` falls back to `FIZZY_BOARD` or the `board` key in + config, and errors if neither is set. Seventeen commands: `board accesses`, + `board closed`, `board postponed`, `board stream`, `card create`, `column list`, + `column show`, `column create`, `column update`, `column delete`, and all seven + `webhook` subcommands. +- **Defaulted** — `card list` uses `defaultBoard`, the same fallback without the error; + an empty board just goes unset. +- **Optional filter** — `activity list` has no fallback at all. The board query + parameter is added only when the flag is given, so `FIZZY_BOARD` has no effect there. ## Authentication From 2129405123647c1d1a4f9c8a2a7d7095f10c1a8a Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Wed, 29 Jul 2026 12:16:06 -0700 Subject: [PATCH 5/5] Review fix: --board belongs in the precedence ladder, scoped 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. --- AGENTS.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d428b409..f6292e1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,7 +80,8 @@ E2E environment variables: ## Configuration The CLI reads config from multiple sources with this priority: -1. CLI flags (`--token`, `--profile`, `--api-url`) +1. CLI flags (`--token`, `--profile`, `--api-url`, and `--board` on the commands that + accept it — see below; a given `--board` beats every configured default) 2. Environment variables (`FIZZY_TOKEN`, `FIZZY_PROFILE`, `FIZZY_API_URL`, `FIZZY_BOARD`) 3. Named profile settings (base URL, board from `~/.config/fizzy/config.json`) 4. Local project config (`.fizzy.yaml`) @@ -88,10 +89,12 @@ The CLI reads config from multiple sources with this priority: `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`. -**`--board` is not a global flag.** `fizzy --board X ...` fails with `unknown flag`. -It is declared per-command, by around nineteen of them across the activity, board, -card, column and webhook groups — so `fizzy card list --board X` works while -`fizzy --board X card list` does not. What happens when you omit it varies by command: +**`--board` is command-scoped, not global.** `fizzy --board X ...` fails with +`unknown flag`; it is declared per-command, by nineteen of them across the activity, +board, card, column and webhook groups. So `fizzy card list --board X` works while +`fizzy --board X card list` does not. Where it is accepted it sits at the top of the +ladder above: `defaultBoard` returns the flag value before consulting `FIZZY_BOARD` or +config. What happens when you omit it varies by command: - **Required** — `requireBoard` falls back to `FIZZY_BOARD` or the `board` key in config, and errors if neither is set. Seventeen commands: `board accesses`,