@journeykit/canon 0.18.0 → 0.21.0

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

@@ -142,7 +142,7 @@ A present section, even `require_evidence: false` or a malformed one
   case). This is the gap evidence presence cannot see: every scenario
   attested, none of them specifying a refusal. Untagged scenarios satisfy
   no case, so an unclassified corpus is reported, not passed. Works with
-  `require_evidence: false` too. `canon subject status <id> shipped`
+  `require_evidence: false` too. `canon subject status <id> --to shipped`
   applies the same rule to the scenarios the subject owns.
 - **Independent review** (`require_review`) — scenarios whose subject is
   in `require_review.scope` (default `[verifying, shipped]`; `[]` = every
@@ -228,25 +228,38 @@ canon evidence add --kind audit --project-id root --scenario-id cart.add.01 \
 - Audits fold apart: per `(project_id, scenario_id)` there is a latest
   declared record and a latest audit. An audit never becomes the
   scenario's latest declared verdict.
-- `canon subject status <id> shipped` refuses `false-success`, and an
+- `canon subject status <id> --to shipped` refuses `false-success`, and an
   owed sampled audit when `require_audit.scope` covers `shipped`.
 - `canon status` shows an `audits` section (sampled / confirmed / owed /
   refuted) and suggests `canon evidence add --kind audit …` in `next:`.
 
-### Dropping a binding (`--drop-attachment`)
-
-`canon evidence add` for a scenario refuses (exit `2`) when the
-scenario's current latest record of the same fold (declared records, or
-audit records for an audit) — committed ledger plus `_staging` — binds
-files the new record does not. The refusal names the paths and two ways
-out: re-bind them (`--artifact`/`--report`; new bytes at the same path
-are fine), or drop them on purpose with `--drop-attachment <path>`
-(repeatable) and one single-line `--drop-reason <text>`. The drop is
-recorded as `attachment_drop: {paths, reason}`. Refused (`2`): a drop
-without a reason, a reason without a drop, a drop path that is not
-actually dropped, a multi-line reason, or a drop without
-`--scenario-id` (task-only evidence has no drop guard). `canon status`
-lists recorded drops (`dropped bindings (N):`; `drops[]` in `--json`).
+### Carrying and dropping bindings (`--drop-attachment`)
+
+`canon evidence add` for a scenario carries forward what the scenario's
+current latest record of the same fold (declared records, or audit
+records for an audit; committed ledger plus `_staging`) bound: every
+file the new write does not name again is bound into the new record
+unchanged (same path, digest and stored blob), and `--json` lists it as
+`carried: [paths]`. A file named again (`--artifact`/`--report`, new
+bytes at the same path included) replaces its earlier binding. A suite
+batch (`--all-scenarios`) therefore never costs a scenario its
+screenshots. A carried file whose blob the artifact store does not
+hold intact is refused (exit `2`, `EVIDENCE_CARRY_BLOB_MISSING`, nothing
+written): re-bind it, run `canon evidence vault`, or drop it. The audit
+fold (`--kind audit`) does not carry: an audit that leaves out a file
+the latest audit bound is refused (exit `2`) unless it names the file
+again or drops it with `--drop-attachment`, so a counterexample never
+rides along into a confirming audit.
+
+The only way to lose a binding is `--drop-attachment <path>`
+(repeatable) with one single-line `--drop-reason <text>`, recorded as
+`attachment_drop: {paths, reason}`. With `--all-scenarios` the drop
+applies to each scenario that binds the path. Refused (`2`): a drop
+without a reason, a reason without a drop, a drop path that no
+scenario of the write leaves out, a multi-line reason, or a drop
+without `--scenario-id`/`--all-scenarios` (task-only evidence has no
+carry or drop). `canon status` lists recorded drops (`dropped bindings
+(N):`; `drops[]` in `--json`).
 
 ### Nothing is attested before the brief is approved (`--override-reason`)
 
@@ -256,7 +269,8 @@ reports it, and builds nothing for that scope until the human answers.
 refuses (exit `1`, nothing staged or stored) while a subject the record
 attests for has an enforced, unapproved brief: the newest adopted
 change's canon `.canon/changes/<change>/brief.md` has no `Approved:`
-line, or there is no canon `brief.md` yet but the change comes from an
+line, was edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`), or
+there is no canon `brief.md` yet but the change comes from an
 external openspec plan with a `proposal.md` under the plan sources (the
 check `canon status` and the ship guard use; see
 `canon-subject`). The subjects are the scenario's `@subject` owner for
@@ -264,8 +278,8 @@ check `canon status` and the ship guard use; see
 `--task`:
 
 ```
-canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
-canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that brief.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve --change c-demo --by <the human> --note "<their words>"`
+canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their answer with `canon brief approve --by <the human> --note "<their words>"` only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
 ```
 
 For a change from an external plan with no canon brief yet, the first
@@ -274,8 +288,8 @@ change `c-ext` comes from the external plan
 openspec/changes/c-ext/proposal.md, which canon reads and never edits, so
 its approval lives in that canon file, so the human has not answered it;
 once they do, create .canon/changes/c-ext/brief.md holding a `Source:
-openspec/changes/c-ext/proposal.md` line and record their words there as
-`Approved: <who> <when> — "<their words>"` ``. An `Approved:` line in the
+openspec/changes/c-ext/proposal.md` line, then record their words with
+`canon brief approve --change c-ext --by <the human> --note "<their words>"` ``. An `Approved:` line in the
 external `proposal.md` itself is never read.
 
 A subject with no brief to answer (no adopted change, or a newest change
@@ -305,7 +319,7 @@ brief overrides: 1 evidence record(s) attested before their brief was approved
 
 ### Review-waiver advisories
 
-A subject moved into a review-scoped status with `canon subject status
+A subject moved into a review-scoped status with `canon subject status <id> --to <state>
 --override-reason` (see `canon-subject`) keeps the `unreviewed-promotion`
 and `open-blocker` gaps its waiver recorded visible without failing the
 gate. Only those exact `(class, subject)` pairs are waived; a gap that
@@ -319,15 +333,18 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 The waiver lasts only until the subject's next status write.
 
