canon-ai 3.12.0 → 3.14.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@
 
 ## [Unreleased]
 
+## [3.14.0] — 2026-10-25
+
+### Added
+
+- **`canon completion` prints a shell completion script for bash, zsh, fish, and tcsh.** Add the line shown by `canon completion --help` to your shell startup file, and Tab completes commands, `task` subcommands, flags, phase names, review verdicts, task sizes, and task ids. Task ids complete from any directory in the repo, including a linked worktree, and completion never offers a flag canon would reject.
+- **Every canon command answers `--help` in any position.** `canon run foo --help`, `canon task phase --help`, and the rest print that command's own usage to stdout and exit 0 without running anything; `canon task --help` lists all nine subcommands. Help wins over other argument errors.
+
+### Changed
+
+- **`canon run --reroute` works once implementation has begun.** A task can now be rerouted while implement is in progress or blocked, while code review is blocked at the loop limit, or after a review round or pre-flight rejection in the current loop. A task at implement with no review activity is still refused. In a bundle, a task at implement with no review activity is admitted alongside a qualifying task on the same branch, and a reroute that names only part of a shared-branch bundle is refused before anything changes, with the full command to run. The reroute prompts treat the prior round as possibly partial and pick up unfinished work along with the amendment, and the loop-limit message names the amend-and-reroute path.
+- **`--pr` and `--push` push canon's own scaffold commits to the base branch.** A PR no longer stops at the base-divergence check until you push the base by hand. canon pushes only commits made of task scaffolds and pipeline telemetry, all or nothing; any other unpushed base commit still blocks. A base branch that exists only locally is created on origin only when every commit on it is canon's own.
+- **`canon --help` is a short summary, and unknown flags are rejected on every command.** The summary lists one line per command and points to `canon <command> --help`. An unknown flag names itself and points to that command's help; `init`, `doctor`, and `stop` used to ignore unknown flags and now exit 1. `canon update` and `canon upgrade` reject stray words.
+- **`canon task` requires a git repository.** Outside one, every `canon task` subcommand exits 1 with a single error naming the requirement and creates nothing. Before, `canon task new` succeeded outside git and later commands failed.
+- **QA's "Human reroute?" quality-log column counts a human reroute at any phase**, not only a rejection at human review. Existing projects keep their old column description in `docs/task-quality-log.md`; edit that line if you want it to match.
+
+### Fixed
+
+- **`canon task` and `canon doctor` work from any subdirectory of a repository.** They read `tasks/` and `.canon/templates` from the repository root instead of the current directory, so `canon task list` in a subdirectory no longer prints "No tasks found." `canon task new` run inside a task's worktree creates the task in the main checkout, based on the main checkout's branch. `canon task list` no longer shows directories under `tasks/` whose names aren't valid task ids.
+- **A rejected base push names the cause.** When origin's base has moved ahead, the message tells you to rebase the local base instead of suggesting branch protection. `--full-send` warns and skips the base push on a fetch failure instead of stopping.
+- **`canon upgrade` with a bad argument prints a one-line error** instead of a stack trace, and `canon watch --help` prints its usage on separate lines.
+
+## [3.13.0] — 2026-10-23
+
+### Added
+
+- **Bug-fix tasks record red-first evidence in the handoff, and code review checks for it.** The handoff template has a Red-First Evidence section with one row per red-first acceptance criterion: the test command, the commit the pre-fix code was at, the failure it showed there, and the post-fix result. A `[wrong-premise]` blocker can stand in when the test cannot be made to fail for the reason the spec states. The implement prompts point at the section and say which pre-fix state to run against. The anchored code-review lens flags a red-first criterion with no pre-fix run as a spec-compliance gap, and a revision round can close the gap by running the test against the pre-fix commit without redoing the fix.
+- **Claude sub-agents get their own metrics rows.** When a pipeline phase's Claude session spawns sub-agents, each top-level sub-agent gets a row with Agent `claude:<agent type>`, its duration, and its own cumulative tokens. For `code_review` that separates the anchored and cold reviewers from the foreman. The session's own row is unchanged.
+
+### Fixed
+
+- **The spec_gap halt's fix hint names the amendment heading the next `--reroute` requires.** After a task's first reroute, it says `## Amendment Round N` instead of a bare `## Amendment` that `--reroute` refuses.
+- **Implement auto-commit no longer fails on a gitignored generated file listed beside its generator.** The ignored file is not passed to `git add`. If staging fails partway, the index is restored to its state before the attempt.
+- **A handoff row for one of the task's own artifacts no longer fails the coverage checks** when the pipeline rewrote it identical to the base. Another bundle member's artifact is still rejected.
+- **The scaffold commit no longer fails when a telemetry file was removed with `git rm`**, and a committed rename's old path counts as deletion evidence at implement close.
+- **The base-divergence and orphaned-branch messages name the actual branch** instead of a literal `<base>`, quoted when the name needs it, so the printed `git push` and `gh pr create` commands can be pasted as is.
+
 ## [3.12.0] — 2026-10-21
 
 ### Added

