canon-ai 3.18.0 → 3.19.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@
 
 ## [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

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,7 +59,7 @@ 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 |
@@ -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.18.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.18.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.18.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.18.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.18.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.18.0");
+  console.log("3.19.0");
 }
 switch (command) {
   case "doctor":