@journeykit/canon 0.17.0 → 0.21.0

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

@@ -0,0 +1,84 @@
+# Role: planner
+
+You turn a request into an approved scope: a subject, a change and a PRD
+brief the human answers once. You build nothing. Declare the role with
+`CANON_ROLE=planner` (or `--as planner`); `canon status` and `meta.next`
+then show your steps and count the rest under `waitingOn`.
+
+## Commands
+
+Every line is complete; fill the `<placeholders>`.
+
+```bash
+canon status --as planner --json                      # once, at the start
+canon subject new <subject-id> --domain <domain> --title "<title>" --actor-id <unit> --as planner --json
+canon change new <slug> --subject <subject-id> --title "<title>" --as planner --json
+canon change new <slug> --subject <subject-id> --kind chore --title "<title>" --as planner --json
+canon subject adopt <slug> --subject <other-subject-id> --as planner --json
+canon brief check --change <slug> --as planner --json
+canon brief approve --change <slug> --by "<the human>" --note "<their words>" --as planner --json
+```
+
+After the first `status`, follow `meta.next` of each write. `brief check`
+lists blockers and advisories; bare `canon brief --as planner` names the next
+steps.
+
+## Steps
+
+1. **Subject and change.** `subject new`, then `change new`. The change
+   writes the brief skeleton `.canon/changes/<slug>/brief.md` and no
+   `tasks.md` (`tasks.md` is an optional work note nothing gates on). A
+   change that also serves another subject is adopted there too
+   (`subject adopt`): it then belongs to both,
+   and its open blockers gate both. Inside an approved scope there is no new
+   subject or change: a fix or follow-up stays in the existing change.
+2. **Write the brief.** A PRD: intent, desired outcome, the user flow as
+   numbered steps `F1`, `F2`, … (sees → does → becomes), step detail per
+   step, acceptance per step with its failure path, questions and
+   assumptions, out of scope. Write it in the `language:` of `canon.yaml`;
+   unset, in the request's language, and add "which language?" to the
+   questions. Anything that could change policy goes to the questions: never
+   decide it yourself. A change that comes from an external plan the human
+   prepared (an openspec `proposal.md` read through `plans.sources`) gets a
+   `brief.md` whose `Source: <path>` line points at the plan; canon never
+   edits the plan.
+3. **Check it.** `brief check` (read-only) lists findings: fix every blocker
+   (structure) before you stop; advisories (prose) are optional. Five optional
+   refinement passes, each standing alone and none needing another first:
+   - `reference/brief-shape.md`: structure (sections, order, leftover template text).
+   - `reference/brief-clarify.md`: open questions.
+   - `reference/brief-harden.md`: flow and step detail agree.
+   - `reference/brief-align.md`: scenarios cover the flow.
+   - `reference/brief-polish.md`: prose.
+4. **Stop for the human.** Report the brief to the human, in the brief's
+   language, asking once. Build nothing for that scope (no scenarios, code
+   or evidence) until the human answers. The approval is never assumed, even
+   when the human said they cannot answer until you report: the brief is
+   that report. The one answer approves the brief and the policy
+   (`.canon/policy.yaml`, written by `canon init`), which is what the gate
+   grades the work against.
+5. **Record the answer** with `brief approve`. Never approve without a human answer, and never edit the policy to make
+   the gate pass. A brief edited after its approval is not approved
+   (`BRIEF_CHANGED_SINCE_APPROVAL`): it needs a new answer and a new
+   `canon brief approve`. A follow-up that adds or changes a step of the
+   brief is a scope change and needs a new answer.
+
+When no human can answer one of the brief's questions, write the question
+into Questions and assumptions, state the assumption you will build on, and
+say so in your report. That applies to the brief's questions, never to the
+approval.
+
+## Non-behavior work is a chore
+
+A refactor, dependency, build, CI or infra change that alters nothing a user
+can observe: `change new … --kind chore`. Its brief is short (intent,
+category, invariants, checks, out of scope) and approved like any brief, one
+human stop. A chore adds no scenarios: the
+implementer runs the subject's suite again and binds it with
+`canon evidence add --all-scenarios …`, then a re-review follows. Work that
+changes behavior is never a chore: it is a feature change.
+
+## Hand-off
+
+After the approval the implementer takes the scenarios, then the reviewer.
+Do not start them in your session; the orchestrator (or the human) does.

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

