@freetesh/zeno 0.8.0 → 0.9.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,10 +1,28 @@
-# zeno
+<p align="center">
+  <img src=".github/assets/icon.svg" width="96" height="96" alt="zeno icon">
+</p>
 
-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.
+<h1 align="center">zeno</h1>
+
+<p align="center">
+  <b>Facts, not assumptions.</b> Your rules, kept in your repo. Enforced.<br>
+  A Claude Code plugin and CLI · MIT
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@freetesh/zeno"><img alt="npm" src="https://img.shields.io/npm/v/@freetesh/zeno"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+</p>
+
+zeno keeps your domain knowledge, decisions and AI rules in your own repos, and
+enforces them. Claude searches them before it answers. It weighs each request
+against them before it acts, and it checks every claim in the request against
+facts. `zeno check` fails when code or docs break a rule. The AI guesses less,
+and you redo less work.
+
+<p align="center">
+  <img src=".github/assets/demo.svg" alt="zeno weighs a request. Two of three claims have no facts and the request breaks a decided rule, so it pushes back and stops until the user brings facts, agrees to terms, or drops it.">
+</p>
 
 It has two halves that read the same config:
 
@@ -19,6 +37,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.
@@ -78,17 +105,6 @@ starter `.dependency-cruiser.cjs` to your layers. `evals/fixtures/streaks` is a
 small product with a wiki and decision records, if you want to see the
 `.context/` layout before touching your own repo.
 
-For local development of zeno itself, link the repo as a skills-dir plugin so
-edits apply on the next session: `ln -s "$PWD" ~/.claude/skills/zeno`.
-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
@@ -136,7 +152,7 @@ context:
 
 ```yaml
 # <repo>/.claude/zeno.yaml — written by `zeno init`
-zeno: 0.6.0
+zeno: 0.9.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]
@@ -155,7 +171,7 @@ carry a `reason:`, and `zeno check` lists every override.
 
 | zeno default | What it holds |
 |---|---|
-| `constitution.md` | Principles C-01–C-13 a request is weighed against. A team adds C-20+ in its own `constitution.md`. |
+| `constitution.md` | Principles C-01–C-15 a request is weighed against. A team adds C-20+ in its own `constitution.md`. |
 | `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
 | `context-layout.md` | The `.context/` ten-folder layout, `features/` and `tasks.md` |
 | `agent-contract.md` | What every agent does before, during and after work |
@@ -168,7 +184,7 @@ your own.
 
 ## Evals
 
-`evals/` runs seven 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:
 
@@ -190,3 +206,16 @@ scripts/          log-verdict.mjs — append-only override log
 cli/              the zeno CLI (TypeScript, vitest; built to cli/dist for npm)
 evals/            plugin evals and the fixture product
 ```
+
+## Develop zeno
+
+Link the repo as a skills-dir plugin so edits apply on the next session:
+`ln -s "$PWD" ~/.claude/skills/zeno`.
+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.

package/cli/dist/checks/index.js

@@ -4,6 +4,7 @@ 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,
@@ -13,5 +14,6 @@ export const ALL_CHECKS = [
     staleCopies,
     architecture,
     metricsDefinitions,
+    sources,
     commandChecks,
 ];

package/cli/dist/checks/sources.js

@@ -0,0 +1,40 @@
+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 that a person reads it by hand (`manual:`), or the weigh gate
+// cannot turn a claim into a fact.
+const ACCESS = /^(mcp|skill|cli|manual):\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, 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."))
+                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>, cli: <command> or manual: <where>`);
+            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/package.json

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

package/skills/weigh/SKILL.md

@@ -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
@@ -31,7 +34,7 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
 3. **Domain.** Search before you judge. Run `mcp__plugin_zeno_qmd__query` with
    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 4 is where
+   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/`.
@@ -42,30 +45,42 @@ 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:`, `cli:` or `manual:`) and which claims it
+   answers. For `manual:`, ask the user for the numbers and say where to find
+   them; do not guess. 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".
-     When a number would settle it, check the product's `SOURCE.*` entity pages
-     for where that data lives and query it rather than guess.
+     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. **Too-large, or the user asked for a second opinion?** Then, and only then,
+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
@@ -85,26 +100,50 @@ 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. Any terms
+  you show, here or later, are a numbered list, so the user can agree line by
+  line.
+
+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/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/wiki-schema.md

@@ -60,16 +60,28 @@ What this source holds, in one sentence.
 | Key | Value | Last changed |
 |---|---|---|
 | SOURCE.SENTRY.PROJECT | streaks-mobile | 2026-10-23 |
-| SOURCE.SENTRY.ACCESS | Sentry MCP server | 2026-10-23 |
+| SOURCE.SENTRY.ACCESS | mcp: sentry | 2026-10-23 |
 
 ## How to query
-The MCP server or CLI to use, and one example query. Results that back a
-decision are saved to `raw/YYYY-MM-DD-<source>-<slug>.md` so they can be re-read.
+The claims this source can answer, and one example query for each.
 ```
 
-zeno has no connector of its own: the vendor's MCP server or CLI does the
-reading. Add it to `doctor.tools` in `.claude/zeno.yaml` so `zeno doctor`
-reports when it is missing. Never put a key or token on the page.
+zeno has no connector of its own. The repo picks what does the reading, and
+`ACCESS` names it: `mcp: <server>`, `skill: <name>`, `cli: <command>`, or
+`manual: <where>` for a dashboard with no API, which a person reads and pastes
+into `raw/`. 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.
 
 ---