@freetesh/zeno 0.10.0 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less.",
   "author": {
     "name": "Ritesh Firodiya",

package/README.md

@@ -54,8 +54,19 @@ It has two halves that read the same config:
   `.context` layout, agent contract). A team adds or replaces them from its own
   folder; a repo can override again. `zeno standards` shows what applies.
 - **Hard rules are checks.** `zeno check` validates layout, wiki frontmatter,
-  stale pages, prices with no canonical home, copied standards, and runs every
-  checker your config declares.
+  stale pages, placeholder text, page and `tasks.md` size caps, blocked tasks,
+  feature pages, the store listing tree, dead `.context/` paths, prices with no
+  canonical home, files shared across products, and runs every checker your
+  config declares. `zeno hooks install` makes every push run it.
+- **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.
+- **Stages stop at their gates.** A `pipeline:` in `zeno.yaml` lists your
+  stages in order, with the paths that show each has started. A gated stage
+  needs a person to run `zeno approve <stage>` before any later stage starts;
+  `zeno check` fails otherwise. Approvals are dated in
+  `.context/raw/zeno/gates.jsonl`, so you can see where work waits. A product
+  replaces the estate's pipeline by declaring its own.
 - **Each repo's architecture is enforced.** With the `architecture` module, a
   repo keeps its own import rules in `.dependency-cruiser.cjs` files: one at the
   root, or one per workspace under `apps/` and `packages/` (each runs from its
@@ -114,6 +125,8 @@ zeno init -y --kind web --modules docs,code --packs nextjs   # same, no question
 zeno add              # list packs; `zeno add expo` adds one and indexes its docs (-g: whole estate)
 zeno check            # this repo against the standards (exit 1 on any error)
 zeno check --all -q   # every repo in the estate, only the ones with findings
+zeno copies --sync    # overwrite drifted shared files from copies.source (never adds one)
+zeno hooks install    # a pre-push hook that runs `zeno check` (--all: every product)
 zeno standards        # which standards apply here, and where each comes from
 zeno sync             # refresh pack docs + search index, move the pinned zeno version, then check
 zeno status           # version, kind, modules, config layers, check summary
@@ -141,7 +154,7 @@ doctor:
   tools:
     - { tool: pnpm, why: product scripts, hint: npm i -g pnpm }
 wiki:
-  types:                            # added to the six built-in page types
+  types:                            # added to the built-in folders (concepts, entities, decisions, surfaces, synthesis)
     - type: postmortem
       folder: postmortems
       reason: incidents need a timeline and a fix
@@ -149,11 +162,17 @@ wiki:
 context:
   folders:                          # added to the ten .context folders
     - { folder: research, reason: interview notes, kept apart from raw/ }
+copies:                             # files every product copies from one source repo
+  source: charades                  # a folder beside the estate config
+  files:
+    - scripts/play-upload.mjs       # same path; a product carries it or skips it
+    - { from: .context/designs/mobile/index.html, to: [.context/designs/mobile/index.html, .context/designs/web/index.html], named: true }
+    - { from: .context/designs/mobile/shared.css, to: [.context/designs/mobile/shared.css], until: "PALETTE — " }
 ```
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
-zeno: 0.9.0
+zeno: 0.11.0
 kind: expo-app                      # expo-app | web | content
 modules: [docs, knowledge, code, listing]   # all optional; design is added when .context/designs exists, metrics only when asked
 packs: [expo]
@@ -161,6 +180,10 @@ checks:
   stale-copies: { enabled: false, reason: "Cursor is still used here" }
 weigh:
   weights: { C-05: 2 }
+name: Chitragupt                    # how the product is written; `named` copies swap it in
+copies:
+  skip:                             # shared files this product does without, or keeps its own of
+    - { file: scripts/release-android.mjs, reason: built on EAS from a tag }
 ```
 
 Scalars: the most specific layer wins. `packs` and `standards` add up across
@@ -173,8 +196,8 @@ carry a `reason:`, and `zeno check` lists every override.
 | zeno default | What it holds |
 |---|---|
 | `constitution.md` | Principles C-01–C-15 a request is weighed against. A team adds C-20+ in its own `constitution.md`. |
-| `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
-| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` |
+| `wiki-schema.md` | What belongs in the wiki, its folders, decisions, frontmatter and size caps |
+| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` (open work only) |
 | `agent-contract.md` | What every agent does before, during and after work |
 
 ## Packs

package/cli/dist/checks/architecture.js

@@ -29,6 +29,13 @@ export function findRules(repo) {
     });
 }
 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");
@@ -81,7 +88,9 @@ export const architecture = {
             const result = depcruise(repo, bin, rules, ["--output-type", "json"]);
             try {
                 const cruise = JSON.parse(result.stdout);
-                const findings = summarize(cruise.summary.violations.map((v) => ({ ...v, from: fromRoot(rules.dir, v.from), to: fromRoot(rules.dir, v.to) })));
+                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 {

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

@@ -10,25 +10,27 @@ const PRICE_WORDS = /pric|cost|paywall|plan|tier|subscri|bundle|pack|purchase|bu
 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/);
+    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 shown on a surface page is held by an entity page — one home per fact (C-04)",
+    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 live = pages.filter((page) => page.data?.status !== "superseded");
-        const held = new Set(live.filter((page) => page.data?.type === "entity").flatMap((page) => heldAmounts(page.body)));
-        // Surfaces are where store prices get restated. Concepts legitimately carry
+        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 live
-            .filter((page) => page.data?.type === "surface")
+        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)

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

@@ -1,5 +1,6 @@
-import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+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. */
@@ -8,6 +9,17 @@ export function requiredContext(modules) {
     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,
@@ -37,6 +49,35 @@ export const contextLayout = {
         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.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { REMOVED_WIKI_FOLDERS as REMOVED_FOLDERS } from "../config/schema.js";
+import { wikiPages } from "./wiki-frontmatter.js";
+// Every line here is read by an agent on every task; a cap keeps .context to what it would get wrong without.
+const MAX_LINES = { page: 60, decision: 30, readme: 30, tasks: 100 };
+const DATED_NAME = /^\d{4}-\d{2}-\d{2}-/;
+const lineCount = (repo, file) => readFileSync(join(repo, file), "utf8").trimEnd().split("\n").length;
+export const contextSize = {
+    id: "context-size",
+    module: "docs",
+    description: "pages, decisions, README.md and tasks.md stay under their line caps; decisions are one file per topic; no flow pages",
+    run({ repo }) {
+        const findings = [];
+        const warn = (file, message) => findings.push({ check: "context-size", level: "warn", file, message });
+        const overCap = (file, cap) => {
+            const lines = lineCount(repo, file);
+            if (lines > cap)
+                warn(file, `${lines} lines, cap ${cap} — cut what code, designs or git already say`);
+        };
+        for (const [folder, why] of Object.entries(REMOVED_FOLDERS)) {
+            if (existsSync(join(repo, ".context/wiki", folder)))
+                warn(`.context/wiki/${folder}`, `${folder}/ is gone: ${why}`);
+        }
+        for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder === "synthesis" || folder in REMOVED_FOLDERS)
+                continue;
+            if (folder === "decisions" && DATED_NAME.test(basename(file))) {
+                warn(file, "name a decision by topic and edit it in place — git keeps the history");
+            }
+            overCap(file, folder === "decisions" ? MAX_LINES.decision : MAX_LINES.page);
+        }
+        const readme = ".context/README.md";
+        const tasks = ".context/tasks.md";
+        if (existsSync(join(repo, readme)))
+            overCap(readme, MAX_LINES.readme);
+        if (existsSync(join(repo, tasks))) {
+            overCap(tasks, MAX_LINES.tasks);
+            if (/^## (Done|Session Notes)\b/m.test(readFileSync(join(repo, tasks), "utf8"))) {
+                warn(tasks, "tasks.md holds only open work — delete done tasks and session notes; the commits record them");
+            }
+        }
+        return findings;
+    },
+};

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.js

@@ -1,19 +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.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/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 zeno.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 \`zeno approve ${gate.id}\``,
+                },
+            ];
+        });
+    },
+};

