astrolabe/CLAUDE.md

# Claude Context — Astrolabe

See @AGENTS.md for project overview, architecture rules, and the AI developer protocol.

## Documentation Index

- **[SOUL.md](SOUL.md)** — project philosophy and identity. _Read first._
- **[docs/spec/](docs/spec/)** — behavioral specification (sections 00–10): the **what**.
  Descriptive, kept current with the code: the code leads; on conflict amend the spec,
  never drift silently. User-facing behavior ships with its spec section.
- **[docs/architecture/](docs/architecture/00-overview.md)** — architecture playbook
  (00–11): the **how** (state, persistence, modals, routing, rendering, inference,
  relationships, vega-editor techniques, visual design, interaction & feedback, learning
  section).
  Self-contained — no external repo needed. Companion:
  **[visual-specimen.html](docs/architecture/visual-specimen.html)** — token sandbox +
  reusable-primitive catalog (open in a browser).
- **[`/council`](.claude/skills/council/SKILL.md)** — the design council: consult external
  interaction/content/a11y canon (Carbon, GOV.UK, WAI-ARIA APG, Nielsen Norman, cloned
  under `reference/`) before a user-facing decision. It advises; our contract (architecture
  09/10) decides. Resolutions are recorded back into the contract.
- **[`/eng-council`](.claude/skills/eng-council/SKILL.md)** — the engineering council:
  evidence-grounded review of codebase structure, consistency, altitude, and subtraction
  (what to delete). Sweep / refactor-review / new-work-review / pre-build-consult modes;
  recurring findings become `docs/architecture/` rules and `/alignment` checks.
- **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone
  plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture
  reference index.
- **[docs/manual-verification.md](docs/manual-verification.md)** — standing QA checklist for
  what tests can't cover (offline/install, keyboard/a11y, theming, reduced-motion).
- **[AGENTS.md](AGENTS.md)** — onboarding, stack, directory map, scripts, conventions.

## Quick Orientation

- Astrolabe is a **spec-recorded rebuild** — the architecture is adapted from Syto, and
  `docs/spec/` records the behavior as built. Build deliberately, record in the spec;
  don't port legacy code.
- **`src/core/` is portable and tested hardest.** Browser specifics live in
  `src/app/infrastructure/`. UI is React + Zustand.
- **Editor is Monaco**, charts render via **vega-embed**, storage is **IndexedDB**.
- Work milestone by milestone (see the plan): core-first, then UI, then tests, then a
  manual smoke check against the spec's acceptance points.

## Conventions

- No git actions unless explicitly invited.
- Run `npm run typecheck` and `npm test` after changes.
- Single-line commit subjects; no Co-Authored-By trailers.

## Session wrap-up protocol

When the user signals the session is wrapping (asks to commit, says it's done/wrapped),
run the review pass **before** anything is committed:

1. **Flush knowledge first — `/doc-update`, in-session.** Capture what this session
   decided or discovered: rationale for non-obvious choices (to `docs/` or a code
   comment at the site, whichever is the right home), spec/architecture gaps, decisions
   made in conversation that never landed in writing. This step cannot be delegated —
   only the session knows what was decided — and it runs first so the clean-context
   reviewers below judge against recorded rationale instead of flagging deliberate
   choices as oversights.
2. **Alignment — clean-context subagent.** Spawn an agent with no session context
   beyond this prompt: "Read `.claude/skills/alignment/SKILL.md` and execute it against
   the current uncommitted/staged diff. Fix directly per the skill, run typecheck and
   tests, and return the skill's summary as your final message." The clean slate is the
   point — the reviewer simulates the future maintainer and must not inherit the
   session's rationalizations.
3. **Eng-council review — clean-context subagent, conditional.** Only when the session's
   diff is structural (a new module or kind-instance, a refactor, a new dependency):
   spawn an agent the same way to execute `.claude/skills/eng-council/SKILL.md` in the
   matching review mode (refactor review / new-functionality review — never the sweep;
   sweeps stay a deliberate act).

Run the subagents **sequentially**, not in parallel — both may edit the working tree.
Relay each report back to the user, then arbitrate each finding to one of three ends —
**accept and fix**, **accept but defer**, or **overrule** — and **write down the two you
don't act on now**, because a subagent's report is ephemeral and chat is not a record. A
deferred finding gets a `// TODO:` at the relevant code site (or a line in the closest doc);
an overruled one records the missing rationale where the reviewer looked. Out of scope for
_this session_ is not out of scope for the _project_: with a single maintainer there is no
"someone else's problem", so an unrecorded deferral or beyond-scope note recurs as work
handed to your future self. Then commit only when invited.