@journeykit/canon 0.23.0 → 0.24.1

package/dist/skills/SKILL.src.md

@@ -24,7 +24,7 @@ a feature, a one-line request included. A human is needed once per scope:
   answer until you report: the brief is that report. The one answer
   approves the brief and the policy, `.canon/policy.yaml`, which is what
   the gate grades the work against. Record it only from the human's answer:
-  `canon brief approve --change <slug> --by <the human> --note "<their words>"`.
+  `canon brief approve --change-id <slug> --by <the human> --note "<their words>"`.
   Never edit the policy to make the gate pass: a policy that differs from
   the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
   waivable); stop and ask the human. A brief edited after its
@@ -41,7 +41,7 @@ a feature, a one-line request included. A human is needed once per scope:
   closed `fixed`, and an approved chore, then need the whole suite evidenced
   again (`evidence add --all-scenarios`, for a chore after its approval)
   before it ships, and a chore also needs one change-level review
-  (`review add --change <slug>`).
+  (`review add --change-id <slug>`).
 - When no human can answer one of the brief's questions, write your
   assumption into the brief's Questions and assumptions, build on it, and say
   so in your report. That covers the brief's questions and work inside an
@@ -113,6 +113,10 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   on `error.code`, fix the option `field` names using the `expected` values,
   and follow `error.hint`. Every refusal carries a concrete `hint`: follow
   it. The codes are stable; `canon schema --errors --json` lists them.
+- Flags that name an id are spelled `--<noun>-id` everywhere (`--change-id`,
+  `--project-id`, `--subject-id`, `--scenario-id`, `--actor-id`,
+  `--session-id`), and `--kind` values carry no `_record` suffix
+  (`--kind evidence`).
 - `canon status` sends the planner to write the brief while `brief check`
   has blockers; the human stop appears only when the brief is clean and
   unapproved.

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

@@ -84,7 +84,7 @@ enum, like `lane`.
 ## Subject pinning
 
 Every scenario belongs to a Subject (the durable product unit, see
-`canon-subject`). Write the Subject first, then pin with `--subject`;
+`canon-subject`). Write the Subject first, then pin with `--subject-id`;
 the scenario index carries the tag onto the index record and
 `spec_coverage.scope` filters on it. An unpinned scenario is invisible to
 a scoped gate.
@@ -94,9 +94,9 @@ a scoped gate.
 ```bash
 canon feature new checkout.cart --title "Cart"                       # once per surface
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject checkout-core --lane behavior --case happy               # once per behavior
+  --subject-id checkout-core --lane behavior --case happy               # once per behavior
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
-  --subject checkout-core --lane behavior --case failure             # and its failure path
+  --subject-id checkout-core --lane behavior --case failure             # and its failure path
 ```
 
 There is no format or sync step after these: the scaffold writes a
@@ -108,7 +108,7 @@ one of them prints `NOT refreshed`, the corpus has a format violation
 duplicate id; `canon inventory sync` (or `canon format <root>`) names it.
 Fix it and the next command indexes the files (see `canon-inventory`).
 
-- `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
+- `--actor-id <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
   provenance line. Default is `canon-scaffold`.
 - **Keep the `# canon:` lines when you fill in the scenario.** Dropping one
   makes `canon inventory sync` abort on `missing-provenance`; restore it
@@ -146,7 +146,7 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 - **A Feature title that is a theme.** "Fidelity of the original
   experience" names no surface. Name the screen.
 - **Hand-stamped provenance.** Eighty lines with one timestamp and the
-  same `agent_id`. Use `canon scenario new --actor`.
+  same `agent_id`. Use `canon scenario new --actor-id`.
 - **Coverage by splitting.** One behavior as two scenarios so two rows go
   green. One behavior, one id.
 - **Runner tags as classification.** `@design`, `@p2`, `@wip` are

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

@@ -223,14 +223,17 @@ accepted divergences: 1 known gap(s) — not failing the gate:
 Re-verification is one rule with two triggers: a blocker whose latest
 disposition is `fixed`, and a chore change once approved, keep the subject
 from shipping until every one of its evidenced scenarios has evidence
