@freetesh/zeno 0.10.0 → 0.12.0

package/standards/agent-contract.md

@@ -8,7 +8,7 @@ file with its own `agent-contract.md` in a configured standards folder.
 - Read the repo's `CLAUDE.md` / `AGENTS.md`: stack, layout, the rules that are
   the repo's own.
 - Read `.context/tasks.md`. It is the ordered queue — the top item of `## Now`
-  is the next action. After finishing, tick the task and append a Session Note.
+  is the next action. After finishing, delete the task.
 - For a non-trivial request, run the weigh gate first (`/zeno:weigh`).
 
 ## Repository rules
@@ -40,7 +40,8 @@ function's own name.
 
 ## Before calling work done
 
-1. Reflect changed behaviour in `CLAUDE.md` and any affected `.context/` page.
+1. Update any `.context/` page the change made wrong. Add a page only if an
+   agent would get something wrong without it.
 2. Run the repo's own lint, typecheck and tests.
 3. Run `zeno check`. Every checker the repo declares under `commands:` runs
    with it.

package/standards/context-layout.md

@@ -52,10 +52,10 @@ folder.
 
 ## Naming and frontmatter
 
-- Append-only, time-ordered files → ISO date: `YYYY-MM-DD-slug.md`.
-- Files referenced by a stable ID → zero-padded number: `NNNN-slug.md`.
-- Frontmatter follows the wiki schema: `id`, `type`, `status`, `last-verified`,
-  `supersedes`, `superseded-by`. Kebab-case keys.
+- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`.
+- Features → zero-padded number: `NNNN-slug.md`.
+- Everything else is named by topic and edited in place.
+- Frontmatter: `last-verified`, kebab-case keys. See the wiki schema.
 
 ## Where each kind of document lives
 
@@ -64,8 +64,8 @@ separate folder per name.
 
 | Document | Home |
 |---|---|
-| ADR | `wiki/decisions/`, `status: canonical` |
-| RFC | `wiki/decisions/`, `status: draft` — the same page becomes the ADR when accepted |
+| ADR | `wiki/decisions/<topic>.md`, overwritten when the choice changes |
+| RFC | `features/`; once accepted, the choice goes in `wiki/decisions/` |
 | PRD | `features/`, `type: feature` |
 | Experiment | `features/`, `type: experiment`; the result is a decision page |
 | Initiative | `wiki/synthesis/`, linking its features and decisions |
@@ -99,16 +99,11 @@ 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.
+feature goes `status: shipped`.
 
-## `tasks.md` — the ordered queue
+## `tasks.md` — open work only
 
 ```markdown
----
-updated: 2026-09-29
-horizon: 2026-10-13        # this file is stale after this date
----
-
 # Tasks
 
 ## Now                       <!-- position is the dependency; do in order -->
@@ -116,7 +111,7 @@ horizon: 2026-10-13        # this file is stale after this date
 2. [ ] T002 Write the capture flows  needs:T001  ~3h
 
 ## Parallel                  <!-- independent, safe to batch -->
-- [ ] T004 [P] Move the SKU IDs into the wiki  ~1h
+- [ ] T004 Move the SKU IDs into the wiki  ~1h
 
 ## Blocked
 - [ ] T005 Submit the iOS build
@@ -125,14 +120,9 @@ horizon: 2026-10-13        # this file is stale after this date
 
 ## Waiting                   <!-- deferred by time, not by a task -->
 - [ ] T006 Second-language listing  wait:2026-11-01
-
-## Done
-- [x] T000 Set up .context  done:2026-09-29
-
-## Session Notes
-### 2026-09-29
-- Done: T000.  Learned: …  Next: T001.
 ```
 
-A blocker with no named unblocking action and no check date is a silent leak.
-A task that needs more than a line and a continuation is a `features/` page.
+Delete a task when it is done — the commit records it. No `## Done`, no session
+notes. Cap: 100 lines. A blocker with no unblocking action and no check date is a
+silent leak. A task that needs more than a line and a continuation is a
+`features/` page.

package/standards/wiki-schema.md

@@ -1,299 +1,71 @@
-# Wiki — schema and rules
+# Wiki — rules
 
