@journeykit/canon 0.17.0 → 0.21.0

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

@@ -103,7 +103,7 @@ this subject and domain — the exact memory step 2 retrieves next time.
 
 ## Status lifecycle + the shipped evidence gate
 
-`canon subject status <id> <state> [--override-reason <text>] [--actor-id <id>]`
+`canon subject status <id> --to <state> [--override-reason <text>] [--reason <text>] [--actor-id <id>]`
 performs a policy-gated transition.
 The legal chain:
 
@@ -111,15 +111,16 @@ The legal chain:
 proposed → specced → building → verifying → shipped
 ```
 
-plus **any state → retired** (a subject can be retired from anywhere).
-Any other transition is rejected by failure class, exits 1, and leaves
-the record UNCHANGED (fail closed).
+plus **shipped → verifying** to reopen a shipped subject (with
+`--reason`, below) and **any state → retired** (a subject can be retired
+from anywhere). Any other transition is rejected by failure class, exits
+1, and leaves the record UNCHANGED (fail closed).
 
 ```bash
-canon subject status subject-domain-loop specced
-canon subject status subject-domain-loop building
-canon subject status subject-domain-loop verifying
-canon subject status subject-domain-loop shipped   # gated — see below
+canon subject status subject-domain-loop --to specced
+canon subject status subject-domain-loop --to building
+canon subject status subject-domain-loop --to verifying
+canon subject status subject-domain-loop --to shipped   # gated — see below
 ```
 
 On success the status updates in place; `--json` prints the updated
@@ -148,29 +149,34 @@ empty set; so is one whose `scenario` records route away from the
 gate's rung. Each refusal prints by failure class (`uncovered-cell`),
 exits 1, and the status stays `verifying`. `retired` is not gated.
 
-**The brief (0.16, 0.17):** `verifying → shipped` also refuses where a brief
+**The brief (0.16, 0.17, 0.19):** `verifying → shipped` also refuses where a brief
 exists and is not approved, read exactly as `canon status` reads it (one
 shared check, so status says `ship` only when this passes): the subject's
 newest adopted change has a canon `.canon/changes/<change>/brief.md`
-with no `Approved:` line outside HTML comments and code fences, or has no
-canon `brief.md` yet but comes from an external openspec plan with a
-`proposal.md` under the plan sources. It runs with or without a policy.
-The refusal is an `unreviewed-promotion` naming the subject, and says
-what to do:
+with no `Approved:` line outside HTML comments and code fences, whose
+`Approved:` line carries a digest the brief's text no longer matches
+(`BRIEF_CHANGED_SINCE_APPROVAL`; the brief was edited after the human
+answered), or has no canon `brief.md` yet but comes from an external
+openspec plan with a `proposal.md` under the plan sources. It also
+refuses while `canon brief check` has blocker findings for that change,
+which include a flow step with no scenario or no failure scenario (the
+coverage rules gate shipping, never approval). It runs with or without
+a policy. The refusal is an `unreviewed-promotion` naming the subject, and
+says what to do:
 
 ```
-canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
-canon subject status: refused — get the human's answer to the brief and record it as its `Approved:` line, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
+canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve --change c-demo --by <the human> --note "<their words>"`
+canon subject status: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
 ```
 
 For an external change with no canon brief yet, the reason reads
 ``.canon/changes/<c>/brief.md does not exist yet: change `<c>` comes from
 the external plan <proposal>, which canon reads and never edits, so its
 approval lives in that canon file`` and the agent will ``create
-.canon/changes/<c>/brief.md holding a `Source: <proposal>` line and
-record their words there as `Approved: <who> <when> — "<their words>"` ``.
+.canon/changes/<c>/brief.md holding a `Source: <proposal>` line, then
+record their words with `canon brief approve --change <c> --by <the human> --note "<their words>"` ``.
 
-Never write the line without the human's answer. When there is no brief to
+Never record the approval without the human's answer. When there is no brief to
 answer (no adopted change, or a newest change with neither a canon
 `brief.md` nor an external `proposal.md`), the move is not refused: it
 prints ``canon subject status: advisory: <id>'s brief is not approved —
