@journeykit/canon 0.27.0 → 0.28.0

package/man/canon-export.1

@@ -0,0 +1,108 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-export 1  "export 0.28.0" 
+.SH NAME
+canon\-export \- Export a redacted retention manifest without deleting records
+.SH SYNOPSIS
+\fBcanon export\fR [\fB\-\-as\fR] <\fB\-\-kind\fR> [\fB\-\-before\fR] [\fB\-\-after\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-include\-sensitive\fR] [\fB\-\-limit\fR] [\fB\-\-cursor\fR] [\fB\-\-all\fR] [\fB\-\-fields\fR] [\fB\-\-dry\-run\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Export a redacted retention manifest without deleting records
+.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
+The record kind to export
+.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\-\-before\fR \fI<TIMESTAMP>\fR
+Only records strictly before this time (RFC3339 or YYYY\-MM\-DD, UTC)
+.TP
+\fB\-\-after\fR \fI<TIMESTAMP>\fR
+Only records at or after this time (RFC3339 or YYYY\-MM\-DD, UTC)
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<FILE>\fR
+Write the manifest to this file (mode 0600) instead of stdout
+.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\-\-include\-sensitive\fR
+Include records marked sensitive (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
+Keep only these fields of each exported record (comma\-separated): kind, at, id, digest; an unknown field is refused (camelCase and snake_case both match)
+.TP
+\fB\-\-dry\-run\fR
+Validate fully and report what would be written, without writing anything
+.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-feature-new.1

@@ -0,0 +1,62 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-feature-new 1  "new 0.28.0" 
+.SH NAME
+canon\-feature\-new \- Create a fresh .feature file for a new area.surface
+.SH SYNOPSIS
+\fBcanon feature new\fR [\fB\-\-as\fR] <\fB\-\-title\fR> [\fB\-\-actor\-id\fR] [\fB\-\-session\-id\fR] [\fB\-\-project\-id\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISURFACE\fR> 
+.SH DESCRIPTION
+Create a fresh .feature file for a new area.surface
+.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\-\-title\fR \fI<TEXT>\fR
+The Feature: header label
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR [default: canon\-scaffold]
+Agent id written into provenance (env: CANON_ACTOR)
+.RS
+May also be specified with the \fBCANON_ACTOR\fR environment variable. 
+.RE
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The acting session (recorded as actor.session_id); optional
+.TP
+\fB\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Which configured `specs.roots[]` entry to write under, by its id. Required only when the repo configures more than one
+.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
+<\fISURFACE\fR>
+<area>.<surface> the fresh .feature file scaffolds
+.SH VERSION
+v0.28.0

package/man/canon-feature.1

@@ -0,0 +1,39 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-feature 1  "feature 0.28.0" 
+.SH NAME
+canon\-feature \- Scaffold a new .feature spec file
+.SH SYNOPSIS
+\fBcanon feature\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Scaffold a new .feature spec file
+.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\-feature\-new(1)
+Create a fresh .feature file for a new area.surface
+.SH VERSION
+v0.28.0

package/man/canon-finding-add.1

@@ -0,0 +1,196 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-finding-add 1  "add 0.28.0" 
+.SH NAME
+canon\-finding\-add \- Record one code\-review finding (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 finding add\fR [\fB\-\-as\fR] <\fB\-\-change\-id\fR> <\fB\-\-round\fR> <\fB\-\-seq\fR> <\fB\-\-severity\fR> [\fB\-\-disposition\fR] <\fB\-\-actor\-id\fR> <\fB\-\-summary\fR> [\fB\-\-rev\fR] [\fB\-\-resolution\-rev\fR] [\fB\-\-introduced\-rev\fR] [\fB\-\-file\-ref\fR] [\fB\-\-scenario\-id\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\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 code\-review finding (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\-\-change\-id\fR \fI<CHANGE_ID>\fR
+The change under review (e.g. s43\-findings\-are\-records) — first component of the natural key
+.TP
+\fB\-\-round\fR \fI<N>\fR
+Which review round on this change raised it (1\-based)
+.TP
+\fB\-\-seq\fR \fI<N>\fR
+This finding\*(Aqs index within the round (1\-based). Required, never auto\-assigned; a collision is refused
+.TP
+\fB\-\-severity\fR \fI<SEVERITY>\fR
+blocker / should\-fix / note — the reviewer\*(Aqs own judgement, never a score canon derives
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+blocker
+.IP \(bu 2
+should\-fix
+.IP \(bu 2
+note
+.RE
+.TP
+\fB\-\-disposition\fR \fI<DISPOSITION>\fR [default: open]
+open / fixed / rejected / deferred (fixed records \-\-resolution\-rev, default HEAD, and only fixed may carry one)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+open
+.IP \(bu 2
+fixed
+.IP \(bu 2
+rejected
+.IP \(bu 2
+deferred
+.RE
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer who raised it, recorded as the finding\*(Aqs reviewer and author (line breaks refused)
+.TP
+\fB\-\-summary\fR \fI<TEXT>\fR
+One line of what the finding IS, in the reviewer\*(Aqs own words. NEVER checked against the code (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\-\-resolution\-rev\fR \fI<REV>\fR
+The commit that closed it, any git revision (resolved to the full sha, with the code tree it saw). Permitted only with \-\-disposition fixed, where it defaults to HEAD. Existence only; canon never reads the commit\*(Aqs message or diff
+.TP
+\fB\-\-introduced\-rev\fR \fI<REV>\fR
+The SOURCED introducing commit, any git revision (resolved to the full sha). No default: leave it unset when it is not known, never guess (see \-\-help). Existence only; canon never reads the commit\*(Aqs message or diff
+.TP
+\fB\-\-file\-ref\fR \fI<TEXT>\fR
+Where in the tree, as path/to/file.rs:120\-134 (line breaks refused)
+.TP
+\fB\-\-scenario\-id\fR \fI<SCENARIO_ID>\fR
+A scenario this finding is about (repeatable). After a `fixed` close, fresh evidence for these scenarios alone re\-verifies the fix; with none named, every evidenced scenario of the subject does. Each must be a scenario the index knows; a close inherits the list
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR [default: reviewer]
+Attribution only — unlike `canon evidence add`, no partition key derives from it
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The authoring session (recorded as actor.session_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
+RECORDED OBSERVATION, NOT PROOF. canon does not verify that the defect
+existed, that it was real, that it was fixed, or that \-\-introduced\-rev names
+the commit that actually caused it. This records that a named reviewer, at a
+stamped time, RAISED this finding against this change.
+
+An agent that can run this command can record its own review round, with its
+own severities: the author of a finding and its beneficiary are the same
+party, with no signature and no second party — the same gap `canon evidence
+add` states about attestations.
+
+What canon does NOT check:
+  \- \-\-summary, against the diff, the code, or the review transcript. The
+    record is identical whether the defect was real, misdiagnosed, or invented
+  \- \-\-resolution\-rev: resolved to a full commit sha, existence only; the
+    commit\*(Aqs message and diff are never read. `\-\-disposition fixed` records
+    that someone SAID this commit closed it, not that it did
+  \- \-\-introduced\-rev: never verified, and never guessed (below)
+  \- \-\-rev: optional, because most rounds review an uncommitted
+    working tree. When absent, canon does not infer one
+  \- whether a finding is right. canon gates on one all the same: a blocker
+    that is still `open`, or `fixed` with no fresh evidence after the fix, is
+    an `open\-blocker` violation of `canon gate check` and the ship guard
+
+What the record IS good for:
+  \- attribution: an append\-only row naming who raised what, in which round,
+    against which change, at which severity and disposition. Before this
+    command, a review round left nothing at all once its transcript was gone
+  \- a DERIVED count that stops being typed from memory. v0.4.0\*(Aqs release note
+    hand\-typed its issue counts into a published tag and got them wrong; that
+    is why this command exists. No count is quoted here and none is asserted
+    in its place \-\- read them off the \*(AqReview rounds\*(Aq panel in
+    .canon/REPORT.md or the dashboard, which derive them from these records
+
+\-\-introduced\-rev must be SOURCED:
+  Set it only when the introducing commit was actually established — someone
+  read the diff, or the fixing commit names it. Never from timing, commit
+  adjacency, or `git blame`. Leaving it UNSET is the correct record when it is
+  not known, not an incomplete one. Unset means UNSOURCED, never \*(Aqno cause\*(Aq; a
+  guessed value would inflate the exact number this command exists to make
+  trustworthy.
+
+What a derived fix\-of\-fix count MEANS, stated here word for word as every
+other surface states it (canon_report::render::FIX_OF_FIX_MEANING) rather
+than paraphrased, because paraphrase is how the previous wording went wrong
+on seven surfaces at once:
+
+  `fix_of_fix` bounds NOTHING — not from below, not from above: it
+  UNDER\-counts, because an unsourced finding is never counted and a fix in
+  one change that breaks something first found while reviewing a DIFFERENT
+  change is not counted at all; it OVER\-counts, because a `resolution_sha`
+  commit may carry work BEYOND the fix and every finding recording that
+  commit is counted regardless; and for any individual match the data cannot
+  say whether the fix or the other work in that commit introduced the
+  defect.
+
+Fix\-of\-fix is DERIVED, never recorded: a finding is one when its
+introduced_by equals an EARLIER finding\*(Aqs resolution_sha (lower round/seq in
+the same change). There is no flag for it and there will not be one — a flag
+would relocate the hand\-typing from the release notes into the record.
+
+\-\-seq is REQUIRED, never auto\-assigned: two concurrent adds would read the
+same highest seq and both pick the next one, landing two records under one
+finding\*(Aqs identity and inflating the count. An already\-occupied
+(\-\-change\-id, \-\-round, \-\-seq) is refused, naming it.
+
+Refused before anything is staged:
+  \- \-\-disposition fixed with no \-\-resolution\-rev, and \-\-resolution\-rev with
+    any other disposition
+  \- a line separator in \-\-summary, \-\-file\-ref or \-\-actor\-id: a
+    finding is rendered as ONE row, so a separator appends a second row that
+    no record backs
+
+The loop:
+  canon finding add ...     Record a Finding (promoted in the same run under
+                            `write: { promote: auto }`, which `canon init` writes)
+Under `write.promote: manual` (no `write:` key), run `canon gate promote` to
+commit it.
+.SH VERSION
+v0.28.0

package/man/canon-finding-close.1

@@ -0,0 +1,117 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-finding-close 1  "close 0.28.0" 
+.SH NAME
+canon\-finding\-close \- Move an already\-committed finding\*(Aqs disposition (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 finding close\fR [\fB\-\-as\fR] <\fB\-\-round\fR> <\fB\-\-seq\fR> <\fB\-\-disposition\fR> [\fB\-\-resolution\-rev\fR] [\fB\-\-reason\fR] [\fB\-\-actor\-id\fR] [\fB\-\-role\fR] [\fB\-\-session\-id\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] <\fICHANGE_ID\fR> 
+.SH DESCRIPTION
+Move an already\-committed finding\*(Aqs disposition (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\-\-round\fR \fI<N>\fR
+Which review round raised it (1\-based)
+.TP
+\fB\-\-seq\fR \fI<N>\fR
+The finding\*(Aqs index within the round (1\-based)
+.TP
+\fB\-\-disposition\fR \fI<DISPOSITION>\fR
+Where it lands: fixed / rejected / deferred / open (reopening is a real transition). fixed records \-\-resolution\-rev, default HEAD, and only fixed may carry one
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+open
+.IP \(bu 2
+fixed
+.IP \(bu 2
+rejected
+.IP \(bu 2
+deferred
+.RE
+.TP
+\fB\-\-resolution\-rev\fR \fI<REV>\fR
+The commit that closed it, any git revision (resolved to the full sha, with the code tree it saw). Permitted only with \-\-disposition fixed, where it defaults to HEAD. Existence only; canon never reads the commit\*(Aqs message or diff
+.TP
+\fB\-\-reason\fR \fI<TEXT>\fR
+Why it was closed, one line. Required for rejected and deferred, optional for fixed and open; stored on the closing version and shown by `finding list`
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR [default: canon]
+The actor recorded as authoring the TRANSITION — not the original finding\*(Aqs author, which is preserved on the record this supersedes
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR [default: reviewer]
+Attribution only — no partition key derives from it
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The session that authored the TRANSITION (recorded as actor.session_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
+<\fICHANGE_ID\fR>
+The change under review — first component of the natural key
+.SH EXTRA
+A finding is raised `open` and later closed. This is the ONLY way to record
+that second state: `canon finding add` refuses an occupied natural key,
+because two DIFFERENT findings under one (change, round, seq) are two
+reviewers\*(Aq work collapsed into one identity.
+
+What it changes: the disposition, `resolution_sha` with it, and the closing
+\-\-reason (required for rejected and deferred). NOTHING else.
+Severity, reviewer, summary, \-\-rev, \-\-introduced\-rev and \-\-file\-ref
+are READ from the committed record and copied byte\-identically — this command
+cannot edit them, and no command can. A finding recorded wrongly stays
+wrongly recorded; that is the append\-only ledger working, not a gap.
+
+The committed record STAYS. This appends a second version at the same
+natural key, and the pair IS the history: `open` at one instant, `fixed` at
+another, each with its own author and timestamp. Every reader folds by
+natural key to the latest version, so the finding is still counted once.
+
+`canon gate promote` re\-derives the transition rule itself before committing
+the second version, so a hand\-written body must clear the same bar.
+
+Examples:
+  canon finding close \-\-change\-id s44\-spec\-derived\-worklist \-\-round 1 \-\-seq 1 \\
+      \-\-disposition fixed \-\-resolution\-rev $(git rev\-parse HEAD)
+  canon finding close \-\-change\-id s44\-spec\-derived\-worklist \-\-round 1 \-\-seq 9 \\
+      \-\-disposition rejected
+.SH VERSION
+v0.28.0

package/man/canon-finding-list.1

@@ -0,0 +1,59 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-finding-list 1  "list 0.28.0" 
+.SH NAME
+canon\-finding\-list \- List a change\*(Aqs committed findings at their latest version: round, seq, severity, disposition, reviewer and summary
+.SH SYNOPSIS
+\fBcanon finding list\fR [\fB\-\-as\fR] <\fB\-\-change\-id\fR> [\fB\-\-open\fR] [\fB\-\-json\fR] [\fB\-\-repo\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 a change\*(Aqs committed findings at their latest version: round, seq, severity, disposition, reviewer and summary
+.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\-\-change\-id\fR \fI<CHANGE_ID>\fR
+The change whose findings to list
+.TP
+\fB\-\-open\fR
+Only findings whose current disposition is open
+.TP
+\fB\-\-json\fR
+Print `{change_id, findings: [...], meta}` as JSON
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.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 finding fields (comma\-separated): round, seq, severity, disposition, reviewer, summary, resolution_sha, file_ref; 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-finding.1

@@ -0,0 +1,67 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-finding 1  "finding 0.28.0" 
+.SH NAME
+canon\-finding \- Record one code\-review finding as a durable record
+.SH SYNOPSIS
+\fBcanon finding\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Record one code\-review finding as a durable record
+.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\-finding\-add(1)
+Record one code\-review finding (promoted in the same run under `write: { promote: auto }` or with \-\-promote; under `write.promote: manual`, commit it with `canon gate promote`)
+.TP
+canon\-finding\-close(1)
+Move an already\-committed finding\*(Aqs disposition (promoted in the same run under `write: { promote: auto }` or with \-\-promote; under `write.promote: manual`, commit it with `canon gate promote`)
+.TP
+canon\-finding\-list(1)
+List a change\*(Aqs committed findings at their latest version: round, seq, severity, disposition, reviewer and summary
+.SH EXTRA
+Examples:
+  canon finding add \-\-change\-id s43\-findings\-are\-records \-\-round 1 \-\-seq 1 \\
+      \-\-severity blocker \-\-disposition open \-\-actor\-id review\-voice \\
+      \-\-summary \*(Aqa release metric is asserted, never computed\*(Aq
+  canon finding close s43\-findings\-are\-records \-\-round 1 \-\-seq 1 \\
+      \-\-disposition fixed \-\-resolution\-rev $(git rev\-parse HEAD)
+
+The loop:
+  canon finding add ...     Record a Finding
+  canon finding close ...   Record its disposition TRANSITION, once fixed
+Each is promoted in the same run under `write: { promote: auto }`, which
+`canon init` writes. Under `write.promote: manual` (no `write:` key), run
+`canon gate promote` after each to commit it.
+
+The committed finding STAYS when it is closed: the ledger is append\-only and
+the pair IS the history. Every reader folds by natural key to the latest
+version, so the finding is still counted once.
+
+RECORDED OBSERVATION, NOT PROOF — canon never verifies that the defect
+existed, that it was fixed, or that \-\-introduced\-rev is the true cause.
+See `canon finding add \-\-help` for exactly what it does and does not establish.
+.SH VERSION
+v0.28.0