ThothII/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-11-report.md

Task 11 report

Status: completed on 2026-08-08.

Scope delivered

• Updated operator-facing documentation for the internal Qdrant + Ollama architecture.
• Tightened documentation contract tests to require the current four-service-plus-init topology, CPU-first/GPU-override guidance, fixed internal model/dimensions, schema-v3 migration wording, one-collection-per-workspace ownership, and Qdrant backup/restore safety.
• Updated stable repo guidance in AGENTS.md and the current snapshot in PROJECT_STATE.md.
• Rewrote the workspace diagnostic protocol to the schema-v3/internal-semantic-service contract.
• Updated the memory guide to describe Qdrant as the derived persistent index.
• Updated the runtime secret-bundle guide to remove active vector/embedding secret guidance.

Files changed

• README.md
• AGENTS.md
• PROJECT_STATE.md
• docs/install/local-workspace-registry.md
• docs/install/server-workspace-registry.md
• docs/installazione-docker-4-contesti.md
• docs/workspace-diagnostic-protocol.md
• docs/gestione-memory.md
• deploy/secrets/README.md
• scripts/verify-workspace-install-docs.sh
• scripts/test-verify-workspace-install-docs.sh

Verification

Fresh successful runs:

./scripts/test-verify-workspace-install-docs.sh
./scripts/verify-workspace-install-docs.sh --fixtures-only
git diff --check

Key outcomes:

• internal semantic infrastructure documentation contract passed
• all existing install/manual fixture contracts still passed
• diff hygiene passed with no whitespace/errors

Self-review notes

• The updated docs now match the code-backed Compose topology: frontend, core, qdrant, embedding, and embedding-model-init.
• Active manuals no longer instruct operators to configure external vector or embedding runtime endpoints/secrets.
• Qdrant backup/restore wording now matches the helper scripts' exact confirmation and rollback behavior.
• Legacy descriptor handling is documented as explicit schema-v3 migration only; no silent semantic-data migration is claimed.

Residual concerns

• 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:

./scripts/test-verify-workspace-install-docs.sh
./scripts/verify-workspace-install-docs.sh --fixtures-only
git diff --check

Observed RED before the fix:

PROJECT_STATE.md: missing Historical snapshots boundary

Fix round 2/5 — 2026-08-08

Addressed reviewer findings:

• Renamed every historical PROJECT_STATE.md heading after the historical boundary so no heading level uses LIVE or current-state semantics there.
• Strengthened the historical-boundary regression to reject any Markdown heading level (# through ######) containing LIVE or current-state wording after the boundary.
• Added a fixture with a ### ... — LIVE ... historical heading to prove RED then GREEN.
• Replaced remaining exact phrase checks with concept/semantic validation for:
  • one-workspace/one-collection ownership;
  • external boundary (DWH/LLM external; vector/embedding internal);
  • the Italian compact install note.
• Added paraphrase fixtures that pass and omission/inversion fixtures that fail.

Evidence:

./scripts/test-verify-workspace-install-docs.sh
./scripts/verify-workspace-install-docs.sh --fixtures-only
git diff --check

Observed RED during this round:

PROJECT_STATE.md: historical section still contains active/live heading markers
compact manual paraphrase lacks required pattern: (esterni solo|solo esterni|restano esterni)