@erclx/canon 5.73.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/claude/skills/ui-film/references/pr-clip.md

@@ -1,108 +0,0 @@
----
-title: Pull request clip
-description: Pull request mode of ui-film, run for pr-evidence with no operator present, covering the beat choice from the checklist, the length cap, the still check that stands in for approval, the reel flag, and the push to the frames branch
----
-
-# Pull request clip
-
-Read at the top of `ui-film` when the caller names pull request mode. `pr-evidence` is the only caller, passing the pull request number, the `url` its `canon pr local` read returned, and the checklist text.
-
-This mode films a short reel of what the checklist asks a reviewer to try, hosts it on `canon/frames`, and hands back the link or the reason it skipped.
-
-## Contents
-
-- [What changes from an ordinary run](#what-changes-from-an-ordinary-run)
-- [Choose the beats](#choose-the-beats)
-- [Film the reel](#film-the-reel)
-- [Check each still](#check-each-still)
-- [Push the reel](#push-the-reel)
-- [What goes back to the caller](#what-goes-back-to-the-caller)
-
-## What changes from an ordinary run
-
-The mode holds only while the caller names it. An ordinary run that finds a pull request in its context still stops at Step 2 for approval.
-
-- Skip Step 1's throwaway copy. Film the address the caller passed, joined to the config's `access` value, and start no server.
-- Skip Step 2's approval. The beats come from a checklist a reviewer already reads, and the still check below is the guard against posting a wrong take.
-- Skip Step 5's handoff and its output block, since the reel is the product and HyperFrames composes nothing here
-- Write inside `.canon/tmp/ui-film/pr-<number>/` at the current worktree's root in place of the video workspace, since a reel is thrown away once posted
-- Ask nothing at any step. Every stop below is a skip with a reason, since the ship chain runs this with nobody to answer.
-
-## Choose the beats
-
-Film where motion is the claim. Filter the boxes first, then spend the three beats so each feature area shows its change once before any area shows two.
-
-### Filter the boxes
-
-A box is filmable when it asks the reviewer to click, fill, or scroll something and its result is a visible change.
-
-- Skip a box ending in `(taste)`, since no driver judges it
-- Skip a box that asks only to look at a state the page opens on, since a screenshot already shows it
-- Skip a negative box, one asserting that something does not happen, such as "no drop line draws", since footage of nothing shows nothing
-
-Read the box's text for the negative. A box asserting an unchanged result, such as "the board goes to all projects as before", is not negative, since the action still produces a visible change. Rank it behind a box in the same group that names new behavior.
-
-### Order the beats
-
-A group is the bold feature-area label above at most five boxes, as `ui-checklist` defines it.
-
-1. Take one beat per group in checklist order, from the highest-ranked filmable box of each group, up to three beats.
-2. When beats remain after every group has one, take a second pass in checklist order over the boxes left, highest-ranked first within each group, up to three beats in all.
-
-A checklist with one group gives up to three beats from it. A checklist with four groups gives three beats, one from each of the first three.
-
-### Plan the beats
-
-Write one plan entry for each beat chosen, then skip when none was.
-
-- Name each beat after its box's text, cut to the action
-- Write the plan per `${CLAUDE_SKILL_DIR}/references/take-craft.md`, finding each target on the served page rather than guessing it
-- With no interactive box, skip as `no-interactive-box` and film nothing
-- With interactive boxes that the filter removed, whether negative, static, or marked `(taste)`, skip as `no-visible-change` and film nothing
-
-The negative test is a judgment over the box's text. A misread box costs a weaker reel and never a wrong pass, since the still check below guards the footage and the UI reviewer drives every box regardless.
-
-Keep the whole reel at or under 12 seconds. Each beat opens and closes on a 0.6 s hold, so give each action's `wait` only what its result needs to settle.
-
-## Film the reel
-
-```bash
-canon take <url> .canon/tmp/ui-film/pr-<number>/plan.json --out .canon/tmp/ui-film/pr-<number>/takes --reel .canon/tmp/ui-film/pr-<number>/reel.webp --json
-```
-
-Branch on the record's `reason`, never on the exit code.
-
-| Record          | Route                                                              |
-| --------------- | ------------------------------------------------------------------ |
-| No `reason`     | Sum the beats' `seconds` and continue to the stills                |
-| `reel-failed`   | Skip as `reel-failed` with the record's `message`                  |
-| Any other value | Skip under that `reason`, such as `target-missing` with its `beat` |
-
-When the beats sum past 12 seconds, drop the last beat from the plan and film once more. A second run past the cap skips as `over-cap`.
-
-## Check each still
-
-Open each beat's `still.jpg`, the closing frame the record names in its `still` field, and confirm it shows the state the beat's box describes. This check replaces the operator's approval, so it runs on every reel.
-
-- A still showing the wrong state skips the reel as `wrong-state`, naming the beat and what the still shows
-- A record whose beats carry no `still` field comes from a `canon` predating the still, so skip as `no-still` rather than posting a reel nothing checked
-- Read `fallback` on each beat the way an ordinary run does. A beat filmed by screencast still joins the reel, since the reel shrinks every beat to one width.
-
-## Push the reel
-
-Stamp the pass in compact UTC and push the file:
-
-```bash
-canon pr frames <number> --reel .canon/tmp/ui-film/pr-<number>/reel.webp --pass "$(date -u +%Y%m%dT%H%M%SZ)" --json
-```
-
-- `ok`: hold the record's `link`
-- `reel-too-large`: skip as `reel-too-large`, since GitHub would not render it
-- Any other `reason`: skip under it with the record's `message`
-
-## What goes back to the caller
-
-Hand `pr-evidence` one of two things and print nothing of your own:
-
-- The `link` from the push, which it passes to `canon pr evidence --reel`
-- A skip, as the reason and a one-line message, which its report names

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 })
-}