diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index eee67abd..98445b3b 100644 --- a/PROJECT_STATE.md +++ b/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 `/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//revisions//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 --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` diff --git a/docs/testing/p2-p6-manual-verification.md b/docs/testing/p2-p6-manual-verification.md index e3f9f24e..5d6f3741 100644 --- a/docs/testing/p2-p6-manual-verification.md +++ b/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 `/schema/annotations.yaml` in an author clone, publish it, -pull the new revision, explicitly accept the reviewed blob, and prove atomic revision-correct sync -without changing `physical.yaml` in Git. +Manual goal: curate `/schema/annotations.yaml` in an author clone, publish it, pull the new +revision, and prove the revision-pinned sync and the explicit `schema accept` review, without ever +pushing curated content from the operator CLI. -Checks to fill during P5: +Commands (contract: `docs/contracts/workspace-preprocessing-cli.md`): -1. candidate/export review; -2. Git commit and exact blob identity; -3. pull and controlled revision transition; -4. explicit acceptance record; -5. synchronized destination and ownership manifest; -6. malformed/oversized/symlink/cross-namespace refusal; -7. pinned historical revision isolation. +```bash +thothctl --installation /thothii-installation.yaml workspace schema suggest-fks --workspace --from-sql .sql --output .yaml --json +# curate the candidate into /schema/annotations.yaml in the author clone, then commit/push/pull +thothctl --installation /thothii-installation.yaml workspace schema accept --workspace --run --yes --json +thothctl --installation /thothii-installation.yaml workspace preprocess run --workspace --resume --json +``` + +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 `/schema/annotations.yaml` as a regular Git blob at + the same commit as the descriptor and synchronizes it to + `/sessions//revisions//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 --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 ` 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.