@erclx/canon 5.26.0 → 5.28.0

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/tsconfig.json

@@ -11,5 +11,5 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src", "claude/skills/*/scripts/**/*.ts"]
+  "include": ["src", "claude/skills/*/scripts/**/*.ts", "sandbox/*/*.ts"]
 }

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