@@ -184,9 +190,10 @@ the transition, not the check.
 
 This refusal is a backstop, and so is the evidence one: shipping is not
 the first thing an unapproved brief stops. The agent writes the brief,
-then stops and reports it, and nothing is built or attested for the
-subject until the human answers. `canon evidence add` refuses (exit 1,
-nothing staged) a scenario whose `@subject` owner, or a task whose change
+runs `canon brief check` until it has no blockers, then stops and reports
+it, and nothing is built or attested for the subject until the human
+answers. `canon evidence add` refuses (exit 1, nothing staged) a
+scenario whose `@subject` owner, or a task whose change
 an adopting subject, has an enforced, unapproved brief, through the same
 check; see `canon-gate`.
 
@@ -213,7 +220,7 @@ also refuses a `false-success` (a scenario whose latest audit is
 sampled audit; see `canon-gate`.
 
 ```bash
-canon subject status demo-subject verifying \
+canon subject status demo-subject --to verifying \
   --override-reason "reviewer out until Monday" --actor-id lead
 ```
 
@@ -242,6 +249,39 @@ raised later, a scenario tagged later) still fails the gate. Without
 `require_review`, nothing is printed and nothing changes, except that
 `shipped` still runs the brief check above.
 
+### Reopening a shipped subject (0.18)
+
+A follow-up on a shipped subject (a fix, a review round, a scenario its
+gate now misses) reopens it: reopen, add tasks to the approved change,
+scenario, evidence, review, ship.
+
+```bash
+canon subject status demo-subject --to verifying \
+  --reason "follow-up: the retry path leaks a file handle" --actor-id impl
+```
+
+```
+canon subject status: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; keep the follow-up in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
+canon subject status: demo-subject → verifying — written directly; nothing to promote
+```
+
+- `--reason "<one line>"` is required for `shipped → verifying` and
+  refused on any other transition (exit 2, as is a blank one). The new
+  record carries it with the actor and the change the work goes into:
+  `reopen: { reason: …, change: c-demo, actor: { agent_id: impl } }`. The
+  next status write clears it, as it clears a waiver.
+- Inside the approved scope it needs no human: the subject's newest
+  adopted change's brief is approved, or there is no brief to answer.
+  Otherwise it refuses, exit 1, naming the brief to approve, and
+  `--override-reason` does not waive it:
+  ``unreviewed-promotion demo-subject — shipped → verifying: reopening needs the approved scope, and the brief is not approved — .canon/changes/c-next/brief.md has no `Approved:` line; …``.
+- The review guard does not run on a reopen (it prints `skipped … — a
+  reopen moves the subject back to fix its gaps; shipping again runs
+  it`). `verifying → shipped` afterwards runs every guard above again.
+- `canon status` flags a shipped subject whose gate went red (whatever
+  `verifying → shipped` would now refuse it on) and its only step is
+  this reopen.
+
 ## Adopt flow
 
 Planning docs written outside canon become change/task records via