-recorded after the close or the approval. The refusal names the scenarios
-and the batch command: `canon evidence add --project-id <root-id>
+recorded after the close or the approval. A blocker that names its
+scenarios (`finding add --scenario-id`) asks only those, and the refusal
+names them with the per-scenario command (`canon evidence add --project-id
+<root-id> --scenario-id <id> --report <format>:<path> …`). Otherwise the
+refusal names the scenarios and the batch command: `canon evidence add --project-id <root-id>
 --all-scenarios --report <format>:<path> --kind test-run --role
 implementer --ref "<test command>" …`. Reviews pin what the evidence says
 (its verdict and the identity of its checks), not which record it is, so
 recording the suite again with the same verdicts from the same cases leaves
 every scenario review current. A chore instead needs one change-level
-review of the chore itself (`canon review add --change <slug> …`) before
+review of the chore itself (`canon review add --change-id <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).
 
@@ -295,7 +298,7 @@ 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 with `canon brief approve --change c-demo --by <the human> --note "<their words>"`
+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-id 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
 ```
 
@@ -306,7 +309,7 @@ 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, then record their words with
-`canon brief approve --change c-ext --by <the human> --note "<their words>"` ``. An `Approved:` line in the
+`canon brief approve --change-id 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
@@ -482,8 +485,14 @@ them: `faithful` when every case passed, `divergent` when one failed,
 claims the same verdict for every record instead. A case whose id is not
 indexed is named and skipped (`skipped <id> — not an indexed scenario`);
 a report no indexed scenario owns is refused (exit 2). The records share
-the stored report and every `--artifact`, and the output lists each
-scenario with its verdict on its own line.
+the stored report, and the output lists each scenario with its verdict on
+its own line. Each record binds the attachments its own cases name in the
+report (a JUnit test case's `[[ATTACHMENT|path]]` lines, which Playwright's
+JUnit reporter writes; a Cucumber JSON embedding), so a test's screenshot
+stays with its scenario. A file the report does not name goes with
+`--artifact <scenario-id>=<path>`; a bare `--artifact <path>` in a batch is
+refused (`EVIDENCE_INVALID_ARGUMENT`). A report attachment that is missing,
+outside the repo or oversized is refused.
 
 It is all or nothing: a claimed `faithful` verdict over a failed case,
 a fabrication marker in `--summary`, an unapproved brief for any

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

@@ -179,7 +179,7 @@ record.
 An operator-requested rollback is a distinct authenticated action:
 
 ```bash
-canon learn rollback <strategy_id> --reason "<reason>" --actor alice \
+canon learn rollback <strategy_id> --reason "<reason>" --actor-id alice \
   --signature-file rollback.sig --approved-at 2026-10-02T12:00:00Z \
   [--contradicting-trajectory-id <trajectory_id>] --repo .
 ```

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

@@ -70,11 +70,17 @@ work collapsed into one identity.
 canon finding add --change-id <c> --round <n> --seq <n> \
   --severity blocker|should-fix|note --disposition open \
   --reviewer <who> --summary "<one line>" \
-  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--actor-id <id>] [--session-id <id>]
+  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--scenario-id <id> …] [--actor-id <id>] [--session-id <id>]
 canon finding close --change-id <c> --round <n> --seq <n> \
   --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
 ```
 
+`--scenario-id` (repeatable, each a scenario the index knows; refused with
+`FINDING_UNKNOWN_SCENARIO` otherwise) names the scenarios the finding is
+about. After a `fixed` close, fresh evidence for those scenarios alone
+re-verifies the fix; a finding naming none asks every evidenced scenario of
+the subject, as before. `finding close` copies the list.
+
 Both stage a candidate. Under `write: { promote: auto }` (what
 `canon init` writes) the same run promotes it and the success line names
 the committed record (``wrote kind=finding/… — staged and promoted in this
@@ -142,7 +148,7 @@ canon review add --project-id <root-id> --scenario-id <id> [--scenario-id <id>].
   [--outcome signed|indeterminate|unavailable] \
   [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>] \
   [--artifact <path>]... [--max-artifact-mib <MiB>]
-canon review add --project-id <root> --change <slug> --reviewer <who> --pin <sha-or-ref> \
+canon review add --project-id <root> --change-id <slug> --reviewer <who> --pin <sha-or-ref> \
   --role reviewer (--upstream-ref <ref> | --original-spec-ref <ref>) …   # a chore, below
 ```
 
