@erclx/canon 5.7.0 → 5.9.0

package/docs/agents/pr-evidence.md

@@ -6,10 +6,10 @@ description: What canon pr evidence compares, the marker that lets it edit its o
 # The pull request evidence comparison
 
 `canon pr evidence` renders one comment naming every changed image under an
-`evidence/` path segment, comparing each against the pull request's merge base
-with the trunk. `git-pr` posts it when a pull request opens or is edited, and
-`git-followup` posts it again after every later push, so a reviewer never has
-to open Files Changed to see what a case looked like before and after.
+`evidence/` path segment, comparing each against the pull request's merge base.
+`git-pr` posts it when a pull request opens or is edited, and `git-followup`
+posts it again after every later push, so a reviewer never has to open Files
+Changed to see what a case looked like before and after.
 
 ```bash
 canon pr evidence
@@ -55,9 +55,9 @@ image or marks the case new.
 | `gh-failed`            | `gh` could not answer for this repository or branch, or read its comments.    |
 | `no-branch`            | The pull request carries no head branch name.                                 |
 | `no-object-head`       | The pull request object reported no head commit.                              |
-| `no-base`              | No base resolves against the trunk.                                           |
-| `unreadable-tree`      | git could not read the tree at the base commit.                               |
-| `unreadable-changes`   | git could not list what this branch changed.                                  |
+| `no-base`              | GitHub reported no merge base for the pull request.                           |
+| `unreadable-changes`   | GitHub could not list what the pull request changed.                          |
+| `would-empty`          | The render holds no cases and the marked comment holds some. No body.         |
 
 `no-evidence` is not a refusal a caller reports. A project on a stack that
 carries no evidence path, such as `base` or `python`, hits this reason on
@@ -83,16 +83,32 @@ reporting the fields absent.
 
 ## What `[number]` selects, and what it does not
 
-Naming a number picks which pull request the rendered body claims to
-describe: its head commit and, when one already exists, the marked comment to
-edit in place. The base and the changed set are always read from the local
-checkout's own history, `git diff` and `git ls-tree` against the merge base
-with the trunk, rather than fetched for the named pull request over the API.
-That is correct for `git-pr` and `git-followup`, which never pass a number
-and always run from the worktree building the branch, so the local checkout
-and the named pull request describe the same branch. Naming a number for a
-pull request built somewhere else compares this checkout's own diff against a
-head commit that describes a different one.
+Naming a number picks the pull request the whole record describes: its head
+commit, its merge base, its changed set, and the marked comment to edit in
+place. The changed paths and whether each was added or modified come from the
+pull request's files endpoint, paged to the end, and the merge base comes from
+the compare endpoint, so the record is the same from any checkout. A run from
+the main worktree against a branch built elsewhere renders that branch's
+comparison.
+
+The trade is that the verb no longer sees evidence that is uncommitted or
+unpushed, which the comment's head-pinned image links could not show anyway.
+A path the pull request renamed or copied counts as added, since the new path
+has no counterpart at the merge base, so a rename loses its before image and
+renders `*(new)*`. A path the pull request removed is dropped, since it has no
+head image to show. A failed files read refuses as `unreadable-changes` rather
+than rendering a short set, and a missing merge base refuses as `no-base`.
+
+## A render never empties a comment that carries cases
+
+When the render holds no cases and the marked comment holds some, the verb
+refuses `would-empty` and prints no body. A render with no cases cannot tell a
+case removed on purpose from a short read, so the destructive direction needs a
+person: they edit the comment directly. The record keeps `commentId` and the
+carried fields, so the caller can still find the comment. A comment holding
+only a preview or a checklist has no cases to lose and still re-renders `ok`.
+`no-evidence` without a flag returns before any render, so the guard touches
+only `--preview`, `--local`, and `--checklist` calls.
 
 ## One comment, found by its own marker
 

package/docs/agents/records-push.md

@@ -58,4 +58,4 @@ The two `pull` refusals exist because the directions are not symmetric. A push o
 
 ## When it runs
 
-`.husky/post-merge` runs `push` after the task archiving loop, on every merge rather than only on one that archived a task. A review report and a memory entry both land on runs that close nothing. The call sits inside an `if` and last in the file, so an unreachable remote neither aborts the hook nor delays the archiving above it, and a checkout that never ran the setup reports nothing. Anything the hook misses is covered by running the verb by hand.
+`canon hooks post-merge`, which `.husky/post-merge` calls, runs `push` after the task archiving, on every merge rather than only on one that archived a task. A review report and a memory entry both land on runs that close nothing. The verb exits zero whatever the push answers, so an unreachable remote neither aborts the hook nor delays the archiving before it, and a checkout that never ran the setup reports nothing. `hooks.md` covers the verb. Anything the hook misses is covered by running the verb by hand.

package/docs/agents/records-validate.md

@@ -46,7 +46,7 @@ A memory `category` is compared against the sentence-case form of the filename p
 
 The standards filename check derives a word from the governed path rather than counting words in the name. Every member of the corpus is named for the artifact its scope statement governs, and one word is what that produces rather than the rule itself, so a check keyed on word count would pass a conforming single word naming the wrong artifact. Each path segment offers its own word, a dotted container segment offers none, a hyphenated segment offers its parts, and the singular and the plural both match.
 
-The scope statement is read exactly as `scripts/standards/list.sh` reads it for the catalog's `appliesTo` field: backticked spans in the first sentence alone, with an attribute standard resolving where that sentence backticks nothing and the statement says it governs an attribute. One sentence read two ways would let a standard pass the check while publishing a different jurisdiction to every consumer of the catalog. An attribute standard is exempt from the filename derivation because it governs no path to derive from, and a statement that anchors nothing and claims no attribute is reported as `scope-unanchored` rather than passed, since silence there would let the backticks be removed to disable the check.
+The scope statement is read exactly as `canon standards list` reads it for the catalog's `appliesTo` field: backticked spans in the first sentence alone, with an attribute standard resolving where that sentence backticks nothing and the statement says it governs an attribute. One sentence read two ways would let a standard pass the check while publishing a different jurisdiction to every consumer of the catalog. An attribute standard is exempt from the filename derivation because it governs no path to derive from, and a statement that anchors nothing and claims no attribute is reported as `scope-unanchored` rather than passed, since silence there would let the backticks be removed to disable the check.
 
 An absent `## Scope` section suppresses the filename finding. The name derives from the statement, so a missing section leaves nothing to derive against, and reporting both would name one defect twice and point the fix at the wrong file. The walk skips `index.md`, which is generated from its siblings rather than authored.
 

