@journeykit/canon 0.36.0 → 0.38.0

package/dist/skills/SKILL.src.md

@@ -127,7 +127,11 @@ tree, or in a repo with no commits, a command that needs a commit refuses
 After a chore approval or a reopen, a scenario whose latest evidence was
 recorded on the current `codeTree` needs nothing new: a docs-only chore then
 needs its change-level review alone. What counts as code is `code.exclude` in
-`canon.yaml` (globs, default `docs/**` and `*.md`). When code did change,
+`canon.yaml` (globs, default `docs/**` and `*.md`). A chore approved over the
+code as it still is (the `(code tree <id>)` of its `Approved:` line is the
+current tree) asks for no evidence at all, whatever tree the evidence is on, and
+`status` says so; an approval with no recorded tree follows the rule above.
+When code did change,
 `canon status`, `meta.next` and the refusal hint lead with one batch over
 every report, for example
 `canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer`
@@ -156,7 +160,15 @@ an object-store tier, in which case `evidence add`, `review scenario`, `review c
 `canon artifacts verify` (`--full` re-hashes every blob) ask the store and
 refuse, never pass, when it cannot be reached. Moving an existing store with
 `canon artifacts move --tier <tier>` is the repo owner's decision, not a step
-of the loop.
+of the loop. So is `canon artifacts prune`, which deletes the blobs no record
+binds any more (the store only grows: a report written anew on every run adds a
+blob per run). A blob stays while the latest evidence or a current review binds
+it (what the gate and `artifacts verify` read), while a record not promoted yet
+binds it, and, with `--keep-days N`, while any evidence or review of the last
+`N` days binds it; the bare run previews the blobs it deletes and why the rest
+stay, and `--commit --plan-digest` deletes. A deleted local blob stays in git
+history (shrinking that history is the repo owner's call, not the command's); a
+deleted object of an object-store tier is gone for good.
 
 ### Search and trace
 
@@ -211,8 +223,11 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   your complete command set, every option of every leaf included. Run `canon schema <command> --json` only for a
   command it does not list, or after a `USAGE` refusal (read `error.field`
   and `error.expected` first). `canon schema --json` is the tree of every group and command
-  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it);
-  its `options` define once the options that two or more commands share (`--repo`, `--as`, `--actor`, …)
+  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it).
+  `x-canon.roles` is the string `all` for a command all four roles use, else an array of
+  role names (empty: only a human runs it), so read it as `roles == "all"` or a name in the array;
+  the root's `x-canon.rolesForm` says so once. The tree's
+  `options` define once the options that two or more commands share (`--repo`, `--as`, `--actor`, …)
   and a command names them. `canon schema <group> --json` lists a group's
   commands; `canon schema <command> --json` is the call surface of one command and nothing
   else: `options` (each name of a tree option, or an object with `valueType`, a typed
@@ -227,11 +242,18 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   gives the JSON Schema of each report in `schemas`, `Input` (the schema of one `--input`
   document) and `rejects` (what each validator refuses, in order); `#/schemas/<Name>` in
   the command document resolves there. The first line of every `--help` points at it.
+- An option of the same name takes the same value in every command that has it, and `canon schema` declares it once. An id
+  (`--project`, `--role`, `--domain`) is a kebab slug: lowercase letters and digits, single hyphens between them. A name
+  (`--actor`, `--approver`, `--relayed-via`) and a sentence (`--reason`, `--summary`, `--override-reason`) are one line of text:
+  the white space around it is trimmed (what is recorded, and what a signature is made of, is the trimmed text), and a value
+  that is empty once trimmed, or has a control character (a tab, an escape) or a line break inside it, is refused with the
+  command's own argument code. `--round` and `--limit` start at 1, and `--regime` is the four-part key `retrieve` and
+  `dispatch begin` both take. `finding close` takes `fixed`, `rejected` or `deferred`, never `open`.
 - Pass `--json` and read stdout as one document, nothing on stderr. Success is
   `{"ok":true,"data":…,"meta":…}`; failure is
   `{"ok":false,"error":{…},"meta":…}` (a check that fails keeps its report in
   `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`),
