@erclx/canon 5.19.0 → 5.20.0

package/src/sandbox/stub-remote.ts

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+const STUB_ORG = 'stub-org'
+const ANCHOR_REPO = 'canon-sandbox'
+
+/** The URL `sandbox_anchor_url` builds once `GITHUB_ORG` names the stub organization. */
+export const STUB_ANCHOR_URL = `https://github.com/${STUB_ORG}/${ANCHOR_REPO}.git`
+
+/** Port 9 is the discard service, which nothing listens on, so a real HTTPS attempt fails. */
+const DEAD_PROXY = 'http://127.0.0.1:9'
+
+/** Pinned so a commit id depends on its tree alone and two provisions of one tree agree. */
+const PINNED_DATE = '2026-01-01T00:00:00Z'
+
+/**
+ * Answers the `gh` calls the git scenarios make and fails on any other, so a new
+ * call reaches a reader as a red arm rather than a silent pass. Every call is
+ * logged as one line, quoted so an argument holding a space stays one argument.
+ */
+const STUB_GH = `#!/usr/bin/env bash
+# stub gh
+dir="$STUB_GH_DIR"
+line="$(printf '%q ' "$@")"
+line="\${line% }"
+printf '%s\\n' "$line" >>"$dir/gh.log"
+
+case "$1" in
+api) exit 0 ;;
+pr)
+  case "$2" in
+  create)
+    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
+    count=$((count + 1))
+    echo "$count" >"$dir/pr-count"
+    echo "https://github.com/${STUB_ORG}/${ANCHOR_REPO}/pull/$count"
+    exit 0
+    ;;
+  close | list) exit 0 ;;
+  esac
+  ;;
+esac
+
+printf '%s\\n' "$line" >>"$dir/gh-unknown.log"
+echo "stub gh: unknown call: $line" >&2
+exit 1
+`
+
+/**
+ * Builds a local bare repository and a stub `gh` under `stubDir` and returns the
+ * environment that sends a provision's pushes and `gh` calls there. Nothing in
+ * it reaches the shared anchor: the URL rewrite turns every push into a file
+ * path, and the stub heads `PATH` ahead of any real `gh`.
+ */
+export function createStubRemote(stubDir: string): Record<string, string> {
+  rmSync(stubDir, { recursive: true, force: true })
+  const bin = join(stubDir, 'bin')
+  const remotes = join(stubDir, 'remotes')
+  mkdirSync(bin, { recursive: true })
+  mkdirSync(remotes, { recursive: true })
+
+  execFileSync(
+    'git',
+    ['init', '-q', '--bare', '-b', 'main', join(remotes, `${ANCHOR_REPO}.git`)],
+    { stdio: 'ignore' },
+  )
+
+  const gh = join(bin, 'gh')
+  writeFileSync(gh, STUB_GH)
+  chmodSync(gh, 0o755)
+
+  return {
+    PATH: `${bin}:${process.env.PATH ?? ''}`,
+    STUB_GH_DIR: stubDir,
+    GITHUB_ORG: STUB_ORG,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: `url.${remotes}/.insteadOf`,
+    GIT_CONFIG_VALUE_0: `https://github.com/${STUB_ORG}/`,
+    GIT_AUTHOR_DATE: PINNED_DATE,
+    GIT_COMMITTER_DATE: PINNED_DATE,
+    HTTPS_PROXY: DEAD_PROXY,
+    https_proxy: DEAD_PROXY,
+    ALL_PROXY: DEAD_PROXY,
+  }
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trimEnd()
+}
+
+function readLog(path: string): string {
+  return existsSync(path) ? readFileSync(path, 'utf8').trimEnd() : ''
+}
+
+/**
+ * Reads what a provision left in the stub: the `gh` calls, the calls it did not
+ * recognize, and for each bare repository every ref with its tip tree and the
+ * commit subjects beneath it. A tree id carries no timestamp, so it compares
+ * across two runs where a commit id would not.
+ */
+export function readStubManifest(stubDir: string): Map<string, string> {
+  const manifest = new Map<string, string>()
+  manifest.set('stub:gh', readLog(join(stubDir, 'gh.log')))
+  manifest.set('stub:gh-unknown', readLog(join(stubDir, 'gh-unknown.log')))
+
+  const remotes = join(stubDir, 'remotes')
+  if (!existsSync(remotes)) return manifest
+
+  for (const entry of readdirSync(remotes).sort()) {
+    if (!entry.endsWith('.git')) continue
+    const repo = join(remotes, entry)
+    const name = entry.slice(0, -'.git'.length)
+
+    const refs = git(repo, ['for-each-ref', '--format=%(refname) %(tree)'])
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => {
+        const ref = line.split(' ')[0] ?? ''
+        const subjects = git(repo, ['log', '--format=  %s', '--reverse', ref])
+
+        return `${line}\n${subjects}`
+      })
+    manifest.set(`stub:${name}:refs`, refs.join('\n'))
+  }
+
+  return manifest
+}

