@journeykit/canon 0.27.0 → 0.28.0

package/man/canon-divergence-defer.1

@@ -0,0 +1,71 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence-defer 1  "defer 0.28.0" 
+.SH NAME
+canon\-divergence\-defer \- Directly record a deferred divergence (requires \-\-reason/\-\-expiry)
+.SH SYNOPSIS
+\fBcanon divergence defer\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] [\fB\-\-rev\fR] [\fB\-\-round\fR] <\fB\-\-actor\-id\fR> [\fB\-\-session\-id\fR] <\fB\-\-reason\fR> <\fB\-\-expiry\fR> [\fB\-\-role\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISCENARIO_ID\fR> 
+.SH DESCRIPTION
+Directly record a deferred divergence (requires \-\-reason/\-\-expiry)
+.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` defaults to it
+.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\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id of the scenario. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-round\fR \fI<N>\fR [default: 1]
+The review round this version belongs to (1\-based)
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer recording this (recorded as the divergence\*(Aqs reviewer and actor)
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The acting session (recorded as actor.session_id); optional
+.TP
+\fB\-\-reason\fR \fI<TEXT>\fR
+Why the divergence is deferred
+.TP
+\fB\-\-expiry\fR \fI<TIMESTAMP>\fR
+When the deferral lapses (RFC3339 or YYYY\-MM\-DD, UTC)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The role this record is attributed to (default: the role declared with \-\-as / CANON_ROLE)
+.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
+.TP
+<\fISCENARIO_ID\fR>
+The scenario (`<area>.<surface>.<nn>`)
+.SH VERSION
+v0.28.0

package/man/canon-divergence-list.1

@@ -0,0 +1,56 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence-list 1  "list 0.28.0" 
+.SH NAME
+canon\-divergence\-list \- List the current divergence burn\-down state
+.SH SYNOPSIS
+\fBcanon divergence list\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-as\-of\fR] [\fB\-\-json\fR] [\fB\-\-limit\fR] [\fB\-\-cursor\fR] [\fB\-\-all\fR] [\fB\-\-fields\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+List the current divergence burn\-down state
+.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` defaults to it
+.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\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-as\-of\fR \fI<TIMESTAMP>\fR
+Governs Deferred expiry; defaults to now
+.TP
+\fB\-\-json\fR
+Print `{data, meta}` as JSON
+.TP
+\fB\-\-limit\fR \fI<N>\fR
+Return at most this many records (default 100)
+.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\-\-fields\fR \fI<FIELDS>\fR
+With \-\-json, keep only these scenario fields (comma\-separated): project_id, scenario_id, state, reason, expiry, tracking; an unknown field is refused (camelCase and snake_case both match)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-divergence-resolve.1

@@ -0,0 +1,68 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence-resolve 1  "resolve 0.28.0" 
+.SH NAME
+canon\-divergence\-resolve \- Directly record a resolved divergence
+.SH SYNOPSIS
+\fBcanon divergence resolve\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] [\fB\-\-rev\fR] [\fB\-\-round\fR] <\fB\-\-actor\-id\fR> [\fB\-\-session\-id\fR] [\fB\-\-detail\fR] [\fB\-\-role\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISCENARIO_ID\fR> 
+.SH DESCRIPTION
+Directly record a resolved divergence
+.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` defaults to it
+.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\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id of the scenario. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-round\fR \fI<N>\fR [default: 1]
+The review round this version belongs to (1\-based)
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer recording this (recorded as the divergence\*(Aqs reviewer and actor)
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The acting session (recorded as actor.session_id); optional
+.TP
+\fB\-\-detail\fR \fI<TEXT>\fR
+Free\-text detail recorded on the version (optional)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The role this record is attributed to (default: the role declared with \-\-as / CANON_ROLE)
+.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
+.TP
+<\fISCENARIO_ID\fR>
+The scenario (`<area>.<surface>.<nn>`)
+.SH VERSION
+v0.28.0

package/man/canon-divergence.1

@@ -0,0 +1,51 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence 1  "divergence 0.28.0" 
+.SH NAME
+canon\-divergence \- Stage, promote, resolve, and inspect spec divergences
+.SH SYNOPSIS
+\fBcanon divergence\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Stage, promote, resolve, and inspect spec divergences
+.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` defaults to it
+.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\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-divergence\-add(1)
+Add a divergence candidate, staged with no run_seq yet (commit it with `canon gate promote \-\-kind divergence`, or in the same run with \-\-promote / `write: { promote: auto }`)
+.TP
+canon\-divergence\-resolve(1)
+Directly record a resolved divergence
+.TP
+canon\-divergence\-defer(1)
+Directly record a deferred divergence (requires \-\-reason/\-\-expiry)
+.TP
+canon\-divergence\-accept(1)
+Accept a divergent scenario as a tracked known gap (a reviewer step): its latest evidence must be divergent and not the accepting actor\*(Aqs or session\*(Aqs. The acceptance pins that evidence, so new evidence ends it, and lapses at \-\-expiry; until then the ship guard counts the cell as covered while `status` and `gate check` list it as `accepted\-divergence`
+.TP
+canon\-divergence\-list(1)
+List the current divergence burn\-down state
+.SH VERSION
+v0.28.0

package/man/canon-evidence-add.1

@@ -0,0 +1,168 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-evidence-add 1  "add 0.28.0" 
+.SH NAME
+canon\-evidence\-add \- Record one attributed EvidenceRecord for a task or scenario (promoted in the same run under `write: { promote: auto }` or with \-\-promote; under `write.promote: manual`, commit it with `canon gate promote`)
+.SH SYNOPSIS
+\fBcanon evidence add\fR [\fB\-\-as\fR] [\fB\-\-task\-id\fR] [\fB\-\-project\-id\fR] [\fB\-\-class\fR] [\fB\-\-ref\fR] [\fB\-\-verdict\fR] [\fB\-\-summary\fR] [\fB\-\-command\-result\fR] [\fB\-\-scenario\-id\fR] [\fB\-\-run\-id\fR] [\fB\-\-surface\-ref\fR] [\fB\-\-actor\-id\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\fR] [\fB\-\-approver\fR] [\fB\-\-approval\-role\fR] [\fB\-\-signature\-file\fR] [\fB\-\-approval\-at\fR] [\fB\-\-rev\fR] [\fB\-\-artifact\fR] [\fB\-\-report\fR] [\fB\-\-report\-case\fR] [\fB\-\-all\-scenarios\fR] [\fB\-\-max\-artifact\-mib\fR] [\fB\-\-override\-reason\fR] [\fB\-\-promote\fR] [\fB\-\-no\-promote\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Record one attributed EvidenceRecord for a task or scenario (promoted in the same run under `write: { promote: auto }` or with \-\-promote; under `write.promote: manual`, commit it with `canon gate promote`)
+.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` defaults to it
+.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\-\-task\-id\fR \fI<TASK_ID>\fR
+Plan task this evidence attests to (<change_id>#<n>); required unless \-\-scenario\-id is given
+.TP
+\fB\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id for \-\-scenario\-id (canon keys a scenario by the composite (project_id, scenario_id)). Must name a spec root configured in canon.yaml, or the add is refused (UNKNOWN_SPEC_ROOT) before anything is written
+.TP
+\fB\-\-class\fR \fI<CLASS>\fR
+What CLASS of evidence is attested to (test\-run, review, ...); default `test\-run` when a \-\-report is given. `audit` is refused: an external evaluator\*(Aqs re\-audit is `canon evidence audit`
+.TP
+\fB\-\-ref\fR \fI<TEXT>\fR
+The reference a reader can resolve: a command line, commit sha, or report path (default: the \-\-report paths, comma\-separated, when one is given). NEVER run or resolved by canon
+.TP
+\fB\-\-verdict\fR \fI<VERDICT>\fR
+faithful / not\-applicable / divergent. Given a \-\-report and no \-\-verdict, the verdict is derived from the bound cases (any failed: divergent; a skipped case and none failed: not\-applicable; else faithful), one record at a time with \-\-all\-scenarios; with no report the default is faithful. An explicit faithful over a failed or skipped case is refused
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+faithful
+.IP \(bu 2
+not\-applicable
+.IP \(bu 2
+divergent
+.RE
+.TP
+\fB\-\-summary\fR \fI<TEXT>\fR
+One\-line note, with or without \-\-task; a task\*(Aqs flipped row shows it as the latest summary (scanned for fabrication markers; line breaks refused)
+.TP
+\fB\-\-command\-result\fR \fI<TEXT>\fR
+The real captured output backing \-\-summary (requires \-\-summary; scanned for fabrication markers)
+.TP
+\fB\-\-scenario\-id\fR \fI<SCENARIO_ID>\fR
+Scenario this evidence also joins to
+.TP
+\fB\-\-run\-id\fR \fI<RUN_ID>\fR
+RunId (ULID) of the run that produced this evidence
+.TP
+\fB\-\-surface\-ref\fR \fI<PATH_OR_EFFECT>\fR
+Explicit risk binding: repository\-relative path or effect:<kebab\-slug>; persisted as surface_ref
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR [default: canon]
+The attesting actor\*(Aqs id (recorded as the attestation\*(Aqs author; line breaks refused)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The attesting role; `canon gate promote` derives its run_seq partition key from it. Default: the declared role (\-\-as / CANON_ROLE); required when none is declared
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The attesting session (recorded as actor.session_id). Under require_review.distinct_actor a review from this session does not count
+.TP
+\fB\-\-approver\fR \fI<NAME>\fR
+Human approval identity; authentication comes only from the detached signature
+.TP
+\fB\-\-approval\-role\fR \fI<ROLE>\fR
+Approval role; only human is eligible for risk approval
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+human
+.RE
+.TP
+\fB\-\-signature\-file\fR \fI<FILE>\fR
+Armored SSH detached signature file. Canon never signs on the user\*(Aqs behalf
+.TP
+\fB\-\-approval\-at\fR \fI<TIMESTAMP>\fR
+Timestamp (RFC3339 or YYYY\-MM\-DD) included in the signed approval payload
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-artifact\fR \fI<PATH>\fR
+EXPERIMENTAL: bind any file (trace, screenshots, agent QA log, report) by sha256; repeatable; must be inside the repo; with \-\-all\-scenarios only as <scenario\-id>=<path>, bound to that scenario\*(Aqs record alone
+.TP
+\fB\-\-report\fR \fI<FORMAT:PATH>\fR
+EXPERIMENTAL: bind and parse a test report, `junit:<path>`, `cucumber:<path>` or `swift\-testing:<path>`; repeatable
+.TP
+\fB\-\-report\-case\fR \fI<NAME>\fR
+EXPERIMENTAL: also bind this report case (a Rust test: its function name); repeatable. Cases whose own scenario id is this one are always bound
+.TP
+\fB\-\-all\-scenarios\fR
+One record per indexed scenario of \-\-project\-id that owns a case in the \-\-report(s), all or nothing (see below)
+.TP
+\fB\-\-max\-artifact\-mib\fR \fI<N>\fR [default: 25]
+Per\-file size limit for the artifact store (.canon/artifacts/sha256/), in MiB; a larger bound file is refused
+.TP
+\fB\-\-override\-reason\fR \fI<TEXT>\fR
+Attest anyway while a subject this record attests for has a brief awaiting the human\*(Aqs answer (one line, recorded on the record with \-\-actor\-id)
+.TP
+\fB\-\-promote\fR
+Promote the record this run staged, in the same run; records others staged stay staged (the default under canon.yaml `write: { promote: auto }`)
+.TP
+\fB\-\-no\-promote\fR
+Keep this write staged even under canon.yaml `write: { promote: auto }`
+.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
+ATTESTATION, NOT PROOF.
+The evidence command never runs, resolves, or checks \-\-ref. The attestor can authorize its own checkbox; this is an attestation, not independent approval.
+The gate skips the staleness, trust\-ladder, release\-trust, and divergence dimensions.
+Detached approvals require an external signature; canon never signs on the user\*(Aqs behalf.
+
+EXPERIMENTAL BINDING (\-\-artifact, \-\-report).
+Canon reads files your runner or agent already wrote; it never runs a test. \-\-artifact binds any file by sha256; \-\-report junit:<path>, cucumber:<path> or swift\-testing:<path> (the JSON\-lines event stream of `swift test \-\-experimental\-event\-stream\-output`) also records the matched case and its outcome (a faithful verdict needs every bound case to pass). Every case whose own scenario id (the first id in its classname, then name, a Swift Testing display name, then function name, or a Cucumber tag) is this one is bound; a case that only mentions it is not; \-\-report\-case adds more. With \-\-task and no \-\-scenario\-id, every case in the report is bound. Bound files are copied into .canon/artifacts/sha256/<hex> (commit them with the ledger; per\-file limit \-\-max\-artifact\-mib, default 25), and canon gate check re\-hashes them: a bound file whose bytes are gone is stale\-evidence. Strength requirements are opt\-in via policy experimental.evidence_binding (off by default).
+
+ONE REPORT, MANY SCENARIOS (\-\-all\-scenarios).
+With \-\-report, writes one record per indexed scenario that owns a case in the report, each with its own cases and its own verdict: \-\-verdict when given, else derived (faithful when every case passed, divergent when one failed, not\-applicable when one was skipped). A case whose id is not indexed is named and skipped. All or nothing: any refusal (a claimed faithful verdict over a failed case, a fabrication marker, an unapproved brief, a dropped binding) writes no record. The records share the stored report file.
+
+FILES BELONG TO TESTS (\-\-artifact).
+A record binds the attachments of the cases it owns: JUnit `[[ATTACHMENT|<path>]]` lines in a test\*(Aqs <system\-out> (Playwright\*(Aqs reporter; the path is relative to the report\*(Aqs directory) and Cucumber JSON embeddings, in a batch and with \-\-scenario\-id alike. A missing, out\-of\-repo or oversized attachment is refused naming the case and the path. With \-\-all\-scenarios a bare \-\-artifact <path> is refused (it would bind to every record); bind a file to one scenario with \-\-artifact <scenario\-id>=<path> (the part before the first `=` counts only when shaped like a scenario id; write ./<path> for a file named otherwise).
+
+A WRITE THAT BREAKS A REVIEW PIN SAYS SO.
+When the new record supersedes evidence a current pinned review saw, one line per review now stale names the reviewer, the scenario and the `canon review scenario` command that re\-pins it (`\-\-rev` names the commit).
+
+RE\-ATTESTING NEVER DROPS A BINDING SILENTLY (\-\-drop\-attachment).
+For a scenario, a record that leaves out a file the scenario\*(Aqs latest record binds is refused (exit 2) until it re\-binds the file (new bytes at the same path are fine) or names it with \-\-drop\-attachment <path> (repeatable) \-\-drop\-reason <text>. The drop is recorded on the record and listed by canon status. Task\-only evidence has no drop guard.
+
+NOTHING IS ATTESTED BEFORE THE BRIEF IS APPROVED (\-\-override\-reason).
+While a subject this record attests for (the scenario\*(Aqs @subject owner, or any subject adopting the task\*(Aqs change) has a newest change whose proposal.md has no `Approved:` line, the add is refused (exit 1, nothing staged): stop, report the brief and wait for the human\*(Aqs answer. \-\-override\-reason <text> attests anyway; the reason, the waived subjects and \-\-actor\-id are recorded on the record and listed by canon status and canon gate check. A subject with no proposal.md to answer is unaffected; review scenario and finding add are never refused.
+
+AUDITS.
+An external evaluator\*(Aqs re\-audit is `canon evidence audit <SCENARIO_ID>`, not `\-\-kind audit`.
+.SH VERSION
+v0.28.0

package/man/canon-evidence-approval-payload.1

@@ -0,0 +1,65 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-evidence-approval-payload 1  "approval-payload 0.28.0" 
+.SH NAME
+canon\-evidence\-approval\-payload \- Emit exact bytes for external `ssh\-keygen \-Y sign \-n canon\-approval\-v1`
+.SH SYNOPSIS
+\fBcanon evidence approval\-payload\fR [\fB\-\-as\fR] [\fB\-\-task\-id\fR] [\fB\-\-project\-id\fR] [\fB\-\-scenario\-id\fR] [\fB\-\-run\-id\fR] [\fB\-\-rev\fR] [\fB\-\-surface\-ref\fR] <\fB\-\-approver\fR> <\fB\-\-approval\-at\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Emit exact bytes for external `ssh\-keygen \-Y sign \-n canon\-approval\-v1`
+.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` defaults to it
+.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\-\-task\-id\fR \fI<TASK_ID>\fR
+The plan task the approval is for (<change_id>#<n>); give this or \-\-scenario\-id
+.TP
+\fB\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id for \-\-scenario\-id. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-scenario\-id\fR \fI<SCENARIO_ID>\fR
+The scenario the approval is for; give this or \-\-task\-id
+.TP
+\fB\-\-run\-id\fR \fI<RUN_ID>\fR
+The dispatch run the approved work belongs to
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-surface\-ref\fR \fI<PATH_OR_EFFECT>\fR
+The risk surface being approved: a repository\-relative path or `effect:<kebab\-slug>` (repeatable)
+.TP
+\fB\-\-approver\fR \fI<NAME>\fR
+Who approved (the human whose detached signature the payload is for)
+.TP
+\fB\-\-approval\-at\fR \fI<TIMESTAMP>\fR
+The approval time that is signed into the payload: RFC3339, or YYYY\-MM\-DD (UTC midnight)
+.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\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-evidence-audit.1

@@ -0,0 +1,121 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-evidence-audit 1  "audit 0.28.0" 
+.SH NAME
+canon\-evidence\-audit \- Record an external evaluator\*(Aqs re\-audit of one scenario (class `audit`; the verdict follows \-\-audit\-result; canon never runs the evaluator)
+.SH SYNOPSIS
+\fBcanon evidence audit\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] <\fB\-\-ref\fR> [\fB\-\-summary\fR] [\fB\-\-command\-result\fR] [\fB\-\-run\-id\fR] [\fB\-\-actor\-id\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\fR] [\fB\-\-rev\fR] [\fB\-\-artifact\fR] [\fB\-\-report\fR] [\fB\-\-report\-case\fR] [\fB\-\-max\-artifact\-mib\fR] <\fB\-\-evaluator\-id\fR> <\fB\-\-evaluator\-version\fR> <\fB\-\-evaluator\-digest\fR> <\fB\-\-audit\-result\fR> [\fB\-\-override\-reason\fR] [\fB\-\-promote\fR] [\fB\-\-no\-promote\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISCENARIO_ID\fR> 
+.SH DESCRIPTION
+Record an external evaluator\*(Aqs re\-audit of one scenario (class `audit`; the verdict follows \-\-audit\-result; canon never runs the evaluator)
+.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` defaults to it
+.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\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id of the scenario. Required only when canon.yaml configures more than one spec root; refused (UNKNOWN_SPEC_ROOT) when it names none
+.TP
+\fB\-\-ref\fR \fI<TEXT>\fR
+The reference a reader can resolve: a command line, commit sha, or report path. NEVER run or resolved by canon
+.TP
+\fB\-\-summary\fR \fI<TEXT>\fR
+One\-line note (scanned for fabrication markers; line breaks refused)
+.TP
+\fB\-\-command\-result\fR \fI<TEXT>\fR
+The real captured output backing \-\-summary (requires \-\-summary; scanned for fabrication markers)
+.TP
+\fB\-\-run\-id\fR \fI<RUN_ID>\fR
+RunId (ULID) of the run that produced this evidence
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR [default: canon]
+The attesting actor\*(Aqs id (recorded as the attestation\*(Aqs author; line breaks refused)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The attesting role; `canon gate promote` derives its run_seq partition key from it. Default: the declared role (\-\-as / CANON_ROLE); required when none is declared
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The attesting session (recorded as actor.session_id)
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-artifact\fR \fI<PATH>\fR
+EXPERIMENTAL: bind any file (trace, log, report) by sha256; repeatable; must be inside the repo
+.TP
+\fB\-\-report\fR \fI<FORMAT:PATH>\fR
+EXPERIMENTAL: bind and parse a test report, `junit:<path>`, `cucumber:<path>` or `swift\-testing:<path>`; repeatable
+.TP
+\fB\-\-report\-case\fR \fI<NAME>\fR
+EXPERIMENTAL: also bind this report case (a Rust test: its function name); repeatable
+.TP
+\fB\-\-max\-artifact\-mib\fR \fI<N>\fR [default: 25]
+Per\-file size limit for the artifact store (.canon/artifacts/sha256/), in MiB; a larger bound file is refused
+.TP
+\fB\-\-evaluator\-id\fR \fI<ID>\fR
+The external evaluator that re\-audited the scenario (canon never runs it)
+.TP
+\fB\-\-evaluator\-version\fR \fI<TEXT>\fR
+The evaluator\*(Aqs version
+.TP
+\fB\-\-evaluator\-digest\fR \fI<DIGEST>\fR
+sha256 of the evaluator (64 lowercase hex)
+.TP
+\fB\-\-audit\-result\fR \fI<RESULT>\fR
+confirmed / refuted / indeterminate; the record\*(Aqs verdict follows it (confirmed → faithful, refuted → divergent, indeterminate → not\-applicable)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+confirmed
+.IP \(bu 2
+refuted
+.IP \(bu 2
+indeterminate
+.RE
+.TP
+\fB\-\-override\-reason\fR \fI<TEXT>\fR
+Attest anyway while a subject this record attests for has a brief awaiting the human\*(Aqs answer (one line, recorded on the record with \-\-actor\-id)
+.TP
+\fB\-\-promote\fR
+Promote the record this run staged, in the same run; records others staged stay staged (the default under canon.yaml `write: { promote: auto }`)
+.TP
+\fB\-\-no\-promote\fR
+Keep this write staged even under canon.yaml `write: { promote: auto }`
+.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
+.TP
+<\fISCENARIO_ID\fR>
+The re\-audited scenario (`<area>.<surface>.<nn>`)
+.SH EXTRA
+Records an external evaluator\*(Aqs re\-audit of one scenario: \-\-evaluator\-id, \-\-evaluator\-version, \-\-evaluator\-digest <sha256>, \-\-audit\-result confirmed|refuted|indeterminate, and optional \-\-report/\-\-artifact counterexamples, bound and stored like any report. canon never generates or runs the audit. An audit never becomes the scenario\*(Aqs declared verdict; a refuted latest audit is false\-success in canon gate check, whatever the declared verdict says.
+.SH VERSION
+v0.28.0

package/man/canon-evidence.1

@@ -0,0 +1,57 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-evidence 1  "evidence 0.28.0" 
+.SH NAME
+canon\-evidence \- Author a staged, attributed evidence attestation for a plan task
+.SH SYNOPSIS
+\fBcanon evidence\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Author a staged, attributed evidence attestation for a plan task
+.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` defaults to it
+.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\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-evidence\-approval\-payload(1)
+Emit exact bytes for external `ssh\-keygen \-Y sign \-n canon\-approval\-v1`
+.TP
+canon\-evidence\-add(1)
+Record one attributed EvidenceRecord for a task or scenario (promoted in the same run under `write: { promote: auto }` or with \-\-promote; under `write.promote: manual`, commit it with `canon gate promote`)
+.TP
+canon\-evidence\-audit(1)
+Record an external evaluator\*(Aqs re\-audit of one scenario (class `audit`; the verdict follows \-\-audit\-result; canon never runs the evaluator)
+.SH EXTRA
+Examples:
+  canon evidence add \-\-task\-id my\-change#3.1 \-\-class test\-run \-\-ref \*(Aqcargo test \-p canon\-cli\*(Aq \-\-role implementer
+
+The loop:
+  canon evidence add ...    Record an EvidenceRecord (promoted in the same run under
+                            `write: { promote: auto }`, which `canon init` writes)
+  canon task done <id>      Flip the checkbox on it
+Under `write.promote: manual` (no `write:` key), run `canon gate promote` after
+each add to commit it (assigns run_seq).
+
+See `canon evidence add \-\-help` for exactly what the gate does and does not check.
+.SH VERSION
+v0.28.0