Skip to content

README.md

Latest commit

 

History

History
107 lines (92 loc) · 9.85 KB

README.md

File metadata and controls

107 lines (92 loc) · 9.85 KB
Raw

Doc index

The map of every project document, so nothing gets lost or duplicated. Rules: before writing a new doc, check this index for an existing home; when adding, moving, or retiring a doc, update this index in the same change. Repo-level operating rules live in CLAUDE.md (repo root).

Read order for a fresh session: CLAUDE.md (root), then PROJECT-STATE.md, then GATES.md, then only what the active gate needs.

Ledgers and state

Doc What it is
PROJECT-STATE.md The cache. Current facts: stack, structure, commands, what is built. Start every planning task here.
DECISIONS.md Decision log. Dated, append-only. Settled items are not relitigated without a new entry.
GATES.md Gate ledger. One row per gate: status, evidence, date. One gate active at a time.

Operating

Doc What it is
RUNBOOK.md Install, start, and run a first review. Says which actions spend model usage.
AI-GUIDE.md For an AI session: how the app fits together, where each feature lives, how common changes are made, traps.

Standards

Doc What it is
AI-ANTIPATTERNS.md Catalog of AI tells. Binding on all surfaces: code, docs, copy, commits.

Plans

Doc What it is
plans/APP-PLAN.md The app plan: feasibility verdict, architecture proposal, resolved questions. DRAFT.
plans/BUILD-PLAN.md Work packages WP-A..L, milestones, founder gates, standing rails.
plans/EXECUTION-ORDER.md STANDING EXECUTION ORDER: remaining work T1-T19, dependencies, founder gates, pre-resolved decisions D-1..D-20.
plans/M2-FINISH-PLAN.md Implementation plan for T8, T9 and the FG-2 demo: commit map W1-W8, the resume design, decisions D-21..D-26.
plans/FG2-CHECKLIST.md What the maintainer judges at founder gate FG-2, where the evidence lives, and what each verdict means.
plans/M3-FINISH-PLAN.md Implementation plan for the usable app (T10-T17 remainder plus W8 leftovers): commit map V1-V9, spend-safety and confirmation-loop design, decisions D-30..D-44.
plans/M4-FINISH-PLAN.md The v1 close-out plan from the 2026-08-03 full audit: verified gap inventory, commit map U1-U13, decisions D-45..D-56.
plans/U12-FIXTURE-GAPS.md The four seeded-fixture defects still owed, planned against the live tree and adversarially verified. The driver's working order for the rest of U12.
plans/POST-M4-PLAN.md The driver's plan after M4: land the in-flight sweep fix, close gates G1-G3 with evidence, D-59 dedup, inbox spend-down.
plans/UX-UPLIFT-PLAN.md The 2026-08-17 UX audit (14 findings, screenshots + code inventory), the gamification research and its honest-version design, six maintainer gates, and work packages WP-A..J.
plans/DASHBOARD-SHELL-PLAN.md D-81 executed in detail: the widget dashboard, the top bar, the rail's retirement; work packages M0-M6 with the verified e2e blast radius.
plans/PLAN-TEMPLATE.md Template for multi-step plan docs (work packages, decision gates, done tracking).
plans/idea-inbox.md One-line dated idea capture. Ideas are not expanded until the active gate passes.
plans/AUDIT-2026-10-16-GLM.md The 2026-10-16 audit: gate results on Windows, the unit-failure taxonomy, security findings, open work, and a cross-check against the parallel audit. Read-only report; nothing in it was fixed.
plans/AUDIT-2026-10-16.md The parallel 2026-10-16 audit: finding IDs W, S, E, A, U, T, R, D with proof per finding, and the evidence behind each disagreement with the GLM report. Read-only report.
plans/MVP-PLAN.md The MVP: three-OS support, security, engine fixes, spend safety, Claude connect, then the G1 and G2 verdicts. Seven phases, decision gates MG-1..MG-10. RATIFIED 2026-10-16 (D-86).
plans/PROOF-AND-STEPS-PLAN.md After the MVP: the 5.5 models, proof a finding must carry and a second verifier, and the run shown as five steps. DRAFT 2026-10-22 (D-184), built after the G1 verdict.

