@erclx/canon 5.25.0 → 5.27.0

package/standards/canvas.md

@@ -41,7 +41,8 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 ## Frames
 
 - Write one frame as one `.html` file inside its page folder. The filename without its extension is the frame's name, and the name follows the page naming rule.
-- Write each frame as a whole document, with a doctype, a `head`, and a `body`. A fragment gets elements the browser builds around it, and an address the operator picks inside it can no longer be matched to the file.
+- Write a frame as a whole document or as a fragment. The server writes in the `html`, `head`, and `body` a fragment leaves out, marked so a pick still matches the file.
+- State a `body` whenever the frame states a `head`. The browser builds one the file leaves out, and an address the operator picks inside the frame can no longer be matched to the file.
 - Write every table with its `tbody` stated, for the same reason. A browser adds one the file leaves out.
 - Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
@@ -78,7 +79,7 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 - Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
 - Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
 - Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
-- Do not assume a default font. Set `font-family` on the `html` element with an installed family first, since a capture checks the root's first family and the browser's default serif is absent from many machines.
+- Do not assume a default font. Set `font-family` with an installed family first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or its wireframes, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 

package/standards/requirements.md

@@ -46,6 +46,8 @@ This file loads into every session, so its weight is paid before any work starts
 
 Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.
 
+The record may carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read it whole for identity drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
+
 Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness, so a section here states what is wanted and never when it lands.
 
 ## Distribution

package/standards/skill-practice.md

@@ -47,5 +47,6 @@ A practice skill failing any of these is non-conforming even when every heading
 ## Which skills are practice skills
 
 - `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
+- It keeps a wider ledger list beside it, holding every practice skill plus the skills that teach a craft drawn from outside sources without a practice's closing shape. A skill on the wider list alone owes the ledger and none of the three sections.
 - Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
-- The list names this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.
+- Both lists name this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/standards/skill.md

@@ -100,6 +100,7 @@ allowed-tools: <tools required>
 - `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger.
 - `allowed-tools`: restrict tool access when the skill is active
 - `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)
+- `metadata.family` (required on a skill under `claude/skills/`): the skill map group the skill's row sits under, as one key from `families` in `canon claude skills list --json`. A skill under `.claude/skills/` takes none.
 
 ## Description
 
@@ -130,6 +131,7 @@ allowed-tools: <tools required>
 - Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
 - Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
 - Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+- Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
 - Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
 

package/standards/wiki.md

@@ -47,9 +47,18 @@ A page failing either is non-conforming even when it satisfies every shape rule
 ## Sourcing
 
 - Close the intro paragraph with a `Source:` sentence naming the owner. Link the canonical page where one exists, and name the owner alone where the subject has no single URL.
+- Link a docs page in its fetchable form, `https://code.claude.com/docs/en/<page>.md`, so a session reads the live text rather than a copy.
 - Fetch current information through the `claude-code-guide` agent when the subject is Claude Code. Do not work from training knowledge.
 - Propose an addition or correction and wait for confirmation. Do not write to a wiki file unasked.
 
+## Shape
+
+- Keep a page thin: the `Source:` sentence, an orientation paragraph, and lesson sections. The source owns the reference detail and a paraphrase of it falls behind within days.
+- Apply the lesson test per section: keep a fact about the subject only when the source page does not state it. Such a fact is a gotcha this project hit, a constraint it relies on, or how it uses the feature.
+- Read the current source before keeping or cutting a section. A fact kept from memory is the drift this shape exists to prevent.
+- Send a session that wants reference detail to the source and fetch it live. The page answers orientation and lessons only.
+- Leave a page with no lessons as the source link and the orientation paragraph. A catalog routes a reader by page, so the stub stays.
+
 ## Template
 
 ```markdown
@@ -60,9 +69,9 @@ description: <one line naming what this page covers>
 
 # <Subject>
 
-<What the subject is and why it matters.> Source: <owner, with a link to the canonical page where one exists>.
+<What the subject is and why it matters, in a short orientation.> Source: <owner, with a link to the canonical page where one exists>.
 
-## <Section>
+## <Lesson>
 
-<Reference content.>
+<A fact the source page does not state.>
 ```

