@erclx/canon 4.120.0 → 4.122.0

package/claude/skills/backlog-triage/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: backlog-triage
+description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create, archive, or decline one named task, which is `task-board`.
+---
+
+# Backlog triage
+
+A backlog only grows while nothing can decline a row. This pass reads every row against the current tree, files one verdict per row for the operator, and later applies what they approved.
+
+The record is an ordinary intake folder at `.canon/intake/<nn>-backlog-triage/`. Read `${CLAUDE_SKILL_DIR}/../../standards/intake.md` before writing any file in it, since it holds the item format, the frontmatter, the index shape, and the answer contract this skill is bound by. Read `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` before applying, since it holds the backlog, the ordering file, and the `Declined:` line.
+
+## Guards
+
+- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo.
+- If `.canon/tasks/backlog.md` does not exist at that root, stop: `❌ No backlog at .canon/tasks/backlog.md. Nothing to triage.`
+- Never fill a `You:` slot, and never read an empty one as agreement. Answering runs through `plan-intake-answer` or the operator's own edit, which is what keeps silence from deciding a row.
+- Branch on each `canon` record's `ok` and `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+## Step 1: detect the phase
+
+Run `canon intake list --json` and take the folders whose slug ends in `-backlog-triage`. Read the newest by ordinal. Where the installed binary carries no such subcommand, stop and report it, since opening a folder beside one awaiting apply leaves the first stranded and applying needs the same verb.
+
+- **No folder, or the newest is fully applied.** Run the file phase.
+- **Unread above zero.** Stop: `❌ <n> items in <slug> are unread. Run /canon:plan-intake-answer, then re-run this skill to apply.`
+- **Malformed above zero.** Stop: `❌ <n> items in <slug> carry no answer slot. Repair them in the cluster files before applying.`
+- **Every item answered, some not yet applied.** Run the apply phase.
+
+An item is applied once its task has moved under `.canon/tasks/declined/` or `.canon/tasks/archive/`, or once its live task file carries a `## Findings` line naming the folder slug. A task whose file sits in none of the three folders counts as applied only once `backlog.md` no longer names it, since its dangling line is the one thing apply has left to remove. Test that per item rather than trusting a count, since a run can stop partway. An item apply skipped for an unreadable answer stays unapplied, so the folder stays in the apply phase until the operator rewrites that answer.
+
+## File phase
+
+Writes only inside `.canon/intake/<nn>-backlog-triage/`, so it runs under any role, including a planner session.
+
+### Step 2: claim the folder
+
+Run `canon records ordinal intake backlog-triage --claim --json` and take its `name`. The verb creates the folder in the same act, so two sessions opening at once never share one. Where the installed binary carries no such subcommand, report it and stop rather than picking an ordinal by hand.
+
+### Step 3: read every row
+
+List each link in `.canon/tasks/backlog.md` and open its task file. Read its origin line (`Plan:`, `Groundwork:`, `Intake:`, or `Issue:`), its `## Outcomes`, and its `## Findings`. Read `.canon/tasks/priority.md` once, so a promote can name what sits at the bottom of `## Needs a plan`.
+
+A row whose link resolves to no file gets an item anyway, carrying `decline` and naming the missing path, since the backlog line is the only thing left pointing at it.
+
+### Step 4: measure each row
+
+Measure every claim the task makes against the tree and `git log` during this pass. Grep for the construct its defect names and count the sites, check whether each open outcome's behavior exists, and search the log for a commit or pull request that shipped it under another task. Never carry a figure from the task file forward as current, since the task states what was true when it was filed.
+
+Name the commit the pass measured against in the overview body.
+
+### Step 5: pick the verdict
+
+Keep and promote carry the burden of proof. A row nobody can argue for from this pass's measurement is declined.
+
+- **keep**: the defect or gap reproduces this pass, stated with a count or a path.
+- **promote**: it reproduces, and the thing it was waiting on has cleared, naming what cleared it.
+- **archive**: every open outcome is measured shipped, naming the commit or pull request per outcome position.
+- **decline**: anything else, including a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
+
+Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping.
+
+### Step 6: write the items
+
+Write one item per row in the intake item format, one cluster file per domain the task touches, numbered in read order. Head each item `### N. <task stem>` so apply can find the task from the heading alone.
+
+- `Problem:` states what this pass measured, with the count, path, or commit behind it
+- `Fix:` states what applying the verdict does to the board
+- `Worth it:` carries the verdict's reason in one clause
+- `Open:` reads `decline, archive, keep, or promote?` on every item
+- `Suggested:` opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
+- `Overlaps:` names a live board task that already carries the work, where one does
+- `You:` ships empty
+
+Write `00-overview.md` last, per the intake standard, with the verdict counts by token and an open-questions list linking each item. Where the pass runs out of context before the index, write `99-next-session.md` naming the last row filed, since a compaction drops the rest.
+
+## Apply phase
+
+Writes the board and task files. Refuses when this session's name starts with `planner-` or `worker-`: read it from `canon sessions list --self --json` before writing anything, and stop: `❌ Apply writes the board, which the <role> role bans. Run it from an operator or orchestrator session.` A refused or failed read proceeds, since it is indistinguishable from a solo project running no named sessions.
+
+Every write here is a main-root write. Route a change inside an existing file the way `session-worktree` states, and report it rather than proceeding silently when that skill does not resolve.
+
+### Step 7: read the answers
+
+Run `canon intake list <slug> --json` and read each item's `answer` and `suggested`.
+
+- An answer of `ok` takes the suggested verdict. A `suggested` that opens with no verdict token is malformed: report the item and skip it, never treating it as keep.
+- An answer opening with a verdict token overrides the suggestion. An override to archive names its own outcome positions, and one that names none is reported and skipped.
+- Any other answer, such as a free-text note, is reported and skipped. Never guess a verdict from prose.
+- An item already applied, by the test in Step 1, is skipped silently, which is what makes a re-run write nothing twice.
+
+### Step 8: run each verdict
+
+Take the task stem from the item heading. Every verdict leaves the folder slug on its task, which is how Step 1 and `task-board`'s unlinked-origin scan both see the folder as acted on.
+
+- **decline**: `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`. The verb clears the backlog line.
+- **decline on a missing file**: when the stem resolves to no file in `.canon/tasks/`, `declined/`, or `archive/`, the verb would refuse as `no-match`, so skip it. Drop the dangling line from `backlog.md` directly and report it as removed with no task behind it. Any other verdict on such an item is reported and skipped, since there is no file to keep, archive, or promote.
+- **archive**: `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`. Outcomes already closed report as closed rather than refusing, so archive still runs. Archive leaves `backlog.md` alone, so drop the task's backlog line once it succeeds, then append the `## Findings` line naming the evidence to the archived file.
+- **keep**: append the `## Findings` line naming what reproduced. The backlog line stays.
+- **promote**: move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, with a `Waiting on` cell stating what cleared and ending in `last`, then append the `## Findings` line.
+
+Write the `## Findings` line as `- <YYYY-MM-DD>, backlog triage <slug>: <verdict>, <evidence>`. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
+
+Before any promote, check the roster the way `task-board` step 4 does: a live session in this repository whose name starts with `orchestrator-` and whose `sessionId` is not this one. When one is found, write the `## Findings` line but not `priority.md` or `backlog.md`, and message that session with the row and its cell so it places the row itself.
+
+### Step 9: route on a refusal
+
+Report every refusal on its item and continue with the rest, since one row's refusal says nothing about another's.
+
+- `decline` refusing with `no-match`: the task already moved elsewhere. Report and skip. A missing-file item never reaches the verb, per Step 8.
+- `outcome` refusing, or `archive` refusing with `open-outcomes`: the verdict named too few positions. Report the positions still open and leave the row on the backlog. Never retry with guessed positions.
+- A promote whose row already sits in `priority.md`: report it, skip the move, and still write the `## Findings` line.
+
+Close with `canon tasks validate --json` and report every finding it raises against a row this run touched. After a shell write under `.canon/tasks/`, regenerate the index with `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`, since no hook fires on `Bash`.
+
+## Output
+
+File phase:
+
+```plaintext
+📂 Opened .canon/intake/<nn>-backlog-triage/
+
+**Filed:** <N> rows across <N> clusters, measured against <sha>
+**Suggested:** <n> decline, <n> archive, <n> keep, <n> promote
+
+Next: /canon:plan-intake-answer to answer the `You:` slots, then /canon:backlog-triage to apply
+```
+
+Apply phase, naming the path every write landed at:
+
+```plaintext
+✅ Applied .canon/intake/<nn>-backlog-triage/
+
+**Declined:** .canon/tasks/declined/<stem>.md
+**Archived:** .canon/tasks/archive/<stem>.md
+**Kept:** .canon/tasks/<stem>.md
+**Promoted:** .canon/tasks/<stem>.md, bottom of ## Needs a plan
+**Skipped:** <item>, <reason>
+```
+
+Drop a line that carries no rows.

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

