whodecided AGENTS.md

AGENTS.md

Guidance for AI agents and contributors working on whodecided itself.

What this is

A thin TypeScript CLI that distills the decisions an AI coding agent (and you) made inside Claude Code / Codex sessions into an append-only, ratifiable ledger, then feeds ratified precedent back to agents. "Common law for agentic coding."

The product is: a schema + a discardable CLI + a .wdd/ directory of plain text inside the user's repo. git, claude -p/codex exec, and the browser are shelled out. The tool holds no state of its own.

Build / test / run

npm run build      # tsc → dist/
npm test           # vitest (unit tests live next to sources as *.test.ts)
node dist/cli.js --help

• Node ≥ 20, ESM ("type": "module" → import paths use .js).
• Single runtime dependency: yaml. Do not add more; argv parsing and everything else is stdlib.
• dist/ and planning/ are gitignored. Design docs (SPEC.md, REVIEW-SPEC.md, CROSS-REVIEW.md) live in planning/ — read them for the full rationale; they are not published.

Architecture

Read-only pipeline with exactly two write points (distill → ledger, ratify → ledger):

cli.ts → commands/*            command routing + orchestration
  transcript/  locate + parse  CC (~/.claude/projects) and Codex (~/.codex/sessions rollouts) → SessionEvent[]
  extract/     candidates      deterministic decision candidates + aware heuristics (NO LLM)
  distill/     detect + distiller   auto-detect claude/codex (config wins, sessions vote) → subprocess → LedgerEntry[] (schema-validated, retry, degrade)
  ledger/      schema + io      append-only jsonl read/write; verdictOf/isPinned/noteOf
  patch/       apply            THE single write path: validate → append ratify lines → (opt) commit
  ledger/      evidence         persisted (redacted) transcript excerpt per decision, keyed by ref
  extract/     redact           mask secrets before a slice reaches the distiller or evidence
  checks/      gate diff-signals risk supersede coverage   pure triage signals over ledger/diff/traces
  commands/    signals          assembles branch diff + per-decision signals for review/board/report
  render/      term/md/html     terminal docket / PR markdown / single-file workbench (Timeline + Threads tabs, keyboard review, change map, per-decision diff, triage)
  config.ts git.ts jsonl.ts validate.ts   infra (git.ts: branchDiff/churn/productFiles)