core/bible-local/governance/documentation-policy.md

Documentation Policy

Purpose

This policy defines how architectural knowledge is captured and maintained.

Mandatory Rules

• Record every architecture decision in the Bible before or together with implementation.
• Use English for all architecture documentation.
• External integration handoff documents may use the consumer language when needed, but they must be explicitly marked as external-facing.
• Keep only current architecture in active sections.
• When a solution is replaced, update or remove obsolete guidance in the same change.
• Keep shared rules in bible/ and project-specific architecture in bible-local/; other top-level docs should only reference them.

Change Workflow

1. Update the relevant file(s) in bible-local/architecture/ or bible-local/docs/.
2. If behavior changed or documentation policy changed, add or update a decision note in bible-local/decisions/.
3. Remove duplicated or outdated statements from non-Bible docs.
4. Validate consistency against code paths in internal/api, internal/ingest, and internal/repository.

Hardware Ingest Contract

bible-local/docs/hardware-ingest-contract.md is a distributable integration document for external teams.

Mandatory: any change to the hardware JSON import contract (HardwareIngestRequest, HardwareSnapshot, or any nested struct in internal/ingest/parser_hardware.go) must be reflected in hardware-ingest-contract.md in the same commit:

• Bump the version field in the YAML front matter (patch for additive/optional fields, minor for new sections, major for breaking changes).
• Update the updated date.
• Add a row to the Changelog table describing what changed.