Specs

Doc What it is
00-BRIEF.md The app brief: local PR reviewer.
01-ARCHITECTURE.md System architecture: topology, layout, data dir, engine adapter, models, errors. RATIFIED 2026-07-30.
02-DATA-MODEL.md SQLite schema, state machines, invariants, deletion rules. RATIFIED 2026-07-30.
03-REVIEW-PIPELINE.md The engine spec: protocol steps mapped to deterministic code and bounded AI stages. RATIFIED 2026-07-30.
04-UI-DESIGN.md Design language, screens, states, accessibility, design proof gate. RATIFIED 2026-07-30.
05-TESTING.md verify.sh spec, unit/e2e strategy, seeded-bug fixture gate. RATIFIED 2026-07-30.
06-MODELS-AND-PROFILES.md Measured model availability, the probe mechanism, and model-dependent review profiles. RATIFIED 2026-07-30.
docs/private/REVIEW_PROTOCOL.md The maintainer private reference protocol used to seed rulesets. Proprietary, gitignored, NOT part of the public repo.

Where a spec and any other doc disagree, the spec wins; where a spec and reality disagree, reality wins and both get fixed in the same session.

Changelog

  • 2026-07-30: Index created with workspace setup. No app brief yet.
  • 2026-07-30: App brief captured as 00-BRIEF.md; feasibility research on subscription-based review runs in progress.
  • 2026-07-30: Feasibility confirmed; decisions logged; spec set 01-05 and plans/BUILD-PLAN.md drafted; gates G1-G3 defined. All DRAFT pending G0.
  • 2026-07-30: plans/EXECUTION-ORDER.md added: the standing order for all remaining work with pre-resolved decisions, so the driver does not ask between founder gates.
  • 2026-07-30: plans/M2-FINISH-PLAN.md added (commit b7ad7c2): T8, T9 and the FG-2 demo planned to commit level.
  • 2026-07-31: plans/M3-FINISH-PLAN.md added (commit 060f969): the rest of the usable app planned to commit level.
  • 2026-07-31: plans/FG2-CHECKLIST.md added (commit 27d92d7): what the maintainer judges at FG-2 and where the evidence lives.
  • 2026-08-03: plans/M4-FINISH-PLAN.md and RUNBOOK.md added: the full-audit gap inventory with the v1 close-out order, and the operator runbook FG-3 needs. The three entries above were backfilled in the same pass, having been added without changelog lines at the time.
  • 2026-08-03: specs 00 to 06 relabelled from DRAFT to RATIFIED. They record ratification at G0 on 2026-07-30 (GATES.md); only the headers were stale.
  • 2026-08-04: plans/U12-FIXTURE-GAPS.md added: the remaining seeded-fixture work, split out of M4-FINISH-PLAN once it was planned in detail.
  • 2026-08-17: plans/UX-UPLIFT-PLAN.md added: the UX audit, the gamification research and its honest version, and work packages WP-A..N.
  • 2026-08-18: plans/DASHBOARD-SHELL-PLAN.md added: D-81 planned to commit level, M0-M6. Both entries were backfilled here on 2026-08-18, having been added to the table above without changelog lines at the time.
  • 2026-10-16: plans/AUDIT-2026-10-16-GLM.md added: read-only audit report (no code changed). Windows gate results and failure taxonomy, security findings, records staleness, and a claim-by-claim cross-check against the parallel session's audit of the same tree.
  • 2026-10-16: plans/AUDIT-2026-10-16.md added: the parallel session's audit with finding IDs, and its cross-check of the GLM report. plans/MVP-PLAN.md added: the MVP planned against both audits (D-85).
  • 2026-10-22: plans/PROOF-AND-STEPS-PLAN.md added: the maintainer's D-184 asks planned against what exists, built after the G1 verdict.