@journeykit/canon 0.16.0 → 0.17.0

package/dist/skills/SKILL.src.md

@@ -25,7 +25,7 @@ a feature, a one-line request included. A human is needed once per scope:
   `.canon/policy.yaml` (written by `canon init`), which is what the gate
   grades the work against. When the human answers, record both at once:
   an `Approved: <who> <when> — "<the human's words>"` line in the change's
-  `proposal.md`, and
+  `.canon/changes/<slug>/brief.md`, and
   `canon policy approve --by <the human> --note "<their words>"`. Never
   approve without a human answer, and never edit the policy to make the
   gate pass.
@@ -44,17 +44,21 @@ work inside an approved scope, never to the approval itself.
 
 1. **Brief.** For a new subject or a scope change, write down the request
    verbatim, your assumptions, and the questions you could not ask. It
-   becomes the change's `openspec/changes/<slug>/proposal.md`, which
-   `canon change new <slug> --subject <id> --title "…"` scaffolds once the
-   subject exists (step 2). Once it is there, stop and report the brief,
+   becomes the change's `.canon/changes/<slug>/brief.md`, which
+   `canon change new <slug> --subject <id> --title "…"` writes once the
+   subject exists (step 2). A change that comes from an external plan the
+   human prepared (an openspec `proposal.md` read through
+   `plans.sources`) gets its brief there too: a `brief.md` whose
+   `Source: <path>` line points at the plan; canon never edits the plan.
+   Once the brief is there, stop and report it,
    asking the human once for the brief and the policy; go on to step 3
    only after the human answers, and record the answer as above. Inside an
    approved scope there is no new brief: go to step 3 under the existing
    subject and change.
 2. **Subject.** `canon subject new <id> --domain <domain> --title "…"`, then
    `canon change new <slug> --subject <id> --title "…"`, and put the brief in
-   the change's `proposal.md`. For a new subject or a scope change, this is
-   where you stop until the human answers (step 1).
+   the `.canon/changes/<slug>/brief.md` it writes. For a new subject or a
+   scope change, this is where you stop until the human answers (step 1).
 3. **Scenarios.** `canon feature new <area>.<surface> --title "…"`, then one
    `canon scenario new <area>.<surface>.<nn> --subject <id> --case <case> --title "…"`
    per behavior, with failure paths (`--case failure`) as well as `happy`
@@ -66,7 +70,10 @@ work inside an approved scope, never to the approval itself.
    one of them prints `NOT refreshed` (a format violation, such as a
    hand-written header with no `# canon:` provenance comment, or a
    duplicate id) run `canon inventory sync`: it names each problem; fix
-   them, and the next command indexes the files.
+   them, and the next command indexes the files. Specs live at
+   `<root>/kind=feature/area=<area>/<surface>.feature` under a
+   `specs.roots[]` root (default `.canon/specs`); a root still on
+   `features/kind=feature/` is refused until you run `canon migrate`.
 4. **Units.** Split the work into units (for example specs, domain code,
    assets, review). Give each unit its own actor id and session id, and pass
    them on everything the unit records (`--actor-id <unit> --session-id <session>`),
@@ -114,12 +121,14 @@ work inside an approved scope, never to the approval itself.
    blocker findings); fix the gap rather than overriding, and finish with
    `canon gate check` clean. A root whose `.feature` edits could not be
    indexed fails the gate and refuses `shipped` (`uncovered-cell <root>`;
-   see step 3). `shipped` also refuses while the change's `proposal.md`
-   has no `Approved:` line, and `canon evidence add` refuses the subject's
-   scenarios and tasks the same way. Both are backstops: the stop itself
-   is at step 1, so you never reach them for a brief the human has not
-   answered. You record the line only from the human's answer (with no
-   `proposal.md` there is no brief to answer: neither refuses, and the
+   see step 3). `shipped` also refuses while the change's
+   `.canon/changes/<slug>/brief.md` has no `Approved:` line (for a change
+   from an external plan with no canon brief yet, it names the `brief.md`
+   to create with its `Source:` line), and `canon evidence add` refuses the
+   subject's scenarios and tasks the same way. Both are backstops: the stop
+   itself is at step 1, so you never reach them for a brief the human has
+   not answered. You record the line only from the human's answer (with no
+   brief to answer there is nothing to refuse, and the
    ship guard only prints an advisory). Move the subject to
    `shipped` yourself once `canon subject status <id> shipped` passes its
    guard, unless the brief says the human ships. `canon status` shows
@@ -137,13 +146,18 @@ Load only the reference the current step needs.
 ### Setup and provider projection
 
 ```bash
-canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, plans home
-canon skills install                         # detects .claude/.agents|.codex/.omp/.pi; if none exists, installs Claude+Codex
-canon skills install --providers=claude,codex,omp,pi
+canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
+canon init --providers=claude,codex          # harnesses for the canon skill; without it init asks on a terminal, else takes the detected .claude/.codex/.omp/.pi
+canon skills install                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing)
+canon skills install --providers=claude,codex,omp,pi   # any subset or none; rewrites skills.providers
 canon skills check                           # read-only drift check
-canon skills doctor                          # diagnostics; never deletes user files
+canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider; never deletes user files
 ```
 