package/docs/agents/scripting.md

@@ -35,6 +35,12 @@ declares nothing a parser can read. A consumer mapping a file to its governing
 standards reads this rather than holding a table of its own, and reports an empty
 array rather than skipping the standard behind it.
 
+Each standard also carries `source`, the labeled path of the copy `canon standards
+<name>` would read: `standards/<name>.md` for the working root and
+`<canon>/standards/<name>.md` for the package corpus. A project's own standard
+lists beside the package's, and one sharing a package name lists once, as the
+project's copy.
+
 `canon claude seeds list` reads the same plan `canon claude init` applies, so the
 listing and the install cannot disagree. It now reports
 `canon/context/index.md`, which `init` has always installed and the listing

package/docs/agents/tasks-archive.md

@@ -30,11 +30,13 @@ The task carries its plan with it. When the closing task is the last live one wh
 
 Every other relative link in the task is re-resolved for the deeper folder too, whether its target moved or not: `Groundwork:`, `Intake:`, a `Plan:` or `Ready:` line whose target stayed put, and a link in the body. Fenced blocks, inline code spans, absolute URLs, `#` anchors, and rooted paths are left alone. `canon tasks decline` applies the same rebase, since `declined/` sits at the same depth. The plan retarget runs before the rebase and writes each moved link relative to the live board, so the rebase carries it into the deeper folder like every other link, while the ready retarget runs after it.
 
