@freetesh/canon 0.0.0-stage → 0.15.0

package/cli/dist/checks/external.js

@@ -0,0 +1,31 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+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))
+            .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/features.d.ts

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

package/cli/dist/checks/features.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { listFiles } from "../lib/files.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+const TYPES = ["feature", "experiment", "chore", "platform"];
+const STATUSES = ["planned", "building", "shipped", "shelved", "superseded"];
+// A chore or a platform change ships with nothing a user reads; a feature that never shipped keeps its target release.
+const NEEDS_STORE_COPY = ["feature", "experiment"];
+const NEVER_SHIPPED = ["shelved", "superseded"];
+const STORE_COPY = /^## Store copy[ \t]*\n([\s\S]*?)(?=^## |(?![\s\S]))/m;
+export const features = {
+    id: "features",
+    module: "docs",
+    description: "each features/ page has id, type and status from their sets; a released feature has its Store copy blockquote (the What's New text)",
+    run({ repo }) {
+        const pages = listFiles(repo, ".context/features", (name) => /^\d{4}-.+\.md$/.test(name));
+        return pages.flatMap((file) => {
+            const findings = [];
+            const add = (message) => findings.push({ check: "features", level: "error", file, message });
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            if (!data)
+                return [{ check: "features", level: "error", file, message: `no frontmatter (${basename(file)})` }];
+            for (const field of ["id", "type", "status"])
+                if (!data[field])
+                    add(`missing ${field}`);
+            if (data.type && !TYPES.includes(String(data.type)))
+                add(`type ${data.type} is not one of ${TYPES.join(", ")}`);
+            if (data.status && !STATUSES.includes(String(data.status)))
+                add(`status ${data.status} is not one of ${STATUSES.join(", ")}`);
+            const released = /\d+\.\d+\.\d+/.test(String(data.release ?? "")) && !NEVER_SHIPPED.includes(String(data.status));
+            const copy = STORE_COPY.exec(body.replace(/<!--[\s\S]*?-->/g, ""));
+            if (released && NEEDS_STORE_COPY.includes(String(data.type)) && !(copy && /^>[ \t]*\S/m.test(copy[1]))) {
+                add(`ships in ${data.release} with no "> …" line under ## Store copy`);
+            }
+            return findings;
+        });
+    },
+};

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

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

package/cli/dist/checks/index.js

@@ -0,0 +1,33 @@
+import { architecture } from "./architecture.js";
+import { canonicalValues } from "./canonical-values.js";
+import { contextLayout } from "./context-layout.js";
+import { contextSize } from "./context-size.js";
+import { staleCopies, standardsCopies } from "./copies.js";
+import { commandChecks } from "./external.js";
+import { features } from "./features.js";
+import { listing } from "./listing.js";
+import { metricsDefinitions } from "./metrics.js";
+import { pipeline } from "./pipeline.js";
+import { refs } from "./refs.js";
+import { sharedFiles } from "./shared-files.js";
+import { sources } from "./sources.js";
+import { tasks } from "./tasks.js";
+import { wikiFrontmatter } from "./wiki-frontmatter.js";
+export const ALL_CHECKS = [
+    contextLayout,
+    wikiFrontmatter,
+    contextSize,
+    tasks,
+    features,
+    listing,
+    canonicalValues,
+    standardsCopies,
+    sharedFiles,
+    refs,
+    staleCopies,
+    architecture,
+    metricsDefinitions,
+    sources,
+    pipeline,
+    commandChecks,
+];

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

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