+The harness list lives in `canon.yaml` as `skills: { providers: [...] }`.
+`.agents` alone never selects Codex; `.codex` does. Change the list with
+`canon skills install --providers=<list>`, never by assuming a default.
+
 The canonical bundle is read-only. Claude receives
 `.claude/skills/canon/SKILL.md`; Codex receives
 `.agents/skills/canon/SKILL.md`; OMP receives `.omp/skills/canon/SKILL.md`; and

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

@@ -105,7 +105,7 @@ format-clean scenario, and `canon status`, `canon gate check`,
 index added, edited and deleted `.feature` files before they read. When
 one of them prints `NOT refreshed`, the corpus has a format violation
 (for example a hand-written header with no `# canon:` line) or a
-duplicate id; `canon inventory sync` (or `canon format specs`) names it.
+duplicate id; `canon inventory sync` (or `canon format <root>`) names it.
 Fix it and the next command indexes the files (see `canon-inventory`).
 
 - `--actor <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
@@ -158,7 +158,7 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 ## Worked example
 
 ```
-specs/features/kind=feature/area=checkout/
+.canon/specs/kind=feature/area=checkout/
   cart.feature        # surface: the cart screen
   payment.feature     # surface: the payment step
 ```

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

@@ -3,7 +3,7 @@
 `canon format --check` is canon's read-only format validator over a
 consumer-repo artifact corpus: ledger records (run/drill/review/clear/
 code-review/design-review), divergence events (manifest/review/
-remediation), `features/`, `inventory/`, and `policy.yaml`. It never
+remediation), `kind=feature/` spec files, `inventory/`, and `policy.yaml`. It never
 rewrites or mutates the corpus — it only validates and reports.
 
 ## Running
@@ -17,7 +17,7 @@ a report grouped by failure class in this fixed order:
 
 | Failure class | Meaning | Fix |
 |---|---|---|
-| `layout-grammar` | Wrong Hive path shape — a `features/`/`inventory/` file not under a `kind=<kind>/area=<area>/` prefix, a wrong leaf filename, or `assets.lock`'s ad-hoc format. | Move the file under the correct `kind=…/area=…/` prefix with the expected leaf name. |
+| `layout-grammar` | Wrong Hive path shape — a spec or `inventory/` file not under a `kind=<kind>/area=<area>/` prefix, a wrong leaf filename, or `assets.lock`'s ad-hoc format. A spec root still on the pre-0.17 layout (any `.feature` file under `<root>/features/`) is refused with one violation at path `features`. | Move the file under the correct `kind=…/area=…/` prefix with the expected leaf name. For a pre-0.17 root, run `canon migrate`, which moves `features/kind=feature/` to `<root>/kind=feature/`. |
 | `missing-envelope` | A YAML file (`inventory/`, `policy.yaml`) has no top-level `schema`/`kind`/`at`/`actor` keys. | Add the four envelope keys at the top level. |
 | `missing-provenance` | A `.feature` file's `Feature:`/`Scenario:` header has no `# canon: {...}` comment either directly above it (with its tags, no blank line) or directly below it. | Use `canon scenario new` / `canon feature new`, which stamp it; never hand-type the line. See `canon-authoring`. |
 | `missing-actor` | No structured `actor` object — a bare `by` string, or absent. | Replace `by: <name>` with a structured `actor` object. |

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

@@ -63,7 +63,7 @@ sync` runs) and says so in one stderr line, silent when the index is
 fresh:
 
 ```
-canon gate check: refreshed the scenario index from 1 changed feature file(s) (specs/features/kind=feature/area=cart/add.feature): 1 record(s) written
+canon gate check: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 A root that fails to sync (format violations, a duplicate id) is named
@@ -77,6 +77,15 @@ the same violation, and `canon status` lists the sync as its only step.
 Fix what the sync lists and run the gate again. See `canon-storage`
 (The scenario index).
 
+A spec root still on the pre-0.17 layout (a `.feature` file under
+`<root>/features/`) fails closed the same way, whether or not the index
+already holds its scenarios: the gate adds `uncovered-cell <root> — spec
+root `<root>` (`<path>`) is on the pre-0.17 layout (…)…; until then its
+scenarios are not graded` and exits 1, the ship guard refuses with the
+same violation, and `canon status` names `canon migrate` as its only
+step. `canon migrate` moves `features/kind=feature/` to
+`<root>/kind=feature/`; run it, then the gate again.
+
 ### The spec-derived worklist (`spec_coverage`, opt-in)
 
 Coverage groups the EVIDENCE corpus, so it can only ever enumerate
@@ -246,19 +255,32 @@ reports it, and builds nothing for that scope until the human answers.
 `canon evidence add` is the backstop for that stop (0.16 M7). It
 refuses (exit `1`, nothing staged or stored) while a subject the record
 attests for has an enforced, unapproved brief: the newest adopted
