docs: record P5 implementation and finalize the P5 manual walkthrough

PROJECT_STATE.md

@@ -7,7 +7,7 @@
 > ThothII per il repository (app + CLI `thothctl`), (3) come usare l'applicazione ThothII di base
 > (sessioni, domande, gate). Il documento userà parole semplici ed esempi; i dettagli tecnici
 > resteranno nei contratti esistenti. Esempio pratico completo: Policlinico San Donato.
- Last updated: 2026-08-13 (P3+P4 manual acceptance).
+ Last updated: 2026-08-13 (P3+P4 manual acceptance; P5 implementation).
 > Point a fresh session here ("read PROJECT_STATE.md") before substantial work.
 
 ### P3 effective configuration and `.tht-dwh` — implementation complete, automated PASS, manual PASS (2026-08-13)
@@ -60,6 +60,44 @@
   `docs/testing/p2-p6-manual-verification.md`.
 
 
+### P5 curated FK annotations in Git — implementation complete, automated PENDING, manual PENDING (2026-08-13)
+
+- **Scope:** P5 (PRD D5): the canonical curated FK file is `<workspace-id>/schema/annotations.yaml`,
+  a regular Git blob at the same commit as the descriptor. Absence is compatible (empty canonical set
+  + warning); symlinks, trees/gitlinks, cross-namespace paths, oversized (>16 MiB), non-UTF-8, and
+  malformed objects are refused at activation. Activation synchronizes the blob to the immutable
+  revision root `/data/sessions/<id>/revisions/<commit>/artifacts/mschema/annotations.yaml` with a
+  restrictive mode and an adjacent ownership manifest (`workspace`, `commit`, `blobId`,
+  `contentDigest`, `destination`); re-sync is idempotent and re-verifies, and tampered destinations
+  fail closed.
+- **Runtime root:** the backend renders `paths.annotations_root` for the pinned revision while
+  `paths.artifacts`/`indexes`/`memory`/`sessions` stay workspace-global (the binding-keyed DWH cache
+  at `artifacts.parent` is untouched); the harness resolves annotations from `annotations_root` with a
+  legacy fallback.
+- **Review primitive:** `thothctl ... workspace schema accept --run <id> --yes` is the only human FK
+  review path. It validates the current synced Git blob with the harness parser and records
+  `{ reviewedCandidatesDigest, annotationsDigest, workspaceRevision, blobId }`. Missing `--yes`, an
+  unknown run, an empty/malformed blob, or a non-matching candidate fails closed (`annotation_invalid`)
+  without recording a review. The P2 host-file `schema check --annotations --reviewed-candidates`
+  review write is superseded (read-only validation only).
+- **Continuation gate:** `preprocess run` continues only when the accepted review's blob digest equals
+  the current revision's synced annotations digest and the DWH binding is compatible; otherwise it
+  records a new `manual_review_required` checkpoint.
+- **Key files:** `backend/src/workspaces/annotations-sync.ts` (+test), `backend/src/workspaces/
+  annotations.ts`, `backend/src/workspaces/git-repository.ts` (`annotationsObject`),
+  `backend/src/workspaces/registry.ts` (activation validation + sync), `backend/src/workspaces/
+  preprocessing-service.ts` (`acceptSchema` + continuation gate), `backend/src/workspace-maintenance.ts`
+  (`schema-accept`), `tools/thothctl/internal/workspaceops/operations.go` (+tests), `harness/tht/
+  config.py` + `cli/schema_cmd.py` (`paths.annotations_root`), `docs/contracts/
+  workspace-preprocessing-cli.md`.
+- **Gates:** backend **689/689** + tsc clean; Go build+test 9/9; harness focused schema/annotations
+  52 passed. Full-suite re-run and the clean-state process goal are recorded at the acceptance gate.
+- **Automated acceptance:** PENDING — runner to be added under `scripts/p5-acceptance.sh` /
+  `backend/scripts/p5-acceptance.mjs` (clean-state fixture Git registry + REST DWH + Qdrant;
+  activation sync, revision isolation, accept happy path + negatives, continuation gate, no push,
+  secret scan, exact cleanup).
+- **Manual acceptance:** PENDING — walkthrough section P5 in `docs/testing/p2-p6-manual-verification.md`.
+
 ### P2 host preprocessing CLI — implementation complete, automated PASS, manual PENDING (2026-08-11)
 
 - **Scope:** P2 (PRD D2, based on the P1.1 registry contract): the installed native `thothctl`