+Every other task file linking to the moved task is repointed at its new path too. The pass reads each markdown file in `.canon/tasks/`, `archive/`, and `declined/` except the moved file, `index.md`, `priority.md`, `backlog.md`, and the session handoffs, and resolves each relative link against the citing file's own folder. Only a link resolving to the old path is rewritten, with its `#` anchor kept, so an `archive/<stem>.md` link already correct, or the same stem in another folder, stays as written. Inline links and reference-style definitions (`[label]: path`) are both rewritten. Fenced blocks and inline code spans are skipped. `priority.md` and `backlog.md` are left alone because `canon tasks validate` reads a blocker there only while its target carries no `/`. Links broken before the move stay broken, and citations from plans, groundwork, and intake records are not read. The `relinked` array on the success record carries a root-relative `file` and a `links` count per file written, and is empty when nothing cited the task. The pass runs after the move, so a file it cannot read or write never stops the ordering-row removal or the index regen that follow. Each such file is left as it was and reported in `relinkFailed` as a root-relative `file` and a `message`, with a warning on stderr, and the verb still exits `0` because the move itself landed. A caller reading the record should treat a non-empty `relinkFailed` as links still pointing at the old path. `canon hooks post-merge`, which `.husky/post-merge` calls, reads the field and prints one `Links not repointed in:` line naming the files, since it discards the archive's stderr and nothing else on that unattended path would show the failure.
+
 The ready folder the task's `Ready:` line names moves with the plan to `.canon/ready/archive/`, falling back to a `.canon/ready/<nn>-<slug>/` path in the plan when the line is absent. The `Ready:` line and the plan's literal path to the folder are retargeted, and the `ready` field on the success record carries `from` and `to`, or `null` when nothing moved. A folder that resolves to nothing, sits already archived, or meets a taken destination moves nothing and refuses nothing.
 
 A plan several tasks share stays where it is, and its ready folder with it, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.
 
-The merge is what settles a plan. `.husky/post-merge` reads the pull request number off the squash subject and calls this verb, so both halves close in one act with nobody naming a file. That is why the move sits inside this verb rather than in a second call the hook would make after it, which could leave the task archived and the plan live.
+The merge is what settles a plan. `canon hooks post-merge`, which `.husky/post-merge` calls, reads the pull request number off the squash subject and calls this verb, so both halves close in one act with nobody naming a file. That is why the move sits inside this verb rather than in a second call the hook would make after it, which could leave the task archived and the plan live.
 
 `bad-input` covers a malformed command line, which all three task verbs answer the same way. It is separate from `ambiguous` and `no-match` because those describe the board, and a caller that passed two selectors would otherwise be sent to repair a task citation that is fine.
 
@@ -72,7 +74,7 @@ Exit codes: `0` declined, `1` refused. The `reason` field carries which gate fir
 
 The decision is written onto the task as a `Declined: <reason>, <who> on <YYYY-MM-DD>` line, anchored the same way `Pull request:` is, after the last origin line the task carries.
 
-The task carries its plans with it the same way archive does, each one the declining task is the last live citation of, and the success record carries the same `plans` array. A declined task's plan lands in `.canon/plans/archive/`, indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+The task carries its plans with it the same way archive does, each one the declining task is the last live citation of, and the success record carries the same `plans` array. Inbound links to the declined task are repointed at `declined/<stem>.md` and reported in `relinked`, as the archive section describes. A declined task's plan lands in `.canon/plans/archive/`, indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
 
 Skills branch on the reason rather than on the exit code, the same rule `canon tasks archive` states:
 

package/docs/agents/tasks.md

@@ -35,7 +35,7 @@ canon tasks next-label --json | jq -r '.label'
 
 ## Archive and decline
 
-`canon tasks archive` moves a shipped task into `.canon/tasks/archive/`, selected by its stem or by the pull request it carries, and `canon tasks decline` moves one decided against into `.canon/tasks/declined/`. Both carry the plan and the ready folder along when the task is their last citation. The selectors, the gates, and the refusal reasons are in `tasks-archive.md`.
+`canon tasks archive` moves a shipped task into `.canon/tasks/archive/`, selected by its stem or by the pull request it carries, and `canon tasks decline` moves one decided against into `.canon/tasks/declined/`. Both carry the plan and the ready folder along when the task is their last citation, and both repoint every link to the moved task from another task file. The selectors, the gates, and the refusal reasons are in `tasks-archive.md`.
 
 ## Plan verbs
 

package/docs/agents/worktrees.md

