From 33b4b755786e6b37907a3e57de9311ba34de320a Mon Sep 17 00:00:00 2001 From: Mikhail Chusavitin Date: Sun, 15 Mar 2026 16:29:24 +0300 Subject: [PATCH] Consolidate project documentation --- README.md | 13 ++++++++++-- bible-local/README.md | 3 ++- .../2026-03-01-mysql-tx-cursor-safety.md | 2 +- .../2026-03-15-documentation-consolidation.md | 21 +++++++++++++++++++ bible-local/decisions/README.md | 1 + bible-local/docs/README.md | 13 ++++++++++++ bible-local/docs/hardware-ingest-contract.md | 3 ++- .../governance/documentation-policy.md | 7 ++++--- internal/api/ui_ingest.tmpl | 2 +- releases/v0.1.0/RELEASE_NOTES.md | 2 ++ 10 files changed, 58 insertions(+), 9 deletions(-) create mode 100644 bible-local/decisions/2026-03-15-documentation-consolidation.md create mode 100644 bible-local/docs/README.md diff --git a/README.md b/README.md index 32db7fa..af7ae7d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,14 @@ # Reanimator Core -Architecture documentation was moved to the Project Bible: +Project documentation is split into two sources: -- `bible/README.md` +- `bible/` - shared engineering rules and cross-project patterns +- `bible-local/` - this project's current architecture, contracts, and decisions + +Read order for contributors and agents: + +1. `bible/README.md` +2. `bible-local/README.md` +3. `bible-local/architecture/system-overview.md` + +Operational status notes and implementation scratchpads are intentionally not kept as long-lived top-level documentation. diff --git a/bible-local/README.md b/bible-local/README.md index 92b7781..ec96345 100644 --- a/bible-local/README.md +++ b/bible-local/README.md @@ -17,5 +17,6 @@ The Bible is the single source of truth for this project's architecture. - `architecture/runtime-flows.md` - ingest, timeline, status, and failure invariants. - `architecture/ui-information-architecture.md` - required UI structure and semantics. - `architecture/data-model.md` - domain language, core tables, and migration boundaries. -- `docs/` - migrated operational and implementation documentation (formerly `/docs`). +- `docs/README.md` - index of active project documents outside the architecture set. +- `docs/hardware-ingest-contract.md` - external JSON integration contract. - `decisions/README.md` - how to capture new and updated architecture decisions. diff --git a/bible-local/decisions/2026-03-01-mysql-tx-cursor-safety.md b/bible-local/decisions/2026-03-01-mysql-tx-cursor-safety.md index 787fb4c..b1351c9 100644 --- a/bible-local/decisions/2026-03-01-mysql-tx-cursor-safety.md +++ b/bible-local/decisions/2026-03-01-mysql-tx-cursor-safety.md @@ -14,6 +14,6 @@ - Consequences: - Recompute/rebuild code paths must be audited and kept cursor-safe. - Future projection rebuild and repair flows must follow two-phase read/write design by default. - - Runtime invariant documented in `bible/architecture/runtime-flows.md`. + - Runtime invariant documented in `bible-local/architecture/runtime-flows.md`. - Supersedes: - None. diff --git a/bible-local/decisions/2026-03-15-documentation-consolidation.md b/bible-local/decisions/2026-03-15-documentation-consolidation.md new file mode 100644 index 0000000..e6a6a86 --- /dev/null +++ b/bible-local/decisions/2026-03-15-documentation-consolidation.md @@ -0,0 +1,21 @@ +# 2026-03-15 - Consolidate Canonical Project Documentation + +- Date: + - `2026-03-15` +- Decision: + - Keep canonical project documentation only in `bible-local/architecture/`, `bible-local/docs/hardware-ingest-contract.md`, and short index/reference files. + - Remove stale progress trackers, migration status snapshots, and one-off implementation plans from `bible-local/docs/`. +- Context: + - The repository accumulated multiple historical status files that no longer matched the current codebase or active architecture. + - Several documents duplicated the same ingest and migration story with conflicting claims. + - Documentation governance already requires removal of obsolete guidance in the same change. +- Consequences: + - Contributors must update the architecture files or the external ingest contract instead of reviving ad-hoc status documents. + - Compatibility references may remain as short pointers, but not as duplicated source-of-truth documents. + - Root documentation now points directly to `bible/` and `bible-local/`. +- Supersedes: + - `bible-local/docs/TODO.md` + - `bible-local/docs/IMPLEMENTATION_STATUS.md` + - `bible-local/docs/STRING_ID_MIGRATION_STATUS.md` + - `bible-local/docs/FINAL_STATUS.md` + - `bible-local/docs/plan/Plan #1.md` diff --git a/bible-local/decisions/README.md b/bible-local/decisions/README.md index de598c9..28b9ef5 100644 --- a/bible-local/decisions/README.md +++ b/bible-local/decisions/README.md @@ -7,6 +7,7 @@ Use this directory to capture architecture decisions and significant updates. - Every architecture decision must be recorded in the Bible. - If a decision replaces an older one, update the older document in the same change. - Keep entries short, explicit, and linked to the affected architecture files. +- Use `bible-local/architecture/...` and `bible-local/docs/...` paths when referencing affected documents. ## Minimal Entry Template diff --git a/bible-local/docs/README.md b/bible-local/docs/README.md new file mode 100644 index 0000000..1a8673a --- /dev/null +++ b/bible-local/docs/README.md @@ -0,0 +1,13 @@ +# Project Docs Index + +This directory keeps active non-architecture documents for Reanimator Core. + +## Active Documents + +- `hardware-ingest-contract.md` - external-facing JSON hardware ingest contract for integrators. + +## Removed Document Types + +The project does not keep long-lived progress trackers, implementation status snapshots, or one-off task plans as canonical documentation. + +When such notes are no longer needed to operate the system, delete them instead of updating them indefinitely. diff --git a/bible-local/docs/hardware-ingest-contract.md b/bible-local/docs/hardware-ingest-contract.md index ac52762..cb7f0ba 100644 --- a/bible-local/docs/hardware-ingest-contract.md +++ b/bible-local/docs/hardware-ingest-contract.md @@ -33,7 +33,7 @@ language: ru 1. **Snapshot** — JSON описывает состояние сервера на момент сбора. Может включать историю изменений статуса компонентов. 2. **Идемпотентность** — повторная отправка идентичного payload не создаёт дублей (дедупликация по хешу). 3. **Частичность** — можно передавать только те секции, данные по которым доступны. Пустой массив и отсутствие секции эквивалентны. -4. **Толерантность к лишним полям** — неизвестные поля JSON молча игнорируются, ошибки не возникает. +4. **Строгая схема** — endpoint использует строгий JSON-декодер; неизвестные поля приводят к `400 Bad Request`. 5. **Event-driven** — импорт создаёт события в timeline (LOG_COLLECTED, INSTALLED, REMOVED, FIRMWARE_CHANGED и др.). --- @@ -102,6 +102,7 @@ GET /ingest/hardware/jobs/{job_id} Частые причины `400`: - Неверный формат `collected_at` (требуется RFC3339). - Пустой `hardware.board.serial_number`. +- Наличие неизвестного JSON-поля на любом уровне. - Тело запроса превышает допустимый размер. --- diff --git a/bible-local/governance/documentation-policy.md b/bible-local/governance/documentation-policy.md index dd8bdd5..e779d70 100644 --- a/bible-local/governance/documentation-policy.md +++ b/bible-local/governance/documentation-policy.md @@ -8,14 +8,15 @@ This policy defines how architectural knowledge is captured and maintained. - 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 architecture details centralized in `bible/`; other top-level docs should only reference it. +- 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/architecture/`. -2. If behavior changed, add or update a decision note in `bible/decisions/`. +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`. diff --git a/internal/api/ui_ingest.tmpl b/internal/api/ui_ingest.tmpl index d14bfa3..fbf86a4 100644 --- a/internal/api/ui_ingest.tmpl +++ b/internal/api/ui_ingest.tmpl @@ -54,7 +54,7 @@
- +