-change has a `proposal.md` under the openspec plan sources with no
-`Approved:` line (the check `canon status` and the ship guard use; see
+change's canon `.canon/changes/<change>/brief.md` has no `Approved:`
+line, or there is no canon `brief.md` yet but the change comes from an
+external openspec plan with a `proposal.md` under the plan sources (the
+check `canon status` and the ship guard use; see
 `canon-subject`). The subjects are the scenario's `@subject` owner for
 `--scenario-id`, and every subject adopting the task's change for
 `--task`:
 
 ```
-canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — openspec/changes/c-demo/proposal.md has no `Approved:` line, so the human has not answered it
-canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that proposal.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words as `Approved: <who> <when> — "<their words>"` in .canon/changes/c-demo/brief.md
+canon evidence add: refused — stop, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their words as `Approved: <who> <when> — "<their words>"` in that brief.md only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
 ```
 
-A subject with no brief to answer (no openspec source, no adopted change,
-no `proposal.md`) and a scenario no subject owns are unaffected.
+For a change from an external plan with no canon brief yet, the first
+line says instead ``.canon/changes/c-ext/brief.md does not exist yet:
+change `c-ext` comes from the external plan
+openspec/changes/c-ext/proposal.md, which canon reads and never edits, so
+its approval lives in that canon file, so the human has not answered it;
+once they do, create .canon/changes/c-ext/brief.md holding a `Source:
+openspec/changes/c-ext/proposal.md` line and record their words there as
+`Approved: <who> <when> — "<their words>"` ``. An `Approved:` line in the
+external `proposal.md` itself is never read.
+
+A subject with no brief to answer (no adopted change, or a newest change
+with neither a canon `brief.md` nor an external `proposal.md`) and a
+scenario no subject owns are unaffected.
 `canon review add` and `canon finding add` are never refused.
 `--override-reason "<one line>"` attests anyway, prints the `waived …`
 lines and `override recorded by `<actor>` for the N brief refusal(s)
@@ -298,8 +320,9 @@ review waivers: 1 advisory(ies) — not failing the gate:
 The waiver lasts only until the subject's next status write.
 
 `canon subject status <id> shipped` also refuses where a brief exists and
-has no `Approved:` line (the subject's newest adopted change has a
-`proposal.md`; see `canon-subject`), as an `unreviewed-promotion` naming
+has no `Approved:` line (the subject's newest adopted change has a canon
+`brief.md`, or an external `proposal.md` and no canon `brief.md` yet;
+see `canon-subject`), as an `unreviewed-promotion` naming
 the subject. With no brief to answer it prints an advisory and does not
 refuse. Like the evidence refusal above, it is a backstop: the stop is at
 the brief. `canon gate check` does not grade briefs, so a waived ship
@@ -317,7 +340,10 @@ scenario) that carry no pins were written before 0.15. Each still names
   `scenario_digest`) equals its current digest, and no declared evidence
   record of the scenario is newer than the review. It counts. When the
   scenario lived in another `.feature` file at that commit, the spec
-  root's files at that commit are searched for its id.
+  root's files at that commit are searched for its id, then the files
+  under each of the root's `former_roots` (where `canon migrate` moved
+  it from, e.g. `specs` for a root now at `.canon/specs`). Only the
+  root's own directories are searched, never another root's.
 - **stale** — the scenario changed since the commit, or it has newer
   evidence. It no longer counts, and an in-scope scenario left with no
   other qualifying review is `unreviewed-promotion`:
@@ -489,12 +515,19 @@ empty clean map.
 ## `canon gate task <task_id> [--repo <dir>]`
 
 The evidence-gated task checkbox flip. Resolves `<task_id>`
-(`<change_id>#<n>`) through `canon.yaml`'s `plans:` sources — the first
-configured dialect whose `PlanWriteBack` locates the task's document
-wins, so the flip is plan-dialect agnostic (`openspec` change dirs,
-`superpowers` plan docs). A repo with no `plans:` section falls back to
-the compat default `[{ dialect: openspec, root: <repo> }]`; no source
-locating the task at all is a loud failure naming every source consulted.
+(`<change_id>#<n>`) through `.canon/changes/` (canon's own changes, read
+first whenever the directory exists, with no `plans:` entry) and then
+`canon.yaml`'s `plans.sources` — the first dialect whose `PlanWriteBack`
+locates the task's document wins, so the flip is plan-dialect agnostic
+(canon's own `tasks.md`, external `openspec` change dirs, `superpowers`
+plan docs). A repo with no `plans:` section falls back to the compat
+default `[{ dialect: openspec, root: <repo> }]`; no source locating the
+task at all is a loud failure naming every source consulted. A repo with
+no `.canon/changes/` and `sources: []` is refused: "this repo configures
+no plan sources (no `.canon/changes` and no `plans.sources` entries in
+canon.yaml) … write the change with `canon change new`, or list your
+external plans under `plans.sources`" (`canon dispatch --task` says the
+same).
 It requires
 a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
 with an appended evidence note ONLY on a clean check. The note
