@erclx/canon 5.26.0 → 5.27.0

package/src/sandbox/headless/watch.ts

@@ -0,0 +1,145 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/** Path to content hash, one entry per regular file. */
+export type Manifest = ReadonlyMap<string, string>
+
+/**
+ * Hashes every regular file under `base`, keyed by its path relative to it, for
+ * the top-level entries `keep` admits. A symlink is neither followed nor
+ * hashed, matching `find -type f`.
+ */
+function hashFiles(base: string, keep: (name: string) => boolean): Manifest {
+  const manifest = new Map<string, string>()
+  const pending = readdirSync(base, { withFileTypes: true })
+    .filter((entry) => keep(entry.name))
+    .map((entry) => ({ entry, dir: base }))
+
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    const path = join(next.dir, next.entry.name)
+    if (next.entry.isDirectory()) {
+      for (const entry of readdirSync(path, { withFileTypes: true }))
+        pending.push({ entry, dir: path })
+    } else if (next.entry.isFile()) {
+      const hash = createHash('sha1').update(readFileSync(path)).digest('hex')
+      manifest.set(relative(base, path), hash)
+    }
+  }
+
+  return new Map([...manifest].sort(([a], [b]) => (a < b ? -1 : 1)))
+}
+
+/**
+ * Records a hash per file so the post-run comparison can name what the session
+ * wrote. A diff against `refs/sandbox/baseline` cannot stand in for this: an arm
+ * that sets SANDBOX_SKIP_AUTO_COMMIT leaves its last stage uncommitted, so the
+ * fixtures the harness staged would read as session writes.
+ */
+export function snapshotTree(dir: string): Manifest {
+  return hashFiles(dir, (name) => name !== '.git')
+}
+
+/**
+ * Reports both sides of a change, so a deletion is a write. Reporting only the
+ * after side would let a file removed outside the declared scope produce no
+ * assertion at all, which is the one way this check stayed weaker than the
+ * permission scoping it replaced. A modified file differs on both sides and
+ * reports once.
+ */
+export function writesBetween(before: Manifest, after: Manifest): string[] {
+  const paths = new Set([...before.keys(), ...after.keys()])
+
+  return [...paths]
+    .filter((path) => before.get(path) !== after.get(path))
+    .sort()
+}
+
+/**
+ * The roots a run must not write shared session scratch to. `snapshotTree`
+ * reads the sandbox alone, so before this a session that resolved that scratch
+ * against a toolkit root wrote where no manifest looked: the run reported
+ * success, the write list came back empty, and `write_scope` had nothing to
+ * assert against.
+ *
+ * It makes an escape visible rather than impossible. A session can write to a
+ * home directory, to a sibling worktree, or to any path outside these roots, and
+ * none of that is watched. The standing limits in
+ * `canon/context/sandbox/overview.md` carry what stays invisible.
+ *
+ * A linked worktree is the normal place to develop this repository, and the
+ * rule an escaping session follows sends scratch to the main root rather than to
+ * the worktree it was launched from, so the main root joins the list whenever it
+ * differs.
+ */
+export function escapeRoots(projectRoot: string): string[] {
+  const listing = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  })
+  const line = (listing.stdout ?? '')
+    .split('\n')
+    .find((l) => l.startsWith('worktree '))
+  const mainRoot = line?.slice('worktree '.length)
+
+  return mainRoot === undefined || mainRoot === '' || mainRoot === projectRoot
+    ? [projectRoot]
+    : [projectRoot, mainRoot]
+}
+
+/**
+ * The four directories the seed's shared-scratch rule names, and the whole of
+ * where an escape lands. A session that resolves that rule against a toolkit
+ * root writes here and nowhere else, so watching these rather than the whole
+ * root costs no detection.
+ *
+ * It buys the difference between a signal and noise. Nothing distinguishes the
+ * spawned session's writes from the operator's own, so a watch over the whole
+ * root reports ordinary editing during a run as an escape. Measured 2026-08-02:
+ * three runs against the relocated sandbox all wrote their report to the right
+ * place, and two of the three still reported an escape under the wide watch,
+ * naming a context entry being edited in the session that launched them.
+ *
+ * The scope stated for an arm author: `escapeRoots` times two, these times four.
+ * This watch reaches nothing past those eight destinations, so a nested run's
+ * own escape is invisible here whether or not an arm declares `escape_scope`. A
+ * nested background dispatch reports through `sessions` instead, from
+ * `dispatch.ts`, so the key defined against this file-write watch keeps one
+ * meaning. An arm whose skill is meant to reach past the sandbox tree declares
+ * `escape_scope` in its `expect.toml`, which bounds a legitimate write rather
+ * than the run. Read `canon/context/sandbox/isolation.md` and
+ * `canon/context/sandbox/coverage/workflow-arms.md` before writing a claim past
+ * that.
+ */
+export const ESCAPE_SCRATCH_DIRS = [
+  '.canon/plans',
+  '.canon/review',
+  '.canon/memory',
+  '.canon/tasks',
+] as const
+
+export interface RootSnapshot {
+  readonly manifest: Manifest
+  /**
+   * The root held at least one of the four directories. A root with none of
+   * them contributes no manifest and no diff, which reads identically to a watch
+   * that ran clean, so `checkEscapeScope` needs this to tell "watched and clean"
+   * from "nothing to watch" apart.
+   */
+  readonly isWatched: boolean
+}
+
+export function snapshotRoot(dir: string): RootSnapshot {
+  const targets = ESCAPE_SCRATCH_DIRS.filter((sub) =>
+    existsSync(join(dir, sub)),
+  )
+  if (targets.length === 0) return { manifest: new Map(), isWatched: false }
+
+  const manifest = new Map<string, string>()
+  for (const sub of targets)
+    for (const [path, hash] of hashFiles(join(dir, sub), () => true))
+      manifest.set(`${sub}/${path}`, hash)
+
+  return { manifest, isWatched: true }
+}

