@journeykit/canon 0.29.0 → 0.31.0

package/man/canon-finding-add.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-finding-add 1  "add 0.29.0" 
+.TH canon-finding-add 1  "add 0.31.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] 
+\fBcanon finding add\fR [\fB\-\-as\fR] <\fB\-\-change\fR> <\fB\-\-round\fR> <\fB\-\-seq\fR> <\fB\-\-severity\fR> [\fB\-\-disposition\fR] <\fB\-\-actor\fR> <\fB\-\-summary\fR> [\fB\-\-rev\fR] [\fB\-\-resolution\-rev\fR] [\fB\-\-introduced\-rev\fR] [\fB\-\-introduced\-unknown\fR] [\fB\-\-review\fR] [\fB\-\-file\-ref\fR] [\fB\-\-scenario\fR] [\fB\-\-role\fR] [\fB\-\-session\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
@@ -26,7 +26,7 @@ reviewer
 orchestrator
 .RE
 .TP
-\fB\-\-change\-id\fR \fI<CHANGE_ID>\fR
+\fB\-\-change\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
@@ -67,7 +67,7 @@ rejected
 deferred
 .RE
 .TP
-\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+\fB\-\-actor\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
@@ -82,16 +82,22 @@ The commit that closed it, any git revision (resolved to the full sha, with the
 \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\-\-introduced\-unknown\fR
+Say the introducing commit is not known, instead of \-\-introduced\-rev. A new blocker or should\-fix needs one of the two; a note needs neither. Stored in its own field, never in the commit slot
+.TP
+\fB\-\-review\fR \fI<REVIEW_ID>\fR
+The review this finding came out of: the review id `canon review scenario` or `canon review change` printed. Refused when no review in the ledger or the archive carries it; a close copies it
+.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
+\fB\-\-scenario\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
+\fB\-\-session\fR \fI<SESSION_ID>\fR
 The authoring session (recorded as actor.session_id)
 .TP
 \fB\-\-promote\fR
@@ -151,8 +157,11 @@ What the record IS good for:
 \-\-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
+  adjacency, or `git blame`. A new blocker or should\-fix must name the commit with \-\-introduced\-rev or
+  say it is not known with \-\-introduced\-unknown (a note needs neither); with
+  neither it is refused, and both together are refused. \-\-introduced\-unknown
+  is the correct record when the commit was not established, not an
+  incomplete one. Not naming a commit means UNSOURCED, never \*(Aqno cause\*(Aq; a
   guessed value would inflate the exact number this command exists to make
   trustworthy.
 
@@ -178,12 +187,15 @@ 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.
+(\-\-change, \-\-round, \-\-seq) is refused, naming it.
 
 Refused before anything is staged:
+  \- a blocker or should\-fix with neither \-\-introduced\-rev nor
+    \-\-introduced\-unknown, and \-\-introduced\-rev together with \-\-introduced\-unknown
+  \- a \-\-review that no review in the ledger or the archive carries
   \- \-\-disposition fixed with no \-\-resolution\-rev, and \-\-resolution\-rev with
     any other disposition
-  \- a line separator in \-\-summary, \-\-file\-ref or \-\-actor\-id: a
+  \- a line separator in \-\-summary, \-\-file\-ref or \-\-actor: a
     finding is rendered as ONE row, so a separator appends a second row that
     no record backs
 
@@ -193,4 +205,4 @@ The loop:
 Under `write.promote: manual` (no `write:` key), run `canon gate promote` to
 commit it.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-finding-close.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-finding-close 1  "close 0.29.0" 
+.TH canon-finding-close 1  "close 0.31.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> 
+\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\fR] [\fB\-\-role\fR] [\fB\-\-session\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
@@ -55,13 +55,13 @@ The commit that closed it, any git revision (resolved to the full sha, with the
 \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]
+\fB\-\-actor\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
+\fB\-\-session\fR \fI<SESSION_ID>\fR
 The session that authored the TRANSITION (recorded as actor.session_id)
 .TP
 \fB\-\-promote\fR
@@ -109,9 +109,9 @@ natural key to the latest version, so the finding is still counted once.
 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 \\
+  canon finding close 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
+  canon finding close s44\-spec\-derived\-worklist \-\-round 1 \-\-seq 9 \\
+      \-\-disposition rejected \-\-reason "not a defect"
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-finding-list.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-finding-list 1  "list 0.29.0" 
+.TH canon-finding-list 1  "list 0.31.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] 
+\fBcanon finding list\fR [\fB\-\-as\fR] <\fB\-\-change\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
@@ -26,7 +26,7 @@ reviewer
 orchestrator
 .RE
 .TP
-\fB\-\-change\-id\fR \fI<CHANGE_ID>\fR
+\fB\-\-change\fR \fI<CHANGE_ID>\fR
 The change whose findings to list
 .TP
 \fB\-\-open\fR
@@ -56,4 +56,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-finding.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-finding 1  "finding 0.29.0" 
+.TH canon-finding 1  "finding 0.31.0" 
 .SH NAME
 canon\-finding \- Record one code\-review finding as a durable record
 .SH SYNOPSIS
@@ -43,8 +43,8 @@ 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 \\
+  canon finding add \-\-change s43\-findings\-are\-records \-\-round 1 \-\-seq 1 \\
+      \-\-severity blocker \-\-disposition open \-\-actor 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)
@@ -64,4 +64,4 @@ 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.29.0
+v0.31.0

package/man/canon-format.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-format 1  "format 0.29.0" 
+.TH canon-format 1  "format 0.31.0" 
 .SH NAME
 canon\-format \- Validate a spec/artifact corpus against canon\*(Aqs format
 .SH SYNOPSIS
@@ -46,4 +46,4 @@ Examples:
   canon format spec
   canon format spec \-\-repo ~/work/myrepo
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-gate-check.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-gate-check 1  "check 0.29.0" 
+.TH canon-gate-check 1  "check 0.31.0" 
 .SH NAME
 canon\-gate\-check \- Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-gate-install-hooks.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-gate-install-hooks 1  "install-hooks 0.29.0" 
+.TH canon-gate-install-hooks 1  "install-hooks 0.31.0" 
 .SH NAME
 canon\-gate\-install\-hooks \- Install the gate hook into .claude/settings.json / .codex/hooks.json
 .SH SYNOPSIS
@@ -56,4 +56,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-gate-promote.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-gate-promote 1  "promote 0.29.0" 
+.TH canon-gate-promote 1  "promote 0.31.0" 
 .SH NAME
 canon\-gate\-promote \- Promote staged records (evidence, findings, divergences) to the committed ledger
 .SH SYNOPSIS
@@ -59,4 +59,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-gate.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-gate 1  "gate 0.29.0" 
+.TH canon-gate 1  "gate 0.31.0" 
 .SH NAME
 canon\-gate \- Run evidence gates, promote staged records, install hooks
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Examples:
   canon task done my\-change#3
   canon gate install\-hooks
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ingest-plans.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ingest-plans 1  "plans 0.29.0" 
+.TH canon-ingest-plans 1  "plans 0.31.0" 
 .SH NAME
 canon\-ingest\-plans \- Import plans as Change/Task records: canon\*(Aqs own .canon/changes, then the configured external sources (openspec, superpowers)
 .SH SYNOPSIS
@@ -50,4 +50,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ingest-records.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ingest-records 1  "records 0.29.0" 
+.TH canon-ingest-records 1  "records 0.31.0" 
 .SH NAME
 canon\-ingest\-records \- Import review/divergence/task/handoff records and derive verdicts
 .SH SYNOPSIS
-\fBcanon ingest records\fR [\fB\-\-as\fR] [\fB\-\-watch\fR] [\fB\-\-interval\-secs\fR] [\fB\-\-repo\fR] [\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-run\-id\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+\fBcanon ingest records\fR [\fB\-\-as\fR] [\fB\-\-watch\fR] [\fB\-\-interval\-secs\fR] [\fB\-\-repo\fR] [\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-run\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
 .SH DESCRIPTION
 Import review/divergence/task/handoff records and derive verdicts
 .SH OPTIONS
@@ -41,7 +41,7 @@ Validate fully and report what would be written, without writing anything
 \fB\-\-json\fR
 Output JSON instead of the human\-readable form
 .TP
-\fB\-\-run\-id\fR \fI<RUN_ID>\fR
+\fB\-\-run\fR \fI<RUN_ID>\fR
 Attribute this pass\*(Aqs trajectories to a dispatched run (a RunId minted by `canon dispatch begin`)
 .TP
 \fB\-\-input\fR \fI<JSON|FILE|\->\fR
@@ -53,4 +53,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ingest-sessions.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ingest-sessions 1  "sessions 0.29.0" 
+.TH canon-ingest-sessions 1  "sessions 0.31.0" 
 .SH NAME
 canon\-ingest\-sessions \- Import agent CLI session transcripts (omp/pi, Claude Code, Codex, Hermes)
 .SH SYNOPSIS
@@ -59,4 +59,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ingest.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ingest 1  "ingest 0.29.0" 
+.TH canon-ingest 1  "ingest 0.31.0" 
 .SH NAME
 canon\-ingest \- Import agent sessions, records, and plans into canon\*(Aqs store
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Examples:
   canon ingest records
   canon ingest plans
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-init.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-init 1  "init 0.29.0" 
+.TH canon-init 1  "init 0.31.0" 
 .SH NAME
 canon\-init \- Set up canon in a repo (canon.yaml, a starter policy, the AGENTS.md block, a plans home)
 .SH SYNOPSIS
@@ -95,4 +95,4 @@ it installs nothing and says how to choose. The answer is recorded as
 Rerunning in a repo that has canon.yaml leaves canon.yaml and .canon/policy.yaml
 alone and only refreshes the canon block in AGENTS.md.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-inventory-sync.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-inventory-sync 1  "sync 0.29.0" 
+.TH canon-inventory-sync 1  "sync 0.31.0" 
 .SH NAME
 canon\-inventory\-sync \- Validate each spec root, then materialize scenario index records
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-inventory.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-inventory 1  "inventory 0.29.0" 
+.TH canon-inventory 1  "inventory 0.31.0" 
 .SH NAME
 canon\-inventory \- Index a validated .feature corpus into the scenario ledger
 .SH SYNOPSIS
@@ -36,4 +36,4 @@ Print version
 canon\-inventory\-sync(1)
 Validate each spec root, then materialize scenario index records
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ledger-compact.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ledger-compact 1  "compact 0.29.0" 
+.TH canon-ledger-compact 1  "compact 0.31.0" 
 .SH NAME
 canon\-ledger\-compact \- Move superseded versions of every record out of the ledger into the archive
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-ledger.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-ledger 1  "ledger 0.29.0" 
+.TH canon-ledger 1  "ledger 0.31.0" 
 .SH NAME
 canon\-ledger \- Keep the ledger to the current version of each record
 .SH SYNOPSIS
@@ -51,4 +51,4 @@ this is for a ledger written before 0.23, or after an interrupted move. Idempote
 `canon migrate` runs it. A record that carries a standing claim (a flagged overlay, a
 brief override, an approval at the current evidence) stays in the ledger.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-migrate.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-migrate 1  "migrate 0.29.0" 
+.TH canon-migrate 1  "migrate 0.31.0" 
 .SH NAME
 canon\-migrate \- Bring a repo from an earlier canon up to date: the 0.17 layout (specs, changes, approvals, skills, .gitignore), the 0.28 hooks, scripts and skill stub (backed up under .canon/migrate\-backup/), the 0.23 latest\-only ledger (superseded versions to .canon/archive) and 0.23 review pins
 .SH SYNOPSIS
-\fBcanon migrate\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-commit\fR] [\fB\-\-plan\-digest\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+\fBcanon migrate\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-commit\fR] [\fB\-\-plan\-digest\fR] [\fB\-\-revert\fR] [\fB\-\-backup\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
 .SH DESCRIPTION
 Bring a repo from an earlier canon up to date: the 0.17 layout (specs, changes, approvals, skills, .gitignore), the 0.28 hooks, scripts and skill stub (backed up under .canon/migrate\-backup/), the 0.23 latest\-only ledger (superseded versions to .canon/archive) and 0.23 review pins
 .SH OPTIONS
@@ -35,6 +35,12 @@ Act on the previewed plan; needs \-\-plan\-digest
 \fB\-\-plan\-digest\fR \fI<DIGEST>\fR
 The `planDigest` the preview printed; the run acts only if the plan recomputed now has this digest
 .TP
+\fB\-\-revert\fR
+Undo the last committed migrate (restores what it backed up, undoes its moves and its Postgres and R2 re\-keying); previews first, `\-\-commit \-\-plan\-digest` acts
+.TP
+\fB\-\-backup\fR \fI<DIR>\fR
+With \-\-revert, the backup directory to restore (default: the newest under .canon/migrate\-backup/)
+.TP
 \fB\-\-json\fR
 Output JSON instead of the human\-readable form
 .TP
@@ -50,6 +56,8 @@ Print version
 Examples:
   canon migrate
   canon migrate \-\-commit \-\-plan\-digest <DIGEST>
+  canon migrate \-\-revert
+  canon migrate \-\-revert \-\-commit \-\-plan\-digest <DIGEST>
 
 The bare run prints the plan and its planDigest and writes nothing; \-\-commit \-\-plan\-digest applies exactly that plan. Idempotent:
 a second run finds nothing to move, and a run that stopped partway is finished
@@ -81,9 +89,23 @@ by the next one.
 \- Reviews written before 0.23 are re\-pinned to what their evidence says: a
   review current under the old rule stays current, a stale one stays stale.
 
+\-\-revert undoes a committed run: before it acts, \-\-commit copies everything it may touch
+(canon.yaml, .gitignore, .canon/ with hot.db, the spec roots, openspec changes, hooks and
+skill) and the git index entries of those paths under .canon/migrate\-backup/<timestamp>/.
+\-\-revert restores that state (files moved back, files it wrote removed, the git mv\*(Aqs undone,
+hot.db restored) and gives Postgres rows and R2 objects their old keys from the plan\*(Aqs
+recorded ones (set the DSN variable the canon.yaml names). It restores the newest backup, or
+the one \-\-backup names, previews first like the migrate, and discards anything written
+under those paths since the migrate.
+
 Refuses (exit 2, nothing written) on uncommitted changes under a path it
 moves, on a destination that already exists, on a change directory that could
 stop halfway, and on a canon.yaml edit it cannot make with every other byte
 kept. canon.yaml is written atomically.
+\- Change briefs in the 0.30 format (`canon:` comments, Korean headings) are rewritten to the 0.31
+  format: comments gone, waivers in the frontmatter, headings in English. The plan says first whether it
+  re\-binds an `Approved:` digest or a chore review pin; then `\-\-commit` is the human\*(Aqs (HUMAN_ONLY for
+  every agent role). `\-\-revert` restores them byte for byte and refuses, naming the file, when one changed
+  since the migrate.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-plugin-sync.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-plugin-sync 1  "sync 0.29.0" 
+.TH canon-plugin-sync 1  "sync 0.31.0" 
 .SH NAME
 canon\-plugin\-sync \- Validate and write a plugin\*(Aqs overlay records
 .SH SYNOPSIS
@@ -50,4 +50,4 @@ Print version
 <\fIPLUGIN_ID\fR>
 A .canon/plugins/<id>/plugin.yaml manifest id (e.g. porting)
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-plugin.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-plugin 1  "plugin 0.29.0" 
+.TH canon-plugin 1  "plugin 0.31.0" 
 .SH NAME
 canon\-plugin \- Sync plugin overlay records onto the ledger
 .SH SYNOPSIS
@@ -36,4 +36,4 @@ Print version
 canon\-plugin\-sync(1)
 Validate and write a plugin\*(Aqs overlay records
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-policy-approve.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-policy-approve 1  "approve 0.29.0" 
+.TH canon-policy-approve 1  "approve 0.31.0" 
 .SH NAME
 canon\-policy\-approve \- Approve the current .canon/policy.yaml (written directly; nothing to promote)
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-policy-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-policy-show 1  "show 0.29.0" 
+.TH canon-policy-show 1  "show 0.31.0" 
 .SH NAME
 canon\-policy\-show \- Show the policy\*(Aqs digest and its approval (who, when, which bytes)
 .SH SYNOPSIS
@@ -38,4 +38,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-policy.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-policy 1  "policy 0.29.0" 
+.TH canon-policy 1  "policy 0.31.0" 
 .SH NAME
 canon\-policy \- Record who approved the gate\*(Aqs policy (.canon/policy.yaml) and which bytes
 .SH SYNOPSIS
@@ -49,4 +49,4 @@ approval (or whose approval cannot be read) fails closed: `gate check` exits 1
 and `subject move` refuses to ship or reopen; `\-\-override\-reason` does not
 waive it. `canon policy show` reads the approval back.
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-prompt-add.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-prompt-add 1  "add 0.29.0" 
+.TH canon-prompt-add 1  "add 0.31.0" 
 .SH NAME
 canon\-prompt\-add \- Add a prompt bundle from a repository\-local JSON manifest
 .SH SYNOPSIS
@@ -44,4 +44,4 @@ Print help
 <\fINAME@VERSION\fR>
 The bundle to register, `NAME@VERSION`
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-prompt-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-prompt-show 1  "show 0.29.0" 
+.TH canon-prompt-show 1  "show 0.31.0" 
 .SH NAME
 canon\-prompt\-show \- Select a registered prompt bundle version
 .SH SYNOPSIS
@@ -38,4 +38,4 @@ Print help
 <\fINAME@VERSION\fR>
 The bundle to show, `NAME@VERSION`
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-prompt.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-prompt 1  "prompt 0.29.0" 
+.TH canon-prompt 1  "prompt 0.31.0" 
 .SH NAME
 canon\-prompt \- Register and select versioned prompt bundles
 .SH SYNOPSIS
@@ -40,4 +40,4 @@ Examples:
   canon prompt add reviewer@v1 \-\-manifest .canon/reviewer.json
   canon prompt show reviewer@v1 \-\-json
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-purge.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-purge 1  "purge 0.29.0" 
+.TH canon-purge 1  "purge 0.31.0" 
 .SH NAME
 canon\-purge \- Remove allowlisted records older than a cutoff: the bare run previews the removal set and its planDigest, `\-\-commit \-\-plan\-digest <DIGEST>` deletes it
 .SH SYNOPSIS
@@ -67,4 +67,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-query.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-query 1  "query 0.29.0" 
+.TH canon-query 1  "query 0.31.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] 
+\fBcanon query\fR [\fB\-\-as\fR] <\fB\-\-kind\fR> [\fB\-\-since\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-plugin\fR] [\fB\-\-history\fR] [\fB\-\-change\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
@@ -72,13 +72,13 @@ The repo to act on (default: the nearest ancestor directory holding a canon.yaml
 \fB\-\-json\fR
 Output JSON instead of the human\-readable form
 .TP
-\fB\-\-plugin\-id\fR \fI<PLUGIN_ID>\fR
+\fB\-\-plugin\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
+\fB\-\-change\fR \fI<CHANGE_ID>\fR
 Scope \-\-kind change/task to one ChangeId (other kinds exit 2)
 .TP
 \fB\-\-status\fR \fI<STATUS>\fR
@@ -108,4 +108,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0

package/man/canon-regime-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-regime-show 1  "show 0.29.0" 
+.TH canon-regime-show 1  "show 0.31.0" 
 .SH NAME
 canon\-regime\-show \- Build a canonical regime key for hook scripts
 .SH SYNOPSIS
@@ -47,4 +47,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.29.0
+v0.31.0