package/standards/architecture.md

@@ -1,6 +1,11 @@
 ---
 title: Architecture reference
 description: Shape and content rules for canon/ARCHITECTURE.md
+paths:
+  - 'canon/ARCHITECTURE.md'
+  - '.claude/ARCHITECTURE.md'
+rule:
+  - "Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one."
 ---
 
 # Architecture reference

package/standards/context.md

@@ -1,6 +1,12 @@
 ---
 title: Context entry reference
 description: Shape and content rules for canon/context/<domain>.md entries
+paths:
+  - 'canon/context/**'
+  - '.claude/context/**'
+rule:
+  - 'Before non-trivial work in a domain, read its `canon/context/<domain>.md` entry. Use `canon/context/index.md` to find it.'
+  - 'Leave the entry conforming when work in its domain changes what it describes.'
 ---
 
 # Context entry reference

package/standards/design.md

@@ -1,6 +1,9 @@
 ---
 title: Design reference
 description: Shape and content rules for canon/DESIGN.md
+paths:
+  - 'canon/DESIGN.md'
+  - '.claude/DESIGN.md'
 ---
 
 # Design reference

package/standards/diagrams.md

@@ -1,6 +1,14 @@
 ---
 title: Diagram reference
 description: Shape and content rules for .canon/diagrams/<kind>.md files
+paths:
+  - '.canon/diagrams/**'
+  - '.claude/DIAGRAMS.md'
+rule:
+  - 'Layout, budgets, accessibility, labels, and render verification inside the fence are a separate topic. The mermaid standard routes them.'
+  - 'A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.'
+  - 'Write a new diagram to `.canon/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`'
+  - 'Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it'
 ---
 
 # Diagram reference

package/standards/groundwork-spikes.md

@@ -0,0 +1,66 @@
+---
+title: Groundwork spikes reference
+description: What each spike in a track's 08-spikes.md records, the sample rule, and the three folders that hold what a spike produced
+---
+
+# Groundwork spikes reference
+
+Applies to `08-spikes.md` inside a groundwork track at `.canon/groundwork/<nn>-<slug>/`, and to the folders beside it that hold what a spike produced. It records evidence by experiment, beside the evidence by measurement `01-current-state.md` holds.
+
+## Scope
+
+Governs `08-spikes.md`, what each spike in it carries, how a spike is sized, and the `evidence/`, `scripts/`, and `clones/` folders in a track.
+
+Does not govern:
+
+- The track's folder layout, its other files, frontmatter, and numbering: `groundwork.md`
+- Running a spike, which belongs to the surface driving the track
+
+## What a working spike record looks like
+
+A spike record works when a later reader can re-run each spike and trust what it settled:
+
+- Which open question did each spike answer, and did it close it?
+- Can the method be re-run from the file, against the fixture it names?
+- What did it cost, and what does the result not prove?
+
+## Spikes
+
+The file is optional, since measuring what is already there settles most questions.
+
+Each spike carries four things:
+
+- The open question it answers, named by file and number. A spike attached to no question is a runaway.
+- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
+- The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
+- The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
+
+Start a spike against a sample bounded on input size, duration, and spend, and scale up only once it shows the method works. Record the sample's bounds beside the figure for the full input.
+
+## What a spike produced
+
+A file a reader opens to verify how a result was produced or what it showed lives inside the track, and bulk input such as a large fixture stays outside it. Three unnumbered subfolders carry the first kind, since a reader reaches them from the citing claim rather than in read order:
+
+- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
+- `scripts/`: the arm scripts and harnesses a spike ran, which a reader opens to check the method.
+- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
+
+Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
+
+Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
+
+Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.
+
+## Template
+
+```markdown
+# Spikes
+
+## <nn>. <what the spike tests>
+
+- Question: <file and number of the open question>
+- Method: <fixture and where it lived, exact command, repetition count>
+- Result: <what it showed, and which question it closes>
+- Cost: <measured cost>, <sample bounds beside the full-input figure>
+- Caveats: <what the result does not prove>
+```

