@freetesh/zeno 0.7.0 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "zeno",
       "source": "./",
-      "description": "Shared standards, searchable product knowledge and decision checks for every product repo."
+      "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less."
     }
   ],
-  "description": "zeno: standards, searchable product knowledge and a decision gate for Claude Code."
+  "description": "zeno: Keep your domain knowledge and AI rules in your repo, and enforce them. Less AI guessing, faster delivery."
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.7.0",
-  "description": "Shared standards, searchable product knowledge and decision checks for every product repo.",
+  "version": "0.9.0",
+  "description": "Keeps your domain knowledge and AI rules local and enforces them, so Claude hallucinates less.",
   "author": {
     "name": "Ritesh Firodiya",
     "email": "40817224+ritesh-firodiya@users.noreply.github.com"

package/README.md

@@ -1,9 +1,10 @@
 # zeno
 
-Standards, searchable product knowledge and a decision gate for teams that
-build with Claude Code. zeno keeps several products consistent as they evolve,
-keeps what you decided findable, and makes Claude weigh a request against your
-rules and history before it acts on it.
+A productivity tool for the whole product development lifecycle (PDLC), from
+idea to release. zeno keeps your domain knowledge, decisions and AI rules local,
+in your own repos, and enforces them: Claude searches them before it answers,
+weighs a request against them before it acts, and `zeno check` fails when code
+or docs break them. The AI hallucinates less, and your team ships faster.
 
 It has two halves that read the same config:
 
@@ -18,6 +19,15 @@ It has two halves that read the same config:
   cost vs value, and the write-less ladder, then answers **DO IT**, **DO IT
   DIFFERENTLY** or **PUSH BACK** with citations. Push back stops work until you
   give a reason; overrides are logged and feed `zeno learn`.
+- **No assumptions.** A request is not a fact. Each claim in it ("users want
+  this", "it is slow") is checked against the repo and its data sources and
+  marked backed or not. Work that rests on an assumption stops until you agree
+  to written, numbered terms. Replies use plain words.
+- **Your data sources, your tools.** zeno has no connectors. A repo describes
+  each tool that holds its data (Sentry, Datadog, Snowflake) on a `SOURCE.*`
+  wiki page that names the MCP server, skill or CLI that reads it. The gate
+  queries it, read-only, to back or reject a claim, and `zeno check` fails a
+  source page that does not say how to read it.
 - **Knowledge that is found, not remembered.** Every repo's `.context/wiki` and
   feature board is indexed with [QMD](https://github.com/tobi/qmd) (local hybrid
   search). Claude is told to search before answering.
@@ -42,7 +52,7 @@ It has two halves that read the same config:
 
 ```bash
 # plugin (from GitHub)
-claude plugin marketplace add ritesh-firodiya/zeno-ai
+claude plugin marketplace add ritesh-firodiya/zeno
 claude plugin install zeno@zeno
 
 # CLI (Node 22+)
@@ -83,6 +93,11 @@ Run the CLI from source (Node 23.6+ runs the TypeScript directly):
 `pnpm install && ln -s "$PWD/cli/src/index.ts" ~/.local/bin/zeno`.
 `pnpm test`, `pnpm typecheck` and `pnpm build` run from the repo root.
 
+**Releasing.** Bump `version` in `package.json` and `.claude-plugin/plugin.json`,
+then push or merge to `main`. The `release` workflow runs the tests, publishes
+`@freetesh/zeno` to npm, tags `vX.Y.Z` and creates the GitHub release. A push
+without a bump releases nothing. It needs the `NPM_TOKEN` Actions secret.
+
 ## CLI
 
 ```bash
@@ -117,13 +132,22 @@ commands:                           # your own checkers, run by `zeno check`
 doctor:
   tools:
     - { tool: pnpm, why: product scripts, hint: npm i -g pnpm }
+wiki:
+  types:                            # added to the six built-in page types
+    - type: postmortem
+      folder: postmortems
+      reason: incidents need a timeline and a fix
+      sections: [Summary, Timeline, Root cause, Fix, Sources]   # zeno check requires each `## ` heading
+context:
+  folders:                          # added to the ten .context folders
+    - { folder: research, reason: interview notes, kept apart from raw/ }
 ```
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
 zeno: 0.6.0
 kind: expo-app                      # expo-app | web | content
-modules: [docs, knowledge, metrics, code, listing]   # all optional; design is added when .context/designs exists
+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" }
@@ -132,7 +156,8 @@ weigh:
 ```
 
 Scalars: the most specific layer wins. `packs` and `standards` add up across
-layers; `commands` and `doctor.tools` merge by id. A check turned off must
+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.
 
 ## Standards
@@ -152,12 +177,12 @@ your own.
 
 ## Evals
 
-`evals/` runs five requests against a fixture product (`evals/fixtures/streaks`)
+`evals/` runs nine requests against a fixture product (`evals/fixtures/streaks`)
 with and without the plugin, each in a sandbox seeded with the fixture and a
 local QMD index:
 
 ```bash
-claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd__*' --runs 2
+claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd__*' Write Edit --runs 2
 ```
 
 ## Layout
@@ -165,7 +190,7 @@ claude plugin eval . --scaffold --mocks off --allow-tools 'mcp__plugin_zeno_qmd_
 ```
 .claude-plugin/   plugin manifest and marketplace
 skills/           weigh, standards, ask, ingest, decision, wiki-lint
-agents/           challenger — independent second opinion for large requests
+agents/           challenger — independent second opinion for too-large requests
 hooks/            session start: constitution titles, qmd refresh
 standards/        default standards
 packs/            vendor doc packs

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

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-const ALLOWED_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
+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. */
 export function requiredContext(modules) {
@@ -11,7 +11,7 @@ const ROOT_FILES = ["README.md", "tasks.md"];
 export const contextLayout = {
     id: "context-layout",
     module: null,
-    description: ".context/ has the required folders, only the ten allowed ones, and only README.md + tasks.md at its root",
+    description: ".context/ has the required folders, only the allowed ones (the ten plus context.folders), and only README.md + tasks.md at its root",
     run({ repo, config }) {
         const context = join(repo, ".context");
         const finding = (level, file, message) => ({
@@ -23,11 +23,12 @@ export const contextLayout = {
         if (!existsSync(context))
             return [finding("error", ".context", "no .context/ folder — run `zeno init`")];
         const findings = requiredContext(config.modules).filter((name) => !existsSync(join(context, name))).map((name) => finding("error", `.context/${name}`, `required ${name} is missing`));
+        const allowed = [...CONTEXT_FOLDERS, ...config.context.folders.map((entry) => entry.folder)];
         for (const entry of readdirSync(context, { withFileTypes: true })) {
             if (entry.name === ".DS_Store")
                 continue;
-            if (entry.isDirectory() && !ALLOWED_FOLDERS.includes(entry.name)) {
-                findings.push(finding("error", `.context/${entry.name}`, `${entry.name}/ is not one of the ten folders`));
+            if (entry.isDirectory() && !allowed.includes(entry.name)) {
+                findings.push(finding("error", `.context/${entry.name}`, `${entry.name}/ is not an allowed folder — move it, or add it under context.folders in zeno.yaml`));
             }
             if (entry.isFile() && !ROOT_FILES.includes(entry.name)) {
                 findings.push(finding("error", `.context/${entry.name}`, "only README.md and tasks.md may sit at .context/ root"));

package/cli/dist/checks/index.js

@@ -3,6 +3,8 @@ import { canonicalValues } from "./canonical-values.js";
 import { contextLayout } from "./context-layout.js";
 import { staleCopies, standardsCopies } from "./copies.js";
 import { commandChecks } from "./external.js";
+import { metricsDefinitions } from "./metrics.js";
+import { sources } from "./sources.js";
 import { wikiFrontmatter } from "./wiki-frontmatter.js";
 export const ALL_CHECKS = [
     contextLayout,
@@ -11,5 +13,7 @@ export const ALL_CHECKS = [
     standardsCopies,
     staleCopies,
     architecture,
+    metricsDefinitions,
+    sources,
     commandChecks,
 ];

package/cli/dist/checks/metrics.js

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

package/cli/dist/checks/sources.js

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

package/cli/dist/checks/wiki-frontmatter.js

@@ -2,15 +2,8 @@ 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"];
-const FOLDER_BY_TYPE = {
-    concept: "concepts",
-    entity: "entities",
-    surface: "surfaces",
-    flow: "flows",
-    decision: "decisions",
-    synthesis: "synthesis",
-};
 const STALE_AFTER_DAYS = 90;
 const DAY_MS = 86_400_000;
 const NOT_PAGES = ["index.md", "CLAUDE.md"];
@@ -26,13 +19,16 @@ 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",
-    run({ repo, today }) {
+    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.
+        const sectionsByType = new Map(config.wiki.types.map((entry) => [entry.type, entry.sections]));
         const findings = [];
         const add = (level, file, message) => findings.push({ check: "wiki-frontmatter", level, file, message });
         const filesById = new Map();
         const stale = [];
         for (const file of wikiPages(repo)) {
-            const { data } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
             if (!data) {
                 add("error", file, "no frontmatter");
                 continue;
@@ -41,9 +37,16 @@ export const wikiFrontmatter = {
             if (missing.length > 0)
                 add("error", file, `missing ${missing.join(", ")}`);
             const folder = file.split("/")[2];
-            const expected = FOLDER_BY_TYPE[String(data.type)];
+            const expected = folderByType[String(data.type)];
             if (data.type && expected !== folder)
                 add("error", file, `type ${data.type} does not belong in ${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()] : [])));
