canon-ai 3.17.0 → 3.19.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 ## [Unreleased]
 
+## [3.19.0] — 2026-11-09
+
+### Added
+
+- **Node 26 is supported alongside Node 24.** canon's `engines` range is `24.x || 26.x`, so installing on Node 26 no longer warns. `canon doctor` passes on 24 and 26, warns on other majors from 24 up (such as 25 and 27), and still fails below 24.
+- **Implementers self-check before handoff, and the pipeline checks the record.** Implement prompts list the files that reference the task's Affected Files and the files containing identifiers and flags the spec names, as a bounded map that leaves out `linguist-generated` files and canon's log docs. The handoff gains a `## Self-Check` table covering test integrity, restatement sweep, and sibling parity, each with evidence or `N/A` and a reason. Before code review, the pipeline sends back a handoff with missing rows, a missing baseline section, or evidence that is empty, a bare `N/A`, or still the template placeholder. The anchored reviewer checks each row against the diff. A task already in review when you upgrade gets one rejection to add the baseline section. Editing a file outside Affected Files still requires a Blocker.
+
+### Changed
+
+- **Implementers see the pitfalls and lessons that touch their task's files.** Implement prompts no longer inject the whole `## Known Pitfalls` section. They select the entries, Trigger Table rows, and lessons that cite a path in the spec's Affected Files (a listed directory covers the paths under it) and show the others as one-line titles within a size cap. A Known Pitfalls section written as prose, with no `###` headings, is included in full. Split pitfall docs are indexed by path glob. To be selected, a pitfall must cite its path inside backticks or as a link target, using a trailing `/` for a directory or `*` for a glob. The scaffold's `docs/patterns.md` shows the convention.
+- **Spec prompts carry the term-renames rule.** When a spec renames a term used across the codebase, the author and reviser gate each string family with its own zero-result search instead of a hand-listed set of hits.
+- **`canon watch` labels an automatic loop-back `(review loop)`.** `(reroute)` now appears only after a human `canon run --reroute`.
+- **`/canon-spec` asks for "go" before a delicate full-send.** It used to promise a 5-second abort window that it never honored.
+
+### Fixed
+
+- **`--pr` no longer stops on broken references in code-review notes.** Code review gets the same citation rule and reference fix-up as implement and QA. A fix that would change the verdict, or touch any file other than the review, blocks code review instead.
+- **Agent runs no longer fail when a prompt embeds content containing NUL bytes.** NULs are escaped before the prompt is passed to the agent CLI.
+- **`/canon-status` reports a full-tier task waiting at the human spec gate**, and `/canon-spec-review` rates an unlisted judgment call BLOCKING, as the pipeline's `spec_review` does.
+
+## [3.18.0] — 2026-11-04
+
+### Changed
+
+- **The mixed-mode cold-Codex review lens uses the full Codex model on L and XL/delicate tasks.** XS, S and M tasks keep the mini model; effort stays `high` everywhere. `CODEX_MODEL_FULL` (or its deprecated fallback `CODEX_MODEL_DELICATE`) now also steers the lens on L, XL and delicate tasks, so a custom full-model override reaches it. A bundle containing an L, XL, or delicate member runs its single cold review on the full model. To restore the mini model at every size, install the previous canon release; there is no per-phase Codex override.
+
 ## [3.17.0] — 2026-11-02
 
 ### Added

package/README.md

@@ -32,7 +32,7 @@ canon task new my-first-feature "Short description"
 canon run my-first-feature
 ```
 
-Needs Node 24.x and git. See [Getting started](#getting-started) below for prerequisites, permission allowlists, and the trust model before running this on a repo you care about.
+Needs Node 24.x or 26.x and git. See [Getting started](#getting-started) below for prerequisites, permission allowlists, and the trust model before running this on a repo you care about.
 
 ## What this is
 
@@ -59,12 +59,12 @@ Canon is what happens when you treat those failure modes as engineering problems
 |---|---|
 | Agent jumps to implementation before requirements are clear | **Spec phase** before code, written conversationally with grilling for non-trivial tasks |
 | Agent silently drops a requirement | **Two-stage code review** — Stage 1 is a spec-compliance gate that fails the whole review if any AC is missing from the cross-reference table |
-| Agent reinvents an existing pattern | **`docs/patterns.md` trigger table** + Known Pitfalls injected into implement prompts |
+| Agent reinvents an existing pattern | **`docs/patterns.md` trigger table** + pitfalls and lessons selected by spec Affected Files and injected into implement prompts; a Known Pitfalls section without `###` entries is injected whole except blockquotes and index tables, and a directory in Affected Files selects pitfalls citing paths inside it |
 | Agent re-debates a settled decision | **`docs/decisions.md`** — agents read, don't re-propose |
 | Agent forgets a past mistake | **`docs/lessons-learned.md`** — distilled cross-task wisdom that promotes into permanent rules over time |
 | Reviews loop forever on the same disagreement | **Auto-block on runaway review loops** — per-size caps (see `pipeline-policy.ts`), escalation to human after the cap |
 | Spec drift between conversation and pipeline | **File-based handoff protocol** — every artifact lives in `tasks/<id>/`, no copy-pasting |