@@ -7,7 +7,7 @@ description: Generates production Bash scripts with a visual timeline UI, state-
 
 Generate production-ready Bash scripts for DevOps and CLI workflows. Enforce strict formatting with a visual timeline UI and state-based interactivity.
 
-Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, interactive prompt, help-screen, and full-script code templates. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
+Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, help-screen, and full-script code templates, and `${CLAUDE_SKILL_DIR}/references/prompts.md` for the `ask()` and `select_option()` templates when the script prompts. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
 
 ## Guards
 

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

@@ -91,105 +91,6 @@ Renders as:
 └
 ```
 
-## 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

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

@@ -0,0 +1,100 @@
+# Bash script prompts
+
+Interactive prompt templates for the `bash-script` skill, read only when the script prompts. Copy verbatim, alongside the colors and logging functions from `patterns.md`.
+
+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]}"
+}
+```

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

@@ -17,7 +17,7 @@ One wave takes one toolkit change to every target and ends with a pull request p
 - The invocation or the launch prompt names the worker role, a target path, or both: worker. Skip to `## The worker role` and run no phase above it.
 - Neither is named: orchestrator. Run the three phases in order.
 
-The role is read off the prompt because nothing else carries it. A dispatched worker starts in the target's own checkout, which is a repository like any other from the session's side, so a test on the working directory answers the same for a worker in a target and an operator who invoked this from one. Reading the role wrong in that direction starts a second wave from inside a consuming project, which is why the dispatch below names the role and the path both rather than relying on either alone.
+The role is read off the prompt because nothing else carries it. A test on the working directory answers the same for a worker in a target and an operator who invoked this from one, and reading the role wrong starts a second wave from inside a consuming project.
 
 Do not invoke `canon:role-worker` from either role. That body states the role for a session building one branch under one plan in this repository, and it resolves session scratch against a main worktree root a target does not carry, so a rollout worker reading it hunts for a plan nobody wrote.
 
