@freetesh/canon 0.0.0-stage → 0.16.0

package/skills/weigh/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: weigh
+description: Decision gate run BEFORE acting on a non-trivial request in a product repo — a new feature, screen or product, a new dependency or library, a migration or rewrite, a schema, money, pricing or store change, a release or deploy, deleting something, or a change that spans more than one product. Weighs the request against the canon constitution, the product's wiki and ADRs, existing features and tasks, cost vs value, and writing less code, then returns do it / do it differently / push back with citations. Also use when the user types /weigh or asks "should we…", "is it worth…", "does this make sense".
+---
+
+# Weigh before acting
+
+You are deciding whether and how to do a request — not doing it yet.
+Request: `$ARGUMENTS` (empty = the user's latest request in this conversation).
+
+## Skip the gate when it is trivial
+
+Answer and act directly, with no verdict block, when **all** are true: one file,
+no new dependency, no schema / money / store / release / delete, and the change is
+fully specified (a typo, a spacing fix, a copy edit the user dictated). A
+product's `.claude/canon.yaml` may tighten this under `weigh.trivial`.
+
+## Steps
+
+1. **Restate the goal** in one line — what outcome the user wants, not the
+   mechanism they named. A named mechanism ("use library X", "move to Firebase")
+   is a proposal to weigh, not a given. Then **list the claims** the request
+   makes or rests on: "users want it", "it will help retention", "it is
+   missing", "it is slow". The request is not a fact (C-14); each claim is
+   checked in step 4.
+
+2. **Rules.** Run `canon standards --constitution` for the principle titles
+   (canon's and any the team added), and read the constitution files that
+   `canon standards` lists — or `../../standards/constitution.md` (relative to
+   this skill) if the CLI is not installed. Note every principle the request
+   touches, by ID. Read a standard from `canon standards` only if the request is
+   in its area.
+
+3. **Domain.** Search before you judge. Run `mcp__plugin_canon_qmd__query` with
+   the goal in plain words, then the key nouns, scoped with `collections` to
+   this product's `<repo>-wiki` and `<repo>-features` (the names `canon init`
+   gives them; add `pack-<name>` when the question is about a vendor's API). Other products' hits are noise here; step 5 is where
+   siblings are searched. Read the top hits with `mcp__plugin_canon_qmd__get`. Look for: an ADR that already
+   decided this, a canonical value it would change, a concept it would break.
+   If qmd is unavailable, read `.context/wiki/index.md` and `decisions/`.
+   **Architecture:** if `.claude/canon.yaml` lists the `architecture` module, read
+   the repo's `.dependency-cruiser.cjs` and its wiki architecture concept page.
+   A request whose code would need an import a rule forbids is DO IT
+   DIFFERENTLY (name the allowed path) or PUSH BACK; one that changes a rule
+   is **too-large** unless a decision page already approves it. Cite the rule
+   by its `name`.
+
+4. **Claims.** Mark each claim from step 1 **backed**, **partly backed** or
+   **not backed**, with the fact and its source. Look in what step 3 read, the
+   code and `.context/raw/`. When that is not enough, look for a data source:
+   query qmd for `SOURCE` pages in this product's wiki. Each says what it holds,
+   how to read it (`mcp:`, `skill:`, `cli:` or `manual:`) and which claims it
+   answers. For `manual:`, ask the user for the numbers and say where to find
+   them; do not guess. If one fits, run its query and follow the query rules in `wiki-schema.md`
+   ("Data sources"): read only, one or two small queries, counts not people.
+   Save a result that decides the verdict to `.context/raw/`. If the tool is not
+   available, say so and leave the claim not backed. If no source fits, name
+   the kind of source that would answer it ("an analytics tool with weekly
+   active users"). Never mark a claim backed because the user said it again.
+
+5. **Duplicates and conflicts.** Check `.context/features/` and `.context/tasks.md`
+   of this product, and the features collections of sibling products in qmd:
+   is this already planned, built, shelved, or in progress elsewhere? Would it
+   conflict with something in `## Now`?
+
+6. **Cost vs value.**
+   - Size: **small** (1 file, < 50 lines) · **medium** (2–5 files, < 200 lines) ·
+     **large** (5+ files) · **too-large** (architecture change — split it).
+   - Ongoing cost: new dependency, new service bill, more to maintain, more to
+     test, store review risk.
+   - Value: name the user or the metric it moves (`metrics/definitions.yml` if
+     the product has one). If neither can be named, say "value unproven". A
+     value claim is checked like any other claim, in step 4.
+   - Evidence: say which evidence from `dev-methods.md` the work must leave — a
+     feature page, a failing test first, or a metric and snapshot.
+
+7. **Write less.** Climb the ladder and stop at the first rung that works:
+   delete it → reuse something in this repo → reuse from a sibling product or
+   shared script → platform or standard library → an existing well-used package
+   → fewer lines → new code. If the `ponytail` plugin is installed, follow its
+   ladder for this step.
+
+8. **Too-large, or the user asked for a second opinion?** Then, and only then,
+   ask the `challenger` agent for an independent read. It costs tens of
+   thousands of tokens, so hand it what you already have: the request, the repo
+   path, your draft verdict, and every file and wiki page you read with one line
+   on what each says. It checks your reasoning and looks only where you did
+   not. Where you and it disagree, show both. A large request is weighed by you
+   alone.
+
+## Verdict
+
+Reply with exactly this block, then stop or proceed as the verdict says:
+
+```
+Verdict: DO IT | DO IT DIFFERENTLY | PUSH BACK
+Goal: <one line>
+Size: small | medium | large | too-large
+Why:
+- <C-xx> <one line> — <file or wiki page cited>
+- ...
+Instead: <only for DO IT DIFFERENTLY — the cheaper or safer way>
+Claims:
+- "<claim>" — backed | partly backed | not backed — <fact and source, or what was searched>
+Assumed: <every claim not backed, or "none">
+Open questions: <only if a real ambiguity blocks a good answer>
+```
+
+- Every bullet under **Why** cites a principle ID and a source (a wiki page, ADR,
+  standard, feature, file or saved query result). A reason with no source is an
+  opinion: drop it, or list it under **Assumed**.
+- **DO IT** only when **Assumed** is "none". Proceed with the work in the same
+  turn.
+- **DO IT DIFFERENTLY** → proceed with the *Instead* version only if the user
+  already accepted it and **Assumed** is "none"; otherwise stop and ask.
+- **PUSH BACK** → stop. Do not start the work, not even a part of it.
+- **Something is assumed** → stop, and give the user three choices: bring the
+  facts (and say where they would go), agree to terms, or drop it. Any terms
+  you show, here or later, are a numbered list, so the user can agree line by
+  line.
+
+Write the whole reply in plain words (C-15): short sentences, common words, no
+jargon the wiki does not define.
+
+## Terms (when the user wants to go on anyway)
+
+When the user wants to go on despite a PUSH BACK or an assumption, write the
+terms as a numbered list: what is in scope, what is out, which rule changes and
+which stays, and how the assumption will be checked later (a metric and a
+date). A fact the user gives in chat is saved to `.context/raw/` first, then
+listed as a fact, not as proof of more than it shows.
+
+Proceed only after the user agrees in writing ("agree", or "agree to 1–4").
+"Go ahead" to a verdict is not agreement to terms that were never shown. Work
+covers only the terms agreed to.
+
+## Logging (every verdict)
+
+Log every verdict once, when you know what happened next. A trivial request
+that skipped the gate is not logged. `--outcome` is one of:
+
+- `proceeded` — work went ahead as the verdict said (DO IT, or an accepted
+  *Instead*).
+- `stopped` — you stopped and asked, and the user has not answered yet. Log it
+  when you stop; if the user later overrides, log a second line.
+- `overridden` — the user went on against a PUSH BACK, rejected a DO IT
+  DIFFERENTLY, or agreed to terms. `--reason` is required: the user's reason,
+  verbatim. Pass each agreed term with its own `--term`.
+- `dropped` — the user chose to drop the request.
+
+```bash
+node ../../scripts/log-verdict.mjs --verdict push-back --outcome overridden \
+  --principles C-04,C-14 --request "<one line>" \
+  --reason "<the user's reason, verbatim>" --term "<term 1>" --term "<term 2>"
+```
+
+(path relative to this skill). It writes to `.context/raw/canon/verdicts.jsonl`
+in the current repo. Never edit or delete existing lines. `canon learn` reads
+the log across products: how often the gate stops work, and which rules keep
+being overridden.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: wiki-lint
+description: Audit .context/wiki/ for drift — broken [[links]], orphan pages, contradictions between entities, stale last-verified dates, unprocessed raw files. Optionally auto-fix safe issues and regenerate .context/wiki/index.md. Usage `/wiki-lint` (audit) or `/wiki-lint --fix` (audit + auto-fix).
+---
+
+You are linting the wiki at `.context/wiki/` against the wiki schema (the `wiki-schema.md` that `canon standards` lists — a team's own replaces canon's; without the CLI, `../../standards/wiki-schema.md` relative to this skill).
+
+Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
+
+## Steps
+
+1. **Read the wiki schema** to refresh the folders, the one test and the caps.
+
+2. **Run `canon check` first** if the CLI is installed. It checks frontmatter,
+   placeholders, caps, dated decision names, duplicate IDs, staleness and
+   prices held by no entity in under a second,
+   plus any checker the repo declares. Start from its output rather than
+   re-deriving it.
+
+3. **Enumerate pages.** List every `.md` file under `.context/wiki/` (excluding `index.md` and `CLAUDE.md`). For each, parse the frontmatter.
+
+4. **Build the graph:**
+   - Map `id → file path`.
+   - For each page, extract all `[[wikilink]]` tokens from the body.
+   - Build inbound and outbound link sets per page.
+
+5. **Run the checks below.** Group findings into **Blockers** and **Warnings**.
+
+### Blockers (must be fixed)
+
+| Check | Rule |
+|---|---|
+| Broken `[[wikilink]]` | Target page does not exist |
+| Duplicate `id` | Two pages claim the same ID |
+| Contradictory canonical value | Two `entity` pages list the same key with different values |
+| Placeholder text | `TBD`, `none yet`: write the fact or delete the section |
+| `type` does not match folder | If a page sets `type`, it lives in that type's folder |
+
+### Warnings
+
+| Check | Rule |
+|---|---|
+| Over a cap | Page 60 lines, decision 30, README 30, tasks 100 |
+| Restates code, a design or git | Delete the lines; link the source instead |
+| Two pages on one topic | Merge into one, edited in place |
+| Stale `last-verified` | > 90 days from today. |
+| Unprocessed raw file | A file under `.context/raw/` that no wiki page references in its `Sources`. |
+| User-facing string violates copy rules | Check quoted copy against the rules in the root `CLAUDE.md`. Best-effort. |
+
+6. **Auto-fix (only if `--fix` is in `$ARGUMENTS`):**
+   - Regenerate `.context/wiki/index.md` from scratch: enumerate pages by type, sort alphabetically by slug, keep the structure the file already has.
+   - Fix `last-verified` to today's date on any page whose body was edited in the working tree.
+   - **Never** auto-fix: contradictory canonical values, broken `[[wikilinks]]`, merges or cuts. These need a human decision.
+
+7. **Report.** Print:
+   - Counts: pages, blockers, warnings, auto-fixes applied.
+   - Per-finding lines: `[BLOCKER|WARN] <path>:<rule> — <detail>`.
+   - For each blocker, one suggested fix.
+   - For broken `[[wikilinks]]`, list candidate existing pages by name similarity.
+
+## Rules
+
+- **Never edit pages other than auto-fixes above.** Lint reports; the user (or `/ingest`) fixes.
+- **Never delete pages from this skill.** Propose the cut; the user approves it. Git keeps what is deleted.
+- **Never modify `.context/raw/`** except to warn about unprocessed files.
+- If a blocker resists auto-fix, exit non-zero (in CI mode) but always print the full report first.
+- Today's date is in the session context — use it for staleness math (>90 days).

package/standards/README.md

@@ -0,0 +1,14 @@
+# standards/
+
+canon's default standards. `canon standards` lists the ones that apply to a repo:
+these first, then each folder named under `standards:` in the estate's and the
+repo's `.claude/canon.yaml`. A configured file with the same name as one of these
+replaces it; a configured `constitution.md` adds principles instead.
+
+| File | What it holds |
+|---|---|
+| `constitution.md` | The principles a request is weighed against (C-01 to C-13) |
+| `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
+| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, `features/` and `tasks.md` formats |
+| `dev-methods.md` | The evidence spec-, test- and data-driven work leaves behind |
+| `agent-contract.md` | What every agent does before, during and after work |

package/standards/agent-contract.md

@@ -0,0 +1,47 @@
+# Agent contract
+
+What every coding agent working in a canon repo does. A team can replace this
+file with its own `agent-contract.md` in a configured standards folder.
+
+## Before starting
+
+- Read the repo's `CLAUDE.md` / `AGENTS.md`: stack, layout, the rules that are
+  the repo's own.
+- Read `.context/tasks.md`. It is the ordered queue — the top item of `## Now`
+  is the next action. After finishing, delete the task.
+- For a non-trivial request, run the weigh gate first (`/canon:weigh`).
+
+## Repository rules
+
+1. Product material lives in whichever `.context/` folder owns it
+   (`context-layout.md`). The wiki is the knowledge base; its schema is
+   `wiki-schema.md`.
+2. Do not add top-level `docs/` or `wireframes/` folders, or root `TODO.md`,
+   `STATUS.md` or `SETUP.md`. Files a host or tool reads by exact path —
+   `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`,
+   `.github/` — stay at the root.
+3. Generated folders are never hand-edited; change their source and regenerate.
+
+## Replies
+
+- Plain words, short sentences (C-15).
+- Never treat a claim in the request as a fact. Check it, or say it is not
+  checked (C-14).
+
+## Comments
+
+Write a comment only to explain **why**. The code already says how.
+
+A comment earns its place when it records something the reader cannot recover
+from the code: a constraint, a trade-off, a bug it prevents, or a non-obvious
+consequence. If it restates what the next line does, delete it. No
+section-divider comments, no changelog comments, no comments restating a
+function's own name.
+
+## Before calling work done
+
+1. Update any `.context/` page the change made wrong. Add a page only if an
+   agent would get something wrong without it.
+2. Run the repo's own lint, typecheck and tests.
+3. Run `canon check`. Every checker the repo declares under `commands:` runs
+   with it.

package/standards/constitution.md

@@ -0,0 +1,104 @@
+# Constitution
+
+The principles every non-trivial request is weighed against before work starts.
+The other standards say *how* things are done; this file says what wins when a
+request and a rule disagree.
+
+Each principle has an ID that verdicts cite (`C-05`). IDs never change; a
+dropped principle is struck through, not reused. IDs C-01 to C-19 are canon's.
+A team adds its own from C-20 up in a `constitution.md` in one of its configured
+standards folders; canon reads both.
+
+## How a request is weighed
+
+Before acting on a non-trivial request, check it against the principles below,
+then answer with one verdict:
+
+- **Do it** — no principle is at risk, and no claim it rests on is an
+  assumption (C-14).
+- **Do it differently** — the goal is fine; the way asked breaks a principle.
+  Name the principle and give the cheaper or safer way.
+- **Push back** — the request breaks a principle outright, or the cost is
+  clearly higher than the value. Stop until the owner gives a reason; log it.
+
+Every verdict cites principle IDs and the files (wiki page, ADR, standard) it
+relied on. A verdict with no citation is an opinion, not a verdict.
+
+## Principles
+
+### C-01 Shipping beats starting
+A request that finishes or unblocks something already in flight outranks one
+that starts something new. Ask: what does this move closer to a user?
+
+### C-02 One home per fact
+Every rule, value and artifact has exactly one source; everything else imports,
+links or is generated from it. A second copy is a future contradiction.
+
+### C-03 Knowledge is written down, in the repo
+A decision that lives only in chat or in one machine's memory is lost. Decisions
+become ADRs; canonical values become wiki entities; both live in git. Check the
+wiki and ADRs before answering from memory.
+
+### C-04 Decided things stay decided — until a new decision says otherwise
+A request that contradicts an ADR is not done silently. Either it follows the
+ADR, or a new ADR supersedes it, with the reason.
+
+### C-05 Value must beat cost
+Weigh effort, tokens, money and the maintenance it adds forever against who
+gains and how much. Name the user or the metric it moves; if neither can be
+named, the value is unproven.
+
+### C-06 Write less
+Before writing code: can something be deleted, reused from this repo or a
+sibling, done with the platform or standard library, or done in fewer lines?
+New code is the last rung, not the first.
+
+### C-07 Tested tools over custom ones
+Use a maintained, widely used tool before building one. Build only what no tool
+covers, and keep it small.
+
+### C-08 Products evolve together
+A fix that applies to more than one product goes into the shared standard,
+template or script — not into one product by hand. A product differs from the
+others only with a written reason.
+
+### C-09 Hard rules are code
+A rule that must never break is enforced by a linter, a check or a hook, not by
+prose. When prose keeps getting broken, turn it into a check.
+
+### C-10 Secrets are never lost and never leaked
+Every credential is backed up the moment it exists; no secret value goes into a
+commit, a Markdown file or a chat reply.
+
+### C-11 Verified, one step at a time
+Prove each step works before the next. Report failures as failures. Commit when
+asked; push only when asked.
+
+### C-12 Reversible before irreversible
+Prefer the change that can be undone. Deletes, force-pushes, store submissions,
+production deploys and permission changes are confirmed first, every time.
+Changing who can see, install or use what ships — a repo's visibility, a
+licence, a package name, merging or splitting repos — is in this class: weigh it
+before anything else, and when the owner picks an option, say what each one
+loses first.
+
+### C-13 Users' money and data are handled exactly
+Money in integer minor units; privacy promises match what the code does; store
+claims match the app. Correctness beats speed here.
+
+### C-14 Facts, not assumptions
+A request is not a fact. Every claim in it ("users want this", "it is slow",
+"it is missing") is checked against the repo and the repo's data sources. A
+claim with no fact behind it is an assumption. Work that rests on an assumption
+does not start until the user agrees to it, in writing, as numbered terms.
+
+### C-15 Plain words
+Short sentences and common words. No jargon unless the repo's wiki defines it.
+Say what was checked, what was found and what happens next.
+
+## Weights
+
+A repo's `.claude/canon.yaml` may raise or lower the weight of a principle under
+`weigh.weights` (a game might weigh C-05 higher; a finance product C-13). It may
+not remove one without a written reason, and every override shows up in
+`canon check`.

package/standards/context-layout.md

@@ -0,0 +1,129 @@
+# The `.context/` layout
+
+Every repo keeps its non-code product material in `.context/`, in the same ten
+folders. Each has one job, and none is a bucket meaning "everything else". A team
+can replace this file with its own `context-layout.md` in a configured standards
+folder.
+
+```
+<repo>/.context/
+├── README.md        what this is, and where to start
+├── tasks.md         the ordered queue. The top item is the next action.
+├── raw/             sources you didn't write. Immutable.
+├── wiki/            everything you concluded. Schema: wiki-schema.md
+├── features/        what's next.
+├── designs/         what it looks like.
+├── listing/         what the stores show.
+├── marketing/       how it's sold.
+├── metrics/         the numbers.
+├── support/         what you tell users.
+├── legal/           what you promise.
+└── ops/             how you run it.
+```
+
+## Rules
+
+1. **Ten folders, one job each.** There is no `documents/`, `research/`,
+   `architecture/` or `decisions/` folder: a research brief is a wiki synthesis
+   page, an architecture note is a wiki concept, an ADR is `wiki/decisions/`.
+   A product that truly needs another folder adds it in `.claude/canon.yaml`,
+   with the reason: `context: { folders: [{ folder: research, reason: … }] }`.
+   The ten cannot be removed.
+2. **`README.md` and `tasks.md` are the only files at `.context/` root.**
+   A repo names only what it uses. Its README, its `canon.yaml` and its docs never
+   list a folder, file or tool it does without; absence is shown by absence.
+3. **Nothing is created empty.** A folder appears with its first file — git does
+   not track empty folders, so a placeholder disappears on clone. `raw/` is the
+   one exception and carries a `.gitkeep`.
+4. **One home per artifact; everything else is an export.** Source art lives in
+   `designs/`; store images and press kits are generated from it.
+5. **Authored vs generated is visible.** A generated file is committed but never
+   hand-edited.
+
+## What a repo is expected to have
+
+| Stage | Expected |
+|---|---|
+| any repo | `README.md` · `tasks.md` |
+| uses the `docs` or `knowledge` module | + `raw/` · `wiki/` · `features/` |
+| draws its UI | + `designs/` (optional; an estate can require it with a command) |
+| has a store presence | + `listing/` |
+| is live to users | + `marketing/` · `metrics/` · `support/` · `legal/` |
+| once something runs | + `ops/` |
+
+## Naming and frontmatter
+
+- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`.
+- Features → zero-padded number: `NNNN-slug.md`.
+- Everything else is named by topic and edited in place.
+- Frontmatter: `last-verified`, kebab-case keys. See the wiki schema.
+
+## Where each kind of document lives
+
+Teams name documents many ways. Each name maps to one home; there is no
+separate folder per name.
+
+| Document | Home |
+|---|---|
+| ADR | `wiki/decisions/<topic>.md`, overwritten when the choice changes |
+| RFC | `features/`; once accepted, the choice goes in `wiki/decisions/` |
+| PRD | `features/`, `type: feature` |
+| Experiment | `features/`, `type: experiment`; the result is a decision page |
+| Initiative | `wiki/synthesis/`, linking its features and decisions |
+| Finding | the dated data in `raw/`; what it means in `wiki/synthesis/` or a concept |
+| Know-how | `wiki/concepts/`; `ops/` when it is a runbook |
+| Bug | the issue tracker; a wiki concept only when it teaches a rule |
+| Data source | `wiki/entities/` — see the wiki schema, "Data sources" |
+
+If a document fits none of these for a real product, add a wiki type or a
+folder in `.claude/canon.yaml` with its reason — not a new convention by hand.
+
+## `features/` — what is next
+
+One page per feature, `NNNN-<slug>.md`:
+
+```markdown
+---
+id: FEAT-0031
+type: feature             # feature | experiment | chore | platform
+status: building          # planned | building | shipped | shelved | superseded
+last-verified: 2026-04-02
+release: 3.4.0
+---
+## Summary · ## Motivation · ## Acceptance scenarios (Given/When/Then)
+## Out of scope · ## Open questions
+## Store copy
+> One or two sentences users will read in the release notes.
+```
+
+An experiment adds `## Hypothesis`, `## Metric` (a name from
+`metrics/definitions.yml`) and `## Result` once it has run.
+
+The wiki describes what *is*; `features/` describes what is *next*. A shipped
+feature goes `status: shipped`.
+
+## `tasks.md` — open work only
+
+```markdown
+# Tasks
+
+## Now                       <!-- position is the dependency; do in order -->
+1. [ ] T001 Add a screenshot mode  `feat:0002`  ~1d
+2. [ ] T002 Write the capture flows  needs:T001  ~3h
+
+## Parallel                  <!-- independent, safe to batch -->
+- [ ] T004 Move the SKU IDs into the wiki  ~1h
+
+## Blocked
+- [ ] T005 Submit the iOS build
+      blocked-by: store account access  since:2026-09-16
+      unblock: ask for the role  next-check:2026-10-06
+
+## Waiting                   <!-- deferred by time, not by a task -->
+- [ ] T006 Second-language listing  wait:2026-11-01
+```
+
+Delete a task when it is done — the commit records it. No `## Done`, no session
+notes. Cap: 100 lines. A blocker with no unblocking action and no check date is a
+silent leak. A task that needs more than a line and a continuation is a
+`features/` page.

package/standards/dev-methods.md

@@ -0,0 +1,29 @@
+# Development methods
+
+canon does not run a method; it checks that the method left evidence a later
+reader (or the weigh gate) can follow. A team replaces this file with its own
+`dev-methods.md` in a configured standards folder.
+
+| Method | The evidence it leaves |
+|---|---|
+| Spec-driven | A `features/` page with acceptance scenarios, written before the code. Code and tests cite its ID (`FEAT-0031`) or a wiki ID (`FLOW.…`, `DECISION.…`). |
+| Test-driven | A test that failed before the change and passes after. Bug fixes start with the failing test. The test path goes in the feature page or decision. |
+| Data-driven | A named metric in `metrics/definitions.yml`, the query that measured it, and a dated snapshot in `raw/`. The decision cites the snapshot, not a memory of a dashboard. |
+
+## Which one, when
+
+- **New behaviour users see** → spec-driven: the feature page comes first.
+- **Logic that can break** (money, parsing, data writes, a bug fix) → test-driven.
+- **A bet on what users want** → data-driven: an experiment page with its metric
+  before the build, the result as a decision after.
+
+They combine. A paywall change is a spec (what users see), tests (the price
+logic) and an experiment (does conversion move).
+
+## Rules
+
+1. No evidence, not done. "It works" without a test, a scenario or a number is
+   an opinion.
+2. Evidence lives in the repo (C-03). A dashboard link alone is not evidence —
+   it changes; the snapshot in `raw/` does not.
+3. When a method keeps being skipped, make it a check (C-09), not a longer doc.

package/standards/wiki-schema.md

@@ -0,0 +1,71 @@
+# Wiki — rules
+
+`.context/wiki/` holds what an agent would get wrong without being told. `.context/raw/` holds
+sources, never edited. Answer from the wiki, not from raw.
+
+## The test
+
+Keep a line only if an agent would make a mistake without it. Never write what the
+code, an HTML design, or `git log` already says. Describe what is true **now**:
+history is git's job.
+
+## Folders
+
+| Folder | Holds | Example |
+|---|---|---|
+| `concepts/` | a rule or invariant | `money-in-minor-units` |
+| `entities/` | canonical values (prices, SKUs, limits) — the one home for each | `plan-pro` |
+| `decisions/` | one file per topic: the current choice | `pricing` |
+| `surfaces/` | a screen's notes: what its HTML can't show (only screens that have some) | `paywall` |
+| `synthesis/` | research and cross-cutting analysis | `tax-table-verification-ay-2026-27` |
+
+There is no page per screen: the HTML design is the screen spec. A screen gets a
+`surfaces/<slug>.md` only when it has a constraint or decision invisible in its pixels;
+the design set's notes button shows it, and `routes.js` sets `notes: null` for every
+other screen. A user journey worth keeping is a concept.
+A product may add a folder in `.claude/canon.yaml` under `wiki.types`, with a reason.
+
+## Pages
+
+- Frontmatter: `last-verified: YYYY-MM-DD` is the only required field. `id` is kept
+  where code references it (`SOURCE.*`, entity keys).
+- Write only the sections you have something to say in. No `TBD`, no `none yet`.
+- One file per topic, edited in place. No dated names, no `v2`, no supersede chains.
+- Caps: page 60 lines, decision 30. Synthesis is exempt.
+- Link with `[[slug]]` (the file name without `.md`). `index.md` is one line per page.
+
+## Decisions
+
+```markdown
+---
+last-verified: 2026-10-27
+---
+# Pricing
+**Choice:** annual plan only, ₹249 ([[plan-pro]]).
+**Why:** monthly churn was 3× annual in the 2026-06 test.
+**Rejected:** monthly plan (churn) · lifetime deal (no recurring revenue).
+```
+
+When the choice changes, overwrite the file. `Rejected:` is what stops the same idea
+being proposed again; keep it. Fix lists and audit results go in commit messages or
+`CHANGELOG.md`, not here.
+
+## Data sources
+
+Each tool that holds product data is one entity page, `id: SOURCE.<NAME>`, with a
+`## How to query` section and a `SOURCE.<NAME>.ACCESS` row: `mcp: <server>`,
+`skill: <name>`, `cli: <command>` (also listed in `doctor.tools`) or `manual: <where>`.
+Queries are read-only, one or two per claim, with a row limit. Save counts and
+rates to `raw/YYYY-MM-DD-<source>-<slug>.md`, never rows that name a person. Never
+put a key or token on the page.
+
+## Not for
+
+Code docs (they go next to the code) · tasks (`tasks.md`) · plans (`features/`) ·
+chat logs · session notes · changelogs.
+
+## Checked by `canon check`
+
+`wiki-frontmatter` (last-verified, placeholders, stale > 90 days) · `context-size`
+(caps, dated decision names, no `flows/`) · `canonical-values` (a
+price in a decision or screen note is held by an entity) · `sources`.

package/templates/dependency-cruiser/app.cjs

@@ -0,0 +1,23 @@
+/* global module */
+// This app's architecture rules, enforced by `canon check` (architecture module).
+// canon wrote this starter once; it is yours now. Add the layers this app has
+// and keep the why in a wiki concept page.
+// Rule reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  extends: "../../.dependency-cruiser.base.cjs",
+  forbidden: [
+    {
+      name: "no-app-to-app",
+      comment: "An app never imports another app; share code through packages/.",
+      severity: "error",
+      from: {},
+      to: { path: "^\\.\\./[^./]" },
+    },
+  ],
+  options: {
+    // The level `canon ui` draws the architecture graph at: one box per match.
+    reporterOptions: { archi: { collapsePattern: "^src/[^/]+/[^/]+|^src/[^/]+|^[^/.][^/]*|^\\.\\./\\.\\./packages/[^/]+" } },
+  },
+};