@@ -255,25 +295,40 @@ canon subject adopt subject-domain-loop-plan \
 ```
 
 A change made with `canon change new` (below) is recorded and adopted
-already, and editing its `tasks.md` needs no import either:
+already. A `tasks.md` in it is an optional work note nothing gates on
+(`canon change new` no longer writes one); an existing one is still read:
 `canon evidence add --task` and `canon gate task` read the file as it is,
 and a flip re-imports that change itself. Run `canon ingest plans` for a
 plan written outside canon, or when `canon query --kind task` must list
 rows nobody has flipped yet.
 
-`adopt` stamps the change's `subject_id` and adds it to the Subject's
-`change_ids`, so `canon query --kind change --change-id …` and `canon
-query --kind subject` agree on the link from both ends. It writes only
-the side that lacks the link, so rerunning it on a linked pair writes
-nothing and exits `0`.
+`adopt` adds the subject to the change's `subject_ids` and the change to
+the Subject's `change_ids`, so `canon query --kind change --change-id …`
+and `canon query --kind subject` agree on the link from both ends. It
+writes only the side that lacks the link, so rerunning it on a linked
+pair writes nothing and exits `0`.
+
+A change may belong to several subjects (0.18). Adopting it under a
+second subject adds that subject, never re-points the change, and says
+so:
+
+```
+canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
+```
+
+Every reader joins a subject to its changes from both sides (the
+subject's `change_ids`, and every change whose `subject_ids` names it):
+the open-blocker rule, the status guard, `canon status`, the brief and
+the evidence refusal. An open blocker on a shared change gates each
+subject it belongs to. A change written before 0.18 names one subject as
+`subject_id`; it reads, and `canon query --kind change --json` shows it,
+as a one-element `subject_ids`.
 
 The two records cannot be written atomically, so the subject is written
-first: its `change_ids` is what the gate reads a subject's adopted
-changes from (`open-blocker`, the status guard), so a half-done adoption
-still has that change's open blockers counted. If the change write then
-fails, `adopt` exits `2`, names the subject that now lists the change,
-and prints `canon subject adopt <change_id> --subject <id>` to complete
-it.
+first: a half-done adoption still has that change's open blockers
+counted. If the change write then fails, `adopt` exits `2`, names the
+subject that now lists the change, and prints `canon subject adopt
+<change_id> --subject <id>` to complete it.
 
 ### Starting a new change: `canon change new`
 
@@ -286,16 +341,21 @@ canon change new add-login --subject auth --title "Add login"
 
 ```
 canon change new: wrote .canon/changes/add-login/brief.md
