@erclx/canon 5.74.0 → 5.75.0

package/tooling/claude/reference.md

@@ -68,14 +68,16 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 
 ## settings.json
 
-- Pair the seed's three PreToolUse hooks with `index-reminder.sh`, `search-reminder.sh`, and `scratch-guard.sh`, and its PostToolUse hook with `standards-audit.sh`, all under `.claude/hooks/`
+- Pair the seed's PreToolUse hooks with `index-reminder.sh`, `search-reminder.sh`, `scratch-guard.sh`, `review-post-scan.sh`, and `plan-guard.sh`, and its PostToolUse hook with `standards-audit.sh`
 - Keep only what is project-specific in the project file, since project settings layer over user settings
 - Expect `permissions.deny` to hold `Agent` and `Task`, so no session spawns a subagent and parallel work runs as separate background sessions
 - Expect `autoMemoryEnabled` to be `false`. A person turns it back on for themselves in `settings.local.json`.
-- Run `canon migrate session-defaults` on a target seeded before those two defaults or before the merge entries below, since sync never rewrites an existing settings file
+- Run `canon migrate session-defaults` on a target seeded before those defaults, the merge entries, or the plan guard below, since sync never rewrites an existing settings file
 
 The seed's deny list also holds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)`, so the operator alone merges. An existing target gets both from `canon migrate session-defaults --write`, and `canon claude sync` warns while either is absent. Neither covers more than the form an agent writes by default.
 
+`plan-guard.sh` blocks a new plan under `.canon/plans/` until `plan-feature` is invoked for it, since a heredoc never loads the plan rule. It passes when the transcript holds no assistant tool call it can parse, though a format change confined to the Skill call still blocks. It logs each decision under `.canon/tmp/hooks/plan-guard/`.
+
 ## User settings
 
 - `canon claude setup` installs `tooling/claude/user/settings.template.json` once per machine