-This folder is a **Claude-maintained knowledge base** for the product. The model is the LLM-Wiki pattern: `.context/raw/` holds immutable sources, `.context/wiki/` holds synthesised pages with `[[wikilinks]]`, this file defines the schema.
+`.context/wiki/` holds what an agent would get wrong without being told. `.context/raw/` holds
+sources, never edited. Answer from the wiki, not from raw.
 
-**Read this file before creating or editing any page under `.context/wiki/`.**
+## The test
 
----
-
-## Three layers
-
-| Layer | Path | Mutability | Who writes |
-|---|---|---|---|
-| Raw | `.context/raw/`, `.context/designs/` | **Immutable** — never edit | Humans (or external systems) |
-| Wiki | `.context/wiki/` | Mutable, schema-bound | Claude (via `/zeno:ingest`, `/zeno:ask`, `/zeno:wiki-lint`) |
-| Index | `.context/wiki/index.md` | Auto-maintained | `/zeno:ingest` and `/zeno:wiki-lint` |
-
-The wiki is the **only** layer Claude reads for `/zeno:ask`. Never answer from `.context/raw/` directly — the synthesis must be written down or it doesn't exist.
-
----
+Keep a line only if an agent would make a mistake without it. Never write what the
+code, an HTML design, or `git log` already says. Describe what is true **now**:
+history is git's job.
 
-## Page types
-
-Every page in `.context/wiki/` belongs to exactly one type. The folder name is the type.
-
-| Type | Folder | What it owns | Example |
-|---|---|---|---|
-| `concept` | `concepts/` | An idea, principle, or invariant. Prose-shaped. | `offline-first`, `money-in-minor-units` |
-| `entity` | `entities/` | A thing with canonical values (price, name, enum). Table-shaped. | `plan-pro`, `plan-free` |
-| `surface` | `surfaces/` | One screen / route / email / callable. Links to a raw wireframe. | `onboarding-welcome` |
-| `flow` | `flows/` | A user journey. Ordered list of `[[surface]]` steps. | `new-user-to-first-save` |
-| `decision` | `decisions/` | One ADR. Filename = `YYYY-MM-DD-slug.md`. Append-only. | `2026-06-24-annual-plan-only` |
-| `synthesis` | `synthesis/` | Cross-cutting page built from many entities/concepts. Refreshable. | `pricing`, `launch-checklist` |
-
-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] }
-```
+## Folders
 
-`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 |
+| Folder | Holds | Example |
 |---|---|---|
-| SOURCE.SENTRY.PROJECT | streaks-mobile | 2026-10-23 |
-| SOURCE.SENTRY.ACCESS | mcp: sentry | 2026-10-23 |
+| `concepts/` | a rule or invariant | `money-in-minor-units` |
+| `entities/` | canonical values (prices, SKUs, limits) — the one home for each | `plan-pro` |
+| `decisions/` | one file per topic: the current choice | `pricing` |
+| `surfaces/` | a screen's notes: what its HTML can't show (only screens that have some) | `paywall` |
+| `synthesis/` | research and cross-cutting analysis | `tax-table-verification-ay-2026-27` |
 