-`canon subject status <id> shipped` also refuses where a brief exists and
-has no `Approved:` line (the subject's newest adopted change has a canon
-`brief.md`, or an external `proposal.md` and no canon `brief.md` yet;
+`canon subject status <id> --to shipped` also refuses where a brief exists and
+is not approved (the subject's newest adopted change has a canon
+`brief.md` with no `Approved:` line or one the brief's text no longer
+matches, or an external `proposal.md` and no canon `brief.md` yet;
 see `canon-subject`), as an `unreviewed-promotion` naming
-the subject. With no brief to answer it prints an advisory and does not
-refuse. Like the evidence refusal above, it is a backstop: the stop is at
-the brief. `canon gate check` does not grade briefs, so a waived ship
-brief prints no advisory here; `canon status` keeps showing the brief as
-not approved.
+the subject, and while `canon brief check` has structure blockers or a
+flow step has no scenario or no failure scenario (the coverage rules gate
+shipping, never approval). With no brief to answer it prints an advisory
+and does not refuse. Like the evidence refusal above, it is a backstop:
+the stop is at the brief. `canon gate check` does not grade briefs, so a
+waived ship brief prints no advisory here; `canon status` keeps showing
+the brief as not approved.
 
 ### Reviews that predate pinning (checked against their pin)
 
@@ -461,11 +478,12 @@ scenario with its verdict on its own line.
 
 It is all or nothing: a claimed `faithful` verdict over a failed case,
 a fabrication marker in `--summary`, an unapproved brief for any
-scenario's subject, or a scenario whose latest record binds a file the
-batch does not refuses the whole batch, and nothing is written.
-`--scenario-id`, `--task`, `--report-case`, `--kind audit`,
-`--drop-attachment` and the approval flags name one subject and are
-refused with `--all-scenarios`.
+scenario's subject, or a carried attachment whose blob is missing from the
+store refuses the whole batch, and nothing is written. Each scenario's
+earlier attachments are carried into its new record (see above), and
+`--drop-attachment` applies per scenario. `--scenario-id`, `--task`,
+`--report-case`, `--kind audit` and the approval flags name one subject
+and are refused with `--all-scenarios`.
 
 A task's evidence with `--report` and no `--scenario-id` binds EVERY case
 in the report, so a `faithful` verdict needs all of them to pass.
@@ -580,6 +598,11 @@ empty clean map.
 
 ## `canon gate task <task_id> [--repo <dir>]`
 
+For imported external plans, and for a `tasks.md` that already exists in
+a canon change. `canon change new` writes no `tasks.md` (0.19), and
+nothing gates on one: a canon-owned change is covered by its flow steps'
+scenarios (`canon status`).
+
 The evidence-gated task checkbox flip. Resolves `<task_id>`
 (`<change_id>#<n>`) through `.canon/changes/` (canon's own changes, read
 first whenever the directory exists, with no `plans:` entry) and then
@@ -661,7 +684,7 @@ promote`, so no separate
 staged. A record another run staged is not touched: only `gate promote`
 commits everything staged. It stays safe to run anyway: with nothing
 staged it prints
-`nothing staged` and exits `0`. `divergence stage` stages for `canon
+`nothing staged` and exits `0`. `divergence add` stages for `canon
 divergence promote` and names it, under the same `write:` rule. Every
 other write — `review add`, `divergence
 resolve|defer`, `subject new|adopt|status`, `change new`, `scenario new`, `feature new`,

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

@@ -72,7 +72,7 @@ scenario index                  # refreshed by every reader; `canon inventory sy
         │
         ▼
 canon review add                # attests a review — see canon-inventory downstream / canon-gate
-canon divergence {stage,promote,resolve,defer,status}   # tracks/resolves a divergence
+canon divergence {add,promote,resolve,defer,status}   # tracks/resolves a divergence
 canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
         │
         ▼
@@ -158,7 +158,7 @@ specs:
 
 - **Review** — `canon review add` attests a verdict against a synced
   scenario. (See `canon-inventory` downstream commands and each command's `--help`.)
-- **Divergence** — `canon divergence {stage,promote,resolve,defer,status}`
+- **Divergence** — `canon divergence {add,promote,resolve,defer,status}`
   tracks/resolves divergences against synced scenarios.
 - **Gate** — `canon gate check` enforces trust-ladder / staleness /
   coverage over the corpus (see `canon-gate`).

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

@@ -46,15 +46,13 @@ The production activation path is a signed, paired-evaluation workflow:
    ```bash
    canon learn approve <strategy_id> --evaluation evaluation.json \
      --principal alice --repo .
-   # `request` is an exact alias:
-   canon learn request <strategy_id> --evaluation evaluation.json \
-     --principal alice --repo .
    ```
 
-   The JSON output contains the evaluation digest, RFC3339 `approved_at`,
+   With `--json` the payload is `.data` of the `{ "data", "meta" }` envelope, and
+   `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`. `approve`/`request` never
-   read a private key and never set `verified`.
+   `canon-learning-approval-v1`, and `payload_hex`. `approve` never
+   reads a private key and never sets `verified`.
 6. Decode `payload_hex` to the exact canonical JSON bytes. The signed object
    is:
 

package/dist/skills/reference/canon-plan-import.md

@@ -10,8 +10,9 @@ one, and neither can `canon gate`.
 ## 1. Canon's own changes and external `plans:` sources
 
 `.canon/changes/` is canon's native plan source (dialect id `canon`):
-one `<slug>/` directory per change holding `brief.md` and `tasks.md`,
-written by `canon change new` (see `canon-subject`). Every plan reader —
+one `<slug>/` directory per change holding `brief.md` (and a `tasks.md`
+only when someone adds one: an optional work note), written by
+`canon change new` (see `canon-subject`). Every plan reader —
 `canon ingest plans`, `canon gate task`, `canon evidence add --task`,
 `canon dispatch --task`, `canon status` and the brief check — reads it
 first whenever the directory exists, with no `plans:` entry. Being first,
@@ -21,7 +22,8 @@ Its records carry the actor `canon-plan-import-canon`; an external
 openspec change's carry `canon-plan-import-openspec`. A `brief.md` with a
 `Source: <path>` line is not a change of its own: it is the canon brief
 of a change imported from an external plan (it points at the external
-document and holds the human's `Approved:` line), so the native reader
+document and holds the human's `Approved:` line, written by
+`canon brief approve`), so the native reader
 skips that directory and the external source keeps the change id.
 
 `plans.sources` lists only EXTERNAL plans — documents you prepare outside
@@ -89,12 +91,13 @@ No dialect/plugin filter exists or is needed — an imported `change`/
 ## The `canon` dialect (`.canon/changes/`)
 
 Uses the `openspec` change-dir grammar below, with three differences:
-the brief is `brief.md` (its `## Why` first paragraph is the summary; a
+the brief is `brief.md` (the first paragraph of its intent section, or of
+`## Why` in a pre-0.19 brief, is the summary; a
 missing one is a `missing-brief-md` malformed dir), the source root is
 always `.canon/changes/` itself (archived changes under
 `.canon/changes/archive/`), and a `brief.md` carrying a `Source:` line is
-skipped (a pointer brief, above). `tasks.md` uses the same checkbox row
-grammar.
+skipped (a pointer brief, above). An existing `tasks.md` uses the same
+checkbox row grammar; a change with none imports with zero tasks.
 
 ## The `openspec` dialect
 
@@ -175,7 +178,7 @@ downstream reader's job.
 ## What this skill does NOT cover
 
 - **Authoring a change** — `canon change new` writes
-  `.canon/changes/<slug>/brief.md` and `tasks.md` and adopts the change
+  `.canon/changes/<slug>/brief.md` (no `tasks.md`) and adopts the change
   into a subject (see `canon-subject`); it never scaffolds an openspec
   change dir. This skill covers IMPORTING plans.
 - **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-

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

@@ -74,8 +74,10 @@ canon policy approve --by <who> [--note <text>] [--repo <dir>]
 
 A human approves the policy after reviewing `.canon/policy.yaml`, in the
 same answer that approves a subject's brief (0.16; see the skill's working
-loop). The human runs this, or the agent runs it right after that answer
-as `canon policy approve --by <the human> --note "<their words>"`. It
+loop). `canon brief approve` records both in one call, so the agent does
+not run this command next to it. Run `canon policy approve` alone for a
+policy-only change, as the human, or as the agent right after that answer
+(`canon policy approve --by <the human> --note "<their words>"`). It
 writes `.canon/policy.approval.json` directly (nothing to promote):
 
 ```json
@@ -227,7 +229,7 @@ read as a big-endian u64, are less than `rate · 2^64` — computed exactly,
 as a comparison against `ceil(rate · 2^64)`, so `rate: 0` samples nothing
 and `rate: 1` samples everything. A sampled in-scope scenario whose
 latest audit is missing or `indeterminate` is `uncovered-cell`; with
-`shipped` in `scope`, `canon subject status <id> shipped` also refuses
+`shipped` in `scope`, `canon subject status <id> --to shipped` also refuses
 it. `canon context` and the `canon status` policy line show
 `require_audit=(rate=… seed=`…` scope=…)`.
 

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

@@ -55,7 +55,7 @@ The order an agent follows to claim a subject done:
    the screenshots or recordings it looked at with `--artifact <path>`
    (below).
 
-4. **Move the subject**: `canon subject status <id> verifying`, later
+4. **Move the subject**: `canon subject status <id> --to verifying`, later
    `shipped`. See `canon-subject`.
 
 ## `canon finding add` / `canon finding close`
@@ -413,7 +413,7 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 ## The status guard
 
-With `require_review` present, `canon subject status <id> <state>`
+With `require_review` present, `canon subject status <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
 ```

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

@@ -98,6 +98,11 @@ canon query --kind handoff --since 2026-06-01T00:00:00Z
 
 # Machine-readable output instead of the human table.
 canon query --kind trajectory --json
+
+# Page a long result and keep only the fields you need; `meta` carries
+# returned, total, hasMore and nextCursor (`--all` returns everything).
+canon query --kind trajectory --json --limit 50 --fields at,kind
+canon query --kind trajectory --json --limit 50 --cursor <nextCursor>
 ```
 
 ## What `canon report` does and doesn't read
@@ -120,8 +125,11 @@ section listing them and emits a matching stderr `WARN`.
 
 ## Retention, export, and access audit
 
-`canon purge --kind <kind> --before <RFC3339> [--repo <dir>] [--dry-run] [--json]`
-is the canonical data-lifecycle boundary. The only purgeable kinds are
+`canon purge --kind <kind> --before <RFC3339> (--plan | --confirm <planDigest>) [--repo <dir>] [--json]`
+is the canonical data-lifecycle boundary: `--plan` prints the removal set and
+its `planDigest` and deletes nothing; `--confirm <planDigest>` deletes only if
+the plan recomputed now has the same digest (`PLAN_CHANGED`, exit 2, when the
+data moved), and a bare `purge` is refused (`PURGE_PLAN_REQUIRED`). The only purgeable kinds are
 `session`, `run`, `event`, and `trajectory`; the cutoff applies to every
 routed rung and every configured aging destination, including retained
 historical versions. For `trajectory`, the command also purges the
@@ -134,8 +142,14 @@ an explicit `partial` result with matched/deleted counts and a nonzero
 status. Purge never rewrites Git history or deletes source transcript
 files.
 
+With `--json`, `purge` and `export` answer `{ "data", "meta" }` like every other
+command: `data` is the plan or manifest, `meta.next` the step after (a plan's is the
+human's review and `--confirm`), and an export's page state (`total`, `returned`,
+`nextCursor`) sits in `meta`. `export --json --out <file>` writes the manifest to the
+file and answers with `data: { out, kind, recordCount }`.
+
 `canon export --kind <kind> [--before <RFC3339>] [--after <RFC3339>]
-[--out <file>] [--json]` emits a versioned manifest containing source scope,
+[--out <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
 `0600`. Raw event detail text is excluded unless `--include-sensitive` is
@@ -161,7 +175,7 @@ record bodies.
 Four writes stage their record instead of committing it: `canon evidence
 add`, `canon finding add` and `canon finding close` (under
 `.canon/ledger/_staging/`, committed by `canon gate promote`) and `canon
-divergence stage` (committed by `canon divergence promote`). `canon.yaml`'s
+divergence add` (committed by `canon divergence promote`). `canon.yaml`'s
 `write:` section decides whether they promote in the same run:
 
 ```yaml