@freetesh/zeno 0.9.0 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "zeno",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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:
 
@@ -18,7 +36,8 @@ It has two halves that read the same config:
   constitution, your wiki and decision records, existing features and tasks,
   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`.
+  give a reason. Every verdict is logged; `zeno learn` shows how often the gate
+  stops you and turns repeated overrides into proposals.
 - **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
@@ -87,17 +106,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
@@ -145,7 +153,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]
@@ -164,7 +172,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 |
@@ -195,7 +203,20 @@ hooks/            session start: constitution titles, qmd refresh
 standards/        default standards
 packs/            vendor doc packs
 templates/        files init writes: dependency-cruiser base (synced) and starters
-scripts/          log-verdict.mjs — append-only override log
+scripts/          log-verdict.mjs — append-only verdict 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/sources.js

@@ -3,8 +3,9 @@ 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+)/;
+// 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|`));
@@ -13,7 +14,7 @@ function accessValue(body, id) {
 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",
+    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) => {
@@ -30,7 +31,7 @@ export const sources = {
             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>`);
+                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/cli/dist/commands/learn.js

@@ -1,11 +1,11 @@
-import { proposals, readDecisions, readVerdicts, recordDecision } from "../learn.js";
+import { proposals, readDecisions, readVerdicts, recordDecision, summarise } from "../learn.js";
 import { findProducts } from "../run.js";
 import { requireEstate } from "./env.js";
 const DEFAULT_THRESHOLD = 3;
 export function registerLearn(program, env) {
     program
         .command("learn")
-        .description("turn overridden verdicts across products into proposals to change the rules")
+        .description("show how often the gate stops work, and turn overrides across products into proposals to change the rules")
         .option("--threshold <n>", "overrides of one principle before it is proposed", String(DEFAULT_THRESHOLD))
         .option("--approve <id>", "mark a proposal approved (then edit the standard)")
         .option("--reject <id>", "mark a proposal rejected; it returns only with new evidence")
@@ -23,7 +23,8 @@ export function registerLearn(program, env) {
             console.log(`${options.approve ? "approved" : "rejected"} ${target}`);
             return;
         }
-        console.log(`${entries.length} overridden verdict(s) logged across the estate`);
+        const s = summarise(entries);
+        console.log(`${s.total} verdict(s) logged: ${s.proceeded} went ahead, ${s.stopped} stopped, ${s.overridden} overridden, ${s.dropped} dropped`);
         if (found.length === 0)
             console.log("no proposals");
         for (const proposal of found) {

package/cli/dist/learn.js

@@ -1,5 +1,14 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+export const OUTCOMES = ["proceeded", "stopped", "overridden", "dropped"];
+const outcomeOf = (entry) => entry.outcome ?? "overridden";
+/** How often the gate let work through, stopped it, or was overridden. */
+export function summarise(entries) {
+    const counts = Object.fromEntries(OUTCOMES.map((o) => [o, 0]));
+    for (const entry of entries)
+        counts[outcomeOf(entry)] += 1;
+    return { total: entries.length, ...counts };
+}
 const LOG = join(".context", "raw", "zeno", "verdicts.jsonl");
 const MAX_REASONS = 5;
 function readJsonLines(path) {
@@ -41,7 +50,9 @@ function toProposal(id, summary, entries) {
  * times, or one reason given in two or more products. A decided proposal comes
  * back only when its count has grown past what it was when decided.
  */
-export function proposals(entries, options) {
+export function proposals(all, options) {
+    // Only an override says a rule may be wrong; a verdict the user followed says nothing about it.
+    const entries = all.filter((entry) => outcomeOf(entry) === "overridden");
     const found = [];
     for (const [principle, group_] of group(entries, (e) => e.principles)) {
         if (group_.length >= options.threshold) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freetesh/zeno",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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

@@ -49,8 +49,9 @@ product's `.claude/zeno.yaml` may tighten this under `weigh.trivial`.
    **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`
+   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
@@ -114,7 +115,9 @@ Open questions: <only if a real ambiguity blocks a good answer>
   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.
+  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.
@@ -131,17 +134,27 @@ 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)
+## Logging (every verdict)
 
-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`:
+Log every verdict once, when you know what happened next. A trivial request
+that skipped the gate is not logged. `--outcome` is one of:
+
+- `proceeded` — work went ahead as the verdict said (DO IT, or an accepted
+  *Instead*).
+- `stopped` — you stopped and asked, and the user has not answered yet. Log it
+  when you stop; if the user later overrides, log a second line.
+- `overridden` — the user went on against a PUSH BACK, rejected a DO IT
+  DIFFERENTLY, or agreed to terms. `--reason` is required: the user's reason,
+  verbatim. Pass each agreed term with its own `--term`.
+- `dropped` — the user chose to drop the request.
 
 ```bash
-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>"
+node ../../scripts/log-verdict.mjs --verdict push-back --outcome overridden \
+  --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`
-in the current repo. Never edit or delete existing lines.
+in the current repo. Never edit or delete existing lines. `zeno learn` reads
+the log across products: how often the gate stops work, and which rules keep
+being overridden.

package/standards/wiki-schema.md

@@ -67,8 +67,9 @@ 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`
+`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.