@@ -169,18 +175,18 @@ that is not a scenario id, refuses the call (exit 2) and writes no review.
 This is also the batch re-pin after `canon evidence add` reports reviews
 it made stale (see `canon-gate`).
 
-### A chore is reviewed as a change (`--change`, 0.23)
+### A chore is reviewed as a change (`--change-id`, 0.23)
 
 A chore adds no scenarios, and recording the suite again after it leaves
 every scenario review current (a review pins the evidence's verdict and
 checks, so the same verdicts from the same cases change nothing). What the
 chore needs instead is one change-level review: the reviewer signs its
-invariants and checks against the diff with `canon review add --change
+invariants and checks against the diff with `canon review add --change-id
 <slug> …`, in place of `--scenario-id`. The review pins the chore's brief
 (its digest, less the `Approved:` line), so an edit to the brief stales it,
 and `--to shipped` refuses a chore with no signed, current change-level
 review (`spec_coverage.require_review.distinct_actor` asks it of a reviewer
-and session that did not attest the subject's evidence). `--change` takes a
+and session that did not attest the subject's evidence). `--change-id` takes a
 chore's slug and refuses a feature change.
 
 ### What the reviewer looked at (artifacts)

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

@@ -115,7 +115,7 @@ file names, tracked in git. `status`, the gate, the guards and `canon query`
 read the ledger only.
 
 ```bash
-canon query --kind evidence_record --history   # every version, archive included
+canon query --kind evidence --history   # every version, archive included
 canon ledger compact --dry-run                 # report; writes nothing
 canon ledger compact                           # pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
 ```

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

@@ -69,12 +69,12 @@ canon subject new subject-domain-loop \
 ### 2. Retrieve subject-scoped strategy memory BEFORE working
 
 ```bash
-canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
+canon retrieve --role dev --domain dev --subject-id subject-domain-loop --k 5
 ```
 
-- `--regime <key>` XOR the derived pair `--domain <d> [--subject <id>]`:
+- `--regime <key>` XOR the derived pair `--domain <d> [--subject-id <id>]`:
   give the full regime key directly, OR let retrieval derive it. Never both.
-- With `--domain`/`--subject`, retrieval tries `<domain>-<subject_id>`
+- With `--domain`/`--subject-id`, retrieval tries `<domain>-<subject_id>`
   first, then `<domain>` — a subject's own lessons win, falling back to
   the domain's shared memory when the subject is new.
 - Fail-soft: an empty/missing store degrades to an empty guidance list,
@@ -82,7 +82,7 @@ canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
 
 ### 3. Work → pin every artifact to `subject_id`
 
-- **Scenarios**: `canon scenario new <tag> --subject <subject-id>` emits
+- **Scenarios**: `canon scenario new <tag> --subject-id <subject-id>` emits
   the `@subject:<subject-id>` tag; the scenario index maps the tag onto
   the scenario's `subject_id` the next time a command reads it (no sync
   step; see `canon-inventory`). A malformed/absent tag leaves it unset
@@ -172,7 +172,7 @@ a policy. The refusal is an `unreviewed-promotion` naming the subject, and
 says what to do:
 
 ```
-canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve --change c-demo --by <the human> --note "<their words>"`
+canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve --change-id c-demo --by <the human> --note "<their words>"`
 canon subject status: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
 ```
 
@@ -181,7 +181,7 @@ For an external change with no canon brief yet, the reason reads
 the external plan <proposal>, which canon reads and never edits, so its
 approval lives in that canon file`` and the agent will ``create
 .canon/changes/<c>/brief.md holding a `Source: <proposal>` line, then
-record their words with `canon brief approve --change <c> --by <the human> --note "<their words>"` ``.
+record their words with `canon brief approve --change-id <c> --by <the human> --note "<their words>"` ``.
 
 Never record the approval without the human's answer. When there is no brief to
 answer (no adopted change, or a newest change with neither a canon
@@ -306,7 +306,7 @@ Planning docs written outside canon become change/task records via
 ```bash
 canon ingest plans --repo .                          # import → change/task rows
 canon subject adopt subject-domain-loop-plan \