package/tooling/base/configs/.github/workflows/pr-local-preview.yml

@@ -16,7 +16,7 @@ jobs:
       # Say so and pass rather than failing a close nobody can fix.
       - name: Skip a fork pull request
         if: github.event.pull_request.head.repo.full_name != github.repository
-        run: echo "::notice::Fork pull request, so the token cannot edit the evidence comment. The local preview line stays."
+        run: echo "::notice::Fork pull request, so the token cannot edit the evidence comment. The preview line stays."
 
       - name: Setup Bun
         if: github.event.pull_request.head.repo.full_name == github.repository
@@ -24,7 +24,7 @@ jobs:
         with:
           bun-version: latest
 
-      - name: Replace the local preview line on the evidence comment
+      - name: Drop the preview line from the evidence comment
         if: github.event.pull_request.head.repo.full_name == github.repository
         env:
           GH_TOKEN: ${{ github.token }}

package/scripts/lib/sandbox-dispatch.sh

@@ -1,190 +0,0 @@
-#!/usr/bin/env bash
-
-# The bound on a nested background dispatch, and the recording behind it.
-#
-# An arm invoked without the narration its fixture states dispatched a real
-# `claude --bg` session against the machine's own process table, and nothing in
-# the harness noticed. `snapshot_tree` reads the sandbox and `snapshot_root`
-# reads four scratch directories, and a dispatched session writes into none of
-# them, so the escape watch reported clean throughout and was right to. The run
-# spent real cost until a person found it, and `SIGTERM` alone did not end it.
-#
-# Three mechanisms sit here rather than in `sandbox/run.sh`, which is the
-# only caller. Each is reachable from a test that never launches a session:
-# `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
-# reap against a `sleep`, where proving either through `run.sh` would mean
-# spawning the thing the bound exists to prevent.
-
-# The prevention. Writes a `claude` that refuses a background dispatch by flag
-# name and delegates everything else, for `run.sh` to place first on the PATH of
-# the session it spawns.
-#
-# The real binary is baked into the file rather than passed through the
-# environment. An env var carrying it would sit in the spawned session's own
-# environment, which hands any arm the exact string that walks around the shim.
-#
-# It names itself in its refusal. No arm shells to `claude` today, and one
-# written tomorrow would meet this and read it as the harness being broken
-# unless the text says which layer refused and why.
-#
-# It is not the whole bound. A dispatch reaching the binary by an absolute path
-# never resolves through PATH at all, which is what `reap_process_group`
-# backstops.
-install_dispatch_shim() {
-  local dir="$1"
-  local real="$2"
-
-  cat >"$dir/claude" <<SHIM
-#!/usr/bin/env bash
-# Generated by install_dispatch_shim in scripts/lib/sandbox-dispatch.sh.
-for arg in "\$@"; do
-  case "\$arg" in
-  --bg | --background)
-    echo "canon sandbox harness: refusing \$arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2
-    exit 64
-    ;;
-  esac
-done
-exec "$real" "\$@"
-SHIM
-
-  chmod +x "$dir/claude"
-}
-
-# True while any process still carries this group id. Reads the whole table
-# rather than `ps -g`, which selects by session on some builds and reports an
-# empty group as a clean exit either way.
-process_group_alive() {
-  ps -eo pgid= 2>/dev/null | tr -d ' ' | grep -qx "$1"
-}
-
-# The backstop. Signals a process group `run.sh` created, escalating rather than
-# sending one signal and reporting success, since the dispatch that produced this
-# row took two signals to reap.
-#
-# Prints its outcome and always exits zero. Every caller runs under `set -e`, and
-# a survivor is something to report rather than a reason to abandon the verdict
-# the run already took.
-#
-# The group has to be one the run created, and the refusal below is what makes
-# that property travel with the function rather than living in one caller.
-# `run.sh` reads the harness group once and reports `inherited` when the session
-# failed to lead a group of its own, which is a diagnosis; this is the floor
-# under it, and under every caller after it, because the cost of getting the
-# argument wrong is the operator's own shell.
-#
-# What it cannot reach is a dispatch that called `setsid` on its way out, which
-# leaves the group before this reads it. That is the half the shim covers.
-reap_process_group() {
-  local pgid="$1"
-
-  if [ "$pgid" = "$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')" ]; then
-    printf 'refused-own-group\n'
-    return 0
-  fi
-
-  if ! process_group_alive "$pgid"; then
-    printf 'clear\n'
-    return 0
-  fi
-
-  kill -TERM -"$pgid" 2>/dev/null || true
-  wait_for_group_exit "$pgid"
-
-  if ! process_group_alive "$pgid"; then
-    printf 'reaped-term\n'
-    return 0
-  fi
-
-  kill -KILL -"$pgid" 2>/dev/null || true
-  wait_for_group_exit "$pgid"
-
-  if process_group_alive "$pgid"; then
-    printf 'survived\n'
-  else
-    printf 'reaped-kill\n'
-  fi
-  return 0
-}
-
-# Five seconds per signal. A shorter window reports a survivor for a process
-# that was already exiting, and a longer one stalls a run whose verdict is
-# already taken.
-wait_for_group_exit() {
-  local pgid="$1"
-  local waited=0
-
-  while [ "$waited" -lt 20 ] && process_group_alive "$pgid"; do
-    sleep 0.25
-    waited=$((waited + 1))
-  done
-}
-
-# The client's own session registry, which is the only surface a nested dispatch
-# leaves a trace on that this harness can read. It is client-owned and carries no
-# contract, so a client that stops writing a record per session breaks the
-# detection silently. That is why what reads it reports rather than asserts.
-sessions_dir() {
-  printf '%s/sessions\n' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
-}
-
-# Set whenever the registry directory existed at snapshot time. An absent
-# registry produces the same empty manifest a quiet run does, and the two mean
-# opposite things, so the report carries this rather than letting an unwatched
-# run read as a clean one. Same distinction `escape_watched` draws in `run.sh`,
-# which is also the only reader, hence the exemption on the write below.
-sessions_watched=0
-
-# Record names only, never hashes. A live session rewrites its own record on
-# every status change, so a content manifest would name every session running
-# beside this one, which is the noise the escape watch was already narrowed to
-# avoid. A record that appears between the two snapshots is a session that
-# started during the run, and that is the whole question.
-snapshot_sessions() {
-  local manifest="$1"
-  local dir
-  dir="$(sessions_dir)"
-
-  : >"$manifest"
-  [ -d "$dir" ] || return 0
-  # shellcheck disable=SC2034
-  sessions_watched=1
-
-  find "$dir" -maxdepth 1 -type f -name '*.json' 2>/dev/null |
-    sed 's|.*/||' | sort >"$manifest"
-  return 0
-}
-
-# The new side alone, unlike `writes_between`. A record that vanished is a
-# session that ended and a record that changed is one that was already running,
-# and neither is a dispatch this run made.
-sessions_between() {
-  comm -13 "$1" "$2"
-}
-
-# The side `sessions_between` drops. A record present on both sides is a session
-# that was already running before this run started and still was after, which
-# rules it out as this run's own dispatch and rules it in as a witness able to
-# explain a write the escape watch attributes to nobody.
-sessions_concurrent() {
-  comm -12 "$1" "$2"
-}
-
-# Turns a record name into a line a person can act on. The file can be gone by
-# the time this reads it, since a session that started and exited inside the run
-# takes its record with it, so an unreadable record still reports its name rather
-# than dropping out of the list.
-#
-# One record is one line. The name is written by whatever peer claimed the
-# session, so a newline inside it would split one record across two entries in a
-# list every reader takes as one line each.
-describe_session() {
-  local record desc
-  record="$(sessions_dir)/$1"
-
-  desc="$(jq -r '"\(.name // "unnamed") in \(.cwd // "an unrecorded directory")"
-    | gsub("\\s+"; " ")' "$record" 2>/dev/null || true)"
-  [ -z "$desc" ] && desc="record already gone"
-
-  printf '%s: %s\n' "$1" "$desc"
-}