-canon change new: wrote .canon/changes/add-login/tasks.md
 canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
 ```
 
-- **Writes** canon's own change dir, `.canon/changes/<slug>/`:
-  `brief.md` (`# <title>`, `## Why` holding the title, which imports as
-  the change summary, `## What Changes` with a comment saying what goes
-  there, and a comment naming where the human's `Approved:` line goes,
-  so the file starts unapproved) and `tasks.md` (no rows yet, so the
-  change imports as `proposed`; the openspec checkbox row grammar).
+- **Writes** canon's own change dir, `.canon/changes/<slug>/`, holding
+  `brief.md` only: the PRD skeleton (`# <title>`, then the sections intent,
+  desired outcome, user flow, step detail, acceptance, questions and
+  assumptions, out of scope, each opened by a
+  `<!-- canon:section <key> role=… -->` marker and a hint comment, with
+  the headings in the repo's `language:`), and a comment naming
+  `canon brief approve` as where the human's answer is recorded, so the
+  file starts unapproved. The intent section's first paragraph holds the
+  title, which imports as the change summary. `--kind chore` writes the
+  short chore brief instead (intent, category, invariants, checks, out of
+  scope; see `canon brief` below). No `tasks.md` is written:
+  `canon status` lists each flow step's scenarios instead.
   `.canon/changes/` is canon's native plan source: every plan reader
   reads it with no `plans:` entry, so `canon.yaml` needs no edit and no
   external plans source is needed (see `canon-plan-import`).
@@ -318,9 +378,10 @@ canon change new: recorded change `add-login` adopted into subject `auth` — wr
   exist, or when the slug already has a `.canon/changes/<slug>` dir
   (active or under `.canon/changes/archive/`) or a `change` record.
 
-Add task rows to `tasks.md` as `- [ ] <n> <title>`, and flip each with
-`canon gate task <slug>#<n>` once evidence exists. `canon evidence add
---task` and the flip read `tasks.md` as it is, so a new row needs no
+A `tasks.md` is an optional work note canon never writes and nothing
+gates on. If one exists, rows added as `- [ ] <n> <title>` are flipped with
+`canon gate task <slug>#<n>` once evidence exists; `canon evidence add
+--task` and the flip read the file as it is, so a new row needs no
 `canon ingest plans` run.
 
 A change from an external plan (an openspec change listed under
@@ -328,10 +389,59 @@ A change from an external plan (an openspec change listed under
 `canon subject adopt`) gets its brief as a canon file too:
 `.canon/changes/<change>/brief.md` holding a `Source: <path>` line that
 points at the external document and, once the human answers, the
-`Approved:` line. Canon never edits the external document. Such a
+`Approved:` line that `canon brief approve` writes. Canon never edits the external document. Such a
 pointer `brief.md` is not a change of its own: the native reader skips
 it, so the external source keeps the change, its summary and its tasks.
 
+### The brief: `canon brief`, `canon brief check`, `canon brief approve`
+
+```bash
+canon brief [--change <slug>]                 # state and the next one to three steps; never edits
+canon brief check [--change <slug>] [--json]  # findings; exit 0 clean, 2 blockers, 1 error
+canon brief approve --change <slug> --by <the human> --note "<their words>"
+```
+
+Without `--change`, the repo's only live change is read. The brief is the
+PRD `canon change new` writes; sections are found by their
+`<!-- canon:section <key> role=… -->` marker, never by heading text. A
+brief without markers (written before 0.19) checks as `brief.legacy`, an
+advisory, and is read as before.
+
+- **Blockers (structure, `brief.*`)**: a missing, duplicated or
+  out-of-order section; a flow with no steps or a duplicate step id;
+  step detail that does not match the flow ids in order; leftover
+  placeholders (a hint comment still there, an empty section,
+  `TODO`/`TBD`); a malformed waiver; for a chore, a flow/detail/acceptance
+  section, a category outside `refactor|dependency|build|ci|infra`, or
+  invariants/checks that say only "none". Once the subject is `building`
+  or later, a flow step no scenario points at (`brief.flow-uncovered`) or
+  one with no failure scenario (`brief.flow-no-failure`): these two
+  **gate shipping, never approval**.
+- **Advisories (prose, `prose.*`)**: phrase lists, sentence and
+  paragraph length, and key-sentence marking in `role=normative`
+  sections, for `language: en` and `ko`. Never an authorship verdict.
+- **Waivers**: `<!-- canon:waive <rule-id> <section-key> "<reason>" -->`,
+  one rule in one section, reason required; listed in the output.
+- **`approve`** records the human's answer: it writes
+  `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
+  brief and records the policy approval in the same call. It refuses
+  (exit 2) while the check has structure blockers. Edit the brief
+  afterwards and every reader says `BRIEF_CHANGED_SINCE_APPROVAL` until a
+  human answers again and `approve` runs again. Run it only from the
+  human's answer, with their words as `--note`.
+
+The optional refinement passes that fix findings before the human stop are
+listed in `role-planner.md` in this directory.
+
+A **chore** (`canon change new --kind chore`) changes how the subject is
+built or kept, never what it does. Its brief is intent, category,
+invariants, checks, out of scope; it adds no scenarios, and its evidence
+is the subject's suite run again at the chore commit with
+`canon evidence add --all-scenarios --report <kind>:<path> …`. That
+supersedes the old evidence, which makes the pinned reviews stale, so an
+independent re-review follows. Work that changes behavior is a feature
+change, never a chore.
+
 ## Where are we: `canon status`
 
 ```bash
@@ -365,7 +475,7 @@ uses, so status and the gate cannot disagree about a gap:
   `require_review` on, a `warning:` line counts the in-effect reviews that
   predate review pinning (0.15), checked against the commit each pinned:
   current, stale (named) and undecidable.
-- **Brief** (0.16, 0.17) — for each `building`, `verifying` or `shipped`
+- **Brief** (0.16, 0.17, 0.19) — for each `building`, `verifying` or `shipped`
   subject, and each `proposed` subject whose newest adopted change has a
   brief (a canon `brief.md`, or an external `proposal.md`), a `brief:`
   line under it says whether the brief is approved:
@@ -375,10 +485,16 @@ uses, so status and the gate cannot disagree about a gap:
   change (the last one adopted; a live dir before an archived one), and
   only there: a line that starts with `Approved:` (indent allowed), says
   something after it, and sits outside HTML comments (`<!-- … -->`,
-  multi-line included) and fenced code blocks (```` ``` ```` or `~~~`),
-  written by the agent once the human answers, as
-  `Approved: <who> <when> — "<the human's words>"`. Fixes and follow-ups
-  live as tasks in the approved change, so a newly adopted change is a
+  multi-line included) and fenced code blocks (```` ``` ```` or `~~~`).
+  `canon brief approve` writes it from the human's answer, as
+  `Approved: <who> <when> — "<the human's words>" (brief sha256:<digest>)`,
+  the digest covering the brief without its `Approved:` lines. A brief
+  edited after that reads `brief: not approved (<brief> changed after its
+  approval (BRIEF_CHANGED_SINCE_APPROVAL))` and names the re-approval
+  command: the changed brief needs a new human answer. A line with no
+  digest (written before 0.19) stays approved, with an `advisory:` to
+  re-approve so it binds to the text. Fixes and follow-ups
+  stay in the approved change, so a newly adopted change is a
   new scope: an older change's approval does not cover it. A change from
   an external plan has its brief in the same canon file, with a
   `Source: <path>` line pointing at the external document; an `Approved:`
@@ -392,7 +508,21 @@ uses, so status and the gate cannot disagree about a gap:
   and never edits, so its approval lives in that canon file)``. With a
   canon brief and no line it reads
   ``brief: not approved (<brief> has no `Approved:` line)``.
-  There is no record kind for it; the file is the record.
+  There is no record kind for it; the file is the record. For a brief in
+  the PRD format, `brief check: <n> blocker(s), <n> advisory(ies)` follows
+  (`canon brief` names the next step), then, per flow step of the
+  change, `flow F1` (with ` — <gaps>` when it has no scenario or no
+  failure scenario) and under it each scenario that carries
+  `@flow:<change>.F1` with its title, `[failure]` when it is, its
+  evidence (`yes`/`none`) and its review state.
+- **Red shipped subject** (0.18) — a `shipped` subject that the
+  `verifying → shipped` guard would now refuse, by the guard's own checks
+  (owned scenarios, verdicts, required cases, audits, and, where
+  `require_review` covers `shipped`, reviews and open blockers under
+  `block_on_findings`; a gap its waiver recorded is not counted), prints
+  ``gate: red — <n> <class> (first: <subject>), …; reopen with `canon subject status <id> --to verifying --reason "<why it reopens>" --actor-id <unit>` ``,
+  carries `red: [...]` in `--json`, and that reopen is its only `next:`
+  step. Open blockers count against every subject a change belongs to.
 - **Unowned** — scenarios with no `@subject:` tag.
 - **Audits** — how many scenarios are sampled for
   `spec_coverage.require_audit`, confirmed, owed (no audit or
@@ -425,7 +555,7 @@ uses, so status and the gate cannot disagree about a gap:
   …` (its reason adds "then `canon gate promote`" only under
   `write.promote: manual`); an open blocker → `canon finding close …`; a
   due, unreviewed, evidenced scenario → `canon review add …` from another
-  session; none of these → `canon subject status <id> <next status>`.
+  session; none of these → `canon subject status <id> --to <next status>`.
   Last, unowned scenarios → `canon status`, after tagging them in their
   `.feature` files (status re-indexes the edit; no sync step). With more
   than one `specs.roots[]` entry, every suggested `canon scenario new`
@@ -441,15 +571,17 @@ uses, so status and the gate cannot disagree about a gap:
   unanswered> (an older change's approval does not cover a new scope),
   and the approval is never assumed: `canon evidence add` refuses <id>'s
   scenarios and tasks until it is recorded; once the human answers,
-  <record> and run `canon policy approve --by <the human> --note "<their
-  words>"` ``, where `<record>` is ``record their words as `Approved: <who>
-  <when> — "<their words>"` in <brief>``, or, for an external change,
-  ``create <brief> holding a `Source: <proposal>` line and record their
-  words there as `Approved: <who> <when> — "<their words>"` ``.
+  <record> (one call records the brief and the policy approval)``, where
+  `<record>` is ``record their words with `canon brief approve --change
+  <c> --by <the human> --note "<their words>"` ``, or, for an external
+  change, ``create <brief> holding a `Source: <proposal>` line, then
+  record their words with `canon brief approve --change <c> --by <the
+  human> --note "<their words>"` ``; for a brief edited after its
+  approval, ``re-approve with `canon brief approve …` ``.
   It is the subject's only step, whatever its status: nothing suggests
   `canon feature new`, `canon scenario new`, `canon evidence add`, a
   review or a move-on for it before the human answers, and
-  `canon subject status <id> shipped` refuses on the same check. The
+  `canon subject status <id> --to shipped` refuses on the same check. The
   approval is never assumed. A subject with no brief to answer gets no human step;
   its `brief:` line says
   `not approved (no adopted change; advisory, nothing to approve yet)` or
@@ -457,7 +589,7 @@ uses, so status and the gate cannot disagree about a gap:
   approve yet)`` and nothing is withheld (a `proposed` subject with no
   brief, and a `specced` subject, show no `brief:` line at all). Once nothing blocks, a
   ship-ready verifying subject gets the agent's own
-  `canon subject status <id> shipped`; status never asks a human to ship.
+  `canon subject status <id> --to shipped`; status never asks a human to ship.
 
 Status fails closed rather than suggest progress the gate would refuse:
 
@@ -489,7 +621,7 @@ Status fails closed rather than suggest progress the gate would refuse:
   ],
   "unowned": ["cart.promo.01"],
   "next": [
-    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line and record their words there as `Approved: <who> <when> — \"<their words>\"` and run `canon policy approve --by <the human> --note \"<their words>\"`", "actor": "human" },
+    { "command": "stop and report the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers (one answer approves brief and policy)", "why": "promo: .canon/changes/c-promo/brief.md does not exist yet: change `c-promo` comes from the external plan openspec/changes/c-promo/proposal.md, which canon reads and never edits, so its approval lives in that canon file (an older change's approval does not cover a new scope), and the approval is never assumed: … once the human answers, create .canon/changes/c-promo/brief.md holding a `Source: openspec/changes/c-promo/proposal.md` line, then record their words with `canon brief approve --change c-promo --by <the human> --note \"<their words>\"` (one call records the brief and the policy approval)", "actor": "human" },
     { "command": "canon finding close --change-id c-cart --round 1 --seq 1 --disposition fixed --resolution-sha <sha> --actor-id <unit> --session-id <session>", "why": "cart: 1 open blocker finding(s) (first: …); fix it, commit, then close it", "actor": "agent" },
     { "command": "canon review add --project-id root --scenario-id cart.add.02 --reviewer <reviewer> --actor-id <reviewer> --session-id <review-session> --role reviewer --pin <sha> --original-spec-ref \"<feature file>\"", "why": "cart: 1 of 2 scenario(s) lack a qualifying review; …", "actor": "agent" },
     { "command": "canon status", "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again: …", "actor": "agent" }
@@ -513,7 +645,12 @@ plan document the change comes from (the canon brief's `Source:` line,
 or, before that file exists, the external `proposal.md`; omitted for a
 canon-written change); `approval` the text after `Approved:`; and
 `enforced` whether the missing approval blocks (a brief exists to
-answer). The 0.16 `proposal` field is gone.
+answer). The 0.16 `proposal` field is gone. `changed` (omitted when
+false) says the brief was edited after its approval, `legacyApproval`
+that the `Approved:` line carries no digest, `findings` is
+`{ "blockers", "advisories" }` from `canon brief check` (PRD briefs
+only), and `flow` lists each flow step as `{ "id", "change",
+"scenarios": [{ id, title, failure, evidenced, review }], "gaps" }`.
 
 Each `next` entry's `actor` is `agent` (its `command` is a canon command
 line) or `human` (its `command` says what to get from the human).

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

