@journeykit/canon 0.27.0 → 0.28.0

package/man/canon-query.1

@@ -0,0 +1,111 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-query 1  "query 0.28.0" 
+.SH NAME
+canon\-query \- Read stored records across every storage tier
+.SH SYNOPSIS
+\fBcanon query\fR [\fB\-\-as\fR] <\fB\-\-kind\fR> [\fB\-\-since\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-plugin\-id\fR] [\fB\-\-history\fR] [\fB\-\-change\-id\fR] [\fB\-\-status\fR] [\fB\-\-domain\fR] [\fB\-\-include\-sensitive\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
+Read stored records across every storage tier
+.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\-\-kind\fR \fI<KIND>\fR
+Record kind to read (e.g. handoff, strategy_item)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+change
+.IP \(bu 2
+task
+.IP \(bu 2
+scenario
+.IP \(bu 2
+session
+.IP \(bu 2
+run
+.IP \(bu 2
+event
+.IP \(bu 2
+handoff
+.IP \(bu 2
+review
+.IP \(bu 2
+divergence
+.IP \(bu 2
+trajectory
+.IP \(bu 2
+strategy_item
+.IP \(bu 2
+evidence
+.IP \(bu 2
+subject
+.IP \(bu 2
+finding
+.RE
+.TP
+\fB\-\-since\fR \fI<TIMESTAMP>\fR
+Only records with at >= <since> (RFC3339/ISO\-8601)
+.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\-\-plugin\-id\fR \fI<PLUGIN_ID>\fR
+Project a plugin\*(Aqs overlay fields onto each record (fail\-soft)
+.TP
+\fB\-\-history\fR
+Every version of the kind, the ledger\*(Aqs and the archive\*(Aqs, oldest first, instead of the current records
+.TP
+\fB\-\-change\-id\fR \fI<CHANGE_ID>\fR
+Scope \-\-kind change/task to one ChangeId (other kinds exit 2)
+.TP
+\fB\-\-status\fR \fI<STATUS>\fR
+Scope \-\-kind change/task by status field (other kinds exit 2)
+.TP
+\fB\-\-domain\fR \fI<NAME>\fR
+Scope \-\-kind subject by domain (other kinds exit 2)
+.TP
+\fB\-\-include\-sensitive\fR
+Permit sensitive query output only when policy explicitly allows it
+.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 top\-level record fields (comma\-separated); 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-regime-show.1

@@ -0,0 +1,50 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-regime-show 1  "show 0.28.0" 
+.SH NAME
+canon\-regime\-show \- Build a canonical regime key for hook scripts
+.SH SYNOPSIS
+\fBcanon regime show\fR [\fB\-\-as\fR] <\fB\-\-role\-segment\fR> <\fB\-\-repo\-name\fR> <\fB\-\-area\fR> <\fB\-\-hash\fR> [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Build a canonical regime key for hook scripts
+.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\-\-role\-segment\fR \fI<NAME>\fR
+The <role> segment (canonicalized)
+.TP
+\fB\-\-repo\-name\fR \fI<NAME>\fR
+The <repo> segment (canonicalized)
+.TP
+\fB\-\-area\fR \fI<NAME>\fR
+The <area> segment (canonicalized)
+.TP
+\fB\-\-hash\fR \fI<HASH>\fR
+The <hash> segment (6\-64\-char lowercase hex; passed through, never re\-hashed)
+.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-regime.1

@@ -0,0 +1,39 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-regime 1  "regime 0.28.0" 
+.SH NAME
+canon\-regime \- Build a canonical regime key for hook scripts
+.SH SYNOPSIS
+\fBcanon regime\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Build a canonical regime key for hook scripts
+.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\-regime\-show(1)
+Build a canonical regime key for hook scripts
+.SH VERSION
+v0.28.0

package/man/canon-report-build.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-report-build 1  "build 0.28.0" 
+.SH NAME
+canon\-report\-build \- Write the status report (.canon/REPORT.md)
+.SH SYNOPSIS
+\fBcanon report build\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Write the status report (.canon/REPORT.md)
+.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\-\-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 VERSION
+v0.28.0

package/man/canon-report-check.1

@@ -0,0 +1,41 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-report-check 1  "check 0.28.0" 
+.SH NAME
+canon\-report\-check \- Byte\-diff .canon/REPORT.md against a fresh build (0 fresh, 1 missing or drifted); writes nothing
+.SH SYNOPSIS
+\fBcanon report check\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Byte\-diff .canon/REPORT.md against a fresh build (0 fresh, 1 missing or drifted); writes nothing
+.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\-\-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-report-snapshot.1

@@ -0,0 +1,47 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-report-snapshot 1  "snapshot 0.28.0" 
+.SH NAME
+canon\-report\-snapshot \- Export the panel marts to <DIR>/*.parquet plus manifest.json
+.SH SYNOPSIS
+\fBcanon report snapshot\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIDIR\fR> 
+.SH DESCRIPTION
+Export the panel marts to <DIR>/*.parquet plus manifest.json
+.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\-\-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
+<\fIDIR\fR>
+The output directory (created if absent)
+.SH VERSION
+v0.28.0

package/man/canon-report.1

@@ -0,0 +1,45 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-report 1  "report 0.28.0" 
+.SH NAME
+canon\-report \- Build, check, or snapshot the status report
+.SH SYNOPSIS
+\fBcanon report\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Build, check, or snapshot the status report
+.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\-report\-build(1)
+Write the status report (.canon/REPORT.md)
+.TP
+canon\-report\-check(1)
+Byte\-diff .canon/REPORT.md against a fresh build (0 fresh, 1 missing or drifted); writes nothing
+.TP
+canon\-report\-snapshot(1)
+Export the panel marts to <DIR>/*.parquet plus manifest.json
+.SH VERSION
+v0.28.0

package/man/canon-retrieve.1

@@ -0,0 +1,56 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-retrieve 1  "retrieve 0.28.0" 
+.SH NAME
+canon\-retrieve \- Fetch role\-scoped strategy guidance
+.SH SYNOPSIS
+\fBcanon retrieve\fR [\fB\-\-as\fR] <\fB\-\-for\-role\fR> [\fB\-\-regime\fR] [\fB\-\-domain\fR] [\fB\-\-subject\-id\fR] [\fB\-\-limit\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Fetch role\-scoped strategy guidance
+.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\-\-for\-role\fR \fI<ROLE>\fR
+Role scope; with \-\-regime must equal its leading segment
+.TP
+\fB\-\-regime\fR \fI<KEY>\fR
+Full regime key (<role>/<repo>/<area>/<hash>); mutually exclusive with \-\-domain/\-\-subject\-id
+.TP
+\fB\-\-domain\fR \fI<NAME>\fR
+Derive the regime from a domain slug; mutually exclusive with \-\-regime
+.TP
+\fB\-\-subject\-id\fR \fI<SUBJECT_ID>\fR
+Narrow \-\-domain to one subject_id; requires \-\-domain, mutually exclusive with \-\-regime
+.TP
+\fB\-\-limit\fR \fI<N>\fR [default: 5]
+Cap on the guidance items returned (default: 5)
+.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-review-change.1

@@ -0,0 +1,98 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-review-change 1  "change 0.28.0" 
+.SH NAME
+canon\-review\-change \- Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required). The review signs the chore\*(Aqs invariants and checks against the diff and pins the change\*(Aqs brief; an edit to the brief stales it. A chore needs exactly this one review before `subject move \-\-to shipped`
+.SH SYNOPSIS
+\fBcanon review change\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] <\fB\-\-actor\-id\fR> [\fB\-\-rev\fR] [\fB\-\-upstream\-ref\fR] [\fB\-\-original\-spec\-ref\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\fR] [\fB\-\-review\-outcome\fR] [\fB\-\-reviewer\-provider\fR] [\fB\-\-reviewer\-model\fR] [\fB\-\-reviewer\-harness\fR] [\fB\-\-artifact\fR] [\fB\-\-max\-artifact\-mib\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fICHANGE_ID\fR> 
+.SH DESCRIPTION
+Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required). The review signs the chore\*(Aqs invariants and checks against the diff and pins the change\*(Aqs brief; an edit to the brief stales it. A chore needs exactly this one review before `subject move \-\-to shipped`
+.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 scenarios. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer\*(Aqs id (recorded as the review\*(Aqs author and as its reviewer; line breaks refused)
+.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\-\-upstream\-ref\fR \fI<TEXT>\fR
+Provenance ref (mutually exclusive with \-\-original\-spec\-ref; exactly one required)
+.TP
+\fB\-\-original\-spec\-ref\fR \fI<TEXT>\fR
+Provenance ref (mutually exclusive with \-\-upstream\-ref; exactly one required)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The reviewer\*(Aqs role. Required unless the declared role (\-\-as / CANON_ROLE) is implementer or reviewer, which it then defaults to
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The reviewing session (recorded as actor.session_id). Under require_review.distinct_actor a review whose session also attested the scenario\*(Aqs evidence does not count
+.TP
+\fB\-\-review\-outcome\fR \fI<REVIEW_OUTCOME>\fR [default: signed]
+How the reviewer\*(Aqs run ended: signed (an approval), indeterminate (ran, reached no verdict) or unavailable (could not run). Only signed counts; the others are recorded as review gaps
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+signed
+.IP \(bu 2
+indeterminate
+.IP \(bu 2
+unavailable
+.RE
+.TP
+\fB\-\-reviewer\-provider\fR \fI<NAME>\fR
+The reviewer runtime\*(Aqs provider (e.g. anthropic, openai)
+.TP
+\fB\-\-reviewer\-model\fR \fI<NAME>\fR
+The reviewer runtime\*(Aqs model id
+.TP
+\fB\-\-reviewer\-harness\fR \fI<NAME>\fR
+The harness that ran the reviewer (e.g. omp, codex, claude)
+.TP
+\fB\-\-artifact\fR \fI<PATH>\fR
+A file the reviewer looked at (screenshot, recording); repeatable; must be inside the repo. Stored in .canon/artifacts/sha256/ and re\-hashed by `canon gate check`
+.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 file is refused
+.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
+<\fICHANGE_ID\fR>
+The chore change to review
+.SH VERSION
+v0.28.0

package/man/canon-review-scenario.1

@@ -0,0 +1,98 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-review-scenario 1  "scenario 0.28.0" 
+.SH NAME
+canon\-review\-scenario \- Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required). A review pins the scenario\*(Aqs digest and what its latest evidence says (verdict and checks); it counts only while both are unchanged. Each scenario must be indexed, or nothing is written (exit 2)
+.SH SYNOPSIS
+\fBcanon review scenario\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] <\fB\-\-actor\-id\fR> [\fB\-\-rev\fR] [\fB\-\-upstream\-ref\fR] [\fB\-\-original\-spec\-ref\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\fR] [\fB\-\-review\-outcome\fR] [\fB\-\-reviewer\-provider\fR] [\fB\-\-reviewer\-model\fR] [\fB\-\-reviewer\-harness\fR] [\fB\-\-artifact\fR] [\fB\-\-max\-artifact\-mib\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
+Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required). A review pins the scenario\*(Aqs digest and what its latest evidence says (verdict and checks); it counts only while both are unchanged. Each scenario must be indexed, or nothing is written (exit 2)
+.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 scenarios. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer\*(Aqs id (recorded as the review\*(Aqs author and as its reviewer; line breaks refused)
+.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\-\-upstream\-ref\fR \fI<TEXT>\fR
+Provenance ref (mutually exclusive with \-\-original\-spec\-ref; exactly one required)
+.TP
+\fB\-\-original\-spec\-ref\fR \fI<TEXT>\fR
+Provenance ref (mutually exclusive with \-\-upstream\-ref; exactly one required)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The reviewer\*(Aqs role. Required unless the declared role (\-\-as / CANON_ROLE) is implementer or reviewer, which it then defaults to
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The reviewing session (recorded as actor.session_id). Under require_review.distinct_actor a review whose session also attested the scenario\*(Aqs evidence does not count
+.TP
+\fB\-\-review\-outcome\fR \fI<REVIEW_OUTCOME>\fR [default: signed]
+How the reviewer\*(Aqs run ended: signed (an approval), indeterminate (ran, reached no verdict) or unavailable (could not run). Only signed counts; the others are recorded as review gaps
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+signed
+.IP \(bu 2
+indeterminate
+.IP \(bu 2
+unavailable
+.RE
+.TP
+\fB\-\-reviewer\-provider\fR \fI<NAME>\fR
+The reviewer runtime\*(Aqs provider (e.g. anthropic, openai)
+.TP
+\fB\-\-reviewer\-model\fR \fI<NAME>\fR
+The reviewer runtime\*(Aqs model id
+.TP
+\fB\-\-reviewer\-harness\fR \fI<NAME>\fR
+The harness that ran the reviewer (e.g. omp, codex, claude)
+.TP
+\fB\-\-artifact\fR \fI<PATH>\fR
+A file the reviewer looked at (screenshot, recording); repeatable; must be inside the repo. Stored in .canon/artifacts/sha256/ and re\-hashed by `canon gate check`
+.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 file is refused
+.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 reviewed scenarios (`<area>.<surface>.<nn>`), one review each, all or nothing. Each must have a record (`canon inventory sync`), or nothing is written (exit 2)
+.SH VERSION
+v0.28.0

package/man/canon-review.1

@@ -0,0 +1,42 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-review 1  "review 0.28.0" 
+.SH NAME
+canon\-review \- Record an attributed review verdict
+.SH SYNOPSIS
+\fBcanon review\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Record an attributed review verdict
+.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\-review\-scenario(1)
+Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required). A review pins the scenario\*(Aqs digest and what its latest evidence says (verdict and checks); it counts only while both are unchanged. Each scenario must be indexed, or nothing is written (exit 2)
+.TP
+canon\-review\-change(1)
+Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required). The review signs the chore\*(Aqs invariants and checks against the diff and pins the change\*(Aqs brief; an edit to the brief stales it. A chore needs exactly this one review before `subject move \-\-to shipped`
+.SH VERSION
+v0.28.0