@journeykit/canon 0.37.0 → 0.38.0

package/dist/skills/SKILL.src.md

@@ -160,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
 
@@ -215,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
@@ -316,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
@@ -353,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
 ```
 
@@ -372,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

@@ -266,6 +266,32 @@ 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
@@ -599,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-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
@@ -448,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`
@@ -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/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

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

@@ -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.37.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.37.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.37.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.37.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.37.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.37.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.37.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.37.0
+v0.38.0

package/man/canon-artifacts-prune.1

@@ -0,0 +1,75 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-artifacts-prune 1  "prune 0.38.0" 
+.SH NAME
+canon\-artifacts\-prune \- Delete the artifact blobs no record binds any more (the bare run previews; \-\-commit \-\-plan\-digest deletes)
+.SH SYNOPSIS
+\fBcanon artifacts prune\fR [\fB\-\-as\fR] [\fB\-\-keep\-days\fR] [\fB\-\-limit\fR] [\fB\-\-cursor\fR] [\fB\-\-all\fR] [\fB\-\-commit\fR] [\fB\-\-plan\-digest\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Delete the artifact blobs no record binds any more (the bare run previews; \-\-commit \-\-plan\-digest deletes)
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` is this role unless given
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-keep\-days\fR \fI<N>\fR
+Also keep the blobs that evidence and reviews written in the last N days bind
+.TP
+\fB\-\-limit\fR \fI<N>\fR [default: 100]
+Return at most this many records per page
+.TP
+\fB\-\-cursor\fR \fI<CURSOR>\fR
+Resume after the last record of the previous page (the `nextCursor` it reported)
+.TP
+\fB\-\-all\fR
+Return every record from the cursor on, not one page
+.TP
+\fB\-\-commit\fR
+Make the change; without it the command only previews.
+.TP
+\fB\-\-plan\-digest\fR \fI<PLAN_DIGEST>\fR
+The digest of the preview this commit carries out.
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH EXTRA
+Examples:
+  canon artifacts prune
+  canon artifacts prune \-\-keep\-days 30
+  canon artifacts prune \-\-commit \-\-plan\-digest <PLAN_DIGEST>
+
+The store only grows: a report written anew on every run adds a blob per run. A blob stays while a record binds it: the latest evidence of a task or of a scenario and the reviews still in effect (what `canon gate check` and `canon artifacts verify` read), a record not promoted yet, and, with \-\-keep\-days N, any evidence or review written in the last N days. Every other blob of the configured store is deleted: the local directory .canon/artifacts/sha256, or the objects of the object\-store tier `artifact_store:` names (the same rule; a copy left in the local directory of such a repo is judged by it too).
+
+The bare run previews: it says how many blobs and bytes go and stay, why each kept blob stays, lists the blobs to delete a page at a time (\-\-limit, \-\-cursor, \-\-all; the totals are the whole\*(Aqs) and writes nothing. With nothing to delete it says so and offers no \-\-commit. \-\-commit \-\-plan\-digest deletes exactly that plan (PLAN_STALE, exit 2, nothing deleted, when evidence or a record changed since). A repo whose records or staging cannot be read in full is refused: a blob is never deleted on a guess. After a prune, `canon artifacts verify` and `canon gate check` answer as before.
+
+A deleted local blob leaves the working tree, so commit the removal with the ledger; it stays in git history, and shrinking that history is the repo owner\*(Aqs call, not this command\*(Aqs. A deleted object of a tier cannot be undone: the tier keeps no other copy. A delete that fails stops the run (ARTIFACTS_PRUNE_INCOMPLETE says what was deleted); a new preview lists what remains.
+
+Exit 0 for a preview or a commit, 1 when a delete failed, 2 when the plan is stale or the records or the store cannot be read.
+.SH VERSION
+v0.38.0

package/man/canon-artifacts-store.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-store 1  "store 0.37.0" 
+.TH canon-artifacts-store 1  "store 0.38.0" 
 .SH NAME
 canon\-artifacts\-store \- Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 .SH SYNOPSIS
@@ -51,4 +51,4 @@ For records written before canon stored bound bytes (0.11\-0.13), and for any ev
 
 Exit 0 when the pass ran (the gate decides whether an unstored file matters), 2 when the ledger cannot be read or a write fails.
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-artifacts-verify.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-verify 1  "verify 0.37.0" 
+.TH canon-artifacts-verify 1  "verify 0.38.0" 
 .SH NAME
 canon\-artifacts\-verify \- Check that the artifact store holds every file the latest evidence and current reviews bind (\-\-full re\-hashes the stored bytes)
 .SH SYNOPSIS
@@ -45,4 +45,4 @@ Asks the store canon.yaml\*(Aqs `artifacts:` block selects (default: local, .can
 
 Exit 0 when every file is stored, 1 when one is missing or altered (data.problems names each), 2 when the store cannot be used or reached: an unreachable store is a refusal, never a pass.
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-artifacts.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts 1  "artifacts 0.37.0" 
+.TH canon-artifacts 1  "artifacts 0.38.0" 
 .SH NAME
 canon\-artifacts \- Check or move the evidence artifact store (local, or an object\-store tier)
 .SH SYNOPSIS
@@ -41,5 +41,8 @@ Store the bound files of existing evidence records and current reviews in the ar
 .TP
 canon\-artifacts\-move(1)
 Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
+.TP
+canon\-artifacts\-prune(1)
+Delete the artifact blobs no record binds any more (the bare run previews; \-\-commit \-\-plan\-digest deletes)
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-brief-approve.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-approve 1  "approve 0.37.0" 
+.TH canon-brief-approve 1  "approve 0.38.0" 
 .SH NAME
 canon\-brief\-approve \- Record the human\*(Aqs approval of the brief, bound to its text; refused while `brief check` has blockers
 .SH SYNOPSIS
@@ -74,4 +74,4 @@ chore whose approval saw the code tree that is still the current one asks for no
 not approved (BRIEF_APPROVAL_STALE) until a human answers again and this
 runs again. Run it only from the human\*(Aqs answer, with their words as \-\-note.
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-brief-check.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-check 1  "check 0.37.0" 
+.TH canon-brief-check 1  "check 0.38.0" 
 .SH NAME
 canon\-brief\-check \- Read the brief against the rules: blocker and advisory findings (exit 0 clean, 1 blockers, 2 refused)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 [\fICHANGE_ID\fR]
 The change to read (default: the repo\*(Aqs only live change)
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-brief-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-show 1  "show 0.37.0" 
+.TH canon-brief-show 1  "show 0.38.0" 
 .SH NAME
 canon\-brief\-show \- Show where the change stands and the next one to three steps; never edits
 .SH SYNOPSIS
@@ -50,4 +50,4 @@ Examples:
 
 The operand names the change; without it the repo\*(Aqs only live change is read.
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-brief.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief 1  "brief 0.37.0" 
+.TH canon-brief 1  "brief 0.38.0" 
 .SH NAME
 canon\-brief \- Check a change\*(Aqs brief (PRD format) and see the next steps; never edits
 .SH SYNOPSIS
@@ -61,4 +61,4 @@ gets one blocker, `brief.old\-format`: `canon migrate` rewrites it. A brief
 with fewer than two known headings (written before 0.19) checks as `brief.legacy`, an
 advisory. Without \-\-change, the repo\*(Aqs only live change is checked.
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-change-new.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change-new 1  "new 0.37.0" 
+.TH canon-change-new 1  "new 0.38.0" 
 .SH NAME
 canon\-change\-new \- Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 .SH SYNOPSIS
@@ -63,4 +63,4 @@ Print version
 <\fICHANGE_ID\fR>
 The change\*(Aqs slug (its change_id)
 .SH VERSION
-v0.37.0
+v0.38.0

package/man/canon-change.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change 1  "change 0.37.0" 
+.TH canon-change 1  "change 0.38.0" 
 .SH NAME
 canon\-change \- Write a plan change (.canon/changes/<slug>/brief.md) and adopt it into a subject
 .SH SYNOPSIS
@@ -39,4 +39,4 @@ Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 Examples:
   canon change new add\-login \-\-subject auth \-\-title \*(AqAdd login\*(Aq
 .SH VERSION
-v0.37.0
+v0.38.0