-## How to query
-The claims this source can answer, and one example query for each.
-```
+There is no page per screen: the HTML design is the screen spec. A screen gets a
+`surfaces/<slug>.md` only when it has a constraint or decision invisible in its pixels;
+the design set's notes button shows it, and `routes.js` sets `notes: null` for every
+other screen. A user journey worth keeping is a concept.
+A product may add a folder in `.claude/zeno.yaml` under `wiki.types`, with a reason.
 
-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.
+## Pages
 
-The weigh gate reads sources to check a claim (C-14). Every query follows these
-rules:
+- Frontmatter: `last-verified: YYYY-MM-DD` is the only required field. `id` is kept
+  where code references it (`SOURCE.*`, entity keys).
+- Write only the sections you have something to say in. No `TBD`, no `none yet`.
+- One file per topic, edited in place. No dated names, no `v2`, no supersede chains.
+- Caps: page 60 lines, decision 30. Synthesis is exempt.
+- Link with `[[slug]]` (the file name without `.md`). `index.md` is one line per page.
 
-- **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.
+## Decisions
 
----
-
-## Frontmatter (mandatory)
-
-Every page begins with YAML frontmatter:
-
-```yaml
----
-id: PLAN.PRO                  # Stable, uppercase, dot-separated. Never changes. Referenced from code.
-type: entity                  # concept | entity | surface | flow | decision | synthesis
-status: canonical             # canonical | draft | superseded
-last-verified: 2026-06-24     # ISO date. /zeno:wiki-lint flags pages > 90 days.
-supersedes: []                # IDs this page replaces (decisions only)
-superseded-by: null           # If non-null, this page is no longer canonical
----
-```
-
-### ID conventions
-
-| Type | ID shape | Example |
-|---|---|---|
-| concept | `CONCEPT.<SLUG>` | `CONCEPT.OFFLINE-FIRST` |
-| entity | `<DOMAIN>.<NAME>` | `PLAN.PRO`, `PLAN.FREE` |
-| surface | `SURFACE.<APP>.<PATH>` | `SURFACE.MOBILE.ONBOARDING.WELCOME` |
-| flow | `FLOW.<SLUG>` | `FLOW.NEW-USER-TO-FIRST-SAVE` |
-| decision | `DECISION.<YYYY-MM-DD>.<SLUG>` | `DECISION.2026-06-24.ANNUAL-PLAN-ONLY` |
-| synthesis | `SYNTHESIS.<SLUG>` | `SYNTHESIS.PRICING` |
-
-Once assigned, an ID never changes. If a page is renamed, the ID stays. If the thing it describes is killed, mark `status: superseded` and set `superseded-by`; do not delete.
-
----
-
-## Page body — required sections
-
-Each type has a required section list. `/zeno:wiki-lint` fails the page if any are missing.
-
-### `concept`
 ```markdown
-## Summary
-One sentence — what the concept is.
-
-## Why it matters
-Why this is a load-bearing idea. Tie it to a constraint, an incident, or a principle.
-
-## Implications
-Bulleted: what this forces / forbids in practice.
-
-## Related
-- [[other-concept]] — relationship
-- [[entity-x]] — where this applies
-
-## Sources
-- .context/raw/<source> or .context/designs/<surface>/<flow>/<screen>.html
-```
-
-### `entity`
-```markdown
-## Summary
-One sentence — what this entity is.
-
-## Canonical values
-| Key | Value | Last changed |
-|---|---|---|
-| PRICE.PRO.YEARLY | $49 | 2026-04-12 |
-| STORAGE.PRO | 5 GB | 2026-04-12 |
-
-## Related
-- [[concept-x]] — concept this entity instantiates
-- [[entity-y]] — sibling / upgrade-from
-
-## Sources
-- .context/raw/<source>
-```
-
-The `Canonical values` table is the single source of truth. Any value here that disagrees with the codebase is a bug — fix the code or update this page.
-
-### `surface`
-```markdown
-## Summary
-One sentence — what this screen does.
-
-## Raw wireframe
-- .context/designs/<surface>/<flow>/<screen>.html
-
-## Copy
-Verbatim user-visible strings. Each must pass the [[copy-voice]] rules.
-
-## Flows that touch this surface
-- [[new-user-to-first-save]] — step 4
-
-## Entities referenced
-- [[plan-free]]
-- [[privacy-consent]]
-
-## Sources
-- .context/raw/<source>
-```
-
-### `flow`
-```markdown
-## Summary
-One sentence — what journey this is.
-
-## Audience
-end-user | admin
-
-## Entry
-Where the user arrives from.
-
-## Steps
-| # | Step | Surface | Notes |
-|---|---|---|---|
-| 1 | Welcome | [[welcome]] | First launch |
-| 2 | Sign up | [[sign-up]] | Email |
-| ... |
-
-## Exit
-The success state.
-
-## Escapes
-Back-button, skips, abandonment outcomes.
-
-## Sources
-- .context/raw/<source>
-```
-
-### `decision`
-```markdown
-## Decision
-One-line statement.
-
-## Why
-The motivation. Cite the trigger — incident, user feedback, regulator, scope cut.
-
-## Impact
-What changes downstream. Which [[entities]] / [[surfaces]] / [[concepts]] update.
-
-## Status
-Active | Superseded by [[decision-id]]
-
-## Sources
-- .context/raw/<source>
-```
-
-Decisions are append-only. To reverse a decision, write a new one with `supersedes: [DECISION.<old>]` and mark the old one's `superseded-by`.
-
-### `synthesis`
-```markdown
-## Summary
-What this synthesis combines.
-
-## Built from
-- [[entity-x]]
-- [[entity-y]]
-- [[concept-z]]
-
-## Body
-The cross-cutting answer. Every claim links back to a source page.
-
-## Last refresh
-2026-06-24 — refresh when any "Built from" page changes.
-
-## Sources
-- (synthesis pages cite wiki pages, not raw files)
-```
-
-Synthesis pages are **derived**. If a source page changes, `/zeno:wiki-lint` marks the synthesis stale.
-
 ---
-
-## Linking
-
-- Use `[[page-slug]]` — the filename without `.md`. Match the file exactly (case-sensitive on case-sensitive filesystems).
-- Cross-folder links use the slug, not the path: `[[tier-self]]`, not `[[entities/tier-self]]`.
-- An `[[unknown-link]]` is a TODO marker — `/zeno:wiki-lint` reports it. Never silently delete a broken link; either create the target page or rename the link.
-- The `Related` section is what makes the graph navigable. Every page must have at least two outbound links (or be flagged as orphan-source).
-
+last-verified: 2026-10-27
 ---
+# Pricing
+**Choice:** annual plan only, ₹249 ([[plan-pro]]).
+**Why:** monthly churn was 3× annual in the 2026-06 test.
+**Rejected:** monthly plan (churn) · lifetime deal (no recurring revenue).
+```
 
