@erclx/canon 4.121.0 → 4.123.0

package/docs/agents/drift-surfaces.md

@@ -0,0 +1,192 @@
+---
+title: Drift surfaces
+description: The six sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
+---
+
+# Drift surfaces
+
+`canon sync --check` reports six sections outside the per-domain scan that
+`install-and-sync.md` describes, because each names something
+that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
+`newRules`, and `reverse`. None of them produces a change, and no sync command
+applies any of them. The headings below group the first three together and give
+`newSkills` its description under `newRules`, which answers the same question
+about a different corpus.
+
+All six report only against a toolkit-managed target, which is one carrying a
+`.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
+report says so through `managed` in the JSON and routes an unmanaged directory to
+`canon init`. Seeds are why the gate exists, since they enumerate from the toolkit
+source rather than from what a target installed, so an unmanaged directory would
+otherwise report every seed as `missing`.
+
+A root-layout domain counts as a marker on its own, because the detection fires
+only on root files the toolkit ships and a project in the old layout is one the
+toolkit installed. When `managed` is false every section comes back empty rather
+than the render alone going quiet, so a consumer reading `--json` never acts on a
+finding the rendered half withheld.
+
+## Seeds, superseded artifacts, and unmigrated domains
+
+`seeds` classifies every seed the toolkit ships against the target's copy, as
+`matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
+equivalent, since the domain walk lists what a target installed and cannot see a
+file that never arrived. There is no `customized` verdict here, because that one
+needs a stamp and seeds carry none, so a file history cannot attribute stays
+`drifted`. Reconcile the section with `seed-sync`, which merges one
+section at a time rather than replacing a file the project edits.
+
+A markdown seed installs rewritten rather than copied, since the `stub: true`
+marker the toolkit's own seed gate reads is stripped on the way in. The
+comparison above runs against what the install would write, so a marked seed a
+target never touched still reports `matching`. Every other seed copies byte for
+byte.
+
+`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
+against the `.canon/tasks/` that now ships. The entry carries `replacedBy` and
+nothing else, and the file is never deleted, since the content belongs to the
+project and only its author can decide where it moves. The list derives from the
+seed tree rather than from a fixed set of filenames, so a folder added later is
+covered without a code change. Only an exact stem matches, which leaves a
+suffixed variant such as `TASKS-ARCHIVE.md` unreported.
+
+No skill splits the file. The standard governing `replacedBy` is the one the
+`appliesTo` the standards catalog declares, and `canon standards <name>` reads
+its destination shape, so the split is the project's own to make.
+
+`unmigrated` names a domain sitting at the root layout an older toolkit installed
+to, with nothing at the path the current one reads. It carries `rootPath`,
+`installPath`, and a file count. Without it a project holding `standards/` at its
+root reports zero entries for that domain and reads as clean, which is the most
+misleading state the report can produce.
+
+The field currently names no domain. Standards and snippets are the two the
+toolkit ever installed at a project root, and both closed their install channel,
+so a project still holding a root `standards/` or `snippets/` folder is carrying
+its own authoring surface rather than an unfinished install. Nothing proposes
+moving either, and no command relocates the content. Move it yourself.
+
+## Rules the target never received
+
+`newRules` names a rule the target could receive and its tree does not hold. A
+sync refreshes the files a target already holds and adds none, so without this
+section a project's rule set freezes at its install date while every file it
+does hold reports as current. That is the report's most confident wrong
+answer, since a clean result reads as a target holding everything the toolkit
+publishes.
+
+The list rides beside `newSkills`, which asks the same question about the plugin
+catalog. Both are names rather than paths, and neither queues a change, because
+the two remedies differ: a skill loads live from the plugin directory and needs
+nothing run, while a rule reaches a target only when someone runs
+`canon gov install`.
+
+Read a clean section as reporting rather than as delivering. Nothing here
+installs, nothing counts toward `--exit-code`, and a target can read the list and
+act on none of it. The value stops at an operator reading it, which is the same
+contract the skills list already sets.
+
+Since `canon gov install` records the stack it resolved, a target carrying that
+record answers this by comparing its current entitlement against its current
+tree, with no anchor and no git diff involved. That is what lets the section
+name a rule that shipped before the target's last sync: the anchor a sync
+advances plays no part in the read, where an anchor-bound diff can never see a
+rule on the far side of a window a later sync moved past it. The per-file
+`missing` state `canon gov sync` reports comes from the same comparison, so a
+rule the chain lists reaches both surfaces the same way.
+
+A target stamped before governance recorded a chain falls back to the older
+band-inference read below. The measurement there anchors on governance's own
+stamp rather than on the oldest anchor across domains, since rules are
+domain-scoped and a shared anchor would let another domain's sync move the
+revision rules are measured from. A target carrying no chain and no governance anchor
+reports nothing at all: it has no date to measure against, and diffing from the
+start of history would read the whole catalog as new.
+
+An anchor this toolkit cannot resolve reports nothing by the same route, and that
+one is not visible. A stamp naming a revision the running clone has never seen,
+which is what a registry install without history or a shallow clone produces,
+fails the read and yields an empty list rather than a stated absence. It looks
+identical to a target holding every rule the toolkit publishes. `newSkills`
+behaves the same way, and neither carries the `historyUnavailable` flag the
+per-domain scan uses to separate the two. Treat an empty section on a toolkit
+that is not a full clone as unmeasured rather than clean. This gap does not
+reach the chain-based read above, since it consults no anchor at all.
+
+In the fallback, entitlement is filtered, because a stack does not receive
+every rule. The base stack takes the `core` and `claude` folders whole and
+every other stack extends it with individually named rules, so an unfiltered
+list would tell a base consumer about rules it can never receive and train the
+reader to skip the section.
+
+The filter accepts a band on either of two grounds. A folder the base stack takes
+whole is entitled to every target, read from the stack file so a folder added to
+base later needs no code change. Every other band is read off the folders the
+target already carries, which is the fallback's only evidence of what a target
+was entitled to before it recorded a chain. One band can be reached by more than
+one stack, so the test over-reports inside a folder the target holds, which
+costs a line where under-reporting would cost the section its point.
+
+A rule the target already holds is dropped by name. That is what keeps a rule the
+toolkit moved between band folders out of the list, since a rename reaches this
+read as an addition and only the name tells the two apart.
+
+This closes the dangling-citation case as a side effect rather than checking for
+one. The live instance is a rule citing a sibling authored after the target's
+install, and the section names the sibling as new rather than naming the citation
+as broken. That is enough for an operator to act on, and it is not a citation
+check.
+
+## The reverse walk
+
+`reverse` is the one section built by walking the target rather than the
+catalog. Every other surface enumerates toolkit-owned keys and asks whether the
+target matches, so a folder the toolkit deleted appears in none of them. It
+carries `unclaimed` and `historyUnavailable`.
+
+`unclaimed` names a folder the target holds at a top-level path the toolkit once
+shipped and has since deleted. The candidate roots come from the toolkit's own
+history rather than from a list, so a root dropped later is covered without a
+code change. Scoping to those roots is what keeps the walk useful: walking the
+whole tree reports every project folder as unclaimed, which is true and says
+nothing.
+
+The managed gate above applies here too, and it is the one place it surprises.
+A directory holding a dropped folder and nothing else reports an empty `reverse`
+rather than the folder, because it carries none of the three markers. Read an
+empty section on an unmanaged target as a walk that never ran rather than as a
+clean result.
+
+Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
+`project`, or `unattributed`. A dropped folder and one the project wrote are the
+same bytes at the same path, so the verdict is traced from history rather than
+guessed from the filesystem.
+
+Content matching a version the toolkit published reads as `dropped` and carries
+the `since` commit that published it. Names the toolkit shipped holding content
+it never published read as `unattributed`, which is a state in its own right
+rather than a soft yes. No overlap at all reads as `project`, and the render
+drops those while the JSON keeps them.
+
+Only files whose path the toolkit once held are hashed, so a project folder
+colliding on a retired name costs the walk no reads. The cost is that a file the
+toolkit shipped and the target renamed goes unmatched, the same limit the
+`unmigrated` count carries.
+
+## What counts toward the gate
+
+`unmigrated` counts toward `--exit-code`, since running the relocation closes it.
+`superseded` and every seed state are excluded, for the reason `orphaned` already
+is: only the user can move content they wrote, so failing a job on it leaves the
+job red with no mechanical remedy.
+
+`newRules` is excluded on a different ground, since a command does close it. What
+excludes it is that installing a rule changes what a project is governed by, so
+gating on the count would pressure a target into adopting rules nobody chose.
+`newSkills` is excluded because it needs no command at all.
+
+The whole `reverse` section is excluded on the same grounds, and more strongly.
+Every entry in it is a judgment about a file the project may own, and one of its
+three verdicts is a labelled unknown by design. The unmigrated detection shipped
+that exact false positive once, failing a push with no action that cleared it,
+so this section reports and gates nothing.

package/docs/agents/index.md

@@ -8,18 +8,20 @@ category: Agent surface
 
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
+- [Architecture record](architecture-record.md): The four findings canon context audit reads off the architecture record, being the entry cap and length gates the record states for itself, the claim coverage report, and the word counts
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
 - [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
-- [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
+- [Command catalog](commands.md): Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
-- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length and entry cap gates and claim coverage, which folders each check reaches, and what moved to the attribute tier
+- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, where the architecture record's findings are described, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Doc classifier](context-classify.md): Classifying canonical-doc content as keep, replace/rewrite, history, or move in diff and sweep mode, the classifier setting pair, the record shape, and the exit codes
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
 - [Design board](design-board.md): Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
+- [Drift surfaces](drift-surfaces.md): The six sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
@@ -27,7 +29,9 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
 - [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing
 - [Label coverage](label-coverage.md): Reading a changed set against the pull request label map, the two tables it matches, how a gap is separated from a decision, and why an absent map is an answer
+- [Markdown audit weight](markdown-audit-weight.md): The structural half of the markdown audit, being bullet and paragraph weight, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and why none of them gates
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
+- [Migrate](migrate.md): What each canon migrate verb moves and rewrites, what it refuses, the markers that keep an old spelling, and the idempotence check a second run gives
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
@@ -35,8 +39,9 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records push](records-push.md): Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
+- [Records stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, and the exit codes and refusals
 - [Records validate](records-validate.md): Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
-- [Records](records.md): The two roots a record folder resolves at, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation and the private-remote backup are described
+- [Records](records.md): The two roots a record folder resolves at, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation, the memory review queue, and the private-remote backup are described
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
@@ -51,7 +56,10 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
-- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, deriving the branch a dispatch and a worker both take, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
+- [Tasks archive](tasks-archive.md): Archiving a shipped task by stem or pull request, declining one decided against, the refusal reasons each carries, and how the plan and ready folder move with the task
+- [Tasks plans](tasks-plans.md): The five verbs that read or write a task's plan, being where it sits and who cites it, whether it waits on the operator, the branch it derives, what a branch reached against what it declared, and writing its Plan line
+- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the untested, claims, and unplaced arrays, the exit codes, and the refusal reasons
+- [Tasks](tasks.md): Claiming the next phase label, recording a pull request number and closing an outcome, listing each task's readiness, and where archiving, the plan verbs, and board validation are described
 - [Teach authoring](teach-authoring.md): 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](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): 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

package/docs/agents/install-and-sync.md

@@ -228,187 +228,8 @@ edit and a job counting those stays red with no remedy.
 Six sections sit outside the per-domain scan, because each names something
 that walk cannot see: `seeds`, `superseded`, `unmigrated`, `newSkills`,
 `newRules`, and `reverse`. None of them produces a change, and no sync command
-applies any of them. The headings below group the first three together and give
-`newSkills` its description under `newRules`, which answers the same question
-about a different corpus.
-
-All six report only against a toolkit-managed target, which is one carrying a
-`.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
-report says so through `managed` in the JSON and routes an unmanaged directory to
-`canon init`. Seeds are why the gate exists, since they enumerate from the toolkit
-source rather than from what a target installed, so an unmanaged directory would
-otherwise report every seed as `missing`.
-
-A root-layout domain counts as a marker on its own, because the detection fires
-only on root files the toolkit ships and a project in the old layout is one the
-toolkit installed. When `managed` is false every section comes back empty rather
-than the render alone going quiet, so a consumer reading `--json` never acts on a
-finding the rendered half withheld.
-
-#### Seeds, superseded artifacts, and unmigrated domains
-
-`seeds` classifies every seed the toolkit ships against the target's copy, as
-`matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
-equivalent, since the domain walk lists what a target installed and cannot see a
-file that never arrived. There is no `customized` verdict here, because that one
-needs a stamp and seeds carry none, so a file history cannot attribute stays
-`drifted`. Reconcile the section with `seed-sync`, which merges one
-section at a time rather than replacing a file the project edits.
-
-A markdown seed installs rewritten rather than copied, since the `stub: true`
-marker the toolkit's own seed gate reads is stripped on the way in. The
-comparison above runs against what the install would write, so a marked seed a
-target never touched still reports `matching`. Every other seed copies byte for
-byte.
-
-`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
-against the `.canon/tasks/` that now ships. The entry carries `replacedBy` and
-nothing else, and the file is never deleted, since the content belongs to the
-project and only its author can decide where it moves. The list derives from the
-seed tree rather than from a fixed set of filenames, so a folder added later is
-covered without a code change. Only an exact stem matches, which leaves a
-suffixed variant such as `TASKS-ARCHIVE.md` unreported.
-
-No skill splits the file. The standard governing `replacedBy` is the one the
-`appliesTo` the standards catalog declares, and `canon standards <name>` reads
-its destination shape, so the split is the project's own to make.
-
-`unmigrated` names a domain sitting at the root layout an older toolkit installed
-to, with nothing at the path the current one reads. It carries `rootPath`,
-`installPath`, and a file count. Without it a project holding `standards/` at its
-root reports zero entries for that domain and reads as clean, which is the most
-misleading state the report can produce.
-
-The field currently names no domain. Standards and snippets are the two the
-toolkit ever installed at a project root, and both closed their install channel,
-so a project still holding a root `standards/` or `snippets/` folder is carrying
-its own authoring surface rather than an unfinished install. Nothing proposes
-moving either, and no command relocates the content. Move it yourself.
-
-#### Rules the target never received
-
-`newRules` names a rule the target could receive and its tree does not hold. A
-sync refreshes the files a target already holds and adds none, so without this
-section a project's rule set freezes at its install date while every file it
-does hold reports as current. That is the report's most confident wrong
-answer, since a clean result reads as a target holding everything the toolkit
-publishes.
-
-The list rides beside `newSkills`, which asks the same question about the plugin
-catalog. Both are names rather than paths, and neither queues a change, because
-the two remedies differ: a skill loads live from the plugin directory and needs
-nothing run, while a rule reaches a target only when someone runs
-`canon gov install`.
-
-Read a clean section as reporting rather than as delivering. Nothing here
-installs, nothing counts toward `--exit-code`, and a target can read the list and
-act on none of it. The value stops at an operator reading it, which is the same
-contract the skills list already sets.
-
-Since `canon gov install` records the stack it resolved, a target carrying that
-record answers this by comparing its current entitlement against its current
-tree, with no anchor and no git diff involved. That is what lets the section
-name a rule that shipped before the target's last sync: the anchor a sync
-advances plays no part in the read, where an anchor-bound diff can never see a
-rule on the far side of a window a later sync moved past it. The per-file
-`missing` state `canon gov sync` reports comes from the same comparison, so a
-rule the chain lists reaches both surfaces the same way.
-
-A target stamped before governance recorded a chain falls back to the older
-band-inference read below. The measurement there anchors on governance's own
-stamp rather than on the oldest anchor across domains, since rules are
-domain-scoped and a shared anchor would let another domain's sync move the
-revision rules are measured from. A target carrying no chain and no governance anchor
-reports nothing at all: it has no date to measure against, and diffing from the
-start of history would read the whole catalog as new.
-
-An anchor this toolkit cannot resolve reports nothing by the same route, and that
-one is not visible. A stamp naming a revision the running clone has never seen,
-which is what a registry install without history or a shallow clone produces,
-fails the read and yields an empty list rather than a stated absence. It looks
-identical to a target holding every rule the toolkit publishes. `newSkills`
-behaves the same way, and neither carries the `historyUnavailable` flag the
-per-domain scan uses to separate the two. Treat an empty section on a toolkit
-that is not a full clone as unmeasured rather than clean. This gap does not
-reach the chain-based read above, since it consults no anchor at all.
-
-In the fallback, entitlement is filtered, because a stack does not receive
-every rule. The base stack takes the `core` and `claude` folders whole and
-every other stack extends it with individually named rules, so an unfiltered
-list would tell a base consumer about rules it can never receive and train the
-reader to skip the section.
-
-The filter accepts a band on either of two grounds. A folder the base stack takes
-whole is entitled to every target, read from the stack file so a folder added to
-base later needs no code change. Every other band is read off the folders the
-target already carries, which is the fallback's only evidence of what a target
-was entitled to before it recorded a chain. One band can be reached by more than
-one stack, so the test over-reports inside a folder the target holds, which
-costs a line where under-reporting would cost the section its point.
-
-A rule the target already holds is dropped by name. That is what keeps a rule the
-toolkit moved between band folders out of the list, since a rename reaches this
-read as an addition and only the name tells the two apart.
-
-This closes the dangling-citation case as a side effect rather than checking for
-one. The live instance is a rule citing a sibling authored after the target's
-install, and the section names the sibling as new rather than naming the citation
-as broken. That is enough for an operator to act on, and it is not a citation
-check.
-
-#### The reverse walk
-
-`reverse` is the one section built by walking the target rather than the
-catalog. Every other surface enumerates toolkit-owned keys and asks whether the
-target matches, so a folder the toolkit deleted appears in none of them. It
-carries `unclaimed` and `historyUnavailable`.
-
-`unclaimed` names a folder the target holds at a top-level path the toolkit once
-shipped and has since deleted. The candidate roots come from the toolkit's own
-history rather than from a list, so a root dropped later is covered without a
-code change. Scoping to those roots is what keeps the walk useful: walking the
-whole tree reports every project folder as unclaimed, which is true and says
-nothing.
-
-The managed gate above applies here too, and it is the one place it surprises.
-A directory holding a dropped folder and nothing else reports an empty `reverse`
-rather than the folder, because it carries none of the three markers. Read an
-empty section on an unmanaged target as a walk that never ran rather than as a
-clean result.
-
-Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
-`project`, or `unattributed`. A dropped folder and one the project wrote are the
-same bytes at the same path, so the verdict is traced from history rather than
-guessed from the filesystem.
-
-Content matching a version the toolkit published reads as `dropped` and carries
-the `since` commit that published it. Names the toolkit shipped holding content
-it never published read as `unattributed`, which is a state in its own right
-rather than a soft yes. No overlap at all reads as `project`, and the render
-drops those while the JSON keeps them.
-
-Only files whose path the toolkit once held are hashed, so a project folder
-colliding on a retired name costs the walk no reads. The cost is that a file the
-toolkit shipped and the target renamed goes unmatched, the same limit the
-`unmigrated` count carries.
-
-#### What counts toward the gate
-
-`unmigrated` counts toward `--exit-code`, since running the relocation closes it.
-`superseded` and every seed state are excluded, for the reason `orphaned` already
-is: only the user can move content they wrote, so failing a job on it leaves the
-job red with no mechanical remedy.
-
-`newRules` is excluded on a different ground, since a command does close it. What
-excludes it is that installing a rule changes what a project is governed by, so
-gating on the count would pressure a target into adopting rules nobody chose.
-`newSkills` is excluded because it needs no command at all.
-
-The whole `reverse` section is excluded on the same grounds, and more strongly.
-Every entry in it is a judgment about a file the project may own, and one of its
-three verdicts is a labelled unknown by design. The unmigrated detection shipped
-that exact false positive once, failing a push with no action that cleared it,
-so this section reports and gates nothing.
+applies any of them. What each reports, the managed-target gate they share, and
+which count toward `--exit-code` are in `drift-surfaces.md`.
 
 ## Bootstrap
 