@@ -53,9 +53,9 @@ Field order is part of the contract. A shell reads this record with a pattern ra
 
 ## What calls it
 
-`.husky/post-merge` runs `canon worktrees reclaim --json` on every merge, between the records push and the upgrade block, so a merged branch's worktree goes without a person remembering. `CANON_SKIP_RECLAIM=1` turns that step off.
+`canon hooks post-merge`, which `.husky/post-merge` calls, runs `canon worktrees reclaim --json` on every merge, between the records push and the upgrade, so a merged branch's worktree goes without a person remembering. `CANON_SKIP_RECLAIM=1` turns that step off. `hooks.md` covers the verb.
 
-The hook's call carries no `--root` and no `cd`, unlike the two steps above it. Git runs a hook from the top level of the worktree the pull happened in, and the verb reads its own working directory to refuse that worktree as `current-worktree`, so a root argument would turn the running worktree into an ordinary candidate and let a pull inside a linked worktree delete the ground under itself.
+That call carries no `--root` and runs from the hook's own working directory, unlike the two steps before it. Git runs a hook from the top level of the worktree the pull happened in, and the verb reads its own working directory to refuse that worktree as `current-worktree`, so a root argument would turn the running worktree into an ordinary candidate and let a pull inside a linked worktree delete the ground under itself.
 
 ## What makes a worktree reclaimable
 

package/docs/target/scenarios.md