@@ -0,0 +1,80 @@
+# Role: implementer
+
+You build inside an approved scope: scenarios, code, tests and evidence.
+Declare the role with `CANON_ROLE=implementer` (or `--as implementer`).
+Build nothing before the brief is approved: `canon evidence add` refuses an
+unapproved brief's scenarios. If it is not approved, say so and wait; the
+planner and the human own that.
+
+## Commands
+
+Every line is complete; fill the `<placeholders>`. `<root-id>` is the `id` of
+a `specs.roots[]` entry in `canon.yaml` (`root` by default).
+
+```bash
+canon status --as implementer --json                  # once, at the start
+canon feature new <area>.<surface> --title "<title>" --as implementer --json
+canon scenario new <area>.<surface>.<nn> --subject <subject-id> --flow <F-id> --case <happy|edge|failure> --title "<title>" --as implementer --json
+canon scenario new --from - --as implementer --json     # many at once: NDJSON on stdin, one {"id","title","subject","flow","case",…} per line
+canon evidence add --project-id <root-id> --all-scenarios --report <junit|cucumber|swift-testing>:<path> --kind test-run --role implementer --ref "<test command>" --actor-id <unit> --session-id <session> --as implementer --json
+canon evidence add --project-id <root-id> --scenario-id <id> --artifact <path> --kind test-run --role implementer --ref "<what it shows>" --actor-id <unit> --session-id <session> --as implementer --json
+canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <unit> --actor-id <unit> --session-id <session> --summary "<defect>" --as implementer --json
+canon inventory sync --as implementer --json          # only after a write printed NOT refreshed
+canon gate promote --as implementer --json            # only with write.promote: manual
+```
+
+After the first `status`, follow `meta.next` of each write; do not call
+`canon status` again to learn the next step.
+
+## Steps
+
+1. **Scenarios.** One `feature new` per feature surface, then one
+   `scenario new` per behavior (several at once with `scenario new --from -`:
+   one JSON object per line, validated all-or-nothing), each pointing at the brief's flow step it
+   proves, with failure paths (`--case failure`) as well as `happy` and
+   `edge`. When the gate asks for a missing case (`require_cases`), add a new
+   scenario; never retag an existing one. Every bug fix adds or extends a
+   scenario. Canon indexes added, edited or deleted `.feature` files itself;
+   run `inventory sync` only when a command prints `NOT refreshed` (a format
+   violation or a duplicate id: it names each problem). Specs live at
+   `<root>/kind=feature/area=<area>/<surface>.feature` under a `specs.roots[]`
+   root (default `.canon/specs`); `reference/canon-authoring.md` has the
+   scaffold.
+2. **Units.** Give each unit its own actor id and session id and pass them on
+   everything it records. A delegated unit attests its own work; never attest
+   another unit's work under your id.
+3. **Code and tests.** Name tests by scenario id (`game.run.01: …`) so a test
+   report binds to its scenario. Record a defect you find in your own work
+   with `finding add` the moment you find it, before review.
+4. **Evidence.** One test run that proves several scenarios is bound once with
+   `--all-scenarios`: one record per indexed scenario owning a case, each with
+   the verdict its own cases show; any refusal writes none. For one scenario
+   use `--scenario-id <id>` (repeatable) with `--report` or `--artifact`.
+   canon stores the bytes in `.canon/artifacts/sha256/` (commit it with the
+   ledger) and `canon gate check` re-checks them, so the working-tree report
+   may be gitignored. For a scenario about what users see, bind the screenshot
+   or recording (`--artifact <path>`). An external evaluator's audit is
+   `--kind audit`; canon never generates one. Evidence for a task of an
+   imported plan (`--task <id>`) must bind the artifact or report that proves
+   the task; a canon command is never that proof.
+5. **Promote.** Under `write: { promote: auto }` (what `canon init` writes)
+   the record is final when `evidence add` returns. Only with
+   `write.promote: manual` (or no `write:` key) follow it with
+   `gate promote`; `meta.next` names it.
+6. **A new record makes a signed review stale.** The add prints the reviewer
+   and the `canon review add … --pin <sha>` that re-pins it; that is the
+   reviewer's call. Do not run it yourself.
+
+## Retry safety
+
+Repeating `evidence add` with identical input returns the existing record
+with `meta.unchanged: true` instead of a duplicate. After a timeout or a lost
+response, run it again.
+
+## Next
+
+When every scenario has evidence, the review is the reviewer's session, in a
+separate process: do not review your own change. A chore adds no scenarios:
+run the suite again and bind it with `--all-scenarios`, which supersedes the
+old evidence and makes pinned reviews stale. Reference:
+`reference/canon-gate.md`.

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