package/src/sandbox/provision.ts

@@ -273,12 +273,22 @@ function setupAssets(
  * tree, so a scenario exercises the branch's skill rather than the installed
  * plugin's. The merge base against `origin/main` comes first, so a local `main`
  * trailing the remote does not pull in skills other merged branches changed.
+ * A headless run skips it, since a copied body alone shadows the plugin's whole
+ * skill folder and its relative citations then resolve to nothing.
  */
 export function injectChangedSkills(
   root: string,
   sandbox: string,
   isSkipAutoCommit: boolean,
+  isSkipInject = false,
 ): string[] {
+  if (isSkipInject) {
+    logInfo(
+      'Skipped dev skill injection: the run resolves skills through --plugin-dir',
+    )
+    return []
+  }
+
   const base = (
     readGit(root, ['merge-base', 'HEAD', 'origin/main']) ??
     readGit(root, ['merge-base', 'HEAD', 'main']) ??
@@ -438,7 +448,8 @@ function provisionScenario(
   Object.assign(env, staged.exports)
 
   const isSkipAutoCommit = (env.SANDBOX_SKIP_AUTO_COMMIT ?? '') !== ''
-  injectChangedSkills(root, sandbox, isSkipAutoCommit)
+  const isSkipInject = (env.SANDBOX_SKIP_SKILL_INJECT ?? '') !== ''
+  injectChangedSkills(root, sandbox, isSkipAutoCommit, isSkipInject)
   must(commitScenarioChanges(sandbox, isSkipAutoCommit, env))
   tagBaseline(sandbox, env)
 

package/src/sandbox/tree.ts

@@ -6,8 +6,8 @@ import { join } from 'node:path'
 /**
  * Mints a short per-run identifier the first time it is asked for and holds it
  * in `CANON_SANDBOX_RUN_ID` for the rest of this process, so a script that
- * spawns a child inheriting `process.env` — `run.sh` calling `canon sandbox` to
- * provision and then `canon sandbox check` — resolves the same tree in every one
+ * spawns a child inheriting `process.env` — `canon sandbox run` calling
+ * `canon sandbox` to provision and then `canon sandbox check` — resolves the same tree in every one
  * of them, as do the hook and installer children provisioning spawns. A process
  * that already carries the variable, inherited from such a parent, reuses it
  * rather than minting a new one.
@@ -49,9 +49,8 @@ export function sandboxTree(): string {
 }
 
 /**
- * Twin of `normalize_sandbox_path` in `scripts/lib/sandbox-path.sh`, which the
- * headless runner still sources. Lexical rather than `realpath`, since the guard
- * runs before the tree exists, so nothing here follows a symlink.
+ * Lexical rather than `realpath`, since the guard runs before the tree exists,
+ * so nothing here follows a symlink.
  */
 export function normalizeSandboxPath(path: string): string {
   if (path === '') return ''
@@ -110,9 +109,6 @@ export function sandboxRoots(projectRoot: string): SandboxRoots {
  * Provisioning removes the tree before staging, so the test is an allowlist: a
  * strict descendant of the home folder or the temp root, outside the main
  * worktree in both directions.
- *
- * Twin of `assert_sandbox_dir_safe` in `scripts/lib/sandbox-path.sh`, message
- * for message, since the headless runner still guards through that copy.
  */
 export function assertSandboxDirSafe(
   raw: string,

package/src/secrets/scan.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { isBinary } from '@/sweep/binary'
-import { listRepositoryFiles } from '@/git-files'
+import { listRepositoryFiles } from '@/git/files'
 import { isExempt } from '@/secrets/marker'
 import { matchLine } from '@/secrets/patterns'
 import { readShipEntries, selectShipped } from '@/secrets/shipped'

package/src/sessions/claim.ts

@@ -9,7 +9,7 @@ import {
   listWorktrees,
   type RefReport,
   type WorktreeEntry,
-} from '@/worktree'
+} from '@/git/worktree'
 
 export interface ClaimReport {
   readonly claimed: boolean

package/src/sessions/resolve.ts

@@ -1,6 +1,6 @@
 import { basename } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import {
   type Confidence,
   liveness,

package/src/sessions/transfer/bundle.ts

@@ -10,7 +10,7 @@ import {
 } from 'node:fs'
 import { basename, dirname, isAbsolute, join, relative } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { recordDir, recordRoot, SCRATCH } from '@/record-root'
 import { remoteIdentity } from '@/records/backup'
 import {

package/src/slides/package/fonts.ts

@@ -152,9 +152,13 @@ export function eotOf(bytes: Uint8Array): EotResult {
     }
     const strings = names(font, name)
     const padding = Buffer.alloc(2)
-    // RootStringCheckSum, EUDCCodePage, Padding6, SignatureSize, EUDCFlags,
-    // and EUDCFontSize, all zero for a face with no root string or EUDC data.
+    // RootStringCheckSum, then EUDCCodePage, Padding6, SignatureSize,
+    // EUDCFlags, and EUDCFontSize, zero for a face with no EUDC data. The
+    // checksum is the root string's byte sum XOR 0x50475342, so an empty root
+    // string still writes the constant, and PowerPoint refuses to install a
+    // face whose checksum is zero as tampered with.
     const tail = Buffer.alloc(20)
+    tail.writeUInt32LE(0x50475342, 0)
     const eot = Buffer.concat([
       header(font, os2.offset, head.offset),
       padding,

package/src/standards/audit.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
-import { resolveBaseRef } from '@/git-files'
+import { gitEnv } from '@/git/env'
+import { resolveBaseRef } from '@/git/files'
 import { INDEX_FILE, standardsSourceDir } from '@/standards/read'
 
 /** Returned when a standard new to this branch states no success criterion under either heading `CRITERION_HEADING` accepts, the gating check. */

package/src/sync/check.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { createDesignAdapter, DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
 import { successorResolver } from '@/gov/renames'
@@ -29,7 +29,7 @@ import {
   stampedCommit,
   type StampDomain,
 } from '@/sync/stamp'
-import { isDirectory } from '@/target'
+import { isDirectory } from '@/targets/validate'
 import {
   isWholeStack,
   loadManifest,

package/src/sync/engine.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
-import { copyPreservingMode } from '@/copy'
+import { copyPreservingMode } from '@/sync/copy'
 import { checkoutMismatchWarning } from '@/project-root'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 import {
@@ -16,7 +16,7 @@ import {
   toStampKey,
   writeStamp,
 } from '@/sync/stamp'
-import { isDirectory } from '@/target'
+import { isDirectory } from '@/targets/validate'
 import {
   intro,
   isNonInteractive,

package/src/sync/git.ts

@@ -1,6 +1,6 @@
 import { basename } from 'node:path'
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import type { SyncDomain } from '@/sync/target'
 import { pipeOutput } from '@/ui'
 

package/src/sync/history.ts

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { sep } from 'node:path'
 import { execaSync } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /** Blob SHA to the newest commit whose post-image for that path held it. */
 export type PathHistory = ReadonlyMap<string, string>

package/src/sync/reverse.ts

@@ -1,7 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { execaSync } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import {
   findInstalledOrigin,
   type HistoryIndex,

package/src/sync/target.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { DESIGN_INSTALL_DIR } from '@/design/adapter'
-import { isDirectory } from '@/target'
+import { isDirectory } from '@/targets/validate'
 
 export const SYNC_DOMAINS = ['governance', 'design', 'claude'] as const
 

package/src/sync/workflow.ts

@@ -11,7 +11,7 @@ import {
   syncBranchName,
 } from '@/sync/git'
 import { domainPaths, SYNC_DOMAINS } from '@/sync/target'
-import { isDirectory } from '@/target'
+import { isDirectory } from '@/targets/validate'
 import {
   intro,
   logError,

package/src/targets/pulls.ts

@@ -1,6 +1,6 @@
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
-import { isDirectory } from '@/target'
+import { gitEnv } from '@/git/env'
+import { isDirectory } from '@/targets/validate'
 
 const GH_TIMEOUT_MS = 30_000
 

package/src/targets/sweep.ts

@@ -1,7 +1,7 @@
 import { readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import {
   claudeCanonStampPath,
   isLegacyStamped,
@@ -9,7 +9,7 @@ import {
   retiredNameStampPath,
   stampPath,
 } from '@/sync/stamp'
-import { isDirectory } from '@/target'
+import { isDirectory } from '@/targets/validate'
 
 /**
  * Folders a walk never descends into.

package/src/tasks/reach.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { basename, join } from 'node:path'
-import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { listChangedFiles, resolveBaseRef } from '@/git/files'
 import { recordDir } from '@/record-root'
 import { splitPlanSections } from '@/records/validate'
 import { type AnswersRefused, resolvePlanReference } from '@/tasks/answers'

package/src/tasks/trunk.ts

@@ -1,5 +1,5 @@
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 const GIT_TIMEOUT_MS = 10_000
 

package/src/tooling/inject.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
-import { copyPreservingMode } from '@/copy'
+import { copyPreservingMode } from '@/sync/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'

package/src/tooling/subfolder.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs'
 import { basename, join, relative } from 'node:path'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { isWholeStack, type Manifest, seedFiles } from '@/tooling/manifest'
 
 /**

package/src/web/readme-citations.ts

@@ -34,7 +34,7 @@ const QUOTED_PHRASE = /"([^"]+)"/g
  * retired `README.md:<n>` form, reported rather than accepted so the fragile
  * convention this replaces cannot come back on a later edit.
  *
- * Modeled on `clientCommandCitationsIn` in `src/client-commands.ts`, including
+ * Modeled on `clientCommandCitationsIn` in `src/gate/client-commands.ts`, including
  * its use of `isMarked` for the exemption.
  */
 export function readmeCitationsIn(

package/src/worktrees/bare-flag.ts

@@ -1,6 +1,6 @@
 import { basename } from 'node:path'
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /** Why a run wrote nothing. The three are different states a caller can tell apart. */
 export type BareFlagSkip =

package/src/worktrees/reclaim.ts

@@ -1,7 +1,7 @@
 import { $ } from 'bun'
 import { execa } from 'execa'
 import { existsSync } from 'node:fs'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import {
   repositoryOf,
   type ResolvedSession,
@@ -12,7 +12,7 @@ import {
   currentWorktreeRoot,
   listWorktrees,
   type WorktreeEntry,
-} from '@/worktree'
+} from '@/git/worktree'
 
 const GH_TIMEOUT_MS = 30_000
 

package/src/worktrees/remove.ts

@@ -1,5 +1,5 @@
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import type { WorktreeVerdict } from '@/worktrees/reclaim'
 
 /** Which half of the removal a failure landed on, so a reader repairs the right one. */

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.

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
 

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