docs: harden internal semantic doc state

2026-08-08 21:00:50 +02:00
parent 22c3512ac8
commit aa502dcf7d
4 changed files with 275 additions and 59 deletions
@@ -59,3 +59,35 @@ Key outcomes:
 - The broader repository still contains historical design/spec material that references older
  pgvector/external-embedding architecture; this task intentionally updated operator/current-state
  documentation and the corresponding contract tests, not historical planning documents.
+
+## Fix round 1/5 — 2026-08-08
+
+Addressed reviewer findings:
+
+- Moved superseded rollout/state blocks in `PROJECT_STATE.md` behind an explicit
+  `## Historical snapshots and archived reference notes` boundary.
+- Renamed superseded snapshot headings so historical notes no longer present as active `LIVE`
+  state.
+- Added a current-state regression that rejects contradictory active blocks (for example:
+  schema-v2 operational, two-service active stack, or external vector/embedding runtime claims
+  before the historical boundary).
+- Refactored new internal-semantic doc checks away from exact-sentence coupling:
+  - parse `compose.yaml` structurally with YAML;
+  - parse workspace examples structurally with YAML;
+  - inspect backup/restore stable usage interface;
+  - keep targeted forbidden-term checks for active docs while allowing historical sections;
+  - use regex/concept checks for prose.
+
+Evidence:
+
+```sh
+./scripts/test-verify-workspace-install-docs.sh
+./scripts/verify-workspace-install-docs.sh --fixtures-only
+git diff --check
+```
+
+Observed RED before the fix:
+
+```text
+PROJECT_STATE.md: missing Historical snapshots boundary
+```