@erclx/canon 4.0.0

package/claude/skills/bash-script/references/patterns.md

@@ -0,0 +1,349 @@
+# Bash script patterns
+
+Code templates for the `bash-script` skill. Copy verbatim, keeping only the colors and functions the script uses.
+
+## Timeline structure
+
+```plaintext
+┌                    # Start boundary (alone on its own line)
+│ Title              # Script or context title (immediately after ┌)
+│                    # Persistent vertical line (grey)
+├ Section Branch     # Section headers (no diamond)
+│ ✓ Log message      # Info/success logs
+│ ! Warning          # Warning logs
+│ ✗ Error            # Error logs
+└                    # End boundary
+```
+
+## Color palette
+
+Define only the colors the script uses from this set:
+
+```bash
+GREEN='\033[0;32m'      # Success/Active
+RED='\033[0;31m'        # Error/Delete
+YELLOW='\033[0;33m'     # Warning
+WHITE='\033[1;37m'      # Active text
+GREY='\033[0;90m'       # Timeline/Inactive
+CYAN='\033[0;36m'       # Optional accent
+MAGENTA='\033[0;35m'    # Optional highlight
+NC='\033[0m'            # Reset
+```
+
+## Timeline lifecycle
+
+Define `open_timeline` and `close_timeline`. Call `open_timeline "Title"` at the start of `main()`, then register `close_timeline` as the EXIT trap. The trap guarantees `└` prints on every exit path: normal completion, `exit 1` from cancellation, or unexpected errors. Do not print `└` manually anywhere else.
+
+```bash
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+```
+
+Register the trap inside `main()` right after opening:
+
+```bash
+open_timeline "Script title"
+trap close_timeline EXIT
+```
+
+## Logging
+
+All log functions include the `│` prefix and write to stderr.
+
+```bash
+log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
+log_warn()  { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2; }
+log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
+log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
+log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
+log_rem()   { echo -e "${GREY}│${NC} ${RED}-${NC} $1" >&2; }
+```
+
+## Section headers
+
+Use `log_step` for every section header, including the first. It emits a leading blank `│` line to separate the banner from the first section and to give breathing room between subsequent sections:
+
+```bash
+open_timeline "Script title"
+trap close_timeline EXIT
+
+log_step "Deploy"
+log_step "Verify"
+```
+
+Renders as:
+
+```plaintext
+┌
+│ Script title
+│
+├ Deploy
+...
+│
+├ Verify
+...
+└
+```
+
+## Interactive prompts
+
+Both prompts transition `◆` to `◇`, guard against non-TTY stdin with `[ -t 0 ]`, and write UI to stderr.
+
+```bash
+ask() {
+  local prompt_text=$1
+  local var_name=$2
+  local default_val=$3
+  local input=""
+  local char
+  local display_default=""
+  if [ -n "$default_val" ]; then
+    display_default=" (${default_val})"
+  fi
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
+  while IFS= read -r -s -n1 char; do
+    if [[ $char == $'\x1b' ]]; then
+      read -rsn2 -t 0.001 _ || true
+      echo -ne "\r\033[K" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
+      if [ -n "$input" ]; then
+        input="${input%?}"
+        echo -ne "\b \b" >&2
+      fi
+    elif [[ -z "$char" ]]; then
+      break
+    else
+      input+="$char"
+      echo -n "$char" >&2
+    fi
+  done
+  [ -z "$input" ] && input="$default_val"
+  echo -ne "\r\033[K" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
+  export "$var_name"="$input"
+}
+```
+
+```bash
+select_option() {
+  local prompt_text=$1
+  shift
+  local options=("$@")
+  local cur=0
+  local count=${#options[@]}
+
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+
+  echo -ne "${GREY}│${NC}\n${GREEN}◆${NC} ${prompt_text}\n" >&2
+
+  while true; do
+    for i in "${!options[@]}"; do
+      if [ "$i" -eq "$cur" ]; then
+        echo -e "${GREY}│${NC}  ${GREEN}❯ ${options[$i]}${NC}" >&2
+      else
+        echo -e "${GREY}│${NC}    ${GREY}${options[$i]}${NC}" >&2
+      fi
+    done
+
+    read -rsn1 key
+    case "$key" in
+      $'\x1b')
+        if read -rsn2 -t 0.001 key_seq; then
+          if [[ "$key_seq" == "[A" ]]; then cur=$(( (cur - 1 + count) % count )); fi
+          if [[ "$key_seq" == "[B" ]]; then cur=$(( (cur + 1) % count )); fi
+        else
+          echo -en "\033[$((count + 1))A\033[J" >&2
+          echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+          exit 1
+        fi
+        ;;
+      "k") cur=$(( (cur - 1 + count) % count ));;
+      "j") cur=$(( (cur + 1) % count ));;
+      "q")
+        echo -en "\033[$((count + 1))A\033[J" >&2
+        echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+        exit 1
+        ;;
+      "") break ;;
+    esac
+
+    echo -en "\033[${count}A" >&2
+  done
+
+  echo -en "\033[$((count + 1))A\033[J" >&2
+  echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${WHITE}${options[$cur]}${NC}" >&2
+  SELECTED_OPTION="${options[$cur]}"
+}
+```
+
+## Help system
+
+```bash
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} ./script.sh [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}│${NC}    [flag]        ${GREY}# [Description]${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+```
+
+## Error handling helper
+
+```bash
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  if ! eval "$cmd"; then
+    log_error "$err_msg"
+  fi
+}
+```
+
+## Full script structure
+
+```bash
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+[Color definitions - only used colors]
+
+[Function definitions - only needed functions]
+
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+
+check_dependencies() {
+  [Verify required tools installed]
+}
+
+main() {
+  check_dependencies
+
+  open_timeline "Script title"
+  trap close_timeline EXIT
+
+  log_step "First section"
+  [Script logic with timeline maintained]
+
+  trap - EXIT
+  echo -e "${GREY}└${NC}\n" >&2
+  echo -e "${GREEN}✓ Final success message${NC}"
+}
+
+main "$@"
+```
+
+## Worked example
+
+```bash
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
+log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
+log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
+log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
+
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+
+ask() {
+  local prompt_text=$1
+  local var_name=$2
+  local default_val=$3
+  local input=""
+  local char
+  local display_default=""
+  if [ -n "$default_val" ]; then
+    display_default=" (${default_val})"
+  fi
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
+  while IFS= read -r -s -n1 char; do
+    if [[ $char == $'\x1b' ]]; then
+      read -rsn2 -t 0.001 _ || true
+      echo -ne "\r\033[K" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
+      if [ -n "$input" ]; then
+        input="${input%?}"
+        echo -ne "\b \b" >&2
+      fi
+    elif [[ -z "$char" ]]; then
+      break
+    else
+      input+="$char"
+      echo -n "$char" >&2
+    fi
+  done
+  [ -z "$input" ] && input="$default_val"
+  echo -ne "\r\033[K" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
+  export "$var_name"="$input"
+}
+
+check_dependencies() {
+  command -v npm >/dev/null 2>&1 || log_error "npm not installed"
+}
+
+main() {
+  check_dependencies
+
+  open_timeline "Project Setup"
+  trap close_timeline EXIT
+
+  ask "Project name?" "PROJECT_NAME" "my-app"
+
+  log_step "Installing dependencies"
+  npm install vite
+  log_add "vite@latest"
+
+  log_info "Setup complete"
+  echo -e "\n${GREEN}✓ Project created successfully${NC}"
+}
+
+main "$@"
+```

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