+                const absent = sections.filter((section) => !headings.has(section));
+                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 verified = asDate(data["last-verified"]);

package/cli/dist/commands/init.js

@@ -22,7 +22,7 @@ async function askAnswers(inferred, packs) {
     if (cancelled(kind))
         return null;
     const modules = await prompts.multiselect({
-        message: "Which modules? All optional. (docs = wiki, design = HTML designs, knowledge = search, specs, metrics, code = LSP, architecture, listing)",
+        message: "Which modules? All optional. (docs = wiki, design = HTML designs, knowledge = search, metrics = definitions.yml, code = LSP, architecture, listing)",
         initialValues: inferred.config.modules,
         options: MODULES.map((value) => ({ value, label: value })),
         required: false,

package/cli/dist/config/load.js

@@ -62,7 +62,8 @@ function mergeBy(lists, key) {
 /**
  * Reads the estate, product and local zeno.yaml layers over defaults inferred
  * from the repo. Scalars: the most specific layer wins. Lists of names add up
- * (packs, standards); lists of records merge by their key (commands, tools).
+ * (packs, standards); lists of records merge by their key (commands, tools,
+ * wiki types, context folders).
  */
 export function loadConfig(repo, options = {}) {
     const estateRoot = options.estateRoot === undefined ? findEstate(dirname(resolve(repo))) : options.estateRoot;
@@ -86,6 +87,8 @@ export function loadConfig(repo, options = {}) {
         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) },
     };
     if (Object.keys(config.expo ?? {}).length === 0)
         delete config.expo;

package/cli/dist/config/schema.js

@@ -1,6 +1,17 @@
 import { z } from "zod";
 export const KINDS = ["expo-app", "web", "content"];
-export const MODULES = ["docs", "design", "knowledge", "specs", "metrics", "code", "architecture", "listing"];
+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`. */
+export const WIKI_FOLDER_BY_TYPE = {
+    concept: "concepts",
+    entity: "entities",
+    surface: "surfaces",
+    flow: "flows",
+    decision: "decisions",
+    synthesis: "synthesis",
+};
+/** 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, {
@@ -16,6 +27,22 @@ const command = z
     if: z.string().optional(),
 })
     .strict();
+const kebab = z.string().regex(/^[a-z0-9-]+$/, "use lowercase-kebab");
+/** An addition to zeno's layout says why, so products drifting apart is written down. */
+const reason = z.string().min(1);
+const wikiType = z
+    .object({
+    type: kebab,
+    folder: kebab,
+    reason,
+    /** The `## ` headings every page of this type must have, as the schema lists them for the built-in six. */
+    sections: z.array(z.string().min(1)).min(1, "list the `## ` sections every page of this type must have"),
+})
+    .strict()
+    .refine((entry) => !(entry.type in WIKI_FOLDER_BY_TYPE) && !Object.values(WIKI_FOLDER_BY_TYPE).includes(entry.folder), {
+    message: "a built-in wiki type or its folder cannot be redefined — add a new one",
+});
+const contextFolder = z.object({ folder: kebab, reason }).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
@@ -33,11 +60,13 @@ export const layerSchema = z
     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(),
 })
     .partial()
     .strict();
 export const MODULES_BY_KIND = {
-    "expo-app": ["docs", "knowledge", "metrics", "code", "listing"],
-    web: ["docs", "knowledge", "metrics", "code"],
+    "expo-app": ["docs", "knowledge", "code", "listing"],
+    web: ["docs", "knowledge", "code"],
     content: ["docs", "knowledge"],
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@freetesh/zeno",
-  "version": "0.7.0",
-  "description": "zeno CLI: set up, check and sync product repos against the shared standards.",
+  "version": "0.9.0",
+  "description": "zeno CLI: keep your domain knowledge and AI rules in your repo, and enforce them.",
   "license": "MIT",
   "author": "Ritesh Firodiya",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ritesh-firodiya/zeno-ai.git"
+    "url": "git+https://github.com/ritesh-firodiya/zeno.git"
   },
   "type": "module",
   "bin": {

package/skills/decision/SKILL.md

@@ -9,7 +9,7 @@ Decision to record: `$ARGUMENTS`
 
 ## Steps
 
-1. Read the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "`decision`" for the frontmatter and the required sections. If `.context/wiki/decisions/` already holds pages, open a recent one and match it.
+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.

package/skills/ingest/SKILL.md

@@ -9,7 +9,7 @@ Source to ingest: `$ARGUMENTS`
 
 ## Steps
 
-1. **Read the wiki schema (`../../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 page types, frontmatter, required sections, ID conventions, and lint rules. 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.
 
@@ -20,12 +20,13 @@ Source to ingest: `$ARGUMENTS`
    - A new tier / product / canonical value → `entity` page
    - A user journey description → `flow` page
    - 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.
 
 4. **For each page you will create:**
-   - Pick the ID per the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "ID conventions". IDs are uppercase, dot-separated, never change.
+   - 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 (`../../standards/wiki-schema.md`, relative to this skill). Missing a required section is a lint failure.
+   - 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.
 

package/skills/weigh/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weigh
-description: Decision gate run BEFORE acting on a non-trivial request in a product repo — a new feature, screen or product, a new dependency or library, a migration or rewrite, a schema, money, pricing or store change, a release or deploy, deleting something, or any change touching more than one file or more than one product. Weighs the request against the zeno constitution, the product's wiki and ADRs, existing features and tasks, cost vs value, and writing less code, then returns do it / do it differently / push back with citations. Also use when the user types /weigh or asks "should we…", "is it worth…", "does this make sense".
+description: Decision gate run BEFORE acting on a non-trivial request in a product repo — a new feature, screen or product, a new dependency or library, a migration or rewrite, a schema, money, pricing or store change, a release or deploy, deleting something, or a change that spans more than one product. Weighs the request against the zeno constitution, the product's wiki and ADRs, existing features and tasks, cost vs value, and writing less code, then returns do it / do it differently / push back with citations. Also use when the user types /weigh or asks "should we…", "is it worth…", "does this make sense".
 ---
 
 # Weigh before acting
@@ -19,7 +19,10 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
 
 1. **Restate the goal** in one line — what outcome the user wants, not the
    mechanism they named. A named mechanism ("use library X", "move to Firebase")
-   is a proposal to weigh, not a given.
+   is a proposal to weigh, not a given. Then **list the claims** the request
+   makes or rests on: "users want it", "it will help retention", "it is
+   missing", "it is slow". The request is not a fact (C-14); each claim is
+   checked in step 4.
 
 2. **Rules.** Run `zeno standards --constitution` for the principle titles
    (zeno's and any the team added), and read the constitution files that
@@ -29,8 +32,10 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
    in its area.
 
 3. **Domain.** Search before you judge. Run `mcp__plugin_zeno_qmd__query` with
-   the goal in plain words, then the key nouns (product name + topic). Read the
-   top hits with `mcp__plugin_zeno_qmd__get`. Look for: an ADR that already
+   the goal in plain words, then the key nouns, scoped with `collections` to
+   this product's `<repo>-wiki` and `<repo>-features` (the names `zeno init`
+   gives them; add `pack-<name>` when the question is about a vendor's API). Other products' hits are noise here; step 5 is where
+   siblings are searched. Read the top hits with `mcp__plugin_zeno_qmd__get`. Look for: an ADR that already
    decided this, a canonical value it would change, a concept it would break.
    If qmd is unavailable, read `.context/wiki/index.md` and `decisions/`.
    **Architecture:** if `.claude/zeno.yaml` lists the `architecture` module, read
@@ -40,29 +45,47 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
    is **too-large** unless a decision page already approves it. Cite the rule
    by its `name`.
 
-4. **Duplicates and conflicts.** Check `.context/features/` and `.context/tasks.md`
+4. **Claims.** Mark each claim from step 1 **backed**, **partly backed** or
+   **not backed**, with the fact and its source. Look in what step 3 read, the
+   code and `.context/raw/`. When that is not enough, look for a data source:
+   query qmd for `SOURCE` pages in this product's wiki. Each says what it holds,
+   how to read it (`mcp:`, `skill:` or `cli:`) and which claims it answers. If
+   one fits, run its query and follow the query rules in `wiki-schema.md`
+   ("Data sources"): read only, one or two small queries, counts not people.
+   Save a result that decides the verdict to `.context/raw/`. If the tool is not
+   available, say so and leave the claim not backed. If no source fits, name
+   the kind of source that would answer it ("an analytics tool with weekly
+   active users"). Never mark a claim backed because the user said it again.
+
+5. **Duplicates and conflicts.** Check `.context/features/` and `.context/tasks.md`
    of this product, and the features collections of sibling products in qmd:
    is this already planned, built, shelved, or in progress elsewhere? Would it
    conflict with something in `## Now`?
 
-5. **Cost vs value.**
+6. **Cost vs value.**
    - Size: **small** (1 file, < 50 lines) · **medium** (2–5 files, < 200 lines) ·
      **large** (5+ files) · **too-large** (architecture change — split it).
    - Ongoing cost: new dependency, new service bill, more to maintain, more to
      test, store review risk.
    - Value: name the user or the metric it moves (`metrics/definitions.yml` if
-     the product has one). If neither can be named, say "value unproven".
+     the product has one). If neither can be named, say "value unproven". A
+     value claim is checked like any other claim, in step 4.
+   - Evidence: say which evidence from `dev-methods.md` the work must leave — a
+     feature page, a failing test first, or a metric and snapshot.
 
-6. **Write less.** Climb the ladder and stop at the first rung that works:
+7. **Write less.** Climb the ladder and stop at the first rung that works:
    delete it → reuse something in this repo → reuse from a sibling product or
    shared script → platform or standard library → an existing well-used package
    → fewer lines → new code. If the `ponytail` plugin is installed, follow its
    ladder for this step.
 
-7. **Large or too-large?** Delegate steps 2–6 to the `challenger` agent for an
-   independent read — pass it the request, the repo path and the constitution
-   and standards paths from step 2 — then reconcile: where you and it disagree,
-   show both.
+8. **Too-large, or the user asked for a second opinion?** Then, and only then,
+   ask the `challenger` agent for an independent read. It costs tens of
+   thousands of tokens, so hand it what you already have: the request, the repo
+   path, your draft verdict, and every file and wiki page you read with one line
+   on what each says. It checks your reasoning and looks only where you did
+   not. Where you and it disagree, show both. A large request is weighed by you
+   alone.
 
 ## Verdict
 
@@ -76,26 +99,48 @@ Why:
 - <C-xx> <one line> — <file or wiki page cited>
 - ...
 Instead: <only for DO IT DIFFERENTLY — the cheaper or safer way>
+Claims:
+- "<claim>" — backed | partly backed | not backed — <fact and source, or what was searched>
+Assumed: <every claim not backed, or "none">
 Open questions: <only if a real ambiguity blocks a good answer>
 ```
 
 - Every bullet under **Why** cites a principle ID and a source (a wiki page, ADR,
-  standard, feature or file). A reason with no source is an opinion — drop it or
-  mark it "unverified".
-- **DO IT** → proceed with the work in the same turn.
+  standard, feature, file or saved query result). A reason with no source is an
+  opinion: drop it, or list it under **Assumed**.
+- **DO IT** only when **Assumed** is "none". Proceed with the work in the same
+  turn.
 - **DO IT DIFFERENTLY** → proceed with the *Instead* version only if the user
-  already accepted it; otherwise stop and ask which way.
-- **PUSH BACK** → stop. Do not start the work, not even a part of it. Ask for
-  the reason. When the user gives one, log it (below), then proceed as they say.
+  already accepted it and **Assumed** is "none"; otherwise stop and ask.
+- **PUSH BACK** → stop. Do not start the work, not even a part of it.
+- **Something is assumed** → stop, and give the user three choices: bring the
+  facts (and say where they would go), agree to terms, or drop it.
+
+Write the whole reply in plain words (C-15): short sentences, common words, no
+jargon the wiki does not define.
+
+## Terms (when the user wants to go on anyway)
+
+When the user wants to go on despite a PUSH BACK or an assumption, write the
+terms as a numbered list: what is in scope, what is out, which rule changes and
+which stays, and how the assumption will be checked later (a metric and a
+date). A fact the user gives in chat is saved to `.context/raw/` first, then
+listed as a fact, not as proof of more than it shows.
+
+Proceed only after the user agrees in writing ("agree", or "agree to 1–4").
+"Go ahead" to a verdict is not agreement to terms that were never shown. Work
+covers only the terms agreed to.
 
 ## Logging (push back and overrides)
 
-When the user overrides a PUSH BACK or rejects a DO IT DIFFERENTLY, append one
-line to the product's log so zeno can learn from it later:
+When the user overrides a PUSH BACK, rejects a DO IT DIFFERENTLY or agrees to
+terms, append one line to the product's log so zeno can learn from it later.
+Pass each agreed term with its own `--term`:
 
 ```bash
-node ../../scripts/log-verdict.mjs --verdict push-back --principles C-05,C-06 \
-  --request "<one line>" --reason "<the user's reason, verbatim>"
+node ../../scripts/log-verdict.mjs --verdict push-back --principles C-04,C-14 \
+  --request "<one line>" --reason "<the user's reason, verbatim>" \
+  --term "<term 1>" --term "<term 2>"
 ```
 
 (path relative to this skill). It writes to `.context/raw/zeno/verdicts.jsonl`

package/skills/wiki-lint/SKILL.md

@@ -3,13 +3,13 @@ name: wiki-lint
 description: Audit .context/wiki/ for drift — broken [[links]], orphan pages, contradictions between entities, stale last-verified dates, unprocessed raw files. Optionally auto-fix safe issues and regenerate .context/wiki/index.md. Usage `/wiki-lint` (audit) or `/wiki-lint --fix` (audit + auto-fix).
 ---
 
-You are linting the wiki at `.context/wiki/` against the wiki schema (`../../standards/wiki-schema.md`, relative to this skill).
+You are linting the wiki at `.context/wiki/` against 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).
 
 Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 ## Steps
 
-1. **Read the wiki schema (`../../standards/wiki-schema.md`, relative to this skill)** to refresh schema, ID conventions, required sections, and the lint-rules table.
+1. **Read the wiki schema** to refresh schema, ID conventions, required sections, and the lint-rules table.
 
 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,
@@ -29,13 +29,13 @@ Mode: `$ARGUMENTS` (empty = audit only; `--fix` = audit + auto-fix safe issues).
 
 | Check | Rule |
 |---|---|
-| Missing required section | Per the wiki schema (`../../standards/wiki-schema.md`, relative to this skill) § "Page body — required sections" |
+| 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. |
+| `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`. |
 
 ### Warnings
 

package/standards/README.md

@@ -9,5 +9,6 @@ replaces it; a configured `constitution.md` adds principles instead.
 |---|---|
 | `constitution.md` | The principles a request is weighed against (C-01 to C-13) |
 | `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
-| `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` formats |
+| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, `features/` and `tasks.md` formats |
+| `dev-methods.md` | The evidence spec-, test- and data-driven work leaves behind |
 | `agent-contract.md` | What every agent does before, during and after work |

package/standards/agent-contract.md

@@ -22,6 +22,12 @@ file with its own `agent-contract.md` in a configured standards folder.
    `.github/` — stay at the root.
 3. Generated folders are never hand-edited; change their source and regenerate.
 
+## Replies
+
+- Plain words, short sentences (C-15).
+- Never treat a claim in the request as a fact. Check it, or say it is not
+  checked (C-14).
+
 ## Comments
 
 Write a comment only to explain **why**. The code already says how.

package/standards/constitution.md

@@ -14,7 +14,8 @@ standards folders; zeno reads both.
 Before acting on a non-trivial request, check it against the principles below,
 then answer with one verdict:
 
-- **Do it** — no principle is at risk.
+- **Do it** — no principle is at risk, and no claim it rests on is an
+  assumption (C-14).
 - **Do it differently** — the goal is fine; the way asked breaks a principle.
   Name the principle and give the cheaper or safer way.
 - **Push back** — the request breaks a principle outright, or the cost is
@@ -81,6 +82,16 @@ production deploys and permission changes are confirmed first, every time.
 Money in integer minor units; privacy promises match what the code does; store
 claims match the app. Correctness beats speed here.
 
+### C-14 Facts, not assumptions
+A request is not a fact. Every claim in it ("users want this", "it is slow",
+"it is missing") is checked against the repo and the repo's data sources. A
+claim with no fact behind it is an assumption. Work that rests on an assumption
+does not start until the user agrees to it, in writing, as numbered terms.
+
+### C-15 Plain words
+Short sentences and common words. No jargon unless the repo's wiki defines it.
+Say what was checked, what was found and what happens next.
+
 ## Weights
 
 A repo's `.claude/zeno.yaml` may raise or lower the weight of a principle under

package/standards/context-layout.md

@@ -26,6 +26,9 @@ folder.
 1. **Ten folders, one job each.** There is no `documents/`, `research/`,
    `architecture/` or `decisions/` folder: a research brief is a wiki synthesis
    page, an architecture note is a wiki concept, an ADR is `wiki/decisions/`.
+   A product that truly needs another folder adds it in `.claude/zeno.yaml`,
+   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>`.
 3. **Nothing is created empty.** A folder appears with its first file — git does
@@ -54,6 +57,26 @@ folder.
 - Frontmatter follows the wiki schema: `id`, `type`, `status`, `last-verified`,
   `supersedes`, `superseded-by`. Kebab-case keys.
 
+## Where each kind of document lives
+
+Teams name documents many ways. Each name maps to one home; there is no
+separate folder per name.
+
+| Document | Home |
+|---|---|
+| ADR | `wiki/decisions/`, `status: canonical` |
+| RFC | `wiki/decisions/`, `status: draft` — the same page becomes the ADR when accepted |
+| PRD | `features/`, `type: feature` |
+| Experiment | `features/`, `type: experiment`; the result is a decision page |
+| Initiative | `wiki/synthesis/`, linking its features and decisions |
+| Finding | the dated data in `raw/`; what it means in `wiki/synthesis/` or a concept |
+| Know-how | `wiki/concepts/`; `ops/` when it is a runbook |
+| Bug | the issue tracker; a wiki concept only when it teaches a rule |
+| Data source | `wiki/entities/` — see the wiki schema, "Data sources" |
+
+If a document fits none of these for a real product, add a wiki type or a
+folder in `.claude/zeno.yaml` with its reason — not a new convention by hand.
+
 ## `features/` — what is next
 
 One page per feature, `NNNN-<slug>.md`:
@@ -72,6 +95,9 @@ release: 3.4.0
 > One or two sentences users will read in the release notes.
 ```
 
+An experiment adds `## Hypothesis`, `## Metric` (a name from
+`metrics/definitions.yml`) and `## Result` once it has run.
+
 The wiki describes what *is*; `features/` describes what is *next*. A shipped
 feature goes `status: shipped` and is never deleted.
 

package/standards/dev-methods.md

@@ -0,0 +1,29 @@
+# Development methods
+
+zeno does not run a method; it checks that the method left evidence a later
+reader (or the weigh gate) can follow. A team replaces this file with its own
+`dev-methods.md` in a configured standards folder.
+
+| Method | The evidence it leaves |
+|---|---|
+| Spec-driven | A `features/` page with acceptance scenarios, written before the code. Code and tests cite its ID (`FEAT-0031`) or a wiki ID (`FLOW.…`, `DECISION.…`). |
+| Test-driven | A test that failed before the change and passes after. Bug fixes start with the failing test. The test path goes in the feature page or decision. |
+| Data-driven | A named metric in `metrics/definitions.yml`, the query that measured it, and a dated snapshot in `raw/`. The decision cites the snapshot, not a memory of a dashboard. |
+
+## Which one, when
+
+- **New behaviour users see** → spec-driven: the feature page comes first.
+- **Logic that can break** (money, parsing, data writes, a bug fix) → test-driven.
+- **A bet on what users want** → data-driven: an experiment page with its metric
+  before the build, the result as a decision after.
+
+They combine. A paywall change is a spec (what users see), tests (the price
+logic) and an experiment (does conversion move).
+
+## Rules
+
+1. No evidence, not done. "It works" without a test, a scenario or a number is
+   an opinion.
+2. Evidence lives in the repo (C-03). A dashboard link alone is not evidence —
+   it changes; the snapshot in `raw/` does not.
+3. When a method keeps being skipped, make it a check (C-09), not a longer doc.

package/standards/wiki-schema.md

@@ -33,6 +33,55 @@ Every page in `.context/wiki/` belongs to exactly one type. The folder name is t
 
 A page cannot be two types. If it feels like it is, it's two pages — split it.
 
+A product adds a type in `.claude/zeno.yaml`, with the reason and the `## `
+sections every page of it must have:
+
+```yaml
+wiki:
+  types:
+    - { type: postmortem, folder: postmortems, reason: …, sections: [Summary, Timeline, Root cause, Fix, Sources] }
+```
+
+`zeno check` fails a page of that type that misses a section. Its ID is
+`<TYPE>.<SLUG>` (`POSTMORTEM.MIDNIGHT-RESET`). The six built-in types and their
+folders cannot be redefined. Try the six first — an added type is a shape every
+reader and every product must learn.
+
+### Data sources
+
+Each tool that holds product data (Datadog, Sentry, Snowflake, an analytics
+console) is one `entity` page, `id: SOURCE.<NAME>`, in `entities/`:
+
+```markdown
+## Summary
+What this source holds, in one sentence.
+
+## Canonical values
+| Key | Value | Last changed |
+|---|---|---|
+| SOURCE.SENTRY.PROJECT | streaks-mobile | 2026-10-23 |
+| SOURCE.SENTRY.ACCESS | mcp: sentry | 2026-10-23 |
+
+## How to query
+The claims this source can answer, and one example query for each.
+```
+
+zeno has no connector of its own. The repo picks what does the reading, and
+`ACCESS` names it: `mcp: <server>`, `skill: <name>` or `cli: <command>`. A
+`cli:` must also be in `doctor.tools` in `.claude/zeno.yaml`, so `zeno doctor`
+reports when it is missing. `zeno check` fails a source page that breaks either
+rule or has no `## How to query`. Never put a key or token on the page.
+
+The weigh gate reads sources to check a claim (C-14). Every query follows these
+rules:
+
+- **Read only.** Never create, change or delete anything in the source.
+- **Small.** One or two queries per claim, with a row limit. Some sources bill
+  per query.
+- **No user data in git.** Save counts, totals and rates, never rows that name
+  a person, an email or a device. Results that back a decision go to
+  `raw/YYYY-MM-DD-<source>-<slug>.md`: the query, the date and the numbers.
+
 ---
 
 ## Frontmatter (mandatory)