package/cli/dist/checks/refs.js

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, normalize } from "node:path";
+// 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$/;
+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",
+    module: null,
+    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(config.copies.files.flatMap((file) => (typeof file === "string" ? [file] : (file.to ?? [file.from]))));
+        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}`;
+                if (!dated && 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.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+// zeno init writes the README heading `# .context — <Name>`; a product without a `name:` is read from it.
+const README_NAME = /^# \.context — (.+)$/m;
+function pairsOf(file) {
+    if (typeof file === "string")
+        return [{ from: file, to: file, required: true, named: false }];
+    return (file.to ?? [file.from]).map((to) => ({ from: file.from, to, required: false, named: file.named ?? false, until: file.until }));
+}
+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 above(text, marker) {
+    const lines = text.split("\n");
+    const at = lines.findIndex((line) => line.includes(marker));
+    return (at === -1 ? lines : lines.slice(0, at)).join("\n");
+}
+function below(text, marker) {
+    const lines = text.split("\n");
+    const at = lines.findIndex((line) => line.includes(marker));
+    return at === -1 ? "" : lines.slice(at).join("\n");
+}
+/** Compares every shared file of `repo` with the source repo. Skipped files and files absent from the source are left out. */
+export function compareCopies(repo, config) {
+    const { source, files, skip } = config.copies;
+    if (!source || files.length === 0 || resolve(source) === resolve(repo))
+        return [];
+    const skipped = new Set(skip.map((entry) => entry.file));
+    const productName = nameOf(repo, config);
+    const sourceName = nameOf(source, loadConfig(source).config);
+    const states = [];
+    for (const pair of files.flatMap(pairsOf)) {
+        const from = join(source, pair.from);
+        const to = join(repo, pair.to);
+        if (skipped.has(pair.to) || !existsSync(from))
+            continue;
+        if (!existsSync(to)) {
+            if (pair.required)
+                states.push({ pair, state: "missing" });
+            continue;
+        }
+        if (pair.named && (!productName || !sourceName)) {
+            states.push({ pair, state: "unnamed" });
+            continue;
+        }
+        const original = readFileSync(from, "utf8");
+        const current = readFileSync(to, "utf8");
+        let want = pair.named ? original.replaceAll(sourceName, productName) : original;
+        let have = current;
+        if (pair.until) {
+            want = above(want, pair.until);
+            have = above(current, pair.until);
+        }
+        if (want === have)
+            states.push({ pair, state: "same" });
+        // Without the marker the product's own part cannot be told from the shared one, so nothing is written.
+        else if (pair.until && !current.includes(pair.until))
+            states.push({ pair, state: "drift" });
+        else
+            states.push({ pair, state: "drift", want: pair.until ? `${want}\n${below(current, pair.until)}` : want });
+    }
+    return states;
+}
+/** Overwrites each drifted copy with the source's. Never adds a missing file. Returns the paths written. */
+export function syncCopies(repo, config) {
+    const written = [];
+    for (const { pair, state, want } of compareCopies(repo, config)) {
+        if (state !== "drift" || want === undefined)
+            continue;
+        writeFileSync(join(repo, pair.to), want);
+        written.push(pair.to);
+    }
+    return written;
+}
+export const sharedFiles = {
+    id: "shared-files",
+    module: null,
+    description: "files copied from the copies.source repo are identical to it; one a product does without is skipped with a reason",
+    run({ repo, config }) {
+        const source = config.copies.source ? basename(config.copies.source) : "";
+        return compareCopies(repo, config).flatMap(({ pair, state }) => {
+            const finding = (message) => [{ check: "shared-files", level: "error", file: pair.to, message }];
+            if (state === "missing")
+                return finding(`missing — copy it from ${source}, or add it under copies.skip with a reason`);
+            if (state === "unnamed")
+                return finding(`no product name to compare with — set name: in zeno.yaml`);
+            if (state === "drift")
+                return finding(`differs from ${source}${pair.until ? " above the shared block's end" : ""} — \`zeno copies --sync\` copies it`);
+            return [];
+        });
+    },
+};