@freetesh/canon 0.0.0-stage → 0.16.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "canon",
+  "owner": {
+    "name": "Ritesh Firodiya"
+  },
+  "plugins": [
+    {
+      "name": "canon",
+      "source": "./",
+      "version": "0.16.0",
+      "description": "Keeps your domain knowledge and AI rules in your repos and enforces them, so Claude hallucinates less."
+    }
+  ],
+  "description": "canon: domain knowledge and AI rules kept in your repos, enforced, searchable."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "canon",
+  "version": "0.16.0",
+  "description": "Keeps your domain knowledge and AI rules in your repos and enforces them, so Claude hallucinates less."
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritesh Firodiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+<p align="center">
+  <img src=".github/assets/icon.svg" width="96" height="96" alt="canon icon">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">canon</h1>
+
+<p align="center"><b>Facts, not assumptions.</b> Your rules and knowledge, kept in your repos. Enforced.</p>
+
+canon keeps domain knowledge, decisions and AI rules in each repo's `.context/`,
+enforces them, and makes them searchable. Claude searches them before it
+answers, weighs each request against them before it acts, and checks every
+claim in a request against facts. `canon check` fails when code or docs break a
+rule. The AI guesses less, and you redo less work.
+
+<p align="center">
+  <img src=".github/assets/demo.svg" alt="canon weighs a request. Two of three claims have no facts and the request breaks a decided rule, so it pushes back and stops until the user brings facts, agrees to terms, or drops it.">
+</p>
+
+Two parts, free and MIT, that read the same config:
+
+- **a Claude Code plugin** — skills, a decision gate, a session hook and a
+  search server, so every session in every repo starts with the same rules;
+- **the `canon` CLI** — set up, check, sync and search your repos.
+
+A hosted knowledge site, with every repo's `.context/` in one place for a team,
+is a separate paid product built on this CLI.
+
+## What it does
+
+- **Weigh before acting.** For a non-trivial request Claude checks the
+  constitution, the wiki and decisions, features and tasks, cost against value,
+  and the write-less ladder, then answers **DO IT**, **DO IT DIFFERENTLY** or
+  **PUSH BACK** with citations. Every verdict is logged; `canon learn` turns
+  repeated overrides into proposals.
+- **No assumptions.** Each claim in a request ("users want this", "it is slow")
+  is checked against the repo and its data sources and marked backed or not.
+- **Your data sources, your tools.** A repo describes each tool that holds its
+  data on a `SOURCE.*` wiki entity that names the MCP server, skill or CLI that
+  reads it. The gate queries it read-only to back or reject a claim.
+- **Knowledge that is found.** Every repo's wiki and feature board is indexed
+  with [QMD](https://github.com/tobi/qmd); Claude searches before answering.
+- **Context stays small.** A line belongs in `.context/` only if an agent would
+  get something wrong without it. Decisions are one file per topic, overwritten
+  when the choice changes; `tasks.md` holds open work only; history is git's.
+- **Hard rules are checks.** `canon check` validates layout, wiki frontmatter,
+  stale pages, placeholders, size caps, blocked tasks, feature pages, the store
+  listing tree, dead `.context/` paths, prices with no canonical home, shared
+  files, the import architecture, pipeline gates, and every checker your config
+  declares. `canon hooks install` makes every push run it.
+- **Standards with one home.** canon ships defaults; an estate adds or replaces
+  them from its own folder; a repo can override again. `canon standards` shows
+  what applies.
+- **A repo names only what it uses.** Modules, packs and shared-file sets are
+  opt-in; there is no skip list and no setting that turns a check off.
+
+## Install
+
+```bash
+claude plugin marketplace add ritesh-firodiya/canon-cli
+claude plugin install canon@canon
+npm install -g @freetesh/canon
+npm install -g @tobilu/qmd --allow-scripts=node-llama-cpp,tree-sitter-go,tree-sitter-python,tree-sitter-rust,tree-sitter-typescript,tree-sitter-javascript
+```
+
+Then in any repo: `canon doctor`, `canon init`, `canon check`, `canon sync`.
+Try `/canon:weigh add a dark mode toggle` in a session; record choices with
+`/canon:decision` and ask about them with `/canon:ask`. `/canon:ingest` with no
+argument captures what a session taught.
+
+## CLI
+
+```bash
+canon init             # write .claude/canon.yaml and the missing .context files
+canon add              # list packs; `canon add expo` adds one and indexes its docs
+canon check            # this repo against the standards (exit 1 on any error); --all for the estate
+canon copies --sync    # repair drifted shared files from copies.source (never adds one)
+canon hooks install    # a pre-push hook that runs `canon check` (--all: every product)
+canon standards        # which standards apply here, and where each comes from
+canon sync             # refresh pack docs and the search index, move the pinned version
+canon status           # version, kind, modules, config layers, check summary
+canon doctor           # node, git, qmd — plus any tools your config lists
+canon learn            # proposals from overridden verdicts
+canon approve <stage>  # a person records a pipeline gate approval
+canon pipeline         # the stages this repo resolves to, and where each stands
+canon weigh "<ask>"    # the decision gate from the terminal
+canon ui               # every wiki and design gallery on localhost
+canon search "<q>"     # search the knowledge index
+canon mcp              # the search MCP server, for any MCP client
+```
+
+## Config
+
+`.claude/canon.yaml`, read in layers — **estate → repo → local**
+(`canon.local.yaml`, not committed). The estate is the nearest folder above a
+repo whose `canon.yaml` says `estate: true`, or `CANON_ESTATE`.
+
+```yaml
+# <estate>/.claude/canon.yaml — shared by every repo below it
+estate: true
+standards: [.canon/standards]       # estate rules; same name replaces a canon default
+commands:                           # your own checkers, run by `canon check`
+  - { id: designs, run: ./scripts/check-designs.sh, if: .context/designs, module: design }
+  - { id: designs-first, run: test -d .context/designs, kinds: [mobile, web] }   # only repos that ship screens
+copies:                             # files products copy from one source repo, in named sets
+  source: design-system
+  sets:
+    upload: [scripts/upload.mjs]
+    shell-web:
+      - { from: designs/mobile/index.html, to: designs/web/index.html, named: true }
+```
+
+```yaml
+# <repo>/.claude/canon.yaml — written by `canon init`
+canon: 0.16.0
+kind: mobile                        # mobile | web | mobile-and-web | package | content
+modules: [docs, knowledge, code, listing, refs]
+packs: [expo]
+name: Acme                          # how the product is written; `named` copies swap it in
+copies:
+  use: [upload, shell-web]          # the sets this repo uses; only these are held to the source
+```
+
+Scalars: the most specific layer wins. `packs`, `standards` and `copies.use`
+add up across layers; `commands`, `doctor.tools`, `wiki.types` and
+`context.folders` merge by name.
+
+## Layout
+
+```
+.claude-plugin/   plugin manifest and marketplace
+skills/           weigh, standards, ask, ingest, decision, wiki-lint
+agents/           challenger — a second opinion for too-large requests
+hooks/            session start: constitution titles, qmd refresh
+standards/        default standards
+packs/            vendor doc packs
+templates/        files init writes (dependency-cruiser base and starters)
+scripts/          log-verdict.mjs — the verdict log
+evals/            plugin evals and the fixture product
+cli/              the canon CLI (TypeScript, vitest); `@freetesh/canon/api` for tools built on it
+```
+
+Inside `cli/src/`:
+
+```
+index.ts          the program: registers every command
+api.ts            what other tools import (`@freetesh/canon/api`)
+commands/         one file per command — options and output only
+checks/           one file per check, named by its id; index.ts lists them
+config/           .claude/canon.yaml: schema, layered loading, estate discovery
+lib/              shared helpers: files, frontmatter, env, qmd, system calls
+<name>.ts         the logic the commands call: check (+ format for its output), init, packs (add), sync, …
+```
+
+Tests mirror it in `cli/test/`.
+
+## Develop
+
+`pnpm check` runs `canon check` on this repo, the typecheck and every test.
+The version lives in `package.json` and `.claude-plugin/plugin.json`; bump both
+with a CHANGELOG entry. A push to main with a new version publishes to npm.
+
+MIT licence.

package/cli/dist/api.d.ts

@@ -0,0 +1,3 @@
+export { findEstate } from "./config/load.ts";
+export { findProducts } from "./check.ts";
+export { qmdQuery, qmdRefresh } from "./lib/qmd.ts";

package/cli/dist/api.js

@@ -0,0 +1,4 @@
+// What other tools build on: the canon knowledge site reads repos the way `canon check --all` finds them.
+export { findEstate } from "./config/load.js";
+export { findProducts } from "./check.js";
+export { qmdQuery, qmdRefresh } from "./lib/qmd.js";

package/cli/dist/check.d.ts

@@ -0,0 +1,19 @@
+import type { Check, Finding } from "./checks/types.ts";
+export interface Report {
+    repo: string;
+    name: string;
+    findings: Finding[];
+    skipped: Array<{
+        check: string;
+        why: string;
+    }>;
+}
+export interface RunOptions {
+    checks?: Check[];
+    canonRoot: string;
+    estateRoot?: string | null;
+    today?: Date;
+}
+export declare function runChecks(repo: string, options: RunOptions): Report;
+/** Product repos in the estate: every direct child folder holding a .context/. */
+export declare function findProducts(estateRoot: string): string[];

package/cli/dist/check.js

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ALL_CHECKS } from "./checks/index.js";
+import { loadConfig } from "./config/load.js";
+import { isDirectory } from "./lib/files.js";
+export function runChecks(repo, options) {
+    const report = { repo, name: basename(repo), findings: [], skipped: [] };
+    if (!isDirectory(repo)) {
+        report.findings.push({ check: "repo", level: "error", message: `no folder at ${repo}` });
+        return report;
+    }
+    let config;
+    try {
+        config = loadConfig(repo, { estateRoot: options.estateRoot }).config;
+    }
+    catch (error) {
+        report.findings.push({ check: "config", level: "error", message: error.message });
+        return report;
+    }
+    for (const check of options.checks ?? ALL_CHECKS) {
+        if (check.module && !config.modules.includes(check.module)) {
+            report.skipped.push({ check: check.id, why: `module ${check.module} is off` });
+            continue;
+        }
+        try {
+            report.findings.push(...check.run({ repo, name: report.name, config, canonRoot: options.canonRoot, today: options.today ?? new Date() }));
+        }
+        catch (error) {
+            report.findings.push({ check: check.id, level: "error", message: `check crashed: ${error.message}` });
+        }
+    }
+    return report;
+}
+/** Product repos in the estate: every direct child folder holding a .context/. */
+export function findProducts(estateRoot) {
+    return readdirSync(estateRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(estateRoot, entry.name, ".context")))
+        .map((entry) => join(estateRoot, entry.name))
+        .sort();
+}