-| Sensitive surfaces (auth, payments) get refactored on theoretical grounds | **`delicate: true` flag** that moves spec review and implementation to the XL cells (the full Codex model in mixed mode) and triggers extra review discipline |
+| Sensitive surfaces (auth, payments) get refactored on theoretical grounds | **`delicate: true` flag** that moves spec review, implementation, and the mixed-mode cold-Codex review lens to the XL cells (the full Codex model in mixed mode) and triggers extra review discipline |
 
 ## How it works
 
@@ -97,7 +97,7 @@ The pipeline supports two tiers:
 - **Fast tier** (XS tasks): spec + plan in one Claude session; skip the `spec_review` phase, and the human gate replaces it.
 - **Full tier** (S / M / L / XL / delicate tasks): every phase runs separately, and the spec reviewer checks specs before they reach the human.
 
-`delicate: true` promotes any task to full tier and upgrades the model and effort for spec, plan, and code review, plus moves spec review and implementation to their XL cells (in mixed mode, the full Codex model); QA and, in mixed mode, the cold-Codex review lens stay on their regular cells. Set it with `canon task set <task-id> delicate true`. Use it for sensitive surfaces — auth, payments, persistent storage, anything where a regression has unbounded blast radius.
+`delicate: true` promotes any task to full tier and upgrades the model and effort for spec, plan, and code review, plus moves spec review, implementation, and the mixed-mode cold-Codex review lens to their XL cells (in mixed mode, the full Codex model); QA stays on its regular cells. Set it with `canon task set <task-id> delicate true`. Use it for sensitive surfaces — auth, payments, persistent storage, anything where a regression has unbounded blast radius.
 
 A single command runs a task end-to-end:
 
@@ -113,7 +113,7 @@ Multiple task IDs in one invocation activates **bundle mode** — `canon run id1
 
 ### Prerequisites
 
-- **Node 24.x**
+- **Node 24.x or 26.x**
 - **git**
 - **Claude Code (≥ 2.1.72)** — `npm install -g @anthropic-ai/claude-code`
 - **Codex CLI** (required for the default `mixed` provider and for `/canon-inline-review` under either provider; `CANON_PROVIDER=claude` pipeline runs don't need it, and Claude Code's `/code-review` covers inline review without it) — `npm install -g @openai/codex`
@@ -153,7 +153,7 @@ cd your-project
 canon init
 ```
 
-`canon init` installs the canon task templates and Claude Code skills in your project. Open Claude Code in your project directory and run `/canon-init` to start the interactive setup. The skill grills Claude on your codebase — one question at a time, with recommended answers — and generates the `docs/` knowledge corpus tailored to your project. If you want agent files, generate them separately with the built-in `/init` in Claude Code or Codex; those files are adopter-owned and canon does not scaffold, modify, or read them.
+`canon init` installs the canon task templates, Claude Code skills, the review sub-agents under `.claude/agents/`, the guard hook, and the pipeline-orchestrator doc in your project. Open Claude Code in your project directory and run `/canon-init` to start the interactive setup. The skill grills Claude on your codebase — one question at a time, with recommended answers — and generates the `docs/` knowledge corpus tailored to your project. If you want agent files, generate them separately with the built-in `/init` in Claude Code or Codex; those files are adopter-owned and canon does not scaffold, modify, or read them.
 
 ### Generate your agent files with the built-in `/init`
 
