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

Fix round 4/5 — 2026-08-08

Addressed reviewer finding:

• Eliminated semantic-index verifier/test contract drift by extracting the production semantic-index ownership row matcher into semantic_index_relationship_spec and reusing it in the fixture-level paraphrase, omission, and scattered-token checks.
• Kept the relationship constrained to one structured Markdown table row via verify_markdown_table_relationships; the scattered-token fixture still removes the row and appends the same words outside the table, where it must be rejected.
• Added a direct regression that copies the repository docs into an isolated root, applies the accepted paraphrase “A workspace keeps exactly one Qdrant collection reserved for itself”, and runs that root's actual scripts/verify-workspace-install-docs.sh --fixtures-only instead of a separate temporary spec.

Observed RED before the fix:

production verifier rejected the accepted semantic-index paraphrase
local workspace manual: missing relationship in 'Semantic index ownership contract': {'scope': 'workspace semantic index', 'ownership rule': '(each|one|single).*(workspace).*(single|one).*(Qdrant).*(collection)|(each workspace reserves a single qdrant collection)', 'isolation rule': 'schema.*evidence.*memory.*(one|that).*(collection).*(kind|payload)'}

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)

Fix round 3/5 — 2026-08-08

Addressed reviewer findings:

• Added table-driven historical-heading fixtures for every Markdown heading level # through ######; all are rejected after the historical boundary when they contain LIVE/current-state semantics.
• Added small structured ownership tables to the active local/server manuals and to the compact Italian operator note.
• Added small structured semantic-index ownership tables to the active local/server manuals.
• Replaced the remaining scattered-token relationship checks with explicit structured-section parsing:
  • architecture ownership rows map DWH → external, LLM → external, Qdrant → internal, Ollama embedding → internal;
  • semantic-index ownership rows localize the one-workspace/one-collection contract and the schema/Evidence/Memory isolation rule.
• Added adversarial fixtures that fail when the same tokens are merely scattered in free text.
• Added structured 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