@erclx/canon 5.39.0 → 5.41.0

package/docs/agents/teach-authoring.md

@@ -1,118 +0,0 @@
----
-title: Teach authoring
-description: Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
----
-
-# Teach authoring
-
-The verbs a session runs while writing a lesson. Workspace resolution, the verbs that open and record into a workspace, and the refusal reasons they share are in `teach.md`.
-
-## Lesson
-
-`canon teach lesson` resolves what the next lesson needs before it is written. It reads and never writes.
-
-```bash
-canon teach lesson regular-expressions \
-  --slug capture-groups \
-  --questions 3 \
-  --options 4
-```
-
-| Option            | Behavior                                                  |
-| ----------------- | --------------------------------------------------------- |
-| `--slug <kebab>`  | The lesson's own topic, required                          |
-| `--questions <n>` | How many questions the quiz carries, required             |
-| `--options <n>`   | How many options each question carries, defaulting to `4` |
-| `--json`          | Emit a machine-readable record on stdout                  |
-| `--root <path>`   | Teach root, defaulting to the main worktree               |
-
-It reports three things. `lesson` is the numbered path the lesson takes, derived from the highest ordinal already in `lessons/` the way an open derives a workspace ordinal. `success` carries the mission's success lines, so a session reports progress against the exit criteria without a second read of `MISSION.md`. `quiz` carries one entry per question.
-
-A lesson written against this record carries its chrome as four empty marker pairs rather than hand-composed markup: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. `canon teach nav`, below, fills them from what the workspace holds on disk.
-
-`canon teach stylesheet <topic>` writes the pair every lesson in the workspace renders through, seeded from the design source so a workspace renders in the system every other surface does. The two halves are written on different terms. `assets/base.css` holds the generated design layer and is rewritten on every run, so a change to the shared chrome reaches a workspace that already exists. `canon teach nav` and `canon teach up` rewrite it too. `assets/course.css` is the half a workspace owns, so it refuses to overwrite, reporting `written` as false where the workspace already carries one, and `--force` takes the seed back over it. Each workspace used to carry a hand-authored palette, which is how the course styling forked once per workspace, so a lesson adds its own rules under the seed and reaches a value through its custom property rather than restating the hex.
-
-Each `quiz` entry carries `order`, the authored option indices in presentation order where index `0` is the correct answer, and `answer`, the one-based position that answer lands in. Both travel together because a caller deriving the position itself is a caller that can derive it wrongly.
-
-The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.
-
-## Render
-
-`canon teach render` renders a lesson body's structural blocks to HTML, through the five lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
-
-```bash
-echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json
-```
-
-| Option   | Behavior                                 |
-| -------- | ---------------------------------------- |
-| `--json` | Emit a machine-readable record on stdout |
-
-It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, `code`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the components can express takes a `raw` block, carrying its own HTML verbatim and unescaped, which is the shape the quiz and the teach-back block travel in.
-
-A `code` block carries `text` and an optional `lang`, a highlight.js name or alias. The source is highlighted at render time into `hljs-*` class spans the workspace stylesheet colors in both themes, so the page carries no script. A `lang` the renderer does not register renders as plain escaped code, and one that does not match `^[a-z0-9+#-]+$` is refused. A workspace seeded before the syntax colors existed shows the spans uncolored until `canon teach nav`, `canon teach up`, or `canon teach stylesheet <topic>` rewrites its base stylesheet.
-
-```json
-[{ "type": "code", "lang": "ts", "text": "const a: number = 1" }]
-```
-
-A citation takes two shapes. A `paragraph` carries an optional `cites` array of reference numbers, rendered as `sup.cite` markers after its text. The one `refs` block carries `items` of `{ title, url?, note? }`, rendered as `ol.refs` and numbered from 1, so cite `1` links to the first item.
-
-```json
-[
-  { "type": "paragraph", "text": "North is fixed.", "cites": [1] },
-  {
-    "type": "refs",
-    "items": [{ "title": "Compass manual", "url": "https://example.com" }]
-  }
-]
-```
-
-It refuses `bad-input` on empty stdin, on malformed JSON, on stdin that does not parse to an array, and on a block carrying an unrecognized `type` or a field of the wrong shape for its type, naming the block's index in the message. Citations add four refusals, each naming the offending block: a cite that resolves to no reference, `cites` on a lede paragraph, a second `refs` block, and a reference `url` that is not `http` or `https`.
-
-## Nav
-
-`canon teach nav` rewrites the teach-root listing, a workspace's contents page, and each of its lessons' chrome, from what the workspace holds on disk.
-
-```bash
-canon teach nav
-canon teach nav regular-expressions --json
-```
-
-| Option          | Behavior                                          |
-| --------------- | ------------------------------------------------- |
-| `[topic]`       | Workspace folder or topic, scoping the run to one |
-| `--json`        | Emit a machine-readable record on stdout          |
-| `--root <path>` | Teach root, defaulting to the main worktree       |
-
-With no topic it rewrites every workspace. The teach-root listing is always rewritten regardless, since it reports on every workspace and a scoped run leaving it stale would be a second kind of drift this verb exists to end.
-
-A lesson carries its chrome as four marker pairs the authoring skill writes empty: `canon:teach:style`, `canon:teach:header`, `canon:teach:footnav`, and `canon:teach:scripts`. This verb splices each one from the current workspace state, embedding the toolkit's favicon, the shared stylesheet, and the script that settles the course panel before the page paints, rebuilding the course sidebar, the breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts. It leaves the authored `<h1>`, lede, body, and quiz between the header and the footnav as written, with two exceptions. It wraps them in `<main>` when the lesson holds none, since the column width hangs off that element, and a lesson that already carries a `<main>` keeps its own.
-
-It also links each "lesson NNNN" mention in that region to the lesson file in the same workspace carrying that number, skipping text inside `a`, `code`, `pre`, `script`, `style`, `label`, `summary`, and comments. A link the verb writes carries `data-lesson-ref`, and it is the only kind the verb rewrites: every run points one at the current filename for its number, or unwraps it to plain text once that number names no lesson. A link an author wrote is never touched.
-
-Every workspace label in that chrome, being the breadcrumb, the sidebar heading, the workspace switcher, and the root listing's row, reads the mission's `title` and falls back to the folder topic in sentence case where the mission names none.
-
-It also deletes two links a session used to write by hand into a lesson's `<head>`, each matched as its exact string: the old icon link and `<link rel="stylesheet" href="../assets/course.css" />`. The page keeps only the icon and the stylesheets the `style` region carries. Any other link an author wrote stays.
-
-A workspace carrying no `course.css` gets its stylesheet pair seeded first, so the contents page it links is never unstyled, and an existing `course.css` is never overwritten. The `style` region links `assets/base.css` ahead of an embedded copy of `course.css`, so the workspace's own rules still win the cascade. The embedded copy drops the seed's `@import` line, which resolved against the lesson's own folder and never loaded anything, and the link is what reaches the base sheet in its place. A workspace with no `assets/base.css`, one holding a hand-authored `course.css` from before the seed, gets no link rather than one pointing at a missing file.
-
-Every run also rewrites `assets/base.css` wherever the workspace already holds one, so a change to the shared chrome reaches an existing workspace through this verb as well as through `canon teach stylesheet <topic>`. `course.css` is still never rewritten. A legacy workspace holding only a `course.css` is not handed a `base.css`, since its lessons were written without the link. `canon teach up` runs this pass before serving, which is the route that keeps a viewed workspace current.
-
-A lesson missing one of the four marker pairs is refused by name rather than rewritten, and every other lesson in the run still rewrites. The record's `skipped` list carries the refused files and which marker each is missing.
-
-A mention whose number names no lesson in its workspace stays plain text and lands in the record's `unresolved` list, one `{ file, lesson }` entry per distinct number per lesson, with `file` relative to the root the way a `skipped` entry is. The lesson still rewrites and counts toward `lessons`, and the exit stays 0. A mention of the lesson's own number stays plain and is not reported, and a refused lesson reports nothing.
-
-The `style` region carries the quiz stepper after the workspace stylesheet, for every lesson but the one shape named three paragraphs down, so it wins the cascade at equal specificity and reaches a workspace seeded before it existed. The stepper is CSS over the radio inputs a quiz is written from: it hides every question that follows one holding no checked input, and hides a question's feedback until that question does. The general sibling combinator is what keeps that from depending on the markup contract holding, since it selects the same questions as the adjacent one for a quiz written correctly and goes on gating when anything sits between two of them, where the adjacent one matches nothing and shows them all at once. Gating there rather than in a script is what keeps a later stem from answering an earlier question with nothing to bind, and the whole block sits inside `@supports selector(:has(*))`, so an engine without `:has()` renders every question rather than a stepper showing nothing. Feedback there follows the workspace stylesheet, shown by one that says nothing about `.fb` and hidden by one grown under the retired script.
-
-The block hides and shows and sets nothing else, which leaves a workspace's own layout for a question and its own appearance for an option and a feedback panel. The one value it names is `display: block` on revealed feedback, since every stylesheet grown under the retired script carries `.fb { display: none }` and nothing adds the class that used to reveal it.
-
-One detector decides both regions. A lesson carrying `<button class="opt"`, the shape written before the stepper, takes the feedback script and no stepper, and every other lesson takes the stepper and no script. That is a detector rather than a mode, since a lesson has one shape or the other, and removing the script outright would leave the lessons already written showing no feedback at all.
-
-Splicing the stepper into a lesson of either shape was measured against a browser and reverted. Its rules match a button question, which can never hold a checked radio, so a lesson given both hides every question past the first for good and outranks the class the script reveals feedback with. Nothing else caught that: the markup is valid, the splice succeeds, and the page renders.
-
-### Reference pages
-
-Each reference page is rendered to a `reference/<slug>.html` sibling carrying the same chrome, and the contents page links that sibling rather than the markdown, which `canon serve` hands over as plain text. The render drops the frontmatter, turns tables into `<table>` markup, and escapes raw HTML written in the markdown rather than passing it through. A fenced code block in a language the highlighter registers is highlighted the same way a `code` block is, and one in any other language stays plain. A hand-written code block in a lesson body is never highlighted. A body with no H1 gets one from the frontmatter `title`. A relative link to another reference page's markdown points at that page's `.html` sibling, and one to the workspace `GLOSSARY.md` points at the glossary on the contents page, `../index.html#gloss`. Every other link, such as `../RESOURCES.md`, stays as written. The markdown file is never touched.
-
-Every rendered page carries a `<meta name="generator" content="canon teach nav">` tag. A `.html` file under `reference/` whose markdown is gone is deleted when it carries that tag, and a hand-written HTML file there, carrying none, is left alone. The record's `reference` field counts the pages rendered. On a Bun with no `Bun.markdown`, each reference page lands in `skipped` with `Bun.markdown` as what is missing, and the rest of the run goes on.