@@ -189,7 +189,7 @@ canon task new my-first-feature "Short description"
 canon run my-first-feature
 ```
 
-Run `canon doctor` after install to verify your environment — it checks Node/git/Claude Code versions, allowlist coverage, and that any local Claude settings file is gitignored, plus Codex CLI presence and codex project trust when `CANON_PROVIDER` is `mixed`, empty, or unset. Doctor checks that environment setting, not providers pinned on existing tasks, so mixed-pinned tasks still need Codex.
+Run `canon doctor` after install to verify your environment — it checks Node (24.x or 26.x; warns on other majors >= 24), git, and Claude Code versions, allowlist coverage, the `.canon/config.json` docs-freshness config, and that any local Claude settings file is gitignored, plus Codex CLI presence and codex project trust when `CANON_PROVIDER` is `mixed`, empty, or unset. Doctor checks that environment setting, not providers pinned on existing tasks, so mixed-pinned tasks still need Codex.
 
 ### Discovery nudge (recommended)
 
@@ -334,7 +334,7 @@ Run canon on repositories where you would be comfortable running your test suite
 | Command | What it does |
 |---|---|
 | `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), Codex CLI presence and codex project trust (when `CANON_PROVIDER` is `mixed`, empty, or unset), recommended-permission coverage, guard-hook registration, and that any local settings file is gitignored. |
+| `canon doctor` | Verify environment and canon setup — Node (24.x or 26.x; warns on other majors >= 24), git, Claude Code (≥ 2.1.72), Codex CLI presence and codex project trust (when `CANON_PROVIDER` is `mixed`, empty, or unset), recommended-permission coverage, guard-hook registration, the `.canon/config.json` docs-freshness config, 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 |
@@ -457,21 +457,13 @@ Drop this into any repo and you have:
 - Full pipeline orchestrator with phase routing, worktree isolation, session resumption, auto-block, bundle mode, `--reroute`, `--ship`. Bundled into `dist/orchestrator/run-task.js` and invoked via `canon run`.
 - Pure routing policy module (tier/sizing/model/effort matrix), table-tested.
 - `canon task` lifecycle CLI (new / list / status / phase / accept / set / reset-spec-review / reset-code-review / post-merge-sync), in-process TS.
-- `.canon/templates/` — artifact templates (status, spec, spec-review, plan, handoff, review, done, notes)
+- `.canon/templates/` — artifact templates (status, spec, spec-review, plan, handoff, review, done, notes, pr-body)
 - Agent rules and per-agent guidance delivered just-in-time via per-phase prompt templates (`src/orchestrator/prompts/templates/`) and the `/canon-*` skills; adopters generate their own `AGENTS.md` / `CLAUDE.md` with the built-in `/init`
 - `docs/` — knowledge corpus templates with detailed scaffolding
 - `.claude/hooks/canon-guard.mjs` — Claude Code guard hook (registration is recommend-only; canon never writes `.claude/settings.json`)
 - Claude Code skills installed by `canon init`: `/canon-init` (knowledge-corpus bootstrap), `/canon-spec` (new task authoring), `/canon-spec-review` (pre-flight a spec), `/canon-inline-review` (independent cross-review of below-pipeline work), `/canon-pipeline` (drive an existing task), `/canon-status` (in-flight task map), `/canon-changelog` (release notes for versioned projects), `/canon-sweep` (triage the lessons-learned buffer)
 - Unit-test suite covering the policy module, orchestrator extractors, and validation parsers (`npm test`)
 
-## Where to Go Deeper
-
-- `docs/pipeline-orchestrator.md` for orchestrator mechanics, reroute, worktrees, and PR/ship flow.
-- `docs/release-process.md` for release-cut mechanics and branch/version flow.
-- `docs/patterns.md` for implementation pitfalls and load-bearing patterns.
-- `docs/decisions.md` for settled rules and architecture decisions.
-- `docs/codebase-map.md` for file locations and entry points.
-
 🚧 **Stubbed with `TODO[canon]:` markers — fill in for your project:**
 
 - Validation command bindings in `docs/architecture.md` §Validation (which commands satisfy each check category — the universal category matrix ships complete in `implement.md` / `.canon/templates/spec.md`)
@@ -484,11 +476,19 @@ Drop this into any repo and you have:
 - Pre-built docs-check / external-API-citation tooling (project-specific)
 - Per-language project bootstrappers (Python / Rust / Go variants)
 