-  `contractVersion` (`1.4`), `schemaVersion`,
+  `contractVersion` (`1.5`), `schemaVersion`,
   `command`, and when present `next`, `warnings` (`[{code, message}]`) and
   `page`; a repeated write that changed nothing reports `data.unchanged: true`.
   Absent members are omitted, never `null` or `[]` (a value you sent empty comes back as `received: ""`).
@@ -305,9 +327,9 @@ leaves below take one object only.
 
 ### Preview, then `--commit`
 
-The five commands that delete or rewrite existing data (`canon purge`,
+The six commands that delete or rewrite existing data (`canon purge`,
 `canon tier age`, `canon ledger compact`, `canon artifacts move`,
-`canon migrate`) act in two steps. The bare run previews: it writes nothing,
+`canon artifacts prune`, `canon migrate`) act in two steps. The bare run previews: it writes nothing,
 exits 0 and prints the effects and a `planDigest`. Read the effects, then act
 with `--commit --plan-digest <planDigest>`. It refuses (`PLAN_STALE`) when
 the plan differs from the one you previewed, so run the preview again. Appends
@@ -342,15 +364,15 @@ and `canon context` warn when the repo holds 0.27-era state and put
 ```bash
 # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
 canon init
-# harnesses for the canon skill; without it init takes the detected .claude/.codex/.omp/.pi (it never asks)
-canon init --providers=claude,codex
+# harnesses for the canon skill, one --harness each (--no-harness for none); without them init takes the detected .claude/.codex/.omp/.pi (it never asks)
+canon init --harness claude --harness codex
 # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
 canon skills install
-# any subset or none; rewrites skills.providers
-canon skills install --providers=claude,codex,omp,pi
+# any subset; rewrites skills.providers (--no-harness records none)
+canon skills install --harness claude --harness codex --harness omp --harness pi
 # read-only drift check; exit 1 (SKILLS_CHECK_FAILED) names each orphan, a projected file the bundle no longer ships
 canon skills check
-# diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+# diagnostics, incl. a stray canon projection for an unselected harness and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
 canon skills doctor
 ```
 
@@ -361,7 +383,7 @@ Claude gets `.claude/skills/canon/`, Codex `.agents/skills/canon/`, OMP
 `.omp/skills/canon/`, Pi `.pi/skills/canon/` (the retrieve script is a sidecar,
 not an installed hook). `check` reports a stub written by another canon
 version; `install` rewrites it. The harness list lives in `canon.yaml` as
-`skills: { providers: [...] }`; change it with `canon skills install --providers=<list>`,
+`skills: { providers: [...] }`; change it with `canon skills install --harness <name>` once for each name (or `--no-harness`),
 never by assuming a default.
 
 `install` and `doctor` end with `owned-paths:`, the globs of every path

package/dist/skills/reference/canon-gate.md

@@ -255,6 +255,43 @@ review of the chore itself (`canon review change <slug>`) before
 `--to shipped`; a changed verdict or case set stales that scenario's
 review as before (and a new `divergence accept`, where the gap remains).
 
