@erclx/canon 5.38.0 → 5.40.0

package/docs/agents/pr-preview.md

@@ -1,155 +0,0 @@
----
-title: The pull request preview deploy
-description: How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
----
-
-# The pull request preview deploy
-
-`canon pr preview` publishes a pull request's branch to a Cloudflare Pages
-preview and reports the address. `git-pr` calls it after the evidence
-comparison, then re-renders that comment through `canon pr evidence --preview`
-so the link sits on the address line under its heading. A reviewer gets a page
-to click into before merging rather than screenshots and a checklist alone.
-
-```bash
-canon pr preview --json
-canon pr preview 1341 --json --timeout 20
-canon pr preview 1341 --check --json
-```
-
-## Which workflow it dispatches
-
-The verb reads `.github/workflows/*.yml` and `*.yaml` in the checkout and picks
-the first file, in path order, that meets four tests:
-
-- It runs `pages deploy`.
-- It carries a `workflow_dispatch` trigger, since nothing else lets a caller
-  start it on a branch.
-- Its deploy passes `--branch=${{ github.ref_name }}`.
-- It prints a `canon-preview-alias:` line.
-
-The workflow is read before the pull request, so a project with no fenced
-deploy is refused without a network call.
-
-## Which branches it serves
-
-A dispatch runs the workflow whatever its `on.push.paths` filter says, so a
-branch that touched nothing the site builds from would get a preview showing
-none of its change. The verb reads the pull request's changed paths and matches
-them against the picked workflow's own `on.push.paths` or `on.push.paths-ignore`
-list, applying `!` patterns in order the way GitHub does. When nothing matches,
-it refuses as `unserved` and dispatches nothing. `--check` answers `unserved`
-the same way.
-
-The push filter is the one statement of what the site builds from, since it
-already decides when production deploys. A workflow with neither list, with no
-push trigger, or that does not parse as YAML serves every change, so a project
-whose every change ships keeps minting for every branch.
-
-A removed path counts, the same as GitHub's own push filter counts it, so a
-branch whose only site change deletes a file still gets a preview.
-
-## Why an unfenced deploy is refused
-
-Cloudflare Pages publishes a deploy that names no branch to production. A
-dispatch from an unmerged branch through such a workflow ships that branch to
-the live site, so the verb refuses as `unfenced` and dispatches nothing. The
-fix is one flag on the deploy command, and the cloudflare stack's
-`deploy.yml` already carries it.
-
-## Where the address comes from
-
-The workflow prints the alias Cloudflare returned for the deploy, read from
-`wrangler-action`'s `pages-deployment-alias-url` output, on a fixed line:
-
-```plaintext
-canon-preview-alias: https://<alias>.<project>.pages.dev
-```
-
-The verb reads that line out of the finished run's log rather than computing
-the address from the branch name. Cloudflare flattens a branch into its alias
-and may truncate it, and a computed address that is wrong is worse than none.
-The output needs wrangler 3.78 or later, so the workflow pins
-`wranglerVersion`.
-
-`gh workflow run` reports no run id. The verb lists the branch's dispatched
-runs before dispatching and takes the one id that appears afterwards, which
-keeps the match independent of the local clock.
-
-## What the record carries
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason               | What it means                                                              |
-| -------------------- | -------------------------------------------------------------------------- |
-| `ok`                 | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`          | No dispatchable workflow runs `pages deploy`.                              |
-| `unserved`           | The push path filter matches no changed path, so nothing was dispatched.   |
-| `unreadable-changes` | The pull request's changed paths could not be read.                        |
-| `unfenced`           | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`           | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`         | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`            | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout`        | `--timeout` was not a positive number.                                     |
-| `gh-missing`         | `gh` is not on the path.                                                   |
-| `gh-failed`          | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`          | The pull request carries no head branch name.                              |
-| `check-timeout`      | `--check` was combined with `--timeout`.                                   |
-
-The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
-going, so the preview may still land after the verb has given up on it.
-
-## Checking which head a preview was built from
-
-`--check` dispatches nothing and waits on nothing. It lists the branch's
-`workflow_dispatch` runs, takes the newest successful one by creation time, and
-compares the head it ran at with the branch tip read from the remote. The tip
-comes from the remote rather than the pull request object's `headRefOid`, which
-lags a push. `--check` takes no `--timeout` and refuses one as `check-timeout`.
-
-The alias serves the newest successful deployment for the branch and names no
-sha, so the run listing is the only record of the built head. The
-`workflow_dispatch` filter also drops the cleanup run a closed pull request
-fires, which concludes `success` with its deploy skipped. A project that deploys
-on `push` to a feature branch would need that filter widened.
-
-| Reason     | What it means                                                         |
-| ---------- | --------------------------------------------------------------------- |
-| `fresh`    | The newest successful deploy built the tip. Exit 0.                   |
-| `stale`    | It built an earlier head. `built` and `tip` name both. Mint again.    |
-| `building` | A deploy of the tip is still running. Wait rather than minting again. |
-| `no-build` | No deploy of the branch has succeeded.                                |
-
-The record also carries `runId` for the deploy it read. The check covers the
-hosted address only, so a local address has no run to read and stays unverified.
-`review-ui` runs it before driving a hosted preview and posts nothing on any
-reason but `fresh`.
-
-## How the address reaches the pull request
-
-`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the address
-line under the evidence body's `## Evidence` heading. With no evidence image in
-the diff, the body is the heading, that line, and the trailing marker alone, so
-a pull request whose screenshots did not change still gets one comment a later
-call can find and edit.
-
-A later `canon pr evidence` run without `--preview` reads the address off the
-marked comment and carries it into the new body. `git-followup` re-renders the
-comment after every push, and without that carry the first push would delete
-the link. A visual checklist folded in through `--checklist` carries the same
-way, which is what keeps that push from wiping boxes a reviewer already ticked.
-
-## Removing a preview
-
-A `pull_request` trigger on `closed` in the same workflow runs a cleanup job
-that deletes every preview deployment Cloudflare holds for the branch. The
-deploy job carries `if: github.event_name != 'pull_request'`, so a closed pull
-request never deploys. The same close runs `canon pr local --remove`, which
-drops the address line from the evidence comment, hosted link included, so the
-comment never links a deployment that no longer exists.
-
-## What this does not cover
-
-The verb builds only the deployed-and-public case. A private repository whose
-previews need access protection waits for a project that needs it. A local
-server stands in where there is no deploy, through `canon docs pr-local`.

