@freetesh/zeno 0.11.0 → 0.13.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.11.0",
+  "version": "0.13.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,10 @@ 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, placeholder text, page and `tasks.md` size caps, 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.
@@ -123,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
@@ -158,24 +162,33 @@ wiki:
 context:
   folders:                          # added to the ten .context folders
     - { folder: research, reason: interview notes, kept apart from raw/ }
+copies:                             # files products copy from one source repo, in named sets
+  source: charades                  # a folder beside the estate config
+  sets:
+    play-upload: [scripts/play-upload.mjs]            # the same path on both sides
+    design-shell-web:
+      - { from: .context/designs/mobile/index.html, to: .context/designs/web/index.html, named: true }
+      - { from: .context/designs/mobile/shared.css, to: .context/designs/web/shared.css, until: "PALETTE — " }
 ```
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
-zeno: 0.11.0
+zeno: 0.13.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]
-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:
+  use: [play-upload, design-shell-web]   # the sets this product uses; only these are held to the source
 ```
 
 Scalars: the most specific layer wins. `packs` and `standards` add up across
 layers; `commands`, `doctor.tools`, `wiki.types` and `context.folders` merge
-by name. Built-in types and folders cannot be removed or redefined. A check turned off must
-carry a `reason:`, and `zeno check` lists every override.
+by name; `copies.use` adds up. Built-in types and folders cannot be removed or
+redefined. A repo names only what it uses: a check applies through the modules
+it turns on, and there is no setting to skip one.
 
 ## Standards
 

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

@@ -17,6 +17,7 @@ export const commandChecks = {
     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) {

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

@@ -4,16 +4,26 @@ 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,

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

@@ -0,0 +1,89 @@
+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$/;
+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 tool whose docs describe other repos' .context/ (zeno, canon) 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}`;
+                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,84 @@
+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;
+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/zeno.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 zeno.yaml");
+            if (state === "drift")
+                return finding(pair.to, `differs from ${source}${pair.until ? " above the shared block's end" : ""} — \`zeno copies --sync\` copies it`);
+            return [];
+        });
+    },
+};

package/cli/dist/checks/sources.js