+A chore's approval records the code tree of the work tree at that moment, as
+`(code tree <id>)` in its `Approved:` line (outside the brief digest; none
+outside git or with no commit). While that tree is the current code tree the
+chore changed no code since it was approved, so it asks for no evidence at
+all, whatever tree each scenario's latest evidence is on, and `status` says so
+on its line; its change-level review is still asked, and it must be a review of
+this code (the review records the code tree it saw): a brief edited after the
+approval needs a new review, and so does a review of other code, as when the
+same brief is approved again over code that came after the review. An approval
+with no recorded tree (written before 0.37) follows the rule above.
+
+A policy may narrow what a chore asks for with `code_scopes` (0.38): a key is
+a scenario id's area (`core`) or surface (`app.bulkread`), the value a list of
+path patterns written like `code.exclude`; the surface key wins over the area
+key, and a scenario with neither has no scope. For a scenario with a scope the
+chore compares the code tree of its latest evidence with the tree now, and asks
+for new evidence only when a changed path (added, modified, deleted, a rename
+by its old and its new path) matches the scope; the refusal names the first
+three such paths and how many there are. No scope, no recorded tree, or an old
+tree that cannot be computed (the commit is gone, the evidence was recorded over
+uncommitted code) keep the rule above. The scopes stand only while the policy
+is the one a human approved: an agent cannot widen them (an edit after the
+approval fails closed, and so does a change that a brief approval would have
+approved implicitly), and `status` and
+`gate check` warn, never refuse, about a pattern that matches no file or a key
+that matches no scenario. A shared file (lock file, build setting, fixture)
+belongs in the scope of every scenario that depends on it.
+A key none of whose patterns matches a file of the current code tree declares no
+scope (a misspelt `Core/**` never exempts; matching is byte-exact), and an empty
+list is malformed, so that scenario follows the rule above; both are warned.
+`canon brief approve` records the policy approval in its own call except when
+the policy's `code_scopes` differs from the last approved policy's: then it
+approves the brief only, leaves the policy approval stale (the gate fails closed
+until a human reads the scopes and runs `canon policy approve`) and names the
+changed keys, so an agent cannot widen the scopes by asking for a brief's
+approval.
+
 ### Audit records (`canon evidence audit`)
 
 canon never generates or runs an audit. An external evaluator does, and
@@ -588,7 +625,10 @@ git-tracked, no credentials). With an object-store tier, `evidence add`,
 `canon artifacts verify [--full]` ask the store (a HEAD per digest; `--full`
 downloads and re-hashes) and refuse, never pass, when it cannot be reached.
 `canon artifacts move --tier <tier>` (a preview; `--commit --plan-digest` acts) moves an existing local
-store; it is the repo owner's decision. See `canon-storage`.
+store; it is the repo owner's decision. `canon artifacts prune` (a preview;
+`--commit --plan-digest` acts) deletes the blobs no record binds any more and
+leaves what `gate check` and `artifacts verify` read, so their answers do not
+change; it is the repo owner's decision too. See `canon-storage`.
 
 `canon gate check` re-checks every file bound to a LATEST evidence record
 (the latest per task and per `(project_id, scenario_id)`):

package/dist/skills/reference/canon-learn.md

@@ -52,7 +52,11 @@ The production activation path is a signed, paired-evaluation workflow:
    `meta.next` names the human signing step. The `data` contains the evaluation digest, RFC3339 `approved_at`,
    subject `strategy:<strategy_id>`, namespace
    `canon-learning-approval-v1`, and `payload_hex`. `approval-payload` never
-   reads a private key and never sets `verified`.
+   reads a private key and never sets `verified`. `--approval-at` is an RFC 3339
+   date-time (`2026-10-02T12:00:00Z`; a date alone, white space around it and a
+   one-digit month are refused): canon never stamps it, so fix it once and give
+   the same value to the signature and to the record. The bytes hold the instant
+   as UTC to the nanosecond, so one instant written `Z` or `+09:00` is one payload.
 6. Decode `payload_hex` to the exact canonical JSON bytes. The signed object
    is:
 
@@ -190,7 +194,8 @@ canon strategy rollback <strategy_id> --reason "<reason>" --actor alice \
 
 `--signature-file` is an armored SSH detached signature over the
 `canon-learning-approval-v1` payload bound to
-`strategy:<id>:rollback:<sha256(reason)>`, actor, and `--approval-at`.
+`strategy:<id>:rollback:<sha256(reason)>`, actor, and `--approval-at` (the same
+RFC 3339 date-time that was signed; another instant fails the signature).
 `actor` MUST be listed in policy-pinned `approval.allowed_signers`; verification
 uses that file and `ssh-keygen -Y verify`. Successful rollback writes durable
 provenance, sets lifecycle `rolled_back`, and records the optional contradicting