@@ -526,6 +559,13 @@ canon gate task my-change#5.2 --repo .
 This is canon's own authority for the checkbox grammar — always flip
 through `canon gate task`, never by hand.
 
+Canon only reads external plans, with this one exception: for a task
+from an external plan source, `canon gate task` flips the checkbox in
+that plan's own `tasks.md` (or plan document). It is the one place canon
+writes into an external plan; their briefs and approvals still live in
+`.canon/changes/<change>/brief.md`. (Open for the maintainer: record
+external flips only in the ledger instead.)
+
 ## `canon gate promote [--repo <dir>] [--dry-run]`
 
 Staging → committed: every well-formed record under

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

@@ -13,7 +13,7 @@ deleted `.feature` files themselves, with the same code this command runs,
 scoped to the changed files, and say so in one stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (specs/features/…): 1 record(s) written
+canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 So the working loop has no sync step and no `canon format` step: write the
@@ -25,12 +25,43 @@ command. Run `canon inventory sync` when:
   comment, an emptied file, …) or a duplicate id, so its files were not
   indexed. `canon gate check` then fails (`uncovered-cell <root>`),
   `shipped` is refused and `canon status` lists only the sync. `canon
-  inventory sync` names each problem (`canon format specs` names the format ones);
+  inventory sync` names each problem (`canon format <root>` names the format ones);
   fix them and the next command indexes the files;
 - `canon status` says the ledger holds no scenario records while the
   `.feature` files hold some (the same refusal, on an index never built);
 - you want the whole index rebuilt from every root at once.
 
+A spec root still on the pre-0.17 layout (a `.feature` file under
+`<root>/features/`) is not refreshed and fails closed the same way: the
+reader names the root and `canon migrate` on stderr and writes no
+tombstones, `canon gate check` fails (`uncovered-cell <root>`) whether or
+not the index already holds its scenarios, `shipped` is refused, and
+`canon status` lists only `canon migrate`. `canon inventory sync` does not
+fix it; run `canon migrate`, which moves `features/kind=feature/` to
+`<root>/kind=feature/`.
+
+`canon migrate --dry-run` prints the plan without writing anything, and
+`canon migrate` applies it. Commit first: it refuses while a path it
+moves has uncommitted changes, and when a destination already exists.
+A root at the repo-level `specs` moves to `.canon/specs`, and
+`canon.yaml` records `former_roots: [specs]`, so reviews pinned before
+the move still find their scenarios. Changes `canon change new` wrote
+under `openspec/changes/` move to `.canon/changes/<slug>/`
+(`proposal.md` becomes `brief.md`). An `Approved:` line in an external
+`proposal.md` is copied into a canon pointer `brief.md`. The command
+also writes `skills.providers` from the install lock, adds the missing
+canon `.gitignore` lines, and ends with a full index rebuild. It is
+idempotent, and a run that stopped partway is finished by the next run:
+`canon.yaml` is written atomically, a half-moved change is completed,
+and the openspec source `canon init` wrote is removed only after every
+pointer brief is written and nothing unread is left under
+`openspec/changes/` (each unread directory is named).
+
+The reader's refresh treats a file as stale when its latest index
+generation has another `source_digest` or `scenario_digest`. A
+generation written before 0.15 has no `scenario_digest`, so a repo that
+kept an old index gets it rewritten on the first read.
+
 ## Where the index sits in the loop
 
 ```
@@ -66,7 +97,7 @@ Per configured root, in order:
 1. **Validate** — runs `canon format --check` over the root. ANY violation
    (missing provenance, layout-grammar, …) ABORTS THE WHOLE ROOT: zero
    records written for it, the violation(s) reported. Never a partial sync.