package/docs/agents/markdown-audit-weight.md

@@ -0,0 +1,73 @@
+---
+title: Markdown audit weight
+description: The structural half of the markdown audit, being bullet and paragraph weight, run depth, the two cadence numbers, and the length ceiling, with the samples behind each checkpoint and why none of them gates
+---
+
+# Markdown audit weight
+
+## Bullets, paragraphs, and depth
+
+Bullet weight and depth are the checks that moved off `canon context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
+
+Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan `markdown-audit.md` describes: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
+
+A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
+
+The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 15 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 886 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+
+A sentence boundary closes on terminal punctuation ahead of a capital or a code span. The capital is what keeps a version pin and a decimal from each reading as two sentences, and the code span is admitted beside it because a command name opening a sentence carries no capital to find.
+
+The paragraph weight sits at 700 and the bullet weight at 400. Both shipped at 400, because the paragraph number was borrowed from the bullet rule when the two checks landed together, and each has since been read against a sample of its own. They are separate checkpoints in the standard and separate patterns in the parser, so a read that moves one leaves the other where it is.
+
+### The sample behind the paragraph number
+
+The checkpoint shipped at 400 as a borrowed number and was decided against a read of the prose it reports. Thirty-six findings were sampled, six from each of six weight bands, drawn at even spacing through each band ordered by path and line, and each was classed as prose a reader wants split or prose the checkpoint should not have reported.
+
+Every band below was measured before the scan stopped counting link syntax as prose, so a paragraph sitting in one of these bands is heavier than a paragraph reported at the same number today. The re-sample in the section below re-reads the same range against the corrected measure and reaches the opposite verdict on it, which is the measure moving rather than the reader.
+
+| Band      | Wants the split | Reads as written |
+| --------- | --------------- | ---------------- |
+| 400 - 425 | 1               | 5                |
+| 425 - 450 | 2               | 4                |
+| 450 - 500 | 2               | 4                |
+| 500 - 600 | 2               | 4                |
+| 600 - 750 | 6               | 0                |
+| Past 750  | 6               | 0                |
+
+Precision is what moved the number rather than the finding count. Below 600 the checkpoint was right about seven of twenty-four sampled paragraphs, and past 600 it was right about all twelve. A checkpoint is a prompt to look, and a prompt wrong three times in four teaches a reader to stop looking. The distribution offers no seam to place the number against, with a median of 487 and a seventy-fifth percentile of 563, so the read is the whole of the evidence.
+
+Nothing inside the 500 to 600 band separated the two classes by length, which is the reason the number did not land there. The two paragraphs wanting a split ran 543 and 590 characters against four reading well at 515, 532, 555, and 569.
+
+The sample is thirty-six paragraphs against a reported population in the hundreds, and one reader classed all of them. Treat a band's rate as the order of magnitude it is rather than as a measured precision, and re-sample before moving the number again.
+
+### The re-sample that moved the number to 700
+
+That re-sample ran once the scan stopped counting link syntax as prose. Findings at 604, 633, and 677 characters each read as an ordinary four-sentence paragraph on one topic, density arrived around 760 and was plain by 860, and the move cut the weight half of the report roughly in half while leaving the sentence cap untouched.
+
+A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
+
+## Cadence
+
+Uniform cadence is the failure a ban list cannot express. A ban set states negatives, and fragments, verbless clauses, and sentences that all run one length are each the absence of something, so no word added to a ban list reaches any of them. The shape layer already measured a bullet, a paragraph, and a run, and stopped one level above where that failure lives.
+
+Cadence measures a paragraph on two numbers. The spread is the words between its longest and shortest sentence, and the opener count is the times one word opens a sentence in it. A spread of five words or under reads as one cadence, and a word opening more than two sentences is a pattern rather than a coincidence. Both come from `## Rhythm` in the `write-human` skill, which states them about prose a person reads, and this measures against that statement rather than setting a threshold of its own.
+
+Words are counted off the text a reader is shown. A link contributes its anchor text, an autolink contributes nothing, and the sentence boundaries do not move under that masking, since the boundary pattern requires whitespace after the terminal punctuation and no destination carries any. An opening word is lowercased and stripped of punctuation, so a sentence opening on a backticked command name reports the command.
+
+A paragraph carrying fewer than three sentences is skipped rather than scored. A two-sentence configuration note has no spread worth reading, and the opener rule is written about a third sentence turning a coincidence into a pattern, so neither number says anything before the floor. That is the cheap form of a wider exemption: a shape-aware one, exempting a short reference block by what it is rather than by how many sentences it holds, waits on a second case.
+
+The unit is the paragraph and each file names its worst on each measure, which follows the depth check rather than setting a precedent. A file's flattest paragraph and its most repetitive one are named only when each crosses its checkpoint, so a file reading healthy names nothing rather than offering its least healthy paragraph as a finding.
+
+Neither number gates and neither names a file wrong. This is a weaker claim than the one the weight checkpoints make, because a healthy range differs by surface: a catalog entry is several short sentences carrying one fact each, and a page arguing a decision is not, so one range applied across the corpus would report the surfaces that are correct. The run therefore states where the numbers came from beside them, and the counts are what a reader compares against.
+
+A reading of that spread across the whole corpus is what backs the range above, taken once against this repository's own tracked markdown rather than against a target project's.
+
+That reading travels with the command rather than staying here. `BASELINE` in `src/markdown/structure.ts` carries the overall share, the per-file range, and the ten-paragraph floor beneath which a file's own rate says nothing, and the run prints all four in the legend beside the rate it measured. A count with no range beside it reads as a finding, and naming that a healthy range differs by surface states that a range exists rather than what it looks like. This page is toolkit-internal, so a reader running the command in a project that installed no standards would otherwise have two counts and nothing to place them against.
+
+Two of the rules `write-human` states are deliberately not implemented. A sentence's grammatical shape and whether it carries a finite verb each need a parse rather than a match, and an imperative would read as a defect under a pattern that approximated either. The verbless share is the measure closest to the reported symptom, which is exactly why shipping it wrong would discredit the two that hold.
+
+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`.