@@ -30,7 +30,7 @@ Do not invoke `canon:role-worker` from either role. That body states the role fo
 
 ## The fixed shape every target receives
 
-Every target in every wave takes the same branch and the same title, written from here rather than chosen per session. Four hand-driven repairs produced four titles across two scopes, neither of them this one, and three named the toolkit in the half of the shape that withholds it.
+Every target in every wave takes the same branch and the same title, written from here rather than chosen per session.
 
 - Branch: `chore/agents`, in every target and every wave.
 - Title: `chore(agents): <what changed in that target>`.
@@ -48,7 +48,7 @@ One branch name across every target is also what lets the return leg resolve. `c
 
 1. Pin the wave. Record the commit of this repository that the wave carries and name it in this session's own reports. Name it in no target's body.
 2. Enumerate. Run `canon targets list --json` under `CANON_NON_INTERACTIVE=1`, adding `--sweep <root...>` to reach targets installed before the index existed. Read the `bound` object back before treating any count as the population, since it names the roots walked, the depth, where the walk stopped, and what it could not read. The bound a sweep can never state is the machine, so a target on another one sits outside every answer it gives.
-3. Pick the clone that is current. A row carries every checkout of that project under `paths` and leads with the one a sync ran in, which records where an install happened rather than what the checkout holds today. Fetch each candidate, compare it against the origin's default branch, and dispatch into one that is level. Refuse one that is behind rather than branching from a stale base, since three clones read as still owing the repair in one census and every one of them was behind its remote and nothing else.
+3. Pick the clone that is current. A row carries every checkout of that project under `paths` and leads with the one a sync ran in, which records where an install happened rather than what the checkout holds today. Fetch each candidate, compare it against the origin's default branch, and dispatch into one that is level. Refuse one that is behind rather than branching from a stale base, since a stale clone reads as still owing a repair its remote already carries.
 
 ### Check, then dispatch
 
@@ -88,10 +88,10 @@ Report each dispatch by naming the target, the clone, the branch, the model, and
 
 1. Address every finding whatever its severity. A minor is a finding, and a reviewer calling one non-blocking does not close the pass that raised it.
 2. Resolve who holds the branch before dispatching anybody. Run `canon sessions list --branch chore/agents --repository <clone> --json` and read the count rather than the first row.
-   - A live session holds it: send that session the findings and name `canon:review-address` for it to run, which is step 7 of `## The worker role` and the step that session already stands at. Never name this skill in that message. This body carries `disable-model-invocation: true`, which blocks the `Skill` tool rather than only suppressing an auto-trigger, and a session acting on an inbound message reaches a skill that way and no other, so a message naming this one halts the address leg with the branch built and the findings unread. A launch prompt is the one route to a flagged body, which is why the dispatch above names this skill and this message must not. Assuming the worker was gone is what one hand-driven pass got wrong. All four sessions that opened those pull requests were still alive holding their worktrees hours later, and of two fresh addressers 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 live session holds it: send that session the findings and name `canon:review-address` for it to run, which is step 7 of `## The worker role` and the step that session already stands at. Never name this skill in that message. This body carries `disable-model-invocation: true`, which blocks the `Skill` tool rather than only suppressing an auto-trigger, and a session acting on an inbound message reaches a skill that way and no other, so a message naming this one halts the address leg with the branch built and the findings unread. A launch prompt is the one route to a flagged body, which is why the dispatch above names this skill and this message must not. Never assume the worker is gone, since a fresh addresser sent over a live one either refuses on the worktree lock or cuts a second worktree on the same branch.
    - No live session holds it: dispatch a fresh worker into that clone and brief it with the findings, since it holds none of the reasoning behind the diff.
    - More than one row: report the ambiguity and stop rather than picking among candidates.