package/docs/agents/pr-reads.md

@@ -1,111 +0,0 @@
----
-title: Head-sensitive pull request reads
-description: Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
----
-
-# Head-sensitive pull request reads
-
-`canon pr head`, `canon pr checks`, and `canon pr review-state` each answer about a commit, and each exists because the field GitHub offers answers a different question. The first two resolve the branch tip from the remote with `git ls-remote` rather than taking the pull request object's word for which commit the branch is on. The third reads what a review pass covered off a marker the pass wrote, rather than off the head GitHub stamped when the review was submitted.
-
-```bash
-canon pr head
-canon pr head 1341 --json
-canon pr checks
-canon pr checks 1341 --json
-canon pr review-state
-canon pr review-state 1341 --json
-```
-
-## The pull request object is not the authority for a head
-
-The pull request's head sha, `head.sha` on the REST pull read and `headRefOid` in `gh pr view`, is a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
-
-Two failures on 2026-09-01 came off that one field. A reviewing session posted a finding calling a pushed commit unpushed. A worker fired a green claim and retracted it on its own thread minutes later. Neither session did anything wrong with the value it was handed. The value was stale and said so nowhere.
-
-The remote ref carries no such lag. `git ls-remote --heads origin <branch>` asks the remote itself rather than a tracking ref, which is only as current as the last fetch, and the push worth catching is the one this process never saw.
-
-The argument is stated here once. The shipped skill bodies call the verb rather than repeating it, because a sentence telling a session to compare two shas is a sentence a session can decide it already followed.
-
-## What each verb answers
-
-`canon pr head` reports `fresh` when the object and the remote name the same commit and `stale` when they disagree, with both shas on the record. The tip is the authority and the object's head is the claim being checked against it.
-
-`canon pr checks` reads `repos/{owner}/{repo}/commits/<tip>/check-runs` and collapses it to `passing`, `failing`, or `pending`. A failure outranks a run still going, since a run in flight cannot clear a job that already failed.
-
-`canon pr review-state` reports `heading` and `state` for the newest pass in the review family, `commit` and `readAt` for what it covered, `submittedAt` for when GitHub recorded it, and `source` for which of those readings answered. A thread carrying no pass reports `state` and `source` both as `none` with nothing else on the record.
-
-`gh pr checks` cannot be made to answer this question at all, which is the argument for the move rather than a preference between two working commands. Its `--json` field set is `bucket, completedAt, description, event, link, name, startedAt, state, workflow`, with no sha among them, so a caller cannot even learn which commit its answer describes.
-
-## A review's stamps describe the submission, not the read
-
-`commit.oid` on a review names whatever the pull request head was at the instant the review was submitted. `submittedAt` names that instant. Neither names the commit the reviewing session actually opened, and the two are only the same when nothing was pushed while the comment was being written.
-
-A push landing in that window moves both onto a commit nobody reviewed. The next pass then scopes its delta past that commit and reports it covered, which is the failure direction that loses work: the commit is skipped rather than re-read. It fired on a pull request in this toolkit on 2026-09-07, where a pass read one commit, the branch pushed another during the compose, and the poll reported the second as already seen. What it skipped was a genuine fix, and a reader comparing the sha in the report against the sha in the pass caught it.
-
-`review-pr` therefore ends every body it posts with a marker naming what it read:
-
-```markdown
-<!-- review-pr: commit=<sha> read-at=<iso8601> -->
-```
-
-Both values are taken at the top of the pass rather than at the post, so the compose window falls outside what the marker claims. An HTML comment renders as nothing on GitHub, so a reader of the thread never meets it.
-
-The last non-empty line is where it has to sit, and the reader looks nowhere else. Searching a body for the last match instead reads a marker the body was displaying rather than claiming, since a fenced block showing the format on its own line trims to exactly the pattern, and a pass carrying no marker of its own would then hand the next reader a commit taken from an illustration. That is the same defect through a second door, so position rather than shape is what separates a claim from a quotation.
-
-`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's own filters, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
-
-`source` on the record says which reading answered, and a caller checks it before trusting the rest:
-
-| Source     | What it means                                                                               |
-| ---------- | ------------------------------------------------------------------------------------------- |
-| `marker`   | The pass wrote its own read-time record, which is the authority                             |
-| `fallback` | A pass posted before this shipped, read off the submission stamps and carrying their defect |
-| `none`     | The thread carries no pass, so the next one is a first pass                                 |
-
-The record carries `submittedAt` beside `readAt` rather than in place of it, because each is right about a different question. What a pass had read is a fact about the read, and how long a posted comment has waited on a human is a fact about the submission. The orchestrator poll reads the first for its coverage test and the second for its age test.
-
-A `PUT` rewrite of a standing close-out inherits the fix without a mechanism of its own. That request replaces the body and the marker rides in it, so a rewritten comment names the commit the rewriting pass read. `submittedAt` stays pinned to the original submission, which is the reading the age test wants anyway.
-
-## An empty run list is not a pass
-
-Keying the query on a sha is necessary and not sufficient. The endpoint answered with `total_count` 2 and an empty row list during a measured window on 2026-09-02, so a reader that finds no run for the tip and reports `passing` reproduces the false green behind a better query.
-
-Both empty cases report `pending` instead: a tip carrying no run yet, and a listing whose rows all belong to some other commit. The record separates them, since `matched` counts the runs belonging to the tip and `foreign` counts the rest, and a caller that wants to tell "not started" from "still going" reads those two numbers rather than the state alone.
-
-The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
-
-A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. The pull request's `mergeable_state` is the field that separates the two. The verb raises it to upper case, matching the GraphQL `mergeStateStatus` it replaced, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
-
-A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
-
-A count above the rows returned reports `pending` for the same reason. The query asks for 100 rows against the endpoint's default of 30, and a commit carrying more than that comes back short, so the verb reports the tip as unread rather than collapsing the page it happens to hold. `reported` against `matched` and `foreign` is where a reader sees which of the three shapes produced the answer.
-
-## Reading the answer
-
-Branch on the record rather than on the exit. Both verbs exit 0 whenever they resolved a tip, whatever the verdict, and 1 only when they refused. An operator shell profile can wrap `canon` in a function whose status comes from a trailing command, which flattens every non-zero exit to 0, so the exit is not a channel either verb puts a verdict on. `gh pr checks` reserving exit 8 for pending is the pattern being replaced rather than one to copy.
-
-Each refusal names a different repair:
-
-| Reason               | What it means                                                                              |
-| -------------------- | ------------------------------------------------------------------------------------------ |
-| `gh-missing`         | `gh` is not on the path, so no pull request resolved                                       |
-| `gh-failed`          | `gh` could not answer for this branch, so name a number instead                            |
-| `ambiguous-pull`     | Two open pull requests share the branch against different bases, so name a number          |
-| `no-branch`          | The pull request carries no head branch name, so no ref could be read                      |
-| `unresolvable-ref`   | The remote read failed, which is not the same answer as an absent branch                   |
-| `no-remote-branch`   | The remote carries no branch by that name, so there is no tip to compare against           |
-| `no-object-head`     | The pull request object reported no head, so `head` has nothing to compare the tip against |
-| `runs-unreadable`    | The check runs for the tip could not be read, which is unread rather than none             |
-| `reviews-unreadable` | The reviews on the pull request could not be parsed, which is unread rather than none      |
-
-A failed remote read and a branch the remote does not carry stay apart rather than collapsing into one reason. Reading the first as the second would report a network refusal as a deleted branch, and the repairs have nothing in common.
-
-## What it costs
-
-One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-09-01 and 2026-09-02, against 0.001s for the local ref read. The spread is the network rather than the command, so read it as roughly half a second and not as a figure to compare a later reading against. Every caller pointed at these verbs already spends a `gh` round trip on the same line, so the added cost lands on a path that was never local to begin with.
-
-One head-sensitive read is left on the object deliberately. `canon targets pulls` reads `statusCheckRollup` for every open pull request across every target, where resolving a tip per row would cost one remote read per pull request across a dozen projects, against a surface that reports a listing rather than gating a push.
-
-The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It reads over REST alone, one reviews read and one issue-comments read per pull request, plus a pull read only when `canon pr head` returns no tip. It spends a further read per pull request per tick besides, since `canon pr review-state` makes its own REST reviews read beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
-
-`canon pr key-changes` also stays on the object, for a different reason. It reads the body and the head off one pull read, so the two describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it. The file list comes off a second read, since only GraphQL returns it beside the body and a cloud session's proxy refuses GraphQL.

package/docs/agents/pr-tick.md

@@ -1,72 +0,0 @@
----
-title: The pull request checklist tick
-description: How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
----
-
-# The pull request checklist tick
-
-`canon pr tick` ticks the boxes of the visual checklist on the pull request's
-evidence comment. `review-ui` calls it once its verdict has posted, for every
-box that passed at the head it drove, so the person merging reads a checklist
-a driver worked through instead of one that stays empty.
-
-```bash
-canon pr tick 1341 --boxes 1,2,4 --head <sha> --json
-```
-
-Box numbers come from the `boxes` field of `canon pr evidence --json`, which
-numbers the checklist's box lines in order. A caller never counts lines itself.
-
-## What a tick looks like
-
-A ticked box ends in the commit it passed at, visible on the comment:
-
-```markdown
-- [x] click "Pricing" in the header → the pricing page opens · passed at `<short-sha>`
-```
-
-The stamp is visible rather than an HTML comment because the person it is for
-reads the merge record, and a hidden head would tell the machine what the
-reader cannot see. The reader matches the stamp only as the trailing segment of
-a line, so a box whose own text says `passed at` is left alone.
-
-## When a tick is cleared
-
-A tick is a claim about one commit, so a render at another commit does not
-carry it forward. `canon pr evidence` settles the checklist before it renders:
-
-- A tick stamped for the render's head stays.
-- A tick stamped for any other head is cleared and loses its stamp.
-- A tick with no stamp, such as one an author or the operator added by hand,
-  stays only when the comment it came from described the render's head.
-
-A render at the same head after `--preview` keeps every tick. A push that
-reaches the branch without a render leaves its ticks in place until the next
-one, and the stamp still shows which head earned them.
-
-## What it refuses
-
-`reason` on the record is what a caller branches on, not the exit code:
-
-| Reason         | What it means                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------------ |
-| `ticked`       | The boxes were ticked, with the remote tip in `head`.                                                        |
-| `stale-head`   | `--head` is not the branch tip on the remote. Nothing is written.                                            |
-| `taste-box`    | A named box ends in `(taste)`. Nothing is written.                                                           |
-| `no-box`       | A named number is past the end of the checklist. Nothing is written.                                         |
-| `no-checklist` | The evidence comment carries no checklist.                                                                   |
-| `no-comment`   | No comment on the pull request carries the evidence marker.                                                  |
-| `bad-boxes`    | `--boxes` is not a list of positive whole numbers, or `--head` is not a hex sha of seven characters or more. |
-
-A taste box is a judgment of look or feel that a driver reports as needing a
-person's eyes. Refusing it in the verb makes that rule a check rather than a
-sentence a driver can talk itself out of, and a refusal writes none of the
-boxes named beside it.
-
-The head is compared against the tip read from the remote rather than the pull
-request object, which lags a push by up to a minute. A push landing between
-that read and the write leaves a tick at an older head until the next render
-clears it, the same window `canon pr head` documents.
-
-The verb edits the marked comment in place with a `PATCH`, the way
-`canon pr local --remove` does, and ticking a box again restamps it.

package/docs/agents/records-push.md

@@ -1,61 +0,0 @@
----
-title: Records push
-description: Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
----
-
-# Records push
-
-`canon records push` commits the backed record folders to a private remote and pushes them. `canon records pull` fetches the other direction and writes them back. Both take `--json` and `--root` the way `validate` does, and both exit `0` on agreement and `1` on a refusal.
-
-```bash
-canon records push
-canon records push --json
-canon records pull
-```
-
-At the `.canon` root, the backed folders are every top-level directory less three: `tmp`, which is deletable without loss, `ordinal-locks`, whose entries are transient per claim and would race the claim they guard, and `.records.git`, which is the history the rest are pushed into. Nothing bounds the set from outside, since the claude manifest ships one `.canon/` root entry and names no folder, so a record folder added later enters the payload on its own rather than waiting on a name written here. A push names each folder in scope that the records index has never tracked before, so a folder that picked up a name by mistake, such as a misrouted scratch write, is visible in the report rather than entering the payload silently. The report also lists every file new to the history under `added`, since a stray file inside a folder already tracked is visible only by name.
-
-The three excluded names bound the records index as well as the disk. A name an older binary committed, such as `tmp`, is removed from the history once and reported under `dropped`, and no later push stages it again. That removes it from the tip going forward and purges nothing from earlier commits the remote already holds. A project's own drafts folder needs no config to be backed: moved to `.canon/<name>/`, it is a top-level directory like any other and enters the payload on the next push. The legacy `.claude` root keeps a fixed allowlist instead, since that root also holds tracked `skills/`, `rules/`, and `hooks/` a push must never carry, and an exclusion set there would stage all three. Each name is a top-level record folder and every archive sits inside the one it archives, so the set stays at one entry per surface however many archives appear, and it deliberately does not match the six record kinds `validate` hardcodes.
-
-Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the backed folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
-
-## Setup
-
-A person creates the records repository once per machine, and the verbs refuse with the commands when it is absent:
-
-```bash
-git --git-dir=.canon/.records.git init
-git --git-dir=.canon/.records.git remote add origin <private-repo-url>
-printf '.canon/\n' >> .gitignore
-```
-
-The ignore line is repeated here rather than left to the install, because the person running these commands is the one who creates the directory and the rule is worth reading beside the command that needs it. The claude manifest ships `.canon/` too, so a project that ran `canon tooling sync` already carries it and this line is a no-op there. One root entry covers the history and every record beside it, which is what makes the rule worth stating once rather than per folder.
-
-Point it at a private repository, and at one that is not a remote of the project. Records carry the plans, the review reports, and the groundwork trails, so a public project publishes all of it to anyone who fetches all refs. `push` compares the configured origin against every remote of the project and refuses on a match. A read of that list which fails refuses as well, since an empty list clears the comparison for every origin and a gate that passes on its own failure is no gate.
-
-## Refusals
-
-| Reason              | What fired                                                                             |
-| ------------------- | -------------------------------------------------------------------------------------- |
-| `split-roots`       | Record folders sit under both roots, so the resolved work tree is not the whole set    |
-| `no-repository`     | No `.canon/.records.git`, answered with the two setup commands                         |
-| `no-remote`         | The records history has no `origin`                                                    |
-| `remote-unreadable` | The project's own remotes could not be read, so the shared-origin gate could not run   |
-| `remote-shared`     | The records origin is also a remote of the project                                     |
-| `no-remote-records` | `pull` found no branch on the records origin                                           |
-| `local-changes`     | `pull` found records on disk that the history does not carry                           |
-| `local-ahead`       | `pull` found local commits that never reached the origin                               |
-| `unsafe-payload`    | `push` found a pending file over 25 MB or carrying a credential, named under `blocked` |
-| `git-failed`        | A git call failed, with its stderr in the message                                      |
-
-`split-roots` runs ahead of every gate below it and fires on a half-migrated tree, which is what a `canon migrate records` run that failed partway leaves. `recordRoot` answers for the whole tree on the first root that exists, so a folder left at the old root is absent from the work tree while the records index still names it, and an unguarded `add -A` would stage its deletion and drop it from the remote on the next push. Finish the move, or put the stranded folders back beside the others.
-
-`unsafe-payload` runs before anything is staged, so a refusal leaves the index, the log, and the object store as it found them. It reads every new or changed file the push would stage and blocks one over 25 MB, which is read off the file's size without opening it, or one carrying a value `canon secrets scan` would report, through the same patterns and the same `canon-allow-secret` marker. It refuses the whole push rather than skipping the file, and `--json` lists each path with its cause and a detail that names the credential's kind and line, never its value. Move the file out of the record folders, such as into `.canon/tmp/`, or remove the credential, then push again. The guard reads only what this push would add, so a credential committed before it existed stays in the history unreported.
-
-A push the remote rejects undoes the commit that run made and leaves the records on disk, so the next run does not send a payload the remote already refused. A history an older binary committed and left unpushed is outside that undo, and the guard never reads it either, so every push sends the same blob again. Reset it by hand from the project root to the last commit the origin holds, `git --git-dir=.canon/.records.git --work-tree=.canon reset <commit>`, and push again. The `--work-tree` is required, since the setup `init` marks the history bare and git refuses that reset on a bare repository.
-
-The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding no backed folders has nothing to lose, so a restore onto a fresh checkout runs straight through.
-
-## When it runs
-
-`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 plan edit 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-stale.md