package/tooling/claude/seeds/.claude/hooks/plan-guard.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+
+# A path-scoped rule loads on a Read, Write, or Edit of a matching file, and a
+# heredoc onto `.canon/plans/` is none of them, so the plan rule never reaches
+# the session writing most plans. This guard is the check behind that rule: a
+# new plan passes only when the transcript shows a `canon:plan-feature`
+# invocation this session has not already spent on an earlier new plan, or an
+# `auto-ship` invocation naming that plan's path. It
+# backs the rule up rather than replacing it, since a hook fails open on a
+# timeout and on anything below it cannot read.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+# Bash is the highest-frequency tool, so the one field a write names is lifted
+# out of the raw payload and tested with a shell pattern before jq starts.
+field_re='"(command|file_path)":"(([^"\\]|\\.)*)"'
+[[ $input =~ $field_re ]] || exit 0
+case "${BASH_REMATCH[2]}" in
+*.canon/plans/*) ;;
+*) exit 0 ;;
+esac
+
+target=$(printf '%s' "$input" | jq -r '
+  if .tool_name == "Write" then "F" + .tool_input.file_path
+  elif .tool_name == "Bash" then "B" + .tool_input.command
+  else empty end // empty')
+[ -n "$target" ] || exit 0
+kind=${target:0:1}
+target=${target:1}
+
+# A command that only mentions the folder is not a write to it, as with
+# `canon tasks plan-link` or a heredoc body quoting a plan path. The awk pass
+# reads the command as words, drops heredoc bodies, and prints only the words a
+# write lands on: the word after a `>` or `>>`, and every argument of `tee` or
+# `cp`, whose source is an existing file and so never reads as a new plan. A
+# quoted span is one word, so a redirect inside quotes is text. This is a
+# scanner and not a shell parser, so a path built in a variable or written by
+# `printf` into an interpreter passes unseen.
+if [ "$kind" = B ]; then
+  IFS= read -r -d '' scanner <<'AWK'
+{ s = s (NR > 1 ? "\n" : "") $0 }
+function flush() {
+  if (!inword) return
+  if (redirect) print word
+  else if (tag) { nt++; tags[nt] = word; dashes[nt] = dash }
+  else if (cmd == "") {
+    w = word; sub(/.*\//, "", w)
+    if (w !~ /^[A-Za-z_][A-Za-z0-9_]*=/ && w !~ /^(sudo|env|command|exec|time|nice|xargs)$/) cmd = w
+  }
+  else if ((cmd == "tee" || cmd == "cp") && word !~ /^-/) print word
+  word = ""; inword = 0; redirect = 0; tag = 0
+}
+END {
+  n = length(s); i = 1; q = ""; cmd = ""; nt = 0
+  while (i <= n) {
+    c = substr(s, i, 1)
+    if (q != "") {
+      if (c == q) q = ""
+      else if (q == "\"" && c == "\\") { word = word substr(s, i + 1, 1); i += 2; continue }
+      else word = word c
+      i++; continue
+    }
+    if (c == "'" || c == "\"") { q = c; inword = 1; i++; continue }
+    if (c == "\\") { word = word substr(s, i + 1, 1); inword = 1; i += 2; continue }
+    if (c == " " || c == "\t") { flush(); i++; continue }
+    if (c == ">") {
+      flush(); i++
+      if (substr(s, i, 1) == ">" || substr(s, i, 1) == "|") i++
+      if (substr(s, i, 1) == "&") { i++; continue }
+      redirect = 1; continue
+    }
+    if (c == "<" && substr(s, i, 2) == "<<" && substr(s, i, 3) != "<<<") {
+      flush(); i += 2; dash = 0
+      if (substr(s, i, 1) == "-") { dash = 1; i++ }
+      tag = 1; continue
+    }
+    if (c ~ /[;|&()<`]/) { flush(); if (c != "<") cmd = ""; i++; continue }
+    if (c == "\n") {
+      flush(); cmd = ""; i++
+      for (t = 1; t <= nt; t++) {
+        while (i <= n) {
+          e = index(substr(s, i), "\n")
+          if (e == 0) { line = substr(s, i); i = n + 1 } else { line = substr(s, i, e - 1); i += e }
+          if (dashes[t]) sub(/^\t+/, "", line)
+          if (line == tags[t]) break
+        }
+      }
+      nt = 0; continue
+    }
+    word = word c; inword = 1; i++
+  }
+  flush()
+}
+AWK
+  targets=$(printf '%s' "$target" | awk "$scanner")
+else
+  targets=$target
+fi
+[ -n "$targets" ] || exit 0
+
+payload_cwd=$(printf '%s' "$input" | jq -r '.cwd // empty')
+cwd=${payload_cwd:-${CLAUDE_PROJECT_DIR:-.}}
+# Plans live at the main worktree root, which a linked worktree's cwd is not.
+root=$(git -C "$cwd" worktree list --porcelain 2>/dev/null | awk '/^worktree /{sub(/^worktree /, ""); print; exit}')
+root=${root:-$cwd}
+
+# A write onto an existing plan is an amendment, such as a worker rewriting a
+# `- Suggested:` line, and an archive path holds a shipped plan rather than a
+# new one, so only a path naming no file yet asks for the skill.
+new=""
+while IFS= read -r path; do
+  case "$path" in
+  *.canon/plans/*) ;;
+  *) continue ;;
+  esac
+  rest=${path##*.canon/plans/}
+  case "$rest" in
+  '' | archive/* | *'$'* | *'*'*) continue ;;
+  *.md) ;;
+  *) continue ;;
+  esac
+  [ -e "$root/.canon/plans/$rest" ] && continue
+  case "$path" in
+  /*) [ -e "$path" ] && continue ;;
+  esac
+  new=".canon/plans/$rest"
+  break
+done <<EOF
+$targets
+EOF
+[ -n "$new" ] || exit 0
+
+# Without a session id or a readable transcript there is nothing to read the
+# invocation from, and blocking on that would stop every plan, so pass.
+meta=$(printf '%s' "$input" | jq -r '[.session_id // "", .transcript_path // ""] | @tsv')
+session=${meta%%$'\t'*}
+transcript=${meta#*$'\t'}
+[ -n "$session" ] && [ -n "$transcript" ] && [ -r "$transcript" ] || exit 0
+
+# An invocation is a Skill tool call naming the skill, or the operator typing
+# its slash command, whose user line carries the command-name tag. Each one
+# prints as `P <line>`, the line ordering it against the invocation the last
+# new plan spent. An `auto-ship` invocation prints as `A <its arguments>`,
+# since a cloud worker writes the approved plan that launch names verbatim and
+# never plans it, so a write onto the path those arguments name passes.
+invocations=$(grep -n -e 'plan-feature' -e 'auto-ship' "$transcript" 2>/dev/null | jq -Rr '
+  def text: if type == "string" then . else (map(select(.type == "text") | .text) | join("\n")) end;
+  def skill($name): .type == "tool_use" and .name == "Skill"
+    and ((.input.skill // "") | test("^(canon:)?" + $name + "$"));
+  def typed($name): test("<command-name>/?(canon:)?" + $name + "</command-name>");
+  capture("^(?<n>[0-9]+):(?<j>.*)$") as $l
+  | ($l.j | fromjson? // empty) as $o
+  | if $o.type == "assistant" then
+      ($o.message.content[]? | select(type == "object")
+        | if skill("plan-feature") then "P \($l.n)"
+          elif skill("auto-ship") then "A \(.input.args // "" | tostring)"
+          else empty end)
+    elif $o.type == "user" then
+      (($o.message.content // "") | text)
+      | if typed("plan-feature") then "P \($l.n)"
+        elif typed("auto-ship") then "A \(gsub("\n"; " "))"
+        else empty end
+    else empty end' 2>/dev/null)
+
+rest=${new#.canon/plans/}
+key=$(printf '%s' "$session" | tr -c 'A-Za-z0-9' '_')
+marker_dir="$root/.canon/tmp/hooks/plan-guard"
+
+# One line per new plan judged, so a wrong block in any project shows up beside
+# the passes and the unread ones. A failed write never changes the decision.
+log_decision() {
+  # The group takes the redirect's own error, which a `2>/dev/null` after the
+  # `>>` would miss because the shell opens the file first.
+  mkdir -p "$marker_dir" 2>/dev/null && {
+    printf '%s %s %s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" "$key" "$rest" \
+      >>"$marker_dir/decisions.log"
+  } 2>/dev/null
+  return 0
+}
+
+while IFS= read -r line; do
+  case "$line" in
+  "A "*".canon/plans/$rest"*)
+    log_decision pass
+    exit 0
+    ;;
+  esac
+done <<EOF
+$invocations
+EOF
+latest=$(printf '%s\n' "$invocations" | awk '/^P /{n = $2} END {if (n != "") print n}')
+
+# The marker holds the line of the spent invocation and the plan it licensed.
+# A PreToolUse pass is not a landed write, so a retry after a refused heredoc,
+# or the `cp` that follows a worktree `Write`, lands on the same plan and
+# passes on the invocation it already spent.
+marker="$marker_dir/$key"
+spent=0
+spent_plan=""
+if [ -f "$marker" ]; then
+  IFS=' ' read -r spent spent_plan <"$marker" 2>/dev/null
+fi
+case "$spent" in '' | *[!0-9]*) spent=0 ;; esac
+
+if [ "$spent" -gt 0 ] && [ "$spent_plan" = "$rest" ]; then
+  log_decision pass
+  exit 0
+fi
+if [ -n "$latest" ] && [ "$latest" -gt "$spent" ]; then
+  mkdir -p "$marker_dir" 2>/dev/null && printf '%s %s\n' "$latest" "$rest" >"$marker" 2>/dev/null
+  log_decision pass
+  exit 0
+fi
+
+# A transcript holding no assistant `tool_use` line means Claude Code changed
+# its message format rather than that the session skipped the skill, and
+# blocking on that would stop every plan, so pass and log it apart. A change
+# confined to the Skill call's input or the typed command tag leaves other
+# tool calls readable, so this does not catch it and the guard still blocks.
+calls=$(grep -F '"tool_use"' "$transcript" 2>/dev/null | jq -Rrn '
+  first(inputs | fromjson? | select(type == "object" and .type == "assistant")
+    | .message.content[]? | select(type == "object" and .type == "tool_use"
+      and (.name | type) == "string") | "read") // empty' 2>/dev/null)
+if [ -z "$calls" ]; then
+  log_decision unread
+  exit 0
+fi
+
+if [ "$spent" -gt 0 ]; then
+  why='The last canon:plan-feature invocation in this session was spent on an earlier new plan'
+else
+  why='This session has not invoked canon:plan-feature'
+fi
+log_decision block
+printf '%s, so %s would be written outside the skill that owns its shape. Invoke the canon:plan-feature skill for this plan, then resend the write.\n' "$why" "$new" >&2
+exit 2

package/tooling/claude/seeds/.claude/settings.json

@@ -29,6 +29,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scratch-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/plan-guard.sh"
           }
         ]
       },
@@ -38,6 +42,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/review-post-scan.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/plan-guard.sh"
           }
         ]
       }

package/scripts/core/regen-hero.ts

@@ -1,113 +0,0 @@
-/**
- * Fills every assets/captures/*.html.tmpl from the catalogs and the design
- * source, writing the .html beside each one.
- *
- * The name says hero because the hero was the only template when it was written
- * and every citation of it across docs/, canon/context/, and src/ spells that
- * name. The loop below covers whatever templates the folder holds.
- *
- * Each catalog is read through the module its `canon` verb calls, so no child
- * process runs and no stderr is discarded. The palette arrives from
- * `buildDesignCss` without the component half, which is a scrollbar and a
- * status marker a static capture frame renders neither of. The value builder
- * and every guard live in `src/capture/frame-values.ts`, where tsc and vitest
- * reach them.
- *
- * `--check` fills every template into a temp folder and discards it, so a
- * renamed featured skill, an empty catalog, or an unresolved placeholder still
- * fails a branch while no frame file changes. Frames are refreshed after a
- * merge rather than committed by each branch.
- *
- * Only the HTML regenerates here. The PNG beside it is a chromium render whose
- * bytes move with the browser version. Rebuild the images with
- * `canon capture assets/captures --selector .window --out assets/frames`
- * after this script reports a change. That capture writes a .stamp beside each
- * PNG, which records the digest of the markup it rendered and is what the Hero
- * stage compares, so a frame's three files commit together. The frame carries
- * no version, since `package.json` is bumped on main by the release tooling and
- * embedding it would drift every open branch on the next release.
- *
- * Clone-only. This script reads the repository's own catalogs and
- * `assets/captures`, which a registry install does not carry.
- */
-import {
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-import {
-  buildFrameValues,
-  FrameError,
-  fillTemplate,
-} from '../../src/capture/frame-values'
-import { listSkills } from '../../src/claude/skills-list'
-import { countCommands } from '../../src/counts/catalogs'
-import { buildDesignCss } from '../../src/design/css'
-import { buildGovCatalog } from '../../src/gov/list'
-import { buildStackSummaries } from '../../src/tooling/list'
-
-const root = new URL('../..', import.meta.url).pathname
-const assetDir = join(root, 'assets', 'captures')
-
-const [flag, ...extra] = process.argv.slice(2)
-if (flag !== undefined && flag !== '--check') {
-  console.error(`regen-hero: unknown argument ${flag}`)
-  process.exit(1)
-}
-if (extra.length > 0) {
-  console.error(`regen-hero: unknown argument ${extra[0]}`)
-  process.exit(1)
-}
-
-const outDir =
-  flag === '--check' ? mkdtempSync(join(tmpdir(), 'regen-hero-')) : assetDir
-
-function run(): void {
-  const templates = readdirSync(assetDir)
-    .filter((name) => name.endsWith('.html.tmpl'))
-    .sort()
-  if (templates.length === 0) {
-    throw new FrameError(`no templates under ${assetDir}`)
-  }
-
-  const tokenCss = buildDesignCss(undefined, { components: false })
-  if (!tokenCss.trim()) {
-    throw new FrameError(
-      'the design source emitted nothing, refusing to write an unstyled frame',
-    )
-  }
-
-  const { values, frames } = buildFrameValues({
-    skills: listSkills(root).map((entry) => entry.name),
-    gov: buildGovCatalog(root),
-    toolingStacks: buildStackSummaries(root),
-    commandCount: countCommands(root) ?? 0,
-    tokenCss,
-    markSvg: readFileSync(join(root, 'assets', 'brand', 'mark.svg'), 'utf8'),
-  })
-
-  mkdirSync(outDir, { recursive: true })
-  for (const { template, out, tokens } of frames(templates)) {
-    const source = readFileSync(join(assetDir, template), 'utf8')
-    writeFileSync(
-      join(outDir, out),
-      fillTemplate(template, source, values, tokens),
-    )
-  }
-}
-
-try {
-  run()
-} catch (error) {
-  if (!(error instanceof FrameError)) throw error
-  console.error(`regen-hero: ${error.message}`)
-  process.exitCode = 1
-} finally {
-  if (outDir !== assetDir) rmSync(outDir, { recursive: true, force: true })
-}