package/README.md

@@ -94,7 +94,7 @@ A single command runs a task end-to-end:
 canon run <task-id>
 ```
 
-`--step --expect <phase>` runs one phase with a phase-mismatch guard. `--pr` pushes and opens a draft PR at `human_review`. `--ship` runs *after* PR approval — it squash-merges the PR, deletes the branch, tears down the worktree, archives the task, and pulls the base branch (don't merge the PR manually first). `--reroute` resets a task from any phase reached after a completed `implement` round (`code_review`, `qa`, or `human_review`) back into the post-review fix path — full-tier tasks (S/M/L/XL or delicate) re-enter at `spec_review`, fast-tier tasks (XS) re-enter at `implement`. `--full-send` skips the spec gate and auto-opens a draft PR on clean QA. `--dry-run` prints planned phases without spawning agents.
+`--step --expect <phase>` runs one phase with a phase-mismatch guard. `--pr` pushes and opens a draft PR at `human_review`. `--ship` runs *after* PR approval — it squash-merges the PR, deletes the branch, tears down the worktree, archives the task, and pulls the base branch (don't merge the PR manually first). `--reroute` resets a task once implementation has begun: current phase `code_review`, `qa`, or `human_review` (any status or verdict), or `implement` when implement is in progress or blocked, code review is blocked, or code review already ran in the current loop (a review round or a pre-flight rejection). In a bundle, a sibling at implement pending with no current-loop activity is admitted alongside a task that qualifies when both belong to the same non-empty task branch. Full-tier tasks (S/M/L/XL or delicate) re-enter at `spec_review`, fast-tier tasks (XS) re-enter at `implement`. `--full-send` skips the spec gate and auto-opens a draft PR on clean QA. `--dry-run` prints planned phases without spawning agents.
 
 Multiple task IDs in one invocation activates **bundle mode** — `canon run id1 id2 id3` runs all tasks together per phase under a single review loop with one commit history and one PR. Any full-tier task in the bundle promotes the entire bundle to full tier.
 
@@ -124,6 +124,15 @@ npm install -g --install-links github:tstraub89/canon-ai
 
 > **Updating.** Once installed, use `canon update` rather than re-running `npm install` by hand — it resolves the exact install this binary is running from and installs the latest release from the npm registry by default. Use `--channel main` or `--ref <ref|sha>` for a GitHub development commit; each update records what it installed in `provenance.json` under `.canon` for future tooling to read. A project-local update pins the exact version (`--save-exact`); a global update has no manifest to pin.
 
+### Shell completion
+
+Add the line for your shell to its startup file. For zsh, put the line after `compinit`.
+
+- bash (`~/.bashrc`): `eval "$(canon completion bash)"`
+- zsh (`~/.zshrc`, after `compinit`): `eval "$(canon completion zsh)"`
+- fish (`~/.config/fish/config.fish`): `canon completion fish | source`
+- tcsh: run `canon completion tcsh > ~/.canon-completion.tcsh` once, then add `source ~/.canon-completion.tcsh` to `~/.tcshrc`. A multi-line script does not survive backtick `eval`.
+
 ### Set up in a repo
 
 ```bash
@@ -257,7 +266,7 @@ Pipeline sessions are headless, so nobody is at the keyboard to answer a permiss
 - **Worktrees separate branch state by convention, not by enforcement.** Each task, or each bundle when you pass several task ids together, gets its own worktree and branch, and the pipeline's dirty-tree gates inspect the active worktree at phase boundaries. But Claude sessions are also given the main checkout via `--add-dir` and run with permissions skipped, so nothing stops a session from writing there, and an unrelated file dropped into the main checkout is not something those gates look for; tasks with `worktree: false` run in the main checkout outright. Validation commands run with your normal privileges.
 - **Budget caps bound cost, not access.** Each headless Claude phase runs with `--max-budget-usd`; hitting the cap stops the session. It does not narrow what the session may do beforehand, and interactive sessions (`--interactive`) run uncapped.
 - **Your code goes to the model providers.** Each agent phase sends prompts and repository context to the provider running it, Anthropic for Claude phases and OpenAI for Codex phases, with `code_review` using both, all through the Claude Code and Codex CLIs under whatever data terms your accounts have. Treat a `canon run` like any other agent session in that respect.