@@ -0,0 +1,41 @@
+---
+name: canon-cli
+description: Why the overwrite contract is stated before a sync runs, and why the skill reads rather than executes
+---
+
+# Canon cli requirement
+
+## Gap
+
+Without this skill, a session runs a `canon` sync and finds out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
+
+The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a standards install overwrites every standard in a project that only needed the two it had drifted on. The user learns which category a file was in by losing the edit.
+
+The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
+
+Being reachable is a separate problem from being right. This is a pure reference whose moment happens inside another skill's run, so nothing brings it up unless a body names it. Three sibling requirement files named it and routed nothing, because Claude Code loads `SKILL.md` as the entry and never opens the sibling. A route lives in a body or it does not exist, and a fourth requirement mention would repeat the same defect.
+
+The two bodies now carrying an inline pointer are `claude-seed-sync` and `canon-operator`, each at the point it runs or prints an overwriting command.
+
+## Must
+
+- State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
+- Warn about a destructive run before it happens, naming the surface that will be lost
+- Name the section-preserving path for a standard or seed the project has customized
+- Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
+
+## Must not
+
+- Run any `canon` command. The skill is read before acting.
+- Restate the full semantics. It is a target-session summary and the detail lives with its owner.
+- Take a mention in a sibling's requirement file as an inbound route. The three bodies named in the gap above carry the pointer, and adding a fourth means editing that body rather than its requirement.
+
+## Guards
+
+- A surface or command the contract does not cover routes to the context docs rather than to an inference from a similar row
+
+## Out of scope
+
+- Executing the sync, which the user runs or `canon-operator` routes
+- Reconciling a customized seed section by section: `claude-seed-sync`
+- Deciding which stack, rule, or standard a project should install, which the setup skills resolve from live catalogs

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