@@ -14,13 +14,13 @@ function accessValue(body, id) {
 export const sources = {
     id: "sources",
     module: "docs",
-    description: "each SOURCE.* page says how to read it (mcp, skill, manual, or a cli in doctor.tools) and has a How to query section",
+    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 (data?.type !== "entity" || !id.startsWith("SOURCE."))
+            if (!file.startsWith(".context/wiki/entities/") || !id.startsWith("SOURCE."))
                 return [];
             const findings = [];
             const add = (message) => findings.push({ check: "sources", level: "error", file, message });

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/wiki-frontmatter.js

@@ -61,6 +61,8 @@ export const wikiFrontmatter = {
             const age = verified ? Math.floor((today.getTime() - verified.getTime()) / DAY_MS) : 0;
             if (verified && age > STALE_AFTER_DAYS)
                 stale.push({ file, age });
+            if (verified && age < 0)
+                add("error", file, `last-verified ${data["last-verified"]} is in the future`);
             if (data.id)
                 filesById.set(String(data.id), [...(filesById.get(String(data.id)) ?? []), file]);
         }

package/cli/dist/commands/copies.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { compareCopies, syncCopies } from "../checks/shared-files.js";
+import { loadConfig } from "../config/load.js";
+export function registerCopies(program, env) {
+    program
+        .command("copies")
+        .description("compare a product's shared files with copies.source; --sync overwrites the drifted ones")
+        .argument("[repo]", "product repo", ".")
+        .option("--sync", "overwrite drifted copies from the source (never adds a missing file)")
+        .action((repo, options) => {
+        const path = resolve(repo);
+        const { config } = loadConfig(path, { estateRoot: env.estateRoot });
+        if (options.sync) {
+            const written = syncCopies(path, config);
+            console.log(written.length ? written.map((file) => `  synced: ${file}`).join("\n") : "  nothing to sync");
+            return;
+        }
+        const off = compareCopies(path, config).filter((entry) => entry.state !== "same");
+        console.log(off.length ? off.map(({ pair, state }) => `  ${state}: ${pair.to}`).join("\n") : "  ok");
+        if (off.length)
+            process.exitCode = 1;
+    });
+}

package/cli/dist/commands/hooks.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findProducts } from "../run.js";
+import { requireEstate } from "./env.js";
+const MARK = "installed by `zeno hooks install`";
+// Hooks written by the estate script this command replaced; they are ours to overwrite.
+const OLD_MARKS = [MARK, "installed by ~/git/bin/install-hooks"];
+export const HOOK = `#!/bin/sh
+# ${MARK} — run it again rather than editing this file.
+# A machine without zeno pushes unchecked, as it would without any hook.
+command -v zeno >/dev/null 2>&1 || exit 0
+# The product is the folder that owns .git, not the folder being pushed from: a worktree shares these hooks.
+root=$(cd "$(git rev-parse --git-common-dir)/.." && pwd) || exit 0
+exec zeno check "$root"
+`;
+const ours = (path) => OLD_MARKS.some((mark) => readFileSync(path, "utf8").includes(mark));
+/** Writes the pre-push hook into one repo. Returns a one-line outcome. */
+export function installHook(repo) {
+    if (!existsSync(join(repo, ".git")))
+        return `skipped: ${repo} is not a git repo`;
+    if (!existsSync(join(repo, ".context", "tasks.md"))) {
+        const old = join(repo, ".git", "hooks", "pre-push");
+        if (existsSync(old) && ours(old)) {
+            renameSync(old, `${old}.disabled`);
+            return `disabled: ${repo} has no .context/tasks.md, so it would never pass`;
+        }
+        return `skipped: ${repo} has no .context/tasks.md`;
+    }
+    const hooksPath = spawnSync("git", ["-C", repo, "config", "core.hooksPath"], { encoding: "utf8" }).stdout.trim();
+    // husky points core.hooksPath at .husky/_, whose stubs run .husky/<name>.
+    const target = hooksPath === "" ? join(repo, ".git", "hooks", "pre-push") : hooksPath === ".husky/_" ? join(repo, ".husky", "pre-push") : null;
+    if (!target)
+        return `SKIPPED: ${repo} sets core.hooksPath=${hooksPath} — add the hook there by hand`;
+    if (existsSync(target) && (lstatSync(target).isSymbolicLink() || !ours(target)))
+        return `SKIPPED: ${target} exists and is not zeno's`;
+    writeFileSync(target, HOOK);
+    chmodSync(target, 0o755);
+    return target.includes("/.husky/") ? `installed: ${target} — a tracked file, commit it` : `installed: ${target}`;
+}
+export function registerHooks(program, env) {
+    program
+        .command("hooks")
+        .description("install a pre-push hook that runs `zeno check`")
+        .argument("<action>", "install")
+        .argument("[repo]", "product repo", ".")
+        .option("--all", "every product in the estate")
+        .action((action, repo, options) => {
+        if (action !== "install")
+            throw new Error(`unknown action ${action} — use: zeno hooks install`);
+        const repos = options.all ? findProducts(requireEstate(env)) : [resolve(repo)];
+        for (const path of repos)
+            console.log(`  ${installHook(path)}`);
+    });
+}

package/cli/dist/config/load.js

@@ -85,12 +85,19 @@ export function loadConfig(repo, options = {}) {
         standards: [...new Set(layers.flatMap((layer) => (layer.data.standards ?? []).map((dir) => resolve(layer.base, dir))))],
         commands: mergeBy(pick("commands").map((list) => list ?? []), (command) => command.id),
         doctor: { tools: mergeBy(pick("doctor").map((doctor) => doctor?.tools ?? []), (tool) => tool.tool) },
-        checks: Object.assign({}, ...pick("checks")),
         weigh: { weights: Object.assign({}, ...pick("weigh").map((weigh) => weigh?.weights)) },
         wiki: { types: mergeBy(pick("wiki").map((wiki) => wiki?.types ?? []), (entry) => entry.type) },
         context: { folders: mergeBy(pick("context").map((context) => context?.folders ?? []), (entry) => entry.folder) },
         pipeline: lastDefined(pick("pipeline")) ?? [],
+        name: lastDefined(pick("name")),
+        copies: {
+            source: lastDefined(layers.map((layer) => (layer.data.copies?.source ? resolve(layer.base, layer.data.copies.source) : undefined))),
+            sets: Object.assign({}, ...pick("copies").map((copies) => copies?.sets)),
+            use: [...new Set(pick("copies").flatMap((copies) => copies?.use ?? []))],
+        },
     };
+    if (config.name === undefined)
+        delete config.name;
     if (Object.keys(config.expo ?? {}).length === 0)
         delete config.expo;
     return { config, sources };

package/cli/dist/config/schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export const KINDS = ["expo-app", "web", "content"];
-export const MODULES = ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing"];
+export const MODULES = ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing", "refs"];
 /**
  * The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`.
  * No flow type: a journey worth keeping is a concept. A surface page is a screen's notes, only where it has real ones.
@@ -18,11 +18,6 @@ export const REMOVED_WIKI_FOLDERS = {
 };
 /** The `.context/` folders every repo may have. A repo adds more under `context.folders`. */
 export const CONTEXT_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
-const checkOverride = z
-    .object({ enabled: z.boolean().default(true), reason: z.string().min(1).optional() })
-    .refine((check) => check.enabled || check.reason !== undefined, {
-    message: "a check turned off needs a `reason:` — an override nobody can explain is drift",
-});
 const principleId = z.string().regex(/^C-\d{2}$/, "principle IDs look like C-07");
 const command = z
     .object({
@@ -31,6 +26,8 @@ const command = z
     run: z.string().min(1),
     /** Only run when this path exists in the repo. */
     if: z.string().optional(),
+    /** Only run in a repo that uses this module. */
+    module: z.enum(MODULES).optional(),
 })
     .strict();
 const kebab = z.string().regex(/^[a-z0-9-]+$/, "use lowercase-kebab");
@@ -49,6 +46,20 @@ const wikiType = z
     message: "a built-in wiki type or its folder cannot be redefined — add a new one",
 });
 const contextFolder = z.object({ folder: kebab, reason }).strict();
