@erclx/canon 4.115.0 → 4.117.0

package/docs/agents/markdown-audit.md

@@ -27,9 +27,9 @@ A bare run measures every markdown file git lists, tracked plus untracked-and-no
 
 ## Where the rules come from
 
-The three ban sets and all nine checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
+The three ban sets and all ten checkpoints ship with the `canon` package as data, in `src/markdown/bans.ts` and `src/markdown/structure.ts`. Every project is measured against the same sets whether or not it installed any standards, and no file has to resolve for a run to mean something.
 
-Six of the nine are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
+Seven of the ten are stated in `markdown.md` and the three cadence numbers are stated in the `write-human` skill. That split is the content boundary rather than an accident: `markdown.md` carries the enforced rules a scan can decide, and the skill carries the rhythm rules a ban list cannot express. A cadence number moved in the skill and left in the code drifts the same way, so move both.
 
 Reading them out of the standards per run was the original design. It put a parser contract on a document authored for people, and the standard had to carry a paragraph of its own warning an author that a one-word backticked example in a `- Do not use ` bullet would be lifted into a literal ban set and ban that word everywhere. A rule existing to protect a parser from the prose it parses is the argument for separating them.
 
@@ -128,9 +128,13 @@ Two of the rules `write-human` states are deliberately not implemented. A senten
 
 The condition on that was something identifying a finite verb rather than guessing at one, and two parsers have now been run against it over 11,389 paragraph sentences. They disagree by a factor of four. `compromise` reports 2 percent and reads a fronted past participle as a finite verb, so `Measured at <sha> on <date>.` counts as carrying one. `wink-pos-tagger` reports 9 percent, fixes that class, and is still wrong on roughly three in four, because an imperative's verb tags as a proper noun and a noun-ambiguous predicate tags as a noun, which makes `Each maps to a skill.` read verbless. Separating those needs to know which token is the predicate, and that is syntax rather than a tag. The measure stays unimplemented, now against a mechanism rather than against the idea of one.
 
+### Length
+
+The Length step sums rendered lines over the whole source, frontmatter and fenced blocks included, and lists each document past the 300-line ceiling, longest first. A changelog and a document carrying a whole-line `<!-- canon-length-exempt: <reason> -->` outside a fence are counted in one line rather than listed. Each `--json` entry carries `renderedLines` and `exempt`, the stated reason or `null`, and `checkpoints` carries `ceiling`.
+
 ## Exit codes
 
-Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code.
+Exit codes are `0` for a completed run with no gating finding, `1` for a refusal, `2` for a ban hit or a dead relative link, and `3` for a shipped ban set that arrived empty. A banned character, word, or spelling and a relative link resolving to nothing on disk each fail the run, both facts a scan settles rather than a reader judging. Bullet, paragraph, and depth weight are judgments a reader settles, and cadence is a distribution whose healthy range moves with the surface, so all four report under every code. Length reports the same way, since the audit also runs on a plan kept out of version control, and the Document ceiling stage in `canon gate run` owns that verdict instead.
 
 `3` is separate from `1` because the two want different responses from a caller. A refusal means no corpus was built, and the `Markdown bans` stage in `canon gate run` is right to report it as unmeasured rather than as a pass. An empty set means the corpus was walked and nothing was looked for, so that stage fails the push on `3` rather than skipping.
 

package/docs/agents/sandbox.md

@@ -39,7 +39,7 @@ The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.to
 
 Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
 