package/standards/groundwork.md

@@ -1,6 +1,10 @@
 ---
 title: Groundwork reference
 description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+paths:
+  - '.canon/groundwork/**'
+rule:
+  - 'Follow the groundwork spikes standard for `08-spikes.md` and the folders holding what a spike produced. Read it with `canon standards groundwork-spikes`.'
 ---
 
 # Groundwork reference
@@ -15,6 +19,7 @@ Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout
 
 Does not govern:
 
+- `08-spikes.md`, what each spike records, and the folders holding what a spike produced: `groundwork-spikes.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The feature plan a closed track feeds, and the contract its answer slots keep: `plan.md`
 - The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
@@ -110,31 +115,6 @@ The dropped list is what stops a future session re-proposing something already r
 
 Written to survive a compaction that loses the conversation. It repeats facts held elsewhere in the folder rather than pointing at them. That duplication is correct here and wrong everywhere else.
 
-## 08-spikes.md
-
-Evidence by experiment, beside the evidence by measurement `01-current-state.md` holds. Optional, since measuring what is already there settles most questions.
-
-Each spike carries four things:
-
-- The open question it answers, named by file and number. A spike attached to no question is a runaway.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
-- The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
-- The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
-
-Start a spike against a sample bounded on input size, duration, and spend, and scale up only once it shows the method works. Record the sample's bounds beside the figure for the full input.
-
-A file a reader opens to verify how a result was produced or what it showed lives inside the track, and bulk input such as a large fixture stays outside it. Three unnumbered subfolders carry the first kind, since a reader reaches them from the citing claim rather than in read order:
-
-- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
-- `scripts/`: the arm scripts and harnesses a spike ran, which a reader opens to check the method.
-- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
-
-Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
-
-Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
-
-Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.
-
 ## Open questions
 
 Every open question carries a lean, wherever it appears. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.

package/standards/index.md

@@ -17,12 +17,14 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+- [Groundwork spikes reference](groundwork-spikes.md): What each spike in a track's 08-spikes.md records, the sample rule, and the three folders that hold what a spike produced
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Mermaid reference](mermaid.md): Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
-- [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+- [Plan lifecycle reference](plan-lifecycle.md): When a feature plan is written, where it lives, how it changes mid-flight, and its move to the archive
+- [Plan reference](plan.md): Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
@@ -30,11 +32,13 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+- [Skill path reference](skill-paths.md): Which root a file a skill body names resolves against, and how a body cites a standard
 - [Practice skill reference](skill-practice.md): Closing sections and source ledger for a skill carrying engineering practice
 - [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
-- [Claude skill reference](skill.md): Claude skill structure and authoring rules
+- [Claude skill reference](skill.md): Skill structure and authoring rules for Claude Code
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
+- [Task decline reference](tasks-decline.md): Where a task decided against moves, the Declined line it carries, and what happens to its plan and board row
 - [Tasks reference](tasks.md): Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags

package/standards/intake.md

@@ -1,6 +1,8 @@
 ---
 title: Intake reference
 description: Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
+paths:
+  - '.canon/intake/**'
 ---
 
 # Intake reference

package/standards/markdown.md

@@ -1,6 +1,12 @@
 ---
 title: Markdown reference
 description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording
+paths:
+  - '**/*.md'
+rule:
+  - 'Read it before a substantial markdown edit. Do not work the banned characters from memory.'
+  - 'Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.'
+  - 'Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.'
 ---
 
 # Markdown reference

package/standards/memory.md

@@ -1,6 +1,8 @@
 ---
 title: Memory reference
 description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+paths:
+  - '.canon/memory/**'
 ---
 
 # Memory reference

package/standards/mermaid.md

@@ -1,6 +1,12 @@
 ---
 title: Mermaid reference
 description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
+paths:
+  - '**/*.md'
+rule:
+  - 'Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.'
+  - 'Read it before drafting the fence. Do not work the layout or the budgets from memory.'
+  - 'Which diagram a document carries and what question it answers is a separate topic. The diagrams standard routes it.'
 ---
 
 # Mermaid reference

package/standards/plan-lifecycle.md

@@ -0,0 +1,36 @@
+---
+title: Plan lifecycle reference
+description: When a feature plan is written, where it lives, how it changes mid-flight, and its move to the archive
+---
+
+# Plan lifecycle reference
+
+Applies to a feature plan at `.canon/plans/feature-<slug>.md` from the session that writes it to the archive. The folder is gitignored, so nothing but this lifecycle keeps a plan's rejected alternatives readable after the work ships.
+
+This standard governs when a plan moves and changes rather than what the file holds, so it carries no template. The plan's own template is in `plan.md`.
+
+## Scope
+
+Governs when a feature plan is written, where it lives across working trees, how it is amended, and its move to `.canon/plans/archive/`.
+
+Does not govern:
+
+- The filename, the required sections, and the suggested-and-answer contract: `plan.md`
+- The task file a plan is linked from, and how it is archived: `tasks.md`
+
+## What a working lifecycle looks like
+
+A plan's lifecycle works when a later reader can still answer, from the file alone:
+
+- What did the work set out to do, and which alternative did it reject?
+- Which answer to each question is current, without reconciling two passages?
+
+A plan lost to deletion, or carrying two answers to one question, fails both.
+
+## Lifecycle
+
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
+- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.

package/standards/plan.md

@@ -1,20 +1,30 @@
 ---
 title: Plan reference
-description: Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+description: Filename and slug, the required sections, and the suggested-and-answer contract for a feature plan
+paths:
+  - '.canon/plans/**'
+rule:
+  - 'Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.'
+  - 'Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.'
+  - "Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`."
+  - 'Move a shipped plan to `.canon/plans/archive/`. Never delete one.'
+  - 'Amend a plan in place when a decision changes. Do not append a second passage narrating the change.'
+  - 'Follow the plan lifecycle standard for when a plan is written, how it is amended, and its move to the archive. Read it with `canon standards plan-lifecycle`.'
 ---
 
 # Plan reference
 
 Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
 