-  --subject subject-domain-loop                        # link change → subject
+  --subject-id subject-domain-loop                        # link change → subject
 ```
 
 A change made with `canon change new` (below) is recorded and adopted
@@ -343,7 +343,7 @@ The two records cannot be written atomically, so the subject is written
 first: a half-done adoption still has that change's open blockers
 counted. If the change write then fails, `adopt` exits `2`, names the
 subject that now lists the change, and prints `canon subject adopt
-<change_id> --subject <id>` to complete it.
+<change_id> --subject-id <id>` to complete it.
 
 ### Starting a new change: `canon change new`
 
@@ -351,7 +351,7 @@ For a change that does not exist yet, one command writes it and records
 it adopted:
 
 ```bash
-canon change new add-login --subject auth --title "Add login"
+canon change new add-login --subject-id auth --title "Add login"
 ```
 
 ```
@@ -387,7 +387,7 @@ canon change new: recorded change `add-login` adopted into subject `auth` — wr
   cannot be written atomically. If the change record fails after the
   subject record was written, the command exits `2`, keeps the change
   dir and that one subject record, and prints the repair, `canon ingest
-  plans && canon subject adopt <slug> --subject <id>`, which completes
+  plans && canon subject adopt <slug> --subject-id <id>`, which completes
   the link and is safe to rerun.
 - **Refuses** with exit `2`, writing nothing, when the subject does not
   exist, or when the slug already has a `.canon/changes/<slug>` dir
@@ -411,12 +411,12 @@ it, so the external source keeps the change, its summary and its tasks.
 ### The brief: `canon brief`, `canon brief check`, `canon brief approve`
 
 ```bash
-canon brief [--change <slug>]                 # state and the next one to three steps; never edits
-canon brief check [--change <slug>] [--json]  # findings; exit 0 clean, 2 blockers, 1 error
-canon brief approve --change <slug> --by <the human> --note "<their words>"
+canon brief [--change-id <slug>]                 # state and the next one to three steps; never edits
+canon brief check [--change-id <slug>] [--json]  # findings; exit 0 clean, 2 blockers, 1 error
+canon brief approve --change-id <slug> --by <the human> --note "<their words>"
 ```
 
-Without `--change`, the repo's only live change is read. The brief is the
+Without `--change-id`, the repo's only live change is read. The brief is the
 PRD `canon change new` writes; sections are found by their
 `<!-- canon:section <key> role=… -->` marker, never by heading text. A
 brief without markers (written before 0.19) checks as `brief.legacy`, an
@@ -455,7 +455,7 @@ is the subject's suite run again at the chore commit with
 `canon evidence add --all-scenarios --report <kind>:<path> …`. That
 supersedes the old evidence; the pinned reviews stay current while the
 verdicts and checks are the same, so the chore itself is reviewed once with
-`canon review add --change <slug> …` before it ships. Work that changes
+`canon review add --change-id <slug> …` before it ships. Work that changes
 behavior is a feature change, never a chore.
 
 ## Where are we: `canon status`
@@ -560,7 +560,7 @@ uses, so status and the gate cannot disagree about a gap:
   first, then building, specced, proposed, shipped: an unapproved brief
   (building and later, and proposed once its change has a brief)
   → the human step below, which is then the subject's