@@ -0,0 +1,76 @@
+# Role: orchestrator
+
+You run the loop across agents and move the subject. You write no brief,
+code or review yourself. Declare the role with `CANON_ROLE=orchestrator` (or
+`--as orchestrator`); your `canon status` also lists the human's steps.
+
+## Commands
+
+Every line is complete; fill the `<placeholders>`.
+
+```bash
+canon status --as orchestrator --json --fields next,waitingOn   # at the start and when resuming
+canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as orchestrator --json
+canon subject status <subject-id> --to <proposed|specced|building|verifying|shipped> --actor-id <unit> --as orchestrator --json
+canon subject status <subject-id> --to verifying --reason "<why>" --actor-id <unit> --as orchestrator --json   # follow-up on a shipped subject
+canon gate check --as orchestrator --json
+```
+
+## Read the state
+
+`canon status` lists the next steps, each with the `role` that takes it
+(`null` for the human), and `waitingOn` counts the steps held by each other
+owner, `human` included. Call it once at the start and when resuming, not
+after a write: after `subject status --to` or `brief approve`, the write's
+`meta.next` and `meta.waitingOn` are the status for what it touched.
+
+## Spawn each role
+
+Start one agent per role with `CANON_ROLE` set in its environment, and tell
+it to load only `reference/role-<role>.md`:
+
+```bash
+CANON_ROLE=planner     <harness> "<task: the request, the subject, the brief to write>"
+CANON_ROLE=implementer <harness> "<task: change <slug>, scenarios and evidence>"
+CANON_ROLE=reviewer    <harness> "<task: change <slug>; review it>"
+```
+
+A subagent tool that cannot set its child's environment (most in-harness
+subagents share yours) passes the role in the task instead: tell the child
+its role, to load only `reference/role-<role>.md`, and to pass `--as <role>`
+on every canon call (or run `export CANON_ROLE=<role>` first in its own
+shell).
+
+Order: planner, then (after the human's answer) implementer, then reviewer.
+Give each a unit: its own `--actor-id` and a session id.
+
+The reviewer is a separate process with its own session id, never your
+session or the implementer's under another label. Start it as a new process
+(a new `codex exec` run, or the harness's subagent), pass nothing of the
+implementer's context, and have it record its real session id as
+`--session-id` (#39). A reviewer that cannot run the tests says so and does
+not sign off.
+
+## Relay the human stop
+
+When `status` or `meta.next` shows a step with `actor: human` (the brief's
+approval), stop everything for that scope, report the brief to the human in
+its language, and wait. Do not start the implementer before the answer.
+Record the answer with `brief approve`. Never approve it yourself and never
+edit the policy to pass the gate. Inside an approved scope never stop for a
+human: fixes, follow-ups and re-reviews go straight to the implementer and
+reviewer in the same change.
+
+## Move the subject
+
+Move along `proposed → specced → building → verifying → shipped` with
+`subject status --to`. It refuses a move the policy does not allow (missing
+evidence or reviews, open blockers, an unapproved brief); fix the gap rather
+than overriding. Move to `shipped` yourself once its guard passes, unless the
+brief says the human ships. A follow-up on a shipped subject goes back to
+`verifying` with `--reason`, then the implementer and reviewer in the same
+change, then `--to shipped` again. `canon status` flags a shipped subject
+whose gate went red. A bad `--to` fails with `error.field` `--to` and
+`error.expected` listing the states.
+
+Reference: `reference/canon-subject.md`.