-An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/overview.md` names what the watch reaches and what it cannot.
+An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 

package/docs/agents/sessions.md

@@ -1,6 +1,6 @@
 ---
 title: Sessions
-description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, and what each session surface can see
+description: Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and moving a session to another machine with export and import
 ---
 
 # Sessions
@@ -117,6 +117,89 @@ Every row carries `statusUpdatedAt`, the stamp a client writes beside `status` a
 
 The dwell is what separates a status that resolves on its own from one that does not. `busy` and `idle` transition without help, so a long dwell there is ordinary. `waiting` does not: a session in that state is blocked on something outside itself, and a dwell that keeps growing past the ordinary span of a prompt is a session stalled rather than paused. `canon sessions list` renders the dwell beside the status at the coarsest unit that keeps it a whole number, and the JSON record carries both fields on every row.
 
+## Export
+
+`canon sessions export <id>` packs one session into a single gzip tarball so it can resume on another machine. The bundle holds the transcript, its side folder with every path kept, and a manifest.
+
+```bash
+canon sessions export <id>
+canon sessions export <id> --out ~/session.tar.gz --json
+```
+
+| Option         | Behavior                                                   |
+| -------------- | ---------------------------------------------------------- |
+| `--out <path>` | Write the bundle here rather than under the scratch folder |
+| `--json`       | Add a machine-readable record on stdout                    |
+
+Without `--out` the bundle lands at `.canon/tmp/session-export/<id>.tar.gz` under the main worktree root, which is gitignored and reclaimed by `canon records prune-tmp`. It writes locally and never uploads. A transcript holds whatever tool output passed through the session, credentials included where one was printed, so treat the bundle as private.
+
+Exit codes: `0` the bundle was written, `1` refused. The refusal carries a `reason` of `not-found`, where no project folder holds a transcript for the id, or `no-archive`, where the running Bun predates `Bun.Archive`.
+
+The lookup walks every folder under the configuration directory's `projects/`, so a transcript filed under any encoding is found. The transcript is read up to its last newline and never rewritten, so a session exporting itself mid-append drops at most the half line it was writing.
+
+Export runs no skill. Write a handoff with `canon:session-compact` and push it with `canon records push` first where one is wanted. The manifest reports whether a handoff exists and whether it reached the records history, and whatever calls the verb owns that order.
+
+### The manifest
+
+| Field              | Holds                                                                        |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `format`           | The bundle format version, `1`                                               |
+| `sessionId`        | The exported id                                                              |
+| `title`            | The last custom title the transcript recorded, or `null`                     |
+| `cwd`              | The last working directory the transcript recorded, or `null`                |
+| `root`             | The main worktree root of the repository the export read                     |
+| `origin`           | The `origin` remote reduced to `host/path`, or `null`                        |
+| `branch`, `head`   | The branch and commit of the checkout the export ran in                      |
+| `recordsHead`      | The records history `HEAD`, or `null` where no records history exists        |
+| `compacted`        | Whether the transcript carries a compaction boundary                         |
+| `live`             | Whether the id was live in the roster at export                              |
+| `handoff`          | The newest `.canon/compact/` note written since the session began, or `null` |
+| `handoffCommitted` | Whether that note is committed in the records history                        |
+| `recommend`        | `handoff` where a handoff exists, `transcript` otherwise                     |
+
+`recommend` prefers the handoff even though the transcript resumes in full. A resumed transcript carries the source machine's absolute paths into a session working somewhere else, and a handoff states the work without them.
+
+## Import
+
+`canon sessions import <bundle>` places an exported session under this machine's configuration directory so `claude` can resume it.
+
+```bash
+canon sessions import session.tar.gz
+canon sessions import session.tar.gz --root ~/repos/canon --json
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | The repository to resume in. Defaults to the main worktree |
+| `--json`        | Add a machine-readable record on stdout                    |
+
+The transcript and side folder land under `projects/<encoding>/`, where the encoding is the root with every character outside `[A-Za-z0-9]` turned into a dash. Import writes new files only and never overwrites.
+
+Exit codes: `0` the session was placed, `1` refused. The refusal carries one of these reasons:
+
+- `not-a-bundle`: the file is no gzip tarball, carries no manifest at format `1`, or names a path outside its own session, such as one climbing out with `..` or an absolute one
+- `other-repository`: the local `origin` differs from the one the bundle recorded
+- `exists`: the target transcript or side folder is already there, or any other project folder already holds a transcript for the id, which `--resume <id>` could reach first
+- `live-here`: the id is live in the local roster, so a second copy would fork it
+- `write-failed`: a write failed partway for a reason other than a copy appearing, such as a bundle carrying a file where it also needs a folder
+- `no-archive`: the running Bun predates `Bun.Archive`
+
+A write that fails partway removes every file this run placed and every folder it created before refusing, so a retry of the same bundle does not refuse on its own leftovers. Any path it could not remove is named in the message. A copy that appears between the existence check and the write refuses as `exists` on the same terms.
+
+A placed session can still lag the source. The record's `behind` list carries `repository-behind` when this checkout lacks the exported `HEAD`, and `records-behind` when the records history lacks the exported records commit, which `canon records pull` brings. Neither refuses, since each has a remedy the reader runs before resuming.
+
+On success the record carries two `routes`. One runs `claude --resume <id>` from the root, and the other starts `claude` there and runs `/canon:session-resume` bare against the handoff.
+
+### What resume depends on
+
+Measured on `claude` 2.1.281 on 2026-09-24, `--resume <id>` found a copied transcript in any folder under `projects/` and chained the next turn onto its full history, run from a repository path the transcript never recorded. `--continue` found it only under the local encoding, which is why import derives the folder rather than keeping the source machine's.
+
+The encoding is inferred from observed folders rather than read from a published rule, and how a client shortens a path past its length limit was never observed. A client changing the rule leaves `--continue` looking elsewhere while `--resume <id>` still works. The framed report names the derived folder so a reader can compare.
+
+The side folder did not change the conversation sent. What it carries is `tool-results/`, which a `persisted-output` pointer in the transcript names by the source machine's absolute path, and `subagents/`, which holds background agent transcripts. On a machine whose path matches, those pointers resolve. On one whose path differs, they dangle.
+
+Resuming on the target while the source session keeps running forks the conversation, and nothing detects that across machines. The manifest's `live` field and the printed routes are the only warning.
+
 ## What the read depends on
 
 The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.