@@ -0,0 +1,103 @@
+---
+name: canon-cli
+description: Reference for what canon sync and install commands overwrite, merge, or leave untouched in a target project. Use before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`, or when asked "will this overwrite my changes". Do NOT use to run the commands, only to know their effect.
+---
+
+# Toolkit CLI contract
+
+What each `canon` sync or install command does to existing files in a target project. Consult before running one, then warn the user about anything destructive. This skill is reference only. It does not run commands.
+
+## Overwrite contract
+
+| Surface                                                  | Command              | Effect on existing files                                                    |
+| -------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
+| Golden configs, listed in full below                     | `canon tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                 |
+| Dictionary seeds (`.cspell/*.txt`)                       | `canon tooling sync` | Merged and sorted. Existing terms preserved.                                |
+| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `canon tooling sync` | Copy-once. Dropped on first install, untouched after.                       |
+| Standards                                                | none                 | Nothing installs. `canon standards <name>` reads and never writes.          |
+| Seed docs and `CLAUDE.md`                                | `canon claude init`  | Skipped when present. Never overwritten.                                    |
+| Seed docs                                                | `canon claude sync`  | Never touched. Only `.gitignore` is written.                                |
+| Stack references                                         | none                 | Nothing installs. `canon tooling reference <stack>` reads and never writes. |
+| `.gitignore`, deps, scripts                              | any sync             | Additive. Existing entries preserved. Deps re-pin on major skew.            |
+| Generated `index.md`                                     | any sync or regen    | Rewritten from target state. Hand edits are lost.                           |
+
+## What a tooling sync can overwrite
+
+A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the CI workflow, the git hooks, the end-to-end harness, the shell scripts under `scripts/`, and the editor settings, alongside the linters and compilers a reader expects. A stack inherits its parent's configs, so syncing `astro` also writes everything `web` and `base` hold.
+
+Run `canon tooling sync <stack> <target> --check` for the list resolved against a real target. It reports every path and writes nothing. The list below is what the stacks hold as shipped, before any chain resolution.
+
+<!-- generated:tooling-paths -->
+
+### astro
+
+- `astro.config.mjs`
+- `eslint.config.js`
+- `playwright.config.ts`
+- `tsconfig.json`
+- `vitest.config.ts`
+
+### base
+
+- `.editorconfig`
+- `.github/pull_request_template.md`
+- `.github/workflows/verify.yml`
+- `.husky/commit-msg`
+- `.husky/post-merge`
+- `.husky/post-rewrite`
+- `.husky/pre-commit`
+- `.husky/pre-push`
+- `.prettierrc`
+- `.shellcheckrc`
+- `.vscode/extensions.json`
+- `.vscode/settings.json`
+- `commitlint.config.js`
+- `scripts/verify.sh`
+
+### python
+
+- `.coveragerc`
+- `.python-version`
+- `mypy.ini`
+- `pytest.ini`
+- `ruff.toml`
+- `scripts/verify.sh`
+
+### vite-react
+
+- `playwright.config.ts`
+- `tsconfig.json`
+- `vite.config.ts`
+- `vitest.config.ts`
+
+### web
+
+- `.github/workflows/verify.yml`
+- `.vscode/extensions.json`
+- `.vscode/settings.json`
+- `e2e/home.spec.ts`
+- `e2e/screenshot.ts`
+- `eslint.config.js`
+- `scripts/screenshot.sh`
+- `scripts/verify.sh`
+- `scripts/worktree-port.sh`
+- `src/test/setup.ts`
+
+<!-- /generated:tooling-paths -->
+
+## Rules
+
+- `canon tooling sync` writes nothing until `--write` is passed. A headless run without it reports and exits 1, so a script that forgets the flag fails rather than silently skipping the sync.
+- Run `--check` first when the project carries local edits to any path above. The report names each file it would replace, which is the warning the user needs before the write.
+- An interactive run still prompts. `--write` skips the prompt, and `--check` refuses to write even with a TTY.
+- Seeds are user-owned. Dictionary `.txt` files merge and sort. Other seeds are copy-once, so re-seeding a structured file means deleting it and syncing again.
+- No command writes a standard into a project. A `.claude/standards/` folder from an older toolkit is inert, and deleting it costs nothing.
+- For section-level customizations of a seed doc, use the `claude-seed-sync` skill, not `canon ... sync`. It diffs per section and preserves edits.
+
+## CLAUDE.md
+
+- `CLAUDE.md` is a copy-once seed. No `canon` sync command ever updates it. Reconcile it with the `claude-seed-sync` skill, which diffs the preamble and each section and preserves customizations by default.
+
+## Source of truth
+
+- Full semantics live in the toolkit's `.claude/context/tooling.md`, `.claude/context/standards/`, and `.claude/context/claude-plugin/`. This skill is the target-session summary. When they disagree, the context docs win.

