# Contract: Project Bible (bible-local/)

Version: 1.0

## Purpose

`bible-local/` is the single source of truth for everything **specific to this project**:
data model, API surface, business rules, architectural decisions.

Shared engineering rules (CSV, logging, DB, tables, etc.) live in the `bible/` submodule.
Do not duplicate them in `bible-local/`.

## Required Files

Every project bible must have these files:

```
bible-local/
  README.md              — index: what files exist and what each covers
  architecture/
    system-overview.md   — what the product does, active scope, non-goals
    data-model.md        — domain entities, DB tables, naming conventions
    api-surface.md       — all HTTP endpoints with methods and response shape
    runtime-flows.md     — key mutation flows, invariants, critical rules
  decisions/
    README.md            — ADL format explanation
    YYYY-MM-DD-topic.md  — one file per architectural decision
```

Optional (add when relevant):
```
  architecture/
    ui-information-architecture.md  — page structure, navigation, UI invariants
  docs/
    INTEGRATION_GUIDE.md            — external system integration (formats, protocols)
```

## system-overview.md Rules

- List what is **in scope** and what is **explicitly out of scope**.
- Out of scope section prevents scope creep — update it when you reject a feature.
- Include tech stack and local run command.

## data-model.md Rules

- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
- List all DB tables with one-line description of each.
- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
- Migration policy: how migrations are numbered and applied.

## api-surface.md Rules

- Every endpoint: method, path, brief description, key response fields.
- Group by domain area (Registry, Ingest, Timeline, etc.).
- Note any endpoints that are UI-only routes vs JSON API.
- Document pagination, filtering params where non-obvious.

## runtime-flows.md Rules

This is the most important file. Document flows that are **easy to break**:

- Mutation paths (what happens step by step when user does X)
- Event/time source priority rules
- Deduplication logic
- Cross-entity side effects (e.g. removing a component affects asset status)
- Anything that caused a bug or regression — add a "DO NOT reintroduce" note

Format each flow as a numbered list of steps, not prose.

## Architectural Decision Log (ADL)

Write a decision entry when:
- You choose between two non-obvious approaches
- You intentionally reject a feature or pattern
- A bug caused a rule change (e.g. cursor safety)
- You freeze or deprecate something

**Format:**

```markdown
# Decision: <short title>

**Date:** YYYY-MM-DD
**Status:** active | superseded by YYYY-MM-DD-topic.md

## Context
What situation made this decision necessary.

## Decision
What was decided, stated clearly.

## Consequences
What this means going forward. What is now forbidden or required.
```

- One decision per file, named `YYYY-MM-DD-short-topic.md`.
- When a decision is superseded, add `superseded by` to the old file's status — do not delete it.
- Record the decision **in the same commit** as the code that implements it.

## What NOT to Put in bible-local/

- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/`
- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder
- Duplicate of what is already in code (don't restate what the code clearly shows)
- Speculative future architecture — document what exists, not what might exist

## Keeping the Bible Current

- Update `bible-local/` in the **same commit** as the code change it describes.
- If you change a flow, update `runtime-flows.md` in the same PR.
- If a section becomes outdated, fix or delete it — stale docs are worse than no docs.
- Bible files are in **English only**.