package/docs/agents/skills-audit.md

@@ -35,18 +35,25 @@ Each check traces to a line in the standard.
 - No `README.md` inside a skill folder
 - Folder name in kebab-case
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
+- No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
+The date check reads prose alone. A date inside a fence or a code span is example data, such as a sample frontmatter block, and a date in the body's own frontmatter is metadata, so neither reports. `REQUIREMENT.md` and `EVAL.md` are not read, since the requirement's `Gap` is where the standard sends the incident and the date that earned a rule.
+
+Each finding names the file and the line, such as `claude/skills/<name>/references/<file>.md  line 12: <date>`. A date after "measured" or "verified" reports like any other, unlike the context audit, because a skill body states the rule a session follows today rather than a reading of the tree.
+
 ## What it leaves alone
 
 The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in that standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 150-line body checkpoint is the one mechanical rule still absent here, and adding it would print a count rather than a defect, since the standard makes it a prompt to look with nothing enforcing it.
 
+The date check reads ISO dates alone. A date written in words, a month with no day, and provenance carrying no date at all pass it.
+
 A check with no rule behind it prints an opinion as a defect, which is where the list stops.
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, and requirement-section findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, and dated-provenance findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
 
 ## The requirement gate
 

package/docs/agents/teach.md

@@ -141,7 +141,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the three lesson components. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the four 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
@@ -151,9 +151,21 @@ echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach re
 | -------- | ---------------------------------------- |
 | `--json` | Emit a machine-readable record on stdout |
 
-It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, or `raw` block, and reports `{ ok: true, html }` on `--json` or the bare rendered HTML on stdout otherwise. Content none of the three 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.
+It reads a JSON array of blocks from stdin, each a `heading`, `paragraph`, `list`, `refs`, 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.
 
-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.
+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
 
@@ -172,7 +184,9 @@ canon teach nav regular-expressions --json
 
 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, and wraps them in `<main>` when the lesson holds none, since the column width hangs off that element. A lesson that already carries a `<main>` keeps its own.
+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.
 