package/dist/skills/reference/canon-review.md

@@ -88,6 +88,15 @@ on the closing version, shown by `finding list` as `[reason: …]` and carried
 in the JSON. Give the reason when you reject or defer: it is the only record
 of why the finding was not fixed.
 
+Closing `rejected` or `deferred` overturns the judgement of whoever raised
+the finding, so it is the reviewer's: a call that declares another role
+(`--as` or `CANON_ROLE`: planner, implementer, orchestrator) is refused
+with `FINDING_ROLE_DENIED`, nothing is written and the finding stays open.
+`fixed` is closed by every role. The closing version records the role the
+call declared (`--role` is accepted only when it names that role, or when
+none is declared) and no role when none was; `finding list` names who
+closed each closed finding and under which role (`closedBy`, `closedRole`).
+
 `--scenario` (repeatable, each a scenario the index knows; refused with
 `SCENARIO_NOT_FOUND` otherwise) names the scenarios the finding is
 about. After a `fixed` close, fresh evidence for those scenarios alone
@@ -155,7 +164,7 @@ text in the summary, not a field.
 
 | Disposition | Meaning |
 |---|---|
-| `open` | Raised and not yet dealt with. The default on `finding add`; `finding close --disposition open` reopens. |
+| `open` | Raised and not yet dealt with. The default on `finding add`; `finding close` refuses it (a defect that came back is a new finding). |
 | `fixed` | Fixed by a commit. Carries `--resolution-rev <rev>` (default `HEAD`) naming a commit this repo holds; only `fixed` may carry one. |
 | `rejected` | The reviewer's point was considered and declined. Needs `--reason`. |
 | `deferred` | Accepted, but postponed to later work. Needs `--reason`. |
@@ -164,8 +173,10 @@ text in the summary, not a field.
 
 Every reader takes the **latest version per natural key**
 `(change_id, round, seq)` — the same fold the report's finding panel
-uses. A blocker raised `open` and later closed `fixed` counts as fixed; a
-fixed finding reopened with `--disposition open` counts as open again.
+uses. A blocker raised `open` and later closed `fixed` counts as fixed.
+A finding is not reopened: `finding close` takes `fixed`, `rejected` or
+`deferred` and refuses `--disposition open`; a defect that came back is a new
+`finding add` (the next `--seq`).
 
 ## `canon review scenario`
 
@@ -446,7 +457,7 @@ subject's `change_ids` (`canon subject adopt`). The subject string is
 `<change_id>#<round>.<seq>`:
 
 ```
-open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close <change> --round <n> --seq <n> --disposition fixed`, or close it as rejected or deferred
+open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close <change> --round <n> --seq <n> --disposition fixed`, or have a reviewer close it as rejected or deferred
 ```
 
 Findings on changes no in-scope subject has adopted do not block.

package/dist/skills/reference/canon-storage.md

@@ -172,6 +172,32 @@ uploads, reads back and verifies every local blob, then writes the
 `.canon/artifacts/`; commit the removals, `.gitignore` and `canon.yaml`. It is
 resumable and a second run finds nothing to do.
 