@@ -1,40 +0,0 @@
----
-title: Records stale
-description: Counting the releases since the requirements record was last reviewed, where the review date is read from, and the exit codes and refusals
----
-
-# Records stale
-
-`canon records stale canonical` reports when the requirements record was last reviewed and how many releases have shipped since. A skill takes the count from the verb rather than re-deriving it from the tag list.
-
-```bash
-canon records stale canonical
-canon records stale canonical --json
-```
-
-| Option          | Behavior                                                          |
-| --------------- | ----------------------------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout                           |
-| `--root <path>` | Project root, defaulting to the current worktree rather than main |
-
-`canonical` is the one kind it reads. Any other argument refuses as `unknown-kind`, including `memory`, which the verb read until the memory pen retired.
-
-It reports and never writes, matching `validate` and `size`.
-
-## Canonical records
-
-`canonical` reads `REQUIREMENTS.md` at whichever surface root carries it, `canon/` ahead of `.claude/`, and omits it when the project does not hold one. It is tracked, so `--root` defaults to the worktree the caller stands in rather than the main one, and a stamp a branch just wrote reads back from that branch.
-
-The review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `claude/skills/draft-doc/references/requirements.md`. It is a date rather than a commit, since a commit written on a feature branch never reaches a trunk that squash-merges. The field is read off the raw frontmatter block rather than a parsed value, since a YAML parser resolves a bare date to a date object on one schema and a string on another. A value that is not a calendar date reads as never reviewed, and the record carries the raw value as `invalidReviewed` so a review can see it rather than the verb throwing over one hand edit.
-
-The count is every release tag merged into `HEAD` whose creator date falls after the reviewed day. A release tag ends in a dotted version, bare as `v5.25.0` or behind a component prefix as `canon-v2.1.0`, so an eval, deploy, or snapshot tag on the trunk never inflates it. A lightweight tag's creator date is its commit's date and an annotated tag's is the tagging date, so a project mixing both counts by two clocks.
-
-The record carries `tagged`, false when `HEAD` has merged no release tag or the repository has no commit yet, and one `docs` row per doc with `path`, `reviewed`, `releasesSince`, and `latestRelease`. `releasesSince` is null on a doc never reviewed and `0` on one reviewed after every tag. With no tags it is also `0`, which is why `tagged` travels beside it.
-
-It gates nothing, and no hook, gate stage, or workflow runs it. `canon:document-health` reads it when asked to review the two records.
-
-## Exit codes and refusals
-
-Exit codes: `0` the reading completed, whatever it found, and `1` refused. A release count is a prompt for the review to judge rather than a failure, so nothing here gates.
-
-A `reason` field carries which gate fired: `unknown-kind` for any kind but `canonical`, and `unreadable-tags` when the tags cannot be read.

