@johanesimm/fundamentum 0.1.0

package/blueprint/phases/foundation.md

@@ -0,0 +1,78 @@
+# Phase 1 — Product Foundation (docs/foundation/00–08)
+
+> Extension of `blueprint`. Read and follow this file when the
+> orchestrator reaches the foundation phase. Interview-driven — never
+> invents product facts.
+
+Produce nine documents in dependency order. Each is written only after
+its interview round; **every product fact comes from the user**.
+Recommended defaults are allowed for structure, never for domain
+content.
+
+## Documents & what to grill for each
+
+Work strictly in order — later docs consume earlier ones:
+
+1.  **00-Product-Vision** — vision/mission; the 2–3 questions the
+    product answers; product philosophy principles; personas (+ future
+    personas); core capability domains; MVP in/out-of-scope lists;
+    success criteria; explicit non-goals ("the product is NOT…").
+    *Grill:* purpose, who suffers today and how, what stays manual,
+    what is explicitly refused.
+2.  **01-Product-Principles** — ~10 stable product principles + UX and
+    engineering principle lists; note that principles change only via
+    explicit product decisions. *Grill:* trade-off stances (e.g.
+    standardization vs flexibility, simplicity vs power); at least one
+    quantified UX target if possible.
+3.  **02-Product-Glossary** — THE authoritative terminology table;
+    controlled vocabularies (statuses, categories) enumerated in full;
+    naming rules ("use X never Y"); governance line (changes require a
+    product decision). *Grill:* every ambiguous noun surfaced in 00;
+    exact status lists.
+4.  **03-Domain-Model** — entity tree, per-entity rules, relationship
+    table with cardinalities, business rules, design rationale, and an
+    honest **Open Questions** section (allowed here — foundation docs
+    may carry open questions; they get resolved in the PRDs).
+    *Grill:* containment chains, what is immutable, lifecycle
+    endpoints (can X be reopened?).
+5.  **04-Organization-Model** — org hierarchy vs work assignment
+    (keep them independent unless the user says otherwise), role
+    responsibilities with Can/Cannot lists, coarse permission scopes.
+    *Grill:* who approves what; one-or-many leads; matrix org needs.
+6.  **05-Information-Architecture** — global navigation tree, module
+    definitions, per-role default landing + primary navigation,
+    navigation rules (hidden modules not rendered), MVP vs future
+    navigation, design principles (three-click rule, action-first).
+    *Grill:* what each role sees first thing in the morning.
+7.  **06-User-Journeys** — one end-to-end journey per persona (use
+    the product's natural cadence, e.g. weekly Monday/Friday), AI
+    touchpoints table if AI exists, notifications-per-role list,
+    exception flows, success criteria. *Grill:* the unhappy paths
+    (rejection, escalation, completion).
+8.  **07-AI-Strategy** — only if the product has AI: capabilities
+    matrix (MVP vs future), context sources, guardrails (recommends-
+    only, no business writes, human approval model), what is
+    deliberately deferred to engineering. *Grill:* what AI must never
+    do.
+9.  **08-MVP-Roadmap** — capability phases (not dates), per-phase
+    deliverables + exit criteria, MoSCoW prioritization, dependency
+    graph, MVP success criteria, risk table, and a closing "Transition
+    to Master PRD" section. *Grill:* the smallest release that would
+    actually be used; what can wait.
+
+## Conventions (mandatory)
+
+-   Header blockquote (`Document ID`, `Status: Draft v0.1`,
+    `Depends On`), Documentation Roadmap status table, `---`
+    separators.
+-   Glossary discipline from doc 02 onward: one name per concept,
+    everywhere.
+-   After EACH document: update PROJECT_STATE.md (milestone),
+    CHANGELOG.md, ROADMAP/README status markers.
+
+## Done when
+
+All nine exist, cross-reference cleanly (no term used that 02 doesn't
+define; no feature in 08 absent from 00's scope), open questions are
+consolidated in 03/04, and PROJECT_STATE points at the architecture
+phase (`phases/architecture.md`).

package/blueprint/phases/planning.md

@@ -0,0 +1,95 @@
+# Phase 5 — Development Plan (docs/planning/)
+
+> Extension of `blueprint`. Read and follow this file when the
+> orchestrator reaches the planning phase — the final documentation
+> step. Requires PRDs and engineering specs.
+
+This plan turns the specs into a **priority-ordered, dependency-
+sequenced build order** with verifiable gates. It contains no new
+decisions — only sequencing (confirm the priority cut with the user if
+the product has any unusual emphasis).
+
+## Files to produce
+
+**`00-Development-Plan-Overview.md`** containing:
+
+-   Phase index table: number, file, one-line scope, priority
+    (P1 = irreducible core → P3 = observability/shipping), depends-on,
+    mapping to the product roadmap (08)
+-   Rationale for the priority cut (P1 = the product's primary
+    workflow end-to-end; P2 = what makes it decision-grade; P3 =
+    measurable + shippable)
+-   Working agreements: specs are authoritative (changes go through
+    docs first); checklist discipline; tracking via PROJECT_STATE/
+    CHANGELOG; a **Definition of Done** for every deliverable — adapt
+    its clauses to the project (the web default: implements its cited
+    requirements with server-side guards, emits its events/activities
+    transactionally, covered by its spec's verification, runs in the dev
+    environment; a library/CLI instead: public API stable, invariants
+    enforced, tests green, usable from a clean install)
+-   **Out of Plan** list — everything the Master PRD defers, stated as
+    "do not build"
+
+**One file per phase** (typically 6–9 phases). Derive the sequence
+from the roadmap dependency graph. The canonical shape below is a
+**web-product example** — keep the ordering principle (irreducible core
+first, hardening/shipping last) but replace the middle phases with the
+project's real building blocks (a CLI has commands/config/output; a
+library has core API/edge-cases/docs; a pipeline has ingest/transform/
+sink):
+
+1.  Foundation — scaffold, dev environment, persistence/migration (if
+    any), auth, core plumbing, app shell (always P1, always first)
+2.  Organization/administration — users, org entities, assignments
+    (if the product has them)
+3.  Core domain module(s) — the "what are we managing" layer
+4.  Primary workflow — the product's main loop end-to-end + its jobs
+    (always P1; the MVP is meaningless without it)
+5.  Delivery channels (email/integrations, if any)
+6.  Intelligence/AI (against a stub provider first, if any)
+7.  Analytics/reporting (if any)
+8.  Hardening & release — full acceptance-criteria sweep, performance
+    budgets, production packaging/publishing, bootstrap rehearsal
+    (always last)
+
+Each phase file:
+
+-   Header: goal (one paragraph), priority, depends-on, the spec
+    sections it implements
+-   **Deliverables as checkboxes**, grouped by the project's real tiers
+    (e.g. backend / worker / frontend, or core / CLI / docs), each
+    citing its requirement IDs
+-   **Cross-phase seams made explicit**: if a guard or view needs data
+    from a later phase, ship it as a stub now and name the phase that
+    wires it (never silently defer)
+-   **Exit criteria**: numbered, verifiable, mapped to PRD acceptance
+    scenarios — a phase is done when these pass, not when the boxes
+    are ticked
+
+## Wire it into the primer file
+
+Add/replace the **Implementation Guide** section of the project's
+agent-context (primer) file — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or
+whichever the `primer` skill resolves for the user's tool: trigger
+condition; "no decisions remain open — do not invent behavior; if a
+spec doesn't answer, stop and update the spec first"; the phase list
+with the rule that a phase starts only when the previous exit criteria
+pass; a "which spec answers what" map; the non-negotiables (server-side
+transactional guards, transactional event emission, immutable tables,
+AI isolation, no dev bypasses, the do-not-build list). Generate the
+primer file itself with the `primer` skill (it asks which tool/file and
+reuses everything above as interview input).
+
+## Validation & bookkeeping
+
+Cross-check every requirement ID cited in planning files against the
+PRDs (same comm/grep as the engineering phase). Update PROJECT_STATE
+(current milestone = Dev Phase 1), CHANGELOG, README (add the planning
+section), ROADMAP (documentation ✅, implementation 🚧 Next).
+
+## Done when
+
+Overview + all phase files exist with clean ID cross-checks, the primer
+file guides a fresh session from zero to "start Phase 1", and the state
+files agree. The documentation pipeline is complete — implementation
+begins.

package/blueprint/phases/prd.md

@@ -0,0 +1,97 @@
+# Phase 3 — PRDs (docs/prd/): Master PRD 10 + Feature PRDs 11+
+
+> Extension of `blueprint`. Read and follow this file when the
+> orchestrator reaches the PRD phase. Enforces the fully-decided rule
+> (zero open questions in Feature PRDs) and grills the user on every
+> product decision instead of parking it.
+
+Requires foundation (00–08) and architecture (09.x) to exist — read
+them first and mine them for **gaps, ambiguities, and inconsistencies**
+(undefined metrics, conflicting scope statements, terms used but not
+defined, thresholds referenced but never quantified). Those gaps are
+your interview agenda: **every one becomes a question to the user,
+then a decision in the PRD. Nothing is parked.**
+
+## Part 1 — Master PRD (10)
+
+Recommend the **comprehensive** model (confirm with the user): the
+Master PRD owns all cross-cutting requirements; Feature PRDs inherit
+and never restate.
+
+Build chapter by chapter in `docs/prd/10-chapters/10.NN-<name>.md`,
+then merge (header + concatenation) into `docs/prd/10-Master-PRD.md`:
+
+1.  **Executive Summary** — product, problem, solution, MVP in one
+    paragraph, this document's role
+2.  **Goals & Success Metrics** — foundation criteria made measurable
+3.  **Personas & Roles** — persona → role → landing/workspace binding
+4.  **Scope** — MVP in/out per module; a numbered **Scope Decisions**
+    table resolving every foundation ambiguity (SD-1, SD-2, …)
+5.  **Cross-Cutting Requirements** — the heart. Define the
+    requirement-ID convention (recommend module-prefixed:
+    `<MOD>-NNN` + a cross-cutting prefix), then themed ID blocks:
+    core workflow mechanics, permission matrix (role × capability ×
+    scope), notification matrix (event × recipient × channel),
+    controlled-vocabulary gaps (add missing ones to the glossary as a
+    recorded product decision), metric/threshold definitions with
+    formulas, event catalog (extending 09.E), AI guardrails as
+    requirements, general terminology/navigation rules
+6.  **Feature PRD Index** — one Feature PRD per architecture module
+    (09.C), each with scope paragraph, owned ID prefix, dependency
+    order, and the **template obligations** list (§ below)
+7.  **Non-Functional Requirements** — security, performance,
+    reliability, usability, AI quality — numbered in the cross-cutting
+    scheme
+8.  **Open Questions & Deferred Items** — the ONLY place unresolved
+    questions may live in the whole documentation set: inherited
+    foundation questions (OQ-n), deliberate deferrals (DF-n), and
+    foundational defaults awaiting confirmation (convert to
+    "Confirmed" with date once the user ratifies them)
+9.  **Traceability** — chapter → sources → consumers; ID block →
+    consuming PRDs; amendments this PRD makes to upstream docs
+
+## Part 2 — Feature PRDs (11+)
+
+One per architecture module, in dependency order. **Do not start a
+PRD until the previous one is fully decided.** Per PRD, sections in
+order:
+
+1. Metadata header + status table
+2. Purpose & module boundary (cite 09.C/09.F data ownership)
+3. Personas & permissions (reference the master matrix; deltas only)
+4. Structural Decisions table (SD-NN.n) — the decisions this PRD's
+   interview produced
+5. Functional requirements, `<PREFIX>-NNN`, themed blocks, each
+   testable
+6. Business rules — inherited (cited) + new (BR-NN.n, flagged as
+   product decisions)
+7. Workflows traceable to the user journeys
+8. Events emitted (subset of the master catalog; new events =
+   Master-PRD amendment, applied immediately)
+9. Notifications consumed (subset of the master matrix)
+10. Acceptance criteria — concrete numbered scenarios
+11. **Out of Scope (definitive)** — "This PRD is fully decided; it
+    contains no open questions." Future items reference the Master
+    PRD deferred registry. NEVER an "Open Questions" section; avoid
+    the word "Pending" in status tables (use "⏳ Planned").
+
+## Working loop per PRD
+
+1. Read the relevant foundation/architecture/master material; list
+   the genuine product decisions the docs don't settle.
+2. Grill the user (AskUserQuestion, recommended option first).
+3. Write the PRD fully decided.
+4. Apply ripple effects immediately: glossary/domain-model amendments
+   (marked as product decisions), Master-PRD catalog/matrix
+   amendments, merged-file regeneration.
+5. Validate: `grep` for duplicate/dangling requirement IDs, unresolved
+   language, banned terms.
+6. Bookkeeping: PROJECT_STATE (next milestone), CHANGELOG (decisions
+   recorded individually), ROADMAP/README markers.
+
+## Done when
+
+Master PRD + all module PRDs exist, validation greps are clean
+everywhere, every foundation open question is either decided in a PRD
+or explicitly registered in Master PRD chapter 8, and PROJECT_STATE
+points at engineering (`phases/engineering.md`).

package/excavate/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: excavate
+description: Retro-document an EXISTING codebase — survey the real code and database, then drive a reduced documentation pipeline (foundation → prd → data/API engineering → planning) that captures what the system already does and why. Use when the user wants to document, backfill docs for, or "reverse-engineer" an existing/brownfield project, or asks for vision/domain/glossary, PRDs, an ERD/schema/API reference, or a forward dev plan for a codebase that already exists. Reads the code as the source of truth; interviews the user only to fill product-intent gaps. Skips architecture and backend/frontend build-specs (the code already embodies those).
+---
+
+# Documented Project (existing codebase) — orchestrator
+
+You are documenting a project that **already has code**. Unlike a
+greenfield init, most technical facts already exist — your job is to
+**read them out of the code and database**, then interview the user
+**only for product intent the code cannot reveal** (vision, non-goals,
+business rationale, intended rules, canonical terminology). This is the
+brownfield sibling of `blueprint`.
+
+Reduced pipeline (architecture and backend/frontend build-specs are
+deliberately skipped — the code is the authority for those):
+
+```
+foundation (00-08) → PRDs (10-16) → data/API engineering (20-22)
+→ planning (remaining work)
+```
+
+Each phase is a bundled instruction file in `phases/`; read the
+relevant `phases/*.md` file and follow it. **Never invent behavior the
+code doesn't have** — when code and stated intent disagree, surface the
+discrepancy, don't paper over it. If the user asks for just one phase,
+jump to that file (each states its prerequisites).
+
+## Golden rule: code is the source of truth
+
+For anything observable in the repo — entities, modules, routes, DB
+tables, enums, current behavior — **derive it from the code, do not ask
+the user to recite it.** Interview only for what the code cannot tell
+you: *why* it exists, what it deliberately does NOT do, which behaviors
+are intended vs accidental, canonical names, and locked business rules.
+Every documented fact is either (a) read from the code, or (b) a
+product-intent answer from the user — never a guess.
+
+## Step 1 — Survey the codebase (always first)
+
+Before any interview, spend real effort mapping the repo. Produce a
+short internal survey (you'll reuse it in every phase):
+
+-   **Stack & shape**: languages, frameworks, package manifests, how it
+    runs (compose files, entrypoints, workers, jobs).
+-   **Modules / features**: top-level code boundaries (folders,
+    packages) — these become the Feature-PRD and data-ownership units.
+-   **Domain entities**: models/schemas/ORM classes/migrations → the
+    noun list and their relationships.
+-   **Database**: locate migrations/schema; identify the live/dev DB so
+    the engineering phase can introspect it.
+-   **API surface**: route definitions → endpoints, methods, auth.
+-   **Terminology & enums**: status/enum values and names actually used
+    in code (the glossary must match these).
+-   **Existing docs**: any README/docs already present — reconcile, do
+    not duplicate.
+
+Present a 5–8 line summary of what you found and the **gaps only the
+user can fill** (intent, non-goals, rules, canonical names). That gap
+list is your interview agenda.
+
+## Step 2 — Interview (product intent only)
+
+Ask (AskUserQuestion, batched) about what the code can't show: product
+name + one-sentence purpose; what it explicitly is NOT; target users /
+roles and who they map to in the code; which observed behaviors are
+intended vs legacy/accidental; locked business rules; canonical
+terminology where the code is inconsistent; and how far they want to go
+now (full reduced pipeline vs one phase). Do not re-ask anything the
+survey already answered.
+
+## Step 3 — Scaffold `./docs/`
+
+Create the four state files (small, from the survey + answers). Mark
+them clearly as documenting an **existing** system:
+
+-   `docs/README.md` — documentation index listing the phases below
+    with status markers (✅ / 🚧 Next / ⏳ Planned)
+-   `docs/PROJECT_STATE.md` — Project, Current Phase, Current Milestone,
+    Completed, Next Tasks, Locked Decisions (seed with decisions
+    already evident in code), Conversation Resume Prompt
+-   `docs/ROADMAP.md` — phase table + "Repository Rule: update
+    PROJECT_STATE.md and CHANGELOG.md after completing a major document"
+-   `docs/CHANGELOG.md` — `## v0.1` scaffold entry noting this documents
+    a pre-existing codebase as of today, + the record-all-decisions
+    policy line
+
+Create empty dirs: `docs/foundation`, `docs/prd`, `docs/engineering`,
+`docs/planning`. (No `docs/architecture` — that phase is skipped.)
+
+## Step 4 — Drive the phases
+
+Work through these in order, one at a time, finishing each before the
+next. For each, **read the phase file and follow it to completion**:
+
+| Order | Phase file | Produces |
+|---|---|---|
+| 1 | `phases/foundation.md` | foundation/00–08 (derived + intent-confirmed) |
+| 2 | `phases/prd.md` | prd/10-Master-PRD + Feature PRDs 11+ (as-built, fully decided) |
+| 3 | `phases/engineering.md` | engineering/20-ERD, 21-Database-Schema, 22-REST-API (introspected from the real code + DB) |
+| 4 | `phases/planning.md` | planning/ forward plan for remaining/desired work |
+
+Each phase file ends with a "Done when" gate and a pointer to the next
+file — do not advance until the gate passes.
+
+## House conventions (enforced by every phase file; you enforce them
+too when reviewing output)
+
+1.  **Code first, intent second**: observable facts come from the code;
+    the user is interviewed only for intent, rationale, and non-goals.
+2.  **Surface discrepancies**: when the code contradicts stated intent
+    or is internally inconsistent, record it explicitly (a "Known
+    Discrepancies" note) rather than choosing silently.
+3.  **Doc format**: header blockquote (`Document ID`, `Status: Draft
+    vX.Y`, `Depends On`), a Documentation Roadmap status table, `---`
+    separators between sections.
+4.  **Numbering**: 00–08 foundation, 10 Master PRD, 11+ Feature PRDs,
+    20–22 engineering. IDs never reused. (09.x architecture and 23–25
+    build/deploy specs are intentionally absent.)
+5.  **Single source of truth**: reference authoritative docs, never
+    duplicate them; the glossary owns terminology (and must match the
+    code's actual names).
+6.  **Fully-decided rule** (PRDs onward): no "Open Questions" / "TBD" in
+    Feature PRDs or engineering specs — resolve every question with the
+    user (or by reading the code) before finishing. The Master PRD's
+    deferred-registry chapter is the ONLY place unresolved future
+    questions may live.
+7.  **Bookkeeping after every major document**: update PROJECT_STATE.md,
+    CHANGELOG.md, README.md and ROADMAP.md status markers.
+8.  **Validate against reality**: the engineering phase introspects and
+    checks docs against the actual running database and route table —
+    a schema/API doc that doesn't match the code is not done.
+
+## Exit
+
+When the four phases are complete, generate the project's agent-context
+(primer) file with the `primer` skill — it asks which agentic coding
+tool the user uses and writes the correctly-named file (`CLAUDE.md`,
+`AGENTS.md`, `GEMINI.md`, …) or skips if they use none, reusing the
+survey + docs above as interview input. Then hand over to implementation
+of the planned remaining work.

package/excavate/phases/engineering.md

@@ -0,0 +1,96 @@
+# Phase 3 — Engineering Reference (docs/engineering/20–22), introspected
+
+> Extension of `excavate`. Read and follow this file when
+> the orchestrator reaches the engineering phase. Generate the data +
+> API reference FROM the real code and database — do not design.
+
+Requires fully-decided PRDs. This phase produces up to three
+**reference** documents that describe the system's data and contract as
+it actually is: **20-ERD, 21-Database-Schema, 22-REST-API**. The
+backend/frontend build-specs (23/24) and deployment guide (25) are
+intentionally skipped — for an existing project the code and its
+deploy config are the authority, and re-specifying them adds no value.
+
+**Produce only the docs the project actually has.** The trio below
+assumes a service with a relational database and an HTTP API — the
+common case, not a universal one. Adapt:
+
+-   **No datastore** (CLI, stateless service, library) → skip 20 and 21.
+-   **Non-relational store** → keep 20/21 but document the real model
+    (collections/keys/documents, or the KV/graph shape) in that store's
+    terms instead of an ER diagram + DDL.
+-   **Non-HTTP interface** → retitle 22 to the real surface
+    (**22-CLI-Interface**, **22-Public-API** for a library, **22-API**
+    for gRPC/GraphQL) and document that contract as-built.
+
+Note any skipped/retitled doc in 20 (or the umbrella) so the omission is
+explicit. Everything here is **introspected, then verified against
+reality** — not invented. Every requirement ID cited must already exist
+in the PRDs; run the cross-check grep after each document:
+
+```
+comm -13 <(cat docs/prd/*.md | grep -oE '<ID-REGEX>' | sort -u) \
+         <(grep -oE '<ID-REGEX>' <spec>.md | sort -u)
+```
+
+## 20-ERD (or data-model reference)
+
+Reconstruct the data model **from the actual migrations / ORM models /
+live schema**, not from a redesign. For a non-relational store, describe
+the real collections/documents/keys and their relationships instead of
+an ER diagram. Include: a conventions
+table describing the patterns the code already follows (PK strategy,
+naming, timestamps, enum policy, deletion policy, immutability as
+implemented); entity overview by owning module (mirror the code's
+module boundaries); a mermaid `erDiagram` matching the real tables and
+foreign keys; entity notes for **non-obvious existing choices only**,
+each tied to a requirement ID or flagged as an unexplained artifact; a
+table of referential-integrity rules the schema actually enforces vs
+those enforced in the service layer. Where the model diverges from
+what the PRDs describe, record it in **Known Discrepancies**.
+
+## 21-Database-Schema
+
+The **authoritative current schema**, captured from the real database
+— not a fresh design. Prefer introspecting the live/dev database
+(`pg_dump --schema-only` or the equivalent) and/or consolidating the
+migrations, then present the DDL grouped by module with the existing
+constraints, indexes, triggers, and enum types, citing requirement IDs
+in comments where a constraint enforces a PRD rule.
+
+**MANDATORY when there is a database: verify the doc against the real
+store.** Point at the existing dev/live database (or spin the migrations
+up in a throwaway instance), diff the documented schema against the
+introspected one, and reconcile until they match — field for field. A
+schema doc that doesn't match the running store is not done. Record any
+migration-vs-store drift you find as a Known Discrepancy (do not
+silently "fix" it in the doc).
+
+## 22-REST-API (or the project's real interface)
+
+The **actual contract**, read from the code — route definitions for an
+HTTP API, command/flag definitions for a CLI, exported signatures for a
+library. Start with conventions the code already uses (for HTTP: base
+path/versioning, auth, response/error envelope, status codes — including
+how business-rule violations are signalled today, e.g. 409 vs 400).
+Then per-module operation tables (method/path/roles/behavior for HTTP,
+or command/args/output, or function/params/returns) generated from the
+real code, each row referencing the PRD requirement it satisfies. Include
+a guard-code / error-code registry **if the code has one** (map each
+code → PRD rule → endpoints); if error signalling is inconsistent,
+document it as-is and flag it. Note the cross-cutting behaviors that
+actually exist (event emission, async patterns, pagination).
+
+Endpoints with no corresponding PRD requirement, and PRD requirements
+with no endpoint, both get listed explicitly — that gap list feeds the
+planning phase.
+
+## Bookkeeping & done
+
+After each doc: cross-check grep, PROJECT_STATE, CHANGELOG (record
+notable discrepancies found), ROADMAP/README markers. Done when every
+applicable doc in 20–22 exists (skipped/retitled ones noted), any schema
+doc has been verified against the real store, the interface doc matches
+the real code, all reference greps are clean, every code-vs-doc
+discrepancy is recorded, and PROJECT_STATE points at planning
+(`phases/planning.md`).

package/excavate/phases/foundation.md

@@ -0,0 +1,75 @@
+# Phase 1 — Product Foundation (docs/foundation/00–08), as-built
+
+> Extension of `excavate`. Read and follow this file when
+> the orchestrator reaches the foundation phase. Derive structure from
+> the code; interview only for product intent.
+
+Produce nine foundation documents in dependency order. For an existing
+codebase, **the domain-shaped docs are read out of the code and merely
+confirmed with the user; the intent-shaped docs come from the user.**
+Never invent product facts.
+
+## Where each document's content comes from
+
+Split every doc into what the **code already tells you** (write it,
+then confirm) vs what only the **user knows** (grill for it):
+
+1.  **00-Product-Vision** — *user:* vision/mission, the questions the
+    product answers, philosophy, personas, explicit non-goals ("is
+    NOT…"). *Code:* the capability domains actually implemented (list
+    them from the modules). *Grill:* purpose, who it's for, what it
+    deliberately refuses — none of which is in the code.
+2.  **01-Product-Principles** — *user:* the stable product/UX/eng
+    principles and trade-off stances. *Code:* infer candidate
+    principles from recurring patterns and propose them for
+    confirmation; never assert intent from a pattern that may be
+    incidental.
+3.  **02-Product-Glossary** — THE authoritative terminology table.
+    *Code:* enumerate the real nouns, statuses, enum values, and
+    role names as they appear in code — the glossary MUST match them.
+    *Grill:* where the code is inconsistent (two names for one
+    concept), ask the canonical choice and record the alias as a
+    known discrepancy.
+4.  **03-Domain-Model** — *Code:* entity tree, per-entity fields,
+    relationships with cardinalities read from models/migrations;
+    render the real structure. *User:* which rules are intended vs
+    accidental, what is immutable by design, lifecycle intent. Keep an
+    honest **Open Questions / Known Discrepancies** section.
+5.  **04-Organization-Model** — *Code:* the roles/permissions actually
+    enforced. *User:* the intended org hierarchy vs work assignment,
+    role responsibilities (Can/Cannot), who approves what.
+6.  **05-Information-Architecture** — *Code:* the real navigation tree,
+    modules, and per-role routes/landing pages from the frontend.
+    *User:* the design intent (three-click/action-first) and any
+    gap between current and desired navigation.
+7.  **06-User-Journeys** — *Code:* the flows that actually exist
+    (routes + handlers). *User:* the intended end-to-end journey per
+    persona, the unhappy paths, and which existing flows are intended.
+8.  **07-AI-Strategy** — only if the codebase has AI: *Code:* what the
+    AI integration actually does, its inputs, and existing guardrails.
+    *User:* what it must never do; intended vs current guardrails.
+9.  **08-MVP-Roadmap** — reframed as **current-state + gap**: what is
+    already shipped (from the code), what is partial, and what the user
+    still wants — a capability map of built vs remaining (this feeds the
+    planning phase). *Grill:* which unbuilt capabilities matter next.
+
+## Conventions (mandatory)
+
+-   Header blockquote (`Document ID`, `Status: Draft v0.1`,
+    `Depends On`), Documentation Roadmap status table, `---`
+    separators.
+-   Glossary discipline from doc 02 onward: one name per concept, and
+    that name must be the one the code uses (or the recorded canonical
+    choice).
+-   Any code-vs-intent mismatch goes in a **Known Discrepancies** note,
+    never silently resolved.
+-   After EACH document: update PROJECT_STATE.md, CHANGELOG.md,
+    ROADMAP/README status markers.
+
+## Done when
+
+All nine exist, the domain-shaped docs (02/03/04/05) faithfully match
+the code, intent-shaped docs (00/01/06/07) are user-confirmed,
+discrepancies are recorded, and PROJECT_STATE points at the PRD phase
+(`phases/prd.md`). Architecture (09.x) is intentionally skipped — the
+PRDs cite the code and data-ownership directly.