package/cli/dist/checks/architecture.d.ts

@@ -0,0 +1,23 @@
+import type { Check, Finding } from "./types.ts";
+export declare const RULES_FILES: string[];
+export interface Violation {
+    rule: {
+        name: string;
+        severity: string;
+    };
+    from: string;
+    to: string;
+}
+interface Rules {
+    /** Folder the rules apply to, relative to the repo ("." for the root). */
+    dir: string;
+    file: string;
+}
+/** Every rules file in the repo: the root's, then one per workspace under apps/ and packages/. */
+export declare function findRules(repo: string): Rules[];
+/** One finding per broken rule: how often, and the first few places. */
+export declare function summarize(violations: Violation[]): Finding[];
+export declare const architecture: Check;
+/** The repo's architecture as markdown — one mermaid graph per rules file — or undefined when there is nothing to draw. */
+export declare function architectureGraph(repo: string): string | undefined;
+export {};

package/cli/dist/checks/architecture.js

@@ -0,0 +1,135 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, posix } from "node:path";
+// The names dependency-cruiser itself looks for; `canon init` writes the first.
+export const RULES_FILES = [".dependency-cruiser.cjs", ".dependency-cruiser.js", ".dependency-cruiser.mjs", ".dependency-cruiser.json"];
+const DEFAULT_COLLAPSE = "^(apps|packages)/[^/]+|^[^/]+/[^/]+";
+const SHOWN_PER_RULE = 3;
+// Mermaid refuses diagrams over 50k characters.
+const MERMAID_MAX_CHARS = 50_000;
+const MAX_BUFFER = 64 * 1024 * 1024;
+// Monorepo workspaces whose apps each map `@/` to their own src need one rules file each,
+// because dependency-cruiser resolves aliases from a single tsconfig per run.
+const WORKSPACE_PARENTS = ["apps", "packages"];
+function rulesFile(dir) {
+    return RULES_FILES.find((file) => existsSync(join(dir, file)));
+}
+/** Every rules file in the repo: the root's, then one per workspace under apps/ and packages/. */
+export function findRules(repo) {
+    const workspaces = WORKSPACE_PARENTS.flatMap((parent) => existsSync(join(repo, parent))
+        ? readdirSync(join(repo, parent), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => `${parent}/${entry.name}`)
+            .sort()
+        : []);
+    return [".", ...workspaces].flatMap((dir) => {
+        const file = rulesFile(join(repo, dir));
+        return file ? [{ dir, file }] : [];
+    });
+}
+const fromRoot = (dir, path) => posix.normalize(posix.join(dir, path));
+// The rules are about committed code; a gitignored file (a stale dist/ build) is never shipped.
+function ignoredBy(repo, paths) {
+    if (paths.length === 0)
+        return new Set();
+    const result = spawnSync("git", ["-C", repo, "check-ignore", "--stdin"], { input: paths.join("\n"), encoding: "utf8" });
+    return new Set(result.stdout.split("\n").filter(Boolean));
+}
+// The repo's own pinned copy, never a global one, so every machine runs the same version.
+function depcruiseBin(repo) {
+    const bin = join(repo, "node_modules", ".bin", "depcruise");
+    return existsSync(bin) ? bin : undefined;
+}
+function depcruise(repo, bin, rules, args) {
+    return spawnSync(bin, [".", "--config", rules.file, ...args], { cwd: join(repo, rules.dir), encoding: "utf8", maxBuffer: MAX_BUFFER });
+}
+// dependency-cruiser needs a TypeScript it supports (below 7) to read .ts files; without one it
+// skips them and still reports success, so a TypeScript workspace with none read is not a pass.
+function unreadTypeScript(repo, rules, modules) {
+    return existsSync(join(repo, rules.dir, "tsconfig.json")) && !modules.some((m) => /\.tsx?$/.test(m.source));
+}
+function typeScriptWarning(rules) {
+    const file = fromRoot(rules.dir, "tsconfig.json");
+    const message = "no TypeScript files were read, so their imports went unchecked — dependency-cruiser needs `typescript` below 7 installed here";
+    return [{ check: "architecture", level: "warn", file, message }];
+}
+/** One finding per broken rule: how often, and the first few places. */
+export function summarize(violations) {
+    const byRule = new Map();
+    for (const violation of violations.filter((v) => v.rule.severity === "error" || v.rule.severity === "warn")) {
+        byRule.set(violation.rule.name, [...(byRule.get(violation.rule.name) ?? []), violation]);
+    }
+    return [...byRule].map(([name, list]) => {
+        const shown = list.slice(0, SHOWN_PER_RULE).map((v) => (v.from === v.to ? v.from : `${v.from} → ${v.to}`));
+        const more = list.length > SHOWN_PER_RULE ? ` and ${list.length - SHOWN_PER_RULE} more` : "";
+        return {
+            check: "architecture",
+            level: list[0].rule.severity === "error" ? "error" : "warn",
+            file: list[0].from,
+            message: `${name} (${list.length}): ${shown.join(", ")}${more}`,
+        };
+    });
+}
+export const architecture = {
+    id: "architecture",
+    module: "architecture",
+    description: "the repo keeps the import boundaries in its own .dependency-cruiser.cjs",
+    run({ repo }) {
+        const finding = (message, file) => [{ check: "architecture", level: "error", file, message }];
+        const all = findRules(repo);
+        if (all.length === 0) {
+            return finding("no architecture rules — run `canon init --force --modules ...,architecture` for a starter, or write one", RULES_FILES[0]);
+        }
+        const bin = depcruiseBin(repo);
+        if (!bin)
+            return finding("dependency-cruiser is not installed here — add it as a devDependency (e.g. `pnpm add -D dependency-cruiser`)", "package.json");
+        return all.flatMap((rules) => {
+            const result = depcruise(repo, bin, rules, ["--output-type", "json"]);
+            try {
+                const cruise = JSON.parse(result.stdout);
+                const violations = cruise.summary.violations.map((v) => ({ ...v, from: fromRoot(rules.dir, v.from), to: fromRoot(rules.dir, v.to) }));
+                const ignored = ignoredBy(repo, violations.map((v) => v.from));
+                const findings = summarize(violations.filter((v) => !ignored.has(v.from)));
+                return unreadTypeScript(repo, rules, cruise.modules) ? [...findings, ...typeScriptWarning(rules)] : findings;
+            }
+            catch {
+                const why = (result.error?.message ?? result.stderr).trim().split("\n").slice(-5).join(" ");
+                return finding(`dependency-cruiser failed: ${why}`, fromRoot(rules.dir, rules.file));
+            }
+        });
+    },
+};
+// The graph level is the repo's choice, kept where dependency-cruiser keeps it for its own high-level view.
+function collapsePattern(dir, file) {
+    try {
+        const config = createRequire(join(dir, "noop.js"))(join(dir, file));
+        return config.options?.reporterOptions?.archi?.collapsePattern ?? DEFAULT_COLLAPSE;
+    }
+    catch {
+        return DEFAULT_COLLAPSE;
+    }
+}
+function graphOf(repo, bin, rules) {
+    const collapse = collapsePattern(join(repo, rules.dir), rules.file);
+    // The graph shows the repo's own parts; npm packages would bury them (the rules still check npm imports).
+    const ownCode = "^(?!(\\.\\./)*node_modules/)";
+    const result = depcruise(repo, bin, rules, ["--output-type", "mermaid", "--collapse", collapse, "--include-only", ownCode]);
+    if (result.status !== 0 || !result.stdout.trim())
+        return undefined;
+    if (result.stdout.length > MERMAID_MAX_CHARS) {
+        return "flowchart LR\n  too_big[\"Graph too large to draw — set a coarser reporterOptions.archi.collapsePattern\"]";
+    }
+    return result.stdout.trim();
+}
+/** The repo's architecture as markdown — one mermaid graph per rules file — or undefined when there is nothing to draw. */
+export function architectureGraph(repo) {
+    const bin = depcruiseBin(repo);
+    if (!bin)
+        return undefined;
+    const sections = findRules(repo).flatMap((rules) => {
+        const graph = graphOf(repo, bin, rules);
+        return graph ? [`## ${rules.dir === "." ? "Whole repo" : rules.dir}\n\n\`\`\`mermaid\n${graph}\n\`\`\``] : [];
+    });
+    return sections.length > 0 ? sections.join("\n\n") : undefined;
+}