package/docs/agents/records-validate.md

@@ -1,57 +0,0 @@
----
-title: Records validate
-description: Validating the session records, the per-kind checks, which root they default to, the exit codes, and the refusal reasons
----
-
-# Records validate
-
-`canon records validate <kind>` reports where a file and the standard governing it disagree. Four kinds exist, each a gitignored folder under the record root resolved at `.canon/` first: `plans`, `groundwork`, `intake`, and `teach`.
-
-```bash
-canon records validate plans
-canon records validate intake --json
-```
-
-| Option          | Behavior                                      |
-| --------------- | --------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout       |
-| `--root <path>` | Project root, defaulting to the main worktree |
-
-It reads and never writes. A session record is per-machine scratch with no history behind it, so a repair that guessed wrong could not be undone.
-
-Nothing fires it automatically. The four record folders are gitignored, so the standards-audit hook exits early on them and any check reading changed files from git never lists one. The verb runs at the moment a session claims the record is finished, which is the same placement `canon tasks validate` takes over the board.
-
-The two record roots every kind resolves at are in `records.md`.
-
-## What each kind checks
-
-| Kind         | What it reports                                                                                                                                                                                                                                                                                                                                   |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, a question carrying no suggestion or no answer slot, and a batch still staged with a `**Batch N**` sub-heading inside the one file rather than split into its own plan |
-| `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse                                                                                                             |
-| `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                                                                                                                                        |
-| `teach`      | A workspace folder carrying no two-digit ordinal, an absent `MISSION.md`, `RESOURCES.md`, or `GLOSSARY.md`, a file missing `title` or `description`, a mission with no `date` as `YYYY-MM-DD` or no `## Success looks like` section, an unnumbered learning record, and a reference page opening with an ordinal                                  |
-
-The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
-
-The item check skips `00-overview.md` and `99-next-session.md`, since neither holds items and running it over the handoff would report every heading it carries.
-
-A plan section opens as a bold label or as an H2 and the check counts both, naming the reference's spelling when it reports one missing. Plans split roughly four to one between the two forms, so failing the variant would report nearly every plan on a rule that costs a reader nothing.
-
-A section runs to the next marker-shaped line whatever it names, so a plan carrying a label of its own closes the section above it rather than collecting into it. Fenced blocks are dropped before any of this, since a plan showing the shape it writes puts real-looking bullets and headings inside a fence.
-
-## Exit codes and refusals
-
-Exit codes: `0` every check passed, `1` refused, `2` at least one record carries a finding. A `reason` field carries which gate fired: `no-folder` when none of the kind's directories exist, and `unknown-kind` when the argument names no published kind. A `no-folder` message names every candidate, so a refusal names both record roots.
-
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `findings` array and its `reason` rather than the exit when a skill consumes this.
-
-The four record folders are shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. A linked worktree validates the same records every other session reads.
-
-Skills branch on the findings rather than on the exit code:
-
-```bash
-canon records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
-```
-
-For the shapes each check enforces, see `claude/skills/plan-feature/references/plan.md`, `claude/skills/plan-groundwork/references/groundwork.md`, and `claude/skills/plan-intake/references/intake.md`.