-2. **Scan** — walks `<root>/features/**/*.feature`, pairing each
+2. **Scan** — walks `<root>/kind=feature/area=<area>/<surface>.feature`, pairing each
    `@<area>.<surface>.<nn>` tag with its header label as `title` and a
    `source_digest` (sha256 over the raw `.feature` bytes). `@subject:<id>`
    → `subject_id`, `@lane:<v>` → `lane`, `@case:<v>` → `case` (first tag
@@ -100,7 +131,10 @@ specs:
       root: apps/b/specs
 ```
 
-- **Absent `specs:` key** → the single default root `{id: root, root: specs}`.
+- **Absent `specs:` key** → the single default root
+  `{id: root, root: .canon/specs}`, the one `canon init` writes. An entry
+  with no `root:` also resolves to `.canon/specs`. The default root is
+  authored and git-tracked; no canon gitignore line covers it.
 - **Present `specs:` with an empty/missing `roots[]`** → fails LOUD; a
   present-but-incomplete config never silently resolves to zero roots.
 - **A malformed entry** (missing `id`, `roots` not a list, `id` not a
@@ -113,6 +147,10 @@ specs:
 
 - **A `canon format --check` validation violation** in the root's corpus →
   whole root aborts, 0 writes, violations reported.
+- **A root on the pre-0.17 layout** (a `.feature` file under
+  `<root>/features/`) → a `layout-grammar` violation at path `features`;
+  the root aborts, 0 writes, exit 1. Run `canon migrate`. An empty
+  leftover `features/` directory is not a refusal.
 - **A duplicate `scenario_id`** within one root → that root aborts, 0
   writes, reported as a sync error (a distinct lane from fmt violations).
 

package/dist/skills/reference/canon-plan-import.md

@@ -1,13 +1,34 @@
 # canon-plan-import
 
-`canon ingest plans` imports a FOREIGN plan dialect's on-disk state into
-canon's `change`/`task` records, through the same validated path every
-other ingest family uses. Imported rows carry no special marker — once
+`canon ingest plans` imports plan state into canon's `change`/`task`
+records, through the same validated path every other ingest family uses:
+canon's own changes under `.canon/changes/`, and any FOREIGN plan dialect
+listed in `canon.yaml`. Imported rows carry no special marker — once
 imported, `canon query` cannot tell an imported row from a hand-authored
 one, and neither can `canon gate`.
 
-## 1. Configure a `plans:` source
-
+## 1. Canon's own changes and external `plans:` sources
+
+`.canon/changes/` is canon's native plan source (dialect id `canon`):
+one `<slug>/` directory per change holding `brief.md` and `tasks.md`,
+written by `canon change new` (see `canon-subject`). Every plan reader —
+`canon ingest plans`, `canon gate task`, `canon evidence add --task`,
+`canon dispatch --task`, `canon status` and the brief check — reads it
+first whenever the directory exists, with no `plans:` entry. Being first,
+it owns a change id an external source also carries (the external copy
+is the later duplicate, skipped and counted under `duplicate_change_id`).
+Its records carry the actor `canon-plan-import-canon`; an external
+openspec change's carry `canon-plan-import-openspec`. A `brief.md` with a
+`Source: <path>` line is not a change of its own: it is the canon brief
+of a change imported from an external plan (it points at the external
+document and holds the human's `Approved:` line), so the native reader
+skips that directory and the external source keeps the change id.
+
+`plans.sources` lists only EXTERNAL plans — documents you prepare outside
+canon, which canon only reads. The one exception: `canon gate task`
+flips the task's checkbox in an external plan's `tasks.md` (see
+`canon-gate`). Their briefs and approvals live in
+`.canon/changes/<change>/brief.md`, never in the external document.
 `canon.yaml`:
 
 ```yaml
@@ -17,17 +38,22 @@ plans:
       root: .              # resolved relative to canon.yaml's directory
 ```
 
-- `canon init` writes exactly this source, plus an empty
-  `openspec/changes/` (so the adapter never scans the repo root itself).
-- An absent `plans:` section = zero sources (a clean no-op).
+- `canon init` writes `sources: []`, preceded by comments explaining
+  `.canon/changes/` and commented examples for `openspec` (`root: .`) and
+  `superpowers` (`root: docs/superpowers/plans`). It creates no
+  `openspec/changes/` directory.
+- An absent `plans:` section = zero external sources (a clean no-op;
+  `.canon/changes/` is still read).
 - A present section parses STRICTLY: a typo'd key, an unregistered
   `dialect`, or a nonexistent `root` fails the command loud, naming the
-  offender.
+  offender. `canon` is not a registered dialect: a source naming it is
+  refused, since `.canon/changes/` needs no entry.
 - `root` is whatever the dialect's adapter scans — for `openspec`, a
   repo root containing `openspec/changes/`, or that changes dir directly.
 
-One-shot override (bypasses `canon.yaml` for a single ad hoc import;
-either flag alone fails loud):
+One-shot override (bypasses `canon.yaml` and `.canon/changes/` for a
+single ad hoc import, reading only the source it names; either flag alone
+fails loud):
 
 ```bash
 canon ingest plans --dialect openspec --source ../other-repo
@@ -36,7 +62,7 @@ canon ingest plans --dialect openspec --source ../other-repo
 ## 2. Run the import
 
 ```bash
-canon ingest plans                 # canon.yaml-driven, every configured source
+canon ingest plans                 # .canon/changes/ + every configured source
 canon ingest plans --json          # machine-readable outcome
 canon ingest plans --repo ../svc   # a specific repo root
 ```
@@ -60,9 +86,19 @@ canon query --kind task [--json]
 No dialect/plugin filter exists or is needed — an imported `change`/
 `task` is an ordinary core record.
 
+## The `canon` dialect (`.canon/changes/`)
+
+Uses the `openspec` change-dir grammar below, with three differences:
+the brief is `brief.md` (its `## Why` first paragraph is the summary; a
+missing one is a `missing-brief-md` malformed dir), the source root is
+always `.canon/changes/` itself (archived changes under
+`.canon/changes/archive/`), and a `brief.md` carrying a `Source:` line is
+skipped (a pointer brief, above). `tasks.md` uses the same checkbox row
+grammar.
+
 ## The `openspec` dialect
 
-Maps `openspec/changes/**` onto core kinds:
+Maps an external `openspec/changes/**` onto core kinds:
 
 | openspec construct | Core mapping |
 | --- | --- |
@@ -76,7 +112,9 @@ Maps `openspec/changes/**` onto core kinds:
 A missing/unreadable `proposal.md`, or a basename that isn't a valid
 `change_id`, skips the WHOLE dir (counted `malformed`); siblings
 unaffected. A proposal-only dir imports as `Change { status: proposed }`
-with zero tasks and zero diagnostics.
+with zero tasks and zero diagnostics. An `Approved:` line in an external
+`proposal.md` is not read: the change's approval lives in
+`.canon/changes/<change>/brief.md` (see `canon-subject`).
 
 ## The `superpowers` dialect
 
@@ -136,9 +174,10 @@ downstream reader's job.
 
 ## What this skill does NOT cover
 
-- **Authoring an openspec change dir** (`proposal.md`/`tasks.md`
-  conventions) — `canon change new` scaffolds one and adopts it into a
-  subject (see `canon-subject`); this skill covers IMPORTING that shape.
+- **Authoring a change** — `canon change new` writes
+  `.canon/changes/<slug>/brief.md` and `tasks.md` and adopts the change
+  into a subject (see `canon-subject`); it never scaffolds an openspec
+  change dir. This skill covers IMPORTING plans.
 - **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-
   a-time path this complements at bulk) — see `canon-gate`.
 - **Wiring an imported `Task`/`Change` into a `canon gate` decision** —

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

