@freetesh/zeno 0.10.0 → 0.12.0

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

@@ -2,8 +2,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { listFiles } from "../lib/files.js";
 import { parseFrontmatter } from "../lib/frontmatter.js";
-import { WIKI_FOLDER_BY_TYPE } from "../config/schema.js";
-const REQUIRED_FIELDS = ["id", "type", "status", "last-verified"];
+import { REMOVED_WIKI_FOLDERS, WIKI_FOLDER_BY_TYPE } from "../config/schema.js";
+const REQUIRED_FIELDS = ["last-verified"];
+// Filler an agent would read as fact: a section with nothing to say is deleted, not stubbed.
+const PLACEHOLDER = /\bTBD\b|\bnone yet\b|\bpopulate when\b/i;
+const CODE_BLOCK = /```[\s\S]*?```/g;
 const STALE_AFTER_DAYS = 90;
 const DAY_MS = 86_400_000;
 const NOT_PAGES = ["index.md", "CLAUDE.md"];
@@ -18,7 +21,7 @@ function asDate(value) {
 export const wikiFrontmatter = {
     id: "wiki-frontmatter",
     module: "docs",
-    description: "every wiki page has id, type, status and last-verified; type matches folder; ids are unique; nothing stale",
+    description: "every wiki page has last-verified and no placeholder text; a type, if set, matches its folder; ids are unique; nothing stale",
     run({ repo, config, today }) {
         const folderByType = { ...WIKI_FOLDER_BY_TYPE, ...Object.fromEntries(config.wiki.types.map((entry) => [entry.type, entry.folder])) };
         // Built-in types' sections are linted by the wiki-lint skill; added types carry theirs in config.
@@ -28,6 +31,9 @@ export const wikiFrontmatter = {
         const filesById = new Map();
         const stale = [];
         for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder in REMOVED_WIKI_FOLDERS)
+                continue; // context-size reports the folder once
             const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
             if (!data) {
                 add("error", file, "no frontmatter");
@@ -36,10 +42,11 @@ export const wikiFrontmatter = {
             const missing = REQUIRED_FIELDS.filter((field) => data[field] === undefined || data[field] === null);
             if (missing.length > 0)
                 add("error", file, `missing ${missing.join(", ")}`);
-            const folder = file.split("/")[2];
             const expected = folderByType[String(data.type)];
             if (data.type && expected !== folder)
                 add("error", file, `type ${data.type} does not belong in ${folder}/`);
+            if (!data.type && !Object.values(folderByType).includes(folder))
+                add("error", file, `${folder}/ is not a wiki folder`);
             const sections = sectionsByType.get(String(data.type));
             if (sections) {
                 const headings = new Set(body.split("\n").flatMap((line) => (line.startsWith("## ") ? [line.slice(3).trim()] : [])));
@@ -47,12 +54,15 @@ export const wikiFrontmatter = {
                 if (absent.length > 0)
                     add("error", file, `missing sections: ${absent.join(", ")}`);
             }
-            if (data.status === "superseded" && !data["superseded-by"])
-                add("error", file, "superseded without superseded-by");
+            const placeholder = body.replace(CODE_BLOCK, "").match(PLACEHOLDER);
+            if (placeholder)
+                add("warn", file, `placeholder "${placeholder[0]}" — write the fact or delete the section`);
             const verified = asDate(data["last-verified"]);
             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/approve.js

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { recordApproval } from "../pipeline.js";
+export function registerApprove(program) {
+    program
+        .command("approve")
+        .description("record that a person reviewed and approved a pipeline gate, dated now (a person runs this, not an agent)")
+        .argument("<stage>", "the gated stage's id in zeno.yaml `pipeline:`")
+        .argument("[repo]", "product repo", ".")
+        .option("--note <text>", "what was reviewed", "")
+        .action((stageId, repo, options) => {
+        const root = resolve(repo);
+        const gates = loadConfig(root).config.pipeline.filter((stage) => stage.gate).map((stage) => stage.id);
+        if (!gates.includes(stageId)) {
+            throw new Error(`"${stageId}" is not a gated stage here — gates: ${gates.join(", ") || "none (no pipeline: in zeno.yaml)"}`);
+        }
+        const approval = recordApproval(root, stageId, options.note);
+        console.log(`approved ${stageId} at ${approval.at}`);
+    });
+}

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

@@ -89,7 +89,16 @@ export function loadConfig(repo, options = {}) {
         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))),
+            files: lastDefined(pick("copies").map((copies) => copies?.files)) ?? [],
+            skip: mergeBy(pick("copies").map((copies) => copies?.skip ?? []), (entry) => entry.file),
+        },
     };
+    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,15 +1,21 @@
 import { z } from "zod";
 export const KINDS = ["expo-app", "web", "content"];
 export const MODULES = ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing"];
-/** The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`. */
+/**
+ * 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.
+ */
 export const WIKI_FOLDER_BY_TYPE = {
     concept: "concepts",
     entity: "entities",
     surface: "surfaces",
-    flow: "flows",
     decision: "decisions",
     synthesis: "synthesis",
 };
+/** Wiki folders that no longer exist, and what to do with what was in them. */
+export const REMOVED_WIKI_FOLDERS = {
+    flows: "fold a journey worth keeping into a concept page",
+};
 /** 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
@@ -43,6 +49,34 @@ 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).
+ */
+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(),
+        /** 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 copySkip = z.object({ file: z.string().min(1), reason }).strict();
+const stage = z
+    .object({
+    id: kebab,
+    /** Paths that exist once the stage has started; any one is enough. */
+    done: z.array(z.string().min(1)).min(1),
+    /** A person must approve this stage (`zeno approve <id>`) before any later stage starts. */
+    gate: z.boolean().default(false),
+})
+    .strict();
 const tool = z.object({ tool: z.string(), why: z.string(), hint: z.string() }).strict();
 /** One layer of `.claude/zeno.yaml` as written: every field optional. */
 export const layerSchema = z