+The store only grows: a report written anew on every run adds a blob per run.
+`canon artifacts prune [--keep-days N]` (a preview; `--commit --plan-digest
+<digest>` acts) deletes the blobs no record binds. It keeps a blob for every
+reason that holds, and the preview names them: `latest-evidence` (the latest
+evidence per task and per `(project_id, scenario_id)` binds it, what the gate and
+`artifacts verify` read), `current-review` (a review still in effect binds it),
+`staged` (a record not promoted yet binds it) and `within-keep-days` (with
+`--keep-days N`, evidence or a review of the last `N` days, in the ledger or its
+archive, binds it). Everything else in the configured store goes: the local
+directory, or the objects of the tier `artifact_store:` names by the same rule
+(a copy left in the local directory of such a repo is judged by it too). The
+preview counts the blobs and bytes that go and stay, lists the blobs to delete
+a page at a time (`--limit`, `--cursor`, `--all`) and offers no `--commit` when
+there is nothing to delete. The plan digest covers the blobs to delete, the
+blobs to keep with their reasons and every record read, so evidence added since
+the preview is `PLAN_STALE` and nothing is deleted. A repo whose records,
+staging area or archive cannot be read in full is refused: a blob is never
+deleted on a guess. After a prune, `artifacts verify` and `gate check` answer as
+they did. A deleted local blob leaves the working tree: commit the removal. It
+stays in git history, and shrinking that history is the repo owner's call, not
+the command's. A deleted object of a tier cannot be undone, and the preview says
+so with the object count. A delete that fails stops the run: with nothing deleted yet
+it is `ARTIFACTS_STORE_FAILED` (an object) or `WRITE_FAILED` (a local file); after
+some, `ARTIFACTS_PRUNE_INCOMPLETE` names what was deleted, and a new preview
+lists what remains.
+
 ## What `canon report build` does and doesn't read
 
 canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report build`
@@ -192,7 +218,7 @@ section listing them and emits a matching stderr `WARN`.
 
 ## Retention, export, and access audit
 
-`canon purge --kind <kind> --before <RFC3339> [--commit --plan-digest <planDigest>] [--repo <dir>] [--json]`
+`canon purge --kind <kind> --before <RFC3339 date or date-time> [--commit --plan-digest <planDigest>] [--repo <dir>] [--json]`
 is the canonical data-lifecycle boundary: the bare run previews: it prints the removal set and
 its `planDigest` and deletes nothing; `--commit --plan-digest <planDigest>` deletes only if
 the plan recomputed now has the same digest (`PLAN_STALE`, exit 2, when the
@@ -220,7 +246,7 @@ human's review and `--commit --plan-digest`), and an export's page state (`total
 file and answers with `data: { output, kind, recordCount }`; `--dry-run`
 answers with what it would write and writes nothing.
 
-`canon export --kind <kind> [--before <RFC3339>] [--after <RFC3339>]
+`canon export --kind <kind> [--before <RFC3339 date or date-time>] [--after <RFC3339 date or date-time>]
 [--output <file>] [--json] [--limit <n> | --all] [--cursor <c>]` emits a versioned manifest containing source scope,
 counts, digests, and redacted metadata. It does not authorize backend access;
 credentials remain an operator prerequisite. New output files are mode
@@ -290,13 +316,13 @@ skills:
   providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
 ```
 
-`canon init` writes it and never asks: `--providers a,b` (or `none`) is the
+`canon init` writes it and never asks: `--harness a --harness b` (or `--no-harness`) is the
 answer; without it init takes the harnesses whose
 `.claude`, `.codex`, `.omp` or `.pi` directory exists, and with none detected
 it writes only a commented example
 and installs nothing. `.agents` alone never selects Codex. `canon skills
 install|check|doctor` follow the section; `install` prunes projected files the bundle no longer ships when their bytes match the lock (a modified one stays, reported as `kept:`), `check` exits 1 (`SKILLS_CHECK_FAILED`) naming each orphan and `doctor` prints `orphan:` lines; `canon skills install
---providers=<list>` rewrites it in place. Without the section they use the
+--harness <name>` (once for each name) or `--no-harness` rewrites it in place. Without the section they use the
 install lock's providers, then the detected ones; nothing undetected is ever
 added. A present section that is not this shape, or names another harness,
 fails those commands (exit `1`), and `canon init --check` reports
@@ -381,7 +407,7 @@ retry (the command exits `2` and writes no record).
 ## The repository write lock
 
 A committed destructive command (`canon purge`, `canon tier age`, `canon ledger