-- **Git side effects need a flag.** The pipeline never pushes, opens PRs, merges, or publishes on its own. `--pr` pushes the task branch and opens a draft PR, stopping at `human_review`. `--ship` squash-merges that PR; it checks the task's phase, not whether anyone approved, so PR approval is your prerequisite (or your branch protection's), not something canon enforces. `--full-send` skips the human spec gate and opens the draft PR on clean QA, still stopping before merge; its tail also pushes unpushed base commits that carry only task artifacts and pipeline telemetry, and leaves other unpushed commits to the divergence gate unless `--allow-divergent-base` is set. On a `delicate` task it refuses without `--force`.
+- **Git side effects need a flag.** The pipeline never pushes, opens PRs, merges, or publishes on its own. `--pr` pushes the task branch and opens a draft PR, stopping at `human_review`. `--ship` squash-merges that PR; it checks the task's phase, not whether anyone approved, so PR approval is your prerequisite (or your branch protection's), not something canon enforces. `--full-send` skips the human spec gate and opens the draft PR on clean QA, still stopping before merge. `--pr`, `--push` and full-send first push canon's own unpushed scaffold and telemetry commits on the base, creating it on origin if missing when every local-only commit is canon-safe or already published. Other unpushed base commits block unless `--allow-divergent-base` is set; that escape does not apply to a missing remote base. On a `delicate` task, `--full-send` refuses without `--force`.
 
 Run canon on repositories where you would be comfortable running your test suite unattended. If that is not your situation, keep it to a machine or container scoped for the purpose. Replacing the blanket permission skip with a narrower confinement is on the roadmap; the constraint to solve is that adopter validation commands legitimately need network and system access the sandbox would block. Security reports go through [SECURITY.md](SECURITY.md).
 
@@ -267,6 +276,7 @@ Run canon on repositories where you would be comfortable running your test suite
 |---|---|
 | `canon init` | Install canon into the current repo. Refuses symlinks at destination files or parent directories; replace them with regular files/directories first. |
 | `canon doctor` | Verify environment and canon setup — Node/git versions, Claude Code (≥ 2.1.72) and Codex CLI presence, codex project trust, recommended-permission coverage in `.claude/settings.json`, and that any local settings file is gitignored. |
+| `canon completion <shell>` | Print a completion script for bash, zsh, fish, or tcsh; see Shell completion. |
 | `canon task new <id> "Title"` | Scaffold a new task from templates |
 | `canon task list` | Show all tasks and their pipeline phase |
 | `canon task phase <id> <phase> <status>` | Advance a task phase manually |
@@ -275,7 +285,7 @@ Run canon on repositories where you would be comfortable running your test suite
 | `canon run <id> --step --expect <phase>` | Run one phase then stop, with a phase-mismatch guard |
 | `canon run <id> --pr` | Push branch and open a draft PR (at `human_review`) |
 | `canon run <id> --push` | Push branch only, no PR |
-| `canon run <id> --reroute` | Reset a task from any phase reached after a completed `implement` round (`code_review`, `qa`, or `human_review`) back into the post-review fix path after appending an `## Amendment` section to `spec.md` (full-tier re-enters at `spec_review`, fast-tier at `implement`) |
+| `canon run <id> --reroute` | Reset a task once implementation has begun: current phase `code_review`, `qa`, or `human_review` (any status or verdict), or `implement` when implement is in progress or blocked, code review is blocked, or code review already ran in the current loop (a review round or a pre-flight rejection). In a bundle, a sibling at implement pending with no current-loop activity is admitted alongside a task that qualifies when both belong to the same non-empty task branch. Requires the next amendment section (`## Amendment`, then `## Amendment Round N`) appended to `spec.md` first; full-tier re-enters at `spec_review`, fast-tier at `implement`. |
 | `canon run <id> --full-send` | Skip the spec gate and auto-open a draft PR after clean QA |
 | `canon run <id> --ship` | After PR approval: squash-merge, delete branch, tear down worktree, archive the task, pull base branch. Don't merge the PR manually first. |
 | `canon run <id> --dry-run` | Print each planned phase and exit without spawning any agent |