canon-ai 3.1.0 → 3.1.2

package/dist/cli/index.js

@@ -1207,8 +1207,8 @@ ${RECOMMENDED_NUDGE}`
     };
   }
   const mentionsCanon = existingFiles.some((filename) => {
-    const path13 = join(cwd, filename);
-    return /canon/i.test(readFileSync(path13, "utf8"));
+    const path15 = join(cwd, filename);
+    return /canon/i.test(readFileSync(path15, "utf8"));
   });
   if (mentionsCanon) {
     return { label: "canon discovery nudge", status: "pass" };
@@ -1245,7 +1245,7 @@ function checkTemplates(cwd) {
 }
 function checkCanonVersion(cwd) {
   const versionPath = join(cwd, ".canon", "version");
-  const installedVersion = "3.1.0";
+  const installedVersion = "3.1.2";
   if (!existsSync(versionPath)) {
     return { label: ".canon/version", status: "warn", detail: "missing \u2014 run `canon upgrade`" };
   }
@@ -1419,10 +1419,10 @@ function checkCodexProjectTrust(cwd) {
         trust_level = "trusted"`
   };
 }
-function readAllowFromSettings(path13) {
-  if (!existsSync(path13)) return { allow: /* @__PURE__ */ new Set(), status: "missing" };
+function readAllowFromSettings(path15) {
+  if (!existsSync(path15)) return { allow: /* @__PURE__ */ new Set(), status: "missing" };
   try {
-    const parsed = JSON.parse(readFileSync(path13, "utf8"));
+    const parsed = JSON.parse(readFileSync(path15, "utf8"));
     const raw = parsed?.permissions?.allow;
     const allow = new Set(
       Array.isArray(raw) ? raw.filter((x) => typeof x === "string") : []
@@ -1639,6 +1639,31 @@ import {
 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname2, join as join2, relative as relative2 } from "path";
+
+// src/lib/scaffold-paths.ts
+import { lstatSync } from "fs";
+import path7 from "path";
+function assertNoSymlinkDestinations(root, relativePaths) {
+  for (const relativePath of relativePaths) {
+    let current = root;
+    for (const segment of relativePath.split(/[\\/]/)) {
+      current = path7.join(current, segment);
+      let entry;
+      try {
+        entry = lstatSync(current);
+      } catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR") break;
+        throw error;
+      }
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Refusing to write ${relativePath}: ${current} is a symlink. Replace it with a regular file or directory before running canon init or upgrade; --force does not bypass this check.`);
+      }
+    }
+  }
+}
+
+// src/cli/commands/init.ts
 var packageDir = join2(dirname2(fileURLToPath2(import.meta.url)), "../..");
 var templatesDir = join2(packageDir, "templates");
 var AGENT_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md"]);
@@ -1665,6 +1690,7 @@ function walkDir(dir, base = dir) {
 }
 function scaffoldTemplates(cwd, srcTemplatesDir) {
   const templateFiles = walkDir(srcTemplatesDir);
+  assertNoSymlinkDestinations(cwd, templateFiles);
   const scaffolded = [];
   const skipped = [];
   for (const rel of templateFiles) {
@@ -1682,6 +1708,7 @@ function scaffoldTemplates(cwd, srcTemplatesDir) {
 function initCmd(_args) {
   checkDeps();
   const cwd = process.cwd();
+  assertNoSymlinkDestinations(cwd, [".gitignore", ".canon/version"]);
   const { scaffolded, skipped } = scaffoldTemplates(cwd, templatesDir);
   const gitignorePath = join2(cwd, ".gitignore");
   const existingGitignore = existsSync2(gitignorePath) ? readFileSync2(gitignorePath, "utf8") : "";
@@ -1715,7 +1742,7 @@ function initCmd(_args) {
 }
 function writeCanonVersion(cwd) {
   const versionPath = join2(cwd, ".canon", "version");
-  const version = "3.1.0";
+  const version = "3.1.2";
   mkdirSync(dirname2(versionPath), { recursive: true });
   writeFileSync(versionPath, version + "\n");
 }
@@ -1755,6 +1782,7 @@ function runCmd(args2) {
 
 // src/cli/commands/watch.ts
 import fs7 from "fs";
+import { StringDecoder } from "string_decoder";
 
 // src/cli/commands/stop.ts
 import { existsSync as existsSync3 } from "fs";
@@ -2362,25 +2390,39 @@ function primaryLogTaskId(ctx, fallbackTaskId) {
 function tailRunLog(ctx, taskId, deps, tailState) {
   const logTaskDir = tolerantTaskDir(primaryLogTaskId(ctx, taskId));
   const logPath = runLogPathFor(logTaskDir);
+  let fd;
   try {
-    const stat = fs7.statSync(logPath);
-    if (tailState.position == null) {
+    fd = fs7.openSync(logPath, "r");
+    const stat = fs7.fstatSync(fd);
+    const identity = `${logPath}:${stat.dev}:${stat.ino}`;
+    if (tailState.position == null || tailState.path !== logPath) {
       tailState.position = stat.size;
+      tailState.path = logPath;
+      tailState.identity = identity;
+      tailState.decoder = new StringDecoder("utf8");
       return;
     }
-    if (stat.size < tailState.position) {
+    if (identity !== tailState.identity || stat.size < tailState.position) {
       tailState.position = 0;
+      tailState.decoder = new StringDecoder("utf8");
     }
+    tailState.identity = identity;
     if (stat.size === tailState.position) return;
-    const content = fs7.readFileSync(logPath, "utf8");
-    const chunk = content.slice(tailState.position);
-    if (chunk.length > 0) deps.stderr?.(chunk);
-    tailState.position = stat.size;
+    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, stat.size - tailState.position));
+    while (tailState.position < stat.size) {
+      const bytes = fs7.readSync(fd, buffer, 0, Math.min(buffer.length, stat.size - tailState.position), tailState.position);
+      if (bytes === 0) break;
+      tailState.position += bytes;
+      const chunk = tailState.decoder.write(buffer.subarray(0, bytes));
+      if (chunk.length > 0) deps.stderr?.(chunk);
+    }
   } catch (error) {
     const code = getErrnoCode2(error);
     if (code === "ENOENT") return;
     deps.stderr?.(`canon watch: failed to tail ${logPath}: ${errorMessage2(error)}
 `);
+  } finally {
+    if (fd !== void 0) fs7.closeSync(fd);
   }
 }
 function gatherContext(taskId, deps) {
@@ -2441,7 +2483,7 @@ function watchCmd(args2, deps = {}) {
   }
   const taskId = parsed.taskId;
   const timeoutDeadline = parsed.timeoutMs == null ? null : now() + parsed.timeoutMs;
-  const tailState = { position: null };
+  const tailState = { position: null, decoder: new StringDecoder("utf8") };
   const withinTimeout = () => timeoutDeadline != null && now() >= timeoutDeadline;
   const remainingTimeoutMs = () => {
     if (timeoutDeadline == null) return null;
@@ -2652,21 +2694,21 @@ function watchCmd(args2, deps = {}) {
 
 // src/task/index.ts
 import { spawnSync as spawnSync7 } from "child_process";
-import fs12 from "fs";
-import path12 from "path";
+import fs13 from "fs";
+import path14 from "path";
 
 // src/orchestrator/canon-snapshot.ts
 import { spawnSync as spawnSync6 } from "child_process";
 import fs9 from "fs";
-import path9 from "path";
+import path10 from "path";
 
 // src/orchestrator/git.ts
 import { spawnSync as spawnSync5 } from "child_process";
-import path8 from "path";
+import path9 from "path";
 
 // src/orchestrator/worktree.ts
 import fs8 from "fs";
-import path7 from "path";
+import path8 from "path";
 var PIPELINE_TELEMETRY_FILES = [
   "docs/pipeline-invocations.md",
   "docs/task-quality-log.md",
@@ -2709,18 +2751,18 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.1.0" ?? "dev";
+  return explicit ?? "3.1.2" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);
   if (!ownToplevel) return upstreamCommit;
-  const parentDir = path9.dirname(repoRoot);
+  const parentDir = path10.dirname(repoRoot);
   const parentToplevel = captureGitOutput(parentDir, ["rev-parse", "--show-toplevel"], runGitAt);
   if (!parentToplevel) return upstreamCommit;
-  if (path9.resolve(parentToplevel) === path9.resolve(ownToplevel)) {
+  if (path10.resolve(parentToplevel) === path10.resolve(ownToplevel)) {
     return upstreamCommit;
   }
-  return captureGitOutput(path9.resolve(parentToplevel), ["rev-parse", "HEAD"], runGitAt) || upstreamCommit;
+  return captureGitOutput(path10.resolve(parentToplevel), ["rev-parse", "HEAD"], runGitAt) || upstreamCommit;
 }
 function defaultRunCommand(command2, args2) {
   const result = spawnSync6(command2, args2, {
@@ -2754,7 +2796,7 @@ function captureCanonSnapshot(repoRoot = REPO_ROOT, options = {}) {
   const isInstalled = isInstalledSourcePath(canonSourcePath);
   const superprojectWorkingTree = captureGitOutput(repoRoot, ["rev-parse", "--show-superproject-working-tree"], runGitAt);
   const drivingCommit = captureGitOutput(repoRoot, ["rev-parse", "HEAD"], runGitAt) || "<unavailable>";
-  const hostCommit = superprojectWorkingTree ? captureGitOutput(path9.resolve(superprojectWorkingTree), ["rev-parse", "HEAD"], runGitAt) || "<unavailable>" : null;
+  const hostCommit = superprojectWorkingTree ? captureGitOutput(path10.resolve(superprojectWorkingTree), ["rev-parse", "HEAD"], runGitAt) || "<unavailable>" : null;
   let upstreamCommit;
   let orchestratorCommit;
   if (isInstalled) {
@@ -2801,12 +2843,50 @@ function refreshCanonSnapshotAtPath(statusFilePath, options = {}) {
 }
 
 // src/orchestrator/review-archive.ts
-import fs11 from "fs";
+import fs12 from "fs";
+import path13 from "path";
+
+// src/task/templates.ts
+import fs10 from "fs";
 import path11 from "path";
+function tasksRoot() {
+  return process.env.CANON_TASKS_DIR_OVERRIDE ?? "tasks";
+}
+function templatesRoot() {
+  return path11.join(process.cwd(), ".canon", "templates");
+}
+function taskTemplateOverrideRoot() {
+  return path11.join(tasksRoot(), "_templates");
+}
+function resolveTaskTemplateSource(basename2) {
+  const override = path11.join(taskTemplateOverrideRoot(), basename2);
+  if (fs10.existsSync(override)) return override;
+  const managed = path11.join(templatesRoot(), basename2);
+  return fs10.existsSync(managed) ? managed : null;
+}
+function renderTaskTemplate(source, taskId, title) {
+  return fs10.readFileSync(source, "utf8").replaceAll("[TASK-ID]", taskId).replaceAll("[Title]", title);
+}
+function scaffoldTaskArtifact(taskDir, basename2, taskId, title) {
+  const source = resolveTaskTemplateSource(basename2);
+  if (!source) return null;
+  fs10.writeFileSync(path11.join(taskDir, basename2), renderTaskTemplate(source, taskId, title), "utf8");
+  return source;
+}
+function isPristineTaskArtifact(content, basename2, taskId, title) {
+  if (content.includes("[TASK-ID]")) return true;
+  const source = resolveTaskTemplateSource(basename2);
+  if (!source) return false;
+  try {
+    return content === renderTaskTemplate(source, taskId, title);
+  } catch {
+    return false;
+  }
+}
 
 // src/orchestrator/validation.ts
-import fs10 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path12 from "path";
 function computeLatestValidationResults(handoffContent) {
   const latest = /* @__PURE__ */ new Map();
   const baseline = parseTable(handoffContent, "Validation Outcomes");
@@ -2937,7 +3017,7 @@ function isTemplateUnfilled(content) {
 function isDoneMdTemplate(donePath) {
   let content;
   try {
-    content = fs10.readFileSync(donePath, "utf8");
+    content = fs11.readFileSync(donePath, "utf8");
   } catch {
     return true;
   }
@@ -2967,16 +3047,16 @@ var PHASE_GATE_CONFIG = {
   human_review: {}
 };
 function resolveTaskDirForValidation(taskId, taskDirOverride) {
-  return taskDirOverride ? path10.join(taskDirOverride, taskId) : taskDirFor(taskId);
+  return taskDirOverride ? path12.join(taskDirOverride, taskId) : taskDirFor(taskId);
 }
 function checkPhaseGate(taskId, phase, verdict, taskDirOverride) {
   const config2 = PHASE_GATE_CONFIG[phase];
   const taskDir = resolveTaskDirForValidation(taskId, taskDirOverride);
   if (config2.artifactName) {
-    const artifactPath = path10.join(taskDir, config2.artifactName);
+    const artifactPath = path12.join(taskDir, config2.artifactName);
     let content;
     try {
-      content = fs10.readFileSync(artifactPath, "utf8");
+      content = fs11.readFileSync(artifactPath, "utf8");
     } catch {
       return { ok: false, reason: `${config2.artifactName} is missing for phase '${phase}'` };
     }
@@ -2988,7 +3068,7 @@ function checkPhaseGate(taskId, phase, verdict, taskDirOverride) {
     if (phase === "spec_review" || phase === "plan") {
       let statusRaw;
       try {
-        statusRaw = fs10.readFileSync(path10.join(taskDir, "status.json"), "utf8");
+        statusRaw = fs11.readFileSync(path12.join(taskDir, "status.json"), "utf8");
       } catch {
         return { ok: false, reason: `cannot determine reroute state for '${phase}': status.json in ${taskDir} is missing or unreadable` };
       }
@@ -3023,19 +3103,19 @@ function checkPhaseGate(taskId, phase, verdict, taskDirOverride) {
     }
   }
   if (phase === "human_review") {
-    const handoffPath = path10.join(taskDir, "handoff.md");
+    const handoffPath = path12.join(taskDir, "handoff.md");
     let handoffContent;
     try {
-      handoffContent = fs10.readFileSync(handoffPath, "utf8");
+      handoffContent = fs11.readFileSync(handoffPath, "utf8");
     } catch {
       return { ok: false, reason: `closing human_review requires a handoff.md \u2014 none found in ${taskDir}` };
     }
     const pending = countHumanPendingChecks(handoffContent);
     if (pending.length === 0) return { ok: true };
-    const donePath = path10.join(taskDir, "done.md");
+    const donePath = path12.join(taskDir, "done.md");
     let doneContent = "";
     try {
-      doneContent = fs10.readFileSync(donePath, "utf8");
+      doneContent = fs11.readFileSync(donePath, "utf8");
     } catch {
     }
     if (hasHumanPendingWaiver(doneContent)) return { ok: true };
@@ -3050,10 +3130,10 @@ ${list}
   return { ok: true };
 }
 function parseHandoffChangesRows(taskId) {
-  const handoffPath = path10.join(taskDirFor(taskId), "handoff.md");
+  const handoffPath = path12.join(taskDirFor(taskId), "handoff.md");
   let content;
   try {
-    content = fs10.readFileSync(handoffPath, "utf8");
+    content = fs11.readFileSync(handoffPath, "utf8");
   } catch {
     return { files: [], malformed: [] };
   }
@@ -3357,23 +3437,35 @@ var REVIEW_ARCHIVE_PREFIX = "review-prior-";
 var REVIEW_ARCHIVE_RE = new RegExp(`^${REVIEW_ARCHIVE_PREFIX}(\\d+)\\.md$`);
 function newestReviewArchiveNumber(taskDir) {
   let newest = 0;
-  for (const name of fs11.readdirSync(taskDir)) {
+  for (const name of fs12.readdirSync(taskDir)) {
     const match = REVIEW_ARCHIVE_RE.exec(name);
     if (match) newest = Math.max(newest, Number(match[1]));
   }
   return newest;
 }
 function archivePriorReview(taskDir, options = {}) {
-  const reviewPath = path11.join(taskDir, "review.md");
-  if (!fs11.existsSync(reviewPath)) return null;
+  const reviewPath = path13.join(taskDir, "review.md");
+  if (!fs12.existsSync(reviewPath)) return null;
   if (options.skipUnfilledTemplate) {
-    const content = fs11.readFileSync(reviewPath, "utf8");
+    const content = fs12.readFileSync(reviewPath, "utf8");
     if (isTemplateUnfilled(content)) return null;
+    if (options.scaffold && isPristineTaskArtifact(content, "review.md", options.scaffold.taskId, options.scaffold.title)) {
+      return null;
+    }
   }
   const archiveName = `${REVIEW_ARCHIVE_PREFIX}${newestReviewArchiveNumber(taskDir) + 1}.md`;
-  fs11.renameSync(reviewPath, path11.join(taskDir, archiveName));
+  fs12.renameSync(reviewPath, path13.join(taskDir, archiveName));
   return archiveName;
 }
+function rescaffoldReview(taskDir, identity) {
+  try {
+    if (fs12.existsSync(path13.join(taskDir, "review.md"))) return { outcome: "exists" };
+    const source = scaffoldTaskArtifact(taskDir, "review.md", identity.taskId, identity.title);
+    return source ? { outcome: "written", source } : { outcome: "no-template" };
+  } catch (error) {
+    return { outcome: "error", message: error instanceof Error ? error.message : String(error) };
+  }
+}
 
 // src/task/index.ts
 var VALID_PHASES = new Set(PHASE_ORDER);
@@ -3421,35 +3513,26 @@ function validateTaskId(id) {
     throw new Error(`Error: invalid task ID '${id}'. Must not contain '..'.`);
   }
 }
-function tasksRoot() {
-  return process.env.CANON_TASKS_DIR_OVERRIDE ?? "tasks";
-}
 function taskDirFromRoot(taskId) {
-  return path12.join(tasksRoot(), taskId);
+  return path14.join(tasksRoot(), taskId);
 }
 function taskDirForCwd(_cwd, taskId) {
   const root = tasksRoot();
-  if (path12.isAbsolute(root)) {
-    return path12.join(root, taskId);
+  if (path14.isAbsolute(root)) {
+    return path14.join(root, taskId);
   }
-  return path12.join(resolveTaskCwd(taskId), root, taskId);
+  return path14.join(resolveTaskCwd(taskId), root, taskId);
 }
 function taskStatusFileForCwd(cwd, taskId) {
-  return path12.join(taskDirForCwd(cwd, taskId), "status.json");
+  return path14.join(taskDirForCwd(cwd, taskId), "status.json");
 }
 function taskRootForGate(cwd) {
   const root = tasksRoot();
-  return path12.isAbsolute(root) ? root : path12.join(cwd, root);
-}
-function templatesRoot() {
-  return path12.join(process.cwd(), ".canon", "templates");
-}
-function taskTemplateOverrideRoot() {
-  return path12.join(tasksRoot(), "_templates");
+  return path14.isAbsolute(root) ? root : path14.join(cwd, root);
 }
 function readJsonFile(filePath) {
   try {
-    return JSON.parse(fs12.readFileSync(filePath, "utf8"));
+    return JSON.parse(fs13.readFileSync(filePath, "utf8"));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Error: failed to read ${filePath}: ${message}`);
@@ -3457,9 +3540,9 @@ function readJsonFile(filePath) {
 }
 function writeJsonAtomic(filePath, data) {
   const tmpFile = `${filePath}.tmp`;
-  fs12.writeFileSync(tmpFile, `${JSON.stringify(data, null, 2)}
+  fs13.writeFileSync(tmpFile, `${JSON.stringify(data, null, 2)}
 `, "utf8");
-  fs12.renameSync(tmpFile, filePath);
+  fs13.renameSync(tmpFile, filePath);
 }
 function writeStatusAtomic(filePath, status) {
   status.status = deriveTopLevelStatus(status);
@@ -3498,21 +3581,17 @@ function currentBranchOrEmpty() {
   if (result.error || result.status !== 0) return "";
   return (result.stdout ?? "").trim();
 }
-function copyTemplateFile(source, destination, taskId, title) {
-  const content = fs12.readFileSync(source, "utf8").replaceAll("[TASK-ID]", taskId).replaceAll("[Title]", title);
-  fs12.writeFileSync(destination, content, "utf8");
-}
 function listTemplateFiles() {
   const root = templatesRoot();
-  if (!fs12.existsSync(root)) {
+  if (!fs13.existsSync(root)) {
     throw new Error(`Error: templates directory not found at ${root}`);
   }
-  return fs12.readdirSync(root).filter((name) => name.endsWith(".md") || name.endsWith(".json")).sort();
+  return fs13.readdirSync(root).filter((name) => name.endsWith(".md") || name.endsWith(".json")).sort();
 }
 function printCreatedTask(taskDir, baseBranch) {
   console.log(`Created task: ${taskDir}`);
   console.log("Files:");
-  for (const file of fs12.readdirSync(taskDir).sort()) {
+  for (const file of fs13.readdirSync(taskDir).sort()) {
     console.log(file);
   }
   console.log("");
@@ -3550,20 +3629,18 @@ function taskNew(args2) {
     throw new Error("Error: title must be single-line (no embedded newlines).");
   }
   const taskDir = taskDirFromRoot(id);
-  if (fs12.existsSync(taskDir)) {
+  if (fs13.existsSync(taskDir)) {
     throw new Error(`Error: Task directory ${taskDir} already exists.`);
   }
   if (!baseBranch) {
     baseBranch = currentBranchOrEmpty() || "main";
   }
-  fs12.mkdirSync(taskDir, { recursive: true });
-  const overrideRoot = taskTemplateOverrideRoot();
+  fs13.mkdirSync(taskDir, { recursive: true });
   for (const basename2 of listTemplateFiles()) {
-    const override = path12.join(overrideRoot, basename2);
-    const source = fs12.existsSync(override) ? override : path12.join(templatesRoot(), basename2);
-    copyTemplateFile(source, path12.join(taskDir, basename2), id, title);
+    const source = resolveTaskTemplateSource(basename2) ?? path14.join(templatesRoot(), basename2);
+    fs13.writeFileSync(path14.join(taskDir, basename2), renderTaskTemplate(source, id, title), "utf8");
   }
-  const statusPath = path12.join(taskDir, "status.json");
+  const statusPath = path14.join(taskDir, "status.json");
   const status = readJsonFile(statusPath);
   status.id = id;
   status.title = title;
@@ -3584,31 +3661,31 @@ function derivePhase(status) {
 }
 function taskList() {
   const root = tasksRoot();
-  if (!fs12.existsSync(root)) {
+  if (!fs13.existsSync(root)) {
     console.log("No tasks found.");
     return;
   }
   const rows = [];
   let invalidCount = 0;
-  for (const entry of fs12.readdirSync(root).sort()) {
+  for (const entry of fs13.readdirSync(root).sort()) {
     if (entry === "_archive" || entry === "_templates") continue;
     if (isOrphanedWorktreeState(entry)) {
       invalidCount += 1;
       let title = "(untitled)";
       try {
-        const frozen = readJsonFile(path12.join(taskDirForRepoRoot(entry), "status.json"));
+        const frozen = readJsonFile(path14.join(taskDirForRepoRoot(entry), "status.json"));
         title = frozen.title ?? title;
       } catch {
       }
       rows.push({
         id: entry,
         title,
-        phase: `INVALID: worktree missing \u2014 restore ${path12.join(effectiveWorktreesRoot(), entry)} or archive the task`
+        phase: `INVALID: worktree missing \u2014 restore ${path14.join(effectiveWorktreesRoot(), entry)} or archive the task`
       });
       continue;
     }
-    const statusPath = path12.join(taskDirForCwd(process.cwd(), entry), "status.json");
-    if (!fs12.existsSync(statusPath)) continue;
+    const statusPath = path14.join(taskDirForCwd(process.cwd(), entry), "status.json");
+    if (!fs13.existsSync(statusPath)) continue;
     try {
       const status = readJsonFile(statusPath);
       const phase = derivePhase(status);
@@ -3645,7 +3722,7 @@ function taskStatus(id) {
   validateTaskId(id);
   const cwd = resolveTaskCwd(id);
   const statusPath = taskStatusFileForCwd(cwd, id);
-  if (!fs12.existsSync(statusPath)) {
+  if (!fs13.existsSync(statusPath)) {
     throw new Error(`Error: No status.json found for task ${id}`);
   }
   const status = readJsonFile(statusPath);
@@ -3718,7 +3795,7 @@ function taskPhase(id, phaseArg, statusArg, verdictArg) {
   assertValidVerdict(phaseArg, verdictArg);
   const taskCwd = resolveTaskCwd(id);
   const statusPath = taskStatusFileForCwd(taskCwd, id);
-  if (!fs12.existsSync(statusPath)) {
+  if (!fs13.existsSync(statusPath)) {
     throw new Error(`Error: No status.json found for task ${id} (looked in ${taskDirForCwd(taskCwd, id)}/)`);
   }
   const status = readJsonFile(statusPath);
@@ -3760,7 +3837,7 @@ function taskPhase(id, phaseArg, statusArg, verdictArg) {
     writeQualityLogForTask(
       id,
       taskCwd,
-      path12.join(taskDirForCwd(taskCwd, id), "done.md"),
+      path14.join(taskDirForCwd(taskCwd, id), "done.md"),
       status
     );
   }
@@ -3784,7 +3861,7 @@ function taskAccept(ids, phaseArg, options = {}) {
   for (const id of ids) {
     const taskCwd = resolveTaskCwd(id);
     const statusPath = taskStatusFileForCwd(taskCwd, id);
-    if (!fs12.existsSync(statusPath)) {
+    if (!fs13.existsSync(statusPath)) {
       throw new Error(`Error: No status.json found for task ${id} (looked in ${taskDirForCwd(taskCwd, id)}/)`);
     }
     const status = readJsonFile(statusPath);
@@ -3886,7 +3963,7 @@ function taskAccept(ids, phaseArg, options = {}) {
     const originalSnapshots2 = /* @__PURE__ */ new Map();
     for (const ctx of ctxByTask.values()) {
       try {
-        originalSnapshots2.set(ctx.statusPath, fs12.readFileSync(ctx.statusPath, "utf8"));
+        originalSnapshots2.set(ctx.statusPath, fs13.readFileSync(ctx.statusPath, "utf8"));
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Error: failed to read ${ctx.statusPath} for rollback snapshot: ${message}`);
@@ -3923,8 +4000,8 @@ function taskAccept(ids, phaseArg, options = {}) {
         if (original === void 0) continue;
         try {
           const tmpFile = `${filePath}.rollback.tmp`;
-          fs12.writeFileSync(tmpFile, original, "utf8");
-          fs12.renameSync(tmpFile, filePath);
+          fs13.writeFileSync(tmpFile, original, "utf8");
+          fs13.renameSync(tmpFile, filePath);
         } catch (rollbackErr) {
           const message = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
           rollbackErrors.push(`    ${filePath}: ${message}`);
@@ -3942,18 +4019,18 @@ ${rollbackErrors.join("\n")}`
       throw new Error(`Error: bundled review accept failed; rolled back to pre-accept state. Original error: ${originalMessage}`);
     }
     for (const ctx of ctxByTask.values()) {
-      const notesPath = path12.join(taskDirForCwd(ctx.taskCwd, ctx.id), "notes.md");
+      const notesPath = path14.join(taskDirForCwd(ctx.taskCwd, ctx.id), "notes.md");
       const entry = ctx.status.phases[phaseArg];
       const sanctioned = entry?.verdict === "sanctioned";
       const bundleNote = ids.length > 1 ? ` Bundle: ${ids.join(", ")}.` : "";
       const noteLine = `[${today()}] Operator accepted ${phaseArg} via \`canon task accept\` \u2014 ${sanctioned ? "sanctioned (agent verdict overridden)" : "unblocked (advancing verdict preserved)"}. Reason: ${reason}.${bundleNote}`;
       try {
-        if (fs12.existsSync(notesPath)) {
-          fs12.appendFileSync(notesPath, `
+        if (fs13.existsSync(notesPath)) {
+          fs13.appendFileSync(notesPath, `
 ${noteLine}
 `, "utf8");
         } else {
-          fs12.writeFileSync(notesPath, `${noteLine}
+          fs13.writeFileSync(notesPath, `${noteLine}
 `, "utf8");
         }
       } catch (error) {
@@ -4076,7 +4153,7 @@ ${noteLine}
   const originalSnapshots = /* @__PURE__ */ new Map();
   for (const ctx of ctxByTask.values()) {
     try {
-      originalSnapshots.set(ctx.statusPath, fs12.readFileSync(ctx.statusPath, "utf8"));
+      originalSnapshots.set(ctx.statusPath, fs13.readFileSync(ctx.statusPath, "utf8"));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(`Error: failed to read ${ctx.statusPath} for rollback snapshot: ${message}`);
@@ -4101,8 +4178,8 @@ ${noteLine}
       if (original === void 0) continue;
       try {
         const tmpFile = `${filePath}.rollback.tmp`;
-        fs12.writeFileSync(tmpFile, original, "utf8");
-        fs12.renameSync(tmpFile, filePath);
+        fs13.writeFileSync(tmpFile, original, "utf8");
+        fs13.renameSync(tmpFile, filePath);
       } catch (rollbackErr) {
         const message = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
         rollbackErrors.push(`    ${filePath}: ${message}`);
@@ -4121,15 +4198,15 @@ ${noteLine}
     throw new Error(`Error: bundled accept failed; rolled back to pre-accept state. Original error: ${originalMessage}`);
   }
   for (const ctx of ctxByTask.values()) {
-    const notesPath = path12.join(taskDirForCwd(ctx.taskCwd, ctx.id), "notes.md");
+    const notesPath = path14.join(taskDirForCwd(ctx.taskCwd, ctx.id), "notes.md");
     const noteLine = `[${today()}] Operator accepted implement phase via \`canon task accept\` \u2014 auto-commit will be skipped.${options.force ? " (--force)" : ""}`;
     try {
-      if (fs12.existsSync(notesPath)) {
-        fs12.appendFileSync(notesPath, `
+      if (fs13.existsSync(notesPath)) {
+        fs13.appendFileSync(notesPath, `
 ${noteLine}
 `, "utf8");
       } else {
-        fs12.writeFileSync(notesPath, `${noteLine}
+        fs13.writeFileSync(notesPath, `${noteLine}
 `, "utf8");
       }
     } catch (error) {
@@ -4148,15 +4225,15 @@ function taskResetSpecReview(id) {
   validateTaskId(id);
   const taskCwd = resolveTaskCwd(id);
   const taskDir = taskDirForCwd(taskCwd, id);
-  const statusPath = path12.join(taskDir, "status.json");
-  if (!fs12.existsSync(statusPath)) {
+  const statusPath = path14.join(taskDir, "status.json");
+  if (!fs13.existsSync(statusPath)) {
     throw new Error(`Error: no status.json at ${statusPath}`);
   }
-  const reviewPath = path12.join(taskDir, "spec-review.md");
-  if (fs12.existsSync(reviewPath)) {
+  const reviewPath = path14.join(taskDir, "spec-review.md");
+  if (fs13.existsSync(reviewPath)) {
     let n = 1;
-    while (fs12.existsSync(path12.join(taskDir, `spec-review-prior-${n}.md`))) n += 1;
-    fs12.renameSync(reviewPath, path12.join(taskDir, `spec-review-prior-${n}.md`));
+    while (fs13.existsSync(path14.join(taskDir, `spec-review-prior-${n}.md`))) n += 1;
+    fs13.renameSync(reviewPath, path14.join(taskDir, `spec-review-prior-${n}.md`));
     console.log(`Archived prior spec-review.md \u2192 spec-review-prior-${n}.md`);
   }
   const status = readJsonFile(statusPath);
@@ -4179,8 +4256,8 @@ function taskResetCodeReview(id) {
   validateTaskId(id);
   const taskCwd = resolveTaskCwd(id);
   const taskDir = taskDirForCwd(taskCwd, id);
-  const statusPath = path12.join(taskDir, "status.json");
-  if (!fs12.existsSync(statusPath)) {
+  const statusPath = path14.join(taskDir, "status.json");
+  if (!fs13.existsSync(statusPath)) {
     throw new Error(`Error: no status.json at ${statusPath}`);
   }
   const status = readJsonFile(statusPath);
@@ -4193,6 +4270,18 @@ function taskResetCodeReview(id) {
   if (archivedReview) {
     console.log(`Archived prior review.md \u2192 ${archivedReview}`);
   }
+  const rescaffold = rescaffoldReview(taskDir, { taskId: id, title: status.title ?? "" });
+  if (rescaffold.outcome === "written") {
+    console.log(`Re-scaffolded review.md from ${path14.relative(process.cwd(), rescaffold.source)}`);
+  } else if (rescaffold.outcome === "no-template") {
+    console.warn(
+      "Warning: review.md is missing and no template was found to re-scaffold it (looked for a review.md override under tasks/_templates/ and .canon/templates/review.md); the next code review will write it from scratch."
+    );
+  } else if (rescaffold.outcome === "error") {
+    console.warn(
+      `Warning: review.md is missing and could not be re-scaffolded: ${rescaffold.message}; the next code review will write it from scratch.`
+    );
+  }
   const implement = ensurePhaseEntry(status, "implement");
   const codeReview = ensurePhaseEntry(status, "code_review");
   implement.status = "done";
@@ -4226,16 +4315,16 @@ function parsePorcelainPath(line) {
 }
 function isPipelineOwnedAcceptPath(filePath, taskId, gitCwd) {
   const repoRootForPaths = resolveRepoRootForAccept(gitCwd);
-  const dirtyAbsolute = path12.isAbsolute(filePath) ? filePath : path12.resolve(repoRootForPaths, filePath);
+  const dirtyAbsolute = path14.isAbsolute(filePath) ? filePath : path14.resolve(repoRootForPaths, filePath);
   const canonicalDirty = safeRealpath(dirtyAbsolute);
   const root = tasksRoot();
-  const rootAbsolute = path12.isAbsolute(root) ? root : path12.resolve(repoRootForPaths, root);
+  const rootAbsolute = path14.isAbsolute(root) ? root : path14.resolve(repoRootForPaths, root);
   const canonicalRoot = safeRealpath(rootAbsolute);
-  const taskCanonical = path12.join(canonicalRoot, taskId);
+  const taskCanonical = path14.join(canonicalRoot, taskId);
   if (canonicalDirty === taskCanonical) return true;
-  if (canonicalDirty.startsWith(`${taskCanonical}${path12.sep}`)) return true;
+  if (canonicalDirty.startsWith(`${taskCanonical}${path14.sep}`)) return true;
   for (const telemetry of PIPELINE_TELEMETRY_FILES) {
-    const telemetryAbsolute = path12.resolve(repoRootForPaths, telemetry);
+    const telemetryAbsolute = path14.resolve(repoRootForPaths, telemetry);
     if (safeRealpath(telemetryAbsolute) === canonicalDirty) return true;
   }
   return false;
@@ -4250,16 +4339,16 @@ function resolveMainCheckoutRoot() {
   if (out.error || out.status !== 0) return process.cwd();
   const gitCommonDir = (out.stdout ?? "").trim();
   if (!gitCommonDir) return process.cwd();
-  return path12.dirname(gitCommonDir);
+  return path14.dirname(gitCommonDir);
 }
 function safeRealpath(target) {
   try {
-    return fs12.realpathSync(target);
+    return fs13.realpathSync(target);
   } catch {
-    const parent = path12.dirname(target);
+    const parent = path14.dirname(target);
     if (parent === target) return target;
     try {
-      return path12.join(fs12.realpathSync(parent), path12.basename(target));
+      return path14.join(fs13.realpathSync(parent), path14.basename(target));
     } catch {
       return target;
     }
@@ -4367,12 +4456,12 @@ function taskPostMergeSync(branchArg) {
 }
 function nudgeShippableTasks() {
   const root = tasksRoot();
-  if (!fs12.existsSync(root)) return;
+  if (!fs13.existsSync(root)) return;
   const shippable = [];
-  for (const entry of fs12.readdirSync(root).sort()) {
+  for (const entry of fs13.readdirSync(root).sort()) {
     if (entry === "_archive" || entry.startsWith("_")) continue;
-    const statusPath = path12.join(root, entry, "status.json");
-    if (!fs12.existsSync(statusPath)) continue;
+    const statusPath = path14.join(root, entry, "status.json");
+    if (!fs13.existsSync(statusPath)) continue;
     let status;
     try {
       status = readJsonFile(statusPath);
@@ -4447,7 +4536,7 @@ function taskSet(args2) {
   validateTaskId(id);
   const taskCwd = resolveTaskCwd(id);
   const statusPath = taskStatusFileForCwd(taskCwd, id);
-  if (!fs12.existsSync(statusPath)) {
+  if (!fs13.existsSync(statusPath)) {
     throw new Error(`Error: No status.json found for task ${id}`);
   }
   const status = readJsonFile(statusPath);
@@ -4788,7 +4877,7 @@ function currentPinFromManifest(manifest) {
   return "unknown";
 }
 function bakedVersion() {
-  return "3.1.0";
+  return "3.1.2";
 }
 function ownPackageName(pkgDir) {
   try {
@@ -5170,6 +5259,14 @@ function printUpgradeRefusals(refusals, prefix) {
   }
 }
 function runUpgrade(cwd, pkgDir, options = {}) {
+  assertNoSymlinkDestinations(cwd, [
+    ...CANON_OWNED,
+    ...DELIMITED,
+    ...HEADER_ONLY_SYNC,
+    ".canon/version",
+    ".gitignore",
+    "scripts/docs-refs-config.mjs"
+  ]);
   const upgraded = [];
   const unchanged = [];
   const skipped = [];
@@ -5254,7 +5351,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
     cutoverWarnings.push(docsRefsCheckRel);
   }
   const versionPath = join5(cwd, ".canon", "version");
-  const newVersion = "3.1.0";
+  const newVersion = "3.1.2";
   const currentVersion = existsSync5(versionPath) ? readFileSync4(versionPath, "utf8").trim() : null;
   if (currentVersion !== newVersion) {
     pending.push({ rel: ".canon/version", projectPath: versionPath, content: newVersion + "\n" });
@@ -5332,6 +5429,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
   const reportedWrites = options.force ? pending : clean;
   const staleOverrides = getStaleOverrides(cwd, reportedWrites);
   const toWrite = options.force ? pending : clean;
+  assertNoSymlinkDestinations(cwd, toWrite.map((op) => op.rel));
   for (const op of toWrite) {
     mkdirSync3(dirname5(op.projectPath), { recursive: true });
     writeFileSync3(op.projectPath, op.content);
@@ -5561,7 +5659,7 @@ Global:
 `);
 }
 function printVersion() {
-  console.log("3.1.0");
+  console.log("3.1.2");
 }
 switch (command) {
   case "doctor":