-compact`, `canon artifacts move`, `canon migrate`) recomputes its plan, checks
+compact`, `canon artifacts move`, `canon artifacts prune`, `canon migrate`) recomputes its plan, checks
 its digest and then makes the effects, and nothing may change the plan in
 between. It holds an OS file lock on `.canon/repo-write.lock` for the whole
 span, from before it recomputes the plan to after its last effect; a preview

package/dist/skills/reference/canon-subject.md

@@ -547,8 +547,9 @@ warn, and a command that writes and judges it is refused
   `reason`), one rule in one section, reason required; add `match` to waive
   only the findings whose matched text contains it. Listed in the output.
 - **`approve`** records the human's answer: it writes
-  `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
-  brief and records the policy approval in the same call. It refuses
+  `Approved: <who> <when> — "<words>" (code tree <id>) (brief sha256:<digest>)`
+  into the brief (the code tree, 0.37, is the work tree's as it is now and is
+  left out outside git or with no commit) and records the policy approval in the same call. It refuses
   (exit 2) while the check has structure blockers. Edit the brief
   afterwards and every reader says `BRIEF_APPROVAL_STALE` until a
   human answers again and `approve` runs again. Run it only from the
@@ -617,8 +618,8 @@ uses, so status and the gate cannot disagree about a gap:
   something after it, and sits outside HTML comments (`<!-- … -->`,
   multi-line included) and fenced code blocks (```` ``` ```` or `~~~`).
   `canon brief approve` writes it from the human's answer, as
-  `Approved: <who> <when> — "<the human's words>" (brief sha256:<digest>)`,
-  the digest covering the brief without its `Approved:` lines. A brief
+  `Approved: <who> <when> — "<the human's words>" (code tree <id>) (brief sha256:<digest>)`,
+  the digest covering the brief without its `Approved:` lines (the tree marker is outside it; a line without one is read as before). A brief
   edited after that reads `brief: not approved (<brief> changed after its
   approval (BRIEF_APPROVAL_STALE))` and names the re-approval
   command: the changed brief needs a new human answer. A line with no

package/dist/skills/reference/role-implementer.md

@@ -107,7 +107,7 @@ canon evidence approval-payload --scenario auth.login.01 --project root --approv
 ```
 ```text
 # Record an external evaluator's re-audit of one scenario (class `audit`; the verdict follows --audit-result; canon never runs the evaluator)
-usage: canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+usage: canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <EVALUATOR_ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer --json
@@ -212,7 +212,7 @@ canon task done add-login#1 --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -306,7 +306,8 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    re-checks them, so the working-tree report may be gitignored. Run
    `canon artifacts verify` to ask the store yourself; it refuses, never
    passes, when an object store cannot be reached. Moving an existing store
-   (`canon artifacts move --tier`) is the repo owner's call: do not run it.
+   (`canon artifacts move --tier`) and deleting the blobs no record binds
+   (`canon artifacts prune`) are the repo owner's call: do not run them.
    For a scenario about what users see, let the test report carry its
    screenshots: Playwright's JUnit reporter attaches, per test case, what a
    test attaches (`testInfo.attach(name, {path})`, or `screenshot: 'on'`), and
@@ -342,7 +343,9 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    latest evidence was recorded on a different `codeTree` than the current
    code (`code.exclude` in `canon.yaml` decides what is not code; the default
    is `docs/**` and `*.md`). A docs-only chore needs its change-level review
-   alone. When code did change, the shipping refusal, `status` and
+   alone, and so does a chore whose approval recorded the code tree that is
+   still the current one (`(code tree <id>)` in its `Approved:` line; `status`
+   says so): it asks for no evidence at all. When code did change, the shipping refusal, `status` and
    `meta.next` lead with one command over every report, with the real paths
    (`--project <id>` is added only with several spec roots):
    `canon evidence add --all-scenarios --report junit:a.xml --report junit:b.xml --role implementer`.

package/dist/skills/reference/role-orchestrator.md

