@freetesh/zeno 0.12.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.12.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

@@ -162,34 +162,33 @@ 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
+copies:                             # files products copy from one source repo, in named sets
   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 — " }
+  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:
-  skip:                             # shared files this product does without, or keeps its own of
-    - { file: scripts/release-android.mjs, reason: built on EAS from a tag }
+  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/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/refs.js

@@ -1,6 +1,7 @@
 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;
@@ -28,7 +29,8 @@ function literalPart(token, restOfLine) {
 }
 export const refs = {
     id: "refs",
-    module: null,
+    // 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"]);
@@ -36,7 +38,7 @@ export const refs = {
             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 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`));

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

@@ -3,10 +3,10 @@ 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 }));
+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)
@@ -14,82 +14,70 @@ function nameOf(repo, config) {
     const readme = join(repo, ".context", "README.md");
     return existsSync(readme) ? README_NAME.exec(readFileSync(readme, "utf8"))?.[1]?.trim() : undefined;
 }
-function above(text, marker) {
+function split(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");
+    return at === -1 ? null : { shared: lines.slice(0, at).join("\n"), own: lines.slice(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. */
+/** Compares every file of every set the product uses with the source repo. */
 export function compareCopies(repo, config) {
-    const { source, files, skip } = config.copies;
-    if (!source || files.length === 0 || resolve(source) === resolve(repo))
+    const { source, sets, use } = config.copies;
+    if (use.length === 0 || !source || resolve(source) === resolve(repo))
         return [];
-    const skipped = new Set(skip.map((entry) => entry.file));
+    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);
-    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;
+    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) {
-    const written = [];
-    for (const { pair, state, want } of compareCopies(repo, config)) {
+    return compareCopies(repo, config).flatMap(({ pair, state, want }) => {
         if (state !== "drift" || want === undefined)
-            continue;
+            return [];
         writeFileSync(join(repo, pair.to), want);
-        written.push(pair.to);
-    }
-    return written;
+        return [pair.to];
+    });
 }
 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",
+    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) : "";
+        const source = config.copies.source ? basename(config.copies.source) : "copies.source";
         return compareCopies(repo, config).flatMap(({ pair, state }) => {
-            const finding = (message) => [{ check: "shared-files", level: "error", file: pair.to, message }];
+            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(`missing — copy it from ${source}, or add it under copies.skip with a reason`);
+                return finding(pair.to, `missing — set ${pair.set} is in use; copy it from ${source}`);
             if (state === "unnamed")
-                return finding(`no product name to compare with — set name: in zeno.yaml`);
+                return finding(pair.to, "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 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/config/load.js

@@ -85,7 +85,6 @@ 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) },
@@ -93,8 +92,8 @@ export function loadConfig(repo, options = {}) {
         name: lastDefined(pick("name")),
         copies: {
             source: lastDefined(layers.map((layer) => (layer.data.copies?.source ? resolve(layer.base, layer.data.copies.source) : undefined))),
-            files: lastDefined(pick("copies").map((copies) => copies?.files)) ?? [],
-            skip: mergeBy(pick("copies").map((copies) => copies?.skip ?? []), (entry) => entry.file),
+            sets: Object.assign({}, ...pick("copies").map((copies) => copies?.sets)),
+            use: [...new Set(pick("copies").flatMap((copies) => copies?.use ?? []))],
         },
     };
     if (config.name === undefined)

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,17 +46,13 @@ 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 every product carries a copy of. A plain path is the same path on both sides and every
- * product must carry it or skip it with a reason; an object maps one source file onto product
- * paths that exist only where the product has that part (a design surface, say).
- */
+/** 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.array(z.string().min(1)).min(1).optional(),
+        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. */
@@ -67,7 +60,6 @@ const copyFile = z.union([
     })
         .strict(),
 ]);
-const copySkip = z.object({ file: z.string().min(1), reason }).strict();
 const stage = z
     .object({
     id: kebab,
@@ -92,7 +84,6 @@ 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(),
@@ -100,13 +91,16 @@ export const layerSchema = z
     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 into every product, and the ones a product does without. */
-    copies: z.object({ source: z.string().min(1), files: z.array(copyFile), skip: z.array(copySkip) }).partial().strict(),
+    /**
+     * 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/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.12.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`.