-3. Re-review when the answer lands, scoped to the commits added since. A worker's reply never closes a target. One fix for two minor findings closed both and introduced four more, every one of them in prose that fix added, and a loop trusting the reply merges that.
+3. Re-review when the answer lands, scoped to the commits added since. A worker's reply never closes a target, since a fix can introduce findings of its own in the prose it adds.
 4. A target leaves the wave when a pass posts `## Review closed` and not before.
 5. Run until every target closes. No count bounds the loop. What guards it is this session reviewing every round itself, so it holds what each pass found and can see a target failing to converge, where a dispatched reviewer reads one pass and knows nothing of the one before it. A worker introducing a finding per fix has nothing mechanical stopping it, which is accepted rather than overlooked.
 
@@ -101,7 +101,7 @@ One session, one target, from the worktree entry to the merge of the branch it o
 
 1. Confirm the clone is current. Fetch, then compare against the origin's default branch. Report a checkout that is behind and stop, rather than branching from a stale base.
 2. Enter a worktree. Invoke `canon:session-worktree chore/agents`, which takes the branch as its tier 0 argument and enters a linked worktree inside this target. Branching in the checkout itself is what this avoids, since the operator may be working in it.
-3. Check what this target holds. Invoke `canon:target-check`, which reports per domain what the target carries against what the toolkit ships and repairs nothing. It runs before any repair so the wave reads one stated set of domains per target rather than whatever each session decided to examine.
+3. Check what this target holds. Invoke `canon:target-check`, which reports per domain what the target carries against what the toolkit ships and repairs nothing, so the wave reads one stated set of domains per target.
 4. Diagnose and repair. Invoke `canon:canon-operator`, which reads `canon sync --check . --json` and routes each finding to the command or the skill that owns it. Do not restate that routing here and do not edit a managed file by hand.
 5. Commit and open the pull request through `canon:git-commit` and `canon:git-pr`, handing each the fixed shape above rather than taking the title the generator derives from the diff.
 6. Announce as the pull request opens, carrying its URL, its number, and the branch, to whoever dispatched this session, sending it through `canon:session-relay`. That transition is the one moment only this session can observe.

package/claude/skills/context-fold/REQUIREMENT.md