@@ -44,6 +44,14 @@ usage: canon artifacts move --tier <TIER> [--commit --plan-digest <PLAN_DIGEST>]
 canon artifacts move --tier cold --json
 ```
 ```text
+# Delete the artifact blobs no record binds any more (the bare run previews; --commit --plan-digest deletes)
+usage: canon artifacts prune [--keep-days <N>] [--limit <N> | --all] [--cursor <CURSOR>] [--commit --plan-digest <PLAN_DIGEST>] [--input]
+# a bare run previews and prints planDigest; `--commit --plan-digest <PLAN_DIGEST>` with that digest acts
+```
+```bash
+canon artifacts prune --keep-days 30 --json
+```
+```text
 # Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 usage: canon artifacts store [--max-artifact-mib <N>] [--dry-run] [--input]
 ```
@@ -115,7 +123,7 @@ canon demo review --json
 ```
 ```text
 # Mint a Run manifest with retrieved guidance and context/policy lineage
-usage: canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill <ID>] [--skill-digest <DIGEST> (with --skill)] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task <TASK_ID>] [--parent-run <RUN_ID>] [--input]
+usage: canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill <SKILL_ID>] [--skill-digest <DIGEST> (with --skill)] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task <TASK_ID>] [--parent-run <RUN_ID>] [--input]
 ```
 ```bash
 canon dispatch begin --regime implementer/my-repo/api/abcdef012345 --role implementer --json
@@ -206,7 +214,7 @@ canon ingest sessions --json
 ```
 ```text
 # Set up canon in a repo (canon.yaml, a starter policy, the AGENTS.md block, a plans home)
-usage: canon init [--check] [--no-agents-md | --check] [--policy <light|standard|strict> | --check | --no-policy] [--providers <LIST> | --check] [--language <TAG> | --check] [--dry-run | --check] [--input]
+usage: canon init [--check] [--no-agents-md | --check] [--policy <light|standard|strict> | --check | --no-policy] [--harness <claude|codex|omp|pi> | --check | --no-harness]* [--language <TAG> | --check] [--dry-run | --check] [--input]
 ```
 ```bash
 canon init --json
@@ -335,21 +343,21 @@ canon selftest --suite trust-spine-gate --json
 ```
 ```text
 # Check canonical projections without writing; exit 1 on drift, a legacy remnant, or a lock another canon version wrote
-usage: canon skills check [--skills-source <DIR>] [--providers <LIST>]
+usage: canon skills check [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]*
 ```
 ```bash
 canon skills check --json
 ```
 ```text
-# Print diagnostics for canonical projections, the install lock's canon version, legacy remnants, canon projections for a provider that is not selected, and other skills whose description claims build work; reports only, never edits
-usage: canon skills doctor [--skills-source <DIR>] [--providers <LIST>]
+# Print diagnostics for canonical projections, the install lock's canon version, legacy remnants, canon projections for a harness that is not selected, and other skills whose description claims build work; reports only, never edits
+usage: canon skills doctor [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]*
 ```
 ```bash
 canon skills doctor --json
 ```
 ```text
 # Install the canonical `canon` bundle or legacy developer skills
-usage: canon skills install [--skills-source <DIR>] [--providers <LIST>] [--dry-run] [--input]
+usage: canon skills install [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]* [--dry-run] [--input]
 ```
 ```bash
 canon skills install --json
@@ -384,7 +392,7 @@ canon strategy promote 01ARZ3NDEKTSV4RRFFQ69G5FAV --json
 ```
 ```text
 # Disable an active strategy with durable rollback provenance
-usage: canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory <ID>] [--input]
+usage: canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory <TRAJECTORY_ID>] [--input]
 ```
 ```bash
 canon strategy rollback 01ARZ3NDEKTSV4RRFFQ69G5FAV --reason "regressed in production" --actor alice --signature-file approval.sig --approval-at 2030-01-01T00:00:00Z --json
@@ -434,7 +442,7 @@ canon tier age --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -631,7 +639,7 @@ read that changed since is `PLAN_STALE` too, and `meta.next[0]` is the preview
 to run again. A commit holds the repository write lock for its whole run:
 another command that writes waits for it, and one that waited 30 seconds
 answers `REPO_LOCK_UNAVAILABLE` (exit 2, retryable): run it again. A document passed
-with `--input` never carries `--commit` or `--plan-digest`, and these five
+with `--input` never carries `--commit` or `--plan-digest`, and these six
 leaves take one object only (`INPUT_INVALID`).
 
 ```bash