-The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step below is a move rather than a cleanup.
+The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step is a move rather than a cleanup.
 
 ## Scope
 
-Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, and the suggested-and-answer contract.
 
 Does not govern:
 
+- When a plan is written, how it is amended, and its move to the archive: `plan-lifecycle.md`
 - One question measured in depth before anyone can plan against it: `groundwork.md`
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
 - The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
@@ -135,14 +145,6 @@ The plan is archived at ship, so the same deviation takes one line in the open t
 
 This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there.
 
-## Lifecycle
-
-- Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
-- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
-- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
-- Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
-
 ## Template
 
 ```markdown

package/standards/readme.md

@@ -1,6 +1,8 @@
 ---
 title: Readme reference
 description: Readme voice, structure, and content conventions
+paths:
+  - '**/README.md'
 ---
 
 # Readme reference

package/standards/ready.md

@@ -1,6 +1,10 @@
 ---
 title: Ready reference
 description: Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
+paths:
+  - '.canon/ready/**'
+rule:
+  - 'Load the `canon:draft-ready` skill to write a ready folder, its overview, the thin plan, and the task row. It owns the procedure. Report it rather than proceeding silently when it does not resolve, since it ships with the plugin and this rule ships with the CLI.'
 ---
 
 # Ready reference

package/standards/requirements.md

@@ -1,6 +1,9 @@
 ---
 title: Requirements reference
 description: Shape and content rules for canon/REQUIREMENTS.md
+paths:
+  - 'canon/REQUIREMENTS.md'
+  - '.claude/REQUIREMENTS.md'
 ---
 
 # Requirements reference

package/standards/rule.md

@@ -1,6 +1,10 @@
 ---
 title: Governance rule reference
 description: Rule frontmatter, body shape, and voice for .claude/rules files
+paths:
+  - '.claude/rules/**/*.md'
+rule:
+  - 'Read it before writing or editing a rule. Do not work the shape from memory.'
 ---
 
 # Governance rule reference
@@ -36,7 +40,8 @@ Write both when both apply. A rule stating the directive and a skill stating how
 - `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
 - A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, a sibling of `canon/` rather than nested inside it, keeping the same subdirectory names
 - This repository's own toolkit-only rules, which never ship to a target, live at `.claude/rules/internal/<subdirectory>/<n>-<slug>.md`, a second sibling of `canon/`. See "Two sources numbering into one folder" below.
-- Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+- Give every authored rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
+- A rule that only routes a path to a standard is generated, not authored. It lives at `governance/rules/standards/<standard>.md` under the standard's name, carries no number, and installs to `.claude/rules/canon/standards/`. Never hand-edit one. Change its globs and bullets in the standard's `paths` and `rule` frontmatter, and `canon gov regen` rewrites it. The generator refuses a standard named like a band folder, which keeps the bare-word name reachable.
 
 ## Reserved numbers
 

package/standards/session.md

@@ -1,6 +1,10 @@
 ---
 title: Session map reference
 description: Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+paths:
+  - '.canon/tasks/session-*.md'
+rule:
+  - 'Follow this rule rather than the tasks rule for a `session-` file. A handoff is not a task and carries neither `## Outcomes` nor `## Findings`.'
 ---
 
 # Session map reference

package/standards/skill-paths.md

@@ -0,0 +1,50 @@
+---
+title: Skill path reference
+description: Which root a file a skill body names resolves against, and how a body cites a standard
+---
+
+# Skill path reference
+
+Applies to every path a skill body names, under `skills/<name>/`. A skill reads from two roots, so the path it writes decides whether the file is found once the skill runs from another project.
+
+This is an attribute standard. It governs the path strings a body carries rather than a file of its own, so it carries no template.
+
+## Scope
+
+Governs how a `SKILL.md` body or a file under its `references/` names a bundled asset, an installed shared doc, or a standard.
+
+Does not govern:
+
+- The skill folder, its frontmatter, the body rules, and the choice between skill types: `skill.md`
+- Punctuation, formatting, and word choice: `markdown.md`
+
+## What a working path looks like
+
+A path in a skill body works when the skill resolves it from any project it runs in:
+
+- Does each bundled asset resolve against the skill's own directory rather than the session's working directory?
+- Does each cited standard resolve in a target that installed nothing but the plugin?
+- Does a procedure two skills share live in one place, with each body citing it?
+
+A body failing any of these is non-conforming even when every path resolves in this repository.
+
+## Path resolution
+
+Know which root a file lives under before referencing it.
+
+- Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, which resolves against the session cwd and fails when a plugin skill runs from another project.
+- Installed shared docs (`.claude/rules/`, `canon/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
+- Do not hand-copy a standard into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+
+## Citing a standard
+
+No standard installs into a project, so a body cites one place rather than choosing between two.
+
+- Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install.
+- Never cite `.claude/standards/X.md` from a shipped body. A target holds no such folder. <!-- audit-ignore-citations: .claude/standards/X.md -->
+- Name `canon standards X` instead where the body wants the document rather than a path to open, such as a value it captures or reports. That verb resolves `standards/` at the project root and then the corpus inside the package.
+- State the path once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
+- A guard on a standard's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+- Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
+- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in a standard and a citation in each body.
+- Keep the trigger in the body and the procedure in the standard. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the standard cannot know it.