feat: implement memory and evidence administration with guided repairs

Add PostgreSQL-backed memory, editable evidence with source review and activation, and human-approved archive repairs across the harness, API, and UI. Include migrations, deployment support, regression coverage, and validation documentation. Refresh permissions from validated session roles so existing administrator logins can access newly deployed archive management features.
2026-09-10 10:31:34 +02:00
parent 8fe526dd6e
commit 82e2c91f42
168 changed files with 11914 additions and 1772 deletions
@@ -0,0 +1,74 @@
+# Reusable Memory during the workflow
+
+Consult rules at schema linking and SQL construction with
+`tht memory rules "<current question>" --session <id> --json`.
+An optional `--filters '{"table":"orders","column":"id"}'` narrows the physical
+context. The runtime fixes database and schema. A returned card is a candidate:
+explain its scope and Memory ID in the existing join, CTE or SQL proposal. That
+gate approves the concrete use; a retrieved link is not an approval. Exemplars
+remain references to previous questions.
+
+## Prepare additions and updates
+
+After a reviewer approves a reusable definition, join/calculation rule or explained
+correction, prepare a card citing the effective decision sequence(s) from
+`tht session show <id>`. Preserve the explanation and physical dependencies.
+Keep query-specific choices (for example only using 2024) in the solved question.
+An unselected option, unexplained rejection or timeout is not a reusable source.
+When an error and correction state the same rule, prepare one card.
+
+Write the complete current proposal list to a temporary JSON file and run
+`tht memory propose --session <id> --data <file.json>`. This persists
+`memory_proposals.json` in the session without changing the shared archive.
+Reuse proposal IDs when refining their wording. The accepted shape is:
+
+```json
+[
+  {
+    "id": "order-grain",
+    "source_seqs": [11],
+    "reason": "The reviewer corrected repeated header totals; this also applies to future questions.",
+    "card": {
+      "family": "sql_rule",
+      "subject": "Order totals after joining lines",
+      "detail": "Aggregate each order once before combining it with line totals.",
+      "scope": "Sales orders and order lines",
+      "rationale": "A line join repeats the header amount once per line.",
+      "concepts": ["order grain"],
+      "dependencies": [{"database": "warehouse", "schema_name": "sales", "table": "orders", "column": "total"}],
+      "links": []
+    }
+  }
+]
+```
+
+Use the actual decision numbers and schema identifiers from this session. Families
+are `domain_clarification`, `sql_rule`, `explained_error` and `solved_question`.
+Explained errors require both the corrected behavior and an approved explanation.
+The summary adds domain clarifications and the current approved exemplar when they
+are not covered by authored proposals, so author only the additions/changes needed.
+
+For an update, include `target_id` and `target_revision` from the current recalled
+card, explain the change in `reason`, and provide its complete resulting content.
+The reviewer sees the current card alongside the proposal. A conflicting manual
+edit requires a refreshed proposal and another review; it is not overwritten.
+Keep different rules with different scopes separate. Exact duplicates do not need
+another card. Semantic deletion belongs to Memory management.
+
+Links contain `target_id` and `meaning`. Use a current Memory ID for an existing
+destination or `proposal:<proposal-id>` for another new card in the summary. The
+reviewer may edit/remove links; a link to a new card requires selecting that card.
+
+## Final review
+
+At the end of F8, call `reviewer_memory_promote`. The widget permits content, scope,
+concept, dependency and link edits and accepts an empty selection. Approved exemplar
+SQL remains the session's solution; changing it requires returning to SQL review.
+The gate applies selected cards and links atomically in PostgreSQL and then updates
+Qdrant. An incomplete index update is reported and retained for explicit retry.
+An interrupted review is recovered from its persisted receipt rather than applied
+again. Once the gate reports finalization, end the session without another gate.
+
+For a Memory/Evidence conflict requiring a persistent correction, follow
+`archive-repair.md`. A correction already saved by that gate does not need a
+duplicate update in the final summary.