package/claude/skills/canon-feedback-file/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: canon-feedback-file
+description: Why a toolkit defect is reported from session context alone, and what shipping through the CLI replaces
+---
+
+# Canon feedback file requirement
+
+## Gap
+
+Without this skill, a toolkit defect noticed inside a target project dies with the session. The user is told to mention it in the toolkit repository later, which means retyping a report they no longer have the context to write, so the defect is either reported badly or not at all.
+
+The report itself fails two ways. A block printed in chat needs a copy-paste into another repository, and a step that manual is skipped under any time pressure. A report that names no surface cannot be routed, because the toolkit acts on a plugin skill, a snippet, a CLI command, and a seed through different paths, and the difference is not recoverable from the symptom.
+
+The last failure is the session's own effort. Asked to report, a session starts diagnosing instead, searching the toolkit and reading its surfaces to find the cause. That spends the context the report was meant to capture cheaply, and it produces a diagnosis from a project that cannot see the toolkit's current source.
+
+## Must
+
+- Build the report from what the session already holds
+- Name the surface and its type, since the toolkit routes on that rather than on the symptom
+- Write the stated fallback for a field the session cannot fill, so an empty field reads as absent rather than as unreported
+- Ship through the CLI so the report lands without a copy-paste, and print the returned path on its own line
+- Offer the durable route for a report worth keeping across sessions and machines
+- Fall back to printing the block when the CLI is absent, so the report still exists
+
+## Must not
+
+- Probe the project, list files, grep, or read toolkit surfaces to enrich the report
+- Guess the surface type when the session is ambiguous. Ask one line.
+- Diagnose or fix, which needs the toolkit's source rather than the target's
+
+## Guards
+
+- Nothing in session context pointing at a toolkit issue stops, since a report assembled from nothing wastes the triage it reaches
+
+## Out of scope
+
+- Fixing the defect, which happens in the toolkit repository against its own source
+- Draining the queue this fills: `canon-feedback-triage`
+- Filing an issue against the current project: `git-issue`
+- Complaints about tooling the toolkit does not own

