181 lines
7.2 KiB
Markdown
181 lines
7.2 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```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)
|
|
```
|
|
|
|
## 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:
|
|
|
|
```sh
|
|
./scripts/test-verify-workspace-install-docs.sh
|
|
./scripts/verify-workspace-install-docs.sh --fixtures-only
|
|
git diff --check
|
|
```
|