@@ -0,0 +1,75 @@
+---
+name: context-fold
+description: What the planning-doc reconcile is for, the gaps it closes, and why the diff decides completion alone
+---
+
+# Context fold requirement
+
+## Gap
+
+Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A requirement or architecture decision that changed mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+
+A decision's verification anchor has the same shape of gap in the other direction. The reasoning keeps reading as current while the number it cites moves underneath, and an amendment written without an anchor leaves nothing recording which numbers were checked and which nobody has read since.
+
+A handoff file has the same shape of gap as an unmarked outcome. A page a learning workspace produced and an operator already picked a destination for sits in gitignored scratch until something lands it, and the session that produced it is gone by the time a branch exists to carry the write. Left unfolded it reads as promoted while the destination holds nothing.
+
+The receipt half of that sweep was missing entirely. A review receipt was deleted per shipped branch and a memory-review receipt was skipped, because the exclusion protecting the checklist and audit prefixes caught a third by accident. Nothing but an operator asking collected it, and a collection that waits on someone remembering to ask is one a folder outgrows, so the skipped population grew per shipped branch and never shrank until it was most of the folder.
+
+The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
+
+This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
+
+## Must
+
+- Name the context entries and the task board in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
+- Take completion from the diff and everything else from the session, since completion is a fact about the repository rather than about the conversation
+- Match an outcome on the behavior it names, never on a filename or a commit subject
+- Leave an outcome unchecked when the diff is ambiguous. An unmarked shipped outcome costs one manual edit and a wrongly marked one hides work that never happened.
+- Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
+- Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
+- Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
+- Write a decision to the domain context entry it constrains unless it fills an architecture slot, since reach admits nearly every decision to an always-loaded file
+- Merge or retire an architecture entry before adding one at the record's stated cap, and name which in the report, so the cap never turns into compressed prose or two decisions packed under one heading
+- Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
+- Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
+- Scan every memory-review receipt rather than the one matching this slug, since the skill that writes them runs after this one in the ship chain and a slug is unique per feature
+- Collect a memory-review receipt whose items are all decided, folding each skip into its memory entry first, since a declined item is recorded nowhere else and a promoted one is already in git
+- Leave a memory-review receipt holding a pending item, and report the count. A branch shipping is not an operator deciding what the receipt proposed.
+- Leave the current branch's review receipt alone, since the chain that wrote it cites it in its own closing line and this skill cannot read whether that citation is still live
+- Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
+- Take a promotion destination as already decided, since the operator confirmed it where the page was produced
+- Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
+- Apply a `REPLACE` or `HISTORY` finding, and a regex-decided `MOVE` finding, against the quote it names, report a model-decided `MOVE` finding naming the surface it belongs on rather than cutting it, or keep a finding with a one-line reason, rather than leaving a finding unanswered
+- Rewrite a restated or superseded statement in place rather than appending the replacement beside it, on every canonical doc type this skill writes
+- Report a refusal or a missing `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
+
+## Must not
+
+- Infer a new task from the diff. Only outcomes already on the board get marked.
+- Touch task files the session did not change
+- Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
+- Create a context entry, or move or delete a plan. A plan is settled by the merge, and `canon tasks archive` carries it.
+- Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
+- Write an anchor onto a decision the run did not amend, or refresh one without re-reading the number. A date from a pass that measured nothing is the false confidence the marker exists to prevent.
+- Anchor an entry written before the rule, which dates it by blame rather than by a read
+- Pick or configure a classifier backend. The project setting decides it, and this skill reports the resolved `modelLayer` as returned.
+- Stop the fold on a classify finding, a refusal, or a missing subcommand. All three report and continue.
+- Apply a finding against a quote found more than once or not found at all. Report that it could not be located instead of guessing.
+- Re-run the classifier after applying a finding, which loops it over its own edit
+- Cut a model-decided `MOVE` finding. The model's own prompt defines `MOVE` more broadly than the regex layer does, for correct content sitting on the wrong surface rather than a deletion candidate, so cutting one can discard content that belongs elsewhere rather than removing detail that never belonged at all.
+- Paste a regex-decided `MOVE` finding's content into another canonical doc after cutting it. It never belonged on the wireframe surface at all, so cutting is the whole fix, not a relocation.
+- Scope Step 10 to the files Steps 3 and 7 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
+
+## Guards
+
+- Neither a `canon/` nor a `.claude/` directory: stop and name the command that sets one up
+- No session divergence and no queued outcome the diff shipped: stop with a pass, since both conditions have to hold
+
+## Out of scope
+
+- Creating a task file or moving one off the board, which `task-board` owns
+- Public-facing docs, which `docs-sync` owns, apart from landing a page a promotion handoff already carries a confirmed destination for. This skill reconciles the context entries, the planning records, and the task board, and both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
+- Deciding where a promoted page belongs, which is settled with the operator by the surface that produced the page
+- Regenerating the task index, owned by a hook
+- Re-measuring an architecture claim to decide whether its number moved. The sweep keys on a cited path entering the diff, so a claim whose number moved with no cited path in the diff goes unflagged.