Retire the curl-style @file/@- sigil on finish --summary; keep --summary-file #794

New issue

Open

opened 2026-10-16 19:17:26 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-16 19:17:26 +00:00

Owner

finish --summary reads a summary from a file two ways today, and the curl-style @ sigil is the redundant one. I am dropping it and keeping the gh-style --summary-file <path>, with --summary-file - for stdin, as the one file form on the CLI. That matches --body-file on pr and issue, and it matches gh.

Why

finish reads a summary from a file two ways today:

--summary @file and --summary @-: the curl sigil (internal/cmd/workflow/finish.go:139, expanded at finish.go:208-227).
--summary-file <path> and --summary-file -: a plain file flag (finish.go:140, finish.go:231-244).

--summary-file already does the same job on the same command, so the @ sigil is redundant. The @ form is a curl idiom (curl -d @file, -F field=@file). madtea already uses it in the one place it fits: the raw api passthrough (internal/service/api/body.go, -F key=@file). For a first-class text flag the convention is a dedicated --*-file flag, which pr and issue (--body-file) and finish (--summary-file) already follow. So finish --summary @file is the only spot that puts the sigil on a first-class flag that has a gh-style twin.

Change

--summary no longer reads a file. A --summary value that would have been read as a file fails loud with a redirect to --summary-file, in the actionable-redirect style of the removed --all/-A staging flags (finishRemovedStagingFlagHint, finish.go:169). The error names --summary-file <path> and --summary-file - for stdin, and it never changes behavior silently.
--summary-file and its - stdin form are unchanged.
The @file and @- text leaves the --summary flag help (finish.go:139) and the help examples (finish.go:131-132).

This is CLI-only. The MCP surface already refuses a file sigil (#792). Removing the sigil on the CLI surface too leaves one rule: a --*-file flag for first-class commands, and @ only in the raw api passthrough.

Edge

Today --summary reads any value that starts with @ as a file, so a summary that starts with @, such as @reviewer please look, is already read wrong. The redirect error replaces that, and a summary that really starts with @ goes through --summary-file or stdin.

Breaking

Removing a flag behavior is a breaking change, so it waits for the next breaking release and the release notes name it. Update docs/COMPARISON.md, the gh/tea matrix, and docs/COMPAT.md if a caveat applies.

Acceptance

finish --summary @summary.md no longer reads the file; it errors and the message names --summary-file. A test covers the error and the redirect text.
finish --summary @- errors with the same redirect, naming --summary-file -.
finish --summary-file summary.md and finish --summary-file - still read the file and stdin.
The --summary help and the finish examples no longer mention @file or @-.
docs/COMPARISON.md reflects the removed flag form.

`finish --summary` reads a summary from a file two ways today, and the curl-style `@` sigil is the redundant one. I am dropping it and keeping the gh-style `--summary-file <path>`, with `--summary-file -` for stdin, as the one file form on the CLI. That matches `--body-file` on `pr` and `issue`, and it matches gh. ## Why `finish` reads a summary from a file two ways today: - `--summary @file` and `--summary @-`: the curl sigil (`internal/cmd/workflow/finish.go:139`, expanded at `finish.go:208-227`). - `--summary-file <path>` and `--summary-file -`: a plain file flag (`finish.go:140`, `finish.go:231-244`). `--summary-file` already does the same job on the same command, so the `@` sigil is redundant. The `@` form is a curl idiom (`curl -d @file`, `-F field=@file`). madtea already uses it in the one place it fits: the raw `api` passthrough (`internal/service/api/body.go`, `-F key=@file`). For a first-class text flag the convention is a dedicated `--*-file` flag, which `pr` and `issue` (`--body-file`) and `finish` (`--summary-file`) already follow. So `finish --summary @file` is the only spot that puts the sigil on a first-class flag that has a gh-style twin. ## Change - `--summary` no longer reads a file. A `--summary` value that would have been read as a file fails loud with a redirect to `--summary-file`, in the actionable-redirect style of the removed `--all`/`-A` staging flags (`finishRemovedStagingFlagHint`, `finish.go:169`). The error names `--summary-file <path>` and `--summary-file -` for stdin, and it never changes behavior silently. - `--summary-file` and its `-` stdin form are unchanged. - The `@file` and `@-` text leaves the `--summary` flag help (`finish.go:139`) and the help examples (`finish.go:131-132`). This is CLI-only. The MCP surface already refuses a file sigil (#792). Removing the sigil on the CLI surface too leaves one rule: a `--*-file` flag for first-class commands, and `@` only in the raw `api` passthrough. ## Edge Today `--summary` reads any value that starts with `@` as a file, so a summary that starts with `@`, such as `@reviewer please look`, is already read wrong. The redirect error replaces that, and a summary that really starts with `@` goes through `--summary-file` or stdin. ## Breaking Removing a flag behavior is a breaking change, so it waits for the next breaking release and the release notes name it. Update `docs/COMPARISON.md`, the gh/tea matrix, and `docs/COMPAT.md` if a caveat applies. ## Acceptance - `finish --summary @summary.md` no longer reads the file; it errors and the message names `--summary-file`. A test covers the error and the redirect text. - `finish --summary @-` errors with the same redirect, naming `--summary-file -`. - `finish --summary-file summary.md` and `finish --summary-file -` still read the file and stdin. - The `--summary` help and the finish examples no longer mention `@file` or `@-`. - `docs/COMPARISON.md` reflects the removed flag form.

hexajon added the

breaking

label

2026-10-16 19:17:26 +00:00

No milestone

No project

No assignees

1 participant

Notifications

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

sixfold-space/madtea#794

No description provided.

Rows
Columns