@freetesh/canon 0.16.0 → 0.17.0

package/standards/README.md

@@ -1,14 +1,31 @@
 # 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.
+canon's standards. `canon standards` lists the ones that apply to a repo.
+
+## Defaults — apply to every repo
 
 | File | What it holds |
 |---|---|
-| `constitution.md` | The principles a request is weighed against (C-01 to C-13) |
+| `constitution.md` | The principles a request is weighed against (C-01 to C-15; C-01 to C-19 are canon's) |
 | `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 |
+| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, the repo root, `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 |
+
+## Library — a repo opts in by name
+
+A repo lists the ones it wants in `.claude/canon.yaml`:
+`standards: [design-sets, pipeline, expo]`.
+
+| Name | What it holds |
+|---|---|
+| `design-sets` | HTML design sets: layout, `routes.js`, the navbar, the flow chart, tokens, checks |
+| `pipeline` | The five stages and their hard gates; principles C-16 and C-17 |
+| `expo` | Scaffolding an Expo app, its layout, the versioned-docs rule, release checks |
+| `frontend` | `.tsx` code rules: one component per file, thin routes, helpers in `lib/` and `hooks/`, UniWind |
+| `performance` | No redraw after a local edit, counted round trips, no blank navigation, a number before and after |
+| `secrets` | Every secret backed up the moment it exists; key names only in `INVENTORY.md` |
+| `store-listing` | `.context/listing/` as fastlane's tree, screenshots, release notes from `features/` |
+
+A library standard may add principles in the constitution's `### C-NN Title`
+format; they apply only to repos that opt in.

package/standards/agent-contract.md

@@ -8,7 +8,9 @@ file with its own `agent-contract.md` in a configured standards folder.
 - 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.
+  is the next action. After finishing, delete the task. The repo's `AGENTS.md`
+  (or `CLAUDE.md`) carries these two lines, because without them an agent that
+  was not told about `.context/` never finds it.
 - For a non-trivial request, run the weigh gate first (`/canon:weigh`).
 
 ## Repository rules
@@ -17,10 +19,11 @@ file with its own `agent-contract.md` in a configured standards folder.
    (`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.
+   `STATUS.md` or `SETUP.md`. What stays at the root, and where the rest goes:
+   `context-layout.md`, "Repo root".
 3. Generated folders are never hand-edited; change their source and regenerate.
+4. File names are lowercase kebab-case unless the language says otherwise.
+5. Names follow the repo's current identity, not a legacy name.
 
 ## Replies
 
@@ -34,13 +37,25 @@ 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
+consequence. If it restates what the next line does, delete it.
+
+```ts
+// Good — the reason is invisible in the code:
+// Prune only. Recomputing here would discard the user's per-pack choices
+// on every launch, which is the bug this replaced.
+state.selectedPackIds = prunePackIds(...);
+
+// Bad — narrates the mechanism:
+// Loop over the packs and filter out the locked ones
+```
+
+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
+1. Update `CLAUDE.md` and 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

package/standards/context-layout.md

@@ -24,8 +24,9 @@ folder.
 ## 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/`.
+   `architecture/`, `decisions/` or `email-templates/` folder: a research brief
+   is a wiki synthesis page, an architecture note is a wiki concept, an ADR is
+   `wiki/decisions/`, a transactional email is HTML in `designs/`.
    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.
@@ -38,7 +39,8 @@ folder.
 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.
+   hand-edited. Its source is a hand-written file such as `marketing/context.md`,
+   `metrics/definitions.yml` or `metrics/events.yml`.
 
 ## What a repo is expected to have
 
@@ -53,7 +55,8 @@ folder.
 
 ## Naming and frontmatter
 
-- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`.
+- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`. Month-grain data
+  keeps `YYYY-MM.csv`.
 - 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.
@@ -74,10 +77,40 @@ separate folder per name.
 | 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" |
+| Setup notes (account IDs, console links, where credentials live) | `ops/setup.md` |
+| What is live right now, per surface | `ops/release.yml` |
+| Runbook | `ops/runbooks/<slug>.md` |
+| Incident | `ops/incidents/YYYY-MM-DD-<slug>.md` |
+| Dated engineering narrative | `CHANGELOG.md` at the repo root |
 
 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.
 
+## Inside the folders
+
+A folder holds only what it uses; these are the usual names.
+
+```
+marketing/   context.md (identity, goals, markets) · brand/ (WORDS only — art is in designs/brand/)
+             posts/ · video/ · launch/ · press/ (press/media/ is an export of designs/brand/)
+metrics/     definitions.yml (the KPI dictionary) · events.yml (what each event means)
+             history/YYYY-MM.csv (metric,period,value)
+support/     SUPPORT.md · faq/ · replies/ · reviews/
+legal/       privacy policy · terms · data deletion
+ops/         release.yml · setup.md · runbooks/ · incidents/
+```
+
+## Repo root
+
+These stay at the root, because a host renders them or a tool reads them by
+exact path: `README.md` · `LICENSE` · `CHANGELOG.md` · `CONTRIBUTING.md` ·
+`SECURITY.md` · `CLAUDE.md` · `AGENTS.md` · `.github/`.
+
+`TODO.md`, `STATUS.md` and `SETUP.md` do not. `SETUP.md` becomes `ops/setup.md`.
+The other two are not single documents, so split them: the backlog goes to
+`tasks.md`, what is live to `ops/release.yml`, the dated narrative to
+`CHANGELOG.md`, canonical values to `wiki/entities/`, a how-to to `ops/runbooks/`.
+
 ## `features/` — what is next
 
 One page per feature, `NNNN-<slug>.md`:
@@ -88,7 +121,9 @@ 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
+release: 3.4.0            # ties to CHANGELOG.md and the release notes
+superseded-by: null
+surfaces: ["[[settings-screen]]"]
 ---
 ## Summary · ## Motivation · ## Acceptance scenarios (Given/When/Then)
 ## Out of scope · ## Open questions
@@ -100,7 +135,7 @@ 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`.
+feature goes `status: shipped` and is never deleted, so the reasoning survives.
 
 ## `tasks.md` — open work only