package/docs/agents/restated.md

@@ -1,83 +0,0 @@
----
-title: Restated instructions
-description: Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
----
-
-# Restated instructions
-
-`canon gov restated` reports every instruction the always-loaded file or a path-scoped rule states that a further surface states too. It answers a question nothing else here could: one rule was found written in three places, and it was found by accident when a shipped skill deleted a file the rule said to keep.
-
-```bash
-canon gov restated
-canon gov restated --json
-canon gov restated --root ../my-app
-```
-
-| Option          | Behavior                                                   |
-| --------------- | ---------------------------------------------------------- |
-| `--root <path>` | Tree to read, defaulting to the current directory          |
-| `--json`        | Add a machine-readable record on stdout, keeping the frame |
-
-Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
-
-## The corpus it reads
-
-Four surfaces, and they are not read symmetrically. Every top-level bullet in `CLAUDE.md` and in every path-scoped rule is a subject, and every surface below is searched, rules included a second time:
-
-- `tooling/claude/seeds/CLAUDE.md`, read as bullets, since the seed carries the same shape as the file it is authored from
-- `claude/skills/*/SKILL.md` and `.claude/skills/*/SKILL.md`, read as every prose line and bullet, since the motivating case was stated in a body as a paragraph rather than a list item. The second root holds the project's own skills, which are equally a place a rule gets restated
-- `governance/rules/**/*.md` and `internal/rules/**/*.md`, the authoring roots rather than the consumed copy under `.claude/rules/`, read as bullets the same way the seed is. Each record's `file` carries the root it was read from
-
-A rule reads as both a subject and a candidate, unlike the seed and the skill bodies. A stack ships a whole rule folder, so a bullet duplicated between two rules reaches a target exactly as a bullet duplicated between the always-loaded file and a rule does, and neither shape is visible from one side alone. A candidate sharing its subject's file is skipped, since two bullets inside one rule sharing anchors are adjacent instructions on one topic rather than the same rule shipped twice, and a pair found from one direction is not reported again from the other.
-
-Frontmatter, headings, tables, and fenced blocks are read past. A heading names a section instead of stating a rule, a fenced block is an example whose words belong to the prose around it, and a body's `description` restates that skill's own purpose, so sweeping it would match every subject naming its domain.
-
-A rule stated in two skill bodies and never in `CLAUDE.md` or another rule is outside this reading. A body is searched but never read as a subject, and a subject is what the search runs from.
-
-## How a match is decided
-
-Matching is recall-first and keyed on shared distinctive tokens rather than on a phrase two surfaces spell the same way. The case this exists for was one rule written three different ways, so a near-exact matcher would ship a cheap report blind to the defect it was built for.
-
-A token is distinctive when it appears in at most 20 of the corpus's statements, which is under one percent of them. `.canon/plans/` sits at 14 and is the anchor the motivating case turns on, while `file` sits at 371 and would match most of the tree.
-
-A backticked token counts double. An author marking a span as code named an identifier rather than describing one, so `.canon/plans/archive/` says more about what a statement governs than any two prose words do. Two statements are one rule when their shared anchors reach a weight of 3.
-
-Every record names the anchors its match rested on, so a reader can weigh a finding instead of taking it.
-
-## The three classes
-
-- **Mirror.** Both files sit on a declared path pair whose duplication is deliberate. `CLAUDE.md` and the seed are the one pair, since the seed is authored from it and a hand merge reconciles the two. Excluding by pair rather than by content is the point: the duplication is a location fact this repository already records, and a content test would rediscover it on every run.
-- **Repetition.** Two surfaces state one rule and neither is declared a copy of the other.
-- **Contradiction.** The prohibition falls on one surface alone, on a match strong enough to read that as a disagreement. This is a polarity reading rather than a judgment about meaning, so weigh each against the surfaces it names.
-
-The contradiction floor sits above the match floor deliberately. A thin match says two statements touch the same subject, which is not enough to claim one forbids what the other prescribes, so a weak pair reports as a repetition and the loudest class is reserved for a pair sharing real identity.
-
-Two further rules decide where a prohibition counts, and both came out of false positives rather than from reasoning ahead of the corpus.
-
-Polarity is read off the clause the anchors landed in, and off the densest such clause rather than every one carrying an anchor. A statement states one rule across several clauses, so a union answers true whenever any clause anywhere carries a marker, which is the whole statement again under another name.
-
-The marker also has to open its clause, because an instruction leads with its verb. `Never delete a task file` prohibits where `a fallback never fires` reports, and no test reading the marker anywhere in the clause tells those apart. What that costs is a prohibition written mid-clause, which now reads as description and lands the pair in the repetition class, so both surfaces still reach the report and only the label is weaker.
-
-One mid-clause shape still counts. A `no` opening a clause or a comma-set phrase directly on a code span prohibits, as in `pinned to major tags, no` followed by the pinned tag, since sitting on an identifier it names what is ruled out. The phrase boundary keeps description out: `returns no` then a code span puts the marker after a verb and reports what happens. `not` and `never` in the same position are left out, because admitting them turned agreeing pairs into false contradictions.
-
-A mirror that disagrees stays a finding. The exclusion reaches a repetition alone, because the two files on a declared pair are meant to agree.
-
-## Which surface is authoritative
-
-Each restatement names where a later edit starts.
-
-- `claude-md` for a seed match, since the always-loaded file is authored first and the seed carries it to a target
-- `skill-body` where the subject names that skill, which is the content-ownership rule that behavior triggered only when editing one domain belongs to that domain's skill
-- `unknown` everywhere else, a rule match included, which is a first-class answer rather than a gap
-
-The ownership table assigns a cross-domain rule and a domain-triggered one, and reaches nothing stated in a skill body the always-loaded file never names. Guessing there would put a reader on a surface nobody decided.
-
-## Exit codes
-
-Exit codes are `0` when no instruction is restated outside a declared mirror, `1` for a refusal, and `2` for at least one restatement outside one. Mirrors move no exit code.
-
-Nothing wires this into `bun run check` or into a hook. A restatement is legitimate more often than not, and gating a measure whose ordinary result is a finding is what teaches contributors to route around the stage. `canon gov test-order` and `canon labels audit` are the siblings.
-
-Both refusals are absences rather than breaks. A target may hold none of the seed, a skills tree, or a rules tree, so `canon audits run` reads `no-instructions` and `no-surfaces` as a corpus that is not there rather than a verb that failed.
-
-An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `counts` rather than the exit when a skill consumes this.