@erclx/canon 4.58.0 → 4.59.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.58.0",
+  "version": "4.59.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-pr-review/SKILL.md

@@ -141,7 +141,7 @@ Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor
 
 ## Step 4: post to the PR
 
-Write the comment to `.canon/tmp/pr-review/body-<number>-<short-sha>.md`, which the rest of this step calls `<body-file>`. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post. The head commit stops a second pass overwriting the first one's body, and leaves the folder a record of which commit each review covered.
+Write the comment to `.canon/tmp/pr-review/body-<number>-<short-sha>.md` at the main worktree root, not the current worktree, which the rest of this step calls `<body-file>`. Resolve that root the way `claude-worktree` does, and send the write as a plain single `Bash` command carrying a heredoc from a linked worktree, since `Edit` and `Write` refuse a main-root path there. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post, and the head commit stops a second pass overwriting the first one's body, leaving the folder a record of which commit each review covered.
 
 Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
 

package/claude/skills/setup-init/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: Scope boundary for the one-shot onboarding chain and the setup step
 
 Without this skill, a session installs a stack whose name it recalled rather than read, hand-writes configs the tooling sync already ships as golden files, and re-runs the chain over a project that owns its configs already.
 
-Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
+Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when plugin provisioning never runs, since no step states that it sits outside the chain.
 
 Two more start at the resolve step. A project whose language the toolkit carries no stack for resolves to `base`, and the preview reports the resolved name without marking it as a fallback, so `base` development dependencies, scripts, and hooks land on a project that will not use them and nobody had the moment to decline.
 
@@ -20,7 +20,7 @@ The other is the refusal that ends rather than routes. An existing project, an i
 - Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
 - Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
 - Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
-- State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+- State which onboarding steps the chain does not run and why, so a caller knows what is left and where the boundary sits rather than inferring completeness from a clean report
 - Mark a stack reached by fallback as a fallback in the preview, and name what `base` carries, so the write can be declined at the one point it is still declinable
 - Name a destination for every state the chain does not serve, in this body rather than only in a reference doc the person would have to already know to open, and say for each whether the chain stops or runs on a default
 
@@ -37,9 +37,10 @@ The other is the refusal that ends rather than routes. An existing project, an i
 ## Out of scope
 
 - Installing governance rules alone: `setup-gov`. This skill installs governance beside tooling and the seeds.
-- Bootstrapping the `index.md` system: `setup-indexes`. Neither `canon init` nor this chain performs it.
 - Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
-- Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
+- Running the verification scripts, which `setup-verify` owns and this chain invokes as step 4
+- Publishing repository metadata: `repo-metadata`. It reaches a remote, which is past the project edge this chain stops at.
+- Making the first commit: `git-commit`. It reaches the project's history, which is past the project edge this chain stops at.
 - Re-installing into a project that already has the files, which the per-domain `canon <domain> install` and `canon sync` commands own
 - Deciding which of those per-domain commands an existing project needs: `canon-operator`. That skill reads the target before naming one, which this chain never does, so it is the destination rather than a guess made here.
 - Seeding the `.claude/` folder without the tooling chain, which `canon claude init` does on its own and `setup-indexes` finishes

package/claude/skills/setup-init/SKILL.md