@@ -192,6 +192,29 @@ write (promote: manual)`, or `[FAIL] write: …`. `canon gate promote` still
 works under `auto` and is idempotent: with nothing staged it prints
 `nothing staged` and exits `0`.
 
+## Harnesses: the `skills:` section
+
+`canon.yaml`'s `skills:` section names the harnesses the canon skill is
+installed for (0.17):
+
+```yaml
+skills:
+  providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
+```
+
+`canon init` writes it: on a terminal it asks, with the harnesses whose
+`.claude`, `.codex`, `.omp` or `.pi` directory exists checked;
+`--providers a,b` (or `none`) answers without asking; with neither it takes
+the detected ones, and with none detected it writes only a commented example
+and installs nothing. `.agents` alone never selects Codex. `canon skills
+install|check|doctor` follow the section; `canon skills install
+--providers=<list>` rewrites it in place. Without the section they use the
+install lock's providers, then the detected ones; nothing undetected is ever
+added. A present section that is not this shape, or names another harness,
+fails those commands (exit `1`), and `canon init --check-config` reports
+`[PASS] skills (providers: …)`, `[not configured] skills (…)`, or
+`[FAIL] skills: …`.
+
 ## The scenario index
 
 `canon inventory sync` materializes one `Scenario` record per
@@ -207,7 +230,7 @@ that no `.feature` file of it declares any more. The reader then runs
 covers the whole root) and prints one stderr line:
 
 ```
-canon status: refreshed the scenario index from 1 changed feature file(s) (specs/features/kind=feature/area=cart/add.feature): 1 record(s) written
+canon status: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 A deleted scenario is not erased: `canon inventory sync` — and a reader's

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

@@ -148,27 +148,39 @@ 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):** `verifying → shipped` also refuses where a brief
+**The brief (0.16, 0.17):** `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 `proposal.md` under the openspec plan sources,
-and it carries no `Approved:` line outside HTML comments and code fences.
-It runs with or without a policy. The refusal is an `unreviewed-promotion`
-naming the subject, and says what to do:
+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:
 
 ```
-canon subject status: unreviewed-promotion demo-subject — verifying → shipped: brief not approved — openspec/changes/c-demo/proposal.md has no `Approved:` line; a human must answer the brief, and the agent records `Approved: <who> <when> — "<their words>"` there only from that answer
+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
 ```
 
+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>"` ``.
+
 Never write the line without the human's answer. When there is no brief to
-answer (no openspec plan source, no adopted change, or a change with no
-`proposal.md`), the move is not refused: it prints
-`canon subject status: advisory: <id>'s brief is not approved — <why>, so
-there is no brief to answer and shipping is not refused`, and status shows
-the brief as not approved, as an advisory. `subjects[].brief.enforced` in
-`canon status --json` says which case applies. A brief that says the human
-ships changes who runs the transition, not the check.
+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 —
+its newest adopted change `<c>` has no brief (no
+.canon/changes/<c>/brief.md, no openspec proposal.md), so there is no
+brief to answer and shipping is not refused`` (or `— <id> adopts no
+change, so …`), and status shows the brief as not approved, as an
+advisory. `subjects[].brief.enforced` in `canon status --json` says
+which case applies. A brief that says the human ships changes who runs
+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,
@@ -265,21 +277,33 @@ it.
 
 ### Starting a new change: `canon change new`
 
