bible/rules/patterns/go-project-bible/contract.md

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:

# 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.