package/cli/dist/checks/listing.js

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { listFiles } from "../lib/files.js";
+const LISTING = ".context/listing";
+// supply and deliver treat every folder in metadata/ as a locale, so a stray one aborts the upload.
+const NOT_LOCALES = ["review_information", "trade_representative_contact_information", "app_clip_review_information"];
+const LOCALE = /^[a-z]{2,3}(-([A-Za-z]{2}|[A-Za-z]{4}))?$/;
+const PLAY_TEXT = ["title.txt", "short_description.txt", "full_description.txt"];
+const PLAY_IMAGE_FOLDERS = ["phoneScreenshots", "sevenInchScreenshots", "tenInchScreenshots", "tvScreenshots", "wearScreenshots"];
+const folders = (path) => (existsSync(path) ? readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : []);
+export const listing = {
+    id: "listing",
+    module: "listing",
+    description: "listing/ is fastlane's tree: metadata/ per store, locale folders only, Play's three text files, fastlane image folders, zero-padded screenshots",
+    run({ repo }) {
+        const root = join(repo, LISTING);
+        if (!existsSync(root))
+            return [];
+        const findings = [];
+        const add = (file, message) => findings.push({ check: "listing", level: "error", file, message });
+        for (const store of ["android", "ios"]) {
+            if (!existsSync(join(root, store)))
+                continue;
+            const metadata = join(root, store, "metadata");
+            if (!existsSync(metadata)) {
+                add(`${LISTING}/${store}/`, "no metadata/ folder");
+                continue;
+            }
+            for (const name of folders(metadata)) {
+                if (!NOT_LOCALES.includes(name) && !LOCALE.test(name))
+                    add(`${LISTING}/${store}/metadata/${name}`, "not a locale — fastlane would upload it as one");
+            }
+        }
+        for (const locale of folders(join(root, "android", "metadata"))) {
+            const at = `${LISTING}/android/metadata/${locale}`;
+            for (const file of PLAY_TEXT)
+                if (!existsSync(join(repo, at, file)))
+                    add(`${at}/${file}`, "missing");
+            for (const name of folders(join(repo, at, "images"))) {
+                if (!PLAY_IMAGE_FOLDERS.includes(name))
+                    add(`${at}/images/${name}`, "not a fastlane image folder");
+            }
+        }
+        // Play ships screenshots in file-name order, so `2-` sorts after `10-`.
+        for (const file of listFiles(repo, LISTING, (name) => name.endsWith(".png"))) {
+            if (/[Ss]creenshots\//.test(file) && /\/\d-[^/]*$/.test(file))
+                add(file, "unpadded screenshot number — name it NN-<screen>.png");
+        }
+        return findings;
+    },
+};

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

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

package/cli/dist/checks/metrics.js

@@ -0,0 +1,14 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const DEFINITIONS = ".context/metrics/definitions.yml";
+export const metricsDefinitions = {
+    id: "metrics-definitions",
+    module: "metrics",
+    description: "metrics/definitions.yml names the numbers the weigh gate measures value against",
+    run({ repo }) {
+        if (existsSync(join(repo, DEFINITIONS)))
+            return [];
+        // A warning: most products turn metrics on before they define a single number.
+        return [{ check: "metrics-definitions", level: "warn", file: DEFINITIONS, message: "no metric definitions — the weigh gate cannot name the metric a request moves" }];
+    },
+};

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

@@ -0,0 +1,8 @@
+import type { Check } from "./types.ts";
+/**
+ * Stages run in the order canon.yaml lists them. A stage has started once one
+ * of its `done` paths exists; a gated stage must be approved before any later
+ * stage starts. Each unapproved gate is reported once, at the first later
+ * stage that started.
+ */
+export declare const pipeline: Check;

package/cli/dist/checks/pipeline.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readApprovals } from "../pipeline.js";
+/**
+ * Stages run in the order canon.yaml lists them. A stage has started once one
+ * of its `done` paths exists; a gated stage must be approved before any later
+ * stage starts. Each unapproved gate is reported once, at the first later
+ * stage that started.
+ */
+export const pipeline = {
+    id: "pipeline",
+    module: null,
+    description: "no stage starts before every earlier gate is approved",
+    run({ repo, config }) {
+        const approved = new Set(readApprovals(repo).map((approval) => approval.stage));
+        const startedAt = config.pipeline.map((stage) => stage.done.find((path) => existsSync(join(repo, path))));
+        return config.pipeline.flatMap((gate, index) => {
+            if (!gate.gate || approved.has(gate.id))
+                return [];
+            const later = config.pipeline.findIndex((_, i) => i > index && startedAt[i] !== undefined);
+            if (later === -1)
+                return [];
+            const stage = config.pipeline[later];
+            return [
+                {
+                    check: "pipeline",
+                    level: "error",
+                    file: startedAt[later],
+                    message: `stage "${stage.id}" started before gate "${gate.id}" was approved — review ${gate.id}, then a person runs \`canon approve ${gate.id}\``,
+                },
+            ];
+        });
+    },
+};

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

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