@@ -184,6 +198,8 @@ That seeding fires on the absent file alone, so a workspace already holding a `c
 
 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.

package/docs/workflow/ai-workflow.md

@@ -273,15 +273,15 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Run several tracks at once
 
-| Skill                     | When to use                                                                                          |
-| ------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                       |
-| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass |
-| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                      |
-| `canon:session-relay`     | When this session owes another session a message, with or without a role                             |
-| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                       |
-| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board                       |
-| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                            |
+| Skill                     | When to use                                                                                                 |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:role-orchestrator` | To assert the control session that owns the queue and reviews each worker's PR                              |
+| `canon:role-planner`      | To assert the thinking role for a cold session writing a plan, a groundwork track, or an intake pass        |
+| `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan                             |
+| `canon:session-relay`     | When this session owes another session a message, with or without a role                                    |
+| `canon:session-resume`    | At the start of a session, to pick up what a previous one left                                              |
+| `canon:session-compact`   | Before a compaction or a move to another machine, to write a plain session's handoff note outside the board |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff                                   |
 
 ### Keep the project current with the toolkit
 

package/governance/rules/ui/440-surface-capture.md

@@ -44,5 +44,7 @@ paths:
 - Commit a flagged case's evidence output so the pull request carries the comparison, rather than attaching it by hand.
 - A project whose own established convention already commits that same comparison may route a flagged case's evidence there instead of a separate evidence folder. Only an established convention already committing the same comparison qualifies, not a preference for skipping a second folder.
 - Commit an evidence case for the first time only after running the capture twice with no code change between the runs and confirming the two outputs are byte-identical.
+- Mask the element carrying a value that moves between runs, such as an elapsed-time counter, a clock, or a relative date, in the state's capture case before the double capture, so the check still runs on everything else in the frame. Mask the smallest element holding the value, never the state.
+- Do not commit the state as evidence when the masked outputs still differ, which happens when the value's width reflows its neighbors. Name the variance in the pull request instead, and never re-run toward a match.
 - Recommitting an unbounded sweep on every run reaches a gigabyte of repository history inside a hundred merges. A small, committed evidence set is what a reviewer needs and what lets GitHub draw its own before-and-after comparison on the pull request.
 - `git-pr` and `git-followup` maintain a comparison comment on the pull request automatically once a case is committed, so a reviewer never has to open Files Changed to see it.

package/package.json

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

package/scripts/core/check-capability-seeding.sh

@@ -60,7 +60,8 @@ check_capability "Hooks" "$PROJECT_ROOT/.claude/hooks" \
   "$PROJECT_ROOT"/tooling/claude/seeds/.claude/hooks/*
 
 check_capability "Workflows" "$PROJECT_ROOT/.github/workflows" \
-  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/*
+  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/* \
+  "$PROJECT_ROOT"/tooling/*/seeds/.github/workflows/*
 
 check_capability "Husky" "$PROJECT_ROOT/.husky" \
   "$PROJECT_ROOT"/tooling/base/configs/.husky/*
@@ -90,7 +91,8 @@ check_orphans() {
 check_orphans "Hooks" "$PROJECT_ROOT/.claude/hooks" \
   "$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
 
-for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows; do
+for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows \
+  "$PROJECT_ROOT"/tooling/*/seeds/.github/workflows; do
   check_orphans "Workflows" "$PROJECT_ROOT/.github/workflows" "$dir"
 done
 

package/src/claude/cases/misc.ts

@@ -36,6 +36,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "We're about to hit the context limit, write the handoff before we lose state.",
     expect: 'session-compact',
   },
+  {
+    prompt:
+      "I'm moving this session to another machine, write the handoff before I pack it up.",
+    expect: 'session-compact',
+  },
   {
     prompt:
       'I am the orchestrating session and about to compact, so write the board handoff as a session map on the task board.',

package/src/claude/skills-audit.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import { bodyLines, maskDisplayed } from '@/markdown/scan'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -33,6 +34,14 @@ const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 const HEADING = /^#{1,6}\s+(.+?)\s*$/
 
+/**
+ * An ISO date, read as provenance wherever a reader is told it. The context
+ * audit's detector clears a date after "measured" or "verified", and a skill
+ * body keeps no such carve-out, since the standard sends every incident and its
+ * date to the requirement's Gap or to git.
+ */
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
+
 export interface SkillFinding {
   readonly rel: string
   readonly detail: string
@@ -59,6 +68,7 @@ export interface SkillsAudit {
   readonly nameMismatch: readonly SkillFinding[]
   readonly longDescription: readonly SkillFinding[]
   readonly requirementSections: readonly SkillFinding[]
+  readonly datedProvenance: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -69,6 +79,17 @@ interface SkillSource {
   readonly description: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
+  /**
+   * `SKILL.md` and every reference below the folder, keyed by the path a
+   * finding names. `REQUIREMENT.md` and `EVAL.md` are left out, since the
+   * requirement is where the standard sends a date.
+   */
+  readonly bodies: readonly SkillText[]
+}
+
+interface SkillText {
+  readonly rel: string
+  readonly text: string
 }
 
 /**
@@ -110,6 +131,9 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     nameMismatch: sources.flatMap(nameFindings),
     longDescription: sources.flatMap(lengthFindings),
     requirementSections: sources.flatMap(sectionFindings),
+    datedProvenance: sources.flatMap((source) =>
+      source.bodies.flatMap(dateFindings),
+    ),
   }
 }
 
@@ -138,23 +162,41 @@ async function readSkill(
   const skillDir = join(dir, folder)
   const requirementPath = join(skillDir, 'REQUIREMENT.md')
 
-  const [body, requirement] = await Promise.all([
+  const references = [
+    ...new Bun.Glob('references/**/*.md').scanSync({
+      cwd: skillDir,
+      onlyFiles: true,
+    }),
+  ].sort()
+
+  const [body, requirement, referenceTexts] = await Promise.all([
     Bun.file(join(skillDir, 'SKILL.md')).text(),
     existsSync(requirementPath)
       ? Bun.file(requirementPath).text()
       : Promise.resolve(undefined),
+    Promise.all(
+      references.map((path) => Bun.file(join(skillDir, path)).text()),
+    ),
   ])
 
   const fields = parseFrontmatter(body)
+  const skillRel = join(rel, folder)
 
   return {
-    rel: join(rel, folder),
+    rel: skillRel,
     folder,
     hasReadme: existsSync(join(skillDir, 'README.md')),
     name: declared(readField(fields, 'name')),
     description: declared(readField(fields, 'description')),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
+    bodies: [
+      { rel: join(skillRel, 'SKILL.md'), text: body },
+      ...references.map((path, index) => ({
+        rel: join(skillRel, path),
+        text: referenceTexts[index] ?? '',
+      })),
+    ],
   }
 }
 
@@ -209,3 +251,18 @@ function sectionFindings(source: SkillSource): SkillFinding[] {
     },
   ]
 }
+
+/**
+ * A date inside a fence or a code span is example data a reader is shown, such
+ * as a sample frontmatter block, so only prose outside both is read.
+ */
+function dateFindings(source: SkillText): SkillFinding[] {
+  return bodyLines(source.text)
+    .filter((line) => !line.fenced)
+    .flatMap((line) =>
+      [...maskDisplayed(line.text).matchAll(ISO_DATE)].map((match) => ({
+        rel: source.rel,
+        detail: `line ${line.number}: ${match[0]}`,
+      })),
+    )
+}

package/src/commands/claude.ts

@@ -1397,6 +1397,7 @@ async function runSkillsAudit(
     reportFrontmatter(report)
     reportFolder(report)
     reportRequirementShape(report)
+    reportProvenance(report)
     reportUnmeasured()
     outro()
   }
@@ -1418,6 +1419,7 @@ async function runSkillsAudit(
           readme: report.readme,
           folderName: report.folderName,
           requirementSections: report.requirementSections,
+          datedProvenance: report.datedProvenance,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
@@ -1588,6 +1590,31 @@ function reportRequirementShape(report: SkillsAudit): void {
   reportFindings(report.requirementSections)
 }
 
+/**
+ * Names where the date belongs, since the finding is a date to move rather
+ * than one to delete, and reports without failing the run for the same reason
+ * the frontmatter measures do.
+ */
+function reportProvenance(report: SkillsAudit): void {
+  logStep('Provenance')
+  logInfo(
+    'A SKILL.md and its references state the current rule, with no ISO date outside a fence or code span.',
+  )
+  logInfo(
+    'The incident and date that earned a rule go in REQUIREMENT.md under Gap, or stay in git.',
+  )
+
+  if (report.datedProvenance.length === 0) {
+    logInfo('No body or reference carries a date.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.datedProvenance.length, 'date')} in a body or reference`,
+  )
+  reportFindings(report.datedProvenance)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard
@@ -1604,4 +1631,7 @@ function reportUnmeasured(): void {
   logInfo(
     'The 150-line body checkpoint is mechanical and still absent here, and it would print a count rather than a defect.',
   )
+  logInfo(
+    'Undated provenance, such as "a pull request dropped...", and a date written in words or without its day are not read.',
+  )
 }