package/claude/skills/canon-feedback-file/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: canon-feedback-file
+description: Format a paste-back report about something broken, missing, or off in canon and write it directly to the toolkit's `.claude/review/feedback/` folder via `canon feedback`. Use when asked to "send this to the toolkit", "report this to canon", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate canon surfaces.
+---
+
+# Canon feedback file
+
+Format a `## Toolkit feedback` block from the current session, then ship it to the toolkit repo without manual copy-paste.
+
+## Guards
+
+- If nothing in session context points to a toolkit issue, stop: `❌ No toolkit issue in session context. Describe what broke, then re-invoke.`
+- If the surface type is ambiguous (snippet vs. plugin skill vs. CLI vs. seed), ask one line before formatting.
+- Do not probe the project, list files, grep, or read toolkit surfaces. Use only what the session already contains.
+
+## Step 1: build the block
+
+From the conversation so far, identify:
+
+- Target project name or path
+- Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI)
+- Specific toolkit file or name when the session cites one
+- Observed behavior
+- Expected behavior, or `unclear`
+- Repro details already in context (commands run, files touched), or `none`
+- Proposed fix when the user stated one, or `open`
+
+Format as a single fenced markdown block:
+
+```markdown
+## Toolkit feedback
+
+**From project:** <name or path>
+**Surface:** <type>, <file path or name>
+**Observed:** <one or two lines>
+**Expected:** <one or two lines, or "unclear">
+**Repro:** <commands or steps, or "none">
+**Proposed fix:** <one line, or "open">
+```
+
+Keep each field to one or two lines. Write the literal fallback shown above when a field has nothing.
+
+## Step 2: ship to the toolkit
+
+Detect whether `canon` is on PATH:
+
+```bash
+command -v canon >/dev/null 2>&1
+```
+
+If present, pipe the block to `canon feedback`. The CLI writes to its own repo's `.claude/review/feedback/feedback-<slug>-<ts>.md` and prints the absolute path on stdout:
+
+```bash
+cat <<'EOF' | canon feedback
+## Toolkit feedback
+
+...
+EOF
+```
+
+Report the printed path back to the user on its own line, in the form the project's instruction file sets under `## Output`.
+
+For a durable, cross-machine report instead of local scratch, add `--github`. The CLI opens a GitHub issue on the toolkit repo and prints the issue URL. It needs `gh` authenticated, and falls back to local scratch with a warning when `gh` is absent.
+
+```bash
+cat <<'EOF' | canon feedback --github
+## Toolkit feedback
+
+...
+EOF
+```
+
+Default to local scratch for a quick note. Use `--github` for a report worth tracking across sessions and machines.
+
+If `canon` is not on PATH, fall back: print the block in chat and tell the user `📋 Copy the block above into a toolkit-repo session.`
+
+## Notes
+
+- `canon feedback` resolves the toolkit root from the running `canon` binary's source location. If multiple toolkit clones exist on the machine, the first `canon` on PATH wins.
+- The destination `.claude/review/` is gitignored in the toolkit repo. Feedback lives as session scratch for the next toolkit-side triage, not as a durable archive.

package/claude/skills/canon-feedback-triage/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: canon-feedback-triage
+description: Why the feedback queue is read from GitHub rather than local scratch, and why triage routes instead of implementing
+---
+
+# Canon feedback triage requirement
+
+## Gap
+
+Without this skill, the feedback queue fills and nothing drains it. Reports arrive from projects the toolkit never sees, and a queue nobody reads on a schedule is the same as no queue. The local review folder looks like the right place to read, and it is the wrong one, because that content is per-machine session scratch that any cleanup removes.
+
+Triage fails three ways once it starts. Unrelated issues get batched into one branch, so review has to judge several unconnected changes at once and can approve none of them cleanly. An issue needing a plan gets implemented inline from a paragraph of description, which skips the step where scope is argued. And an issue whose report contradicts itself gets a guess rather than a question, so the fix addresses a defect nobody confirmed.
+
+The queue also fails to drain even when the work ships. A fix merged with no link back leaves its issue open, and the next triage re-reads work already done.
+
+## Must
+
+- Read the durable queue rather than local session scratch
+- Classify each issue in a fixed order and stop at the first match, stating the class and its one-line reason before routing
+- Route to the skills that own planning, branch naming, and the pull request body rather than restating them
+- Keep one issue to one branch and one pull request
+- Link a fix to its issue so merge closes it, and preserve that link when the body is regenerated
+- Ask on the issue when the report is unreadable, then move on rather than blocking the batch
+
+## Must not
+
+- Batch unrelated fixes into one branch
+- Implement a plan-worthy issue, which stops at the plan handed back to the user
+- Close an issue whose pull request has yet to merge
+
+## Guards
+
+- The `gh` CLI absent or unauthenticated stops, since the queue is unreachable
+- An empty queue reports nothing open rather than widening the label to find work
+
+## Out of scope
+
+- Filing new feedback: `canon-feedback-file`
+- Writing the plan a plan-worthy issue needs: `claude-feature`
+- Triage of issues carrying any other label, which surface here by design only under the feedback label