canon-ai 3.10.1 → 3.12.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 > Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). canon-ai uses SemVer per [`docs/decisions.md`](docs/decisions.md).
 
+## [Unreleased]
+
+## [3.12.0] — 2026-10-21
+
+### Added
+
+- **Broken references in a task's handoff or QA summary are fixed by the agent that wrote them, before the commit.** After implement, and again after QA, `canon run` checks the task's own artifacts with the docs-refs checker. If it finds a broken reference, it resumes the same agent session to fix it, up to two attempts. A fix session may change only the task's own artifacts; if it touches anything else, the run stops and names the files. If a reference is still broken after two attempts, canon warns and continues as before. The implement and QA prompts also now ask agents to cite repository files by full path and deleted files as markdown links.
+- **`--full-send` pushes its own scaffold commits to the base branch before opening the draft PR.** It pushes only commits that have the exact scaffold subject and change only task artifacts and pipeline telemetry, and it pushes the checked commit rather than the moving branch. If any other commit is unpushed on the base branch, nothing is pushed and the run stops at the divergence check as before. A rejected push (for example, a protected branch) stops with a hint to push or merge manually. The "Scaffold committed" hint now prints only when such commits exist.
+
+### Changed
+
+- **`--pr` and `--push` block only on real merge conflicts with the base.** A base branch that moved on files the task never touched, such as another task's artifacts, no longer stops the run; canon prints one line saying those files merge cleanly. A conflict with `origin/<base>`, including in a file the spec declared, still aborts before the push and names the conflicted files. The task's own out-of-scope changes still abort as before. `--force` bypasses a conflict with a warning. On Git older than 2.38, canon warns that conflicts weren't checked and proceeds.
+
+### Fixed
+
+- **`canon watch` reports a full-send run that died after QA as a death, not a clean stop.** A run that crashed while opening its draft PR now shows `reason=death` and exits 4, with the reason on stderr, whether watch was attached during the run or started after it. A tail that is still running keeps watch blocking.
+- **`canon task reset-spec-review` re-arms the spec gate.** The gate disarms itself when it halts, so a reset after that halt used to let the next run go straight through to human review. The reset now re-arms it and says so, unless the task is full-send.
+- **`--ship` no longer warns that the branch delete failed.** It merges with `gh pr merge --squash`, deletes the remote branch itself, and deletes the local branch after the worktree is removed; the old order made `gh` try to delete a branch the worktree still held.
+
+## [3.11.0] — 2026-10-20
+
+### Changed
+
+- **An agent session failure now stops the run at a blocked phase instead of killing the orchestrator.** If a non-interactive Claude or Codex session fails mid-phase (it won't start, stalls, is killed, or Claude exits with an error such as an exhausted budget or an expired login), `canon run` marks the phase blocked, records the reason in the task's escalations, prints the command to resume, and exits 2. Fix the cause and run `canon run <id>` again: the phase re-runs with no manual reset. In a bundle, every member is parked. A detached run no longer disappears with its phase stuck in progress. `--interactive` sessions keep their existing terminal behavior.
+
+### Fixed
+
+- **`canon watch` reports a crashed run as a death, not a finished step or nothing to watch.** A run that exited with an error right after a phase finished used to show `reason=step_done` (exit 0), or `reason=nothing_to_watch` (exit 2) when watch started after the crash. It now shows `reason=death` and exits 4 when the run log's newest exit line is non-zero (including a run stopped by a signal) and isn't older than the task state, or when the run's runtime files survive. The reason prints to stderr; the summary line is unchanged. A clean `--step` finish and a clean stop at a gate still report `step_done`. A late watch on a bundle's secondary member, after the run's heartbeat is gone, can't find the primary's log and still reports `nothing_to_watch`; watch the primary task instead. `canon watch --follow` keeps streaming the active run's log after the task moves into a worktree or resumes.
+- **A failed implement auto-commit is retried before code review starts.** If the auto-commit after implement fails (for example, a pre-commit hook rejects it), the next `canon run` commits the pending handoff files first. Previously they went to the code-review pre-flight, which rejected them and used up a review loop. If the retry fails again, the run stops with the same `Auto-commit failed:` message and no review loop is used.
+- **The code-review foreman cites headings exactly.** A quoted `§"Heading"` citation in `review.md` must match a real heading, so the foreman no longer writes citations that fail the docs-refs check at commit time.
+- **A worktree can be created right after `canon update`.** The install record `canon update` writes (`provenance.json` under `.canon`) no longer counts as a stray source edit that blocks the first task worktree.
+- **`canon task new` warns when the base branch came from a non-default current branch.** Without `--base`, if you're on a branch other than the remote default, it says so and prints the `canon task set <id> base_branch <default>` fix. An explicit `--base` is silent.
+- **The handoff pre-flight says how to fix an unchanged file.** A Changes row for a file with no committed change against the task base now says to drop the row if the file was untouched or rewritten with identical content.
+- **`canon update` names pnpm for a pnpm-managed install.** The layout refusal for pnpm's virtual-store shape now says to update with `pnpm add -g canon-ai@<version>` (or the `github:<repo>#<sha>` form for `--channel main` / `--ref`, honoring `CANON_UPSTREAM_REPO`).
+- **Mixed bundle sizes list in size order.** The implement header now shows `XS, S, M, L, XL` order instead of alphabetical.
+
 ## [3.10.1] — 2026-10-17
 
 ### Fixed

package/README.md

@@ -257,7 +257,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; 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; 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`.
 
 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).