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

```sh
./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:

```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
```

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

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

Observed RED during this round:

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