@erclx/canon 5.31.0 → 5.33.0

package/tooling/claude/seeds/.claude/hooks/review-post-scan.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+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
+}
+
+# Every Bash call reaches this line, so the command is read in one jq pass and
+# matched with a shell pattern before anything else costs a process.
+fields=$(printf '%s' "$input" | jq -r 'if .tool_name == "Bash" then [(.cwd // ""), (.tool_input.command // "")] | @json else empty end')
+[ -n "$fields" ] || exit 0
+
+cmd=$(printf '%s' "$fields" | jq -r '.[1]')
+case "$cmd" in
+*'gh api'*) ;;
+*) exit 0 ;;
+esac
+
+# A command that only mentions a post is not one: a heredoc writing a review
+# body that quotes the command, or a search whose pattern holds it. The string
+# is cut into the commands it runs, with heredoc bodies dropped and quoted text
+# left whole, and only a command that starts with `gh api` is read further.
+# Splitting on the separators outside quotes is what keeps `echo 'a; gh api'`
+# one command rather than two.
+IFS= read -r -d '' splitter <<'AWK'
+{ s = s (NR > 1 ? "\n" : "") $0 }
+function emit() {
+  gsub(/\n/, " ", seg)
+  sub(/^[ \t]+/, "", seg)
+  if (seg != "") print seg
+  seg = ""
+}
+END {
+  n = length(s); q = ""; seg = ""; nt = 0; i = 1
+  while (i <= n) {
+    c = substr(s, i, 1)
+    if (q == "'") { seg = seg c; if (c == "'") q = ""; i++; continue }
+    if (q == "\"") {
+      if (c == "\\") { seg = seg c substr(s, i + 1, 1); i += 2; continue }
+      if (c == "\"") q = ""
+      seg = seg c; i++; continue
+    }
+    if (c == "\\") { seg = seg c substr(s, i + 1, 1); i += 2; continue }
+    if (c == "'" || c == "\"") { q = c; seg = seg c; i++; continue }
+    if (c == "#" && (seg == "" || substr(seg, length(seg), 1) ~ /[ \t]/)) {
+      while (i <= n && substr(s, i, 1) != "\n") i++
+      continue
+    }
+    if (c == "<" && substr(s, i, 2) == "<<" && substr(s, i, 3) != "<<<") {
+      j = i + 2; dash = 0
+      if (substr(s, j, 1) == "-") { dash = 1; j++ }
+      while (substr(s, j, 1) ~ /[ \t]/) j++
+      oq = substr(s, j, 1)
+      if (oq == "'" || oq == "\"") j++
+      tag = ""
+      while (substr(s, j, 1) ~ /[A-Za-z0-9_]/) { tag = tag substr(s, j, 1); j++ }
+      if (oq == "'" || oq == "\"") j++
+      if (tag != "") { nt++; tags[nt] = tag; dashes[nt] = dash; i = j; continue }
+    }
+    if (c == "\n") {
+      emit(); 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
+    }
+    if (c == ";" || c == "|" || c == "(" || c == ")" || c == "`" || c == "&") {
+      if (c == "&" && (substr(seg, length(seg), 1) ~ /[<>]/ || substr(s, i + 1, 1) == ">")) { seg = seg c; i++; continue }
+      emit(); i++; continue
+    }
+    seg = seg c; i++
+  }
+  emit()
+}
+AWK
+
+# A block reaches the session through stderr, and stdout stays empty so nothing
+# unframed lands in the hook protocol.
+deny() {
+  printf '%s\n' "$1" >&2
+  exit 2
+}
+
+# The thread a review or a comment lands on: a review post or edit, and an issue
+# or pull request comment post or edit. A pull request's inline comments are left
+# out, since no shipped skill posts one.
+seg="[^/[:space:]'\"]+"
+end="(['\" ?]|\$)"
+endpoint="(pulls/$seg/reviews(/$seg)?|issues/$seg/comments|issues/comments/$seg)$end"
+starts_gh_api="^([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*((command|exec)[[:space:]]+)?gh[[:space:]]+api([[:space:]]|\$)"
+body_inline="[[:space:]](-f|-F|--field|--raw-field)[[:space:]=]*['\"]?body="
+body_file="[[:space:]](-F|--field)[[:space:]=]*['\"]?body=@([^'\"[:space:]]+)"
+
+# Reads one command already known to start with `gh api` and returns when it
+# has nothing to scan or the scan came back clean.
+check() {
+  local call=$1 method='' file='' cwd out code warnings
+
+  [[ $call =~ $endpoint ]] || return 0
+
+  # gh sends POST when a field flag is present and no method is named, and the
+  # explicit method wins when one is. A call naming neither is a read.
+  if [[ $call =~ (-X|--method)[[:space:]=]*([A-Za-z]+) ]]; then
+    method=$(printf '%s' "${BASH_REMATCH[2]}" | tr '[:lower:]' '[:upper:]')
+  elif [[ $call =~ [[:space:]](-f|-F|--field|--raw-field|--input)([[:space:]=]|$) ]]; then
+    method=POST
+  fi
+  case "$method" in
+  POST | PATCH | PUT) ;;
+  *) return 0 ;;
+  esac
+
+  if [[ $call =~ $body_file ]]; then
+    file=${BASH_REMATCH[2]}
+  elif [[ $call =~ $body_inline ]]; then
+    deny 'This review or comment post passes its body inline, so the label scan cannot read it. Write the body to a file in an earlier call and pass it as -F body=@<file>.'
+  else
+    return 0
+  fi
+
+  [ "$file" != '-' ] || deny 'This post reads its body from stdin, so the label scan cannot read it. Write the body to a file in an earlier call and pass it as -F body=@<file>.'
+
+  if ! command -v canon >/dev/null 2>&1; then
+    jq -nc '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:"The label scan did not run on this review or comment post, since canon is not on PATH. Run canon labels scan --body-file on the body once it is."}}'
+    exit 0
+  fi
+
+  # The payload's own cwd is the directory a relative path was written against.
+  # The project dir and this process's directory can each be a different worktree.
+  cwd=$(printf '%s' "$fields" | jq -r '.[0]')
+  [ -n "$cwd" ] || cwd=${CLAUDE_PROJECT_DIR:-.}
+  case "$file" in
+  /*) ;;
+  *) file="$cwd/$file" ;;
+  esac
+
+  # A body written by the same call does not exist when this hook runs, so the
+  # post would go out unread by the scan. Blocking is the only verdict that holds.
+  [ -f "$file" ] || deny "The body file $file does not exist yet, so the label scan cannot read it. Write the body in an earlier call, then post it."
+
+  # No --title: a review body carries none, and a title would grade it as an
+  # ordinary pull request body.
+  out=$(cd "$cwd" && canon labels scan --body-file "$file" 2>&1)
+  code=$?
+  [ "$code" -ne 0 ] || return 0
+
+  warnings=$(printf '%s\n' "$out" | grep -F '!')
+  [ -n "$warnings" ] || warnings=$out
+  if [ "$code" -eq 2 ]; then
+    deny "The label scan found text this post would publish. Fix the body file and post again.
+$warnings"
+  fi
+  deny "The label scan could not grade $file (exit $code). Fix what it reports and post again.
+$warnings"
+}
+
+commands=$(printf '%s' "$cmd" | awk "$splitter")
+while IFS= read -r line; do
+  [[ $line =~ $starts_gh_api ]] || continue
+  check "$line"
+done <<<"$commands"
+exit 0

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -18,12 +18,12 @@ case "$file" in
 *) exit 0 ;;
 esac
 
-# Four record folders, at either root. A skip list fixed at the old spelling
+# Three record folders, at either root. A skip list fixed at the old spelling
 # audits a project's own session records the moment the move reaches it, which
 # reports findings against prose nobody publishes.
 case "$file" in
-*.claude/.tmp/* | *.claude/memory/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
-*.canon/tmp/* | *.canon/memory/* | *.canon/review/* | *.canon/plans/*) exit 0 ;;
+*.claude/.tmp/* | *.claude/review/* | *.claude/plans/*) exit 0 ;;
+*.canon/tmp/* | *.canon/review/* | *.canon/plans/*) exit 0 ;;
 esac
 
 [ -f "$file" ] || exit 0

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

@@ -27,6 +27,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scratch-guard.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/review-post-scan.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/tooling/claude/seeds/CLAUDE.md

@@ -4,12 +4,10 @@
 
 ## Context
 
-- Before non-trivial work in a domain read `canon/context/<domain>.md`, and before touching a UI surface read `canon/wireframes/<surface>.md`. Pick which from the index anchors below.
+- Before non-trivial work in a domain read `canon/context/<domain>.md`. Pick which from the index anchor below.
 
 @canon/REQUIREMENTS.md
-@canon/ARCHITECTURE.md
 @canon/context/index.md
-@canon/wireframes/index.md
 
 ## Commands
 

package/tooling/claude/seeds/canon/REQUIREMENTS.md

@@ -1,18 +1,11 @@
 # Requirements
 
+[One line: the problem and who has it]
+
 Authoring guidance: the requirements standard.
 
 This record holds at most 600 words.
 
-## Problem
-
 ## Goals
 
 ## Non-goals
-
-## MVP features
-
-1. Feature: description
-2. Feature: description
-
-## Constraints

package/tooling/web/configs/e2e/screenshot.ts

@@ -58,7 +58,6 @@ const HOME_SECTIONS: CaptureSection[] = [
   { name: 'dispatch', selector: '#dispatch' },
   { name: 'workers', selector: '#workers' },
   { name: 'gate', selector: '#gate' },
-  { name: 'memory', selector: '#memory' },
   { name: 'evidence', selector: '#evidence' },
   { name: 'loop', selector: '#loop' },
   { name: 'merge', selector: '#merge' },

package/claude/skills/auto-ship/references/review-findings.md

@@ -1,20 +0,0 @@
----
-title: Review findings
-description: How auto-ship Step 7 splits the review receipt's findings by origin, which ones it repairs in place and which stop the chain, and the one-pass bound on the repair
----
-
-# Evaluate the review findings
-
-Step 7 of `auto-ship`. The session reads this file when Step 6 ran review rather than skipping it.
-
-Read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
-
-- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
-- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
-
-Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
-
-Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-
-This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.

package/claude/skills/bash-cli-script/REQUIREMENT.md

@@ -1,43 +0,0 @@
----
-name: bash-cli-script
-description: What a small non-interactive shell wrapper owes its caller, and the 100-line threshold past which the work belongs in TypeScript on Bun
----
-
-# Bash CLI script requirement
-
-## Gap
-
-Without this skill, a wrapper is written with an interactive tool's habits. Progress lines, icons, and color land on stdout, so the script stops composing in a pipe and the caller parses a spinner as data. The failure is invisible in a terminal and total in CI.
-
-The robustness failures are the ones that reach production. Without strict mode a failed stage inside a pipe exits zero and the script reports success on work that did not happen. An unset variable expands to nothing and a path built from it points somewhere nobody meant.
-
-The size failure is the slow one. A shell script that keeps growing past a wrapper's job turns into the long file nobody will touch, and the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) puts the line at 100: past it, the script is rewritten in a more structured language. Without a stop before generating, a session writes the long script first and the rewrite never happens.
-
-## Must
-
-- Stop before generating when the script will run past 100 lines, and route the work to TypeScript on Bun citing the style guide
-- Stop the same way on a request for prompts or a terminal UI, saying why
-- Open with the strict-mode preamble, so a failed stage stops the script
-- Keep data on stdout and put every log line, progress message, and error on stderr
-- Exit non-zero with actionable context through one error helper
-- Default every variable expansion rather than relying on it being set
-- Guard a command that returns non-zero on a valid empty result
-- Run the validation list before responding
-
-## Must not
-
-- Emit timeline frames, icons, color, or an interactive prompt
-- Put a log or progress line on stdout
-- Comment what the code already states
-- Rewrite an existing long shell file on contact, which is a rewrite decision rather than an edit
-
-## Guards
-
-- A script that will run past 100 lines stops before any of it is written, and the session writes it in TypeScript on Bun instead.
-- A request for prompts, a framed timeline, icons, or color stops with the same route.
-
-## Out of scope
-
-- A tool a person drives through prompts or a terminal UI, which is written in TypeScript on Bun
-- A GitHub Actions workflow file, which `ci-workflow` owns
-- Running, installing, or scheduling what it generates

package/claude/skills/bash-cli-script/SKILL.md

@@ -1,53 +0,0 @@
----
-name: bash-cli-script
-description: Generates a small non-interactive Bash wrapper for automation, CI, and agent-run tasks, with strict mode, logs on stderr, a clean stdout, and explicit exit codes. Stops at 100 lines and routes the work to TypeScript on Bun. Use when asked for "a shell script", "a wrapper script", an automation or CI script, a cron job, or a pipeline helper. Do NOT use for a tool that prompts a person or draws a terminal UI, or for a script that will run past 100 lines. Both are written in TypeScript on Bun.
-metadata:
-  family: generate
----
-
-# Bash CLI script
-
-Generate small non-interactive Bash wrappers for automation, CI, and agent-run workflows. Shell is for small utilities and simple wrappers, and anything larger is written in TypeScript on Bun, which runs a script about as fast as bash starts one.
-
-Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it and keep only what the task needs.
-
-## Guards
-
-- Estimate the script's length before writing any of it. When it will run past 100 lines, stop and write it in TypeScript on Bun instead, saying the threshold is the one the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) sets: "If you are writing a script that is more than 100 lines long ... you should rewrite it in a more structured language now". Stopping after generating wastes the draft and leaves a long script to argue against.
-- A request for interactive prompts, a framed timeline, icons, or color stops the same way. Say that a tool a person drives is past what a wrapper is for, and offer the TypeScript route rather than generating a script with prompts.
-- Editing an existing shell file already over 100 lines is not a new script. Edit it in place without growing it, and flag it for a rewrite rather than rewriting it on contact.
-
-## Script setup
-
-- Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
-- Do not rely on unset variables. Use `${VAR:-default}`.
-
-## Output contract
-
-- Write data to stdout. Write logs, progress, and errors to stderr.
-- Keep stdout clean so the script composes in a pipe.
-- Do not emit timeline frames, icons, or color.
-
-## Error handling
-
-- Define `die()` that prints an error to stderr and exits non-zero.
-- Include actionable context in error messages.
-- Guard commands that return non-zero on a valid empty result with `|| true`.
-- Set explicit exit codes. Reserve 0 for success.
-- Read a called command's machine-readable record where it emits one. An exit status separates success from failure and never names which failure, so a script routing on the reason reads the record and keeps the exit for the pass-fail decision alone.
-
-## Code style
-
-- Quote variables in expansions and test brackets.
-- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
-- Use 2-space indentation.
-
-## Validation
-
-Before responding, verify:
-
-- The script is 100 lines or fewer.
-- File starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
-- Data goes to stdout, logs and errors go to stderr.
-- No timeline frames, icons, or interactive prompts.
-- Errors exit non-zero with context through `die()`.

package/claude/skills/bash-cli-script/references/template.md

@@ -1,19 +0,0 @@
-# Wrapper template
-
-Copy this skeleton for a small non-interactive wrapper. Keep only the parts the task needs, and stop at 100 lines.
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-log() { printf '%s\n' "$*" >&2; }
-
-die() {
-  printf 'error: %s\n' "$*" >&2
-  exit 1
-}
-
-[ $# -ge 1 ] || die "usage: script.sh <arg>"
-
-log "starting"
-```

package/claude/skills/canon-operator/REQUIREMENT.md

@@ -1,62 +0,0 @@
----
-name: canon-operator
-description: Why the toolkit has one front door, what orienting on live catalogs prevents, and where it hands off
----
-
-# Canon operator requirement
-
-## Gap
-
-Without this skill, using the toolkit means knowing which skill to pick, and the user who most needs it is the one who cannot. A plain-language intent has no obvious owner among a dozen setup and sync skills, so the session guesses a command instead of resolving one, and a wrong guess installs into a project rather than reporting a mismatch.
-
-Two failures come from acting on memory. A session that names a stack or rule from what it remembers rather than from the live catalog runs against an entry that has been renamed or removed. And a session that edits a managed file by hand produces a change the next sync overwrites, which reads as the toolkit undoing work rather than as the edit having been made in the wrong place.
-
-The third failure is duplication. A front door that answers everything itself reimplements first-time detection and seed diffing inline, badly, beside the skills that already do both. The value of a router is that it stops at the handoff.
-
-A fourth failure sits between the router and what it runs. This skill executes the install and sync commands whose effect on an existing file is invisible from the command line, and the reference stating that effect per surface is named in the boundary below, which Claude Code never loads. The router therefore overwrites a customized golden config with the answer sitting one skill away and unread.
-
-The fifth failure is writing without re-checking. A domain sync brought a stricter standard into a target and left ten of its eleven context entries non-compliant in the same moment, and the run reported success because reporting the command was where its work ended. A person found the breakage afterwards by running an audit by hand. The audit that would have caught it is built and reachable from nothing the router offers, so one session held both the defect and its detector and connected neither to the other.
-
-The last failure is a section no route reaches. `## Route` maps an intent or a diagnostic finding to one lifecycle phase, so audit offers sitting below that table with no row naming them are unreachable by a correct reading. Two runs asked what the toolkit could measure and both took the scaffold handoff, the row the table declares. A route in settles half of it, since a project carrying a context folder and no installed domain fires the scaffold row and two audit conditions at once, and a body ranking neither leaves the choice to whichever the session read last.
-
-## Must
-
-- Orient on the toolkit's own docs and the live catalogs before acting
-- Map the stated intent to one lifecycle phase, then either run the simplest command that satisfies it or hand off
-- Resolve every stack, rule, and standard name from a catalog at runtime
-- Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
-- Read the overwrite contract from the body before any install or sync, and name each surface it lists as overwritten before running one
-- Read the reverse walk beside the forward sections, so a folder the toolkit stopped shipping reaches the user
-- Read `unmovedSurfaces` from the report itself, since the drift status ignores it by design, and name `canon migrate surface-roots` without running either form
-- Name an unmigrated domain's root and install path for the user to move themselves, since no skill covers the move
-- Route a measurement intent to the audit offers from the route table itself, rather than leaving the section reachable only by reading past the table
-- Rank a lifecycle row against the audit offers where the route table itself states it, so a session acting on the lifecycle row reads the ranking without opening the section being ranked
-- Offer every audit whose surface the target carries, and offer none whose surface it lacks
-- Hand off an audit that is a skill rather than a command, since the execute contract governs a CLI run and says nothing about a skill's own guards
-- Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
-
-## Must not
-
-- Edit a managed file by hand instead of running the CLI that owns it
-- Reimplement a flow another skill owns
-- Hardcode a catalog name
-- Move, delete, or name a command against a folder in `unclaimed`. The toolkit stopped claiming the path and only the user knows whether the project owns what sits there
-- Run an audit the user did not pick, which turns a front door into a full sweep
-- Refuse to finish an operation over an audit finding, since every audit reports judgments beside facts and a router that stops on one is a router a target works around
-- Auto-trigger. It is a door the user opens, and a router that fires on its own routes requests nobody made.
-
-## Guards
-
-- An intent matching a deep flow hands off rather than running a shallow version of it, since a partial scaffold is harder to recover from than none
-- An ignore-only fix on an unmeasured tooling report stops, names which cause applies, and names the command answering that cause. Unmeasured has several causes and they do not share a remedy, so one suggested command is wrong for at least one of them. No cause asks the user to supply a stack name, and none reads the zero counts under an unmeasured report as a clean target.
-- A re-check with no earlier report to compare against says the write ran without a baseline, rather than describing the target from scratch
-- A report missing a field this skill reads names the CLI version as the cause and reports that section as unread. Neither an absent key nor a hand-rolled substitute for it may be reported as a finding, since the first reads as a clean target and the second reaches a verdict only the field's attribution can make
-
-## Out of scope
-
-- First-time scaffold of a fresh project: `target-setup`
-- Seed and preamble drift in installed files: `seed-sync`
-- Governance rule install and index bootstrap: `target-setup`, on its `gov` and `indexes` phases
-- What a given sync overwrites once it runs: `canon-cli`
-
-That last contract carries no row for the governance install this skill routes to, so the overwrite `Must` above reads nothing at one of its own destinations. The row belongs to the skill owning the table. This file records the silence rather than answering it, since a rule written here for a silent contract teaches a session that silence means safe.

package/claude/skills/canon-operator/SKILL.md

@@ -1,113 +0,0 @@
----
-name: canon-operator
-description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `canon` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup and seed drift to seed-sync.
-disable-model-invocation: true
-metadata:
-  family: setup
----
-
-# Canon operator
-
-Front door to the toolkit. Orient first, then run the simplest operation that satisfies the intent or hand off to the owning skill. Never bypass `canon` to edit managed files by hand.
-
-## Orient
-
-Run these from the target project root, in parallel, before acting:
-
-- `canon docs list`: the index of toolkit reference docs
-- `canon docs agents`: the CLI command catalog and invocation contract
-- `canon docs projects`: the scaffold, add-a-domain, and sync lifecycle
-
-Load a domain doc with `canon docs <topic>` only when the intent touches that domain. Read the live catalog for any domain you act on with `canon <domain> list --json`. Never hardcode stack, rule, or standards names.
-
-## Diagnose
-
-Run `canon sync --check . --json` before routing. It reports what a target is behind on across every surface, so the intent comes from the project state rather than from the user having to know it already. Skip only when the user named a single operation to run.
-
-Read eight fields off the report and carry each to `## Route`:
-
-- `unmigrated`: a domain sitting at the root layout with nothing under `.claude/`. The most urgent finding, because that domain reports no drift of its own while being entirely behind
-- `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own, so this routes to `canon:target-check` for the full per-domain reading rather than ending at the report
-- `unmovedSurfaces`: a surface held only at its `.claude/` spelling, each entry carrying `rel` and `movesTo`. Every other field reads clean for such a target, and the report's drift status ignores it by design, so read the array itself rather than an exit status
-- `seeds`: entries are `matching`, `stale`, `drifted`, or `missing`. Anything but `matching` needs the seed handoff
-- `domains[].entries`: per-file `stale`, `customized`, `stranded`, and `orphaned` as before, plus `retired` for a rule the toolkit no longer ships, which the next sync deletes
-- `reverse`: what the target holds that no live catalog claims. `unclaimed` lists folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`. Act on the first two and leave `project` alone, which history proved the project owns
-- `historyUnavailable` on a domain, on `seeds`, or on `reverse`: nothing could be dated, so treat every difference as unverified and say so rather than reporting a file as untouched. It is set on `reverse` when the toolkit itself ships without history, which is the registry-install case, so the walk found nothing rather than finding a clean target
-- `tooling`: read `measured` first. Every count under it is zero when it is false, which is an absence of measurement rather than a measured zero. Past that, `chain` names the stacks the install resolved, nearest first, and `counts.gitignore` counts the managed ignore entries the target is missing.
-
-State what the report found in one line per finding before acting on any of it.
-
-An `unmovedSurfaces` key the report does not carry at all is likewise a CLI predating the field rather than a target with nothing to move. Say the section was unread and name the installed CLI version as the cause.
-
-A `reverse` key the report does not carry at all is a CLI predating the field rather than a target with nothing unclaimed. Say the walk did not run and name the CLI version as the cause. Reading the absent key as an empty answer reports a clean target to a project nobody has looked at, and answering it from a filesystem walk of your own is worse, since that reaches a verdict the attribution the field carries is the only thing entitled to make.
-
-## Route
-
-Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act.
-
-The two can name different rows, and a reply answers both rather than picking one. Run or hand off what the finding names, then answer the intent in the same reply. A measurement intent therefore reaches the audit offers below even on a target whose diagnostic found scaffold work, which is the case a session leaving from the scaffold row would otherwise never read.
-
-- A domain in `unmigrated`: name it, the root path, and the install path. No command moves it, so the user runs the relocation themselves
-- Anything in `superseded`: name which files and what replaced them, then hand off to `canon:target-check`, which reports and never moves or deletes the file
-- Anything in `unmovedSurfaces`: name `canon migrate surface-roots`, which only reports its plan until `--write` is passed, with each entry's `rel` and `movesTo`, and run neither form, since the move rewrites tracked paths
-- A folder in `unclaimed`: name it and the attribution it carries. No command moves it and the content may be the project's own, so the decision is the user's
-
-- First-time scaffold of a fresh project: hand off to `target-setup`
-- Governance rules for the project stack: hand off to `target-setup`, which installs them alone on its `gov` phase
-- Bootstrap the `index.md` system: hand off to `target-setup`, which bootstraps it on its `indexes` phase
-- Seed or standards drift in `CLAUDE.md` or `.claude/` preambles: hand off to `seed-sync`
-- Install one rule: run the domain `install` command
-- Sync one domain or every installed domain: run `canon <domain> sync` or `canon sync`
-- Fix only the ignore entries of the installed stack: run `canon tooling inject --gitignore <stack>`
-- Measure a surface without changing it: offer the audits under `### Audits`
-- Browse what is available: run `canon <domain> list`
-
-### The ignore-only row
-
-The ignore-only row runs on a measured tooling report alone, so `measured` decides before `chain` is read at all. A false one splits three ways. Report tooling as unmeasured in each, name the cause, and run nothing, since the zero counts underneath are unmeasured rather than clean:
-
-- An empty `chain` at a workspace root, which carries `pnpm-workspace.yaml` or a `workspaces` key in `package.json`: no chain is recorded there by design, since one would guess at what the packages hold. Name `canon tooling sync <stack> <path>` against a package.
-- An empty `chain` anywhere else: no tooling install is recorded, so name `canon tooling sync` as the command that records one rather than asking the user for a stack.
-- A `chain` carrying names: this toolkit no longer ships those stacks. Name them, since injecting would write against a retired name.
-
-On a measured report, take `<stack>` from the first name in `tooling.chain`, which records the stack nearest the target. Inject re-resolves that leaf's own chain, so a target whose recorded chain is shorter receives the entries from the layer its install skipped. Say so before running it.
-
-### Audits
-
-Five audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
-
-A lifecycle row and these offers fire together on a project carrying a context folder and no installed domain, which is the ranking the preamble states. Scaffold work on a target with nothing installed is real work, so an audit offered instead of it answers a question nobody asked, while an audit dropped in favor of it loses the one the user did.
-
-- `canon/context/` present: offer `canon context audit`
-- A record folder present under `.claude/`, one of `plans`, `groundwork`, `intake`, or `memory`: offer `canon records validate <kind>` for each one found
-- Markdown that git lists: offer `canon markdown audit`
-- TypeScript or shell source present: offer `canon comments scan`
-- A `package.json` script that serves an interface, one of `dev`, `preview`, `serve`, or `start`: offer `ux-measure`
-
-An audit offered against a surface the target lacks reports an empty run as a finding, which is the same defect as never offering it at all. Check the surface before naming the command.
-
-The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the five rows read alike, and the row needs no gate beyond it.
-
-The last row is a skill handoff rather than a command, so `## Execute` does not govern it. Hand it off and stop, the way a lifecycle row hands off. Its condition reads a serving command rather than a source folder, since that skill measures what a browser receives and never opens the tree behind it. It carries a second condition this skill cannot read, which is a browser harness the project already installed, and the skill itself reports what it needs when it finds none. Testing for that here would put the detection in two places and let this one answer stale.
-
-## Execute
-
-For operations this skill runs directly:
-
-- Read the catalog first with `canon <domain> list --json`, then match against project context
-- Read the `canon-cli` skill before any install or sync, and warn the user by name about each surface it lists as overwritten. A command name says nothing about what it does to a file already there, and this skill is the one running it.
-- Run the CLI with `CANON_NON_INTERACTIVE=1` so it skips prompts. The tool permission dialog is the confirmation gate.
-- Report the command run and what changed. Emit the full relative path for any file written.
-- Re-run `canon sync --check . --json` after any operation that wrote, and compare it against the report `## Diagnose` read before acting
-- Report the fields that moved and name the write that moved each one. Do not restate the second report, since the value sits in the difference alone.
-- State a field that moved the wrong way and leave it for the user to decide on. The re-check reports and never repairs.
-
-A write can leave a target worse in a field the write never named, which stays silent while the operation itself succeeds. The re-check is what makes that visible, so it runs before the operation is reported as done.
-
-The comparison needs the earlier report. When `## Diagnose` was skipped because the user named a single operation, say the write ran with no baseline rather than describing the target from scratch, which would attribute differences another session made to this run.
-
-## Boundaries
-
-- Run `canon`. Never reimplement its install or sync logic, and never edit managed files like rules, configs, or seeds by hand.
-- Hand off the deep flows. Do not duplicate `target-setup` detection or `seed-sync` part-diffing inline.
-- Resolve names from catalogs at runtime. A hardcoded name is a bug.

package/claude/skills/canon-rollout/REQUIREMENT.md

@@ -1,59 +0,0 @@
----
-name: canon-rollout
-description: Why one skill carries both roles of an outbound wave, and where its boundary sits against the seven skills that operate inside a target
----
-
-# Canon rollout requirement
-
-## Gap
-
-Without this skill, a toolkit change reaches its consuming projects by hand. One measured pass across four targets took four hand-written `cd <path> && claude --bg` invocations, each carrying a brief composed by hand from that project's review. Nothing enumerated the targets, nothing derived the brief, and nothing applied a convention across the set.
-
-The conventions were already settled and reached none of the four. The branch and title shape was answered and reconfirmed, and the four pull requests carried four titles across two scopes, neither of them the settled one, with three naming the toolkit in the half of the shape that withholds it. A convention nothing applies holds only where somebody remembers it.
-
-The return leg dead-ends outside this repository. A review that posts a finding on a target's pull request has to reach the session holding that branch, and every dispatch guessed instead. All four sessions that opened those pull requests were still alive holding their worktrees hours later, two fresh addressers were sent over them, one refused on the worktree lock, and one cut a second worktree on the same branch, which would have put two sessions pushing to one ref.
-
-A wave ends without telling the operator what to do. Reading where four targets stood took a hand-written shell loop over four repositories, re-run three times as reviews landed, and every status line it produced named a repository and a number and no link. Merging is the one act only the operator performs, and they reached each result by navigating to it by hand.
-
-A worker's reply reads as done when it is not. One pull request's fix for two minor findings closed both and introduced four more, all in prose the fix added, including a claim about a workflow that runs on a trigger it does not declare. A loop that closes a target on the worker's word merges that.
-
-## Must
-
-- Enumerate the targets from the record the install writes, with the sweep as the fallback and its stated bound read before any count is trusted, since a hand census of this population was wrong in both directions at once
-- Write the branch and the title from a fixed shape rather than leaving either to the dispatched session, since the settled convention reached none of four hand-driven repairs
-- Carry one line in each target's body naming the toolkit as the source and where to change the content upstream, since a reader in that repository has no other route to the fact that a local edit is lost at the next wave
-- Name no toolkit version in any target's body, since the install stamp in that target already records `syncedAt` and a sha256 per synced file and a version string is the copy that goes stale
-- Dispatch one worker per target, with the branch checked as unclaimed in that target before the launch
-- Branch from the clone that is current rather than from whichever the record names first, since a working copy answers what that machine last pulled rather than what the target holds
-- Resolve who holds a branch before dispatching an addresser, and dispatch a fresh one only where the resolver reports the owning session gone
-- Address every finding whatever its severity, and close a target only when a narrow re-review posts `## Review closed`
-- Name a pull request URL on every line that reports a target, at dispatch and at hand-back both
-- Close a wave by naming every target with its URL, review heading, CI state, and what is owed, the targets needing nothing included
-
-## Must not
-
-- Merge anything, in either role, at any size. The operator holds that gate over every role rather than as a setting on a wave.
-- Reimplement what `canon targets list`, `canon targets pulls`, or `canon sessions list --repository` already answers. Each is a shipped verb this body reads under `CANON_NON_INTERACTIVE=1`.
-- Restate the in-target diagnosis and routing that `canon-operator` owns, or the review, address, and worktree procedures the three skills named below own
-- Read or write this repository's task board. The board is `role-orchestrator`'s subject and a wave is not a row on it.
-- Bound the review and address loop with a count. The bound was declined with its failure mode stated, and what guards the loop is the orchestrator reviewing every round itself.
-- Edit a managed file in a target by hand rather than through the `canon` verb that owns it
-- Be a skill nothing invokes but its author typing the name. Nothing else routes to it, since it carries `disable-model-invocation: true` and no sibling body names it, so a wave that only ever runs when somebody types the name is the signal that the loop never replaced the hand-driven pass it was built against.
-
-## Guards
-
-- `gh` absent: stop, since no target's pull request can be read or opened
-- The target index reads as unknown with no sweep behind it: stop and name the reason, rather than reporting a population of zero
-- The claim check refuses or comes back with either readability flag false: treat the target as unverified rather than clear and hand it to the operator
-- Every clone of a target is behind its remote: refuse that target rather than branching from a stale base
-- More than one session holds a target's branch: report the ambiguity and stop, rather than sending findings to whichever row came first
-
-## Out of scope
-
-- This repository's own board, queue, and worker dispatch, which `role-orchestrator` holds
-- The role a session building one branch under one plan in this repository takes, which `role-worker` holds. A rollout worker does not take it, since that body resolves session scratch against a main worktree root a target does not carry.
-- Entering the worktree, which `session-worktree` owns, including the branch collision tests it runs before entry
-- Diagnosing what a target is behind on and routing each finding to its command, which `canon-operator` owns
-- Posting a review to a pull request and moving its heading, which `review-pr` owns
-- Answering a posted review inside the target, which `review-address` owns
-- The commit and the pull request mechanics, which the `git-*` family owns