package/cli/dist/checks/canonical-values.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const canonicalValues: Check;

package/cli/dist/checks/canonical-values.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+const PRICE = /(?:[$₹€£]\s?\d[\d,]*(?:\.\d+)?)/g;
+const CODE_BLOCK = /```[\s\S]*?```/g;
+// An amount counts as a price only in a paragraph that talks about selling something;
+// "Ravi paid ₹6,200" in a bill-splitting app is an example, not a price.
+const PRICE_WORDS = /pric|cost|paywall|plan|tier|subscri|bundle|pack|purchase|buy|unlock|\/mo|per month|per year|annual|yearly|monthly/i;
+function amounts(text) {
+    return (text.match(PRICE) ?? []).map((price) => price.replace(/\s/g, ""));
+}
+// A decision's `Rejected:` line names old prices on purpose; they are history, not a second home.
+const REJECTED = /^\*\*Rejected:\*\*/;
+function pricesIn(text) {
+    const paragraphs = text.replace(CODE_BLOCK, "").split(/\n\s*\n/).filter((paragraph) => !REJECTED.test(paragraph.trim()));
+    return [...new Set(paragraphs.filter((paragraph) => PRICE_WORDS.test(paragraph)).flatMap(amounts))];
+}
+function heldAmounts(text) {
+    return amounts(text.replace(CODE_BLOCK, ""));
+}
+const folderOf = (file) => file.split("/")[2];
+export const canonicalValues = {
+    id: "canonical-values",
+    module: "docs",
+    description: "a price stated in a decision or screen note is held by an entity page — one home per fact (C-02)",
+    run({ repo }) {
+        const pages = wikiPages(repo).map((file) => ({ file, ...parseFrontmatter(readFileSync(join(repo, file), "utf8")) }));
+        const held = new Set(pages.filter((page) => folderOf(page.file) === "entities").flatMap((page) => heldAmounts(page.body)));
+        // Decisions and screen notes are where prices get restated. Concepts legitimately carry
+        // example amounts (a tax product explains slabs with them).
+        return pages
+            .filter((page) => ["decisions", "surfaces"].includes(folderOf(page.file)))
+            .flatMap((page) => {
+            const orphans = pricesIn(page.body).filter((price) => !held.has(price));
+            if (orphans.length === 0)
+                return [];
+            return [
+                {
+                    check: "canonical-values",
+                    level: "warn",
+                    file: page.file,
+                    message: `${orphans.join(", ")} stated here but held by no entity page`,
+                },
+            ];
+        });
+    },
+};

