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`

docs/testing/p2-p6-manual-verification.md

@@ -126,24 +126,42 @@ Checks to complete during P4 manual acceptance (decision: **PASS** (owner approv
 
 ## P5 — Curated FK annotations in Git
 
-**Status:** instructions to be finalized by P5 implementation; not yet runnable.
+**Status:** P5 implementation complete; automated integration PENDING; manual acceptance PENDING.
 
-Manual goal: curate `<id>/schema/annotations.yaml` in an author clone, publish it,
+Manual goal: curate `<id>/schema/annotations.yaml` in an author clone, publish it, pull the new
-pull the new revision, explicitly accept the reviewed blob, and prove atomic revision-correct sync
+revision, and prove the revision-pinned sync and the explicit `schema accept` review, without ever
-without changing `physical.yaml` in Git.
+pushing curated content from the operator CLI.
 
-Checks to fill during P5:
+Commands (contract: `docs/contracts/workspace-preprocessing-cli.md`):
 
-1. candidate/export review;
+```bash
-2. Git commit and exact blob identity;
+thothctl --installation <abs>/thothii-installation.yaml workspace schema suggest-fks --workspace <id> --from-sql <file>.sql --output <candidates>.yaml --json
-3. pull and controlled revision transition;
+# curate the candidate into <id>/schema/annotations.yaml in the author clone, then commit/push/pull
-4. explicit acceptance record;
+thothctl --installation <abs>/thothii-installation.yaml workspace schema accept --workspace <id> --run <run-id> --yes --json
-5. synchronized destination and ownership manifest;
+thothctl --installation <abs>/thothii-installation.yaml workspace preprocess run --workspace <id> --resume <run-id> --json
-6. malformed/oversized/symlink/cross-namespace refusal;
+```
-7. pinned historical revision isolation.
+
+Checks:
+
+1. `schema suggest-fks` returns pristine JSON with `suggestedFksYaml` and a `manual_review_required`
+   block (exit 3) when candidates exist; the suggested YAML digest equals the reported digest;
+2. after commit/push/pull, activation reads `<id>/schema/annotations.yaml` as a regular Git blob at
+   the same commit as the descriptor and synchronizes it to
+   `<data>/sessions/<id>/revisions/<commit>/artifacts/mschema/annotations.yaml` with a restrictive
+   mode and an adjacent ownership manifest `{ workspace, commit, blobId, contentDigest, destination }`;
+3. two revisions write two different directories; a session pinned to an older revision reads its own
+   revision's annotations;
+4. `schema accept --run <id> --yes` records the accepted candidate/current-blob digests and the new
+   revision; missing `--yes`, an unknown run, an empty file, a malformed blob, or a blob not matching
+   the recorded candidate is refused (exit 1, `annotation_invalid`) without recording a review;
+5. `preprocess run --resume <id>` continues only with the exact accepted blob digest and compatible
+   DWH binding; otherwise it records a new `manual_review_required` checkpoint;
+6. negatives: symlink/tree-at-path, cross-namespace, oversized (>16 MiB), non-UTF-8, and malformed
+   annotation objects are refused at activation without mutating the snapshot or runtime roots;
+7. the operator CLI never stages/commits/pushes curated content; secret scan and exact owned-resource
+   cleanup pass.
 
 Decision: **PENDING**.
-
 ## P6 — Commit-addressed Evidence materialization
 
 **Status:** instructions to be finalized by P6 implementation; not yet runnable.