From f48196a57f76dbe9387fe60e4d93349a941feb6a Mon Sep 17 00:00:00 2001 From: mptyl Date: Wed, 26 Aug 2026 08:10:37 +0200 Subject: [PATCH] chore: commit remaining worktree changes --- .../reviews/task9-quality-audit-final5.md | 66 - .artifacts/task-15/automated-gates.json | 282 --- .artifacts/task-15/unified-docker-images.json | 54 - .claude/launch.json | 11 - .dockerignore | 2 - .github/workflows/deployment.yml | 1 - .gitignore | 2 - .kilo/kilo.jsonc | 7 - .../task-3-report.md | 105 - .../task-7-report.md | 101 - .../task-9-report.md | 73 - .../task-11-report.md | 180 -- .../task-12-report.md | 43 - .../task-13-implementation.md | 175 -- .../task-2-report.md | 165 -- .../task-3-report.md | 132 -- .../task-4-report.md | 149 -- .../task-5-report.md | 170 -- .../task-6-report.md | 144 -- .../task-7-report.md | 98 - .../task-9-report.md | 65 - .../task-5-report.md | 83 - .../task-6-report.md | 55 - .../task-15-report.md | 163 -- .../fix-round-1-report.md | 162 -- .../fix-round-2-report.md | 133 -- .../task-4-report.md | 131 -- .../final-fix-report.md | 175 -- .../task-12-report.md | 276 --- .superpowers/sdd/adapter-final-fix-report.md | 137 -- .superpowers/sdd/container-task-3-report.md | 206 -- .superpowers/sdd/container-task-4-report.md | 82 - .superpowers/sdd/evidence-task-1-report.md | 98 - .superpowers/sdd/evidence-task-2-report.md | 65 - .superpowers/sdd/evidence-task-3-report.md | 59 - .superpowers/sdd/evidence-task-4-report.md | 107 - .superpowers/sdd/evidence-task-5-report.md | 82 - .superpowers/sdd/evidence-task-5b-report.md | 94 - .superpowers/sdd/evidence-task-5c-report.md | 188 -- .superpowers/sdd/evidence-task-5d-report.md | 50 - .superpowers/sdd/evidence-task-6-report.md | 49 - .superpowers/sdd/evidence-task-7-report.md | 93 - .../sdd/model-provider-credential-report.md | 16 - .superpowers/sdd/pgvector-final-fix-report.md | 59 - .superpowers/sdd/pgvector-task-1-report.md | 95 - .superpowers/sdd/pgvector-task-2-report.md | 82 - .superpowers/sdd/pgvector-task-3-report.md | 133 -- .superpowers/sdd/pgvector-task-4-report.md | 94 - .superpowers/sdd/predeploy-fix-report.md | 929 -------- .superpowers/sdd/progress.md | 53 - .superpowers/sdd/task-2-report.md | 325 --- .superpowers/sdd/task-3-report.md | 129 -- .superpowers/sdd/task-4-report.md | 60 - .superpowers/sdd/task-5-report.md | 71 - .superpowers/sdd/task-6-report.md | 298 --- .superpowers/sdd/task-7-report.md | 90 - AGENTS.md | 4 +- CLAUDE.md | 105 - PROJECT_STATE.md | 1395 +----------- README.md | 16 +- .../verify-workspace-descriptor-files.mjs | 3 - ...verify-workspace-descriptor-files.test.mjs | 14 - .../datamart-builder-deployment-gotchas.md | 14 - brain/codebase/pi-model-selection.md | 11 - brain/codebase/psd-dwh-transport.md | 20 - brain/codebase/workflow-ui-contracts.md | 44 - brain/index.md | 6 - deploy/compose.preprocess.yaml | 44 - deploy/workspaces/preprocess-dwh.yaml | 11 - deploy/workspaces/preprocess-evidence.yaml | 22 - docs/architecture/overview.md | 7 +- docs/installazione-docker-4-contesti.md | 17 +- docs/operations/psd-dwh-auth-rollout.md | 2 +- ...psd-server-survey-remediation-checklist.md | 8 +- ...2026-07-21-button-press-feedback-design.md | 19 - .../plans/2026-07-21-button-press-feedback.md | 72 - .../2026-08-08-internal-qdrant-ollama.md | 773 ------- .../2026-08-10-rimozione-schema-v1-v2.md | 447 ---- ...-14-read-only-workspace-runtime-secrets.md | 401 ---- .../2026-08-18-evidence-canonica-design.md | 217 -- ...ntication-acceptance-and-psd-deployment.md | 2 +- ...026-08-19-tht-documentation-convergence.md | 92 - ...026-08-20-psd-server-deployment-program.md | 2 +- ...6-08-20-psd-server-project-a-standalone.md | 2 +- ...26-08-20-psd-server-project-b-authentik.md | 2 +- docs/plans/2026-08-20-psd-server-survey.md | 2 +- ...026-08-24-evidence-restructuring-design.md | 2 +- .../2026-08-24-evidence-restructuring.md | 1326 ----------- .../2026-08-09-workspace-preprocessing-prd.md | 38 +- docs/reports/2026-08-15-tht-command-audit.md | 171 -- ...8-15-tht-command-maintain-erase-enhance.md | 148 -- docs/reports/l2-run-report-2026-06-27.md | 126 -- .../superpowers/2026-06-27-stato-e-ripresa.md | 46 - .../2026-06-25-harness-implementation.md | 1697 --------------- .../2026-06-27-backend-implementation.md | 1024 --------- .../2026-06-27-frontend-implementation.md | 860 -------- .../plans/2026-06-27-harness-rpc-readiness.md | 967 -------- .../plans/2026-06-27-tht-porting-cli-skill.md | 1221 ----------- .../plans/2026-06-28-settings-menu.md | 1506 ------------- .../plans/2026-06-29-ollama-ensure.md | 750 ------- .../plans/2026-06-29-session-management.md | 1939 ----------------- .../2026-06-29-session-ui-refinements.md | 767 ------- .../2026-06-30-cross-model-behavior-matrix.md | 106 - .../2026-07-01-workflow-contract-hardening.md | 721 ------ .../2026-07-02-reviewer-gate-ux-fixes.md | 575 ----- .../plans/2026-07-03-workflow-ui-fixes.md | 944 -------- ...schema-linking-column-curation-frontend.md | 707 ------ ...-schema-linking-column-curation-harness.md | 852 -------- ...e-memory-promotion-and-solved-questions.md | 1188 ---------- .../plans/2026-07-11-adapter-foundations.md | 344 --- ...11-container-packaging-portable-storage.md | 302 --- .../2026-07-11-evidence-preprocessing.md | 373 ---- .../2026-07-11-local-pgvector-profile.md | 211 -- .../2026-07-11-portable-deployment-program.md | 47 - ...7-12-local-and-server-docker-deployment.md | 70 - ...7-12-local-docker-deploy-implementation.md | 979 --------- .../plans/2026-07-12-simple-docker-config.md | 156 -- .../2026-07-14-activity-log-cte-layout.md | 776 ------- .../2026-07-14-f3-rewrite-auto-approval.md | 44 - .../2026-07-14-memory-selection-clarity.md | 115 - ...odel-activity-layout-and-composer-state.md | 274 --- .../2026-07-14-pi-enabled-model-selector.md | 918 -------- ...07-14-qwen-connectivity-resume-recovery.md | 717 ------ .../2026-07-14-workflow-ui-regressions.md | 314 --- ...2026-07-15-central-live-log-cte-density.md | 791 ------- ...2026-07-15-model-activity-signal-filter.md | 495 ----- ...15-resizable-model-activity-cte-density.md | 850 -------- .../2026-07-16-user-owned-session-storage.md | 130 -- .../2026-07-16-user-preference-bootstrap.md | 110 - .../2026-07-20-full-audit-remediation-plan.md | 210 -- ...6-07-21-pi-user-auth-and-startup-errors.md | 87 - .../2026-07-23-session-summary-layout.md | 172 -- ...026-08-03-diagnostic-contract-extension.md | 59 - .../2026-08-03-git-workspace-registry.md | 906 -------- .../2026-08-04-unified-compose-deployment.md | 687 ------ .../2026-08-09-prd-p1-descriptor-evidence.md | 1697 --------------- ...-10-p2-host-workspace-preprocessing-cli.md | 593 ----- ...08-11-p1-1-workspace-directory-registry.md | 1250 ----------- ...08-11-p2-p6-adaptation-to-p1-1-registry.md | 228 -- ...6-08-11-p3-effective-config-and-tht-dwh.md | 150 -- ...26-08-11-p4-qdrant-collection-lifecycle.md | 61 - ...-08-13-p5-curated-fk-annotations-in-git.md | 197 -- ...mmit-addressed-evidence-materialization.md | 179 -- .../plans/2026-08-13-p7-psd-migration.md | 122 -- ...6-08-14-pi-management-operator-workflow.md | 764 ------- ...-08-14-thothctl-discovery-and-pi-update.md | 86 - ...2026-08-15-unified-tht-cli-product-step.md | 1159 ---------- .../2026-08-16-thothii-authentication.md | 1456 ------------- ...8-18-thothii-authentication-remediation.md | 911 -------- ...26-08-20-dwh-rest-per-installation-auth.md | 761 ------- ...-08-20-psd-survey-remediation-checklist.md | 120 - ...e-install-docs-fixture-self-containment.md | 247 --- ...roject-a-server-auth-runtime-projection.md | 1066 --------- .../plans/2026-08-21-psd-clean-replacement.md | 259 --- .../2026-08-22-datamart-builder-cutover.md | 436 ---- .../2026-08-22-datamart-builder-test-route.md | 73 - ...2026-08-22-local-only-logout-visibility.md | 342 --- ...workspace-postgres-diagnostic-alignment.md | 428 ---- .../2026-06-25-thothii-architecture-design.md | 728 ------- .../specs/2026-06-27-backend-design.md | 189 -- ...li-port-completo-skill-riscritta-design.md | 279 --- .../specs/2026-06-27-frontend-design.md | 160 -- .../specs/2026-06-28-settings-menu-design.md | 141 -- .../specs/2026-06-29-ollama-ensure-design.md | 140 -- .../2026-06-29-session-management-design.md | 270 --- ...026-06-29-session-ui-refinements-design.md | 155 -- ...7-01-workflow-contract-hardening-design.md | 136 -- ...026-07-02-reviewer-gate-ux-fixes-design.md | 198 -- .../2026-07-03-workflow-ui-fixes-design.md | 188 -- .../2026-07-04-dual-mode-gate-evaluation.md | 228 -- ...4-schema-linking-column-curation-design.md | 220 -- ...portable-deployment-architecture-design.md | 333 --- ...cal-and-server-docker-deployment-design.md | 34 - .../2026-07-12-simple-docker-config-design.md | 98 - ...26-07-14-activity-log-cte-layout-design.md | 152 -- ...6-07-14-f3-rewrite-auto-approval-design.md | 15 - ...tivity-layout-and-composer-state-design.md | 56 - ...-07-14-pi-enabled-model-selector-design.md | 167 -- ...wen-connectivity-resume-recovery-design.md | 84 - ...26-07-14-workflow-ui-regressions-design.md | 70 - ...-15-central-live-log-cte-density-design.md | 155 -- ...-15-model-activity-signal-filter-design.md | 108 - ...zable-model-activity-cte-density-design.md | 174 -- ...07-16-user-owned-session-storage-design.md | 25 - ...-07-16-user-preference-bootstrap-design.md | 34 - ...-pi-user-auth-and-startup-errors-design.md | 46 - ...026-07-23-session-summary-layout-design.md | 108 - ...026-08-03-git-workspace-registry-design.md | 674 ------ ...08-04-unified-compose-deployment-design.md | 293 --- ...10-p2-p6-workspace-preprocessing-design.md | 273 --- ...1-1-workspace-directory-registry-design.md | 255 --- ...-pi-management-operator-workflow-design.md | 215 -- ...thothctl-discovery-and-pi-update-design.md | 44 - ...-15-unified-tht-cli-product-step-design.md | 235 -- ...026-08-16-thothii-authentication-design.md | 495 ----- ...0-dwh-rest-per-installation-auth-design.md | 386 ---- ...psd-survey-remediation-checklist-design.md | 80 - ...ll-docs-fixture-self-containment-design.md | 97 - ...a-server-auth-runtime-projection-design.md | 424 ---- ...2026-08-21-psd-clean-replacement-design.md | 86 - ...6-08-22-datamart-builder-cutover-design.md | 148 -- ...-22-local-only-logout-visibility-design.md | 124 -- ...026-08-22-local-user-identity-ui-design.md | 7 - ...ce-postgres-diagnostic-alignment-design.md | 58 - docs/testing/evidence-restructuring-manual.md | 186 -- ...restructuring-psd-acceptance-2026-08-25.md | 2 +- frontend/src/api/sql.ts | 14 - frontend/src/components/ui/radio-group.tsx | 38 - frontend/src/components/ui/textarea.tsx | 18 - frontend/src/shell/NewSessionDialog.test.tsx | 120 - frontend/src/shell/NewSessionDialog.tsx | 115 - frontend/src/shell/WorkingSpinner.tsx | 24 - frontend/src/viewers/ResultsPanel.test.tsx | 145 -- frontend/src/viewers/ResultsPanel.tsx | 67 - frontend/src/viewers/artifactV2.ts | 3 +- harness/README.md | 5 +- harness/docs/testing.md | 2 +- .../test_evidence_restructuring_fixture.py | 36 - harness/tests/test_session_coherence_smoke.py | 13 +- harness/tests/test_taskdoc.py | 104 - harness/tht/mschema/eligibility.py | 1 - harness/tht/taskdoc.py | 102 - harness/tht/textutil.py | 8 - harness/tht/vendor/VENDORED.md | 4 +- mkdocs.yml | 25 - prd/ThothII-prd.md | 113 - scripts/preprocess-smoke.sh | 160 -- scripts/test-deployment-command-contract.sh | 1 - scripts/test-no-deployment-coupling-scope.sh | 8 +- scripts/test-no-deployment-coupling.sh | 2 +- scripts/test-preprocess-compose-config.sh | 62 - scripts/test-verify-schema-v3-only.sh | 8 +- scripts/verify-schema-v3-only.sh | 2 +- task-10-report.md | 93 - 234 files changed, 146 insertions(+), 61044 deletions(-) delete mode 100644 .artifacts/reviews/task9-quality-audit-final5.md delete mode 100644 .artifacts/task-15/automated-gates.json delete mode 100644 .artifacts/task-15/unified-docker-images.json delete mode 100644 .claude/launch.json delete mode 100644 .kilo/kilo.jsonc delete mode 100644 .superpowers/sdd/2026-08-03-diagnostic-contract-extension/task-3-report.md delete mode 100644 .superpowers/sdd/2026-08-03-git-workspace-registry/task-7-report.md delete mode 100644 .superpowers/sdd/2026-08-03-git-workspace-registry/task-9-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-11-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-12-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-13-implementation.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-2-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-3-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-4-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-5-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-6-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-7-report.md delete mode 100644 .superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-9-report.md delete mode 100644 .superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-5-report.md delete mode 100644 .superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-6-report.md delete mode 100644 .superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md delete mode 100644 .superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-1-report.md delete mode 100644 .superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md delete mode 100644 .superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md delete mode 100644 .superpowers/sdd/2026-08-24-evidence-restructuring/final-fix-report.md delete mode 100644 .superpowers/sdd/2026-08-24-evidence-restructuring/task-12-report.md delete mode 100644 .superpowers/sdd/adapter-final-fix-report.md delete mode 100644 .superpowers/sdd/container-task-3-report.md delete mode 100644 .superpowers/sdd/container-task-4-report.md delete mode 100644 .superpowers/sdd/evidence-task-1-report.md delete mode 100644 .superpowers/sdd/evidence-task-2-report.md delete mode 100644 .superpowers/sdd/evidence-task-3-report.md delete mode 100644 .superpowers/sdd/evidence-task-4-report.md delete mode 100644 .superpowers/sdd/evidence-task-5-report.md delete mode 100644 .superpowers/sdd/evidence-task-5b-report.md delete mode 100644 .superpowers/sdd/evidence-task-5c-report.md delete mode 100644 .superpowers/sdd/evidence-task-5d-report.md delete mode 100644 .superpowers/sdd/evidence-task-6-report.md delete mode 100644 .superpowers/sdd/evidence-task-7-report.md delete mode 100644 .superpowers/sdd/model-provider-credential-report.md delete mode 100644 .superpowers/sdd/pgvector-final-fix-report.md delete mode 100644 .superpowers/sdd/pgvector-task-1-report.md delete mode 100644 .superpowers/sdd/pgvector-task-2-report.md delete mode 100644 .superpowers/sdd/pgvector-task-3-report.md delete mode 100644 .superpowers/sdd/pgvector-task-4-report.md delete mode 100644 .superpowers/sdd/predeploy-fix-report.md delete mode 100644 .superpowers/sdd/progress.md delete mode 100644 .superpowers/sdd/task-2-report.md delete mode 100644 .superpowers/sdd/task-3-report.md delete mode 100644 .superpowers/sdd/task-4-report.md delete mode 100644 .superpowers/sdd/task-5-report.md delete mode 100644 .superpowers/sdd/task-6-report.md delete mode 100644 .superpowers/sdd/task-7-report.md delete mode 100644 CLAUDE.md delete mode 100644 brain/codebase/datamart-builder-deployment-gotchas.md delete mode 100644 brain/codebase/pi-model-selection.md delete mode 100644 brain/codebase/psd-dwh-transport.md delete mode 100644 brain/codebase/workflow-ui-contracts.md delete mode 100644 brain/index.md delete mode 100644 deploy/compose.preprocess.yaml delete mode 100644 deploy/workspaces/preprocess-dwh.yaml delete mode 100644 deploy/workspaces/preprocess-evidence.yaml delete mode 100644 docs/plans/2026-07-21-button-press-feedback-design.md delete mode 100644 docs/plans/2026-07-21-button-press-feedback.md delete mode 100644 docs/plans/2026-08-08-internal-qdrant-ollama.md delete mode 100644 docs/plans/2026-08-10-rimozione-schema-v1-v2.md delete mode 100644 docs/plans/2026-08-14-read-only-workspace-runtime-secrets.md delete mode 100644 docs/plans/2026-08-18-evidence-canonica-design.md delete mode 100644 docs/plans/2026-08-19-tht-documentation-convergence.md delete mode 100644 docs/plans/2026-08-24-evidence-restructuring.md delete mode 100644 docs/reports/2026-08-15-tht-command-audit.md delete mode 100644 docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md delete mode 100644 docs/reports/l2-run-report-2026-06-27.md delete mode 100644 docs/superpowers/2026-06-27-stato-e-ripresa.md delete mode 100644 docs/superpowers/plans/2026-06-25-harness-implementation.md delete mode 100644 docs/superpowers/plans/2026-06-27-backend-implementation.md delete mode 100644 docs/superpowers/plans/2026-06-27-frontend-implementation.md delete mode 100644 docs/superpowers/plans/2026-06-27-harness-rpc-readiness.md delete mode 100644 docs/superpowers/plans/2026-06-27-tht-porting-cli-skill.md delete mode 100644 docs/superpowers/plans/2026-06-28-settings-menu.md delete mode 100644 docs/superpowers/plans/2026-06-29-ollama-ensure.md delete mode 100644 docs/superpowers/plans/2026-06-29-session-management.md delete mode 100644 docs/superpowers/plans/2026-06-29-session-ui-refinements.md delete mode 100644 docs/superpowers/plans/2026-06-30-cross-model-behavior-matrix.md delete mode 100644 docs/superpowers/plans/2026-07-01-workflow-contract-hardening.md delete mode 100644 docs/superpowers/plans/2026-07-02-reviewer-gate-ux-fixes.md delete mode 100644 docs/superpowers/plans/2026-07-03-workflow-ui-fixes.md delete mode 100644 docs/superpowers/plans/2026-07-06-f4-schema-linking-column-curation-frontend.md delete mode 100644 docs/superpowers/plans/2026-07-06-f4-schema-linking-column-curation-harness.md delete mode 100644 docs/superpowers/plans/2026-07-07-active-memory-promotion-and-solved-questions.md delete mode 100644 docs/superpowers/plans/2026-07-11-adapter-foundations.md delete mode 100644 docs/superpowers/plans/2026-07-11-container-packaging-portable-storage.md delete mode 100644 docs/superpowers/plans/2026-07-11-evidence-preprocessing.md delete mode 100644 docs/superpowers/plans/2026-07-11-local-pgvector-profile.md delete mode 100644 docs/superpowers/plans/2026-07-11-portable-deployment-program.md delete mode 100644 docs/superpowers/plans/2026-07-12-local-and-server-docker-deployment.md delete mode 100644 docs/superpowers/plans/2026-07-12-local-docker-deploy-implementation.md delete mode 100644 docs/superpowers/plans/2026-07-12-simple-docker-config.md delete mode 100644 docs/superpowers/plans/2026-07-14-activity-log-cte-layout.md delete mode 100644 docs/superpowers/plans/2026-07-14-f3-rewrite-auto-approval.md delete mode 100644 docs/superpowers/plans/2026-07-14-memory-selection-clarity.md delete mode 100644 docs/superpowers/plans/2026-07-14-model-activity-layout-and-composer-state.md delete mode 100644 docs/superpowers/plans/2026-07-14-pi-enabled-model-selector.md delete mode 100644 docs/superpowers/plans/2026-07-14-qwen-connectivity-resume-recovery.md delete mode 100644 docs/superpowers/plans/2026-07-14-workflow-ui-regressions.md delete mode 100644 docs/superpowers/plans/2026-07-15-central-live-log-cte-density.md delete mode 100644 docs/superpowers/plans/2026-07-15-model-activity-signal-filter.md delete mode 100644 docs/superpowers/plans/2026-07-15-resizable-model-activity-cte-density.md delete mode 100644 docs/superpowers/plans/2026-07-16-user-owned-session-storage.md delete mode 100644 docs/superpowers/plans/2026-07-16-user-preference-bootstrap.md delete mode 100644 docs/superpowers/plans/2026-07-20-full-audit-remediation-plan.md delete mode 100644 docs/superpowers/plans/2026-07-21-pi-user-auth-and-startup-errors.md delete mode 100644 docs/superpowers/plans/2026-07-23-session-summary-layout.md delete mode 100644 docs/superpowers/plans/2026-08-03-diagnostic-contract-extension.md delete mode 100644 docs/superpowers/plans/2026-08-03-git-workspace-registry.md delete mode 100644 docs/superpowers/plans/2026-08-04-unified-compose-deployment.md delete mode 100644 docs/superpowers/plans/2026-08-09-prd-p1-descriptor-evidence.md delete mode 100644 docs/superpowers/plans/2026-08-10-p2-host-workspace-preprocessing-cli.md delete mode 100644 docs/superpowers/plans/2026-08-11-p1-1-workspace-directory-registry.md delete mode 100644 docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md delete mode 100644 docs/superpowers/plans/2026-08-11-p3-effective-config-and-tht-dwh.md delete mode 100644 docs/superpowers/plans/2026-08-11-p4-qdrant-collection-lifecycle.md delete mode 100644 docs/superpowers/plans/2026-08-13-p5-curated-fk-annotations-in-git.md delete mode 100644 docs/superpowers/plans/2026-08-13-p6-commit-addressed-evidence-materialization.md delete mode 100644 docs/superpowers/plans/2026-08-13-p7-psd-migration.md delete mode 100644 docs/superpowers/plans/2026-08-14-pi-management-operator-workflow.md delete mode 100644 docs/superpowers/plans/2026-08-14-thothctl-discovery-and-pi-update.md delete mode 100644 docs/superpowers/plans/2026-08-15-unified-tht-cli-product-step.md delete mode 100644 docs/superpowers/plans/2026-08-16-thothii-authentication.md delete mode 100644 docs/superpowers/plans/2026-08-18-thothii-authentication-remediation.md delete mode 100644 docs/superpowers/plans/2026-08-20-dwh-rest-per-installation-auth.md delete mode 100644 docs/superpowers/plans/2026-08-20-psd-survey-remediation-checklist.md delete mode 100644 docs/superpowers/plans/2026-08-20-workspace-install-docs-fixture-self-containment.md delete mode 100644 docs/superpowers/plans/2026-08-21-project-a-server-auth-runtime-projection.md delete mode 100644 docs/superpowers/plans/2026-08-21-psd-clean-replacement.md delete mode 100644 docs/superpowers/plans/2026-08-22-datamart-builder-cutover.md delete mode 100644 docs/superpowers/plans/2026-08-22-datamart-builder-test-route.md delete mode 100644 docs/superpowers/plans/2026-08-22-local-only-logout-visibility.md delete mode 100644 docs/superpowers/plans/2026-08-22-workspace-postgres-diagnostic-alignment.md delete mode 100644 docs/superpowers/specs/2026-06-25-thothii-architecture-design.md delete mode 100644 docs/superpowers/specs/2026-06-27-backend-design.md delete mode 100644 docs/superpowers/specs/2026-06-27-cli-port-completo-skill-riscritta-design.md delete mode 100644 docs/superpowers/specs/2026-06-27-frontend-design.md delete mode 100644 docs/superpowers/specs/2026-06-28-settings-menu-design.md delete mode 100644 docs/superpowers/specs/2026-06-29-ollama-ensure-design.md delete mode 100644 docs/superpowers/specs/2026-06-29-session-management-design.md delete mode 100644 docs/superpowers/specs/2026-06-29-session-ui-refinements-design.md delete mode 100644 docs/superpowers/specs/2026-07-01-workflow-contract-hardening-design.md delete mode 100644 docs/superpowers/specs/2026-07-02-reviewer-gate-ux-fixes-design.md delete mode 100644 docs/superpowers/specs/2026-07-03-workflow-ui-fixes-design.md delete mode 100644 docs/superpowers/specs/2026-07-04-dual-mode-gate-evaluation.md delete mode 100644 docs/superpowers/specs/2026-07-06-f4-schema-linking-column-curation-design.md delete mode 100644 docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md delete mode 100644 docs/superpowers/specs/2026-07-12-local-and-server-docker-deployment-design.md delete mode 100644 docs/superpowers/specs/2026-07-12-simple-docker-config-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-activity-log-cte-layout-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-f3-rewrite-auto-approval-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-model-activity-layout-and-composer-state-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-pi-enabled-model-selector-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-qwen-connectivity-resume-recovery-design.md delete mode 100644 docs/superpowers/specs/2026-07-14-workflow-ui-regressions-design.md delete mode 100644 docs/superpowers/specs/2026-07-15-central-live-log-cte-density-design.md delete mode 100644 docs/superpowers/specs/2026-07-15-model-activity-signal-filter-design.md delete mode 100644 docs/superpowers/specs/2026-07-15-resizable-model-activity-cte-density-design.md delete mode 100644 docs/superpowers/specs/2026-07-16-user-owned-session-storage-design.md delete mode 100644 docs/superpowers/specs/2026-07-16-user-preference-bootstrap-design.md delete mode 100644 docs/superpowers/specs/2026-07-21-pi-user-auth-and-startup-errors-design.md delete mode 100644 docs/superpowers/specs/2026-07-23-session-summary-layout-design.md delete mode 100644 docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md delete mode 100644 docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md delete mode 100644 docs/superpowers/specs/2026-08-10-p2-p6-workspace-preprocessing-design.md delete mode 100644 docs/superpowers/specs/2026-08-11-p1-1-workspace-directory-registry-design.md delete mode 100644 docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md delete mode 100644 docs/superpowers/specs/2026-08-14-thothctl-discovery-and-pi-update-design.md delete mode 100644 docs/superpowers/specs/2026-08-15-unified-tht-cli-product-step-design.md delete mode 100644 docs/superpowers/specs/2026-08-16-thothii-authentication-design.md delete mode 100644 docs/superpowers/specs/2026-08-20-dwh-rest-per-installation-auth-design.md delete mode 100644 docs/superpowers/specs/2026-08-20-psd-survey-remediation-checklist-design.md delete mode 100644 docs/superpowers/specs/2026-08-20-workspace-install-docs-fixture-self-containment-design.md delete mode 100644 docs/superpowers/specs/2026-08-21-project-a-server-auth-runtime-projection-design.md delete mode 100644 docs/superpowers/specs/2026-08-21-psd-clean-replacement-design.md delete mode 100644 docs/superpowers/specs/2026-08-22-datamart-builder-cutover-design.md delete mode 100644 docs/superpowers/specs/2026-08-22-local-only-logout-visibility-design.md delete mode 100644 docs/superpowers/specs/2026-08-22-local-user-identity-ui-design.md delete mode 100644 docs/superpowers/specs/2026-08-22-workspace-postgres-diagnostic-alignment-design.md delete mode 100644 docs/testing/evidence-restructuring-manual.md delete mode 100644 frontend/src/api/sql.ts delete mode 100644 frontend/src/components/ui/radio-group.tsx delete mode 100644 frontend/src/components/ui/textarea.tsx delete mode 100644 frontend/src/shell/NewSessionDialog.test.tsx delete mode 100644 frontend/src/shell/NewSessionDialog.tsx delete mode 100644 frontend/src/shell/WorkingSpinner.tsx delete mode 100644 frontend/src/viewers/ResultsPanel.test.tsx delete mode 100644 frontend/src/viewers/ResultsPanel.tsx delete mode 100644 harness/tests/test_taskdoc.py delete mode 100644 harness/tht/taskdoc.py delete mode 100644 harness/tht/textutil.py delete mode 100644 prd/ThothII-prd.md delete mode 100755 scripts/preprocess-smoke.sh delete mode 100755 scripts/test-preprocess-compose-config.sh delete mode 100644 task-10-report.md diff --git a/.artifacts/reviews/task9-quality-audit-final5.md b/.artifacts/reviews/task9-quality-audit-final5.md deleted file mode 100644 index 665653b3..00000000 --- a/.artifacts/reviews/task9-quality-audit-final5.md +++ /dev/null @@ -1,66 +0,0 @@ -# Task 9 quality audit — final 5 - -**Scope:** the two blocking findings from `task9-quality-audit-final4.md` — unbound production -module graph at manual serve, and commit-addressed snapshots accepted without content identity at -render. Manual acceptance remains **PENDING**; no `VERDICT.md` was created. - -## Verdict: APPROVED for the two final integrity blockers - -### 1. Manual serve binds the complete `backend/dist` module graph, not only `server.js` - -`prepare` now builds a post-build manifest of every regular `backend/dist` file -(relative path, size, SHA-256, device, inode) and writes it as an exclusive `0600` record -(`installation/runtime/backend-dist.manifest.json`) inside the owned root; `ownership.json` -records that record's path/device/inode/size/SHA-256. `serve` revalidates the manifest record -identity and bytes, revalidates every distribution file against it (no-follow, single inode, -size and digest), and refuses before spawning. The manifest descriptor is passed to the child on -fd 4 together with the entrypoint on fd 3. The immutable preload parses the manifest, verifies -the entrypoint cross-digest, reads and hash-verifies **every** file at startup, caches the -verified bytes, and its load hook serves **only** those cached bytes for any import below -`backend/dist` (entry URL still served from the bound fd-3 bytes). A same-path regular -replacement of any imported dependency is therefore refused before `RUNNING` (serve-time -validation), refused at child startup (startup verification), or rendered harmless (cached -bytes), and the parent revalidates the full manifest at `RUNNING` publication and at `stop`. - -### 2. Renderer binds snapshot content to its commit identity - -The generated render command validates the bounded saved read/publish revisions, the -commit-addressed owned snapshot path, the installed Git HEAD, and the bounded -`snapshot.json` manifest of that commit: `head` equals the commit, `files[.yaml]` is the -SHA-256 of the snapshot bytes, the manifest revision binds commit/blob/snapshot path, the saved -revision blob equals the manifest blob, and `git rev-parse :workspaces/.yaml` plus -`git hash-object` of the snapshot bytes both equal that blob. It passes the expected digest as -`--snapshot-sha256`. The renderer re-reads the bounded `snapshot.json` (`head`, -`files[.yaml]` must equal the carried digest), opens the snapshot once with no-follow -semantics and bounded reads, renders only the digest-verified bytes, re-verifies around lease -publication, releases the lease in `finally`, and publishes no output on any refusal. - -## Deterministic regressions added - -- static regular replacement of an imported production dependency after `prepare` is refused, - no marker, no accepted PID record, no orphan; -- deterministic dependency check/load swap (`beforeSpawn` rename) is refused by the child's - startup verification, no marker, no PID record, no orphan; -- after `RUNNING`, a same-path regular dependency replacement is never executed: the loader - serves the verified cached bytes (health-visible source stays the original) and the marker is - absent; -- renderer refuses a same-path regular snapshot byte replacement against the carried digest and - manifest, with lease release and no output; -- renderer refuses manifest `head`, `files` digest, expected-digest, missing, and malformed - cases, with lease release and no output; -- wrapper refuses missing manifest, manifest head/digest/revision tampering, saved-revision blob - mismatch, Git blob mismatch, and snapshot-vs-Git-bytes mismatch, and passes the exact - `--snapshot-sha256` on the valid path (stub renderer records arguments). - -## Verification - -- `bash scripts/test-p1-manual-acceptance.sh` (backend build + both suites): **59 tests, 59 - pass, 0 fail**; no `8791/8792` listener and no `--p1-manual-nonce` process remain. -- `npx tsc --noEmit -p .` (backend): PASS. -- Real-repository `prepare` + `cleanup` cycle: 39 distribution files bound, entrypoint - cross-digest verified, owned root fully removed afterwards. -- Diff check: only the seven Task 9 paths are touched; no Task 8 file was modified. -- This report and the implementation contain no fixture secret or canary values. - -Manual acceptance remains **PENDING** by design; the walkthrough and human verdict are -unchanged. diff --git a/.artifacts/task-15/automated-gates.json b/.artifacts/task-15/automated-gates.json deleted file mode 100644 index 80664d7a..00000000 --- a/.artifacts/task-15/automated-gates.json +++ /dev/null @@ -1,282 +0,0 @@ -{ - "schema": "thothii-task4-certification-v1", - "generated_on": "2026-08-18", - "started_at_utc": "2026-08-18T14:16:40Z", - "ended_at_utc": "2026-08-18T14:20:10Z", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "source_immutability": { - "status": "PASS", - "tracked_changes_after_freeze": false, - "allowed_untracked": [".playwright-cli/", ".thothctl/"] - }, - "source_commits": { - "task4_candidate": "b31b27e5845ffd3adf311429367319beaba263c7", - "task1": "d43738eeae6d14bb5e470093058b069a983f5372", - "task2": "5f9a3ae066a060b43a11a959b60a1efadd1c2425", - "task3": "0d8e707533fada938c99eb06f8457150e7ef2b40", - "task3_follow_up": "b31b27e5845ffd3adf311429367319beaba263c7", - "fix_round_1_source": "10cd66fe6a5b484a4dc569326a228c1c5484a5d4", - "fix_round_2_source": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "historical_task15_final": "74b062f1a737103524cbe706346cfd65f87cdfd1" - }, - "versions": { - "node_contract": "v24.16.0", - "node_host_default": "v25.6.1", - "go": "go1.26.5", - "pi": "0.80.3" - }, - "retained_report": ".superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md", - "task4_report": ".superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md", - "fix_round_2_report": ".superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md", - "workflow": { - "run_id": "32147345625", - "url": "https://github.com/mptyl/ThothII/actions/runs/32147345625", - "event": "workflow_dispatch", - "head_sha": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "status": "completed", - "conclusion": "failure", - "windows_job": { - "name": "Windows clone and Compose contract", - "job_id": "95744249248", - "url": "https://github.com/mptyl/ThothII/actions/runs/32147345625/job/95744249248", - "conclusion": "failure", - "native_step": "Run native Windows retained-capability tests", - "native_step_conclusion": "success", - "command": "go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1", - "requested_packages": ["internal/safeio", "internal/backup", "internal/authstorage"], - "executed_packages": ["internal/safeio", "internal/backup", "internal/authstorage"], - "not_executed_packages": [], - "package_results": { - "internal/safeio": "PASS (22.058s)", - "internal/backup": "PASS (7.161s)", - "internal/authstorage": "PASS (16.088s)" - }, - "failed_step": "Verify Windows clone contract", - "failure_category": "baseline_powershell_parser", - "failure_detail": "scripts/test-windows-clone-contract.ps1:208 parses $remoteYaml: as an invalid variable reference" - }, - "lf_compose_docs_typescript_job": { - "name": "LF, Compose, docs, and TypeScript", - "job_id": "95744249458", - "url": "https://github.com/mptyl/ThothII/actions/runs/32147345625/job/95744249458", - "conclusion": "failure", - "failed_step": "Verify Compose and installation contracts", - "category": "baseline_ci_contract", - "detail": "unified Compose contract passed; test-no-deployment-coupling-scope.sh stopped on TMPDIR: unbound variable", - "downstream_steps": "skipped" - }, - "linux_docker_job": { - "name": "Linux Docker deployment and rollback", - "job_id": "95744249354", - "url": "https://github.com/mptyl/ThothII/actions/runs/32147345625/job/95744249354", - "conclusion": "failure", - "failed_step": "Run unified deployment smoke", - "category": "infrastructure_prerequisite", - "detail": "Task 13 smoke failed before deployment because rg is required", - "cleanup": "PASS", - "image_manifest": "not_generated" - }, - "windows_docker_startup_job": { - "name": "Native Windows Docker Desktop/WSL2 startup", - "job_id": "95744250450", - "url": "https://github.com/mptyl/ThothII/actions/runs/32147345625/job/95744250450", - "status": "NOT_RUN", - "classification": "BLOCKED", - "workflow_conclusion": "skipped", - "reason": "workflow conditions skipped the job; no Windows Docker Desktop/WSL2 command executed" - } - }, - "docker_image_evidence": { - "authentication_smoke": { - "status": "PASS", - "docker_images": [], - "reason": "no_docker_images_exercised" - }, - "unified_docker_smoke": { - "status": "FAIL", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "run_id": "32147345625", - "workflow_job_id": "95744249354", - "manifest": ".artifacts/task-15/unified-docker-images.json", - "reason": "workflow attempt stopped before deployment because rg is required", - "cleanup": "PASS", - "images": 0, - "historical": { - "status": "PASS", - "source_commit": "74b062f1a737103524cbe706346cfd65f87cdfd1", - "run_id": "20260818070637-66409-30058", - "manifest_sha256": "9c8dec4546909fd93799dbcf374bcb3a89bc46cfe0fd482472c0cbe757ddf5b6", - "images": 5, - "cleanup": "PASS" - } - } - }, - "gates": { - "posix_registry_ownership": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "evidence": "backend Node 24 full suite including local-registry ownership coverage" - }, - "stagearchive_unix_retained_capability": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "evidence": "focused safeio/backup tests, Go race suite, and Unix ancestor-swap coverage" - }, - "windows_stagearchive_retained_capability": { - "status": "PASS", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "evidence": "native Windows backup package passed, including the two-file shared retained-root staging test" - }, - "windows_claim_retained_capability": { - "status": "PASS", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "evidence": "native Windows safeio and authstorage packages passed concurrent claim/consume coverage" - }, - "workflow_lf_compose_docs_typescript": { - "status": "FAIL", - "classification": "baseline_ci_contract", - "reason": "TMPDIR was unset after the unified Compose contract passed" - }, - "workflow_linux_docker": { - "status": "FAIL", - "classification": "infrastructure_prerequisite", - "reason": "runner did not provide rg; cleanup proof passed and no image manifest was generated" - }, - "go_security_build": { - "status": "PASS", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "focused_packages": 3, - "race_packages": 18, - "focused_test": "PASS", - "race": "PASS", - "vet": "PASS", - "host_build": "PASS" - }, - "windows_cross_compile": { - "status": "PASS", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "focused_test_packages": 3, - "cli_build": "PASS", - "execution": "cross_compile_only_not_native_execution" - }, - "backend_node24": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "node": "v24.16.0", - "files": 76, - "tests": 1092, - "typecheck": "PASS", - "build": "PASS", - "note": "an initial full run had one workspace-registry timeout; focused rerun and complete rerun passed" - }, - "frontend_node24": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "node": "v24.16.0", - "files": 61, - "tests": 444, - "typecheck": "PASS", - "build": "PASS" - }, - "authentication_and_f1_smoke": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "node": "v24.16.0", - "filtered_e2e": "1 passed", - "sentinel_leak_scan": "PASS" - }, - "harness_pytest": { - "status": "FAIL", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7", - "passed": 951, - "failed": 1, - "skipped": 4, - "subtests": 232, - "failure": "test_column_decisions::test_f4_emits_column_types: workflow.yaml not found from harness test cwd" - }, - "authentication_docs": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7" - }, - "shell_syntax": { - "status": "PASS", - "source_commit": "b31b27e5845ffd3adf311429367319beaba263c7" - }, - "authentication_smoke_runtime": { - "status": "PASS", - "node": "v24.16.0", - "sentinel_leak_scan": "PASS" - }, - "compose_default": { - "status": "FAIL", - "reason": "required THT_WORKSPACE_GIT_REMOTE was not available" - }, - "compose_unified": { - "status": "FAIL", - "reason": "compose.unified.yaml is absent from the frozen source" - }, - "unified_docker_smoke": { - "status": "FAIL", - "source_commit": "2a9359071257f9b8a71d36ec2bbb25b161003f81", - "workflow_run_id": "32147345625", - "reason": "remote workflow attempted the smoke but stopped before deployment because rg is required", - "cleanup": "PASS", - "image_manifest": "not_generated" - }, - "ruff": { - "status": "FAIL", - "errors": 192, - "classification": "known_baseline" - }, - "mkdocs_strict": { - "status": "NOT_RUN", - "classification": "BLOCKED", - "historical_status": "FAIL", - "historical_warnings": 69 - }, - "canonical_install_docs": { - "status": "NOT_RUN", - "classification": "BLOCKED", - "historical_status": "FAIL" - }, - "workspace_install_docs": { - "status": "NOT_RUN", - "classification": "BLOCKED", - "historical_status": "FAIL" - }, - "pi_user_auth_compose": { - "status": "NOT_RUN", - "classification": "BLOCKED", - "historical_status": "FAIL" - }, - "deployment_coupling": { - "status": "NOT_RUN", - "classification": "BLOCKED", - "historical_status": "FAIL" - }, - "l2": { - "status": "PENDING", - "reason": "configured secret layout unavailable; gate not run after stop" - }, - "manual_psd": { - "status": "PENDING", - "reason": "approved real identity/access unavailable; gate not run after stop" - }, - "provider_readiness": { - "status": "PENDING", - "reason": "provider prerequisite unavailable; gate not run after stop" - } - }, - "review": { - "original_important_findings_resolved": 3, - "fix_round_2_important_lifecycle": "ADDRESSED", - "fix_round_2_minor_windows_diagnostics": "ADDRESSED", - "verdict": "PASS", - "reason": "the lifecycle controller is bounded and cancellation-aware with cancel, bounded join, and lock-release proof; the temporary Windows diagnostic matrix is removed; exact-source native safeio, backup, and authstorage all pass" - }, - "remediation_status": "PASS", - "release_complete": false, - "authentication_implementation_complete": true, - "release_readiness": "FAIL", - "release_readiness_pending_external_gates": true -} diff --git a/.artifacts/task-15/unified-docker-images.json b/.artifacts/task-15/unified-docker-images.json deleted file mode 100644 index 4cbfd1fa..00000000 --- a/.artifacts/task-15/unified-docker-images.json +++ /dev/null @@ -1,54 +0,0 @@ -{ - "gate": "unified-deployment-smoke", - "status": "pass", - "source_commit": "74b062f1a737103524cbe706346cfd65f87cdfd1", - "run_id": "20260818070637-66409-30058", - "images": [ - { - "id": "sha256:2d7b19491c7eb8c119c3cedb390aaeb2ff5593f6fc43ab66c317565560da6d7d", - "roles": [ - "compose-runtime", - "fixture-runtime" - ], - "repo_digests": [ - "sha256:2d7b19491c7eb8c119c3cedb390aaeb2ff5593f6fc43ab66c317565560da6d7d" - ] - }, - { - "id": "sha256:3b6c31a5d8f8fc58fa3233391b6175bd2fbc793eebb44d5e285ecc6e02e9e687", - "roles": [ - "compose-runtime" - ], - "repo_digests": [ - "sha256:3b6c31a5d8f8fc58fa3233391b6175bd2fbc793eebb44d5e285ecc6e02e9e687" - ] - }, - { - "id": "sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a", - "roles": [ - "compose-runtime" - ], - "repo_digests": [ - "sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a" - ] - }, - { - "id": "sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c", - "roles": [ - "compose-runtime" - ], - "repo_digests": [ - "sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c" - ] - }, - { - "id": "sha256:c3cbe1cc1aa588a64951ac6286e0df7b27fe2e6324b1001c619bb358770c0178", - "roles": [ - "rollback-candidate" - ], - "repo_digests": [ - "sha256:c3cbe1cc1aa588a64951ac6286e0df7b27fe2e6324b1001c619bb358770c0178" - ] - } - ] -} diff --git a/.claude/launch.json b/.claude/launch.json deleted file mode 100644 index 61be3335..00000000 --- a/.claude/launch.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "version": "0.0.1", - "configurations": [ - { - "name": "replay", - "runtimeExecutable": "node", - "runtimeArgs": ["tools/replay/server.mjs"], - "port": 5333 - } - ] -} diff --git a/.dockerignore b/.dockerignore index 492b9eef..7ac93658 100644 --- a/.dockerignore +++ b/.dockerignore @@ -27,5 +27,3 @@ coverage/ data/ sessions/ workspace-registry/ -# docs/site (mkdocs build) — non necessari nelle immagini -docs/superpowers/plans diff --git a/.github/workflows/deployment.yml b/.github/workflows/deployment.yml index 735f0207..84b10285 100644 --- a/.github/workflows/deployment.yml +++ b/.github/workflows/deployment.yml @@ -50,7 +50,6 @@ jobs: bash scripts/test-no-deployment-coupling-scope.sh bash scripts/test-compose-secret-policy.sh bash scripts/test-no-deployment-coupling.sh - bash scripts/test-preprocess-compose-config.sh bash scripts/test-verify-workspace-install-docs.sh git diff --check - name: Assert clean checkout before release trust bootstrap diff --git a/.gitignore b/.gitignore index 604924df..8af7af0e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,8 +5,6 @@ ChironeWp3/ Thoth/ -# === Visual companion brainstorming artifacts (local-only) === -.superpowers/ .worktrees/ .tht/ diff --git a/.kilo/kilo.jsonc b/.kilo/kilo.jsonc deleted file mode 100644 index cc2fb594..00000000 --- a/.kilo/kilo.jsonc +++ /dev/null @@ -1,7 +0,0 @@ -{ - "$schema": "https://app.kilo.ai/config.json", - "indexing": { - "vectorStore": "qdrant", - "model": "sentence-transformers/all-minilm-l12-v2" - } -} \ No newline at end of file diff --git a/.superpowers/sdd/2026-08-03-diagnostic-contract-extension/task-3-report.md b/.superpowers/sdd/2026-08-03-diagnostic-contract-extension/task-3-report.md deleted file mode 100644 index 246794e4..00000000 --- a/.superpowers/sdd/2026-08-03-diagnostic-contract-extension/task-3-report.md +++ /dev/null @@ -1,105 +0,0 @@ -# Task 3 — Diagnostic contract remediation report - -Date: 2026-08-04 - -## Scope - -This remediation is limited to the four approved review findings for the workspace diagnostic -extension. It does not add registry routes, change workspace publication, alter session startup, -or expand transport support. - -## Changes - -1. `RuntimeBindings` now has an explicit `vectorWriter` binding. The new - `resolveRuntimeBindings()` resolves DWH, vector reader, vector writer, and embedding bindings - together. The diagnoser takes the writer credential only from `bindings.vectorWriter`, never - from vector-reader values. -2. Direct PostgreSQL and SSH-tunnelled direct probes accept an absent CA binding while retaining - certificate verification through the runtime system trust store. A supplied CA still uses - verified private-CA trust. REST private-CA refusal is unchanged. -3. A reversible vector probe now requires an authenticated POST declaration with a response map - containing `operation`. The adapter requires the successful JSON response to echo `create` or - `remove` respectively, so an arbitrary 2xx or an upsert-only response cannot activate the - write probe. -4. For DWH and vector REST diagnostics declared with `auth: none`, the resolver no longer - requires an API-key file and the adapter sends no credential. Credential-backed diagnostics - continue to require their local secret file. - -## TDD evidence - -The first focused RED run failed for the intended missing behavior: - -- `resolveRuntimeBindings is not a function` for unauthenticated resolver bindings; -- schema accepted a reversible probe without a response contract; and -- existing diagnostic fixtures rejected the new `response` declaration until schema support was - implemented. - -The focused GREEN run passed `43/43` tests across: - -- `test/workspaces-bindings.test.ts` -- `test/workspaces-schema.test.ts` -- `test/workspaces-diagnostics.test.ts` - -The regression coverage includes resolver-to-diagnoser writer propagation without manually -inserting the writer key into vector-reader bindings, no-CA direct/SSH system-trust requests, -operation-echo validation for create/remove, and `auth: none` bindings without secret files. - -## Documentation and design - -- `docs/workspace-diagnostic-protocol.md` now documents the verified system-trust fallback, - no-secret `auth: none` behavior, and required reversible response contract. -- `docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md` now records the same - response, CA, SSH, and authentication rules. - -## Final verification - -The initial sandboxed full suite could not bind its local SSE listener (`listen EPERM: -operation not permitted 127.0.0.1`). It was rerun unchanged with local-listener permission. - -```text -backend: npx vitest run -31 test files passed; 329 tests passed - -backend: npx tsc --noEmit -p . -exit 0 - -repository: git diff --check -exit 0 -``` - -Expected test harness stderr from existing Pi/process failure-path tests remained present; no test -failed and no diagnostic secret was emitted. - -## Blockers - -None. - -## Round 2 remediation - -The final review found two remaining contract gaps. The binding resolver already treated -`auth: none` as credential-free, but the runtime renderer and diagnostic connector still required -the API-key file. Rendering and connector construction now make that requirement conditional on -the declared REST authentication mode, so a DWH/vector `auth: none` workspace passes resolver, -runtime rendering, and diagnostics with no API-key file. - -SSH forwarding previously changed the PostgreSQL connection host to `127.0.0.1` without retaining -the original target for TLS hostname validation. Forwarded probes now carry `SSH_TARGET_HOST` as -`tlsServername` into the PostgreSQL TLS options; private CA and verified system trust behavior are -unchanged. - -TDD RED: the new end-to-end no-key test failed at the unconditional runtime -`API_KEY_FILE` requirement, while the SSH test showed no `tlsServername` on the loopback probe or -database-client request. TDD GREEN: the focused backend workspace tests passed `40/40`. - -Round 2 final verification: - -```text -backend: npx vitest run -31 test files passed; 332 tests passed - -backend: npx tsc --noEmit -p . -exit 0 - -repository: git diff --check -exit 0 -``` diff --git a/.superpowers/sdd/2026-08-03-git-workspace-registry/task-7-report.md b/.superpowers/sdd/2026-08-03-git-workspace-registry/task-7-report.md deleted file mode 100644 index 53111d0d..00000000 --- a/.superpowers/sdd/2026-08-03-git-workspace-registry/task-7-report.md +++ /dev/null @@ -1,101 +0,0 @@ -# Task 7 report — revision-pinned sessions - -## Delivered - -- New-session requests may carry `workspaceId`, provider, model, and thinking. The backend - resolves the active operational registry revision, enforces its LLM policy, and persists the - workspace ID/revision with the selected LLM settings. -- The harness manifest and `tht session new` support the optional, backward-compatible - `workspace_id` and `workspace_revision` fields. -- Resume resolves the manifest's retained snapshot, including after later registry publication. - A missing retained revision returns a sanitized `workspace_revision_unavailable` response. - Legacy manifests retain the prior workspace behavior and are marked with a visible warning on - `GET /sessions/:id`. -- `/settings` is now a non-mutating compatibility endpoint: installation defaults remain - readable, while anonymous workspace/provider/model/thinking selections are no longer written - to backend settings or principal preferences. - -## TDD evidence - -- RED: `npx vitest run test/routes-sessions.test.ts test/routes-settings.test.ts` failed for the - new immutable-snapshot and no-settings-mutation assertions; the manifest test failed because - `new_session_manifest` did not accept workspace revision fields. -- GREEN: `npx vitest run test/tht-runner.test.ts test/routes-sessions.test.ts test/routes-settings.test.ts && npx tsc --noEmit -p .` - completed with 97 passing tests and a clean type check. -- GREEN: `THT_HOME=/private/tmp/thothii-task7-home .venv/bin/pytest tests/test_session_documents.py tests/test_session_mutations.py -q` - completed with 22 passing tests. -- `git diff --check` completed cleanly. - -## Review fixes — round 3 - -- The active registry snapshot that located a session now remains the authorization and mutation - config for response, steer, events, close/delete, archive/group/rename, documents, and detail. - A pruned historical revision cannot block an already-located session's active lifecycle. -- Only Resume resolves the retained pinned descriptor because Pi needs that immutable config to - restart safely. A pruned pin therefore returns the existing sanitized - `workspace_revision_unavailable` 409 solely for Resume. - -### Round 3 verification - -- RED: with a manifest found through an active registry snapshot and `readPinned` forced to fail, - `POST /sessions/:id/response` returned 409 instead of forwarding the active gate response. -- GREEN: `npx vitest run test/routes-sessions.test.ts test/tht-runner.test.ts test/routes-settings.test.ts && npx tsc --noEmit -p .` - — 102 tests passed with a clean type check. The regression confirms response, close, and delete - use the locating snapshot without calling `readPinned`, while Resume returns a sanitized 409. -- `git diff --check` completed cleanly. - -## Review fixes — round 2 - -- Lifecycle authorization no longer selects the installation-default workspace. The backend now - finds each session by querying every operational registry snapshot with the authenticated - principal, preserving RLS ownership concealment. -- After locating the manifest, durable pinned sessions resolve their retained descriptor before - any lifecycle mutation/reopen. Legacy sessions continue using the locating registry snapshot. -- Session listing aggregates the owner-visible rows from all operational registry snapshots; - detail, response, steer, resume, events, documents, and lifecycle mutations use the same - server-side locator. No route depends on browser-local workspace state. - -### Round 2 verification - -- RED: the new cross-workspace route integration test created a B session while installation - default A was selected, then demonstrated that `GET /sessions` returned an empty list. -- GREEN: `npx vitest run test/routes-sessions.test.ts test/tht-runner.test.ts test/routes-settings.test.ts && npx tsc --noEmit -p .` - — 101 tests passed with a clean type check. The integration test covers create B, list, detail, - response, and resume through B's pinned descriptor while default A remains configured. -- Full backend suite: 342 tests passed. The remaining 7 tests require binding `127.0.0.1` and - fail in this sandbox with `listen EPERM: operation not permitted`; no application assertion - failed. The focused typecheck above passed. -- `git diff --check` completed cleanly. - -## Verification note - -The unscoped backend suite was also run. The Task 7 code regressions in `test/tht-runner.test.ts` -were fixed; the remaining failures were existing sandbox restrictions on tests that listen on -`127.0.0.1` (`listen EPERM: operation not permitted` in SSE/e2e health tests), not application -assertions. - -## Review fixes — round 1 - -- Every new session now resolves `workspaceId` through the registry; an omitted value uses the - configured installation default and persists both the resolved ID and revision. Callers cannot - bypass revision pinning by supplying a workspace ID. -- Browser-local preferences now migrate once from the read-only legacy settings response and hold - workspace, provider, model, and thinking. Session creation includes those selections, including - direct entry points that run before the composer mounts. The frontend no longer `PUT`s shared - settings. -- The settings compatibility endpoint honors a stored installation workspace before falling back - to the first workspace configuration. -- Resume rejects finalized and archived sessions before looking up any pinned snapshot, preserving - the read-only response even when a historical snapshot is unavailable. - -### Review verification - -- RED: the added backend tests failed for omitted-default pinning, read-only resume ordering, and - stored-default precedence; the added frontend preference tests failed because preferences were - neither stored nor included in session requests. -- GREEN: `npx vitest run test/tht-runner.test.ts test/routes-sessions.test.ts test/routes-settings.test.ts && npx tsc --noEmit -p .` - — 100 tests passed with a clean type check. -- GREEN: `npx vitest run && npx tsc -b` — 332 frontend tests passed with a clean type check. -- GREEN: `THT_HOME=/private/tmp/thothii-task7-home .venv/bin/pytest tests/test_session_documents.py tests/test_session_mutations.py -q` - — 22 tests passed (one existing testcontainers deprecation warning). -- `git diff --check` completed cleanly. diff --git a/.superpowers/sdd/2026-08-03-git-workspace-registry/task-9-report.md b/.superpowers/sdd/2026-08-03-git-workspace-registry/task-9-report.md deleted file mode 100644 index 03b48d80..00000000 --- a/.superpowers/sdd/2026-08-03-git-workspace-registry/task-9-report.md +++ /dev/null @@ -1,73 +0,0 @@ -# Task 9 report — Workspace Management CRUD page - -## Delivered - -- Added the Workspace management dialog, launched from the persistent right sidebar and the - Model activity header without touching live-session/SSE state. -- Added a workspace list/detail editor for General, DWH, Semantic index, LLM policy, - Installation requirements, and Git status/history. -- Added browser-only New, Edit, Duplicate, Save draft, and Delete-draft workflows. A deletion - draft stores only ID and immutable revision references; publication remains a Task 10 action. -- Used closed native controls for languages, engines, transports, distance metrics, embedding - providers, and selectable default models. Free values have client-side, accessible errors. -- Made semantic-index dimensions atomic: one editor field always writes the same value to the - vector-store and embedding contracts. -- Added Validate and Test-on-this-installation actions. They display sanitized code/message - diagnostics only; neither action exposes or stores credentials, secrets, or raw response bodies. -- Explicitly excluded publish, pull, import, and export user flows from this task. - -## TDD evidence - -- RED: `npx vitest run src/shell/WorkspaceManager.test.tsx src/shell/WorkspaceEditor.test.tsx` - failed because the manager and editor modules did not exist. -- GREEN: focused manager/editor/AppShell coverage passed after the implementation. -- RED: a deletion-draft persistence regression failed with - `Cannot read properties of undefined (reading 'save')` before the sanitized draft store was added. -- GREEN: the draft-store and manager tests passed once deletion intent persisted locally. - -## Verification - -Executed from `frontend/`: - -```text -npx vitest run -50 test files passed, 358 tests passed -npx tsc -b -exit 0 -``` - -`git diff --check` passed before commit. No workspace secret value, secret-file path, raw -diagnostic body, publish call, import flow, or export flow was introduced. - -## Fix round 1 - -### Root causes and fixes - -- The original duplicate proposal appended `-copy` and then truncated at 63 characters. For an - already-maximal ID, truncation could remove the suffix and reproduce the immutable source ID. - The proposal now reserves suffix space and falls back to a distinct `-2` suffix when a maximal - source already ends in `-copy`. -- `dwh.timeout_ms` was rendered as a positive numeric field but was absent from the client - validation map. It now has the same immediate accessible error treatment as other numeric - fields, so a rejected save never reaches the manager’s saved-draft toast. -- Registry status, workspace list, and selected-detail React Query failures were rendered as - loading, empty, or unselected states. Each now has a named alert and a retry control, distinct - from its corresponding loading and empty state. - -### TDD evidence - -- RED: max-length duplication retained the original 63-character ID; the timeout field produced - no alert; and each of the three failed queries had no accessible retry control. -- GREEN: the focused manager/editor tests passed **12/12**, covering a valid changed duplicate - proposal, rejected zero timeout with no save toast, and status/list/detail retry recovery. - -### Verification - -Executed from `frontend/`: - -```text -npx vitest run -50 test files passed, 364 tests passed -npx tsc -b -exit 0 -``` diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-11-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-11-report.md deleted file mode 100644 index b9c381de..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-11-report.md +++ /dev/null @@ -1,180 +0,0 @@ -# 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 -``` diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-12-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-12-report.md deleted file mode 100644 index 1ea763f5..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-12-report.md +++ /dev/null @@ -1,43 +0,0 @@ -# Task 12 Report — Remove unreachable pgvector runtime code - -Status: completed - -Summary: -- Proved the retired pgvector runtime had no remaining operational adapter call sites after migration by re-running the required grep; only the packaging assertion still mentions `migrations/vector`. -- Removed the obsolete pgvector/HTTP/direct vector runtime modules, vector SQL migrations, and their affected runtime tests. -- Kept the operational semantic path on Qdrant and migrated the remaining runtime callers to that path. -- Kept `psycopg2-binary` because DWH direct PostgreSQL and session PostgreSQL code still depend on it. - -Implementation notes: -- Extracted shared collection/kind validation into `harness/tht/adapters/vector/_shared.py` so `QdrantVectorStore` no longer depends on the deleted pgvector module. -- Simplified `build_vector_store()` to return only `QdrantVectorStore`. -- Migrated vector/evidence/memory CLI paths away from legacy pgvector loaders and REST vector clients. -- Updated packaging coverage so the built wheel asserts session SQL migrations are present and vector SQL migrations are absent. - -Verification: -- `cd harness && .venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py tests/test_semantic_kind_isolation.py tests/test_vector_migration_packaging.py -q` -- `cd harness && .venv/bin/pytest tests/test_adapter_factory.py tests/test_solved_search_cli.py -q` -- `cd harness && .venv/bin/python -c "import tht.cli, tht.adapters.factory, tht.adapters.vector, tht.vectorstore.reader"` -- `cd harness && uv build` -- `harness/.venv/bin/ruff check harness/tests/test_adapter_factory.py harness/tests/test_solved_search_cli.py harness/tests/test_vector_migration_packaging.py harness/tests/test_vector_port_contract.py harness/tht/adapters/factory.py harness/tht/adapters/vector/__init__.py harness/tht/adapters/vector/_shared.py harness/tht/adapters/vector/qdrant.py harness/tht/cli/evidence_cmd.py harness/tht/cli/memory_cmd.py harness/tht/cli/search_cmd.py harness/tht/cli/vector_cmd.py harness/tht/solved.py harness/tht/vectorstore/reader.py` -- `git diff --check` - -Notes / concerns: -- Repository-wide `harness/.venv/bin/ruff check .` still reports many pre-existing findings outside this task’s touched files; it is not clean on this branch baseline. -- Some legacy config compatibility parsing still exists outside the deleted runtime path. This task removed the unreachable runtime/migration code without broad config-schema refactoring. - -## Fix round 1 evidence - -Changes: -- Removed dead `vector migrate` registration from `harness/tht/cli/__init__.py` and deleted `harness/tht/cli/vector_migrate_cmd.py`. -- Added CLI regressions proving `vector migrate` is absent while `vector init` and `vector index-schema` remain available. -- Restored the accidentally removed non-vector regressions by moving report coverage into `harness/tests/test_report.py` and restoring the taskdoc promoted-table slicing check in `harness/tests/test_taskdoc.py`. -- Reworded surviving active help/docstrings away from pgvector-specific wording in the touched Qdrant-backed command surface. - -Verification: -- `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py tests/test_report.py tests/test_taskdoc.py tests/test_vector_migration_packaging.py -q` -- `cd harness && .venv/bin/python -c "from typer.testing import CliRunner; from tht.cli import app; r=CliRunner().invoke(app, ['vector','--help']); assert r.exit_code == 0, r.output; assert 'migrate' not in r.output; r=CliRunner().invoke(app, ['vector','migrate','--help']); assert r.exit_code != 0, r.output; print('cli-help-ok')"` -- `cd harness && .venv/bin/python -c "import tht.cli, tht.cli.vector_cmd, tht.report, tht.taskdoc; print('imports-ok')"` -- `cd harness && uv build` -- `harness/.venv/bin/ruff check harness/tests/test_qdrant_cli_commands.py harness/tests/test_report.py harness/tests/test_taskdoc.py harness/tests/test_vector_migration_packaging.py harness/tht/cli/__init__.py harness/tht/cli/search_cmd.py harness/tht/cli/vector_cmd.py harness/tht/cli/memory_cmd.py harness/tht/solved.py` -- `git diff --check` diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-13-implementation.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-13-implementation.md deleted file mode 100644 index 9f798a3a..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-13-implementation.md +++ /dev/null @@ -1,175 +0,0 @@ -# Task 13 Implementation Report - -## Status - -DONE_WITH_CONCERNS - -## Changes - -- Updated stale harness/backend/frontend tests and fixtures to the Task 13 internal Qdrant/Ollama contract. -- Made `deploy/workspaces/psd.yaml.example` generic while preserving schema-v3 Qdrant/Ollama shape. -- Fixed `scripts/workspace-registry-smoke.sh` to pass the required legacy migration `--collection` and prove exact Docker cleanup, including its smoke image. -- Updated `PROJECT_STATE.md` with only evidence observed in this run. - -Changed files: - -- `PROJECT_STATE.md` -- `backend/test/routes-workspaces.test.ts` -- `backend/test/workspace-runtime-handoff.test.ts` -- `backend/test/workspaces-contracts.test.ts` -- `backend/test/workspaces-git-repository.test.ts` -- `deploy/workspaces/psd.yaml.example` -- `frontend/src/shell/NewSessionDialog.test.tsx` -- `harness/tests/test_adapter_command_regressions.py` -- `harness/tests/test_workspace.py` -- `scripts/task13-runtime-fixture-check.ts` -- `scripts/test-verify-workspace-install-docs.sh` -- `scripts/workspace-registry-smoke.sh` - -## Verification - -Deterministic gates: - -- `cd harness && .venv/bin/pytest -q && .venv/bin/ruff check .` - - Initial red: 2 harness pytest failures. - - After fixture fixes: harness pytest passed `819 passed, 4 deselected, 74 warnings in 27.73s`. - - Ruff still failed with `Found 220 errors`; treated as existing unrelated debt. - - Touched harness files verified clean with `cd harness && .venv/bin/ruff check tests/test_adapter_command_regressions.py tests/test_workspace.py && .venv/bin/pytest -q tests/test_adapter_command_regressions.py::test_solved_index_writes_through_writer_only_factory_store tests/test_workspace.py::test_load_workspace_expands_env_vars`: `All checks passed!` and `2 passed, 2 warnings in 0.14s`. -- `cd backend && npx vitest run && npx tsc --noEmit -p . && npm run build` - - Initial red: 4 backend Vitest failures. - - After fixes: `Test Files 39 passed (39)`, `Tests 464 passed (464)`, TypeScript passed, build passed. -- `cd frontend && npx vitest run && npx tsc -b && npm run build` - - Initial red: 1 frontend Vitest failure. - - After fix: frontend Vitest passed `374/374`, TypeScript passed, build passed with Vite `built in 6.55s`. -- `git diff --check` - - Passed with no output. - -Focused reruns: - -- `cd backend && npx vitest run test/workspaces-migrate-legacy.test.ts test/workspaces-contracts.test.ts test/routes-workspaces.test.ts test/workspace-runtime-handoff.test.ts test/workspaces-git-repository.test.ts && cd .. && ./scripts/test-no-deployment-coupling.sh && ./scripts/verify-workspace-install-docs.sh --fixtures-only && git diff --check` - - `Test Files 5 passed (5)`, `Tests 35 passed (35)`. - - Coupling guard passed: `no active retired deployment or external semantic coupling found.` - - Install docs fixtures passed through `relative secret-source fixture rejected passed`. - -Deployment contracts: - -- `./scripts/test-default-compose.sh && ./scripts/test-unified-compose.sh && ./scripts/test-internal-semantic-compose.sh && ./scripts/test-no-deployment-coupling.sh && ./scripts/test-compose-secret-policy.sh && ./scripts/verify-workspace-install-docs.sh --fixtures-only` - - Passed. Output included: - - `default Compose contract passed.` - - `unified Compose contract passed.` - - `internal semantic Compose/script contracts passed.` - - `no active retired deployment or external semantic coupling found.` - - `Compose secret policy passed.` - - install-doc fixture checks through `relative secret-source fixture rejected passed`. - -Docker smokes: - -- `/usr/bin/time -p ./scripts/internal-semantic-smoke.sh` - - Passed: `Task 13 internal semantic smoke passed.` - - Cleanup proof: `no labeled containers, volumes, networks, or images remain for 20260808200245-83368-17823.` - - Duration: `real 217.34`. -- `/usr/bin/time -p ./scripts/workspace-registry-smoke.sh` - - Initial red: `usage: migrate-legacy --input --output --collection [--id ]`. - - After fix: `workspace registry smoke passed`. - - Cleanup proof: `no compose containers, volumes, networks, or image remain for thoth-workspace-registry-smoke-89671.` - - Duration: `real 9.93`. -- `/usr/bin/time -p ./scripts/unified-deployment-smoke.sh` - - Passed: `Task 13 full deployment smoke passed.` - - Cleanup proof: `no labeled containers, volumes, networks, or images remain for 20260808200706-85638-13391.` - - Duration: `real 125.57`. -- `/usr/bin/time -p ./scripts/thothctl-update-smoke.sh` - - Passed: `Task 13 update deployment smoke passed.` - - Cleanup proof: `no labeled containers, volumes, networks, or images remain for 20260808200918-87340-10404.` - - Duration: `real 85.40`. -- `/usr/bin/time -p ./scripts/server-deployment-smoke.sh` - - Passed: `Task 13 Linux server deployment smoke passed.` - - Cleanup proof: `no labeled containers, volumes, networks, or images remain for 20260808201047-88645-20675.` - - Duration: `real 55.99`. - -Final audit: - -- `rg -n "pgvector|local-vector|THT_VECTOR_|EMBEDDING_BASE_URL|openai_compatible|ollama_compatible" . --glob '!docs/plans/**' --glob '!docs/superpowers/**' --glob '!**/node_modules/**' --glob '!**/.venv/**' --glob '!**/.git/**'` - - Returned matches in legacy schema-v1/v2 support, migration tests, negative guards, historical notes, and older harness docs/code. - - This remains a concern: the audit is not clean under the brief's strict expected outcome. -- `git status --short` - - Before report/commit, contained only intentional Task 13 changes. - -## Image and Host Evidence - -- Host CPU: `Apple M4 Pro`. -- Host OS: `Darwin MacProM4-di-Marco.local 25.5.0 Darwin Kernel Version 25.5.0: Tue Jun 9 22:28:34 PDT 2026; root:xnu-12377.121.10~1/RELEASE_ARM64_T6041 arm64`. -- Docker server: `29.6.2 linux/arm64`. -- Verified pinned images: - - `qdrant/qdrant:v1.18.2@sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c`. - - `ollama/ollama:0.32.0@sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a`. -- Workspace registry smoke ephemeral image: - - Manifest list: `sha256:4d056bf2cb38d0e8ede91fbf121df1f9f18caee0d401581618ccef9ed8a55e73`. - - Config: `sha256:613f8fb28c0517adee4085f41bc447f2c3813b0fdbb7b26624bfb4cb192b6fd8`. - - Removed during cleanup. - -## Manual Gates - -- GPU exposure gate (`THOTH_ENABLE_EMBEDDING_GPU=1` on Linux): not executed in this run. -- Windows Docker Desktop startup/manual job: not executed in this run. - -## Commits - -- `4e810af` (`test: align qdrant ollama verification fixtures`) -- `7c09b98` (`docs: record qdrant ollama verification`) - -## Known Limitations - -- Broad harness Ruff remains existing unrelated debt: `Found 220 errors`. -- Final active-reference audit is not clean; it still finds legacy/negative-guard references outside explicit migration fixture files. -- Ephemeral Task 13 core/frontend image IDs from `internal-semantic-smoke.sh`, `unified-deployment-smoke.sh`, `thothctl-update-smoke.sh`, and `server-deployment-smoke.sh` were removed by exact cleanup and were not emitted in stdout; pinned Qdrant/Ollama digests and the workspace-registry smoke image digest were captured. - -## Fix Round 1 — reviewer findings - -Status: DONE - -Changes: - -- `scripts/workspace-registry-smoke.sh` now derives the smoke image reference from the already unique Compose project instead of using the global tag `thothii-workspace-registry-smoke:local`. -- The workspace-registry cleanup helpers remove and verify only the exact per-run image reference, plus Compose resources labeled with the exact project. -- Added deterministic self-test coverage in `backend/test/workspaces-migrate-legacy.test.ts` via `WORKSPACE_REGISTRY_SMOKE_SELF_TEST=image-cleanup-identity`; it stubs Docker and fails if cleanup touches same-repository foreign tags such as `:local` or another project tag. -- Updated active harness/testing/PRD docs and Python comments that still described the current semantic store as pgvector/vectordb. Preserved schema-v1/v2 and harness legacy compatibility fixtures. -- Updated `PROJECT_STATE.md` with fix-round smoke evidence and a precise, non-overclaiming audit limitation. - -Focused verification: - -- `cd backend && npx vitest run test/workspaces-migrate-legacy.test.ts` - - Passed: `7 passed`. -- `cd harness && .venv/bin/pytest -q tests/test_memory_save_one.py tests/test_adapter_command_regressions.py tests/test_solved_search_cli.py tests/test_search_pack.py` - - Passed: `22 passed, 14 warnings`. -- `cd harness && .venv/bin/ruff check tht/memory.py tht/search/__init__.py tht/workspace.py tht/vectorstore/store.py tests/test_memory_save_one.py tests/test_adapter_command_regressions.py tests/test_solved_search_cli.py` - - Passed: `All checks passed!` -- `bash -n scripts/workspace-registry-smoke.sh && WORKSPACE_REGISTRY_SMOKE_SELF_TEST=image-cleanup-identity bash scripts/workspace-registry-smoke.sh` - - Passed: `workspace registry smoke image cleanup identity self-test passed`. -- `./scripts/test-no-deployment-coupling.sh` - - Passed: `no active retired deployment or external semantic coupling found.` -- `./scripts/verify-workspace-install-docs.sh --fixtures-only` - - Passed through `relative secret-source fixture rejected passed`. -- `cd backend && npx tsc --noEmit -p .` - - Passed with no output. -- `/usr/bin/time -p ./scripts/workspace-registry-smoke.sh` - - Passed: `workspace registry smoke passed`. - - Built exact per-run tag: `thothii-workspace-registry-smoke:thoth-workspace-registry-smoke-thoth-workspace-registry-smoke-10vi3a-19157`. - - Manifest list: `sha256:715b943057929418cad4aa71806d9edbaf823555d19bda6b875297617463fd4a`. - - Config: `sha256:a566521981e08958aae9a12bfc7803bb5f3f835536b4bb8c39df8fcf26063161`. - - Cleanup proof: `no compose containers, volumes, networks, or image remain for thoth-workspace-registry-smoke-thoth-workspace-registry-smoke-10vi3a-19157.` - - Duration: `real 42.06`. - -Fix-round audit command: - -- `rg -n "pgvector|local-vector|THT_VECTOR_|EMBEDDING_BASE_URL|openai_compatible|ollama_compatible" . --glob '!docs/plans/**' --glob '!docs/superpowers/**' --glob '!**/node_modules/**' --glob '!**/.venv/**' --glob '!**/.git/**'` - -Categorized remaining hits: - -- Backend legacy parser/migration compatibility, kept deliberately non-operational for schema-v1/v2 descriptors: `backend/src/workspaces/schema.ts`, `types.ts`, `migrate-legacy.ts`, `runtime-renderer.ts`, `bindings.ts`, `contracts.ts`, `diagnostics.ts`. -- Backend negative guards and legacy fixture tests: `backend/test/workspaces-schema.test.ts`, `workspaces-migrate-v2-qdrant.test.ts`, `workspace-registry.test.ts`, `workspace-runtime-renderer.test.ts`, `workspaces-bindings.test.ts`, `workspaces-contracts.test.ts`, `workspaces-diagnostics.test.ts`, `workspaces-git-repository.test.ts`, `routes-workspaces.test.ts`, `routes-sessions.test.ts`, `provider-credentials.test.ts`. -- Secret/env scrub guards for retired variables: `backend/src/config.ts`, `backend/src/config/secret-bundle.ts`, `backend/src/pi/provider-credentials.ts`, `scripts/compose-with-preflight.sh`, `scripts/test-external-compose-lifecycle.sh`. -- Deployment negative guards and fixture-scope tests: `scripts/test-no-deployment-coupling.sh`, `scripts/test-no-deployment-coupling-scope.sh`, `scripts/test-preprocess-compose-config.sh`, `scripts/test-verify-workspace-install-docs.sh`, `scripts/verify-workspace-install-docs.sh`, `scripts/vector-rotate-bootstrap-password.sh`. -- Harness legacy config compatibility and fixtures: `harness/tht/config.py`, `harness/tht/config_compat.py`, `harness/tests/test_config_resources.py`, `harness/tests/l2/test_session_ablazione.py`, `harness/workspaces/tht.example.yaml`, `harness/workspaces/tht-test.yaml`. -- Retained off-repository migration SQL fixtures: `harness/scripts/create_vector_reader_rpc.sql`, `harness/scripts/create_vector_writer_rpc.sql`. -- Historical/reference notes, not active operator contracts: `brain/codebase/datamart-builder-deployment-gotchas.md`, `PROJECT_STATE.md`. -- Gitignored task report self-reference: `.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-13-implementation.md`. diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-2-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-2-report.md deleted file mode 100644 index 9f88efee..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-2-report.md +++ /dev/null @@ -1,165 +0,0 @@ -Task 2 report — Make collection ownership unique in the Git registry - -Summary - -- Implemented unique Qdrant collection ownership enforcement during registry snapshot activation. -- Registry session revision leases now reject `migration_required` descriptors. -- Legacy migration now requires an explicit target collection and emits schema v3 descriptors. -- Preserved active snapshot rollback behavior on invalid pulled snapshots. - -RED evidence - -Focused RED command from the brief: - -```bash -cd backend -npx vitest run test/workspace-registry.test.ts test/workspaces-migrate-legacy.test.ts \ - -t "collection|migration_required" -``` - -Observed failures before implementation: - -- `rejects duplicate schema v3 collection ownership and keeps the previous active snapshot` - - `registry.pull()` resolved instead of rejecting. -- `does not acquire a session revision lease for a migration_required workspace` - - `acquireSessionRevision()` resolved instead of rejecting. -- `migrates a legacy descriptor only with an explicit target collection into schema v3` - - received schema version `1` instead of `3`. -- `requires an explicit target collection for legacy migration` - - migration did not throw without a collection. - -GREEN evidence - -Focused GREEN command from the brief: - -```bash -cd backend -npx vitest run test/workspace-registry.test.ts test/workspaces-migrate-legacy.test.ts \ - -t "collection|migration_required" -``` - -Fresh result after implementation: - -- 2 files passed -- 4 tests passed -- 0 failures - -Additional verification run after final cleanup: - -```bash -cd backend -npx vitest run test/routes-workspaces.test.ts -npx vitest run -npx tsc --noEmit -p . -git diff --check -``` - -Fresh results: - -- `test/routes-workspaces.test.ts`: 7 passed -- full backend Vitest: 39 files passed, 454 tests passed -- backend typecheck: passed -- `git diff --check`: passed - -Changed files - -- `backend/src/workspaces/registry.ts` -- `backend/src/workspaces/migrate-legacy.ts` -- `backend/test/workspace-registry.test.ts` -- `backend/test/workspaces-migrate-legacy.test.ts` -- `backend/test/routes-workspaces.test.ts` - -Why one extra file changed - -- `backend/test/routes-workspaces.test.ts` needed updating because Task 1 made schema v3 the only operational descriptor shape, and the route test still assumed the old pre-Task-3 runtime behavior. Updating that expectation was necessary to keep the required backend suite verification meaningful. - -Implementation notes - -- Duplicate collection detection is enforced only for operational schema v3 descriptors by tracking `collection -> workspaceId` during activation. -- Duplicate failures are sanitized back to `workspace_invalid` / `Workspace repository content is invalid`. -- `acquireSessionRevision()` now fails closed for `migration_required` revisions. -- Legacy migration CLI now requires `--collection `. -- Legacy migration output is schema v3 with the fixed internal semantic contract: - - `vector_store.engine = qdrant` - - explicit `collection` - - embedding provider `ollama_internal` - - embedding model `qwen3-embedding:0.6b` - -self-review - -- Confirmed invalid pulled snapshots do not replace the previous active snapshot. -- Confirmed duplicate collection enforcement does not affect legacy migration-required descriptors. -- Confirmed create/update publication tests still pass with unique per-workspace collections. -- Confirmed no JSON stdout contract regressions in the migration CLI. -- Kept runtime/data mutation scope descriptor-only; no user workspace repo or Qdrant data changes. - -Concerns - -- No code concerns remaining for Task 2. -- One deliberate scope exception: a route test was updated to align with the already-established Task 1 / Task 3 fail-closed contract. - -Fix round 1 - -Scope - -- Restored meaningful route-level diagnoser coverage without reopening schema-v3 semantic runtime paths. -- Added direct schema-v2 registry coverage for `migration_required` listing and lease rejection. - -Covering test files - -- `backend/test/routes-workspaces.test.ts` -- `backend/test/workspace-registry.test.ts` - -RED command and output - -Command: - -```bash -cd backend -npx vitest run test/routes-workspaces.test.ts test/workspace-registry.test.ts -``` - -Observed result on top of `76bc94d` after adding the restored/new assertions: - -- 2 files passed -- 37 tests passed -- 0 failures - -Why no RED appeared: - -- The review items exposed missing/weakened coverage, not a production behavior bug. -- `/workspaces/:id/test` already reaches the diagnoser for resolvable legacy v2 descriptors. -- Schema-v3 `/workspaces/:id/test` already fails closed before diagnoser entry. -- Schema-v2 descriptors were already listed as `migration_required` and already rejected by `acquireSessionRevision()`. - -GREEN command and output - -Command: - -```bash -cd backend -npx vitest run test/routes-workspaces.test.ts test/workspace-registry.test.ts -npx tsc --noEmit -p . -``` - -Fresh results: - -- covering tests: 2 files passed, 37 tests passed -- backend typecheck: passed - -Changed files - -- `backend/test/routes-workspaces.test.ts` -- `backend/test/workspace-registry.test.ts` -- `.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-2-report.md` - -What changed - -- Split route coverage so `POST /workspaces/validate` still checks canonical validation independently. -- Restored route-level diagnoser coverage through a migration-required schema-v2 descriptor with resolvable legacy bindings. -- Added an explicit schema-v3 fail-closed regression for `POST /workspaces/:id/test`. -- Added a direct schema-v2 registry regression proving `list()` returns `migration_required` and `acquireSessionRevision()` rejects it. - -Concerns - -- No production concerns. This round only tightened coverage and corrected the weakened test expectation. diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-3-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-3-report.md deleted file mode 100644 index 82bb1f00..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-3-report.md +++ /dev/null @@ -1,132 +0,0 @@ -# Task 3 report — Remove external semantic bindings and render internal endpoints - -Date: 2026-08-08 - -## Scope - -Implemented backend-owned schema-v3 semantic runtime rendering so workspace descriptors and installation contracts remain free of external Qdrant/Ollama endpoints and credentials, while DWH bindings stay unchanged. - -## RED evidence - -Focused RED command: - -`cd backend && npx vitest run test/workspaces-contracts.test.ts test/workspaces-bindings.test.ts test/workspace-runtime-renderer.test.ts test/config.test.ts` - -Observed failures before implementation: - -- `config.test.ts` - - missing `internalQdrantUrl` - - missing `internalEmbeddingUrl` -- `workspaces-bindings.test.ts` - - schema v3 semantic binding resolution threw unsupported errors -- `workspace-runtime-renderer.test.ts` - - schema v3 runtime rendering threw `Schema version 3 runtime rendering is unsupported until the internal semantic runtime is implemented` - -## GREEN evidence - -Focused GREEN command: - -`cd backend && npx vitest run test/workspaces-contracts.test.ts test/workspaces-bindings.test.ts test/workspace-runtime-renderer.test.ts test/config.test.ts` - -Result: - -- 4 test files passed -- 36 tests passed - -Typecheck: - -`cd backend && npx tsc --noEmit -p .` - -Result: - -- passed - -Hygiene: - -- `git diff --check` passed - -## Files changed - -Listed-task files changed: - -- `backend/src/config.ts` -- `backend/src/workspaces/bindings.ts` -- `backend/src/workspaces/runtime-renderer.ts` -- `backend/test/config.test.ts` -- `backend/test/workspace-runtime-renderer.test.ts` -- `backend/test/workspaces-bindings.test.ts` -- `backend/test/workspaces-contracts.test.ts` - -Listed-task files inspected but not changed: - -- `backend/src/workspaces/contracts.ts` - -Unavoidable additional wiring changes: - -- `backend/src/app.ts` -- `backend/src/tht/tht-runner.ts` - -Reason: the new typed internal semantic runtime config had to flow from backend config into ephemeral harness config rendering at runtime. - -## Behavior delivered - -- schema-v3 installation contract exposes DWH bindings only -- schema-v3 binding resolution ignores external semantic env vars instead of sourcing runtime semantics from them -- runtime rendering for schema v3 emits backend-owned internal semantic endpoints: - - Qdrant: `http://qdrant:6333` - - Embedding: `http://embedding:11434` - - Model: `qwen3-embedding:0.6b` - - Dimensions: `1024` -- internal semantic URLs are validated to allow only `qdrant` / `embedding` / `localhost` / loopback hosts -- DWH transport/runtime behavior remains unchanged - -## Self-review - -- Confirmed schema-v3 contracts/docs no longer advertise VECTOR or EMBEDDING installation variables. -- Confirmed schema-v3 runtime output ignores injected external semantic endpoints from env bindings. -- Confirmed semantic endpoints are rendered only in the ephemeral backend-owned harness config path. -- Confirmed type wiring is explicit from `AppConfig` → `ThtRunner` → runtime renderer. - -## Concerns - -- Host validation currently permits both `http` and `https` on the allowed internal hosts. That keeps the configuration flexible, but if the installation contract intended `http` only, that restriction is not enforced here. - -## Fix round 1/5 - -Scope: - -- moved schema-v3 internal embeddings under `resources.embeddings` -- enforced `http`-only internal semantic URLs - -RED evidence: - -`cd backend && npx vitest run test/workspace-runtime-renderer.test.ts test/config.test.ts` - -Observed failures on `bc8afe0`: - -- `workspace-runtime-renderer.test.ts` - - schema-v3 output omitted `resources.embeddings` - - schema-v3 still exposed top-level `embeddings` -- `config.test.ts` - - `https://qdrant:6333` was accepted - -GREEN evidence: - -`cd backend && npx vitest run test/workspace-runtime-renderer.test.ts test/config.test.ts` - -Result: - -- 2 test files passed -- 16 tests passed - -Typecheck: - -`cd backend && npx tsc --noEmit -p .` - -Result: - -- passed - -Updated concerns: - -- none for this round beyond future tightening if exact-port rejection is later requested explicitly. diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-4-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-4-report.md deleted file mode 100644 index d3248faf..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-4-report.md +++ /dev/null @@ -1,149 +0,0 @@ -# Task 4 Report — Narrow harness embedding configuration to internal Ollama - -## Status - -Implemented on 2026-08-08 in `/Users/mp/projects/ThothII/.worktrees/git-workspace-registry`. - -## RED evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py -q -``` - -Observed before implementation: - -- exit code `1` -- `10 failed, 10 passed` -- failures proved the missing `OllamaInternalEmbeddings` client and missing internal-only config validation - -Representative failures: - -- `ImportError: cannot import name 'OllamaInternalEmbeddings'` -- `AttributeError: 'EmbeddingsConfig' object has no attribute 'provider'` -- config tests `DID NOT RAISE ConfigError` for external provider, API key, and non-private base URL - -## GREEN evidence - -Focused behavior suite: - -```bash -cd harness -./.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py -q -``` - -- exit code `0` -- `20 passed` - -Relevant harness verification: - -```bash -cd harness -./.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py tests/test_ollama_ensure.py -q -``` - -- exit code `0` -- `36 passed, 2 warnings` - -Changed-file lint: - -```bash -cd harness -./.venv/bin/ruff check tht/config.py tht/config_compat.py tht/vectorstore/embeddings.py tht/cli/ollama_cmd.py tests/test_config_resources.py tests/test_internal_embeddings.py -``` - -- exit code `0` -- `All checks passed!` - -Patch hygiene: - -```bash -git diff --check -``` - -- exit code `0` - -## What changed - -- translated schema-v3 `resources.embeddings` into the harness-compatible embedding config view -- validated the internal embedding contract only for that runtime-owned `resources.embeddings` path: - - provider must be `ollama_internal` - - model must be `qwen3-embedding:0.6b` - - dimensions must be `1024` - - base URL must be `http://embedding:11434` or loopback HTTP on port `11434` - - extra fields like `api_key` are rejected -- replaced the active embed client with `OllamaInternalEmbeddings`, using one bounded `/api/embed` request per batch -- removed task/query prefix rewriting from the active embedding path -- validated response count, vector dimension, and finite numeric values before returning embeddings -- kept `tht ollama ensure --json` stdout pristine while warming through the internal client - -## Self-review - -- kept changes inside the brief-listed files -- preserved DWH and session-persistence behavior -- preserved the legacy `OllamaEmbeddings` import path as an alias to avoid unrelated call-site churn - -## Concerns - -- the focused harness verification still emits two pre-existing warnings: - - `DeprecationWarning` from `testcontainers.postgres` - - `FutureWarning` because `resources` currently flows through the legacy config translation path - -## Fix round 1 — 2026-08-08 - -### Findings addressed - -- HIGH: external top-level `embeddings` remained an operational fallback and could still load -- MEDIUM: non-object embed JSON payloads escaped as raw `AttributeError` - -### RED evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py tests/test_ollama_ensure.py -q -``` - -Observed before the fix: - -- exit code `1` -- `2 failed, 36 passed, 2 warnings` - -Representative failures: - -- `AttributeError: 'list' object has no attribute 'get'` from `response.json()` returning a JSON array -- `Failed: DID NOT RAISE ConfigError` for top-level external `embeddings.provider=openai_compatible` - -### GREEN evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py tests/test_ollama_ensure.py -q -``` - -Observed after the fix: - -- exit code `0` -- `38 passed, 2 warnings` - -Touched-file lint: - -```bash -cd harness -./.venv/bin/ruff check tht/config.py tht/vectorstore/embeddings.py tests/test_internal_embeddings.py tests/test_config_resources.py -``` - -- exit code `0` -- `All checks passed!` - -### Minimal fix - -- validated the final active `cfg.embeddings` contract after config loading, so legacy top-level - embedding inputs now fail explicitly unless they exactly match the internal Ollama contract -- converted non-mapping embed JSON payloads into controlled `EmbeddingsError` failures with - sanitized diagnostics instead of raw attribute errors diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-5-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-5-report.md deleted file mode 100644 index d4243cc5..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-5-report.md +++ /dev/null @@ -1,170 +0,0 @@ -# Task 5 Report — Implement the Qdrant VectorStore adapter - -## Status - -Implemented on 2026-08-08 in `/Users/mp/projects/ThothII/.worktrees/git-workspace-registry`. - -## RED evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -Observed before implementation: - -- exit code `2` -- collection failed during import because the adapter did not exist yet - -Representative failures: - -- `ModuleNotFoundError: No module named 'tht.adapters.vector.qdrant'` - -## GREEN evidence - -Focused behavior suite: - -```bash -cd harness -./.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -- exit code `0` -- `31 passed, 1 warning` - -Touched-file lint: - -```bash -cd harness -./.venv/bin/ruff check tht/adapters/vector/qdrant.py tht/adapters/vector/__init__.py \ - tht/ports/vector.py tht/vectorstore/records.py tht/vectorstore/store.py \ - tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -``` - -- exit code `0` -- `All checks passed!` - -Patch hygiene: - -```bash -git diff --check -``` - -- exit code `0` - -## What changed - -- added `QdrantVectorStore` with direct `requests`-based REST calls for: - - `GET /collections/{collection}` - - `PUT /collections/{collection}` - - `PUT /collections/{collection}/index` - - `PUT /collections/{collection}/points?wait=true` - - `POST /collections/{collection}/points/query` - - `POST /collections/{collection}/points/scroll` - - `POST /collections/{collection}/points/delete?wait=true` -- implemented idempotent collection provisioning for `1024` dimensions and `Cosine` distance -- created deterministic UUIDv5 point IDs from workspace, semantic kind, and canonical record key -- preserved canonical record identity and only upserted/deleted points matching the exact workspace - and generation filters -- added Qdrant payload helpers so stored payloads carry: - - `workspace_id` - - grouped semantic `kind` (`schema`, `evidence`, `memory`) - - original `record_kind` - - canonical `record_key` - - `content_hash` - - existing Thoth metadata fields -- mapped Qdrant payloads back into existing `VectorHit` objects without losing the original - Thoth kind -- exported the new adapter from the public vector adapter package and added focused contract tests -- sanitized timeout and malformed-response failures so CLI-facing callers do not leak raw endpoint - details - -## Self-review - -- confirmed collection mismatch fails without any delete/recreate path -- confirmed every query/scroll/delete operation includes a workspace filter -- confirmed the adapter never deletes or rewrites unrelated Qdrant points -- added keyword payload indexes for all filter-critical fields used here, including `document_id` - for exact Evidence filtering - -## Concerns - -- the requested `adversarial-review` skill could not run its full external reviewer flow in this - environment because the skill’s referenced `brain/` files are missing at - `/Users/mp/.agents/skills/adversarial-review`; I performed a manual adversarial self-review - instead -- the focused suite still emits one pre-existing warning from `testcontainers.postgres` - -## Fix round 1 — 2026-08-08 - -### Findings addressed - -- IMPORTANT: metadata collisions could override canonical Qdrant payload identity fields and break - workspace isolation -- IMPORTANT: scroll-based operations only read the first page and did not follow - `next_page_offset`, making `existing_hashes`, `list_evidence_generations`, and delete counts - inexact beyond one page - -### RED evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -Observed before the fix: - -- exit code `1` -- `2 failed, 31 passed, 1 warning` - -Representative failures: - -- `assert payload["workspace_id"] == "demo"` failed because colliding `record.metadata` - overwrote canonical payload fields -- paginated scroll test missed later pages, so `existing_hashes` and generation cleanup counts - were incomplete - -### GREEN evidence - -Command: - -```bash -cd harness -./.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -Observed after the fix: - -- exit code `0` -- `33 passed, 1 warning` - -Touched-file lint: - -```bash -cd harness -./.venv/bin/ruff check tht/adapters/vector/qdrant.py tht/vectorstore/records.py \ - tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -``` - -- exit code `0` -- `All checks passed!` - -Patch hygiene: - -```bash -git diff --check -``` - -- exit code `0` - -### Minimal fix - -- made `qdrant_payload` apply canonical fields after `record.metadata` so workspace ID, semantic - kind, original record kind, canonical record key, and content hash cannot be overridden by - metadata collisions -- paginated `_scroll` until `next_page_offset` is absent, sent the returned `offset` back on the - next request, and reject repeated offsets as malformed to avoid infinite loops diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-6-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-6-report.md deleted file mode 100644 index 8b70773e..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-6-report.md +++ /dev/null @@ -1,144 +0,0 @@ -# Task 6 Report - -Date: 2026-08-08 - -Status: implemented and verified - -Summary: - -- Added schema-v3 Qdrant runtime support to the harness config/resource layer and vector factory. -- Made Qdrant payloads carry `workspace_id` and `workspace_revision` on every point. -- Routed schema and memory bulk indexing through the transport-neutral vector port with canonical hash-based dedup. -- Kept Evidence canonical on filesystem and Memory canonical in JSONL; Qdrant remains derived/rebuildable. -- Added focused tests for semantic-kind isolation, shared identity fields, search-pack kind boundaries, and the schema-v3 factory/config path. - -Files changed: - -- `harness/tht/config.py` -- `harness/tht/config_compat.py` -- `harness/tht/adapters/factory.py` -- `harness/tht/adapters/vector/qdrant.py` -- `harness/tht/vectorstore/records.py` -- `harness/tht/cli/vector_cmd.py` -- `harness/tht/cli/memory_cmd.py` -- `harness/tests/test_semantic_kind_isolation.py` -- `harness/tests/test_memory_save_one.py` -- `harness/tests/test_search_pack.py` -- `harness/tests/test_qdrant_vector_store.py` -- `harness/tests/test_adapter_factory.py` -- `harness/tests/test_config_resources.py` - -Verification: - -- Focused RED/GREEN task suite: - - `cd harness && .venv/bin/pytest tests/test_semantic_kind_isolation.py tests/test_memory_save_one.py tests/test_search_pack.py -q` -- Relevant harness suite: - - `cd harness && .venv/bin/pytest tests/test_semantic_kind_isolation.py tests/test_memory_save_one.py tests/test_search_pack.py tests/test_qdrant_vector_store.py tests/test_adapter_factory.py tests/test_config_resources.py tests/test_vector_port_contract.py tests/test_corpus_pipeline.py -q` - - Result: `131 passed` -- Changed-file Ruff: - - `cd harness && .venv/bin/ruff check tht/vectorstore/records.py tht/adapters/vector/qdrant.py tht/config_compat.py tht/config.py tht/adapters/factory.py tht/cli/vector_cmd.py tht/cli/memory_cmd.py tests/test_memory_save_one.py tests/test_search_pack.py tests/test_semantic_kind_isolation.py tests/test_qdrant_vector_store.py tests/test_adapter_factory.py tests/test_config_resources.py` - - Result: clean - -Concerns / follow-up: - -- `memory clear` still retains its older direct-vector assumptions and was not expanded in this task because the brief focused on canonical builders and schema/evidence/memory routing through the active Qdrant path. -- The relevant suite still emits pre-existing warnings (legacy config deprecation in older fixtures, plus existing Pydantic serializer warnings in corpus tests), but they are not introduced by this task. - -## Fix round 1 (2026-08-08) - -Scope: - -- Fixed qdrant-only schema-v3 command gating for `vector index-schema`, `memory promote`, and `memory index`. -- Replaced `memory clear`'s direct-pgvector-only path with vector-port deletion by kind. -- Added focused qdrant-only CLI regression tests and refreshed older CLI fixtures to the enforced internal embedding contract. - -RED evidence: - -- `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py -q` -- Initial result against commit `5e39cfa`: `4 failed` -- Failure signatures: - - `ERRORE: sezioni mancanti nel workspace yaml: vector_db o vector_write_rest.` - - `ERRORE: sezioni mancanti nel workspace yaml: vector_db.` - -GREEN evidence: - -- Focused fix suite: - - `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py tests/test_qdrant_vector_store.py tests/test_adapter_factory.py tests/test_config_resources.py tests/test_memory_save_one.py tests/test_search_pack.py -q` - - Result: `51 passed` -- Relevant broader vector/memory/schema/search suite: - - `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py tests/test_qdrant_vector_store.py tests/test_adapter_factory.py tests/test_config_resources.py tests/test_memory_save_one.py tests/test_search_pack.py tests/test_vector_port_contract.py tests/test_adapter_command_regressions.py tests/test_solved_search_cli.py tests/test_schema_introspect_guard.py tests/test_semantic_kind_isolation.py tests/test_corpus_pipeline.py -q` - - Result: `154 passed` -- Ruff on the fix surface: - - `cd harness && .venv/bin/ruff check tht/ports/vector.py tht/adapters/vector/qdrant.py tht/adapters/vector/pgvector.py tht/adapters/vector/thoth_http.py tht/vectorstore/rest_client.py tht/cli/vector_cmd.py tht/cli/memory_cmd.py tests/test_qdrant_cli_commands.py tests/test_solved_search_cli.py` - - Result: clean - -Notes: - -- `memory clear` now deletes derived `kind=memory` points through the configured writable vector store, while leaving the JSONL registry as the source of truth until the registry file is removed by the command. -- The broader suite still carries the same pre-existing warnings noted above; this fix round did not add new warnings or failures. - -## Fix round 2 (2026-08-08) - -Scope: - -- Removed the accidental HTTP writer `delete_kinds` capability expansion from `ThothHttpVectorStore` and `VectorRestClient`. -- Reworked `memory clear` so schema-v3 Qdrant uses scoped `kind=memory` deletion, while legacy transports keep the pre-task direct-sync path instead of advertising a nonexistent RPC. -- Tightened the qdrant-only memory-clear regression to assert the exact `("memory", ["memory"])` delete scope. - -RED evidence: - -- Re-review found a transport contract mismatch in fix round 1: - - `ThothHttpVectorStore` exposed `delete_kinds(...)` - - `VectorRestClient` exposed `delete_kinds(...)` - - but the legacy HTTP writer migration only allowlists `delete_vector_generation`, not `delete_vector_kinds` -- The new regressions added in this round capture that mismatch and the missing qdrant delete-scope assertion: - - `tests/test_vector_port_contract.py::test_http_store_supports_writer_without_reader` - - `tests/l0/test_vector_adapter_parity.py::test_http_rest_client_does_not_advertise_nonexistent_delete_kinds_rpc` - - `tests/test_qdrant_cli_commands.py::test_memory_clear_accepts_qdrant_only_runtime_config` - -GREEN evidence: - -- Focused regression suite: - - `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py tests/test_vector_port_contract.py tests/l0/test_vector_adapter_parity.py tests/test_adapter_command_regressions.py -q` - - Result: `53 passed` -- Broader relevant vector/memory/search suite: - - `cd harness && .venv/bin/pytest tests/test_qdrant_cli_commands.py tests/test_adapter_command_regressions.py tests/test_vector_port_contract.py tests/l0/test_vector_adapter_parity.py tests/test_solved_search_cli.py tests/test_qdrant_vector_store.py tests/test_search_similar_kinds.py tests/test_corpus_pipeline.py -q` - - Result: `135 passed` -- Ruff on the changed fix surface: - - `cd harness && .venv/bin/ruff check tht/cli/memory_cmd.py tht/ports/vector.py tht/adapters/vector/thoth_http.py tht/vectorstore/rest_client.py tests/test_qdrant_cli_commands.py tests/test_vector_port_contract.py tests/l0/test_vector_adapter_parity.py` - - Result: clean - -Notes: - -- Legacy HTTP/vector-rest deployments do not gain a new destructive RPC surface from this fix; they keep their previous behavior and continue to fail closed for unsupported cleanup. -- The broader suite still emits the same pre-existing deprecation and serializer warnings already noted above; this round did not introduce new warnings. - -## Fix round 3 (2026-08-08) - -Scope: - -- Added an adapter-level Qdrant regression for mixed semantic kinds within one workspace plus a second workspace memory point. -- Verified that `delete_kinds("memory", ["memory"])` emits the real adapter filter with both `workspace_id=demo` and `record_kind=memory`. -- Verified that non-memory semantic kinds in the same workspace and memory from another workspace survive the delete. - -RED evidence: - -- Re-review identified a test gap rather than a confirmed runtime bug: - - existing coverage asserted only the CLI mock call shape for qdrant memory clear - - there was no adapter-level regression proving the real Qdrant delete filter and resulting fake-Qdrant state across mixed semantic kinds/workspaces -- Added regression: - - `tests/test_qdrant_vector_store.py::test_delete_kinds_is_workspace_scoped_and_preserves_other_semantic_kinds` - -GREEN evidence: - -- Requested focused suite: - - `cd harness && .venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_qdrant_cli_commands.py tests/test_semantic_kind_isolation.py -q` - - Result: `18 passed` -- Ruff on changed files: - - `cd harness && .venv/bin/ruff check tests/test_qdrant_vector_store.py` - - Result: clean - -Notes: - -- This round required no production change; the new adapter regression passed against the existing Qdrant implementation. -- The focused suite still emits the same pre-existing `testcontainers.postgres` deprecation warning from `tests/conftest.py`; no new warnings were introduced. diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-7-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-7-report.md deleted file mode 100644 index a0d72e66..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-7-report.md +++ /dev/null @@ -1,98 +0,0 @@ -# Task 7 report — mandatory Qdrant and Ollama Compose services - -Date: 2026-08-08 - -Status: completed - -Summary: - -- Added mandatory private `qdrant`, `embedding`, and `embedding-model-init` services to the base Compose stack. -- Pinned Qdrant `v1.18.2` and Ollama `0.32.0` by immutable multi-arch digest. -- Persisted Qdrant storage in `qdrant-data` and Ollama model cache in `embedding-models`. -- Wired `core` to fixed internal semantic endpoints: - - `THT_INTERNAL_QDRANT_URL=http://qdrant:6333` - - `THT_INTERNAL_EMBEDDING_URL=http://embedding:11434` - - `THT_INTERNAL_EMBEDDING_MODEL=qwen3-embedding:0.6b` - - `THT_INTERNAL_EMBEDDING_DIMENSIONS=1024` -- Removed external vector / embedding endpoint requirements from the local and server env examples. -- Added an idempotent Ollama model bootstrap script that: - - waits up to a bounded deadline for `/api/tags` - - skips `ollama pull` when the model is already cached - - pulls `qwen3-embedding:0.6b` only when needed - - verifies the model appears in `/api/tags` after pull -- Added optional GPU override file `deploy/compose.embedding-gpu.yaml`; base Compose remains CPU-only. -- Updated `scripts/run-stack.sh` so the GPU override is included only when `THOTH_ENABLE_EMBEDDING_GPU=1`. - -Verification: - -- RED confirmed before implementation: - - `./scripts/test-default-compose.sh` failed on missing required services. - - `./scripts/test-unified-compose.sh` failed on missing required services. - - `./scripts/test-internal-semantic-compose.sh` failed because the GPU override file did not exist. -- GREEN after implementation: - - `./scripts/test-default-compose.sh` - - `./scripts/test-unified-compose.sh` - - `./scripts/test-internal-semantic-compose.sh` - - `git diff --check` -- Additional shell verification: - - `scripts/run-stack.sh --wait` includes only base + local Compose files by default. - - `THOTH_ENABLE_EMBEDDING_GPU=1 scripts/run-stack.sh --wait` adds `deploy/compose.embedding-gpu.yaml`. - -Resolved image digests: - -- `qdrant/qdrant:v1.18.2@sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c` -- `ollama/ollama:0.32.0@sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a` - -Self-review: - -- The first bootstrap-script draft depended on tools not guaranteed inside the Ollama image. This was corrected after image inspection; the final script uses only confirmed image tools (`bash`, `ollama`, `grep`) plus raw HTTP over `/dev/tcp`. -- The server overlay intentionally replaces most named core volumes with bind mounts, so the unified contract was tightened to require named semantic-cache volumes there while preserving the local/base named-volume checks. - -Concerns: - -- The model bootstrap waits for Ollama readiness and verifies cache state, but the first real cold-start will still take time to download `qwen3-embedding:0.6b`. -- The GPU override requests generic Docker GPU capability only; actual GPU availability remains host/runtime dependent and intentionally stays opt-in. - -## Fix round 1 / 5 — 2026-08-08 - -Rulings applied: - -- Kept the Task 1 boundary intact: schema-v3 remains the only operational workspace descriptor shape. -- Did not restore any external semantic fallback for schema-v2 live sessions. -- Treated `PROJECT_STATE.md` as stale documentation for this point, not runtime truth. - -Focused schema-v2 evidence: - -- Re-ran the existing targeted registry test: - - `cd backend && npx vitest run test/workspace-registry.test.ts -t "lists a schema v2 descriptor as migration_required and refuses to acquire it"` -- Result: pass. -- Evidence from that test: - - schema-v2 descriptors list as `migration_required` - - `acquireSessionRevision("psd-clinical")` rejects with `code: "workspace_invalid"` -- Conclusion: schema-v2 acquisition remains blocked; no external semantic fallback was reintroduced. - -Contract consistency fixes: - -- Updated `harness/tests/test_local_compose_contract.py` to assert the mandatory internal semantic stack, fixed internal core semantic env, private-service topology, persistent volumes, and Ollama health/dependency contract. -- Updated shell Compose contracts to require: - - Ollama healthcheck on `embedding` - - `embedding-model-init` dependency on `embedding: service_healthy` -- Updated `scripts/unified-deployment-smoke.sh` rendered-contract helper to expect the mandatory internal semantic topology and internal semantic env names, and to reject retired external semantic bindings. -- Updated `scripts/test-task13-runtime-fixtures.sh` to exercise `task13_assert_rendered_contract` for both local and server fixture renders. - -Fix round 1 verification: - -- RED before implementation: - - `cd harness && .venv/bin/pytest tests/test_local_compose_contract.py -q` failed because `embedding` had no healthcheck. - - `./scripts/test-default-compose.sh` failed because `embedding` had no healthcheck. - - `./scripts/test-unified-compose.sh` failed because `embedding` had no healthcheck. - - `./scripts/test-task13-runtime-fixtures.sh local` failed because `unified-deployment-smoke.sh` still expected `core,frontend`. -- GREEN after implementation: - - `./scripts/test-default-compose.sh` - - `./scripts/test-unified-compose.sh` - - `./scripts/test-internal-semantic-compose.sh` - - `cd harness && .venv/bin/pytest tests/test_local_compose_contract.py -q` - - `./scripts/test-task13-runtime-fixtures.sh local` - - `./scripts/test-task13-runtime-fixtures.sh server` - - `cd backend && npx vitest run test/workspace-registry.test.ts -t "lists a schema v2 descriptor as migration_required and refuses to acquire it"` - - `docker compose --env-file deploy/env/local.env.example -f compose.yaml -f deploy/compose.local.yaml config --format json` diff --git a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-9-report.md b/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-9-report.md deleted file mode 100644 index da2f169d..00000000 --- a/.superpowers/sdd/2026-08-08-internal-qdrant-ollama/task-9-report.md +++ /dev/null @@ -1,65 +0,0 @@ -Status: completed on August 8, 2026. - -Summary: -- Updated the frontend workspace contract from schema v2 editing to schema v3 publishing. -- Kept only `semantic_index.vector_store.collection` editable; rendered qdrant / internal Ollama semantic values as fixed read-only architecture values. -- Removed external vector transport / endpoint / credential / embedding diagnostics branches from frontend draft sanitization, conflict parsing, and editor UI. -- Added a migration-required banner in workspace management and blocked `migration_required` workspaces from new-session selection. -- Aligned the example workspace YAML comments with the fixed internal qdrant/Ollama architecture. - -Files changed: -- `frontend/src/api/workspaces.ts` -- `frontend/src/api/workspaces.test.ts` -- `frontend/src/workspaces/drafts.ts` -- `frontend/src/workspaces/drafts.test.ts` -- `frontend/src/shell/WorkspaceEditor.tsx` -- `frontend/src/shell/WorkspaceEditor.test.tsx` -- `frontend/src/shell/WorkspaceManager.tsx` -- `frontend/src/shell/WorkspaceManager.test.tsx` -- `frontend/src/shell/WorkspacePublishDialog.test.tsx` -- `frontend/src/api/sessions.ts` -- `frontend/src/shell/SteerInput.tsx` -- `frontend/src/shell/SteerInput.test.tsx` -- `deploy/workspaces/example.yaml` -- `deploy/workspaces/psd.yaml.example` - -Verification: -- `cd frontend && npx vitest run src/shell/SteerInput.test.tsx src/shell/WorkspaceEditor.test.tsx src/shell/WorkspaceManager.test.tsx src/shell/WorkspacePublishDialog.test.tsx src/workspaces/drafts.test.ts src/api/workspaces.test.ts` - - Result: 6 files passed, 59 tests passed. -- `cd frontend && npx tsc -b` - - Result: passed. -- `git diff --check` - - Result: passed. - -Self-review: -- The frontend now publishes the exact schema v3 semantic shape and no longer persists legacy semantic transport/credential branches. -- Migration-required workspaces are visible in management with an explicit banner and are excluded from the composer workspace selector. -- One dependent test file outside the original brief list (`WorkspacePublishDialog.test.tsx`) and the composer/session-selection path (`api/sessions.ts`, `SteerInput.tsx`, related test) were updated because they were directly coupled to the old v2 semantic/edit-selection behavior. - -Concerns: -- The composer still retains backward-compatible behavior for summaries that omit `revision` entirely; only explicit `revision.state === "migration_required"` is blocked. That matches the current mixed-test environment, but once summary responses are guaranteed to include `revision`, that fallback may be removable. - -Fix round 1/5 — August 8, 2026 - -Summary: -- Made missing or invalid workspace summaries fail safe in frontend session creation and composer selection instead of falling open as legacy. -- Added an actionable unavailable message in workspace management for incomplete summaries with no canonical revision. -- Replaced the old runtime-oriented example descriptor files with exact backend WorkspaceV3 descriptor YAML. - -Additional files changed: -- `frontend/src/api/sessions.test.ts` -- `backend/test/workspaces-schema.test.ts` - -Fix-round verification: -- `cd frontend && npx vitest run src/api/sessions.test.ts src/shell/SteerInput.test.tsx src/shell/WorkspaceManager.test.tsx src/shell/WorkspaceEditor.test.tsx src/shell/WorkspacePublishDialog.test.tsx src/workspaces/drafts.test.ts src/api/workspaces.test.ts` - - Result: 7 files passed, 73 tests passed. -- `cd frontend && npx tsc -b` - - Result: passed. -- `cd backend && npx vitest run test/workspaces-schema.test.ts` - - Result: 1 file passed, 17 tests passed. -- `git diff --check` - - Result: passed. - -Notes: -- Missing `revision` in a workspace summary now fails with the same session/composer safety posture as `migration_required`, using the existing safe workspace-policy error for session creation and an explicit unavailable message in workspace management. -- The committed example files now validate as actual schema-v3 descriptors instead of deployment/runtime templates with forbidden semantic endpoint fields. diff --git a/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-5-report.md b/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-5-report.md deleted file mode 100644 index ef8da22c..00000000 --- a/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-5-report.md +++ /dev/null @@ -1,83 +0,0 @@ -# Task 5 Report — `tht setup` lifecycle orchestration - -## Status - -Completed. `tht setup` now validates the checkout and host prerequisites, creates or validates -the non-secret installation files, validates Compose, and by default builds, starts, health-checks, -and verifies the installation. `tht setup --configure-only` stops immediately after successful -Compose rendering. - -## Implementation - -- Added `setup.Run`, with an ordered host preflight: project/worktree discovery, Docker Engine, - Docker Compose, supported architecture, and LF line-ending checks. -- Reused `config.Installation.ComposeArgs` for all Compose calls and added a narrow - `compose.InstallationRunner` adapter for Pi diagnostics; no shell command construction was added - to the top-level CLI parser. -- Default setup performs `compose build`, `compose up --detach --remove-orphans`, bounded polling - for `core`, `frontend`, `qdrant`, `embedding`, and `embedding-model-init`, then aggregate volume - diagnostics and `pi.Doctor`. -- Health timeout errors identify the last failing service and preserve containers for diagnosis, - with `tht logs ` and `tht status` guidance. -- Completion output includes the frontend URL, selected descriptor, and next action. - -## TDD evidence - -The initial focused test run failed because `setup.Run` did not exist. Tests were then written -against a fake Compose runner before the orchestration was implemented. They cover the complete -ordered flow, configure-only stop, preflight failure before writing configuration, health retry, -timeout guidance, and CLI default versus `--configure-only` dispatch. - -## Verification - -Executed from `tools/tht`: - -```bash -go test ./internal/setup ./internal/compose ./cmd/tht -run 'TestRun|TestSetupCommand|TestInstallationRunner' -count=1 -go test ./internal/setup ./internal/compose ./cmd/tht -count=1 -go test ./... -git diff --check -``` - -All commands passed. No actual Docker build, container start, live-stack restart, system -installation, Pi configuration edit, or documentation rewrite was performed. - -## Commit - -`feat(setup): build start and verify ThothII` (this report is included in that commit). - -## Concerns - -- The bounded health wait is verified with fakes only, as required for this task. Real Docker - lifecycle verification belongs to the later live acceptance task. -- The existing aggregate `tht doctor` command remains a separate implementation; Task 5 performs - its equivalent setup-time prerequisite checks plus `pi.Doctor` without invoking a nested CLI - process. - -## Fix round 1 - -The independent review identified three gaps. All were reproduced with RED tests before the -production change: - -- A rendered Compose document containing any one volume was accepted. `requireVolumes` now - requires `settings`, `pi-state`, `workspace-registry`, `workspace-secrets`, `sessions`, - `qdrant-data`, and `embedding-models`; tests reject each individual omission and an - unrelated-only volume set. -- Failures after `compose up` could return without recovery instructions. A single recovery - wrapper now preserves the underlying error while adding the retained-container, `tht logs - `, and `tht status` guidance for failed `up`, health, aggregate doctor, and Pi doctor - phases. Focused tests also prove build failure stops before attempting startup. -- LF inspection previously walked the full checkout. It now inspects only `compose.yaml`, - `deploy/`, and `docker/`; a test proves CRLF content under `node_modules/` is ignored. - -Verification added for this round: - -```bash -go test ./internal/setup -run 'TestRequireVolumes|TestRun(BuildFailure|UpFailure|AggregateDoctorFailure|PiDoctorFailure|IgnoresIrrelevant|TimesOut)' -count=1 -go test ./internal/setup -count=1 -``` - -Both passed before the final full-suite verification. No Docker or live operation was run. - -Implementation commit evidence: `ea70cc95b04532043744a9de6c5912e30a214595` — -`fix(setup): harden verification and recovery`. diff --git a/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-6-report.md b/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-6-report.md deleted file mode 100644 index 90a7d55b..00000000 --- a/.superpowers/sdd/2026-08-15-unified-tht-cli-product-step/task-6-report.md +++ /dev/null @@ -1,55 +0,0 @@ -# Task 6 — Version, aggregate doctor, and build-aware start - -Status: complete. - -Implemented the host-side `tht version`, aggregate `tht doctor [--json]`, and `tht start [--build]` contracts. - -- `version` is descriptor-free and reports semantic version, commit, build time, OS, and architecture. -- `doctor` emits typed, redacted checks for descriptor state, Docker/Compose, rendered volumes, file permissions, service health, workspace registry, the container-local workflow doctor, and Pi doctor. Its JSON mode writes exactly one JSON document to stdout. -- The Python workflow doctor is invoked only as `docker compose exec -T core tht doctor --json` after core is running. -- `start` uses the shared lifecycle service: default `up → health`; `--build` is `build → up → health`. -- `setup` now reuses the shared lifecycle and aggregate diagnostics rather than keeping parallel health/volume implementations. - -Verification performed without live Docker/container commands: - -```bash -cd tools/tht -go test ./internal/version ./internal/doctor ./internal/service ./cmd/tht \ - -run 'TestVersion|TestDoctor|TestStart|TestCurrent|TestRun' -count=1 -go test ./internal/setup -count=1 -run 'TestRun' -v -go test ./... -count=1 -git diff --check -``` - -All completed successfully. The intentionally fake runner coverage includes unavailable Docker, -stopped/running core, workflow failure redaction, pristine JSON output, and start ordering. - -Concerns: no live Docker validation or host installation was run, by explicit task constraint. - -## Fix round 1 - -Completed the independent-review follow-up without live Docker operations. - -- `workspace-registry` now executes a container-local, read-only Node validation of - `/data/workspace-registry/state/active.json` and every declared snapshot descriptor. It no - longer passes merely because Compose declares a volume. -- Host file permissions are checked before Docker/Compose availability and therefore remain - visible as failures when Docker is unavailable. -- Separate typed, bounded HTTP probes verify core (`curl --max-time 5`) and frontend - (`wget -T 5`) reachability, independently of Compose health. The probe is injectable in tests. -- The successful report tests assert the stable full checklist: - `descriptor`, `files`, `docker`, `compose`, `configuration`, `services`, `core-http`, - `frontend-http`, `workspace-registry`, `workflow`, `pi`. - -Additional verification: - -```bash -cd tools/tht -go test ./internal/doctor -run 'TestRun(ChecksUnsafeFilesEvenWhenDockerIsUnavailable|FailsAnInvalidContainerLocalRegistryState|ReportsEachHTTPReachabilityProbeFailure|UsesOnlyContainerLocalWorkflowAndPiDiagnosticsWhenCoreRuns)' -count=1 -v -go test ./internal/doctor ./internal/setup ./internal/service ./cmd/tht -count=1 -go test ./... -count=1 -git diff --check -``` - -All passed with fake runners/probes only. No live container, HTTP endpoint, or host installation -was touched. diff --git a/.superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md b/.superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md deleted file mode 100644 index 6b173538..00000000 --- a/.superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md +++ /dev/null @@ -1,163 +0,0 @@ -# Task 15 retained release-gate report — fix round 5 (sanitized) - -## Final-review fix-round-2 addendum — frozen source `2a9359071257f9b8a71d36ec2bbb25b161003f81` - -This addendum supersedes the fix-round-1 addendum for current authentication remediation status -while preserving the fix-round-5 material below as historical provenance. - -- Authentication remediation status: `PASS`. The three original remediation Important findings - remain `RESOLVED`; the fix-round-2 fully bounded lifecycle Important is `ADDRESSED`; and the - temporary Windows diagnostic-matrix Minor is `ADDRESSED`. -- Overall branch/release readiness is separately `FAIL`, with unavailable external/manual gates - `PENDING`. -- Completed exact-source workflow run `32147345625` concluded `failure` on baseline release jobs. - Its `Windows clone and Compose contract` job (`95744249248`) executed the unfiltered command - `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`; the native step - passed all three packages: safeio `22.058s`, backup `7.161s`, authstorage `16.088s`. -- The Windows job failed only afterward in the baseline clone-contract script at - `scripts/test-windows-clone-contract.ps1:208`, where PowerShell rejects the undelimited - `$remoteYaml:` variable reference. -- `LF, Compose, docs, and TypeScript` job `95744249458` reproduced the baseline unset-`TMPDIR` - failure after unified Compose passed. Linux Docker job `95744249354` reproduced the missing-`rg` - prerequisite failure; cleanup passed and no image manifest was generated. -- The skipped Windows Docker Desktop/WSL2 job is recorded as `NOT_RUN` / `BLOCKED`, not FAIL. - Downstream commands skipped after executed baseline failures use the same classification. The - matrix contains an explicit native `windows_stagearchive_retained_capability` PASS row. -- Historical Node/auth/browser/docs PASS and harness/Ruff/Compose FAIL evidence remains bound to - its recorded source where not rerun. L2, real PSD/manual acceptance, and provider readiness - remain `PENDING`. -- Current machine-readable evidence and the requested Task 4 report are recorded in - `.artifacts/task-15/automated-gates.json` and - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md`. -- The full fix-round-2 RED/GREEN and finding disposition is recorded in - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md`. -- Current automated-gates SHA-256: - `6c516db5c2064c4a4a2e5f25961b993cd4a8fe020bbbb822fbac7faa0c119599`. -- Historical unified Docker manifest SHA-256: `9c8dec4546909fd93799dbcf374bcb3a89bc46cfe0fd482472c0cbe757ddf5b6`. - -The complete sanitized Task 4 matrix and the separate remediation/release verdicts are in the -requested Task 4 report. - -- Final tested source commit: `74b062f1a737103524cbe706346cfd65f87cdfd1`. -- Historical retained source commits: fix-round-2 `fe190e7046acc173f510dddcb32f46ed142858c1`, - maintenance follow-up `4d230b87afdcd24f02264f8f937c8628b92db05a`, prior final Docker - source `e20bf33e2a00102192e5be66b178037aeca3a7b1`, and fix-round-4 streamed - archive privacy `54698e73400a54ce7c3e6c10099e14eb471ce8b9`. -- Versions: Node contract `v24.16.0`; host default Node `v25.6.1`; Go `go1.26.5`; - Pi `0.80.3`. -- Historical automated gate artifact: `.artifacts/task-15/automated-gates.json`; - SHA-256 `7d9ec93af15510605f1aa7179b26a7ee46d78122f647854300f7a9922057a63f`. -- Docker image manifest: `.artifacts/task-15/unified-docker-images.json`; - SHA-256 `9c8dec4546909fd93799dbcf374bcb3a89bc46cfe0fd482472c0cbe757ddf5b6`. - -## Fix-round-5 evidence - -- PASS, RED then GREEN: `TestCreateCanonicalNewPrivateFileUsesPinnedParentAfterAncestorSwap` - first failed because the creator had not retained its parent before creation. It now opens every - Unix ancestor once, creates the leaf with `openat(O_NOFOLLOW|O_CREAT|O_EXCL)`, applies and checks - `0600` by descriptor (`fchmod`/`fstat`), and uses `unlinkat` for creator failure cleanup. The - deterministic test moves the opened parent, replaces its lexical name with an outside symlink, - validates the archive under the moved original parent, and proves no outside archive was written. -- PASS: the Windows implementation uses NT `RootDirectory`-relative traversal for every component - after the volume root and for final file creation. The retained final parent receives only the - required child-create right (`FILE_WRITE_DATA` for a file, `FILE_APPEND_DATA` for a directory), - reparse points are rejected, and the owner-only protected DACL is installed in the same - `NtCreateFile` operation. The native-Windows test attempts the pre-create parent swap and calls - `safeio.ValidatePrivateRegular`; it is compiled but not executed on this host. -- PASS: `go test ./internal/safeio ./internal/backup -count=1`, `go test -race ./...` across - `18` packages, `go vet ./...`, and a native host `tht` CLI build. Existing StageArchive - capacity, lifecycle, rollback, streaming, and cleanup tests remain passing. -- PASS, compile-only: Windows amd64 static test/build compilation across `18` packages, including - the retained-handle Windows tests. No Windows executable was run; native execution remains - PENDING and is not inferred from compilation. -- PASS on Node `v24.16.0`: the hermetic OIDC/F1 authentication browser smoke passed all current - `8` checks in `frontend/e2e/auth.spec.ts` and `frontend/e2e/f1.spec.ts`; the runtime sentinel - leak scan passed. -- PASS: shell syntax, unified-smoke safety self-test, default Compose contract, unified Compose - contract, and Compose secret-policy contract. -- PASS: final unified Docker deployment smoke run `20260818070637-66409-30058`, bound exactly to - source `74b062f1a737103524cbe706346cfd65f87cdfd1`. It exercised maintenance-auth isolation, - restore, registry lifecycle, bad-candidate rollback, image revalidation, and task-scoped cleanup. - -## Sanitized final unified Docker output - -```text -== Build and start isolated local Compose distribution == -== Recreate offline and retain the validated registry snapshot == -== Pull a valid catalog+descriptor metadata update == -== Pull a content-only Git Evidence update == -== Reject catalog/descriptor metadata mismatch and retain the valid snapshot == -== Reject orphan descriptor directories not listed in the catalog == -== Reject the retired flat workspace layout and retain the valid snapshot == -== Inject a bad pinned Pi candidate and prove automatic rollback == -Task 13 full deployment smoke passed. -Task 13 cleanup proof: no labeled containers, volumes, networks, or images remain for 20260818070637-66409-30058. -``` - -## Sanitized Docker image identities - -- `sha256:2d7b19491c7eb8c119c3cedb390aaeb2ff5593f6fc43ab66c317565560da6d7d`; - roles `compose-runtime`, `fixture-runtime`. -- `sha256:3b6c31a5d8f8fc58fa3233391b6175bd2fbc793eebb44d5e285ecc6e02e9e687`; - role `compose-runtime`. -- `sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a`; - role `compose-runtime`. -- `sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c`; - role `compose-runtime`. -- `sha256:c3cbe1cc1aa588a64951ac6286e0df7b27fe2e6324b1001c619bb358770c0178`; - role `rollback-candidate`. - -For each image, the retained repository-digest component equals the listed image digest. Registry -names and credentials are deliberately omitted. - -## Complete observed matrix - -- PASS: Task 13 lifecycle carry-ins; retained-handle owner-private restore staging; provider fixture - round-one `6/6`; backend Node 24 round-one suite `75 files / 1081 tests`; frontend Node 24 - round-one suite `61 files / 444 tests`; current Node 24 authentication/F1 browser smoke `8/8`; - final-source Go race/build `18 packages`; Windows static cross-compile `18 packages`; harness - round-one suite `921 passed / 4 L2 deselected`; authentication docs round-one gate; shell/Compose - contracts; final unified Docker smoke; five-image traceability; and Docker cleanup. -- FAIL: Ruff `192` known-baseline errors; MkDocs strict `69` known-baseline warnings; existing - canonical/workspace install wording checks; existing Pi model-policy check; deployment-coupling - scan against preserved ignored private material. -- PENDING: native Windows execution because required host prerequisites are unavailable; L2 because - the configured secret layout is unavailable; real PSD/manual acceptance because no real - identity/access is available; isolated provider readiness because an unrelated host port is - occupied. - -## Final Task 15 review after fix round 5 - -The fresh Terra review verdict is **CHANGES REQUIRED**. The five-round breaker is exhausted; no -sixth implementation round was started. Two Important findings remain: - -- `StageArchive` does not retain the opaque parent/directory capability through the complete - stream and `Close` lifecycle. Staging-directory creation and final cleanup still use pathname - operations, so an ancestor swap after creation can strand the secret-bearing archive or redirect - cleanup. Deterministic StageArchive swap-and-cleanup coverage is still required on Unix and - native Windows. -- Windows claim removal closes its validated retained parent handles before calling pathname-based - `DeleteFile`. Removal must instead remain handle-relative (or delete through the opened handle), - with a native-Windows ancestor-swap test. - -The focused/full Go, cross-compile, Node 24, browser, Compose, Docker lifecycle, image-traceability, -and cleanup results above remain valid evidence for source `74b062f1a737103524cbe706346cfd65f87cdfd1`. -They do not override the final code-review verdict. Native Windows execution remains PENDING. - -The authentication feature is **not implementation-complete or release-complete** while these code -findings and the required FAIL/PENDING gates remain. No secret values, real identities, internal -endpoints, or registry names are retained. - -## Final whole-branch review - -The final read-only Terra review of `351361f..39b5453` also returned **CHANGES REQUIRED** and found -one additional Important issue: the POSIX local-user registry validates file type, link count, and -mode for `users.yaml` and its parent directory, but does not require ownership by the effective UID. -A foreign-owned `0600` registry inside a runtime-owned `0700` directory can remain writable by the -foreign owner and be used to alter credentials or grant the administrator role. The registry must -enforce effective-UID ownership on every POSIX `lstat`/`fstat` path and add foreign-owner rejection -coverage. - -No new Critical issue or load-bearing Minor issue was found. The branch is **not ready to merge**: -this ownership defect and the two retained-capability cleanup defects above require fixes and renewed -review, independently of the remaining FAIL/PENDING release gates. diff --git a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-1-report.md b/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-1-report.md deleted file mode 100644 index 92d2a4cd..00000000 --- a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-1-report.md +++ /dev/null @@ -1,162 +0,0 @@ -# Final-review fix round 1 report (sanitized) - -## Verdict - -- Base: `fa499a9bdd37011833691b0f447470d8b7e8a3a6`. -- Final frozen source: `10cd66fe6a5b484a4dc569326a228c1c5484a5d4` on - `feat/thoth-auth`. -- Authentication remediation: **PASS / ADDRESSED**. All four final-review Important findings are - resolved relative to the remediation brief. -- Terra Minor evidence corrections: **ADDRESSED**. -- Branch/release readiness: **FAIL**. The completed exact-source workflow still contains executed - baseline clone-contract, LF/Compose, and Linux Docker failures. Unavailable external/manual - gates remain **PENDING**. -- Source and evidence remain separate commits. No workflow was dispatched from the evidence-only - phase. - -## Finding disposition - -| Finding | Disposition | Evidence | -|---|---|---| -| Important 1 — exhaustive Windows cleanup | RESOLVED | Cleanup now attempts close/delete/validation operations in deterministic order and returns sanitized `ErrUnsafeFile` after aggregating failures. `TestWindowsPrivateRegularCleanupClosesAfterDeleteDispositionFailure` and `TestWindowsClaimCleanupAttemptsLaterOperationsAfterEarlierFailure` cover the non-short-circuit contract. Global no-delete sharing remains unchanged. | -| Important 2 — usable native Windows authority | RESOLVED | Owner-only descriptors use the current user SID, protected/non-defaulted DACL semantics, valid NT attributes/access masks, self-relative creation descriptors, and semantic full-control validation. Equal-or-stronger Windows fixture adaptations retain no-delete handles instead of weakening ACL/identity checks. The final native three-package gate passes. | -| Important 3 — restore-test deadlock | RESOLVED | Lifecycle-stage release observes the buffered worker outcome, uses a bounded/cancellable release, reports premature completion directly, and never waits indefinitely on `done`. `TestReleaseLifecycleStageReturnsPrematureWorkerOutcome` and the lifecycle-lock terminal-cleanup test are green. | -| Important 4 — complete native package gate | RESOLVED | Workflow and remediation plan both use the exact unfiltered command `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`. Final logs prove all three packages executed natively. | -| Minor — non-executed gate classification | RESOLVED | Non-executed/skipped commands are `NOT_RUN` / `BLOCKED`; `FAIL` is reserved for commands that ran and failed. Historical results remain separately labelled. | -| Minor — explicit Windows StageArchive row | RESOLVED | `.artifacts/task-15/automated-gates.json` contains `windows_stagearchive_retained_capability` = PASS, bound to the final source and native backup result. | - -Additional failures exposed by the required unfiltered gate were fixed without narrowing the -workflow: Windows secret-bearing archive reservation is protected before use; StageArchive shares -one retained root capability across both staged files; claim/consume transitions serialize the -complete public validation and retained-handle operation while preserving ACL, hard-link identity, -reparse rejection, and no-delete invariants. - -## RED → GREEN record - -### Initial RED - -- Run `32122302381`: - https://github.com/mptyl/ThothII/actions/runs/32122302381 -- Source: `b31b27e5845ffd3adf311429367319beaba263c7`. -- Windows job: `95665197885`. -- Result: native `safeio`/`backup` failure, including the 10-minute restore lifecycle timeout; - `authstorage` was absent from the command. This established the RED for Important 2–4 and the - required native authority. -- Cleanup failure-injection tests added for Important 1 first exposed the short-circuit behavior - before the implementation was changed. - -### Final concurrency RED - -- Run `32140481263`: - https://github.com/mptyl/ThothII/actions/runs/32140481263 -- Source: `b48e9e9189dd0e8083db9bd0378704524e670edb`. -- Windows job: `95721724645`. -- Native results: backup PASS (`20.757s`), authstorage PASS (`104.180s`), safeio FAIL - (`63.502s`). The only failures were: - - `TestCanonicalPrivateClaimWaitsForRetainedRemoveOperation`: the concurrent claim returned - `false, unsafe file` before retained removal completed; - - `TestCanonicalPrivateClaimConsumeHasOneConcurrentWinner`: iteration 8 returned `unsafe file`. -- Diagnosis: the process mutex started below `validateClaimPaths`; a concurrent caller could fail - while reopening the retained no-delete directory before reaching the lock. - -### GREEN implementation and local gates - -The lock boundary was moved to the three public claim/read/remove APIs, covering validation, -relative operation, and handle close. The Unix implementation uses a no-op boundary and retains its -existing descriptor-relative semantics. - -Final-source local commands passed: - -```text -go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1 -go test -race ./... -go vet ./... -go build -o /tmp/thothii-tht-host ./cmd/tht -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o /tmp/thothii-tht-windows.exe ./cmd/tht -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go test -c ... ./internal/{safeio,backup,authstorage} -``` - -- Focused host package times: safeio `8.750s`, backup `8.378s`, authstorage `8.854s`. -- Race suite and vet: PASS. -- Host CLI: Mach-O arm64; Windows CLI and all three Windows test binaries: PE32+ x86-64. -- Cross-compilation remains compile-only and is not used as native proof. - -## Exact-source native certification - -- Run: `32141428407` -- URL: https://github.com/mptyl/ThothII/actions/runs/32141428407 -- Event/status/conclusion: `workflow_dispatch` / `completed` / `failure`. -- Head SHA: `10cd66fe6a5b484a4dc569326a228c1c5484a5d4` — exact final source match. -- Windows job: `Windows clone and Compose contract`, job `95724751282`: - https://github.com/mptyl/ThothII/actions/runs/32141428407/job/95724751282 -- Native step: `Run native Windows retained-capability tests` — **PASS**. -- Exact command: `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`. -- Native package results: - - safeio PASS (`8.230s`); - - backup PASS (`5.195s`); - - authstorage PASS (`8.383s`). -- Job conclusion: `failure` only because the following `Verify Windows clone contract` baseline - step failed with a PowerShell `ParserError` at - `scripts/test-windows-clone-contract.ps1:208`; `$remoteYaml:` is not delimited before `:`. - -## Remaining branch/release blockers - -| Gate | Classification | Exact outcome | -|---|---|---| -| Windows native authentication packages | PASS | All three required packages executed on final source. | -| Windows clone contract | FAIL / baseline | Executed after native PASS; PowerShell parser error at line 208. | -| LF, Compose, docs, and TypeScript | FAIL / baseline CI contract | Job `95724751205`; unified Compose passed, then `test-no-deployment-coupling-scope.sh` failed because `TMPDIR` was unset. Downstream skipped commands are `NOT_RUN` / `BLOCKED`. | -| Linux Docker deployment and rollback | FAIL / infrastructure prerequisite | Job `95724751356`; executed smoke stopped because `rg` was unavailable. Cleanup proof passed; no new image manifest was generated. | -| Native Windows Docker Desktop/WSL2 startup | NOT_RUN / BLOCKED | Job `95724752028` was skipped by workflow conditions; no Docker/WSL2 command executed. | -| Harness/Ruff/other historical baseline gates | FAIL | Retained with their recorded source and results; not rewritten as final-source proof. | -| L2, real PSD/manual acceptance, provider readiness | PENDING | Required secrets, identity/access, or provider prerequisites remain unavailable. | - -The historical Docker image manifest remains bound to source -`74b062f1a737103524cbe706346cfd65f87cdfd1`; it was not reused as proof for the final source. - -## Principal source commits - -- `cd5f505` — exhaustive cleanup, Windows authority foundation, restore deadlock tests/fix, and - complete workflow/plan package command. -- `a0e05ad` through `b6396e6` — effective full-control DACL semantics, valid NT attributes/access, - self-relative descriptors, retained no-delete fixture ordering, and Windows installation fixture - protection. -- `824245d` — preserve existing lifecycle ACL trees instead of mutating inherited authority. -- `455fffb`, `2d1670e`, `c01482c`, `9fc1a15` — concurrent claim/consume and settled-loss handling. -- `6474118` — one retained StageArchive root capability shared across staged files. -- `feee4ee` — unified Windows path wrappers on the retained primitive. -- `b261dd4` — bounded private-root sharing contention handling. -- `b48e9e9` — deterministic retained-remove concurrency regression and claim-operation lock. -- `10cd66f` — final lock boundary includes public path validation; frozen source. - -## Files changed - -Source changes relative to the fix-round base: - -- `.github/workflows/deployment.yml`; -- `docs/superpowers/plans/2026-08-18-thothii-authentication-remediation.md`; -- `tools/tht/internal/authstorage/storage_test.go`; -- `tools/tht/internal/backup/{create.go,create_test.go,fixture_security_unix_test.go,fixture_security_windows_test.go,preflight.go,preflight_test.go,preflight_windows_test.go,restore.go,restore_test.go}`; -- `tools/tht/internal/safeio/{claim_unix.go,claim_windows.go,claim_windows_test.go,files.go,files_test.go,private_root_windows.go,private_windows.go,private_windows_test.go}`. - -Evidence/status changes are restricted to: - -- `.artifacts/task-15/automated-gates.json`; -- `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md`; -- `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-1-report.md`; -- `.superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md`; -- `PROJECT_STATE.md`. - -Machine-readable evidence SHA-256: -`5c110b7b2607693de078def441b10290c5a29024c83b7e5a0ced894b72b7507f`. - -## Git and protection status - -- The evidence commit contains only the five evidence/status files listed above; no source is - changed after frozen source `10cd66fe6a5b484a4dc569326a228c1c5484a5d4`. -- After the evidence commit and push, the intended status is synchronized - `feat/thoth-auth...origin/feat/thoth-auth` with only protected untracked `.playwright-cli/` and - `.thothctl/`. -- `AGENTS.md`, `CLAUDE.md`, and `docs/agents/` are untouched. No generated `tools/tht/tht` exists. -- Evidence commit SHA is reported externally after commit creation because a commit cannot contain - its own final hash. diff --git a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md b/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md deleted file mode 100644 index 77f2fbbd..00000000 --- a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md +++ /dev/null @@ -1,133 +0,0 @@ -# Final-review fix round 2 report (sanitized) - -## Verdict - -- Base evidence head: `0f762ad6b67675356389cc546421a1c46ad5a736`. -- Frozen source: `2a9359071257f9b8a71d36ec2bbb25b161003f81` on `feat/thoth-auth`. -- Authentication remediation: **PASS**. -- Three original remediation Important findings: **RESOLVED**. -- Fix-round-2 bounded lifecycle Important: **ADDRESSED**. -- Fix-round-2 temporary Windows diagnostics Minor: **ADDRESSED**. -- Release readiness: **FAIL** for executed unrelated baseline gates, with unavailable - external/manual gates separately **PENDING**. -- Source and evidence are separate commits. The evidence-only phase changed no source or tests and - dispatched no workflow. - -## Finding disposition - -| Finding | Disposition | Evidence | -|---|---|---| -| Original Important — POSIX local-registry ownership | RESOLVED | Effective-UID ownership enforcement and its Node 24 coverage remain green at their recorded source. Fix round 2 did not alter this boundary. | -| Original Important — retained-capability StageArchive lifecycle | RESOLVED | Native Windows `internal/backup` passed on the exact source, preserving the retained-root staging and cleanup coverage. | -| Original Important — handle-relative Windows claim removal | RESOLVED | Native Windows `internal/safeio` and `internal/authstorage` passed on the exact source, including retained claim/consume coverage. | -| Fix-round-2 Important — fully bounded restore lifecycle test | ADDRESSED | Gate publication and release are context-aware; stage, outcome, admission, checkpoint, and verification waits are bounded; aborts cancel, safely release, bounded-join, then assert lock-free. The deterministic withheld-gate test proves prompt timeout/cancellation, worker join, and eventual lock release. | -| Fix-round-2 Minor — temporary Windows diagnostic matrix | ADDRESSED | `windowsRelativeOpenMatrix` and its diagnostic-only call/import were removed. Owner-only DACL shape, NT access normalization, full-control, cleanup, and retained no-delete tests remain. | - -The round-1 restore lifecycle finding was broadened by the scoped round-2 review: bounded release -alone was insufficient while stage publication, gate waits, and nearby outcome/admission waits -could still outlive a controller abort. The round-2 implementation closes that broader test -orchestration gap without changing production authentication semantics. - -## RED → GREEN record - -### RED - -The deterministic withheld-gate regression was introduced first and run without relying on a -global ten-minute package timeout: - -```text -go test ./internal/backup -run '^TestRestoreLifecycleCancellationJoinsWithWithheldGate$' -count=1 -``` - -It failed in approximately `0.64s` with: - -```text -cancelled restore worker did not join within the bounded deadline -``` - -This proved that cancellation did not yet unblock and join a worker retained at the lifecycle -gate. - -### GREEN and refactor - -- The gate uses a cancellation source shared by controller and worker. Both publication and - release are `select`-based and cancellation-aware. -- Shared bounded helpers cover stage, outcome, error, signal, release, and admission waits. -- Abort cleanup is ordered: cancel, cancel the controller gate when distinct, safely release a - pending gate, bounded-join the worker, then prove the lifecycle lock is free. -- Premature worker outcomes retain and surface their original error. -- The existing success, recovery, maintenance-barrier, stale-checkpoint, and verification - assertions remain active. - -Final local gates on the frozen source: - -```text -go test ./internal/backup -run '^(TestRestoreLifecycleCancellationJoinsWithWithheldGate|TestReleaseLifecycleStage|TestRestoreLifecycleLockExcludesCompetingTransactionsUntilTerminalCleanup|TestRestoreCannotApplyAStaleCheckpointOverAnInterleavedRestore|TestRestoreKeepsAdmissionBarrierActiveUntilVerificationCommits)$' -count=1 -go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1 -go test ./... -count=1 -go test -race ./... -go vet ./... -go build -o /tmp/thothii-tht-host-fix-round-2 ./cmd/tht -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go test -c ./internal/safeio -o /tmp/tht-safeio-fix-round-2-windows.test.exe -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go test -c ./internal/backup -o /tmp/tht-backup-fix-round-2-windows.test.exe -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go test -c ./internal/authstorage -o /tmp/tht-authstorage-fix-round-2-windows.test.exe -GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o /tmp/thothii-tht-fix-round-2-windows.exe ./cmd/tht -``` - -All commands passed. The final focused lifecycle run completed in `0.672s`; the full security -package run passed safeio, backup, and authstorage; race, vet, host build, Windows test-package -cross-compiles, and Windows CLI cross-compile also passed. Cross-compilation is recorded only as -compile evidence and is not used as native authority. - -## Exact-source native certification - -- Controller-authorized run: `32147345625` — - https://github.com/mptyl/ThothII/actions/runs/32147345625. -- Event/status/conclusion: `workflow_dispatch` / `completed` / `failure`. -- Head SHA: `2a9359071257f9b8a71d36ec2bbb25b161003f81`, exactly matching the frozen source. -- Windows job: `Windows clone and Compose contract`, job `95744249248` — - https://github.com/mptyl/ThothII/actions/runs/32147345625/job/95744249248. -- Native step: `Run native Windows retained-capability tests` — **PASS**. -- Exact unfiltered command: - `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`. -- Native package results: - - `internal/safeio` PASS (`22.058s`); - - `internal/backup` PASS (`7.161s`); - - `internal/authstorage` PASS (`16.088s`). - -The Windows job failed only in the following baseline clone-contract step. PowerShell reported a -parser error at `scripts/test-windows-clone-contract.ps1:208` because `$remoteYaml:` is not a -delimited variable reference. This later failure does not alter the successful native Go step. - -## Separate release-readiness verdict - -| Gate | Classification | Exact outcome | -|---|---|---| -| Authentication remediation | PASS | Source and exact-source native three-package authority are green. | -| Windows clone contract | FAIL / baseline | Job `95744249248`; parser error at `scripts/test-windows-clone-contract.ps1:208`, after native PASS. | -| LF, Compose, docs, and TypeScript | FAIL / baseline CI contract | Job `95744249458`; unified Compose passed, then the existing unset-`TMPDIR` failure stopped the contract step. Downstream commands were skipped. | -| Linux Docker deployment and rollback | FAIL / infrastructure prerequisite | Job `95744249354`; the existing missing-`rg` prerequisite stopped the smoke before deployment. Cleanup passed and no new image manifest was generated. | -| Native Windows Docker Desktop/WSL2 startup | NOT_RUN / BLOCKED | Job `95744250450` was skipped by workflow conditions; no native Docker/WSL2 command ran. | -| L2, real PSD/manual acceptance, provider readiness | PENDING | Required secrets, identity/access, or provider prerequisites remain unavailable. | - -Executed failures remain `FAIL`; skipped commands are `NOT_RUN` / `BLOCKED`; unavailable external -gates remain `PENDING`. Therefore remediation PASS does not imply release readiness PASS. - -## Evidence and protection status - -- Machine-readable evidence: `.artifacts/task-15/automated-gates.json`; SHA-256 - `6c516db5c2064c4a4a2e5f25961b993cd4a8fe020bbbb822fbac7faa0c119599`. -- Current Task 4 report: - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md`. -- Retained Task 15 report: - `.superpowers/sdd/2026-08-16-thothii-authentication/task-15-report.md`. -- Project snapshot: `PROJECT_STATE.md`. -- Historical Docker evidence remains bound to its recorded older source and is not reused as proof - for `2a9359071257f9b8a71d36ec2bbb25b161003f81`. -- `.playwright-cli/` and `.thothctl/` remain protected and untracked. No source/test file, - instruction file, workflow, or `docs/agents/` content changed in this evidence phase. -- The separate evidence commit SHA is reported after commit creation because a commit cannot - contain its own final hash. - -No credentials, tokens, internal endpoints, identities, registry names, raw environments, or -browser traces are retained in this report. diff --git a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md b/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md deleted file mode 100644 index 6a6d3b8c..00000000 --- a/.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md +++ /dev/null @@ -1,131 +0,0 @@ -# Task 4 authentication remediation recertification (sanitized) - -## Fix-round-2 recertification — remediation PASS - -- Exact source: `2a9359071257f9b8a71d36ec2bbb25b161003f81` on `feat/thoth-auth`. -- Authorized workflow: completed run `32147345625`, - https://github.com/mptyl/ThothII/actions/runs/32147345625, exact matching head SHA. -- Native job: `Windows clone and Compose contract`, job `95744249248`. -- Required native step: `Run native Windows retained-capability tests` — **PASS**. -- Exact unfiltered command: - `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`. -- Package evidence: `internal/safeio` PASS (`22.058s`), `internal/backup` PASS (`7.161s`), - `internal/authstorage` PASS (`16.088s`). This includes explicit native Windows - StageArchive retained-capability and concurrent claim-consume coverage. -- The later `Verify Windows clone contract` step failed independently at - `scripts/test-windows-clone-contract.ps1:208`: PowerShell parsed `$remoteYaml:` as an invalid - variable reference. This baseline deployment-contract failure does not change the native Go - package result. -- The optional `Native Windows Docker Desktop/WSL2 startup` job was skipped by workflow - conditions. It is `NOT_RUN` / `BLOCKED`, because no Docker Desktop/WSL2 command executed. -- The workflow reached `completed` with conclusion `failure`: the native authentication step is - PASS, while the later clone-contract, LF/Compose, and Linux Docker baseline steps are FAIL. -- Existing LF/Compose job `95744249458` and Linux Docker job `95744249354` failures repeated - before downstream work. Skipped commands are `NOT_RUN` / `BLOCKED`, not executed failures. - External L2/PSD/provider gates remain `PENDING`. - -Finding disposition is explicit: the three original remediation Important findings remain -**RESOLVED**; the fix-round-2 lifecycle Important is **ADDRESSED**; and the temporary Windows -diagnostic-matrix Minor is **ADDRESSED**. Authentication remediation is **PASS**. This does not -change overall release readiness: executed baseline gates remain **FAIL**, while unavailable -external/manual gates remain **PENDING**. - -The section below is retained as historical evidence for the pre-fix frozen source. - -## Historical pre-fix result - -- Frozen source under test: `b31b27e5845ffd3adf311429367319beaba263c7` on `feat/thoth-auth`. -- Freeze check: PASS. No tracked source changed during certification. The only untracked paths - retained are `.playwright-cli/` and `.thothctl/`. -- Certification window: `2026-08-18T09:26Z` to `2026-08-18T09:48:36Z` (UTC; the start marker is - minute-precision because no earlier second-level operator timestamp was captured). -- Overall result: `FAIL` / `CHANGES_REQUIRED`. The three Important findings are not closed and - authentication is not implementation-complete or release-complete. - -## Local gate matrix - -| Gate | Result | Sanitized evidence | -|---|---|---| -| Go focused security tests | PASS | `safeio`, `backup`, and `authstorage`; 3 packages | -| Go race/vet/host build | PASS | 18 race-tested packages; vet and host CLI build exit 0 | -| Windows amd64 cross-compile | PASS | focused safeio/backup test binaries and CLI build; compile-only | -| POSIX registry ownership | PASS | Node 24 backend suite includes local-registry ownership coverage | -| Unix StageArchive retained capability | PASS | focused safeio/backup and race coverage passed on host | -| Backend Node 24 | PASS | 76 files / 1092 tests; typecheck and build passed | -| Frontend Node 24 | PASS | 61 files / 444 tests; typecheck and build passed | -| Authentication/F1 browser smoke | PASS | Node `v24.16.0`; filtered E2E 1 passed; sentinel scan passed | -| Harness pytest | FAIL | 951 passed, 1 failed, 4 skipped, 232 subtests; `test_f4_emits_column_types` could not find `workflow.yaml` from its test cwd | -| Ruff | FAIL | 192 errors; known baseline | -| Authentication docs smoke | PASS | required-term and forbidden-word checks passed | -| Shell syntax | PASS | `bash -n scripts/*.sh` | -| Default Compose contract | FAIL | required `THT_WORKSPACE_GIT_REMOTE` was unavailable | -| Unified Compose contract | FAIL | `compose.unified.yaml` is absent from the frozen source | -| Unified Docker smoke | FAIL | workflow attempted it on the frozen SHA but stopped before deployment because `rg` was unavailable; cleanup proof passed and no new image manifest was generated | -| L2 / PSD manual / provider readiness | PENDING | required external secrets, identities/access, or provider prerequisites unavailable/not reached | - -The first full backend Vitest attempt had one workspace-registry timeout. The focused test and a -fresh complete rerun passed, so the current backend result above is the fresh complete rerun. - -## Native Windows authority - -The authorized dispatch was bound to the frozen SHA: - -- Run: `32122302381` -- URL: https://github.com/mptyl/ThothII/actions/runs/32122302381 -- Head SHA: `b31b27e5845ffd3adf311429367319beaba263c7` -- Workflow conclusion: `failure` -- Job: `Windows clone and Compose contract`, job `95665197885` -- Job URL: https://github.com/mptyl/ThothII/actions/runs/32122302381/job/95665197885 -- Native step: `Run native Windows retained-capability tests` — `failure` -- Executed command: `go test ./internal/safeio ./internal/backup -count=1` -- Observed focused failures include `TestRemoveCanonicalPrivateClaimRetainsParentDuringDeletion` - and `TestRemoveCanonicalPrivateClaimPreservesOrphan`. -- The backup package timed out in - `TestRestoreLifecycleLockExcludesCompetingTransactionsUntilTerminalCleanup` after `10m0s`. -- Additional backup failures included retained-staging `unsafe file` results, Windows temporary-file - cleanup reporting that a file was still in use, and fixture cases that could not read external - secret declarations. The first two categories are remediation/security-boundary failures; the - fixture declaration failures are recorded as an accompanying CI-fixture issue. -- `internal/authstorage` was not requested by the frozen workflow step and therefore has no native - Windows execution evidence. Cross-compilation does not substitute for this gate. - -This native failure is the blocking gate. No source fix was attempted, and no later Docker smoke -was run locally after the failure. - -## Other workflow failures - -- `LF, Compose, docs, and TypeScript` (job `95665197839`) failed in - `Verify Compose and installation contracts` after the unified Compose contract itself passed. - `test-no-deployment-coupling-scope.sh` aborted on `TMPDIR: unbound variable`; this is classified - as a baseline/CI contract prerequisite, and later docs/TypeScript steps were skipped. -- `Linux Docker deployment and rollback` (job `95665197846`) failed before deployment because the - runner did not provide `rg` (`Task 13 smoke failed: rg is required`). The sanitized cleanup proof - passed and no Docker image manifest was generated. This is classified as an infrastructure - prerequisite failure, not as evidence of a remediation regression. - -## Evidence and provenance - -- Current machine-readable matrix: `.artifacts/task-15/automated-gates.json`; SHA-256 - `6c516db5c2064c4a4a2e5f25961b993cd4a8fe020bbbb822fbac7faa0c119599`. -- Current requested report: this file (SHA-256 recorded after the evidence commit if needed for - external indexing). -- Current fix-round report: - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md`. -- Historical Docker image manifest: `.artifacts/task-15/unified-docker-images.json`, unchanged - because no new immutable-source Docker smoke ran. Its retained historical SHA-256 is - `9c8dec4546909fd93799dbcf374bcb3a89bc46cfe0fd482472c0cbe757ddf5b6`, bound to historical source - `74b062f1a737103524cbe706346cfd65f87cdfd1`, not to this Task 4 candidate. -- The historical Task 15 report remains provenance for earlier source SHAs; its current addendum - records this recertification separately. - -No credentials, tokens, internal endpoints, provider identities, registry names, raw environments, -or browser traces are retained here. - -## Separate verdicts - -- Three Important findings: `CHANGES_REQUIRED`. Native Windows retained-capability authority - failed, and the frozen workflow omits the required `authstorage` package from its native command. -- Overall release readiness: `FAIL` with additional `PENDING` gates. The native Windows remediation - gate failed; the remote Docker attempt failed on a missing runner prerequisite; existing - Ruff/harness/Compose failures and external/manual prerequisites remain unresolved; and no - successful new unified Docker image evidence exists. diff --git a/.superpowers/sdd/2026-08-24-evidence-restructuring/final-fix-report.md b/.superpowers/sdd/2026-08-24-evidence-restructuring/final-fix-report.md deleted file mode 100644 index 49f19fb4..00000000 --- a/.superpowers/sdd/2026-08-24-evidence-restructuring/final-fix-report.md +++ /dev/null @@ -1,175 +0,0 @@ -# Final-review fix report — Evidence #43–#46 - -Date: 2026-08-25 - -Base ThothII revision: `d4818c8cc33b8b11204377ff3cc65c6c9ee1425e` - -Binding inputs: - -- requirements: `docs/plans/2026-08-24-evidence-restructuring.md`; -- approved design: `docs/plans/2026-08-24-evidence-restructuring-design.md`; -- final review: `.superpowers/sdd/2026-08-24-evidence-restructuring/final-review.md`. - -No PSD path was read or mutated during this fix wave. No issue was closed. - -## Verdict - -All three Important findings are fixed. Candidate evaluation remains mandatory for schema-v2 -filesystem curated corpora and is absent for legacy v1, HTTP-only, and S3-only acquisition. -Reviewed formula migration now fails closed unless the caller supplies the exact original source, -the source parses back to the same formula, and every supporting excerpt is present after the -canonical mechanical normalization. Current owner-gate summaries explicitly distinguish the -immutable 225-test owner-gate observation from the expanded 230-test final-review verification and -place stale 222/224-era statements under an explicitly superseded historical section. - -## RED/GREEN record - -### Finding 1 — evaluator compatibility boundary - -RED: - -```text -cd harness -.venv/bin/pytest -q tests/test_preprocess_cli.py tests/test_evidence_formula_migration.py \ - tests/test_evidence_restructuring_fixture.py \ - -k 'candidate_evaluation_is_not_required or runtime_identity' -6 failed, 18 deselected, 1 warning -``` - -The v1 filesystem run still received a callable evaluator; v1 HTTP/S3 and v2 HTTP/S3 attempted to -resolve a filesystem evaluation root before the pipeline could run. - -GREEN: - -```text -6 passed, 9 deselected, 1 warning -``` - -`_requires_candidate_evaluation()` is now the single boundary used by both curated-corpus -validation and evaluator construction. It returns true only for `schema_version: 2` with a -filesystem source (including an explicit filesystem `source_root`). The existing integrated v2 -candidate test remains the positive proof: it validates the corpus, performs all nine -candidate-generation searches while inactive, publishes only after PASS, and compensates a failed -candidate. - -### Finding 2 — formula provenance - -RED: - -```text -cd harness -.venv/bin/pytest -q tests/test_evidence_formula_migration.py \ - tests/test_evidence_restructuring_fixture.py -5 failed, 4 passed, 1 warning -``` - -The converter rejected the new `source_content` argument, returned clean Curated Evidence when no -original source was supplied, and the documentation consistency assertion still failed. - -GREEN: - -```text -cd harness -.venv/bin/pytest -q tests/test_evidence_formula_migration.py tests/test_formula.py \ - tests/test_formula_wiring.py tests/test_preprocess_cli.py \ - tests/test_evidence_candidate_publication.py -39 passed, 1 warning -``` - -The migration now: - -1. returns `None` unchanged for `auto` and `draft` formulas; -2. requires original source content for a reviewed formula; -3. normalizes it with the authoring validator's `normalize_source_text()`; -4. parses it and requires equality with the supplied `ConceptFormula`; -5. requires one or more legacy provenance notes and verifies each note in normalized source text; -6. hashes the verified normalized original source, never `formula.dump()`; -7. returns `LegacyFormulaMigrationFailure(code="legacy_formula_requires_manual_review")` with - bounded problem codes for missing, invalid, mismatched, or excerpt-incomplete provenance. - -The regression matrix covers exact original formatting, deterministic digest, absent original -source, absent excerpts, a YAML-folded excerpt that cannot validate literally, mismatched original -formula content, invalid full-query Formula Evidence, stable path-derived IDs, and unreviewed -session-only behavior. - -### Finding 3 — current owner-gate record - -RED: - -```text -cd harness -.venv/bin/pytest -q tests/test_evidence_restructuring_fixture.py \ - -k current_summaries -1 failed, 3 deselected, 1 warning -``` - -The current report did not contain the fresh expanded-suite result. Earlier RED also showed that -the leading report still lacked an authoritative read-only PSD summary and `PROJECT_STATE.md` -still said 222. - -GREEN: - -```text -4 passed, 1 warning -``` - -The task report now begins with one authoritative current record and moves all earlier scope/count -statements below `Historical record — explicitly superseded`. The manual and `PROJECT_STATE.md` -record both immutable observations without conflating them: 225 passed at the reviewed `d4818c8` -owner gate; 230 passed after five final-review regressions entered the selected acceptance files. -Both summaries describe the authorized PSD package as read-only, with 35 moveable sources plus the -retained README, narrow no-payload/no-vector observations, no secrets, and no mutation. Issue #47 -still owns migration and manual acceptance. - -## Requirement mapping - -| Requirement | Implementation evidence | Verification | -| --- | --- | --- | -| v1 filesystem remains viable without `evaluation.yaml` or a new curated tree | `_requires_candidate_evaluation()` returns false for schema v1; `run_from_config()` passes `None` | v1 runtime identity test and parameterized filesystem case | -| HTTP/S3 preserve existing behavior | evaluator construction returns `None` for HTTP-only/S3-only configs in schema v1 and v2 | four parameterized HTTP/S3 cases | -| v2 filesystem evaluation remains mandatory | shared predicate drives validation and evaluator; no permissive missing-fixture path was added | integrated inactive-candidate publication/failure-compensation test | -| formula digest represents verified normalized original | caller supplies `source_content`; authoring normalization computes digest | literal SHA-256 assertion from independently normalized original fixture | -| formula and source cannot silently mismatch | original source is parsed and compared with the supplied model | `original_source_mismatch` regression | -| supporting excerpts are real and nonempty | notes are required and each normalized note must occur in normalized source | missing and folded/unverifiable excerpt regressions | -| unverifiable migration requires human resolution | every provenance failure returns the existing bounded manual-review result | exact code/problem assertions preserve original path and formula | -| current acceptance record is unambiguous | authoritative current sections plus explicit historical supersession | owner-gate document consistency test | -| PSD scope remains read-only | no PSD tool/path used in fix; current docs retain issue #47 authorization gate | diff review and acceptance isolation probe | - -## Verification evidence - -```text -focused Evidence compatibility/formula/candidate: 39 passed, 1 warning -owner-gate document contract: 4 passed, 1 warning -harness full: 1093 passed, 4 deselected, 53 warnings -harness Ruff: All checks passed! -acceptance runner: 230 passed, 1 warning; PASS -backend TypeScript: PASS -native tht build: PASS -git diff --check: PASS -``` - -The full backend Vitest gate remains outside this patch's modified files and reported 13 failures: -the ten previously recorded auth-runtime projection failures, the recorded Node 25 versus Node 24 -contract failure, the recorded Argon2 401/429 timing assertion, plus one Windows timeout-helper -marker failure that is timing-sensitive and was not part of the prior stable 12-failure baseline. -The native Go suite with `-timeout 20s` reproduced the recorded authconfig timeout and backup/setup -failures. These unrelated failures were not repaired or hidden; backend TypeScript and native build -both pass. - -## SHA-256 artifact hashes - -```text -193f9e83634c17160dc5f589ee392f6cefbca2e24efa0770181500e7dce008a7 PROJECT_STATE.md -4f9cfb213fdfbab481fcad9eeb0002ab0bd69d83d7ef0c459c5fccd5f5b44048 docs/testing/evidence-restructuring-manual.md -e47862d4bf9b846f059ef133b77a6311fbeb297671843bfeda0d0445eb2e4933 harness/tht/cli/preprocess_cmd.py -4017f66dc6d3aeaa4f0294bbca581b8d447e3b60bd8daff4efff08048dc43d4b harness/tht/evidence/formula_store.py -35bd73f6d0759cf0c8cb15a9125cc97b5dda64eb02417eda9dd1a9c82ed8a558 harness/tests/test_preprocess_cli.py -a0affbf9213c41c95d5fea8e596ef37ae21836e0df9bdfa8f6adda95d9238fb6 harness/tests/test_evidence_formula_migration.py -6ed7d7679c860c6edc54cbcfc2a04db89c7d32ecab80c7daa72be96cdc14f164 harness/tests/test_formula.py -26d886074244be7cf6ca084f859dcbc0c0ade74c302077a506198a2e96bfc07e harness/tests/test_evidence_restructuring_fixture.py -62743e885230823f8942d14feadae511b6d09b5d391807a04d10a164f71dd919 .superpowers/sdd/2026-08-24-evidence-restructuring/task-12-report.md -e753674bb55d4880448a51e7fbdb3ccf506800ecc5fd3b73f59ed655cf9b63c7 tracked working-tree diff before this report -``` - -The final commit hash is reported with the completed handoff because a commit cannot include its -own hash without changing itself. diff --git a/.superpowers/sdd/2026-08-24-evidence-restructuring/task-12-report.md b/.superpowers/sdd/2026-08-24-evidence-restructuring/task-12-report.md deleted file mode 100644 index d488609e..00000000 --- a/.superpowers/sdd/2026-08-24-evidence-restructuring/task-12-report.md +++ /dev/null @@ -1,276 +0,0 @@ -# Task 12 report — owner migration gate (#46) - -## Current owner-gate record - -This section supersedes every historical section below. The owner-gate run at `d4818c8` observed -**225 passed, 1 warning**. The final-review fix added five regressions to the selected files; its -fresh run of `bash scripts/evidence-restructuring-acceptance.sh` observed **230 passed, 1 warning**. -Both runs remained hermetic: they used only an isolated temporary authoring workspace and did not -receive or mutate a PSD path. - -The authorized read-only PSD owner-gate package inspected the clean repository at immutable -commit `47516f85b4db4a67cfa8a86cea4cb2e7b98c5813`. It recorded 35 moveable source documents plus -the retained `psd-clinical/evidence/README.md` (36 current Evidence files total), and the narrow -legacy Qdrant baseline: 163 `schema_table`, 2,275 `schema_column`, 2 `memory`, and 1 -`solved_question`. The replacement observations used exact filtered counts and at most three IDs -per kind with `with_payload:false` and `with_vector:false`. PSD Git status remained clean; no -secret was read and no external mutation, branch, migration, activation, commit, or push occurred. - -The real Pi call, PSD migration, human Git review, authoritative pre/post vector inspection, -activation, and complete manual walkthrough remain pending in issue #47 until the owner -authorizes the migration window and exact target branch. The current package is read-only -preparation, not migration or manual acceptance. - -## Historical record — explicitly superseded - -Everything below preserves the sequence of earlier Task 12 runs for audit history only. Counts, -scope statements, and pending-inventory wording below are not current; the current owner-gate -record above and `docs/testing/evidence-restructuring-manual.md` are authoritative. - -### Initial scope and boundary - -Implemented only ThothII-local artifacts: - -- `harness/tests/fixtures/evidence_authoring/poorly_structured.md` supplies prose, a - rough list, enum values, URL, ambiguity, and a PostgreSQL-expression candidate. -- `scripts/evidence-restructuring-acceptance.sh` uses a fake restructurer and an - isolated `mktemp` authoring workspace. It never receives, discovers, or accesses a - PSD path; it also asserts that the ThothII worktree status is unchanged. -- `docs/testing/evidence-restructuring-manual.md` is the owner-gate package and manual - procedure. It intentionally leaves the PSD 36-path inventory, PSD commit, and - before-counts pending authorization. -- `PROJECT_STATE.md` records only the observed hermetic result and says that issue #47 - is pending. - -No external PSD authoring repository was accessed, modified, staged, migrated, or -inspected. No GitHub issue was closed. - -### Initial TDD record - -RED: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_restructuring_fixture.py -FAILED: FileNotFoundError for fixtures/evidence_authoring/poorly_structured.md -``` - -GREEN: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_restructuring_fixture.py -1 passed -cd harness && .venv/bin/ruff check . -All checks passed! -``` - -### Initial hermetic acceptance evidence - -```text -bash scripts/evidence-restructuring-acceptance.sh -PASS hermetic fake-restructurer: split, review, Git recovery/diff, no-op, dirty, upgrade, orphan -PASS isolation: only a temporary workspace was supplied; no external PSD path was read or written -222 passed, 1 warning -PASS evidence restructuring automated acceptance -``` - -The runner directly proves typed splitting; visible unresolved-review and orphan -validation failures; one-source manifest membership; recovery of the committed curated -baseline and a visible Git diff; unchanged no-op; dirty-state refusal; no-write -pipeline mismatch refusal and explicit all-source upgrade. Its selected suites cover -all eight typed kinds, no-tool/no-session Pi invocation, formula acceptance/rejection, -atomic semantic chunking and the 4,000-character policy, candidate evaluation and -inactive-generation failure behavior, deterministic query rendering, hybrid branch and -fused ranks, fail-closed search, and the pinned Qdrant Italian-BM25 L0 contract. - -### Initial required local gates - -| Gate | Result | -| --- | --- | -| `harness/.venv/bin/pytest -q` | PASS — 1080 passed, 4 deselected, 53 warnings | -| `harness/.venv/bin/ruff check .` | PASS | -| `backend/npx tsc --noEmit -p .` | PASS | -| `backend/npx vitest run` | FAIL — pre-existing failures listed below | -| `tools/tht/go build ./cmd/tht` | PASS | -| `tools/tht/go test ./...` | FAIL / timeout — pre-existing failures listed below | -| `bash scripts/evidence-restructuring-acceptance.sh` | PASS — 222 passed, 1 warning | - -#### Baseline proof for unrelated failures - -The immutable pre-task source `0caa747` was checked out to a temporary detached -worktree. Its targeted backend run reproduced the same 12 stable failures: - -- all ten failures in `test/auth-runtime-projection.test.ts` (`authentication runtime - projection is invalid`); -- `test/health.test.ts` expects Node 24 but the host runs Node 25; -- `test/auth-routes-local.test.ts` expects the third Argon2 request to receive 429 but - receives 401. - -The native host suite was run first unbounded and remained silent for more than seven -minutes, then was rerun with `go test ./... -timeout 20s`. Both the task worktree and -the detached `0caa747` baseline reproduce the same failures: - -- `internal/authconfig: TestRunProjectedMutationHoldsOuterLockAcrossCanonicalAndProjection` - times out; -- `internal/backup` restore/auth publication assertions fail; -- `internal/setup` projected-server/root assertions fail. - -These packages and backend files were not changed by Task 12. The suite failures are -therefore recorded as pre-existing concerns and were not repaired or hidden. - -### Initial pending owner decision - -Focused ThothII commit: `fc83d29b5836b4db173e0874689426ecf2da526f` -(`test(evidence): record restructuring acceptance`). Issue #46 is ready for the owner -migration authorization gate. Issue #47 remains pending: the owner must authorize the -migration window and exact PSD branch before any external repository inspection, -36-file inventory, migration, validation, activation, or manual PSD acceptance work -begins. - -### Fix round 1 evidence (Task 12 review) - -#### TDD - -RED: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_candidate_publication.py tests/test_evidence_restructuring_fixture.py -FAILED: acceptance runner did not include test_evidence_candidate_publication.py -``` - -The first integrated-test draft also exposed that the real configuration refuses a -non-1024 embedding dimension; the fake was corrected to model the production contract -instead of bypassing configuration loading. - -GREEN: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_candidate_publication.py tests/test_evidence_restructuring_fixture.py -3 passed, 1 warning -cd harness && .venv/bin/ruff check tests/test_evidence_candidate_publication.py tests/test_evidence_restructuring_fixture.py -All checks passed! -bash scripts/evidence-restructuring-acceptance.sh -224 passed, 1 warning -``` - -The new integrated test invokes the real v2 canonical-corpus validator, the real -`preprocess_cmd._candidate_evaluator`, and `CorpusPipeline`, with an observable store, -vector writer, and searcher. It records nine exact-generation branch searches (dense, -BM25, fused for lexical, semantic, and mixed queries), asserts that the candidate is -not ACTIVE during any search, publishes only after the PASS report, then proves a -failed candidate remains inactive and is compensated. It also asserts the 4,000 default, -rendered fragment bound, and rejection/absence of parallel vector-size aliases. - -The acceptance probe now creates a real temporary Git repository, commits its initial -and proposed corpus, makes `evidence/curated` genuinely dirty, and calls -`prepare_workspace_evidence` with the default Git-status detection path. It restores -the temporary file before continuing; no injected `git_status` is used by the dirty -case, no-op, pipeline mismatch, or explicit upgrade checks. - -#### Authorized read-only PSD preparation - -The PSD repository was inspected read-only at immutable commit -`47516f85b4db4a67cfa8a86cea4cb2e7b98c5813`. `git status --porcelain` was empty before -and after, `git diff --quiet` succeeded after, and no PSD secret, worktree content -beyond the listed source names, or mutation command was used. The exact 36 paths, -concrete rollback command, and Qdrant baseline are now in -`docs/testing/evidence-restructuring-manual.md`. - -Read-only Qdrant observation for `127.0.0.1:6333`, collection `psd-clinical`: -`schema_table=163`, `schema_column=2275`, `memory=2`, `solved_question=1`; the manual -records representative IDs. The standard `tht workspace vector inspect --json` command -was attempted, but its temporary maintenance container stopped before Qdrant access -because production auth configuration was unavailable. No secret was read to bypass -that guard; the owner-gate package explicitly requires repeating the contract command -immediately before authorized preprocessing. - -Fresh no-write verification after the inspection: - -```text -status_lines=0 diff_quiet_exit=0 -head=47516f85b4db4a67cfa8a86cea4cb2e7b98c5813 -``` - -Fresh required-gate evidence for this fix round: - -```text -harness pytest: 1082 passed, 4 deselected, 53 warnings -harness ruff: PASS -acceptance runner: 224 passed, 1 warning -backend tsc: PASS -backend vitest: 12 failures, exactly reproduced at baseline 0caa747 -Go build: PASS -Go test -timeout 20s: authconfig timeout plus backup/setup failures, exactly reproduced at baseline 0caa747 -``` - -Fix-round commit: `8542124f2737354b7ae35973933fc38ca85a31c1` -(`test(evidence): harden owner gate acceptance`). - -### Fix round 2 evidence (Task 12 re-review) - -#### TDD - -RED: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_restructuring_fixture.py -1 failed, 2 passed, 1 warning -``` - -The new manual-contract test failed because the package still described 36 source -documents and retained the old broad Qdrant request. - -GREEN: the package now distinguishes exactly 35 moveable source documents from the -retained `psd-clinical/evidence/README.md` (36 current evidence files total). The -authorized migration instruction moves exactly the 35 listed documents to -`evidence/source/` and retains the README at its current path; the owner-only rollback -restores the immutable pre-migration SHA. - -#### Narrow replacement Qdrant baseline - -The prior `with_payload:true` full-collection scroll was out-of-scope and is withdrawn -as evidence. It is not a permitted fallback, and this report makes no claim that it -did not materialize payloads. - -On 2026-08-25, the replacement baseline sent, for each of `schema_table`, -`schema_column`, `memory`, and `solved_question`: - -```text -POST /collections/psd-clinical/points/count -{"filter":{"must":[{"key":"record_kind","match":{"value":""}}]},"exact":true} - -POST /collections/psd-clinical/points/scroll -{"filter":{"must":[{"key":"record_kind","match":{"value":""}}]},"limit":3,"with_payload":false,"with_vector":false} -``` - -The resulting no-payload/no-vector observations were: - -```text -schema_table=163: 01bc2535-24d6-5722-a58b-64a122b90b36, - 024ddf60-c80d-5223-ac06-9247e7de7027, 086e00c8-b4a9-5063-b82d-e5a67add29cd -schema_column=2275: 00126cc1-7564-521a-a084-c2d670263258, - 00365200-2c55-5bb4-86bb-87dd2d1bb529, 004304bc-b543-5b2d-8b40-f18da8e82af7 -memory=2: 8d5cd772-563a-5e22-b764-2ca76cf6efca, - db74457a-3de8-5b95-9a31-d28a1ecf8141 -solved_question=1: 2b6bb7d2-1a35-5f49-bd8d-b0cdcb98459a -``` - -No secret was read, no PSD mutation/stage/branch/commit/migration/activation/push command -was invoked, and the PSD repository remained at -`47516f85b4db4a67cfa8a86cea4cb2e7b98c5813` with empty porcelain status and a successful -`git diff --quiet` after the replacement queries. The standard `tht workspace vector -inspect --json` attempt remains blocked by missing production auth and must be repeated -successfully immediately before any owner-authorized preprocessing. - -Focused correction gates: - -```text -cd harness && .venv/bin/pytest -q tests/test_evidence_restructuring_fixture.py -3 passed, 1 warning -cd harness && .venv/bin/ruff check tests/test_evidence_restructuring_fixture.py -All checks passed! -bash scripts/evidence-restructuring-acceptance.sh -225 passed, 1 warning -``` - -Fix-round commit: `d4818c8cc33b8b11204377ff3cc65c6c9ee1425e` -(`docs(evidence): narrow owner gate baseline`). diff --git a/.superpowers/sdd/adapter-final-fix-report.md b/.superpowers/sdd/adapter-final-fix-report.md deleted file mode 100644 index dfdd4c7e..00000000 --- a/.superpowers/sdd/adapter-final-fix-report.md +++ /dev/null @@ -1,137 +0,0 @@ -# Adapter Foundations final-review fix report - -Date: 2026-07-11 -Branch: `codex/portable-deployment` -Worktree: `/Users/mp/projects/ThothII/.worktrees/portable-deployment` -Binding findings: `.superpowers/sdd/adapter-final-review-findings.md` - -## Outcome - -All seven final-review findings are addressed as one coherent adapter-foundations change: - -1. HTTP vector reader and writer clients are independently optional. Capabilities reflect the - configured side; writer-only new and legacy configurations build successfully for targeted - writes; search without a reader raises public `VectorReadUnavailable`. -2. `VectorHealth` now reports read/write configured and reachable state independently, preserves - side-specific errors, and reports expected/observed embedding dimensions plus compatibility. - HTTP diagnostics cover read-only, write-only, both-up, and writer-down cases. Direct health - exposes its configured expected dimension without adding schema or migration work. -3. `ThothRestDwhAdapter` accepts `DatabaseIdentityConfig`, matching its resource contract. -4. Both vector adapters reject bools, floats, zero, and negative search limits using one exact - positive-integer guard. -5. Port tests explicitly cover public exports and frozen capability records. -6. A real `tht` subprocess test proves one legacy deprecation warning per config load on stderr - while JSON stdout remains parseable and uncontaminated. -7. The adapter plan and SDD progress explicitly constrain `build_vector_loader` to transitional - bulk sync and schedule its removal/migration in the local pgvector plan. Targeted memory and - solved-question writes remain on `build_vector_store(..., require_write=True)`. - -No pgvector schema or migration changes were made. - -## Files changed - -- `harness/tht/ports/vector.py` -- `harness/tht/ports/__init__.py` -- `harness/tht/adapters/vector/thoth_http.py` -- `harness/tht/adapters/vector/legacy_direct.py` -- `harness/tht/adapters/factory.py` -- `harness/tht/adapters/dwh/thoth_rest.py` -- `harness/tests/test_vector_port_contract.py` -- `harness/tests/test_adapter_factory.py` -- `harness/tests/test_config_resources.py` -- `harness/tests/test_config_legacy_compat.py` -- `harness/tests/test_adapter_command_regressions.py` -- `harness/tests/test_dwh_port_contract.py` -- `docs/superpowers/plans/2026-07-11-adapter-foundations.md` -- `.superpowers/sdd/progress.md` -- `.superpowers/sdd/adapter-final-fix-report.md` - -## TDD and verification evidence - -RED: - -```text -cd harness && .venv/bin/pytest tests/test_vector_port_contract.py \ - tests/test_adapter_factory.py tests/test_config_resources.py \ - tests/test_config_legacy_compat.py -q -``` - -Result: collection failed as expected because `VectorReadUnavailable` did not exist. After the -initial implementation, the same command exposed two expected contract/test-harness corrections: -dimension mismatch makes aggregate health unhealthy, and the installed CLI entry point is `tht` -rather than `python -m tht.cli`. - -GREEN, covering adapter/config/command regressions: - -```text -cd harness && .venv/bin/pytest tests/test_vector_port_contract.py \ - tests/test_adapter_factory.py tests/test_config_resources.py \ - tests/test_config_legacy_compat.py tests/test_adapter_command_regressions.py \ - tests/test_dwh_port_contract.py tests/test_memory_save_one.py \ - tests/test_solved_question.py tests/test_search_similar_kinds.py \ - tests/test_vector_dual_key.py -q -``` - -Result: `66 passed in 0.45s`. - -Docker availability: - -```text -docker info --format '{{.ServerVersion}}' -``` - -Result: `29.4.1` (available; command required Docker socket access). - -Full repository-default non-L2 harness suite, with Docker available for L0 tests: - -```text -cd harness && .venv/bin/pytest -q -``` - -Result: `433 passed, 5 deselected, 17 warnings in 9.14s`. The five deselections are the configured -L2/live-service tests. Warnings are existing legacy-workspace `FutureWarning` emissions. - -Scoped lint and diff hygiene: - -```text -cd harness && .venv/bin/ruff check tht/ports tht/adapters \ - tests/test_vector_port_contract.py tests/test_adapter_factory.py \ - tests/test_config_resources.py tests/test_config_legacy_compat.py \ - tests/test_adapter_command_regressions.py tests/test_dwh_port_contract.py -git diff --check -``` - -Result: `All checks passed!`; `git diff --check` produced no output. - -## Commit - -Commit subject: `fix(adapter): close final foundation review` - -The report is part of that same final commit. A Git object cannot contain its own SHA without -changing that SHA; the exact resulting commit ID is therefore recorded in the task handoff from -`git rev-parse HEAD` after creation. - -## Self-review - -- Reader/writer separation is preserved: search dereferences only `_reader`; hashes/upsert only - `_writer`; health probes each configured client independently and never substitutes one result - for the other. -- Writer failure contributes to aggregate `ok=False`, even when the reader succeeds. -- Dimension compatibility is derived only from configured embedding dimension and existing - `list_tables` metadata. Missing metadata remains `None`, not a guessed success/failure. -- The shared limit guard uses `type(limit) is int`, intentionally rejecting Python booleans and - numeric coercions before either adapter reaches its transport. -- Existing JSON/CLI behavior is preserved; the subprocess regression parses stdout as JSON and - counts exactly one deprecation marker on stderr. -- Scope remains adapter foundations. No vector DDL, schema initialization, or migration work was - introduced. - -## Concerns / follow-up - -- Write reachability uses the existing `list_tables` diagnostic on the separately authenticated - writer client. Deployments must allow that non-mutating diagnostic RPC to the writer credential; - failures are intentionally visible rather than hidden by reader success. -- Existing legacy-workspace tests emit 17 `FutureWarning`s in the full suite. This wave pins the - required production stderr behavior but does not migrate unrelated test fixtures. -- `build_vector_loader` remains transitional technical debt only for bulk sync, explicitly assigned - to `2026-07-11-local-pgvector-profile.md`. diff --git a/.superpowers/sdd/container-task-3-report.md b/.superpowers/sdd/container-task-3-report.md deleted file mode 100644 index faa90627..00000000 --- a/.superpowers/sdd/container-task-3-report.md +++ /dev/null @@ -1,206 +0,0 @@ -# Container Packaging Task 3 Report - -## Status - -Implemented the multi-stage core application image, non-root runtime, pinned Pi installation, -container entrypoint, context exclusions, and an in-image health smoke test. - -## TDD / Build Evidence - -Initial RED: - -```text -docker build -f docker/core.Dockerfile -t thothii-core:test . -ERROR: failed to build: resolve : lstat docker: no such file or directory -``` - -The first sandboxed attempt could not access the Docker socket; the authorized rerun reached the -builder and failed for the expected reason: the Dockerfile did not exist. - -GREEN build: - -```text -sh -n docker/core-entrypoint.sh docker/smoke/core-smoke.sh -docker build --progress=plain -f docker/core.Dockerfile -t thothii-core:test . -``` - -Result: shell syntax exited 0; Docker build exited 0. A final rebuild after tightening -`.dockerignore` also exited 0 and transferred only 17.60 kB of changed context (the initial clean -build transferred 1.02 MB). - -## Runtime and Entrypoints - -- Runtime user is `10001:10001` (`thoth`), never root. -- Runtime contains Node `v22.19.0` and Python `3.12.13`. Python 3.12 is intentional because the - harness declares `requires-python = ">=3.12"` and also satisfies the deployment floor of 3.11+. -- Pi is installed exactly as `@earendil-works/pi-coding-agent@0.80.3`; its build-time and runtime - version probes both reported `0.80.3`. -- `server` starts `/app/backend/dist/server.js`; `doctor` routes to `tht doctor`; `preprocess` - routes to the future-facing `tht preprocess` command; explicit `tht ...` and arbitrary CLI - arguments route to the installed `tht` binary. -- The gate extension's `typebox` runtime dependency is installed from the harness lockfile. - -## Smoke and Diagnostic Results - -```text -docker run --rm thothii-core:test doctor -config: error - configuration is invalid or unreadable -data_root: ok -``` - -Result: expected exit 1 for absent mounted workspace configuration, with no traceback and no -secret-bearing validation detail. - -```text -docker run --rm --entrypoint /app/docker/smoke/core-smoke.sh thothii-core:test -backend listening on http://127.0.0.1:8787 -v22.19.0 -Python 3.12.13 -core smoke: ok -``` - -Result: exit 0. The script asserted non-root execution, `tht --help`, `pi --version`, runtime -version floors, and `GET /health` through curl. Fastify's returned display address was loopback; -the inspected container environment is `HOST=0.0.0.0`, and the compiled server passes that value -to `app.listen`. - -```text -docker run --rm thothii-core:test tht --version -0.1.0 -``` - -Result: arbitrary `tht` entrypoint exited 0. - -An explicit runtime assertion checked UID 10001, exact Node and Pi versions, Python 3.11+, and the -absence of `/app/harness/.env` and `/app/harness/workspaces`; it exited 0. - -## Image Size and Containment Inspection - -```text -docker image inspect thothii-core:test --format '{{.Size}} {{json .Config.User}} {{json .Config.Env}}' -221419008 "10001:10001" [...runtime paths and version metadata only...] -``` - -Image size: **221,419,008 bytes** (about 211.2 MiB). - -`docker history --no-trunc thothii-core:test` was inspected. It contains only Dockerfile commands, -the pinned public package name/version, base-image metadata, and non-sensitive runtime variables; -no credentials or customer paths were found. An in-image filename scan found only -`/app/harness/.pi/settings.json` among `.env`, key/certificate, and settings-name candidates; that -tracked Pi file contains theme/startup preferences, not secrets. The build asserts `.env` and -workspace directories are absent. - -`.dockerignore` excludes VCS/agent state, all environment files except examples, package-manager -credential files, SSH/private-key and certificate formats, local virtualenvs/node_modules/caches, -backend runtime data, customer workspaces, sessions, artifacts, indexes, corpus, and deployment -mount content. - -## Self-review - -- `git diff --check` is clean. -- Entrypoint processes use `exec`, preserving container signal handling. -- Backend production dependencies are pruned; TypeScript build tools remain in the build stage. -- The writable `/data` root is owned by UID 10001; application payload remains root-owned and - read-only to the runtime user. -- CA certificates and curl are present for HTTPS integrations and health probing. -- No existing source, customer workspace, secret, or unrelated progress-ledger change is included - in the task commit. - -## Concerns - -- The `tht preprocess` command is deliberately a future-facing routing contract; its CLI group is - scheduled in the Evidence/preprocessing plan and is not implemented in the current harness. -- Python dependencies are range-resolved because the existing harness has no Python lockfile. The - Pi package, Node runtime, and package-lock-backed Node dependency sets are pinned/reproducible. -- The image was built and smoked on Docker Desktop arm64. The chosen official multi-arch base - images and Pi package are architecture-neutral at the package level, but amd64 still needs a CI - build/smoke before being advertised as verified. - -## Reproducibility Review Fix - -The original image pinned Pi's direct version in the Dockerfile but resolved its transitives at -build time, and pip resolved all harness dependencies from ranges. Both paths now consume committed -locks. - -### Lock generation - -Pi uses the minimal `docker/pi-runtime/package.json` and its committed npm v3 lock. It was generated -with: - -```text -npm install --package-lock-only --ignore-scripts --no-audit --no-fund \ - --prefix docker/pi-runtime -``` - -The package manifest specifies exact `@earendil-works/pi-coding-agent` version `0.80.3`; a lock -inspection confirmed that same resolved package version. Docker installs it with: - -```text -npm ci --omit=dev --ignore-scripts --no-audit --no-fund -``` - -The Python lock was generated directly from the harness production metadata plus one explicit, -pinned PEP 517 build-backend input—not from a host `pip freeze`: - -```text -uv pip compile harness/pyproject.toml docker/python-runtime/build-requirements.in \ - --universal \ - --python-version 3.12 \ - --no-emit-package tht \ - --generate-hashes \ - --custom-compile-command \ - 'uv pip compile harness/pyproject.toml docker/python-runtime/build-requirements.in --universal --python-version 3.12 --no-emit-package tht --generate-hashes --output-file docker/python-runtime/requirements.lock' \ - --output-file docker/python-runtime/requirements.lock -``` - -`pytest`, `ruff`, and `testcontainers` are absent. All production direct and transitive packages -are exact and hashed. `setuptools==80.9.0` is explicit so the local harness install can use -`--no-build-isolation` without an unpinned build-time resolution. Refresh instructions are in -`docker/LOCKS.md`. - -### No-cache rebuild and verification - -Final build command: - -```text -docker build --no-cache -f docker/core.Dockerfile -t thothii-core:test . -``` - -Result: exit 0. The logs showed Pi `0.80.3`, Node `v22.19.0`, a hash-enforced Python dependency -install, explicit `setuptools==80.9.0`, and a non-isolated local `tht` wheel build. No isolated -build-dependency download occurred. - -Fresh runtime checks: - -```text -docker run --rm --entrypoint /app/docker/smoke/core-smoke.sh thothii-core:test -backend listening on http://127.0.0.1:8787 -v22.19.0 -Python 3.12.13 -core smoke: ok - -docker run --rm thothii-core:test tht --version -0.1.0 - -/opt/venv/bin/pip check -No broken requirements found. -``` - -An in-container package inspection reconfirmed Pi `0.80.3`. Non-root UID, runtime version floors, -doctor's expected concise exit 1/no traceback, `/health`, and arbitrary `tht` routing all passed. - -The full filename containment scan found no `.env`, PEM, private-key, P12, or PFX file in `/app`; -`/app/harness/workspaces` remains absent. Image environment and `docker history --no-trunc` were -re-inspected and contain only public package/build commands and non-sensitive runtime metadata. - -Final locked image size: - -```text -220003986 10001:10001 -``` - -That is **220,003,986 bytes** (about 209.8 MiB), 1,415,022 bytes smaller than the original image. - -Remaining concern: the universal lock is resolved for Python 3.12 and includes hashes/markers for -all supported platforms, but only Linux arm64 has been built and smoked locally; amd64 remains a CI -verification gate. diff --git a/.superpowers/sdd/container-task-4-report.md b/.superpowers/sdd/container-task-4-report.md deleted file mode 100644 index 3ea43714..00000000 --- a/.superpowers/sdd/container-task-4-report.md +++ /dev/null @@ -1,82 +0,0 @@ -# Container Packaging Task 4 Report - -## Status - -Implemented and verified runtime-configured frontend packaging. - -## Changes - -- Added the browser runtime contract `window.__THOTHII_CONFIG__.backendBaseUrl`. -- Loaded `/config.js` before the Vite module entrypoint. -- Made runtime configuration take precedence while preserving `VITE_BACKEND_URL` and the - existing `http://localhost:8787` client default for development and tests. -- Added a multi-stage frontend image that builds with Node and serves static assets as - unprivileged UID/GID `101:101` with nginx on port 8080. -- Added startup-time `BACKEND_BASE_URL` substitution (default `/api`). -- Added `/api/` reverse proxying to `core:8787`, SPA fallback, no-cache runtime config, - and SSE-safe proxy settings (`proxy_buffering off`, `proxy_cache off`, one-hour read timeout). - -## TDD evidence - -- RED: `npx vitest run src/api/runtime-config.test.ts` failed because - `./runtime-config` did not exist. -- GREEN: targeted runtime config suite passed (3 tests after preserving the legacy client - default). - -## Verification - -- `cd frontend && npx vitest run --reporter=dot && npx tsc -b && npm run build` — exit 0 - (40 test files, 185 tests; TypeScript and Vite production build passed). -- `docker build -f docker/frontend.Dockerfile -t thothii-frontend:test .` — success. -- Image metadata reports `USER 101:101`. -- Two-container isolated-network smoke: - - `/config.js` returned `window.__THOTHII_CONFIG__ = { backendBaseUrl: "/api" };` - - `/api/health` proxied to the core image and returned `{"status":"ok"}`. - - an unknown nested route returned the SPA `index.html`. - - active nginx config contained `proxy_buffering off`, `proxy_cache off`, and - `proxy_read_timeout 1h`. - - `/config.js` returned `Cache-Control: no-store`. -- `sh -n docker/frontend-entrypoint.sh` and `git diff --check` — exit 0. - -## Secret-leakage inspection - -- `.dockerignore` excludes `.env*` (except examples), credentials/key formats, dependency - trees, build outputs, backend data, and deployment data. -- The runtime web root contained no `.env*`, `.pem`, `.key`, `.p12`, or `.pfx` files. -- Image history contained build/package instructions only; no secret build arguments or - credential values were introduced by this task. - -## Self-review / concerns - -- nginx resolves the `core` hostname at startup, matching the planned Compose service name; - standalone runs therefore need a reachable network alias named `core`. -- Existing frontend test warnings (React refs/act, MSW unmatched incidental requests, Vite - chunk-size warnings) remain; they did not fail the requested gates and are unrelated to - this task. -- `.superpowers/sdd/progress.md` was already modified by the orchestrator and was intentionally - excluded from this task's commit. - -## P1 review fixes - -Follow-up commit work addressed both review findings: - -- Runtime configuration is now produced with `jq -cn --arg`, so `BACKEND_BASE_URL` is encoded - by a real JSON serializer rather than interpolated into JavaScript by `sed`. -- The image includes `frontend-config-smoke`, which strips only the fixed assignment wrapper, - parses the remaining JSON with `jq`, requires exactly the `backendBaseUrl` key, and compares - the decoded value to the environment input. -- The hostile smoke passed with quotes, backslashes, a literal newline, ampersand, pipe, and - `"; globalThis.PWNED=true; //` in the value. A breakout would leave non-JSON trailing input - and fail parsing. -- Added `joinBackendPath`, shared by API fetch and EventSource creation. It removes duplicate - boundary slashes for relative and absolute bases while keeping empty and `/` bases rooted. - -Follow-up verification: - -- RED: six join cases failed with `joinBackendPath is not a function` before implementation. -- Targeted: runtime config, API client, and EventSource suites — 14 tests passed. -- Full frontend gate — exit 0 (40 test files, 191 tests, TypeScript, Vite build). -- Rebuilt `thothii-frontend:test` successfully. -- Hostile config image smoke — `frontend runtime config smoke: ok`. -- Rebuilt two-container smoke — default `/api` config, proxied `/api/health`, SPA fallback, - and SSE-safe nginx directives all passed. diff --git a/.superpowers/sdd/evidence-task-1-report.md b/.superpowers/sdd/evidence-task-1-report.md deleted file mode 100644 index c8c6dd18..00000000 --- a/.superpowers/sdd/evidence-task-1-report.md +++ /dev/null @@ -1,98 +0,0 @@ -# Evidence / Preprocessing Task 1 Report - -## Outcome - -Implemented the additive Evidence source port and canonical corpus records. Existing evidence, -search, vector, and session runtime code is unchanged. - -## Contract - -- `EvidenceSource` is a runtime-checkable protocol with `discover` and `acquire` operations. -- `SourceObject` and `AcquiredDocument` are frozen, reject extra fields, use independent metadata - defaults, and restrict metadata to Pydantic `JsonValue` values. -- `CanonicalDocument`, `CanonicalChunk`, and `CorpusManifest` are frozen and reject extra fields. -- Provenance includes stable source IDs, canonical URIs, fingerprints, modification time, and - content hashes. -- Pipeline versions are recorded on documents, chunks, and manifests. Manifests also carry schema - version, optional publish ID/vector generation, and paired embedding model/dimension fields. -- Credential-like metadata keys are rejected recursively. Credentials are not model fields and - therefore cannot enter serialized canonical artifacts through extras. - -## TDD evidence - -The initial focused run failed during collection because `tht.ports.evidence` and `tht.corpus` -did not exist. After implementation, the focused suite passed. - -## Verification - -- Focused models/protocol tests: 13 passed. -- Harness excluding Docker-backed L0 and the network-dependent wheel packaging test: 444 passed, - 5 deselected. -- Focused Ruff: passed. -- Full-repository Ruff remains blocked by 34 pre-existing findings outside the task files. -- An unrestricted `pytest -q` attempt reached 453 passed and 5 deselected, but reported 47 Docker - setup errors plus 4 Docker parity failures because the sandbox cannot access the Docker socket; - the wheel packaging test also failed because its isolated `uv build` needs unavailable network. - -## Concerns / follow-up - -- Pydantic's `frozen=True` prevents model field reassignment but does not recursively freeze list - and dict contents. `default_factory` prevents shared mutable defaults. Later pipeline stages should - treat these value objects as immutable and construct replacements rather than mutate collections. -- The adapter and normalization tasks should preserve the credential-free boundary by passing only - these records beyond acquisition. - -## Review hardening follow-up - -All six binding review areas were addressed in a separate TDD pass: - -- JSON metadata is recursively converted to immutable `FrozenDict`/tuple values while retaining - stable object/array JSON serialization. Manifest document and chunk collections are tuples. -- Secret-key matching now normalizes camelCase and punctuation. It rejects credential-specific - names (passwords, API keys, access/refresh tokens, client/private keys, session cookies and - authorization) recursively, while deliberate benign labels such as generic `token` and `secret` - remain valid. -- Canonical URIs require a scheme and reject userinfo or credential-bearing query parameters. -- Namespaced IDs, SHA-256 content hashes, timezone-aware UTC timestamps, embedding/vector - compatibility, unique IDs, chunk referential/provenance integrity, contiguous per-document - ordinals and pipeline-version consistency are validated. Nested Pydantic instances are always - revalidated so `model_copy(update=...)` cannot bypass a manifest boundary. -- Acquired arbitrary bytes have explicit base64 JSON encoding and validation, covered by a JSON - round-trip test. -- `EvidenceSourceError` classifies transient/retryable versus permanent failures and exposes only - recursively immutable, credential-screened JSON details. - -Follow-up verification: - -- Focused contract suite: 39 passed. -- Focused Ruff: passed. -- Harness excluding Docker-backed L0 and the network-dependent wheel packaging test: 470 passed, - 5 deselected. -- Fresh unrestricted harness attempt: 479 passed, 5 deselected; the same environmental boundary - remains (47 Docker socket setup errors, four Docker parity failures, one isolated `uv build` - network failure). - -## Final blocker follow-up - -The remaining four contract blockers were closed in a third TDD cycle: - -- `EvidenceSourceError` now always exposes the fixed public message/`args` value `evidence source - operation failed`; caller diagnostics are not retained. Category, details and args cannot be - reassigned, details remain recursively frozen and credential-screened, and an original exception - is available only when callers use standard exception chaining. -- Canonical document/chunk provenance stores only URI scheme, authority and path. Userinfo is - rejected; query strings and fragments are removed unconditionally, including AWS `X-Amz-*`, SAS - `sig`, and fragment token material. -- Binding model bases override Pydantic's unchecked `model_copy(update=...)`: merged values always - pass full field/model validation, so invalid copied records and top-level manifests fail. -- A canonical document/chunk `content_hash` must equal SHA-256 of the exact stored text encoded as - UTF-8. This establishes the normalization boundary explicitly: line-ending/frontmatter/text - normalization happens before model construction; the canonical models never rewrite content. - -Final follow-up verification: - -- Focused contract suite: 45 passed. -- Focused Ruff: passed. -- Harness excluding Docker-backed L0 and network-dependent packaging: 476 passed, 5 deselected. -- Fresh unrestricted harness attempt: 486 passed, 5 deselected, with the unchanged environmental - failures (47 Docker setup errors, four Docker parity failures, one isolated `uv build` failure). diff --git a/.superpowers/sdd/evidence-task-2-report.md b/.superpowers/sdd/evidence-task-2-report.md deleted file mode 100644 index 583ffda0..00000000 --- a/.superpowers/sdd/evidence-task-2-report.md +++ /dev/null @@ -1,65 +0,0 @@ -# Evidence Task 2 Report - -## Status - -Implemented filesystem and explicit-manifest HTTP Evidence source adapters, typed source -configuration with legacy compatibility, and factory construction. - -## Delivered behavior - -- Filesystem discovery is deterministic and rooted at a strict canonical directory. -- Symlink/path escapes are rejected before content is exposed. -- Discovery hashing and acquisition reads enforce a configurable byte limit. -- Filesystem fingerprints are content SHA-256 values; stable IDs derive from relative paths. -- HTTP accepts only explicit `http`/`https` manifest entries and keeps transport URLs private. -- HTTP provenance strips query strings/fragments, while config and adapter representations hide - signed or secret-bearing transport URLs. -- HTTP acquisition uses separate connect/read timeouts, streaming byte limits, bounded redirects, - private redirect rejection, and safe transient/permanent error classification. -- HTTP fingerprints prefer a deterministic ETag digest, then Last-Modified, then content SHA-256. -- `build_evidence_sources(cfg)` supports both typed `evidence.sources` entries and the legacy - `source_root` plus `evidence_dir` filesystem configuration. - -## TDD and verification - -- RED: focused tests initially failed during collection because the adapter package did not exist. -- GREEN: `15 passed` for filesystem, HTTP, and resource-config tests. -- Full harness: `548 passed, 5 deselected`. -- Changed-file Ruff: clean. -- Repository-wide Ruff remains non-clean due to 34 pre-existing findings in unrelated test files; - no unrelated lint files were modified. - -## Notes - -The approved `SourceObject` namespace grammar does not permit raw quoted ETags such as -`etag:"abc"`. The adapter therefore uses `etag:`: it preserves ETag-based -change identity without weakening the canonical contract or exposing validator contents. - -## Review hardening follow-up - -Four review findings were closed in a separate follow-up commit: - -- Filesystem access now anchors a persistent descriptor at the canonical root and walks each - component with `openat` semantics (`dir_fd`, `O_NOFOLLOW`, and `O_DIRECTORY`). The regular-file - check, bounded read, metadata, and hash all use the opened descriptor. Acquisition reopens by - the same path-safe mechanism and rejects a changed fingerprint. Deterministic tests swap both a - leaf and an ancestor to symlinks at open time. -- HTTP network policy defaults to public hosts only. Initial URLs and every redirect reject - userinfo, mixed public/private IPv4/IPv6 answers fail closed, and the connected peer must be a - public member of the previously validated DNS answer set before any body bytes are consumed. - Explicit `allow_private_hosts: true` is required for trusted private deployments and local tests. -- Every HTTP response is closed in a `finally` block, including redirects, status failures, - policy failures, oversized bodies, and mid-stream exceptions. -- ETag and Last-Modified values remain adapter-internal. Repeated discovery and acquisition send - conditional headers; a 304 reuses only previously verified cached bytes and identity. The LRU - content cache has an explicit byte bound (`max_cache_bytes`). Validators are not forwarded - across redirect origins. - -### Conditional cache binding correction - -The conditional cache now binds bytes and validators to both the canonical provenance key and the -exact final effective representation URL. Redirect traversal recomputes request headers per hop: -validators are sent only when that exact URL matches the cached final URL, never merely because a -redirect retains an origin. A same-origin path change therefore downloads and replaces the body. -The adapter accepts 304 only when the exact request carried a bound ETag or Last-Modified validator; -unsolicited and cross-origin 304 responses are permanent protocol errors. diff --git a/.superpowers/sdd/evidence-task-3-report.md b/.superpowers/sdd/evidence-task-3-report.md deleted file mode 100644 index db9ad616..00000000 --- a/.superpowers/sdd/evidence-task-3-report.md +++ /dev/null @@ -1,59 +0,0 @@ -# Evidence Task 3 — deterministic normalization and chunking - -## Outcome - -- Added pure `normalize(acquired, pipeline_version)` and `chunk(document, policy)` transforms. -- Normalization enforces UTF-8 (including UTF-8 BOM), a 10 MiB input ceiling, LF line endings, - NFC Unicode, safe YAML frontmatter extraction, canonical provenance URIs, and hashes the exact - canonical UTF-8 text stored on the document. -- Undecodable, unsupported-charset, oversized, and invalid-frontmatter inputs fail explicitly; - byte content is never truncated. -- Chunking uses a versioned immutable policy, paragraph/word boundaries with deterministic - character-count hard splits for long tokens, contiguous ordinals, provenance metadata, exact - per-chunk hashes, and IDs derived from document hash + ordinal + policy version. -- Empty documents produce no chunks. Non-ASCII, CRLF equivalence, repeatability, policy changes, - duplicate-content ordinal collisions, and max-character limits are covered by tests. - -## TDD evidence - -- Initial focused test run failed during collection because both transform modules were absent. -- The EOF-frontmatter edge test was separately observed failing before its implementation. -- Final focused verification: `12 passed`. - -## Verification - -- `cd harness && .venv/bin/pytest tests/test_corpus_normalize.py tests/test_corpus_chunk.py -q` - — **12 passed**. -- `cd harness && .venv/bin/pytest -q` — **573 passed, 5 deselected**. The sandboxed attempt could - not access Docker; the approved rerun with local Docker access passed. -- Targeted Ruff over all four implementation/test files — **clean**. -- Full `cd harness && .venv/bin/ruff check .` — reports **34 pre-existing errors** in unrelated - legacy tests (unused imports and existing E702 semicolon lines); none are in Task 3 files. - -## Concerns - -- The 10 MiB normalization ceiling is deliberately explicit and independent of adapter download - limits. If deployment policy needs a different ceiling, it should become a versioned pipeline - configuration before ingestion is wired. -- Character limits use Python Unicode code points (`len`), not UTF-8 bytes or tokenizer tokens; - this is recorded in the chunk-policy metadata and tested with non-ASCII content. - -## Review hardening follow-up - -- Chunk IDs now bind the canonical document identity, document content hash, ordinal, chunk hash, - and a canonical SHA-256 fingerprint of every `ChunkPolicy` field. Identical content in separate - documents and same-version policies with different limits cannot collide. -- Boundary-aware slicing now retains separators in the slices. Concatenating every chunk exactly - reconstructs the canonical document for repeated spaces, tabs, blank lines, Markdown hard - breaks, fenced code, whitespace-only input, Unicode, and overlong tokens; every slice remains - within `max_chars`. -- Frontmatter uses a bounded `SafeLoader` variant: duplicate keys, anchors/aliases, structures - deeper than 20 nodes, and documents larger than 1000 composed nodes are rejected. YAML parse, - JSON type, credential-safety, and resulting canonical-model errors attributable to frontmatter - map to `PermanentNormalizationError(reason="invalid_frontmatter")`; invalid pipeline policy - remains a programmer-facing `ValueError`. -- Follow-up TDD evidence: the expanded focused suite first reported 11 expected failures against - the prior implementation, then passed **45/45** across normalization, chunking, and manifest - invariants. -- Follow-up full verification: **586 passed, 5 deselected**. Targeted Ruff is clean. Full Ruff - continues to report the same **34 unrelated pre-existing** violations in legacy tests. diff --git a/.superpowers/sdd/evidence-task-4-report.md b/.superpowers/sdd/evidence-task-4-report.md deleted file mode 100644 index 8cfd32bb..00000000 --- a/.superpowers/sdd/evidence-task-4-report.md +++ /dev/null @@ -1,107 +0,0 @@ -# Evidence Task 4 — shared job envelope - -Status: complete - -## Delivered - -- Immutable `JobSpec`, `JobRun`, `JobReport`, per-stage state, sanitized error, and UTC - timestamp records. -- `run_job(spec, stages)` with a durable checkpoint at job start, before and after every stage, - and at terminal state. Successful stages are skipped when a prior run is resumed. -- Atomic JSON checkpoint/report replacement using a unique same-directory temporary file, - file `fsync`, atomic `os.replace`, and parent-directory `fsync`. -- Public reports contain fixed operational fields only. Workspace paths, stage return values, - exception messages, source content, credentials, and arbitrary metadata are not serialized. -- `WorkspaceJobLock` uses non-blocking kernel `flock` on a stable workspace/job-specific inode. - Locks are released by the kernel on process exit; lock files are never removed based on PID, - avoiding stale-lock and PID-reuse deletion races. Evidence and DWH use distinct lock files. -- Dry-run intent is immutable in the spec/report and exposed to every stage through `JobContext`. - -## TDD evidence - -Initial focused collection failed because `tht.jobs` did not exist. Tests then drove: - -- failure, sanitized reporting, resume, and idempotent successful-stage skipping; -- corrupt-checkpoint refusal before stage execution; -- JSON schema and path/secret/PII exclusion; -- dry-run propagation and ordered aware timestamps; -- multiprocessing exclusion, distinct Evidence/DWH jobs, traversal rejection, and recovery after - a lock-owning process crashes. - -Final focused result: - -```text -11 passed in 0.42s -``` - -## Verification - -```text -cd harness && .venv/bin/pytest -q -597 passed, 5 deselected, 17 warnings in 28.45s - -cd harness && .venv/bin/ruff check tht/jobs tests/test_job_runner.py tests/test_job_locking.py -All checks passed! -``` - -The full Ruff invocation was also run. It reports 34 pre-existing violations in unrelated legacy -tests; no Task 4 file is among them. L2 tests remain deselected by the repository configuration. - -## Operational notes - -- `fcntl.flock` intentionally targets the supported Linux/macOS deployment environments; it is not - a Windows locking implementation. -- The envelope does not publish or mutate an active corpus. Later pipeline stages must use - `JobContext.run_dir` for staging and perform their own final atomic publish only after validation. -- A dry run is an execution mode foundation: the runner exposes and records it; individual stages - remain responsible for suppressing external mutations. - -## Review hardening follow-up - -Four post-implementation findings were fixed test-first: - -1. Resume compatibility is now a canonical SHA-256 fingerprint over checkpoint schema version, - hashed workspace identity, job type, dry-run mode, explicit spec/pipeline versions, - configuration/input fingerprints, and the exact ordered explicit `stage_ids`. Any insertion, - removal, reorder, mode, identity, version, config, or input change rejects resume before a stage - executes. Omitting `resume_run_id` remains the explicit safe path for a new run. -2. Lock traversal now uses directory file descriptors with `O_DIRECTORY` and `O_NOFOLLOW`. - Lock files use `O_NOFOLLOW | O_CLOEXEC`; `fstat` requires a regular file owned by the current - UID with one link, and permissions are forced to `0600` (`0700` for private directories). - Pre-existing lock-file and lock-directory symlinks are rejected. -3. Stage failures now serialize only the fixed safe tuple `internal` / `stage_exception` / - `stage execution failed`. Neither exception class names nor messages are inspected for output; - a hostile exception-name/message regression test proves a terminal failed report is retained. -4. Job/run directory creation is no-follow, owner-checked, private, and durable. Each newly created - parent is fsynced, the run directory is fsynced before the first atomic file write, and the - existing file-fsync → replace → directory-fsync ordering has an explicit regression test. - -Follow-up verification: - -```text -focused job/lock suite: 27 passed in 0.45s -full harness suite: 613 passed, 5 deselected, 17 warnings in 29.65s -Task 4 scoped Ruff: All checks passed -``` - -Repository-wide Ruff continues to report the same 34 unrelated pre-existing legacy-test findings. - -## Final resume-integrity fix - -Resume is now read-only until the source checkpoint proves trustworthy. The runner loads the source -before allocating a new run ID or directory, validates the exact stage state/timestamp/error ledger, -rejects duplicate stage identifiers, and recomputes compatibility from every persisted compatibility -field plus the exact ordered persisted stage IDs. It first requires the stored fingerprint to match -that recomputation, then compares the trusted recomputation with the requested job fingerprint. - -Valid-JSON tampering tests cover removed, inserted/duplicated, reordered, and substituted stages; -input-field and stored-fingerprint changes; and invalid stage-state shapes. Every rejection occurs -before stage execution and asserts that the runs directory contains no orphan allocation. - -Final verification: - -```text -focused job/lock suite: 34 passed in 0.56s -full harness suite: 620 passed, 5 deselected, 17 warnings in 27.42s -Task 4 scoped Ruff: All checks passed -``` diff --git a/.superpowers/sdd/evidence-task-5-report.md b/.superpowers/sdd/evidence-task-5-report.md deleted file mode 100644 index e778b59d..00000000 --- a/.superpowers/sdd/evidence-task-5-report.md +++ /dev/null @@ -1,82 +0,0 @@ -# Evidence Task 5 report - -## Outcome - -Implemented an incremental Evidence corpus pipeline with immutable materialized generations, -generation-scoped vector records, and an fsynced atomic `ACTIVE` pointer. Runtime Evidence -artifact lookup reads the active canonical manifest and keeps a legacy source-tree fallback only -when no corpus has been published. - -The CLI is available as `tht preprocess evidence [--dry-run] [--resume RUN_ID] [--json]`. -JSON success and failure output is pristine and failure details are sanitized. - -## Safety and failure model - -- A workspace writer lock serializes preprocess writers; readers never take the lock. -- Generation directories, manifests, materialized files, locks, and `ACTIVE` reject symlink/path - escape cases and use owner-only durable writes. -- Vector records use generation-specific keys and metadata. The active manifest maps each active - document to its valid vector generation, allowing unchanged documents to retain their vectors. -- Runtime retrieval admits only active document IDs and their manifest-selected generations. - Removed documents and partial writes from failed generations are therefore unreachable. -- Embedding count and dimension checks occur before vector upsert; vector write count is checked - before staging/publish. Any failure leaves `ACTIVE` unchanged. -- Dry runs perform discovery/fingerprint planning only and never acquire, embed, write vectors, or - publish. Fully unchanged runs return the active generation without creating a replacement. -- Resume can safely retry idempotent generation-scoped upserts and publish an already staged, - compatibility-checked generation after a crash between staging and pointer replacement. - -## TDD evidence - -Initial focused collection failed because `tht.corpus.pipeline` and `tht.corpus.store` did not -exist. The implemented suite covers incremental skips, removals, model/policy rebuilds, acquire and -partial-vector failures, dry-run isolation, dimension validation, atomic reader snapshots, pointer -validation, symlink defense, and pristine CLI JSON. - -Fresh focused verification: - -```text -18 passed, 3 warnings in 0.39s -``` - -Command: - -```text -.venv/bin/pytest tests/test_corpus_pipeline.py tests/test_corpus_publish.py \ - tests/test_preprocess_cli.py tests/test_search_pack.py tests/test_session_documents.py -q -``` - -Scoped Ruff: `All checks passed!` - -Broader non-Docker/non-packaging run reached `560 passed, 5 deselected`; ten pre-existing HTTP -adapter tests could not bind localhost under the sandbox. The complete suite reached `570 passed, -5 deselected`, with the remaining failures/errors caused by denied Docker socket, localhost bind, -and offline wheel-build access. No task-focused test failed. - -## Remaining operational gate - -Live pgvector integration needs Docker or an authorized local pgvector endpoint. The compensation -strategy is logical isolation rather than destructive cleanup because the shared `VectorStore` -port intentionally exposes no delete/transaction API; unreachable failed generations can be -garbage-collected by a future maintenance job. - -## Review integration wave - -Added an enforceable `metadata_filter` vector-port contract and capability flags. Direct pgvector -places exact Evidence generation/document predicates in SQL before `LIMIT`; HTTP sends the same -filter to the RPC and deliberately does not use the legacy 404 fallback. The reader RPC script now -validates and applies that filter. Normal Evidence search and search-pack use an ACTIVE-aware -searcher that groups active documents by generation, executes complete server-filtered searches, -and merges the results. - -Added exact-generation Evidence cleanup to direct and HTTP writers plus the allowlisted writer RPC. -Pipeline failures compensate both staged filesystem state and vector writes; cleanup failures stay -sanitized and ACTIVE filtering remains the exposure boundary. Corpus-present session artifact -resolution now fails closed on corrupt/missing ACTIVE rather than falling through to source files. - -Focused review-wave verification: 45 passed, scoped Ruff clean. A mocked REST regression proves -the exact filter payload and fail-closed legacy 404 behavior. - -Still outstanding from the expanded review request: Task-4 JobRunner stage-by-stage integration, -published-generation retention/garbage collection, same-fd `dirfd` materialized-file reads, and -live local pgvector integration could not be completed in this wave. diff --git a/.superpowers/sdd/evidence-task-5b-report.md b/.superpowers/sdd/evidence-task-5b-report.md deleted file mode 100644 index ad0fcfdf..00000000 --- a/.superpowers/sdd/evidence-task-5b-report.md +++ /dev/null @@ -1,94 +0,0 @@ -# Evidence Task 5B implementation report - -## Status - -Integrated Evidence preprocessing with the Task 4 `JobRunner`. The CLI now accepts only a -32-character JobRunner run ID for `--resume`; generation IDs remain outputs. Runs persist the -exact ordered stages `discover`, `acquire_normalize_chunk`, `embed`, `vector_upsert`, -`stage_validate`, `publish`, and `retention_cleanup`. - -Successful-stage artifacts are copied into the new resume run before execution, allowing later -stages to continue without rediscovery, acquisition, normalization, chunking, or embedding. -Job compatibility includes workspace, configuration, discovered-input, pipeline, embedding, and -chunk-policy fingerprints. Generation-specific filesystem/vector compensation is retained, and a -compensated generation is rotated before retry. `ACTIVE` is mutated only by `publish`. - -Dry-run executes discovery/planning and makes every side-effecting stage a no-op. JSON output is -pristine and includes the JobRunner `run_id`, `resumed_from`, generation, plan, and publish status. - -## TDD evidence - -- RED: run-ID rejection and resume-artifact tests failed because generation IDs reached - configuration and resume runs had empty artifact directories. -- GREEN: the two regression tests passed after strict CLI validation and durable artifact carryover. -- Added pipeline job-plan and dry-run counting-fake coverage; both passed. - -## Fresh verification - -- Focused integration/search suite: `62 passed, 4 warnings`. -- Available harness suite excluding sandbox-blocked Docker, loopback HTTP-server, and networked - wheel-build tests: `559 passed, 5 deselected, 18 warnings`. -- Scoped Ruff: `All checks passed!`. -- `git diff --check`: clean. - -## Environment limitations and concerns - -The literal full harness invocation cannot complete in the managed sandbox: Docker socket access, -loopback HTTP test servers, and the `uv build` dependency resolution path are denied. It reached -`575 passed, 5 deselected` before those environment errors. The available-suite rerun above is -green. - -One pre-existing Pydantic serialization warning is exposed by the new end-to-end job test when -canonical metadata contains frozen tuple values; it does not contaminate CLI stdout. Retention is -an explicit stable no-op until a retention policy is configured. - -## Review fix wave — crash consistency and artifact integrity - -Addressed all five follow-up findings: - -- `JobRunner` now supports a test-only post-call/pre-checkpoint fault hook. Each stage seals a - canonical artifact manifest containing required flat filenames, SHA-256, byte size, producer - stage, and the full spec compatibility fingerprint. Resume validates the checkpoint and every - sealed artifact before allocating/copying a new run, rejecting missing, tampered, extra, nested, - or symlinked state. A sealed `running` stage is promoted after a simulated process crash; a - sealed `failed` stage is deliberately retried. -- Vector intent (exact record IDs and content hashes) is sealed before upsert. Execution reconciles - `existing_hashes` and writes only missing/mismatched rows. Crash-after-effect tests prove no - duplicate acquire, embed, or vector upsert. -- Raw upsert, stage, recovery-upsert, recovery-stage, and publish exceptions compensate the exact - generation. Compensation markers survive failed checkpoints; resume rotates the generation, - refreshes generation-bound artifacts, reconciles vectors, and stages idempotently. -- `CorpusStore.publish` is idempotent and failure-atomic. If replace succeeds but directory fsync - fails, it restores the previous `ACTIVE` value (or removes a newly created pointer), fsyncs the - rollback, and re-raises. Pipeline cleanup refuses to discard a generation referenced by ACTIVE. -- Added crash/resume coverage after all seven ordered stages; corrupt/missing plan, manifest, and - embeddings; unsafe extra paths; nonexistent run IDs; raw vector/stage failures; and post-replace - ACTIVE rollback. - -Fresh fix-wave verification: - -- Focused jobs/corpus/CLI/search suite: `82 passed, 17 warnings`. -- Available harness suite (same sandbox exclusions described above): - `579 passed, 5 deselected, 31 warnings`. -- Scoped Ruff and `git diff --check`: clean. - -## Final P1 fix — effect state and checkpoint-bound manifest roots - -- Stage checkpoints now distinguish `intent` from `completed`. Vector intent is atomically sealed - and checkpointed before upsert. A process-level `BaseException` after a partial multi-record - write leaves the stage `running/intent`; resume never promotes it and instead reconciles - `existing_hashes`, writing only the missing records. The completed state is persisted only after - reconciliation returns successfully. -- Every stage now persists its completed artifact state while still `running`, before the - post-call fault hook. The checkpoint binds the SHA-256 of canonical `artifact-manifest.json`, - effect state, exact producer stage, and exact required-file mapping. Resume validates this root - and all bindings before promotion or copying. -- Added process-interruption coverage proving the already-written vector record is not submitted - twice, remaining records are written, and publish completes only after reconciliation. Added - coordinated artifact/manifest, spec-binding, and producer-binding tamper rejection tests. - -Fresh verification: - -- Focused jobs/corpus/CLI/search suite: `86 passed, 18 warnings`. -- Available broad harness suite: `583 passed, 5 deselected, 32 warnings`. -- Scoped Ruff and `git diff --check`: clean. diff --git a/.superpowers/sdd/evidence-task-5c-report.md b/.superpowers/sdd/evidence-task-5c-report.md deleted file mode 100644 index 556bd02b..00000000 --- a/.superpowers/sdd/evidence-task-5c-report.md +++ /dev/null @@ -1,188 +0,0 @@ -# Evidence Task 5C report - -## Delivered - -- Added `vector.retain_published_generations` (default `3`, validation minimum `1`). -- Retention runs only after publication. It keeps ACTIVE, the newest configured generations, - and generations referenced by running or resumable failed job checkpoints. -- Cleanup deletes the exact Evidence generation from the vector store before removing its - immutable filesystem directory. Vector failures retain filesystem metadata for retry and - produce credential-free partial reports. -- Added idempotent `tht preprocess evidence gc [--dry-run] --json` reconciliation with pristine - JSON output. -- Materialized document reads now open generation/documents components with directory file - descriptors and `O_NOFOLLOW`, require a regular file owned by the process with one link, and - hash the bytes read from the same descriptor against the canonical manifest. -- HTTP generation deletion is pinned to `delete_vector_generation` with exact - table/kind/generation arguments. Legacy 404 responses fail closed with an actionable, - sanitized migration message. - -## Evidence - -- Focused retention, safe-read, CLI, and HTTP contract tests: `51 passed` (Docker-backed direct - parametrizations excluded from that focused invocation). -- Real Docker pgvector adapter suites: `33 passed`. -- Full harness suite, including Docker-backed tests: `668 passed, 5 deselected`. -- Changed-file Ruff: clean. -- `git diff --check`: clean. - -The five deselected tests are the repository's opt-in `l2` tests requiring external services; -they are not local pgvector tests. Test output retains pre-existing Pydantic serialization and -legacy-config deprecation warnings. - -## Review fix wave - -- Publication is now explicit and durable (`PUBLISHED` marker). Retention candidates require a - valid generation manifest and publication marker (ACTIVE remains backward-compatible), so - staged and malformed directories neither consume retention slots nor become deletion targets. -- The policy retains ACTIVE plus exactly `N-1` newest rollback publications, ordered by durable - publication time and generation id. Running and failed-resumable JobRunner checkpoints protect - every referenced plan generation. -- `VectorStore` now exposes exact Evidence generation inventory. Direct pgvector uses a constrained - `SELECT DISTINCT` over `kind='evidence'` and `metadata.vector_generation`; HTTP uses the - allowlisted `list_evidence_generations` RPC and fails closed on legacy 404. The writer RPC SQL, - revokes, and grants are packaged in `create_vector_writer_rpc.sql`. -- Explicit GC reconciles the union of published filesystem generations and vector-only orphans, - preserving vector-before-filesystem deletion and retry semantics. -- `run_as_job` holds the same corpus writer lock across checkpoint recovery, staging, publish, and - retention. Explicit GC already uses this lock, serializing candidate snapshots with publishers. -- Session artifact consumers no longer receive the corpus source path after validation. They get - an owned, read-only copy atomically written from the bytes read and hash-validated on the same - descriptor. - -Fresh verification after the fix wave: full harness `672 passed, 5 deselected`; Docker pgvector, -HTTP parity, and migration suites `43 passed`; exact direct inventory/delete integration `1 passed`; -changed-file Ruff and `git diff --check` clean. - -## Final hardening verification - -- Canonical generation validation is exact (`^gen:[0-9a-f]{32}$`) before HTTP/direct deletion; - malformed HTTP inventory rows fail closed rather than entering the GC candidate set. -- Added explicit protection coverage for running and failed-resumable JobRunner checkpoints, plus - a second-GC idempotence assertion for vector-only orphan reconciliation. -- Added deterministic concurrent locking coverage: a job paused after discovery retains the corpus - writer lock, explicit GC blocks, then completes after publication without deleting the active run. -- Added a descriptor-race regression: replacing the corpus pathname immediately after `read(2)` - leaves the atomically materialized session-owned copy byte-for-byte equal to the validated ACTIVE - document and its manifest hash. - -Final fresh evidence: Docker pgvector/HTTP/migration suites `48 passed`; full harness `680 passed, -5 external L2 deselected`; changed-file Ruff and `git diff --check` clean. - -## Integrated Task 5 dependency fixes - -- GC now distinguishes filesystem retention from vector dependencies. ACTIVE and the newest - `N-1` published manifests keep their directories; every exact generation in their - `document_generations` maps remains vector-protected even after its old publication directory is - evicted. Job-protected manifests receive the same dependency treatment. -- The real four-publication Docker lifecycle now includes an unchanged document whose vectors come - from the first generation. With retention `N=2`, only the final two publication directories remain - while the first generation's vectors remain searchable from ACTIVE and survive restart/explicit GC. -- Evidence lookup is always wrapped by the ACTIVE-aware searcher. With no corpus/ACTIVE, Evidence - returns no rows and search packs cannot expose legacy vectors; non-Evidence kinds are unchanged. -- Session artifact resolution holds the corpus writer lock, snapshots the active manifest once, and - materializes bytes using that exact `manifest_id`, preventing a concurrent publish/retain-1 GC from - changing or deleting the selected source generation. - -Focused unit tests, the updated real Docker lifecycle, changed-file Ruff, and `git diff --check` pass. -The final full harness invocation completed with exit code 0, including the concurrently added DWH -JobRunner tests. - -## Final ACTIVE search review fixes - -- `ActiveEvidenceSearcher` now treats default (`kinds=None`) and mixed-kind searches as explicit - split queries: non-Evidence kinds are queried separately, while Evidence is queried only with - ACTIVE manifest generation/document predicates applied server-side before every limit. -- Results are merged deterministically by descending similarity then stable id and truncated once - to the caller's global `top_n`. Pure non-Evidence searches retain their original delegate path. -- The corpus writer lock now covers manifest snapshot construction and all corresponding vector - queries, preventing retain-1 publication/GC from switching or deleting generations mid-search. -- Removed the public post-LIMIT `active_evidence_hits` helper; no public Evidence path performs - client filtering after limit. - -Focused default/mixed/no-ACTIVE/search-pack tests pass, the real Docker pgvector lifecycle passes, -and the final full harness plus scoped Ruff/diff invocation completed with exit code 0. - -## Workspace-scoped Evidence isolation - -- Evidence manifests, vector metadata, and record keys now carry the stable JobRunner workspace id - derived from the configured workspace identity (config stem), never credentials or absolute paths. -- Every ACTIVE server-side predicate includes `workspace_id`. Legacy unscoped rows therefore fail - closed and cannot appear in Evidence results. -- Vector generation inventory and deletion require the workspace namespace across the port, direct - pgvector adapter, HTTP client/adapter, and allowlisted RPC SQL. Legacy unscoped RPC overloads are - explicitly dropped during migration; destructive SQL matches collection, kind, generation, and - workspace together. -- GC recovers the persisted namespace from ACTIVE for explicit/restarted cleanup and can only list - or delete that workspace's generations. Real shared-pgvector coverage proves deleting a generation - for workspace A preserves the same generation in workspace B. -- `PipelineResult.model_dump` now serializes fields explicitly instead of `dataclasses.asdict`, - avoiding deepcopy of immutable `FrozenDict` metadata while preserving pristine JSON CLI output. - -Final focused verification: `89 passed` across corpus/CLI JSON, direct/HTTP parity, migrations, and -real Docker pgvector lifecycle; scoped Ruff and `git diff --check` clean. A contemporaneous full-suite -run reached unrelated Task 6 immutable-file tamper tests; those files were deliberately not changed. - -## Immutable corpus/workspace binding - -- A corpus root becomes bound to the workspace id persisted in its ACTIVE manifest. Job, non-job, - explicit GC, and ACTIVE search entry points compare the configured namespace before discovery, - vector access, staging, deletion, or ACTIVE mutation. -- Reusing the same paths after renaming a workspace now fails closed with a typed/sanitized message: - use a new corpus root or perform an intentional explicit rebuild. Unscoped legacy manifests also - fail this ownership check. -- Tests prove unchanged-document reuse cannot silently mix workspace A vectors into a workspace B - manifest, and that mismatched job, GC, and search paths perform no vector/filesystem mutations. - -Focused workspace-binding, search-pack, preprocess JSON, and scoped Ruff/diff tests pass. - -Compatibility follow-up: direct/internal `CorpusPipeline` instances now distinguish an omitted -workspace identity from an explicit config/job identity. An unbound instance adopts the persisted -ACTIVE owner (or `default` only for a brand-new direct corpus), preserving safe resume/GC tests and -the real pgvector lifecycle. Explicit config/job identities still fail closed on any mismatch. The -two reported regressions, workspace mismatch guards, real Docker lifecycle, scoped Ruff/diff, and -the full harness suite all pass. - -Final fail-closed follow-up: persisted ACTIVE ownership is now validated under the corpus lock before -every configured search delegate, including default, mixed, pack, and non-Evidence-only operations. -Malformed or missing `metadata.workspace_id` is intrinsically rejected even for unbound direct -callers; source discovery, vector operations, GC, files, and ACTIVE remain untouched. Focused tests, -real Docker lifecycle, scoped Ruff/diff, and the full harness regression run pass. - -Final lock/preflight follow-up: `CorpusPipeline.gc()` now acquires the corpus writer lock itself for -ownership validation through vector/filesystem cleanup. The store lock is thread-reentrant so nested -job retention is safe without weakening cross-thread/process exclusion; the CLI wrapper no longer -double-locks. Search find/pack performs locked corpus ownership preflight immediately after config -load, before DWH leasing, vector/searcher factories, embeddings, or schema work. Focused concurrency -and fail-closed tests, real Docker lifecycle, scoped Ruff/diff, and the full harness pass. - -## Compact public Evidence reports - -- Public `PipelineResult.model_dump()` is now a bounded operational envelope: terminal status, - run/resume/publication/generation/manifest identifiers, capped changed/unchanged/removed source - identifiers, and aggregate document/chunk counts. Full manifests, bodies, and metadata remain - internal/on disk and are never serialized to CLI stdout. -- `tht preprocess evidence` exits `1` for any durable terminal status other than `succeeded` in - both JSON and text modes. JSON stdout remains one pristine sanitized object; text mode emits one - compact stderr error without traceback, exception identity, evidence content, or credentials. -- Tests cover a real failed acquisition job, sensitive evidence content, capped thousand-item - summaries, bounded report size, and smoke-compatible changed/unchanged fields. - -Focused tests and scoped Ruff/diff pass. The contemporaneous full suite reaches an unrelated Task 6 -DWH snapshot fixture missing its newly required workspace identity. - -### Safe result representation and exact text totals - -- `PipelineResult.manifest` is explicitly excluded from dataclass representation and the custom - representation is fixed-size operational data only. It omits manifest ids, documents, chunks, - content, metadata, and errors; `str(result)` inherits the same safe representation. -- Text-mode Evidence success output reads the uncapped aggregate totals from `payload["counts"]` - rather than the intentionally capped identifier arrays. -- Regression coverage builds a thousand-document/chunk manifest containing content and - credential-like metadata secrets, checks bounded `repr`/`str`, and verifies exact totals above - the 100-item public-array cap. - -Focused Evidence verification passes (`67 passed`), and scoped Ruff is clean. The full harness run -is not green in this sandbox: Docker-backed tests cannot access the daemon, wheel packaging cannot -use the restricted build environment, and concurrent Task 6 DWH binding changes currently fail two -DWH tests. None of those failures touch the Evidence files in this follow-up. diff --git a/.superpowers/sdd/evidence-task-5d-report.md b/.superpowers/sdd/evidence-task-5d-report.md deleted file mode 100644 index 9d87b141..00000000 --- a/.superpowers/sdd/evidence-task-5d-report.md +++ /dev/null @@ -1,50 +0,0 @@ -# Evidence Task 5D — Real pgvector lifecycle gate - -## Status - -Complete. The Docker-backed L0 gate uses one persistent `pgvector/pgvector:pg16` -database and the production migrations, direct reader/writer `PgVectorStore`, -`CorpusStore`, `CorpusPipeline.run_as_job`/JobRunner, ACTIVE Evidence retrieval, -search-pack fusion, owned session artifact copy, retention, and explicit GC. - -## Lifecycle covered - -- Four real corpus publications with retention set to two generations. -- A higher-similarity stale vector proves ACTIVE metadata filtering happens before LIMIT - for normal Evidence retrieval and the search-pack fusion path. -- A removed source is absent from ACTIVE retrieval and cannot be copied to a session. -- An injected process death occurs after one real committed vector upsert. Resume uses the - real run ID, preserves that record, fills the missing records, and produces no duplicate keys. -- Database engines and direct store objects are disposed/recreated before persisted ACTIVE - retrieval is checked again. -- An exact canonical vector-only orphan generation is discovered and removed by explicit GC. -- Filesystem and vector inventories converge exactly to ACTIVE plus one rollback; a second GC - is a no-op. -- Owned session artifact bytes and SHA-256 match the ACTIVE canonical document. - -## Production bug found and fixed - -Production migration `003_roles.sql` intentionally restricted `vector_writer`, but omitted -the privileges used by the production generation lifecycle: `SELECT(metadata)` for inventory -and `DELETE` for cleanup on `vectors.evidence`. Consequently a real job published successfully -and then failed in `retention_cleanup` on its first run. - -Added versioned migration `004_evidence_generation_gc.sql` granting only those two Evidence -generation-management privileges. Runtime application code was not redesigned. - -## Verification - -- Target lifecycle: `1 passed` (Docker-backed). -- Full harness: `681 passed, 5 deselected`. -- Scoped Ruff: passed. -- `git diff --check`: passed. - -The existing Pydantic serialization and legacy-workspace deprecation warnings remain unchanged. - -## Follow-up assertion correction - -The removal phase now retains the removed canonical document ID/ref before publication and -asserts both fields are absent from post-resume ACTIVE Evidence hits. It reruns the real -search-pack fusion after removal, proves active fourth-generation content is positively -returned in both paths, and proves the removed content remains absent. The owned session -artifact lookup for the retained removed ID remains empty. diff --git a/.superpowers/sdd/evidence-task-6-report.md b/.superpowers/sdd/evidence-task-6-report.md deleted file mode 100644 index b1d347ab..00000000 --- a/.superpowers/sdd/evidence-task-6-report.md +++ /dev/null @@ -1,49 +0,0 @@ -# Evidence Task 6 — final fd-anchored DWH correction - -All DWH generation state below `.tht-dwh` is now accessed relative to the directory descriptor -retained by the shared/exclusive generation lease. ACTIVE reads, atomic temp writes, replacement, -fsync, and rollback use `openat`/`replaceat` operations. Generation staging, validation, -reconciliation, resume checks, retention classification, and recursive deletion likewise use owned -root/generations/candidate descriptors with `O_NOFOLLOW`; locked operations no longer reopen -generation paths through `workspace_root`. - -Portable reader snapshots are copied from validated generation file descriptors into private 0700 -process-owned temporary directories while the shared lease is held. This avoids Linux-only -`/proc/self/fd` paths and prevents a renamed/replaced `.tht-dwh` pathname from redirecting later -schema or LSH reads. Lease-scoped copies are removed on exit and standalone snapshots are removed -at process exit. - -Deterministic adversarial tests rename the DWH root after lease acquisition during ACTIVE reads, -ACTIVE publication, and retention cleanup. Each test proves the replacement tree is never read, -written, or deleted; the descriptor-pinned original either completes consistently or fails closed. -Existing owner binding, legacy rejection, crash reconciliation, resume, atomic rollback, retention, -and reader/writer exclusion behavior remains covered. - -## Final review correction - -Snapshot materialization now reads the manifest and every owned artifact exactly once through the -already-open generation descriptor, validates each hash against those exact bytes, and writes the -same byte objects to the private snapshot. A deterministic second-read mutation test proves hostile -pickle bytes can neither pass validation nor enter the snapshot. Reconciliation closes the ACTIVE -generation descriptor in a `finally` block on matches, mismatches, and exceptions. Pipeline-owned -snapshot directories are removed and deregistered after `run_job` on both successful and failed -runs, preventing repeated pipeline use from accumulating temporary directories or registry entries. - -The cleanup boundary now begins immediately after snapshot materialization. Resume checkpoint -validation and `JobSpec` construction are guarded by the same release routine as `run_job`, so -corrupt/mismatched resume state or constructor failure clears the pipeline holder, removes the -private directory, and restores the snapshot registry to its prior state before propagating. - -## Shipped preprocessing startup contract - -Local-vector preprocessing now uses a dedicated Compose override. Both one-shot jobs depend on a -successfully completed `vector-migrate`, whose transitive chain waits for database health and role -reconciliation. The generic preprocessing overlay remains independently renderable and contains no -local-vector services or password secrets. README commands include the local override and build the -job image before running. - -The real clean-project smoke no longer injects dependencies or manually starts, reconciles, or -migrates PostgreSQL. Its first shipped `compose run preprocess-evidence` demonstrably creates the -database, waits for health, runs reconciliation and migration, then runs the Evidence job. Unchanged -rerun, changed-source publish, DWH preprocessing, ACTIVE verification, and injected-failure cleanup -all pass through the same shipped dependency path. diff --git a/.superpowers/sdd/evidence-task-7-report.md b/.superpowers/sdd/evidence-task-7-report.md deleted file mode 100644 index 2c217cd2..00000000 --- a/.superpowers/sdd/evidence-task-7-report.md +++ /dev/null @@ -1,93 +0,0 @@ -# Evidence preprocessing Task 7 report - -Implemented the S3-compatible Evidence adapter, explicit preprocessing Compose overlay, and -operational gates. - -- S3 discovery uses bounded paginator pages, page size, and total objects; acquisition enforces a - byte ceiling and always closes streaming bodies. -- Provenance is canonical `s3://bucket/key`. Versioned objects use `s3-version:`; - unversioned objects use a hashed exact ETag, and acquisition refuses validator drift. -- The adapter uses boto3/botocore rather than custom signing. TLS verification is enabled by - default. Custom HTTP and private endpoints require independent explicit opt-ins; endpoint - userinfo is rejected and public custom endpoints are DNS-policy checked. -- Access, secret, and session credentials support file-secret resolution into masked `SecretStr` - config fields. They are never emitted in provenance, reports, errors, or Compose environment. -- `deploy/compose.preprocess.yaml` provides separate one-shot Evidence and DWH jobs and is inert - unless explicitly included with the `preprocess` profile. -- `scripts/preprocess-smoke.sh` verifies both services render without secret material and pins an - unchanged rerun plus a modified generation through deterministic pipeline tests. - -Verification: focused S3/HTTP/filesystem/config tests 34 passed; operational smoke 2 passed; core -image with locked boto3 extra built; full harness 702 passed, 5 deselected; scoped Ruff and diff -checks passed. - -Operational risk: custom S3-compatible endpoints remain part of the deployment trust boundary. -Private endpoint access must be explicitly enabled and should be restricted by container egress -policy in production. S3 list consistency semantics are provider-defined; version IDs are preferred -over ETags wherever bucket versioning is available. - -## Review correction - -The Compose overlay now uses committed, purpose-built Evidence and DWH workspace files with -job-specific dependencies. Its services create their lock roots and mount only the vector secrets -they consume. The operational smoke is a real isolated Compose project: real pgvector migrations, -a deterministic in-project embeddings endpoint, actual Evidence CLI JSON across initial/unchanged/ -mutated runs, exact ACTIVE verification, an actual DWH introspection job, and owned cleanup. - -S3 custom endpoints now fail closed unless declared trusted; HTTP and private loopback endpoints -need additional independent opt-ins. Boto uses forced path-style addressing. Custom endpoints reject -userinfo, query, fragment, and non-root paths. Buckets use strict DNS syntax; listed keys must remain -under prefix and within the S3 byte bound; validators must be nonempty/bounded. Because -ListObjectsV2 does not provide version IDs, discovery honestly fingerprints the exact ETag and -acquisition rejects ETag drift. - -Final correction verification: S3/config focused 20 passed; full harness 721 passed, 5 deselected; -real Compose smoke and image build passed; scoped Ruff, shell syntax, and diff checks passed. - -## Final security review correction - -Literal non-global IPv4/IPv6 endpoints now require the private-endpoint opt-in without claiming DNS -pinning for hostnames. Pagination uses explicit continuation requests and never fetches page -`max_pages + 1`. IP-shaped buckets, leading-slash prefixes, empty/overlong/control-character keys, -and absent validators fail closed. Acquisition accepts only the exact stored `SourceObject` and -compares the response ETag with the stored discovery validator. The real smoke snapshots generation -directory counts after every run and has an injected-failure cleanup mode; cleanup fails if Compose -down fails or any owned container, volume, or network remains. - -The canonical smoke correction counts only root-level `corpus/gen-<32 hex>` directories. It exposed -that the durable job path still published an empty unchanged generation; the pipeline now returns -the existing ACTIVE generation without staging a directory when compatibility and all source -fingerprints are unchanged. The smoke therefore proves directory deltas `+1`, `+0`, `+1`. -Failure injection runs a real exit-97 command after resources exist and reaches the EXIT trap. -Cleanup aggregates Compose-down, residual container/volume/network, and temp-directory failures -while preserving the original failure status. S3 prefixes are validated before any client request -for leading slash, UTF-8 byte length, controls, and DEL. - -## Canonical unchanged-run correction - -The durable job now persists a deterministic source snapshot keyed by source identity. Each entry -binds canonical URI, exact source fingerprint, UTC modification time, canonical immutable metadata, -and explicit media type and size contract fields. The manifest also binds document-to-source -provenance, supplied config/input fingerprints, compatibility, embedding settings, and pipeline and -chunk-policy versions. - -An unchanged run reuses ACTIVE only when ownership, bindings, the complete snapshot, document -provenance, materialized document hashes, and every required vector ID/content hash match exactly. -Snapshot changes rebuild only the affected sources; job input/config changes publish a new manifest -while retaining valid stable vector-generation dependencies. Missing or corrupt legacy contract -metadata, documents, or vectors fails closed and rebuilds. The Compose smoke now explicitly expects -the unchanged no-op to report `published=false` while proving generation deltas `+1`, `+0`, `+1`. - -## Corrupt ACTIVE reconstruction correction - -ACTIVE reuse now reconstructs each source contract from the persisted discovery snapshot and checks -the deterministic document identity, canonical URI, source fingerprint, UTC modification time, -source metadata, applicable media type, content hash, and pipeline identity against the owned -materialized document. The persisted document-source map carries the same exact binding. - -Chunks are recomputed under the current chunk policy and must match the manifest exactly in count, -order, IDs, ordinals, content, hashes, linkage, provenance, and policy metadata. Vector health must -report the configured dimension, and every recomputed chunk must have its generation-scoped vector -ID with the exact content hash. Missing, altered, or extra chunks and corrupt document or vector -contracts therefore disable the no-op and rebuild, while a valid unchanged run still performs no -source acquisition. diff --git a/.superpowers/sdd/model-provider-credential-report.md b/.superpowers/sdd/model-provider-credential-report.md deleted file mode 100644 index 7fcdc16c..00000000 --- a/.superpowers/sdd/model-provider-credential-report.md +++ /dev/null @@ -1,16 +0,0 @@ -# Model provider credential boundary - -The backend accepts only an absolute `THT_MODEL_API_KEY_FILE` reference. `PiProcessManager` reads -and validates it afresh before each hosted-provider spawn, rejects symlinks, non-regular/hard-linked, -empty, whitespace-containing, oversized, unreadable, or permissively-mode files, and accepts Docker -0444 secrets only beneath `/run/secrets`. Failures are sanitized and occur before child creation. - -Provider names are normalized and mapped to Pi-recognized variables. The child environment removes -the generic path, deprecated `PI_PROVIDER_API_KEY`, and all unselected known provider keys before -injecting only the selected key. Values never enter argv, settings, health, or diagnostics. Local -providers remain keyless and unknown hosted providers fail closed. - -The production Compose overlay mounts `model_api_key` read-only and points the backend at its file; -the deployment render smoke proves the value is absent from rendered configuration. Entrypoint, -root README, Pi configuration guide, environment example, and secrets operator guide document the -new contract and reject the legacy generic value variable. diff --git a/.superpowers/sdd/pgvector-final-fix-report.md b/.superpowers/sdd/pgvector-final-fix-report.md deleted file mode 100644 index e33ee639..00000000 --- a/.superpowers/sdd/pgvector-final-fix-report.md +++ /dev/null @@ -1,59 +0,0 @@ -# Local pgvector whole-plan final fix report - -## Outcome - -All four binding final-review findings are closed. - -1. `PgVectorStore.health()` checks namespace `USAGE` independently for reader and writer - before inspecting vector types. Real PostgreSQL tests revoke only schema `USAGE`, prove both - health sides false and operations unavailable, then grant it back and prove recovery. -2. Direct reader/writer passwords use workspace `password_file` references. Compose mounts the - two files read-only into core and exposes only `_FILE` paths. Rendered Compose and live - `docker inspect` checks prove secret contents are absent. -3. Direct search failures map to `VectorReadUnavailable`; hash/upsert failures map to - `VectorWriteUnavailable`. Messages are fixed and sanitized, original exceptions remain chained, - and upsert rollback is preserved. -4. The shared secret policy uses Linux `stat -c` with macOS `stat -f` fallback. Host files permit - only `0600`/`0400`; Docker's read-only `0444` is accepted only beneath `/run/secrets`. Tests and - operator docs pin this exact policy. - -## TDD evidence - -The new config, mode, schema-usage, unavailable-connection, and permission regressions failed -before their implementations. The first live secret-policy run also caught GNU `stat -f` accepting -an incompatible format invocation; detection now tries the native Linux form first. The next live -run caught smoke-generated rotation fixtures at `0644`; fixtures now model the documented host -policy. - -## Verification - -- Real direct pgvector + HTTP parity: `31 passed`. -- Full harness from `harness/`: `493 passed, 5 deselected`. -- Live `local-vector` rotation, restart persistence, inspect boundary, and backup/restore: pass. -- Core image vector migration discovery/status smoke: pass. -- External and local Compose deployment security contracts: pass. -- Config/port focused suite: `26 passed`. -- Secret policy, bootstrap rotation, and backup/restore safety scripts: pass. -- Changed Python Ruff, shell syntax, and `git diff --check`: pass. - -One attempted full-harness invocation from the repository root produced a path-dependent failure -in an existing test that opens `workflow.yaml` relative to CWD. It was immediately rerun using the -documented `cd harness && .venv/bin/pytest -q` command and passed completely. - -## Operational notes - -Workspace files contain file paths, never direct passwords. Secret contents necessarily exist in -the in-process validated `DatabaseConfig` used to establish PostgreSQL connections, but are not -serialized by doctor/Compose/inspect paths. Docker Desktop file-backed secrets may appear as bind -mounts; the safe runtime exception is therefore based on the read-only service mount location -`/run/secrets`, while source files remain owner-only on the host. - -## External-profile regression follow-up - -Local pgvector is now an explicit `deploy/compose.local-vector.yaml` overlay. The base Compose and -production external override contain no direct vector password declarations, mounts, or `_FILE` -variables, so external deployments do not resolve or require local password files. A real lifecycle -gate unsets all local secret-file variables, renders external config, builds and starts core, waits -for health, and inspects the live container for absence of local direct-vector secret paths. The -local overlay retains its live inspect assertion (paths present, values absent), rotation, restart -persistence, and transactional backup/restore drill. diff --git a/.superpowers/sdd/pgvector-task-1-report.md b/.superpowers/sdd/pgvector-task-1-report.md deleted file mode 100644 index f2025c83..00000000 --- a/.superpowers/sdd/pgvector-task-1-report.md +++ /dev/null @@ -1,95 +0,0 @@ -# Local pgvector Task 1 report - -## Status - -Implemented the direct `PgVectorStore` behind the transport-neutral `VectorStore` port. -The adapter uses separate optional reader and writer database configurations, derives -capabilities from configured authority, validates strict positive search limits, filters kinds -in SQL before limiting, and merges multi-collection results by cosine similarity. - -All collection identifiers are selected from the fixed `schema_records`, `evidence`, and -`memory` allowlist and composed with `psycopg2.sql.Identifier`. Values, vectors, kinds, hashes, -and limits remain bound parameters. Collection/kind mismatches fail with `VectorStoreError`. - -Upserts preserve the canonical metadata shape, use `record_key` conflict semantics, update the -transport hash and embedding, and leave semantic metadata fields intact. Health probes reader -and writer independently and reports observed `vector(N)` dimensions against the configured -embedding dimension. - -## Configuration and factory - -`pgvector_direct` now accepts explicit optional `reader` and `writer` `DatabaseConfig` entries. -The former `connection` entry remains supported as a deprecated read-only compatibility path. -`build_vector_store(..., require_write=True)` accepts writer-only direct configurations and -fails early when no explicit writer is present. - -The transitional `build_vector_loader` bulk-sync path remains in place. It uses an explicit -direct writer when present, or the legacy `connection`; it deliberately does not treat a new -reader-only credential as writable. No production schema migration was added. - -## TDD and verification - -- RED: the new tests initially failed at collection because `PgVectorStore` did not exist. -- Docker L0 pgvector tests: `11 passed`. -- Direct + HTTP parity/factory/config focus: `51 passed`. -- Full harness: `461 passed, 5 deselected`. -- Changed-file Ruff lint: clean. -- Changed-file Ruff format check: clean. -- `git diff --check`: clean. - -The repository-wide `ruff check .` still reports 34 pre-existing test-file findings outside -Task 1; none are in changed files. The full pytest suite emits 17 existing legacy-config -deprecation warnings. - -## Scope and concerns - -- Test fixtures create only the three existing vector tables needed to exercise the adapter; - migration/versioning remains Task 2. -- The legacy single `connection` form stays read-only through the public port, matching its - previous adapter behavior, while remaining available to the explicitly documented bulk-loader - transition. - -## Review fix wave - -The Task 1 review findings were addressed in a follow-up TDD cycle: - -- Search now validates requested kinds against the global known-kind set, intersects valid kinds - with each collection, and skips unrelated collections. A direct-versus-HTTP parity test covers - the multi-collection case. -- Health requires all three allowlisted tables, an `embedding vector(N)` column on every table, - the expected dimension on every table, and the appropriate read or write table privileges for - each configured side. Empty and partial schemas return deterministic, credential-free details; - unexpected database failures expose only their exception class. -- The Docker L0 fixture now provisions separate least-privilege reader and writer roles. Tests - prove the reader cannot insert, the writer cannot execute the cosine-search SELECT, and the - adapter still routes search to the reader and upsert/hash operations to the writer. Direct - upsert uses an atomic `INSERT ... ON CONFLICT DO NOTHING` followed by `UPDATE` for an existing - key, avoiding broad SELECT authority while retaining conflict-safe hash/upsert semantics. - -Fresh verification after the fix wave: - -- Docker L0 + HTTP port/search parity: `42 passed` (earlier checkpoint); the final L0 file has - `16 passed` including the stricter raw-role search denial. -- Expanded focused adapter/config suite: `56 passed`. -- Full harness: `466 passed, 5 deselected`. -- Changed-file Ruff lint/format and `git diff --check`: clean. - -## Sequence privilege health follow-up - -Writer health now resolves the real serial/identity sequence for the `id` column of every -required collection using `pg_get_serial_sequence`. It requires `USAGE` on each resolved -sequence, which is the privilege used by the adapter's implicit `nextval`; sequence `SELECT` is -not required because no adapter operation reads sequence state. - -The Docker fixture includes a writer role with complete table/hash-column authority but no -sequence grant. Its health is deterministically unhealthy and a new-key upsert fails. Granting -only sequence `USAGE` makes health green and the same port upsert succeeds. Sequence discovery is -guarded for partial schemas so a missing `id` column produces the existing sanitized schema -diagnostic instead of a PostgreSQL error. - -Fresh verification for this follow-up: - -- Docker pgvector L0 after formatting: `17 passed`. -- Expanded focused adapter/config/parity suite: `57 passed`. -- Full harness: `467 passed, 5 deselected`. -- Changed-file Ruff lint/format and `git diff --check`: clean. diff --git a/.superpowers/sdd/pgvector-task-2-report.md b/.superpowers/sdd/pgvector-task-2-report.md deleted file mode 100644 index 6fcac409..00000000 --- a/.superpowers/sdd/pgvector-task-2-report.md +++ /dev/null @@ -1,82 +0,0 @@ -# Local pgvector Task 2 report - -## Outcome - -Implemented ordered, idempotent production migrations and the `tht vector migrate` -interface, including `tht vector migrate --status --json` with pristine JSON output. - -## Implementation - -- `001_extensions.sql` installs pgvector. -- `002_schema_tables.sql` creates `vectors.schema_records`, `vectors.evidence`, and - `vectors.memory` with the `VectorWriteRecord` columns and `vector(768)` embeddings. -- `003_roles.sql` creates passwordless `NOLOGIN` reader/writer roles. Deployments inject - credentials (or grant these roles to separately-created login roles); no production secret - is stored in the repository. -- Reader authority is schema usage plus table `SELECT`. -- Writer authority is schema usage, table `INSERT`/`UPDATE`, narrow hash-probe column `SELECT`, - and sequence `USAGE`. It has no `DELETE`, broad row `SELECT`, DDL, or ownership authority. -- The migration runner discovers ordered SQL files, records SHA-256 checksums in - `public.tht_vector_migrations`, serializes runners with a transaction-scoped advisory lock, - and applies the full pending batch in one transaction. -- Status distinguishes applied, pending, and checksum-drifted migrations. Apply refuses drift. - A failed migration rolls back both prior migrations in that batch and ledger writes. - -## TDD evidence - -RED was observed with a real `pgvector/pgvector:pg16` testcontainer: 6 failures for the missing -module, missing command, and missing schema. - -GREEN verification: - -- Focused migration + direct adapter integration: `23 passed`. -- Full harness from the documented `harness/` cwd: `473 passed, 5 deselected`. -- Targeted Ruff (`tht` plus the new L0 test): clean. -- `git diff --check`: clean. - -The new L0 coverage exercises clean install, idempotent rerun, pristine JSON status, checksum -drift, transaction rollback, exact tables/columns/dimensions, role isolation, sequence authority, -and the real `PgVectorStore.health()` plus `VectorWriteRecord` upsert path. - -## Existing repository lint baseline - -The requested full `ruff check .` was run. It reports 34 pre-existing violations in unrelated -test files (unused imports and one-line semicolon statements). None are in Task 2 files; changing -them would exceed this task's scope. The complete harness test gate is green. - -## Self-review - -No unresolved Task 2 correctness concern found. One deliberate contract choice is worth noting: -writer `INSERT` and `UPDATE` are table-level because the approved direct adapter health probe uses -`has_table_privilege` for those authorities. Least privilege is retained by withholding broad -`SELECT`, `DELETE`, DDL, ownership, and credentials. - -## Review fix wave - -The post-implementation review found four production-boundary gaps. They are fixed as follows: - -- Migration SQL now ships inside the `tht` wheel (`tht/migrations/vector`) via explicit - setuptools package-data and is discovered through `importlib.resources`, rather than relying on - a source-checkout-relative directory. -- Both status and apply reject ledger versions absent from the installed manifest, including - nonnumeric future version labels. This treats a binary/database downgrade as drift instead of - silently reporting a healthy state. -- Migration files are ordered by parsed integer version; spellings such as `2` and `02` are - rejected as duplicate versions. -- Every migration transaction pins `search_path` locally to `pg_catalog, pg_temp`; catalog calls - and the ledger are schema-qualified. pgvector is installed into the locked `vectors` schema, - tables use `vectors.vector`, and `PgVectorStore` qualifies vector casts and the cosine operator. - A hostile admin default path with a writable shadow schema cannot redirect migration objects. -- The core image build asserts CLI discovery. Image verification now starts an ephemeral pgvector - database, runs the installed image's migration command, and compares pristine apply/status JSON. - -Additional verification after the fix wave: - -- Focused migration, adapter, hostile-path, and wheel suite: `27 passed`. -- Full harness: `477 passed, 5 deselected`. -- Production core image build: passed, including build-time CLI discovery. -- Core-image apply/status smoke against `pgvector/pgvector:pg16`: passed. -- Changed production and test files: Ruff clean; `git diff --check` clean. -- Full Ruff remains at the same 34 pre-existing unrelated test-file findings documented above. - -No dependency changed, so the committed Python requirements lock did not require regeneration. diff --git a/.superpowers/sdd/pgvector-task-3-report.md b/.superpowers/sdd/pgvector-task-3-report.md deleted file mode 100644 index 32199b42..00000000 --- a/.superpowers/sdd/pgvector-task-3-report.md +++ /dev/null @@ -1,133 +0,0 @@ -# Task 3 report — optional local pgvector profile - -## Status - -Implemented and verified the `local-vector` Compose profile. - -- `vector-db` uses pgvector 0.8.5 on PostgreSQL 16, pinned to the official multi-arch - manifest digest. -- `vector_data` is a project-scoped named volume and is not shared with application data. -- database readiness gates the packaged one-shot `vector-migrate` job; core declares the - migration completion dependency while remaining usable in the pre-existing external profile. -- bootstrap, migrator, reader, and writer identities are distinct. Bootstrap and migration - credentials are supplied as Compose secrets; the application receives only reader/writer - credentials. -- `deploy/workspaces/local-vector.yaml` selects `pgvector_direct` with separate reader and - writer connections. -- the base loopback port binding, `AUTH_MODE=none`, and `THOTH_PUBLIC_EXPOSURE=false` defaults - are unchanged. - -## Red/green evidence - -The initial Compose contract did not list `vector-db`, as required by the brief. The first real -smoke then failed migration 002 because bootstrap installed the vector extension in `public`. -The bootstrap was corrected to create the `vectors` schema under the migration owner and install -the extension there. A clean-volume rerun passed. - -## Verification - -- `./scripts/local-vector-smoke.sh`: PASS - - isolated generated Compose project and credentials - - clean migration plus idempotent status rerun - - reader/writer privilege health - - one-record upsert and similarity search - - restart of both `core` and `vector-db` - - persisted search result after restart - - project-only volume cleanup -- `./scripts/test-container-deployment.sh`: PASS -- `./scripts/test-backend-url-policy.sh`: PASS -- `docker compose --profile local-vector config --quiet`: PASS -- harness: 477 passed, 5 deselected -- backend: 84 passed; TypeScript typecheck PASS -- frontend: 226 passed; TypeScript typecheck PASS -- `git diff --check`: PASS - -## Self-review / concerns - -- Compose cannot make a dependency required only under one profile. The core dependency uses - `required: false` so the established `external` profile does not activate local infrastructure; - under `local-vector`, `compose up --wait` still fails if `vector-migrate` exits nonzero, and the - smoke verifies that successful migration precedes the healthy stack. -- Reader/writer passwords are injected into core environment variables because Compose service - attributes cannot be conditional by profile. Bootstrap and migrator credentials remain - file-backed secrets and are never exposed to core. -- The smoke intentionally refuses the operator project name `thothii` and removes only its unique - project namespace and volumes. - -## Follow-up hardening — credential reconciliation and cleanup ownership - -Review findings were resolved in a separate follow-up: - -- Replaced fresh-volume-only initialization with `vector-reconcile`, an idempotent one-shot that - runs after database health and before `vector-migrate`. It authenticates with only the bootstrap - admin secret, safely creates missing identities, reconciles role attributes and passwords on - existing volumes, restores memberships/ownership, and leaves vector data untouched. -- The migrator is explicitly `NOSUPERUSER NOCREATEDB NOCREATEROLE`. Schema/database ownership is - sufficient for all packaged migrations because reconciliation creates the two group roles first. -- The live smoke rotates migrator, reader, and writer secrets on the same populated volume, rejects - the old reader credential, reruns migrations, recreates core with the new runtime credentials, - and retrieves the record written before rotation and again after database/core restart. -- Smoke project names are no longer caller-controlled. Each run creates a unique namespace and - ownership token. Containers, networks, and volumes carry the ownership label; preflight refuses - any collision and cleanup verifies every discovered resource before `down --volumes`. -- Added a dynamic fake-Docker contract suite for caller override, collision, and mismatched cleanup - labels, plus a real-Docker collision probe using a unique labeled volume. - -Follow-up verification: - -- `./scripts/local-vector-smoke.sh`: PASS, including live secret rotation and persisted retrieval -- `./scripts/test-local-vector-smoke-safety.sh`: PASS -- `./scripts/test-local-vector-smoke-live-collision.sh`: PASS -- harness: 477 passed, 5 deselected -- backend: 84 passed; TypeScript typecheck PASS -- frontend: 226 passed; TypeScript typecheck PASS -- Compose security, backend URL, config, shell syntax, and diff checks: PASS - -Remaining operational constraint: the bootstrap admin secret must continue to match the PostgreSQL -bootstrap account stored in the volume. Runtime migrator/reader/writer rotation is supported without -data deletion; bootstrap-account password rotation is a distinct database-administration operation. - -## Final hardening — bootstrap account rotation - -The remaining operational constraint is now covered by -`scripts/vector-rotate-bootstrap-password.sh OLD_SECRET_FILE NEW_SECRET_FILE`: - -- It does not rely on `POSTGRES_PASSWORD_FILE` after initialization. -- It pre-stages the deployment-file replacement in the same directory, authenticates to the live - database with the explicit old file, and changes only the authenticated bootstrap role. -- Passwords are passed as connection parameters and rendered with psycopg2 SQL composition, so - shell and SQL metacharacters are not interpolated. -- A second connection must authenticate with the new password before the command succeeds. If that - verification fails, the still-open old connection restores the old database password. -- Only after verified database login does an atomic rename replace the current deployment secret. - Wrong-old authentication and verification failures leave deployment configuration unchanged. - -Final live smoke evidence on one existing `vector_data` volume: - -- wrong-old bootstrap rotation rejected; current deployment secret unchanged -- bootstrap password with quote characters rotated successfully -- old bootstrap login rejected and new login accepted -- `vector-reconcile`, packaged migrations, and core health passed afterward -- the vector record written before rotation remained searchable after rotation and after a further - database/core restart - -Final tests: - -- `./scripts/test-vector-bootstrap-rotation.sh`: PASS -- `./scripts/local-vector-smoke.sh`: PASS with negative and positive live bootstrap rotation -- existing local-vector collision/safety and Compose deployment contracts: PASS - -## Final identity and secret-policy alignment - -- `THT_VECTOR_BOOTSTRAP_USER` is now passed through core as well as vector-db and reconciliation, - so the rotation helper uses the authoritative configured role instead of defaulting to `postgres`. -- Rotation and reconciliation source the same raw-file `secret-policy.sh`: non-empty and no - whitespace, including trailing newlines. Rotation validates both files before Docker, - PostgreSQL, or atomic replacement staging; `test-vector-secret-policy.sh` pins empty, newline, - internal-space, and valid metacharacter cases. -- Fake-Docker tests prove a non-default identity reaches the helper path and whitespace rejection - performs no Docker call and creates no staged replacement. -- The real smoke runs the entire stack as `thoth_bootstrap_smoke`. Its whitespace-negative case - leaves the deployment file unchanged and proves the existing database login still succeeds; - non-default-account bootstrap rotation, reconciliation, migration, core health, restart, and - persisted retrieval all pass. diff --git a/.superpowers/sdd/pgvector-task-4-report.md b/.superpowers/sdd/pgvector-task-4-report.md deleted file mode 100644 index 38fe1607..00000000 --- a/.superpowers/sdd/pgvector-task-4-report.md +++ /dev/null @@ -1,94 +0,0 @@ -# Local pgvector Task 4 report - -## Outcome - -Implemented adapter parity gates and an operator-safe custom-format backup/restore workflow. - -- Direct and HTTP stores now share validation, configured-dimension rejection, and deterministic - similarity ordering with record ID as the tie-break. -- The parity fixture exercises identical records through real pgvector and the HTTP RPC contract: - kind filtering, ordering, hashes, replacement upserts, invalid collection/kind errors, and query - plus write dimensions. -- Backup explicitly allowlists the three vector tables and migration ledger, refuses overwrite, - writes through a partial file, and uses a custom compressed archive. -- Restore requires explicit active-source and target coordinates. It compares PostgreSQL system - identifier plus database OID (robust across DNS aliases), refuses the active database, checks for - an empty target unless force is explicit, and restores with exit-on-error. -- Passwords are accepted only through validated secret files, converted to private temporary - `PGPASSFILE`s, and never placed in command arguments or success/error logs. -- Role passwords/login identities are deliberately not dumped. The target must have the approved - passwordless group roles and pgvector extension reconciled before restore; archived ACLs restore - the reader/writer grants. - -## TDD and semantic alignment - -The first parity run exposed the intended HTTP differences: it accepted unknown collections and -wrong dimensions. Direct pgvector also had no stable order for equal cosine distance. The adapters -were aligned, and the final focused real-pgvector gate passed: **25 passed**. - -The first recovery run caught an incorrect probe username before restore. The second caught an -intersection between `pg_dump --schema` and the explicit public ledger table. The third confirmed -the archive contents but caught missing target group roles. Each defect was corrected and the -complete drill was rerun from a fresh generated project. - -## Live recovery smoke - -`./scripts/local-vector-smoke.sh --backup-restore`: **PASS**. - -- generated/owned source Compose project and source `vector_data` -- distinct restore container and distinct named restore volume -- migration and role health, secret rotation, restart persistence -- real custom backup, then deliberate mutation of the active source record -- same-database identity guard evaluated before restore -- restore into the separate target only -- restored hash equals the pre-mutation backup, proving retrieval parity -- migration ledger has all three applied versions -- all three restored embedding columns report `vectors.vector(768)` -- ownership-checked cleanup; the active operator project/volume is never addressed - -## Verification - -- parity + direct adapter: 25 passed -- full harness: 485 passed, 5 deselected -- changed Python files: Ruff clean -- shell syntax: clean -- `git diff --check`: clean -- full Ruff: unchanged repository baseline of 34 unrelated pre-existing test-file violations - -## Self-review and operational constraints - -The restore account must be able to read `pg_control_system()` for the robust cluster-identity -comparison and create/restore the selected objects. This is intentionally an administrative -recovery operation, not a runtime reader/writer action. `--force-nonempty` is explicit but still -uses `pg_restore --clean --if-exists`; operators should prefer a new database/volume and validate -migration status, health, and known retrieval before endpoint cutover. - -## Post-review hardening - -All five final review findings were addressed in a follow-up commit: - -- Restore now requires a physically separate PostgreSQL cluster and refuses any equal - `system_identifier`, independent of database OID or hostname. -- `pg_restore` combines `--single-transaction` with `--exit-on-error`. The live drill creates an - existing vector sentinel, deliberately fails late during a forced restore, and proves the - original sentinel row/hash remains unchanged before performing the successful restore. -- Backup uses a mode-0600 `mktemp` in the output directory, atomically renames it, and cleans only - that owned path. A fake-command test pins symlink-clobber resistance and preserves an adversarial - legacy `.partial` symlink and its target. -- HTTP parity now traverses the real `VectorRestClient` transport boundary. It asserts RPC URL/key - and kinds payloads, legacy 404 fallback, response conversion, malformed metadata tolerance, and - canonical `VectorRestError` to `VectorStoreError` mapping. -- The restored target runs role/secret reconciliation and a real `PgVectorStore` with separate - reader/writer logins. Health, known-record search, writer upsert, hash probe, schema/table/column/ - sequence authority, and 768-dimensional compatibility are therefore verified through the - production adapter. Reconciliation now restores group-role schema `USAGE`, which table-selected - archives cannot carry. - -### Atomic no-replace backup publication - -The final publication review is also closed. The private same-directory archive is published with -an atomic hard-link create rather than rename-overwrite semantics. If any process creates the final -file or symlink after preflight but before publication, `ln` fails with `EEXIST`, the backup exits -nonzero, the concurrent destination remains byte-for-byte intact, and the trap removes only the -randomly named temporary archive owned by this invocation. The fake `pg_dump` safety test creates -that destination immediately before returning and pins the failure and cleanup behavior. diff --git a/.superpowers/sdd/predeploy-fix-report.md b/.superpowers/sdd/predeploy-fix-report.md deleted file mode 100644 index 98968698..00000000 --- a/.superpowers/sdd/predeploy-fix-report.md +++ /dev/null @@ -1,929 +0,0 @@ -# Pre-deployment Fix Wave Report - -Date: 2026-07-14 -Worktree: `/home/chirone/ThothII/.worktrees/activity-log-cte-layout` -Base: `e5366d14a6da8fb331d94be60b8929cefb1fe3e0` - -## Outcome - -All three reviewed findings are implemented in one coherent backend/frontend wave: - -1. Resume leaves the prior selection, Zustand state, document panel, and EventSource untouched - until `POST /resume` succeeds. Cold Resume changes state and reconnects only after backend - clear/rebind; already-active same-session Resume preserves the existing binding; failure is a - no-op apart from the fixed toast. -2. SSE uses monotonically increasing per-session ids, cursor-filtered replay, native and manual - reconnect cursors, id continuity across `hub.clear`, and descriptor-id pending-gate - idempotence at both backend and frontend layers. -3. Generic Pi system events and readiness errors are projected through explicit public - allowlists. Sentinel URLs, paths, tokens, stderr, commands, and extra fields do not reach HTTP - or SSE. - -No harness, workflow, persistence, model, CTE viewer, CTE card, or shared Card file changed. - -## Interfaces - -- Frontend `resumeSession(id)` now returns - `Promise<{ id: string; alreadyActive: boolean }>` via `ResumeSessionResult`. -- Backend successful Resume always returns the same shape: - - running/waiting runtime: `{ id, alreadyActive: true }` - - validated cold runtime: `{ id, alreadyActive: false }` -- `SseHub.publish(sessionId, event, data): number` returns the assigned SSE id. -- `SseHub.subscribe(sessionId, send, { afterId, pending })` calls - `send(event, data, id)` for replay/live frames with `id > afterId`. -- `GET /sessions/:id/events` accepts native `Last-Event-ID` and manual - `?lastEventId=`; when both are valid it uses the greater cursor. -- Every emitted SSE frame is `id: \nevent: \ndata: \n\n`. -- Public readiness failure is exactly: - `Session services are not ready. Check configuration and connectivity, then try again.` -- Generic Pi system events are exactly `{ type: "system_event", event }`, and `event` must be a - non-empty string. - -## Files - -Backend production: - -- `backend/src/bridge/session-bridge.ts` -- `backend/src/routes/sessions.ts` -- `backend/src/sse/sse-hub.ts` - -Backend tests: - -- `backend/test/routes-sessions.test.ts` -- `backend/test/session-bridge.test.ts` -- `backend/test/sse-hub.test.ts` -- `backend/test/sse-route.test.ts` (new) - -Frontend production/support: - -- `frontend/src/api/sessions.ts` -- `frontend/src/api/types.ts` -- `frontend/src/shell/AppShell.tsx` -- `frontend/src/store/sessionStore.ts` -- `frontend/src/stream/useSessionStream.ts` -- `frontend/src/test/fakeEventSource.ts` - -Frontend tests: - -- `frontend/src/api/sessions.test.ts` -- `frontend/src/shell/AppShell.session-mgmt.test.tsx` -- `frontend/src/store/sessionStore.test.ts` -- `frontend/src/stream/useSessionStream.test.tsx` - -## TDD RED/GREEN evidence - -### 1. Backend Resume result and client-boundary allowlists - -RED command: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts test/session-bridge.test.ts -``` - -RED output (exit 1): - -```text -Test Files 2 failed (2) -Tests 6 failed | 35 passed (41) - -expected { id: 's1' } to deeply equal { id: 's1', alreadyActive: false } -expected raw readiness URL/token/path to equal the fixed public message -expected three raw generic system events to equal [{ type: 'system_event', event: 'session_exit' }] -``` - -GREEN command: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts test/session-bridge.test.ts -``` - -GREEN output (exit 0): - -```text -✓ test/session-bridge.test.ts (14 tests) -✓ test/routes-sessions.test.ts (27 tests) -Test Files 2 passed (2) -Tests 41 passed (41) -``` - -### 2. Backend exact-once SseHub and route framing - -RED command: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/sse-route.test.ts -``` - -RED output (exit 1): - -```text -Test Files 2 failed (2) -Tests 7 failed (7) - -expected [undefined, undefined, undefined] to deeply equal [1, 2, 3] -expected unconditional replay not to contain "one" / "two" -expected one buffered pending gate, received replay plus a second pending emission -``` - -GREEN command: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/sse-route.test.ts -``` - -GREEN output (exit 0): - -```text -✓ test/sse-hub.test.ts (4 tests) -✓ test/sse-route.test.ts (3 tests) -Test Files 2 passed (2) -Tests 7 passed (7) -``` - -### 3. Frontend cursor tracking and gate idempotence - -RED command: - -```text -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx src/store/sessionStore.test.ts -``` - -RED output (exit 1): - -```text -Test Files 2 failed (2) -Tests 2 failed | 28 passed (30) - -expected /sessions/s1/events to be /sessions/s1/events?lastEventId=7 -expected duplicate gate pendingWidget to remain null, received gate-1 -``` - -GREEN command: - -```text -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx src/store/sessionStore.test.ts -``` - -GREEN output (exit 0): - -```text -✓ src/store/sessionStore.test.ts (23 tests) -✓ src/stream/useSessionStream.test.tsx (7 tests) -Test Files 2 passed (2) -Tests 30 passed (30) -``` - -### 4. Frontend typed Resume and AppShell ordering/preservation - -Typed API RED command: - -```text -cd frontend && npx tsc -b -``` - -Typed API RED output (exit 1): - -```text -src/api/sessions.test.ts(43,9): error TS2322: Type 'void' is not assignable to type -'{ id: string; alreadyActive: boolean; }'. -``` - -Lifecycle RED command: - -```text -cd frontend && npx vitest run src/api/sessions.test.ts src/shell/AppShell.session-mgmt.test.tsx -``` - -Lifecycle RED output (exit 1): - -```text -✓ src/api/sessions.test.ts (9 tests) -❯ src/shell/AppShell.session-mgmt.test.tsx (15 tests | 4 failed) -Test Files 1 failed | 1 passed (2) -Tests 4 failed | 20 passed (24) - -already-active same-session Resume created two EventSources instead of one -deferred cold Resume closed the document panel before POST completion -failed same-session Resume closed the prior EventSource -failed Resume with no active session opened an EventSource -``` - -GREEN commands: - -```text -cd frontend && npx vitest run src/api/sessions.test.ts src/shell/AppShell.session-mgmt.test.tsx -cd frontend && npx tsc -b -``` - -GREEN output (exit 0): - -```text -✓ src/api/sessions.test.ts (9 tests) -✓ src/shell/AppShell.session-mgmt.test.tsx (15 tests) -Test Files 2 passed (2) -Tests 24 passed (24) -TypeScript: no output, exit 0 -``` - -The AppShell cold-reconnect test additionally proves that the old source accepts an event while -Resume is pending, the replacement URL carries `lastEventId=8`, the replacement receives one -post-resume transcript/activity row, and two deliveries of the same descriptor id yield one gate. - -## Affected verification - -Backend command: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts test/session-bridge.test.ts \ - test/sse-hub.test.ts test/sse-route.test.ts test/health.test.ts test/e2e-f1.test.ts -``` - -Output (exit 0): - -```text -Test Files 6 passed (6) -Tests 52 passed (52) -``` - -Backend typecheck: - -```text -cd backend && npx tsc --noEmit -p . -``` - -Output: no output, exit 0. - -Frontend command: - -```text -cd frontend && npx vitest run src/api/sessions.test.ts src/store/sessionStore.test.ts \ - src/stream/useSessionStream.test.tsx src/shell/AppShell.session-mgmt.test.tsx \ - src/shell/CentralStatus.test.tsx src/shell/ModelActivityPanel.test.tsx \ - src/shell/f1-loop.test.tsx src/shell/AppShell.new-session.test.tsx -``` - -Output (exit 0): - -```text -Test Files 8 passed (8) -Tests 74 passed (74) -``` - -Frontend typecheck: - -```text -cd frontend && npx tsc -b -``` - -Output: no output, exit 0. - -## Full verification - -Backend full suite: - -```text -cd backend && npx vitest run -``` - -```text -Test Files 22 passed (22) -Tests 177 passed (177) -``` - -Frontend full suite: - -```text -cd frontend && npx vitest run -``` - -```text -Test Files 43 passed (43) -Tests 271 passed (271) -``` - -Backend production build: - -```text -cd backend && npm run build -> tsc -p tsconfig.json -exit 0 -``` - -Frontend production build: - -```text -cd frontend && npm run build -> tsc -b && vite build -✓ 4835 modules transformed. -✓ built in 8.25s -exit 0 -``` - -## Integrated re-review closure (2026-07-15) - -This section supersedes the earlier cold same-session assertion that the replacement URL carries -`lastEventId=8`. That behavior was correct only while the backend process and its in-memory id -sequence survived. A restarted backend begins a fresh sequence, so a successful cold Resume now -explicitly discards the browser's cursor before replacing the EventSource. - -All four integrated re-review findings are closed: - -1. `AppShell` passes a dedicated cursor-reset epoch to `useSessionStream`. A cold same-session - Resume increments it only after `alreadyActive: false`; a high cursor such as `901` is omitted - from the replacement URL and fresh low-id events/gates are consumed. An already-active - same-session Resume still preserves its source, cursor, and store. -2. `useSessionStream` no longer mutates the cursor ref during render. Effect setup resets cursor - state on session/reset-epoch changes, callbacks are guarded by a captured active-source - identity, and cleanup clears only its own active identity. A queued event from the replaced - source cannot write the new store or poison its next reconnect URL. -3. Backend Resume is serialized per session and rechecks runtime state inside the lock. Manifest, - readiness, and reopen validation precede the transport commit. Idle/failed replacement creates - and binds the new runtime before `hub.clear`, which occurs synchronously immediately before the - first `Resuming session` publish. Reopen/create failure returns exactly - `Session could not be resumed. Check configuration and connectivity, then try again.`, keeps the - prior hub buffer/subscribers attached, and does not expose exception sentinels. Concurrent calls - perform one cold start and the waiter returns `alreadyActive: true`. -4. `SseHub.forget(id)` removes subscribers, buffered events, and the last id. Permanent session - DELETE invokes it after disk deletion; ordinary close and Resume continue to use `clear`, which - preserves the id sequence. - -### Re-review files - -Production: - -- `backend/src/pi/pi-process-manager.ts` -- `backend/src/routes/sessions.ts` -- `backend/src/sse/sse-hub.ts` -- `frontend/src/shell/AppShell.tsx` -- `frontend/src/stream/useSessionStream.ts` - -Tests/support: - -- `backend/test/pi-process-manager.test.ts` -- `backend/test/routes-sessions.test.ts` -- `backend/test/sse-hub.test.ts` -- `frontend/src/shell/AppShell.session-mgmt.test.tsx` -- `frontend/src/stream/useSessionStream.test.tsx` -- `frontend/src/test/fakeEventSource.ts` - -### Re-review TDD RED/GREEN evidence - -Frontend RED command: - -```text -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx \ - src/shell/AppShell.session-mgmt.test.tsx -``` - -RED output (exit 1): - -```text -Test Files 2 failed (2) -Tests 3 failed | 21 passed (24) - -reset epoch: expected the old source to close, received false -cold same-session: expected /sessions/s1/events, received ?lastEventId=901 -stale source: expected an empty transcript, received "stale session one" -``` - -Frontend GREEN command: - -```text -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx \ - src/shell/AppShell.session-mgmt.test.tsx -cd frontend && npx tsc -b -``` - -GREEN output (exit 0): - -```text -Test Files 2 passed (2) -Tests 24 passed (24) -TypeScript: no output, exit 0 -``` - -Backend RED command: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/routes-sessions.test.ts -``` - -RED output (exit 1): - -```text -Test Files 2 failed (2) -Tests 8 failed | 28 passed (36) - -three Resume ordering assertions observed clear before reopen/create -reopen and create sentinels escaped as raw HTTP 500 responses -the concurrent waiter cold-started again instead of returning alreadyActive: true -SseHub.forget was absent and DELETE did not invoke permanent cleanup -``` - -Backend GREEN command: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/routes-sessions.test.ts -cd backend && npx tsc --noEmit -p . -``` - -GREEN output (exit 0): - -```text -Test Files 2 passed (2) -Tests 36 passed (36) -TypeScript: no output, exit 0 -``` - -The failure tests publish a post-failure probe through the same hub and prove that a subscriber -attached before either reopen or create rejection still receives it. The concurrency test overlaps -two same-id requests behind a deferred reopen and proves one manifest/readiness/reopen/create/clear -sequence. - -### Initial re-review verification (before independent-review hardening) - -```text -cd backend && npx vitest run -Test Files 22 passed (22) -Tests 182 passed (182) - -cd frontend && npx vitest run -Test Files 43 passed (43) -Tests 273 passed (273) - -cd backend && npm run build -> tsc -p tsconfig.json -exit 0 - -cd frontend && npm run build -> tsc -b && vite build -✓ 4835 modules transformed. -✓ built in 8.46s -exit 0 -``` - -`git diff --check` produced no output (exit 0). The frontend build retains its pre-existing -large-chunk warning; no new build or type errors were introduced. - -Final whitespace verification: - -```text -git diff --check -no output, exit 0 -``` - -## Self-review - -- Resume sequencing: reopen and runtime binding precede backend `clear` and HTTP success; frontend - state mutation and cursor-reset epoch follow it. Failure catch only emits fixed UI copy. -- Already active: same-session returns before reset/generation/manifest repaint; different session - resets the single-session store and binds the new id only after success. -- SSE exact-once: ids are transport identity, not content hashes; replay is strictly `id > cursor`; - `clear` retains the counter; pending gate matching uses only descriptor id. -- Cursor behavior: hook tracks `MessageEvent.lastEventId`, carries it only to an ordinary same-id - generation, and resets it on session-id/cold-runtime epoch change. Native EventSource reconnect - remains supported by the route header. -- Gate defense: the Zustand set survives pending clear but resets with the session store. -- Client boundary: raw `ensure.error` is unused in public responses; generic Pi system events are - reconstructed rather than spread; frontend type mirrors the two-field event. -- Scope: `git diff` contains no CTE/Card/harness/workflow/persistence/model changes. Four pre-existing - modified `.superpowers/sdd/{progress,task-2-report,task-3-report,task-4-report}.md` files are user - work and are excluded from staging. - -## Remaining concerns - -- The 200-event SSE ring limit remains intentional. A brand-new page can reconstruct only retained - backlog; an in-memory same-session reconnect is exact-once from its cursor. -- Per-session sequence counters remain in backend memory after `clear` by design so later in-process - cold same-id Resume cannot reuse ids. Permanent DELETE removes the counter via `forget`. -- The Delete-then-Resume adversarial route test proves the deleted session is not resurrected but - currently receives the runner's generic HTTP 500 when `sessionShow` can no longer find it. A - future API cleanup can normalize that missing-session response to 404 or 409. -- Frontend tests still print pre-existing MSW unhandled-request and React ref/`act` warnings even - though all 276 tests pass. The frontend production build still reports pre-existing large chunk - warnings. Neither warning class was introduced or expanded by this change. -- No live Pi/DWH smoke was run; this wave changes only REST/SSE/frontend lifecycle boundaries and - is covered by fake-Pi, live Fastify SSE, component, full-suite, typecheck, and production-build - gates. - -## Independent-review hardening - -The required independent review was run repeatedly against the uncommitted diff. Its first pass -found four Important lifecycle edges beyond the integrated findings: queued old-runtime callbacks, -post-spawn construction cleanup, concurrent frontend Resume completions, and the passive-effect -commit window. Its second pass confirmed those fixes and identified one remaining Important -retention issue in the new runtime-identity map. The final pass reported no Critical, Important, or -Minor findings and assessed the diff ready to merge. - -The resulting hardening is: - -- Runtime bridge callbacks are gated by the bound runtime identity. Replacement, close, and DELETE - invalidate the old identity, so queued old events cannot publish or call `failSession`. An active - runtime removed by the manager can still publish its complete public failure sequence; after the - terminal unmanaged `agent_end`, its binding is released and later events are rejected. -- `PiProcessManager` kills the spawned child and removes any registered map entry if either - spawn-boundary stderr setup or later RPC/bridge/map initialization throws. -- Resume completion compares against synchronously maintained current active-session identity. - Concurrent `alreadyActive: false` then `alreadyActive: true` results preserve the cold source, - cursor, store, and replayed gate. -- Stream source replacement uses a layout effect. A deterministic later-layout-effect test delivers - a queued old event inside the former commit-to-passive-cleanup window and proves it is ignored. -- Cursor tests cover both a restarted backend's fresh low ids and an in-process hub's preserved high - ids followed by a cursor-bearing ordinary reconnect. - -### Hardening TDD RED/GREEN evidence - -Backend identity/construction RED command: - -```text -cd backend && npx vitest run test/pi-process-manager.test.ts test/routes-sessions.test.ts -``` - -```text -Test Files 2 failed (2) -Tests 3 failed | 69 passed (72) - -post-spawn reader initialization did not kill the child -replaced and deleted runtime callbacks still called failSession/published -``` - -Additional spawn-boundary and terminal-release RED checks: - -```text -cd backend && npx vitest run test/pi-process-manager.test.ts \ - -t "spawn boundary initialization" -Tests 1 failed | 38 skipped (39) - -cd backend && npx vitest run test/routes-sessions.test.ts -t "terminal sequence" -Tests 1 failed | 34 skipped (35) -``` - -Frontend concurrency/layout RED command: - -```text -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx \ - src/shell/AppShell.session-mgmt.test.tsx -``` - -```text -Test Files 2 failed (2) -Tests 2 failed | 25 passed (27) - -the later-layout-effect event wrote "commit-window stale text" -the false→true completion pair erased pending gate "cold-gate" -``` - -Final focused GREEN commands: - -```text -cd backend && npx vitest run test/pi-process-manager.test.ts \ - test/routes-sessions.test.ts test/sse-hub.test.ts -cd backend && npx tsc --noEmit -p . - -Test Files 3 passed (3) -Tests 79 passed (79) -TypeScript: no output, exit 0 - -cd frontend && npx vitest run src/stream/useSessionStream.test.tsx \ - src/shell/AppShell.session-mgmt.test.tsx -cd frontend && npx tsc -b - -Test Files 2 passed (2) -Tests 27 passed (27) -TypeScript: no output, exit 0 -``` - -### Final full verification after review hardening - -```text -cd backend && npx vitest run -Test Files 22 passed (22) -Tests 188 passed (188) - -cd frontend && npx vitest run -Test Files 43 passed (43) -Tests 276 passed (276) - -cd backend && npm run build -> tsc -p tsconfig.json -exit 0 - -cd frontend && npm run build -> tsc -b && vite build -✓ 4835 modules transformed. -✓ built in 8.47s -exit 0 -``` - -The final frontend run retains the repository's pre-existing MSW/ref/`act` warnings, and the build -retains the pre-existing large-chunk warning. No test, typecheck, or build failures remain. - -## Stale-bootstrap, lifecycle-lock, and competing-Resume hardening - -Date: 2026-07-15 -Base: `08b1f4909e8eb7538156cecc2e7a6cafb46ddfc7` - -This follow-up closes asynchronous identity/order and multi-client transport gaps found in the -pre-deployment review: - -- `PiProcessManager.teardownIfCurrent(id, runtime)` makes teardown an identity-checked operation. - Bootstrap re-checks identity after configuration/retrieval and before both the public - `Starting model` event and model start. Its failure continuation acquires the same session - lifecycle lock, claims only its own runtime identity, and holds serialization through persisted - failure and the public terminal sequence. A continuation left behind by Close or DELETE cannot - target a replacement or recreate forgotten SSE state. -- The former Resume-only promise tail is now a per-session lifecycle lock shared by Resume, Close, - and DELETE. Each route reads the current runtime inside the lock immediately before replacement - or removal and uses identity-checked teardown. Deferred route tests prove both orderings: - Resume then Close/Delete finishes removed with no post-removal bootstrap event; Close then Resume - creates only after Close completes; DELETE then Resume cannot recreate a deleted session. -- AppShell assigns each Resume invocation a monotonic token and records the latest target. A - completion for a different, superseding session id cannot reset the store, select a source, close - the panel, or repaint phase from a late manifest. Same-id invocations are per-target single-flight - operations through the POST and local binding commit: repeated pre-commit clicks update the - shared operation's latest token but issue no second POST or commit path. The operation becomes - joinable again before its manifest fetch, whose repaint remains token/id/selection guarded. Start - new, Stop, streamed session exit, and active-session deletion invalidate pending Resume work. - This prevents stale-source preservation and reverse/non-Resume intent overwrite without allowing - a slow manifest to suppress a later explicit rebind. -- `SseHub` subscriber registrations now carry idempotent transport-close callbacks. `clear` and - `forget` snapshot and actively close every response before discarding runtime transport state; - callback-driven unsubscription during that iteration is safe. The SSE route ends its response so - native EventSource reconnects with `Last-Event-ID`. Post-clear events retain monotonic ids and are - buffered for replay; `forget` additionally resets the id state. - -Production files: - -- `backend/src/pi/pi-process-manager.ts` -- `backend/src/routes/sessions.ts` -- `backend/src/sse/sse-hub.ts` -- `frontend/src/shell/AppShell.tsx` - -Regression tests: - -- `backend/test/pi-process-manager.test.ts` -- `backend/test/routes-sessions.test.ts` -- `backend/test/sse-hub.test.ts` -- `backend/test/sse-route.test.ts` -- `frontend/src/shell/AppShell.session-mgmt.test.tsx` - -### TDD RED/GREEN evidence - -Runtime identity API RED: - -```text -cd backend && npx vitest run test/pi-process-manager.test.ts -t "identity-checked teardown" - -Test Files 1 failed (1) -Tests 1 failed | 39 skipped (40) -TypeError: mgr.teardownIfCurrent is not a function -``` - -Runtime identity API GREEN: - -```text -Test Files 1 passed (1) -Tests 1 passed | 39 skipped (40) -``` - -Deferred bootstrap RED: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts \ - -t "stale bootstrap|bootstrap that" - -Test Files 1 failed (1) -Tests 6 failed | 35 skipped (41) - -close/delete + replacement: stale continuation removed the replacement runtime -delete without replacement: stale continuation called failSession after forget -``` - -Deferred bootstrap GREEN: - -```text -Test Files 1 passed (1) -Tests 6 passed | 35 skipped (41) -``` - -Shared lifecycle ordering RED: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts \ - -t "Resume followed|Close followed|Delete followed" - -Test Files 1 failed (1) -Tests 4 failed | 41 skipped (45) - -All four deferred assertions observed the competing route settle before the first lifecycle -operation released. -``` - -Bootstrap plus lifecycle GREEN: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts \ - -t "Resume followed|Close followed|Delete followed|stale bootstrap|bootstrap that" - -Test Files 1 passed (1) -Tests 10 passed | 35 skipped (45) -``` - -Competing frontend Resume RED: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "competing Resume|stale Resume manifest" - -Test Files 1 failed (1) -Tests 2 failed | 16 skipped (18) - -reverse POST completion opened a second, stale EventSource -late s1 manifest repainted the selected s3 phase from F3 to F7 -``` - -Competing and same-id Resume GREEN: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "competing Resume|stale Resume manifest|false then true" - -Test Files 1 passed (1) -Tests 3 passed | 15 skipped (18) -``` - -### Independent-review hardening RED/GREEN - -The first final review reported no Critical findings and three Important edge cases: bootstrap -could start during an in-progress Close; bootstrap-owned failure was persisted twice; and an older -same-id result could overwrite newer state. The integrated reviewer also required non-Resume -navigation to invalidate pending Resume work. The final main review tightened the same-ID contract -to true single-flight so a second same-target click cannot preserve a dead pre-restart source. - -Backend review RED: - -```text -cd backend && npx vitest run test/routes-sessions.test.ts \ - -t "Close suppresses|bootstrap failure persists once" - -Test Files 1 failed (1) -Tests 2 failed | 45 skipped (47) - -deferred configure started Pi while closeSession was still pending -bootstrap/public failure called failSession twice -``` - -Backend review GREEN: - -```text -Test Files 1 passed (1) -Tests 2 passed | 45 skipped (47) -``` - -Same-id single-flight RED: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "share one cold request" - -Test Files 1 failed (1) -Tests 1 failed | 18 skipped (19) - -two concurrent same-ID invocations issued two cold POSTs (three total including initial activation) -``` - -Non-Resume invalidation RED: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "starting a new question invalidates" - -Test Files 1 failed (1) -Tests 1 failed | 19 skipped (20) - -the late Resume opened an EventSource after Start new returned to the landing state -``` - -Frontend review GREEN: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "share one cold request|competing Resume|stale Resume manifest|starting a new question invalidates" - -Test Files 1 passed (1) -Tests 4 passed | 15 skipped (19) -``` - -Post-commit single-flight lifetime RED: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - -t "releases same-id single-flight" - -Test Files 1 failed (1) -Tests 1 failed | 19 skipped (20) - -s1 committed and waited on its manifest; after s3 superseded it, a new s1 Resume reused the old -operation and issued no second s1 POST (expected 2, received 1). -``` - -Same-id and manifest lifetime GREEN: - -```text -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx -t "same-id|manifest" -Test Files 1 passed (1) -Tests 4 passed | 16 skipped (20) - -cd frontend && npx tsc -b -no output, exit 0 -``` - -Multi-client SSE disconnect RED: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/sse-route.test.ts - -Test Files 2 failed (2) -Tests 3 failed | 6 passed (9) - -clear/forget invoked zero of two registered close callbacks, and two live HTTP SSE responses timed -out instead of reaching EOF after clear. -``` - -Multi-client SSE disconnect GREEN: - -```text -cd backend && npx vitest run test/sse-hub.test.ts test/sse-route.test.ts -Test Files 2 passed (2) -Tests 9 passed (9) - -cd backend && npx tsc --noEmit -p . -no output, exit 0 -``` - -The Hub tests use two subscribers whose close callbacks immediately unsubscribe themselves, proving -safe snapshot iteration and exactly-once closure. The live-route test opens two HTTP streams, proves -both receive EOF on clear, publishes a new event and gate, then reconnects after id 1 and replays -exactly ids 2 and 3. The forget test closes both subscribers and proves the next id resets to 1. - -Close now removes the observed runtime identity before awaiting persistence. Failure persistence is -claimed once per runtime and lifecycle-serialized; bootstrap's public `session_failed` cannot start -a duplicate. A per-target in-flight map owns the only same-ID POST and commit while its mutable -latest token keeps s1→s2→s1 ordering correct; it is removed immediately after the binding commit, -before awaiting the independently guarded manifest. One shared invalidation helper is called when -active deletion, streamed exit, Start new, or Stop begins. - -### Focused verification - -```text -cd backend && npx vitest run test/routes-sessions.test.ts test/pi-process-manager.test.ts \ - test/sse-hub.test.ts test/sse-route.test.ts -Test Files 4 passed (4) -Tests 96 passed (96) - -cd backend && npx tsc --noEmit -p . -no output, exit 0 - -cd frontend && npx vitest run src/shell/AppShell.session-mgmt.test.tsx \ - src/shell/AppShell.new-session.test.tsx src/stream/useSessionStream.test.tsx -Test Files 3 passed (3) -Tests 36 passed (36) - -cd frontend && npx tsc -b -no output, exit 0 -``` - -### Full verification - -```text -cd backend && npx vitest run -Test Files 22 passed (22) -Tests 202 passed (202) - -cd frontend && npx vitest run -Test Files 43 passed (43) -Tests 280 passed (280) - -cd backend && npm run build -> tsc -p tsconfig.json -exit 0 - -cd frontend && npm run build -> tsc -b && vite build -✓ 4835 modules transformed. -✓ built in 8.47s -exit 0 -``` - -The frontend suite/build retain the previously documented MSW, React ref/`act`, experimental type -stripping, and large-chunk warnings. No warning class was introduced by this wave. No harness, -workflow, persistence, SQL/CTE viewer, model-selection, or deployment file changed. The four -pre-existing modified `.superpowers/sdd/{progress,task-2-report,task-3-report,task-4-report}.md` -files remain excluded from staging. - -### Final independent-review verdict - -After the multi-client transport fix, the independent reviewer reported no Critical, Important, or -Minor findings. Its own focused verification passed 96 backend transport/lifecycle tests, 31 -frontend Resume/stream tests, both TypeScript checks, and `git diff --check`. Final assessment: -**Ready to deploy: Yes.** diff --git a/.superpowers/sdd/progress.md b/.superpowers/sdd/progress.md deleted file mode 100644 index d36bc8d2..00000000 --- a/.superpowers/sdd/progress.md +++ /dev/null @@ -1,53 +0,0 @@ -# DWH REST per-installation authentication SDD progress - -Plan: `docs/superpowers/plans/2026-08-20-dwh-rest-per-installation-auth.md` -Branch: `feat/dwh-rest-installation-auth` -Worktree: `/home/chirone/ThothII-next/.worktrees/dwh-rest-installation-auth` -Baseline: workspace docs PASS; Go unavailable on host (use containerized Go 1.26.5); default Compose pre-existing path-sensitive false positive under `/home/chirone`. - -Task 1: complete (commits 3bc84b0..1e82fd3, review clean after bounded-digest fix wave). -Task 1 plan note: the dotted-import grep was resolved by the exact module assertion in `09290a0`; `go list -m all` confirms the DWH module only. - -Task 2: complete (commits 541ef45, 971a0e6, e90a1a1; independent vet fix d2415b5; review clean after bounded-read, expiry/JSON, same-Store, and cross-Store synchronization fix waves). - -Task 3: complete (commits ebb360f, 055dcab, b1079bd; independent review clean after CLI grammar, metadata validation, and ambiguous-publication cleanup fix waves). - -Task 4: complete (commits 943f809, 419c344, 134dc19; independent review PASS after legacy multiplicity, fail-closed handler/socket, SGID 2750, O_RDONLY shared lock, OpenReadOnly, and safe socket-parent waves). Task 5 must precreate `.writer.lock` as `0640 root:dwh-auth`; add a non-owner group/cross-process integration proof when packaging permits. - -Task 5: complete (commits 87606c7, 62ec29f; independent review PASS after auth-subrequest header isolation and target-Nginx duplicate-header verification). No runtime installation or service/Nginx mutation performed. - -Task 6: complete (commits 1b18a0f, d0f7e04; independent review PASS after regex/duplicate bypass, exact-PID TCP, and bounded-cleanup hardening). Minor for final review: remove or rename the redundant legacy `negative_postgrest_bypass` fixture and align the historical fixture-count prose if useful. No active Nginx/runtime mutation performed. - -Task 7: complete (commits 7b9b8b3, 707c13d, f616aab, 7b86ea9, 7fe5316; Terra review PASS). Documentation and rollout-contract alignment completed; no runtime mutation performed. - -Task 8: complete at frozen SHA `6499d24892b4383ac492579303e766cfb51fe44e` (fix commits `09290a0`, `6499d24`; Terra review PASS). Focused, portability, scanner, DWH Go, and two full tools/tht matrix runs PASS; evidence recorded at `.artifacts/dwh-auth/source-verification.md`. Broad coupling remains `BASELINE_RED` debt; immutable paths remain unchanged. - -Task 9: PASS at frozen SHA `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. Built and installed the exact local candidate, enabled and started `dwh-auth`, imported the protected legacy credential under public ID `legacy-shared`, and created `psd-mac-primary` with public key ID `oNPdOfoH7ypLtVb1`. Registry check, AF_UNIX-only listener, v1/legacy `204`, random/missing `401`, bounded journal scan, installed-file hashes, and `nginx -t` all PASS. Protected report: `/root/dwh-auth-provision/gate9-20260821T054514Z.report.md`, SHA-256 `65ce1e0d8be5f74355eca2b1dca901da16f2864f68eafb7dede9d23ef36b82d5`. Nginx was not changed or reloaded; the legacy key remains active; the old stack was not changed or stopped. Terra final review: PASS with no Critical or Important findings. - -Task 10: NOT STARTED and requires a second explicit authorization. Public Nginx cutover, Mac-key delivery/configuration, and legacy revocation have not occurred. Activity 1 remains `IN_DISCUSSION`; external deployment remains `SURVEY_NO_GO`. - -Final clarification (bookkeeping): initial authorization at `6499d24` stopped before installation because the protected legacy file was missing and a journal-scan finding remained. A secret-safe legacy file was prepared without emit/hash; Nginx metadata remained unchanged and `nginx -t` PASS. Fix commits `6fb4886`, `dee0f9c`, `0c4ff37` received Terra PASS, followed by a detached complete re-freeze PASS at full `0c4ff3750d3ecd3fc514e50e511cf7475fbe0446`. The owner then explicitly authorized Gate 9 at that exact SHA; Gate 9 completed as recorded above. Task 10 remains a separate gate. - -## Project A authentication runtime projection - -Plan: `docs/superpowers/plans/2026-08-21-project-a-server-auth-runtime-projection.md` -Plan commit: `64f46c7019e11a74dae35a7cdb447cd881e17061` -Implementation baseline: `64f46c7019e11a74dae35a7cdb447cd881e17061` -Runtime constraint: source, synthetic tests, and documentation only; Project A, `/srv`, Nginx, -the legacy stack, and shared services remain untouched. - -Task 1: complete (commits `8a8f2c2`, `f9e2950`, `de86760`; independent Terra review PASS after descriptor-relative rewrite, full-history validation, crash recovery, destructive replacement guards, deterministic failure seams, and interrupted-retention recovery). -Task 2: complete (commits `05f8615`, `da2f4a6`, `1e2c4e6`; independent review PASS after exact GID enforcement, bounded descriptor-bound namespace enumeration, strict trailing-slash parity, OIDC coverage, and complete one-retry `CURRENT` publication linearization). -Task 3: complete (commit `903c0b4`; independent Terra review PASS after retained-FD outer locking, cancellable runtime/canonical waits, public transaction-context propagation, deterministic swap/metadata/creator-race tests, and fail-closed pre/post-commit error handling). -Task 4: complete (commit `3d9a9f0`; independent Terra review PASS after moving the Linux/root restore gate before secret-bearing checkpoint creation). Exact focused Go, race, vet, Node 24 focused/full, TypeScript, projected Compose, secret-policy, Windows backup compile, and full serialized tools/tht gates PASS. Historical canonical/unified Compose failures were reproduced as baseline-only documentation/path coupling failures and were not weakened. -Task 5: complete (commit `ef7ae70`; independent Terra review PASS after read-only Vitest gate repair, -remote-Docker/context hardening, and adversarial canonical-mount/`sudo printenv` verifier fixes). -All 14 cross-layer acceptance cases, documentation verifiers, shell syntax, full Go/race/vet, -backend Node 24 Vitest/typecheck, projected Compose, and secret-policy gates PASS. The three known -default/canonical/unified Compose policy failures were reproduced at `a21e2c1` and remain -unmodified baseline debt. Project A has not been started; applying the descriptor or any runtime -root under `/srv/thothii` still requires a new explicit authorization. -Final Project A source review: PASS for `a21e2c1..ef7ae70`; independent Terra review found no -remaining Critical or Important issue after validating restore admission/order, backend path and -identity controls, transaction cancellation, lifecycle gating, portability, dependency scope, and -redaction. Pre-live stop boundary remains in force. diff --git a/.superpowers/sdd/task-2-report.md b/.superpowers/sdd/task-2-report.md deleted file mode 100644 index 8de7fa04..00000000 --- a/.superpowers/sdd/task-2-report.md +++ /dev/null @@ -1,325 +0,0 @@ -# Task 2 report — protected atomic registry - -## Scope and commit - -- Commit: `541ef45 feat: add protected DWH credential registry` -- Committed files only: - - `tools/dwh-auth/internal/securefile/securefile_linux.go` - - `tools/dwh-auth/internal/securefile/securefile_linux_test.go` - - `tools/dwh-auth/internal/registry/store.go` - - `tools/dwh-auth/internal/registry/store_test.go` -- No server, Nginx, systemd, Docker stack, real registry, secrets, or legacy ThothII files were - read or changed. Tests use `t.TempDir` and synthetic record digests only. - -## TDD evidence - -All Go commands ran in the required official `golang:1.26.5` container with only this linked -worktree bind-mounted at `/work`. The container image reports `go version go1.26.5 linux/amd64`. - -### RED - -Before either Task 2 production file existed, the focused command was run inside the container: - -```text -go test ./internal/securefile ./internal/registry -count=1 -``` - -It failed non-zero for the expected absent implementation symbols, including `undefined: OpenDir`, -`undefined: ReadSecret`, `undefined: Open`, `undefined: State`, `undefined: PublicRecord`, and -`undefined: Store`. - -### GREEN - -After the minimal implementation and formatting: - -```text -go test ./internal/securefile ./internal/registry -count=1 -``` - -Result: - -```text -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry -``` - -### Race verification - -The required race command completed successfully: - -```text -go test -race ./internal/securefile ./internal/registry -count=1 -``` - -Result: - -```text -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 1.027s -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 1.179s -``` - -Additional scoped verification: - -```text -go vet ./internal/securefile ./internal/registry -go test ./... -count=1 -git diff --cached --check -``` - -The Task 2 vet command completed with no findings; all four DWH-auth packages passed the full -module test run; the staged-diff check completed with no output. - -## Delivered behavior - -- `securefile` is Linux-only and traverses absolute paths through descriptor-anchored - `syscall.Open`/`Openat` calls with `O_NOFOLLOW|O_CLOEXEC`; protected roots, child directories, - records, and secret files are regular/directories only and are checked against `Lstat` after - `Fstat`. -- Protected reads reject special, group-writable, or world-writable modes, cap record reads at - 4096 bytes, read at most one extra byte, and reject file-size changes or short/partial reads. - Secret ingress additionally requires exact `0600`. -- Secret output uses `O_CREAT|O_EXCL|O_NOFOLLOW`, exact `0600`, and an absolute protected parent. -- `registry.Open` creates protected `active` and `revoked` subdirectories under an existing safe - root. Record enumeration rejects unexpected entries, unsafe files, symlinks, oversized files, - bad filenames, malformed JSON, unknown JSON fields, duplicate JSON fields, and trailing JSON. -- `Add` validates Task 1 records, writes canonical JSON plus one newline through an exclusive - temporary file, sets final mode `0640`, syncs the file, renames under a protected per-root writer - lock, then syncs the directory. -- `Revoke` writes and syncs a valid revoked record before unlinking and syncing the active record. - `Find` checks revoked first; `List` resolves an active/revoked overlap to the revoked public - record. `FindLegacy` scans fail-closed and permits only the reserved legacy record state. -- `PublicRecord` deliberately omits `secret_sha256`; the redaction is regression-tested. - -## Security-test coverage - -- protected normal files and canonical record publication; -- symlinked roots, registry directories, records, and secret input; -- unsafe root/directory/record/secret modes; -- bounded/oversized record input; -- unknown, duplicate, trailing, and partial JSON; -- filename mismatch and multiple legacy-record integrity failures; -- revoked-state precedence when both active and revoked files exist; -- concurrent adds and concurrent reads during revocation, including the race detector. - -## Self-review - -Reviewed all syscall, path, mode, and error paths after the final race run: - -- Directory traversal never follows a supplied component; later operations use retained directory - descriptors, not re-opened untrusted prefixes. -- `Fstat` validates the opened object and `Lstat` must identify the same inode/device; the direct - child name grammar refuses separators, dot components, and NUL. -- File validation occurs before and after reads; mode/type/size checks fail closed. Directory - listing obtains a fresh `openat(dirfd, ".")` descriptor so scans do not share a mutable directory - offset. -- Writer serialization protects the check-then-rename no-replace sequence. Failed temporary - cleanup leaves an unexpected entry that later scans reject rather than silently accepting it. -- State-specific validation rejects revocation metadata in active records and requires it in - revoked records. Revoked files are consulted before active files so interruption after revoked - publication cannot reactivate a credential. -- All functionality uses only Go standard-library packages and Linux `syscall`; no CGO, SQLite, - or third-party module was added. - -## Concerns - -- The optional whole-module `go vet ./...` reports a pre-existing Task 1 test warning at - `internal/credential/credential_test.go:86` (`append` with no variadic values). The identical - line is present in approved HEAD `1e82fd3`, outside this task’s authorized files. Focused Task 2 - vet passes, and all module tests pass. -- The official image's login shell resets `PATH` and hides `/usr/local/go/bin`; all evidence uses - direct `go`/`gofmt` container entrypoints, which preserves the image’s Go 1.26.5 environment. -- The generic `apply_patch` helper intermittently failed before file access with a sandbox network - namespace error. Exact scoped corrections were applied through the shared worktree workflow; - this did not affect the final staged file set or verification evidence. - -## Review remediation — 2026-08-21 - -### Scope and fix commit - -- Review-fix commit: `971a0e6 fix: harden DWH credential registry reads`. -- Committed files only: - - `tools/dwh-auth/internal/registry/store.go` - - `tools/dwh-auth/internal/registry/store_test.go` -- The separate Task 1 vet correction is the independent preceding commit `d2415b5`; it is not - included in this Task 2 fix commit. No filesystem primitive, server, Nginx, service, registry, - secret, Docker stack, or legacy ThothII file was changed. - -### Strict TDD evidence - -All commands again used the official `golang:1.26.5` image with only this linked worktree mounted -at `/work`. - -#### RED - -The first focused command was run after the new regression tests and before production changes: - -```text -go test ./internal/securefile ./internal/registry -count=1 -``` - -It failed as intended. The three case-variant aliases (`SECRET_SHA256`, `Secret_SHA256`, and -`Schema_Version`) were accepted; past expiry returned active records from both `Find` and -`FindLegacy`; a revocation snapshot let readers return active data before publication; a temporary -file let `List`, `Check`, and `FindLegacy` observe false integrity failures; and the original -concurrent-read regression observed `ErrNotFound` during revocation. - -The deterministic exact-expiry test was then added before the clock implementation. Its focused -run failed as intended with: - -```text -internal/registry/store_test.go:572:10: store.now undefined -``` - -#### GREEN and verification - -After the minimum implementation and `gofmt`: - -```text -go test ./internal/securefile ./internal/registry -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 0.014s -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 0.684s - -go test -race ./internal/securefile ./internal/registry -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 1.022s -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 1.711s - -go vet ./internal/securefile ./internal/registry -``` - -The focused vet output was empty (success). Additional final checks passed: - -```text -go test ./... -count=1 -ok internal/credential -ok internal/record -ok internal/registry -ok internal/securefile - -go vet ./... -go test -race ./internal/registry -count=10 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 8.127s -git diff --cached --check -``` - -### Remediated security invariants - -- `Find` and `FindLegacy` now deny an active record when `ExpiresAt <= now.UTC()`, returning the - existing non-disclosing `ErrNotFound`. The unexported per-Store `now` function is the minimal - deterministic clock seam; past, exact-equality, and future cases are covered for v1 and legacy - records. A revoked record is still consulted before expiry and therefore remains authoritative. -- One per-Store `sync.RWMutex` creates an in-process consistent snapshot. `Add` and `Revoke` hold - it exclusively for their full writer-lock lifetime, including temporary-file publication and - revoked-then-active removal. `Find`, `FindLegacy`, `List`, and `Check` hold a shared lock; their - bodies delegate only to unlocked helpers, preventing nested-lock deadlocks. `Close` also takes - the exclusive lock before closing descriptors. -- Deterministic regression tests hold the writer path at the revocation publication/unlink and - temporary-file stages. They prove public readers wait, then see either the final revoked state or - a clean directory, eliminating the `Names`-to-load/unlink and temporary-entry false failures - within the Store contract. -- Before struct decoding, the outer record JSON object now requires exactly spelled keys from the - schema allowlist and rejects duplicate literal keys. `Decoder.DisallowUnknownFields`, recursive - duplicate detection, trailing-value rejection, record validation, filename matching, no-follow - reads, modes, and durability ordering remain intact. - -### Self-review and concerns - -- Reviewed the new lock boundaries, error returns, revoked-first ordering, clock fallback, - JSON-token consumption, and every unchanged `securefile` syscall/path/mode boundary. The change - adds only standard-library `sync`; it does not relax existing fail-closed behavior. -- The synchronized snapshot is intentionally per `Store`, matching the requested in-process - contract. The existing protected advisory lock continues to serialize writers across Store - instances/processes; no cross-process reader snapshot is claimed by this fix. -- The historical whole-module vet concern in the original Task 2 report is now resolved by the - independent Task 1 commit `d2415b5`; complete module vet passes in the final evidence above. - -## Cross-Store snapshot remediation — 2026-08-21 - -### Scope and TDD evidence - -This third Task 2 fix wave changes only the protected lock primitive and registry snapshot code: - -- `tools/dwh-auth/internal/securefile/securefile_linux.go` -- `tools/dwh-auth/internal/securefile/securefile_linux_test.go` -- `tools/dwh-auth/internal/registry/store.go` -- `tools/dwh-auth/internal/registry/store_test.go` - -All commands used the official `golang:1.26.5` image with only this linked worktree mounted at -`/work`. - -The test-only red patch initially tried to inspect the unexported `securefile.Dir.fd` through the -registry package and therefore did not compile. That assertion was removed without production -changes: the registry tests still create writer Store A and reader Store B through two independent -`Open(root)` calls, while the securefile test proves separate descriptors directly in its own -package. The subsequent behavioral RED run, before the production change, was: - -```text -go test ./internal/securefile ./internal/registry -count=1 -FAIL TestLockSharedAllowsReadersAndBlocksExclusiveWriter: Dir lacks shared advisory locking -FAIL TestCrossStoreReadersWaitAcrossRevokePublicationAndUnlink: - Find, List, Check, and FindLegacy completed during Store A's revocation snapshot -FAIL TestCrossStoreScanReadersWaitForWriterTemporaryFile: - Store B's List, Check, and FindLegacy observed `.tmp-regression` -``` - -### Delivered synchronization contract - -- `securefile.Dir.LockShared` now acquires `LOCK_SH` on the same protected, no-follow, exact-0600 - root lock file used by `Lock`, which continues to acquire `LOCK_EX`. The lock file is still - opened/created, mode-validated, inode-checked, and closed through the existing Linux syscall - path. -- Every public snapshot reader (`Find`, `FindLegacy`, `List`, and `Check`) takes its Store - `RLock`, then a shared advisory lock on root `.writer.lock`, and retains both through the whole - revoked/active lookup or directory scan/load. `Add` and `Revoke` retain Store `Lock`, then the - same root lock under `LOCK_EX`, over their full operation. -- The lock order is universally Store mutex then root advisory lock. Public methods delegate only - to unlocked helpers, so neither reader nor writer paths recursively acquire the Store mutex. - `Close` retains its exclusive Store mutex, preventing descriptor closure from racing any locked - reader or writer. -- Revoked-first precedence, expiry denial, exact JSON validation, no-follow checks, record modes, - temporary-file durability, and all previous behavior remain unchanged. - -### GREEN and repeated verification - -```text -go test ./internal/securefile ./internal/registry -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 0.019s -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 0.711s - -go test -race ./internal/securefile ./internal/registry -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 1.032s -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 1.748s - -go vet ./internal/securefile ./internal/registry -go test ./... -count=1 -ok internal/credential -ok internal/record -ok internal/registry -ok internal/securefile -go vet ./... - -go test -race ./internal/registry \ - -run 'TestCrossStoreReadersWaitAcrossRevokePublicationAndUnlink|TestCrossStoreScanReadersWaitForWriterTemporaryFile' -count=20 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/registry 9.880s - -go test -race ./internal/securefile \ - -run TestLockSharedAllowsReadersAndBlocksExclusiveWriter -count=20 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/securefile 1.063s - -git diff --check -``` - -Both vet commands and the whitespace check produced no output. The securefile regression opens -three protected directory descriptors, proves they are distinct, permits two independent shared -holders, proves a third descriptor cannot take `LOCK_EX|LOCK_NB`, then proves exclusive acquisition -succeeds after shared release. The registry regressions deterministically block Store B readers -while Store A holds the exclusive root lock and verify only final revoked/clean states afterward. - -### Self-review and concerns - -- Reviewed lock creation/reopen races, no-follow flags, exact lock-file mode validation, lock - release, descriptor lifetime, lock ordering, error wrapping, and the unlocked-helper call graph. - No public reader invokes another public reader or writer while holding a Store lock. -- Advisory synchronization necessarily covers cooperating registry Store instances/processes; - arbitrary external filesystem mutation remains fail-closed through the existing integrity - checks rather than being silently accepted. -- No known concerns within the registry's cooperating-process contract. diff --git a/.superpowers/sdd/task-3-report.md b/.superpowers/sdd/task-3-report.md deleted file mode 100644 index 52d8a10f..00000000 --- a/.superpowers/sdd/task-3-report.md +++ /dev/null @@ -1,129 +0,0 @@ -# Task 3 report — secret-safe dwh-auth administrative CLI - -## Scope - -- Added `tools/dwh-auth/internal/command/command.go`, its command tests, and - `tools/dwh-auth/cmd/dwh-auth/main.go`. -- The CLI accepts only the frozen Task 3 grammar: key create/import/list/status/revoke, - registry check, and the reserved serve invocation. -- Existing Task 1–2 APIs are consumed without modifying their files. -- No server, Nginx, systemd, Compose, portable `tht`, real registry, real secret, or legacy - stack was accessed or changed. - -## TDD evidence - -Tests were written before `Run` existed. In the official `golang:1.26.5` container, mounted -against only the dedicated worktree, the focused RED run was: - -```text -go test ./internal/command -count=1 -internal/command/command_test.go:214:10: undefined: Run -FAIL -``` - -After implementation and formatting: - -```text -go test ./internal/command -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/command - -go test -race ./internal/command -count=1 -ok github.com/aritmolab/thothii/tools/dwh-auth/internal/command - -go test ./... -count=1 -ok internal/command, internal/credential, internal/record, internal/registry, internal/securefile - -go test -race ./... -count=1 -ok internal/command, internal/credential, internal/record, internal/registry, internal/securefile - -go vet ./... -``` - -## Contract coverage - -- Create generates the Task 1 canonical credential, writes it once through the protected - exclusive `0600` output primitive, syncs/closes it before registry publication, and emits - only `created key_id=... installation_id=... output=...`. -- Existing output is never overwritten. Publication failure attempts compensating removal; - cleanup uncertainty returns exit 4 and reports only the output path. -- Legacy import requires `--legacy-raw`, the reserved `legacy-shared` installation ID, and an - absolute exact-`0600` source. It verifies the opaque value, never changes its source, and - stores only its digest. -- List/status expose `PublicRecord` data only; JSON is written as pristine JSON with no digest. - Revoke requires a non-empty reason and reports only its public key ID. -- Relative paths, malformed/unknown flags, duplicate options, invalid IDs/metadata/expiry, - and missing required values return exit 2. Missing status/revoke keys return exit 3. - Registry/filesystem/integrity failures return exit 4. -- Diagnostics are fixed redacted strings. Tests use a sentinel secret and assert it is absent - from stdout/stderr, list/status/check JSON, import output, and unsafe/integrity failures. - -## Secret-redaction evidence - -The command never prints credential contents or digests. It does not use environment fallback, -interactive stdin, or `flag` diagnostics that echo argument values. The sentinel appears only -in synthetic temporary test input and an integrity-fixture file; all command output assertions -confirm it is absent. The registry’s existing `PublicRecord` contract omits `secret_sha256`. - -## Concerns - -- `serve` is grammar-reserved and returns a redacted exit-4 unavailable response; Task 4 owns - the Unix-socket service implementation and will wire this dispatch. -- The earlier concern about UTF-8 metadata hardening is superseded by `055dcab`: metadata now - rejects invalid UTF-8 and Unicode controls before generation/output. The nil-safe cleanup note - remains non-blocking and outside this review wave. - -## Review-fix wave - -Review findings were addressed in separate commit `055dcab`. Regression tests were added first. The focused RED run in the official Go 1.26.5 container failed on intentionally absent seams: - -```text -undefined: nowUTC -undefined: addRecord -undefined: closeStore -FAIL github.com/aritmolab/thothii/tools/dwh-auth/internal/command -``` - -The fix rejects embedded canonical v1 credentials in description/revocation reason without echoing metadata, validates UTF-8/Unicode controls and expiry against one captured UTC creation time before generation/output, reserves exactly `serve --registry-root ABS --socket ABS`, and makes publication cleanup depend on a definitive registry lookup. Output is retained after publication or close ambiguity, with path-only recovery guidance. - -Review-fix verification in Go 1.26.5: - -```text -go test ./internal/command -count=1 PASS -go test -race ./internal/command -count=1 PASS -go test ./... -count=1 PASS -go test -race ./... -count=1 PASS -go vet ./... PASS -git diff --check PASS -``` - -New tests cover synthetic canonical credentials embedded with prefix/suffix, invalid UTF-8, C1 Unicode controls, past/equal/future expiry, exact serve ordering, deterministic pre-/post-publication and close-failure seams, and sentinel absence from stdout/stderr/list/status JSON. - -## Cleanup snapshot review-fix wave - -The second re-review added two regression tests before implementation. The RED run in the -official Go 1.26.5 container showed the old `Find` proof incorrectly treated both cases as -cleanup-safe: - -```text -FAIL TestCreateRetainsOutputWhenSnapshotFindsUnrelatedIntegrityFailure - corrupt snapshot result = (4, "", "integrity failure\n") -FAIL TestCreateRetainsOutputWhenFailedPublicationRecordIsExpired - expired publication result = (4, "", "integrity failure\n") -``` - -Commit `b1079bd fix: retain DWH key output on ambiguous publication` replaces the `Find` proof -with a complete `Store.List()` snapshot. It removes generated output only when the snapshot -succeeds, the generated key ID is absent, and `Store.Close()` succeeds. Any unrelated integrity -error, active/revoked/expired record, or close error retains the output and emits only path-based -recovery guidance. The clean pre-publication failure path still removes the output. - -Final cleanup-wave verification in Go 1.26.5: - -```text -go test ./internal/command -count=1 PASS -go test -race ./internal/command -count=1 PASS -go test ./... -count=1 PASS -go test -race ./... -count=1 PASS -go vet ./... PASS -git diff --check PASS -``` diff --git a/.superpowers/sdd/task-4-report.md b/.superpowers/sdd/task-4-report.md deleted file mode 100644 index a7f811b0..00000000 --- a/.superpowers/sdd/task-4-report.md +++ /dev/null @@ -1,60 +0,0 @@ -# Task 4 — Unix-socket DWH verification report - -## Scope - -Implemented the standalone Linux verifier at `tools/dwh-auth/internal/service` and wired the exact command: - -```text -dwh-auth serve --registry-root ABSOLUTE_CANONICAL --socket ABSOLUTE_CANONICAL -``` - -The service accepts only `GET /verify`. It returns empty `204` responses with `X-DWH-Key-ID` for verified v1 or reserved legacy credentials; credential failures are generic empty `401` responses, and registry/integrity faults are empty `503` responses. Other paths/methods return empty `404`/`405`. - -## Security decisions - -- Exactly one `X-API-Key` header, maximum 128 bytes. -- Strict `thtdwh_v1.` parsing precedes legacy lookup; non-v1 values alone may use the reserved legacy record. -- Registry integrity is checked before every verification request, so unrelated malformed/unsafe records fail closed with `503`. -- Logs emit only timestamp, decision code, and (when safely parsed or verified) public key ID; test sentinels prove no key, digest, description, or query value is emitted. -- `serve` validates canonical absolute paths, performs startup `Store.Check`, and reports service startup errors as non-secret `integrity failure`. -- Socket collisions that are regular files, directories, symlinks, live sockets, or foreign-owned stale sockets are refused. Only an owned stale Unix socket after `ECONNREFUSED` can be reclaimed. -- Published sockets are mode `0660`; cancellation calls graceful shutdown and removes only a revalidated same-device/same-inode owned socket. A test seam proves a changed path is retained rather than unlinked. - -## Required supporting security fix - -Commit `943f809` (`fix: reject duplicate legacy DWH records`) tightens the Task 2 registry contract: a synthetically valid active plus revoked legacy pair is now an integrity failure. It is intentionally separate from the Task 4 commit. - -## TDD evidence - -RED was observed for the missing handler, listener/configuration API, CLI wiring, unrelated-registry corruption, active+revoked legacy state, and cleanup replacement race. Each increment was then implemented minimally and rerun GREEN. - -## Verification - -All commands were executed in official `golang:1.26.5`, with only this worktree mounted: - -```text -gofmt -w cmd internal/command internal/service -go test ./internal/service ./internal/command -count=1 -go test ./... -count=1 -go test -race ./... -count=1 -go vet ./... -git diff --check -``` - -All passed. A dependency scan also found no third-party Go dependencies. - -## Scope boundary - -No Nginx, systemd, real Unix socket, real registry, credential, legacy stack, or external service was changed. All test data was synthetic and temporary. - -## Follow-up hardening: runtime read-only registry and socket parent - -The Task 5 storage contract uses `root:dwh-auth` SGID directories (`2750`) and a service account with read-only group access. The original registry reader path was incompatible because shared locks were opened `O_RDWR` and lazily created as `0600`; secure-directory validation also rejected SGID. - -The runtime path now uses `registry.OpenReadOnly`: it opens only preprovisioned root, `active`, `revoked`, and `.writer.lock` paths, and rejects `Add`/`Revoke`. The administrative `Open` path bootstraps the lock through the exclusive writer path. Shared lock acquisition opens the existing `root:dwh-auth 0640` lock `O_RDONLY` with `LOCK_SH`; writer acquisition remains `O_RDWR` with `LOCK_EX`, preserving cross-process snapshot exclusion. Secure directories allow SGID but still reject setuid, sticky, group-write, and world-write bits. - -Task 5 must create `.writer.lock` as `0640 root:dwh-auth` alongside the `2750 root:dwh-auth` registry directories before the service starts. - -The socket parent must be a canonical non-symlink directory owned by the service EUID and not group/world writable. This removes the bind-to-chmod and path-replacement exposure from other principals. The remaining POSIX path race is bounded to trusted processes sharing the service EUID inside that non-contendible parent. - -Additional verification (official `golang:1.26.5`, worktree only): focused securefile/registry/service/command tests, full tests, full race tests, vet, plus ten race repetitions each for cross-store snapshot readers, `OpenReadOnly`, and listener tests: all PASS. diff --git a/.superpowers/sdd/task-5-report.md b/.superpowers/sdd/task-5-report.md deleted file mode 100644 index cebde76c..00000000 --- a/.superpowers/sdd/task-5-report.md +++ /dev/null @@ -1,71 +0,0 @@ -# Task 5 report — backend principal enforcement - -## RED - -Added backend route/auth tests before implementation. The initial focused run failed in -seven new assertions: `getPrincipal` did not exist, upstream requests still required the -legacy identity header, foreign session/SSE routes were not hidden, admin scope was not -enforced, new sessions had no trusted principal binding, and settings were global. - -## GREEN - -- Focused backend suite: `66 passed` across auth, sessions, SSE, and settings tests. -- Complete backend Vitest suite: `209 passed` across `22` files. -- `npx tsc --noEmit -p .`, `npm run build`, `git diff --check`, and changed Python - source Ruff all exit successfully. -- Harness targeted repository/local/migration tests and Python bytecode compilation exit - successfully. The new `tht session preferences get|set` commands are registered and - expose the expected Typer help. A direct local CLI preference smoke was not run because - the checked-in local workspace requires unavailable `THT_DB_HOST` configuration. - -## Route and child-process coverage - -- `GET /me` returns the request `PrincipalContext`; upstream accepts only the portal's - normalized `X-Thoth-*` identity tuple, with the legacy header ignored. Local mode uses - the same stable `THT_HOME`/`~/.thothii/identity.json` UUID contract as the harness. -- All session operations are principal-scoped: list (`mine` and admin-only `all`), show, - create, resume, close, delete, rename, group, archive, unarchive, documents, reviewer - response, steer, SQL preview/export, and SSE. Missing and foreign sessions are 404; - absent upstream identity is 401. SSE is authorized before response headers or hub - subscription, so a rejected request cannot attach to a live stream. -- New/resumed Pi runtimes and every route-spawned `tht` process receive - `THT_PRINCIPAL_ISSUER`, `THT_PRINCIPAL_SUBJECT`, optional display name, and admin flag. - The readiness `tht` child is also principal-bound. -- Settings use asynchronous repository-backed `tht session preferences get|set` in the - production runner, which isolates preferences by principal. The legacy settings file is - retained only as an injected-runner compatibility fallback for existing isolated tests. -- Repository/settings authorization failures map to 503 before model startup. SQL execution - errors remain 500 after authorization, preserving the prior API distinction. - -## Self-review and concerns - -- Confirmed the Task 4 portal emits lowercase `true`/`false` for the admin header; the - parser accepts that exact normalized form plus the repository's existing `1`/`0` - compatibility form, and rejects all other values. -- The harness principal resolver is the ownership authority; the backend never accepts an - owner supplied in request bodies. Its route guards use a repository-scoped `session show` - before every session resource operation. -- Existing dependency-injected route fakes without `sessionShow` retain a narrow test seam; - production `ThtRunner` always has that method, so deployed requests cannot bypass the - repository authorization check. - -## Review follow-up - -### RED - -Focused regressions initially failed exactly at the three review findings: stale ambient -display names survived into both `tht` and Pi child environments; mutation/document runner -methods dropped the selected workspace; and `expandLocalHome` did not exist. - -### GREEN - -- Child environments now remove all four `THT_PRINCIPAL_*` keys from their cloned base - environment before applying the exact request principal. Regression tests prove an absent - display name does not inherit a stale ambient value in either child path. -- `setName`, `setGroup`, `archive`, `unarchive`, and `documents` now take and retain an - optional workspace. The rename route regression proves `session show` authorization and - the mutation use the same non-default workspace. -- Local principal paths expand `~`/`~/...`; existing local home and identity file modes are - repaired to POSIX `0700`/`0600` when applicable, with Windows left unchanged. -- Focused suite: `74 passed`; full backend suite: `213 passed` across `22` files, followed by - TypeScript typecheck, production build, and diff check. diff --git a/.superpowers/sdd/task-6-report.md b/.superpowers/sdd/task-6-report.md deleted file mode 100644 index 38267610..00000000 --- a/.superpowers/sdd/task-6-report.md +++ /dev/null @@ -1,298 +0,0 @@ -# Task 6 — Frontend identity and administrator UX report - -## RED - -- Added API tests for the `/me` principal call and `mine`/`all` session-list scopes. -- Added component tests for regular-user scope, admin scope switching, owner labels, - administrator banner, foreign-owner delete confirmation, and foreign-owner archive - confirmation. -- Initial focused run: 7 expected failures (missing `getMe`, missing scope query, - missing owner label/admin controls, and missing foreign-action confirmation). -- The archive-confirmation regression was also run separately before its implementation - and failed because `window.confirm` was not called. - -## GREEN - -- `npx vitest run src/api/sessions.test.ts src/shell/NavSessions.test.tsx src/shell/AppShell.session-mgmt.test.tsx` - — passed (47 tests before the archive follow-up; the focused archive regression then passed). -- `npm test` — passed: 44 files / 305 tests. -- `npx tsc -b` — passed. -- `npm run build` — passed. -- `git diff --check` — passed. -- `npm run e2e` reached Playwright but could not run: the environment has no Chromium - executable at Playwright's configured cache path. No application test failure was reported. - -## Files changed - -- `frontend/src/api/types.ts`: typed principal and session scope contracts. -- `frontend/src/api/sessions.ts`: typed `/me` API call; scoped listing defaults to `mine`. -- `frontend/src/shell/AppShell.tsx`: identity query, admin-only session scope selector and - banner, owner-aware destructive action confirmations. -- `frontend/src/shell/NavSessions.tsx`: owner labels in the all-sessions view. -- `frontend/src/api/sessions.test.ts`, `frontend/src/shell/NavSessions.test.tsx`, and - `frontend/src/shell/AppShell.session-mgmt.test.tsx`: contract and UX coverage. - -## Self-review - -- Regular users remain fail-closed on `mine`; no administrator control renders without - `principal.isAdmin`. -- The all-sessions view includes owner labels (including `Unknown` for legacy records). -- Delete confirmation preserves the pre-existing select-all behavior and adds confirmation - for foreign/unknown owners. Foreign archive now also requires an explicit browser - confirmation; existing Stop & save already has its confirmation dialog. -- A read-only review found no critical, important, or minor issues. The archive guard was - added after that review in response to the requirement to cover every destructive rail - action, and has its own RED/GREEN regression plus the final full verification above. - -## Concerns - -- E2E remains environment-blocked until the Playwright Chromium browser is installed. -- Existing Vitest runs emit pre-existing MSW unmatched-request and dialog-ref warnings; all - assertions pass and this task does not modify those shared test/UI primitives. - -## Review remediation - -- A post-commit review correctly identified that matching `displayName` must never establish - ownership. The predicate now skips confirmation only when `session.author` exactly equals - `principal.subject`; all display-name matches and missing authors are conservative - cross-owner actions. -- Added RED/GREEN regressions where two principals share display name `Alice` but have distinct - subjects: both delete (with another session present, so select-all cannot mask the guard) and - archive require confirmation. -- Added `aria-pressed` to the My sessions / All sessions controls and asserts their selected state - before and after switching. -- Remediation verification: focused regressions passed; full frontend Vitest (44 files / 305 - tests), `npx tsc -b`, `npm run build`, and `git diff --check` all passed. - - ---- - -# DWH authentication Task 6 — Nginx and CI gate report - -## Scope - -Added only the two DWH-auth Nginx gates and the `dwh-auth-linux` deployment workflow job: - -- `scripts/test-dwh-auth-nginx-contract.sh` -- `scripts/test-dwh-auth-nginx-integration.sh` -- `.github/workflows/deployment.yml` - -This report deliberately remains unstaged. The pre-existing frontend Task 6 report above is -preserved rather than overwritten. - -## TDD RED - -The structural gate was written before any Task 5 template change. Those templates already met -the approved contract, so the behavioral RED was obtained by copying them into one exact temporary -root and removing only the effective `/dwh/` `auth_request` directive. The new checker failed as -required, with no credential material in output: - -```text -case=source_contract status=FAIL -``` - -The runtime gate was also first invoked before its file existed: - -```text -bash: scripts/test-dwh-auth-nginx-integration.sh: No such file or directory -``` - -The CI-job RED check found no `dwh-auth-linux` job in `deployment.yml`. No production template was -modified: the tests prove the existing Task 5 template contract instead of weakening it. - -## GREEN - -Shell syntax and workflow YAML were checked with: - -```text -bash -n scripts/test-dwh-auth-nginx-contract.sh scripts/test-dwh-auth-nginx-integration.sh -python3 -c import-yaml-and-safe-load -``` - -The structural gate passed its source contract plus these 13 real copied-and-mutated Nginx fixtures: - -```text -missing_auth_request -missing_proxy_method -missing_proxy_body -missing_proxy_header_isolation -missing_content_length_clear -missing_verifier_key_forward -missing_upstream_key_clear -missing_failure_mapping -public_verifier -tcp_authenticator -postgrest_bypass -failure_mapped_to_success -full_secret_rate_key -``` - -Each test mutates an effective, not comment-only, directive and requires the checker to reject it. -The source test and all 13 fixture tests emitted `case=... status=PASS`, followed by -`case=summary status=PASS`. - -The isolated Nginx 1.24 smoke passed these sanitized cases: - -```text -nginx_1_24 -build_dwh_auth -registry_setup -verifier_start -synthetic_upstreams -composite_nginx_config -nginx_start -auth_socket_unix_only -verifier_not_public -valid_v1 -valid_legacy -invalid_key -revoked_key -expired_key -duplicate_v1 -duplicate_legacy -stopped_verifier -header_and_path_isolation -summary -``` - -It builds with the pinned official Go 1.26.5 image when the host Go binary is absent, creates only -synthetic v1, legacy, revoked, and expired credentials in a `0700` `/tmp` root, runs both Nginx and -the verifier on explicit temporary Unix sockets, and uses a loopback-only marker backend. Its output -is strictly `case` and `status`; keys, values, and digests remain only in the exact temporary root -and are removed by the trap. - -`nginx -t` passed against the complete generated configuration. The marker proves that successful -`/dwh/?keep=exact&second=two` reaches the upstream unchanged, while neither the client API key nor -client or verifier `X-DWH-Key-ID` reaches it. A Unix forwarding probe proves that the verifier sees -only `X-API-Key`, with Cookie, Authorization, and spoofed audit ID absent. Duplicate v1 and ordinary -legacy headers return 401 through Nginx; a stopped verifier returns 503. - -The final local equivalent of the four CI commands passed: - -```text -Docker Go 1.26.5: go test -race ./... -count=1 and go vet ./... -bash scripts/test-dwh-auth-build-contract.sh -bash scripts/test-dwh-auth-nginx-contract.sh -bash scripts/test-dwh-auth-nginx-integration.sh -``` - -The Go race suite passed for command, credential, record, registry, securefile, and service; -`go vet` was silent; the build contract passed; both Nginx gates reached their summaries. - -## CI contract - -The new job uses `actions/checkout` with `persist-credentials: false`, pins Go 1.26.5 with cache -keyed on `tools/dwh-auth/go.mod`, installs `nginx-light`, and runs exactly the four required commands. -Existing jobs were not altered. - -## Self-review - -- The template tests parse normalized effective directives, so commented-out declarations cannot - satisfy the gate. -- The authentication socket is configured as `http://unix:...:/verify`, is observed by `ss -xl`, - and Nginx itself listens only on a temporary Unix socket; neither test starts a public listener. -- All spawned processes are registered by PID; cleanup signals only those PIDs and deletes only the - exact `mktemp` root after a guarded path check. -- The verifier, marker, registry, Nginx prefix, PID, logs, config, and sockets all reside beneath - that root. No `/etc`, systemd, active Nginx config, stack, legacy route, or real registry/key is - read or changed. -- Task 5 templates were not modified because the structural and runtime tests passed unchanged. - -## Concern - -The sandbox `apply_patch` helper repeatedly failed with `bwrap: loopback: Failed RTM_NEWADDR: -Operation not permitted`. A narrowly scoped fallback editor was used only for the workflow and the -Nginx-version assertion. Its first workflow insertion interpreted the action-reference at signs; -the two malformed values were immediately corrected and all final YAML, exact-string, syntax, and -four-command checks were rerun. No remaining product concern is known; the integration gate requires -Nginx 1.24 and Python 3, both supplied by the specified Ubuntu CI runner. - - ---- - -# DWH authentication Task 6 — review remediation wave - -## Review findings and RED evidence - -The three review findings were reproduced against the Task 6 commit before their corresponding -hardening was accepted. - -1. The contract checker originally selected only the first matching `/dwh/` location. A real copied - fixture appended this competing location without authentication: - -```nginx -location ~ ^/dwh/ { - proxy_pass http://127.0.0.1:3001; -} -``` - - The first run reached the new check and failed as required: - -```text -case=negative_postgrest_regex_bypass status=FAIL -``` - -2. The previous process stop sent TERM and immediately used an unbounded `wait`. A synthetic Python - child ignored TERM; the RED run used one exact short-lived watchdog only to prevent a test hang and - produced: - -```text -case=cleanup_term_ignored_bounded status=FAIL -``` - -3. The TCP detector has a positive-control regression. A scratch copy of the integration script - replaced its `ss -ltnpH` detector with `return 1`; its known loopback listener was then not - detected and the run failed with: - -```text -case=tcp_listener_detector_positive status=FAIL -``` - -All RED fixtures and the scratch script used an exact temporary path and were removed. No template, -service, workflow, key, or active Nginx configuration was changed. - -## GREEN changes - -- `location_declarations` consumes normalized, comment-stripped effective lines and `check_templates` - requires exactly one each of the only approved locations: verifier, unavailable named location, and - `/dwh/`. It therefore rejects both any extra intercepting location and a duplicate. The real regex - bypass and a new real duplicate `/dwh/` bypass fixture both pass by being rejected. -- `tcp_listener_for_pid` uses `ss -ltnpH` and a PID-bound match. The integration gate starts a - loopback-only synthetic listener, proves the detector sees that exact PID, stops and deregisters it, - then proves the verifier PID has no TCP listener while its Unix socket remains present. -- `stop_registered_pid` now sends TERM, polls for exit or zombie for a bounded deadline, sends KILL - if required, polls a second bounded deadline, and only reaps a direct child after terminal state is - proved. Explicit stops deregister their PID. The cleanup loop invokes that bounded operation only - for recorded PIDs and removes only its guarded temporary root. -- The synthetic child that ignores TERM is killed by the bounded path, must no longer answer to - `kill -0`, must not remain registered, and must finish within three seconds. Final gate output is - restricted to `case` and `status` lines. - -## GREEN verification - -```text -bash -n scripts/test-dwh-auth-nginx-contract.sh scripts/test-dwh-auth-nginx-integration.sh -Docker Go 1.26.5: go test -race ./... -count=1 and go vet ./... -bash scripts/test-dwh-auth-build-contract.sh -bash scripts/test-dwh-auth-nginx-contract.sh -gate contract: source plus 15 negative fixtures PASS, then summary PASS -bash scripts/test-dwh-auth-nginx-integration.sh -gate integration: 20 named cases PASS, then summary PASS -git diff --check -``` - -The integration cases include `cleanup_term_ignored_bounded`, -`tcp_listener_detector_positive`, `auth_socket_unix_only`, all existing credential decisions, -composite Nginx syntax, and stopped-verifier 503 behavior. Go race tests passed for command, -credential, record, registry, securefile, and service; vet and both diff checks were silent. - -## Self-review and concern - -The new location parser rejects comment-only and non-exact declarations because it operates on the -same normalized effective representation used by the rest of the contract. The TCP positive control -binds only `127.0.0.1` on a kernel-selected temporary port and is stopped through the same exact-PID -path under test. The bounded cleanup avoids arbitrary process lookup or broad signaling. - -The environment still intermittently rejects `apply_patch` with the sandbox loopback error noted in -the original report; only narrowly scoped fallback edits to the two authorized scripts were used and -all final gates were rerun. No remaining review concern is known. diff --git a/.superpowers/sdd/task-7-report.md b/.superpowers/sdd/task-7-report.md deleted file mode 100644 index 7ebb7998..00000000 --- a/.superpowers/sdd/task-7-report.md +++ /dev/null @@ -1,90 +0,0 @@ -# Task 7 — report - -## RED - -- Creato `scripts/test-verify-dwh-auth-docs.sh` con fixture positiva e fixture negative per - credenziale/digest sintetici, TLS insicuro, segreto in env/argv, mode world-readable, cattura - Nginx e coupling Compose. -- Eseguito `bash scripts/test-verify-dwh-auth-docs.sh` prima del verificatore: `case=verifier_missing status=FAIL`. - -## GREEN - -- Aggiunti manuali server, client, TLS, runbook PSD, collaudo ed evidenza sanitizzata; collegati - manuali locali/server, setup PSD, guida, indice e nav MkDocs. -- Eseguiti: `bash -n scripts/verify-dwh-auth-docs.sh scripts/test-verify-dwh-auth-docs.sh`, - `bash scripts/test-verify-dwh-auth-docs.sh`, `bash scripts/verify-dwh-auth-docs.sh`, - `bash scripts/test-verify-workspace-install-docs.sh`, `bash scripts/auth-docs-smoke.sh`. -- Tutti gli output finali sono PASS; il nuovo gate esercita una fixture positiva e nove negative. - -## Self-review - -- Verificati path/owner/mode: registry 2750, lock/record 0640, socket 0660. -- Verificata separazione: chiavi solo `rest_api`; PSD server `postgres_direct`; Mac/remoti REST; - nessun lifecycle Compose per `dwh-auth`. -- Verificati TLS `.it`/SAN, `.com` non coperto, `TLS_CA_FILE`, fingerprint fuori banda, rinnovo e - assenza di bypass. -- Verificati due gate Task 9–10, evidenze solo metadati e nessuna migrazione di sessioni/index/cache legacy. - -## Concern - -- Nessuna mutazione PSD/Nginx/systemd/registry o lettura di segreti è stata eseguita. I comandi del - runbook restano condizionati alle autorizzazioni separate dei Task 9 e 10. - - -## Review fix — RED/GREEN - -### RED review - -- La fixture `sudo nginx -T` ha prodotto il rifiuto `case=sudo_raw_nginx_capture status=FAIL` prima della correzione del gate. -- La fixture header legacy opaco ha prodotto `case=opaque_legacy_header_literal status=FAIL` prima della correzione del gate. -- Dopo avere riallineato le label UI nei manuali, `bash scripts/test-verify-workspace-install-docs.sh` ha prodotto `server-workspace-registry.md: curator flow missing registry rule`: il verifier cercava ancora le due label precedenti. Il test sulla base HEAD e il diff hanno confermato la causa. - -### GREEN review - -- Il gate DWH ora rifiuta anche header opaco, digest JSON quotato, `export` di API key, `curl --header` e `-H`, `sudo nginx -T`, raw diff e Compose; le mutation fixture coprono label, PSD direct/Mac REST/CA, socket e flag REST. -- Il runbook non prescrive raw diff o dump: solo checker strutturale e secret scan con metadati e PASS/FAIL. Il piano Task 10 adotta la stessa regola. -- Il template `psd-local` resta `rest_api` solo Mac/local/remota; il server PSD Project A resta `postgres_direct` con binding separato. La CA privata e `TLS_CA_FILE` sono obbligatori salvo trust approvato equivalente. -- Le procedure server ora coprono backup manifest protetto, restore, curl config 0600 senza segreto in argv/env/output, Unix 204/401, HTTPS 2xx/401, 503 bounded con trap, journal PASS/FAIL e retention alla disinstallazione. -- Il verifier workspace-install e entrambi i manuali registry usano ora le quattro label effettive: `Validate workspace source`, `Test workspace connections`, `Save entered secrets`, `Forget stored value`. - -### Final verification review - -- PASS: `bash scripts/test-verify-dwh-auth-docs.sh`. -- PASS: `bash scripts/verify-dwh-auth-docs.sh`. -- PASS: `bash scripts/test-verify-workspace-install-docs.sh` (fixture complete). -- PASS: `bash scripts/auth-docs-smoke.sh`. -- PASS: `bash -n scripts/verify-dwh-auth-docs.sh scripts/test-verify-dwh-auth-docs.sh` e `git diff --check`. - -### Review concern - -- Nessuna mutazione runtime e nessun segreto reale sono stati letti. I soli comandi server documentati restano soggetti ai gate autorizzativi Task 9 e Task 10. - -## Review fix wave 2 — RED/GREEN - -### RED wave 2 - -- Prima della correzione del proxy, `bash scripts/test-dwh-auth-build-contract.sh` ha fallito il contratto di preservazione path e `bash scripts/test-dwh-auth-nginx-integration.sh` ha chiuso con `case=header_and_path_isolation status=FAIL`: il prefisso `/dwh` arrivava a PostgREST invece di essere rimosso. -- Prima delle procedure finali, il gate docs ha rifiutato il path chiave non deterministico e la fixture curl con header legacy opaco ha dato `case=header_file_curl_synthetic status=FAIL` perché il valore non veniva confrontato esattamente. -- Le mutation fixture hanno catturato l'estrazione tar sul registro attivo e i rename non protetti. Dopo l'inasprimento finale del gate, la sorgente ha dato `dwh-auth docs: restore must stage/check then use guarded same-filesystem renames` finché mancava il controllo fail-closed del candidato. -- Il RED finale dello scanner journal è stato `dwh-auth docs: docs/install/dwh-auth-server.md lacks required topic: sys.argv[2:]`: il gate esige la lettura byte-esatta di v1 e legacy e un `journalctl` che fallisca chiuso. - -### GREEN wave 2 - -- Commit `f616aab fix: preserve PostgREST RPC path through DWH proxy`: `proxy_pass` termina con `/`; il contratto e l'integrazione verificano `/dwh/rpc/ping?x` verso `/rpc/ping?x`. -- Il runbook usa un singolo file chiave v1, header file `0600` passati solo con `curl --header @file`, socket 204 dual-key, HTTPS 2xx pre/post per v1 e 401 post-revoca per legacy `legacy-shared`. -- Restore protetto: staging sul filesystem `/var/lib`, check candidato, `mv -T --` guardato per ogni publish/rollback e pre-restore conservato. Backup/manifest restano root-only `0600` su storage cifrato approvato. -- Lo scanner journal esegue `journalctl` in un unico processo Python root, sopprime stderr, controlla return code e bytes esatti di entrambe le chiavi senza emettere journal o segreti; la shell mostra solo PASS/FAIL. -- Il verifier rifiuta `curl --config`, header in argv, raw Nginx/diff, TLS insicuro, segreti env, mode insicuri e Compose. Le fixture mutano path chiave, ID legacy, header/legacy probes, restore, journal, codici HTTPS e label UI. - -### Final verification wave 2 - -- PASS: `bash scripts/test-dwh-auth-build-contract.sh`. -- PASS: `bash scripts/test-dwh-auth-nginx-contract.sh`. -- PASS: `bash scripts/test-dwh-auth-nginx-integration.sh`. -- PASS: `bash scripts/test-verify-dwh-auth-docs.sh` e `bash scripts/verify-dwh-auth-docs.sh`. -- PASS: `bash scripts/test-verify-workspace-install-docs.sh` e `bash scripts/auth-docs-smoke.sh`. -- PASS: `bash -n` sugli otto gate shell e `git diff --check`. - -### Review concern wave 2 - -- Nessuna configurazione protetta, chiave reale, Nginx, systemd o stack PSD è stata letta o mutata. Le procedure privilegiate restano istruzioni condizionate ai Gate 9–10; la verifica degli owner/mode reali è un'attività del rollout autorizzato, non di questo task documentale. diff --git a/AGENTS.md b/AGENTS.md index 46840fc0..bcb509f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,9 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t Read [PROJECT_STATE.md](PROJECT_STATE.md) for the current-state snapshot: what was last built, pending manual gates, workspace/secret layout, and design-doc locations. This file holds the stable commands + architecture mental model; PROJECT_STATE.md holds the evolving -detail. Design history lives in `docs/superpowers/specs/` and `docs/superpowers/plans/`. +detail. Current architecture and contracts live in `docs/architecture/`, `docs/contracts/`, +and `docs/evidence.md`; durable design decisions live in `docs/adr/`. Git history is the source +for superseded designs and implementation plans. ## Commands diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9c37d7e3..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,105 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Start here - -Read [PROJECT_STATE.md](PROJECT_STATE.md) for the current-state snapshot: what was last -built, pending manual gates, workspace/secret layout, and design-doc locations. This file -holds the stable commands + architecture mental model; PROJECT_STATE.md holds the evolving -detail. Design history lives in `docs/superpowers/specs/` and `docs/superpowers/plans/`. - -## Agent skills - -### Issue tracker - -Issues and specifications are tracked in GitHub Issues for `mptyl/ThothII`. -See `docs/agents/issue-tracker.md`. - -### Triage labels - -Use the standard Matt Pocock triage roles and their corresponding GitHub labels. -See `docs/agents/triage-labels.md`. - -### Domain documentation - -This repository uses a single-context domain layout: `CONTEXT.md` at the -repository root, with repository-wide ADRs stored under `docs/adr/`. -See `docs/agents/domain.md`. - -## Commands - -The repo has three independently-built layers. Run the **full stack** (real Pi + DWH, needs -VPN + `harness/.env` + `pi` on PATH) with `./scripts/run-stack.sh` (frontend :5173 → backend :8787). - -**harness/** (Python `tht` CLI + Pi gate extension) -- Install: `cd harness && python -m venv .venv && pip install -e ".[dev]"` (puts `tht` on PATH) -- Test: `.venv/bin/pytest -q` — `l2` (real GLM + remote DB) is opt-in via `addopts = -m 'not l2'`; `l0` (testcontainers) needs Docker -- Single test: `.venv/bin/pytest tests/test_session_mutations.py::test_set_name -v` (or `-k `); include e2e with `-m l2` -- Lint: `.venv/bin/ruff check .` (line-length 100) - -**backend/** (Fastify + TypeScript, vitest) -- Dev: `npm run dev` (tsx watch `src/server.ts`) · Build: `npm run build` (tsc → `dist/`) -- Test: `npx vitest run` · Single: `npx vitest run test/routes-sessions.test.ts -t "rename"` -- Typecheck: `npx tsc --noEmit -p .` (vitest does NOT type-check — run this before committing) - -**frontend/** (React 18 + Vite + vitest) -- Dev: `npm run dev` (Vite; set `VITE_BACKEND_URL`) · Build: `npm run build` -- Test: `npx vitest run` · Single: `npx vitest run src/shell/NavSessions.test.tsx` -- Typecheck: `npx tsc -b` · E2E: `npm run e2e` (Playwright) - -No ESLint on the TS layers — `tsc` is the gate. Tests use vitest + MSW (no network). - -## Architecture (the parts that need multiple files to see) - -``` -frontend (React/SSE) → backend (Fastify) → pi --mode rpc → tht/harness → DWH (read-only) -``` - -- **The harness owns the workflow and all persistence.** `tht` (Python) is a deterministic - CLI; `harness/.pi/extensions/tht-gate.js` is a Pi extension that drives an **8-phase - NL→SQL workflow**. The single source of workflow truth is `harness/workflow.yaml`; the - orchestration rules the model must follow are `harness/.pi/skills/tht-sessione/SKILL.md`. - "Current phase" is computed by folding the decision ledger (`harness/tht/phase.py`), not - stored — read it before reasoning about phase logic. - -- **Persistence = phase documents, NOT chat.** A session is a directory under the workspace's - `sessions/` path: `session_manifest.yaml` + per-phase artifacts (`question.md`, - `schema_linking.json`, `sql_final.sql`, …) + `review_decisions.jsonl`. The contract - (SKILL.md): *"the persisted state is the truth — what is not recorded did not happen."* - There is no verbatim transcript store. A resumed Pi process rebuilds context from - `tht session show ` + the on-disk artifacts. - -- **The backend is a thin bridge with no database of its own.** `ThtRunner` shells `tht` - subcommands; `PiProcessManager` runs one Pi child per session and bridges its RPC stream; - `SessionBridge` maps Pi RPC events → client events (`ui_request`/`text_delta`/`info`); - `SseHub` fans them out over SSE to the browser. Persistence belongs to the HARNESS, which - selects the session repository from the workspace config (`harness/tht/session/repository.py`): - filesystem by default, **PostgreSQL when `session_storage` is configured** (server/portable - deployment). Settings flow through harness preferences (`tht session preferences`) with - `backend/data/settings.json` only as the file fallback for injected runners/tests. - -- **Human-in-the-loop gate contract.** The model proposes; a human reviewer decides at gates - via widgets (`reviewer_select` = single pick — a chosen option carrying a `decision` payload - auto-confirms/persists directly, an option without one only asks; `reviewer_decide` = multiselect, - each choice IS a decision; `reviewer_confirm` = artifact/phase gate). The frontend renders these - widget-descriptors (`src/widgets/` registry) and the live transcript is rebuilt in-memory - from the SSE stream (`src/store/sessionStore.ts`) — it is not persisted. - -## Project-specific gotchas - -- **`tht`'s `-c`/`--config` is a PER-COMMAND option** — it must follow the subcommand, never - precede it (`ThtRunner.buildArgv` enforces this; prepending caused live 500s). -- **`--json` output must be pristine** (only valid JSON on stdout) — used as a machine contract. -- **UI strings are English; document *content* stays the workspace language** (Italian for - `psd`) because it's the real data. Only chrome/labels are English. -- **Workspaces** (`harness/workspaces/*.yaml`) set the DB target and **absolute** - `paths.sessions/artifacts/indexes` — for `psd` these point at a *separate, uncommitted* repo - (`tht-workspace-psd/`). Secrets live ONLY in `harness/.env` (gitignored). -- **Settings are global** (workspace/provider/model/thinking, persisted via harness - preferences — `backend/data/settings.json` is only the fallback); the New-session form is - question-only. -- **Resume**: a resumable session re-enters at its last incomplete phase. The backend refuses - resume with 409 when `finalized` or `archived`, and `PiProcessManager.spawnFor` must send - `/riprendi-sessione ` (resume mode) vs `/nuova-domanda` (new) — sending the wrong prompt - silently turns a resume into a new question. diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index d54ba2d1..91f193da 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -1,1349 +1,118 @@ # ThothII — Project State -## Evidence restructuring — PSD migration and real acceptance PASS (#47/#35) (2026-08-25) +Last updated: 2026-08-26. -- **Automated owner-gate history:** the isolated runs recorded - **225 passed, 1 known pytest deprecation warning** at `d4818c8` and, after five added - regressions, **230 passed, 1 known pytest deprecation warning**. The final authorized run and - full-suite results are linked from the acceptance record below. -- **Approved corpus:** Marco Pancotti recorded Human Git review PASS for all 35 proposed Evidence - and all 60 review items. PSD PRs `#2`, `#3`, and `#4` are merged; published workspace revision - `1c304efa02547a4c10826f557376a38e959b8bbf` contains 35 validated curated units with zero - unresolved findings. -- **Safe publication:** snapshot - `psd-clinical-6759909623621226-2026-08-25-18-43-21.snapshot` was taken before mutation. - Publication run `c564d7fdb36436b3ae76dc0c2ce1e20d` activated - `gen:f968808223bf462fa406c9a6df8f6a55` only after 20/20 retrieval queries passed Hit@10. The - existing unnamed 1,024-d cosine vector and collection remain; only BM25/IDF was added. The - previous generation is retained for rollback. -- **Real walkthrough:** finalized session `20301df7-cb3c-421a-b14f-dec8cf8d9620` exercised every - required phase against the VPN-backed PSD DWH, persisted five generation-bound Evidence - receipts, executed all three CTEs successfully, and returned 78 patients from approved - read-only SQL. Memory/synthesis did not search Evidence; formulas and session Evidence stayed - unpublished. -- **Acceptance record:** - `docs/testing/evidence/evidence-restructuring-psd-acceptance-2026-08-25.md` records the seven - manual gates, commit/run/generation IDs, retrieval ranks, recovery material, durable artifact - paths, and suite results. State: **PASS**; issues `#47` and `#35` may be closed after PR `#48` - is green and merged. +This file is the short operational snapshot. Stable commands and the architecture mental model +live in `AGENTS.md`; current design and runtime contracts live under `docs/architecture/`, +`docs/contracts/`, `docs/adr/`, and `docs/evidence.md`. Superseded plans and reports are +available from Git history rather than duplicated in the working tree. -## Modular workflow refactor candidate — live (2026-08-24) +## Current product shape -- **Isolation:** worktree `.worktrees/refactoring-modulare-contract-baseline`, branch - `codex/refactoring-modulare-contract-baseline`; the base stack is unchanged. -- **Candidate runtime:** Compose project `thothii-d811484ae2e4` is healthy at frontend - `127.0.0.1:18080`, core `127.0.0.1:18787`, and Qdrant `127.0.0.1:16333`. Its explicit volumes - preserve the PSD sessions, schema index, and embedding cache across image rebuilds. -- **Real data:** the VPN-backed PSD DWH is reachable; preprocessing indexed 163 tables and 2275 - columns. Manual session `85a0b758-ae30-432e-8298-837bf55abad9` completed F1-F8 on the modular - image and finalized successfully. -- **Phase progress fix:** Pi now emits a deduplicated, machine-readable phase-start notification - after persisted workflow mutations; the backend sanitizes it to `phase_started`; the frontend - advances the active workflow dot without waiting for a human widget. The real Pi RPC probe - emitted F8, and the harness/backend/frontend contract suites plus both TypeScript builds pass. -- **Testing:** the automated probe session `cccbee8c-b13d-4bcb-88a6-aa60a4cae533` is closed at F8 - after repeated cold-Resume probes preserved its 29 decisions and SQL/CTE/schema artifacts, so it - does not occupy the admin principal. The candidate stack is intentionally left running for owner - validation at `http://127.0.0.1:18080/`. - -> Starting-point snapshot for new sessions. -> **Requisito finale del progetto (owner, 2026-08-11):** al termine dell'ultima fase tecnica deve -> essere prodotto un documento unico che guidi l'utente passo-passo su (1) come preparare il -> repository dei workspace su Git secondo le regole del progetto, (2) come usare gli strumenti di -> ThothII per il repository (app + CLI `tht`), (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-21 (DWH per-installation authentication is active in dual-key mode; -> the owner deferred Mac acceptance and legacy revocation to the mandatory pre-Project-B gate, -> approved a clean replacement with no legacy-state migration and no new host account, authorized -> the read-only survey and Project A private preparation, and did not authorize either stopping the -> legacy stack or starting the new stack). -> Point a fresh session here ("read PROJECT_STATE.md") before substantial work. - -### PSD server deployment program — design approved, execution PENDING (2026-08-20) - -- **Approved design:** `docs/plans/2026-08-20-psd-server-deployment-program-design.md`; design - commit `3fd177b`. The owner approved a common read-only survey followed by two independently - accepted projects: A installs/proves a private local-auth stack through F1-F8; B starts only - after A PASS and integrates Supabase schema storage, Authentik OIDC, Nginx, the load balancer, - and the existing Aritmolab sidebar journey. -- **Executable entrypoint:** `docs/plans/2026-08-20-psd-server-deployment-program.md`, with separate - plans for the survey, Project A, and Project B. The server-local Sol agent must execute them with - `superpowers:executing-plans`, checkpointing every verified step and stopping on the documented - owner/secret/rollback boundaries. -- **Human gates:** `docs/testing/psd-server-project-a-manual.md` and - `docs/testing/psd-server-project-b-manual.md`; survey and Project A/B report templates are under - `docs/testing/evidence/`. Automated evidence never substitutes for the two explicit human PASS - decisions. -- **Workspace decision:** keep one `psd-clinical` descriptor in `tht-workspace-psd`; publish - `supported_transports: [rest_api, postgres_direct]`. Mac selects REST, server selects direct; - all installation bindings/secrets remain outside Git. -- **Data/runtime decision:** migrate configuration only. Legacy work sessions, Qdrant indexes, and - Ollama cache are not imported. Project A rebuilds internal Qdrant/Ollama and uses filesystem work - sessions. Project B uses the existing Supabase PostgreSQL database with isolated schema - `thoth_sessions`, dedicated migrator/runtime roles, forced RLS, and no PostgREST exposure. -- **Network/auth decision:** no SSH tunnel. Project A is loopback-only unless the surveyed load - balancer can prove an operator-only temporary endpoint. Project B preserves the real user flow - `Aritmolab homepage -> sidebar -> load balancer -> Nginx -> ThothII`, with direct ThothII-managed - OIDC and no second Nginx `auth_request`. -- **Clean-replacement amendment (owner, 2026-08-21):** no host `thothii` user or group is created. - The image retains its internal numeric UID/GID `10001:10001`; only its dedicated writable bind - trees may carry that unmapped numeric ownership. Old ThothII sessions/configuration are - disposable, but the exact legacy containers, images, source, and data remain intact until the - new Aritmolab journey passes Project B. Shared Omics/LocalLLM networks, ETL Evidence, DWH, - `dwh-auth`, Supabase, Authentik, Superset, and Aritmolab are never cleanup targets. Approved - design and executable amendment: `docs/superpowers/specs/2026-08-21-psd-clean-replacement-design.md` - and `docs/superpowers/plans/2026-08-21-psd-clean-replacement.md`. -- **State:** survey `SURVEY_NO_GO` for Project A private; Project A - `BLOCKED_BY_SURVEY_AND_MUTATION_GATE`; Project B `BLOCKED_BY_PROJECT_A_AND_PRE_B_GATE`. - Legacy retention and UID strategy are resolved. Remaining private-scope blockers are dedicated - read-only workspace access, a dedicated direct-DWH role/route, and sanitized Pi/LLM - metadata. The catalog-only survey proved the currently available `postgres` identity owns - `datawarehouse` and has full write/DDL privileges, so it must not be reused by the new core. - Pi metadata resolves to 0.80.3, `deepseek/deepseek-v4-pro`, thinking `high`, but the bounded - no-session/no-tool reachability probe is FAIL and must be diagnosed without exposing auth data. -- **Sequencing amendment (owner, 2026-08-21):** use two survey decisions. Project A private may - proceed only after `SURVEY_GO_PROJECT_A_PRIVATE` and a separate stop/start authorization. Mac - `rest_api` acceptance, the 48-hour/two-ETL observation, and revocation of `legacy-shared` are - mandatory before `SURVEY_GO_PROJECT_B`. Current authorization covers read-only survey and - preparation only; old-stack stop and new-stack start remain forbidden. -- **Runtime-projection preparation (2026-08-22):** the source contract and hermetic gates prepare - root-only canonical authentication plus a separate `10001:10001` read-only core projection. - This is implementation preparation and test evidence only. Project A has not been started; - applying its descriptor or any server runtime root still needs explicit authorization. - -### Authentication final-review fix round 2 — remediation PASS, release gates remain (2026-08-18) - -- Frozen source is `2a9359071257f9b8a71d36ec2bbb25b161003f81` on `feat/thoth-auth`. - Source and evidence are separate commits; generated local runtime-state directories remain - untracked and must not be staged. -- Local PASS on the frozen source: exact `safeio`/`backup`/`authstorage` tests, full Go race suite, - `go vet`, macOS host build, Windows amd64 package cross-compiles, and Windows CLI build. -- The lifecycle tests now use context-aware gate publication/release, bounded waits for stages, - outcomes and admission, and cancel plus bounded worker join before lock-release assertions. A - deterministic withheld-gate case proves timeout, cancellation, join, and eventual lock release. - The temporary Windows relative-open diagnostic matrix was removed without reducing DACL, NT - normalization, or retained no-delete assertions. -- Authorized exact-source workflow run `32147345625` completed on the exact frozen SHA and - executed the unfiltered native command - `go test ./internal/safeio ./internal/backup ./internal/authstorage -count=1`. The required step - passed: safeio `22.058s`, backup `7.161s`, authstorage `16.088s`. Native Windows StageArchive and - concurrent claim-consume evidence are therefore PASS, not inferred from cross-compilation. -- The same Windows job later failed the unrelated clone-contract script at - `scripts/test-windows-clone-contract.ps1:208` because `$remoteYaml:` is not a valid PowerShell - variable reference. LF/Compose and Linux Docker baseline failures also repeated. The optional - Windows Docker startup job was skipped without executing and is `NOT_RUN` / `BLOCKED`; the - overall completed run conclusion is `failure` because the baseline jobs remain red. -- Historical Node/auth/browser/docs PASS and harness/Ruff/Compose FAIL evidence remains bound to - its recorded source where not rerun. L2, PSD/manual, and provider prerequisites remain - `PENDING`; no new Docker image manifest was generated. -- Durable evidence: `.artifacts/task-15/automated-gates.json`, - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/task-4-report.md`, and - `.superpowers/sdd/2026-08-18-thothii-authentication-remediation/fix-round-2-report.md`. -- Current automated-gates SHA-256 is - `6c516db5c2064c4a4a2e5f25961b993cd4a8fe020bbbb822fbac7faa0c119599`; the historical Docker - manifest remains bound to its recorded older source and was not reused for this candidate. -- **State:** the three original remediation Important findings remain `RESOLVED`; the fix-round-2 - lifecycle Important is `ADDRESSED`; the Windows diagnostics Minor is `ADDRESSED`; authentication - remediation is `PASS`. Separately, release readiness remains `FAIL`, with L2, PSD/manual, and - provider gates `PENDING`, until unrelated deployment, runner, baseline, and external gates close. - -### P3 effective configuration and `.tht-dwh` — implementation complete, automated PASS, manual PASS (2026-08-13) - -- **Scope:** P3 (PRD D3): a versioned shared canonicalizer produces the non-secret effective - DWH/preprocessing configuration and a stable logical identity - (`workspace://@v1:`), used identically by the application sessions and the operator - CLI. `OWNER.json` writes are versioned; legacy roots remain readable; content-only/Evidence-only - changes keep the identity (no forced reconfiguration), while DWH-affecting changes fail closed - (never silently reusing the old generation). -- **Memory:** explicit workspace-global `paths.memory` root with a guarded migration command - (`tht memory migrate`) that copies and verifies exactly one legacy JSONL under the workspace - lock and fails closed on conflicts. -- **Revision-scoped records:** schema and Evidence Qdrant point IDs, payloads and queries include - `workspace_revision`; memory/solved stay workspace-wide. -- **Operator contract:** `tht` now carries `effectiveConfigIdentity`/`configFingerprint`/ - `inputFingerprint` in results; the operator config lease path is deterministic for the same - revision+identity. -- **Retained evidence:** `.artifacts/p3-integration/p3-da9428d84f152fe059d41a89436496b7/` - (15/15 checks PASS), bound to clean source commit - `3b0726472e15c157…`. -- **Manual gate:** P3 walkthrough in `docs/testing/p2-p6-manual-verification.md`; decision - **PASS** (owner approval 2026-08-13). -### P4 Qdrant collection lifecycle — implementation complete, automated PASS, manual PASS (2026-08-13) - -- **Scope:** P4 (PRD D4): one shared TypeScript collection manager owns the Qdrant collection - and payload-index contract; session admission self-heals a missing collection (1024/cosine + - the 8 required keyword payload indexes) and adds missing indexes, but never mutates an - incompatible collection (`semantic_index_incompatible`); the operator path keeps - `require_existing` semantics. -- **Host CLI:** `tht workspace vector inspect` (read-only contract report) and - `tht workspace vector rebuild --workspace --collection --confirm --destroy` - (guarded delete/recreate of only the descriptor-owned collection, with durable state before - deletion and verification after recreation; mismatched confirmation or missing `--destroy` - → exit 2). -- **Key files:** `backend/src/workspaces/qdrant-collection.ts` (+test), `backend/src/tht/tht-runner.ts` - (`qdrantEnsure` self-heal for admission; default `require_existing` elsewhere), - `backend/src/workspaces/runtime-config-lease.ts` (lease exposes `semanticQdrantUrl`), - `backend/src/workspace-maintenance.ts` + `preprocessing-service.ts` (`vector-inspect`/`vector-rebuild` - operator commands), `tools/tht/internal/workspaceops/operations.go` (+tests). -- **Automated acceptance:** PASS 11/11 (run `p4-466bbfdea9ef3111f36baa99fc2d64aa`, - report `.artifacts/p4-integration/p4-466bbfdea9ef3111f36baa99fc2d64aa/` retained via `--keep`, - bound to clean source commit `e056c19e6214254a9e3b2390e24c389920b84e95`): preflight, clean_state, - ownership, qdrant_up, self_heal_create_missing, self_heal_repairs_missing_index, - incompatible_refused, require_existing_refused, rebuild_recreates_contract, secret_scan, - cleanup_confinement. -- **Gates:** backend 666/666 + tsc clean; Go build+test 9/9; p4 runner unit tests 3/3; harness - 841 passed (only the two pre-existing debt failures unchanged). -- **Manual acceptance:** PASS (owner approval 2026-08-13) — walkthrough section P4 in - `docs/testing/p2-p6-manual-verification.md`. - - -### P5 curated FK annotations in Git — implementation complete, automated PASS, manual PASS (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:** `tht ... 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/tht/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:** PASS 10/10 (run `p5-66b1f1e74f147a23c0a4bff04e6d2a4c`, report - `.artifacts/p5-integration/p5-66b1f1e74f147a23c0a4bff04e6d2a4c/` retained via `--keep`, bound to - clean source commit `9db0299063d5068198c05dc467d7f86dc34de85b`): preflight, clean_state, ownership, - activation_sync, accept_happy_path, revision_isolation, accept_negatives, continuation_gate, - secret_scan, cleanup_confinement. Runner: `scripts/p5-acceptance.sh` / - `backend/scripts/p5-acceptance.mjs` (+unit test `scripts/test-p5-acceptance.sh`). -- **Manual acceptance:** PASS (owner approval 2026-08-13) — walkthrough section P5 in - `docs/testing/p2-p6-manual-verification.md`. - -### P6 commit-addressed Evidence materialization — implementation complete, automated PASS, manual PASS (2026-08-13) - -- **Scope:** P6 (PRD D6): filesystem Evidence `/evidence` is materialized from the exact pinned - Git commit into the immutable revision content root `/snapshots///evidence` - at activation, with a sibling bounded manifest `/evidence.manifest.json` whose digest is chained - into `snapshot.json`. -- **Safety:** fixed Git plumbing (`ls-tree -r -z` + `cat-file blob`), no shell, no mobile checkout; - symlinks/gitlinks at any depth, traversal/absolute/duplicate/cross-namespace paths, and non-regular - modes are refused. Installation-local bounds (defaults): 4096 entries, 64 MiB total, 8 MiB per - file, 4096 path bytes, 1 MiB manifest; a size-sum preflight runs before writing and no partial root - is published. Re-activation reuses a valid root and fails closed on a tampered manifest. -- **Engine:** `evidencePolicy` no longer stops filesystem sources (`evidence_materialization_required` - retired); `preprocess evidence`/`preprocess run` operate on the materialized root. Evidence Qdrant - records remain revision-scoped; corpus ACTIVE is revision-qualified. HTTP/S3 Evidence is unchanged. -- **Curated-only runtime contract (Evidence contract version 2):** the new authoring layout preserves the - complete commit-addressed `evidence/` tree (`source/`, `curated/`, manifest and evaluation files), - while the rendered filesystem acquisition pattern is exactly `curated/**/*.md`. Version 2 rejects - every other pattern, including source, mixed source/curated, broad curated, and non-Markdown - patterns; legacy Evidence version 1 retains its explicit safe-pattern compatibility. The curator - validates before merge and the runtime validates the - pinned curated corpus before indexing. The existing unnamed dense vector remains intact while - Evidence may add `bm25`/`idf` additively; no runtime operation writes the authoring repository. -- **Retention:** materialized roots live inside the commit-addressed snapshot directory, so they are - retained while pinned and removed by the existing snapshot retention scan when unreferenced. -- **Key files:** `backend/src/workspaces/evidence-materialization.ts` (+test), - `backend/src/workspaces/git-repository.ts` (`evidenceTreeObjects`/`evidenceTreeId`/ - `evidenceBlobBytes`/`gitObjectSize`), `backend/src/workspaces/registry.ts` (activation staging + - integrity chain), `backend/src/workspaces/preprocessing-service.ts` (stop removal), - `backend/src/workspaces/types.ts` + `config.ts` (limits), `docs/contracts/ - workspace-preprocessing-cli.md`. -- **Gates:** backend **698/698** + tsc clean; Go build+test 9/9 (unchanged); harness focused suites - pass. Full-suite re-run and the clean-state process goal recorded at the acceptance gate. -- **Automated acceptance:** PASS 10/10 (run `p6-7a4c4d0ebb63399cfa9f674738b9e8fc`, report - `.artifacts/p6-integration/p6-7a4c4d0ebb63399cfa9f674738b9e8fc/` retained via `--keep`, bound to - clean source commit `124891bbfe8dc8270e8b58c4206150eb8bebeaa7`): preflight, clean_state, ownership, - activation_materialization, evidence_preprocess, revision_isolation, unsafe_tree_refused, - bound_refused, secret_scan, cleanup_confinement. Runner: `scripts/p6-acceptance.sh` / - `backend/scripts/p6-acceptance.mjs` (+unit test `scripts/test-p6-acceptance.sh`). -- **Manual acceptance:** PASS (owner approval 2026-08-13) — walkthrough section P6 in - `docs/testing/p2-p6-manual-verification.md`. - -### P7 PSD migration — plan + repository restructured + local validation PASS; owner-gated (2026-08-13) - -- **Plan:** `docs/superpowers/plans/2026-08-13-p7-psd-migration.md`. -- **Done (autonomous):** `/Users/mp/projects/tht-workspace-psd` restructured to the P1.1 layout and - committed (`thoth-workspaces.yaml` + `psd-clinical/workspace.yaml` schema v3 + `psd-clinical/ - evidence/` 36 `.md` + `psd-clinical/schema/annotations.yaml` 42 KB); legacy runtime dirs gitignored - and the old flat `psd.yaml` retired. A local `WorkspaceRegistry.bootstrap()` against a scratch bare - clone **activated `psd-clinical`** (descriptor valid, 36 Evidence materialized + manifest, 42 KB - annotations synced, `workspace-docs` generated) with no DWH/secret access. -- **Templates:** `deploy/psd/{workspace-bindings,operator,thothii-installation}.env.example` + - gitignored `secrets/`; operator checklist in `docs/install/psd-workspace-setup.md` (registered in - MkDocs nav). -- **Published (2026-08-13):** private repo `https://github.com/mptyl/tht-workspace-psd` (main = - `d4f9185`), consumed via SSH deploy key `thothii-psd` (read-write, passphrase-less, generated in - `deploy/psd/secrets/`). Real operator config is wired (gitignored): `deploy/psd/operator.env`, - `workspace-bindings.env`, `thothii-installation.yaml`, `connector-secrets.yaml` + `secrets/` - (DWH X-API-Key reused from the legacy `.env`; no CA — the DWH REST is public HTTPS). -- **Stack live:** started via `tht start` (project `thothii-70417a3e30ea`), all services - healthy, `qwen3-embedding:0.6b` present; the registry cloned + activated `psd-clinical` - (`ready`); `tht workspace inspect` returns `ok` with descriptor/catalog/runtime identities. - Gotcha recorded: `tht` uses a per-descriptor Compose project name, so the stack must be - started with `tht start` (not a raw `compose-with-preflight.sh up`). -- **Preprocessing live (2026-08-13):** with VPN active, `tht workspace preprocess run - --workspace psd-clinical` **succeeded** against the real PSD DWH — DWH introspection + LSH - (163 tables / 2275 columns), FK review (no new candidates: the 42 KB curated annotations are - authoritative), schema index (2438 records) and filesystem Evidence index (36 docs / 43 chunks). - Qdrant `psd-clinical` now holds **2482 revision-scoped points** (`schema_table` 164, - `schema_column` 2275, `evidence` 43; all carry `workspace_revision`). Rerun is idempotent - (Evidence `unchanged: 36`). -- **Fixes shipped during the live run** (real-DWH scale revealed them): (1) pruned ~95 GB of orphaned - acceptance-run Docker volumes; (2) raised `workspace-maintenance` tmpfs `/tmp` 64 MiB → 1 GiB - (PSD LSH snapshot is ~105 MB); (3) `vector rebuild` now recreates the 8 keyword payload indexes - (it only created dimensions/distance); (4) Qdrant upserts are chunked (256 points/batch) — a 2438- - record schema batch exceeded Qdrant's 32 MiB JSON limit; (5) frozen Evidence metadata lists now - stay lists (`FrozenList`) instead of tuples, preserving JSON shape; (6) embedding timeout 30 s → - 300 s and batch 32 → 16 for large CPU corpora. -- **Remaining:** live session smoke on `psd-clinical` (P8 L2) — create a session with a real - natural-language question and reach the first reviewer gate. - -### Final aggregate P2–P6 verification — automated PASS, manual PENDING (2026-08-13) - -- **Aggregate process goal:** one clean-state run exercises the complete DWH → FK → schema → - filesystem Evidence chain through `tht`/the operator surface, proves idempotency and - revision isolation, proves a second installation consumes the same Git workspace with its own - state, exercises unsafe-tree and bound negatives, and cleans only owned resources. -- **Automated acceptance:** PASS 12/12 (run `p2p6-ee542112c526ef0d4c25ddf6c8bc164b`, report - `.artifacts/p2p6-integration/p2p6-ee542112c526ef0d4c25ddf6c8bc164b/` retained via `--keep`, bound - to clean source commit `1dcf4051b0d9db8ae163e4d7c53871564ca3c564`): preflight, clean_state, - ownership, activation_materialization, dwh_chain, fk_schema_evidence_chain, revision_isolation, - second_installation, unsafe_tree_refused, bound_refused, secret_scan, cleanup_confinement. Runner: - `scripts/p2p6-acceptance.sh` / `backend/scripts/p2p6-acceptance.mjs` (+unit test). -- **Full suites + builds (design §10):** harness **873 passed / 4 deselected** (with color disabled; - the forced-color environment splits `--help` flags and trips the gate-CLI consistency test only); - backend **698/698** + tsc + build; frontend **364/364** + `tsc -b` + build; `tht` Go - build+test **9/9**; `git diff --check` clean. -- **Manual acceptance:** PENDING — "Final aggregate P2–P6 verification" in - `docs/testing/p2-p6-manual-verification.md`. - -### User-guide deliverable (owner requirement) — written, review PENDING (2026-08-13) - -- **`docs/guida-utente.md`** (Italian, simple words + examples) covers: (1) preparing the workspace - Git repository (catalog + schema-v3 descriptor + Evidence + curated annotations), (2) using the - ThothII tools for the repository (`tht` commands + read-only workspace management), and (3) - using the base ThothII application (sessions, questions, gates). It ends with a complete - Policlinico San Donato walkthrough and links to the technical contracts. -- Registered in the MkDocs nav (`mkdocs.yml`). Owner review PENDING. - -### 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 `tht` - binary is the only host interface for workspace preprocessing. Commands: `workspace inspect`, - `preprocess dwh`, `schema suggest-fks`, `schema check`, `index-schema`, `preprocess evidence`, - `preprocess run`, with the exact grammar, file-ingress bounds, result contract and exit codes in - `docs/contracts/workspace-preprocessing-cli.md`. -- **Operator:** `workspace-maintenance` is a profile-gated Compose service sharing the core image, - with no Pi auth/state, no backend/Pi/frontend listener, no Git credentials, and a compiled Node - entrypoint (`backend/src/workspace-maintenance.ts`) driving the existing harness engine through - pristine JSON machine interfaces (`schema_cmd.py`, `vector_cmd.py`, `preprocess_cmd.py`). -- **Boundaries honored:** FK review is digest-bound (candidate digest == persisted artifact; a - review accepted for the same candidate content counts); Qdrant collections are never created by - the product path (`require_existing` + pre-provisioned fixture, P4 owns lifecycle); filesystem - Evidence stops with `evidence_materialization_required` (P6); HTTP Evidence enforces an - installation private-host allowlist; `ssh_tunnel` stays fail-closed (P10); cross-revision DWH - reuse is explicitly P3. -- **Retained evidence:** `.artifacts/p2-integration/p2-b109757b26388a5ed6b1d173dee86584/` - (11/11 checks PASS), bound to clean source commit - `de5de36f9a4edfd4fbebf277822090871ccdd61f`. -- **Manual gate:** P2 walkthrough in `docs/testing/p2-p6-manual-verification.md`; the owner - approved P2 on 2026-08-11 (manual acceptance PASS). P3 and later start only after an explicit - new authorization. - -### P1.1 workspace-directory registry — automated integration PASS, manual PENDING (2026-08-11) - -- **Scope:** P1 correction (not preprocessing). Root curator-owned catalog `thoth-workspaces.yaml`; - one self-contained directory per workspace (`/workspace.yaml`, optional `/evidence/**`); - generated docs stay API-owned under `workspace-docs/`; internal immutable snapshots remain - flat (`//.yaml`) to preserve session pins and runtime trust. -- **Ownership:** the API may create a descriptor once when its catalog slot exists and the - descriptor Git object is absent at the exact base commit. Existing descriptors and curated - content are curator-owned and change only through Git commit/push then installation pull. - Update/delete publish payloads are refused as HTTP 409 `workspace_curator_owned`. Catalog and - Evidence are never written/staged/cleaned by the API. Explicit pull may produce one deterministic - docs-only follow-up commit that never touches curator bytes. -- **Schema/UI:** schema v3 remains the only descriptor schema; filesystem Evidence URI is exactly - `/evidence`. Browser workspace management is read-only for ready workspaces (Pull/Sync, - Validate, installation Test, Export, Evidence summary, curator Git guidance) and offers an - editable bootstrap form only for `configuration_required` catalog slots. -- **Retained evidence:** `.artifacts/p11-integration/p11-ac0b047024fb09eeca218512526a6b23/` - (`report.json` sha256 `44250145fede36de5de941262beb833c920e8c73366d987cdd738856aac6f6d6`), - 19/19 checks PASS, bound to clean source commit - `eac472011e465c24572d9a6bae14de0fb3e246c0` / tree `4fd15ec28d3b7967b7b8757158013307fb20f3b9`. -- **Verification:** backend Vitest **634 passed / 41 files** + tsc + build; frontend Vitest - **364 passed / 54 files** + tsc + build; harness focused Evidence/config pytest **39 passed**; - install-docs and schema-v3-only gates PASS; `workspace-registry-smoke.sh` and - `unified-deployment-smoke.sh` full Docker runs PASS with exact cleanup. -- **Known limitations:** P2–P6 plans/designs are unchanged and their old source paths are - inventoried for a later owner-approved adaptation plan. Windows Docker startup and native - PowerShell contract were not executed on a Windows host. P1's accepted historical evidence and - process artifacts remain untouched; the old P1 process commands are not rerunnable against the - superseding P1.1 repository contract. -- **Manual gate:** `.artifacts/manual-acceptance/p11/` prepared for the reviewer; - follow `docs/testing/p11-manual-acceptance.md`. The owner reviewed the walkthrough and - approved the implementation on 2026-08-11. +ThothII is a human-in-the-loop datamart builder with three independently built layers: ```text -P1.1 automated integration: PASS -P1.1 manual acceptance: PASS (owner approval 2026-08-11) +frontend (React/SSE) → backend (Fastify) → pi --mode rpc → tht/harness → DWH (read-only) ``` -# P1 configuration process — ACCEPTED 2026-08-10 +The harness owns the deterministic eight-phase NL→SQL workflow and all session persistence. +The backend is a process/RPC/SSE bridge without a database of its own. The frontend renders the +review gates and keeps the live transcript in memory. See +`docs/architecture/components.md` for the detailed component and data-flow map. -- Retained evidence: `.artifacts/p1-integration/p1-038bf31360180dc831220b33fbadcfe6/report.md` -- Final report hashes: `report.json` `f07d49097966de6f0307490089fdb2ae61379c04b7fc7177d3c44cf001e1b46a`; `report.md` `09b6a9e9ad9eed2b049e286af452e12fa1f3174ea8d633253542604470890c6c`. -- automated integration: PASS -- manual acceptance: PASS — explicitly approved by the project reviewer on 2026-08-10. -- The retained run is bound to clean source commit - `c7338969d7c7c1c396d9099b7ab2d309b70ab6cf` and tree - `5f7013904806054b9f587230be89f34cbc80f5fc`. Its hash-bound provenance contains exact - 43-file backend source and 39-file compiled `dist` manifests (manifest SHA-256 - `eb6d6c77c78d14c798b50d0be430ad124b8fd8965afbc4bb07d358089d23f49` and `9f9e8899f8aca882ff08d49ec6cd00caeea75691c8280095a9b88bc74939a30a`). -- The retained audit has exactly 15 PASS checks and 134 unique declared artifacts whose final - bytes match every SHA-256 declaration. It records 749 PASS command events and 1,664 production - child/network events, with listener shutdown and refusal checks recorded in the final ownership - artifact. Raw Git rejects configured executable diff drivers and other helper-bearing state. -- Manual production acceptance binds every regular compiled distribution file through an immutable - manifest and cached verified module bytes; imported dependency replacement is refused before - RUNNING. Snapshot rendering validates the bounded `snapshot.json`, expected digest, and Git blob - identity, refusing regular source replacement without publishing output. -- Final Task 8/9 focused suites pass (48/48 Task 8; 59/59 manual acceptance and renderer checks), - backend TypeScript/build pass, frontend tests/build pass. Historical harness pytest/Ruff debt - remains unrelated to this P1 work. +## Evidence restructuring — accepted -## Internal Qdrant + Ollama semantic infrastructure — LIVE 2026-08-08 +The evidence restructuring and PSD migration completed real acceptance on 2026-08-25. -- **Compose topology.** The mandatory application stack is `frontend`, `core`, `qdrant`, - `embedding`, and the one-shot `embedding-model-init`. Startup is CPU-first by default; Linux - hosts may opt into GPU exposure with `THOTH_ENABLE_EMBEDDING_GPU=1`. Qdrant is private on the - Compose network and persists `/qdrant/storage` in `qdrant-data`. Ollama persists its local model - cache in `embedding-models`, and `embedding-model-init` blocks `core` until - `qwen3-embedding:0.6b` is present. - -- **Semantic contract.** Internal semantic indexing is fixed to `qwen3-embedding:0.6b`, - `1024` dimensions, and cosine distance. Schema v3 is the only accepted workspace descriptor. - Schema v1 and v2 workspace descriptors are rejected before activation. Candidate snapshot - validation makes activation or a pull fail atomically and leaves the prior valid snapshot active; - there is no in-product migrator or automatic conversion. One workspace owns one Qdrant - collection, and - schema, Evidence, and Memory records coexist inside that collection with payload `kind` - separation. - -- **Final review runtime barriers.** Operational routes, retained session pins, and runtime - rendering now require schema version 3 before resolving bindings, readiness, diagnostics, or - Pi. Session admission verifies the exact internal Qdrant collection (dimensions, cosine - distance, and required keyword payload indexes) before Ollama and before manifest persistence. - The Qdrant adapter binds every search/list/delete filter to its constructed workspace identity - and rejects conflicting caller namespaces. -- **Boundary and persistence.** Only DWH and LLM remain external runtime application endpoints. - There are no active external vector or embedding endpoint instructions, bindings, or secrets in - the supported operator manuals. Qdrant remains a derived but persistent semantic index: the - canonical sources of truth stay the workspace Git descriptors, phase artifacts, and memory - registry/ledger. The Ollama model cache is recoverable for offline startup but is not the - canonical source of semantic content. -- **Backup and recovery.** `./scripts/vector-backup.sh --project-name --output ` - archives exactly one labeled `_qdrant-data` volume and preserves the prior `qdrant` - running state. `./scripts/vector-restore.sh --project-name --input - --confirm-project ` requires the exact repeated project confirmation, validates manifest - and archive safety before stopping `qdrant`, stages rollback content, restores semantic storage - in place, and restarts `qdrant` only if it was previously running. Recovery requires the registry - to already hold a reviewed v3 descriptor revision compatible with the restored collection; the - helper does not restore descriptors, rename collections, or repair a semantic-index - incompatibility. Backup and restore share one atomic Docker-daemon lock per Compose - project/Qdrant volume; contenders fail before volume resolution, and cleanup removes the lock - only when its ownership labels still match. -- **Verification recorded for Task 13 final audit.** On Apple M4 Pro - (`Darwin 25.5.0`, Docker Server `29.6.2 linux/arm64`), harness pytest passed - **827 passed / 4 deselected**; backend Vitest passed **477/477** plus TypeScript and build; - frontend Vitest passed **374/374** plus TypeScript and build; `git diff --check` passed. - Deployment contracts passed: - `test-default-compose.sh`, `test-unified-compose.sh`, `test-internal-semantic-compose.sh`, - `test-no-deployment-coupling.sh`, `test-compose-secret-policy.sh`, and - `verify-workspace-install-docs.sh --fixtures-only`. -- **Task 13 Docker smoke evidence.** CPU semantic smoke passed in **217.34s** and proved - offline Qdrant/Ollama persistence plus exact cleanup. Workspace registry smoke passed in - **42.06s** in fix round 1 with a per-run image tag derived from the unique Compose project, - and proves exact cleanup of compose containers, volumes, networks, and only that smoke image. - Unified deployment smoke passed in **125.57s**; update-only rollback smoke - passed in **85.40s**; Linux server deployment smoke passed in **55.99s**. The previously - observed `tht` rollback failure did not recur. -- **Task 13 image and manual-gate notes.** Verified pinned runtime images: - `qdrant/qdrant:v1.18.2@sha256:75eab8c4ba42096724fdcfde8b4de0b5713d529dde32f285a1f86fdcb2c9e50c` - and - `ollama/ollama:0.32.0@sha256:57f573b47f1f71ebb445789f279fe3e596a8beab182f7cf486db9205bad87c5a`. - The workspace-registry smoke fix-round image used tag - `thothii-workspace-registry-smoke:thoth-workspace-registry-smoke-thoth-workspace-registry-smoke-10vi3a-19157`, - built manifest list `sha256:715b943057929418cad4aa71806d9edbaf823555d19bda6b875297617463fd4a` - with config `sha256:a566521981e08958aae9a12bfc7803bb5f3f835536b4bb8c39df8fcf26063161`, - and removed that exact reference during cleanup. Local GPU exposure (`THOTH_ENABLE_EMBEDDING_GPU=1`) and - Windows Docker Desktop startup were not manually executed in this run. -- **Task 13 known limitations.** Broad harness Ruff remains existing unrelated debt - (**220 errors**); touched harness files were verified Ruff-clean. The final active-reference - audit remains non-empty only in deterministic negative guards, retained off-repository migration - SQL, L2 compatibility fixtures, gitignored task notes, and historical reference notes. No active - schema-v3 operator manual or supported runtime deployment path retains external vector or - embedding endpoint coupling. -- **Final review fix verification.** Backend Vitest passed **477/477** plus TypeScript and build; - harness pytest passed **827 passed / 4 deselected** with the existing 74 warnings; touched Python - files are Ruff-clean. The complete `tht` Go suite, deterministic backup/restore safety test, - internal semantic Compose contract, no-deployment-coupling gate, CPU/offline semantic smoke, and - unified deployment smoke all pass after the final fix. The intermittent `tht` rollback failure was - traced to Docker Desktop alternating equivalent bind sources between `/private/...` and - `/host_mnt/private/...`. Exact state-v4 source hashes remain unchanged; only fresh bind - observations made by a Darwin `tht` carry non-serialized aliases for the rollback - comparison, so pre-fix recovery state remains readable and Linux `/host_mnt` paths remain - distinct. The rollback-only smoke passed twice consecutively after each fix revision, and the - subsequent full unified smoke passed with exact cleanup. +- The curated PSD revision contains 35 approved Evidence units and 60 review items. +- The accepted snapshot is + `psd-clinical-675990d90eae51da6f2bd51b1ae2609f245772ef-snapshot`. +- The active generation is `gen:f968b3bd7a553dbfef3cf47093698f2bc7f95f11`. +- Retrieval acceptance reached 20/20 Hit@10. +- A real session, `20301df7-cad7-403d-a4c1-9f35c9d07b66`, completed F1–F8 with five + receipts, three CTEs, and a final result of 78 patients. +- The durable acceptance record is + `docs/testing/evidence/evidence-restructuring-psd-acceptance-2026-08-25.md`. -# Historical archive -## Historical snapshots and archived reference notes +The canonical authoring, validation, publication, materialization, and preprocessing flow is +documented in `docs/evidence.md`. The governing contracts are +`docs/contracts/workspace-evidence-v3.md` and +`docs/contracts/workspace-preprocessing-cli.md`. -### Historical snapshot — Unified deployment release gate, Task 13 (2026-08-05) +## Workspace preprocessing and configuration -- **Release coverage.** `scripts/unified-deployment-smoke.sh` gates the two-service render/build, - frontend-to-core routing, embedded pinned Pi, Git registry bootstrap, offline recreation, valid - update, invalid-update retention, and the four persistent stores. `scripts/tht-update-smoke.sh` - independently exercises the bad-Pi update and automatic rollback path. - `scripts/server-deployment-smoke.sh` starts the server plus required session overlays with the - same smoke-built core/frontend images, disposable bind roots/secrets/session configuration, - upstream-auth checks, and fail-closed unavailable-session behavior. -- **Isolation and disclosure boundary.** Every run generates a unique temporary root, Compose - project, container/image names, transaction image tags, and run label. The rollback fixture uses - an immutable `hello-world` digest whose preflight exits successfully, guaranteeing the stopped - core state required by `tht` compensation. Cleanup includes stopped project containers in - its final ownership check immediately before teardown and removes only exact containers, - Compose resources, image references, control state, and temporary files. There is no global - prune. Failure diagnostics are bounded and sanitized, and all credentials/endpoints used by the - smokes are disposable fixtures rather than operator or repository secrets. Every public smoke - also has an internal 30-minute process-group supervisor with TERM/KILL of the complete group. -- **Cross-platform CI contract.** `.github/workflows/deployment.yml` uses immutable action commits, - pinned supported Node and Go versions, runs LF/Compose/secret/coupling/docs/TypeScript gates on - Linux, runs each Linux Docker smoke once under its own outer timeout, and copies the Windows - source into a path containing spaces before building/invoking native `tht` and rendering - Compose. The optional `windows_docker_startup` dispatch targets a labelled self-hosted Windows - Docker Desktop/WSL2 runner and performs bounded two-service startup and exact cleanup. No local - Windows or Windows Docker execution is claimed until that manual job is recorded. -- **Validation status.** Deterministic Phase A gates, backend **434/434** plus TypeScript, - frontend **386/386** plus TypeScript, and harness **862 passed / 5 L2 deselected** are green. - Review round 1 ran each Docker smoke exactly once without retry. Unified (`103.86s`) and - update-only (`46.45s`) passed build/start, core/Pi/registry/persistence setup and the stopped - candidate preflight, but `tht` stopped before mutation at its active-session inventory gate. - Round 2 replaces presence-only fixture checks with generated Compose renders plus the production - workspace resolver; this found and fixed missing explicit direct transport selections. The - clean-server preflight now atomically initializes the three hidden Pi-agent targets under the - writable parent bind while protected/tracked sources remain separate read-only mounts. Clean - empty-root render/setup and wrong-service/value/mount mutations are green. The corrected server - one-shot built and started both healthy services from an empty Pi-state root, then stopped at an - incorrectly addressed authenticated frontend hop. Fix round 3 adds the exact fourth private - non-admin claim and proves its nginx/backend transformation in a focused auth test. It also - centralizes schema-v2 registry descriptor resolution and secret-safe runtime rendering in - `ThtRunner`, preserving canonical revision identity and durable session roots for inventory, - create/resume/show, SQL, and Pi calls. The fresh update-only one-shot now passes mutation, - automatic `rolled_back` compensation, exact prior-image restoration, unchanged registry head - and mount identities, all four persistence sentinels, post-rollback doctor/workspace checks, - and exact labeled-resource cleanup. The one authorized server invocation was blocked at its - first Docker readiness call by the execution sandbox's socket permission before any Compose - resource could be created, so authenticated workspace/fail-closed session behavior remains an - explicit release gate. Native Windows PowerShell/Docker execution also remains pending. +The native host CLI `tht` is the operator surface. Workspace preprocessing runs through: -### Historical snapshot — Portable deployment decoupling (superseded 2026-08-08) - -- **Mandatory stack.** The supported Compose stack is exactly `frontend` plus `core`; use the - base file with `deploy/compose.local.yaml`, or with `deploy/compose.server.yaml` plus the - required public-server session overlay. `run-stack.sh` - invokes the base+local Compose command and the core image provides Pi, so no host Pi binary is - part of the launch contract. -- **External boundaries.** DWH, vector DB, embedding, LLM, and reverse-proxy services are - external configurable endpoints even when deployed on the same infrastructure. The two - superseded PSD/portal deployment overlays were removed. Workspace descriptors and migration - utilities remain separate from deployment runtime configuration. -- **Legacy PSD deployment ruling.** The PSD bootstrap was deleted because it generated the - retired overlay and was therefore deployment machinery, not a data migration utility. Its - remaining live contract checks were renamed for the generic local Compose profile. The coupling - gate rejects stale active deployment filenames and content while deliberately excluding - historical plans/specs, canonical workspace descriptors, and non-runtime migration helpers. -- **Fresh provider and secret contract.** Local, server, and standalone development mount the - protected Pi auth JSON plus tracked declarative model/settings files read-only under - `/home/thoth/.pi/agent`. The existing strict application bundle is a core-only Docker secret at - `/run/secrets/thothii.secrets`; operator env files contain only its absolute source path. - Provider readiness is exercised from a fresh Compose volume through model listing, configuration, - and sanitized credential status. -- **Install and scan closure.** Superseded copied one-service installation examples and the - provider-owned-network test are retired. Active manuals use the canonical base plus local/server - and optional overrides, while the category-based coupling scan covers runtime, Docker smoke, - install, operator, and positive deployment-test contracts and propagates scanner errors. - -### Historical snapshot — Portable Git workspace registry, pre-schema-v3 (superseded 2026-08-08) - -- **Source of truth and scope.** The canonical workspace repository is a generic Git remote, - configured only by `THT_WORKSPACE_GIT_REMOTE` and `THT_WORKSPACE_GIT_BRANCH` (there is no - committed PSD/Chirone remote or branch default). Both a local Docker installation and a server - persist its checkout, validated snapshots, state, and locks at `/data/workspace-registry`. - Connector endpoints, transport choices, and secret-file paths remain local bindings; secret - contents are never stored in Git, API responses, browser storage, diagnostics, or bundles. -- **Migration and session safety.** Schema-v2 descriptors are operational; legacy descriptors are - visible as `migration_required` until migrated by the documented operator workflow. New sessions - acquire a persistent revision lease before readiness and persist workspace ID plus immutable Git - revision. Retention hands that lease off only after an authoritative scan observes the manifest, - so a stale concurrent scan cannot prune the pinned snapshot. Resume resolves that historical - snapshot, while retention preserves every revision referenced by an open, closed, or failed - unarchived manifest. - Reconciliation runs only with a complete local installation list or an administrator's complete - server list, never from a remote user's partial view. -- **SSH connector boundary.** The current OpenSSH forward is owned by one bounded diagnostic and is - always cleaned up afterward. DWH/vector `ssh_tunnel` bindings therefore return - `workspace_not_activatable`, and new-session creation rejects them before persistence. Direct and - REST runtime connectors remain supported; Git remote access over SSH is unaffected. -- **Operator manuals.** Follow [the local manual](docs/install/local-workspace-registry.md) for - macOS/Windows/Linux Docker Desktop deployment and [the server manual](docs/install/server-workspace-registry.md) - for Gitea-compatible remotes, reverse proxy, migration, backup, and recovery. The release - workflow is Git review/push → installation pull → validate → local diagnostic test → browser-local - workspace/model/reasoning selection → revision-pinned session. -- **Verification recorded for this source branch.** `git diff --check` passed; backend Vitest - **371/371** and TypeScript passed; frontend Vitest **398/398** and TypeScript passed; the - harness document regression passed **10/10**. `./scripts/workspace-registry-smoke.sh` and the - executable installation-manual fixture verifier passed with Docker. A final unrestricted full - harness run remains a release command for the deployment environment; the earlier local - long-running harness run was intentionally cancelled before it produced a final result. - -### Historical snapshot — Session summary redesign (2026-07-23) - -- Session documents are projected at read time in outcome-first order: original question, - final SQL, persisted data preview, revised question, assumptions, one memory list, then - remaining technical documents. This applies to existing filesystem and repository-backed - sessions without rewriting their artifacts. -- Final SQL has an always-visible clipboard action. All prose, including original/revised - questions, assumptions, memory content, and remaining decisions, renders as Markdown. -- Memories are shown once, approved before declined. The generic decision list suppresses - memory ledger records plus `phase_approved`, `phase_auto_approved`, `table_approved`, - `table_promoted`, and `column_promoted`. -- The session summary has its own accessible pointer/keyboard resize separator, persists its - width independently from Model activity, reaches 50% when space permits, and preserves a - 512 px right-side minimum on narrower desktop layouts. -- Verification: harness **861 passed / 5 L2 deselected**, Pi gate **163/163**, full frontend - suite, TypeScript check, production build, Ruff, and `git diff --check` all passed. A live - pre-existing session returned the new canonical order and none of the suppressed decision - labels. Compose rebuilt and force-recreated both services; core image - `sha256:3566d1258b956f8ca96d3b5ff8f625503247a7fd3b0dffe77020ae03956403d8` - is healthy and frontend image - `sha256:8311ca1308b459ece7236bf143da7b1a226ff4082fed924e1b5a207c24b6ca29` - is running. Frontend and `/api/health` both returned HTTP 200. - -### Historical snapshot — Local Pi user auth + startup failure handling (2026-07-21) - -- The PSD Docker profile now bind-mounts the configurable host `PI_AUTH_FILE` read-only at - `/home/thoth/.pi/agent/auth.json`; on this Mac it resolves to the real user profile - `/Users/mp/.pi/agent/auth.json`. The container keeps its correct Linux identity - `HOME=/home/thoth` while Pi sees the user's independent `deepseek` and `zai` credentials. -- `deploy/pi/settings.json` is the non-secret model policy and exposes, in order, - `zai/glm-5.2`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-pro`, and - `aritmolab/qwen3.6-35b-a3b`. The core image is aligned to Pi 0.80.3. -- New-session creation now validates the saved provider/model against Pi before persistence; - unavailable selections return sanitized `503 model_unavailable` without creating a manifest. - A synchronous runtime-construction failure after persistence marks that session `failed` and - returns the fixed startup-recovery message instead of leaving an ambiguous `open` session. -- Verification: backend 235/235, TypeScript clean, dedicated Compose auth/model contract green - with a demonstrated RED→GREEN cycle. Rebuilt core image - `sha256:a8b4dd9f016c2335e4da897073bc6d5bdf1e8ce9b60dcfcca171b6677f563228` - is healthy; live `/models` returned all four models; a real `deepseek-v4-pro` smoke reached its - first reviewer gate, deleted only its own session, and restored the exact prior settings. -- Deleted the three explicitly approved incomplete DeepSeek attempts: - `a390c8b8-0a91-4a37-967b-ce7ff9be9797`, `a2f974b2-4c48-4967-b4b6-afdbc2b2d541`, and - `f66e1959-3c71-4b10-8aa1-606992046b7e` (API delete 204, subsequent lookup 404 for each). - -### Historical snapshot — User-owned sessions cutover (2026-07-16) - -- **Target contract:** the public server runs `AUTH_MODE=upstream` with Task 4 portal identity - forwarding and Task 5 principal enforcement deployed together. Its session source of truth is - direct TLS-verified PostgreSQL `thoth_sessions`; local development remains loopback-only with - filesystem sessions under `THT_HOME`. The core never receives the migrator credential. -- **Deployment material:** copy `deploy/compose.session-server.yaml.example` and - `deploy/workspaces/server-sessions.yaml.example` into reviewed, untracked operator files. The - runtime password, migrator password, and CA are three separate Docker secret mounts; server - startup rejects public/local storage and incomplete server DB/TLS configuration. -- **Readiness behavior:** `/health` remains the unauthenticated process liveness endpoint. Any - route requiring unavailable session/preferences storage returns fixed HTTP 503 before starting - Pi; this is intentional and must not be hidden by changing liveness to a database check. -- **Manual cutover only:** schedule maintenance, drain Pi work, run the one-shot migrator and - require `pending=[]` and `drifted=[]`, then replace core and perform an authenticated storage - smoke. Archive/checksum the three reviewed legacy filesystem session directories before deleting - exactly those three with `docker/cutover-legacy-sessions.sh --delete`; no deletion has been run - from this repository task. Do not import their untrusted ownership. -- **Rollback:** PostgreSQL remains the single source of truth. Revert only to a compatible fixed - release; never re-enable filesystem persistence, restore the archive into production, or - dual-write during rollback. - -### Historical snapshot — Docker locale deployment, Profile A (superseded 2026-08-05) - -ThothII gira in Docker sul server co-locato, **embedded nel portale omics_portal** a `https://aritmolab.policlinicosandonato.it/datamart-builder` (backend invisibile, tutto same-origin via nginx del portale). - -- **2 container** su `compose.yaml`: `thothii-core` (Fastify + harness tht + Pi) + `thothii-frontend` (Vite + nginx-unprivileged). Rete `omics_portal_omics_network` (external) con alias `thothii-core`/`thothii-frontend`. -- **DB**: Postgres diretto `:5438` (stessa istanza: schema `datawarehouse` 163 tabelle + `vectors` pgvector). Ruoli dedicati `thoth_dwh_reader` (read-only) + `thoth_vector_rw` (read+write). Embeddings: Ollama `:11434`. -- **Secrets**: `deploy/thothii.env` (env_file, gitignored) + `THT_MODEL_API_KEY_FILE` (key modello, file 0600 — meccanismo provider-credentials di Codex) + bind-mount `~/.pi` (pi-config). -- **Backend**: merge di `codex/portable-deployment` (secret-bundle, provider-credentials, auth `upstream`, security hardening, CI multiarch). Setup Docker MIO tenuto (il modello Docker-secrets di Codex è in `deploy/` come alternativa inerte). -- **Portale** (repo `omics_portal`, branch `agent/patient-capabilities-datamart-ui`): `nginx.conf` rotte `/datamart-builder/api`+`/assets` + `auth_request`, template `datamart_builder.html` (mount `
` + tag `{% vite_assets %}`), vista `datamart_builder_api_auth`. Auth: `authentik Admins` bypass; utenti normali necessitano gruppo `omics-datamart-builder`. -- **Fix load-bearing**: `configPath` da `THT_CONFIG` (route senza workspace), `vite_assets` `mark_safe` (SPA bianca), `COPY harness/`+`cp workflow.yaml`+`pip install .` (pip 26 / tht module-relative), entrypoint `server` case. -- **Standalone/dev**: `docker-compose.dev.yml` (rete propria, porte host 8787/8090) + `scripts/docker-smoke.sh`. -- Piano dettagliato: `docs/superpowers/plans/2026-07-12-local-docker-deploy-implementation.md`. - -### Archived snapshot — Runtime incident fixes (2026-07-13) - -- The bind-mounted Pi profile came from host paths and did not trust `/app/harness`. - Pi 0.80 consequently loaded **zero** project extensions, prompts and skills, silently - sending `/nuova-domanda`/`/riprendi-sessione` to the model as plain text. The core - entrypoint now idempotently adds only `/app/harness` to the persistent - `/home/thoth/.pi/agent/trust.json`, preserving all existing decisions. -- The gate embeds the canonical `tht-sessione/SKILL.md` in the one-shot kickoff system - prompt and explicitly prohibits repository discovery. A live RPC `get_commands` must - show `torna`, `nuova-domanda`, `riprendi-sessione`, and `skill:tht-sessione` after deploy. -- Workspace identity is derived from the resolved config path, so - `config/tht.yaml -> workspaces/local.yaml` matches DWH artifact ownership (`local`). -- Direct pgvector now discovers the actual namespaces of the `vector` type and cosine - operator from PostgreSQL catalogs. This supports server layout `vectors.*` tables with - the extension installed in `public`. -- Live verification: session `2026-07-13-074712-dammi-la-lista-dei-pazienti-che-haoo-fat` - resumed directly at F1, ran `tht session show`, and completed `tht search pack` - (12 tables, 0 evidence, 2 solved) without repository exploration or adapter errors. - -### Archived snapshot — Workflow/UI regression fixes (2026-07-14) - -- **F1 Model Activity restored.** Session create/resume now preserves configured/persisted - thinking instead of forcing `off`. Pi's nested `thinking_delta` is bridged to a dedicated - named SSE `activity_delta`; EventSource subscribes to that name and the panel keeps it separate - from final assistant text. Reasoning remains in-memory and is not persisted to session artifacts. -- **F3 rewrite confirmation remains bypassed.** `rewrite_question` records approval and advances - automatically without a reviewer widget. The repeated prompt came from old running containers: - images had been rebuilt but services had not been recreated. -- **Join review is read-only and complete-set safe.** Join-only proposals render informational - cards with only `Continue` and `Other — specify`. Continue requires the exact complete id set; - all joins are persisted together by `decision add-join-set`, using an atomic ledger replacement - under a per-session cross-process writer lock. Other persists none of the rejected proposal. -- **CTE presentation fixed.** F6 CTE cards now structure purpose, rationale, tables, filters, keys, - and output columns with responsive wrapping/alignment. The Horizontal/Vertical switch is hidden - for a single SQL block (the per-CTE view), because it only affects multi-block layouts. -- **Latest render failure diagnosed and hardened.** Session - `2026-07-14-115847-estrai-i-pazienti-che-hanno-fatto-un-abl` sent an object in - `open_questions`, which React cannot render as a child. The v2 gate now enforces - `open_questions?: string[]`; the frontend also safely normalizes legacy malformed payloads. -- **Verification/deploy:** Python harness 798 passed / 5 L2 deselected; gate JS 126; backend 143; - frontend 250; TypeScript/build gates green. Compose rebuilt and force-recreated both services. - Running image ids: core `sha256:55acef2f12151ea97144c2f5e9164d63f2ca734bc2746fef553df94849e3fb3f`; - frontend `sha256:1043f79392420149655cc63d70461e2ca2005b2290a1e3e21dcf845ec3bd1c81`. - -### Archived snapshot — Pi-enabled model selector (2026-07-14) - -- **Pi is the allowlist authority.** `/models` reads the mounted Pi `enabledModels`, intersects - it with models currently available from Pi, and preserves the configured order. Enumeration - does not require `PI_PROVIDER`, does not inject generic/provider credentials, and fails closed - for missing or malformed scope. -- **Live scope:** exactly `deepseek/deepseek-v4-flash`, `zai/glm-5.2`, and - `local-qwen/qwen3.6-35b-a3b`. The live endpoint returned those three composite IDs once each and - in that order; `zai/glm-5v-turbo` and all other authenticated Pi models are hidden. -- **Validation/process smoke:** live settings updates returned 200 for DeepSeek Flash and local - Qwen, while hidden GLM-5V returned 400; a post-restore equality check confirmed the original app - settings were restored. The real `PiProcessManager` configure path succeeded for DeepSeek and - local Qwen without sending a prompt or starting a DWH operation; local Qwen required no hosted - provider key. Unknown and compound providers remain fail-closed in the verified backend suite. -- **Verification/deploy (`2026-07-14T19:24:22+02:00`):** backend **154/154** and frontend - **251/251** passed; both TypeScript gates and `git diff --check` were green. Compose built and - force-recreated only `core`; container start was `2026-07-14T17:24:01.992971976Z`, health was - `healthy`, and sanitized post-recreate logs contained only the backend listen line. Rebuilt image - ID and running container image ID both equal - `sha256:577f99754fd0731251c8ddd8608b1b8baee09d02fad66c759b23f8221083e676`. - -### Archived snapshot — Qwen connectivity + state-aware Resume recovery (2026-07-14) - -- **Pi turns have an explicit lifecycle.** The bridge tracks `idle`, `running`, `waiting`, - and `failed`; a reviewer gate is `waiting`, responses/steering return to `running`, and an - assistant provider error or unexpected Pi child exit becomes `failed`. Provider error details - are never forwarded to the client; the UI receives a fixed sanitized recovery message. -- **Resume preserves only active work.** `running`/`waiting` runtimes return as already active. - Every validated cold path—including recovery after a child has already exited—clears stale SSE - state before reopening and restarts from persisted provider/model/thinking with - `/riprendi-sessione`; `idle`/`failed` runtimes are torn down at that point. Failed validation does - not detach the existing stream. A successful Resume of the currently selected session also - closes and recreates its EventSource, so the replacement runtime cannot be left behind an old - same-ID stream. -- **Private Qwen routing is live.** Core is attached to both `omics_portal_omics_network` and - external `localllm_default`; frontend remains only on the portal network. The mounted Pi profile - resolves `local-qwen/qwen3.6-35b-a3b` at the sanitized base URL - `http://localllm-vllm:8000/v1`. A direct probe from core verified the model catalog and received - a non-empty real chat completion. -- **Verification/deploy (`2026-07-14T21:41:52+02:00`):** backend **168/168** and frontend - **256/256** passed; both TypeScript gates, both production builds, the Qwen Compose network - contract, and `git diff --check` exited 0. The initial deployment built and force-recreated - `core` and `frontend`; after the final crash-recovery review, only the affected `core` image was - rebuilt and force-recreated with no active Pi session. Core is healthy and its post-recreate - Qwen catalog/completion probe succeeded. Built and running image IDs match: core - `sha256:9867c2fa002b6f117da9a1d02c73b47bfe0372b8c1c137a5174c3e7ecb1e1db1`, frontend - `sha256:5a47f81bc887423e05cef8fd3feb075aa600cb33217247186124f60ca5a3005b`. - The frontend entry hash changed, so only `omics_portal-web-1` was restarted to invalidate its - indefinite Vite-manifest cache. The application-level Qwen smoke reached its first - `ui_request`, persisted the expected provider/model, deleted only its uniquely named smoke - session, restored the exact saved settings object, and left no smoke session or Pi runtime. The - supplied probe's success path left its keep-alive SSE reader open, so only that probe process was - terminated (exit 143), without touching backend, Pi, or unrelated runtimes. The same smoke then - exited 0 with `controller.abort()` in cleanup, preserving the gate, session cleanup, and exact - settings-restoration evidence. - -### Archived snapshot — Complete activity timeline + CTE spacing (2026-07-15) - -- **Model activity is complete from F1.** The left panel now records the submitted prompt before - session creation completes, then projects thinking, assistant output, sanitized tool lifecycle, - reviewer gates, status, and turn lifecycle in chronological order. It remains in-memory only; - closing and reopening the panel does not discard it, while Resume intentionally starts a fresh - live timeline. -- **Tool activity is a narrow public contract.** Only call id, tool name, and - `running`/`completed`/`failed` status cross Pi → backend → SSE. Updates, arguments, results, - commands, output, credentials, and raw errors stay server-side. Resume and SSE replay were also - hardened for process restarts, concurrent lifecycle requests, stale callbacks, cursor reset, and - multi-client reconnects. -- **CTE plan layout uses real Tailwind 3 spacing.** Shared cards use concrete 16 px default / 12 px - compact padding utilities; F6 CTE headers and content use responsive 16/20 px edge padding. - Semantic ordered steps, single-boundary divided filter/table lists, long-value wrapping, and a - plain top-divider rationale preserve the artifact content while improving scanability. -- **Final verification/deploy (`2026-07-15T02:18:54+02:00`, HEAD `56d73d2`):** backend - **204/204** and frontend **285/285** passed; both TypeScript gates and production builds exited - 0, and `git diff --check` was clean. The final lifecycle fixes make restarted-hub cursor replay - generation-aware and mutate frontend delete/resume state only for sessions actually deleted. - Compose rebuilt and force-recreated `core` and `frontend`; built and running image ids match: - core `sha256:edd8f19ef269ee6f45ecaf464ba4053460d94378f9cdc967d2dbcb386f599147` - (`healthy`), frontend - `sha256:dd7ef721b661b57b8c5422c47088e1a9a2e9821af021541cab372c9892fbd638` - (`running`). The entry changed from `index-DcZviApa.js` to `index-CuIt1NQg.js`, so only - `omics_portal-web-1` was restarted to refresh its indefinite manifest cache. -- **Final live local-Qwen smoke:** session - `2026-07-15-001922-final-no-thinking-activity-smoke-2026-07` observed **0** - `activity_delta` events while receiving **5** strictly allowlisted tool lifecycle events and the - first reviewer gate (`bash` running/completed and `reviewer_select` running). No forbidden tool - field crossed SSE. Cleanup closed with 200, deleted only that session with 204, restored the - exact settings object, and left no Pi runtime or smoke session. - -### Archived snapshot — Filtered Model activity projection (2026-07-15) - -- **Resolved contract.** `activityLog` still folds the complete in-memory prompt, thinking, - assistant, sanitized tool, reviewer-gate, status, and turn-lifecycle history. The left panel now - applies a default-deny rendering boundary and shows only prompt, thinking, status, and gate; - assistant text remains available to the central transcript, while tool, lifecycle, and unknown - future activity kinds do not render or move the panel scroll. -- **Frontend-only verification/deploy (`2026-07-15T03:44:02+02:00`, source HEAD `7208599`):** - frontend **287/287** passed; `npx tsc -b`, `npm run build`, and `git diff --check` exited 0. - Compose rebuilt and force-recreated only `frontend`; its image changed from - `sha256:dd7ef721b661b57b8c5422c47088e1a9a2e9821af021541cab372c9892fbd638` to - `sha256:75fc0b7786c75ded1b488e9fad3232aa061c82d89140c67ad62b5285954d1d36`, with container start - `2026-07-15T01:42:45.582760612Z`. The active Vite entry changed from - `index-CuIt1NQg.js` to `index-BdZpFO7j.js`, so only `omics_portal-web-1` was restarted at - `2026-07-15T01:42:53.715330158Z`; core retained image - `sha256:edd8f19ef269ee6f45ecaf464ba4053460d94378f9cdc967d2dbcb386f599147` and start - `2026-07-15T00:18:37.040145636Z`. -- **Real local-Qwen no-COT smoke:** session - `2026-07-15-014328-activity-filter-smoke-2026-07-15t01-43-2` reached its first reviewer gate - with **0** `activity_delta` events and **3** tool lifecycle events, each containing exactly the - four public fields. The probe accepted the close response, deleted only that session with 204, - restored the exact saved settings object, confirmed the session absent, and left no Pi runtime. - -### Archived snapshot — Central activity log + compact CTE density (2026-07-15) - -- **Resolved UI contract.** The central working body now renders every chronological non-blank - assistant transcript line in one bounded accessible log, without user-entry echoes, - timer/spinner labels, or step messages. The left Model activity panel is a default-deny - projection of only thinking and status, while the complete raw activity fold and the existing - reviewer widgets, artifacts, and workflow state remain unchanged. F6 CTE headers, content, - table rows, and filter rows use 8 px vertical padding with 12 px lateral padding below `sm` and - 16 px from `sm` upward; divider top padding is 8 px. The final review amendment keeps historical - log rows at the full muted-foreground token so their normal-size text retains AA contrast. -- **Source verification (source HEAD - `09f9bdffe582ff3c66845ca219f60c11472a550a`).** Frontend tests passed **292/292** across - **43/43** files. `npx tsc -b`, `npm run build`, the Impeccable layout detector, and - `git diff --check` all exited 0; the detector returned `[]`. -- **Frontend-only deployment.** The pre-deploy frontend was image - `sha256:8c9aaee6453b26c69e4057d3f9e53aa791d449b88ba4a0669a25cd442667d582`, started - `2026-07-15T10:17:16.919166255Z`, serving `index-CveSyban.js`. Compose built and - force-recreated only `frontend` with `--no-deps`; the final running frontend is image - `sha256:39dc47d81abcb13466218500476fbb78d1be66a424f4293470437700c848c26d`, started - `2026-07-15T10:30:30.869532521Z`, serving `index-CihtpQJV.js`. Because the entry changed, - exactly `omics_portal-web-1` was restarted: it retained image - `sha256:4580cf2bc85f3656ee515996c24ed02d9096d24ed0d8afe384a2f8bd8cf4bac9` and moved from - start `2026-07-15T10:17:36.151611451Z` to `2026-07-15T10:30:46.369205604Z`. -- **Isolation and final state.** Core remained `running`/`healthy` with exactly its original image - `sha256:edd8f19ef269ee6f45ecaf464ba4053460d94378f9cdc967d2dbcb386f599147` and start - `2026-07-15T00:18:37.040145636Z`; frontend and portal were `running` with no container - healthcheck. Pre/post `docker top` showed only core's supervisor and backend server, so no - unrelated Pi runtime existed to disturb. The count-only frontend sensitive/error pattern scan - was **0**. No live model smoke was run, and settings and sessions were intentionally untouched. - -### Archived snapshot — Resizable activity split + compact CTE rows (2026-07-15) - -- **Resolved UI contract.** `activityLog` remains the complete in-memory chronological fold. The - left Model activity panel default-denies every kind except prompt, thinking, and assistant, - labels those entries Question, Reasoning, and Response in source order, and hides status, tool, - gate, lifecycle, and unknown kinds. The desktop panel is pointer/keyboard resizable from 288–576 - px while preserving 512 px centrally, persists its global width in localStorage, and becomes an - overlay drawer below `lg` or whenever the measured app shell is narrower than 800 px. F6 CTE - cards retain their semantic structure and responsive grids; - lateral padding is 12/16 px, header/content edge padding is 8 px, internal section gaps are 12 - px, heading/divider spacing is 4 px, and table/filter rows use 4 px vertical padding with compact - line heights. -- **Source verification (`2026-07-15T15:22:17+02:00`, source HEAD - `f1af1f909b387ae12a10f1b534bf6a529ea42505`).** Frontend tests passed **295/295** across - **44/44** files. `npx tsc -b`, `npm run build`, and `git diff --check` exited 0; the Impeccable - layout detector returned `[]`. The local source build emitted Vite entry - `assets/index-PlvQqhNG.js`. -- **Frontend-only deployment.** The pre-deploy frontend was image - `sha256:39dc47d81abcb13466218500476fbb78d1be66a424f4293470437700c848c26d`, started - `2026-07-15T10:30:30.869532521Z`, serving `index-CihtpQJV.js`. Compose built and force-recreated - only `frontend` with `--no-deps`; the final running frontend is image - `sha256:0947211373784a860c7507d03c0fcf1f901ac3d1547cd0aa62b914d158f15bd5`, started - `2026-07-15T13:21:08.29613952Z`, serving `index-Dn7T524a.js`. Because the entry changed, exactly - `omics_portal-web-1` was restarted: it retained image - `sha256:4580cf2bc85f3656ee515996c24ed02d9096d24ed0d8afe384a2f8bd8cf4bac9` and moved from - start `2026-07-15T10:30:46.369205604Z` to `2026-07-15T13:21:21.968808414Z`. -- **Isolation and final state.** Core remained `running`/`healthy` with exactly its original image - `sha256:edd8f19ef269ee6f45ecaf464ba4053460d94378f9cdc967d2dbcb386f599147` and start - `2026-07-15T00:18:37.040145636Z`; frontend and portal were `running` with no container - healthcheck. Pre/post `docker top` showed only core's supervisor and backend server, so no - unrelated Pi process existed and no Pi process was stopped or steered. The count-only frontend - sensitive/error pattern scan was **0**. No live model smoke was run; settings and sessions were - intentionally untouched. - -### Archived snapshot — Final activity-split fix (2026-07-15) - -- **Source and verification (`2026-07-15T15:56:57+02:00`).** Deployed source commit - `1f540fcb78ac9e552e56a21e47edf66e9872b323` (`1f540fc`). Frontend Vitest passed **298/298** - tests across **44/44** files; `npx tsc -b` and `npm run build` exited 0. The Impeccable detector - scoped to AppShell, ModelActivityPanel, index.css, and CtePlanViewer returned `[]`; `git diff - --check` exited 0. -- **Frontend-only deployment.** Compose built and force-recreated only `frontend` with `--no-deps`. - The frontend image changed from - `sha256:0947211373784a860c7507d03c0fcf1f901ac3d1547cd0aa62b914d158f15bd5` to - `sha256:6e14f55092b7e3aca9a396220394ae484147674d81b051771e394e59b73b1c88`; its active Vite entry - changed from `index-Dn7T524a.js` to `index-BIznZeLH.js`. Therefore exactly - `omics_portal-web-1` was restarted to refresh its manifest cache; it retained image - `sha256:4580cf2bc85f3656ee515996c24ed02d9096d24ed0d8afe384a2f8bd8cf4bac9` and started at - `2026-07-15T13:56:32.786693915Z`. -- **Isolation and final state.** Core retained image - `sha256:edd8f19ef269ee6f45ecaf464ba4053460d94378f9cdc967d2dbcb386f599147` and exact original - start `2026-07-15T00:18:37.040145636Z`, remaining `running`/`healthy`. Final frontend and portal - states are `running` (no healthcheck). Pre/post core process tables contained only the supervisor - and backend server, so Pi was preserved and no Pi process was stopped or steered. The count-only - frontend sensitive/error-pattern scan was **0**. No model smoke was run; settings and sessions - were intentionally untouched. - -## What ThothII is - -A **human-in-the-loop datamart builder**: it turns a natural-language question into -validated SQL (and optionally a dbt datamart) through a deterministic **8-phase -NL→SQL workflow**, where the model *proposes* and a human *reviewer decides* at gates. -The UI is meant to embed inside the Omics Portal (GSD design system) and is **English**. - -## Architecture — three layers - -``` -frontend (React, :5173) → backend (Fastify, :8787) → pi --mode rpc → tht / harness → DWH (read-only) +```sh +tht --installation /absolute/path/thothii-installation.yaml workspace preprocess evidence +tht --installation /absolute/path/thothii-installation.yaml workspace preprocess dwh ``` -- **harness/** — the Pi layer. A deterministic Python CLI **`tht`** + a Pi gate extension - (`.pi/extensions/tht-gate.js`) that runs the 8-phase workflow and emits/consumes - widget-descriptor JSON. **Owns all persistence.** Workflow truth is `harness/workflow.yaml`; - orchestration rules are `harness/.pi/skills/tht-sessione/SKILL.md`. -- **backend/** — Fastify + TypeScript. A **thin bridge**: proxies REST routes to the `tht` - CLI (`ThtRunner`), manages Pi processes (`PiProcessManager`, one child per session), - bridges Pi RPC events to SSE (`SessionBridge` + `SseHub`). No application database. -- **frontend/** — React 18 + base-ui + Tailwind + TanStack Query + Zustand. Chat-style - shell (`src/shell/AppShell.tsx`); the live transcript is rebuilt in-memory from the SSE - stream (`src/store/sessionStore.ts`), **not persisted**. +These commands use the profile-gated `workspace-maintenance` service. The former standalone +preprocessing Compose fixtures are retired. -### Persistence model (the load-bearing premise) -There is **no verbatim chat store**. Each workflow phase persists its own document into the -session directory, and that **IS** the persistence. A session = a directory under the -workspace's `sessions/` path containing `session_manifest.yaml` + phase artifacts -(`question.md`, `schema_linking.json`, `cte_plan.json`, `sql_final.sql`, -`validation_report.md`, `review_decisions.jsonl`, …). A fresh Pi process resumes by reading -`tht session show ` + the on-disk artifacts — never by replaying chat. +Workspace descriptors use schema v3. For PSD, workspace content and runtime roots point to the +separate uncommitted repository `/Users/mp/projects/tht-workspace-psd`. Secrets remain outside +Git and are supplied only through installation-local protected files. -## The 8 phases (harness/workflow.yaml) -F1 chiarimento · F2 memoria · F3 riscrittura (`question.md`) · F4 schema_linking -(`schema_linking.json`) · F5 sintesi · F6 cte (`cte_plan.json`, `cte_tests.json`) · -F7 sql_finale (`sql_final.sql`) · F8 datamart. Current phase is a fold over the decision -ledger (`harness/tht/phase.py`); statuses: `open` / `closed` / `finalized`. +## Active deployment work and manual gates -## How to run +### PSD server deployment program -**Full stack (real Pi + DWH):** from project root, -```bash -./scripts/run-stack.sh -# Opens frontend: http://localhost:5173 (proxies backend :8787) -``` -**Prereqs:** VPN on; `pi` on PATH (with a configured model, e.g., `pi model set claude-fable-5`); -`harness/.env` populated (see `.env.example`); `harness/config/tht.yaml` → workspace (psd recommended for testing). -All three layers' deps installed (`npm install` in each, `python -m venv + pip install -e ".[dev]"` in harness). +The approved design and executable entry point are: -**Individual dev:** -- backend: `cd backend && npm run dev` (tsx watch; env: `PORT`, `THT_HARNESS_DIR`, `THT_BIN`, `PI_BIN`, `AUTH_MODE`) -- frontend: `cd frontend && npm run dev` (Vite; `VITE_BACKEND_URL` → backend) -- harness install: `cd harness && python -m venv .venv && pip install -e ".[dev]"` → `tht` on PATH +- `docs/plans/2026-08-20-psd-server-deployment-program-design.md` +- `docs/plans/2026-08-20-psd-server-deployment-program.md` +- `docs/plans/2026-08-20-psd-server-survey.md` +- `docs/plans/2026-08-20-psd-server-project-a-standalone.md` +- `docs/plans/2026-08-20-psd-server-project-b-authentik.md` -## How to test (latest TS gates green 2026-07-15: backend 204 / frontend 292 (43 files); harness 798 / gate JS 126 last recorded 2026-07-14) -- harness: `cd harness && .venv/bin/pytest -q` (5 L2/real-DB tests are deselected by default) -- backend: `cd backend && npx vitest run` · typecheck `npx tsc --noEmit -p .` -- frontend: `cd frontend && npx vitest run` · typecheck `npx tsc -b` · e2e `npm run e2e` (Playwright) +Last recorded state: -## Config & workspaces -- Workspaces: `harness/workspaces/*.yaml` (`psd`, `tht-test`, `tht.example`). A workspace sets - the DB target and the **absolute** `paths.sessions/artifacts/indexes` (psd → a *separate* - repo `tht-workspace-psd/`, NOT committed here). -- Secrets live ONLY in `harness/.env` (gitignored; `THT_*` — DB, DWH REST, vector, SSL CA…). - See `harness/.env.example` for the variable list. -- App settings (global): `{ workspace, provider, model, thinking }`, persisted via harness - preferences (`tht session preferences get/set` → the configured session repository — - filesystem or Postgres in server mode). `backend/data/settings.json` (gitignored) remains - only the file fallback for injected runners/tests. The "New session" form is question-only; - these settings supply the rest. +- survey: `SURVEY_NO_GO`; +- Project A: `BLOCKED_BY_SURVEY_AND_MUTATION_GATE`; +- Project B: `BLOCKED_BY_PROJECT_A_AND_PRE_B_GATE`. -## Efficiency levers (NL→SQL workflow optimization, 2026-07-08) +The deployment is a clean replacement: legacy sessions, indexes, and application configuration +are not migration inputs. The existing stack remains intact until its documented mutation and +rollback gates are explicitly approved. Shared Omics/LocalLLM networks, ETL Evidence, DWH, +`dwh-auth`, Supabase, Authentik, Superset, and Aritmolab are outside cleanup scope. -Three deployed optimizations target model thinking time (the dominant cost, ~220s in F1 alone): +Human acceptance guides and sanitized report templates live under `docs/testing/` and +`docs/testing/evidence/`. The remediation checklist is +`docs/operations/psd-server-survey-remediation-checklist.md`. -1. **Join-graph via FK annotations + `tht schema suggest-fks`** - - DWH has no FK constraints declared. Annotations file (`tht-workspace-*/artifacts/mschema/annotations.yaml`) now stores curated logical FKs. - - Three ranking rules: mine from approved SQL (highest confidence), heuristics (`*_time_key → dim_time.day_key`), same-name PK discovery with `--assume` flag for disambiguity. - - **Psd workspace:** 228 FK suggestions already generated (139 tables); `tht schema suggest-fks --from-sql --assume cod_paz=dim_patient` for updates. - - **Activation:** automatic. The mschema renderer populates the `【Foreign keys】` section. F4 in SKILL.md now reads FK joins from there instead of the model re-deriving them. +### Authentication -2. **Context-pack consolidation at F1 kickoff (`tht search pack`)** - - Single embedding of the question, reused for schema + evidence + solved-question searches. - - Command: `tht search pack "" --session ` → `sessions//retrieval_pack.md` (tabelle candidate, relevant evidence, solved exemplars). - - Graceful degradation: if Ollama or vector store unreachable (no VPN), sections are empty but exit 0 — session continues with live searches. - - **Activation:** automatic at next session. SKILL.md F1 now prescribes as first call; reduces exploratory turns. +The local/OIDC authentication remediation passed its automated review on 2026-08-18. Release and +PSD mutation gates remain governed by: -3. **Phase-summary recap auto-construction from session ledger** - - `tht session show --json` includes the full decisions ledger; `tht phase meta --json` exports decision types per phase. - - Gate appends deterministic `【Decisioni registrate in questa fase】` section to v2 phase-summary artifacts. - - Model authors only `summary` + `checks`; the gate fills the recap table from persisted state → exact by construction. - - **Activation:** automatic at next session and Pi restart. SKILL.md Disciplina 6 updated: model keeps output brief, gate enriches from catalog + ledger. +- `docs/architecture/authentication.md`; +- `docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md`; +- `docs/operations/psd-dwh-auth-rollout.md`; +- `docs/testing/authentication-manual-acceptance.md`. -**Tests:** 358 Python + 111 JS gate, all pass. L2 (live DWH) verification on psd workspace recommended when time permits. +Do not infer authorization for server, Nginx, Authentik, database, credential, or cutover changes +from an automated PASS. -## Conventions & contracts (don't relearn the hard way) -- **`-c`/`--config` is a PER-COMMAND option in `tht`** — append it AFTER the subcommand, - never globally (`ThtRunner.buildArgv` handles this). -- **`--json` output must be pristine** (only valid JSON on stdout). -- **UI strings are English.** Document *content* stays in the workspace language (Italian - for psd) because it's the real data; only chrome/labels are English. -- **Settings are global**, not per-question. -- TDD throughout; tests assert real behavior, not mocks. Frequent, scoped commits. -- Global user rules (`~/.claude/CLAUDE.md`): think before coding, simplicity first, surgical - changes, goal-driven verification. +## Verification status -## Active memory — F8 promotion gate + solved-question recall — SHIPPED, L2 pending (2026-07-07) +- The P1.1 workspace-directory registry and P2–P6 preprocessing workstreams are implemented and + have automated coverage. +- Evidence restructuring has a real PSD acceptance PASS as recorded above. +- L2 tests requiring real providers or remote databases remain opt-in. +- Server deployment, release, and owner-operated acceptance steps remain pending wherever the + referenced runbooks require explicit approval. -Two additions to close the loop on reusable memory, on top of the existing `tht memory -search` (Phase 2) reuse: +Run the layer-specific checks documented in `AGENTS.md`. For release-sensitive changes, also run +the repository contract scripts in `scripts/` and build the MkDocs site. -- **F8 promotion gate.** `reviewer_memory_promote` (Phase 8, called with only the session - id): the gate computes candidates deterministically via `tht memory promote --preview - --json` (the 3 reusable decision types, already excluding previously promoted/declined - ones) and shows a pre-selected checklist. Selected → `tht memory save-one` persists to - the vectordb + records `memory_promoted`; deselected → `memory_promotion_declined` - (ledger detail `seq:`) so it is never re-proposed. `tht memory promote`/`save-one` were - added to the gate's anti-bypass FORBIDDEN list (model must go through the gate tool). -- **Solved-question exemplars.** New vector kind `solved_question` reusing the existing - `memory` pgvector table (no server-side DDL); `harness/tht/memory/solved.py` does a one-row - upsert keyed by a hash of question+SQL. CLI: `tht memory solved-index` / `solved-search`. - `tht session finalize` auto-indexes the pair (best-effort: green line on upsert, cyan - "già aggiornata" on dedup no-op, yellow warning + the recovery command - `tht memory solved-index ` on failure). `SKILL.md` now prescribes calling - `solved-search` as reference-only context in F4 (schema linking), F6 (CTE plan) and F7 - (final SQL), and documents the finalize auto-index in "Session end". +## Operational invariants -**Pending L2 gate (not yet run — needs VPN + writer key):** one live end-to-end session on -workspace `psd` via `./scripts/run-stack.sh` to verify (a) the promotion checklist renders -pre-selected and persists selected/declined correctly, (b) finalize indexes the pair, -(c) `tht memory solved-search` returns it with sql + tables. - -**Fast-follow:** -- RestSearcher top-k dilution — **client-side DONE** (2026-07-07): `search_similar` manda - `kinds` alla RPC (filtro server-side esatto) con fallback automatico su server legacy - (404 → retry senza filtro, post-filter client). **Resta la migrazione server** della - funzione SQL `search_similar` (+`kinds text[] DEFAULT NULL`): istruzioni pronte in - `harness/docs/vector-rest-kinds-migration.md`; l'ordine di deploy è libero, ma fino - alla migrazione il filtro resta client-side e la diluizione persiste. -- ~~`tht memory solved-search` muore con traceback grezzo se il vectordb è irraggiungibile~~ - **DONE** (2026-07-07): degrada a warning di una riga su stderr, stdout puro (`[]` in - --json), exit 0 — copre VectorRestError/EmbeddingsError/OperationalError. - -## Review gates v2 — payload strutturati + viewer dedicati — COMPLETE (2026-07-07) - -Plan: `~/.claude/plans/prima-di-passare-ai-inherited-marshmallow.md`. Merged to `main` @ `2410f01` -(ff, pushed). Executed via subagent-driven-development (4 workstreams, task reviews, final -whole-branch review + fix wave). - -- **Contracts:** `artifact.data.schema_version: 2` for `cte_plan` / `cte_result` / `phase`, - built **deterministically by the gate** (catalog descriptions via `tht schema columns`; SQL - from `ctes/.sql`; preview rows persisted by `tht cte test`); the model contributes only - purpose/rationale/note. Non-v2 payloads fall through to the legacy renderers — old sessions - and `tools/replay/replay.json` keep working. -- **Harness (Python):** `CteTestRecord.preview_rows` (+ `_jsonable` coercer, ≤10 rows, cells - ≤200 chars); new read-only `tht cte info --session --json` (index/total from - `cte_plan.json`, same source as `next_cte`); `tht cte plan --doc -` writes - `cte_plan_doc.json` (chain documentation; `cte_plan.json` stays a load-bearing `list[str]`). -- **Gate (JS):** `gate/core/artifact-contracts.js` (soft validators → self-corrective - `textResult`, TypeBox untouched) + `gate/core/enrich.js` (pure, catalog lookups injected); - `prepareReviewerArguments` now coerces `artifact.data` too (GLM stringified-param - mitigation); `SKILL.md` Phase 5/6 + disciplines rewritten (plan via `reviewer_confirm - kind:"cte_plan"` with payload A; `cte_result` gates send THIN data only — never SQL/preview - as text). -- **Frontend:** `artifactV2.ts` types; `CtePlanViewer` (per-CTE cards + chain strip), - `CteResultViewer` (shiki SQL + AG Grid preview), `PhaseSummaryViewer` (checks + criteria - with the VALUES driving choices), `PreviewGrid` extracted from `ResultsPanel`, - `statusBadge.ts` shared success/warn/error tokens. -- **Replay:** v2 fixtures + `tools/replay/augment-review-gates.mjs`; `replay.json` regenerated; - offline visual pass ok (screenshots in the SDD scratch dir). -- **LIVE E2E (session `2026-07-07-011858`, GLM 5.2):** all 8 phases completed with the v2 - gates; session **finalized** (DWH validation battery green, needs VPN). -- **Bug found live + FIXED (`2410f01`):** infinite spinner at workflow end — the bridge dropped - Pi's `agent_end` (the ONLY end-of-turn signal) and `working` was released only by the next - gate, which the final turn doesn't have. Now: bridge maps `agent_end` → SSE - `system_event`; FE tracks `agentActive`; an unexpected Pi child exit notifies the client - (info error + synthetic `agent_end`). Memory: `pi-rpc-event-vocabulary`. -- **Open (non-blocking):** `tht.sqlcheck` maps table aliases by first occurrence (found and - worked around by the model in F6 — spawned as a separate task); one more live confirmation - that the spinner stops at F8 (the chain is unit-tested end to end). - -## F4 schema-linking column curation + look&feel v2 — COMPLETE (2026-07-06) - -Branches `feat/f4-schema-linking-column-curation` (PR #1) + `feat/frontend-lookfeel-v2`, landed -on `main` (`d942635` … `7491e8c`). The F4 gate (`reviewer_schema_linking`) presents -catalog-enriched tables/columns (descriptions from `tht schema columns`, hardened enrichment), -per-table columns modal (suggested pre-checked, suggested-first ordering + filter box); -decisions `column_promoted`/`column_excluded` + deterministic `tht session -sync-schema-linking` projection into `schema_linking.json`. Live-verified including the -clobber test (the model's joins write preserves curated columns). Look&feel v2: shadows/radii/ -mono labels, 70% gate modal, structured cards (colors untouched). Memory: -`thothii-visual-language-v2`. - -## Workflow contract hardening — COMPLETE (2026-07-01) - -Spec: `docs/superpowers/specs/2026-07-01-workflow-contract-hardening-design.md` · Plan: -`docs/superpowers/plans/2026-07-01-workflow-contract-hardening.md`. Merged to `main` @ `3dadc6f` -(pushed). Driven by analysis of Pi session `2026-06-30-165708` (GLM 5.2), where the model spent -~80% of its tool calls reverse-engineering the harness because `SKILL.md` mis-stated the -phase-advance contract — and Phase 6 was a hard dead-end. Three coordinated harness fixes (TDD): - -- **F6 CTE-approval dead-end FIXED.** The gate's `reviewer_confirm kind:"cte_result"` used to - register `cte_approved --subject phase:6`, which `decision_cmd` rejects (exit 5 — it needs a - real CTE name from the plan) → F6 could never close. New `tht cte next --session ` returns - the first unapproved plan CTE; the gate now approves **by name**. (`tht/cli/cte_cmd.py`, - `.pi/extensions/tht-gate.js`.) -- **`schema_linking.json` writer/validator.** `store.set_schema_linking` (validates against the - `SchemaLinking` model, THEN writes — no partial file) → CLI `tht session set-schema-linking - --file ` (exit 5 on bad JSON / ValidationError) → gate tool `write_schema_linking` - (stdin). Replaces the model hand-writing the F4 artifact + ad-hoc python validation. -- **`SKILL.md` corrected to match the code.** Only F2-empty / F6-skipped auto-advance - (`_AUTO_ADVANCE_PHASES={2,6}`); every substantive phase closes with `reviewer_confirm - kind:"phase"` (F7 is **two-step**: `kind:"sql"` records `sql_approved`, then `kind:"phase"` - advances). Fixed Discipline 2 + Phase 1/3/4, added a per-phase **cheat-sheet**, documented the - `SchemaLinking` shape. The old false "the reviewer_decide already advances" (F3) claim — the - exact cause of the observed thrash — is gone. - -Verified: harness pytest **281 passed** / 5 deselected, gate JS **34/34**, changed-files ruff -clean (the 36 `ruff check .` errors are pre-existing on `main`). Final whole-branch review -(opus): READY TO MERGE, no Critical/Important. Executed via subagent-driven-development -(implementer + task-review per task, final opus review). **DEFERRED (needs VPN): live F4/F6 -end-to-end** — resuming session `2026-06-30-165708` (stuck at F6) is the ideal live probe. - -## UI/UX redesign + Resume — COMPLETE (2026-06-30) - -Plan: **`~/.claude/plans/foamy-forging-dahl.md`**. Memory: `thothii-ui-redesign-inprogress.md`. -**All workstreams done and pushed to origin/main:** D + E @ `0eeb3f7`, B + C @ `b056ff3`, -F @ `cef9ae4`, A @ `0a13f71`, G @ `e8cdd00`(scope) + `cbb8e18`(results). Nothing pending from this -plan. Per-workstream detail below for reference. - -- **D — DONE** (`c12bdcd`): session display `name` = 3-5 Italian keywords via **YAKE** (no LLM), - derived in `tht session new` (CLI layer); `create_session` core unchanged (`name=None` default). - `yake` added to `harness/pyproject.toml`. TDD `tests/test_session_name.py`; harness 269 passed. -- **E — DONE** (`0eeb3f7`): rotating activity icon replaces the red dot in `CentralStatus` - (inline, clickable → opens the panel); `ModelActivityPanel` is a **5-line expandable - model-stream tail**; `WorkingSpinner` extracted to its own module; the separate spinner button - + orphaned `Transcript.tsx` removed. Frontend 87/87, tsc clean. **Live visual check DONE - (2026-06-30):** inline spinner opens the panel; 5-line collapsed tail; expand → full transcript. -- **B — DONE** (`b056ff3`): `WorkflowBar` is now colored **dots** F1..F8, no phase-name text - (amber-translucent=running, green=done, red=error, gray=pending; green connectors lead the active - dot). Each dot carries `data-state`. Error is lightweight: store `phaseError` set when an `info` - `level=error` arrives during the phase, cleared on the next `ui_request` (`sessionStore.ts`). - **All four states live-verified** via Playwright. -- **C — DONE** (`b056ff3`): right sidebar — single-line denser rows (inline status dot + name, - `py-1`), a 3-level type hierarchy via **`/impeccable`** (L1 `SESSIONS` red/bold/wide-tracking · - L2 section + group headers muted uppercase · L3 names normal-case), and the **"No group" label - removed** (ungrouped sessions render after the last group; guarded so the empty-state still - teaches when there are no groups). **Live-verified.** (Resume in `SessionMenu` stays with A1.) -- **Tests:** frontend **93/93** (was 87; +3 store `phaseError`, +2 `WorkflowBar` dot-state, +1 - AppShell no-"No group"), `tsc -b` clean. -- **F — DONE** (uncommitted; live check deferred to G): single-select answers **auto-confirm**. - `reviewer_select` options may carry a `decision` payload (`{type, subject, detail?, rationale?}`) - and an optional `advance`; picking such an option persists the decision directly via - `tht decision add` (shared `decisionAddArgs` helper, also used by `reviewer_decide`) — no redundant - `reviewer_decide`/`reviewer_confirm` gate. Options without a payload stay ask-only; back/exit/Other - never persist. Pure logic extracted to `resolveSelectOutcome`/`decisionAddArgs` (exported, unit- - tested). Contract docs updated: `reviewer_select` tool desc + `SKILL.md` (widget summary, - disciplines 2-3, Phase-1 single-pick) + the `CLAUDE.md` gate note. Gate JS **33/33**, harness 269. - **Live verification (model actually uses `reviewer_select`+decision, no follow-up gate, decision in - `review_decisions.jsonl`) deferred to G** — it is model-behavior-dependent. -- **A — DONE** (uncommitted): **A1** — `SessionMenu` gains a **Resume** item (gated to - `status!=="finalized" && !archived`), wired in `AppShell` to the existing `doResume` → `POST - /sessions/:id/resume`. 3 tests (`SessionMenu.test.tsx`); frontend **96/96**, tsc clean. **A2** — - diagnosis-first clean-room repro shows the **resume cold-start stall NO LONGER reproduces on pi - 0.79.4** (8/8 chained into the tool calls, fresh + partway; GLM 5.2 now narrates AND emits - `tht session show`+`read SKILL.md` in-turn). The earlier narrate-and-stop predates the pi upgrade. - Defense-in-depth applied: `RIPRENDI_KICKOFF` hardened to force the in-turn tool call (gate test + - live regression 2/2). The cross-model angle (weaker/older models) lives in **G**. -- **G — DONE** (`e8cdd00`+`cbb8e18`): cross-model behavior matrix via a committed clean-room harness - (`harness/scripts/model-matrix.mjs`). **Tier 1** — kickoff + resume first-turn: all *available* - models chain in-turn (`zai/glm-5.2`, `deepseek/deepseek-v4-{pro,flash}`, `aritmolab/qwen3.6-35b-a3b`, - `zai/glm-4.5-air`); the resume stall recurs on none (closes A's cross-model robustness). - `aritmolab/gemma4-26b-a4b` = **404 unavailable** at the endpoint (listed but not served) — infra - gap, not a workflow issue. **Tier 2** — F single-select auto-confirm verified live on `glm-5.2`: - answering the first `reviewer_select` persisted a `concept_clarified` decision **0→1** with **no - follow-up gate** (closes F's deferred live check). Full results: the G plan doc + memory - `thothii-cross-model-matrix`. No prompt hardening needed. - -**Status:** **All UI-redesign + resume workstreams done and pushed — D, E, B, C, F, A, G.** -Nothing pending from the plan. Optional nice-to-haves (not required): Tier-2 F/multiselect live for -the non-baseline models (cheap re-run with `harness/scripts/model-matrix.mjs` + the Tier-2 method), -and a one-off manual Playwright kebab→resume pass in the live UI. - -## Live verification + reviewer_select fix (2026-06-30, afternoon) - -Drove the real stack (Playwright → backend → real Pi → GLM 5.2 → DWH) end-to-end. - -- **F1 hang fix (`418187a`) VERIFIED LIVE.** Answered an F1 reviewer widget; Pi resumed (model - socket reopened) and the gate produced new output — vs the old silent hang. The transition - "silent hang → gate re-presents/advances" proves `ctx.ui.input` now resolves. -- **New bug found + fixed: reviewer_select `choices` vs `choice`.** The gate's `reviewer_select` - (and `reviewer_confirm` reject) read `resp.choice` (singular) but the frontend uniformly sends - `choices: [id]` (array) — so every single-select gate answered "Nessuna scelta ricevuta" and - re-proposed forever (multiselect was fine; it already read `choices`). Fix: a shared - `selectedChoice(resp)` helper (`harness/.pi/extensions/tht-gate.js`) reading the array; both - handlers use it. TDD: `gate/__tests__/gate_choice.test.js` RED→GREEN, full gate suite **28/28**. - VERIFIED LIVE: a single-select answer is now accepted and the workflow advances (2/4 → 3/4). -- **Resume cold-start STALL confirmed (open item #1).** On `/riprendi-sessione`, GLM 5.2 narrates - the bootstrap step then ends the turn without the tool call → Pi idle, unrecoverable from the UI. - Memory: `thothii-resume-cold-start-stall.md`. -- **GLM 5.2 F1 is slow (~3-4 min, ~50+ reads) but works** — looks stuck but isn't; don't hit - "Stop and save" (it `POST /close`s → kills Pi). Memory: `thothii-glm52-f1-slow-not-stuck.md`. - -## Earlier work — F1 reviewer-widget hang fix + multiselect guidance (committed 2026-06-30; authored 2026-06-29) - -Two fixes, **committed to `main`** (7 files): - -1. **Bug: every reviewer widget hung "stuck with no output" after the human answered** — F1 - disambiguation (and any gate) dead-ended. Root cause, confirmed from Pi's own source - (`@mariozechner/pi-coding-agent` `dist/modes/rpc/rpc-mode.js`, `createDialogPromise`): - `ctx.ui.input` assigns its OWN RPC id (`crypto.randomUUID`) and correlates - `extension_ui_response` on THAT id, silently dropping unknown ids. The gate puts a - different id (`u${Date.now()}`) inside the descriptor carried in `title`. `SessionBridge` - was replying with the **descriptor** id, so real Pi never resolved `ctx.ui.input` → the - model never continued. **Fix:** `SessionBridge` now stores Pi's top-level `m.id` - (`pendingPiId`) on the incoming request and replies `extension_ui_response{ id: pendingPiId, - value: }` (value still carries the descriptor id, so the gate's internal - `resp.id === descriptor.id` check holds). File: `backend/src/bridge/session-bridge.ts`. - Full write-up: memory `pi-ui-input-id-correlation.md`. - - **The test double was masking it:** `harness/tests/fake_pi/fake_pi_rpc.mjs` had forced - `m.id == descriptor.id`. Corrected to mirror real Pi (distinct `randomUUID` top-level id, - correlate on it, drop unknown ids); `test_fake_pi_contract.mjs` gained a negative - regression test ("respond with descriptor id → no follow-up"). - - TDD: `backend/test/session-bridge.test.ts` (unit) + `backend/test/e2e-f1.test.ts` - (integration — now asserts the model's follow-up arrives after the answer) went - RED→GREEN. - -2. **UX: multi-answer disambiguation** — `harness/.pi/skills/tht-sessione/SKILL.md` Phase 1 - now tells the model to use `reviewer_decide` (the existing multiselect/checkbox widget) - when an ambiguity admits several simultaneously-true answers, instead of single-pick - `reviewer_select`. Guidance-only — no new widget (`frontend MultiselectWidget` already - exists). - -Verified at commit time: backend `npx vitest run` **67/67 green**; `tsc --noEmit -p .` **OK**; -fake-pi contract `node --test test_fake_pi_contract.mjs` **2/2 green**. **Verified LIVE -2026-06-30** (see the top "Live verification" section). - -## Most recent feature — Session management (MERGED to main @ 2c21e46) -Full session management modeled on Claude's UI, all three layers: -- **Read-only "split view" panel** (left drawer, `SessionDocumentsPanel`) showing a session's - phase documents read-only (reuses `SqlViewer`/`SchemaLinkingViewer`/`MarkdownView`). -- **Rename / Move to group / Archive / Delete** via a kebab menu (`SessionMenu`) → REST → - `tht session set-name/set-group/archive/unarchive/delete`. Archive = a manifest `archived` - flag (not a dir move); groups = a manifest `group` field; delete = hard `rmtree` + confirm. -- Rail: collapsible group headers + "No group" + a separate **Archive** view. -- **Resume correctness:** read-only **guard** (HTTP 409 when `finalized` or `archived`); - `PiProcessManager.spawnFor` now has a `new`/`resume` mode (resume sends - `/riprendi-sessione `); a "Phase 0 — Resume" cold-start section in `SKILL.md`. -- Design docs: `docs/superpowers/specs/2026-06-29-session-management-design.md` + - `docs/superpowers/plans/2026-06-29-session-management.md`. - -### ⚠️ Open items / pending gates -1. **Resume cold-start stall — RESOLVED on pi 0.79.4 (workstream A, 2026-06-30).** The earlier - narrate-and-stop (GLM 5.2 narrating the bootstrap step then ending the turn without the tool - call) **no longer reproduces**: a clean-room repro of the backend's exact resume handshake - chained into `tht session show`+`read SKILL.md` in-turn **8/8** (fresh + partway sessions). The - pi upgrade is the likely fix. Defense-in-depth: `RIPRENDI_KICKOFF` hardened to force the in-turn - tool call (gate test + live 2/2). Memory: `thothii-resume-cold-start-stall.md`. **Remaining:** - the cross-model angle (older/weaker models) is folded into **G**; a full Playwright kebab→resume - pass through the live UI is still worth one manual run (item 2). -2. **Full Playwright live-stack verification (MANUAL, not yet run).** -3. **Minor backlog (non-blocking):** explicit id-traversal guard in `delete_session` - (today gated by `load_session`); `close_session` could reuse `_save_touched` (DRY); - delete-via-kebab integration test skipped (base-ui Menu portal not drivable in jsdom — - the dialog itself is unit-tested); a couple of test-file lint nits. -4. **DONE — F1 hang fix live-verified 2026-06-30** (see top section). The live verification - also surfaced + fixed the reviewer_select `choices` mismatch. -5. **Resolved: settings use `zai/glm-5.2`/medium** (not deepseek-flash); GLM 5.2 drives F1 - fine, just slowly (~3-4 min, ~50+ reads). To tell a truly stalled Pi from a merely-slow one, - check its sockets/children. Memory: `thothii-glm52-f1-slow-not-stuck.md`. -6. **DONE — Pi migrated to `@earendil-works/pi-coding-agent@0.80.3` (2026-07-04).** The old - scope `@mariozechner/pi-coding-agent` is frozen at 0.73.1; every release ≥0.74 lives under - the new scope `@earendil-works` (latest 0.80.3). The live `pi` (`~/.local/bin/pi`) was - repointed to 0.80.3. Validated by an API/RPC-surface diff (0.73.1→0.80.3: `ExtensionUIContext` - byte-identical, `rpc-types` additive-only, `createDialogPromise` + provider-registration API - unchanged) **plus** a live `model-matrix` smoke (GLM 5.2, `new`+`resume` both `CHAINED`, - full RPC event vocabulary incl. `extension_ui_request` intact). Notable: 0.80.3 adds - `ctx.mode: "tui"|"rpc"|"json"|"print"` (a proper mode discriminator; the earlier `0.79.4` - references above are superseded). Rollback: the old package is still on disk — repoint the - symlink to `@mariozechner/.../dist/cli.js`. Memory: `thothii-pi-earendil-migration.md`. - -## Where design history lives -- Specs: `docs/superpowers/specs/` · Plans: `docs/superpowers/plans/` -- SDD execution ledger (gitignored scratch): `.superpowers/sdd/progress.md` -- Auto-memory index: `~/.claude/projects/-Users-mp-projects-ThothII/memory/MEMORY.md` - (Pi RPC event vocabulary, ui.input id correlation, Omics Portal/GSD design system, - resume cold-start stall, GLM 5.2 F1 slow≠stuck). - -## Git -`main` @ `2410f01`, **pushed to `origin`** (github.com/mptyl/ThothII); working tree clean, no stashes. -Latest arc (2026-07-07): review-gates-v2 ff-merged — `9b4f6b9` (WS1 harness) · `3ad93cd` (WS2 -gate+SKILL) · `1c97289` (WS3 viewers) · `4042d0b`+`b089482` (WS4 replay) · `b59b57c` (review fix -wave) · `2410f01` (agent_end spinner fix). Branch `feat/review-gates-v2` still exists (local + -origin), fully merged. Before that (2026-07-05/06): F4 column curation (PR #1) + look&feel v2 — -`0d9e035` · `0a63ba9` · `d942635` · `9fe1c93` · `e9b2934` · `9403147` · `7491e8c`. -Older history (workflow hardening 2026-07-01, UI redesign 2026-06-30): see the sections above; -stale branches were pruned on 2026-06-30 (SHAs recoverable via reflog). +- `tht`'s `-c`/`--config` option follows the subcommand; it is not a global option. +- `--json` commands write pristine JSON to stdout. +- Persisted phase documents and the decision ledger are the source of session truth; chat is not. +- UI chrome is English; workspace document content retains the workspace language. +- The backend refuses resume for finalized or archived sessions. +- A resume must send `/riprendi-sessione `; a new session must send `/nuova-domanda`. +- DWH access is read-only. diff --git a/README.md b/README.md index 7a912f46..51b3a3ac 100644 --- a/README.md +++ b/README.md @@ -202,20 +202,18 @@ Startup mode adds bounded image build/two-service health startup, installation-a status, stopped-container-aware ownership checks, and exact cleanup. The ordinary hosted Windows job remains deterministic and does not claim Docker startup. -## Preprocessing jobs and S3 Evidence +## Workspace preprocessing and S3 Evidence -The included preprocessing services reuse the internal Qdrant/Ollama stack. Mount Evidence at -`/data/source/evidence`, then run the explicit preprocessing preset: +Run preprocessing through the native host CLI and the installation descriptor: ```sh -docker compose --env-file deploy/env/local.env \ - -f compose.yaml -f deploy/compose.local.yaml \ - -f deploy/compose.preprocess.yaml --profile preprocess run --rm preprocess-evidence +tht --installation /absolute/path/thothii-installation.yaml workspace preprocess evidence +tht --installation /absolute/path/thothii-installation.yaml workspace preprocess dwh ``` -Replace the final service with `preprocess-dwh` when required. The overlay makes each job wait for the internal Qdrant -service health checks and embedding model initialization; no separate semantic-service startup is -required. +The CLI starts the profile-gated `workspace-maintenance` service and enforces the workspace, +secret, Qdrant, and embedding contracts. See [Evidence](docs/evidence.md) and the +[workspace preprocessing CLI contract](docs/contracts/workspace-preprocessing-cli.md). S3 Evidence uses the optional `tht[s3]` dependency and canonical `s3://bucket/key` provenance. AWS endpoints are used when no custom URL is supplied. Every custom endpoint is an explicit egress diff --git a/backend/scripts/verify-workspace-descriptor-files.mjs b/backend/scripts/verify-workspace-descriptor-files.mjs index fd57a721..971bf230 100755 --- a/backend/scripts/verify-workspace-descriptor-files.mjs +++ b/backend/scripts/verify-workspace-descriptor-files.mjs @@ -15,9 +15,6 @@ const allowedKinds = new Set(["policy_text", "workspace_descriptor", "deployment // opener line through the closer line (including physical line endings). These // blocks are reviewed non-workspace runtime/config generation, not semantic proof. const reviewedExpandableBlocks = new Map([ - ["scripts/preprocess-smoke.sh", [ - { sha256: "fc530dc721c946644ab6552bbd46b7918d6c5f11f06f3495b6ea1fcda819b38d", rationale: "Generates the reviewed preprocess Compose override." }, - ]], ["scripts/test-dwh-auth-nginx-integration.sh", [ { sha256: "ead57234ad3520b5c7d4262b772957cbc7b9589da4f35fb17b160f948eb2ac7b", rationale: "Generates the reviewed isolated Nginx integration configuration." }, ]], diff --git a/backend/scripts/verify-workspace-descriptor-files.test.mjs b/backend/scripts/verify-workspace-descriptor-files.test.mjs index 97e4fe85..a66bc921 100644 --- a/backend/scripts/verify-workspace-descriptor-files.test.mjs +++ b/backend/scripts/verify-workspace-descriptor-files.test.mjs @@ -624,7 +624,6 @@ test("an in-band marker cannot authorize expandable content", async (t) => { test("current exact reviewed expandable blocks pass only at their trusted paths", async (t) => { const reviewedPaths = [ - "scripts/preprocess-smoke.sh", "scripts/test-server-pi-state-topology.sh", "scripts/test-vector-backup-restore-safety.sh", "scripts/test-windows-clone-contract.ps1", @@ -636,19 +635,6 @@ test("current exact reviewed expandable blocks pass only at their trusted paths" root: repositoryRoot, entries: reviewedPaths.map((path) => entry("deployment_script", path)), }); - - const root = await fixture(t); - const original = await readFile(join(repositoryRoot, "scripts/preprocess-smoke.sh"), "utf8"); - await put(root, "scripts/copied-preprocess.sh", original); - await assert.rejects( - verifyEntries({ root, entries: [entry("deployment_script", "scripts/copied-preprocess.sh")] }), - /exact-content reviewed allowlist/, - ); - await put(root, "scripts/preprocess-smoke.sh", original.replace('$tmp/smoke.yaml', '$tmp/other.yaml')); - await assert.rejects( - verifyEntries({ root, entries: [entry("deployment_script", "scripts/preprocess-smoke.sh")] }), - /exact-content reviewed allowlist/, - ); }); test("PowerShell tokenizer ignores opener text in comments and ordinary strings", async (t) => { diff --git a/brain/codebase/datamart-builder-deployment-gotchas.md b/brain/codebase/datamart-builder-deployment-gotchas.md deleted file mode 100644 index 8dbceec4..00000000 --- a/brain/codebase/datamart-builder-deployment-gotchas.md +++ /dev/null @@ -1,14 +0,0 @@ -# Datamart Builder deployment gotchas - -- Il percorso pubblico attraversa due reverse proxy: nginx host → nginx Omics Portal → core ThothII. -- Per SSE, ogni livello deve disabilitare `proxy_buffering`, `proxy_request_buffering` e cache, usare HTTP/1.1, timeout lunghi e propagare `X-Accel-Buffering: no`. -- Il core aggiunge `X-Accel-Buffering: no` alla risposta EventSource; Omics Portal lo riaggiunge esplicitamente per i proxy a monte. -- Una sonda utile deve attraversare il portale autenticato e misurare l'arrivo degli header `200 text/event-stream`, non solo interrogare il core nel network Docker. -- La configurazione nginx host attiva vive in `/etc/nginx/sites-available/policlinicosandonato`; validare con `nginx -t` prima del reload. -- Django può tenere in memoria il manifest Vite per worker: dopo un rebuild del frontend riavviare anche i worker Omics Portal, altrimenti richieste diverse possono produrre hash asset vecchi e nuovi. -- Nel profilo server legacy, `vector_db` è una connessione pgvector RW condivisa; il factory può riusarla come writer solo con `profile=server`. La workstation senza writer REST deve restare read-only. -- Non convertire in-place `local.yaml` da chiavi legacy a risorse moderne durante un incident fix: cambia il binding del workspace e può invalidare gli snapshot DWH attivi. -- `session_storage` è configurazione di persistenza delle sessioni, non degli artefatti DWH: escluderla dall'impronta in `config_dwh_binding`, altrimenti l'attivazione di profili utente rende incompatibile un indice DWH già valido. -- Con profili per utente, un profilo privato vuoto deve essere inizializzato una sola volta dai settings legacy completi; trattare `{}` come settings effettivi fa creare sessioni senza provider/modello e lo spawn Pi fallisce prima di partire. - -- Regola operativa concordata: dopo ogni modifica o enhancement, ricostruire e ricreare tutti i container ThothII coinvolti prima dell'handoff, quindi verificare che siano healthy affinché l'utente possa testare live. Il push Git non aggiorna le immagini Docker automaticamente. diff --git a/brain/codebase/pi-model-selection.md b/brain/codebase/pi-model-selection.md deleted file mode 100644 index 37a489bf..00000000 --- a/brain/codebase/pi-model-selection.md +++ /dev/null @@ -1,11 +0,0 @@ -# Pi model selection - -- `get_available_models` restituisce tutti i modelli con autenticazione/configurazione disponibile; non applica `settings.json.enabledModels`. -- Il selettore web usa l'intersezione esatta tra catalogo RPC e `enabledModels`, preservando l'ordine configurato e confrontando `provider/model`. -- In produzione `PI_PROVIDER` può essere assente: il provider corrente vive in `/data/settings/settings.json`; l'enumerazione Pi deve quindi essere provider-neutral e usare il profilo montato per l'autenticazione. -- Lo spawn di enumerazione deve comunque passare da `buildPiChildEnv({})` per rimuovere credenziali ambientali e metadati dei secret. -- `local-qwen` è un provider custom locale esplicito; non richiede la chiave generica dei provider hosted. Provider sconosciuti e composti restano fail-closed. -- Il profilo Pi live è montato da `/home/chirone/thothii-data/pi-config` a `/home/thoth/.pi`; non leggere né stampare mai i valori di `auth.json`. -- Il provider live `local-qwen` usa `http://localllm-vllm:8000/v1` e il modello `qwen3.6-35b-a3b`; il file montato conserva owner/mode e non contiene modifiche alle credenziali. -- In Compose solo `core` entra nella rete esterna `localllm_default`, oltre alla rete del portale; `frontend` non deve avere accesso diretto alla rete del modello. -- La connettività è verificata dal namespace di `core`: catalogo `/v1/models`, modello atteso presente e completion reale non vuota, senza stampare il testo della risposta. diff --git a/brain/codebase/psd-dwh-transport.md b/brain/codebase/psd-dwh-transport.md deleted file mode 100644 index a4391f88..00000000 --- a/brain/codebase/psd-dwh-transport.md +++ /dev/null @@ -1,20 +0,0 @@ -# PSD DWH transport - -- Il workspace PSD supporta `rest_api` e `postgres_direct`; il trasporto è scelto dall'installazione. -- Il Mac usa REST/PostgREST; il ThothII installato sul server PSD usa PostgreSQL diretto. -- Il server deve usare un ruolo DWH dedicato: `USAGE` sullo schema e `SELECT` soltanto, verificati sui grant reali. -- La difesa read-only applicativa aggiunge: SQL strutturalmente SELECT-only, transazione `READ ONLY`, timeout, limite e rollback. -- La credenziale DWH REST `X-API-Key` non deve essere fornita al ThothII server. -- REST è il trasporto stabile per il Mac e per future installazioni remote che non possono aprire tunnel SSH. -- L'autenticazione REST target deve dare a ogni installazione un'identità separata, revocabile e auditabile; una chiave globale condivisa non scala. -- La rotazione della chiave globale esposta richiede una finestra dual-key che preservi il Mac prima della revoca. -- Il certificato REST corrente resta invariato: è self-issued e viene presentato anche dall'endpoint esterno; i client che non lo considerano già trusted richiedono `TLS_CA_FILE`. -- Il manuale deve coprire consegna e fingerprint della CA, scadenza/rinnovo coordinato e il fatto che i SAN correnti coprono `.it`, non `.com`. -- Non esiste un ambiente di test PSD: le rotazioni devono usare backup, dual-key, probe read-only e rollback sull'endpoint di produzione. -- Supabase Studio è un pannello amministrativo loopback, non un data-plane o un trasporto per ThothII. -- Le credenziali DWH, session storage e amministrazione Supabase devono restare separate. -- Il collegamento container→PostgreSQL deve usare un endpoint host/rete esplicito e ristretto; il loopback dell'host non è il loopback del container. -- Il nightly ETL PSD delle 03:00 usa PostgreSQL diretto; non è un consumer della route REST `/dwh/`. -- Un preprocessing REST Thoth genera `1 + 3T + Ct + Ce` richieste: una lista tabelle, tre RPC per tabella e due famiglie di campionamento testuale. -- Per PSD nel run 2026-08-13: `T=163` e `Ct+Ce=1180`, quindi 1670 richieste per ciclo; undici rerun spiegano 18.370 richieste. -- I repository server esistenti contengono materiale sensibile hardcoded: non copiarlo; inventariare, rimuovere dal tracking e ruotare i segreti coinvolti. diff --git a/brain/codebase/workflow-ui-contracts.md b/brain/codebase/workflow-ui-contracts.md deleted file mode 100644 index bae08bb0..00000000 --- a/brain/codebase/workflow-ui-contracts.md +++ /dev/null @@ -1,44 +0,0 @@ -# ThothII workflow UI contracts - -- Pi reasoning arrives as nested `message_update.assistantMessageEvent.type = thinking_delta`. - The backend maps it to the named SSE event `activity_delta`; the frontend EventSource must - explicitly subscribe to that name. Model activity is separate from final `text_delta` output. -- Session create/resume must preserve the configured or persisted thinking level. Forcing - `thinking: off` disables the upstream signal and makes the activity panel legitimately empty. -- A join-only `reviewer_decide` proposal is one complete, atomic join set. The read-only - `join-review` widget persists every proposed join on Continue; `Other — specify` persists none - and requires the model to propose the complete corrected set again. Ledger read, sequence - assignment, and atomic replacement share a per-session cross-process writer lock. -- A v2 phase summary accepts `open_questions?: string[]`. Validate this at the gate boundary and - normalize legacy malformed entries defensively in the viewer so one object cannot crash React. -- `SqlViewer`'s horizontal/vertical layout control is meaningful only with multiple SQL blocks; - hide it for the single CTE result shown by `CteResultViewer`. -- A Pi turn is `idle`, `running`, `waiting`, or `failed`. A reviewer gate/request moves it to - `waiting`; the reviewer response and steering move it back to `running`; provider failures and - unexpected Pi child exits mark it `failed` without forwarding raw failure detail. -- Resume preserves `running`/`waiting` runtimes. After manifest/readiness validation, every cold - path clears old SSE buffer/subscribers before reopen—including when a crashed child has already - left no runtime—and reuses persisted provider/model/thinking. Failed validation does not clear. -- A successful Resume of the already selected session increments the stream generation so React - closes the old EventSource and opens the same session URL again. Failed Resume must not reconnect. -- SSE endpoints are intentionally keep-alive. Browser cleanup and one-off probes must explicitly - close the EventSource or cancel/abort the response reader after their terminal event. -- `activityLog` remains the complete in-memory chronological fold. The left Model activity panel - default-denies every kind except prompt, thinking, and assistant, presenting them as Question, - Reasoning, and Response in source order; status, tool, gate, lifecycle, and unknown kinds stay - hidden. Its desktop width is pointer/keyboard resizable from 288–576 px while preserving 512 px - centrally, persists globally in localStorage, and becomes an overlay drawer below `lg`. -- F6 CTE cards keep their semantic structure, responsive grids, 12/16 px lateral padding, and 8 px - header/content edge padding. Internal section gaps are 12 px, headings/dividers use 4 px spacing, - and table/filter rows use 4 px vertical padding with compact line heights. -- Pi tool events may cross the backend/client boundary only as call id, tool name, and - `running`/`completed`/`failed` status. Tool updates, arguments, partial/final results, commands, - raw output, and raw errors remain server-side. -- The frontend uses Tailwind CSS 3.4. Shared primitives must use concrete Tailwind 3-compatible - spacing utilities; Tailwind 4 custom-spacing syntax can compile to no effective padding here. -- A native EventSource can retain a `Last-Event-ID` from an older backend process. If that cursor - is newer than every id produced by the current `SseHub` generation, treat it as stale and replay - the fresh generation from id 0 instead of suppressing all new low-id events. -- Batch delete mutates client selection, active-session, panel, and Resume intent only for ids whose - DELETE actually succeeded. A failed active delete preserves its live binding, and deleting an - unrelated session must not invalidate a concurrent Resume targeting another id. diff --git a/brain/index.md b/brain/index.md deleted file mode 100644 index 15288d32..00000000 --- a/brain/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Brain - -- [[codebase/datamart-builder-deployment-gotchas]] -- [[codebase/pi-model-selection]] -- [[codebase/psd-dwh-transport]] -- [[codebase/workflow-ui-contracts]] diff --git a/deploy/compose.preprocess.yaml b/deploy/compose.preprocess.yaml deleted file mode 100644 index 4873ba99..00000000 --- a/deploy/compose.preprocess.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# Retired for operator use: this profile remains only as a non-public engine-fixture path. -# It exercises the legacy preprocessing fixtures and must not become a second operator interface. -services: - preprocess-evidence: - image: thothii-core:local - profiles: [preprocess] - build: - context: . - dockerfile: docker/core.Dockerfile - entrypoint: [sh, -ec] - command: ["mkdir -p /data/workspaces/preprocess-evidence && exec /app/docker/core-entrypoint.sh preprocess evidence --json -c /app/harness/workspaces/preprocess-evidence.yaml"] - environment: - THT_DATA_ROOT: /data - THT_SECRETS_FILE: /run/secrets/thothii.secrets - secrets: [{source: thothii_secrets, target: thothii.secrets}] - volumes: - - thoth_data:/data - - ./deploy/workspaces:/app/harness/workspaces:ro - restart: "no" - depends_on: - qdrant: - condition: service_healthy - embedding-model-init: - condition: service_completed_successfully - - preprocess-dwh: - image: thothii-core:local - profiles: [preprocess] - build: - context: . - dockerfile: docker/core.Dockerfile - entrypoint: [sh, -ec] - command: ["mkdir -p /data/workspaces/preprocess-dwh && exec /app/docker/core-entrypoint.sh preprocess dwh --steps introspect --json -c /app/harness/workspaces/preprocess-dwh.yaml"] - environment: - THT_DATA_ROOT: /data - THT_SECRETS_FILE: /run/secrets/thothii.secrets - secrets: [{source: thothii_secrets, target: thothii.secrets}] - volumes: - - thoth_data:/data - - ./deploy/workspaces:/app/harness/workspaces:ro - restart: "no" - -volumes: - thoth_data: diff --git a/deploy/workspaces/preprocess-dwh.yaml b/deploy/workspaces/preprocess-dwh.yaml deleted file mode 100644 index d2f3edff..00000000 --- a/deploy/workspaces/preprocess-dwh.yaml +++ /dev/null @@ -1,11 +0,0 @@ -language: en -dwh: - type: postgres_direct - connection: - host: "${THT_PREPROCESS_DWH_HOST:-dwh}" - port: "${THT_PREPROCESS_DWH_PORT:-5432}" - database: "${THT_PREPROCESS_DWH_DATABASE:-warehouse}" - schema: "${THT_PREPROCESS_DWH_SCHEMA:-public}" - user: "${THT_PREPROCESS_DWH_USER:-thoth_reader}" - password_file: "${THT_PREPROCESS_DWH_PASSWORD_FILE:-/run/secrets/preprocess-dwh-password}" -roots: {artifacts: artifacts, indexes: indexes, sessions: sessions} diff --git a/deploy/workspaces/preprocess-evidence.yaml b/deploy/workspaces/preprocess-evidence.yaml deleted file mode 100644 index 444b4844..00000000 --- a/deploy/workspaces/preprocess-evidence.yaml +++ /dev/null @@ -1,22 +0,0 @@ -language: en -dwh: - type: postgres_direct - connection: - host: "${THT_PREPROCESS_DWH_HOST:-unused}" - port: "${THT_PREPROCESS_DWH_PORT:-5432}" - database: "${THT_PREPROCESS_DWH_DATABASE:-unused}" - schema: "${THT_PREPROCESS_DWH_SCHEMA:-public}" - user: "${THT_PREPROCESS_DWH_USER:-unused}" - password_file: "${THT_PREPROCESS_DWH_PASSWORD_FILE:-/run/secrets/preprocess-dwh-password}" -vectors: - type: qdrant - base_url: http://qdrant:6333 - collection: preprocess-evidence -roots: {artifacts: artifacts, indexes: indexes, sessions: sessions} -evidence: {source_root: /data/source, evidence_dir: evidence} -embeddings: - provider: ollama_internal - base_url: http://embedding:11434 - model: qwen3-embedding:0.6b - dim: 1024 - batch_size: 32 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index bbb57813..5a4281b5 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,6 +1,9 @@ # Panoramica dell'architettura -> Sintesi ad uso documentazione. Per il dettaglio storico delle decisioni di design vedi le [Specifiche di Design](../superpowers/specs/2026-06-25-thothii-architecture-design.md) e i [Piani di Implementazione](../superpowers/plans/2026-06-25-harness-implementation.md). Per lo stato corrente del progetto (gate manuali pendenti, layout workspace/secret) vedi `PROJECT_STATE.md` nella radice del repo. +> Sintesi ad uso documentazione. Per il dettaglio dei moduli e dei flussi vedi +> [Componenti, moduli e flussi](components.md); i contratti correnti sono in `docs/contracts/` +> e le decisioni durevoli in `docs/adr/`. Per lo stato corrente del progetto (gate manuali +> pendenti, layout workspace/secret) vedi `PROJECT_STATE.md` nella radice del repo. ThothII è un **datamart builder human-in-the-loop**: trasforma una domanda in linguaggio naturale in SQL validato (ed eventualmente un datamart dbt) attraverso un **workflow deterministico a 8 fasi NL→SQL**, in cui il modello *propone* e un revisore umano *decide* ai gate. @@ -76,4 +79,4 @@ Lo stack locale si avvia con `./scripts/run-stack.sh`, dopo aver creato `deploy/env/local.env` da `deploy/env/local.env.example`. Il core Compose include Pi; DWH, vector DB, embedding e LLM sono endpoint esterni configurati nel file locale. -Comandi per singolo layer, test, lint: vedi il file `CLAUDE.md` nella radice del repo (guida operativa per Claude Code, tenuta sincronizzata con questa pagina). +Comandi per singolo layer, test e lint: vedi `AGENTS.md` nella radice del repo. diff --git a/docs/installazione-docker-4-contesti.md b/docs/installazione-docker-4-contesti.md index 08cd5db5..db043594 100644 --- a/docs/installazione-docker-4-contesti.md +++ b/docs/installazione-docker-4-contesti.md @@ -55,21 +55,16 @@ Una CA privata PEM resta esterna al bundle e va montata con un override Compose ## Preprocessing -I job di preprocessing usano gli stessi servizi interni Qdrant/Ollama: +Il preprocessing passa dal CLI host nativo e dal descrittore dell'installazione: ```sh -docker compose --env-file deploy/env/local.env \ - -f compose.yaml -f deploy/compose.local.yaml \ - -f deploy/compose.preprocess.yaml --profile preprocess run --rm preprocess-evidence +tht --installation /percorso/assoluto/thothii-installation.yaml workspace preprocess evidence +tht --installation /percorso/assoluto/thothii-installation.yaml workspace preprocess dwh ``` -Per introspezione DWH: - -```sh -docker compose --env-file deploy/env/local.env \ - -f compose.yaml -f deploy/compose.local.yaml \ - -f deploy/compose.preprocess.yaml --profile preprocess run --rm preprocess-dwh -``` +Il CLI esegue il servizio profile-gated `workspace-maintenance`. I dettagli sono nel +[contratto del preprocessing](contracts/workspace-preprocessing-cli.md) e nella guida +[Evidence](evidence.md). ## Server diff --git a/docs/operations/psd-dwh-auth-rollout.md b/docs/operations/psd-dwh-auth-rollout.md index 415c5e3e..c31f95fc 100644 --- a/docs/operations/psd-dwh-auth-rollout.md +++ b/docs/operations/psd-dwh-auth-rollout.md @@ -1,6 +1,6 @@ # PSD — rollout controllato DWH REST -Questo runbook rispecchia i Task 9–10 del [piano](../superpowers/plans/2026-08-20-dwh-rest-per-installation-auth.md). Gate A e la parte dual-key di Gate B sono stati eseguiti con autorizzazioni separate. L'emendamento del proprietario del 2026-08-21 rinvia collaudo Mac, osservazione e revoca a prima di Project B; non autorizza ulteriori mutazioni. +Questo runbook completa il [piano di accettazione autenticazione](../plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md) e il [programma di deployment PSD](../plans/2026-08-20-psd-server-deployment-program.md). Gate A e la parte dual-key di Gate B sono stati eseguiti con autorizzazioni separate. L'emendamento del proprietario del 2026-08-21 rinvia collaudo Mac, osservazione e revoca a prima di Project B; non autorizza ulteriori mutazioni. ## Invarianti diff --git a/docs/operations/psd-server-survey-remediation-checklist.md b/docs/operations/psd-server-survey-remediation-checklist.md index ec99119a..a94abd37 100644 --- a/docs/operations/psd-server-survey-remediation-checklist.md +++ b/docs/operations/psd-server-survey-remediation-checklist.md @@ -11,7 +11,7 @@ Fonti normative: - `docs/operations/psd-server-sol-orchestration-prompt.md` - `docs/plans/2026-08-20-psd-server-deployment-program.md` - `docs/plans/2026-08-20-psd-server-survey.md` -- `docs/superpowers/specs/2026-08-20-psd-survey-remediation-checklist-design.md` +- `docs/plans/2026-08-20-psd-server-deployment-program-design.md` Questo documento non autorizza modifiche a server, servizi, database, Nginx, load balancer, Authentik, Aritmolab o repository esterni. @@ -149,9 +149,9 @@ Authentik, Aritmolab o repository esterni. - il proprietario conferma che le sessioni, gli indici e le cache del vecchio ThothII erano solo test e non richiedono migrazione o attività di salvaguardia dedicate. Restano necessari il rollback della route DWH condivisa e il rispetto del gate esplicito prima di fermare lo stack; - - il proprietario ha revisionato e approvato la specifica scritta. Il piano eseguibile è in - `docs/superpowers/plans/2026-08-20-dwh-rest-per-installation-auth.md`; separa sviluppo e - verifica del componente dai due gate espliciti di mutazione PSD; + - il proprietario ha revisionato e approvato la specifica scritta. Il runbook eseguibile è in + `docs/operations/psd-dwh-auth-rollout.md`; separa sviluppo e verifica del componente dai due + gate espliciti di mutazione PSD; - la credenziale condivisa corrente, priva del nuovo identificativo pubblico, sarà l’unico record temporaneo `legacy_raw` con ID `legacy-shared`. Dopo la revoca non saranno accettate chiavi prive del formato versionato per installazione. diff --git a/docs/plans/2026-07-21-button-press-feedback-design.md b/docs/plans/2026-07-21-button-press-feedback-design.md deleted file mode 100644 index 0c63f6ce..00000000 --- a/docs/plans/2026-07-21-button-press-feedback-design.md +++ /dev/null @@ -1,19 +0,0 @@ -# Button Press Feedback Design - -## Context - -Buttons currently change on hover, but many provide little or no visible acknowledgment while the pointer is pressed. The interface mixes a shared Base UI button with native buttons, so changing only the shared component would leave inconsistent behavior. - -## Chosen interaction - -Apply one CSS press vocabulary to every enabled native button. During `:active`, the button compresses to `scale(0.97)`, loses raised shadow, and receives a restrained brightness change. The transition lasts 140 ms and uses an ease-out-quint curve (`cubic-bezier(0.22, 1, 0.36, 1)`). This reads as a physical press without bounce, ripple, layout movement, or JavaScript state. - -The existing one-pixel translation on the shared button is removed so shared and native buttons do not combine two motion patterns. - -## Accessibility - -Under `prefers-reduced-motion: reduce`, scale is disabled. The brightness and shadow change remain, providing a clear pressed state without kinetic motion. Disabled buttons receive no press treatment. - -## Verification - -A focused contract test checks the global enabled-button selector, scale, timing, easing, and reduced-motion override. The full frontend suite and typecheck guard regressions. Playwright then holds a real button in the active state and confirms its computed transform, followed by a visual screenshot/snapshot check. diff --git a/docs/plans/2026-07-21-button-press-feedback.md b/docs/plans/2026-07-21-button-press-feedback.md deleted file mode 100644 index fe01afdb..00000000 --- a/docs/plans/2026-07-21-button-press-feedback.md +++ /dev/null @@ -1,72 +0,0 @@ -# Button Press Feedback Implementation Plan - -> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. - -**Goal:** Give every enabled button immediate, consistent click acknowledgment while preserving a non-kinetic reduced-motion alternative. - -**Architecture:** Define the interaction once in the global Tailwind base layer so both Base UI and native buttons inherit it. Remove the shared button's older translation-only active state to avoid compounded transforms. Verify the CSS contract first, then exercise the real interaction in Playwright. - -**Tech Stack:** React 18, Tailwind CSS 3, Vitest, Playwright CLI. - ---- - -### Task 1: Specify the global press contract - -**Files:** -- Create: `frontend/src/button-press-feedback.test.ts` -- Test: `frontend/src/button-press-feedback.test.ts` - -**Step 1: Write the failing test** - -Read `src/index.css` and assert the enabled-button active selector, `scale(0.97)`, 140 ms duration, ease-out-quint curve, disabled exclusion, and reduced-motion transform override. Assert that `components/ui/button.tsx` no longer contains the legacy translation active class. - -**Step 2: Run test to verify it fails** - -Run: `npx vitest run src/button-press-feedback.test.ts` - -Expected: FAIL because the global press rules do not exist and the shared button still uses translation. - -### Task 2: Implement the press feedback - -**Files:** -- Modify: `frontend/src/index.css` -- Modify: `frontend/src/components/ui/button.tsx` -- Test: `frontend/src/button-press-feedback.test.ts` - -**Step 1: Add the minimal CSS** - -Add a global enabled-button transition and active state using only transform, filter, and shadow. Add a `prefers-reduced-motion` override that removes scale while preserving non-kinetic contrast feedback. - -**Step 2: Remove the legacy shared-button translation** - -Delete `active:not-aria-[haspopup]:translate-y-px` from the shared variant base string. - -**Step 3: Run the focused test** - -Run: `npx vitest run src/button-press-feedback.test.ts` - -Expected: PASS. - -### Task 3: Verify regressions and real-browser behavior - -**Files:** -- Verify: `frontend/src/index.css` -- Verify: `frontend/src/components/ui/button.tsx` - -**Step 1: Run frontend verification** - -Run: `npx vitest run` - -Run: `npx tsc -b` - -Expected: all tests pass and typecheck exits 0. - -**Step 2: Verify in Playwright** - -Open `http://localhost:5173`, hold pointer-down on an enabled button, and inspect its computed transform and filter before release. Repeat with reduced motion emulation and confirm transform remains `none` while contrast feedback remains. - -**Step 3: Review the final diff** - -Run: `git diff --check` and inspect `git diff --stat`. - -Expected: no whitespace errors and only the intended product/design, CSS, component, and test files changed. diff --git a/docs/plans/2026-08-08-internal-qdrant-ollama.md b/docs/plans/2026-08-08-internal-qdrant-ollama.md deleted file mode 100644 index 075c2fa6..00000000 --- a/docs/plans/2026-08-08-internal-qdrant-ollama.md +++ /dev/null @@ -1,773 +0,0 @@ -# Internal Qdrant and Ollama Implementation Plan - -> **Historical nomenclature:** this plan predates the native host CLI convergence. The current -> operator command is `tht`; any older `thothctl` smoke-script or rollback wording below is retained -> only as historical evidence. - -> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. - -**Goal:** Make Qdrant and Ollama mandatory internal ThothII services while keeping the analytical -DWH external and associating each workspace with one Qdrant collection for schema, Evidence, and -Memory embeddings. - -**Architecture:** Introduce workspace schema v3, preserve v1/v2 only as migration inputs, and keep -the existing harness `VectorStore` port behind a new Qdrant REST adapter. Base Compose owns Qdrant, -Ollama, their persistent volumes, and model initialization; workspace descriptors contain semantic -identity but no vector/embedding endpoints or credentials. - -**Tech Stack:** TypeScript/Fastify/Zod, Python 3.12/Pydantic/requests, React 18, Docker Compose, -Qdrant REST API, Ollama `/api/embed`, Vitest, pytest. - ---- - -## Guardrails - -- Apply `@superpowers:test-driven-development` to every behavior change: add one focused failing - test, observe the expected failure, implement the minimum, and rerun the focused test. -- Do not run broad suites until the corresponding code/config changes exist; this preserves the - requested ordering while still using TDD. -- Preserve the external DWH connector contract and session persistence model. -- Do not retain an operational fallback to pgvector or an external embedding endpoint. -- Do not delete or rewrite user workspace repositories or Qdrant data. Migration is descriptor-only; - semantic data is rebuilt explicitly. -- Commit after each task only when focused tests are green. - -### Task 1: Define workspace schema v3 - -**Files:** - -- Modify: `backend/src/workspaces/schema.ts` -- Modify: `backend/src/workspaces/types.ts` -- Modify: `backend/test/workspaces-schema.test.ts` -- Modify: `backend/test/workspaces-migrate-legacy.test.ts` -- Create: `backend/src/workspaces/migrate-v2-qdrant.ts` -- Create: `backend/test/workspaces-migrate-v2-qdrant.test.ts` - -**Step 1: Write the failing schema tests** - -Add tests proving that schema v3 accepts only this semantic shape: - -```ts -const semantic_index = { - vector_store: { - engine: "qdrant", - collection: "psd-clinical", - dimensions: 1024, - distance: "cosine", - }, - embedding: { - provider: "ollama_internal", - model: "qwen3-embedding:0.6b", - dimensions: 1024, - }, -}; -``` - -Add separate rejection cases for `pgvector`, `supported_transports`, external embedding providers, -non-1024 dimensions, non-cosine distance, and unknown fields. Assert v1/v2 remain parseable as -legacy descriptors but `isOperationalWorkspace()` returns false. - -**Step 2: Run the tests and verify RED** - -Run: - -```bash -cd backend -npx vitest run test/workspaces-schema.test.ts test/workspaces-migrate-v2-qdrant.test.ts -``` - -Expected: failure because schema version 3 and `migrateWorkspaceV2ToV3` do not exist. - -**Step 3: Implement the minimum schema and migration** - -Add `QdrantVectorStore`, `InternalEmbedding`, and `WorkspaceV3` types. Replace the operational type -guard with schema-v3-only semantics. Implement: - -```ts -export function migrateWorkspaceV2ToV3( - legacy: WorkspaceV2, - collection: string, -): WorkspaceV3 { - return validateOperationalWorkspace({ - workspace: { ...legacy.workspace, schema_version: 3 }, - dwh: legacy.dwh, - semantic_index: { - vector_store: { - engine: "qdrant", - collection, - dimensions: 1024, - distance: "cosine", - }, - embedding: { - provider: "ollama_internal", - model: "qwen3-embedding:0.6b", - dimensions: 1024, - }, - }, - llm_policy: legacy.llm_policy, - ...(legacy.diagnostics?.dwh_rest - ? { diagnostics: { dwh_rest: legacy.diagnostics.dwh_rest } } - : {}), - }); -} -``` - -Do not copy vector/embedding diagnostics or transports. - -**Step 4: Verify GREEN** - -Run the command from Step 2. Expected: all selected tests pass. - -**Step 5: Commit** - -```bash -git add backend/src/workspaces/schema.ts backend/src/workspaces/types.ts \ - backend/src/workspaces/migrate-v2-qdrant.ts backend/test/workspaces-schema.test.ts \ - backend/test/workspaces-migrate-legacy.test.ts backend/test/workspaces-migrate-v2-qdrant.test.ts -git commit -m "feat: define internal semantic workspace schema" -``` - -### Task 2: Make collection ownership unique in the Git registry - -**Files:** - -- Modify: `backend/src/workspaces/registry.ts` -- Modify: `backend/src/workspaces/migrate-legacy.ts` -- Modify: `backend/test/workspace-registry.test.ts` -- Modify: `backend/test/workspaces-migrate-legacy.test.ts` - -**Step 1: Write failing registry tests** - -Add fixtures with two schema-v3 workspaces claiming `collection: shared`. Assert snapshot activation -fails with `workspace_invalid` and retains the previous active snapshot. Assert v1/v2 entries are -listed as `migration_required` and cannot be acquired with `acquireSessionRevision()`. - -**Step 2: Verify RED** - -```bash -cd backend -npx vitest run test/workspace-registry.test.ts test/workspaces-migrate-legacy.test.ts \ - -t "collection|migration_required" -``` - -Expected: duplicate collections are currently accepted and v2 is currently operational. - -**Step 3: Implement uniqueness and migration state** - -During snapshot validation, build `Map` for operational descriptors and -raise a sanitized `workspace_invalid` error on a duplicate. Update migration output and CLI wording -to require an explicit target collection and schema v3. - -**Step 4: Verify GREEN and commit** - -```bash -cd backend -npx vitest run test/workspace-registry.test.ts test/workspaces-migrate-legacy.test.ts \ - -t "collection|migration_required" -cd .. -git add backend/src/workspaces/registry.ts backend/src/workspaces/migrate-legacy.ts \ - backend/test/workspace-registry.test.ts backend/test/workspaces-migrate-legacy.test.ts -git commit -m "feat: reserve one qdrant collection per workspace" -``` - -### Task 3: Remove external semantic bindings and render internal endpoints - -**Files:** - -- Modify: `backend/src/workspaces/contracts.ts` -- Modify: `backend/src/workspaces/bindings.ts` -- Modify: `backend/src/workspaces/runtime-renderer.ts` -- Modify: `backend/src/config.ts` -- Modify: `backend/test/workspaces-contracts.test.ts` -- Modify: `backend/test/workspaces-bindings.test.ts` -- Modify: `backend/test/workspace-runtime-renderer.test.ts` -- Modify: `backend/test/config.test.ts` - -**Step 1: Write failing contract tests** - -Assert schema-v3 installation contracts contain DWH variables only. Assert environment variables -matching `*_VECTOR_*`, `*_EMBEDDING_BASE_URL`, or semantic API-key suffixes are ignored/rejected. -Assert the rendered harness config always contains: - -```yaml -resources: - vector: - engine: qdrant - base_url: http://qdrant:6333 - collection: psd-clinical - embeddings: - provider: ollama_internal - base_url: http://embedding:11434 - model: qwen3-embedding:0.6b - dimensions: 1024 -``` - -**Step 2: Verify RED** - -```bash -cd backend -npx vitest run test/workspaces-contracts.test.ts test/workspaces-bindings.test.ts \ - test/workspace-runtime-renderer.test.ts test/config.test.ts -``` - -Expected: current contracts require external vector and embedding bindings. - -**Step 3: Implement internal runtime configuration** - -Add typed backend config fields with Compose defaults: - -```ts -internalQdrantUrl: "http://qdrant:6333" -internalEmbeddingUrl: "http://embedding:11434" -internalEmbeddingModel: "qwen3-embedding:0.6b" -internalEmbeddingDimensions: 1024 -``` - -Accept only `qdrant`, `embedding`, `localhost`, or loopback hosts. Keep these values out of Git -workspace descriptors, API payloads, and generated installation docs. Render them into the -ephemeral backend-owned harness config after descriptor validation. - -**Step 4: Verify GREEN and commit** - -Run Step 2, then: - -```bash -git add backend/src/config.ts backend/src/workspaces/contracts.ts backend/src/workspaces/bindings.ts \ - backend/src/workspaces/runtime-renderer.ts backend/test/config.test.ts \ - backend/test/workspaces-contracts.test.ts backend/test/workspaces-bindings.test.ts \ - backend/test/workspace-runtime-renderer.test.ts -git commit -m "feat: render private semantic service endpoints" -``` - -### Task 4: Narrow harness embedding configuration to internal Ollama - -**Files:** - -- Modify: `harness/tht/config.py` -- Modify: `harness/tht/config_compat.py` -- Modify: `harness/tht/vectorstore/embeddings.py` -- Modify: `harness/tht/cli/ollama_cmd.py` -- Modify: `harness/tests/test_config_resources.py` -- Create: `harness/tests/test_internal_embeddings.py` - -**Step 1: Write failing embedding tests** - -Use a fake `requests.Session` to prove `OllamaInternalEmbeddings.embed()` calls `/api/embed` with -model and batch input, returns 1024-dimensional finite vectors, and rejects count/dimension/NaN -mismatches. Add config tests rejecting external providers, API keys, and non-private base URLs. - -**Step 2: Verify RED** - -```bash -cd harness -.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py -q -``` - -Expected: `OllamaInternalEmbeddings` and internal-only config do not exist. - -**Step 3: Implement the client** - -Implement one bounded `/api/embed` request per batch: - -```python -response = self._session.post( - f"{self.base_url}/api/embed", - json={"model": self.model, "input": texts}, - timeout=self.timeout, -) -``` - -Validate response shape before returning any vector. Keep retry behavior bounded and sanitize URLs -and response bodies from raised errors. - -**Step 4: Verify GREEN and commit** - -```bash -cd harness -.venv/bin/pytest tests/test_internal_embeddings.py tests/test_config_resources.py -q -cd .. -git add harness/tht/config.py harness/tht/config_compat.py harness/tht/vectorstore/embeddings.py \ - harness/tht/cli/ollama_cmd.py harness/tests/test_config_resources.py \ - harness/tests/test_internal_embeddings.py -git commit -m "feat: use internal ollama embeddings" -``` - -### Task 5: Implement the Qdrant VectorStore adapter - -**Files:** - -- Create: `harness/tht/adapters/vector/qdrant.py` -- Modify: `harness/tht/adapters/vector/__init__.py` -- Modify: `harness/tht/ports/vector.py` -- Modify: `harness/tht/vectorstore/records.py` -- Modify: `harness/tht/vectorstore/store.py` -- Create: `harness/tests/test_qdrant_vector_store.py` -- Modify: `harness/tests/test_vector_port_contract.py` - -**Step 1: Write failing adapter tests** - -Test a real adapter against a deterministic fake HTTP server. Cover: - -- idempotent collection create with 1024/Cosine; -- mismatch fails without delete/recreate; -- keyword payload-index creation; -- deterministic UUIDv5 point IDs; -- upsert payload for `schema`, `evidence`, and `memory`; -- query filtered by workspace and allowed kinds; -- `existing_hashes`, exact Evidence generation list/delete, and health; -- sanitized timeouts and malformed responses. - -The point ID helper must satisfy: - -```python -def point_id(workspace_id: str, kind: str, record_key: str) -> str: - return str(uuid5(NAMESPACE_URL, f"thothii:{workspace_id}:{kind}:{record_key}")) -``` - -**Step 2: Verify RED** - -```bash -cd harness -.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -Expected: import failure for the Qdrant adapter. - -**Step 3: Implement minimal REST mappings** - -Use existing `requests` dependency and these endpoints: - -```text -GET /collections/{collection} -PUT /collections/{collection} -PUT /collections/{collection}/index -PUT /collections/{collection}/points?wait=true -POST /collections/{collection}/points/query -POST /collections/{collection}/points/scroll -POST /collections/{collection}/points/delete?wait=true -``` - -Every operation must include the workspace filter even though the collection is workspace-owned. -Map Qdrant scores and payloads back into existing `VectorHit` objects. - -**Step 4: Verify GREEN and commit** - -```bash -cd harness -.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -cd .. -git add harness/tht/adapters/vector/qdrant.py harness/tht/adapters/vector/__init__.py \ - harness/tht/ports/vector.py harness/tht/vectorstore/records.py \ - harness/tht/vectorstore/store.py harness/tests/test_qdrant_vector_store.py \ - harness/tests/test_vector_port_contract.py -git commit -m "feat: add qdrant vector adapter" -``` - -### Task 6: Wire schema, Evidence, and Memory through Qdrant - -**Files:** - -- Modify: `harness/tht/vectorstore/reader.py` -- Modify: `harness/tht/cli/vector_cmd.py` -- Modify: `harness/tht/cli/memory_cmd.py` -- Modify: `harness/tht/corpus/pipeline.py` -- Modify: `harness/tht/search/evidence.py` -- Modify: `harness/tht/cli/schema_cmd.py` -- Modify: `harness/tests/test_memory_save_one.py` -- Modify: `harness/tests/test_search_pack.py` -- Create: `harness/tests/test_semantic_kind_isolation.py` - -**Step 1: Write failing integration tests** - -Use an in-memory fake implementing the `VectorStore` port. Assert: - -- schema records use `kind=schema`; -- corpus records use `kind=evidence` and exact generation; -- approved memories use `kind=memory`; -- search pack requests only its allowed kind set; -- all three paths share `workspace_id`, `workspace_revision`, hashing, and point-key construction; -- retries do not duplicate points. - -**Step 2: Verify RED** - -```bash -cd harness -.venv/bin/pytest tests/test_semantic_kind_isolation.py tests/test_memory_save_one.py \ - tests/test_search_pack.py -q -``` - -Expected: current factories select pgvector/HTTP adapters and payloads lack the v3 identity fields. - -**Step 3: Wire the adapter** - -Make schema-v3 `qdrant` the only operational vector factory branch. Reuse the current canonical -record builders; add only missing identity fields. Keep the JSONL Memory registry and filesystem -Evidence corpus as sources of truth. - -**Step 4: Verify GREEN and commit** - -Run Step 2, then commit the listed files with: - -```bash -git commit -m "feat: index semantic records in qdrant" -``` - -### Task 7: Add mandatory Qdrant and Ollama Compose services - -**Files:** - -- Modify: `compose.yaml` -- Create: `deploy/compose.embedding-gpu.yaml` -- Create: `docker/embedding-model-init.sh` -- Modify: `docker/core.Dockerfile` -- Modify: `deploy/env/local.env.example` -- Modify: `deploy/env/server.env.example` -- Modify: `scripts/run-stack.sh` -- Modify: `scripts/test-default-compose.sh` -- Modify: `scripts/test-unified-compose.sh` -- Create: `scripts/test-internal-semantic-compose.sh` - -**Step 1: Write failing Compose contract tests** - -Assert the rendered base profile has `core`, `frontend`, `qdrant`, `embedding`, and -`embedding-model-init`; private services have no published ports; persistent volumes exist; core -depends on Qdrant health and successful model init; no external vector/embedding binding is required. - -Also assert all service images use version plus immutable digest. Resolve and record supported -multi-architecture digests for Qdrant v1.18.x and Ollama v0.32.x during implementation: - -```bash -docker buildx imagetools inspect qdrant/qdrant:v1.18.2 -docker buildx imagetools inspect ollama/ollama:0.32.0 -``` - -**Step 2: Verify RED** - -```bash -./scripts/test-default-compose.sh -./scripts/test-unified-compose.sh -./scripts/test-internal-semantic-compose.sh -``` - -Expected: required services and volumes are absent. - -**Step 3: Implement the services** - -`embedding-model-init.sh` must wait with a bounded deadline, call `ollama pull` for the exact model, -and verify it appears in `/api/tags`. The Qdrant healthcheck uses its HTTP health endpoint. The CPU -base has no device reservation; the GPU override adds only the supported device stanza. - -**Step 4: Verify GREEN and commit** - -Run Step 2, then: - -```bash -git add compose.yaml deploy/compose.embedding-gpu.yaml docker/embedding-model-init.sh \ - docker/core.Dockerfile deploy/env/local.env.example deploy/env/server.env.example \ - scripts/run-stack.sh scripts/test-default-compose.sh scripts/test-unified-compose.sh \ - scripts/test-internal-semantic-compose.sh -git commit -m "feat: run qdrant and ollama inside thothii" -``` - -### Task 8: Retire pgvector deployment and external semantic connectors - -**Files:** - -- Delete: `deploy/compose.local-vector.yaml` -- Delete: `deploy/compose.preprocess-local-vector.yaml` -- Delete: `deploy/sql/20-vector-roles.sql` -- Delete: `deploy/vector/reconcile-roles.sh` -- Delete: `deploy/vector/rotate-bootstrap-password.py` -- Delete: `deploy/vector/secret-policy.sh` -- Delete: `deploy/vector/vector-db-entrypoint.sh` -- Delete: `scripts/local-vector-smoke.sh` -- Delete: `scripts/test-local-vector-smoke-safety.sh` -- Delete: `scripts/test-local-vector-smoke-live-collision.sh` -- Delete: `scripts/test-vector-bootstrap-rotation.sh` -- Delete: `scripts/test-vector-migration-image.sh` -- Delete: `scripts/test-vector-secret-policy.sh` -- Modify: `scripts/test-no-deployment-coupling.sh` -- Modify: `scripts/test-no-deployment-coupling-scope.sh` -- Modify: `scripts/test-compose-secret-policy.sh` -- Modify: `.github/workflows/deployment.yml` - -**Step 1: Write the failing coupling test** - -Teach the coupling gate to reject active `pgvector`, `local-vector`, `THT_VECTOR_*`, workspace -embedding URLs/API keys, and external vector transports while allowing historical specs and the -explicit descriptor migration module. - -**Step 2: Verify RED** - -```bash -./scripts/test-no-deployment-coupling-scope.sh -./scripts/test-no-deployment-coupling.sh -./scripts/test-compose-secret-policy.sh -``` - -Expected: active pgvector deployment paths are reported. - -**Step 3: Remove the retired paths and update CI** - -Remove only repository deployment machinery. Retain harness pgvector code temporarily only if it -is needed to read/export legacy data during migration; it must not be reachable from schema v3 or -Compose. Remove it in a follow-up task once migration fixtures no longer import it. - -**Step 4: Verify GREEN and commit** - -Run Step 2 and the workflow fixture tests, then commit all deletions and modifications: - -```bash -git add -A deploy scripts .github/workflows/deployment.yml -git commit -m "refactor: retire external vector deployment" -``` - -### Task 9: Update frontend workspace editing and examples - -**Files:** - -- Modify: `frontend/src/api/workspaces.ts` -- Modify: `frontend/src/shell/WorkspaceEditor.tsx` -- Modify: `frontend/src/shell/WorkspaceEditor.test.tsx` -- Modify: `frontend/src/shell/WorkspaceManager.test.tsx` -- Modify: `frontend/src/api/workspaces.test.ts` -- Modify: `frontend/src/workspaces/drafts.test.ts` -- Modify: `deploy/workspaces/example.yaml` -- Modify: `deploy/workspaces/psd.yaml.example` - -**Step 1: Write failing UI tests** - -Assert editor/preview show Qdrant collection and fixed internal embedding model, expose no vector -endpoint/credential fields, and publish schema v3. Assert legacy descriptors display a migration -banner and cannot be selected for a new session. - -**Step 2: Verify RED** - -```bash -cd frontend -npx vitest run src/shell/WorkspaceEditor.test.tsx src/shell/WorkspaceManager.test.tsx \ - src/api/workspaces.test.ts src/workspaces/drafts.test.ts -``` - -Expected: fixtures and controls still use pgvector/external embedding. - -**Step 3: Implement fixed semantic controls** - -Collection remains editable and validated. Engine, provider, model, dimensions, and distance render -as fixed architecture values. Remove external semantic diagnostics from drafts and publish payloads. - -**Step 4: Verify GREEN and commit** - -Run Step 2, then commit the listed files with: - -```bash -git commit -m "feat: edit qdrant workspace collections" -``` - -### Task 10: Add a real internal semantic smoke - -**Files:** - -- Create: `scripts/internal-semantic-smoke.sh` -- Modify: `scripts/unified-deployment-smoke.sh` -- Modify: `scripts/server-deployment-smoke.sh` -- Modify: `scripts/task13-runtime-fixture-check.ts` -- Modify: `scripts/test-task13-runtime-fixtures.sh` - -**Step 1: Write failing smoke fixture assertions** - -The fixture must require private Qdrant/Ollama services, model volume, Qdrant volume, fixed internal -URLs, and no host ports. It must reject wrong service names, external URLs, collection reuse, and -dimension changes. - -**Step 2: Verify RED** - -```bash -./scripts/test-task13-runtime-fixtures.sh local -./scripts/test-task13-runtime-fixtures.sh server -``` - -Expected: current fixture expects the two-service topology. - -**Step 3: Implement the live smoke** - -Using disposable volumes and a fixture workspace, start the stack on CPU, wait for the model, ensure -the collection, embed one record of each kind, query each kind with filters, restart offline, and -prove all points and the model remain available. Cleanup must remain exact and must not prune global -Docker resources. - -**Step 4: Verify GREEN and commit** - -```bash -./scripts/test-task13-runtime-fixtures.sh local -./scripts/test-task13-runtime-fixtures.sh server -./scripts/internal-semantic-smoke.sh -git add scripts/internal-semantic-smoke.sh scripts/unified-deployment-smoke.sh \ - scripts/server-deployment-smoke.sh scripts/task13-runtime-fixture-check.ts \ - scripts/test-task13-runtime-fixtures.sh -git commit -m "test: cover internal semantic services" -``` - -### Task 11: Update operator documentation and state - -**Files:** - -- Modify: `README.md` -- Modify: `AGENTS.md` -- Modify: `PROJECT_STATE.md` -- Modify: `docs/install/local-workspace-registry.md` -- Modify: `docs/install/server-workspace-registry.md` -- Modify: `docs/installazione-docker-4-contesti.md` -- Modify: `docs/workspace-diagnostic-protocol.md` -- Modify: `docs/gestione-memory.md` -- Modify: `deploy/secrets/README.md` -- Modify: `scripts/verify-workspace-install-docs.sh` -- Modify: `scripts/test-verify-workspace-install-docs.sh` - -**Step 1: Write failing documentation contract assertions** - -Require the four-service topology, CPU/GPU behavior, volume backup/restore, schema-v3 migration, -Qdrant collection ownership, and removal of external vector/embedding variables from active manuals. - -**Step 2: Verify RED** - -```bash -./scripts/test-verify-workspace-install-docs.sh -./scripts/verify-workspace-install-docs.sh --fixtures-only -``` - -Expected: manuals still describe external pgvector/embedding and a two-service mandatory stack. - -**Step 3: Update documentation** - -Document Qdrant as a derived but persistent index, Ollama model cache behavior, CPU-first startup, -optional GPU override, snapshot/restore, explicit legacy migration, and the fact that only the DWH -and LLM remain external application endpoints. - -**Step 4: Verify GREEN and commit** - -Run Step 2, then: - -```bash -git add README.md AGENTS.md PROJECT_STATE.md docs deploy/secrets/README.md \ - scripts/verify-workspace-install-docs.sh scripts/test-verify-workspace-install-docs.sh -git commit -m "docs: document internal semantic infrastructure" -``` - -### Task 12: Remove unreachable pgvector runtime code - -**Files:** - -- Delete: `harness/tht/adapters/vector/pgvector.py` -- Delete: `harness/tht/adapters/vector/legacy_direct.py` -- Delete: `harness/tht/adapters/vector/thoth_http.py` -- Delete: `harness/tht/vectorstore/rest_client.py` -- Delete: `harness/tht/vectorstore/rest_writer.py` -- Delete: `harness/tht/migrations/vector/001_extensions.sql` -- Delete: `harness/tht/migrations/vector/002_schema_tables.sql` -- Delete: `harness/tht/migrations/vector/003_roles.sql` -- Delete: `harness/tht/migrations/vector/004_evidence_generation_gc.sql` -- Modify: `harness/pyproject.toml` -- Modify/Delete: affected pgvector and migration tests under `harness/tests/l0/` - -**Step 1: Prove the code is unreachable** - -```bash -rg -n "PgVectorStore|ThothHttpVectorStore|LegacyDirectVectorStore|migrations/vector" \ - harness backend frontend compose.yaml deploy scripts docker docs \ - --glob '!docs/plans/**' --glob '!docs/superpowers/**' -``` - -Expected before cleanup: matches only in the files scheduled for deletion and legacy tests. If an -operational call site remains, stop and migrate it before deleting anything. - -**Step 2: Delete obsolete runtime and tests** - -Retain descriptor migration tests, but remove PostgreSQL vector runtime/migration packaging tests. -Remove `psycopg2-binary` only if the DWH/session PostgreSQL paths do not need it; otherwise keep it. - -**Step 3: Verify focused imports and packaging** - -```bash -cd harness -.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py \ - tests/test_semantic_kind_isolation.py tests/test_vector_migration_packaging.py -q -python -m build -``` - -Expected: Qdrant tests pass and the wheel contains no pgvector migrations. Adjust the packaging test -to assert Qdrant has no SQL migration payload. - -**Step 4: Commit** - -```bash -git add -A harness -git commit -m "refactor: remove pgvector runtime" -``` - -### Task 13: Run complete verification - -**Files:** - -- Modify only if a genuine regression is discovered. - -**Step 1: Deterministic layer gates** - -```bash -cd harness && .venv/bin/pytest -q && .venv/bin/ruff check . -cd ../backend && npx vitest run && npx tsc --noEmit -p . && npm run build -cd ../frontend && npx vitest run && npx tsc -b && npm run build -cd .. && git diff --check -``` - -Expected: all gates pass. Existing unrelated Ruff debt must be reported separately if it remains; -new/modified files must be Ruff-clean. - -**Step 2: Deployment contracts** - -```bash -./scripts/test-default-compose.sh -./scripts/test-unified-compose.sh -./scripts/test-internal-semantic-compose.sh -./scripts/test-no-deployment-coupling.sh -./scripts/test-compose-secret-policy.sh -./scripts/verify-workspace-install-docs.sh --fixtures-only -``` - -Expected: all pass without external vector/embedding settings. - -**Step 3: Docker smokes** - -```bash -./scripts/internal-semantic-smoke.sh -./scripts/workspace-registry-smoke.sh -./scripts/unified-deployment-smoke.sh -./scripts/thothctl-update-smoke.sh -./scripts/server-deployment-smoke.sh -``` - -Expected: CPU semantic smoke passes, persistence survives offline restart, and every script proves -exact cleanup. Investigate the previously observed `thothctl` rollback failure independently if it -recurs; do not weaken the new semantic gate to hide it. - -**Step 4: Final audit** - -```bash -rg -n "pgvector|local-vector|THT_VECTOR_|EMBEDDING_BASE_URL|openai_compatible|ollama_compatible" \ - . --glob '!docs/plans/**' --glob '!docs/superpowers/**' --glob '!**/node_modules/**' \ - --glob '!**/.venv/**' --glob '!**/.git/**' -git status --short -``` - -Expected: no active operational references; only explicit legacy descriptor migration fixtures may -remain. Worktree contains only intentional changes. - -**Step 5: Commit verification metadata** - -Update `PROJECT_STATE.md` with exact counts, image digests, smoke durations, CPU hardware, and any -manual GPU/Windows gates. Commit only verified claims: - -```bash -git add PROJECT_STATE.md -git commit -m "docs: record qdrant ollama verification" -``` diff --git a/docs/plans/2026-08-10-rimozione-schema-v1-v2.md b/docs/plans/2026-08-10-rimozione-schema-v1-v2.md deleted file mode 100644 index 81ffa54d..00000000 --- a/docs/plans/2026-08-10-rimozione-schema-v1-v2.md +++ /dev/null @@ -1,447 +0,0 @@ -# Piano di implementazione: workspace descriptor esclusivamente schema v3 - -> **Per gli agenti esecutori:** SUB-SKILL OBBLIGATORIA: usare `superpowers:subagent-driven-development` (raccomandata) oppure `superpowers:executing-plans`, procedendo task per task con TDD e review tra i task. - -**Obiettivo:** rimuovere dal prodotto ogni capacità di leggere, migrare, rendere operativo o presentare workspace descriptor schema v1/v2. Il solo descriptor accettato diventa schema v3. Restano intatti i formati versionati non correlati e gli state file del registry già prodotti da versioni recenti con revisioni v3. - -**Architettura:** parser, registry, renderer, diagnostica, route e frontend convergono su un solo tipo `WorkspaceV3`. Il campo pubblico `WorkspaceRevision.state` scompare. Un decoder privato normalizza in memoria gli state file già scritti con `state: "operational"`, elimina quel campo prima di qualsiasi uso/API e rifiuta ogni combinazione non-v3 o incoerente. I build backend diventano clean-first, così la cancellazione dei migratori sorgente implica anche la loro assenza da `dist` e dall'immagine core. - -**Tech stack:** TypeScript 5, Zod 4, Fastify 5, React 18, Vitest, Node.js 22, Bash/PowerShell, Git e Docker Compose. - -**Stato:** piano revisionato dopo review indipendente. La sua approvazione non autorizza l'implementazione; attendere un esplicito ordine separato. - ---- - -## Decisioni confermate - -1. Nessun workspace v1/v2 reale deve essere preservato o migrato. -2. Eliminare `migrate-legacy.ts`, `migrate-v2-qdrant.ts` e le relative interfacce CLI. -3. Eliminare il campo `state` dal tipo/API `WorkspaceRevision` e da tutti i nuovi state/manifest del registry. -4. Descriptor v1/v2 presenti in Git o negli snapshot vengono rifiutati, senza conversione automatica. -5. Non toccare i documenti storici sotto `docs/superpowers/` e i vecchi piani; possono descrivere decisioni passate. -6. Non iniziare P2 finché P1 non dispone di nuova evidenza automatica e di una nuova decisione manuale esplicita. - -## Confini da non oltrepassare - -Questa rimozione riguarda soltanto il **workspace descriptor**. Non eliminare o rinominare: - -- `schemaVersion`/`schema_version` di bundle ZIP, report, job, ledger, manifest di sessione o artifact di fase; -- `RevisionLeaseRecord.state` (`creating`/`persisted`), maintenance state, process state o UI state non collegati a `WorkspaceRevision`; -- `migration_required` usato nei futuri piani P3–P6 per ownership DWH, punti semantici revisionless o altre migrazioni non-descriptor; -- `allowLegacy` del frontend sessioni, che significa “sessione senza revisione workspace” e non descriptor v1/v2; -- documenti storici o report conservati. - -L'unica compatibilità legacy mantenuta nel codice è il decoder privato degli state file già scritti con il campo revisionale `state: "operational"`. Non costituisce supporto a descriptor v1/v2. - -## Contratto v3-only - -- `WorkspaceDescriptor`, `CanonicalWorkspace` e `WorkspaceV3` rappresentano la stessa forma v3; mantenere gli alias soltanto quando migliorano la semantica dei confini. -- `parseWorkspaceYaml` e `validateWorkspaceDescriptor` accettano esclusivamente `workspace.schema_version === 3`. -- v1/v2 generano l'errore pubblico già sanitizzato `workspace_invalid`; non usare più il messaggio o lo stato `migration_required` per i descriptor. -- Un'attivazione Git contenente anche un solo descriptor non-v3 fallisce interamente e conserva il precedente active state. -- Le revisioni restituite dalle API contengono esattamente `id`, `commit`, `blob`, `snapshotPath`, senza `state`. -- Nuovi `active.json` e `snapshot.json` non contengono `state` nelle revisioni. - -## Compatibilità degli state file esistenti - -Definire due decoder stretti e distinti: - -```ts -interface StoredWorkspaceRevision { - id: string; - commit: string; - blob: string; - snapshotPath: string; - state?: "operational"; // solo input compatibile; mai restituito -} - -interface WorkspaceRevision { - id: string; - commit: string; - blob: string; - snapshotPath: string; -} -``` - -Regole: - -1. `active.json` accetta soltanto `{head,revisions}`; `snapshot.json` soltanto `{head,revisions,files}`. -2. Ogni revision object accetta soltanto i quattro campi correnti più l'opzionale vecchio `state: "operational"`. -3. `state: "migration_required"`, qualsiasi altro valore o campo sconosciuto è rifiutato. -4. Il decoder ricostruisce un nuovo oggetto `WorkspaceRevision`; non restituisce mai l'oggetto JSON originale. -5. Active state e snapshot manifest vengono confrontati dopo la normalizzazione. -6. L'integrità continua a validare path, commit, blob, digest, descriptor v3 e Evidence context. -7. La lettura non modifica snapshot storici. La successiva attivazione riscrive `active.json` nel formato corrente; tutti i nuovi snapshot sono state-free. -8. Un vecchio file già privo di `state` è naturalmente il formato corrente, ma il relativo descriptor deve comunque essere v3. - -## Mappa completa dei file - -### Backend produttivo - -- `backend/src/workspaces/schema.ts` -- `backend/src/workspaces/types.ts` -- `backend/src/workspaces/runtime-renderer.ts` -- `backend/src/workspaces/contracts.ts` -- `backend/src/workspaces/diagnostics.ts` -- `backend/src/workspaces/bindings.ts` -- `backend/src/workspaces/registry.ts` -- `backend/src/routes/workspaces.ts` -- `backend/src/routes/sessions.ts` -- `backend/src/routes/sql.ts` -- Eliminare `backend/src/workspaces/migrate-legacy.ts` -- Eliminare `backend/src/workspaces/migrate-v2-qdrant.ts` - -### Build e tooling P1 - -- `backend/package.json` -- Creare `backend/scripts/clean-dist.mjs` -- Creare un test Node per il clean build -- `backend/scripts/p1-manual-acceptance.mjs` -- `backend/scripts/p1-manual-acceptance.test.mjs` -- `backend/scripts/p1-render-snapshot.test.mjs` - -### Frontend - -- `frontend/src/api/workspaces.ts` -- `frontend/src/api/sessions.ts` -- `frontend/src/shell/SteerInput.tsx` -- `frontend/src/shell/WorkspaceManager.tsx` -- Test/fixture in `api`, `SteerInput`, `WorkspaceManager`, `NewSessionDialog`, `WorkspacePublishDialog` e `drafts`. - -### Deploy, fixture e verificatori - -- `scripts/workspace-registry-smoke.sh` -- Creare `scripts/fixtures/workspace-registry-smoke.yaml` -- `scripts/test-no-deployment-coupling-scope.sh` -- `scripts/test-windows-clone-contract.ps1` -- `scripts/verify-workspace-install-docs.sh` -- `scripts/test-verify-workspace-install-docs.sh` - -### Documentazione corrente - -- `README.md` -- sezione corrente di `PROJECT_STATE.md`, prima di `## Historical snapshots` -- `docs/workspace-diagnostic-protocol.md` -- `docs/install/local-workspace-registry.md` -- `docs/install/server-workspace-registry.md` - ---- - -### Task 0: Congelare scope e baseline prima delle modifiche - -**File:** nessuna modifica produttiva. - -- [ ] Registrare `BASE_SHA=$(git rev-parse HEAD)` e verificare che gli altri piani non vengano inclusi nei commit di implementazione. -- [ ] Salvare l'inventario iniziale dei simboli descriptor-legacy: - -```bash -git grep -nE 'WorkspaceV1|WorkspaceV2|LegacyWorkspace|migration_required|migrate-legacy|migrateWorkspaceV1ToV2|migrateWorkspaceV2ToV3' -- \ - backend/src backend/test backend/scripts frontend/src scripts README.md PROJECT_STATE.md docs/install docs/workspace-diagnostic-protocol.md -``` - -- [ ] Classificare ogni risultato come descriptor legacy, compatibility decoder previsto, contratto diverso o documento storico. -- [ ] Verificare nei registry/installazioni disponibili che i descriptor attivi siano v3; questa è una precondizione di deploy, non un migratore. -- [ ] Non procedere se il worktree contiene modifiche applicative non attribuibili a questo piano. - -### Task 1: Scrivere i test RED del contratto v3-only - -**File:** -- `backend/test/workspaces-schema.test.ts` -- `backend/test/workspace-registry.test.ts` -- `backend/test/routes-workspaces.test.ts` - -- [ ] Aggiungere test che `parseWorkspaceYaml`, `validateWorkspaceDescriptor` e le route validate/publish rifiutino esplicitamente v1 e v2. -- [ ] Aggiungere test registry per: - - bootstrap pulito con solo v1/v2: fallimento, nessun `active.json` pubblicato; - - repository misto v3+v2: attivazione atomica rifiutata; - - pull che introduce v1/v2: precedente active state ancora leggibile; - - retained snapshot contenente descriptor non-v3: rifiuto fail-closed; - - risposta API state-free. -- [ ] Eseguire: - -```bash -cd backend -npx vitest run test/workspaces-schema.test.ts test/workspace-registry.test.ts test/routes-workspaces.test.ts -``` - -Atteso: RED per i nuovi requisiti, non errori di fixture casuali. - -### Task 2: Rendere lo schema backend esclusivamente v3 - -**File:** -- `backend/src/workspaces/schema.ts` -- `backend/src/workspaces/types.ts` -- test del Task 1 - -- [ ] Eliminare `WorkspaceV1`, `WorkspaceV2`, `LegacyWorkspace`, relativi Zod schema e `migrateWorkspaceV1ToV2`. -- [ ] Rendere `WorkspaceDescriptorSchema = WorkspaceV3Schema`. -- [ ] Eliminare `validateCanonicalWorkspace`, aggiornando **tutti** i chiamanti in `routes/workspaces.ts`, incluso il chiamante attualmente oltre quelli elencati nel vecchio piano. -- [ ] Eliminare `isCanonicalWorkspace`/`isOperationalWorkspace` dopo aver sostituito i rami condizionali con validazione v3 diretta. -- [ ] Conservare test negativi v1/v2; non cancellare le sole prove che impediscono una regressione futura. -- [ ] Eseguire test focalizzati e typecheck. -- [ ] Commit: `refactor: make workspace descriptors schema v3 only`. - -### Task 3: Normalizzare in sicurezza active state e snapshot manifest - -**File:** -- `backend/src/workspaces/registry.ts` -- `backend/test/workspace-registry.test.ts` - -- [ ] Scrivere RED per state/manifest con: - - campo assente; - - vecchio `state: "operational"`; - - `state: "migration_required"`; - - valore sconosciuto; - - campo extra; - - active state e manifest con formati misti; - - snapshot attivo, storico e fallback offline. -- [ ] Rimuovere `state` da `WorkspaceRevision` e da tutti i nuovi writer. -- [ ] Sostituire cast e vecchie migrazioni con decoder stretti che restituiscono oggetti normalizzati state-free. -- [ ] Rimuovere `LegacyWorkspaceRevision`, `LegacyActiveState`, `LegacySnapshotManifest`, `deriveStateFromLegacyRevisions`, `migrateLegacyActiveState`, `migrateLegacySnapshotManifest`, `sameLegacyRevisions` e le condizioni operative basate su `state`. -- [ ] Mantenere tutti i controlli di integrità e far validare ogni YAML come v3. -- [ ] Provare che list/read/API non riemettono il vecchio campo anche immediatamente dopo un restart, prima di una nuova attivazione. -- [ ] Commit: `refactor: remove workspace revision state`. - -### Task 4: Eliminare i rami v1/v2 da renderer, contracts, bindings e diagnostica - -**File:** -- `backend/src/workspaces/runtime-renderer.ts` -- `backend/src/workspaces/contracts.ts` -- `backend/src/workspaces/diagnostics.ts` -- `backend/src/workspaces/bindings.ts` -- relativi test - -- [ ] Scrivere/aggiornare test RED che accettano v3 e rifiutano input non-v3 al confine, senza renderer/diagnoser legacy. -- [ ] Eliminare il renderer v2/pgvector e i rami v1. -- [ ] Eliminare variabili contract e diagnostica solamente v2. -- [ ] Semplificare bindings dopo la validazione v3, senza indebolire validazione secrets/trasporti. -- [ ] Eseguire i test focalizzati: - -```bash -cd backend -npx vitest run \ - test/workspace-runtime-renderer.test.ts \ - test/workspaces-contracts.test.ts \ - test/workspaces-diagnostics.test.ts \ - test/workspaces-bindings.test.ts \ - test/workspace-runtime-handoff.test.ts -``` - -- [ ] Commit: `refactor: remove legacy workspace runtime branches`. - -### Task 5: Rimuovere migratori senza perdere test di deployment non correlati - -**File:** -- Eliminare i due migratori e i test esclusivamente di migrazione. -- Creare/spostare in un test dedicato le prove deployment presenti in `workspaces-migrate-legacy.test.ts:81-114`. - -- [ ] Prima di eliminare `workspaces-migrate-legacy.test.ts`, spostare in un file con nome coerente: - - volume registry durevole e mount Git read-only; - - contratto Dockerfile; - - fallback offline smoke; - - self-test di cleanup dell'immagine per-run. -- [ ] Eliminare `migrate-legacy.ts`, `migrate-v2-qdrant.ts` e i test di trasformazione. -- [ ] Conservare un fixture v2 soltanto nei test negativi di rifiuto. -- [ ] Eseguire i nuovi test deployment e il typecheck. -- [ ] Commit: `refactor: remove workspace migration utilities`. - -### Task 6: Aggiornare tutte le route backend e il tooling P1 - -**File:** -- `backend/src/routes/workspaces.ts` -- `backend/src/routes/sessions.ts` -- `backend/src/routes/sql.ts` -- test route inclusi `routes-sql-meta.test.ts` -- `backend/scripts/p1-manual-acceptance.mjs` -- test manual/render P1 - -- [ ] Rimuovere filtri/gate `revision.state` da tutte le route. La garanzia deriva dal registry v3-only. -- [ ] Aggiornare mock/fixture `WorkspaceRevision` in tutti i test backend. -- [ ] Aggiornare il validatore del manifest P1 manuale affinché richieda esattamente la revisione state-free. -- [ ] Aggiornare i fixture `p1-manual-acceptance.test.mjs` e `p1-render-snapshot.test.mjs`. -- [ ] Aggiungere un test JS specifico che rifiuti manifest con revisioni malformate senza reintrodurre `migration_required`. -- [ ] Eseguire: - -```bash -cd backend -npx vitest run test/routes-workspaces.test.ts test/routes-sessions.test.ts test/routes-sql-meta.test.ts -cd .. -node --test --test-concurrency=1 \ - backend/scripts/p1-manual-acceptance.test.mjs \ - backend/scripts/p1-render-snapshot.test.mjs -``` - -- [ ] Commit: `refactor: remove workspace revision state consumers`. - -### Task 7: Rendere il build backend clean-first - -**File:** -- `backend/package.json` -- Creare `backend/scripts/clean-dist.mjs` -- Creare test Node del clean build - -- [ ] Scrivere RED: creare un file sentinella in `backend/dist/workspaces/`, eseguire il clean/build e verificare che non sopravviva. -- [ ] Implementare la pulizia con API Node multipiattaforma, non con `rm -rf` nella npm script. -- [ ] Fare eseguire il clean prima di `tsc` da `npm run build`. -- [ ] Verificare dopo il build: - -```bash -test ! -e backend/dist/workspaces/migrate-legacy.js -test ! -e backend/dist/workspaces/migrate-v2-qdrant.js -``` - -- [ ] Costruire l'immagine core in un contesto pulito e verificare che i due moduli non esistano nell'immagine. -- [ ] Verificare che i manifest di integrità P1 continuino a legare l'intero nuovo `dist`. -- [ ] Commit: `build: remove stale backend distribution files`. - -### Task 8: Aggiornare frontend e contratto API state-free - -**File:** -- `frontend/src/api/workspaces.ts` -- `frontend/src/api/sessions.ts` -- `frontend/src/shell/SteerInput.tsx` -- `frontend/src/shell/WorkspaceManager.tsx` -- test/fixture frontend correlati - -- [ ] Scrivere/aggiornare test per revisioni senza `state` e risposta non-v3 rifiutata al confine workspace. -- [ ] Eliminare `state` dal tipo e dal parser revisionale. -- [ ] Rimuovere gate/banner/filtro `migration_required` e anche la visualizzazione `record.revision.state`. -- [ ] Mantenere `allowLegacy` per sessioni senza revisione. -- [ ] Aggiornare fixture in: - - `api/workspaces.test.ts`, `api/sessions.test.ts`; - - `SteerInput.test.tsx`, `WorkspaceManager.test.tsx`; - - `NewSessionDialog.test.tsx`, `WorkspacePublishDialog.test.tsx`; - - `drafts.test.ts`, mantenendo il test negativo di schema non-3. -- [ ] Documentare che core e frontend devono essere aggiornati insieme; il parser nuovo non usa più `state`. -- [ ] Eseguire typecheck e suite frontend. -- [ ] Commit: `refactor: remove legacy workspace UI state`. - -### Task 9: Sostituire fixture e smoke con descriptor v3 completi - -**File:** -- `scripts/workspace-registry-smoke.sh` -- Creare `scripts/fixtures/workspace-registry-smoke.yaml` -- `scripts/test-no-deployment-coupling-scope.sh` -- `scripts/test-windows-clone-contract.ps1` -- test deployment spostati nel Task 5 - -- [ ] Creare un descriptor v3 completo `id: local`, collection `local`, embedding interno 1024/cosine, LLM policy e diagnostica DWH; omettere Evidence per non richiedere un tree Git nello smoke registry. -- [ ] Validare il fixture con il parser produttivo in un test backend. -- [ ] Copiare il fixture nello seed repository e rimuovere sia l'invocazione del migratore sia il build backend ormai inutile allo smoke. -- [ ] Nel test Windows non cambiare soltanto il numero di versione: fornire il contratto v3 completo mantenendo lo scopo path-with-spaces/clone. -- [ ] Aggiornare il fixture dello scope coupling senza indebolire l'assenza-gate. -- [ ] Eseguire test shell focalizzati e, con Docker disponibile, lo smoke reale senza retry. -- [ ] Commit: `test: replace legacy workspace deployment fixtures`. - -### Task 10: Aggiornare documentazione corrente e relativi verifier - -**File:** -- documenti/verifier indicati nella mappa - -- [ ] Aggiornare README e soltanto la sezione corrente di `PROJECT_STATE.md`; non riscrivere gli snapshot storici. -- [ ] Eliminare procedure di migrazione v1/v2 dai manuali local/server e dal protocollo diagnostico. -- [ ] Modificare `verify-workspace-install-docs.sh` perché richieda “schema v3 only” e l'assenza di `migration_required` nella documentazione corrente. -- [ ] Aggiornare i fixture negativi del test del verifier. -- [ ] Non cambiare gli usi di `migration_required` nei piani P3–P6 relativi a ownership/artifact diversi. -- [ ] Eseguire: - -```bash -bash scripts/test-verify-workspace-install-docs.sh -bash scripts/verify-workspace-install-docs.sh --fixtures-only -``` - -- [ ] Commit: `docs: make schema v3 the only workspace contract`. - -### Task 11: Eseguire absence gate e suite complete - -- [ ] Eseguire backend clean build, typecheck e test: - -```bash -cd backend -npm run build -npx tsc --noEmit -p . -npx vitest run -``` - -- [ ] Eseguire frontend: - -```bash -cd frontend -npx tsc -b -npx vitest run -npm run build -``` - -- [ ] Eseguire script/verifier interessati, incluso lo smoke Docker obbligatorio se l'ambiente dispone di Docker. Non lasciarlo “opzionale” in una consegna che modifica lo smoke. -- [ ] Eseguire `git diff --check`. -- [ ] Eseguire l'absence gate ristretto: - -```bash -git grep -nE 'WorkspaceV1|WorkspaceV2|LegacyWorkspace|migrateWorkspaceV1ToV2|migrateWorkspaceV2ToV3' -- \ - backend/src frontend/src scripts && exit 1 || true - -git grep -nE 'migration_required|migrate-legacy|migrate-v2-qdrant' -- \ - backend/src backend/scripts frontend/src scripts README.md docs/install docs/workspace-diagnostic-protocol.md && exit 1 || true - -test ! -e backend/dist/workspaces/migrate-legacy.js -test ! -e backend/dist/workspaces/migrate-v2-qdrant.js -``` - -Nota: trasformare questi esempi in uno script con allowlist esplicita; non affidarsi a `&& exit 1 || true`, che può mascherare errori di esecuzione. Lo script deve distinguere “nessun match” da errore Git/I/O. - -- [ ] Ispezionare il diff per assicurarsi che nessun formato non-descriptor sia stato modificato. - -### Task 12: Rigenerare l'evidenza automatica P1 - -- [ ] Partire dal commit sorgente finale pulito. -- [ ] Eseguire una sola integrazione completa, senza retry automatico: - -```bash -./scripts/p1-acceptance.sh integration --keep -``` - -- [ ] Verificare report JSON/Markdown, hash dichiarati, manifest sorgente/dist, secret scan, ownership cleanup e porte chiuse. -- [ ] Aggiornare `PROJECT_STATE.md` con il nuovo commit/tree/report e con stati distinti: - -```text -automated integration: PASS -manual acceptance: PENDING -``` - -- [ ] Committare soltanto lo stato tracciato, mai `.artifacts`. -- [ ] Non riusare l'evidenza precedente legata a `c733896`. - -### Task 13: Riaprire e chiudere il gate manuale P1 - -- [ ] Preparare un ambiente manuale nuovo: - -```bash -./scripts/p1-manual-acceptance.sh prepare -./scripts/p1-manual-acceptance.sh serve -``` - -- [ ] Il reviewer segue integralmente il nuovo `GUIDE.md`, verificando anche che revisioni/API/manifest siano state-free e che v1/v2 siano rifiutati senza mutazione. -- [ ] Arrestare il server e verificare porte/processi: - -```bash -./scripts/p1-manual-acceptance.sh stop -``` - -- [ ] Solo il reviewer crea `VERDICT.md` e decide PASS/FAIL. -- [ ] Se PASS, aggiornare `PROJECT_STATE.md` e committare `docs: record schema-v3-only P1 acceptance`. -- [ ] Pulire il lab soltanto dopo conferma del reviewer. -- [ ] **STOP:** non iniziare P2 finché il reviewer non approva esplicitamente il nuovo P1. - ---- - -## Criteri finali di accettazione - -1. Nessun descriptor v1/v2 viene parsato, pubblicato, attivato, renderizzato, diagnosticato o mostrato. -2. I vecchi state file di revisioni v3 con `state: "operational"` continuano a caricarsi, ma API e nuovi file sono state-free. -3. Descriptor non-v3 o state incoerenti falliscono senza sostituire il precedente active state. -4. Nessun migratore sopravvive in sorgenti, `dist`, immagine core, script o documentazione corrente. -5. I formati versionati non collegati ai workspace descriptor sono invariati. -6. Backend, frontend, verifier, smoke e build interessati sono verdi. -7. Una nuova integrazione P1 è PASS al commit finale. -8. La nuova acceptance manuale P1 è decisa esplicitamente dal reviewer. -9. P2 resta non iniziato fino a ulteriore autorizzazione. diff --git a/docs/plans/2026-08-14-read-only-workspace-runtime-secrets.md b/docs/plans/2026-08-14-read-only-workspace-runtime-secrets.md deleted file mode 100644 index d1709de6..00000000 --- a/docs/plans/2026-08-14-read-only-workspace-runtime-secrets.md +++ /dev/null @@ -1,401 +0,0 @@ -# Read-only Workspace Runtime Secrets Implementation Plan - -> **Historical nomenclature:** this plan predates the native host CLI convergence. References to -> `thothctl` and `tools/thothctl` describe the implementation snapshot from which this plan was -> written; current operator commands and paths use native `tht` and `tools/tht`. - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. - -**Goal:** Make workspace consumption strictly read-only while adding installation-scoped Git identity and persistent GUI-managed runtime secrets. - -**Architecture:** Git remains the source of truth and is fetched into an application-owned checkout; complete candidate commits are validated before atomic activation and the backend has no Git write path. Runtime connector credentials are discovered from trusted connector contracts, stored as authenticated ciphertext by a backend vault, and materialized only for the lifetime of diagnostics or runtime leases. The browser exposes repository/readiness status and write-only secret forms without workspace persistence. - -**Tech Stack:** Fastify, TypeScript, Node.js crypto/filesystem, React 18, TanStack Query, Vitest, Go `thothctl`, Docker Compose. - ---- - -### Task 1: Freeze the Git repository boundary to read-only - -**Files:** -- Modify: `backend/src/workspaces/types.ts` -- Modify: `backend/src/workspaces/git-repository.ts` -- Modify: `backend/src/workspaces/registry.ts` -- Modify: `backend/test/workspaces-git-repository.test.ts` -- Modify: `backend/test/workspace-registry.test.ts` -- Modify: `backend/test/workspace-registry-deployment.test.ts` - -**Step 1: Write failing tests** - -Add tests proving that pull never configures a Git author, writes generated files, commits, or pushes; that a malformed candidate leaves the prior active snapshot intact; and that a missing catalog descriptor rejects the whole candidate instead of producing a bootstrap slot. - -**Step 2: Run the focused tests** - -Run: `cd backend && npx vitest run test/workspaces-git-repository.test.ts test/workspace-registry.test.ts test/workspace-registry-deployment.test.ts` - -Expected: FAIL on write/publish behavior and missing-descriptor semantics. - -**Step 3: Implement the read-only boundary** - -Remove `gitAuthorName`, `gitAuthorEmail`, mutation helpers, generated-document reconciliation, publish/conflict types, and bootstrap-slot activation. `pull()` must fetch, validate the complete commit in a candidate snapshot, and replace active state only after validation succeeds. - -**Step 4: Run focused tests** - -Run the command from Step 2. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend/src/workspaces backend/test/workspaces-git-repository.test.ts backend/test/workspace-registry.test.ts backend/test/workspace-registry-deployment.test.ts -git commit -m "refactor: make workspace repository strictly read only" -``` - -### Task 2: Remove publishing and bundle HTTP contracts - -**Files:** -- Modify: `backend/src/routes/workspaces.ts` -- Modify: `backend/test/routes-workspaces.test.ts` -- Modify: `backend/test/workspaces-runtime-v3-boundaries.test.ts` -- Modify: `backend/src/config.ts` -- Modify: `backend/test/workspaces-config.test.ts` - -**Step 1: Write failing route tests** - -Assert `POST /workspaces/publish`, `GET /workspaces/:id/export`, and `POST /workspaces/import` return 404 and that the backend no longer registers multipart or ZIP handling. Assert configuration no longer accepts Git author or bundle-limit settings as workspace-registry fields. - -**Step 2: Run tests and observe failure** - -Run: `cd backend && npx vitest run test/routes-workspaces.test.ts test/workspaces-config.test.ts test/workspaces-runtime-v3-boundaries.test.ts` - -Expected: FAIL because mutation and bundle routes still exist. - -**Step 3: Remove the mutation surface** - -Delete publish/import/export schemas and helpers, remove `multipart`, `yauzl`, and `yazl` usage from the route, and simplify safe workspace errors to read/validate/sync errors. - -**Step 4: Run tests** - -Run the command from Step 2 plus `cd backend && npx tsc --noEmit -p .`. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend/src backend/test package.json package-lock.json -git commit -m "refactor: remove workspace publishing and bundles" -``` - -### Task 3: Expose a sanitized installation repository identity - -**Files:** -- Modify: `backend/src/workspaces/git-repository.ts` -- Modify: `backend/src/routes/workspaces.ts` -- Modify: `backend/test/workspaces-git-repository.test.ts` -- Modify: `backend/test/routes-workspaces.test.ts` -- Modify: `tools/thothctl/internal/config/installation.go` -- Modify: `tools/thothctl/internal/config/installation_test.go` -- Modify: `deploy/psd/thothii-installation.yaml.example` -- Modify: `docs/install/examples/thothii-installation.local.yaml` -- Modify: `docs/install/examples/thothii-installation.server.yaml` - -**Step 1: Write failing parser and status tests** - -Cover HTTPS, SSH URL, and SCP-style remotes; reject embedded user-info for HTTPS; return only `host`, `repository`, `branch`, and `transport`; never return a token, key path, or raw credential-bearing URL. Add installation-descriptor tests for a required `workspaceRepository` block and exactly one read-only transport. - -**Step 2: Run focused tests** - -Run: `cd backend && npx vitest run test/workspaces-git-repository.test.ts test/routes-workspaces.test.ts && cd ../tools/thothctl && go test ./internal/config` - -Expected: FAIL because repository identity and typed installation configuration do not exist. - -**Step 3: Implement safe normalization and installation validation** - -Add the normalized identity to registry status. Extend `thothii-installation.yaml` with remote, branch, and SSH/HTTPS access metadata, validate it against the selected Compose override and environment without reading or returning secret values, and retain the existing environment rendering boundary. - -**Step 4: Run focused tests** - -Run the command from Step 2. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend tools/thothctl deploy docs/install/examples -git commit -m "feat: declare workspace repository in installation config" -``` - -### Task 4: Add the persistent encrypted workspace secret store - -**Files:** -- Create: `backend/src/workspaces/secret-store.ts` -- Create: `backend/test/workspace-secret-store.test.ts` -- Modify: `backend/src/config.ts` -- Modify: `backend/src/app.ts` -- Modify: `compose.yaml` -- Modify: `deploy/compose.local.yaml` -- Modify: `deploy/compose.server.yaml` - -**Step 1: Write failing vault tests** - -Test first-start initialization, atomic blind replacement, deletion, enumeration by configured ID only, AES-256-GCM ciphertext with installation/workspace/field associated data, corruption failure, restrictive files/directories, size limits, and absence of plaintext in persistent bytes. - -**Step 2: Run the vault test** - -Run: `cd backend && npx vitest run test/workspace-secret-store.test.ts` - -Expected: FAIL because `WorkspaceSecretStore` does not exist. - -**Step 3: Implement the vault** - -Create an injectable `WorkspaceSecretStore` backed by an application-managed data root. Persist a versioned encrypted document atomically, generate or load the installation vault key in the private control area, expose only `has`, `put`, `delete`, and scoped materialization operations, and never add a plaintext read API. - -**Step 4: Run tests and typecheck** - -Run: `cd backend && npx vitest run test/workspace-secret-store.test.ts && npx tsc --noEmit -p .` - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend compose.yaml deploy -git commit -m "feat: persist encrypted workspace runtime secrets" -``` - -### Task 5: Derive connector requirements and integrate temporary materialization - -**Files:** -- Create: `backend/src/workspaces/secret-requirements.ts` -- Create: `backend/test/workspace-secret-requirements.test.ts` -- Modify: `backend/src/workspaces/bindings.ts` -- Modify: `backend/src/workspaces/runtime-config-lease.ts` -- Modify: `backend/src/tht/tht-runner.ts` -- Modify: `backend/src/app.ts` -- Modify: `backend/test/workspace-runtime-config-lease.test.ts` -- Modify: `backend/test/workspace-runtime-handoff.test.ts` -- Modify: `backend/test/workspaces-bindings.test.ts` - -**Step 1: Write failing requirement and lifecycle tests** - -Cover PostgreSQL password, REST bearer API key, unauthenticated REST, SSH private key/password, signed HTTP Evidence, and static S3 credentials. Assert temporary files are restrictive, live for exactly one diagnostic/runtime lease, disappear on release and error, and are never persisted in the encrypted vault document. - -**Step 2: Run focused tests** - -Run: `cd backend && npx vitest run test/workspace-secret-requirements.test.ts test/workspaces-bindings.test.ts test/workspace-runtime-config-lease.test.ts test/workspace-runtime-handoff.test.ts` - -Expected: FAIL because requirements still come from installation secret-file paths. - -**Step 3: Implement dynamic requirement resolution** - -Use the selected DWH transport and Evidence authentication contract to map trusted installation-contract suffixes to stable GUI requirement IDs. Overlay materialized temporary file paths only while resolving existing file-oriented connectors, and attach cleanup to every runtime lease. - -**Step 4: Run tests and typecheck** - -Run the command from Step 2 plus `cd backend && npx tsc --noEmit -p .`. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend/src backend/test -git commit -m "feat: resolve workspace secrets from connector requirements" -``` - -### Task 6: Add write-only workspace secret and readiness APIs - -**Files:** -- Modify: `backend/src/routes/workspaces.ts` -- Modify: `backend/src/app.ts` -- Modify: `backend/src/workspaces/types.ts` -- Modify: `backend/test/routes-workspaces.test.ts` - -**Step 1: Write failing API tests** - -Test `GET /workspaces/:id/runtime-configuration`, blind `PUT /workspaces/:id/secrets`, and `DELETE /workspaces/:id/secrets/:requirementId`. Assert strict bodies, limits, unknown-ID rejection, status-only responses, diagnostic invalidation, and `configuration_required`/`ready` state transitions. - -**Step 2: Run tests** - -Run: `cd backend && npx vitest run test/routes-workspaces.test.ts` - -Expected: FAIL because the routes do not exist. - -**Step 3: Implement the routes and readiness projection** - -Inject the secret store into workspace routes and runtime support. Compute per-workspace readiness from active descriptor, current requirement set, configured IDs, and diagnostic generation. Materialize values only inside the diagnostic request and always clean up. - -**Step 4: Run backend gates** - -Run: `cd backend && npx vitest run && npx tsc --noEmit -p . && npm run build`. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add backend -git commit -m "feat: manage runtime workspace secrets through the API" -``` - -### Task 7: Replace workspace management with the two-level read-only UI - -**Files:** -- Modify: `frontend/src/api/workspaces.ts` -- Modify: `frontend/src/api/workspaces.test.ts` -- Modify: `frontend/src/shell/WorkspaceManager.tsx` -- Modify: `frontend/src/shell/WorkspaceManager.test.tsx` -- Delete: `frontend/src/shell/WorkspacePublishDialog.tsx` -- Delete: corresponding publish-dialog tests -- Modify/Delete: `frontend/src/shell/WorkspaceEditor.tsx` and bootstrap-only tests as references permit -- Modify: `frontend/src/workspaces/drafts.ts` -- Modify: `frontend/src/workspaces/drafts.test.ts` - -**Step 1: Write failing UI/API tests** - -Assert the dialog uses at least 60% viewport width and height, shows general repository concepts and exact button consequences at level 1, gates workspace-specific controls on selection, renders requirement explanations and write-only fields at level 2, and has no create/edit/publish/import/export/bundle controls. - -**Step 2: Run focused tests** - -Run: `cd frontend && npx vitest run src/api/workspaces.test.ts src/shell/WorkspaceManager.test.tsx src/workspaces/drafts.test.ts` - -Expected: FAIL on the old draft/publish interface. - -**Step 3: Implement the read-only interface** - -Replace bootstrap editor state with repository status, selection, validation/readiness details, dynamic secret fields, blind save/forget actions, and connection test. Remove workspace draft persistence and clear secret field component state after submit/close. - -**Step 4: Run focused tests and typecheck** - -Run the command from Step 2 plus `cd frontend && npx tsc -b`. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add frontend -git commit -m "feat: add read-only workspace and secret management UI" -``` - -### Task 8: Remove browser-persisted workspace preferences - -**Files:** -- Modify: `frontend/src/workspaces/preferences.ts` -- Modify: `frontend/src/workspaces/preferences.test.ts` -- Modify: `frontend/src/api/sessions.ts` -- Modify: `frontend/src/api/sessions.test.ts` -- Modify: `frontend/src/shell/SteerInput.tsx` -- Modify: `frontend/src/shell/SteerInput.test.tsx` - -**Step 1: Write failing persistence-boundary tests** - -Assert workspace/model/thinking choices are kept only in current application memory or saved through the existing backend settings API, and that no workspace code calls `localStorage`. - -**Step 2: Run focused tests** - -Run: `cd frontend && npx vitest run src/workspaces/preferences.test.ts src/api/sessions.test.ts src/shell/SteerInput.test.tsx` - -Expected: FAIL because preferences still use browser storage. - -**Step 3: Implement ephemeral preferences** - -Replace the storage adapter with an in-memory external store seeded from backend settings. Preserve concurrent workspace-policy gates and session request determinism without persisting selections in the browser. - -**Step 4: Run frontend gates** - -Run: `cd frontend && npx vitest run && npx tsc -b && npm run build`. - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add frontend -git commit -m "refactor: stop persisting workspace state in the browser" -``` - -### Task 9: Update deployment contracts and documentation - -**Files:** -- Modify: `compose.yaml` -- Modify: `deploy/compose.git-ssh.yaml` -- Modify: `deploy/compose.git-https.yaml` -- Modify: `deploy/workspace-registry.env.example` -- Modify: `deploy/psd/operator.env.example` -- Modify: `docs/install/local-workspace-registry.md` -- Modify: `docs/install/server-workspace-registry.md` -- Modify: `docs/guida-utente.md` -- Modify: `scripts/verify-workspace-install-docs.sh` -- Modify: `scripts/workspace-registry-smoke.sh` - -**Step 1: Update executable contract tests first** - -Require read-only Git wording and configuration, repository identity visibility, vault persistence, -and absence of author/push/bundle/browser-secret instructions. - -**Step 2: Run contract tests and observe failure** - -Run: `bash scripts/verify-workspace-install-docs.sh` - -Expected: FAIL against the old manuals and examples. - -**Step 3: Update deployment and manuals** - -Remove Git author settings and write-oriented documentation. Document installation Git bootstrap, -GUI runtime-secret completion, platform-neutral application storage, rotation/forget flows, and -candidate validation semantics. - -**Step 4: Run contract and Go gates** - -Run: `bash scripts/verify-workspace-install-docs.sh && cd tools/thothctl && go test ./...` - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add compose.yaml deploy docs scripts tools/thothctl -git commit -m "docs: describe read-only workspace runtime configuration" -``` - -### Task 10: Full verification and deployed-container refresh - -**Files:** -- Modify only files needed to fix failures found by verification. - -**Step 1: Run static and unit gates** - -```bash -cd backend && npx vitest run && npx tsc --noEmit -p . && npm run build -cd ../frontend && npx vitest run && npx tsc -b && npm run build -cd ../harness && .venv/bin/pytest -q -cd ../tools/thothctl && go test ./... -``` - -Expected: all gates PASS. - -**Step 2: Run deployment contract gates** - -Run: `bash scripts/verify-workspace-install-docs.sh` and the focused workspace registry smoke appropriate to the configured installation. - -Expected: PASS without Git writes or secret disclosure. - -**Step 3: Inspect the final diff and secret scan** - -Run: `git diff --check`, inspect `git status --short`, and search active code/config for removed publish, bundle, Git author, and workspace-localStorage contracts. - -Expected: no whitespace errors, no accidental secrets, and only intended changes. - -**Step 4: Rebuild and restart affected services** - -Use the installation-aware `thothctl` lifecycle for the configured installation to rebuild/restart `core` and `frontend`, then verify health and repository status. Do not restart if no valid local installation descriptor is available; report that external gate explicitly. - -**Step 5: Commit verification fixes** - -```bash -git add -git commit -m "test: verify read-only workspace secret flow" -``` diff --git a/docs/plans/2026-08-18-evidence-canonica-design.md b/docs/plans/2026-08-18-evidence-canonica-design.md deleted file mode 100644 index 4e272754..00000000 --- a/docs/plans/2026-08-18-evidence-canonica-design.md +++ /dev/null @@ -1,217 +0,0 @@ -# Evidence canonica — struttura tipizzata per disambiguazione, schema linking e SQL - -> **Superseded (2026-08-24).** Questo documento conserva la storia della prima -> proposta. Il disegno approvato è -> [`2026-08-24-evidence-restructuring-design.md`](2026-08-24-evidence-restructuring-design.md) -> e il relativo piano esecutivo è -> [`2026-08-24-evidence-restructuring.md`](2026-08-24-evidence-restructuring.md). - -## Contesto e decisioni prese - -ThothII ha già due livelli separati che non si parlano: - -- **`EvidenceDoc`** (`harness/tht/evidence/model.py`) — runtime: frontmatter piatto - (`id/title/tier/status/tables/concepts/sources`) + `body` markdown libero. `tier` - distingue solo `structural|concept`, insufficiente rispetto ai 6 tipi reali del corpus. -- **Pipeline corpus** (`harness/tht/corpus/`) — canonizzazione *tecnica* (hash, - provenienza, chunking, vettorizzazione), agnostica rispetto al tipo di evidenza. - -Il corpus reale (`ChironeWp3/artifacts/evidence/`) ha una tassonomia implicita in 6 -directory (`00-glossario`, `10-domini-clinici`, `20-valori-enum`, `30-esempi-nlq`, -`40-mapping-semantico`, `50-metadati-normalizzazione`) ma: - -- frontmatter piatto, `tier` inadeguato; -- file già rotti (`--` invece di `---`, bullet `•⁠ ⁠` invece di `-`) che `EvidenceDoc.parse` - rifiuterebbe; -- al retrieval la struttura si perde: `tht search pack` proietta solo `title` + 400 char. - -**Decisioni (confermate nel brainstorming):** - -1. **Obiettivo**: strutturare il *contenuto* runtime, non toccare la pipeline corpus. -2. **Forma**: ibrido — frontmatter tipizzato + sezioni canoniche per `kind`. -3. **Tassonomia**: doppia — `kind` (contenuto) + `applies_to` (destinazioni: - `disambiguation`, `rewriting`, `schema_linking`, `sql_generation`, `memory`). -4. **Anchors come fonte primaria** per il value-grounding in F4; LSH solo fallback. -5. **Approccio**: contratto in `tht` + authoring sottile (niente app separata, niente - client LLM diretto in `tht`). -6. **Modello sorgente→canonizzato** (non sovrascrittura in place): file umani in - `source_root/evidence/`, canonizzati derivati in `artifacts/evidence/`, coerente con - l'esistente `tht evidence extract`. -7. **Review**: batch con diff aggregato (approvazione per file). -8. **Rielaborazione**: LLM-assistita via Pi (sessione di manutenzione + gate), con parte - deterministica in `tht`. - -## Modello canonico v2 - -### `CanonicalEvidence` (frontmatter tipizzato) - -```yaml ---- -schema_version: 2 -id: ev-dom-ablazione-see -title: Dominio Ablazione e SEE -kind: domain # glossario | domain | enum | example | mapping | normalization -applies_to: # destinazioni d'uso - - disambiguation # F1 - - schema_linking # F4 - - sql_generation # F6/F7 -status: reviewed -language: it -concepts: - - term: ablazione - synonyms: [ablazione transcatetere, SEE, studio elettrofisiologico] - - term: fibrillazione atriale - synonyms: [FA] -tables: - - name: datawarehouse.fact_studio_elettrofisiologico_endocavitario_ablazione - role: fact - columns: [ablazione_transcatetere, cod_paz, num] -anchors: - - column: datawarehouse.fact_see_ablazione_procedura_patologia.patologia - value: ablazione - match: exact -sources: [...] -# provenienza del derivato (aggiunta dal canonicalize, non dall'umano): -source_file: 10-domini-clinici/ablazione.md -source_fingerprint: sha256:... -canonicalized_at: 2026-08-18T... ---- -``` - -Il `body` resta markdown, ma con **titoli di sezione canonici per `kind`**: -- `glossario`: `## Definizione` -- `domain`: `## Cosa rappresenta`, `## Schema a stella`, `## Granularità`, `## Domande di business tipiche` -- `enum`: `## Valori ammessi` -- `example`: `## Domanda → SQL` + `## Nota clinica` -- `mapping`: `## Trasformazioni disponibili` -- `normalization`: `## Regole di normalizzazione` - -Le sezioni canoniche permettono al retrieval di estrarre solo la sezione rilevante per -fase invece di 400 caratteri generici. - -### `kind` vs `applies_to` - -- `kind` descrive il *contenuto* (i 6 tipi già impliciti). -- `applies_to` descrive *quando usarlo*. Esempi: `enum-tipo-intervento` è `kind: enum` ma - `applies_to: [disambiguation, sql_generation]`; un `example` è - `applies_to: [sql_generation, memory]`. - -## Modello a 3 livelli - -``` -source_root/evidence/*.md (umano, libero, può essere sporco) - │ tht evidence canonicalize (deterministico + LLM via Pi + review batch) - ▼ -artifacts/evidence/*.md (canonico, validato, derivato, rigenerabile) - │ tht evidence index (esistente) - ▼ -corpus / vector store (vettorializzato dal canonico, mai dal sorgente) -``` - -Il canonizzato porta `source_file` + `source_fingerprint`: se il sorgente cambia, la -canonizzazione ripropone il diff; se invariato, no-op. - -## Componenti da creare/modificare - -### 1. `harness/tht/evidence/model.py` (modifica) -- Aggiungere `CanonicalEvidence` (pydantic, v2) con `schema_version`, `kind`, - `applies_to`, `concepts[]` (`{term, synonyms[]}`), `tables[]` - (`{name, role, columns[]}`), `anchors[]` (`{column, value, match}`), `source_file`, - `source_fingerprint`, `canonicalized_at`. -- Validatore strict: `kind` ammesso, `applies_to` ammesso, `anchors[].column` deve - essere `schema.colonna` ben formato, `match` in `{exact, contains, regex, substring}`. -- `EvidenceDoc` v1 resta per leggere il sorgente e per retro-compatibilità dei vecchi - canonizzati; `CanonicalEvidence` è un modello separato, non una sottoclasse. -- Validatore che garantisce `source_fingerprint` = sha256 del contenuto sorgente. - -### 2. `harness/tht/evidence/lint.py` (nuovo, deterministico) -- `lint_source(path) -> list[Diagnostic]`: frontmatter rotto, `tier`/`status` non validi, - bullet Unicode, campi mancanti, `tables` non qualificate con schema, concetti senza - sinonimi, sezioni non canoniche per il `kind` atteso. -- Exit code 0 se nessun errore, 1 se warning, 2 se errori. Nessun LLM. - -### 3. `harness/tht/evidence/canonicalize.py` (nuovo) -- `plan(sources, artifacts) -> CanonicalizePlan`: confronta fingerprint dei sorgenti con - i canonizzati esistenti, produce la lista dei file da (ri)canonizzare. -- `render_proposal(source, llm_completions) -> CanonicalEvidence`: assembla il - canonizzato da parsing deterministico + campi semantici forniti da Pi. -- `apply(plan, approved_ids) -> None`: scrive solo i canonizzati approvati in - `artifacts/evidence/`, atomico per file, mantiene la gerarchia per dominio. -- `diff(source, candidate) -> str`: diff markdown per il gate. - -### 4. `harness/tht/vectorstore/records.py` (modifica) -- `evidence_records()`: metadata ora include `kind`, `applies_to`, `anchors` (non solo - `status/tier/tables/concepts`). -- Il `content` di ogni record resta title+body, ma per file con sezioni canoniche si - indicizza anche un record per sezione (id `evidence::`) così il retrieval - può restringere per sezione oltre che per documento. - -### 5. `harness/tht/search/__init__.py` + `cli/search_cmd.py` (modifica) -- `SearchResult` e `combined_search` accettano `applies_to` come filtro metadata. -- `tht search pack`: la sezione "Evidence rilevanti" ora proietta `kind` + sezione - canonica pertinente (non solo excerpt generico); usa `applies_to` per non mischiare - destinazioni. -- `tht search find --kind evidence --applies-to ` per il retrieval mirato. - -### 6. `harness/tht/cli/evidence_cmd.py` (modifica) -- Nuovi comandi: - - `tht evidence lint --source ` — diagnostica deterministica. - - `tht evidence canonicalize plan --source-root --json` — piano di - (ri)canonizzazione. - - `tht evidence canonicalize apply --plan --approved --json` — applica. -- `--json` sempre pristine (solo JSON su stdout), come da contratto di progetto. - -### 7. `harness/.pi/extensions/tht-gate.js` (modifica) -- Nuovo tool `reviewer_evidence_batch`: riceve il piano + i diff aggregati e presenta un - multiselect per file (approva/rifiuta/richiedi modifica). Le scelte approvate vengono - persistite tramite `tht evidence canonicalize apply`. -- Aggiungere `tht evidence canonicalize apply` alla FORBIDDEN anti-bypass list (il - modello non può applicare canonizzazioni senza review). - -### 8. Sessione di manutenzione Pi (nuova skill o sezione SKILL) -- Una skill dedicata `tht-evidence-canonicalize` (o un comando slash nel gate) descrive - la sessione di manutenzione: il modello legge i sorgenti marcati dal piano, propone i - campi semantici (`kind`, `applies_to`, `concepts` con sinonimi, `tables` con ruolo, - `anchors`) e li invia al `reviewer_evidence_batch`. -- Il gate è l'unico canale di review; il modello non scrive mai direttamente - `artifacts/evidence/`. - -### 9. `harness/.pi/skills/tht-sessione/SKILL.md` (modifica) -- Aggiornare i punti F1/F4/F6-F7 dove il modello legge evidence: spiegare che l'evidence - canonica espone `kind`/`applies_to`/`anchors`, che gli `anchors` sono la fonte primaria - per il value-grounding in F4, e che le sezioni canoniche vanno citate per destinazione. -- Aggiungere il nuovo tool `reviewer_evidence_batch` alla lista dei tool disponibili. - -## Migrazione del corpus (incrementale, v1+v2 convivono) - -- `CanonicalEvidence` (v2) convive con `EvidenceDoc` (v1): `lint` segnala i non-canonici - ma nulla si rompe; `load_evidence_dir` carica entrambi. -- Convertire a lotti, partendo da `20-valori-enum` e `10-domini-clinici` (impatto - maggiore su F1/F4, anchors più ricchi). -- Il canonizzato derivato in `artifacts/evidence/` sostituisce progressivamente il file - sorgente mirrorato; finché un sorgente non è canonizzato, `extract` continua a - rispecchiare il v1 come oggi. - -## Ordine di implementazione - -1. `CanonicalEvidence` + `lint` (TDD, nessun LLM). -2. `canonicalize.py` (plan/apply/diff) + comandi CLI (TDD). -3. `records.py` + filtro `applies_to` in `search` + proiezione pack (TDD). -4. Gate `reviewer_evidence_batch` + skill manutenzione Pi. -5. Aggiornamento `SKILL.md` tht-sessione. -6. Conversione primo lotto (`enum` + `domain`) con review batch. - -## Verifica - -- `cd harness && .venv/bin/pytest -q` — test nuovi per model/lint/canonicalize/records/search. -- `node --test` sul gate per `reviewer_evidence_batch` e anti-bypass. -- Su un campione del corpus: `tht evidence lint` riporta i file rotti (frontmatter `--`, - bullet Unicode) senza crash; `tht evidence canonicalize plan --json` produce piano - corretto; `apply` con fingerprint invariato è no-op. -- `tht search pack ""` mostra evidence con `kind`/sezione pertinente e - gli anchor presenti; `tht search find --kind evidence --applies-to schema_linking` - restituisce solo evidence pertinenti. -- Live: una sessione F4 su psd usa un anchor canonico per il value-grounding invece del - solo LSH (verificabile dal `reviewer_decide` con opzioni `value_grounded` provenienti - dall'evidence, non dal ranking LSH). -- `git diff --check` e typecheck/ruff puliti. diff --git a/docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md b/docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md index 930194a5..906fd942 100644 --- a/docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md +++ b/docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md @@ -1,6 +1,6 @@ # ThothII Authentication Acceptance and PSD Deployment Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to execute this plan task-by-task. +> **For agentic workers:** execute one task at a time, record its completion criteria, and stop at every documented approval boundary. **Goal:** Validate local and OIDC authentication on macOS, deploy the exact feat/thoth-auth candidate to the Aritmolab/PSD server before merging it into main, and complete end-to-end acceptance with remote Authentik. diff --git a/docs/plans/2026-08-19-tht-documentation-convergence.md b/docs/plans/2026-08-19-tht-documentation-convergence.md deleted file mode 100644 index 7bbe506d..00000000 --- a/docs/plans/2026-08-19-tht-documentation-convergence.md +++ /dev/null @@ -1,92 +0,0 @@ -# Tht Documentation Convergence Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. - -**Goal:** Align current documentation and documentation smoke checks with the converged native host CLI `tht`, while preserving historical references only where they describe past decisions or evidence. - -**Architecture:** Treat `tools/tht/cmd/tht/main.go` as the canonical host CLI surface for installation, authentication, diagnostics, lifecycle, and workspace operations. Keep the Python `harness/.venv/bin/tht` distinction explicit for the workflow runtime, and update current operator/test instructions to invoke the native `tht` with `--installation`. - -**Tech Stack:** Markdown documentation, shell smoke tests, Go CLI command surface, repository search-based verification. - ---- - -### Task 1: Classify current and historical legacy CLI references - -**Files:** -- Inspect: `README.md`, `PROJECT_STATE.md`, `AGENTS.md`, `docs/**`, `scripts/**` -- Reference: `tools/tht/cmd/tht/main.go` - -**Step 1:** Build a complete occurrence inventory with a case-insensitive search for the former host CLI name and classify every match. - -**Step 2:** Classify each occurrence as current operator documentation, documentation smoke expectation, executable/script contract, or historical design/evidence. - -**Step 3:** Record the classification in the implementation notes before editing. - -### Task 2: Update canonical operator and installation documentation - -**Files:** -- Modify: `README.md` -- Modify: `AGENTS.md` -- Modify: `PROJECT_STATE.md` -- Modify: `docs/guida-utente.md` -- Modify: `docs/contracts/workspace-preprocessing-cli.md` -- Rename/update: `docs/contracts/tht-pi.md` as the current `tht` Pi contract -- Modify: relevant installation and architecture pages that expose operator commands - -**Step 1:** Replace current host/operator invocations with `tht --installation ...`. - -**Step 2:** Document the distinction between the native host CLI `tht` and the Python harness CLI invoked by the backend/runtime. - -**Step 3:** Update command examples for `start`, `status`, `doctor`, `auth`, `workspace`, and `pi`. - -**Step 4:** Add a short historical note only where a document must explain the former name. - -### Task 3: Rewrite authentication acceptance and manual test instructions - -**Files:** -- Modify: `docs/testing/authentication-manual-acceptance.md` -- Modify: `docs/plans/2026-08-18-thothii-authentication-acceptance-and-psd-deployment.md` -- Modify: `docs/install/authentication-local.md` -- Modify: `docs/install/authentication-oidc.md` -- Modify: `docs/install/authentik.md` - -**Step 1:** Make `tht auth status`, `tht auth check`, `tht auth check --interactive`, and `tht doctor --json` the canonical terminal preflight. - -**Step 2:** Use `tht status`, `tht start`, and `tht workspace inspect --workspace psd-clinical --json` for PSD deployment checks. - -**Step 3:** Clarify that the P8 L2 gate is authentication-to-application integration through the first reviewer gate. - -**Step 4:** Retain the prior functional test suite as a baseline and add only the authentication boundary smoke required for this acceptance. - -### Task 4: Align documentation smoke tests - -**Files:** -- Modify: `scripts/auth-docs-smoke.sh` -- Modify: `scripts/test-auth-docs-smoke.sh` -- Inspect/update: any current smoke script whose user-facing command examples still require the legacy CLI name - -**Step 1:** Replace forbidden/current command assertions with `tht` equivalents. - -**Step 2:** Preserve negative checks for obsolete authentication CLI wording. - -**Step 3:** Run the positive and negative documentation fixtures. - -### Task 5: Preserve or annotate historical material - -**Files:** -- Inspect the historical discovery specification for context, without treating it as current operator documentation. -- Inspect: dated reports and archived acceptance scripts - -**Step 1:** Do not rewrite historical titles, commit evidence, or old implementation names solely to erase history. - -**Step 2:** Add a concise “historical nomenclature” note where an archived document could otherwise be mistaken for current instructions. - -### Task 6: Verify the convergence - -**Step 1:** Run `scripts/auth-docs-smoke.sh` and `scripts/test-auth-docs-smoke.sh`. - -**Step 2:** Search active documentation for remaining legacy CLI references. - -**Step 3:** Confirm every remaining match is either an explicit historical note, an ignored runtime directory name, or a non-document executable compatibility artifact. - -**Step 4:** Run `git diff --check` and report the exact files changed plus any intentionally retained historical references. diff --git a/docs/plans/2026-08-20-psd-server-deployment-program.md b/docs/plans/2026-08-20-psd-server-deployment-program.md index c8b5b692..6da39467 100644 --- a/docs/plans/2026-08-20-psd-server-deployment-program.md +++ b/docs/plans/2026-08-20-psd-server-deployment-program.md @@ -1,6 +1,6 @@ # PSD Server Deployment Program Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For agentic workers:** execute one task at a time, record its completion criteria, and stop at every documented approval boundary. **Goal:** Replace the legacy PSD ThothII installation, prove the replacement with local authentication, and then integrate the accepted release with Supabase, Authentik, Nginx, the load balancer, and the Aritmolab sidebar. diff --git a/docs/plans/2026-08-20-psd-server-project-a-standalone.md b/docs/plans/2026-08-20-psd-server-project-a-standalone.md index fd2e0882..3fac668a 100644 --- a/docs/plans/2026-08-20-psd-server-project-a-standalone.md +++ b/docs/plans/2026-08-20-psd-server-project-a-standalone.md @@ -1,6 +1,6 @@ # PSD Server Project A Standalone Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For agentic workers:** execute one task at a time, record its completion criteria, and stop at every documented approval boundary. **Goal:** Install a clean PSD ThothII stack with local authentication, direct read-only DWH access, internal Qdrant/Ollama, rebuilt preprocessing, and one completed F1-F8 work session. diff --git a/docs/plans/2026-08-20-psd-server-project-b-authentik.md b/docs/plans/2026-08-20-psd-server-project-b-authentik.md index 2baf0e1e..e985de3b 100644 --- a/docs/plans/2026-08-20-psd-server-project-b-authentik.md +++ b/docs/plans/2026-08-20-psd-server-project-b-authentik.md @@ -1,6 +1,6 @@ # PSD Server Project B Authentik Integration Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For agentic workers:** execute one task at a time, record its completion criteria, and stop at every documented approval boundary. **Goal:** Convert the accepted Project A installation to public OIDC mode, store owned work sessions in the existing Supabase database's `thoth_sessions` schema, and restore the established Aritmolab-sidebar user journey through the load balancer and Nginx. diff --git a/docs/plans/2026-08-20-psd-server-survey.md b/docs/plans/2026-08-20-psd-server-survey.md index 963ec60e..7ce68c78 100644 --- a/docs/plans/2026-08-20-psd-server-survey.md +++ b/docs/plans/2026-08-20-psd-server-survey.md @@ -1,6 +1,6 @@ # PSD Server Survey Implementation Plan -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. +> **For agentic workers:** execute one task at a time, record its completion criteria, and stop at every documented approval boundary. **Goal:** Produce a non-mutating, redacted survey of the PSD server that resolves every path, owner, network boundary, credential location, and rollback prerequisite needed by Projects A and B. diff --git a/docs/plans/2026-08-24-evidence-restructuring-design.md b/docs/plans/2026-08-24-evidence-restructuring-design.md index 9c90268e..a3337a64 100644 --- a/docs/plans/2026-08-24-evidence-restructuring-design.md +++ b/docs/plans/2026-08-24-evidence-restructuring-design.md @@ -1,7 +1,7 @@ # Ristrutturazione delle Evidence — disegno approvato **Stato:** approvato il 24 agosto 2026 -**Sostituisce:** `docs/plans/2026-08-18-evidence-canonica-design.md` +**Sostituisce:** il precedente disegno di Evidence canonica, disponibile nella storia Git **Ambito:** authoring, revisione, pubblicazione, indicizzazione e uso runtime delle Evidence ## 1. Obiettivo diff --git a/docs/plans/2026-08-24-evidence-restructuring.md b/docs/plans/2026-08-24-evidence-restructuring.md deleted file mode 100644 index 082e2a9a..00000000 --- a/docs/plans/2026-08-24-evidence-restructuring.md +++ /dev/null @@ -1,1326 +0,0 @@ -# Evidence Restructuring Implementation Plan - -> **Execution:** GitHub issue #35 is the approved parent specification. Issues #36–#47 -> are the executable tracer-bullet tickets; implement one unblocked ticket at a time -> with `/implement`. This document remains the detailed technical reference and must -> not be executed as a second, parallel work queue. - -**Goal:** Build a Git-reviewed, typed Evidence authoring pipeline and publish its approved output to the existing revision-scoped Qdrant lifecycle with dense+BM25 hybrid retrieval. - -**Architecture:** Keep authoring outside NL→SQL sessions: deterministic preparation wraps one read-only Pi restructuring call, writes reviewable Markdown into the workspace repository, and blocks publication on unresolved review items. Reuse the current Evidence module, corpus generations, rollback, active-revision checks, and workspace-owned semantic collection; extend them instead of introducing a parallel store. - -**Tech Stack:** Python 3.12, Pydantic 2, Typer, PyYAML, sqlglot, pytest, Pi CLI, TypeScript, Fastify workspace maintenance, Vitest, Qdrant 1.18.2 Query API, server-side `qdrant/bm25`, Git. - ---- - -## Preconditions - -- Work in this dedicated worktree. -- Read `PROJECT_STATE.md`, `CONTEXT.md`, - `docs/plans/2026-08-24-evidence-restructuring-design.md`, - `docs/contracts/workspace-evidence-v3.md`, and - `docs/contracts/workspace-preprocessing-cli.md`. -- Preserve the public facade in `harness/tht/evidence/__init__.py`. -- Do not edit `harness/.pi/skills/tht-sessione/SKILL.md` directly; regenerate it with - `python -m tht.pi_skill_projection --write`. -- Keep runtime workspace access read-only. Only the authoring CLI may write - `evidence/curated/` and `evidence/manifest.yaml` in a curator clone. -- Do not migrate the external PSD repository until all code and contract gates pass. - -### Task 1: Add the typed Curated Evidence model - -**Files:** - -- Create: `harness/tht/evidence/canonical.py` -- Modify: `harness/tht/evidence/__init__.py` -- Create: `harness/tests/test_evidence_canonical.py` - -**Step 1: Write failing tests for the common envelope** - -Cover: - -- all eight `kind` values; -- all four `purpose` values; -- immutable provenance; -- strict unknown-field rejection; -- kind-independent stable IDs; -- SHA-256 syntax; -- directory/`kind` agreement; -- parsing and dumping Markdown with YAML frontmatter. -- review items containing a stable `code`, human `message` and optional `field`, with no - status or history fields; -- IDs matching `evidence:` and remaining independent from `kind`. - -Start with: - -```python -def test_formula_requires_formula_payload(): - with pytest.raises(ValidationError): - CuratedEvidence.model_validate({ - **COMMON, - "kind": "formula", - "payload": {"concept": "fascia pediatrica"}, - }) - - -def test_reference_rejects_formula_payload(): - with pytest.raises(ValidationError): - CuratedEvidence.model_validate({ - **COMMON, - "kind": "reference", - "payload": { - "concept": "x", - "columns": ["clinical.patient.birth_date"], - "sql": "CASE WHEN true THEN 1 END", - }, - }) -``` - -**Step 2: Run the focused tests and confirm RED** - -Run: - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_canonical.py -q -``` - -Expected: import failure for `tht.evidence.canonical`. - -**Step 3: Implement the discriminated model** - -Use a strict Pydantic model with these public types: - -```python -EvidenceKind = Literal[ - "glossary", "domain", "enum", "example", "mapping", - "normalization", "formula", "reference", -] -EvidencePurpose = Literal[ - "disambiguation", "rewriting", "schema_linking", "sql_generation", -] - -class EvidenceScope(StrictModel): - concepts: tuple[str, ...] = () - tables: tuple[str, ...] = () - columns: tuple[str, ...] = () - -class EvidenceProvenance(StrictModel): - source_file: str - source_sha256: str - supporting_excerpts: tuple[str, ...] - -class FormulaPayload(StrictModel): - concept: str - columns: tuple[str, ...] - sql: str - -class ReviewItem(StrictModel): - code: str - message: str - field: str | None = None - -class ReferencePayload(StrictModel): - url: AnyHttpUrl - label: str - description: str -``` - -Define equally strict payloads for the other six kinds and expose a single -`CuratedEvidence` API. The implementation may use an internal Pydantic discriminated -union, but callers must not switch between eight unrelated loaders. - -Add: - -```python -def parse_curated_markdown(text: str, *, path: Path | None = None) -> CuratedEvidence: ... -def dump_curated_markdown(value: CuratedEvidence) -> str: ... -def load_curated_tree(root: Path) -> list[CuratedEvidence]: ... -``` - -Validate formula SQL with `sqlglot` as one PostgreSQL expression, rejecting complete -`SELECT`/`WITH` statements, DDL, DML and multiple statements. Validate `schema.table` / -`schema.table.column` identifiers without querying the DWH. -Require one to five supporting excerpts, each nonempty and at most 1,000 characters. - -**Step 4: Export only the stable API** - -Add the model and loader functions to `harness/tht/evidence/__init__.py`. Do not export -internal union member helpers unless another module needs them. - -**Step 5: Run tests and lint** - -Run: - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_canonical.py tests/test_evidence_facade_contract.py -q -.venv/bin/ruff check tht/evidence/canonical.py tests/test_evidence_canonical.py -``` - -Expected: PASS. - -**Step 6: Commit** - -```bash -git add harness/tht/evidence/canonical.py harness/tht/evidence/__init__.py \ - harness/tests/test_evidence_canonical.py -git commit -m "feat(evidence): add typed curated evidence model" -``` - -### Task 2: Add deterministic validation and the Evidence manifest - -**Files:** - -- Create: `harness/tht/evidence/authoring.py` -- Create: `harness/tests/test_evidence_authoring.py` -- Modify: `harness/tht/evidence/__init__.py` - -**Step 1: Write failing tests for publication validation** - -Test that: - -- `review_items != []` is valid as a draft but blocks publication; -- `orphans != []` is preserved but blocks publication; -- a missing or mismatched source hash blocks publication; -- every supporting excerpt is found after applying the same mechanical normalization - to the excerpt and its source; -- two units cannot share an ID; -- one unit cannot claim two source files; -- `curated/formula/x.md` must contain `kind: formula`; -- credentials in URLs, YAML, or body are rejected; -- only Markdown, `.txt`, and `.sql.md` sources are accepted; -- UTF-8 and per-file limits are enforced. - -Expose errors as bounded structured values: - -```python -@dataclass(frozen=True) -class ValidationFinding: - severity: Literal["error", "warning"] - code: str - path: str - message: str -``` - -**Step 2: Write failing tests for the versioned manifest** - -Use this minimum shape: - -```yaml -schema_version: 1 -pipeline_version: evidence-authoring-v1 -sources: - source/domain/patient.md: - sha256: sha256:... - units: - - domain:patient -orphans: [] -``` - -Test deterministic key ordering, stable round-trip, unknown fields, duplicate unit IDs, -orphan preservation and incompatible `pipeline_version` refusal. - -**Step 3: Run and confirm RED** - -Run: - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_authoring.py -q -``` - -Expected: missing authoring API. - -**Step 4: Implement `EvidenceManifest` and `validate_workspace_evidence`** - -Provide: - -```python -def load_manifest(path: Path) -> EvidenceManifest: ... -def dump_manifest(manifest: EvidenceManifest) -> str: ... -def validate_workspace_evidence(workspace_root: Path) -> ValidationReport: ... -``` - -`ValidationReport.publishable` is true only when there are no errors and no unresolved -review items or orphaned units. Warnings alone do not block publication. - -Do not use status fields such as `draft/reviewed` as an approval mechanism. The approved -Git revision is the publication boundary. - -**Step 5: Run tests and lint** - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_authoring.py tests/test_evidence_canonical.py -q -.venv/bin/ruff check tht/evidence/authoring.py tests/test_evidence_authoring.py -``` - -Expected: PASS. - -**Step 6: Commit** - -```bash -git add harness/tht/evidence/authoring.py harness/tht/evidence/__init__.py \ - harness/tests/test_evidence_authoring.py -git commit -m "feat(evidence): validate curated corpus and manifest" -``` - -### Task 3: Implement incremental preparation with one Pi restructuring call - -**Files:** - -- Modify: `harness/tht/evidence/authoring.py` -- Create: `harness/.pi/skills/tht-evidence-authoring/SKILL.md` -- Modify: `harness/tests/test_evidence_authoring.py` -- Create: `harness/tests/test_evidence_pi_restructurer.py` - -**Step 1: Define the restructuring port and request/response models** - -Add: - -```python -class EvidenceRestructurer(Protocol): - def restructure(self, request: RestructureRequest) -> tuple[RestructureCandidate, ...]: ... - -class RestructureRequest(StrictModel): - source_file: str - source_sha256: str - normalized_text: str - previous_units: tuple[CuratedEvidence, ...] = () - -class RestructureCandidate(StrictModel): - existing_id: str | None = None - # The same title, kind, purposes, scope, provenance excerpts and typed payload - # needed to construct CuratedEvidence, but no model-assigned canonical ID. -``` - -`existing_id`, when present, must belong to `previous_units`. The preparer rejects any -unknown ID and deterministically allocates `evidence:` plus a collision suffix for -every candidate without one. The response is converted to and validated through the -models from Task 1 before any write. - -**Step 2: Write RED tests for the incremental rules** - -Test: - -- unchanged source: no model call and no file write; -- changed source: exactly one model call; -- new source: new stable IDs; -- removed source: old units become orphans and remain on disk; -- uniquely renamed source with the same hash: provenance changes and unit IDs remain; -- existing source no longer supporting a prior unit: retain it with - `source_no_longer_supports_unit` and block publication; -- kind-only reclassification: preserve the unit ID; -- semantic split: allocate new IDs for the new independent units; -- a semantic split retains the previous unit as a blocking retirement candidate until - the curator explicitly retires it; -- one source may produce several units; -- every returned unit contains one to five exact supporting excerpts found in its - normalized source; -- no returned unit may cite another source; -- prior curated units are included in the request; -- a dirty `evidence/curated/` or `evidence/manifest.yaml` fails before the model call; -- committed human edits remain recoverable in Git and every proposed change is exposed - in the working-tree diff; -- all output writes are staged and atomically replaced only after complete validation. -- one invalid source leaves the complete batch and manifest unchanged; - -Inject the Git status runner and filesystem writer in tests; do not require a real Git -repository for every unit test. - -**Step 3: Implement deterministic source normalization** - -Normalize UTF-8 text with NFC, LF newlines and terminal newline. Preserve meaningful -Markdown, tables, fenced SQL, URLs and list structure. Do not rewrite vocabulary or -infer domain facts in this step. - -**Step 4: Implement `PiEvidenceRestructurer`** - -Invoke Pi as an ephemeral, no-tools process using an argument list, never a shell: - -```python -argv = [ - pi_executable, - "--mode", "text", - "--print", - "--no-session", - "--no-tools", - "--no-extensions", - "--no-context-files", - "--skill", str(skill_path), - f"@{request_path}", - "Return only the JSON object required by the Evidence authoring skill.", -] -``` - -Use a private `TemporaryDirectory`, a bounded timeout, bounded stdout/stderr, and strict -JSON parsing. Do not forward the model's raw output to public JSON errors. The skill must -state: - -- use only facts present in `normalized_text`; -- preserve prior reviewed wording where it remains supported; -- retain unsupported prior units with a `source_no_longer_supports_unit` review item; -- never merge sources; -- emit `review_items` for uncertainty; -- copy short exact supporting excerpts from `normalized_text`; -- use only a supplied `existing_id` or omit it for deterministic allocation; -- emit exactly the schema-versioned JSON object and no Markdown fence. - -Do not retry automatically after a timeout, nonzero exit, malformed JSON or invalid -response. Return a stable error code and the affected source so the curator can rerun -the command explicitly. - -**Step 5: Implement `prepare_workspace_evidence`** - -Return a bounded report with `changed`, `unchanged`, `created`, `orphaned`, `findings`, -and `model_calls`. Keep the model implementation behind `EvidenceRestructurer`. Build -the complete batch in a private staging directory and replace curated files plus the -manifest only after every candidate validates; never expose partial success. - -**Step 6: Run tests** - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_authoring.py tests/test_evidence_pi_restructurer.py -q -.venv/bin/ruff check tht/evidence/authoring.py tests/test_evidence_pi_restructurer.py -``` - -Expected: PASS with no live model call. - -**Step 7: Commit** - -```bash -git add harness/tht/evidence/authoring.py \ - harness/.pi/skills/tht-evidence-authoring/SKILL.md \ - harness/tests/test_evidence_authoring.py harness/tests/test_evidence_pi_restructurer.py -git commit -m "feat(evidence): prepare curated evidence incrementally" -``` - -### Task 4: Add the authoring CLI - -**Files:** - -- Create: `harness/tht/cli/evidence_cmd.py` -- Modify: `harness/tht/cli/__init__.py` -- Create: `harness/tests/test_evidence_cli.py` - -**Step 1: Write CLI grammar tests** - -Cover: - -```text -tht evidence prepare [--upgrade] [--json] -tht evidence validate [--json] -tht evidence resolve --retire [--json] -tht evidence resolve --source [--json] -``` - -Require an existing canonical Git worktree root. Reject unknown flags, symlinks, a -workspace path outside the Git root, duplicate options and dirty curated state. A -pipeline-version mismatch must fail without writes unless `--upgrade` is explicit; -`--upgrade` reprocesses every source. Ensure `--json` writes pristine JSON to stdout. -For `resolve`, require exactly one of `--retire` and `--source`, an existing Evidence ID, -an existing in-root source path for relinking and a clean worktree. Test atomic updates -to the curated file and manifest, with no commit or publication side effect. - -**Step 2: Run and confirm RED** - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_cli.py -q -``` - -Expected: `evidence` command group is unknown. - -**Step 3: Implement the Typer group** - -Use one top-level authoring group: - -```python -evidence_app = typer.Typer(help="Prepare and validate workspace Evidence") - -@evidence_app.command("prepare") -def prepare_cmd(workspace_root: Path, json_output: bool = False) -> None: ... - -@evidence_app.command("validate") -def validate_cmd(workspace_root: Path, json_output: bool = False) -> None: ... - -@evidence_app.command("resolve") -def resolve_cmd( - workspace_root: Path, - evidence_id: str, - retire: bool = False, - source: Path | None = None, - json_output: bool = False, -) -> None: ... -``` - -Register it in `harness/tht/cli/__init__.py`. Keep this separate from the existing -runtime command `tht preprocess evidence`. - -Exit codes: - -- `0`: prepared/unchanged or valid; -- `2`: unsafe path or CLI misuse; -- `3`: valid drafts but review required; -- `1`: operational/model/structural failure. - -**Step 4: Run tests and CLI help** - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_cli.py tests/test_preprocess_cli.py -q -.venv/bin/tht evidence --help -.venv/bin/tht preprocess evidence --help -``` - -Expected: both command families are present and unambiguous. - -**Step 5: Commit** - -```bash -git add harness/tht/cli/evidence_cmd.py harness/tht/cli/__init__.py \ - harness/tests/test_evidence_cli.py -git commit -m "feat(evidence): expose prepare and validate commands" -``` - -### Task 5: Project typed units into semantic Evidence Fragments - -**Files:** - -- Modify: `harness/tht/evidence/corpus/models.py` -- Modify: `harness/tht/evidence/corpus/chunk.py` -- Modify: `harness/tht/evidence/corpus/normalize.py` -- Modify: `harness/tht/evidence/corpus/pipeline.py` -- Modify: `harness/tht/evidence/preprocessing.py` -- Modify: `harness/tests/test_corpus_models.py` -- Modify: `harness/tests/test_corpus_chunk.py` -- Modify: `harness/tests/test_corpus_pipeline.py` - -**Step 1: Write failing projection tests** - -Test that: - -- a short formula remains one fragment; -- a domain document splits only at semantic section boundaries; -- enum entries are not split in the middle of a value/meaning pair; -- formulas, value/meaning pairs, mappings, rules and URLs are never split; -- the complete rendered fragment, including labels and textual metadata, uses the - existing `max_chunk_chars` setting whose default is 4,000 characters; -- an atomic element over `max_chunk_chars` produces the blocking - `atomic_content_too_large` review item instead of fixed-size chunks, with no second - size setting; -- all fragments carry `evidence_id`, `evidence_kind`, `purposes`, scope, language and - provenance; -- fragment IDs and ordinals are deterministic; -- only `curated/**/*.md` is accepted as canonical filesystem content. - -**Step 2: Extend the immutable corpus models** - -Keep `CanonicalDocument` and `CanonicalChunk` as transport-neutral storage models. Put -typed Evidence metadata in their already-safe `metadata` field, with exact allowlisted -keys. Do not make corpus storage depend on Pydantic subtype classes at read time. - -**Step 3: Implement kind-aware fragment rendering** - -Construct embedding text from title, purpose, scope and type-specific data. Example for -a formula: - -```text -Formula: Fascia pediatrica -Concept: fascia pediatrica -Columns: clinical.patient.birth_date -SQL: CASE WHEN ... END -Limitations: ... -``` - -The rendered text is derived; provenance and canonical content remain in the corpus -manifest. - -**Step 4: Run focused pipeline tests** - -```bash -cd harness -.venv/bin/pytest tests/test_corpus_models.py tests/test_corpus_chunk.py \ - tests/test_corpus_normalize.py tests/test_corpus_pipeline.py \ - tests/test_corpus_publish.py -q -``` - -Expected: PASS, including existing rollback, compensation, retention and resume tests. - -**Step 5: Commit** - -```bash -git add harness/tht/evidence/corpus harness/tht/evidence/preprocessing.py \ - harness/tests/test_corpus_models.py harness/tests/test_corpus_chunk.py \ - harness/tests/test_corpus_normalize.py harness/tests/test_corpus_pipeline.py -git commit -m "feat(evidence): build semantic fragments from typed units" -``` - -### Task 6: Add BM25 to the existing Qdrant collection without rebuilding it - -**Files:** - -- Modify: `backend/src/workspaces/qdrant-collection.ts` -- Modify: `backend/src/workspaces/evidence/preprocessing.ts` -- Modify: `backend/test/qdrant-collection.test.ts` -- Modify: `backend/test/workspaces/evidence/preprocessing.test.ts` -- Modify: `harness/tht/adapters/vector/qdrant.py` -- Modify: `harness/tests/test_qdrant_vector_store.py` -- Modify: `docs/contracts/workspace-preprocessing-cli.md` - -**Step 1: Write RED TypeScript collection-contract tests** - -The required vector contract is: - -```json -{ - "vectors": {"size": 1024, "distance": "Cosine"}, - "sparse_vectors": { - "bm25": {"modifier": "idf"} - } -} -``` - -Keep the current unnamed dense vector. Test three distinct states: - -- compatible: unnamed dense is correct and `bm25` has `modifier: idf`; -- Evidence-upgradeable: unnamed dense is correct and `bm25` is absent; -- incompatible: dense dimension/distance is wrong, dense is unexpectedly named, or - `bm25` exists with a different configuration. - -Only the Evidence maintenance path may turn the upgradeable state into compatible by -adding `bm25`. Session admission and searches remain read-only. Missing payload indexes -may still use the existing additive reconciliation; no path may delete or rename a -vector. - -Add keyword indexes only for fields used by filters: - -```text -content_hash, document_id, kind, record_key, record_kind, -vector_generation, workspace_id, workspace_revision, -evidence_id, evidence_kind, purposes, concepts, tables, columns, language -``` - -**Step 2: Run the TypeScript test and confirm RED** - -```bash -cd backend -npx vitest run test/qdrant-collection.test.ts -``` - -Expected: the new additive BM25 expectations fail. - -**Step 3: Implement additive BM25 reconciliation** - -Keep base `vectorCompatibility` concerned with the unnamed dense contract used by -Schema and Memory. Add an Evidence-specific compatibility result that also classifies -`bm25` as compatible, upgradeable or incompatible. Update `createCollection` and the -Evidence preprocessing preflight: a new collection is created with unnamed dense plus -`bm25`; on an existing upgradeable collection, `workspace preprocess evidence` calls -Qdrant's additive vector-schema endpoint to create only `bm25` with IDF, then verifies -the result before upload. Retain `require_existing` behavior for ordinary runtime -validation: it never mutates. An incompatible state fails without changes. Missing -BM25 does not make Schema or Memory unavailable; only Evidence reports `unavailable`. - -**Step 4: Update the Python adapter's collection validation** - -`QdrantVectorStore.health()` and `_ensure_collection()` must recognize exactly the same -contract as TypeScript. Add a shared test fixture shape even though the two languages do -not share implementation code. - -**Step 5: Run backend and harness tests** - -```bash -cd backend -npx vitest run test/qdrant-collection.test.ts test/workspaces/evidence/preprocessing.test.ts -npx tsc --noEmit -p . -cd ../harness -.venv/bin/pytest tests/test_qdrant_vector_store.py tests/test_vector_port_contract.py -q -``` - -Expected: PASS. - -**Step 6: Document the additive maintenance behavior** - -Update the CLI contract to state that `workspace preprocess evidence` may add the -missing `bm25` definition but may not delete or rename vectors. The existing destructive -`workspace vector rebuild` command remains available for unrelated operator recovery -and is not used by this migration. - -**Step 7: Commit** - -```bash -git add backend/src/workspaces/qdrant-collection.ts \ - backend/src/workspaces/evidence/preprocessing.ts \ - backend/test/qdrant-collection.test.ts backend/test/workspaces/evidence/preprocessing.test.ts \ - harness/tht/adapters/vector/qdrant.py \ - harness/tests/test_qdrant_vector_store.py docs/contracts/workspace-preprocessing-cli.md -git commit -m "feat(evidence): add qdrant bm25 vector in place" -``` - -### Task 7: Add server-side BM25 ingestion and hybrid Query API retrieval - -**Files:** - -- Modify: `harness/tht/ports/vector.py` -- Modify: `harness/tht/adapters/vector/qdrant.py` -- Modify: `harness/tht/vectorstore/records.py` -- Modify: `harness/tht/evidence/corpus/pipeline.py` -- Modify: `harness/tests/test_vector_port_contract.py` -- Modify: `harness/tests/test_qdrant_vector_store.py` -- Modify: `harness/tests/test_corpus_pipeline.py` -- Create: `harness/tests/l0/test_qdrant_bm25_inference.py` - -**Step 1: Write RED port tests** - -Extend, do not replace, the current record: - -```python -@dataclass(frozen=True) -class VectorWriteRecord: - record: VectorRecord - embedding: list[float] - content_hash: str - sparse_text: str | None = None - sparse_language: str | None = None -``` - -Extend `VectorStore.search` with keyword-only `query_text` and `query_language`. Existing -callers that omit them remain dense-only. - -**Step 2: Write exact Qdrant request tests** - -For Evidence upsert, assert: - -```json -"vector": { - "": [0.1, 0.2], - "bm25": { - "text": "...", - "model": "qdrant/bm25", - "options": {"language": "italian"} - } -} -``` - -For hybrid search, assert two filtered prefetches and default RRF: - -```json -{ - "prefetch": [ - {"query": [0.1, 0.2], "limit": 20, "filter": {}}, - { - "query": { - "text": "fascia pediatrica", - "model": "qdrant/bm25", - "options": {"language": "italian"} - }, - "using": "bm25", - "limit": 20, - "filter": {} - } - ], - "query": {"rrf": {}}, - "limit": 10, - "with_payload": true -} -``` - -Both prefetch filters must include workspace, revision, active generation and record -kind. Do not add hand-tuned weights. - -**Step 3: Prove BM25 on the actual local Qdrant image** - -Add an `l0` test that reads the Qdrant image reference from the root `compose.yaml`, -starts that exact image with testcontainers, creates a uniquely named temporary -collection, adds `bm25` with IDF, indexes two Italian texts through server-side -`qdrant/bm25`, retrieves the expected text and deletes the collection. The test must -not use FastEmbed or accept a dense fallback. It fails if the Compose reference and the -tested image diverge. - -**Step 4: Preserve dense writes for all existing semantic records** - -Schema, Memory and solved-question records keep their current unnamed dense writes. -Evidence records use the empty default-vector name plus `bm25` in the mixed-vector -upsert shape. Only records with `sparse_text` receive `bm25`; no full reindex of Schema -or Memory is performed. - -**Step 5: Implement BM25 Evidence ingestion** - -Populate `sparse_text` and map workspace language `it` to Qdrant's `italian`. Reject an -unsupported language before uploading the generation. Use the same options at ingest -and query time. - -**Step 6: Implement hybrid search with dense fallback only for non-Evidence callers** - -An Evidence hybrid request must fail as unavailable if the configured Qdrant version or -collection contract does not support BM25. It must not silently claim to have run hybrid -search. Existing non-Evidence dense requests continue to work. - -**Step 7: Run focused tests** - -```bash -cd harness -.venv/bin/pytest tests/test_vector_port_contract.py tests/test_qdrant_vector_store.py \ - tests/test_corpus_pipeline.py tests/test_search_pack.py -q -.venv/bin/pytest tests/l0/test_qdrant_bm25_inference.py -m l0 -q -.venv/bin/ruff check tht/ports/vector.py tht/adapters/vector/qdrant.py \ - tht/evidence/corpus/pipeline.py -``` - -Expected: PASS. - -**Step 8: Commit** - -```bash -git add harness/tht/ports/vector.py harness/tht/adapters/vector/qdrant.py \ - harness/tht/vectorstore/records.py harness/tht/evidence/corpus/pipeline.py \ - harness/tests/test_vector_port_contract.py harness/tests/test_qdrant_vector_store.py \ - harness/tests/test_corpus_pipeline.py harness/tests/l0/test_qdrant_bm25_inference.py -git commit -m "feat(evidence): add qdrant bm25 hybrid retrieval" -``` - -### Task 8: Add the typed Evidence search contract and workflow-owned purposes - -**Files:** - -- Modify: `harness/tht/evidence/search.py` -- Modify: `harness/tht/evidence/__init__.py` -- Modify: `harness/tht/evidence/session.py` -- Modify: `harness/tht/cli/search_cmd.py` -- Modify: `harness/tht/session/filesystem_repository.py` -- Modify: `harness/tht/session/postgres_repository.py` -- Modify: `harness/tests/test_evidence_facade_contract.py` -- Create: `harness/tests/test_evidence_session_receipts.py` -- Modify: `harness/tests/test_search_pack.py` -- Create: `harness/.pi/skills/tht-sessione/modules/evidence/runtime-search.md` -- Modify: `harness/.pi/skills/tht-sessione/projection.md.tmpl` -- Modify: `harness/tht/pi_skill_projection.py` -- Modify: `harness/tests/test_pi_skill_projection.py` -- Regenerate: `harness/.pi/skills/tht-sessione/SKILL.md` - -**Step 1: Write RED search-facade tests** - -Introduce: - -```python -class EvidenceSearchContext(BaseModel): - concepts: tuple[str, ...] = () - tables: tuple[str, ...] = () - columns: tuple[str, ...] = () - required_kinds: tuple[EvidenceKind, ...] = () - required_concepts: tuple[str, ...] = () - required_tables: tuple[str, ...] = () - required_columns: tuple[str, ...] = () - -def search_evidence( - query: str, - purpose: EvidencePurpose, - context: EvidenceSearchContext, - *, - searcher: ActiveEvidenceSearcher, - embedder: EvidenceQueryEmbedder, - top_n: int = 10, -) -> EvidenceSearchOutcome: ... -``` - -Test hard filters for workspace, revision, generation, purpose and every explicit -`required_*` constraint. Concepts, tables and columns without the `required_` prefix -enrich the dense and BM25 query text but do not create payload filters. Do not add -implicit kind or scope bonuses in v1. - -Render that enrichment once, identically for both retrieval branches, in this fixed -order: - -```text -Domanda: -Concetti: -Tabelle: -Colonne: -``` - -Omit empty lines and do not rewrite the original question. Test that permutations and -duplicates in context produce the same rendered text and that the dense embedder and -BM25 request receive exactly that same value. - -The renderer normalizes the question to Unicode NFC, converts CRLF and CR to `\n`, -strips only leading and trailing whitespace and rejects an empty result. It preserves -case, punctuation and internal whitespace. Apply NFC and `strip` to context values, -remove empty strings and exact duplicates, then sort by Unicode value. Do not call -`lower()` or `casefold()` because quoted PostgreSQL identifiers can be case-sensitive. - -`EvidenceSearchOutcome` has an `available` state with a generation and zero or more -results, and an `unavailable` state with a stable error code, a bounded message and no -results. `memory` is not an `EvidencePurpose`: the `memory` stage remains owned by the -Memory Module. - -**Step 2: Test fragment grouping** - -Two returned fragments with the same `evidence_id` must become one `EvidenceResult`, -with the best score, ordered matching excerpts, canonical citation, a reference for -resolving the full document and no duplicate unit. Do not insert the full document into -the search pack automatically. - -**Step 3: Distinguish an empty search from technical unavailability** - -Test a successful search with zero matches separately from absent ACTIVE corpus, -revision mismatch, unavailable Qdrant and malformed payload. The first returns -`available` with an empty result list and may continue. Every technical case returns -`unavailable`, blocks the calling stage until retry, and never uses stale rows or a -fallback purpose. - -**Step 4: Implement the facade and CLI mapping** - -Keep Qdrant syntax inside `tht.evidence`. `search_cmd.py` translates command inputs to -the facade and renders results; it must not duplicate ranking logic. - -**Step 5: Integrate the contributor with semantic stages** - -Move the shared Evidence rules from the projection template into -`modules/evidence/runtime-search.md`. The fragment must state: - -- candidates are not truth; -- pass the phase-appropriate purpose; -- show provenance; -- formulas are `kind=formula`, not a separate search store; -- an available empty result is visible and does not block the stage; -- an unavailable outcome blocks the stage and is retriable; -- Evidence never writes decisions, canonical artifacts or workflow state. - -Map semantic stages, independently of their display codes: - -```text -clarification -> disambiguation -rewriting -> rewriting -schema_linking -> schema_linking -cte -> sql_generation -final_sql -> sql_generation -``` - -Do not invoke Evidence from `memory` or `synthesis`. Run an independent search in every -mapped stage; the `final_sql` query includes the approved CTE plan. - -**Step 6: Persist the minimal Evidence receipt** - -Use the existing session artifact repositories to maintain one -`evidence_receipts.json` artifact. For every available search, append or replace the -receipt identified by semantic stage with exactly `stage`, `purpose`, -`vector_generation` and ordered `evidence_ids`. Do not copy excerpts or complete -Evidence text. The workflow integration owns the write; `tht.evidence` only constructs -and returns the typed receipt. Test filesystem and PostgreSQL repositories, resume and -retry replacement. - -Register the fragment in the static `FRAGMENT_ORDER` and regenerate. - -**Step 7: Run tests** - -```bash -cd harness -python -m tht.pi_skill_projection --write -python -m tht.pi_skill_projection --check -.venv/bin/pytest tests/test_evidence_facade_contract.py tests/test_search_pack.py \ - tests/test_evidence_session_receipts.py \ - tests/test_pi_skill_projection.py -q -``` - -Expected: PASS and no direct edit drift in generated `SKILL.md`. - -**Step 7: Commit** - -```bash -git add harness/tht/evidence/search.py harness/tht/evidence/__init__.py \ - harness/tht/cli/search_cmd.py harness/tests/test_evidence_facade_contract.py \ - harness/tests/test_search_pack.py \ - harness/.pi/skills/tht-sessione/modules/evidence/runtime-search.md \ - harness/.pi/skills/tht-sessione/projection.md.tmpl \ - harness/.pi/skills/tht-sessione/SKILL.md harness/tht/pi_skill_projection.py \ - harness/tests/test_pi_skill_projection.py -git commit -m "refactor(evidence): own typed runtime retrieval" -``` - -### Task 9: Migrate formulas into Curated Evidence - -**Files:** - -- Modify: `harness/tht/evidence/formula_store.py` -- Modify: `harness/tht/evidence/session.py` -- Modify: `harness/tht/cli/search_cmd.py` -- Create: `harness/.pi/skills/tht-sessione/modules/evidence/formula-proposals.md` -- Modify: `harness/.pi/skills/tht-sessione/projection.md.tmpl` -- Modify: `harness/tht/pi_skill_projection.py` -- Modify: `harness/tests/test_formula.py` -- Modify: `harness/tests/test_formula_wiring.py` -- Create: `harness/tests/test_evidence_formula_migration.py` -- Modify: `harness/tests/test_pi_skill_projection.py` -- Regenerate: `harness/.pi/skills/tht-sessione/SKILL.md` - -**Step 1: Write RED migration tests** - -Map an approved legacy `ConceptFormula` to a Curated Evidence formula while preserving: - -- concept; -- SQL; -- columns; -- sources as provenance notes; -- stable deterministic ID; -- reviewed content wording. - -Reject `auto` and unresolved `draft` formulas from direct publication; they become -Formula proposals. - -**Step 2: Define the session proposal contract** - -Add a schema-versioned formula-proposal projection in the session artifact. Keep -`concept_formula_approved` / `concept_formula_rejected` decisions unchanged because they -record a session-local choice, not repository publication. - -**Step 3: Remove the separate runtime formula lookup** - -Change `tht search find --kind formula` to call typed Evidence search with -`required_kinds=("formula",)`. Keep the legacy store readable only for the migration -command/window, with a deprecation warning in human output and no warning leakage into -pristine JSON. - -**Step 4: Add and project formula instructions** - -The Evidence fragment must say that a newly synthesized formula is a session proposal -and cannot be treated as Published Evidence. - -**Step 5: Run tests** - -```bash -cd harness -python -m tht.pi_skill_projection --write -.venv/bin/pytest tests/test_formula.py tests/test_formula_wiring.py \ - tests/test_evidence_formula_migration.py tests/test_pi_skill_projection.py \ - tests/test_decision_min_phase.py tests/test_workflow_observable_contract.py -q -``` - -Expected: PASS; decision phase ownership remains F4. - -**Step 6: Commit** - -```bash -git add harness/tht/evidence/formula_store.py harness/tht/evidence/session.py \ - harness/tht/cli/search_cmd.py \ - harness/.pi/skills/tht-sessione/modules/evidence/formula-proposals.md \ - harness/.pi/skills/tht-sessione/projection.md.tmpl \ - harness/.pi/skills/tht-sessione/SKILL.md harness/tht/pi_skill_projection.py \ - harness/tests/test_formula.py harness/tests/test_formula_wiring.py \ - harness/tests/test_evidence_formula_migration.py harness/tests/test_pi_skill_projection.py -git commit -m "refactor(evidence): unify formulas with typed evidence" -``` - -### Task 10: Add the small retrieval evaluation command - -**Files:** - -- Create: `harness/tht/evidence/evaluation.py` -- Modify: `harness/tht/cli/evidence_cmd.py` -- Create: `harness/tests/test_evidence_evaluation.py` -- Modify: `harness/tests/test_evidence_cli.py` - -**Step 1: Write RED schema tests** - -Use a deliberately small format: - -```yaml -schema_version: 1 -queries: - - id: pediatric-formula - query: Come distinguo i pazienti pediatrici? - profile: semantic - purpose: sql_generation - expected: - - evidence:fascia-pediatrica -``` - -Require unique query IDs, nonempty expected IDs, one of `lexical`, `semantic` or -`mixed` for every profile, only public purpose values and at least one query of every -profile in the complete file. - -**Step 2: Write RED metric tests** - -Compute `hit_at_5`, `hit_at_10`, missing expected IDs, empty-result queries and counts by -expected `kind`. For each expected ID, also report its nullable dense-only, BM25-only -and fused rank. The evaluator runs both branches separately for diagnosis and the same -hybrid request used by runtime. The report passes only when every query finds at least -one expected ID in its first ten fused results; branch ranks and `hit_at_5` are -informative. Do not add nDCG, relevance grading or an evaluation database in v1. - -**Step 3: Implement the evaluator and CLI** - -Expose: - -```text -tht evidence evaluate -c - [--generation ] [--json] -``` - -The report includes workspace revision, evaluated vector generation and the fixed -default RRF configuration. It is read-only. With no `--generation`, it evaluates the -active generation for monitoring. Before publication, the preprocessing pipeline calls -the same evaluator against its candidate generation and atomically activates it only -when the report passes. A failed candidate remains inactive. - -**Step 4: Run tests** - -```bash -cd harness -.venv/bin/pytest tests/test_evidence_evaluation.py tests/test_evidence_cli.py -q -.venv/bin/ruff check tht/evidence/evaluation.py tests/test_evidence_evaluation.py -``` - -Expected: PASS. - -**Step 5: Commit** - -```bash -git add harness/tht/evidence/evaluation.py harness/tht/cli/evidence_cmd.py \ - harness/tests/test_evidence_evaluation.py harness/tests/test_evidence_cli.py -git commit -m "feat(evidence): evaluate retrieval with a small fixture" -``` - -### Task 11: Enforce curated-only runtime ingestion and update contracts - -**Files:** - -- Modify: `backend/src/workspaces/schema.ts` -- Modify: `backend/src/workspaces/runtime-renderer.ts` -- Modify: `backend/test/workspaces/schema.test.ts` -- Modify: `backend/test/workspaces/runtime-renderer.test.ts` -- Modify: `docs/contracts/workspace-evidence-v3.md` -- Modify: `docs/contracts/workspace-preprocessing-cli.md` -- Modify: `docs/architecture/overview.md` -- Modify: `PROJECT_STATE.md` - -**Step 1: Write RED descriptor/rendering tests** - -For filesystem Evidence, make `patterns: ["curated/**/*.md"]` the documented and -generated default for the new authoring layout. Continue accepting an explicitly -configured safe pattern for non-Git HTTP/S3 compatibility, but reject a filesystem -descriptor that includes both `source/**` and `curated/**` once it declares the new -layout version. - -If a schema-version field is required to preserve compatibility, add it to the Evidence -subcontract, not to the whole workspace descriptor. - -**Step 2: Implement the narrowest compatible descriptor change** - -The materializer continues to copy the entire `evidence/` tree at the pinned commit. -Only the rendered runtime acquisition patterns restrict preprocessing to `curated/`. -Do not duplicate or move P6 materialization logic. - -**Step 3: Update documentation contracts** - -Document: - -- source/curated layout; -- Git publication boundary; -- no runtime writes; -- validation before indexing; -- unnamed-dense plus BM25 contract and additive Evidence upgrade; -- exact public operation names and JSON status additions, if any. - -**Step 4: Run backend and harness contract gates** - -```bash -cd backend -npx vitest run test/workspaces/schema.test.ts test/workspaces/runtime-renderer.test.ts \ - test/workspaces/evidence/materialization.test.ts \ - test/workspaces/evidence/preprocessing.test.ts -npx tsc --noEmit -p . -cd ../harness -.venv/bin/pytest tests/test_registry_evidence_config.py \ - tests/test_filesystem_evidence_source.py tests/test_preprocess_cli.py -q -``` - -Expected: PASS; P6 materialization safety remains unchanged. - -**Step 5: Commit** - -```bash -git add backend/src/workspaces/schema.ts backend/src/workspaces/runtime-renderer.ts \ - backend/test/workspaces/schema.test.ts \ - backend/test/workspaces/runtime-renderer.test.ts \ - docs/contracts/workspace-evidence-v3.md \ - docs/contracts/workspace-preprocessing-cli.md docs/architecture/overview.md PROJECT_STATE.md -git commit -m "docs(evidence): publish curated-only workspace contract" -``` - -### Task 12: Migrate PSD and perform acceptance - -**Files in ThothII:** - -- Create: `docs/testing/evidence-restructuring-manual.md` -- Create: `scripts/evidence-restructuring-acceptance.sh` -- Create: `harness/tests/fixtures/evidence_authoring/poorly_structured.md` -- Modify: `PROJECT_STATE.md` - -**Files in the external authoring repository:** - -- Move: `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/` - to `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/source/` -- Create: `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/curated//` -- Create: `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/manifest.yaml` -- Create: `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/evaluation.yaml` -- Modify: `/Users/mp/projects/tht-workspace-psd/psd-clinical/evidence/README.md` -- Modify: `/Users/mp/projects/tht-workspace-psd/psd-clinical/workspace.yaml` - -Do not modify the external repository until the owner confirms the migration window and -the exact target branch. Treat that as the only manual authorization gate in this task. - -**Step 1: Add a hermetic badly-structured fixture** - -The fixture must contain prose, a rough list, an enum, an URL, an ambiguous statement -and a SQL formula candidate. The acceptance runner must prove: - -- split into multiple typed units; -- ambiguity becomes `review_items`; -- no cross-source merge; -- unchanged rerun is a no-op; -- committed human content remains recoverable and proposed changes are visible in Git; -- dirty-tree refusal; -- validation blocks unresolved review and orphaned units; -- pipeline-version mismatch refusal and explicit full-corpus `--upgrade`; -- validated corpus builds an inactive candidate and searches it hybrid; -- every evaluation query retrieves at least one expected ID in the first ten results - before the candidate becomes active; -- the evaluation set contains lexical, semantic and mixed cases and reports dense, - BM25 and fused ranks separately; -- dense and BM25 receive the same deterministic query text; -- no atomic formula, enum pair, mapping, rule or URL is split into fixed-size chunks; -- the complete rendered fragment stays within the existing 4,000-character - `max_chunk_chars` default and no parallel size option exists; -- the L0 probe passes against the Qdrant image referenced by `compose.yaml` without - FastEmbed or fallback; -- query normalization is limited to NFC, newline canonicalization and outer trimming, - preserving internal whitespace, punctuation and case-sensitive identifiers; -- Formula Evidence accepts a PostgreSQL expression and rejects a complete query; -- Qdrant failure remains fail-closed. - -Use a fake restructurer for hermetic CI. The real Pi call is a separate manual check. - -**Step 2: Run the complete automated gates before external writes** - -```bash -cd harness -.venv/bin/pytest -q -.venv/bin/ruff check . -cd ../backend -npx vitest run -npx tsc --noEmit -p . -cd ../tools/tht -go test ./... -go build ./cmd/tht -cd ../.. -bash scripts/evidence-restructuring-acceptance.sh -``` - -Expected: all suites and acceptance checks PASS. If pre-existing unrelated failures -remain, record exact names and prove they reproduce at the baseline commit before -continuing. - -**Step 3: Stop for the owner migration gate** - -Provide: - -- clean ThothII commit; -- test and acceptance summary; -- proposed PSD branch name; -- exact list of 36 source files to move; -- rollback command based on the pre-migration PSD commit; -- before/after Schema and Memory counts plus sample IDs used to prove non-regression. - -Do not infer approval from prior design acceptance. - -**Step 4: Migrate the PSD repository after approval** - -Use `tht evidence prepare`, review the Git diff, resolve all review items manually, run -`tht evidence validate`, and create the approximately twenty evaluation queries. Do not -auto-merge or auto-push unless separately requested. - -**Step 5: Activate and perform the additive BM25 upgrade** - -After the PSD merge/pull and activation, inspect first: - -```text -tht --installation /thothii-installation.yaml workspace vector inspect - --workspace psd-clinical --json -``` - -Before preprocessing, record counts and representative IDs for `schema_table`, -`schema_column`, `memory` and `solved_question`. Run `workspace preprocess evidence`: -it adds `bm25` when absent, builds the candidate, evaluates that exact generation and -publishes it only if the report passes. Repeat the counts, verify the representative IDs -and run dense smoke searches for Schema and Memory before completing the manual -walkthrough of `clarification`, `rewriting`, `schema_linking`, `cte` and `final_sql`. - -**Step 6: Record acceptance and commit ThothII documentation** - -`docs/testing/evidence-restructuring-manual.md` must record separate outcomes for: - -- authoring and Git review; -- additive BM25 schema upgrade; -- Schema and Memory before/after non-regression evidence; -- preprocessing generation publication; -- hybrid retrieval evaluation; -- formula retrieval; -- distinzione fra risultato vuoto e indisponibilità bloccante; -- complete session behavior. - -Update `PROJECT_STATE.md` only with observed results and immutable commit/run IDs. - -```bash -git add docs/testing/evidence-restructuring-manual.md \ - scripts/evidence-restructuring-acceptance.sh \ - harness/tests/fixtures/evidence_authoring/poorly_structured.md PROJECT_STATE.md -git commit -m "test(evidence): record restructuring acceptance" -``` - -## Final verification checklist - -Before claiming completion, verify: - -- [ ] `CONTEXT.md` and both Evidence plan documents use the same terminology. -- [ ] All eight Evidence kinds have type-specific positive and negative tests. -- [ ] Pi is called once per changed source, with no tools and no saved session. -- [ ] `prepare` refuses dirty curated state, exposes every proposal in Git and never - deletes orphans. -- [ ] `validate` blocks unresolved review items and orphaned units. -- [ ] Source renames and kind-only reclassifications preserve unit IDs; semantic splits - receive new IDs. -- [ ] IDs use `evidence:`, remain independent from kind and are not recomputed - after their initial assignment. -- [ ] Formula Evidence accepts one PostgreSQL expression and rejects full queries. -- [ ] A pipeline-version mismatch performs no writes without explicit `--upgrade`. -- [ ] Runtime reads only `curated/**/*.md` from the pinned Git revision. -- [ ] The TypeScript and Python Qdrant compatibility checks agree. -- [ ] Qdrant retains the unnamed dense vector and adds only `bm25` with IDF. -- [ ] Evidence preprocessing adds a missing `bm25` definition but never deletes, - renames or destructively rebuilds collection vectors. -- [ ] Schema and Memory counts, sample IDs and dense searches remain unchanged across - the additive upgrade. -- [ ] Italian BM25 options are identical during ingest and query. -- [ ] Hybrid search uses two prefetches and default RRF. -- [ ] Hard filters always include workspace, revision, active generation and purpose; - only explicit `required_*` context values add further filters. -- [ ] Formula runtime lookup uses typed Evidence; session proposals remain non-published. -- [ ] Fragment hits are grouped into one Evidence Result with excerpts and a reference; - full documents are loaded only on demand. -- [ ] Evidence is queried independently from the five mapped semantic stages and is not - invoked from `memory` or `synthesis`. -- [ ] An available empty result can continue; technical unavailability blocks the - current stage without stale-generation or purpose fallback. -- [ ] Each available stage search persists only its minimal Evidence receipt. -- [ ] Evaluation reports hit@5 and hit@10 against a versioned fixture and passes only - when every query has at least one expected result in the first ten. -- [ ] Evaluation runs against the candidate generation before atomic activation; a - failed candidate remains invisible to sessions. -- [ ] Existing corpus rollback, compensation, retention and resume tests still pass. -- [ ] Backend Vitest and TypeScript gates pass. -- [ ] Harness pytest and Ruff gates pass. -- [ ] Native `tht` Go tests/build pass. -- [ ] External PSD writes occurred only after explicit migration authorization. diff --git a/docs/prd/2026-08-09-workspace-preprocessing-prd.md b/docs/prd/2026-08-09-workspace-preprocessing-prd.md index 60fc54db..ee5c99a9 100644 --- a/docs/prd/2026-08-09-workspace-preprocessing-prd.md +++ b/docs/prd/2026-08-09-workspace-preprocessing-prd.md @@ -1,11 +1,11 @@ # PRD — Preprocessing per-workspace su ThothII (Qdrant + Git workspace registry) -**Status:** PRD in revisione — decisioni D1–D9 chiuse il 2026-08-09; i piani P1–P10 partiranno solo dopo -revisione e conferma del proprietario +**Status:** baseline storica dei requisiti — implementazione completata; per i contratti correnti vedere +`docs/contracts/workspace-preprocessing-cli.md`, `docs/contracts/workspace-evidence-v3.md` e +`docs/evidence.md` **Data:** 2026-08-09 **Autore:** analisi dello stato attuale (branch `codex/git-workspace-registry`) + decisioni con il proprietario -**Uso:** riferimento stabile di requisiti e decisioni; da ogni punto nascerà un piano separato in -`docs/superpowers/plans/` (sez. 11) — questo documento non è un piano di lavoro +**Uso:** riferimento stabile delle decisioni originarie; questo documento non è un piano operativo --- @@ -14,8 +14,8 @@ revisione e conferma del proprietario > descriptor `/workspace.yaml`, evidence embedded `/evidence/`, annotazioni FK curate > `/schema/annotations.yaml` (P5), docs generate `workspace-docs//`. I vecchi percorsi > piatti (`workspaces/.yaml`, `workspace-content//evidence/`) sono superseded; le uniche -> occorrenze rimaste sono storiche (changelog/revisioni). Vedi -> `docs/superpowers/plans/2026-08-11-p2-p6-adaptation-to-p1-1-registry.md`. +> occorrenze rimaste sono storiche (changelog/revisioni). Il contratto corrente è descritto in +> `docs/contracts/workspace-evidence-v3.md`. --- @@ -34,10 +34,9 @@ scrittura via REST dedicato o loading diretto) a un'architettura con: `resources.embeddings` + `roots` sotto `/sessions//`). La **macchina di preprocessing** (comandi, job a generazioni con publish atomico, adapter Qdrant, corpus -evidence, FK, memory) **esiste già ed è testata**: `tht preprocess evidence|dwh`, `tht vector init|index-schema`, -`tht schema introspect|suggest-fks|check`, `tht evidence extract|index`, `tht lsh build`, memory/solved. -Esistono job Compose fixture (`deploy/compose.preprocess.yaml` + `deploy/workspaces/preprocess-{dwh,evidence}.yaml`) -e uno smoke (`scripts/preprocess-smoke.sh`). +evidence, FK, memory) **esiste ed è testata**. La superficie operativa corrente è il comando host +`tht --installation ... workspace preprocess ...`, che esegue il servizio profile-gated +`workspace-maintenance`; le vecchie fixture Compose dedicate sono state ritirate. ### Il problema @@ -210,8 +209,7 @@ documentato e verificato da smoke end-to-end. verifica → uso → backup/restore). - RF8.2 La documentazione di progetto spiega **cos'è `.tht-dwh`** (generazioni, `OWNER.json`, `ACTIVE`, vincolo di fingerprint) in modo comprensibile per l'operatore (D3). -- RF8.3 Smoke end-to-end automatico (workspace nuovo → tutto il ciclo → sessione reale → cleanup) che - sostituisce/completa `preprocess-smoke.sh` (oggi solo fixture). +- RF8.3 Smoke end-to-end automatico (workspace nuovo → tutto il ciclo → sessione reale → cleanup). - RF8.4 Backup/restore coprono Qdrant (già `vector-backup.sh`/`vector-restore.sh`), corpus, `.tht-dwh` e registry. - RF8.5 Ogni piano successivo traduce il proprio risultato operativo in un **process goal** verificabile da @@ -332,7 +330,7 @@ Ogni piano tecnico riporta, adattandoli al proprio scope: keyword-index. 8. Rerun del preprocessing: `unchanged` (nessun duplicato); modifica di un'evidence → nuova generazione, ACTIVE aggiornato, vecchie generazioni in GC. -9. Smoke end-to-end automatico verde in CI con cleanup esatto (stile `preprocess-smoke.sh`). +9. Smoke end-to-end automatico verde in CI con cleanup esatto. 10. Migrazione PSD documentata e provata almeno in dry-run (re-introspection o riuso catalogo + re-embedding). 11. Ogni piano tecnico successivo include un process goal automatico completo per il proprio scope e un walkthrough manuale quando utile, oppure documenta l'inevitabile eccezione umana secondo S4. @@ -417,12 +415,11 @@ Ogni piano tecnico riporta, adattandoli al proprio scope: - Default invariati (`retain_published_generations: 3`, chunk 4000 char), configurabili per-workspace via la sezione `evidence`/policy del descriptor (D1). -## 11. Mappa dei piani (uno per punto del PRD) +## 11. Mappa storica dell'implementazione -Questo PRD non diventa un unico piano: **ogni decisione/requisito produce un piano separato (P1–P10)** in -`docs/superpowers/plans/`, eseguibile in sequenza o come workstream indipendenti. Il PRD resta il -riferimento stabile (requisiti + decisioni); ogni piano cita il punto di origine e i criteri di -accettazione applicabili (sez. 9) e adotta lo standard integration-first (sez. 8). +L'implementazione è stata suddivisa nei workstream P1–P10 riportati sotto. I piani esecutivi +superati sono disponibili nella storia Git; questa tabella conserva soltanto la relazione tra +requisiti, dipendenze e risultati attesi. | Piano | Punto PRD | Contenuto sintetico | Dipende da | | --- | --- | --- | --- | @@ -532,12 +529,11 @@ traccia separatamente implementazione, automated integration e manual acceptance - Stato attuale: `PROJECT_STATE.md` (sezioni "Internal Qdrant + Ollama semantic infrastructure", snapshot registry) e `AGENTS.md`. - Design architettura semantica: `docs/plans/2026-08-08-internal-qdrant-ollama-design.md` e relativo piano. -- Registry: `docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md`, manuali +- Registry e Evidence: `docs/contracts/workspace-evidence-v3.md`, `docs/evidence.md`, manuali `docs/install/local-workspace-registry.md` / `server-workspace-registry.md`. - Motore preprocessing: `harness/tht/cli/preprocess_cmd.py`, `harness/tht/corpus/pipeline.py`, `harness/tht/jobs/dwh_pipeline.py`, `harness/tht/adapters/vector/qdrant.py`, `harness/tht/vectorstore/records.py`, `harness/tht/cli/{vector,schema,evidence,memory}_cmd.py`. -- Fixture attuali: `deploy/compose.preprocess.yaml`, `deploy/workspaces/preprocess-{dwh,evidence}.yaml`, - `scripts/preprocess-smoke.sh`. +- Superficie operativa: `tools/tht/` e `docs/contracts/workspace-preprocessing-cli.md`. - Ammissione runtime: `backend/src/tht/tht-runner.ts` (`qdrantEnsure`/`ollamaEnsure`), `backend/src/workspaces/runtime-renderer.ts`. diff --git a/docs/reports/2026-08-15-tht-command-audit.md b/docs/reports/2026-08-15-tht-command-audit.md deleted file mode 100644 index d2cc3a00..00000000 --- a/docs/reports/2026-08-15-tht-command-audit.md +++ /dev/null @@ -1,171 +0,0 @@ -# Audit critico dei comandi `tht` - -Data: 2026-08-15 - -## Scopo - -Questo audit valuta tutti i comandi terminali registrati dall'attuale CLI Python `tht` prima di -unificare la CLI di ThothII sotto un solo eseguibile pubblico. La valutazione incrocia: - -- il contratto del workflow Pi in `harness/.pi/skills/tht-sessione/SKILL.md`; -- le invocazioni reali del gate in `harness/.pi/extensions/tht-gate.js`; -- le invocazioni del backend in `backend/src/tht/tht-runner.ts`; -- i job operatore in `backend/src/workspaces/preprocessing-service.ts`; -- il migratore in `docker/session-migrate.sh`; -- test e documentazione esistenti. - -L'inventario autorevole contiene 76 comandi Typer più il comando callback `doctor`: 77 comandi -terminali complessivi. - -## Legenda - -- **WF — intoccabile workflow**: chiamato da Pi, dal gate o dal contratto delle otto fasi. Va - conservato con semantica, output JSON ed exit code compatibili. Non deve necessariamente apparire - nell'help ordinario dell'utente. -- **PL — intoccabile piattaforma**: chiamato dal backend, dai job workspace o dal deployment. Anche - questo è un contratto interno, non necessariamente un comando da mostrare all'utente. -- **ADV — mantenere avanzato**: non è nel flusso automatico, ma offre una capacità amministrativa o - di recupero che sarebbe imprudente perdere. Va nascosto dall'help base. -- **ACCORPA**: la capacità serve, ma non merita un comando autonomo. -- **RIMUOVI**: il comando non ha chiamanti reali ed è duplicato, superato, pericoloso o incompleto. - L'eventuale logica riutilizzata da altri flussi resta una libreria interna. - -## Risultato sintetico - -| Esito | Numero | Conseguenza | -|---|---:|---| -| WF o PL, intoccabili | 55 | Conservare il contratto; nascondere i primitivi tecnici dall'help base | -| ADV o ACCORPA | 8 | Conservare la capacità riducendo la superficie UX | -| RIMUOVI | 14 | Eliminare il comando dalla nuova CLI | -| **Totale** | **77** | Una sola CLI pubblica molto più semplice, senza riscrivere il workflow vivo | - -## Matrice completa - -### Diagnostica, configurazione e dipendenze - -| Comando | Valutazione | -|---|---| -| `config check` | **ACCORPA** in `tht doctor`: la validazione della configurazione serve, ma due preflight distinti confondono l'utente. | -| `doctor` | **ACCORPA/MANTIENI pubblico** come unico `tht doctor`, includendo controlli host, Compose, storage e configurazione runtime. | -| `db ping` | **PL**: il backend lo usa per rifiutare correttamente una nuova sessione quando il DWH non è raggiungibile o non è read-only. Interno. | -| `db fetch-ca` | **ACCORPA** in `tht setup` o nella configurazione workspace: utile per TLS, ma non giustifica un comando isolato. | -| `ollama ensure` | **PL**: preflight automatico dell'embedder usato dal backend. Interno. | - -### Fasi e decision ledger - -| Comando | Valutazione | -|---|---| -| `phase advance` | **WF**: il gate lo usa per avanzare solo dopo la decisione umana. Primitivo anti-bypass, quindi interno. | -| `phase meta` | **WF**: fornisce al gate la definizione data-driven delle fasi e dei tipi di decisione. Interno. | -| `phase reopen` | **WF**: è il percorso canonico per tornare a una fase precedente e invalidare deterministicamente gli artefatti successivi. | -| `phase show` | **WF**: il gate lo usa per calcolare la fase corrente. Interno. | -| `decision add` | **WF**: persistenza fondamentale delle decisioni del reviewer. Solo gate, non shell utente. | -| `decision add-batch` | **WF**: scrittura atomica delle decisioni multiple. Evita ledger parziali. | -| `decision add-join-set` | **WF**: sostituzione atomica dell'intero insieme di join. | -| `decision list` | **RIMUOVI**: nessun chiamante; `session show --json` contiene già il ledger necessario. | -| `decision retract` | **RIMUOVI** dalla CLI: nessun flusso vivo lo invoca e `phase reopen` è il percorso di correzione supportato. La semantica tombstone può restare nel dominio finché utile. | - -### Sessioni - -| Comando | Valutazione | -|---|---| -| `session archive` | **PL**: usato dalla gestione sessioni del backend. | -| `session check` | **WF**: gate oggettivo della fase 5; verifica decisioni e schema linking. | -| `session close` | **PL**: usato dal backend. | -| `session delete` | **PL**: usato dal backend con i relativi controlli applicativi. | -| `session documents` | **WF/PL**: ricostruisce il contesto persistito e alimenta sia Pi sia la GUI. | -| `session fail` | **PL**: usato dal backend per rappresentare il fallimento terminale. | -| `session finalize` | **WF**: chiusura deterministica della fase finale e indicizzazione della domanda risolta. | -| `session list` | **PL**: alimenta la lista sessioni della GUI. | -| `session migrate` | **PL**: eseguito dal servizio one-shot di migrazione server; resta interno dietro `tht sessions migrate`. | -| `session new` | **WF/PL**: crea la persistenza iniziale della domanda; il backend dipende dal JSON restituito. | -| `session preferences get` | **PL**: lettura delle preferenze applicative. Interno. | -| `session preferences set` | **PL**: scrittura delle preferenze applicative. Interno. | -| `session reopen` | **PL**: riapertura dello stato terminale esposta dalla gestione sessioni. | -| `session retrieval-pack` | **WF**: legge il retrieval pack già persistito per il kickoff di Pi. Distinto da `search pack`, che lo costruisce. | -| `session set-group` | **PL**: rinomina il raggruppamento dalla GUI. | -| `session set-name` | **PL**: rinomina la sessione dalla GUI. | -| `session set-question` | **WF**: persiste deterministicamente domanda riscritta e assunzioni. Solo gate. | -| `session set-schema-linking` | **WF**: valida e scrive `schema_linking.json`. Solo gate. | -| `session show` | **WF/PL**: fonte compatta dello stato persistito per resume, gate e backend. | -| `session sync-schema-linking` | **WF**: riproietta deterministicamente il ledger nello schema linking. | -| `session unarchive` | **PL**: usato dalla gestione sessioni del backend. | - -### Schema e retrieval - -| Comando | Valutazione | -|---|---| -| `schema check` | **PL**: validazione delle annotazioni curate nel workflow workspace. | -| `schema columns` | **WF**: il gate usa il catalogo colonne per validare e correggere il linking. | -| `schema introspect` | **WF**: fallback previsto dal contratto quando manca lo schema fisico; la modalità refresh resta manutenzione. | -| `schema render` | **WF**: produce il contesto mschema usato dal modello. | -| `schema suggest-fks` | **PL**: comando del flusso operatore per le annotazioni FK curate. | -| `search find` | **WF**: ricerca mirata di evidence, valori e formule durante le fasi. | -| `search pack` | **WF/PL**: costruisce e persiste il contesto iniziale F1; usato anche dal backend. | - -### CTE, SQL e datamart - -| Comando | Valutazione | -|---|---| -| `cte info` | **WF**: restituisce SQL persistito, posizione nel piano e ultimo test. | -| `cte list` | **RIMUOVI**: nessun chiamante o test; `cte plan`, `cte info` e `session documents` coprono il bisogno. | -| `cte next` | **WF**: il gate determina il prossimo CTE da revisionare. | -| `cte plan` | **WF**: persiste l'ordine completo dei CTE. | -| `cte save` | **WF**: tool deterministico di scrittura usato dal gate. | -| `cte test` | **WF**: verifica read-only dei CTE prevista esplicitamente dal contratto. | -| `sql validate` | **WF**: validazione strutturale e read-only prima dell'esecuzione. | -| `sql preview` | **WF/PL**: preview controllata usata dal modello e dalla GUI. | -| `sql set-final` | **WF**: unica scrittura canonica di `sql_final.sql` attraverso il repository di sessione. | -| `sql export` | **PL**: esportazione richiesta dalla GUI. | -| `sql explain` | **RIMUOVI**: nessun chiamante, test o requisito nel workflow corrente. Si reintroduce solo con un vero passo di analisi del piano. | -| `sql save` | **RIMUOVI**: duplica `set-final` ed `export` e permette un percorso di scrittura non usato. | -| `datamart generate` | **WF**: fase 8 del workflow. | - -### Memory - -| Comando | Valutazione | -|---|---| -| `memory promote` | **WF**: preview dei candidati di promozione usata dal gate. | -| `memory save-one` | **WF**: persistenza atomica della singola memory approvata. | -| `memory search` | **WF**: recupero delle memory riutilizzabili nella fase 2. | -| `memory solved-index` | **WF**: recupero manuale previsto se l'indicizzazione al finalize fallisce. | -| `memory solved-search` | **WF**: recupero di domande risolte simili nelle fasi successive. | -| `memory list` | **ADV**: mantenere per amministrare record errati, ma fuori dall'help base. | -| `memory show` | **ADV**: mantenere insieme a `list` per ispezione puntuale. | -| `memory update` | **ADV**: mantenere per correggere il merito di una memory senza alterarne la provenienza. | -| `memory delete` | **ADV**: mantenere come rimedio selettivo; richiede conferma esplicita nella nuova CLI. | -| `memory index` | **ADV**: utile come riparazione/full-resync, ma va presentato come manutenzione e non come uso normale. | -| `memory clear` | **RIMUOVI**: distruzione globale non usata; confligge con una UX sicura di backup/ripristino. | -| `memory migrate` | **RIMUOVI**: migrazione legacy una tantum senza dati di produzione da preservare. | - -### Preprocessing, evidence e indici - -| Comando | Valutazione | -|---|---| -| `preprocess dwh` | **PL**: pipeline canonica usata da `tht workspace preprocess dwh/run`. | -| `preprocess evidence` | **PL**: pipeline canonica usata da `tht workspace preprocess evidence/run`. | -| `vector index-schema` | **PL**: indicizzazione schema usata dal workflow workspace. | -| `evidence extract` | **RIMUOVI**: primitivo superato dalla pipeline versionata `preprocess evidence`. Conservare soltanto la logica riusata. | -| `evidence index` | **RIMUOVI**: primitivo superato dalla stessa pipeline versionata. | -| `lsh build` | **RIMUOVI** come comando: è già uno step di `preprocess dwh`; il builder resta interno. | -| `lsh query` | **RIMUOVI**: probe visuale senza chiamanti, test o documentazione operativa. La ricerca applicativa passa da `search find`. | -| `vector init` | **RIMUOVI**: il controllo di Qdrant/embedder è ormai coperto dal reconciler di collezione, da `ollama ensure` e dal nuovo `tht doctor`. | - -### Formule di concetto - -| Comando | Valutazione | -|---|---| -| `formula save` | **RIMUOVI** dalla CLI corrente: nessun chiamante, test o flusso di approvazione lo usa. Conservare il formato/store e la lettura tramite `search find --kind formula`. | -| `formula list` | **RIMUOVI**: stesso sottosistema incompleto. Un futuro flusso di curation dovrà progettare insieme creazione, approvazione, elenco e modifica. | - -## Conseguenza per la nuova CLI unica - -La semplificazione migliore non consiste nel rinominare tutti i 55 contratti vivi o nel mostrarli -all'utente. Consiste nel mantenere un unico eseguibile `tht` con due livelli di visibilità: - -1. l'help ordinario mostra soltanto setup, lifecycle, backup/restore, Pi e workspace; -2. i contratti WF/PL restano invocabili dallo stesso eseguibile, ma sono interni/nascosti e usati da - backend, gate e job one-shot. - -In questo modo l'utente vede una CLI piccola, mentre il workflow non subisce una riscrittura inutile -e rischiosa. Non serve un secondo eseguibile né un alias `thothctl`. diff --git a/docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md b/docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md deleted file mode 100644 index 9f2095d9..00000000 --- a/docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md +++ /dev/null @@ -1,148 +0,0 @@ -# Proposta maintain-erase-enhance per i comandi `tht` - -Data: 2026-08-15 - -## Criterio - -- **MAINTAIN**: il comando resta disponibile senza modifiche sostanziali. Come richiesto, non viene - aggiunta una motivazione. -- **ERASE**: il comando viene eliminato dalla nuova CLI; la motivazione indica la duplicazione, il - superamento o l'assenza di un utilizzo reale. -- **ENHANCE**: la capacità viene mantenuta, ma il comando viene migliorato, accorpato o reso più - sicuro. La proposta indica l'intervento. - -La proposta copre tutti i 77 comandi terminali dell'attuale CLI Python. - -## Sintesi - -| Proposta | Numero | -|---|---:| -| MAINTAIN | 55 | -| ENHANCE | 8 | -| ERASE | 14 | -| **Totale** | **77** | - -## Lista completa - -### Diagnostica, configurazione e dipendenze - -| Comando | Proposta | -|---|---| -| `config check` | **ENHANCE** — incorporare la validazione nel comando pubblico `tht doctor`, mantenendo una funzione interna riutilizzabile e l'output strutturato. Evita due preflight sovrapposti. | -| `doctor` | **ENHANCE** — farne l'unica diagnostica multilivello: installazione, descriptor, Compose, storage, configurazione runtime, DWH, Pi, Qdrant ed embedder. Deve offrire output umano e `--json`, senza mutare lo stato. | -| `db ping` | **MAINTAIN** | -| `db fetch-ca` | **ENHANCE** — integrarlo nel setup guidato del workspace, mostrando endpoint e fingerprint prima della conferma. Può restare disponibile come operazione TLS avanzata, ma non come passaggio manuale obbligatorio. | -| `ollama ensure` | **MAINTAIN** | - -### Fasi e decision ledger - -| Comando | Proposta | -|---|---| -| `phase advance` | **MAINTAIN** | -| `phase meta` | **MAINTAIN** | -| `phase reopen` | **MAINTAIN** | -| `phase show` | **MAINTAIN** | -| `decision add` | **MAINTAIN** | -| `decision add-batch` | **MAINTAIN** | -| `decision add-join-set` | **MAINTAIN** | -| `decision list` | **ERASE** — non ha chiamanti reali e duplica il ledger già restituito da `session show --json`. | -| `decision retract` | **ERASE** — non è invocato dal workflow corrente; `phase reopen` è il percorso supportato per correggere e invalidare deterministicamente le decisioni. La semantica tombstone può restare nel dominio. | - -### Sessioni - -| Comando | Proposta | -|---|---| -| `session archive` | **MAINTAIN** | -| `session check` | **MAINTAIN** | -| `session close` | **MAINTAIN** | -| `session delete` | **MAINTAIN** | -| `session documents` | **MAINTAIN** | -| `session fail` | **MAINTAIN** | -| `session finalize` | **MAINTAIN** | -| `session list` | **MAINTAIN** | -| `session migrate` | **MAINTAIN** | -| `session new` | **MAINTAIN** | -| `session preferences get` | **MAINTAIN** | -| `session preferences set` | **MAINTAIN** | -| `session reopen` | **MAINTAIN** | -| `session retrieval-pack` | **MAINTAIN** | -| `session set-group` | **MAINTAIN** | -| `session set-name` | **MAINTAIN** | -| `session set-question` | **MAINTAIN** | -| `session set-schema-linking` | **MAINTAIN** | -| `session show` | **MAINTAIN** | -| `session sync-schema-linking` | **MAINTAIN** | -| `session unarchive` | **MAINTAIN** | - -### Schema e retrieval - -| Comando | Proposta | -|---|---| -| `schema check` | **MAINTAIN** | -| `schema columns` | **MAINTAIN** | -| `schema introspect` | **MAINTAIN** | -| `schema render` | **MAINTAIN** | -| `schema suggest-fks` | **MAINTAIN** | -| `search find` | **MAINTAIN** | -| `search pack` | **MAINTAIN** | - -### CTE, SQL e datamart - -| Comando | Proposta | -|---|---| -| `cte info` | **MAINTAIN** | -| `cte list` | **ERASE** — non ha chiamanti o test e sovrappone informazioni già disponibili con `cte plan`, `cte info` e `session documents`. | -| `cte next` | **MAINTAIN** | -| `cte plan` | **MAINTAIN** | -| `cte save` | **MAINTAIN** | -| `cte test` | **MAINTAIN** | -| `sql validate` | **MAINTAIN** | -| `sql preview` | **MAINTAIN** | -| `sql set-final` | **MAINTAIN** | -| `sql export` | **MAINTAIN** | -| `sql explain` | **ERASE** — non è usato né testato dal workflow attuale. Va reintrodotto soltanto se l'analisi del piano diventa un passo esplicito del processo. | -| `sql save` | **ERASE** — duplica `sql set-final` e `sql export` e introduce un percorso di scrittura non utilizzato. | -| `datamart generate` | **MAINTAIN** | - -### Memory - -| Comando | Proposta | -|---|---| -| `memory promote` | **MAINTAIN** | -| `memory save-one` | **MAINTAIN** | -| `memory search` | **MAINTAIN** | -| `memory solved-index` | **MAINTAIN** | -| `memory solved-search` | **MAINTAIN** | -| `memory list` | **ENHANCE** — trasformarlo in una vista amministrativa paginata, con filtri, provenienza, stato e output `--json`; non mostrarlo nell'help base. | -| `memory show` | **ENHANCE** — mostrare provenienza immutabile, decisione sorgente, stato dell'indice e riferimenti necessari a una correzione consapevole. | -| `memory update` | **ENHANCE** — limitare l'aggiornamento ai campi modificabili, mostrare un diff prima della conferma e impedire modifiche alla provenienza. | -| `memory delete` | **ENHANCE** — richiedere identificatore esatto e conferma esplicita, mostrare l'impatto e verificare la rimozione coerente da registro e indice. | -| `memory index` | **ENHANCE** — riposizionarlo come comando di repair: prima rileva il drift, poi ricostruisce soltanto con conferma e verifica finale. Non deve sembrare un'operazione ordinaria. | -| `memory clear` | **ERASE** — cancellazione globale non usata e troppo facile da eseguire per errore; backup/ripristino e cancellazione selettiva sono percorsi più sicuri. | -| `memory migrate` | **ERASE** — migrazione legacy una tantum; non esistono dati di produzione da preservare e la nuova architettura può partire direttamente dal formato corrente. | - -### Preprocessing, evidence e indici - -| Comando | Proposta | -|---|---| -| `preprocess dwh` | **MAINTAIN** | -| `preprocess evidence` | **MAINTAIN** | -| `vector index-schema` | **MAINTAIN** | -| `evidence extract` | **ERASE** — è un primitivo superato dalla pipeline versionata `preprocess evidence`; l'eventuale logica condivisa resta interna. | -| `evidence index` | **ERASE** — è un secondo primitivo superato dalla stessa pipeline, che già gestisce materializzazione, indicizzazione, versionamento e resume. | -| `lsh build` | **ERASE** — la costruzione LSH è già uno step di `preprocess dwh`; mantenere due ingressi permette esecuzioni parziali incoerenti. | -| `lsh query` | **ERASE** — probe visuale senza chiamanti, test o documentazione operativa; il workflow usa `search find`. | -| `vector init` | **ERASE** — il controllo di Qdrant ed embedder è già coperto dal reconciler della collezione, da `ollama ensure` e dal nuovo `tht doctor`. | - -### Formule di concetto - -| Comando | Proposta | -|---|---| -| `formula save` | **ERASE** — non ha chiamanti, test o un flusso di approvazione completo. Il formato e lo store possono restare disponibili alla ricerca finché non viene progettata una vera curation. | -| `formula list` | **ERASE** — appartiene allo stesso sottosistema incompleto; un futuro flusso deve progettare insieme creazione, approvazione, elenco, modifica e cancellazione. | - -## Impatto sulla UX - -I 55 comandi `MAINTAIN` comprendono molti contratti macchina intoccabili. Mantenerli non implica -mostrarli tutti nell'help principale. La futura CLI unica può conservare gli stessi percorsi per -backend, gate e job, mostrando all'utente soltanto i gruppi operativi di primo livello. diff --git a/docs/reports/l2-run-report-2026-06-27.md b/docs/reports/l2-run-report-2026-06-27.md deleted file mode 100644 index c65008d8..00000000 --- a/docs/reports/l2-run-report-2026-06-27.md +++ /dev/null @@ -1,126 +0,0 @@ -# L2 Run Report — 2026-06-27 (sessione cardioversione + ablazione) - -> Esito della prima sessione L2 end-to-end dopo il porting CLI+skill (Onda -1→4 + -> Skill + 0b). Sessione non-deterministica, esito informativo non bloccante per il -> "done" del porting codice (come da piano L2.1, riga 1187). - -## Setup al momento del run - -- Pi: `@earendil-works/pi-coding-agent`, provider `zai`, model `glm-5.2` (default). -- Harness: Onda -1→4 + Skill committate; Onda 0b (workspace cliente `tht-workspace-psd`, - indice LSH 75737 valori, evidence 35). -- `.env` popolato, VPN OK, DWH REST 200, Ollama UP. -- Pre-run fix applicati in questa sessione: `_YamlModel.to_yaml` (bloccava `session new`), - `config/tht.yaml` symlink al workspace cliente (il gate chiama `tht` senza `-c`). - -## Come è partita la sessione - -Lancio `pi --mode rpc` + `/nuova-domanda ""`. -**Nota critica su `--mode rpc`:** la TUI interattiva di Pi (`pi` senza `--mode`) **non -renderizza** i widget `extension_ui_request` del gate (gestiti solo in `modes/rpc/`). -La modalità RPC emette i widget come JSONL su stdio per un client esterno — che non -esiste ancora in ThothII. Il run è stato possibile solo perché il modello, non vedendo -UI, ha operato via shell/tool fino al blocco fatale (vedi bug #4). - -## Cosa ha fatto il modello (transcript: 117 eventi, 365KB) - -Sessione Pi: `~/.pi/agent/sessions/--Users-mp-projects-ThothII-harness--/2026-06-27T13-44-51...jsonl`. -Sessione tht: `tht-workspace-psd/sessions/2026-06-27-134553-crea-una-lista...` (status: open, F1). - -Il modello ha lavorato molto e correttamente nel dominio: -- Ha creato la sessione, caricato la skill, iniziato F1. -- Ha eseguito ricerche semantiche (evidence + LSH), individuato le tabelle centrali - (`fact_cardioversione_elettrica`, `fact_see_ablazione`, `dim_patient`). -- Ha letto evidence molto pertinenti (esempio NLQ, glossario coorti/universi), costruendo - un quadro dominio corretto e verificato sulle tabelle reali. - -Il workflow **non è avanzato oltre F1**: nessuna decisione registrata -(`review_decisions.jsonl` assente). Il modello si è arenato su bug di porting (sotto). - -## Bug di porting emersi (4, di cui 1 fatale) - -### #1 — `tht` non nel PATH del processo Pi [basso] -Il gate chiama `execFileSync("tht", args, {cwd: ctx.cwd})`. L'eseguibile nel venv non è nel -PATH di Pi. Il modello ha creato un wrapper in `~/.local/bin` (workaround). -**Fix root-cause:** installare `tht` in una dir nel PATH (pip install -e . con entry point -globale, o symlink `/usr/local/bin/tht -> harness/.venv/bin/tht`). - -### #2 — `phase show` non passava il config [medio, FIXATO] -`phase_cmd._cfg()` non passava il config a `_load_config_or_exit()`, quindi falliva con -"File non trovato config/tht.yaml" quando non c'era `THT_WORKSPACE` env. -**Fix applicato (dal modello in sessione, validato e pulito):** `_cfg()` ora risolve -`THT_WORKSPACE`/`THT_CONFIG` env, poi fallback a `config/tht.yaml` (stessa convenzione di -`CONFIG_OPT`). Testato: `phase show` funziona. Suite 165 passed. - -### #3 — `session check` signature inconsistente [basso, da verificare] -Il modello ha notato che `session check` prende la sessione come argomento posizionale, -non `--session` come gli altri cmd. Da verificare e allineare. - -### #4 — `ctx.sendRaw is not a function` [FATALE, blocca tutti i widget] -Il gate `tht-gate.js:164` emette i widget con `ctx.sendRaw({type:"extension_ui_request"...})`. -Il runtime Pi installato **non espone `ctx.sendRaw`** sul context delle extensions. Il -modello l'ha verificato leggendo le type definitions (`ExtensionContext` espone `ui`, -`mode`, `hasUI`, `cwd`, `abort` — ma non `sendRaw`). **Nessun widget può essere emesso in -nessuna modalità.** Questo ha fermato il workflow a F1. - -## Analisi del bug #4 (mismatch architetturale, non un typo) - -Il commento nel gate stesso (righe 2-6) dice: *"REWRITE of the reference implementation... -replaces ctx.ui.* blocking primitives"*. Il porting ha **sostituito** i dialog nativi di Pi -con `ctx.sendRaw`, presumendo un'API widget-descriptor diretta che **questa versione di Pi -non espone alle extensions**. Verifiche sul runtime installato: - -- `ctx.sendRaw`: **non esiste** (0 refs in `core/extensions/`). -- `extension_ui_request`: emesso **solo dal runtime** (`modes/rpc/rpc-mode.js`), come - traduzione dei dialog nativi (`ctx.ui.select` → `{method:"select"}`), non come API per - le extensions. -- Canali disponibili in RPC mode per ricevere una decisione umana (enum chiuso): - `ctx.ui.select` / `confirm` / `input` / `editor` (+ `notify` one-way). I `method` di - `extension_ui_request` sono: select/confirm/input/editor/notify/setWidget/setStatus/ - set_editor_text. **Nessun method custom** per widget-descriptor. -- `ctx.ui.custom` (usato da ChironeWp3 per il multiselect TUI): in RPC mode è un **no-op** - (`return undefined`, commento: "Custom UI not supported in RPC mode"). - -### Conseguenza per i 6 widget della spec §4 -- `select` (scelta singola) → ✅ `ctx.ui.select` -- `confirm` (approvazione) → ✅ `ctx.ui.confirm` -- `input` (testo libero / Altro) → ✅ `ctx.ui.input` -- `multiselect` (scelta multipla — **critico per F4 schema-linking**) → ❌ nessun canale - in RPC. Solo `ctx.ui.custom` lo faceva (TUI only). - -Il multiselect è il vero ostacolo. F4 richiede di promuovere/escludere **più** tabelle/ -colonne in una volta. - -## Opzioni per il design del gate (decisione architetturale APERTA) - -Il design del gate influenza tutta la relazione harness↔backend↔FE. Non è un fix da -inserire in coda a una sessione di porting; merita brainstorming dedicato. Opzioni: - -- **A — Torna a `ctx.ui.*` nativi.** Il gate riscrive `emitAndWait` su `ctx.ui.select`/ - `confirm`/`input` (come ChironeWp3 originale). Multiselect F4 emulato (serie di select, o - un input). Funziona con il Pi installato ora. Perde i widget-descriptor ricchi spec §4; - il FE riceve method nativi, la mappatura kind→method va nel backend/FE. -- **B — Versione di Pi con API widget custom.** Verificare se un Pi più recente/preview - espone `ctx.sendRaw` o un method custom. Se sì, il gate attuale funziona. Rischio: - inseguire un'API magari non pubblica; aggiornare Pi può rompere provider/auth. -- **C — Wrapper ibrido (valutato, NON realizzabile).** Registrare un handler che intercetti - gli `extension_ui_request` nativi e li arricchisca nel formato widget-descriptor spec §4 - prima di mandarli al client RPC. **Scartato:** non c'è canale per widget-descriptor custom - in RPC (method è enum chiuso, `ctx.ui.custom` è no-op in RPC). - -## Artefatti prodotti - -- `tht-workspace-psd/sessions/2026-06-27-134553-.../` (manifest + question.md, F1, open). -- Sessione Pi transcript (vedi sopra) — fonte primaria per il debug. -- Fix codice: `_cfg()` in `phase_cmd.py` (bug #2), applicato pulito. - -## Conclusione - -**La sessione L2 ha colto bug di porting reali — ha fatto il suo lavoro.** Il loop -skill→LLM→gate funziona nel dominio (ricerche, evidence, quadro corretto) ma si blocca a -F1 sul bug fatale #4. Tre dei quattro bug sono risolvibili a basso costo (#1, #2 fixato, -#3); il #4 è una decisione di design del gate che richiede brainstorming prima del codice. - -**Stato del porting codice (Onda -1→4 + Skill + 0b):** completo e verificato a livello L0/L1 -(165 passed) + L2 value-grounding (PASS). I bug L2 emersi sono incrementi di qualità, non -regressioni del porting — L2 coglie ciò che L0/L1 per design non possono. diff --git a/docs/superpowers/2026-06-27-stato-e-ripresa.md b/docs/superpowers/2026-06-27-stato-e-ripresa.md deleted file mode 100644 index a3cfdd56..00000000 --- a/docs/superpowers/2026-06-27-stato-e-ripresa.md +++ /dev/null @@ -1,46 +0,0 @@ -# ThothII — Stato e come riprendere - -**Aggiornato:** 2026-06-27 (fine sessione) -**Branch corrente:** `main` (HEAD `b909f3e`) - -## Cosa è fatto (tutto su `main`) - -1. **Harness** (`harness/`) — completo e RPC-ready. Piano: [docs/superpowers/plans/2026-06-27-harness-rpc-readiness.md](plans/2026-06-27-harness-rpc-readiness.md). -2. **Backend** (`backend/`) — completo. Spec: [docs/superpowers/specs/2026-06-27-backend-design.md](specs/2026-06-27-backend-design.md). Piano: [docs/superpowers/plans/2026-06-27-backend-implementation.md](plans/2026-06-27-backend-implementation.md). - -Entrambi sviluppati con subagent-driven development (un implementer + review per task, più review finale del branch). I branch `feat/harness-rpc-readiness` e `feat/backend-implementation` sono già merged in `main` (si possono cancellare: `git branch -d feat/harness-rpc-readiness feat/backend-implementation`). - -## Verifica che sia tutto verde (primo comando di domani) - -```bash -cd ~/projects/ThothII/backend && npm test && npm run build -cd ../harness && source .venv/bin/activate && pytest -q --ignore=tests/l2 && npm test -``` -Atteso: backend 32 test + tsc OK; harness 233 pytest + 24 node:test. - -## Il contratto chiave (per non perderlo) - -Lo spike ha scoperto che il gate non poteva usare `ctx.sendRaw` (inesistente in Pi). Il **wire contract reale**: il gate emette via `ctx.ui.input(JSON.stringify(descriptor))` → Pi manda `{type:"extension_ui_request", id, method:"input", title:""}` → il client risponde `{type:"extension_ui_response", id, value:""}`. Il backend (`SessionBridge`) decodifica `title`→descriptor e ri-codifica la risposta in `value`. Il contratto verso il frontend (`ui_request`/`ui_response`) NON cambia. - -## Due strade per riprendere (scelta rimandata) - -### A) Validazione end-to-end con Pi reale (rischio residuo più importante) -I test sono tutti deterministici contro `fake-pi-rpc`; il loop con **Pi reale** non è mai stato eseguito. Richiede VPN attiva + `pi` (GLM 5.2) configurato + `harness/.env` popolato + il symlink `harness/config/tht.yaml`. -Due assunzioni da provare dal vivo: (1) il comando RPC `prompt` attiva l'`input` hook del gate; (2) Pi serializza verbatim il descriptor nel `title` di `ctx.ui.input`. -Come: avviare il backend (`cd backend && npm run dev`), fare `POST /sessions` con una domanda reale, aprire l'SSE `GET /sessions/:id/events`, verificare che arrivi il widget F1 e che la risposta avanzi. Se fallisce, il fix è localizzato a `emitAndWait` (gate) + il `fake-pi-rpc`. - -### B) Frontend (terzo progetto) -Brainstorming → spec → piano del **frontend** (React/Next/ShadCn/AGGrid), come da architettura [docs/superpowers/specs/2026-06-25-thothii-architecture-design.md](specs/2026-06-25-thothii-architecture-design.md) §6. Consuma SOLO la REST+SSE del backend (contratto già stabile). Avviare con la skill `superpowers:brainstorming`. - -## Backlog non bloccante (da chiudere quando si tocca l'area) - -- **`GET /models`** torna `[]` di default (seam `listModels` pronto): cablare `pi --list-models` o uno spawn Pi effimero perché la tendina FE si popoli. -- **`resume()`** manda il kickoff `/nuova-domanda` invece di `/riprendi-sessione`: per il Pi reale `spawnFor` deve poter scegliere il kickoff di ripresa (altrimenti la sessione ripresa riparte da F1). -- **Multi-workspace lato Pi/gate**: il backend è workspace-aware, ma il gate usa il symlink `config/tht.yaml` (mono-workspace MVP). Per il multi-workspace reale il gate dovrebbe accettare un env `THT_CONFIG`/workspace. -- **`SseHub`**: i `Set` per-sessione vuoti non vengono rimossi (leak minore su processi long-running). -- **Copertura test** da estendere: route `steer`/`close`/404, handler SSE, percorsi `notify`/`oidc`; test gate per `/riprendi-sessione` RPC e i path di re-present di `emitAndWait` (cancel/id-mismatch/JSON-invalido). -- `GET /sessions/:id/events` su id inattivo apre uno stream 200 vuoto invece di 404. - -## Nota operativa - -Il ledger di esecuzione subagent-driven è in `.git/sdd/progress.md` (non versionato): contiene la cronologia task→commit→review. Utile se serve ricostruire perché una scelta è stata fatta. diff --git a/docs/superpowers/plans/2026-06-25-harness-implementation.md b/docs/superpowers/plans/2026-06-25-harness-implementation.md deleted file mode 100644 index f59bf21b..00000000 --- a/docs/superpowers/plans/2026-06-25-harness-implementation.md +++ /dev/null @@ -1,1697 +0,0 @@ -# ThothII — Harness Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Build `harness/` — the self-contained Pi layer (CLI `nsp` Python + gate extension JS + skills markdown + `.pi/`) that runs the 8-phase NL→SQL workflow emitting/consuming widget-descriptor JSON, derived from ChironeWp3 as a validated-and-adapted starting point (not assumed reliable). - -**Architecture:** Port the relevant ChironeWp3 files into `harness/` task-by-task, then adapt each to the ThothII contract: `workflow.yaml` as the single source of workflow truth (F2), an "effective decisions as of pointer" view + `teardown_to_phase` for correct rollback (D15), a per-step task-document generator with enforced bounds for a 35B/<200k model (D16), the dual vector API key + `memory save-one` (D11), free-text interpretation (D13), value/formula grounding (D14), and the gate rewritten to emit/consume the 6-widget descriptor taxonomy (D2/D4). - -**Tech Stack:** Python ≥3.12 (typer, pydantic v2, pyyaml, sqlalchemy 2.0, psycopg2-binary, datasketch, sqlglot, pytest, testcontainers[postgres]); Node/JS for the Pi gate extension; Ollama embeddings (nomic-embed-text-v2-moe); Pi + GLM 5.2 for L2 tests. Testing: two levels (L1 fake + L2 real), see Testing Strategy below. - -**Reference spec:** `docs/superpowers/specs/2026-06-25-thothii-architecture-design.md` (all D1–D16 and §4.*). - -**Source of ported code:** `/Users/mp/projects/ThothII/ChironeWp3/` (read-only reference; never modify it). - ---- - -## Testing Strategy — three levels (L0 testcontainers, L1 fake, L2 real) - -This plan uses a **three-level test strategy**. The split is mandatory because the skill→LLM→tool-call loop cannot be exercised without a real model, and the DB-touching ported code needs a real database to validate (the "not assumed reliable" principle is hollow without it). - -### ⚠️ The honest headline: the core of the system has NO automated regression coverage - -The **skill→LLM→gate loop** — the heart of the system — is covered **only by L2** (manual, non-deterministic, slow, requires credentials+VPN). **There is no automated regression protection on it.** This is a deliberate, conscious choice, not an accidental side-effect: the LLM is non-deterministic and requires a configured Pi + network, so it cannot live in the fast automated loop. **Consequence: agentic-behavior regressions surface at pre-release L2 runs, not at commit.** Accept this and plan L2 runs before any release. A partial automated net for this gap would be a **fake-Pi** that mocks the Pi runtime and lets the gate glue run in CI; that is documented as a **cross-cutting follow-up** (built alongside the backend plan, not in this plan). - -### L0 — testcontainers, local Postgres, runs on every local run (CI) - -**What:** integrity tests of ported DB-touching modules against a real Postgres in a Docker container (testcontainers). No LLM, no remote network. Docker is available on the dev machine, so L0 is always-on locally. - -**Dependencies:** Docker (present in the dev env). No credentials, no VPN. - -**Coverage:** the ported logic that speaks to a DB — `db/connection` (read-only enforcement, exit code 2 if writable), `db/introspect`, `db/sampling`, `db/execute`, `search/RRF` + LSH with real data, `vectorstore/store` direct-load path. This is where "not assumed reliable" gains real teeth for the data layer. - -### L1 — fake data, deterministic, runs on every local run (CI) - -**What:** logic-pure tests with fake data (`tmp_path`, fixtures, mocks). No DB, no LLM, no network. - -**Coverage (honest):** -- Python logic-pure: `workflow.yaml` loading, `effective_decisions`, `teardown_to_phase`, `generate_task_doc`, `aggregate_lsh_multi` (on fake hits), formula store read/write, `decision_retracted`, CLI contract tests (valid input → well-formed JSON). -- **Gate builder functions (pure, in JS, tested in JS)**: the widget-descriptor builders produce the correct JSON given params. Tested in-language (node:test/vitest), no Python↔JS bridge, no Python mirror. - -**Honest limitation (load-bearing):** L1 can test the gate **builders** (pure functions) but **NOT the gate glue** — registration, emission via `ctx.sendRaw`, the no-limbo loop, the anti-bypass hooks. The glue depends on the Pi runtime (`pi.registerTool`, `ctx.sendRaw`, `emitAndWait`) and cannot run without either a real Pi or a fake-Pi mock. **The glue is tested only at L2.** Fuzzy/negative tests on the glue (malformed tool params, out-of-order calls, orphan responses) likewise live at L2; only fuzzy tests on the pure builders live in L1. - -### L2 — real LLM + real remote DB, manual/pre-release, NOT automated - -**What:** end-to-end sessions with GLM 5.2 + the real Chirone datawarehouse and pgvector, reached via REST over VPN. Plus the gate-glue validation (the part L1 cannot reach). - -**Dependencies (all required, skip if missing):** -- LLM: Pi configured locally with GLM 5.2 (already ready). -- DB: the remote Supabase endpoints (see "L2 connection params" below), reachable via VPN. -- `harness/.env` populated with the API keys + CA path. - -**Modes:** -- **Human-in-the-loop (default):** the test runs the harness against GLM 5.2 and the reviewer answers each gate widget via the terminal, prompted by the test. Used for exploratory validation and for exercising the gate glue (which L1 cannot). -- **Pre-scripted answers (opt-in):** for specific cases (free-text "Altro", value grounding "ablazione", rollback), the test supplies canned reviewer answers automatically and asserts the outcome — no human typing. Used to test exact behaviors deterministically with the real model. - -**Coverage (honest):** validates the assumption L1 cannot — that GLM 5.2 produces tool calls the gate accepts, that the skill's prompts lead to the expected interaction shape, that the gate glue handles real tool-call sequences (incl. Altro/Rifiuta/rollback), that value grounding and formula approval surface correctly on the real schema, that `memory save-one` upserts to the real pgvector. Closes the skill→LLM→gate loop AND exercises the gate glue. - -**Honest limitation:** L2 is non-deterministic (the model may behave differently across runs) and slow/costly. It is a pre-release safety net, not a regression gate. A small, curated set of scenarios. - -### L2 connection params (from the operator) - -- **DWH (read-only):** `https://supabase-aritmolab.policlinicosandonato.it/dwh/` — PostgREST, schema `datawarehouse` + `datawarehouse_marts`, role `dwh_reader`. Header `X-API-Key: ${THOTH_DWH_API_KEY}`. -- **pgvector reader:** `https://supabase-aritmolab.policlinicosandonato.it/vector/v1/` — role `vector_reader` (`search_similar`, `list_tables`). Header `X-API-Key: ${THOTH_VEC_API_KEY}` (same value as `THOTH_DWH_API_KEY` — shared reader key). -- **pgvector writer (upsert-only):** same URL as reader, different key → role `vector_writer` (`existing_vector_hashes`, `upsert_vector_records`, no DELETE). Header `X-API-Key: ${THOTH_VEC_WRITE_API_KEY}`. -- **TLS:** self-signed, CA = leaf. On the operator's Mac, a local copy of the CA bundle must be present; `${THOTH_SSL_CA}` points to its local path. (Server path `/etc/nginx/ssl/policlinicosandonato.it.fullchain.crt` is unreachable from outside.) -- **Workspace:** `chirone-test`. -- **Test question (L2):** "dammi la lista dei pazienti che hanno fatto un'ablazione nel 2025" — exercises D14 value grounding + formula on the "ablazione" multi-column case. - -### API key handling (security) - -- All keys live **only** in `harness/.env` (gitignored). Never in code, never in the plan, never committed. -- `.env.example` is committed with variable names and empty values. -- L2 tests load `.env` via `python-dotenv` at startup; if any required var is missing/empty, the L2 test is **skipped with a clear message** (not failed), so L0/L1 never break for missing credentials. -- Tests never log key values. URLs in logs are fine; secrets are masked. -- ⚠️ The operator should rotate the key that appeared in chat transcripts. - -### Test marker convention - -- **L0 tests:** marker `@pytest.mark.l0`. Run always locally (Docker present). Auto-skip if Docker unavailable (rare). File naming: `tests/l0/test_*.py`. -- **L1 tests:** no marker (default, run always). File naming: `test_*.py` under `tests/`. Gate builder tests live in JS (node:test/vitest) under `harness/.pi/extensions/gate/__tests__/` and run via `npm test` alongside pytest. -- **L2 tests:** marker `@pytest.mark.l2`. Skipped automatically when `.env` incomplete. File naming: `tests/l2/test_*.py`. Default run: `pytest -m "not l2"` (L0+L1 only); pre-release: `pytest -m l2` (L2 only). - ---- - -## File Structure - -``` -harness/ -├── .pi/ ← Pi project config (ported + adapted) -│ ├── settings.json -│ ├── prompts/ ← /nuova-domanda, /riprendi-sessione -│ ├── skills/nsp-sessione/ ← SKILL.md + sub-files (adapted: task-doc, D13/D14) -│ └── extensions/ -│ ├── nsp-gate.js ← REWRITTEN: 6-widget descriptor emit/consume (glue, verified at L2) -│ ├── reserved-labels.mjs ← ported -│ └── gate/ -│ ├── builders.js ← NEW: pure widget-builder functions (L1, JS-tested) -│ └── __tests__/ ← node:test golden + fuzzy (L1) -│ ├── builders.test.js -│ └── golden/ -├── nsp/ ← Python package (ported + adapted) -│ ├── __init__.py -│ ├── config.py ← ported + vector_write_rest (D11) -│ ├── workspace.py ← NEW: YAML load + ${VAR} expand (D3 confine) -│ ├── workflow.py ← NEW: reads workflow.yaml (F2) -│ ├── phase.py ← REWRITTEN: data-driven + effective_decisions (D15) -│ ├── teardown.py ← NEW: teardown_to_phase (D15) -│ ├── taskdoc.py ← NEW: per-step task document generator (D16) -│ ├── decisions.py ← ported + decision_retracted (D15) -│ ├── cli/ -│ │ ├── __init__.py ← Typer app `nsp` -│ │ ├── _guards.py ← ported (require_vector_write_allowed etc.) -│ │ ├── workspace_cmd.py ← NEW: nsp workspace list/show -│ │ ├── phase_cmd.py ← adapted: + phase meta --json (F2) -│ │ ├── decision_cmd.py ← adapted: + retraction (D15) -│ │ ├── memory_cmd.py ← adapted: + save-one (D11) -│ │ ├── search_cmd.py ← adapted: + --kind formula (D14b) -│ │ ├── session_cmd.py ← adapted: + consistency check (D15) -│ │ └── (sql_cmd, cte_cmd, db_cmd, lsh_cmd, vector_cmd, evidence_cmd, schema_cmd — ported) -│ ├── db/ ← ported (connection, introspect, sampling, execute) -│ ├── rest/ ← ported (client, execute) -│ ├── search/ ← ported (combined_search, RRF) + formula retrieval (D14b) -│ ├── mschema/ ← ported (models, render, eligibility) -│ ├── vectorstore/ ← ported + dual-key rest_client (D11) -│ ├── evidence/ ← ported + formula kind (D14b) -│ ├── memory.py ← ported -│ └── session/ ← ported (models, store, artifacts) -├── workflow.yaml ← NEW: single source of workflow truth (F2) -├── workspaces/ ← workspace YAML definitions (D3) -│ └── chirone.example.yaml -├── sessions/ ← session persistence (FS, append-only ledger) -├── tests/ -│ ├── conftest.py ← L2 skip-when-no-.env fixtures -│ ├── golden/ ← golden JSON for widget builders (L1) -│ ├── fixtures/ -│ │ └── scenarios/ ← static .jsonl fixtures (synthesized once by build-scenarios) -│ ├── test_workflow.py ← L1 -│ ├── test_phase_effective.py ← L1 -│ ├── test_teardown.py ← L1 -│ ├── test_taskdoc.py ← L1 -│ ├── test_workspace.py ← L1 -│ ├── test_vector_dual_key.py ← L1 -│ ├── test_memory_save_one.py ← L1 (mocked writer) -│ ├── test_freetext_interpretation.py ← L1 (rationale contract) -│ ├── test_db_connection.py ← L0 Livello B (testcontainers: read-only enforcement) -│ ├── test_rest_client.py ← L1 Livello B (mock transport: RPC call) -│ ├── test_mschema_render.py ← L1 Livello B (3 formats on fake mschema) -│ ├── test_mschema_eligibility.py ← L1 Livello B (eligibility rules on fake columns) -│ ├── test_db_introspect.py ← L0 Livello B (testcontainers: known schema) -│ ├── test_db_sampling.py ← L0 Livello B (testcontainers: known data) -│ ├── test_rrf.py ← L0 Livello B (testcontainers: RRF fusion with real data) -│ ├── test_cli_contract.py ← L1 Livello B (each CLI: valid input → well-formed JSON) -│ ├── l0/ ← testcontainers tests (need Docker) -│ │ └── __init__.py -│ └── l2/ ← L2 (real GLM 5.2 + remote DB, @pytest.mark.l2) -│ └── __init__.py -│ └── l2/ -│ ├── test_session_ablazione.py ← L2 (GLM 5.2 + real DWH, human or scripted) -│ ├── test_value_grounding_real.py ← L2 ("ablazione" on real schema) -│ └── test_memory_save_one_real.py ← L2 (real pgvector writer upsert) -├── scripts/ -│ ├── create_vector_writer_rpc.sql ← ported (writer RPC allowlist) -│ └── create_vector_reader_rpc.sql ← NEW (reader RPC, D11 §5.4 note) -├── pyproject.toml -└── .env.example -``` - ---- - -## Phase A — Foundation (cross-cutting infrastructure first) - -Rationale: every feature depends on these. `workflow.yaml` + `effective_decisions` + `teardown` + `taskdoc` are the substrate the gate and the D11/D13/D14 features build on. - -### Task A1: Scaffold the harness project - -**Files:** -- Create: `harness/pyproject.toml` -- Create: `harness/.env.example` -- Create: `harness/nsp/__init__.py` -- Create: `harness/.gitignore` - -- [ ] **Step 1: Create `pyproject.toml`** - -```toml -[project] -name = "nsp" -version = "0.1.0" -description = "ThothII harness — deterministic CLI for the NL→SQL workflow" -requires-python = ">=3.12" -dependencies = [ - "typer>=0.12", - "pydantic>=2.0", - "pyyaml>=6.0", - "sqlalchemy>=2.0", - "psycopg2-binary>=2.9", - "datasketch>=1.6", - "sqlglot>=23.0", - "python-dotenv>=1.0", - "rich>=13.0", - "requests>=2.31", - "tqdm>=4.66", -] - -[project.scripts] -nsp = "nsp.cli:app" - -[project.optional-dependencies] -dev = [ - "pytest>=8.0", - "testcontainers[postgres]>=4.0", - "ruff>=0.5", -] - -[tool.ruff] -line-length = 100 - -[tool.pytest.ini_options] -testpaths = ["tests"] -``` - -- [ ] **Step 2: Create `.env.example`** (port the structure from `ChironeWp3/.env.example`, renamed to `THOTH_*` per §5.4) - -```bash -# ThothII profile: server (full rebuild) | workstation (read REST + optional upsert) -THOTH_PROFILE=server - -# Workspace DB (relational, direct transport) — example: chirone -THOTH_DB_HOST= -THOTH_DB_PORT=5432 -THOTH_DB_USER= -THOTH_DB_PASSWORD= - -# Vector REST — LETTURA (rpc search_similar) sul Supabase remoto -THOTH_VEC_REST_URL=https://host/vector/v1/ -THOTH_VEC_API_KEY= - -# Vector REST — SCRITTURA controllata (upsert only) da client remoti autorizzati -THOTH_VEC_WRITE_API_KEY= - -# Vector direct loading (server-only) -THOTH_VEC_HOST=localhost -THOTH_VEC_PORT=5438 -THOTH_VEC_USER=postgres -THOTH_VEC_PASSWORD= - -# Embeddings (Ollama) -THOTH_OLLAMA_URL=http://localhost:11434 - -# TLS (optional, internal CA) -THOTH_SSL_CA= -``` - -- [ ] **Step 3: Create `.gitignore`** - -``` -__pycache__/ -*.pyc -.env -.venv/ -sessions/ -indexes/ -*.egg-info/ -dist/ -build/ -``` - -- [ ] **Step 4: Create empty `nsp/__init__.py` and install** - -```bash -cd /Users/mp/projects/ThothII/harness -python -m venv .venv && source .venv/bin/activate -pip install -e ".[dev]" -``` - -- [ ] **Step 5: Verify `nsp` command is not yet wired (expected: import error) then commit** - -```bash -nsp --help 2>&1 | head -3 -``` -Expected: error (no `cli` module yet) — this is fine, we add it in Task A4. - -```bash -git add harness/ -git commit -m "feat(harness): scaffold project (pyproject, env, gitignore)" -``` - ---- - -### Task A2: Port config + create `workspace.py` (D3 confine) - -**Files:** -- Create: `harness/nsp/config.py` (ported + adapted from `ChironeWp3/src/psdwp3/config.py`) -- Create: `harness/nsp/workspace.py` -- Create: `harness/workspaces/chirone.example.yaml` -- Test: `harness/tests/test_workspace.py` - -- [ ] **Step 1: Port `config.py`** — copy `ChironeWp3/src/psdwp3/config.py` → `harness/nsp/config.py`. Rename the package prefix `psdwp3` → `nsp` everywhere. Verify it still defines: `DatabaseConfig`, `RestConfig`, `PathsConfig`, `EligibilityConfig`, `LshConfig`, `EvidenceSourcesConfig`, `EmbeddingsConfig`, `VectorConfig`, `SearchConfig`, `ExecutionConfig`, and the `Config` class with `vector_rest` + `vector_write_rest` (both `RestConfig | None`, see ChironeWp3 config.py:154-159) + `_expand_env` (lines 16-32). - -- [ ] **Step 2: Create `workspaces/chirone.example.yaml`** per spec §5.1 (relational + vector_db with rest/write_rest + evidence + embeddings + execution). - -- [ ] **Step 3: Write failing test for workspace loading** - -```python -# tests/test_workspace.py -from pathlib import Path -from nsp.workspace import load_workspace, WorkspaceError - -def test_load_workspace_expands_env_vars(monkeypatch, tmp_path): - monkeypatch.setenv("THOTH_VEC_API_KEY", "secret-reader") - monkeypatch.setenv("THOTH_VEC_WRITE_API_KEY", "secret-writer") - monkeypatch.setenv("THOTH_VEC_REST_URL", "https://example/vector/v1/") - yaml = tmp_path / "w.yaml" - yaml.write_text( - "name: test\n" - "relational:\n db_type: postgres\n transport: rest\n" - " rest: { base_url: 'https://dwh/', api_key: '${THOTH_VEC_API_KEY}' }\n" - "vector_db:\n collection: test_docs\n dim: 768\n" - " rest: { base_url: '${THOTH_VEC_REST_URL}', api_key: '${THOTH_VEC_API_KEY}' }\n" - " write_rest: { base_url: '${THOTH_VEC_REST_URL}', api_key: '${THOTH_VEC_WRITE_API_KEY}' }\n" - "embeddings:\n provider: ollama\n base_url: 'http://localhost:11434'\n model: m\n dim: 768\n" - ) - ws = load_workspace(yaml) - assert ws.vector_db.rest.api_key == "secret-reader" - assert ws.vector_db.write_rest.api_key == "secret-writer" - -def test_load_workspace_missing_env_raises(monkeypatch, tmp_path): - monkeypatch.delenv("THOTH_VEC_API_KEY", raising=False) - yaml = tmp_path / "w.yaml" - yaml.write_text( - "name: test\nrelational: { db_type: postgres, transport: rest, rest: { base_url: 'https://dwh/', api_key: '${THOTH_VEC_API_KEY}' } }\n" - "vector_db: { collection: c, dim: 768, rest: { base_url: 'https://v/', api_key: '${THOTH_VEC_API_KEY}' } }\n" - "embeddings: { provider: ollama, base_url: 'http://x', model: m, dim: 768 }\n" - ) - try: - load_workspace(yaml) - assert False, "should have raised" - except WorkspaceError as e: - assert "THOTH_VEC_API_KEY" in str(e) -``` - -- [ ] **Step 4: Run test, verify fail** - -Run: `cd harness && pytest tests/test_workspace.py -v` -Expected: FAIL — `ModuleNotFoundError: nsp.workspace` - -- [ ] **Step 5: Implement `workspace.py`** - -```python -# nsp/workspace.py -"""Workspace YAML loading — the single boundary for workspace configuration (spec D3). -Reads workspaces/.yaml, expands ${VAR} from env, validates via the Config model. -Future migration to a DB store would replace only this module. -""" -from __future__ import annotations -import os -from pathlib import Path -import yaml -from nsp.config import Config, ConfigError - -class WorkspaceError(Exception): - pass - -def _expand_str(s: str) -> str: - """Expand ${VAR} occurrences in s. Raises if a referenced var is unset.""" - PREFIX = "${" - SUFFIX = "}" - out: list[str] = [] - i = 0 - while i < len(s): - start = s.find(PREFIX, i) - if start == -1: - out.append(s[i:]) - break - out.append(s[i:start]) - end = s.find(SUFFIX, start + len(PREFIX)) - if end == -1: - raise WorkspaceError(f'Sintassi non valida (manca "}}"): {s[start:]}') - var = s[start + len(PREFIX) : end] - if var not in os.environ: - raise WorkspaceError(f"Variabile d'ambiente non definita: {var}") - out.append(os.environ[var]) - i = end + len(SUFFIX) - return "".join(out) - -def _expand_env(obj): - if isinstance(obj, str): - return _expand_str(obj) - if isinstance(obj, dict): - return {k: _expand_env(v) for k, v in obj.items()} - if isinstance(obj, list): - return [_expand_env(v) for v in obj] - return obj - -def load_workspace(path: str | Path) -> Config: - raw = yaml.safe_load(Path(path).read_text()) - try: - return Config.model_validate(_expand_env(raw)) - except ConfigError as e: - raise WorkspaceError(str(e)) from e -``` - -- [ ] **Step 6: Run test, verify pass** - -Run: `pytest tests/test_workspace.py -v` -Expected: 2 PASS - -- [ ] **Step 7: Commit** - -```bash -git add harness/nsp/config.py harness/nsp/workspace.py harness/workspaces/chirone.example.yaml harness/tests/test_workspace.py -git commit -m "feat(harness): port config + workspace.py YAML loader (D3)" -``` - ---- - -### Task A3: Create `workflow.yaml` + `workflow.py` (F2) — single source of truth - -**Files:** -- Create: `harness/workflow.yaml` -- Create: `harness/nsp/workflow.py` -- Test: `harness/tests/test_workflow.py` - -- [ ] **Step 1: Create `workflow.yaml`** (the 8-phase definition from spec §5.3) - -```yaml -# harness/workflow.yaml — single source of workflow truth (spec F2) -schema_version: 1 - -phases: - - id: F1 - name: chiaramento - advance: kind:phase - prerequisites: [] - artifacts_out: [] - - id: F2 - name: memoria - advance: auto_if_empty - prerequisites: [] - artifacts_out: [] - - id: F3 - name: riscrittura - advance: kind:phase - prerequisites: - - decision_exists: question_rewritten - artifacts_out: [question.md] - - id: F4 - name: schema_linking - advance: reviewer_decide - prerequisites: [] - artifacts_out: [schema_linking.json] - - id: F5 - name: sintesi - advance: kind:phase - prerequisites: - - file_validates: [schema_linking.json, SchemaLinking] - artifacts_out: [] - - id: F6 - name: cte - advance: auto_if_empty_or_skipped - prerequisites: - - any: - - decision_subject_exists: [phase_skipped, "phase:6"] - - all_ctes_approved: true - artifacts_out: [cte_plan.json, ctes/, cte_tests.json] - - id: F7 - name: sql_finale - advance: kind:phase - prerequisites: - - decision_exists: sql_approved - artifacts_out: [sql_final.sql] - - id: F8 - name: datamart - advance: reviewer_decide - prerequisites: - - any: - - decision_exists: datamart_requested - - decision_exists: datamart_declined - artifacts_out: [] - -decision_min_phase: auto -max_phase: auto -``` - -- [ ] **Step 2: Write failing test for workflow loading** - -```python -# tests/test_workflow.py -from nsp.workflow import load_workflow, PhaseSpec - -def test_workflow_loads_8_phases(): - wf = load_workflow() - assert len(wf.phases) == 8 - assert wf.phases[0].id == "F1" - assert wf.max_phase == 8 - assert wf.phase_by_num(1).name == "chiaramento" - -def test_decision_min_phase_derived(): - wf = load_workflow() - # question_rewritten is a prerequisite of F3 → min phase 3 - assert wf.decision_min_phase("question_rewritten") == 3 - # sql_approved is a prerequisite of F7 → min phase 7 - assert wf.decision_min_phase("sql_approved") == 7 - # unknown type → phase 1 (default) - assert wf.decision_min_phase("nonexistent_type") == 1 - -def test_phase_name_lookup(): - wf = load_workflow() - assert wf.phase_name(6) == "cte" - assert wf.phase_name(8) == "datamart" # the JS drift bug — F8 must be present - -def test_artifacts_out_per_phase(): - wf = load_workflow() - assert "schema_linking.json" in wf.phase_by_num(4).artifacts_out - assert "sql_final.sql" in wf.phase_by_num(7).artifacts_out -``` - -- [ ] **Step 3: Run test, verify fail** - -Run: `pytest tests/test_workflow.py -v` -Expected: FAIL — `ModuleNotFoundError: nsp.workflow` - -- [ ] **Step 4: Implement `workflow.py`** - -```python -# nsp/workflow.py -"""Reads workflow.yaml — the SINGLE source of workflow truth (spec F2, §5.3). -phase.py, the gate, and the skill all read from here. No more duplicated constants. -""" -from __future__ import annotations -from dataclasses import dataclass, field -from pathlib import Path -import yaml - -_WF_PATH = Path(__file__).resolve().parent.parent / "workflow.yaml" - -@dataclass -class PhaseSpec: - id: str - num: int - name: str - advance: str - prerequisites: list - artifacts_out: list[str] = field(default_factory=list) - -@dataclass -class Workflow: - schema_version: int - phases: list[PhaseSpec] - _decision_min_map: dict[str, int] = field(default_factory=dict) - - @property - def max_phase(self) -> int: - return len(self.phases) - - def phase_by_num(self, n: int) -> PhaseSpec: - return self.phases[n - 1] - - def phase_name(self, n: int) -> str: - return self.phase_by_num(n).name if 1 <= n <= self.max_phase else "?" - - def decision_min_phase(self, decision_type: str) -> int: - # A decision type's min phase = the earliest phase whose prerequisites - # reference it (via decision_exists/decision_subject_exists), else 1. - return self._decision_min_map.get(decision_type, 1) - -def _collect_decision_mins(phases: list[PhaseSpec]) -> dict[str, int]: - """Scan prerequisites for decision_exists / decision_subject_exists mentions.""" - mins: dict[str, int] = {} - def scan(node, phase_num: int): - if isinstance(node, dict): - for k, v in node.items(): - if k in ("decision_exists", "decision_subject_exists"): - if isinstance(v, list): - dtype = v[0] - else: - dtype = v - if dtype not in mins or phase_num < mins[dtype]: - mins[dtype] = phase_num - else: - scan(v, phase_num) - elif isinstance(node, list): - for item in node: - scan(item, phase_num) - for p in phases: - scan(p.prerequisites, p.num) - return mins - -def load_workflow(path: Path | str = _WF_PATH) -> Workflow: - raw = yaml.safe_load(Path(path).read_text()) - phases = [] - for i, p in enumerate(raw["phases"], start=1): - phases.append(PhaseSpec( - id=p["id"], num=i, name=p["name"], - advance=p["advance"], prerequisites=p.get("prerequisites", []), - artifacts_out=p.get("artifacts_out", []), - )) - return Workflow( - schema_version=raw.get("schema_version", 1), - phases=phases, - _decision_min_map=_collect_decision_mins(phases), - ) -``` - -- [ ] **Step 5: Run test, verify pass** - -Run: `pytest tests/test_workflow.py -v` -Expected: 4 PASS - -- [ ] **Step 6: Commit** - -```bash -git add harness/workflow.yaml harness/nsp/workflow.py harness/tests/test_workflow.py -git commit -m "feat(harness): workflow.yaml as single source of truth + workflow.py loader (F2)" -``` - ---- - -### Task A4: Port `decisions.py` + add `decision_retracted` (D15) - -**Files:** -- Create: `harness/nsp/decisions.py` (ported + adapted) -- Test: `harness/tests/test_decisions_retract.py` - -- [ ] **Step 1: Port `decisions.py`** — copy `ChironeWp3/src/psdwp3/session/decisions.py`. Rename package. Add `decision_retracted` to the `DecisionType` Literal. The `DecisionRecord` model gains an optional `retracts: int | None` field (the `decision_seq` being retracted, for step-level rollback). - -- [ ] **Step 2: Write failing test for retraction** - -```python -# tests/test_decisions_retract.py -from pathlib import Path -from nsp.decisions import append_decision, list_decisions, DecisionRecord - -def test_retracted_decision_in_audit_but_marked(tmp_path): - session = tmp_path / "s1" - session.mkdir() - append_decision(session, DecisionRecord(seq=1, ts="t", type="table_promoted", - subject="phase:4", detail="t1", rationale="r")) - append_decision(session, DecisionRecord(seq=2, ts="t", type="decision_retracted", - subject="phase:4", detail="retract", rationale="wrong", retracts=1)) - all_decisions = list_decisions(session) - assert len(all_decisions) == 2 # both in audit - assert all_decisions[1].retracts == 1 -``` - -- [ ] **Step 3: Run, verify fail, implement the `retracts` field + ensure `append_decision` writes it, verify pass.** (The ported `append_decision` already writes all fields; just ensure the new field is serialized. If using pydantic `model_dump`, add `retracts: int | None = None`.) - -Run: `pytest tests/test_decisions_retract.py -v` -Expected after implement: PASS - -- [ ] **Step 4: Commit** - -```bash -git add harness/nsp/decisions.py harness/tests/test_decisions_retract.py -git commit -m "feat(harness): port decisions.py + decision_retracted for step rollback (D15)" -``` - ---- - -### Task A5: Rewrite `phase.py` — data-driven + `effective_decisions` (D15 core fix) - -**Files:** -- Create: `harness/nsp/phase.py` (rewritten) -- Port: `harness/nsp/session/{models,store,artifacts}.py` (needed for SchemaLinking validation) -- Test: `harness/tests/test_phase_effective.py` - -This is the single most important architectural fix (spec §4.8). `phase.py` reads from `workflow.yaml`, and ALL helpers consult `effective_decisions()` instead of raw `list_decisions()`. - -- [ ] **Step 1: Port session models/store/artifacts** — copy `ChironeWp3/src/psdwp3/session/{models.py, store.py, artifacts.py}` → `harness/nsp/session/`. Rename package. These are needed for `SchemaLinking` validation in `advance_problems`. - -- [ ] **Step 2: Write failing test for effective_decisions** - -```python -# tests/test_phase_effective.py -from pathlib import Path -from nsp.phase import current_phase, effective_decisions -from nsp.decisions import append_decision, DecisionRecord - -def _d(session, seq, dtype, subject, **kw): - append_decision(session, DecisionRecord(seq=seq, ts="t", type=dtype, subject=subject, - detail=kw.get("detail", ""), rationale=kw.get("rationale", ""), - retracts=kw.get("retracts"))) - -def test_effective_decisions_excludes_pre_reopen_tail(tmp_path): - s = tmp_path / "s"; s.mkdir() - _d(s, 1, "phase_approved", "phase:1") - _d(s, 2, "phase_approved", "phase:2") - _d(s, 3, "phase_reopened", "phase:1") # rollback to phase 1 - _d(s, 4, "table_promoted", "phase:4") # stale: produced after reopen but for phase 4 (not current) - # After reopen to phase:1, the effective view truncates everything after the last phase_reopened. - eff = effective_decisions(s) - # The reopen at seq 3 means decisions after it (seq 4) are NOT effective, - # and the reopen itself sets the pointer. Effective = decisions up to and incl. reopen, - # then re-walked. The stale table_promoted at seq 4 must be excluded. - types = [d.type for d in eff] - assert "table_promoted" not in types - -def test_current_phase_after_reopen(tmp_path): - s = tmp_path / "s"; s.mkdir() - _d(s, 1, "phase_approved", "phase:1") - _d(s, 2, "phase_approved", "phase:2") - _d(s, 3, "phase_reopened", "phase:1") - assert current_phase(s) == 1 - _d(s, 4, "phase_approved", "phase:1") # re-approve after reopen - assert current_phase(s) == 2 - -def test_retracted_decision_excluded_from_effective(tmp_path): - s = tmp_path / "s"; s.mkdir() - _d(s, 1, "table_promoted", "phase:4", detail="t1") - _d(s, 2, "decision_retracted", "phase:4", retracts=1) - eff = effective_decisions(s) - types = [d.type for d in eff] - assert "table_promoted" not in types # retracted → excluded -``` - -- [ ] **Step 3: Run, verify fail** - -Run: `pytest tests/test_phase_effective.py -v` -Expected: FAIL - -- [ ] **Step 4: Implement `phase.py`** — the core. Port the fold logic from `ChironeWp3/src/psdwp3/session/phase.py` but: - - Read `max_phase`, `phase_name`, `decision_min_phase`, `advance_problems` rules from `workflow.yaml` via `load_workflow()`. - - Add `effective_decisions(session)`: replay the ledger; when hitting a `phase_reopened phase:N`, truncate everything after it in the effective view AND re-walk from phase N. When hitting a `decision_retracted`, exclude the retracted seq. - - Rewrite `advance_problems(phase)`, `approved_ctes`, `substantive_count_current_phase`, `auto_advance_eligible` to consult `effective_decisions()` instead of `list_decisions()`. - -Reference skeleton (the `effective_decisions` core — the load-bearing part): - -```python -# nsp/phase.py (key function) -from nsp.decisions import list_decisions -from nsp.workflow import load_workflow - -def effective_decisions(session_dir) -> list: - """The canonical effective view. ALL helpers MUST use this, not list_decisions(). - Replays the ledger: phase_reopened truncates the tail; decision_retracted excludes the target. - """ - all_d = list_decisions(session_dir) - retracted_seqs = {d.retracts for d in all_d if d.type == "decision_retracted" and d.retracts} - # Find the LAST phase_reopened; everything strictly after it is stale. - last_reopen_idx = -1 - for i, d in enumerate(all_d): - if d.type == "phase_reopened": - last_reopen_idx = i - if last_reopen_idx >= 0: - effective = all_d[: last_reopen_idx + 1] - else: - effective = list(all_d) - # Exclude retracted decisions (by seq), and the retraction records themselves. - return [d for d in effective if d.seq not in retracted_seqs and d.type != "decision_retracted"] -``` - -Implement `current_phase(session_dir)` as the fold over `effective_decisions(session_dir)` (not over raw list). Implement `advance_problems(phase, session_dir)` by evaluating the `prerequisites` list from `workflow.yaml` for that phase against `effective_decisions`. Reuse the prerequisite predicate types: `decision_exists`, `decision_subject_exists`, `file_validates`, `all_ctes_approved`, `any`, `all`. - -- [ ] **Step 5: Run, verify pass** - -Run: `pytest tests/test_phase_effective.py -v` -Expected: 3 PASS - -- [ ] **Step 6: Commit** - -```bash -git add harness/nsp/phase.py harness/nsp/session/ harness/tests/test_phase_effective.py -git commit -m "feat(harness): rewrite phase.py data-driven + effective_decisions (D15 core, F2)" -``` - ---- - -### Task A6: Create `teardown.py` — `teardown_to_phase` (D15 teardown) - -**Files:** -- Create: `harness/nsp/teardown.py` -- Test: `harness/tests/test_teardown.py` - -- [ ] **Step 1: Write failing test** - -```python -# tests/test_teardown.py -from pathlib import Path -from nsp.teardown import teardown_to_phase, TeardownReport - -def test_teardown_to_phase_4_deletes_phase5plus_artifacts(tmp_path): - s = tmp_path / "sess"; s.mkdir() - (s / "schema_linking.json").write_text("{}") # F4 artifact - (s / "cte_plan.json").write_text("[]") # F6 artifact - (s / "ctes").mkdir() - (s / "ctes" / "x.sql").write_text("SELECT 1") # F6 artifact - (s / "sql_final.sql").write_text("SELECT 1") # F7 artifact - report = teardown_to_phase(s, target_phase=4) - assert (s / "schema_linking.json").exists() # F4 preserved (target is 4) - assert not (s / "cte_plan.json").exists() # F6 deleted (>4) - assert not (s / "ctes").exists() # F6 dir deleted - assert not (s / "sql_final.sql").exists() # F7 deleted - assert "cte_plan.json" in report.deleted_files - assert "sql_final.sql" in report.deleted_files - -def test_teardown_records_deleted_in_ledger(tmp_path): - # teardown itself appends a phase_reopened decision (the rollback marker) - # — verifying that is covered by test_phase_effective; here we check the report. - s = tmp_path / "sess"; s.mkdir() - (s / "sql_final.sql").write_text("SELECT 1") - report = teardown_to_phase(s, target_phase=4) - assert len(report.deleted_files) >= 1 -``` - -- [ ] **Step 2: Run, verify fail** - -Run: `pytest tests/test_teardown.py -v` - -- [ ] **Step 3: Implement `teardown.py`** - -```python -# nsp/teardown.py -"""Artifact teardown on rollback (spec D15, §4.8). -Deletes every artifact whose producing phase > target, using the artifacts_out map -from workflow.yaml. Recomputes derived state. Fixes the orphaned-CTE-blocks-finalize bug. -""" -from __future__ import annotations -from dataclasses import dataclass, field -from pathlib import Path -from nsp.workflow import load_workflow - -@dataclass -class TeardownReport: - target_phase: int - deleted_files: list[str] = field(default_factory=list) - -def teardown_to_phase(session_dir: str | Path, target_phase: int) -> TeardownReport: - session_dir = Path(session_dir) - wf = load_workflow() - report = TeardownReport(target_phase=target_phase) - for phase in wf.phases: - if phase.num <= target_phase: - continue - for artifact in phase.artifacts_out: - target = session_dir / artifact.rstrip("/") - if artifact.endswith("/"): - # directory artifact (e.g. ctes/) - if target.exists(): - for f in target.glob("*"): - f.unlink() - report.deleted_files.append(f.name) - target.rmdir() - else: - if target.exists(): - target.unlink() - report.deleted_files.append(artifact) - return report -``` - -- [ ] **Step 4: Run, verify pass** - -Run: `pytest tests/test_teardown.py -v` -Expected: 2 PASS - -- [ ] **Step 5: Commit** - -```bash -git add harness/nsp/teardown.py harness/tests/test_teardown.py -git commit -m "feat(harness): teardown_to_phase — artifact teardown on rollback (D15)" -``` - ---- - -### Task A7: Create `taskdoc.py` — per-step task document generator (D16) - -**Files:** -- Create: `harness/nsp/taskdoc.py` -- Test: `harness/tests/test_taskdoc.py` - -- [ ] **Step 1: Write failing test** - -```python -# tests/test_taskdoc.py -from pathlib import Path -from nsp.taskdoc import generate_task_doc, TaskDoc - -def test_task_doc_includes_question_and_schema_scope_not_full_physical(tmp_path): - s = tmp_path / "sess"; s.mkdir() - (s / "question.md").write_text("# Domanda\nQuanti pazienti?\n## Assunzioni\n- a") - (s / "schema_linking.json").write_text('{"candidates":[{"kind":"table","name":"pazienti"}],"joins":[]}') - # A fatal-sized artifact that must NOT appear in the task doc - (s.parent / "physical.yaml").write_text("x: " + "y" * 800_000) - doc = generate_task_doc(session_dir=s, phase=7, promoted_tables=["pazienti"]) - assert "Quanti pazienti?" in doc.body - assert "pazienti" in doc.body - assert len(doc.body) < 100_000 # bounded — no fatal full-schema read - assert "physical.yaml" not in doc.body # never embedded - -def test_task_doc_byte_budget_enforced(tmp_path): - s = tmp_path / "sess"; s.mkdir() - (s / "question.md").write_text("q") - doc = generate_task_doc(session_dir=s, phase=1, promoted_tables=[]) - assert doc.byte_budget_ok is True -``` - -- [ ] **Step 2: Run, verify fail** - -Run: `pytest tests/test_taskdoc.py -v` - -- [ ] **Step 3: Implement `taskdoc.py`** - -```python -# nsp/taskdoc.py -"""Per-step task document generator (spec D16, §4.9). -Emits a single compact document per phase/step, derived from prior artifacts, -with enforced byte budget (target <20k tokens). NEVER embeds full physical.yaml. -""" -from __future__ import annotations -from dataclasses import dataclass -from pathlib import Path - -MAX_BODY_BYTES = 80_000 # ~20k tokens - -@dataclass -class TaskDoc: - phase: int - body: str - byte_budget_ok: bool - -def generate_task_doc(session_dir: Path | str, phase: int, promoted_tables: list[str] | None = None) -> TaskDoc: - session_dir = Path(session_dir) - parts: list[str] = [] - q = session_dir / "question.md" - if q.exists(): - parts.append("## Domanda\n" + q.read_text()) - sl = session_dir / "schema_linking.json" - if sl.exists() and phase >= 4: - parts.append("## Schema linking (deciso)\n```json\n" + sl.read_text() + "\n```") - # Task header for the phase - parts.append(f"## Task: fase {phase}") - body = "\n\n".join(parts) - return TaskDoc(phase=phase, body=body, byte_budget_ok=len(body.encode()) <= MAX_BODY_BYTES) -``` - -- [ ] **Step 4: Run, verify pass** - -Run: `pytest tests/test_taskdoc.py -v` -Expected: 2 PASS - -- [ ] **Step 5: Commit** - -```bash -git add harness/nsp/taskdoc.py harness/tests/test_taskdoc.py -git commit -m "feat(harness): taskdoc per-step generator with byte budget (D16)" -``` - ---- - -### Task A8: Port the CLI skeleton + `nsp phase meta --json` (F2) - -**Files:** -- Create: `harness/nsp/cli/__init__.py` (Typer app) -- Create: `harness/nsp/cli/phase_cmd.py` (adapted) -- Create: `harness/nsp/cli/workspace_cmd.py` -- Port the command modules (sql, cte, db, lsh, vector, evidence, schema, memory, search, session, decision) — adapt imports -- Test: `harness/tests/test_cli_phase_meta.py` - -**Honest scope:** this task ports the CLI structure + `phase meta` and verifies that ONE command behaves. It does NOT verify the 11 ported command modules — those get contract tests in **Task A9 (Livello B)**. Porting them here without tests would assume them reliable, which the spec forbids. - -- [ ] **Step 1: Port CLI modules** — copy `ChironeWp3/src/psdwp3/cli/*.py` → `harness/nsp/cli/`. Rename package imports. The gate will need `nsp phase meta --json` to avoid mirroring constants. - -- [ ] **Step 2: Write failing test for `nsp phase meta --json`** - -```python -# tests/test_cli_phase_meta.py -import json -from typer.testing import CliRunner -from nsp.cli import app - -runner = CliRunner() - -def test_phase_meta_json_returns_workflow_data(): - result = runner.invoke(app, ["phase", "meta", "--json"]) - assert result.exit_code == 0 - data = json.loads(result.stdout) - assert data["max_phase"] == 8 - assert len(data["phases"]) == 8 - assert data["phases"][7]["name"] == "datamart" # F8 present (fixes the JS drift) - assert "advance" in data["phases"][0] -``` - -- [ ] **Step 3: Run, verify fail, then implement `phase meta` in `phase_cmd.py`** - -The command reads from `load_workflow()` and dumps `{max_phase, phases: [{num,name,advance,artifacts_out}]}` as JSON. - -- [ ] **Step 4: Run, verify pass; commit** - -```bash -git add harness/nsp/cli/ harness/tests/test_cli_phase_meta.py -git commit -m "feat(harness): port CLI structure + nsp phase meta --json (F2, kills JS/Python drift)" -``` - ---- - -### Task A9: Contract tests for ported load-bearing modules — L0 (testcontainers) + L1 (fake data) - -**Rationale:** spec §1 forbids assuming ported code is reliable. The DB-touching modules get **L0 tests** (testcontainers — real Postgres in container, where "not assumed reliable" gains real teeth); the logic modules get **L1 tests** (fake data). Docker is available on the dev machine, so L0 runs locally on every `pytest`. - -**L0 tests (testcontainers, marker `@pytest.mark.l0`):** - -- [ ] **Step 1: `tests/l0/test_db_connection.py`** — read-only enforcement (exit code 2 if writable role), `ping` succeeds on read-only role. - -- [ ] **Step 2: `tests/l0/test_db_introspect.py` + `test_db_sampling.py`** — create a known schema + known rows in the container, verify `introspect` returns them with columns + comments, and `unique_values_for_lsh` returns the expected most-frequent values. - -- [ ] **Step 3: `tests/l0/test_rrf.py`** — load real-ish data into the container (LSH index built from sampled values + a small vector set), verify `combined_search`/`rrf_fuse` fuses them with stable, sensible ranking. This is the one that truly exercises the ported RRF/LSH pipeline. - -**L1 tests (fake data, no marker):** - -- [ ] **Step 4: `tests/test_rest_client.py`** — mock `requests`, verify one RPC call carries the `X-API-Key` header and parses the response. - -- [ ] **Step 5: `tests/test_mschema_render.py`** — the 3 formats (markdown, mschema-text ThothAI, schema-dict) from a fake `PhysicalSchema`. Catches port breaks in the render layer. - -- [ ] **Step 6: `tests/test_mschema_eligibility.py`** — eligibility rules on fake columns (wide-text excluded above threshold). - -- [ ] **Step 7: `tests/test_cli_contract.py`** — one test per ported CLI command (sql, cte, schema, session, decision, lsh, vector, evidence, memory, search, db): valid input → exit 0 + parseable JSON. - -- [ ] **Step 8: Register `l0` marker in `pyproject.toml`** and run all A9 tests. - -```toml -[tool.pytest.ini_options] -testpaths = ["tests"] -markers = [ - "l0: testcontainers tests (need Docker, run locally)", - "l2: end-to-end tests requiring real GLM 5.2 + remote DB (skipped when .env incomplete)", -] -addopts = "-m 'not l2'" # L0 runs by default (Docker present); L2 opt-in -``` - -```bash -cd harness && pytest tests/l0/ tests/test_rest_client.py tests/test_mschema_render.py \ - tests/test_mschema_eligibility.py tests/test_cli_contract.py -v -``` - -- [ ] **Step 9: Fix porting bugs the tests surface; commit** - -```bash -git add harness/tests/l0/ harness/tests/test_rest_client.py harness/tests/test_mschema_*.py \ - harness/tests/test_cli_contract.py harness/nsp/{db,rest,mschema,search}/ harness/pyproject.toml -git commit -m "test(harness): L0 testcontainers + L1 contract tests for ported modules (spec §1)" -``` - ---- - -## Phase B — Feature deviations (D11, D13, D14) - -### Task B1: Dual vector API key — port `vectorstore` + verify writer config (D11) - -**Files:** -- Port: `harness/nsp/vectorstore/{rest_client.py, rest_writer.py, store.py, reader.py, embeddings.py, records.py}` -- Port: `harness/nsp/cli/_guards.py` -- Port: `harness/scripts/create_vector_writer_rpc.sql` -- Create: `harness/scripts/create_vector_reader_rpc.sql` -- Test: `harness/tests/test_vector_dual_key.py` - -- [ ] **Step 1: Port the vectorstore modules** (rest_client, rest_writer, store, reader, embeddings, records) and `_guards.py` from ChironeWp3. These already implement the dual-key model per spec §5.4 — port them, rename package, verify `has_vector_write_rest` checks `.api_key.strip()`. - -- [ ] **Step 2: Write failing test for dual-key client construction** - -```python -# tests/test_vector_dual_key.py -from nsp.config import RestConfig -from nsp.vectorstore.rest_client import VectorRestClient - -def test_reader_and_writer_use_separate_keys(): - reader = VectorRestClient(RestConfig(base_url="https://v/", api_key="K-READ")) - writer = VectorRestClient(RestConfig(base_url="https://v/", api_key="K-WRITE")) - assert reader.api_key == "K-READ" - assert writer.api_key == "K-WRITE" - -def test_has_vector_write_rest_false_for_empty_key(): - from nsp.cli._guards import has_vector_write_rest - from nsp.config import Config, RestConfig - cfg = Config(vector_write_rest=RestConfig(base_url="x", api_key=" ")) - assert has_vector_write_rest(cfg) is False -``` - -- [ ] **Step 3: Run, verify fail, adjust ported code so `VectorRestClient` exposes `api_key` (it stores the config; add a property if missing), verify pass.** - -- [ ] **Step 4: Create `create_vector_reader_rpc.sql`** — author the reader RPC (`search_similar`, `list_tables`) mirroring the writer allowlist pattern, granted to a `vector_reader` role. (The reader RPCs lived server-side in Supabase and were never in the ChironeWp3 repo — spec §5.4 note. Author them now.) - -- [ ] **Step 5: Commit** - -```bash -git add harness/nsp/vectorstore/ harness/nsp/cli/_guards.py harness/scripts/ harness/tests/test_vector_dual_key.py -git commit -m "feat(harness): port vectorstore dual-key + reader RPC (D11, §5.4)" -``` - ---- - -### Task B2: `nsp memory save-one` — targeted upsert via writer key (D11) - -**Files:** -- Modify: `harness/nsp/cli/memory_cmd.py` (add `save-one`) -- Modify: `harness/nsp/memory.py` (add `memory_vector_record_for_decision`) -- Test: `harness/tests/test_memory_save_one.py` - -- [ ] **Step 1: Write failing test** - -```python -# tests/test_memory_save_one.py -from pathlib import Path -from unittest.mock import patch, MagicMock -from typer.testing import CliRunner -from nsp.cli import app - -runner = CliRunner() - -def test_save_one_calls_upsert_with_single_record(tmp_path, monkeypatch): - session = tmp_path / "s"; session.mkdir() - # build a minimal registry + a decision_seq to save - from nsp.decisions import append_decision, DecisionRecord - append_decision(session, DecisionRecord(seq=7, ts="t", type="table_promoted", - subject="phase:4", detail="pazienti", rationale="r")) - mock_writer = MagicMock() - mock_writer.upsert_records.return_value = 1 - with patch("nsp.cli.memory_cmd.open_store", return_value=mock_writer): - result = runner.invoke(app, ["memory", "save-one", "--session", str(session), "--decision-seq", "7"]) - assert result.exit_code == 0 - mock_writer.sync.assert_not_called() # must be a single upsert, NOT full resync - mock_writer.upsert_records.assert_called_once() - args = mock_writer.upsert_records.call_args - assert len(args[0][1]) == 1 # exactly one row - -def test_save_one_refused_without_writer_key(tmp_path, monkeypatch): - monkeypatch.setenv("THOTH_PROFILE", "workstation") - session = tmp_path / "s"; session.mkdir() - # config with no write_rest - result = runner.invoke(app, ["memory", "save-one", "--session", str(session), "--decision-seq", "1"]) - assert result.exit_code == 4 # require_vector_write_allowed gate -``` - -- [ ] **Step 2: Run, verify fail** - -- [ ] **Step 3: Implement `save-one`** in `memory_cmd.py`: - - Guard: `require_vector_write_allowed(cfg, "memory save-one")`. - - Load the registry, find the memory record for `decision_seq`. - - Build a single `VectorRecord` (reuse `memory_vector_records` but filter to one). - - Call `writer.existing_hashes(kinds={"memory"})` + embed (if hash changed) + `writer.upsert_records(table="memory", rows=[one])`. - - Do NOT call `writer.sync` (that's the full-resync path). - -- [ ] **Step 4: Run, verify pass; commit** - -```bash -git add harness/nsp/cli/memory_cmd.py harness/nsp/memory.py harness/tests/test_memory_save_one.py -git commit -m "feat(harness): nsp memory save-one — targeted upsert via writer key (D11)" -``` - ---- - -### Task B3: Value & Schema Linking — `value_grounded` decision + LSH multi-column (D14a) - -**Files:** -- Modify: `harness/nsp/decisions.py` (add `value_grounded`) -- Modify: `harness/nsp/search/__init__.py` (stop collapsing multi-column to single best) -- Modify: `harness/nsp/session/models.py` (`Candidate.grounded_values`) -- Test: `harness/tests/test_value_grounding.py` - -- [ ] **Step 1: Port `search/__init__.py`, `lshindex/`, `db/sampling.py`** from ChironeWp3. Then modify. - -- [ ] **Step 2: Write failing test for multi-column LSH exposure** - -```python -# tests/test_value_grounding.py -from nsp.search import aggregate_lsh_multi - -def test_value_in_multiple_columns_returns_all(): - hits = [ - {"table": "t", "column": "c1", "value": "ablazione", "score": 0.9}, - {"table": "t", "column": "c2", "value": "ablazione", "score": 0.7}, - ] - result = aggregate_lsh_multi(hits) - # NOT collapsed to single best — both columns exposed - cols = {h["column"] for h in result["t"]} - assert cols == {"c1", "c2"} -``` - -- [ ] **Step 3: Run, verify fail, then implement `aggregate_lsh_multi`** (replaces the collapsing `_aggregate_lsh` behavior — keep the old name as a thin wrapper to the new one if other code needs single-best). Add `value_grounded` to DecisionType. Add `grounded_values: list[dict] = []` to `Candidate` in `session/models.py`. - -- [ ] **Step 4: Run, verify pass; commit** - -```bash -git add harness/nsp/search/ harness/nsp/lshindex/ harness/nsp/db/sampling.py harness/nsp/decisions.py harness/nsp/session/models.py harness/tests/test_value_grounding.py -git commit -m "feat(harness): value grounding — multi-column LSH + value_grounded (D14a)" -``` - ---- - -### Task B4: SQL formula evidence — formula kind + retrieval + approval (D14b) - -**Files:** -- Modify: `harness/nsp/evidence/model.py` (activate `tier: concept` / add formula fields) -- Create: `harness/nsp/evidence/formula_store.py` -- Modify: `harness/nsp/cli/search_cmd.py` (`--kind formula`) -- Modify: `harness/nsp/decisions.py` (add `concept_formula_approved`, `concept_formula_rejected`) -- Test: `harness/tests/test_formula.py` - -- [ ] **Step 1: Port `evidence/` modules** from ChironeWp3. - -- [ ] **Step 2: Write failing test for formula retrieval** - -```python -# tests/test_formula.py -from pathlib import Path -from nsp.evidence.formula_store import ConceptFormula, save_formula, retrieve_formula - -def test_formula_retrieval_by_concept(tmp_path): - f = ConceptFormula(concept="fascia pediatrica", columns=["data_nascita"], - sql="CASE WHEN ... END", status="reviewed", sources=["s1"]) - save_formula(tmp_path, f) - results = retrieve_formula(tmp_path, "fascia pediatrica") - assert len(results) == 1 - assert results[0].sql.startswith("CASE WHEN") - assert results[0].concept == "fascia pediatrica" -``` - -- [ ] **Step 3: Run, verify fail, implement `formula_store.py`** (frontmatter YAML + SQL body, concept→formula units). Add `--kind formula` to `search_cmd` that calls `retrieve_formula`. Add the two new decision types. - -- [ ] **Step 4: Run, verify pass; commit** - -```bash -git add harness/nsp/evidence/ harness/nsp/cli/search_cmd.py harness/nsp/decisions.py harness/tests/test_formula.py -git commit -m "feat(harness): SQL formula evidence — concept→formula units + retrieval + approval decisions (D14b)" -``` - ---- - -### Task B5: Free-text interpretation guidance (D13) - -**Files:** -- Modify: `harness/nsp/cli/decision_cmd.py` (ensure free-text from "Altro"/"Rifiuta" is captured in `rationale`) -- Modify: `.pi/skills/nsp-sessione/SKILL.md` (+ sub-files) — port + add the D13 §4.6 guidance -- Test: `harness/tests/test_freetext_interpretation.py` - -- [ ] **Step 1: Write failing test** — a golden-style test that, given a `ui_response` with `control: freetext` (Altro text), verifies the harness records the user's text in the decision `rationale` (not discarded). - -```python -# tests/test_freetext_interpretation.py -from pathlib import Path -from nsp.decisions import append_decision, list_decisions, DecisionRecord - -def test_altro_freetext_recorded_in_rationale(tmp_path): - s = tmp_path / "sess"; s.mkdir() - # The gate, on receiving Altro text, appends a decision whose rationale carries the user's words. - append_decision(s, DecisionRecord(seq=1, ts="t", type="table_promoted", - subject="phase:4", detail="ablazione", - rationale="Utente (Altro): 'ablazione' va cercato anche in patologia, non solo nel flag")) - decisions = list_decisions(s) - assert "patologia" in decisions[0].rationale # user text preserved, not discarded -``` - -- [ ] **Step 2: Port `SKILL.md` + sub-files** from ChironeWp3. Add a section "Interpretazione del testo libero" per spec §4.6: instructs the model to (1) evaluate Altro/Rifiuta/steering text in context, (2) act on it, (3) if ambiguous, re-ask instead of defaulting, (4) record the text in the decision rationale. - -- [ ] **Step 3: Run, verify pass (the test asserts the recording contract; the actual model behavior is enforced by the skill prose + gate, validated by fake-pi golden tests in Task C3); commit** - -```bash -git add harness/.pi/skills/ harness/nsp/cli/decision_cmd.py harness/tests/test_freetext_interpretation.py -git commit -m "feat(harness): free-text interpretation guidance + rationale capture (D13)" -``` - ---- - -## Phase C — Gate → widget-descriptor (D2/D4) - -The gate has two parts with **very different testability**: -- **Builders** (pure functions that turn tool-call params into widget-descriptor JSON) — fully testable in L1, **in JS, in-language**. -- **Glue** (Pi runtime integration: `pi.registerTool`, `ctx.sendRaw`, `emitAndWait`, anti-bypass hooks, no-limbo loop) — **NOT testable in L1**; it depends on the Pi runtime. Tested at L2. - -This phase therefore has: **C1 (builders, L1, JS)** + **C2 (glue implementation, no L1 test — verified at L2)**. There is no fake-LLM driver and no `build-scenarios` in this plan (see cross-cutting follow-up). - -### Task C1: Pure widget-builder functions + JS tests (L1) - -**Files:** -- Create: `harness/.pi/extensions/gate/builders.js` (pure functions, no Pi context) -- Create: `harness/.pi/extensions/gate/__tests__/builders.test.js` (node:test, in-language) -- Create: `harness/.pi/extensions/gate/__tests__/golden/*.json` (golden widget descriptors) -- Create: `harness/package.json` (for `npm test` → `node --test`) - -This task extracts widget-descriptor **construction** into pure, testable functions and tests them in JS directly — no Python↔JS bridge, no Python mirror (a mirror would drift; the golden tests would validate the mirror, not the real gate). - -- [ ] **Step 1: Create `package.json`** for the gate JS tests. - -```json -{ - "name": "thothii-harness-gate", - "private": true, - "scripts": { "test": "node --test .pi/extensions/gate/__tests__/" } -} -``` - -- [ ] **Step 2: Define the pure builder API in `builders.js`.** Each builder takes plain params and returns a plain widget-descriptor object. No `ctx`, no I/O. - -```javascript -// gate/builders.js — pure functions, no Pi context. Each returns a ui_request descriptor (spec §4.1). -function buildSelectRequest({ id, phase, title, options, intro = null, allowOther = true, recommended = null }) { /* ... */ } -function buildMultiselectRequest({ id, phase, title, options, content = null, allowEmpty = false, allowOther = true }) { /* ... */ } -function buildArtifactGate({ id, phase, title, artifact /* {kind, data, version} */, action /* {kind, prompt} */ }) { /* ... */ } -function buildInfoRequest({ phase, level, text }) { /* ... */ } -function buildFreetextRequest({ id, phase, title }) { /* ... */ } -function withChildLinkage(option, widgetSpec) { /* sets option.opens = widgetSpec; returns option */ } -module.exports = { buildSelectRequest, buildMultiselectRequest, buildArtifactGate, buildInfoRequest, buildFreetextRequest, withChildLinkage }; -``` - -- [ ] **Step 3: Write JS golden tests** — one golden file per widget type, one test per widget. Assert exact shape. - -```javascript -// gate/__tests__/builders.test.js -const test = require("node:test"); -const assert = require("node:assert"); -const fs = require("node:fs"); -const path = require("node:path"); -const { buildSelectRequest, buildMultiselectRequest, buildArtifactGate } = require("../builders.js"); - -const GOLDEN = path.join(__dirname, "golden"); - -test("select F1 matches golden", () => { - const result = buildSelectRequest({ id: "u1", phase: "F1", title: "Disambigua 'ablazione'", - options: [{ id: "o1", label: "procedura" }, { id: "o2", label: "patologia" }] }); - const golden = JSON.parse(fs.readFileSync(path.join(GOLDEN, "select_F1.json"))); - assert.equal(result.widget, "select"); - assert.deepEqual(result.reserved, golden.reserved); // back/exit/other - assert.deepEqual(result.options, golden.options); - assert.ok(result.schema_version); -}); - -test("artifact-gate F5 schema matches golden", () => { - const result = buildArtifactGate({ id: "u2", phase: "F5", title: "Schema-linking", - artifact: { kind: "schema_linking", data: { candidates: [] }, version: 1 }, - action: { kind: "confirm", prompt: "Confermi?" } }); - assert.equal(result.widget, "artifact-gate"); - assert.equal(result.artifact.kind, "schema_linking"); - assert.equal(result.action.kind, "confirm"); -}); - -test("multiselect F4 carries content + allowEmpty", () => { - const result = buildMultiselectRequest({ id: "u3", phase: "F4", title: "Tabelle", - options: [], content: { candidates: [] }, allowEmpty: false }); - assert.equal(result.widget, "multiselect"); - assert.equal(result.allow_empty, false); - assert.ok("content" in result); -}); - -test("Altro option carries freetext linkage", () => { - const result = buildSelectRequest({ id: "u4", phase: "F1", title: "x", options: [] }); - const other = result.options.find(o => o.id === "other"); - assert.equal(other.opens.widget, "freetext"); -}); -``` - -- [ ] **Step 4: Create the golden files**, run `npm test`, verify pass. - -```bash -cd harness && npm test -``` - -- [ ] **Step 5: Fuzzy tests on builders (L1, JS)** — malformed params (missing `title`, non-list `options`, empty `options` with `allowEmpty:false`). Assert builders throw clearly or return a well-formed error descriptor, never silently produce a broken widget. - -```javascript -test("select with missing title throws clearly", () => { - assert.throws(() => buildSelectRequest({ id: "u", phase: "F1", options: [] }), /title/); -}); -test("multiselect allowEmpty:false with zero options throws", () => { - assert.throws(() => buildMultiselectRequest({ id: "u", phase: "F4", title: "x", options: [], allowEmpty: false }), /allow_empty|options/); -}); -``` - -- [ ] **Step 6: Commit** - -```bash -git add harness/package.json harness/.pi/extensions/gate/ -git commit -m "feat(harness): pure widget-builder functions + JS golden/fuzzy tests (D2, L1)" -``` - ---- - -### Task C2: Gate glue — rewrite `nsp-gate.js` (implementation; verification at L2) - -**Files:** -- Create: `harness/.pi/extensions/nsp-gate.js` (rewritten from ChironeWp3) -- Port: `harness/.pi/extensions/reserved-labels.mjs` -- **No L1 test** — the glue depends on the Pi runtime and is verified at L2 (Task D4). - -**Honest scope:** this task implements the glue but cannot unit-test it in L1. The glue's correctness is validated end-to-end at L2 with real Pi + GLM 5.2. This is the load-bearing limitation stated in the Testing Strategy headline. Do NOT attempt to mock Pi here — that is the fake-Pi follow-up (cross-cutting), not part of this plan. - -- [ ] **Step 1: Port `reserved-labels.mjs`** (BACK/EXIT/OTHER labels, `isReserved`/`stripReserved`). - -- [ ] **Step 2: Port the anti-bypass hooks verbatim** from the original `nsp-gate.js`: `tool_call` hook blocking `nsp phase advance|reopen`, `nsp decision add`, `nsp cte plan`; protected-file list (`review_decisions.jsonl`, `session_manifest.yaml`, `cte_plan.json`); input-lock; `before_agent_start` kickoff. These are load-bearing (spec D4) and unchanged. - -- [ ] **Step 3: Wire tools to builders + emission.** Each of the 4 tools (`reviewer_select`, `reviewer_decide`, `reviewer_confirm`, `rewrite_question`) calls the matching builder from C1, then emits via `ctx.sendRaw({type:"extension_ui_request", ...})` and awaits the correlated response by `id`. Preserve: no-limbo invariant (Esc/cancel re-presents — never returns undefined), recommended-option marker, reading `SCHEMA_LINKING_PHASE`/`PHASE_NAMES` from `nsp phase meta --json` (no mirroring). - -```javascript -// nsp-gate.js (the glue) — wires C1 builders to the Pi runtime -const { buildSelectRequest, buildMultiselectRequest, buildArtifactGate } = require("./gate/builders.js"); - -module.exports = function (pi) { - pi.registerTool({ - name: "reviewer_select", /* ... */, - async execute(id, params, signal, onUpdate, ctx) { - const widget = buildSelectRequest({ id, phase: await currentPhase(ctx), ...params }); - const resp = await emitAndWait(ctx, widget); // extension_ui_request → wait → response - return handleSelectResponse(resp, params); // incl. Altro→freetext linkage, Back→reopen - } - }); - // ... reviewer_decide, reviewer_confirm, rewrite_question, anti-bypass hooks, kickoff injection -}; -``` - -- [ ] **Step 4: Manual smoke (optional, pre-L2)** — launch `pi --mode rpc` from `harness/` once, confirm the extension loads and `/nuova-domanda` triggers a tool registration (no crash). This is a sanity check, not a regression test. - -- [ ] **Step 5: Commit** (verification happens at L2 in Task D4) - -```bash -git add harness/.pi/extensions/nsp-gate.js harness/.pi/extensions/reserved-labels.mjs -git commit -m "feat(harness): rewrite nsp-gate.js glue wired to builders (D2/D4) — verified at L2" -``` - ---- - -## Phase D — End-to-end validation (L1 smoke + L2 real) - -### Task D1: L1 session-coherence smoke test (pure logic, CI) - -**Files:** -- Create: `harness/tests/test_session_coherence_smoke.py` - -A pure-logic test (no LLM, no DB) that constructs a plausible ledger by hand and asserts the invariants D1-the-L2-version would check. This is the CI-runnable proxy for "full session coherence." - -- [ ] **Step 1: Write the test** — build a synthetic ledger (decisions appended directly, not via LLM) representing a full F1→F8 walk + a rollback F6→F4 + re-derive. Assert: `current_phase` folds correctly at each step, `effective_decisions` excludes the stale tail after rollback, `teardown_to_phase(4)` deletes the right artifacts, `generate_task_doc` stays under byte budget at every phase, and `nsp session consistency` (the post-rollback coherence check) passes. - -```python -# tests/test_session_coherence_smoke.py -from pathlib import Path -from nsp.decisions import append_decision, DecisionRecord -from nsp.phase import current_phase, effective_decisions -from nsp.teardown import teardown_to_phase -from nsp.taskdoc import generate_task_doc - -def test_full_walk_then_rollback_stays_coherent(tmp_path): - s = tmp_path / "sess"; s.mkdir() - # build a synthetic full-session ledger - for n in range(1, 9): - append_decision(s, DecisionRecord(seq=n, ts="t", type="phase_approved", subject=f"phase:{n}", - detail="", rationale="")) - assert current_phase(s) == 9 # max_phase + 1 - # rollback to F4 - append_decision(s, DecisionRecord(seq=9, ts="t", type="phase_reopened", subject="phase:4", - detail="", rationale="")) - report = teardown_to_phase(s, target_phase=4) - assert current_phase(s) == 4 - assert "sql_final.sql" in report.deleted_files or "cte_plan.json" in report.deleted_files - # task docs stay bounded across phases - for ph in range(1, 9): - doc = generate_task_doc(session_dir=s, phase=ph, promoted_tables=["dim_paziente"]) - assert doc.byte_budget_ok, f"phase {ph} task doc over budget" -``` - -- [ ] **Step 2: Run, verify pass; commit** - -```bash -git add harness/tests/test_session_coherence_smoke.py -git commit -m "test(harness): L1 session-coherence smoke (full walk + rollback, pure logic)" -``` - ---- - -### Task D2: `.pi/` config + prompts + theme ported - -**Files:** -- Create: `harness/.pi/settings.json` -- Create: `harness/.pi/themes/` (port theme) -- Create: `harness/.pi/prompts/nuova-domanda.md`, `riprendi-sessione.md` -- No test (config files) - -- [ ] **Step 1: Port** `.pi/settings.json`, theme, and the two prompt files from ChironeWp3. Verify `pi --mode rpc` launched with `cwd=harness/` finds the `.pi/` directory. - -- [ ] **Step 2: Commit** - -```bash -git add harness/.pi/ -git commit -m "feat(harness): port .pi/ config, prompts, theme" -``` - ---- - -### Task D3: L2 conftest + skip-when-no-.env guard - -**Files:** -- Create: `harness/tests/conftest.py` -- Create: `harness/tests/l2/__init__.py` -- Modify: `harness/pyproject.toml` (register `l2` marker) - -- [ ] **Step 1: Register the `l2` marker** in `pyproject.toml`: - -```toml -[tool.pytest.ini_options] -testpaths = ["tests"] -markers = [ - "l2: end-to-end tests requiring real GLM 5.2 + remote DB (skipped when .env incomplete)", -] -addopts = "-m 'not l2'" # CI default: skip L2 unless explicitly requested -``` - -- [ ] **Step 2: Write `conftest.py`** with a session fixture that loads `.env` and a `l2_env` fixture that skips if any required var is missing. - -```python -# tests/conftest.py -import os -from pathlib import Path -import pytest -from dotenv import load_dotenv - -REQUIRED_L2 = ["THOTH_DWH_API_KEY", "THOTH_VEC_API_KEY", "THOTH_VEC_WRITE_API_KEY", "THOTH_SSL_CA"] - -@pytest.fixture(scope="session", autouse=True) -def _load_env(): - load_dotenv(Path(__file__).resolve().parent.parent / ".env") - -@pytest.fixture(scope="session") -def l2_env(): - missing = [v for v in REQUIRED_L2 if not os.environ.get(v, "").strip()] - if missing: - pytest.skip(f"L2 skipped — missing env vars: {', '.join(missing)} (populate harness/.env)") - return True -``` - -- [ ] **Step 3: Commit** - -```bash -git add harness/tests/conftest.py harness/tests/l2/__init__.py harness/pyproject.toml -git commit -m "test(harness): L2 marker + skip-when-no-.env guard (Testing Strategy)" -``` - ---- - -### Task D4: L2 full session — "ablazione" with GLM 5.2 (human-in-the-loop) - -**Files:** -- Create: `harness/tests/l2/test_session_ablazione.py` -- Create: `harness/workspaces/chirone-test.yaml` - -This is the **end-to-end validation that L1 cannot do**: GLM 5.2 driving the real harness against the real DWH + pgvector, on the "ablazione" question (which exercises D14 value grounding + formula on a multi-column case). Default mode = human answers via terminal; scripted-answers mode for repeatability. - -- [ ] **Step 1: Create `workspaces/chirone-test.yaml`** pointing at the remote endpoints per the L2 connection params. Secrets via `${THOTH_*}`. - -```yaml -name: chirone-test -description: "Chirone DWH — L2 test workspace" -relational: - db_type: postgres - transport: rest - rest: - base_url: https://supabase-aritmolab.policlinicosandonato.it/dwh/ - api_key: ${THOTH_DWH_API_KEY} - ssl_ca: ${THOTH_SSL_CA} -vector_db: - collection: chirone_docs - dim: 768 - rest: - base_url: https://supabase-aritmolab.policlinicosandonato.it/vector/v1/ - api_key: ${THOTH_VEC_API_KEY} - ssl_ca: ${THOTH_SSL_CA} - write_rest: - base_url: https://supabase-aritmolab.policlinicosandonato.it/vector/v1/ - api_key: ${THOTH_VEC_WRITE_API_KEY} - ssl_ca: ${THOTH_SSL_CA} -evidence: - source_root: ${EVIDENCE_ROOT} - evidence_dir: evidence/chirone -embeddings: - provider: ollama - base_url: ${THOTH_OLLAMA_URL} - model: nomic-embed-text-v2-moe - dim: 768 - batch_size: 64 -execution: - allow: [cte_test, explain, preview, aggregate, export] - max_preview_rows: 10 - statement_timeout_ms: 5000 - forbidden_functions: [set_config, dblink, dblink_exec, lo_import] -``` - -- [ ] **Step 2: Write the L2 test** — spawns Pi (`pi --mode rpc`, cwd=harness/) with GLM 5.2, runs `/nuova-domanda "dammi la lista dei pazienti che hanno fatto un'ablazione nel 2025"`, and either (a) prompts the reviewer in the terminal for each gate widget (human mode) or (b) feeds canned answers (scripted mode via `--answers-file`). Asserts: a session is produced, it reaches a finalized state, the `value_grounded` and `concept_formula_approved` decisions appear (D14 exercised), `sql_final.sql` is present and read-only-validates against the DWH. - -```python -# tests/l2/test_session_ablazione.py -import subprocess, json -from pathlib import Path -import pytest - -@pytest.mark.l2 -def test_ablazione_session_human_in_loop(l2_env, tmp_path): - """L2: GLM 5.2 + real DWH. Reviewer answers gates via terminal. - Run with: pytest -m l2 tests/l2/test_session_ablazione.py -s - """ - session_dir = tmp_path / "sess" - proc = subprocess.run( - ["pi", "--mode", "rpc"], - cwd="harness/", - # the test harness feeds /nuova-domanda and relays terminal I/O for reviewer answers - ... - timeout=600, - ) - assert (session_dir / "sql_final.sql").exists() - ledger = (session_dir / "review_decisions.jsonl").read_text().splitlines() - types = {json.loads(l)["type"] for l in ledger} - assert "value_grounded" in types or "concept_formula_approved" in types # D14 exercised -``` - -- [ ] **Step 3: Run manually** (`pytest -m l2 -s`), confirm the session finalizes and D14 surfaces. This is non-deterministic and slow — it's a pre-release check, not CI. **Commit the test + workspace; the operator runs it before release.** - -```bash -git add harness/tests/l2/test_session_ablazione.py harness/workspaces/chirone-test.yaml -git commit -m "test(harness): L2 ablazione session with GLM 5.2 + real DWH (D14, human/scripted)" -``` - ---- - -### Task D5: L2 specific behaviors — value grounding (real) + memory save-one (real) - -**Files:** -- Create: `harness/tests/l2/test_value_grounding_real.py` -- Create: `harness/tests/l2/test_memory_save_one_real.py` - -Targeted L2 tests that close specific gaps L1 leaves open: real value grounding on the live schema, and real `memory save-one` upsert to pgvector. - -- [ ] **Step 1: `test_value_grounding_real.py`** — runs `nsp search "ablazione" --kind values --workspace chirone-test`, asserts multiple columns are returned (not collapsed), and that a grounding widget would surface them. Validates D14a on the real schema. - -- [ ] **Step 2: `test_memory_save_one_real.py`** — runs `nsp memory save-one` against `chirone-test` (writer key), asserts the upsert returns `upserted >= 0` (idempotent) and a subsequent `search_similar` finds the memory. Validates D11 end-to-end. - -- [ ] **Step 3: Run manually (`pytest -m l2 -s tests/l2/`); commit** - -```bash -git add harness/tests/l2/test_value_grounding_real.py harness/tests/l2/test_memory_save_one_real.py -git commit -m "test(harness): L2 value grounding (real schema) + memory save-one (real pgvector)" -``` - ---- - -### Task D6: Documentation — README + workflow editing + testing guide - -**Files:** -- Create: `harness/README.md` -- Create: `harness/docs/workflow-editing.md` -- Create: `harness/docs/testing.md` - -- [ ] **Step 1: Write `README.md`** — install, configure `.env` + `workspaces/`, run `nsp`, run L0+L1 tests, run L2 tests (with the CA-bundle copy step). - -- [ ] **Step 2: Write `docs/workflow-editing.md`** — how to edit `workflow.yaml` (add/reorder/merge/skip phases), referencing spec §5.3. - -- [ ] **Step 3: Write `docs/testing.md`** — explain the L0/L1/L2 split honestly: what each level covers and does NOT cover (in plain language: L0 = DB-touching code vs real Postgres in container; L1 = pure logic + gate builders, no DB no LLM; L2 = full system with real GLM 5.2 + remote DB, manual pre-release). State the headline limitation plainly: the LLM→gate conversation has no automated regression coverage. How to run each level (`pytest` for L0+L1, `pytest -m l2` for L2 needing `.env` + VPN + CA bundle). The security note on keys (`.env` gitignored, never logged). - -- [ ] **Step 4: Commit** - -```bash -git add harness/README.md harness/docs/ -git commit -m "docs(harness): README + workflow editing + testing guide (L1/L2)" -``` - ---- - -## Self-Review Notes - -**Spec coverage check** (spec section → task): -- §1 (ChironeWp3 as starting point, NOT assumed reliable): enforced by a **3-tier porting classification**: - - **Tier A (modified by ThothII → full regression test):** phase.py (A5), decisions.py (A4), vectorstore/_guards dual-key (B1), memory_cmd save-one (B2), search multi-column (B3), evidence formula (B4), phase_cmd meta (A8). Each has a focused L1 test for the changed behavior. - - **Tier B (ported unchanged but load-bearing → contract test):** db/connection + introspect + sampling + RRF (**L0 testcontainers**, A9 steps 1-3 — real Postgres, where "not reliable" is tested for real), rest/client + mschema/render + mschema/eligibility + 11 CLI commands (**L1 fake data**, A9 steps 4-7). The L0/L1 split inside Tier B reflects whether the module touches a DB. - - **Tier C (ported unchanged, non-load-bearing → smoke OK):** fetch_ca, output/formatting helpers. Acceptable with smoke. - This makes "not assumed reliable" honest for the load-bearing surface. ✓ -- D1 (3 projects): this plan = harness only; backend/frontend are separate plans. ✓ -- D2/D4 (widget-descriptor gate): **builders** in C1 (L1, JS, in-language — golden + fuzzy); **glue** in C2 (implementation only — verified at L2, NOT in L1, because it depends on the Pi runtime). The limitation is documented in the Testing Strategy headline. ✓ -- D3 (workspace YAML): Task A2. ✓ -- D5 (FS persistence, ledger): Task A4 (decisions port), session models in A5. ✓ -- D6 (auth): out of scope for harness (auth is backend). ✓ (noted) -- D7 (backend SQL read-only): out of scope for harness. ✓ -- D8 (nsp stays Python): all harness tasks are Python (gate glue is JS, per the source). ✓ -- D10 (testing): **three levels** — L0 testcontainers (A9 steps 1-3, runs locally), L1 fake/logic + gate builders (A2-A8, B1-B5, C1, D1; runs locally), L2 real GLM 5.2 + remote DB (D4, D5; pre-release). Honest headline in Testing Strategy: the skill→LLM→gate loop has NO automated regression coverage. ✓ -- D11 (dual key + save-one): B1 (L1 dual-key), B2 (L1 save-one mocked), D5 (L2 save-one real). ✓ -- D12 (deployment model B): harness runs locally — `.env.example` (THOTH_PROFILE), L2 against remote REST over VPN. ✓ -- D13 (free-text interpretation): B5 (L1 rationale contract), D4 (L2 with real model — the glue that records rationale is L2-only). ✓ -- D14a (value grounding): B3 (L1 aggregate_lsh_multi on fake hits), D5 (L2 real schema). ✓ -- D14b (formula): B4 (L1 formula store). ✓ (L2 formula approval rides on D4) -- D15 (rollback): A4 (retract), A5 (effective view), A6 (teardown), D1 (L1 coherence smoke), D4 (L2 glue behavior). ✓ -- D16 (context minimization): A7 (taskdoc, L1). ✓ (per-phase reset in Pi noted as execution detail) - -**Type consistency:** `effective_decisions`, `teardown_to_phase`, `generate_task_doc`, `load_workflow`, `save_formula`, `retrieve_formula`, `aggregate_lsh_multi`, `decision_retracted`, `value_grounded`, `concept_formula_approved/rejected`, builder functions (`buildSelectRequest` etc.) — names match across tasks. ✓ - -**Testing honesty (the load-bearing facts):** -- **The skill→LLM→gate loop has NO automated regression coverage.** It is exercised only at L2 (manual, non-deterministic, pre-release). This is a conscious choice; plan L2 runs before release. -- **The gate glue cannot be unit-tested in L1** — it depends on the Pi runtime (`pi.registerTool`, `ctx.sendRaw`). Only the pure builders are L1-tested (in JS, in-language). -- L0 (testcontainers) tests the DB-touching ported code against a real Postgres — this is where "not assumed reliable" is actually enforced for the data layer. -- L2 tests (D4, D5) are non-deterministic, slow, require credentials + VPN + CA bundle. Skipped automatically when `.env` incomplete. - -**Known follow-ups (not in this plan):** -- **Cross-cutting: a fake-Pi runtime mock** that lets the gate glue run in L1/CI. When built (likely alongside the backend plan, which also needs a fake-Pi to test its RPC client), it would close the gap "gate glue has no L1 test" AND enable a `build-scenarios`/`fake-LLM` replay harness for deterministic gate-behavior tests. This is the single highest-value testing investment not in this plan. It is deferred because it is substantial and shared with the backend. -- The SSE/REST surface the backend will build on (harness speaks JSONL via Pi + `nsp --json`). -- `session consistency` check integration into `nsp session check` (Task A5 stubs the effective view; the full assertion grows during execution). -- Per-phase context reset mechanism in Pi (D16 §4.9 step 3) — depends on Pi's context-management capability, verified when running the gate against real Pi in Task D4. - -This plan is self-contained: at the end, `harness/` runs the full 8-phase workflow emitting/consuming widget-descriptor JSON, validated by L0 (testcontainers) + L1 (logic + gate builders) on every local run, plus L2 (GLM 5.2 + real DB) pre-release. Ready for the backend to spawn and drive. diff --git a/docs/superpowers/plans/2026-06-27-backend-implementation.md b/docs/superpowers/plans/2026-06-27-backend-implementation.md deleted file mode 100644 index d41e0d1e..00000000 --- a/docs/superpowers/plans/2026-06-27-backend-implementation.md +++ /dev/null @@ -1,1024 +0,0 @@ -# Backend Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Costruire il backend ThothII: un orchestratore/traduttore Node+Fastify+TS che avvia Pi in RPC (un processo per sessione), fa da ponte JSONL↔(SSE/REST) verso il frontend, delega a `tht` l'esecuzione del SQL finale, e applica auth pluggabile. - -**Architecture:** Backend senza stato persistente proprio (verità su disco harness). Un `RpcClient` (framing LF-only) per ogni processo Pi gestito dal `PiProcessManager` (uno per sessione attiva). Il `SessionBridge` traduce `extension_ui_request`↔`ui_request` correlando per `id` e mantiene il widget pendente per il re-emit su riconnessione SSE. Le interazioni con il modello (prompt/steer/set_model/set_thinking/get_available_models) usano i comandi RPC nativi di Pi. Il SQL finale è delegato a `tht sql preview/export` (nessun client DB nel backend). Tutto testabile in CI contro il **fake-pi-rpc** consegnato dal Piano Harness. - -**Tech Stack:** Node ≥ 20, TypeScript (ESM), Fastify 5, vitest (test), tsx (dev run). Pi = `@earendil-works/pi-coding-agent` (`pi --mode rpc`). CLI `tht` (Python, già installato nel venv harness). - -## Global Constraints - -- **Prerequisito:** il Piano Harness (`2026-06-27-harness-rpc-readiness.md`) deve essere completato — il backend dipende da: gate RPC-ready, `THT_SESSION` id injection, `tht sql preview --json/--offset`, `tht session list/show --json`, campi manifest, `fake-pi-rpc`. -- **Framing RPC: LF-only JSONL** — `JSON.stringify(v)+"\n"`; lettura split su `\n`, strip `\r` finale. MAI `readline`. Riferimento: `@earendil-works/pi-coding-agent/dist/modes/rpc/jsonl.js`. -- **WIRE CONTRACT (corretto post-spike, Piano Harness Task 1):** il gate usa l'API UI nativa di Pi. Sul wire arriva `{type:"extension_ui_request", id, method:"input", title:""}`; il backend **decodifica `title` → descriptor**, lo espone al FE come `ui_request`, e risponde `{type:"extension_ui_response", id, value:""}` (o `{id, cancelled:true}`). `ctx.sendRaw` non esiste; non esistono eventi `{ui_request:…}` nidificati. Il contratto verso il FE (`ui_request`/`ui_response`, architettura §4) resta invariato — la traduzione native↔FE è responsabilità del `SessionBridge`. -- **Deployment MVP:** localhost, mono-operatore (D12-B). Auth default `none` (utente `dev@local`). -- **Il backend NON tocca il DB**: ogni esecuzione SQL passa da `tht` (BE-2). Nessun driver `pg`/REST nel backend. -- **Posizione harness:** path configurabile (`THT_HARNESS_DIR`, default `../harness` rispetto al backend); `tht` invocato dal venv harness; spawn di Pi con `cwd = THT_HARNESS_DIR`. -- **Nessun segreto nel codice**: credenziali via `.env`/ambiente, mai committate. -- **Test in CI senza Pi/LLM reali**: si usa `fake-pi-rpc` (Piano Harness, `harness/tests/fake_pi/fake_pi_rpc.mjs`). L2 con Pi reale resta separato e informativo. - ---- - -### Task 1: Scaffold del progetto backend - -**Files:** -- Create: `backend/package.json`, `backend/tsconfig.json`, `backend/vitest.config.ts` -- Create: `backend/src/config.ts`, `backend/src/server.ts`, `backend/src/app.ts` -- Test: `backend/test/health.test.ts` - -**Interfaces:** -- Produces: `buildApp(config: AppConfig): FastifyInstance` (registra le route, non ascolta); `loadConfig(env): AppConfig` con `{ port, harnessDir, thtBin, piBin, authMode, defaults: {provider?, model?, thinking?}, maxPiProcesses }`. - -- [ ] **Step 1: package.json + tsconfig + vitest config** - -```json -// backend/package.json -{ - "name": "thothii-backend", - "private": true, - "type": "module", - "scripts": { - "dev": "tsx watch src/server.ts", - "build": "tsc -p tsconfig.json", - "test": "vitest run", - "start": "node dist/server.js" - }, - "dependencies": { "fastify": "^5.0.0" }, - "devDependencies": { "typescript": "^5.6.0", "tsx": "^4.19.0", "vitest": "^2.1.0", "@types/node": "^22.0.0" } -} -``` -```json -// backend/tsconfig.json -{ "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "Bundler", - "strict": true, "outDir": "dist", "rootDir": "src", "esModuleInterop": true, "skipLibCheck": true }, - "include": ["src"] } -``` -```typescript -// backend/vitest.config.ts -import { defineConfig } from "vitest/config"; -export default defineConfig({ test: { environment: "node", include: ["test/**/*.test.ts"] } }); -``` - -- [ ] **Step 2: Scrivere il test health** - -```typescript -// backend/test/health.test.ts -import { test, expect } from "vitest"; -import { buildApp } from "../src/app.js"; -import { loadConfig } from "../src/config.js"; - -test("GET /health ritorna ok", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "/tmp/h" })); - const res = await app.inject({ method: "GET", url: "/health" }); - expect(res.statusCode).toBe(200); - expect(res.json()).toEqual({ status: "ok" }); -}); -``` - -- [ ] **Step 3: Eseguire (deve fallire)** - -Run: `cd backend && npm install && npm test` -Expected: FAIL — `Cannot find module '../src/app.js'`. - -- [ ] **Step 4: Implementare config + app + server** - -```typescript -// backend/src/config.ts -export interface AppConfig { - port: number; harnessDir: string; thtBin: string; piBin: string; - authMode: "none" | "mock" | "oidc"; - defaults: { provider?: string; model?: string; thinking?: string }; - maxPiProcesses: number; -} -export function loadConfig(env: Record): AppConfig { - return { - port: Number(env.PORT ?? 8787), - harnessDir: env.THT_HARNESS_DIR ?? "../harness", - thtBin: env.THT_BIN ?? "tht", - piBin: env.PI_BIN ?? "pi", - authMode: (env.AUTH_MODE as AppConfig["authMode"]) ?? "none", - defaults: { provider: env.PI_PROVIDER, model: env.PI_MODEL, thinking: env.PI_THINKING }, - maxPiProcesses: Number(env.MAX_PI_PROCESSES ?? 4), - }; -} -``` -```typescript -// backend/src/app.ts -import Fastify, { type FastifyInstance } from "fastify"; -import type { AppConfig } from "./config.js"; -export function buildApp(_config: AppConfig): FastifyInstance { - const app = Fastify({ logger: false }); - app.get("/health", async () => ({ status: "ok" })); - return app; -} -``` -```typescript -// backend/src/server.ts -import { buildApp } from "./app.js"; -import { loadConfig } from "./config.js"; -const config = loadConfig(process.env); -const app = buildApp(config); -app.listen({ port: config.port, host: "127.0.0.1" }) - .then((addr) => console.log(`backend listening on ${addr}`)); -``` - -- [ ] **Step 5: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test` -Expected: PASS. -```bash -git add backend/package.json backend/tsconfig.json backend/vitest.config.ts backend/src backend/test -git commit -m "feat(backend): scaffold Fastify+TS + /health" -``` - ---- - -### Task 2: LineSplitter — lettura JSONL LF-only - -**Files:** -- Create: `backend/src/rpc/line-splitter.ts` -- Test: `backend/test/line-splitter.test.ts` - -**Interfaces:** -- Produces: `attachJsonlReader(stream: Readable, onLine: (line: string) => void): () => void` — split su `\n`, strip `\r` finale, gestione chunk parziali; ritorna funzione di detach. - -- [ ] **Step 1: Scrivere il test** - -```typescript -import { test, expect } from "vitest"; -import { Readable } from "node:stream"; -import { attachJsonlReader } from "../src/rpc/line-splitter.js"; - -test("riassembla righe spezzate tra chunk, split solo su \\n", async () => { - const lines: string[] = []; - const s = new Readable({ read() {} }); - attachJsonlReader(s, (l) => lines.push(l)); - s.push('{"a":1}\n{"b":'); s.push('2}\r\n{"u":"
 in stringa"}\n'); s.push(null); - await new Promise((r) => s.on("end", r)); - expect(lines).toEqual(['{"a":1}', '{"b":2}', '{"u":"
 in stringa"}']); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- line-splitter` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare (port di jsonl.js)** - -```typescript -// backend/src/rpc/line-splitter.ts -import { StringDecoder } from "node:string_decoder"; -import type { Readable } from "node:stream"; -export function attachJsonlReader(stream: Readable, onLine: (line: string) => void): () => void { - const decoder = new StringDecoder("utf8"); - let buffer = ""; - const emit = (line: string) => onLine(line.endsWith("\r") ? line.slice(0, -1) : line); - const onData = (chunk: Buffer | string) => { - buffer += typeof chunk === "string" ? chunk : decoder.write(chunk); - for (let nl; (nl = buffer.indexOf("\n")) !== -1; ) { - emit(buffer.slice(0, nl)); buffer = buffer.slice(nl + 1); - } - }; - const onEnd = () => { buffer += decoder.end(); if (buffer) { emit(buffer); buffer = ""; } }; - stream.on("data", onData); stream.on("end", onEnd); - return () => { stream.off("data", onData); stream.off("end", onEnd); }; -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- line-splitter` -Expected: PASS. -```bash -git add backend/src/rpc/line-splitter.ts backend/test/line-splitter.test.ts -git commit -m "feat(backend): LF-only JSONL line splitter" -``` - ---- - -### Task 3: RpcClient — spawn, invio comandi, correlazione risposte - -**Files:** -- Create: `backend/src/rpc/rpc-client.ts` -- Test: `backend/test/rpc-client.test.ts` - -**Interfaces:** -- Consumes: `attachJsonlReader` (Task 2); `harness/tests/fake_pi/fake_pi_rpc.mjs` (Piano Harness). -- Produces: `class RpcClient`: - - `constructor(child: ChildProcessWithoutNullStreams)` - - `send(cmd: object): void` — scrive `JSON.stringify(cmd)+"\n"` su stdin - - `request(cmd: object & {type:string}): Promise` — invia con `id` generato, risolve sulla `{type:"response"}` correlata - - `on(event: "event", cb: (evt: any) => void)` — emette ogni messaggio NON-response (eventi: `extension_ui_request`, `text_delta`, `agent_end`, …) - - `nextId(): string` - -- [ ] **Step 1: Scrivere il test (contro fake-pi-rpc)** - -```typescript -import { test, expect } from "vitest"; -import { spawn } from "node:child_process"; -import path from "node:path"; -import { RpcClient } from "../src/rpc/rpc-client.js"; - -const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs"); -const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json"); - -test("request(get_available_models) correla la response", async () => { - const child = spawn("node", [FAKE, SCRIPT]); - const rpc = new RpcClient(child as any); - const res = await rpc.request({ type: "get_available_models" }); - expect(res.data.models[0].provider).toBe("zai"); - child.stdin.end(); -}); - -test("prompt emette un evento extension_ui_request", async () => { - const child = spawn("node", [FAKE, SCRIPT]); - const rpc = new RpcClient(child as any); - const got = new Promise((resolve) => rpc.on("event", (e) => e.type === "extension_ui_request" && resolve(e))); - rpc.send({ type: "prompt", message: "/nuova-domanda \"x\"" }); - const evt = await got; - expect(evt.method).toBe("input"); // shape nativa di Pi - expect(JSON.parse(evt.title).widget).toBe("select"); // descriptor nel title - child.stdin.end(); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- rpc-client` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare RpcClient** - -```typescript -// backend/src/rpc/rpc-client.ts -import type { ChildProcessWithoutNullStreams } from "node:child_process"; -import { attachJsonlReader } from "./line-splitter.js"; -type Listener = (evt: any) => void; -export class RpcClient { - private seq = 0; - private pending = new Map void>(); - private listeners = new Set(); - constructor(private child: ChildProcessWithoutNullStreams) { - attachJsonlReader(child.stdout, (line) => { - if (!line) return; - let msg: any; try { msg = JSON.parse(line); } catch { return; } - if (msg.type === "response" && msg.id && this.pending.has(msg.id)) { - this.pending.get(msg.id)!(msg); this.pending.delete(msg.id); return; - } - for (const l of this.listeners) l(msg); - }); - } - nextId(): string { return `c${++this.seq}`; } - send(cmd: object): void { this.child.stdin.write(JSON.stringify(cmd) + "\n"); } - request(cmd: object & { type: string }): Promise { - const id = this.nextId(); - return new Promise((resolve) => { this.pending.set(id, resolve); this.send({ ...cmd, id }); }); - } - on(_event: "event", cb: Listener): void { this.listeners.add(cb); } -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- rpc-client` -Expected: PASS (2 test). -```bash -git add backend/src/rpc/rpc-client.ts backend/test/rpc-client.test.ts -git commit -m "feat(backend): RpcClient (spawn/send/request/event) over JSONL" -``` - ---- - -### Task 4: SessionBridge — traduzione widget-descriptor ↔ RPC + widget pendente - -**Files:** -- Create: `backend/src/bridge/session-bridge.ts` -- Test: `backend/test/session-bridge.test.ts` - -**Interfaces:** -- Consumes: `RpcClient` (Task 3). -- Produces: `class SessionBridge`: - - `constructor(rpc: RpcClient)` - - `onClientEvent(cb: (e: ClientEvent) => void)` — emette verso il FE: `{type:"ui_request"|"info"|"text_delta"|"system_event", ...}` - - `respond(uiResponse: object & {id:string}): void` — invia a Pi `{type:"extension_ui_response", id, value: JSON.stringify(uiResponse)}` (shape NATIVA: il payload va in `value`) - - `steer(text: string): void` — invia `{type:"steer", message: text}` - - `pendingWidget(): object | null` — l'ultimo descriptor non ancora risposto (per re-emit) -- **Decodifica della shape nativa (WIRE CONTRACT):** un evento `{type:"extension_ui_request", id, method:"input", title}` → il bridge fa `JSON.parse(title)` → descriptor, lo espone come `ui_request`; `method:"notify"` → `info`; altri `method` (setStatus/setWidget) ignorati in MVP. -- Tipi: `ClientEvent = {type:"ui_request", ui_request:object} | {type:"text_delta", text:string} | {type:"info",...} | {type:"system_event",...}`. - -- [ ] **Step 1: Scrivere il test** - -```typescript -import { test, expect, vi } from "vitest"; -import { SessionBridge } from "../src/bridge/session-bridge.js"; - -function fakeRpc() { - const sent: any[] = []; let evcb: any; - return { rpc: { send: (c:any)=>sent.push(c), on: (_:any,cb:any)=>{evcb=cb}, request: vi.fn() } as any, - sent, fire: (m:any)=>evcb(m) }; -} - -test("extension_ui_request nativo (method:input, title=json) diventa ui_request ed è il pendente", () => { - const { rpc, fire } = fakeRpc(); - const b = new SessionBridge(rpc); - const seen: any[] = []; b.onClientEvent((e)=>seen.push(e)); - const descriptor = { id:"u1", widget:"select" }; - fire({ type:"extension_ui_request", id:"u1", method:"input", title: JSON.stringify(descriptor) }); - expect(seen[0]).toEqual({ type:"ui_request", ui_request: descriptor }); - expect(b.pendingWidget()).toEqual(descriptor); -}); - -test("respond invia extension_ui_response con payload in value e azzera il pendente", () => { - const { rpc, sent, fire } = fakeRpc(); - const b = new SessionBridge(rpc); - fire({ type:"extension_ui_request", id:"u1", method:"input", title: JSON.stringify({ id:"u1", widget:"select" }) }); - b.respond({ id:"u1", choices:["a"] }); - expect(sent.at(-1)).toEqual({ type:"extension_ui_response", id:"u1", value: JSON.stringify({ id:"u1", choices:["a"] }) }); - expect(b.pendingWidget()).toBeNull(); -}); - -test("steer invia un comando steer", () => { - const { rpc, sent } = fakeRpc(); - new SessionBridge(rpc).steer("considera solo il 2024"); - expect(sent.at(-1)).toEqual({ type:"steer", message:"considera solo il 2024" }); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- session-bridge` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare SessionBridge** - -```typescript -// backend/src/bridge/session-bridge.ts -import type { RpcClient } from "../rpc/rpc-client.js"; -export type ClientEvent = - | { type: "ui_request"; ui_request: any } - | { type: "text_delta"; text: string } - | { type: "info"; [k: string]: any } - | { type: "system_event"; [k: string]: any }; - -export class SessionBridge { - private pending: any = null; - private cbs = new Set<(e: ClientEvent) => void>(); - constructor(private rpc: RpcClient) { - rpc.on("event", (m) => { - if (m.type === "extension_ui_request" && m.method === "input") { - let descriptor: any; try { descriptor = JSON.parse(m.title); } catch { return; } - this.pending = descriptor; - this.fan({ type: "ui_request", ui_request: descriptor }); - } else if (m.type === "extension_ui_request" && m.method === "notify") { - this.fan({ type: "info", level: m.notifyType ?? "info", text: m.message ?? "" }); - } else if (m.type === "text_delta") { - this.fan({ type: "text_delta", text: m.text ?? "" }); - } else if (m.type === "system_event") { - this.fan(m as ClientEvent); - } - // altri method nativi (setStatus/setWidget) e altri eventi Pi (agent_end, tool_call) non inoltrati in MVP - }); - } - private fan(e: ClientEvent) { for (const cb of this.cbs) cb(e); } - onClientEvent(cb: (e: ClientEvent) => void) { this.cbs.add(cb); } - respond(uiResponse: object & { id: string }) { - this.rpc.send({ type: "extension_ui_response", id: uiResponse.id, value: JSON.stringify(uiResponse) }); - if (this.pending && uiResponse.id === this.pending.id) this.pending = null; - } - steer(text: string) { this.rpc.send({ type: "steer", message: text }); } - pendingWidget() { return this.pending; } -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- session-bridge` -Expected: PASS (3 test). -```bash -git add backend/src/bridge/session-bridge.ts backend/test/session-bridge.test.ts -git commit -m "feat(backend): SessionBridge widget-descriptor <-> RPC + pending widget" -``` - ---- - -### Task 5: ThtRunner — wrapper dei comandi `tht … --json` - -**Files:** -- Create: `backend/src/tht/tht-runner.ts` -- Test: `backend/test/tht-runner.test.ts` - -**Interfaces:** -- Produces: `class ThtRunner` (config: `{thtBin, harnessDir, configPath}`): - - `sessionNew(opts): Promise<{id:string}>` → `tht session new [--provider…] --json` - - `sessionList(): Promise` → `tht session list --json` - - `sessionShow(id): Promise` → `tht session show --json` - - `sqlPreview(id, {limit, offset}): Promise<{columns,rows,execution_ms,truncated}>` - - `sqlExport(id): Promise<{path:string}>` - - `run(args: string[]): Promise<{code:number, stdout:string, stderr:string}>` (primitiva, iniettabile per test) - -- [ ] **Step 1: Scrivere il test (run iniettabile)** - -```typescript -import { test, expect } from "vitest"; -import { ThtRunner } from "../src/tht/tht-runner.js"; - -test("sessionNew parsa l'id dal JSON", async () => { - const r = new ThtRunner({ thtBin: "tht", harnessDir: "/h", configPath: "config/tht.yaml" }); - r.run = async () => ({ code: 0, stdout: '{"id":"2026-06-27-100000-x"}', stderr: "" }); - expect(await r.sessionNew({ question: "q" })).toEqual({ id: "2026-06-27-100000-x" }); -}); - -test("run con exit != 0 propaga errore con stderr", async () => { - const r = new ThtRunner({ thtBin: "tht", harnessDir: "/h", configPath: "config/tht.yaml" }); - r.run = async () => ({ code: 1, stdout: "", stderr: "ERRORE: boom" }); - await expect(r.sessionList()).rejects.toThrow(/boom/); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- tht-runner` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare ThtRunner** - -```typescript -// backend/src/tht/tht-runner.ts -import { spawn } from "node:child_process"; -export interface ThtConfig { thtBin: string; harnessDir: string; configPath: string; } -export interface SessionRow { id: string; status: string; question: string; summary: string | null; - created_at: string; updated_at: string | null; author: string | null; } -export class ThtRunner { - constructor(private cfg: ThtConfig) {} - run(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> { - return new Promise((resolve) => { - const ch = spawn(this.cfg.thtBin, ["-c", this.cfg.configPath, ...args], { cwd: this.cfg.harnessDir }); - let stdout = "", stderr = ""; - ch.stdout.on("data", (d) => (stdout += d)); ch.stderr.on("data", (d) => (stderr += d)); - ch.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr })); - }); - } - private async json(args: string[]): Promise { - const { code, stdout, stderr } = await this.run(args); - if (code !== 0) throw new Error(`tht ${args.join(" ")} exit ${code}: ${stderr.trim()}`); - return JSON.parse(stdout) as T; - } - async sessionNew(o: { question: string; provider?: string; model?: string; thinking?: string; name?: string }) { - const a = ["session", "new", o.question]; - for (const [f, v] of [["--provider", o.provider], ["--model", o.model], ["--thinking", o.thinking], ["--name", o.name]] as const) - if (v) a.push(f, v); - a.push("--json"); - return this.json<{ id: string }>(a); - } - sessionList() { return this.json(["session", "list", "--json"]); } - sessionShow(id: string) { return this.json(["session", "show", id, "--json"]); } - sqlPreview(id: string, p: { limit?: number; offset?: number }) { - const a = ["sql", "preview", `sessions/${id}/sql_final.sql`, "--session", id, "--json"]; - if (p.limit != null) a.push("--limit", String(p.limit)); - if (p.offset) a.push("--offset", String(p.offset)); - return this.json<{ columns: string[]; rows: unknown[][]; execution_ms: number; truncated: boolean }>(a); - } - async sqlExport(id: string) { - const { code, stdout, stderr } = await this.run(["sql", "export", "--session", id]); - if (code !== 0) throw new Error(`tht sql export exit ${code}: ${stderr.trim()}`); - return { path: stdout.trim() }; - } -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- tht-runner` -Expected: PASS (2 test). -```bash -git add backend/src/tht/tht-runner.ts backend/test/tht-runner.test.ts -git commit -m "feat(backend): ThtRunner wrapper for tht --json (sessions, sql preview/export)" -``` - ---- - -### Task 6: PiProcessManager — un Pi per sessione, spawn/teardown/resume + settings - -**Files:** -- Create: `backend/src/pi/pi-process-manager.ts` -- Test: `backend/test/pi-process-manager.test.ts` - -**Interfaces:** -- Consumes: `RpcClient` (Task 3), `SessionBridge` (Task 4), `AppConfig` (Task 1). -- Produces: `class PiProcessManager`: - - `spawnFor(sessionId: string, opts: {provider?, model?, thinking?, name?, author?}): Promise` — spawn `pi --mode rpc` con `cwd=harnessDir`, env `{...process.env, THT_SESSION: sessionId, THT_AUTHOR: author, PATH: :PATH}`, `--approve`; dopo lo spawn applica `set_model`/`set_thinking_level` via RPC; manda `prompt "/nuova-domanda …"` per avviare il workflow. - - `get(sessionId): SessionRuntime | undefined` - - `teardown(sessionId): void` - - `count(): number` — rispetta `maxPiProcesses` (errore esplicito oltre il cap) -- `SessionRuntime = { rpc: RpcClient; bridge: SessionBridge; child: ChildProcess }` -- Iniettabile: `spawnFn` (default `spawn`) per test senza Pi reale. - -- [ ] **Step 1: Scrivere il test (spawnFn iniettato = fake-pi-rpc)** - -```typescript -import { test, expect } from "vitest"; -import { spawn } from "node:child_process"; -import path from "node:path"; -import { PiProcessManager } from "../src/pi/pi-process-manager.js"; -import { loadConfig } from "../src/config.js"; - -const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs"); -const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json"); - -test("spawnFor avvia un runtime e il bridge emette il widget F1", async () => { - const cfg = loadConfig({ THT_HARNESS_DIR: "../harness" }); - const mgr = new PiProcessManager(cfg, { spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any }); - const rt = await mgr.spawnFor("2026-06-27-100000-x", {}); - const widget = await new Promise((res) => rt.bridge.onClientEvent((e) => e.type === "ui_request" && res(e))); - expect(widget.ui_request.widget).toBe("select"); - mgr.teardown("2026-06-27-100000-x"); - expect(mgr.count()).toBe(0); -}); - -test("oltre maxPiProcesses solleva errore", async () => { - const cfg = { ...loadConfig({}), maxPiProcesses: 1 }; - const mgr = new PiProcessManager(cfg, { spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any }); - await mgr.spawnFor("a", {}); - await expect(mgr.spawnFor("b", {})).rejects.toThrow(/max/i); - mgr.teardown("a"); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- pi-process-manager` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare PiProcessManager** - -```typescript -// backend/src/pi/pi-process-manager.ts -import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams } from "node:child_process"; -import type { AppConfig } from "../config.js"; -import { RpcClient } from "../rpc/rpc-client.js"; -import { SessionBridge } from "../bridge/session-bridge.js"; - -export interface SessionRuntime { rpc: RpcClient; bridge: SessionBridge; child: ChildProcessWithoutNullStreams; } -type SpawnFn = (cfg: AppConfig, sessionId: string, env: NodeJS.ProcessEnv) => ChildProcessWithoutNullStreams; - -export class PiProcessManager { - private runtimes = new Map(); - private spawnFn: SpawnFn; - constructor(private cfg: AppConfig, opts?: { spawnFn?: (...a: any[]) => ChildProcessWithoutNullStreams }) { - this.spawnFn = opts?.spawnFn - ? () => opts.spawnFn!() - : (cfg, sessionId, env) => nodeSpawn(cfg.piBin, ["--mode", "rpc", "--approve"], { cwd: cfg.harnessDir, env }); - } - count() { return this.runtimes.size; } - get(id: string) { return this.runtimes.get(id); } - async spawnFor(sessionId: string, o: { provider?: string; model?: string; thinking?: string; author?: string }) { - if (this.runtimes.size >= this.cfg.maxPiProcesses) throw new Error("max Pi processes reached"); - const env = { ...process.env, THT_SESSION: sessionId, THT_AUTHOR: o.author ?? "dev@local" }; - const child = this.spawnFn(this.cfg, sessionId, env); - const rpc = new RpcClient(child); const bridge = new SessionBridge(rpc); - const rt: SessionRuntime = { rpc, bridge, child }; - this.runtimes.set(sessionId, rt); - child.on("exit", () => this.runtimes.delete(sessionId)); - const provider = o.provider ?? this.cfg.defaults.provider; - const model = o.model ?? this.cfg.defaults.model; - const thinking = o.thinking ?? this.cfg.defaults.thinking; - if (provider && model) await rpc.request({ type: "set_model", provider, modelId: model }); - if (thinking) await rpc.request({ type: "set_thinking_level", level: thinking }); - rpc.send({ type: "prompt", message: `/nuova-domanda "kickoff"` }); - return rt; - } - teardown(id: string) { const rt = this.runtimes.get(id); if (rt) { rt.child.kill(); this.runtimes.delete(id); } } -} -``` - -> Nota PATH (rischio L2 #1): in produzione `env.PATH` deve includere `harness/.venv/bin` perché Pi spawni `tht`. Aggiungere alla composizione `env`: `PATH: \`${harnessVenvBin}:${process.env.PATH}\``. Coperto in Task 11 (wiring reale). - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- pi-process-manager` -Expected: PASS (2 test). -```bash -git add backend/src/pi/pi-process-manager.ts backend/test/pi-process-manager.test.ts -git commit -m "feat(backend): PiProcessManager (one Pi per session, cap, set_model/thinking)" -``` - ---- - -### Task 7: SSE hub + re-emit del widget pendente - -**Files:** -- Create: `backend/src/sse/sse-hub.ts` -- Test: `backend/test/sse-hub.test.ts` - -**Interfaces:** -- Produces: `class SseHub`: - - `subscribe(sessionId, send: (event: string, data: object) => void, pending?: object | null): () => void` — alla sottoscrizione, se `pending` è presente, invia subito `send("ui_request", {ui_request: pending})`; ritorna unsubscribe. - - `publish(sessionId, event: string, data: object): void` — a tutti i subscriber della sessione. - -- [ ] **Step 1: Scrivere il test** - -```typescript -import { test, expect } from "vitest"; -import { SseHub } from "../src/sse/sse-hub.js"; - -test("re-emette il widget pendente alla sottoscrizione", () => { - const hub = new SseHub(); const sent: any[] = []; - hub.subscribe("s1", (ev, data) => sent.push({ ev, data }), { id: "u1", widget: "select" }); - expect(sent[0]).toEqual({ ev: "ui_request", data: { ui_request: { id: "u1", widget: "select" } } }); -}); - -test("publish raggiunge i subscriber e unsubscribe li stacca", () => { - const hub = new SseHub(); const sent: any[] = []; - const off = hub.subscribe("s1", (ev, data) => sent.push({ ev, data })); - hub.publish("s1", "text_delta", { text: "x" }); - off(); hub.publish("s1", "text_delta", { text: "y" }); - expect(sent).toEqual([{ ev: "text_delta", data: { text: "x" } }]); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- sse-hub` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare SseHub** - -```typescript -// backend/src/sse/sse-hub.ts -type Send = (event: string, data: object) => void; -export class SseHub { - private subs = new Map>(); - subscribe(sessionId: string, send: Send, pending?: object | null): () => void { - if (!this.subs.has(sessionId)) this.subs.set(sessionId, new Set()); - this.subs.get(sessionId)!.add(send); - if (pending) send("ui_request", { ui_request: pending }); - return () => this.subs.get(sessionId)?.delete(send); - } - publish(sessionId: string, event: string, data: object): void { - for (const s of this.subs.get(sessionId) ?? []) s(event, data); - } -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- sse-hub` -Expected: PASS (2 test). -```bash -git add backend/src/sse/sse-hub.ts backend/test/sse-hub.test.ts -git commit -m "feat(backend): SSE hub with pending-widget re-emit on (re)subscribe" -``` - ---- - -### Task 8: Auth middleware pluggabile (none/mock/oidc) - -**Files:** -- Create: `backend/src/auth/auth.ts` -- Test: `backend/test/auth.test.ts` - -**Interfaces:** -- Produces: `authPreHandler(mode)`→ Fastify preHandler che imposta `req.user = {id}`: `none`→`dev@local`; `mock`→header `x-mock-user`; `oidc`→verifica bearer (stub MVP: `501` se non configurato). `getUser(req): {id:string}`. - -- [ ] **Step 1: Scrivere il test** - -```typescript -import { test, expect } from "vitest"; -import Fastify from "fastify"; -import { authPreHandler, getUser } from "../src/auth/auth.js"; - -test("mode none assegna dev@local", async () => { - const app = Fastify(); app.addHook("preHandler", authPreHandler("none")); - app.get("/me", async (req) => getUser(req)); - expect((await app.inject({ method: "GET", url: "/me" })).json()).toEqual({ id: "dev@local" }); -}); - -test("mode mock legge l'header", async () => { - const app = Fastify(); app.addHook("preHandler", authPreHandler("mock")); - app.get("/me", async (req) => getUser(req)); - const res = await app.inject({ method: "GET", url: "/me", headers: { "x-mock-user": "alice" } }); - expect(res.json()).toEqual({ id: "alice" }); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- auth` -Expected: FAIL — modulo assente. - -- [ ] **Step 3: Implementare auth** - -```typescript -// backend/src/auth/auth.ts -import type { FastifyRequest, FastifyReply } from "fastify"; -export function authPreHandler(mode: "none" | "mock" | "oidc") { - return async (req: FastifyRequest, reply: FastifyReply) => { - if (mode === "none") (req as any).user = { id: "dev@local" }; - else if (mode === "mock") (req as any).user = { id: (req.headers["x-mock-user"] as string) ?? "mock" }; - else { reply.code(501); throw new Error("OIDC non configurato (MVP: usa none/mock)"); } - }; -} -export function getUser(req: FastifyRequest): { id: string } { return (req as any).user ?? { id: "dev@local" }; } -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- auth` -Expected: PASS (2 test). -```bash -git add backend/src/auth/auth.ts backend/test/auth.test.ts -git commit -m "feat(backend): pluggable auth (none/mock/oidc seam)" -``` - ---- - -### Task 9: Route sessioni + SSE + response/steer (wiring) - -**Files:** -- Modify: `backend/src/app.ts` (registra le route, costruisce i singleton) -- Create: `backend/src/routes/sessions.ts` -- Test: `backend/test/routes-sessions.test.ts` - -**Interfaces:** -- Consumes: `PiProcessManager` (6), `ThtRunner` (5), `SseHub` (7), `auth` (8). -- Produces (route, tutte sotto `authPreHandler`): - - `POST /sessions {workspace, question, provider?, model?, thinking?, name?}` → `tht session new` (con author dall'auth) → `mgr.spawnFor(id)` → `{id}` - - `GET /sessions` → `tht session list --json` - - `GET /sessions/:id` → `tht session show --json` - - `GET /sessions/:id/events` → SSE; sottoscrive `SseHub` con `bridge.pendingWidget()`; collega `bridge.onClientEvent` → `hub.publish` - - `POST /sessions/:id/response {ui_response}` → `bridge.respond` - - `POST /sessions/:id/steer {text}` → `bridge.steer` - - `POST /sessions/:id/close` → `mgr.teardown` - -- [ ] **Step 1: Scrivere il test (inietta ThtRunner + spawnFn fake)** - -```typescript -import { test, expect } from "vitest"; -import { spawn } from "node:child_process"; -import path from "node:path"; -import { buildApp } from "../src/app.js"; -import { loadConfig } from "../src/config.js"; - -const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs"); -const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json"); - -test("POST /sessions crea e avvia, GET /sessions lista", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { - thtRunner: { sessionNew: async () => ({ id: "s1" }), sessionList: async () => [{ id: "s1" }] } as any, - spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any, - }); - const created = await app.inject({ method: "POST", url: "/sessions", payload: { workspace: "w", question: "q" } }); - expect(created.json()).toEqual({ id: "s1" }); - const list = await app.inject({ method: "GET", url: "/sessions" }); - expect(list.json()).toEqual([{ id: "s1" }]); -}); - -test("POST /sessions/:id/response inoltra al bridge (no error)", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { - thtRunner: { sessionNew: async () => ({ id: "s1" }) } as any, - spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any, - }); - await app.inject({ method: "POST", url: "/sessions", payload: { workspace: "w", question: "q" } }); - const res = await app.inject({ method: "POST", url: "/sessions/s1/response", - payload: { ui_response: { id: "u1", choices: ["a"] } } }); - expect(res.statusCode).toBe(204); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- routes-sessions` -Expected: FAIL — `buildApp` non accetta deps / route assenti. - -- [ ] **Step 3: Rendere buildApp iniettabile e registrare le route** - -In `app.ts` accettare `deps?: { thtRunner?, spawnFn? }`, costruire `ThtRunner`/`PiProcessManager`/`SseHub`, applicare `authPreHandler(config.authMode)`, e registrare `sessionRoutes`. - -```typescript -// backend/src/routes/sessions.ts (estratto load-bearing) -import type { FastifyInstance } from "fastify"; -import type { PiProcessManager } from "../pi/pi-process-manager.js"; -import type { ThtRunner } from "../tht/tht-runner.js"; -import type { SseHub } from "../sse/sse-hub.js"; -import { getUser } from "../auth/auth.js"; - -export function sessionRoutes(app: FastifyInstance, d: { mgr: PiProcessManager; tht: ThtRunner; hub: SseHub }) { - app.post("/sessions", async (req, reply) => { - const b = req.body as any; - const { id } = await d.tht.sessionNew({ question: b.question, provider: b.provider, model: b.model, thinking: b.thinking, name: b.name }); - const rt = await d.mgr.spawnFor(id, { provider: b.provider, model: b.model, thinking: b.thinking, author: getUser(req).id }); - rt.bridge.onClientEvent((e) => d.hub.publish(id, e.type, e)); - return { id }; - }); - app.get("/sessions", async () => d.tht.sessionList()); - app.get("/sessions/:id", async (req) => d.tht.sessionShow((req.params as any).id)); - app.post("/sessions/:id/response", async (req, reply) => { - const id = (req.params as any).id; const rt = d.mgr.get(id); - if (!rt) return reply.code(404).send({ error: "sessione non attiva" }); - rt.bridge.respond((req.body as any).ui_response); return reply.code(204).send(); - }); - app.post("/sessions/:id/steer", async (req, reply) => { - const rt = d.mgr.get((req.params as any).id); - if (!rt) return reply.code(404).send({ error: "sessione non attiva" }); - rt.bridge.steer((req.body as any).text); return reply.code(204).send(); - }); - app.post("/sessions/:id/close", async (req) => { d.mgr.teardown((req.params as any).id); return { closed: true }; }); - app.get("/sessions/:id/events", (req, reply) => { - const id = (req.params as any).id; const rt = d.mgr.get(id); - reply.raw.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" }); - const send = (event: string, data: object) => reply.raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); - const off = d.hub.subscribe(id, send, rt?.bridge.pendingWidget() ?? null); - req.raw.on("close", off); - }); -} -``` - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- routes-sessions` -Expected: PASS (2 test). -```bash -git add backend/src/app.ts backend/src/routes/sessions.ts backend/test/routes-sessions.test.ts -git commit -m "feat(backend): session routes + SSE + response/steer wiring" -``` - ---- - -### Task 10: Route SQL (preview/export) + models + workspaces - -**Files:** -- Create: `backend/src/routes/sql.ts`, `backend/src/routes/meta.ts` -- Modify: `backend/src/app.ts` (registra) -- Test: `backend/test/routes-sql-meta.test.ts` - -**Interfaces:** -- Produces: - - `POST /sessions/:id/sql/preview {limit?, offset?}` → `tht.sqlPreview` → `{columns, rows, execution_ms, truncated}` - - `POST /sessions/:id/sql/export` → `tht.sqlExport` → `{path}` - - `GET /models` → `rpc.request({type:"get_available_models"})` da un Pi effimero, OR set statico dai default se nessun Pi attivo (MVP: legge da un processo Pi effimero via `mgr`); ritorna `{models:[...]}` - - `GET /workspaces` → lista da `harnessDir/workspaces/*.yaml` (solo nomi + path, no secret) - -- [ ] **Step 1: Scrivere il test** - -```typescript -import { test, expect } from "vitest"; -import { buildApp } from "../src/app.js"; -import { loadConfig } from "../src/config.js"; - -test("POST sql/preview ritorna le righe da ThtRunner", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { - thtRunner: { sqlPreview: async () => ({ columns: ["a"], rows: [[1]], execution_ms: 2, truncated: false }) } as any, - }); - const res = await app.inject({ method: "POST", url: "/sessions/s1/sql/preview", payload: { limit: 10, offset: 0 } }); - expect(res.json()).toEqual({ columns: ["a"], rows: [[1]], execution_ms: 2, truncated: false }); -}); - -test("GET /workspaces elenca gli yaml senza secret", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { thtRunner: {} as any }); - const res = await app.inject({ method: "GET", url: "/workspaces" }); - expect(res.statusCode).toBe(200); - expect(Array.isArray(res.json())).toBe(true); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- routes-sql-meta` -Expected: FAIL — route assenti. - -- [ ] **Step 3: Implementare le route** - -```typescript -// backend/src/routes/sql.ts -import type { FastifyInstance } from "fastify"; -import type { ThtRunner } from "../tht/tht-runner.js"; -export function sqlRoutes(app: FastifyInstance, d: { tht: ThtRunner }) { - app.post("/sessions/:id/sql/preview", async (req) => { - const b = (req.body ?? {}) as any; - return d.tht.sqlPreview((req.params as any).id, { limit: b.limit, offset: b.offset }); - }); - app.post("/sessions/:id/sql/export", async (req) => d.tht.sqlExport((req.params as any).id)); -} -``` -```typescript -// backend/src/routes/meta.ts -import type { FastifyInstance } from "fastify"; -import { readdirSync } from "node:fs"; -import { join } from "node:path"; -export function metaRoutes(app: FastifyInstance, d: { harnessDir: string; listModels: () => Promise }) { - app.get("/workspaces", async () => { - const dir = join(d.harnessDir, "workspaces"); - return readdirSync(dir).filter((f) => f.endsWith(".yaml")) - .map((f) => ({ name: f.replace(/\.ya?ml$/, ""), file: f })); - }); - app.get("/models", async () => d.listModels()); -} -``` -In `app.ts`, `listModels` fa spawn di un Pi effimero, `rpc.request({type:"get_available_models"})`, poi teardown; in caso di errore ritorna `{ models: [] }`. - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test -- routes-sql-meta` -Expected: PASS (2 test). -```bash -git add backend/src/routes/sql.ts backend/src/routes/meta.ts backend/src/app.ts backend/test/routes-sql-meta.test.ts -git commit -m "feat(backend): sql preview/export + models + workspaces routes" -``` - ---- - -### Task 11: Resume + PATH venv + smoke end-to-end F1 (fake-pi-rpc) - -**Files:** -- Modify: `backend/src/pi/pi-process-manager.ts` (env PATH venv; `resume(sessionId)` legge il manifest via ThtRunner) -- Modify: `backend/src/routes/sessions.ts` (`POST /sessions/:id/resume`) -- Test: `backend/test/e2e-f1.test.ts` - -**Interfaces:** -- Produces: `mgr.resume(sessionId, tht)` — rilegge `provider/model/thinking` da `tht.sessionShow` e fa `spawnFor` con quei valori; PATH dello spawn reale include `harnessDir/.venv/bin`. - -- [ ] **Step 1: Scrivere lo smoke end-to-end** - -```typescript -import { test, expect } from "vitest"; -import { spawn } from "node:child_process"; -import path from "node:path"; -import { buildApp } from "../src/app.js"; -import { loadConfig } from "../src/config.js"; - -const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs"); -const SCRIPT = path.resolve("../harness/tests/fake_pi/scripts/f1_disambiguation.json"); - -test("loop F1: crea sessione → SSE riceve il widget → risponde → 204", async () => { - const app = buildApp(loadConfig({ THT_HARNESS_DIR: "../harness" }), { - thtRunner: { sessionNew: async () => ({ id: "s1" }) } as any, - spawnFn: () => spawn("node", [FAKE, SCRIPT]) as any, - }); - await app.listen({ port: 0, host: "127.0.0.1" }); - const base = `http://127.0.0.1:${(app.server.address() as any).port}`; - await fetch(`${base}/sessions`, { method: "POST", headers: { "content-type": "application/json" }, - body: JSON.stringify({ workspace: "w", question: "q" }) }); - // SSE: leggi il primo evento ui_request - const es = await fetch(`${base}/sessions/s1/events`); - const reader = es.body!.getReader(); const chunk = await reader.read(); - const text = new TextDecoder().decode(chunk.value); - expect(text).toContain("ui_request"); - await reader.cancel(); - const resp = await fetch(`${base}/sessions/s1/response`, { method: "POST", - headers: { "content-type": "application/json" }, - body: JSON.stringify({ ui_response: { id: "u1", choices: ["a"] } }) }); - expect(resp.status).toBe(204); - await app.close(); -}); -``` - -- [ ] **Step 2: Eseguire (deve fallire)** - -Run: `cd backend && npm test -- e2e-f1` -Expected: FAIL inizialmente (race sull'ordine widget/SSE o resume assente). Diagnosticare con systematic-debugging se necessario. - -- [ ] **Step 3: Implementare resume + PATH venv + fix ordine eventi** - -- In `pi-process-manager.ts` (spawn reale): `PATH: \`${join(cfg.harnessDir, ".venv/bin")}:${process.env.PATH}\``. -- Aggiungere `async resume(id, tht)` che legge `sessionShow(id)` → `{provider, model, thinking}` e chiama `spawnFor`. -- Garantire che la route `POST /sessions` colleghi `bridge.onClientEvent → hub.publish` PRIMA di mandare il `prompt`, così l'evento widget non si perde; il `pendingWidget()` + re-emit (Task 7) copre comunque il caso SSE sottoscritto dopo. -- Aggiungere `POST /sessions/:id/resume` → `mgr.resume(id, tht)` + ricollegamento bridge→hub. - -- [ ] **Step 4: Eseguire (deve passare) + commit** - -Run: `cd backend && npm test` -Expected: PASS (tutta la suite). -```bash -git add backend/src/pi/pi-process-manager.ts backend/src/routes/sessions.ts backend/test/e2e-f1.test.ts -git commit -m "feat(backend): resume + venv PATH + end-to-end F1 smoke (fake-pi-rpc)" -``` - -- [ ] **Step 5: Validazione L2 con Pi reale (informativo, non-CI)** - -Con harness configurato (`.env` + VPN) e `config/tht.yaml` valido: avviare `npm run dev`, fare `POST /sessions` con una domanda reale, aprire l'SSE e confermare che il widget F1 arriva dal Pi reale e che la risposta avanza il workflow. Annotare l'esito (questo è il primo loop end-to-end reale BE↔harness). - ---- - -## Self-Review - -**Spec coverage** (vs `2026-06-27-backend-design.md`): -- BE-1 (un Pi per sessione, resume): Task 6 + Task 11 ✓ -- BE-2 (delega SQL): Task 5 (ThtRunner) + Task 10 (route) ✓ -- BE-3 (re-emit widget pendente): Task 7 + Task 4 (`pendingWidget`) ✓ -- BE-4 (test fake-Pi + unit TS): tutti i task usano vitest; fake-pi-rpc in Task 3/6/9/11 ✓ -- BE-5 (id pre-creato): Task 9 (`tht session new` poi `spawnFor` con `THT_SESSION`) ✓ (dipende dal Piano Harness Task 5) -- BE-6 (model/thinking/provider per-sessione, persistiti, resume): Task 6 (`set_model`/`set_thinking`) + Task 11 (resume legge manifest) ✓ -- BE-7 (settings Pi MVP): `--name`/provider/model/thinking via `sessionNew` (Task 5) + `GET /models` (Task 10); `--approve` nello spawn (Task 6); `quietStartup`/`trust`/`systemPrompt` sono harness-side (Piano Harness Task 9) ✓ -- API §4 (tutti gli endpoint): Task 9 (sessions/events/response/steer/close) + Task 10 (sql/models/workspaces) + Task 1 (health) ✓ -- Auth D6: Task 8 ✓ -- Componenti §5 (PiProcessManager, RpcClient, SessionBridge, SseHub, ThtRunner, auth, config): Task 1–9 ✓ -- Rischio PATH `tht` (§9): Task 6 (nota) + Task 11 (fix) ✓ - -**Placeholder scan:** nessun TBD. Le note implementative (PATH venv, `listModels` effimero) sono concretizzate nel task che le richiede (11, 10). - -**Type consistency:** `ThtRunner.sqlPreview` ritorna `{columns, rows, execution_ms, truncated}` usato identico in Task 10. `SessionRuntime = {rpc, bridge, child}` coerente tra Task 6 e Task 9. `SessionBridge.respond(uiResponse)`/`steer(text)`/`pendingWidget()` coerenti tra Task 4, 7, 9. Comandi RPC (`set_model {provider, modelId}`, `set_thinking_level {level}`, `steer {message}`, `prompt {message}`, `get_available_models`) coerenti con `rpc-types.d.ts` di Pi. Envelope `{type:"extension_ui_request", ui_request}` coerente con il gate (Piano Harness Task 4) e il fake-pi-rpc (Piano Harness Task 10). - -**Nota di sequenza:** Task 1–8 sono indipendenti dal Pi reale (CI puro con fake-pi-rpc). Le validazioni L2 (Task 11 Step 5) richiedono harness configurato + VPN. diff --git a/docs/superpowers/plans/2026-06-27-frontend-implementation.md b/docs/superpowers/plans/2026-06-27-frontend-implementation.md deleted file mode 100644 index 8fc9bcc9..00000000 --- a/docs/superpowers/plans/2026-06-27-frontend-implementation.md +++ /dev/null @@ -1,860 +0,0 @@ -# Frontend Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Costruire il frontend ThothII: una SPA Vite+React+TS che presenta il workflow NL→SQL human-in-the-loop renderizzando i widget-descriptor via SSE e raccogliendo le decisioni del revisore via REST, consumando solo il contratto già implementato del backend. - -**Architecture:** SPA client-only su localhost. TanStack Query per le REST cacheable, uno store Zustand per lo stato live della sessione, un hook `useSessionStream` che apre l'SSE (`EventSource`) e alimenta lo store. Un widget registry mappa `kind`→renderer con fallback universale. I viewer (schema-linking Mermaid, SQL via shiki, risultati AGGrid) vivono nella sidebar destra del layout a 4 zone. Build a slice verticali con il loop F1 chiuso il prima possibile. - -**Tech Stack:** Vite 6, React 18, TypeScript 5.6, @tanstack/react-query 5, zustand 5, Tailwind 3.4 + ShadCn, ag-grid-react/community 32, shiki 1, mermaid 11; test: Vitest 2 + @testing-library/react 16 + jsdom + MSW 2; e2e: @playwright/test 1. - -## Global Constraints - -- **Client-only SPA** (FE-1): niente SSR/route server. Tutto gira nel browser su localhost e consuma il backend Fastify separato. -- **Base URL backend:** da `import.meta.env.VITE_BACKEND_URL`, default `http://localhost:8787`. Mai hard-coded altrove. -- **Contratto FE↔BE invariato.** SSE eventi: `{type:"ui_request",ui_request}` | `{type:"text_delta",text}` | `{type:"info",level?,text}` | `{type:"system_event",event,...}`. REST: `GET /workspaces|/models|/sessions|/sessions/:id`; `POST /sessions|/sessions/:id/response|/steer|/sql/preview|/sql/export|/close|/resume`. Widget kind: `info|select|multiselect|freetext|artifact-gate|artifact` + fallback. -- **SSE via `EventSource` nativo** (FE-3): GET, nessun header (auth=`none` MVP). Non introdurre SSE su fetch in questo MVP. -- **TDD** (FE-5): ogni task scrive prima il test (Vitest+RTL); MSW mocka le REST, un mock di `EventSource` simula l'SSE. Nessun test tocca il backend reale tranne il Playwright e2e (Task finale). -- **Widget isolati** (FE-4): ogni renderer è un file con props `{descriptor, onRespond}`; aggiungere un widget = registrarlo, senza toccare store/stream/registry. -- **Invariante no-limbo:** nessun widget può "chiudere senza rispondere"; Esc/cancel non è una risposta valida. -- **TypeScript strict**; tutti i tipi del contratto vivono in `src/api/types.ts` (unica fonte). Niente `any` se non al confine del fallback. -- **Working dir:** tutti i comandi da `/Users/mp/projects/ThothII/frontend`. Il backend (per l'e2e) è in `../backend`, il fake-pi-rpc in `../harness/tests/fake_pi/`. - ---- - -### Task 1: Scaffold Vite + React + TS + Tailwind/ShadCn + Vitest - -**Files:** -- Create: `frontend/package.json`, `frontend/vite.config.ts`, `frontend/tsconfig.json`, `frontend/vitest.config.ts`, `frontend/index.html`, `frontend/tailwind.config.ts`, `frontend/postcss.config.js`, `frontend/src/main.tsx`, `frontend/src/App.tsx`, `frontend/src/index.css`, `frontend/src/test/setup.ts` -- Test: `frontend/src/App.test.tsx` - -**Interfaces:** -- Produces: un'app montabile; `App` componente root; `npm test` esegue Vitest (jsdom); `npm run dev` serve la SPA; `npm run build` (tsc + vite build) pulito. - -- [ ] **Step 1: package.json + config** - -```json -// frontend/package.json -{ - "name": "thothii-frontend", - "private": true, - "type": "module", - "scripts": { - "dev": "vite", - "build": "tsc -b && vite build", - "preview": "vite preview", - "test": "vitest run", - "test:watch": "vitest", - "e2e": "playwright test" - }, - "dependencies": { - "react": "^18.3.1", "react-dom": "^18.3.1", - "@tanstack/react-query": "^5.59.0", "zustand": "^5.0.0" - }, - "devDependencies": { - "vite": "^6.0.0", "@vitejs/plugin-react": "^4.3.0", "typescript": "^5.6.0", - "vitest": "^2.1.0", "jsdom": "^25.0.0", - "@testing-library/react": "^16.0.0", "@testing-library/jest-dom": "^6.5.0", "@testing-library/user-event": "^14.5.0", - "msw": "^2.4.0", - "tailwindcss": "^3.4.0", "postcss": "^8.4.0", "autoprefixer": "^10.4.0", - "@types/react": "^18.3.0", "@types/react-dom": "^18.3.0" - } -} -``` -```ts -// frontend/vite.config.ts -import { defineConfig } from "vite"; -import react from "@vitejs/plugin-react"; -export default defineConfig({ plugins: [react()] }); -``` -```ts -// frontend/vitest.config.ts -import { defineConfig } from "vitest/config"; -import react from "@vitejs/plugin-react"; -export default defineConfig({ - plugins: [react()], - test: { environment: "jsdom", globals: true, setupFiles: ["./src/test/setup.ts"], include: ["src/**/*.test.{ts,tsx}"] }, -}); -``` -```json -// frontend/tsconfig.json -{ "compilerOptions": { "target": "ES2022", "useDefineForClassFields": true, "lib": ["ES2022","DOM","DOM.Iterable"], - "module": "ESNext", "moduleResolution": "Bundler", "jsx": "react-jsx", "strict": true, "noEmit": true, - "esModuleInterop": true, "skipLibCheck": true, "types": ["vitest/globals","@testing-library/jest-dom"] }, - "include": ["src"] } -``` -`tailwind.config.ts` (`content: ["./index.html","./src/**/*.{ts,tsx}"]`), `postcss.config.js` (tailwind+autoprefixer), `index.html` (root div + `/src/main.tsx`), `src/index.css` (`@tailwind base/components/utilities`). - -- [ ] **Step 2: Write the failing test** - -```tsx -// frontend/src/App.test.tsx -import { render, screen } from "@testing-library/react"; -import { App } from "./App"; -test("App renders the ThothII title", () => { - render(); - expect(screen.getByText(/ThothII/i)).toBeInTheDocument(); -}); -``` - -- [ ] **Step 3: Run (fail)** - -Run: `cd frontend && npm install && npm test` -Expected: FAIL — `Cannot find module './App'`. - -- [ ] **Step 4: Implement App + main + setup** - -```tsx -// frontend/src/App.tsx -export function App() { - return
ThothII
; -} -``` -```tsx -// frontend/src/main.tsx -import { StrictMode } from "react"; -import { createRoot } from "react-dom/client"; -import { App } from "./App"; -import "./index.css"; -createRoot(document.getElementById("root")!).render(); -``` -```ts -// frontend/src/test/setup.ts -import "@testing-library/jest-dom/vitest"; -``` - -- [ ] **Step 5: Run (pass) + ShadCn init + commit** - -Run: `cd frontend && npm test` → PASS. Then init ShadCn (`npx shadcn@latest init -d`) and add the base components used later: `npx shadcn@latest add button checkbox radio-group textarea card dialog badge sonner`. Verify `npm run build` clean. -```bash -git add frontend -git commit -m "feat(frontend): scaffold Vite+React+TS+Tailwind/ShadCn + Vitest" -``` - ---- - -### Task 2: API types + REST client - -**Files:** -- Create: `frontend/src/api/types.ts`, `frontend/src/api/client.ts`, `frontend/src/api/sessions.ts`, `frontend/src/api/workspaces.ts`, `frontend/src/api/models.ts`, `frontend/src/api/sql.ts` -- Create (test infra): `frontend/src/test/msw.ts` -- Test: `frontend/src/api/sessions.test.ts` - -**Interfaces:** -- Produces (canonical contract types — every later task imports these): -```ts -export interface WidgetOption { id: string; label: string; meta?: Record; selected?: boolean; recommended?: boolean; opens?: WidgetDescriptor; } -export interface WidgetDescriptor { - id: string; schema_version?: number; session_id?: string; phase?: string; - title?: string; intro?: string; - widget: "info" | "select" | "multiselect" | "freetext" | "artifact-gate" | "artifact" | string; - options?: WidgetOption[]; reserved?: string[]; allow_empty?: boolean; - artifact?: { kind: string; content?: string; [k: string]: unknown }; - level?: "info" | "warning" | "error"; text?: string; - [k: string]: unknown; -} -export interface UiResponse { id: string; kind?: string; choices?: string[]; text?: string; decision?: { type: string }; control?: string; } -export type StreamEvent = - | { type: "ui_request"; ui_request: WidgetDescriptor } - | { type: "text_delta"; text: string } - | { type: "info"; level?: "info" | "warning" | "error"; text: string } - | { type: "system_event"; event: string; [k: string]: unknown }; -export interface SessionSummary { id: string; status: string; question: string; summary: string | null; created_at: string; updated_at: string | null; author: string | null; } -export interface PreviewResult { columns: string[]; rows: unknown[][]; execution_ms: number; truncated: boolean; limit: number; offset: number; } -``` -- Produces (functions): `createSession(input): Promise<{id:string}>`, `listSessions(): Promise`, `getSession(id): Promise`, `postResponse(id, uiResponse): Promise`, `postSteer(id, text): Promise`, `closeSession(id): Promise`, `resumeSession(id): Promise`, `listWorkspaces(): Promise<{name:string;file:string}[]>`, `listModels(): Promise<{models:unknown[]}>`, `sqlPreview(id,{limit?,offset?}): Promise`, `sqlExport(id): Promise<{path:string}>`. Base: `apiFetch(path, init?)` in `client.ts` using `VITE_BACKEND_URL`. - -- [ ] **Step 1: MSW test infra + failing test** - -```ts -// frontend/src/test/msw.ts -import { setupServer } from "msw/node"; -export const server = setupServer(); -``` -Register in `src/test/setup.ts`: `beforeAll(()=>server.listen()); afterEach(()=>server.resetHandlers()); afterAll(()=>server.close());` (import `server` + vitest globals). -```ts -// frontend/src/api/sessions.test.ts -import { http, HttpResponse } from "msw"; -import { server } from "../test/msw"; -import { createSession, listSessions } from "./sessions"; - -test("createSession POSTs and returns the id", async () => { - server.use(http.post("http://localhost:8787/sessions", () => HttpResponse.json({ id: "s1" }))); - expect(await createSession({ workspace: "w", question: "q" })).toEqual({ id: "s1" }); -}); -test("listSessions GETs the array", async () => { - server.use(http.get("http://localhost:8787/sessions", () => HttpResponse.json([{ id: "s1", status: "open", question: "q", summary: null, created_at: "t", updated_at: null, author: null }]))); - const rows = await listSessions(); - expect(rows[0].id).toBe("s1"); -}); -``` - -- [ ] **Step 2: Run (fail)** - -Run: `cd frontend && npm test -- sessions` -Expected: FAIL — modules absent. - -- [ ] **Step 3: Implement client + api modules** - -```ts -// frontend/src/api/client.ts -const BASE = import.meta.env.VITE_BACKEND_URL ?? "http://localhost:8787"; -export async function apiFetch(path: string, init?: RequestInit): Promise { - const res = await fetch(`${BASE}${path}`, { headers: { "content-type": "application/json" }, ...init }); - if (!res.ok) throw new Error(`${res.status} ${await res.text().catch(() => "")}`); - return res.status === 204 ? (undefined as T) : ((await res.json()) as T); -} -export { BASE }; -``` -```ts -// frontend/src/api/sessions.ts -import { apiFetch } from "./client"; -import type { SessionSummary, UiResponse } from "./types"; -export const createSession = (i: { workspace: string; question: string; provider?: string; model?: string; thinking?: string; name?: string }) => - apiFetch<{ id: string }>("/sessions", { method: "POST", body: JSON.stringify(i) }); -export const listSessions = () => apiFetch("/sessions"); -export const getSession = (id: string) => apiFetch(`/sessions/${id}`); -export const postResponse = (id: string, uiResponse: UiResponse) => apiFetch(`/sessions/${id}/response`, { method: "POST", body: JSON.stringify({ ui_response: uiResponse }) }); -export const postSteer = (id: string, text: string) => apiFetch(`/sessions/${id}/steer`, { method: "POST", body: JSON.stringify({ text }) }); -export const closeSession = (id: string) => apiFetch(`/sessions/${id}/close`, { method: "POST" }); -export const resumeSession = (id: string) => apiFetch(`/sessions/${id}/resume`, { method: "POST" }); -``` -`workspaces.ts` (`listWorkspaces`), `models.ts` (`listModels`), `sql.ts` (`sqlPreview`, `sqlExport`) follow the same pattern with their endpoints; `types.ts` holds the interfaces above. - -- [ ] **Step 4: Run (pass) + commit** - -Run: `cd frontend && npm test -- sessions` → PASS; `npm run build` clean. -```bash -git add frontend/src/api frontend/src/test -git commit -m "feat(frontend): contract types + REST client (MSW-tested)" -``` - ---- - -### Task 3: Session store (Zustand) - -**Files:** -- Create: `frontend/src/store/sessionStore.ts` -- Test: `frontend/src/store/sessionStore.test.ts` - -**Interfaces:** -- Consumes: `StreamEvent`, `WidgetDescriptor` (Task 2). -- Produces: `useSessionStore` (Zustand) with state `{ pendingWidget: WidgetDescriptor|null; transcript: {role:"assistant";text:string}[]; toasts: {level:string;text:string}[]; lastSystemEvent: StreamEvent|null }` and actions `applyEvent(e: StreamEvent): void`, `clearPending(): void`, `resetSession(): void`. `applyEvent`: `ui_request`→set pendingWidget; `text_delta`→append to the current assistant transcript entry (create if none/after a widget); `info`→push toast; `system_event`→set lastSystemEvent. - -- [ ] **Step 1: Failing test** - -```ts -// frontend/src/store/sessionStore.test.ts -import { useSessionStore } from "./sessionStore"; -beforeEach(() => useSessionStore.getState().resetSession()); - -test("ui_request sets pendingWidget", () => { - useSessionStore.getState().applyEvent({ type: "ui_request", ui_request: { id: "u1", widget: "select" } }); - expect(useSessionStore.getState().pendingWidget?.id).toBe("u1"); -}); -test("text_delta accumulates into transcript", () => { - const s = useSessionStore.getState(); - s.applyEvent({ type: "text_delta", text: "Ana" }); - s.applyEvent({ type: "text_delta", text: "lisi" }); - expect(useSessionStore.getState().transcript.at(-1)?.text).toBe("Analisi"); -}); -test("info pushes a toast", () => { - useSessionStore.getState().applyEvent({ type: "info", level: "warning", text: "attenzione" }); - expect(useSessionStore.getState().toasts.at(-1)).toEqual({ level: "warning", text: "attenzione" }); -}); -test("clearPending removes the widget", () => { - useSessionStore.getState().applyEvent({ type: "ui_request", ui_request: { id: "u1", widget: "select" } }); - useSessionStore.getState().clearPending(); - expect(useSessionStore.getState().pendingWidget).toBeNull(); -}); -``` - -- [ ] **Step 2: Run (fail)** — `npm test -- sessionStore` → module absent. - -- [ ] **Step 3: Implement** - -```ts -// frontend/src/store/sessionStore.ts -import { create } from "zustand"; -import type { StreamEvent, WidgetDescriptor } from "../api/types"; -interface Entry { role: "assistant"; text: string } -interface SessionState { - pendingWidget: WidgetDescriptor | null; transcript: Entry[]; toasts: { level: string; text: string }[]; lastSystemEvent: StreamEvent | null; - applyEvent: (e: StreamEvent) => void; clearPending: () => void; resetSession: () => void; -} -const empty = { pendingWidget: null, transcript: [] as Entry[], toasts: [] as { level: string; text: string }[], lastSystemEvent: null }; -export const useSessionStore = create((set) => ({ - ...empty, - applyEvent: (e) => set((st) => { - if (e.type === "ui_request") return { pendingWidget: e.ui_request }; - if (e.type === "text_delta") { - const t = [...st.transcript]; - const last = t.at(-1); - if (last && !st.pendingWidget) t[t.length - 1] = { role: "assistant", text: last.text + e.text }; - else t.push({ role: "assistant", text: e.text }); - return { transcript: t }; - } - if (e.type === "info") return { toasts: [...st.toasts, { level: e.level ?? "info", text: e.text }] }; - if (e.type === "system_event") return { lastSystemEvent: e }; - return {}; - }), - clearPending: () => set({ pendingWidget: null }), - resetSession: () => set({ ...empty }), -})); -``` - -- [ ] **Step 4: Run (pass) + commit** - -Run: `npm test -- sessionStore` → PASS. -```bash -git add frontend/src/store -git commit -m "feat(frontend): Zustand session store + applyEvent" -``` - ---- - -### Task 4: `useSessionStream` (SSE → store) - -**Files:** -- Create: `frontend/src/stream/useSessionStream.ts` -- Create (test): `frontend/src/test/fakeEventSource.ts` -- Test: `frontend/src/stream/useSessionStream.test.tsx` - -**Interfaces:** -- Consumes: `useSessionStore.applyEvent` (Task 3), `BASE` (Task 2). -- Produces: `useSessionStream(sessionId: string | null): { connected: boolean }` — when `sessionId` is set, opens `new EventSource(\`${BASE}/sessions/${id}/events\`)`, parses each `message` `data` as JSON `StreamEvent`, calls `applyEvent`; closes on unmount / id change. Uses the global `EventSource` (overridable in tests via a fake). - -- [ ] **Step 1: Fake EventSource + failing test** - -```ts -// frontend/src/test/fakeEventSource.ts -export class FakeEventSource { - static instances: FakeEventSource[] = []; - onmessage: ((e: { data: string }) => void) | null = null; - onopen: (() => void) | null = null; - onerror: (() => void) | null = null; - closed = false; - constructor(public url: string) { FakeEventSource.instances.push(this); } - emit(obj: unknown) { this.onmessage?.({ data: JSON.stringify(obj) }); } - close() { this.closed = true; } -} -``` -```tsx -// frontend/src/stream/useSessionStream.test.tsx -import { renderHook } from "@testing-library/react"; -import { act } from "react"; -import { FakeEventSource } from "../test/fakeEventSource"; -import { useSessionStream } from "./useSessionStream"; -import { useSessionStore } from "../store/sessionStore"; - -beforeEach(() => { FakeEventSource.instances = []; (globalThis as any).EventSource = FakeEventSource; useSessionStore.getState().resetSession(); }); - -test("opens an EventSource for the session and feeds events to the store", () => { - renderHook(() => useSessionStream("s1")); - const es = FakeEventSource.instances[0]; - expect(es.url).toContain("/sessions/s1/events"); - act(() => es.emit({ type: "ui_request", ui_request: { id: "u1", widget: "select" } })); - expect(useSessionStore.getState().pendingWidget?.id).toBe("u1"); -}); -test("closes the stream on unmount", () => { - const { unmount } = renderHook(() => useSessionStream("s1")); - const es = FakeEventSource.instances[0]; - unmount(); - expect(es.closed).toBe(true); -}); -``` - -- [ ] **Step 2: Run (fail)** — module absent. - -- [ ] **Step 3: Implement** - -```ts -// frontend/src/stream/useSessionStream.ts -import { useEffect, useState } from "react"; -import { BASE } from "../api/client"; -import { useSessionStore } from "../store/sessionStore"; -import type { StreamEvent } from "../api/types"; -export function useSessionStream(sessionId: string | null) { - const [connected, setConnected] = useState(false); - const applyEvent = useSessionStore((s) => s.applyEvent); - useEffect(() => { - if (!sessionId) return; - const es = new EventSource(`${BASE}/sessions/${sessionId}/events`); - es.onopen = () => setConnected(true); - es.onerror = () => setConnected(false); - es.onmessage = (ev) => { try { applyEvent(JSON.parse(ev.data) as StreamEvent); } catch { /* ignore malformed */ } }; - return () => { es.close(); setConnected(false); }; - }, [sessionId, applyEvent]); - return { connected }; -} -``` - -- [ ] **Step 4: Run (pass) + commit** - -Run: `npm test -- useSessionStream` → PASS. -```bash -git add frontend/src/stream frontend/src/test/fakeEventSource.ts -git commit -m "feat(frontend): useSessionStream (EventSource -> store)" -``` - ---- - -### Task 5: Widget registry + fallback - -**Files:** -- Create: `frontend/src/widgets/registry.ts`, `frontend/src/widgets/FallbackWidget.tsx`, `frontend/src/widgets/types.ts` -- Test: `frontend/src/widgets/registry.test.tsx` - -**Interfaces:** -- Consumes: `WidgetDescriptor`, `UiResponse` (Task 2). -- Produces: `WidgetProps = { descriptor: WidgetDescriptor; onRespond: (r: UiResponse) => void }` (`widgets/types.ts`); `register(kind: string, comp: React.FC): void`; `resolve(kind: string): React.FC` (returns `FallbackWidget` for unknown). `FallbackWidget` renders the descriptor JSON + a freetext box that responds with `{id, control:"freetext", text}`. - -- [ ] **Step 1: Failing test** - -```tsx -// frontend/src/widgets/registry.test.tsx -import { render, screen } from "@testing-library/react"; -import { register, resolve } from "./registry"; -import type { WidgetProps } from "./types"; - -test("resolve returns the registered renderer", () => { - const Dummy = (_: WidgetProps) =>
dummy
; - register("dummy", Dummy); - expect(resolve("dummy")).toBe(Dummy); -}); -test("resolve falls back for unknown kind and shows the JSON", () => { - const Comp = resolve("totally-unknown"); - render( {}} />); - expect(screen.getByText(/Widget non supportato/i)).toBeInTheDocument(); -}); -``` - -- [ ] **Step 2: Run (fail)** — modules absent. - -- [ ] **Step 3: Implement** - -```tsx -// frontend/src/widgets/types.ts -import type { WidgetDescriptor, UiResponse } from "../api/types"; -export type WidgetProps = { descriptor: WidgetDescriptor; onRespond: (r: UiResponse) => void }; -``` -```tsx -// frontend/src/widgets/FallbackWidget.tsx -import { useState } from "react"; -import type { WidgetProps } from "./types"; -export function FallbackWidget({ descriptor, onRespond }: WidgetProps) { - const [text, setText] = useState(""); - return ( -
-

Widget non supportato (kind: {descriptor.widget}) — rispondi manualmente

- 
{JSON.stringify(descriptor, null, 2)}
-