+/** A file copied from the source repo: the same path on both sides, or `from` one path `to` another. */
+const copyFile = z.union([
+    z.string().min(1),
+    z
+        .object({
+        from: z.string().min(1),
+        to: z.string().min(1).optional(),
+        /** Identical except that the source product's name reads as this product's. */
+        named: z.boolean().optional(),
+        /** Compared only above the first line containing this text; below it is the product's own. */
+        until: z.string().min(1).optional(),
+    })
+        .strict(),
+]);
 const stage = z
     .object({
     id: kebab,
@@ -73,17 +84,23 @@ export const layerSchema = z
     standards: z.array(z.string()),
     commands: z.array(command),
     doctor: z.object({ tools: z.array(tool) }).partial(),
-    checks: z.record(z.string(), checkOverride),
     weigh: z.object({ weights: z.record(principleId, z.number().nonnegative()) }).partial(),
     wiki: z.object({ types: z.array(wikiType) }).partial(),
     context: z.object({ folders: z.array(contextFolder) }).partial(),
     /** The stages work goes through, in order. A more specific layer replaces the whole list. */
     pipeline: z.array(stage),
+    /** How the product is written in prose, for files shared with only the name changed. */
+    name: z.string().min(1),
+    /**
+     * Files copied from one source repo. The estate names sets of them; a product lists the sets it
+     * uses, and only those are held equal to the source.
+     */
+    copies: z.object({ source: z.string().min(1), sets: z.record(kebab, z.array(copyFile).min(1)), use: z.array(kebab) }).partial().strict(),
 })
     .partial()
     .strict();
 export const MODULES_BY_KIND = {
-    "expo-app": ["docs", "knowledge", "code", "listing"],
-    web: ["docs", "knowledge", "code"],
-    content: ["docs", "knowledge"],
+    "expo-app": ["docs", "knowledge", "code", "listing", "refs"],
+    web: ["docs", "knowledge", "code", "refs"],
+    content: ["docs", "knowledge", "refs"],
 };

package/cli/dist/format.js

@@ -18,7 +18,7 @@ export function formatReports(reports, options = {}) {
         errors += count.errors;
         warnings += count.warnings;
         const clean = report.findings.length === 0;
-        if (clean && options.quiet && report.overrides.length === 0)
+        if (clean && options.quiet)
             continue;
         const summary = clean ? "ok" : `${plural(count.errors, "error")}, ${plural(count.warnings, "warning")}`;
         lines.push(`${report.name}  ${summary}`);
@@ -26,8 +26,6 @@ export function formatReports(reports, options = {}) {
             const message = finding.message.replace(/\n/g, "\n      ");
             lines.push(`  ${MARK[finding.level]} ${finding.check}  ${finding.file ?? ""}  ${message}`.replace(/  +$/, ""));
         }
-        for (const override of report.overrides)
-            lines.push(`  override ${override.check}: ${override.reason}`);
     }
     lines.push(`${plural(reports.length, "product")} · ${plural(errors, "error")} · ${plural(warnings, "warning")}`);
     return lines.join("\n");