package/cli/dist/checks/refs.js

@@ -0,0 +1,92 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, normalize } from "node:path";
+import { usedCopies } from "./shared-files.js";
+// A `.context/` path not preceded by something that makes it part of a longer one (another
+// product's, an absolute path, a URL). A leading `./` means "beside this file".
+const PATH = /(?<![\w/~.-])(\.\/)?(\.context\/[\w./@+-]*)/g;
+const PLACEHOLDER = /[<{*[$]|YYYY|NNNN/;
+const LINK = /\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g;
+// A line reading a path out of git history names it as it was.
+const FROM_HISTORY = /git (show|checkout|log|diff|restore)\b/;
+// Dated records keep a path as it was on the day.
+const DATED = /(^|\/)CHANGELOG\.md$|^\.context\/ops\/incidents\//;
+const BINARY = /\.(png|jpe?g|gif|webp|ico|icns|mp4|mov|pdf|zip|aab|apk|jks|keystore|p8|p12|ttf|otf|woff2?|lock|snap|sqlite|db|bin)$|(^|\/)pnpm-lock\.yaml$/i;
+const FEATURE_FILE = /^\.context\/features\/(\d{4})-[^/]+\.md$/;
+// A pipeline stage's `done:` paths name what will exist once that stage starts.
+const STAGE_DONE = /^\s*-\s*\{[^}]*\bdone:\s*\[/;
+function git(repo, args) {
+    const result = spawnSync("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+/** The part of a path that names something real: cut back to the last whole folder before a placeholder. */
+function literalPart(token, restOfLine) {
+    let path = token.replace(/[.,;:]+$/, "");
+    const cut = PLACEHOLDER.exec(path);
+    if (cut || PLACEHOLDER.test(restOfLine.slice(0, 1))) {
+        path = cut ? path.slice(0, cut.index) : path;
+        path = path.slice(0, path.lastIndexOf("/") + 1);
+    }
+    return path.replace(/^[./]+|[./]+$/g, "") === "context" ? null : path;
+}
+export const refs = {
+    id: "refs",
+    // A module, not always on: a repo whose docs describe other repos' .context/ (a tool, a portfolio) does not use it.
+    module: "refs",
+    description: "every .context/ path a tracked file names exists; a [[link]] names a page (a link to a page not yet written is a note)",
+    run({ repo, config }) {
+        const listed = git(repo, ["ls-files", "-z"]);
+        if (listed.status !== 0)
+            return [];
+        const files = listed.stdout.split("\0").filter((file) => file && !BINARY.test(file));
+        // A copy of the source repo's file carries the source's paths; the product cannot edit it.
+        const copied = new Set(usedCopies(config).map((pair) => pair.to));
+        const pages = new Set(files.filter((f) => f.startsWith(".context/wiki/") && f.endsWith(".md")).map((f) => basename(f, ".md")));
+        const features = new Set(files.flatMap((f) => (FEATURE_FILE.exec(f) ? [`FEAT-${FEATURE_FILE.exec(f)[1]}`] : [])));
+        const resolves = (target) => pages.has(target) || features.has(target) || existsSync(join(repo, ".context", `${target}.md`));
+        const exists = new Map();
+        const present = (path) => {
+            if (!exists.has(path)) {
+                exists.set(path, existsSync(join(repo, path)) || git(repo, ["check-ignore", "-q", path]).status === 0);
+            }
+            return exists.get(path);
+        };
+        const findings = [];
+        for (const file of files) {
+            if (copied.has(file))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(repo, file), "utf8");
+            }
+            catch {
+                continue; // deleted in the working tree, or a submodule
+            }
+            const dated = DATED.test(file);
+            const links = file.startsWith(".context/") && file.endsWith(".md");
+            text.split("\n").forEach((line, index) => {
+                const at = `${file}:${index + 1}`;
+                const future = file === ".claude/canon.yaml" && STAGE_DONE.test(line);
+                if (!dated && !future && line.includes(".context/") && !FROM_HISTORY.test(line)) {
+                    for (const match of line.matchAll(PATH)) {
+                        let path = literalPart(match[2], line.slice(match.index + match[0].length));
+                        if (path === null)
+                            continue;
+                        if (match[1])
+                            path = normalize(join(dirname(file), path)) + (path.endsWith("/") ? "/" : "");
+                        if (!present(path))
+                            findings.push({ check: "refs", level: "error", file: at, message: `${path} does not exist` });
+                    }
+                }
+                if (links && line.includes("[[")) {
+                    for (const match of line.matchAll(LINK)) {
+                        const target = match[1].trim();
+                        if (!resolves(target))
+                            findings.push({ check: "refs", level: "warn", file: at, message: `[[${target}]] names no page yet` });
+                    }
+                }
+            });
+        }
+        return findings;
+    },
+};

package/cli/dist/checks/shared-files.d.ts

@@ -0,0 +1,22 @@
+import type { Config } from "../config/schema.ts";
+import type { Check } from "./types.ts";
+export interface Pair {
+    set: string;
+    from: string;
+    to: string;
+    named: boolean;
+    until?: string;
+}
+/** Every file of every set the product uses, as source → product paths. */
+export declare function usedCopies(config: Config): Pair[];
+export interface CopyState {
+    pair: Pair;
+    state: "same" | "drift" | "missing" | "unknown-set" | "no-source" | "unnamed";
+    /** What the product file should hold; set for a drift --sync can repair. */
+    want?: string;
+}
+/** Compares every file of every set the product uses with the source repo. */
+export declare function compareCopies(repo: string, config: Config): CopyState[];
+/** Overwrites each drifted copy with the source's. Never adds a missing file. Returns the paths written. */
+export declare function syncCopies(repo: string, config: Config): string[];
+export declare const sharedFiles: Check;

package/cli/dist/checks/shared-files.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+// canon init writes the README heading `# .context — <Name>`; a product without a `name:` is read from it.
+const README_NAME = /^# \.context — (.+)$/m;
+const pairOf = (set, file) => typeof file === "string" ? { set, from: file, to: file, named: false } : { set, from: file.from, to: file.to ?? file.from, named: file.named ?? false, until: file.until };
+/** Every file of every set the product uses, as source → product paths. */
+export function usedCopies(config) {
+    return config.copies.use.flatMap((set) => (config.copies.sets[set] ?? []).map((file) => pairOf(set, file)));
+}
+function nameOf(repo, config) {
+    if (config.name)
+        return config.name;
+    const readme = join(repo, ".context", "README.md");
+    return existsSync(readme) ? README_NAME.exec(readFileSync(readme, "utf8"))?.[1]?.trim() : undefined;
+}
+function split(text, marker) {
+    const lines = text.split("\n");
+    const at = lines.findIndex((line) => line.includes(marker));
+    return at === -1 ? null : { shared: lines.slice(0, at).join("\n"), own: lines.slice(at).join("\n") };
+}
+/** Compares every file of every set the product uses with the source repo. */
+export function compareCopies(repo, config) {
+    const { source, sets, use } = config.copies;
+    if (use.length === 0 || !source || resolve(source) === resolve(repo))
+        return [];
+    const unknown = use.filter((set) => !sets[set]).map((set) => ({ pair: { set, from: "", to: "", named: false }, state: "unknown-set" }));
+    const productName = nameOf(repo, config);
+    const sourceName = nameOf(source, loadConfig(source).config);
+    return [
+        ...unknown,
+        ...usedCopies(config).map((pair) => {
+            const from = join(source, pair.from);
+            const to = join(repo, pair.to);
+            if (!existsSync(from))
+                return { pair, state: "no-source" };
+            if (!existsSync(to))
+                return { pair, state: "missing" };
+            if (pair.named && (!productName || !sourceName))
+                return { pair, state: "unnamed" };
+            const original = pair.named ? readFileSync(from, "utf8").replaceAll(sourceName, productName) : readFileSync(from, "utf8");
+            const current = readFileSync(to, "utf8");
+            if (!pair.until)
+                return original === current ? { pair, state: "same" } : { pair, state: "drift", want: original };
+            const theirs = split(original, pair.until);
+            const ours = split(current, pair.until);
+            if (theirs && ours && theirs.shared === ours.shared)
+                return { pair, state: "same" };
+            // Without the marker the product's own part cannot be told from the shared one, so nothing is written.
+            return { pair, state: "drift", want: theirs && ours ? `${theirs.shared}\n${ours.own}` : undefined };
+        }),
+    ];
+}
+/** Overwrites each drifted copy with the source's. Never adds a missing file. Returns the paths written. */
+export function syncCopies(repo, config) {
+    return compareCopies(repo, config).flatMap(({ pair, state, want }) => {
+        if (state !== "drift" || want === undefined)
+            return [];
+        writeFileSync(join(repo, pair.to), want);
+        return [pair.to];
+    });
+}
+export const sharedFiles = {
+    id: "shared-files",
+    module: null,
+    description: "every file of every copies set the product uses exists and matches copies.source",
+    run({ repo, config }) {
+        const source = config.copies.source ? basename(config.copies.source) : "copies.source";
+        return compareCopies(repo, config).flatMap(({ pair, state }) => {
+            const finding = (file, message) => [{ check: "shared-files", level: "error", file, message }];
+            if (state === "unknown-set")
+                return finding(".claude/canon.yaml", `copies.use names ${pair.set}, which no copies.sets defines`);
+            if (state === "no-source")
+                return finding(pair.to, `${source} has no ${pair.from} (set ${pair.set})`);
+            if (state === "missing")
+                return finding(pair.to, `missing — set ${pair.set} is in use; copy it from ${source}`);
+            if (state === "unnamed")
+                return finding(pair.to, "no product name to compare with — set name: in canon.yaml");
+            if (state === "drift")
+                return finding(pair.to, `differs from ${source}${pair.until ? " above the shared block's end" : ""} — \`canon copies --sync\` copies it`);
+            return [];
+        });
+    },
+};

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

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

package/cli/dist/checks/sources.js

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+// canon has no connectors: a source page must say which MCP server, skill or CLI
+// reads it, or that a person reads it by hand (`manual:`), or the weigh gate
+// cannot turn a claim into a fact.
+const ACCESS = /^(mcp|skill|cli|manual):\s*(\S+)/;
+const HOW_TO_QUERY = /^## How to query\s*$/m;
+function accessValue(body, id) {
+    const row = body.split("\n").find((line) => line.replace(/\s/g, "").startsWith(`|${id}.ACCESS|`));
+    return row ? (row.split("|")[2]?.trim() ?? "") : null;
+}
+export const sources = {
+    id: "sources",
+    module: "docs",
+    description: "each SOURCE.* entity page says how to read it (mcp, skill, manual, or a cli in doctor.tools) and has a How to query section",
+    run({ repo, config }) {
+        const tools = new Set(config.doctor.tools.map((tool) => tool.tool));
+        return wikiPages(repo).flatMap((file) => {
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            const id = String(data?.id ?? "");
+            if (!file.startsWith(".context/wiki/entities/") || !id.startsWith("SOURCE."))
+                return [];
+            const findings = [];
+            const add = (message) => findings.push({ check: "sources", level: "error", file, message });
+            if (!HOW_TO_QUERY.test(body))
+                add("no `## How to query` section");
+            const access = accessValue(body, id);
+            const match = access === null ? null : ACCESS.exec(access);
+            if (access === null)
+                add(`no ${id}.ACCESS row — say how to read it`);
+            else if (!match)
+                add(`${id}.ACCESS is "${access}" — write mcp: <server>, skill: <name>, cli: <command> or manual: <where>`);
+            else if (match[1] === "cli" && !tools.has(match[2]))
+                add(`cli ${match[2]} is not in doctor.tools — canon doctor cannot report it missing`);
+            return findings;
+        });
+    },
+};

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

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

package/cli/dist/checks/tasks.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const TASKS = ".context/tasks.md";
+const COMMENT = /<!--[\s\S]*?-->/g;
+const ITEM = /^(?:\d+\.|[-*]) \[[ xX]\] +(T\d+\b)?/gm;
+const ISO_DATE = /\d{4}-\d{2}-\d{2}/;
+// A blocker with no way out and no check date is the silent leak the format exists to stop.
+const BLOCKED_FIELDS = ["blocked-by", "unblock", "next-check"];
+function sectionOf(text, name) {
+    const clean = text.replace(COMMENT, "");
+    const headings = [...clean.matchAll(/^## +(\S[^\n]*?)[ \t]*$/gm)];
+    const at = headings.findIndex((heading) => heading[1].startsWith(name));
+    if (at === -1)
+        return "";
+    const start = headings[at].index + headings[at][0].length;
+    return clean.slice(start, headings[at + 1]?.index ?? clean.length);
+}
+function fieldOf(item, field) {
+    const found = new RegExp(`(?<![\\w-])${field}:[ \\t]*([^\\n]*)`).exec(item);
+    return found ? found[1].trim() : null;
+}
+function asDate(value) {
+    const found = ISO_DATE.exec(value);
+    if (!found)
+        return null;
+    const date = new Date(`${found[0]}T00:00:00Z`);
+    return Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== found[0] ? null : date;
+}
+export const tasks = {
+    id: "tasks",
+    module: null,
+    description: "every blocked task has an id, blocked-by, unblock and next-check; a passed date is a note",
+    run({ repo, today }) {
+        const path = join(repo, TASKS);
+        if (!existsSync(path))
+            return [];
+        const text = readFileSync(path, "utf8");
+        const findings = [];
+        const add = (level, message) => findings.push({ check: "tasks", level, file: TASKS, message });
+        const horizon = /^horizon:\s*(\S+)/m.exec(text);
+        const horizonDate = horizon ? asDate(horizon[1]) : null;
+        if (horizonDate && horizonDate < today)
+            add("warn", `past its horizon (${horizon[1]}) — regenerate it`);
+        const blocked = sectionOf(text, "Blocked");
+        const starts = [...blocked.matchAll(ITEM)];
+        starts.forEach((start, index) => {
+            const item = blocked.slice(start.index, starts[index + 1]?.index ?? blocked.length);
+            const id = start[1];
+            if (!id)
+                return add("error", `blocked item without a task id: ${item.split("\n")[0].trim().slice(0, 60)}`);
+            for (const field of BLOCKED_FIELDS)
+                if (!fieldOf(item, field))
+                    add("error", `${id} is blocked without ${field}:`);
+            // next-check may be prose ("after T010"); only something shaped like a date can be a bad one.
+            const check = fieldOf(item, "next-check") ?? "";
+            if (ISO_DATE.test(check)) {
+                const on = asDate(check);
+                if (!on)
+                    add("error", `${id} next-check: ${check} is not a date`);
+                else if (on < today)
+                    add("warn", `${id} was to be checked on ${check}`);
+            }
+        });
+        return findings;
+    },
+};

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

@@ -0,0 +1,23 @@
+import type { Config, Module } from "../config/schema.ts";
+export type Level = "error" | "warn";
+export interface Finding {
+    check: string;
+    level: Level;
+    message: string;
+    file?: string;
+}
+export interface CheckContext {
+    repo: string;
+    name: string;
+    config: Config;
+    /** Root of the canon repo, where standards/ and skills/ live. */
+    canonRoot: string;
+    today: Date;
+}
+export interface Check {
+    id: string;
+    /** The module that must be enabled for this check to run; null = always. */
+    module: Module | null;
+    description: string;
+    run(context: CheckContext): Finding[];
+}

package/cli/dist/checks/types.js

@@ -0,0 +1 @@
+export {};

package/cli/dist/checks/wiki-frontmatter.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "./types.ts";
+export declare function wikiPages(repo: string): string[];
+export declare const wikiFrontmatter: Check;