package/docs/agents/teach.md

@@ -1,157 +0,0 @@
----
-title: Teach
-description: Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, viewing one with its chrome refreshed, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb
----
-
-# Teach
-
-Learning workspaces sit under `.canon/teach/<nn>-<topic>/`, and `claude/skills/teach-workspace/references/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `claude/skills/teach-workspace/references/glossary.md` fixes, cited from the `teach-workspace` skill, so it travels with the file wherever a promotion lands it. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
-
-Passing `--root` a path already named `teach` reaches that folder directly rather than wrapping it in the `.canon/`-or-`.claude/` record-root lookup, which is what lets a workspace committed outside the record root, such as a worked example kept in version control on purpose, take every verb below the same as one under `.canon/teach/`.
-
-That root resolution is also why the writing verbs exist at all. The file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead, and a caller naming only the destination reports a success that did not happen. A whole-file create still goes out as a shell heredoc. Changing a line inside a file that already exists has no shell route, because the stream editors are banned, so `resource` and `glossary` are the route for the two files a running workspace edits.
-
-## List
-
-`canon teach list` reports the workspaces under `.canon/teach/`, or what one workspace holds. It reads and never writes.
-
-```bash
-canon teach list
-canon teach list regular-expressions --json
-```
-
-| Option          | Behavior                                    |
-| --------------- | ------------------------------------------- |
-| `--json`        | Emit a machine-readable record on stdout    |
-| `--root <path>` | Teach root, defaulting to the main worktree |
-
-With no topic it reports one line per workspace, carrying the lesson, learning-record, reference-page, and glossary-term counts, plus `next`, the ordinal an open would take. With one it reports the filenames behind each count and the glossary entries themselves.
-
-A folder not named `NN-<topic>` is not a workspace, so the listing, `nav`, and every selector skip it and it moves no ordinal. That is what lets a teach root carry a sibling folder such as `evidence/` without it drawing as a stub row and receiving a contents page.
-
-The listing also names the required files a workspace does not carry, which is `MISSION.md`, `RESOURCES.md`, and `GLOSSARY.md`. That is a report rather than a refusal, because a workspace missing one is still a workspace a session can resume.
-
-Every record carries `due`, read from the `## Revisit` sections of the workspace's learning records and sorted soonest first. Each entry names the `item`, its `date`, the `rung` it has reached on the spacing ladder, `overdue` once that date has arrived or passed, and the `record` the surviving entry was written in. A later record supersedes an earlier entry for the same item, matched without regard to case, since the schedule is the state of one topic rather than a log of every time it was set.
-
-Each entry also carries `hit` and `miss`, the two dates the next record could write. The ladder is 1, 3, 7, 16, and 35 days, a retrieval the learner passed unaided moving up a rung and a miss dropping back one, both held inside the ladder at either end. Reporting both dates is what lets a session copy one rather than compute it, on the same reasoning that put quiz option order in `canon teach lesson`.
-
-The field rides on the listing rather than on `canon teach lesson`, because a session needs the schedule before it has chosen what to teach and that verb takes a `--slug` naming a choice already made. An entry not written in the shape the standard fixes is skipped rather than reported, since a note carrying no date has no date to schedule.
-
-## Open
-
-`canon teach open` creates a workspace at the next ordinal and writes all three required files.
-
-```bash
-canon teach open regular-expressions \
-  --subject "Reading and writing regular expressions" \
-  --starting-point "Comfortable with the shell, has never written a group" \
-  --success "Write a pattern matching a date" \
-  --success "Explain what a backreference does"
-```
-
-| Option                    | Behavior                                                    |
-| ------------------------- | ----------------------------------------------------------- |
-| `--subject <line>`        | One line stating what the workspace covers, required        |
-| `--starting-point <text>` | What the learner already knows, required                    |
-| `--success <line>`        | Observable thing the learner will be able to do, repeatable |
-| `--out-of-scope <line>`   | What the workspace does not cover, repeatable               |
-| `--title <text>`          | Title, defaulting to the topic in sentence case             |
-| `--date <YYYY-MM-DD>`     | Opening date, defaulting to today                           |
-| `--json`                  | Emit a machine-readable record on stdout                    |
-| `--root <path>`           | Teach root, defaulting to the main worktree                 |
-
-The ordinal comes from the highest already present, incremented, so the caller derives no name and composes no path. A topic another workspace already covers is refused rather than opened beside it, since two workspaces on one subject fork the learning records the folder exists to keep whole.
-
-`--starting-point` is required rather than defaulted because difficulty with no floor under it teaches nobody, and a mission written without one cannot say what the lessons sit above. At least one `--success` line is required for the same reason in the other direction: a mission nothing can test is a mission nothing can call finished.
-
-## Resource
-
-`canon teach resource` records sources in a workspace `RESOURCES.md`, keeping what was read apart from what was only found.
-
-```bash
-canon teach resource regular-expressions \
-  --read "MDN regular expressions=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions" \
-  --lead "RE2 syntax=https://github.com/google/re2/wiki/Syntax"
-```
-
-| Option               | Behavior                                           |
-| -------------------- | -------------------------------------------------- |
-| `--read <title=url>` | Source that stands behind the material, repeatable |
-| `--lead <title=url>` | Source found and not opened, repeatable            |
-| `--json`             | Emit a machine-readable record on stdout           |
-| `--root <path>`      | Teach root, defaulting to the main worktree        |
-
-The pair splits on the first `=`, so a URL carrying its own separator survives intact. Say in the title which claims rest on the source, since the entry is the only place a later session reads that from. Which sources qualify is the source ladder in `claude/skills/teach-workspace/references/teach.md`, and a source below its first two rungs also names why no higher one covers the claim.
-
-A URL either heading already lists is refused rather than written twice. Two entries for one source split what rests on it across two lines, and a reader checking a claim then finds half of the answer. The exception is a `--read` URL already under `## Leads`, which moves to `## Read` under the title the call carries, since opening a lead is how it becomes read. A `--read` URL already under `## Read`, and any `--lead` URL already listed, stays refused, and a refusal leaves the whole batch unwritten.
-
-A URL a file displays inside a fence does not count as listed, which is how a workspace quoting the entry format in its own prose is read as the sample it is.
-
-## Glossary
-
-`canon teach glossary` adds terms to a workspace `GLOSSARY.md`, alphabetically.
-
-```bash
-canon teach glossary regular-expressions \
-  --term "capture group=A parenthesised part of a pattern whose match is kept" \
-  --first-seen 0002-groups.html
-```
-
-| Option                     | Behavior                                                  |
-| -------------------------- | --------------------------------------------------------- |
-| `--term <term=definition>` | Term the subject defines, repeatable                      |
-| `--first-seen <file>`      | Lesson or reference page the batch first defines these in |
-| `--json`                   | Emit a machine-readable record on stdout                  |
-| `--root <path>`            | Teach root, defaulting to the main worktree               |
-
-One call writes one file, which keeps a batch of terms from racing on the glossary every one of them shares. `--first-seen` names one page for the whole batch rather than one per term, because a batch comes from one lesson.
-
-A term already defined is refused rather than replaced. A definition the subject has moved under is a revision of the entry that exists, and nothing on the command line tells that apart from a second definition arriving by mistake.
-
-The entry lands as the standard's shape, leading with the term as a bolded span. A definition not ending in sentence punctuation is terminated before the citation is appended, so a bare phrase does not run into the sentence naming where the term first appears.
-
-## Lesson, render, and nav
-
-`canon teach lesson`, `canon teach render`, and `canon teach nav` build and splice a lesson rather than editing a workspace's records. They are in `teach-authoring.md`.
-
-## Opening a workspace
-
-`canon teach up` runs the `nav` pass and then serves the teach root, so the page a reader opens carries the chrome the installed CLI generates:
-
-```bash
-canon teach up 03-fde-system-design --json
-```
-
-The link opens the named workspace's contents page, or the root listing when no topic is named. The verb serves the teach folder at its absolute path, so a run from a linked worktree still reaches the main worktree root. `--port` sets the first port tried and `--root` the teach root, as on every other verb. It runs until interrupted, so a session starts it in the background and reads the record off stdout.
-
-The JSON record is one line carrying the `nav` fields, then `served`, the absolute folder, and the server's `host`, `port`, `entry`, `url`, and `entryExists`. A lesson `nav` skips lands in `skipped` and the server still starts, since a partial refresh is still worth viewing. A `nav` refusal starts no server.
-
-While it runs, `up` watches the teach root. A change there, such as a lesson, a workspace, a glossary term, or a reference page added by hand or by another `teach` verb, runs the `nav` pass again, and every open page reloads once that pass changes what is served. Passes run one at a time, so a burst of saves costs one more pass rather than several at once. A pass `nav` refuses, such as one over a workspace deleted while it was served, is reported on stderr, the server keeps running, and no page reloads.
-
-Each refresh is logged to stderr, so stdout stays the one record line. Dotfiles and editor backups ending in `~` start no pass.
-
-The reload script is added to each page as the server sends it and never written to disk, so a page saved from the browser, a promoted lesson, and a committed fixture carry no trace of it. The script listens on `/__live`, which answers only a request naming the server by its loopback address or `localhost`.
-
-Viewing writes. Every page and generated stylesheet `nav` owns is rewritten first, which on a committed fixture shows as a diff. To serve without rewriting anything, `canon teach list <topic>` ends its human output with a `canon serve` line for that workspace, with the teach folder written relative to the cwd, or absolute when it sits outside it. The JSON record of `list` carries no such field.
-
-`canon serve` itself stays general, since nothing about serving a directory is specific to a learning workspace and the same verb carries a slide render and a design preview. What `up` adds in front of it is the refresh and the watch that repeats it, both teach-specific, and it serves through the same server rather than a second one.
-
-Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.
-
-## Refusal reasons
-
-| Reason         | Raised when                                                     |
-| -------------- | --------------------------------------------------------------- |
-| `no-teach`     | The root carries no `.canon/teach/` folder                      |
-| `no-workspace` | No workspace matches the topic, with the folder names as detail |
-| `ambiguous`    | Two workspaces claim one topic, with both names as detail       |
-| `exists`       | A workspace already covers the topic an open names              |
-| `no-file`      | The workspace carries no file the verb writes into              |
-| `no-section`   | `RESOURCES.md` carries no heading the entries belong under      |
-| `listed`       | A URL is already read, or a lead is offered as listed           |
-| `defined`      | A term already carries a glossary entry                         |
-| `bad-input`    | The command line is malformed, before any folder is read        |
-
-`up` also passes through the refusals `canon serve` raises once `nav` has run, `no-port` when every port in reach is taken and `bind-failed` for any other bind error, such as a privileged port, in the same record shape with the server's detail as `message`.
-
-A `bad-input` refusal reports the working directory as its root rather than the resolved one, since the command line is rejected before the root is worth resolving. `lesson` raises it for a slug that is not kebab-case, for a quiz carrying no question, and for a question carrying fewer than two options, since a question with one option has nothing to confuse the right answer with.

