# Front Office

Design-ops system of record for projects built in conversation with AI: **decision logs, open questions, and docs as generated views** — so every session (human or AI, today or months from now, parallel or sequential) works from the same brain instead of chat scrollback.

Born from a real problem: designing a game across long AI sessions produced 46 logged decisions, and "was that ever actually approved?" kept needing an audit. Front Office makes the audit trail the primary artifact.

## Core ideas

- **The decision log is an event log.** Every decision carries *when / who / why*, a **provenance tag** — `[A]` explicit human ruling · `[A→C]` human direction, AI spec · `[C→A]` AI proposal, human ratified · `[C]` AI-assumed, standing but vetoable — and a status (✅ decided · 🕐 doc-pending · 💬 proposed). Corrections are new entries referencing old ones, never edits.
- **Open questions are records, not scrollback.** Unanswered items live in a tracked file until resolved — with a log entry.
- **Docs are builds.** Context packs and status views are generated from the records; markdown is the storage *and* the interchange format, so there is no lock-in — the files are useful with no tooling at all.
- **The rider guard.** A proposal attached to an approved decision never inherits that approval. Drafts written by AI are *always* 💬.

## Use

```bash
npm ci
npm run fo -- status                 # counts, unratified [C] list, pending rulings
npm run fo -- decisions --provenance C --status decided
npm run fo -- open --section A
npm run fo -- show 12
npm run fo -- pack                   # writes projects/<p>/context-pack.md
npm run fo -- validate               # CI-able: exit 1 on invariant violations
```

Project data lives in `projects/<name>/` containing `*decision-log.md` and `*open-items.md` (see `test/fixtures/` for the format). **`projects/` is gitignored — tenant data is yours and stays private.** Point elsewhere with `--project <dir>` or `FO_PROJECT_DIR`.

## Web UI

```bash
npm run fo -- pack   # optional: regenerate views first
npm run web          # http://localhost:4747 (FO_PORT / FO_PROJECT_DIR to override)
```

Live dashboard over the same files: decision feed with provenance/status chips and filters, attention strip (pending rulings, unratified [C]), open items by section, stats — and a draft form (drafts are always 💬). **100% UI/logic separation:** the client contains zero business logic; every derived value arrives precomputed from `/api/state`, the browser only renders and sends commands.

## MCP server (the brains hookup)

Expose the records to any Claude Code session:

```bash
claude mcp add front-office --scope user -- npx tsx <repo>/src/mcp/server.ts
```

Tools: `get_context_pack` · `list_decisions` · `list_open_items` · `draft_decision` (always 💬) · `get_stats`. Set `FO_PROJECT_DIR` in the server env to select the project.

## Architecture

Per the project's own doctrine (yes, its design decisions are tracked in a Front Office log):

- `src/core`, `src/adapters`, `src/views` — **pure** (strict functional ESLint profile: no let/loops/classes/mutation, clocks and randomness must be injected).
- `src/shell`, `src/mcp` — the effects edge (moderate profile).
- Parsers keep raw cells verbatim → serialization round-trips exactly (`parse(serialize(parse(x))) ≡ parse(x)`, property-tested).

```bash
npm run typecheck && npm run lint && npm test
```

MIT.