@@ -641,7 +649,9 @@ canon ledger compact
 ```
 
 `canon artifacts move --tier <tier>` moves the local artifact store to an
-object store and removes the local blobs, and `purge` deletes records. They
+object store and removes the local blobs, `canon artifacts prune` deletes the
+blobs no record binds any more (a deleted local blob stays in git history; a
+deleted object of a tier is gone for good), and `purge` deletes records. They
 are the repo owner's decisions, not steps of the loop: run the preview, give
 the human the effects, and run the commit only on their answer. If the repo is
 large, the store is slow or the human has not asked for it, do not run it.

package/dist/skills/reference/role-planner.md

@@ -165,7 +165,7 @@ canon subject unadopt demo --change add-login --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json

package/dist/skills/reference/role-reviewer.md

@@ -87,7 +87,7 @@ canon finding add --change add-login --round 1 --seq 2 --severity should-fix --i
 ```
 ```text
 # Move an already-committed finding's disposition
-usage: canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
+usage: canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon finding close add-login --round 1 --seq 1 --disposition rejected --reason "works as designed" --json
@@ -171,7 +171,7 @@ canon status --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -325,6 +325,9 @@ covered for the ship guard and stays listed as `accepted-divergence` in
   (`FINDING_REASON_REQUIRED`), and `finding list` shows it as
   `[reason: …]` so the next reader sees why it was not fixed. Closing a
   finding that already has that disposition is `unchanged`.
+  Only you close a finding `rejected` or `deferred`: another role is refused
+  (`FINDING_ROLE_DENIED`), so declare `--as reviewer`; the close records
+  that role.
 - Sign off in one batch with `review scenario <ids>`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.

package/man/canon-adapter-authorize.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-authorize 1  "authorize 0.36.0" 
+.TH canon-adapter-authorize 1  "authorize 0.38.0" 
 .SH NAME
 canon\-adapter\-authorize \- Authorize declared capabilities against repository policy (preflight only)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.36.0
+v0.38.0

package/man/canon-adapter-validate.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-validate 1  "validate 0.36.0" 
+.TH canon-adapter-validate 1  "validate 0.38.0" 
 .SH NAME
 canon\-adapter\-validate \- Read and validate one provider\-neutral response envelope
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.36.0
+v0.38.0

package/man/canon-adapter.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter 1  "adapter 0.36.0" 
+.TH canon-adapter 1  "adapter 0.38.0" 
 .SH NAME
 canon\-adapter \- Validate a provider\-neutral adapter response without executing a provider
 .SH SYNOPSIS
@@ -43,4 +43,4 @@ Examples:
   canon adapter validate \-\-response response.json
   canon adapter validate \-\-response response.json \-\-repo . \-\-json
 .SH VERSION
-v0.36.0
+v0.38.0

package/man/canon-artifacts-move.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-move 1  "move 0.36.0" 
+.TH canon-artifacts-move 1  "move 0.38.0" 
 .SH NAME
 canon\-artifacts\-move \- Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH SYNOPSIS
@@ -60,4 +60,4 @@ The bare run previews: it lists every upload and removal and prints a planDigest
 
 Idempotent and resumable: a run stopped anywhere leaves a repo the gate still passes, and the next run finishes; a second run finds nothing to do. A blob whose bytes do not match its name is never moved. Moving back to local is refused; `\-\-tier local` on a local repo is a no\-op.
 .SH VERSION
-v0.36.0
+v0.38.0