-For a change that does not exist yet, one command scaffolds it and
-records it adopted:
+For a change that does not exist yet, one command writes it and records
+it adopted:
 
 ```bash
 canon change new add-login --subject auth --title "Add login"
 ```
 
-- **Writes** `openspec/changes/<slug>/proposal.md` (the title is its
-  `## Why`, which imports as the change summary) and `tasks.md` (no rows
-  yet, so the change imports as `proposed`), under the repo's first
-  `openspec` plans source. `canon init` configures that source
-  (`{dialect: openspec, root: .}`), so `canon.yaml` needs no edit.
-- **Reads** the files with the same `openspec` adapter `canon ingest
+```
+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).
+  `.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`).
+- **Reads** the files with the native `canon` plan adapter `canon ingest
   plans` uses, then **records** the change already adopted, through the
-  same write as `canon subject adopt`.
+  same write as `canon subject adopt`. Its records carry the actor
+  `canon-plan-import-canon` (canon-written); an external openspec
+  change's carry `canon-plan-import-openspec`.
 - **What a failure leaves behind.** The files are staged under `.canon/`
   and the change dir is moved into place only once they parse. A failure
   before any record is written (staging, publishing the dir, or the
@@ -291,14 +315,23 @@ canon change new add-login --subject auth --title "Add login"
   plans && canon subject adopt <slug> --subject <id>`, which completes
   the link and is safe to rerun.
 - **Refuses** with exit `2`, writing nothing, when the subject does not
-  exist, when the slug already has a change dir (active or archived) or a
-  `change` record, or when `canon.yaml` has no `openspec` plans source.
+  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
 `canon ingest plans` run.
 
+A change from an external plan (an openspec change listed under
+`plans.sources`, imported by `canon ingest plans` and adopted with
+`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
+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.
+
 ## Where are we: `canon status`
 
 ```bash
@@ -332,23 +365,33 @@ 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) — for each `building`, `verifying` or `shipped`
+- **Brief** (0.16, 0.17) — for each `building`, `verifying` or `shipped`
   subject, and each `proposed` subject whose newest adopted change has a
-  `proposal.md`, a `brief:` line under it says whether the brief is approved:
-  `brief: approved in <proposal.md> — <the recorded words>`, or
-  `brief: not approved (…)`. Approval is an `Approved:` line in the
-  `proposal.md` of the subject's newest adopted change (the last one
-  adopted): a line that starts with `Approved:` (indent allowed), says
+  brief (a canon `brief.md`, or an external `proposal.md`), a `brief:`
+  line under it says whether the brief is approved:
+  `brief: approved in <brief> — <the recorded words>`, or
+  `brief: not approved (…)`. Approval is an `Approved:` line in
+  `.canon/changes/<change>/brief.md` for the subject's newest adopted
+  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
-  new scope: an older change's approval does not cover it. Status reads
-  the line from the change dir under the repo's `openspec` plans sources,
-  in config order (the first source holding the change owns it, a live
-  dir before an archived one; with no `plans:` section, the `openspec`
-  source rooted at the repo that `canon gate task` also falls back to).
+  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:`
+  line inside an external `proposal.md` is not read. Before that canon
+  file exists, an external openspec `proposal.md` under the plan sources
+  (the first source holding the change; with no `plans:` section, the
+  `openspec` source rooted at the repo that `canon gate task` also falls
+  back to) still makes the brief one to answer, and the line reads
+  ``brief: not approved (.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)``. 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.
 - **Unowned** — scenarios with no `@subject:` tag.
 - **Audits** — how many scenarios are sampled for
@@ -372,7 +415,7 @@ uses, so status and the gate cannot disagree about a gap:
   itself first, so this means the refresh refused on a format violation
   or a duplicate id, which the sync names). Then per subject, verifying
   first, then building, specced, proposed, shipped: an unapproved brief
