@erclx/canon 5.39.0 → 5.40.0

package/docs/agents/upstream.md

@@ -1,94 +0,0 @@
----
-title: Upstream
-description: The fetch, catalog, due, and advance verbs that read Claude Code releases against the toolkit, the cursor record, and each refusal reason
----
-
-# Upstream
-
-`canon upstream` reads the Claude Code release feed from a stored cursor and lists canon's own mechanisms beside it, so a triage can match a release line to something canon does. The verbs ship in the published CLI as `canon gate` and `canon sandbox` do, and only this repository has the skill that drives them. A target has no use for them.
-
-Run them as `bun src/cli.ts upstream ...` from this repository's root. The global `canon` resolves to the installed package, which lacks the verbs until a release ships them.
-
-## Verbs
-
-| Verb                                | Behavior                                                                     |
-| ----------------------------------- | ---------------------------------------------------------------------------- |
-| `fetch [--since <version>]`         | List the release lines since the cursor, with the mechanical noise dropped   |
-| `catalog`                           | List the skills, verbs, hooks, and gate stages the tree holds, one line each |
-| `due`                               | Say whether a digest is due, from the cursor and the installed version       |
-| `advance <version> --intake <slug>` | Move the cursor to a version, and store the current `llms.txt` beside it     |
-
-Every verb takes `--root <path>` for the repository to read and `--json` for a record on stdout. `fetch` and `catalog` write nothing, and `due` writes only its day cache. `advance` is the only writer of the cursor, and the digest skill runs it after the findings are filed, so a run that dies midway reads the same range next time.
-
-## fetch
-
-```bash
-bun src/cli.ts upstream fetch --json
-bun src/cli.ts upstream fetch --since 2.1.256 --json
-```
-
-The range runs from the cursor, or from `--since` when given, to the newest release. The walk stops at the first release whose version is not newer than the cursor, so a cursor naming a version the feed never carried still bounds the range, and a range crossing a page boundary is read whole.
-
-A line survives when it opens with `Added`, `Changed`, `Removed`, `Improved`, or `Deprecated` and carries none of the dropped surfaces: `[VSCode]`, `[Claude Tag]`, `[Code Review]`, `Windows:`, `Self-hosted`, the apps gateway, managed settings, OpenTelemetry, Bedrock, Vertex, and screen reader. A nested bullet and a `*` bullet are read as well as a `-` one.
-
-Without `--json`, stdout carries one `version<TAB>text` row per line. With it, stdout carries one record:
-
-| Field      | Holds                                                                      |
-| ---------- | -------------------------------------------------------------------------- |
-| `from`     | The cursor version the range starts after                                  |
-| `to`       | The newest release version, or `from` when nothing is newer                |
-| `releases` | How many releases the range spans                                          |
-| `lines`    | Each kept line as `version`, `date`, `text`, and `identifiers`             |
-| `llms`     | `added` and `removed` lines of `llms.txt` against the stored copy, or null |
-
-An identifier is a backticked name on a `Changed`, `Removed`, or `Deprecated` line that holds a dash, a slash, a dot, or a capital. It carries up to three tracked files naming it, and one with no hit is left out. `llms` is null when the page could not be fetched, and every line reads as added until `advance` has stored a first copy.
-
-The request sends `GH_TOKEN` or `GITHUB_TOKEN` when either is set. Unauthenticated, GitHub allows 60 requests an hour, and a range takes about three.
-
-## catalog
-
-Prints a heading per section and a line per entry. With `--json` it prints one record whose fields are `skills`, `internalSkills`, `verbs`, `hooks`, `gate`, and `gaps`, each entry as `name` and `text`. A skill folder with no `SKILL.md` or no description appears in `gaps` rather than dropping out. A hook's text is the first comment line after its shebang.
-
-## due
-
-```bash
-bun src/cli.ts upstream due --json
-```
-
-Answers whether a digest is worth running now. It exits 0 whether or not one is due, so branch on the record rather than the exit. The installed version comes from `claude --version`, and the cursor from the main worktree root.
-
-| Reason            | `due`   | Meaning                                                                    |
-| ----------------- | ------- | -------------------------------------------------------------------------- |
-| `no-cursor`       | `true`  | No digest has been run, so a first run is prompted                         |
-| `week`            | `true`  | The cursor is seven or more days old and the install is ahead of it        |
-| `vocabulary`      | `true`  | An `Added` line in the gap names a plugin, skill, hook, worktree, or so on |
-| `current`         | `false` | The install is at or below the cursor, as after a downgrade                |
-| `recent`          | `false` | The cursor is under a week old and no line in the gap matches              |
-| `unknown-version` | `false` | `claude --version` could not be read                                       |
-
-The record is `due`, `reason`, `releases`, `installed`, and `cursor`. `releases` counts the releases in the gap and is `null` when the feed was not read, so a `week` result can arrive without a count.
-
-The gap is read from GitHub only when the install is ahead of the cursor, and the result is cached for a day under the scratch folder at `.canon/tmp/upstream-due/check.json`. A failed read is cached too, so a rate limit hit by one session is not retried by the next. Nothing here moves the cursor.
-
-The `.claude/hooks/upstream-due.sh` hook runs the verb at an attended session start and shows the operator one line when it is due. It stays silent in a background session, on a resume, a clear, or a compaction, and on any failure.
-
-## advance
-
-Writes `cursor.json` and the fetched `llms.txt` under the upstream record folder at the main worktree root, each through a temp file and a rename. `--no-llms` keeps the stored `llms.txt` and fetches nothing. The record is `version`, `intake`, `advanced`, and `llms`, which reads `stored` when a fresh copy was written and `kept` when the stored one stayed, whether by `--no-llms` or because the fetch failed.
-
-The cursor file holds `version`, `date`, and `intake`. The folder is a backed record folder, so `canon records push` carries it.
-
-## Refusals
-
-A refusal exits 1, prints the reason on stderr, and with `--json` adds `reason` and `message` to stdout. Branch on `reason`.
-
-| Reason              | Verb      | Meaning                                                             |
-| ------------------- | --------- | ------------------------------------------------------------------- |
-| `no-cursor`         | `fetch`   | No cursor is stored and no `--since` was given. Pass the flag.      |
-| `bad-since`         | `fetch`   | `--since` is not a dotted version                                   |
-| `cursor-missing`    | `fetch`   | Every release the feed returned is newer than the cursor            |
-| `rate-limited`      | `fetch`   | GitHub refused the request. Set `GH_TOKEN` or `GITHUB_TOKEN`.       |
-| `network`           | `fetch`   | The feed could not be reached                                       |
-| `http`              | `fetch`   | GitHub answered with an error status                                |
-| `invalid-version`   | `advance` | The version is not a dotted number                                  |
-| `older-than-cursor` | `advance` | The version is older than the stored cursor, which never moves back |