+## Where to Go Deeper
+
+- `docs/pipeline-orchestrator.md` for orchestrator mechanics, reroute, worktrees, and PR/ship flow.
+- `docs/release-process.md` for release-cut mechanics and branch/version flow.
+- `docs/patterns.md` for implementation pitfalls and load-bearing patterns.
+- `docs/decisions.md` for settled rules and architecture decisions.
+- `docs/codebase-map.md` for file locations and entry points.
+
 ## Supported platforms
 
 - **macOS** and **Linux** are the supported targets. Canon's worktree helpers shell out to `git` for `worktree add`/`remove` and `worktree list --porcelain` parsing.
 - **Windows is not supported.** Use WSL2.
-- **Node**: 24.x.
+- **Node**: 24.x or 26.x.
 
 ## The canon philosophy
 
@@ -502,7 +502,7 @@ The implication: **the value of canon compounds with use**. A 6-month-old canon
 
 **Phase 1 (now)**: Layer 1 + Layer 2 ship. Full CLI, open source, installable from npm or GitHub. `/canon-init` skill for interactive project bootstrap. Validate against real projects.
 
-**Phase 2 (next)**: Make the implementer slot pluggable — adapter interface for Codex CLI, Gemini CLI, Aider, others. Architect slot stays Claude Code (skills are load-bearing).
+**Phase 2 (next)**: Make the implementer slot pluggable — an adapter interface beyond Claude Code and Codex CLI (Gemini CLI, Aider, others). Architect slot stays Claude Code (skills are load-bearing).
 
 **Phase 3 (research)**: Productize. Hosted bootstrap service? Per-language scaffolds? Marketplace for `docs/patterns.md` starter packs (Next.js patterns, Rails patterns, etc.)? TBD based on Phase 1 validation.
 

package/dist/cli/index.js

@@ -1925,14 +1925,24 @@ function checkPlatform() {
     detail: "Windows without WSL \u2014 canon is untested here; use WSL for best results"
   };
 }