package/cli/dist/checks/commands.d.ts

@@ -0,0 +1,7 @@
+import type { Check } from "./types.ts";
+/**
+ * Runs each checker a repo or its estate declares under `commands:` in
+ * canon.yaml. canon does not know what they check; a non-zero exit is an error
+ * reported under the command's own id.
+ */
+export declare const commandChecks: Check;

package/cli/dist/checks/commands.js

@@ -0,0 +1,33 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { kindCovers } from "../config/schema.js";
+const MAX_OUTPUT_LINES = 15;
+function tail(text) {
+    return text.trim().split("\n").slice(-MAX_OUTPUT_LINES).join("\n");
+}
+/**
+ * Runs each checker a repo or its estate declares under `commands:` in
+ * canon.yaml. canon does not know what they check; a non-zero exit is an error
+ * reported under the command's own id.
+ */
+export const commandChecks = {
+    id: "commands",
+    module: null,
+    description: "every checker declared under `commands:` in canon.yaml passes",
+    run({ repo, config }) {
+        return config.commands
+            .filter((command) => !command.if || existsSync(join(repo, command.if)))
+            .filter((command) => !command.module || config.modules.includes(command.module))
+            .filter((command) => !command.kinds || command.kinds.some((kind) => kindCovers(config.kind, kind)))
+            .flatMap((command) => {
+            const result = spawnSync("sh", ["-c", command.run], { cwd: repo, encoding: "utf8" });
+            if (result.error) {
+                return [{ check: command.id, level: "error", file: command.if, message: `could not run: ${result.error.message}` }];
+            }
+            if (result.status === 0)
+                return [];
+            return [{ check: command.id, level: "error", file: command.if, message: tail(`${result.stdout}\n${result.stderr}`) }];
+        });
+    },
+};