-  (building and later, and proposed once its change has a `proposal.md`)
+  (building and later, and proposed once its change has a brief)
   → the human step below, which is then the subject's
   only step; no scenario → `canon scenario new … --subject <id>` (and, when no
   `.feature` file holds a scenario yet, `canon feature new` first, unless
@@ -389,12 +432,20 @@ uses, so status and the gate cannot disagree about a gap:
   carries `--project`: the owning root for a missing case, `<root-id>`
   (the reason lists the roots) for a subject that owns no scenario yet.
 - **The one human step.** Every step is the agent's to run except one:
-  a subject whose brief is enforced (its newest change has a
-  `proposal.md` with no `Approved:` line) gets
-  `human: stop and report the brief in <proposal.md>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
-  whose reason names that `proposal.md`, says `canon evidence add`
-  refuses the subject's scenarios and tasks until the line is recorded,
-  and names `canon policy approve --by <the human> --note "<their words>"`.
+  a subject whose brief is enforced (its newest change's canon
+  `brief.md` has no `Approved:` line, or it has no canon `brief.md` yet
+  and comes from an external openspec `proposal.md`) gets
+  `human: stop and report the brief in <brief>; build and attest nothing for <id> until the human answers (one answer approves brief and policy)`,
+  where `<brief>` is the canon `brief.md`, or the external `proposal.md`
+  when no canon brief exists yet. Its reason reads ``<id>: <why
+  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>"` ``.
   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
@@ -402,9 +453,9 @@ uses, so status and the gate cannot disagree about a gap:
   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
-  ``not approved (change `<id>` has no proposal.md; advisory, nothing to
+  ``not approved (change `<id>` has no brief; advisory, nothing to
   approve yet)`` and nothing is withheld (a `proposed` subject with no
-  `proposal.md`, and a `specced` subject, show no `brief:` line at all). Once nothing blocks, a
+  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.
 
@@ -424,21 +475,21 @@ Status fails closed rather than suggest progress the gate would refuse:
 
 ```json
 {
-  "statusVersion": 2,
-  "canonVersion": "0.16.0",
+  "statusVersion": 3,
+  "canonVersion": "0.17.0",
   "policy": { "present": true, "spec_coverage": { "require_evidence": true, "scope": [], "exclude_lanes": [], "require_cases": ["failure"], "require_review": { "scope": ["verifying", "shipped"], "distinct_actor": true, "block_on_findings": true } } },
   "warnings": [],
   "subjects": [
     { "id": "cart", "title": "Cart", "status": "building", "scenarios": 2, "excluded": 0, "evidenced": 2, "divergent": 0,
       "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 1, "missingCases": [],
-      "brief": { "approved": true, "enforced": false, "change": "c-cart", "proposal": "openspec/changes/c-cart/proposal.md", "approval": "Journey 2026-10-11 — \"approved\"" } },
+      "brief": { "approved": true, "enforced": false, "change": "c-cart", "brief": ".canon/changes/c-cart/brief.md", "briefExists": true, "approval": "Journey 2026-10-11 — \"approved\"" } },
     { "id": "promo", "title": "Promo", "status": "verifying", "scenarios": 1, "excluded": 0, "evidenced": 1, "divergent": 0,
       "reviewed": 1, "staleReviews": 0, "unsignedReviews": 0, "reviewDue": true, "openBlockers": 0, "missingCases": [],
-      "brief": { "approved": false, "enforced": true, "change": "c-promo", "proposal": "openspec/changes/c-promo/proposal.md" } }
+      "brief": { "approved": false, "enforced": true, "change": "c-promo", "brief": ".canon/changes/c-promo/brief.md", "briefExists": false, "source": "openspec/changes/c-promo/proposal.md" } }
   ],
   "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: its newest adopted change's proposal.md carries no `Approved:` line …", "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 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": "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" }
@@ -451,21 +502,29 @@ Each `missingCases` entry is `{ "projectId", "surface", "case" }`: the
 spec root, the `<area>.<surface>`, and the required case it lacks.
 
 `brief` is present for `building`, `verifying` and `shipped` subjects,
-and for a `proposed` subject whose newest adopted change has a
-`proposal.md`. `change` is the newest adopted change (omitted when the
-subject adopts none), `proposal` its `proposal.md` (omitted when no
-`openspec` source holds one), `approval` the text after `Approved:`, and
-`enforced` whether the missing approval blocks (a `proposal.md` exists to
-carry it).
+and for a `proposed` subject whose newest adopted change has a brief (a
+canon `brief.md` or an external `proposal.md`). `change` is the newest
+adopted change (omitted when the subject adopts none); `brief` its canon
+`.canon/changes/<change>/brief.md`, the one file the approval is read
+from (omitted when the change has no brief to answer); `briefExists`
+(always present) whether that file exists (`false` for an external
+change whose canon brief is still to be created); `source` the external
+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.
 
 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).
 
 `policy.spec_coverage` has the shape `canon context --json` prints
 (`null` when absent, `{"invalid": …}` when unusable). `statusVersion`
-changes only when a field changes meaning or is removed. It is `2`
-since 0.16, when `next[].command` stopped always being a command line
-(`actor` tells which); `brief` was added alongside.
+changes only when a field changes meaning or is removed. It became `2`
+in 0.16, when `next[].command` stopped always being a command line
+(`actor` tells which), and `brief` was added alongside. It is `3` since
+0.17, when `brief.proposal` was removed: the canon `brief.md` is
+`brief.brief`, with `briefExists` and `source`.
 
 `subject new`, `adopt` and `status` write their records directly; the
 human-readable success line ends `— written directly; nothing to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@journeykit/canon",
-  "version": "0.16.0",
+  "version": "0.17.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.16.0",
-    "@journeykit/canon-core-linux-x64": "0.16.0",
-    "@journeykit/canon-core-win32-x64": "0.16.0"
+    "@journeykit/canon-core-darwin-arm64": "0.17.0",
+    "@journeykit/canon-core-linux-x64": "0.17.0",
+    "@journeykit/canon-core-win32-x64": "0.17.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",