package/docs/agents/test-order.md

@@ -1,58 +0,0 @@
----
-title: Test order
-description: Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
----
-
-# Test order
-
-`canon gov test-order` reports where an implementation reached a commit ahead of the test covering the same behavior. It measures the test-first order that the `test-first` skill and `auto-ship` hold, which until this verb existed was prose with nothing measuring it.
-
-```bash
-canon gov test-order
-canon gov test-order --base origin/main --json
-canon gov test-order --root ../my-app
-```
-
-| Option          | Behavior                                                   |
-| --------------- | ---------------------------------------------------------- |
-| `--base <ref>`  | Ref the range runs back to, defaulting to the trunk        |
-| `--root <path>` | Repository 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. A consumer reading stdout sees pure data, and an operator reading the terminal sees why a run refused rather than a command that appeared to do nothing.
-
-## The range it reads
-
-The default range is the branch against the trunk, resolved as the merge base against `origin/main` and then local `main`. A repository carrying neither falls back to the root commit, so a fresh checkout still answers rather than refusing.
-
-Reading all history on every run measures work nobody is reviewing and buries the finding that matters under the ones already merged. `--base` widens or narrows it when a reader wants a different window.
-
-A ref passed there is resolved the same way, through its merge base with `HEAD`, so it names the far side of the range and not the commit the range starts from. `--base origin/main` therefore reports the same window whether the trunk has moved since the branch left or not. Naming a commit the branch already carries still measures from that commit, since the merge base of `HEAD` and an ancestor is the ancestor, and a ref sharing no history with `HEAD` refuses as `bad-base`.
-
-Only history is read. A file sitting in the working tree and in no commit is invisible here, which is the point: the verification run sees a tree at one moment, and the ordering exists nowhere but history.
-
-## How a pair is decided
-
-A test is paired to an implementation by the module path with the test suffix removed, so `src/parser.test.ts` covers `src/parser.ts`. Every record is keyed on the implementation path, which is what a reader goes looking for.
-
-Pairing is the whole difficulty. A test and its implementation are related by behavior rather than by filename, so a behavior split across two modules pairs wrongly or not at all. That is what the unclassified verdict exists to catch rather than hide.
-
-## The three verdicts
-
-- **Satisfied.** The implementation was added in the range and its test reached history no later. A test that predates the range counts, and so does one commit carrying both sides, since the rule asks that the test not come after and a single commit is the shape a small change takes.
-- **Implementation-first.** The implementation was added in the range and its test was added in a later commit of the same range. This is the only verdict that moves the exit code.
-- **Unclassified.** Everything the pairing cannot read, each carrying its own reason. A module the range modified rather than added lands here, because a refactor and a new behavior cannot be told apart from history. So does an implementation no test names, and a test whose implementation the range never introduced.
-
-## What it reads past
-
-Only `.ts` and `.tsx` are paired, since a test sits beside its subject under one name across that corpus and a bash script has no such partner. Declaration files carry no behavior to test. Every other changed path is counted under `Read past` rather than dropped silently.
-
-Coverage is narrower than the rule the check answers to. The rule speaks to every behavior, and the verb speaks to the behaviors it can identify, so the report states its own scope on every run rather than implying it looked at everything.
-
-## Exit codes
-
-Exit codes are `0` when nothing reached history ahead of its test, `1` for a refusal, and `2` for at least one implementation-first finding. Unclassified rows move no exit code.
-
-Nothing wires this into `bun run check` or into a hook. The unclassified class is large and known, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `canon tasks validate` is the precedent: it exits `2` on findings and is called where the claim is made rather than on every push.
-
-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 JSON record's `findings` array rather than the exit when a skill consumes this.

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.