-function checkNodeVersion() {
-  const match = process.version.match(/^v(\d+)/);
+var SUPPORTED_NODE_MAJORS = [24, 26];
+var NODE_BUILD_FLOOR = 24;
+function checkNodeVersion(version = process.version) {
+  const match = version.match(/^v(\d+)/);
   const major = match ? parseInt(match[1], 10) : 0;
-  if (major >= 24) return { label: `node ${process.version}`, status: "pass" };
+  const label = `node ${version}`;
+  if (major < NODE_BUILD_FLOOR) {
+    return {
+      label,
+      status: "fail",
+      detail: "node 24+ required \u2014 https://nodejs.org"
+    };
+  }
+  if (SUPPORTED_NODE_MAJORS.includes(major)) return { label, status: "pass" };
   return {
-    label: `node ${process.version}`,
-    status: "fail",
-    detail: "node 24+ required \u2014 https://nodejs.org"
+    label,
+    status: "warn",
+    detail: `untested Node major; canon supports ${SUPPORTED_NODE_MAJORS.join(" and ")} \u2014 https://nodejs.org`
   };
 }
 function checkBinary(cmd, required, hint) {
@@ -2025,7 +2035,7 @@ function checkTemplates(cwd) {
 }
 function checkCanonVersion(cwd) {
   const versionPath = join(cwd, ".canon", "version");
-  const installedVersion = "3.17.0";
+  const installedVersion = "3.19.0";
   if (!existsSync(versionPath)) {
     return { label: ".canon/version", status: "warn", detail: "missing \u2014 run `canon upgrade`" };
   }
@@ -2569,7 +2579,7 @@ function initCmd(args2) {
 }
 function writeCanonVersion(cwd) {
   const versionPath = join2(cwd, ".canon", "version");
-  const version = "3.17.0";
+  const version = "3.19.0";
   mkdirSync(dirname2(versionPath), { recursive: true });
   writeFileSync(versionPath, version + "\n");
 }
@@ -2967,26 +2977,31 @@ function findPreviousDonePhase(status, beforePhase) {
 function formatPhaseTransition(from, to) {
   return `${from}\u2192${to}`;
 }
-function formatPhasePointerTransition(from, to) {
+function formatPhasePointerTransition(from, to, humanReroute) {
   const fromIdx = PHASE_ORDER.indexOf(from);
   const toIdx = PHASE_ORDER.indexOf(to);
-  const reroute = fromIdx !== -1 && toIdx !== -1 && toIdx < fromIdx;
-  return `${from} \u2192 ${to}${reroute ? " (reroute)" : ""}`;
+  const backwards = fromIdx !== -1 && toIdx !== -1 && toIdx < fromIdx;
+  if (!backwards) return `${from} \u2192 ${to}`;
+  return `${from} \u2192 ${to} ${humanReroute ? "(reroute)" : "(review loop)"}`;
 }
 function displayedPhasePointer(ctx) {
   if (ctx.statusResult.kind !== "ok" || !isStatusJson(ctx.statusResult.status)) return null;
   return deriveTopLevelStatus(ctx.statusResult.status);
 }
-var REROUTE_VERDICTS = {
+function rerouteCount(ctx) {
+  if (ctx.statusResult.kind !== "ok" || !isStatusJson(ctx.statusResult.status)) return 0;
+  return ctx.statusResult.status.phases.implement?.reroute_count ?? 0;
+}
+var REVIEW_LOOP_VERDICTS = {
   spec_review: ["changes_requested"],
   code_review: ["changes_requested", "needs_re_review"]
 };
-function pointerIsMidReroute(ctx) {
+function pointerIsMidReviewLoop(ctx) {
   if (ctx.statusResult.kind !== "ok" || !isStatusJson(ctx.statusResult.status)) return false;
   for (const phase of ["spec_review", "code_review"]) {
     const entry = ctx.statusResult.status.phases[phase];
     if (entry?.status !== "done") continue;
-    if (entry.verdict != null && REROUTE_VERDICTS[phase].includes(entry.verdict)) return true;
+    if (entry.verdict != null && REVIEW_LOOP_VERDICTS[phase].includes(entry.verdict)) return true;
   }
   return false;
 }
@@ -3479,16 +3494,19 @@ ${unknownOptionMessage("watch", preScan.argument).split("\n")[1]}` : "";
     return reportInitialFailure(initialAttach);
   }
   let previousPhasePointer = displayedPhasePointer(ctx);
+  let previousRerouteCount = rerouteCount(ctx);
   const reportPhasePointer = (pollCtx) => {
     let currentPhase = displayedPhasePointer(pollCtx);
-    if (currentPhase != null && previousPhasePointer != null && pointerIsMidReroute(pollCtx)) {
-      currentPhase = previousPhasePointer;
-    }
+    const holding = currentPhase != null && previousPhasePointer != null && pointerIsMidReviewLoop(pollCtx);
+    if (holding) currentPhase = previousPhasePointer;
+    const currentRerouteCount = rerouteCount(pollCtx);
     if (previousPhasePointer != null && currentPhase != null && previousPhasePointer !== currentPhase) {
-      stderr(`canon watch: phase ${formatPhasePointerTransition(previousPhasePointer, currentPhase)}
+      const humanReroute = currentRerouteCount > previousRerouteCount;
+      stderr(`canon watch: phase ${formatPhasePointerTransition(previousPhasePointer, currentPhase, humanReroute)}
 `);
     }
     previousPhasePointer = currentPhase;
+    if (!holding) previousRerouteCount = currentRerouteCount;
   };
   if (initialAttach.kind === "launch_window") {
     const remaining = remainingTimeoutMs();
@@ -3515,6 +3533,7 @@ ${unknownOptionMessage("watch", preScan.argument).split("\n")[1]}` : "";
         return reportInitialFailure(postWaitAttach);
       }
       previousPhasePointer = displayedPhasePointer(ctx);
+      previousRerouteCount = rerouteCount(ctx);
     } else if (waitResult.kind === "pid-died") {
       emitSummary(stdout, { state: "in_progress", reason: "death" });
       return exit(4);
@@ -3649,7 +3668,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.17.0" ?? "dev";
+  return explicit ?? "3.19.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);
@@ -5957,7 +5976,7 @@ function currentPinFromManifest(manifest) {
   return "unknown";
 }
 function bakedVersion() {
-  return "3.17.0";
+  return "3.19.0";
 }
 function ownPackageName(pkgDir) {
   try {
@@ -6454,7 +6473,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
     cutoverWarnings.push(docsRefsCheckRel);
   }
   const versionPath = join5(cwd, ".canon", "version");
-  const newVersion = "3.17.0";
+  const newVersion = "3.19.0";
   const currentVersion = existsSync5(versionPath) ? readFileSync4(versionPath, "utf8").trim() : null;
   if (currentVersion !== newVersion) {
     pending.push({ rel: ".canon/version", projectPath: versionPath, content: newVersion + "\n" });
@@ -7073,7 +7092,7 @@ Global:
 Run 'canon <command> --help' for details.`);
 }
 function printVersion() {
-  console.log("3.17.0");
+  console.log("3.19.0");
 }
 switch (command) {
   case "doctor":