package/src/commands/markdown.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises'
 import { dirname, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
+import { lengthExemption } from '@/markdown/ceiling'
 import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
 import { decodePath, findBrokenLinks, type LinkFinding } from '@/markdown/links'
@@ -16,6 +17,7 @@ import {
   BASELINE,
   CHECKPOINTS,
   type Checkpoints,
+  documentHeight,
   measureStructure,
   type StructureReport,
 } from '@/markdown/structure'
@@ -51,6 +53,9 @@ interface FileReport {
   readonly bans: readonly BanFinding[]
   readonly links: readonly LinkFinding[]
   readonly structure: StructureReport
+  readonly renderedLines: number
+  /** The stated reason, or null where the document is not exempt. */
+  readonly exempt: string | null
 }
 
 export function register(program: Command): void {
@@ -62,7 +67,7 @@ export function register(program: Command): void {
   markdown
     .command('audit')
     .description(
-      'Fail on a banned character, word, or spelling, and report bullet, paragraph, cadence, and depth',
+      'Fail on a banned character, word, or spelling, and report bullet, paragraph, cadence, depth, and length',
     )
     .argument(
       '[path...]',
@@ -85,6 +90,11 @@ export function register(program: Command): void {
         'Bullet, paragraph, and depth weight are judgments a reader settles,',
         'so all three report and none of them fails a run.',
         '',
+        'Length reports a whole document past the ceiling and never exits 2.',
+        'The Document ceiling gate stage owns that verdict, since this audit also',
+        'runs on a record kept out of version control, where a long plan is not',
+        'a defect.',
+        '',
         'Cadence reports the same way and carries one more caveat. Its range is',
         'drawn from prose a person reads, so terse reference prose sits below',
         'it correctly and a flat paragraph there is not a defect.',
@@ -148,7 +158,8 @@ async function runAudit(
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
       const abs = resolve(root, rel)
-      const lines = bodyLines(await readFile(abs, 'utf8'))
+      const source = await readFile(abs, 'utf8')
+      const lines = bodyLines(source)
       return {
         rel,
         bans: scanBans(lines, bans),
@@ -156,6 +167,8 @@ async function runAudit(
           existsSync(resolve(dirname(abs), path)),
         ),
         structure: measureStructure(rel, lines, checkpoints),
+        renderedLines: documentHeight(source, checkpoints.renderWidth),
+        exempt: lengthExemption(rel, source),
       }
     }),
   )
@@ -168,6 +181,7 @@ async function runAudit(
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
   reportDepth(reports, checkpoints)
+  reportLength(reports, checkpoints)
   outro()
 
   if (opts.json) {
@@ -192,6 +206,7 @@ async function runAudit(
           cadence: checkpoints.cadence,
           spread: checkpoints.spread,
           opener: checkpoints.opener,
+          ceiling: checkpoints.ceiling,
         },
         entries: reports.map((report) => ({
           path: report.rel,
@@ -202,6 +217,8 @@ async function runAudit(
           heavyBullets: report.structure.heavyBullets,
           heavyParagraphs: report.structure.heavyParagraphs,
           cadence: report.structure.cadence,
+          renderedLines: report.renderedLines,
+          exempt: report.exempt,
         })),
       })}\n`,
     )
@@ -606,3 +623,47 @@ function reportDepth(
       .join('\n'),
   )
 }
+
+/**
+ * Lists every document past the ceiling and counts the exempt ones rather than
+ * naming them, since an exemption is settled where its marker sits.
+ */
+function reportLength(
+  reports: readonly FileReport[],
+  checkpoints: Checkpoints,
+): void {
+  logStep('Length')
+  logInfo(
+    `Whole documents measure rendered lines at ${checkpoints.renderWidth} columns, frontmatter and fenced blocks included.`,
+  )
+  logInfo(
+    'A changelog is exempt by name, and so is a document carrying a canon-length-exempt marker that names a reason.',
+  )
+
+  const past = reports.filter(
+    (report) => report.renderedLines > checkpoints.ceiling,
+  )
+  const over = past
+    .filter((report) => report.exempt === null)
+    .sort((a, b) => b.renderedLines - a.renderedLines)
+  const exempt = past.length - over.length
+
+  if (over.length === 0) {
+    logInfo(`No document past the ${checkpoints.ceiling}-line ceiling.`)
+  } else {
+    logWarn(
+      `${plural(over.length, 'document')} past the ${checkpoints.ceiling}-line ceiling`,
+    )
+    pipeOutput(
+      over
+        .map(
+          (report) => `${report.rel}  ${report.renderedLines} rendered lines`,
+        )
+        .join('\n'),
+    )
+  }
+
+  if (exempt > 0) {
+    logInfo(`${plural(exempt, 'exempt document')} past the ceiling.`)
+  }
+}