-## Lint rules (what `/zeno:wiki-lint` enforces)
-
-| Rule | Failure |
-|---|---|
-| Missing required section | Block — must be fixed |
-| `[[wikilink]]` to a non-existent page | Block — create target or rename link |
-| Orphan page (zero inbound links) | Warn |
-| Two entities claim the same `id` | Block |
-| Two entities have contradictory canonical values for the same key | Block |
-| `last-verified` > 90 days | Warn |
-| `status: superseded` without `superseded-by` | Block |
-| Source file in `.context/raw/` not referenced by any wiki page | Warn |
-| Synthesis page where a `Built from` page changed after `Last refresh` | Warn |
-| Filename does not match the `id`'s slug portion | Block |
+When the choice changes, overwrite the file. `Rejected:` is what stops the same idea
+being proposed again; keep it. Fix lists and audit results go in commit messages or
+`CHANGELOG.md`, not here.
 
-`/zeno:wiki-lint --fix` auto-fixes: filename ↔ id mismatches, missing `last-verified` (sets to today if the page is touched), index regeneration.
+## Data sources
 
----
+Each tool that holds product data is one entity page, `id: SOURCE.<NAME>`, with a
+`## How to query` section and a `SOURCE.<NAME>.ACCESS` row: `mcp: <server>`,
+`skill: <name>`, `cli: <command>` (also listed in `doctor.tools`) or `manual: <where>`.
+Queries are read-only, one or two per claim, with a row limit. Save counts and
+rates to `raw/YYYY-MM-DD-<source>-<slug>.md`, never rows that name a person. Never
+put a key or token on the page.
 
-## What the wiki is NOT for
+## Not for
 
-- **Not for code documentation.** Docstrings stay in code. The wiki is product-shaped, not API-shaped.
-- **Not for transient task tracking.** Use `TaskCreate` / PR descriptions / commit messages for ephemeral work.
-- **Not for chat logs.** If a chat produces a decision, write a `decision` page; throw the chat away.
-- **Not for drafts of code.** If it would be a comment, it's a comment.
-
----
+Code docs (they go next to the code) · tasks (`tasks.md`) · plans (`features/`) ·
+chat logs · session notes · changelogs.
 
-## Source of truth
+## Checked by `zeno check`
 
-`.context/wiki/` is the canonical knowledge base, and every page in it follows
-the schema above — there are no plan-shaped exceptions. What is *next* lives in
-`.context/features/`, and the ordered queue lives in `.context/tasks.md`; the
-wiki describes what is, not what is planned. The repo root holds no
-product-knowledge `.md` files.
+`wiki-frontmatter` (last-verified, placeholders, stale > 90 days) · `context-size`
+(caps, dated decision names, no `flows/`) · `canonical-values` (a
+price in a decision or screen note is held by an entity) · `sources`.