package/docs/agents/worktrees.md

@@ -1,118 +0,0 @@
----
-title: Worktrees
-description: Reporting which worktrees are reclaimable, removing the ones that are, the hidden verb that clears a stranded bare flag, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
----
-
-# Worktrees
-
-## List
-
-`canon worktrees list` reports every worktree of the current repository with a reclaim verdict and the reason behind it.
-
-```bash
-canon worktrees list
-canon worktrees list --json
-```
-
-| Option   | Behavior                                |
-| -------- | --------------------------------------- |
-| `--json` | Add a machine-readable record on stdout |
-
-It reads and removes nothing. The question it answers is which worktrees the work has finished with, which nothing in the loop asks: a worktree is created per feature and removed by nobody, so directories left by shipped work accumulate for the life of the checkout.
-
-Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `reason` of `gh-missing`, `gh-failed`, or `sessions-unreadable`.
-
-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 `reason` rather than the exit when a skill consumes this.
-
-## Repair the bare flag
-
-`canon worktrees repair-bare-flag` clears a `core.bare` flag that Claude Code's worktree entry left set in the shared config. It is hidden, so no help listing shows it, because its one caller is a hook rather than a person.
-
-```bash
-canon worktrees repair-bare-flag --root <path> --json
-```
-
-| Option          | Behavior                              |
-| --------------- | ------------------------------------- |
-| `--root <path>` | Repository to repair, default the cwd |
-| `--json`        | Print the record on stdout            |
-
-`--json` writes `{repaired, reason, message}` on stdout, once, whether or not anything was written. `reason` is `flag-unset`, `common-dir-unreadable`, `genuinely-bare`, or `write-failed` when `repaired` is false. `message` carries text when the flag is repaired and when the write failed, and is null on the three quiet skips. A `write-failed` record means the flag is still set, which a lock file or a read-only config causes. A repository whose common dir is not named `.git` keeps its flag. The exit code is always `0`, so a hook never fails a tool call. Without `--json`, a record carrying a message prints it on stderr and any other prints nothing.
-
-## Reclaim
-
-`canon worktrees reclaim` removes every worktree the reading above called reclaimable, and the branch behind each one.
-
-```bash
-canon worktrees reclaim --dry-run
-canon worktrees reclaim
-canon worktrees reclaim --json
-```
-
-| Option      | Behavior                                    |
-| ----------- | ------------------------------------------- |
-| `--dry-run` | Report what would be removed without acting |
-| `--json`    | Add a machine-readable record on stdout     |
-
-Removal sits on the default path rather than behind an apply flag. Report-only is what the `list` verb already did, and what it produced was a hand cleanup: eight directories deleted outside git in one afternoon, each leaving the registration and the branch that `git worktree remove` would have taken with it. A flag a reader has to remember is one nobody passes the first time, and the first time is when the directories are still there.
-
-Each entry unlocks, removes, then deletes its branch, and the sequence is the same whether the directory still stands or is already gone. A run carrying a directory that is gone sweeps stale registrations once between the removals and the branch deletes, since a branch git still reads as held by a worktree cannot be deleted. That sweep is the one step reaching past the reclaimable set, because git takes no path to scope it: it clears the bookkeeping for every directory already gone, refused entries included, and deletes no branch and no directory of its own.
-
-Exit codes: `0` every reclaimable worktree was removed or there were none, `1` refused or a removal failed. A reading that could not reach the merge state refuses every entry rather than falling back to a default, since that state is the one input deciding whether a branch is safe to delete.
-
-### The record
-
-`--json` writes `{reason, detail, dryRun, reclaimable, removed, failed, pruned, outcomes}` on stdout. `reason` is null unless the whole reading refused, `reclaimable` counts what the verdicts named, `removed` and `failed` split the outcomes, and `pruned` says whether the stale-registration sweep ran. A dry run and a reading that found nothing both report `removed` as 0 and differ on `reclaimable`, which separates a quiet repository from a run asked not to act.
-
-Field order is part of the contract. A shell reads this record with a pattern rather than a parser, so `reason` sits ahead of the free-text `detail`, and the scalar counts sit ahead of `outcomes`, whose per-entry `failedAt` and boolean `removed` match neither digit pattern. Read the record's fields rather than the exit when a skill or a hook consumes this, for the reason the `list` section above gives.
-
-## What calls it
-
-`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.
-
-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
-
-All three hold: its branch has a merged pull request, its working tree is clean, and no live session holds the directory. Each alone has a case where removal loses something, so `refusals` names every failing condition rather than the first.
-
-| Refusal                  | What it means                                           |
-| ------------------------ | ------------------------------------------------------- |
-| `main-worktree`          | The main worktree, which is never reclaimable           |
-| `current-worktree`       | The worktree the command is running in                  |
-| `detached-head`          | No branch, so nothing names a pull request              |
-| `no-merged-pull-request` | Its branch has no merged pull request                   |
-| `uncommitted-changes`    | Work no history stands behind, untracked files included |
-| `unreadable-worktree`    | The working tree status could not be read               |
-| `held-by-session`        | A live session still holds the directory                |
-
-Uncommitted work is the condition that gates rather than warns. A worktree is gitignored scratch with no history behind it, so a directory removed with unstaged changes takes them somewhere nothing recovers.
-
-A directory already deleted by hand is clean rather than unreadable, so the merged and session checks decide it like any other worktree. Reading the two together is what reported eight reclaimable worktrees as unreadable, since `git status` exits the same way for a path that is gone and one it could not read.
-
-The worktree the command runs in refuses on position rather than on state. Git removes the directory a caller is standing in without complaint, and every later call scoped to that directory then fails, so a run that took it would leave the branches after it undeleted and report the failures against the worktrees rather than the cause.
-
-## Why the pull request rather than git ancestry
-
-Ancestry is the reading anyone reaches for and it fails in both directions on a repository that squash merges. A merged branch is never an ancestor of the trunk there, so `git merge-base --is-ancestor` calls shipped work unmerged. Measured against nine worktrees, it named five of six lingering branches unmerged, each of which had a merged pull request, reporting them 2 to 6 commits ahead.
-
-The one branch it did call merged was the one that had to stay. That branch had no pull request at all, sat at a release commit, and its worktree held finished work outside any commit. So the cheap test kept every directory safe to remove and offered the only one that was not.
-
-The read is one `gh pr list --state merged` for the whole repository rather than one call per worktree, which would be a network round trip inside a loop. It covers the most recent 200 merges, so a worktree older than that reads as having none and is refused, which fails in the direction that keeps a directory.
-
-## Two removal shapes
-
-`route` names which one applies rather than choosing it, since picking wrong strands state.
-
-- `session`: a live session holds the directory, and the `sessions` field carries `{name, kind, id}` per holder rather than a bare name, since `claude rm <id>` takes the id and never the name. `kind` reads `bg` or `interactive` off this repository's session registry.
-  - A resolved background holder: `id` carries the value `claude agents --json` reports, so `claude rm <id>` is the command to run. Its own report is not reliable: two runs under matched conditions on 2026-09-03 both printed `kept`, and one of them had already removed the worktree, so read `canon worktrees list` again afterward rather than trust what the command printed.
-  - An unresolved background holder: `id` is `null` because the binary is missing, fails, or has not reported that pid yet, so its id has to come from a manual read of `claude agents --json` instead.
-  - An interactive holder: `id` is always `null`, since no id exists for one at all, and nothing removes it until a person closes its terminal.
-- `worktree`: the session has ended, and `canon worktrees reclaim` is what runs the remove and the branch delete.
-- `null`: the main worktree, which no removal shape reaches.
-
-A held worktree is refused rather than reported reclaimable, and its route is reported for whoever decides to act on it. Deleting a directory underneath a live session is the case that has to refuse, and an interactive holder is the one shape inside that refusal with no removal route at all.
-
-## What an unreadable input does
-
-It refuses the whole report rather than producing verdicts around the gap. An absent merge state and a branch with no merged pull request return the same empty answer, and so do an absent session roster and a worktree nobody holds. Reporting the second when it was the first is a false clean, and here that ends in a removal rather than in a warning.

package/docs/target/standards-moved.md

@@ -1,34 +0,0 @@
----
-title: Target standards moved
-description: Which skill owns each standard the retired standards verb used to serve, for a project that still calls it
-category: Agent surface
----
-
-# Target standards moved
-
-`canon standards <name>` is gone, and with it the name map that sent an old call to a new home. A rule, skill, or `CLAUDE.md` of your own that still runs it now gets commander's too-many-arguments error and no content, so search the project for the call and replace it. The surrounding step is in [target migrations](migrations.md). <!-- canon-allow-reference: says the verb is gone -->
-
-Each standard now lives at `references/<name>.md` in the skill that owns it. Load that skill and read the reference it names:
-
-| Skill             | Standards                                                     |
-| ----------------- | ------------------------------------------------------------- |
-| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
-| `context-fold`    | `context`                                                     |
-| `canvas-board`    | `canvas`, `design`                                            |
-| `docs-sync`       | `docs`, `readme`                                              |
-| `draft-figure`    | `figures`, `mermaid`                                          |
-| `create-rule`     | `rule`                                                        |
-| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
-| `git-branch`      | `branch`, `slug`                                              |
-| `git-commit`      | `commit`, `versioning`                                        |
-| `git-pr`          | `pr`, `publish`                                               |
-| `markdown-craft`  | `markdown`                                                    |
-| `teach-workspace` | `glossary`, `teach`                                           |
-| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
-| `plan-intake`     | `intake`                                                      |
-| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
-| `draft-ready`     | `ready`                                                       |
-| `draft-doc`       | `requirements`, `wiki`                                        |
-| `session-map`     | `session`                                                     |
-
-One name moved under a new filename. `standard`, the shape of a standard itself, became `skill-reference.md` in `create-skill`, since the toolkit no longer ships a standards folder to hold one.