canon-ai 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canon-ai",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "type": "module",
   "description": "A spec-first, multi-agent AI coding pipeline you drop into any repo. The law your agents work under.",
   "engines": {

package/templates/.canon/templates/handoff.md

@@ -12,7 +12,7 @@
 >
 > **Deleting a file?** In this table use the `[path/to/file.ext](path/to/file.ext)` markdown-link form — **not** backticks and **not** bare prose. Backticks trip `docs-refs-check` (a backtick path-ref to a now-missing path under a `validDirs` dir reads as broken); bare prose fails this table's path parse (the first column must be a backtick-path or a markdown-link). The markdown-link is the one form that satisfies both.
 
-> **Never backtick a bare directory path** anywhere in this file (e.g. write "the app source tree (apps/app/src)", not `` `apps/app/src` ``). `docs-refs-check` treats a backticked path as a file reference and aborts the pipeline's auto-commit with "missing file" when it is a directory. Backtick only real files.
+> **Directory paths:** backticking a path to an existing directory is fine — `docs-refs-check` accepts it. A backticked directory path that no longer exists (for example, one this task deleted) can be reported as a missing reference, so describe removed directories in prose or use the markdown-link form above.
 
 | File | What Changed |
 |---|---|

package/templates/.canon/templates/review.md

@@ -8,6 +8,8 @@ Code review is synthesized by a foreman from three lenses: an anchored Claude le
 
 The anchored review runs in two stages on the first round. **Stage 1 is a gate.** If it fails, skip Stage 2 entirely and send back — do not write code-quality findings against code that's about to change.
 
+**Scope:** Full — base `<baseBranch>` — reason: Round 1 (initial review)
+
 ## Stage 1 — Spec Compliance (gate)
 
 ### Validation Gate
@@ -99,6 +101,8 @@ breaks routing. Administrative appends use a non-Round heading (e.g.
 
 ## Round N — verifying iteration N-1's response to round N-1
 
+**Scope:** Full | Delta — base `<baseBranch or prevSHA>` — reason: <trigger reason, or "delta">
+
 ### Stage 1 — Acceptance Criteria Re-Check
 
 Re-fill this table with every AC from spec.md against the latest code. Earlier AC tables were snapshots of earlier iterations, not reusable proof. ACs whose relevant code paths did not change may be marked `Met (unchanged from round N-1)` with a one-line evidence pointer.

package/templates/.claude/agents/code-review-anchored.md

@@ -25,6 +25,8 @@ Apply canon's existing code-review charter to the diff, spec, handoff, and prior
 
 Run Stage 2 only if Stage 1 passed.
 
+**Project conventions — do this first.** Check whether `docs/patterns.md` exists. If it does, read it before reviewing: use its Trigger Table (or skim the file if it has none) to find the sections relevant to the files the diff changes, skipping unfilled placeholder content marked `TODO[canon]` and `_example_` rows. Check the changed code against those rules. Report each violation as a `risk/guardrail` finding that names the rule it breaks (or as a `correctness bug` when it causes incorrect behavior). A violation of a written project rule is not a nit. Apply this check in every round, limited to code changed by the diff.
+
 Find correctness bugs, risk/guardrail issues, optional cleanup/nits, and spec gaps. A changed test that passes against broken behavior is a correctness bug. Reference findings by file:line and AC number where applicable.
 
 Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence here — the foreman does that downstream. Tag each Stage 2 finding with both a severity and a confidence so the foreman can rank and filter. Coverage is your job; filtering is not.

package/templates/.claude/agents/code-review-cold.md

@@ -1,6 +1,6 @@
 ---
 name: code-review-cold
-description: Spec-blind adversarial code reviewer for canon code_review. Reviews only the diff and base ref, then returns structured findings to the foreman.
+description: Spec-blind adversarial code reviewer for canon code_review. Receives the diff and base ref, searches code for sibling guards when needed, then returns findings to the foreman.
 ---
 
 You are the cold-Claude code-review lens in canon's three-lens review pipeline. You receive a code diff and base ref only: no spec, no acceptance criteria, no handoff rationale, and no canon docs.
@@ -15,9 +15,11 @@ Review adversarially for bugs the diff introduces: race conditions, lifecycle is
 
 **Diff-local pattern**: when you see the same safety check, guard, or invariant applied at multiple call sites but a new call site introduced by this diff is missing it, flag it — an inconsistently applied guard is a correctness gap regardless of intent.
 
+**Sibling-site sweep**: when the diff adds or changes a guard, check, or invariant, search the repository for other sites that need the same treatment and report any missing site. Keep that search spec-blind; do not read task artifacts or canon docs.
+
 Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence here — the foreman does that downstream. Tag each finding with both a confidence and a severity so the foreman can rank and filter. Coverage is your job; filtering is not.
 
-If the visible diff is truncated and you need more context, inspect only changed files or run a diff against the provided base ref. Do not read `spec.md`, `handoff.md`, `review.md`, canon docs, task notes, or acceptance criteria.
+If the visible diff is truncated and you need more context, inspect changed files or run a diff against the provided base ref. The sibling-site sweep may search other code files. Do not read `spec.md`, `handoff.md`, `review.md`, canon docs, task notes, or acceptance criteria.
 
 ## Return Format
 

package/templates/docs/pipeline-orchestrator.md

@@ -328,7 +328,9 @@ Non-managed Affected Files entries (source files, test files, fixtures) do not e
 
 When a managed doc is committed via the Affected Files allow-list, an advisory warning fires per file inviting the operator to `git diff HEAD -- <path>` to verify the content before `--ship` (residual guard against same-file sibling-pipeline overlap).
 
-Before that dirty-tree auto-commit path runs, the orchestrator also runs remote-boundary gates. First, the base-divergence check fetches `origin/<base>` and lists commits on local `<base>` that are not yet on `origin/<base>`. Those commits block `--push`, `--pr`, and `--ship` because they will collide when the base is pulled; bypass only this commit-divergence gate with `--allow-divergent-base`. Second, for `--pr` and `--push`, the base-drift check fetches `origin/<base>` and compares `origin/<base>` to `HEAD` with a two-dot tree diff (`git diff origin/<base> HEAD --name-status -M -z`). Any diff path outside the spec's `### Affected Files`, `tasks/<id>/`, `PIPELINE_TELEMETRY_FILES`, and — once `qa.status === 'done'` — any `PIPELINE_MANAGED_DOCS` entry is drift and aborts the run. This catches cross-pipeline contamination Mode 1 (the base branch advanced while the task branch was running) and wider Mode 2 (foreign content was already committed to the task branch before `--pr`). It is complementary to the dirty-tree gate: the dirty-tree gate stops bad content from being committed at `human_review`, while base-drift stops already-committed branch content from being pushed or PR'd.
+Before that dirty-tree auto-commit path runs, the orchestrator also runs remote-boundary gates. First, the base-divergence check fetches `origin/<base>` and lists commits on local `<base>` that are not yet on `origin/<base>`. Those commits block `--push`, `--pr`, and `--ship` because they will collide when the base is pulled; bypass only this commit-divergence gate with `--allow-divergent-base`. Second, for `--pr` and `--push`, the base-drift check fetches `origin/<base>` and compares `origin/<base>` to `HEAD` with a two-dot tree diff (`git diff origin/<base> HEAD --name-status -M -z`). Any diff path outside the spec's `### Affected Files`, `tasks/<id>/`, `PIPELINE_TELEMETRY_FILES`, and — once `qa.status === 'done'` — any `PIPELINE_MANAGED_DOCS` entry is drift and aborts the run. The abort message distinguishes files changed only by base advancement (merge or rebase the base into the task branch) from task-changed files outside Affected Files. Both lists appear when both causes exist. This catches cross-pipeline contamination Mode 1 (the base branch advanced while the task branch was running) and wider Mode 2 (foreign content was already committed to the task branch before `--pr`). It is complementary to the dirty-tree gate: the dirty-tree gate stops bad content from being committed at `human_review`, while base-drift stops already-committed branch content from being pushed or PR'd.
+
+At `code_review` entry, a pre-flight checks the task's own rename-aware three-dot diff against the same Affected Files allowlist, always admitting pipeline-managed docs that QA may update. In a normal run, an out-of-scope file blocks before either review agent runs and does not consume review-loop budget. Add the file to the affected task spec's `### Affected Files` table in the active checkout, then rerun `canon run <id>` (pass every bundle ID for a bundle); or reroute with a note to remove the file. In full-send mode, when every bundle member has `full_send: true`, the foreman judges each file as a scope expansion, spec miss, or change to remove. The first two outcomes require an `## Amendment (full-send scope)` section with an Affected Files row and reason (that heading feeds the Affected Files allowlist but never satisfies the human reroute-amendment gate); the last requires `changes_requested`. The foreman records each judgment in `review.md`, and an unjudged file auto-blocks before QA, including when a review finishes during recovery. Amend the spec and rerun `canon run <id>` to resume an unjudged-file block.
 
 For renames, both the old path and the new path must appear in the spec's `### Affected Files` table. The two-dot diff uses rename detection and surfaces both sides; listing only one side leaves the other as drift. `--force` bypasses detected drift with a loud warning after the operator has verified it, but `--force` does not bypass diff-computation failure. `--force` and `--allow-divergent-base` are independent bypasses for distinct gates; pass both only when both the file-allow-list drift and the commit-divergence are intentional.
 
@@ -412,15 +414,17 @@ PIPELINE_STALL_TIMEOUT_MS=1800000 canon run <id>
 
 ## Code Review Diff Injection
 
-Code review starts with a cold-Codex diff review run by the orchestrator in the active worktree: `codex exec review --json -c model_reasoning_effort=<effort> --base <baseBranch> -m <miniModel>`, where canon resolves `<miniModel>` and `<effort>` through the `code_review` policy row (mini / `high` at every size). The captured findings are written verbatim to `tasks/<id>/review-cold-codex.md` for every task in the invocation. Bundles run this once over the combined branch diff, and the same findings reach every member.
+Code review starts with a cold-Codex diff review run by the orchestrator in the active worktree: `codex exec review --json -c model_reasoning_effort=<effort> --base <reviewBase> -m <miniModel>`, where canon resolves `<miniModel>` and `<effort>` through the `code_review` policy row (mini / `high` at every size). The captured findings are written verbatim to `tasks/<id>/review-cold-codex.md` for every task in the invocation. Bundles run this once over the combined branch diff, and the same findings reach every member.
+
+The review base is the task's base branch for Round 1, effective XL or delicate tasks, an absent or unusable previous-round archive, a delta touching a path outside the previous change set, or a delta over 400 added and deleted lines. Otherwise the base is the reviewed SHA in the newest archive for round N−1. Both path sets include both sides of renames; task artifacts and telemetry do not count toward the path or line triggers. Missing, unresolvable, non-ancestor, or HEAD-equal previous SHAs force a full review, as does a failed delta path or line-stat probe. Every successful cold-Codex invocation adds `tasks/<id>/review-cold-codex-run-N.md` with a header recording round, reviewed SHA, scope, base, and reason; the unnumbered file retains only the latest verbatim findings.
 
 If the cold-Codex review cannot be obtained (no captured findings output, spawn error, stall, or signal), `code_review` stops before any Claude session. Re-run `canon run <id>` when Codex is available; there is no two-Claude-lens fallback. Successful runs emit one duration line in the run log: `→ cold-codex review (<taskIds>): <n>s`.
 
-After that, the code-review foreman prompt includes a scoped diff: `git diff <baseBranch>...HEAD` run in the active worktree (three-dot, so only commits on the task branch are included, not unrelated divergence on `baseBranch`). The diff is capped at 50,000 bytes; if truncated, the prompt notes it. The foreman receives the cold-Codex findings as the pre-obtained third lens input, gives the anchored Claude lens the diff plus spec/handoff context, and gives the cold-Claude lens the diff without spec/AC/canon context. The Codex `--base` review and the Claude scoped diff are both over the task branch versus `<baseBranch>` range.
+After that, the foreman receives the cold-Codex findings as the pre-obtained third lens input. On a full round, the prompt includes `git diff <baseBranch>...HEAD` from the active worktree, capped at 50,000 bytes. On a delta round, it includes `<prevSHA>..HEAD` for cold-Claude and explicitly tells anchored Claude to retrieve the full task diff by command. If the delta diff cannot be injected, the foreman is told to retrieve it by command before spawning cold-Claude. Anchored Claude also receives spec/handoff/prior review context; cold-Claude remains spec-blind. The prompt states the scope, base, and reason and tells the foreman to record them in `review.md`.
 
 ## Per-Iteration Prompt Slimming
 
-Round 2+ of code review and implement do not re-inject the full task framing. Resumed sessions already have spec/plan/repo conventions in context; round-1 findings are durable in the artifacts; the round-2+ prompts target only the delta. Code-review re-obtains cold-Codex findings and re-runs the Claude lenses from scratch on every round before the foreman synthesizes the new verdict.
+Round 2+ of code review and implement do not re-inject the full task framing. Resumed sessions already have spec/plan/repo conventions in context, and round-1 findings are durable in the artifacts. Code review selects a full or delta scope as described above, then re-obtains cold-Codex findings and re-runs the Claude lenses from scratch before the foreman synthesizes the new verdict.
 
 **Cumulative artifacts.** `handoff.md` and `review.md` grow by section per round:
 - Round 1 fills the existing template structure.
@@ -429,23 +433,7 @@ Round 2+ of code review and implement do not re-inject the full task framing. Re
 
 The append-don't-rewrite convention is enforced both in the prompts and via a comment block at the bottom of each template showing the expected shape.
 
-**Slim resumed-session prompts.** Round 2+ prompts for both code review and implement are tight. Code review's slim shape:
-
-```
-[REVIEW ROUND N — verifying iteration N-1's response to round N-1 findings]
-
-Codex appended `## Iteration N-1` to handoff.md addressing your prior round's findings.
-[Resumed session: framing in context. Cold start: re-read spec.md and earlier review.md sections.]
-
-Tasks to re-review: <one-line per task pointing at the specific section>
-
-For each task:
-1. Read `## Iteration N-1` of handoff.md
-2. Read git diff since prior review
-3. Re-fill the Stage 1 AC table with every AC from spec.md against the latest code
-4. Verify each prior finding addressed, cross-referencing the refreshed AC table; flag NEW issues
-5. APPEND `## Round N` to review.md
-```
+**Resumed-session prompts.** The code-review foreman prompt renders the round number and prior handoff iteration, then asks the foreman to spawn both Claude lenses and synthesize their findings with newly obtained cold-Codex findings. Delta rounds inject only the capped fix diff for cold-Claude and direct anchored Claude to retrieve the full task diff by command. Full rounds inject the capped full task diff as before. The foreman re-fills the AC table and appends `## Round N` to `review.md`; implement revisions point at the prior round's findings.
 
 The Stage 1 AC table is redone on round 2+. Earlier AC tables were snapshots of earlier code states; a revision can fix a cited finding while regressing an unrelated AC. Every AC appears every round. ACs whose relevant code paths did not change may be marked `Met (unchanged from round N-1)` with a one-line evidence pointer rather than re-derived evidence. Implement-revision prompts are composable: code-review reroutes point at the new `## Round N-1` of `review.md`.
 

package/templates/scripts/docs-refs-check.mjs

@@ -483,7 +483,7 @@ function stripLineCitation(target) {
 
 // `templates/` markdown is intentionally scanned — those files ship to
 // adopters via `canon upgrade`, so broken refs there would propagate
-// silently. Three exempt classes, each by named purpose (not by filename
+// silently. Exempt classes, each by named purpose (not by filename
 // suffix alone):
 //
 // 1. `docs/BACKLOG.md` — deliberate forward-refs to unbuilt work.
@@ -517,7 +517,8 @@ function isNoisySourceFile(relPath, skipPaths = []) {
     return (
         relPath === 'docs/BACKLOG.md' ||
         /(?:^|\/)templates\/(?:.*\/)?(spec|plan|notes|spec-review)\.md$/.test(relPath) ||
-        /^tasks\/[^/]+\/(spec|plan|notes|spec-review)\.md$/.test(relPath)
+        /^tasks\/[^/]+\/(spec|plan|notes|spec-review)\.md$/.test(relPath) ||
+        /^tasks\/[^/]+\/review-cold-codex-run-\d+\.md$/.test(relPath)
     );
 }
 
@@ -769,7 +770,9 @@ function findBrokenRefs(repoRoot, options = {}) {
                 if (gitIgnoredTargets.has(target)) continue;
 
                 const targetPath = resolveRepoRelative(repoRoot, target);
-                if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isFile()) {
+                const targetExists = fs.existsSync(targetPath)
+                    && (fs.statSync(targetPath).isFile() || fs.statSync(targetPath).isDirectory());
+                if (!targetExists) {
                     addFinding(sourceFile, lineNumber, refText, 'missing file');
                 }
             }