@@ -62,6 +96,12 @@ export const layerSchema = z
     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 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(),
 })
     .partial()
     .strict();

package/cli/dist/index.js

@@ -2,8 +2,11 @@
 import { resolve } from "node:path";
 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";
@@ -23,12 +26,15 @@ 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);
 registerWeigh(program);
 program.parseAsync().catch((error) => {
     console.error(`zeno: ${error.message}`);

package/cli/dist/init.js

@@ -66,12 +66,12 @@ const FIRST_FILE = {
     wiki: ".context/wiki/index.md",
     features: ".context/features/index.md",
 };
-function template(file, today) {
+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";
         case ".context/tasks.md":
-            return `---\nupdated: ${today}\nhorizon: ${today}\n---\n\n# Tasks\n\n## Now\n\n## Parallel\n\n## Blocked\n\n## Waiting\n\n## Done\n\n## Session Notes\n`;
+            return "# Tasks\n\n## Now\n\n## Blocked\n\n## Waiting\n";
         case ".context/wiki/index.md":
             return "# Wiki index\n\nPages by type. Schema: the zeno plugin's wiki-schema standard.\n";
         case ".context/features/index.md":
@@ -98,7 +98,6 @@ export function planInit(repo, answers) {
     return { config, create };
 }
 export function applyInit(repo, plan, options) {
-    const today = options.today ?? new Date().toISOString().slice(0, 10);
     const write = (file, content) => {
         mkdirSync(dirname(join(repo, file)), { recursive: true });
         writeFileSync(join(repo, file), content);
@@ -107,7 +106,7 @@ export function applyInit(repo, plan, options) {
     const starters = new Map(architectureStarters(repo).map((s) => [s.file, s.template]));
     for (const file of plan.create) {
         const starter = starters.get(file);
-        write(file, starter ? readFileSync(join(options.zenoRoot, ARCHITECTURE_TEMPLATES, starter), "utf8") : template(file, today));
+        write(file, starter ? readFileSync(join(options.zenoRoot, ARCHITECTURE_TEMPLATES, starter), "utf8") : template(file));
     }
     if (plan.config.modules.includes("knowledge"))
         indexKnowledge(repo, options.name, options.run);

package/cli/dist/pipeline.js

@@ -0,0 +1,20 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// In raw/, which is append-only: the dates are the record of how long each stage waited.
+export const GATES_LOG = join(".context", "raw", "zeno", "gates.jsonl");
+export function readApprovals(repo) {
+    const path = join(repo, GATES_LOG);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+export function recordApproval(repo, stage, note) {
+    const approval = { stage, at: new Date().toISOString(), note };
+    const path = join(repo, GATES_LOG);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(approval)}\n`);
+    return approval;
+}

package/package.json

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

package/skills/ask/SKILL.md

@@ -15,9 +15,8 @@ Question: `$ARGUMENTS`
    - `entity` pages for "what is the value / price / name of X"
    - `synthesis` pages for cross-cutting summaries (use these before chasing individual entities)
    - `concept` pages for "why" or "what does X mean" questions
-   - `surface` pages for "what does this screen do"
-   - `flow` pages for "how does the user get from A to B"
-   - `decision` pages for "why did we choose X over Y"
+   - `decision` pages for "why did we choose X over Y", and its `Rejected:` line for "did we consider Y"
+   - for "what does this screen do", the HTML in `.context/designs/` is the spec; its `surfaces/` note, if any, says why
 
 3. **Read the candidate pages.** Follow `[[wikilinks]]` one hop if the answer is incomplete. Stop at two hops — if you need three, the wiki is missing a synthesis page; say so.
 
@@ -35,8 +34,7 @@ Question: `$ARGUMENTS`
 
 ## Rules
 
-- **Never read `.context/raw/` or `.context/designs/` from this skill.** If the answer requires raw inspection, refuse and recommend `/ingest`.
+- **Never read `.context/raw/` from this skill.** If the answer requires raw inspection, recommend `/ingest`. Designs may be read for screen questions.
 - **Never invent facts.** If a canonical value isn't in an `entity` page, say "not in the wiki".
 - **Every cited page must actually exist.** Don't fabricate a `[[wikilink]]` to make the answer look authoritative.
-- A page with `status: superseded` is not canonical — follow `superseded-by` to the current page.
 - A page with `last-verified` > 90 days is stale — flag it in the answer ("last verified 2025-11-04 — may be out of date").

package/skills/decision/SKILL.md

@@ -1,33 +1,36 @@
 ---
 name: decision
-description: Record a product or technical decision as a new ADR page in .context/wiki/decisions/. Usage `/decision <title> — <body>`.
+description: Record or change a product or technical decision in .context/wiki/decisions/<topic>.md — one file per topic, overwritten when the choice changes. Usage `/decision <topic> — <choice and why>`.
 ---
 
-You are logging a decision as a new `.context/wiki/decisions/<YYYY-MM-DD>-<slug>.md` page.
+You are recording a decision in `.context/wiki/decisions/<topic>.md`.
 
-Decision to record: `$ARGUMENTS`
+Decision: `$ARGUMENTS`
 
 ## Steps
 
-1. Get the shape. If `.context/wiki/decisions/` already holds pages, open the most recent one and match its frontmatter and sections — that is enough. Only when there is none, read two parts of the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../standards/wiki-schema.md` relative to this skill): § "Frontmatter" and § "`decision`". Find their line numbers with Grep and Read just those ranges, not the whole file.
-
-2. Parse `$ARGUMENTS`:
-   - If it contains ` — ` (em-dash with spaces), split on the first occurrence: left = title, right = body.
-   - Otherwise treat the whole string as the title; body = "(no detail provided)".
-
-3. Derive the filename:
-   - Date = today's `currentDate` from the session context (`YYYY-MM-DD`).
-   - Slug = kebab-case of the title, lower-cased, alphanumerics + hyphens only, ≤ 60 chars.
-   - Path = `.context/wiki/decisions/<date>-<slug>.md`. If a file at that path already exists, append `-2`, `-3`, etc.
-
-4. Write the new ADR with the standard frontmatter and the body the user provided. Do not summarise or shorten the body.
-
-5. Add the page to `.context/wiki/index.md` under Decisions.
-
-6. Confirm: `decision logged: "<title>" → <path>`.
+1. Split `$ARGUMENTS` on the first ` — `: left = topic, right = the choice and why. With no ` — `, ask for the choice.
+2. Slug = the topic in kebab-case, no date (`pricing`, `auth-provider`). Look for an existing file on the same topic first, under any name. If there is one, it is the file to change.
+3. Write the file, at most 30 lines:
+
+   ```markdown
+   ---
+   last-verified: <today>
+   ---
+   # <Topic>
+   **Choice:** <one or two lines; link values to their entity page>
+   **Why:** <the trigger: data, incident, user feedback, cost>
+   **Rejected:** <option (why)> · <option (why)>
+   ```
+
+   When changing an existing decision, replace the choice and why, and move the
+   old choice into `Rejected:` with the reason it was dropped. Keep the rest of `Rejected:`.
+4. Put a price, SKU or limit on its entity page, not here (`canonical-values` checks this).
+5. Add or update the one line in `.context/wiki/index.md`.
+6. Confirm: `decision recorded: <topic> → <path>`.
 
 ## Rules
 
-- One decision per file. Never append to an existing ADR.
-- Do not edit any other wiki page in the same command — if cross-references are needed, surface them in the body as `[[wikilinks]]`, but leave the target pages alone.
-- The wiki is the only source of truth for decisions. There is no monolithic decision log.
+- One file per topic, overwritten. Git keeps the old text; never add a dated or `-2` file.
+- No fix lists, audit results or step-by-step history. Those go in the commit message or `CHANGELOG.md`.
+- If the user's text is long, keep the choice, the reason and what was rejected, and drop the rest. Show what you dropped.

package/skills/ingest/SKILL.md

@@ -9,28 +9,27 @@ Source to ingest: `$ARGUMENTS`
 
 ## Steps
 
-1. **Read the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../standards/wiki-schema.md` relative to this skill) first.** It defines page types, frontmatter, required sections, ID conventions, and lint rules. Every page you write must conform.
+1. **Read the wiki schema (the `wiki-schema.md` that `zeno standards` lists — a team's own replaces zeno's; without the CLI, `../../standards/wiki-schema.md` relative to this skill) first.** It defines the folders, the one test for what belongs, and the caps. Every page you write must conform.
 
 2. **Read the raw source** at the path in `$ARGUMENTS`. Accepted: anything under `.context/raw/` or `.context/designs/`, and application source in this repository. Refuse paths outside the repo.
 
 3. **Classify** the source into one or more wiki page types:
-   - HTML wireframe → `surface` page
-   - Decision note → `decision` page
+   - HTML wireframe → nothing; the HTML is the spec. Only a constraint it can't show becomes that screen's `surfaces/<slug>.md` note.
+   - Decision note → the `decisions/<topic>.md` file, via the `decision` skill's format
    - Research doc / interview → typically `concept` pages (split if it covers multiple ideas), or one `synthesis` page for a brief that draws a conclusion
    - A new tier / product / canonical value → `entity` page
-   - A user journey description → `flow` page
+   - A user journey description → a concept, only if it holds a rule the designs don't show
+   - Write nothing an agent could read from the code, the designs or git.
    - Don't force one source into one page — a meeting note can produce multiple pages.
-   - Page types are the six in the schema plus any listed under `wiki.types` in the repo's or the estate's `.claude/zeno.yaml`, each with its folder and its required `sections` (use exactly those `## ` headings, in that order; its ID is `<TYPE>.<SLUG>`). Use an added type only when the source fits it.
+   - Folders are the four in the schema plus any listed under `wiki.types` in the repo's or the estate's `.claude/zeno.yaml`, each with its folder and its required `sections` (use its `sections` headings). Use an added type only when the source fits it.
 
 4. **For each page you will create:**
-   - Pick the ID per the wiki schema § "ID conventions". IDs are uppercase, dot-separated, never change.
-   - Pick the filename: the slug portion of the ID, lowercase, kebab-case, `.md` extension.
-   - Check whether the page already exists. If yes, **update** rather than overwrite: preserve `id`, `supersedes`, `superseded-by`; refresh `last-verified` to today.
-   - Use the required sections for that page type — verbatim from the wiki schema. Missing a required section is a lint failure.
-   - Fill `Related` with at least two `[[wikilinks]]`. A link to a page that doesn't exist yet is OK — `/wiki-lint` will flag it as a TODO.
-   - List the source path under `Sources`, so a future `/wiki-lint` can tell which raw files nothing has read.
+   - Filename: the topic, lowercase kebab-case, no date.
+   - Check whether a page on the topic already exists. If yes, edit it in place and refresh `last-verified` to today. Keep any `id`.
+   - Write only sections with something to say. No placeholders. Stay under the caps (page 60 lines).
+   - Link related pages with `[[slug]]` where it helps a reader. List the source path under `Sources`.
 
-5. **Update `.context/wiki/index.md`:** add the new page under the right type heading, in alphabetical order by slug. Don't reformat existing entries.
+5. **Update `.context/wiki/index.md`:** one line for the new page, under its folder heading, alphabetical. Don't reformat existing entries.
 
 6. **Leave the source where it is.** `.context/raw/` is immutable: a source is "processed" when a wiki page lists it under `Sources`, not when it moves.
 
@@ -39,7 +38,7 @@ Source to ingest: `$ARGUMENTS`
 ## Rules
 
 - Never edit anything under `.context/raw/` or `.context/designs/`.
-- Never delete or rename an existing wiki page from this skill — use a `decision` page to log a rename, then run again.
+- Never delete or rename an existing wiki page from this skill.
 - Never invent canonical values. If the source has a price/string/enum, copy it verbatim; if it's ambiguous, ask the user before writing.
 - Follow the copy rules from the root `CLAUDE.md` for any user-facing strings you transcribe.
 - Today's date is in the session context — use it for `last-verified`.

package/skills/wiki-lint/SKILL.md

@@ -9,10 +9,11 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 ## Steps
 
-1. **Read the wiki schema** to refresh schema, ID conventions, required sections, and the lint-rules table.
+1. **Read the wiki schema** to refresh the folders, the one test and the caps.
 
 2. **Run `zeno check` first** if the CLI is installed. It checks frontmatter,
-   duplicate IDs, staleness and prices held by no entity in under a second,
+   placeholders, caps, dated decision names, duplicate IDs, staleness and
+   prices held by no entity in under a second,
    plus any checker the repo declares. Start from its output rather than
    re-deriving it.
 
@@ -29,30 +30,27 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 | Check | Rule |
 |---|---|
-| Missing required section | Per the wiki schema § "Page body — required sections" |
 | Broken `[[wikilink]]` | Target page does not exist |
 | Duplicate `id` | Two pages claim the same ID |
 | Contradictory canonical value | Two `entity` pages list the same key with different values |
-| `status: superseded` with no `superseded-by` | Set or remove the status |
-| Filename ↔ id slug mismatch | The filename must match the slug portion of the ID |
-| `type` does not match folder | `type: concept` must live in `concepts/`, etc. A type added under `wiki.types` in `.claude/zeno.yaml` lives in its configured folder and has every heading in its `sections`. |
+| Placeholder text | `TBD`, `none yet`: write the fact or delete the section |
+| `type` does not match folder | If a page sets `type`, it lives in that type's folder |
 
 ### Warnings
 
 | Check | Rule |
 |---|---|
-| Orphan page | Zero inbound `[[wikilinks]]`. Exception: `decision` and `synthesis` pages are commonly orphan-source. |
+| Over a cap | Page 60 lines, decision 30, README 30, tasks 100 |
+| Restates code, a design or git | Delete the lines; link the source instead |
+| Two pages on one topic | Merge into one, edited in place |
 | Stale `last-verified` | > 90 days from today. |
 | Unprocessed raw file | A file under `.context/raw/` that no wiki page references in its `Sources`. |
-| Stale synthesis | A `synthesis` page where any `Built from` page was modified after the synthesis's `Last refresh`. |
-| Page missing two outbound links | Body has fewer than two `[[wikilinks]]`. |
 | User-facing string violates copy rules | Check quoted copy against the rules in the root `CLAUDE.md`. Best-effort. |
 
 6. **Auto-fix (only if `--fix` is in `$ARGUMENTS`):**
    - Regenerate `.context/wiki/index.md` from scratch: enumerate pages by type, sort alphabetically by slug, keep the structure the file already has.
    - Fix `last-verified` to today's date on any page whose body was edited in the working tree.
-   - Fix filename ↔ id slug mismatches (rename the file; do NOT change the ID).
-   - **Never** auto-fix: contradictory canonical values, missing required sections, broken `[[wikilinks]]`. These need a human decision.
+   - **Never** auto-fix: contradictory canonical values, broken `[[wikilinks]]`, merges or cuts. These need a human decision.
 
 7. **Report.** Print:
    - Counts: pages, blockers, warnings, auto-fixes applied.
@@ -63,7 +61,7 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 ## Rules
 
 - **Never edit pages other than auto-fixes above.** Lint reports; the user (or `/ingest`) fixes.
-- **Never delete pages.** Superseded pages stay on disk with `status: superseded` and `superseded-by: <new-id>`.
+- **Never delete pages from this skill.** Propose the cut; the user approves it. Git keeps what is deleted.
 - **Never modify `.context/raw/`** except to warn about unprocessed files.
 - If a blocker resists auto-fix, exit non-zero (in CI mode) but always print the full report first.
 - Today's date is in the session context — use it for staleness math (>90 days).