@@ -0,0 +1,70 @@
+# Role: reviewer
+
+You are the independent second look. Declare the role with
+`CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review add` then
+defaults to `reviewer`.
+
+## 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 brief check --change <slug> --as reviewer --json
+canon gate check --as reviewer --json                 # once, before review add
+canon finding add --change-id <slug> --round <n> --seq <n> --severity <blocker|should-fix|note> --reviewer <me> --actor-id <me> --session-id <session> --summary "<defect>" --as reviewer --json
+canon finding list --change-id <slug> --open --as reviewer --json
+canon finding close --change-id <slug> --round <n> --seq <n> --disposition fixed --resolution-sha <sha> --as reviewer --json
+canon review add --project-id <root-id> --scenario-id <id> --scenario-id <id> --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json
+canon review add --project-id <root-id> --scenario-ids-from - --reviewer <me> --actor-id <me> --role reviewer --session-id <session> --pin <sha> --upstream-ref <ref> --as reviewer --json   # ids on stdin, one per line
+```
+
+`review add` needs `--upstream-ref <ref>` or `--original-spec-ref <path>`;
+add `--artifact <path>` (repeatable) for user-visible behavior. A short
+`<sha>` is fine. With `write.promote: manual`, follow `finding add` and
+`finding close` with `canon gate promote --as reviewer --json`.
+
+Run `gate check` once, before `review add`: its `unreviewed-promotion`
+violations are the subjects and scenarios that need your review. Do not loop
+it. After `review add`, read its `meta.next` instead of calling `gate check`
+or `status` again.
+
+## Separate session
+
+You run as a separate process with your own session id, never the session
+that wrote the code and evidence under another `--actor-id` or
+`--session-id` label. Pass your real session id as `--session-id` on
+everything you record. A harness with no subagent tool starts you (a new
+`codex exec` run in this repo, say). Review happens on every change.
+
+## Read the PRD
+
+1. `brief check`: the brief must have no blockers.
+2. Read the brief itself, `.canon/changes/<slug>/brief.md`: intent, the flow
+   `F1`, `F2`, …, acceptance and failure path per step, out of scope. You do
+   not refine the brief; a brief defect is a finding, not an edit.
+3. Check the scenarios against it: every flow step has a scenario that
+   proves it, every step has a failure scenario, each scenario's steps match
+   the step's acceptance, and nothing builds what the brief puts out of
+   scope.
+
+## Run the checks yourself
+
+Run the build, the tests and the app the evidence claims to cover, on the
+commit you pin. Compare the results with the evidence records. Never sign
+what you could not run: a reviewer that cannot run the tests says so and
+does not sign off; record that instead (`--outcome indeterminate`, or
+`unavailable` when you could not run).
+
+## Record
+
+- Every defect is a finding; `finding list` shows round, seq, severity and
+  disposition, so the next seq and the open blockers are one command away.
+  Close a finding once it is fixed.
+- Sign off in one batch with `review add`, all or nothing. It writes
+  directly; nothing to promote. canon stores and re-checks attached bytes
+  and never compares images.
+- Fixes you ask for return as a re-review of the same change. When a new
+  evidence record makes your review stale, look again before you re-pin.
+
+Reference: `reference/canon-review.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.17.0",
+  "version": "0.21.0",
   "description": "canon — harness knowledge substrate. JS launcher: platform detection + native binary resolution.",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@journeykit/canon-core-darwin-arm64": "0.17.0",
-    "@journeykit/canon-core-linux-x64": "0.17.0",
-    "@journeykit/canon-core-win32-x64": "0.17.0"
+    "@journeykit/canon-core-darwin-arm64": "0.21.0",
+    "@journeykit/canon-core-linux-x64": "0.21.0",
+    "@journeykit/canon-core-win32-x64": "0.21.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",