@@ -10,7 +10,7 @@ Orchestrates the onboarding chain. Detects project type, resolves per-domain arg
 ## Scope
 
 - This skill and `canon init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `canon <domain> install` or `canon sync` paths instead.
-- The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
+- The chain folds `setup-indexes` in as its own final step, once the project-scoped work is written. It still does not provision Claude Code plugins: `setup-plugins` owns that, installing once per machine rather than into a project, so no project-scoped chain can carry it. Name it in the report so a clean result does not read as onboarding complete.
 
 ## Declined states
 
@@ -75,7 +75,7 @@ A resolved name and a fallback read alike once written, so mark the fallback her
 
 ## Execute
 
-Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.
+Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate, except step 5, which hands off to a skill that confirms its own folder list with the operator. Do not pause for additional confirmation elsewhere. Run from the target project's current directory.
 
 Step 1: `canon init` installs base tooling, claude seeds, governance rules, and wiki.
 
@@ -115,6 +115,8 @@ Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files
 
 Step 4: invoke `setup-verify`. Runs the `package.json` scripts and reports pass/fail.
 
+Step 5: hand off to `setup-indexes` to bootstrap the `index.md` system over the project's own documentation folders. The skill confirms candidate folders with the operator rather than running unattended, which is the one step in this chain that pauses for a conversation. A fresh scaffold usually has no markdown-heavy folder yet, so this step frequently hands off with nothing for `setup-indexes` to present, which is that skill's own outcome to define rather than a claim this chain makes for it.
+
 ## Report
 
 After the chain, report:
@@ -123,6 +125,9 @@ After the chain, report:
 - Tooling stack synced (or skipped). Name the layers pulled via the extends chain.
 - Any post-sync fixups applied (ESLint pin, filename renames)
 - `setup-verify` outcome
+- `setup-indexes` outcome (folders bootstrapped, or none found)
 - Any domains or scripts that failed
 - Any detection gaps surfaced during resolve
-- Onboarding steps left to the caller: `setup-indexes` for the `index.md` system, `setup-plugins` for Claude Code plugins
+- Onboarding steps left to the caller: `setup-plugins` for Claude Code plugins
+
+The chain stops at the project edge. `repo-metadata` and `git-commit` also ship, reaching a remote and the project's history respectively, and neither runs here.

package/docs/target-projects.md

@@ -59,8 +59,9 @@ The chain is:
 - `canon tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
 - The agent reads `canon tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations: .claude/context/development.md -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
+- `setup-indexes` bootstraps the `index.md` system over the project's own documentation folders, confirming candidate folders with the operator rather than running unattended
 
-The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `canon:canon-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
+The chain stops at the project edge. `repo-metadata` and `git-commit` also ship, reaching a remote and the project's history respectively, and neither runs as part of it. The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `canon:canon-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `canon claude init` for the seed docs and then `canon:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
 
 Keep the `## Scripts` table in `.claude/context/development.md` current as scripts are added. Base tooling seeds that entry with the commands it installs, and each stack reference extends the table. `project-commands` reads it to start the app or run a check on request, so a command missing from the table cannot be run that way. A project whose entry outgrew one file and split into `.claude/context/development/` keeps the table in `overview.md`, which is where the skill looks next. <!-- audit-ignore-citations: .claude/context/development.md -->
 

package/governance/rules/core/055-scratch.md

@@ -8,3 +8,4 @@ description: Write temporary files to the scratch folder structure
 
 - Write temporary files to `.canon/tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
 - Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, which is one the record move has not reached. The hook accepts either, but the ignore file is the source: `.gitignore` and its manifest counterpart are what keep the fallback spelling out of `git status`, and the hook and this rule both defer to it. `canon migrate records` is what moves a project from this second spelling to the first. <!-- canon-keep-record-root -->
+- "The project root" above means the current worktree by default. `085-worktrees.md` states the same mixed default for `.canon/tmp/` and defers to each skill's own body for which write resolves at the main root instead.

package/governance/rules/core/085-worktrees.md

@@ -11,6 +11,7 @@ description: Route tracked-file writes and shared session scratch correctly from
 ## Shared session scratch
 
 - Shared session scratch (`.canon/plans/`, `.canon/review/`, `.canon/memory/`, `.canon/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
+- `.canon/tmp/` is mixed rather than main-root by default: it stays worktree-local per `055-scratch.md`, and a skill that resolves a write there at the main root instead states so in its own body.
 - From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
 - From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
 - `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.58.0",
+  "version": "4.59.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/standards/index.md

@@ -35,4 +35,5 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .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
+- [Wiki reference](wiki.md): Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/wiki.md

@@ -0,0 +1,65 @@
+---
+title: Wiki reference
+description: Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
+---
+
+# Wiki reference
+
+Applies to each authored page under `wiki/`. Skip for `index.md` at any depth, which is a hand-maintained catalog rather than a reference page, and carries `subtitle` rather than `description`.
+
+## Scope
+
+Governs each authored page under `wiki/`: which folder it belongs in, its frontmatter, its filename, and how it cites the subject it documents.
+
+Does not govern:
+
+- Voice, rhythm, sentence construction, and information density: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+
+## What a working wiki page looks like
+
+A page works when a reader who has never opened it settles two things without asking anyone:
+
+- Which folder holds it, decided from the subject alone rather than from where it happened to get written
+- Where the content came from, so a claim can be checked against its owner rather than against this repository
+
+A page failing either is non-conforming even when it satisfies every shape rule below.
+
+## Placement
+
+- Write a page here only when its subject is owned outside this repository. Route anything about how this repository works to `docs/`, `.claude/context/`, or a skill body instead.
+- File the page by owner: `wiki/claude/` for Anthropic, `wiki/tools/` for another vendor, `wiki/concepts/` where no single vendor owns the subject.
+- Treat `wiki/concepts/rule-writing-vocabulary.md` as the one recorded exception to the owner test, stated in the page itself.
+
+## Frontmatter
+
+- `title` (required): sentence case, naming the subject
+- `description` (required): one line naming what the page covers
+
+## Naming
+
+- Name a `wiki/claude/` page with a `claude-` prefix before the kebab subject.
+- Name a `wiki/tools/` or `wiki/concepts/` page as a bare kebab subject, with no prefix.
+
+## 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.
+- 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.
+
+## Template
+
+```markdown
+---
+title: <Subject>
+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>.
+
+## <Section>
+
+<Reference content.>
+```