package/cli/dist/checks/context-layout.d.ts

@@ -0,0 +1,5 @@
+import { type Module } from "../config/schema.ts";
+import type { Check } from "./types.ts";
+/** What .context must hold: README.md and tasks.md always, the knowledge folders only when docs or knowledge is on. */
+export declare function requiredContext(modules: Module[]): string[];
+export declare const contextLayout: Check;

package/cli/dist/checks/context-layout.js

@@ -0,0 +1,83 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CONTEXT_FOLDERS } from "../config/schema.js";
+const KNOWLEDGE_CONTEXT = ["raw", "wiki", "features"];
+/** What .context must hold: README.md and tasks.md always, the knowledge folders only when docs or knowledge is on. */
+export function requiredContext(modules) {
+    const knowledge = modules.includes("docs") || modules.includes("knowledge");
+    return ["README.md", "tasks.md", ...(knowledge ? KNOWLEDGE_CONTEXT : [])];
+}
+const ROOT_FILES = ["README.md", "tasks.md"];
+const LIVE_FOLDERS = ["marketing", "metrics", "support", "legal"];
+const ROOT_STRAYS = ["TODO.md", "STATUS.md", "SETUP.md"];
+function emptyFolders(dir) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    if (entries.length === 0)
+        return [dir];
+    return entries.filter((entry) => entry.isDirectory()).flatMap((entry) => emptyFolders(join(dir, entry.name)));
+}
+function ignored(repo, path) {
+    return spawnSync("git", ["-C", repo, "check-ignore", "-q", path]).status === 0;
+}
+export const contextLayout = {
+    id: "context-layout",
+    module: null,
+    description: ".context/ has the required folders, only the allowed ones (the ten plus context.folders), and only README.md + tasks.md at its root",
+    run({ repo, config }) {
+        const context = join(repo, ".context");
+        const finding = (level, file, message) => ({
+            check: "context-layout",
+            level,
+            file,
+            message,
+        });
+        if (!existsSync(context))
+            return [finding("error", ".context", "no .context/ folder — run `canon init`")];
+        const findings = requiredContext(config.modules).filter((name) => !existsSync(join(context, name))).map((name) => finding("error", `.context/${name}`, `required ${name} is missing`));
+        const allowed = [...CONTEXT_FOLDERS, ...config.context.folders.map((entry) => entry.folder)];
+        for (const entry of readdirSync(context, { withFileTypes: true })) {
+            if (entry.name === ".DS_Store")
+                continue;
+            if (entry.isDirectory() && !allowed.includes(entry.name)) {
+                findings.push(finding("error", `.context/${entry.name}`, `${entry.name}/ is not an allowed folder — move it, or add it under context.folders in canon.yaml`));
+            }
+            if (entry.isFile() && !ROOT_FILES.includes(entry.name)) {
+                findings.push(finding("error", `.context/${entry.name}`, "only README.md and tasks.md may sit at .context/ root"));
+            }
+        }
+        if (existsSync(join(context, "raw")) && !existsSync(join(context, "raw", ".gitkeep"))) {
+            findings.push(finding("warn", ".context/raw/.gitkeep", "raw/ needs its .gitkeep so it survives a clean clone"));
+        }
+        // git drops an empty folder on clone, so on disk it promises something that is not there.
+        // A gitignored one is tool output that recreates itself.
+        for (const empty of emptyFolders(context)) {
+            if (empty !== join(context, "raw") && !ignored(repo, empty)) {
+                findings.push(finding("error", relative(repo, empty), "empty folder — git will drop it"));
+            }
+        }
+        // Once something is live, the go-to-market folders are owed. release.yml is the stage signal.
+        const release = join(context, "ops", "release.yml");
+        if (existsSync(release) && /^\s+live:(?!\s*null)/m.test(readFileSync(release, "utf8"))) {
+            for (const owed of LIVE_FOLDERS) {
+                if (!existsSync(join(context, owed)))
+                    findings.push(finding("error", `.context/${owed}`, `live (ops/release.yml) but no ${owed}/`));
+            }
+        }
+        for (const stray of ROOT_STRAYS) {
+            if (existsSync(join(repo, stray)))
+                findings.push(finding("error", stray, "nothing renders it at the root — it belongs in .context/ (tasks.md, ops/)"));
+        }
+        if (existsSync(join(repo, "docs")))
+            findings.push(finding("error", "docs/", "a root docs/ folder — that material belongs in .context/"));
+        if (existsSync(join(repo, "store.config.json")) && existsSync(join(context, "listing", "ios"))) {
+            findings.push(finding("error", "store.config.json", "two Apple listings — .context/listing/ios/ is the one source"));
+        }
+        // Without the pointer the whole .context/ tree is invisible to an agent.
+        const agents = join(repo, "AGENTS.md");
+        if (existsSync(agents) && !readFileSync(agents, "utf8").includes("tasks.md")) {
+            findings.push(finding("error", "AGENTS.md", "does not point at .context/tasks.md"));
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/context-size.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from "./types.ts";
+export declare const contextSize: Check;