-  only step; no scenario → `canon scenario new … --subject <id>` (and, when no
+  only step; no scenario → `canon scenario new … --subject-id <id>` (and, when no
   `.feature` file holds a scenario yet, `canon feature new` first, unless
   every subject waits on its brief); a missing case → `canon scenario new
   <surface>.<next nn> … --case <case>`; (building and later) an
@@ -572,12 +572,12 @@ uses, so status and the gate cannot disagree about a gap:
   Last, unowned scenarios → `canon status`, after tagging them in their
   `.feature` files (status re-indexes the edit; no sync step). With more
   than one `specs.roots[]` entry, every suggested `canon scenario new`
-  carries `--project`: the owning root for a missing case, `<root-id>`
+  carries `--project-id`: the owning root for a missing case, `<root-id>`
   (the reason lists the roots) for a subject that owns no scenario yet.
 - **The one human step.** Every step is the agent's to run except one,
   and it comes only once the brief is clean: while `canon brief check
-  --change <slug>` has blockers, the subject gets the planner step
-  `write the brief: canon brief check --change <slug> lists N blockers`
+  --change-id <slug>` has blockers, the subject gets the planner step
+  `write the brief: canon brief check --change-id <slug> lists N blockers`
   (`role: planner`) instead. A subject whose brief is enforced (its
   newest change's canon
   `brief.md` has no `Approved:` line, or it has no canon `brief.md` yet
@@ -589,10 +589,10 @@ uses, so status and the gate cannot disagree about a gap:
   and the approval is never assumed: `canon evidence add` refuses <id>'s
   scenarios and tasks until it is recorded; once the human answers,
   <record> (one call records the brief and the policy approval)``, where
-  `<record>` is ``record their words with `canon brief approve --change
+  `<record>` is ``record their words with `canon brief approve --change-id
   <c> --by <the human> --note "<their words>"` ``, or, for an external
   change, ``create <brief> holding a `Source: <proposal>` line, then
-  record their words with `canon brief approve --change <c> --by <the
+  record their words with `canon brief approve --change-id <c> --by <the
   human> --note "<their words>"` ``; for a brief edited after its
   approval, ``re-approve with `canon brief approve …` ``.
   It is the subject's only step, whatever its status: nothing suggests
@@ -638,7 +638,7 @@ Status fails closed rather than suggest progress the gate would refuse:
   ],
   "unowned": ["cart.promo.01"],
   "next": [
-    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line, then record their words with `canon brief approve --change c-promo --by <the human> --note \"<their words>\"` (one call records the brief and the policy approval)", "actor": "human" },
+    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line, then record their words with `canon brief approve --change-id c-promo --by <the human> --note \"<their words>\"` (one call records the brief and the policy approval)", "actor": "human" },
     { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it", "actor": "agent" },
     { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …", "actor": "agent" },
     { "command": "canon status", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again: …", "actor": "agent" }

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

@@ -14,8 +14,8 @@ a `specs.roots[]` entry in `canon.yaml` (`root` by default).
 ```bash
 canon status --as implementer --json                  # once, at the start
 canon feature new <area>.<surface> --title "<title>" --as implementer --json
-canon scenario new <area>.<surface>.<nn> --subject <subject-id> --flow <F-id> --case <happy|edge|failure> --title "<title>" --as implementer --json
-canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject","flow","case",…} per line
+canon scenario new <area>.<surface>.<nn> --subject-id <subject-id> --flow <F-id> --case <happy|edge|failure> --title "<title>" --as implementer --json
+canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject-id","flow","case",…} per line
 canon evidence add --project-id <root-id> --all-scenarios --report <junit|cucumber|swift-testing>:<path> --kind test-run --role implementer --ref "<test command>" --actor-id <unit> --session-id <session> --as implementer --json
 canon evidence add --project-id <root-id> --scenario-id <id> --artifact <path> --kind test-run --role implementer --ref "<what it shows>" --actor-id <unit> --session-id <session> --as implementer --json
 canon evidence add --project-id <root-id> --scenario-id <id> --verdict divergent --artifact <path> --kind test-run --role implementer --ref "<the external limit, and where it is tracked>" --actor-id <unit> --session-id <session> --as implementer --json   # honest divergent evidence
@@ -65,10 +65,13 @@ After the first `status`, follow `meta.next` of each write; do not call
    `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 migrate`) is the repo owner's call: do not run it.
-   For a scenario about what users see, bind its own screenshot or recording
-   with that scenario: `--scenario-id <id> --artifact <path>`. A batch
-   (`--all-scenarios`) binds every file it names to every scenario, so give
-   a batch only the reports; never loop all screenshots into it. An external evaluator's audit is
+   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
+   one `evidence add --all-scenarios --report junit:<path>` binds to each
+   record only its own tests' files. A file the report does not name goes
+   with `--artifact <scenario-id>=<path>`; a bare `--artifact` in a batch is
+   refused. An external evaluator's audit is
    `--kind audit`; canon never generates one. Evidence for a task of an
    imported plan (`--task <id>`) must bind the artifact or report that proves
    the task; a canon command is never that proof. When the behavior cannot
@@ -108,6 +111,6 @@ When every scenario has evidence, the review is the reviewer's session, in a
 separate process: do not review your own change. A chore adds no scenarios:
 once it is approved, run the suite and bind it with `--all-scenarios`;
 shipping needs that evidence newer than the chore's approval, plus the
-reviewer's one change-level review of the chore (`review add --change`).
+reviewer's one change-level review of the chore (`review add --change-id`).
 Scenario reviews stay current when the verdicts and checks are unchanged.
 Reference: `reference/canon-gate.md`.

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

@@ -10,7 +10,7 @@ Every line is complete; fill the `<placeholders>`.
 
 ```bash
 canon status --as orchestrator --json --fields next,waitingOn   # at the start and when resuming
-canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as orchestrator --json
+canon brief approve --change-id <slug> --by "<the human>" --note "<their words>" --as orchestrator --json
 canon subject status <subject-id> --to <proposed|specced|building|verifying|shipped> --actor-id <unit> --as orchestrator --json
 canon subject status <subject-id> --to verifying --reason "<why>" --actor-id <unit> --as orchestrator --json   # reopen a shipped subject (--reason is required here; any other transition accepts it as a note)
 canon policy show --as orchestrator --json            # policy digest and its approval: approved, changed, unreadable or unapproved
@@ -82,7 +82,7 @@ change, then `--to shipped` again. A chore on a shipped subject (`change
 new … --kind chore` names the reopen command) is approved first, then
 reopened the same way; shipping again needs the whole suite evidenced after
 the chore's approval (the implementer's `evidence add --all-scenarios`) and
-one change-level review of the chore from the reviewer (`review add --change
+one change-level review of the chore from the reviewer (`review add --change-id
 <slug>`): the order is approval, evidence, review. A blocker closed
 `fixed` needs the suite again. The refusal names the scenarios and
 the command; never override them. `canon status` flags a shipped subject

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

@@ -12,17 +12,17 @@ Every line is complete; fill the `<placeholders>`.
 ```bash
 canon status --as planner --json                      # once, at the start
 canon subject new <subject-id> --domain <domain> --title "<title>" --actor-id <unit> --as planner --json
-canon change new <slug> --subject <subject-id> --title "<title>" --as planner --json
-canon change new <slug> --subject <subject-id> --kind chore --title "<title>" --as planner --json
-canon subject adopt <slug> --subject <other-subject-id> --as planner --json
-canon brief check --change <slug> --as planner --json
-canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as planner --json
+canon change new <slug> --subject-id <subject-id> --title "<title>" --as planner --json
+canon change new <slug> --subject-id <subject-id> --kind chore --title "<title>" --as planner --json
+canon subject adopt <slug> --subject-id <other-subject-id> --as planner --json
+canon brief check --change-id <slug> --as planner --json
+canon brief approve --change-id <slug> --by "<the human>" --note "<their words>" --as planner --json
 ```
 
 After the first `status`, follow `meta.next` of each write. `brief check`
 lists blockers and advisories; bare `canon brief --as planner` names the next
 steps. While the brief has blockers, `status` and `change new`'s `meta.next`
-send you to write it (`write the brief: canon brief check --change <slug>
+send you to write it (`write the brief: canon brief check --change-id <slug>
 lists N blockers`); the human step appears only once the brief is clean and
 unapproved. A policy that no longer matches its approval fails closed
 (`POLICY_CHANGED_SINCE_APPROVAL`): never edit it; the human re-approves.
@@ -80,7 +80,7 @@ category, invariants, checks, out of scope) and approved like any brief, one
 human stop. A chore adds no scenarios: the
 implementer runs the subject's suite again and binds it with
 `canon evidence add --all-scenarios …`, then the reviewer records one
-change-level review of the chore (`canon review add --change <slug>`). On a
+change-level review of the chore (`canon review add --change-id <slug>`). On a
 shipped subject `change new` prints the reopen command for the orchestrator
 (`subject status <id> --to verifying --reason "<why>"`); the subject cannot
 ship again until the suite is evidenced after the chore's approval. Work that

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

@@ -10,17 +10,17 @@ Every line is complete; fill the `<placeholders>`. `<root-id>` is the `id` of
 a `specs.roots[]` entry in `canon.yaml` (`root` by default).
 
 ```bash
-canon brief check --change <slug> --as reviewer --json
+canon brief check --change-id <slug> --as reviewer --json
 canon gate check --as reviewer --json                 # once, before review add
-canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --as reviewer --json
+canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --scenario-id <id> --scenario-id <id> --as reviewer --json   # one --scenario-id per scenario the defect is about
 canon finding list --change-id <slug> --open --as reviewer --json
 canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha> --as reviewer --json
 canon review add --project-id <root-id> --scenario-id <id> --scenario-id <id> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json
 canon review add --project-id <root-id> --scenario-ids-from - --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # ids on stdin, one per line
-canon review add --project-id <root-id> --change <chore-slug> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # a chore: one change-level review of its invariants and checks against the diff
+canon review add --project-id <root-id> --change-id <chore-slug> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # a chore: one change-level review of its invariants and checks against the diff
 canon divergence accept --project-id <root-id> --scenario-id <id> --reason "<why the gap stays>" --tracking <issue-url-or-ref> [--expiry YYYY-MM-DD] --reviewer <me> --actor-id <me> --session-id <session> --as reviewer --json
 canon artifacts verify --full --as reviewer --json    # the files the evidence and reviews bind are in the artifact store; refuses when an object store is unreachable
-canon query --kind evidence_record --history --as reviewer --json   # every version, not only the current record
+canon query --kind evidence --history --as reviewer --json   # every version, not only the current record
 ```
 
 `review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
@@ -97,14 +97,18 @@ ship guard and stays listed as `accepted-divergence` in `status` and
 - Sign off in one batch with `review add`, all or nothing. It writes
   directly; nothing to promote. canon stores and re-checks attached bytes
   and never compares images.
-- A blocker you close `fixed` stays blocking until the implementer records
-  the whole suite again (`evidence add --all-scenarios`); your pinned review
+- Pass `--scenario-id` for each scenario a finding is about. A blocker you
+  close `fixed` then stays blocking until the implementer records evidence
+  again for those scenarios alone (`evidence add --scenario-id <id> …`); the
+  close inherits the list. A blocker naming no scenario asks for the whole
+  suite again (`evidence add --all-scenarios`), which on a big suite is
+  a long e2e run for a one-scenario fix, so name them. Your pinned review
   stays current when the new evidence says the same, otherwise look again.
 - Fixes you ask for return as a re-review of the same change. When new
   evidence changes a verdict or the checks and so stales your review, look
   again before you re-pin.
   A chore has no scenarios: review it with one change-level review, `canon
-  review add --project-id <root-id> --change <slug> --reviewer <me> --role
+  review add --project-id <root-id> --change-id <slug> --reviewer <me> --role
   reviewer --pin <sha> --upstream-ref <ref> …`. It signs the chore's
   invariants and checks against the diff and pins its brief, so editing the
   brief stales it. The chore also needs evidence recorded after its approval

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.23.0",
-    "@journeykit/canon-core-linux-x64": "0.23.0",
-    "@journeykit/canon-core-win32-x64": "0.23.0"
+    "@journeykit/canon-core-darwin-arm64": "0.24.1",
+    "@journeykit/canon-core-linux-x64": "0.24.1",
+    "@journeykit/canon-core-win32-x64": "0.24.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",