package/cli/dist/index.js

@@ -4,7 +4,9 @@ import { Command } from "commander";
 import { registerAdd } from "./commands/add.js";
 import { registerApprove } from "./commands/approve.js";
 import { registerCheck } from "./commands/check.js";
+import { registerCopies } from "./commands/copies.js";
 import { registerDoctor } from "./commands/doctor.js";
+import { registerHooks } from "./commands/hooks.js";
 import { registerInit } from "./commands/init.js";
 import { registerLearn } from "./commands/learn.js";
 import { registerStandards } from "./commands/standards.js";
@@ -24,10 +26,12 @@ const program = new Command("zeno")
 registerInit(program, env);
 registerAdd(program, env);
 registerCheck(program, env);
+registerCopies(program, env);
 registerSync(program, env);
 registerStatus(program, env);
 registerStandards(program, env);
 registerDoctor(program);
+registerHooks(program, env);
 registerUi(program, env);
 registerLearn(program, env);
 registerApprove(program);

package/cli/dist/init.js

@@ -69,7 +69,7 @@ const FIRST_FILE = {
 function template(file) {
     switch (file) {
         case ".context/README.md":
-            return "# .context\n\nProduct material, in the ten folders of the zeno context layout.\n\n## Absent folders\n\n- listing/ — n/a — no store presence yet\n- marketing/, metrics/, support/, legal/ — n/a — not live yet\n- ops/ — n/a — nothing to run yet\n";
+            return "# .context\n\nProduct material, in the zeno context layout. Start at [`tasks.md`](tasks.md).\n";
         case ".context/tasks.md":
             return "# Tasks\n\n## Now\n\n## Blocked\n\n## Waiting\n";
         case ".context/wiki/index.md":

package/cli/dist/run.js

@@ -4,7 +4,7 @@ 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: [], overrides: [] };
+    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;
@@ -18,11 +18,6 @@ export function runChecks(repo, options) {
         return report;
     }
     for (const check of options.checks ?? ALL_CHECKS) {
-        const override = config.checks[check.id];
-        if (override && !override.enabled) {
-            report.overrides.push({ check: check.id, reason: override.reason ?? "" });
-            continue;
-        }
         if (check.module && !config.modules.includes(check.module)) {
             report.skipped.push({ check: check.id, why: `module ${check.module} is off` });
             continue;

package/cli/dist/status.js

@@ -21,7 +21,6 @@ export function buildStatus(repo, options) {
         `kind     ${config.kind}`,
         `modules  ${config.modules.join(", ")}`,
         `config   ${configLine}`,
-        `checks   ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}` +
-            (report.overrides.length > 0 ? `, ${report.overrides.length} override(s)` : ""),
+        `checks   ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}`,
     ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freetesh/zeno",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "zeno CLI: keep your domain knowledge and AI rules in your repo, and enforce them.",
   "license": "MIT",
   "author": "Ritesh Firodiya",

package/standards/context-layout.md

@@ -7,7 +7,7 @@ folder.
 
 ```
 <repo>/.context/
-├── README.md        what this is, and which folders are absent and why
+├── README.md        what this is, and where to start
 ├── tasks.md         the ordered queue. The top item is the next action.
 ├── raw/             sources you didn't write. Immutable.
 ├── wiki/            everything you concluded. Schema: wiki-schema.md
@@ -30,7 +30,8 @@ folder.
    with the reason: `context: { folders: [{ folder: research, reason: … }] }`.
    The ten cannot be removed.
 2. **`README.md` and `tasks.md` are the only files at `.context/` root.**
-   `README.md` lists every absent folder as `n/a — <why>`.
+   A repo names only what it uses. Its README, its `zeno.yaml` and its docs never
+   list a folder, file or tool it does without; absence is shown by absence.
 3. **Nothing is created empty.** A folder appears with its first file — git does
    not track empty folders, so a placeholder disappears on clone. `raw/` is the
    one exception and carries a `.gitkeep`.