@freetesh/zeno 0.0.0-stage → 0.8.0

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

@@ -0,0 +1,287 @@
+# Wiki — schema and 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.
+
+**Read this file before creating or editing any page under `.context/wiki/`.**
+
+---
+
+## 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.
+
+---
+
+## 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] }
+```
+
+`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 | Sentry MCP server | 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.
+```
+
+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.
+
+---
+
+## 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).
+
+---
+
+## 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 |
+
+`/zeno:wiki-lint --fix` auto-fixes: filename ↔ id mismatches, missing `last-verified` (sets to today if the page is touched), index regeneration.
+
+---
+
+## What the wiki is 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.
+
+---
+
+## Source of truth
+
+`.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.

package/templates/dependency-cruiser/app.cjs

@@ -0,0 +1,23 @@
+/* global module */
+// This app's architecture rules, enforced by `zeno check` (architecture module).
+// zeno wrote this starter once; it is yours now. Add the layers this app has
+// and keep the why in a wiki concept page.
+// Rule reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  extends: "../../.dependency-cruiser.base.cjs",
+  forbidden: [
+    {
+      name: "no-app-to-app",
+      comment: "An app never imports another app; share code through packages/.",
+      severity: "error",
+      from: {},
+      to: { path: "^\\.\\./[^./]" },
+    },
+  ],
+  options: {
+    // The level `zeno ui` draws the architecture graph at: one box per match.
+    reporterOptions: { archi: { collapsePattern: "^src/[^/]+/[^/]+|^src/[^/]+|^[^/.][^/]*|^\\.\\./\\.\\./packages/[^/]+" } },
+  },
+};

package/templates/dependency-cruiser/base.cjs

@@ -0,0 +1,52 @@
+/* global module, require */
+// Managed by zeno — `zeno sync` rewrites this file from zeno's template, so edits here are lost.
+// Put this repo's own rules in the .dependency-cruiser.cjs files that extend it.
+// Each workspace runs on its own because apps map `@/` to their own src, and
+// dependency-cruiser reads one tsconfig per run.
+
+const { existsSync } = require("node:fs");
+
+// recommended's no-orphans exceptions (dot files, .d.ts, tsconfig, babel/webpack configs),
+// restated because the package does not export its rule files…
+const KNOWN_CONFIG_FILES = [
+  "(^|/)\\.[^/]+\\.(js|cjs|mjs|ts|json)$",
+  "\\.d\\.(c|m)?ts$",
+  "(^|/)tsconfig\\.json$",
+  "(^|/)(?:babel|webpack)\\.config\\.(?:js|cjs|mjs|ts|json)$",
+];
+// …plus files a framework or tool loads by convention, so nothing imports them.
+const ENTRY_POINTS = [
+  "(^|/)src/app/[^.]*(page|layout|route|loading|error|not-found|template|default)\\.tsx?$", // Next.js app router
+  "(^|/)src/pages/[^.]+\\.tsx?$", // Next.js pages router
+  "^src/app/[^.]+\\.tsx?$", // Expo Router: every file under app/ is a route
+  "^src/(instrumentation|middleware)\\.ts$", // Next.js hooks
+  "^(scripts|plugins|eslint|e2e|public)/", // run by a tool, not imported
+  "(^|/)__mocks__/", // jest mocks
+  "^(src/)?index\\.ts$", // a package's entry
+  "(^|/)codegen\\.ts$", // GraphQL codegen script
+];
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  extends: "dependency-cruiser/configs/recommended",
+  forbidden: [
+    {
+      name: "no-orphans",
+      comment: "Nothing imports this file: use it or delete it. Add a real entry point to ENTRY_POINTS instead.",
+      severity: "warn",
+      from: { orphan: true, pathNot: [...KNOWN_CONFIG_FILES, ...ENTRY_POINTS] },
+      to: {},
+    },
+  ],
+  options: {
+    // Record imports into a sibling workspace, but leave cruising it to that workspace's own run.
+    doNotFollow: { path: ["node_modules", "^\\.\\./"] },
+    // Specs and tooling configs are not app code.
+    exclude: { path: "^(dist|build|out|generated|coverage|\\.next|\\.expo|\\.turbo)/|^tests/|\\.(spec|test)\\.tsx?$|(^|/)[^/]+\\.config\\.(c|m)?(j|t)s$|(^|/)\\.dependency-cruiser" },
+    tsPreCompilationDeps: true,
+    // Each run starts in its workspace, so this is that workspace's tsconfig (if it has one).
+    ...(existsSync("tsconfig.json") ? { tsConfig: { fileName: "tsconfig.json" } } : {}),
+    // Packages like uuid 13 export only `node`/`default` conditions.
+    enhancedResolveOptions: { exportsFields: ["exports"], conditionNames: ["import", "require", "node", "default", "types"] },
+  },
+};

package/templates/dependency-cruiser/package.cjs

@@ -0,0 +1,31 @@
+/* global module */
+// This package's architecture rules, enforced by `zeno check` (architecture module).
+// zeno wrote this starter once; it is yours now.
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  extends: "../../.dependency-cruiser.base.cjs",
+  forbidden: [
+    {
+      name: "no-package-to-app",
+      comment: "packages/ are shared; they never depend on an app.",
+      severity: "error",
+      from: {},
+      to: { path: "^\\.\\./\\.\\./apps/" },
+    },
+    {
+      name: "no-orphans",
+      comment: "Off here: apps import a package's files through subpath exports, which a run inside the package cannot see.",
+      severity: "ignore",
+      from: { orphan: true },
+      to: {},
+    },
+    {
+      name: "no-duplicate-dep-types",
+      comment: "Off here: a shared package lists react and friends as both peer and dev dependency on purpose.",
+      severity: "ignore",
+      from: {},
+      to: {},
+    },
+  ],
+};

package/templates/dependency-cruiser/root.cjs

@@ -0,0 +1,15 @@
+/* global module */
+// This repo's architecture rules, enforced by `zeno check` (architecture module).
+// zeno wrote this starter once; it is yours now. Add the layers this product has
+// (see the rule reference below) and keep the why in a wiki concept page.
+// Rule reference: https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  extends: "./.dependency-cruiser.base.cjs",
+  forbidden: [],
+  options: {
+    // The level `zeno ui` draws the architecture graph at: one box per match.
+    reporterOptions: { archi: { collapsePattern: "^src/[^/]+|^[^/]+" } },
+  },
+};