@@ -46,11 +46,11 @@ canon tooling sync vite-react ./frontend --skip base --write
 canon tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.sh`, `scripts/verify.ts`, and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
 
 A sync whose target sits below the git root knows it is writing into a subfolder:
 
 - It withholds `.github/`, since GitHub reads workflows only at the repository root, and names each withheld file. Run the subtree from a job in the root workflow instead, with `working-directory` set to the subtree path the sync prints, such as `working-directory: frontend`.
 - It writes a nested `cspell.json` that registers the subtree's word lists, so a root `cspell '**'` reads them for files under that folder. It leaves a spell config the subtree already has alone.
 - It installs no dependencies and adds no scripts to a subtree without a `package.json`. It names what it skipped and ends on `run 'bun init' in <path>, then sync again`.
-- The subtree's `scripts/verify.sh` skips the format, spell, and shell phases a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script.
+- The subtree carries no `check` script, since that lives in the root's base layer, so run `./scripts/verify.sh` there. It skips the format, spell, and shell phases a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.7.0",
-  "description": "Infrastructure and quality tooling for developer workflows",
+  "version": "5.9.0",
+  "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
     "canon": "./src/cli.ts"

package/src/claude/skills-audit.ts

@@ -34,6 +34,7 @@ export const CORPORA: readonly string[] = [
 export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'codebase-layout'),
   join(SHIPPED_CORPUS, 'test-craft'),
+  join(SHIPPED_CORPUS, 'review-craft'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */

package/src/cli.ts

@@ -30,6 +30,7 @@ import { register as migrate } from '@/commands/migrate'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as worktrees } from '@/commands/worktrees'
+import { register as hooks } from '@/commands/hooks'
 import { register as audits } from '@/commands/audits'
 import { register as gate } from '@/commands/gate'
 import { register as secrets } from '@/commands/secrets'
@@ -91,6 +92,7 @@ migrate(program)
 sessions(program)
 targets(program)
 worktrees(program)
+hooks(program)
 secrets(program)
 deps(program)
 labels(program)

package/src/commands/claude.ts

@@ -111,7 +111,7 @@ interface PluginUpdateOptions {
 /**
  * `no-claude` and `no-plugin` name permanent conditions on a machine that
  * never carries the marketplace plugin at all, matching the `gh-missing` and
- * `no-repository` reasons `.husky/post-merge`'s other two steps already stay
+ * `no-repository` reasons the post-merge hook's other two steps already stay
  * quiet on forever rather than nagging a project that will never fix them.
  * Every other reason is a real defect and prints.
  */

package/src/commands/docs.ts

@@ -1,7 +1,6 @@
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { type DocEntry, listDocs } from '@/docs/list'
 import { listTopics, readTopic, resolveTopic } from '@/docs/read'
-import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
 
@@ -22,19 +21,60 @@ export function register(program: Command): void {
         '',
       ].join('\n'),
     )
-    .action(async (topic: string | undefined) => {
-      if (topic === undefined) {
-        intro('canon docs')
-        await execScript('docs/list.sh', [])
-        return
-      }
-
-      process.exitCode = get(topic)
+    .action((topic: string | undefined) => {
+      process.exitCode = topic === undefined ? list({}) : get(topic)
     })
 
-  registerPassThroughVerbs(docs, 'docs', ['list'])
+  docs
+    .command('list')
+    .description('List the docs and domain context with their descriptions')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: ListOptions) => {
+      process.exitCode = list(opts)
+    })
+}
+
+interface ListOptions {
+  readonly json?: boolean
 }
 
+/**
+ * The text listing is frame lines on stderr and the `--json` record is the one
+ * thing on stdout, so a caller piping it through a wrapper reads JSON alone.
+ * The frame opens after the `--json` branch and never wraps it.
+ */
+function list(opts: ListOptions): number {
+  const catalog = listDocs(PROJECT_ROOT)
+  const mismatch = checkoutMismatchWarning(process.cwd())
+
+  if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
+    const docs: DocEntry[] = catalog.hasContext
+      ? [...catalog.docs, ...catalog.context]
+      : catalog.docs
+    process.stdout.write(`${JSON.stringify({ docs })}\n`)
+    return 0
+  }
+
+  intro('canon docs')
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  logStep('Docs')
+  for (const entry of catalog.docs) logInfo(describeEntry(entry))
+
+  if (catalog.hasContext) {
+    logStep('Domain context')
+    for (const entry of catalog.context) logInfo(describeEntry(entry))
+  }
+
+  outro()
+  return 0
+}
+
+const describeEntry = (entry: DocEntry): string =>
+  `${entry.name} : ${entry.description}`
+
 /**
  * Writes the document body to stdout and every frame line to stderr, so a
  * caller capturing the output with `$(...)` receives the document alone.

package/src/commands/hooks.ts

@@ -0,0 +1,67 @@
+import type { Command } from 'commander'
+import {
+  readMergedSubjects,
+  runCanon,
+  runPostMerge,
+  STEP_VERBS,
+} from '@/hooks/post-merge'
+import { mainWorktreeRoot } from '@/worktree'
+
+interface PostMergeOptions {
+  readonly root?: string
+}
+
+export function register(program: Command): void {
+  const hooks = program
+    .command('hooks')
+    .description('Run the steps a git hook drives')
+    .helpOption('-h, --help', 'Show this help message')
+
+  hooks
+    .command('post-merge')
+    .description('Run the post-merge steps in order and report each in a line')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--root <path>',
+      'Main worktree root holding the board and the records',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Runs these steps in order, each a child call reading its --json record:',
+        ...Object.values(STEP_VERBS).map((verb) => `  canon ${verb.join(' ')}`),
+        '',
+        'The archive runs once per pull request number the merge brought in.',
+        'Lines go to stderr, and an ordinary merge prints nothing.',
+        '',
+        'The reclaim runs from the working directory with no root, so a pull',
+        'inside a linked worktree never removes the worktree it stands in.',
+        '',
+        'Environment:',
+        '  CANON_SKIP_RECLAIM=1        skip the worktree reclaim',
+        '  CANON_SKIP_UPGRADE=1        skip the CLI reinstall',
+        '  CANON_SKIP_PLUGIN_UPDATE=1  skip the plugin update',
+        '',
+        'Exit codes:',
+        '  0  always, since a hook failing aborts nothing useful',
+        '',
+        'Examples:',
+        '  canon hooks post-merge',
+        '  CANON_SKIP_UPGRADE=1 canon hooks post-merge --root "$root"',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PostMergeOptions) => {
+      const cwd = process.cwd()
+      await runPostMerge({
+        root: opts.root ?? (await mainWorktreeRoot()),
+        cwd,
+        subjects: await readMergedSubjects(cwd),
+        env: process.env,
+        run: runCanon,
+        write: (text) => process.stderr.write(text),
+      })
+      process.exitCode = 0
+    })
+}