feat: implement memory and evidence administration with guided repairs
Publish documentation / publish (push) Successful in 1m27s

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.
This commit is contained in:
Codex
2026-09-10 10:31:34 +02:00
parent 8fe526dd6e
commit 82e2c91f42
168 changed files with 11914 additions and 1772 deletions
+20 -11
View File
@@ -81,6 +81,9 @@ kind:"cte_result"` of the plan (F6), `reviewer_confirm kind:"sql"` (F7), and
Back" (rollback, see discipline 11), or "Esci/Exit" (session abort). If the
reviewer closes without choosing, the gate re-presents the same widget — there is
no silent skip.
When Memory and Evidence conflict and a shared archive needs correction, read
`archive-repair.md` and use `reviewer_archive_repair`. Its receipt reports the
persistent correction; the normal phase gate still approves the current question.
6. **Self-contained messages.** When you call any `reviewer_*` tool, ALWAYS include
in the `message` (or in the `options`' labels/descriptions) a concise recap of the
context the reviewer needs to decide: what was asked, what you found, what each
@@ -310,6 +313,10 @@ Prerequisite: Phase 3 closed.
questions show which tables comparable questions used. Cite relevant precedents
(session id + tables) to the reviewer as CONTEXT — they are reference material,
NOT decisions to apply; their filters/periods may not transfer.
Run `tht memory rules "<question>" --session <id> --json` for reusable join rules
and explained errors. Read `memory-review.md` when a rule is relevant or a reviewer
approves a reusable correction. Present the applicable rule and its Memory ID in
the existing table/join proposal; that gate decides its use for this question.
2. Propose tables to promote/exclude with **`reviewer_schema_linking`**: pass
`tables[]` as `{id, name, kind: "promote"|"exclude", rationale, suggested_columns}`.
Do NOT list every column yourself — the gate loads the full column set (with
@@ -383,6 +390,8 @@ Prerequisite: Phase 5 closed.
1. Read `cte.md`. Decompose the rewritten question into CTEs (Agent View Generation):
each CTE captures an informative subset with a clear purpose, named in snake_case.
Consult `tht memory rules "<question>" --session <id> --json` and follow
`memory-review.md` for reusable calculation rules and explained errors.
`tht memory solved-search "<question>" --json` shows how similar solved questions
were structured — use as reference only.
2. Present the full CTE plan to the reviewer with `reviewer_confirm kind:"cte_plan"`,
@@ -428,6 +437,8 @@ Prerequisite: Phase 6 closed.
1. Read `sql-generation.md`. Recursive divide-and-conquer: the CTEs approved in
Phase 6 are the preferred building blocks (reuse them by name).
Consult `tht memory rules "<question>" --session <id> --json`; show applicable
rules and Memory IDs in the SQL explanation approved by the existing SQL gate.
`tht memory solved-search "<question>" --json` gives the final SQL of similar
solved questions: reference exemplars — never copy filters, periods or
populations without checking them against the current rewritten question.
@@ -460,15 +471,12 @@ Prerequisite: Phase 7 closed.
2. On a server, if the reviewer chose yes: `tht datamart generate` (stub — raises
NotImplementedError for now). Tell
the reviewer that dbt generation is not implemented yet.
3. **Memory promotion closes the session.** Call `reviewer_memory_promote` with ONLY
the session id: the gate computes the candidates itself (`tht memory promote
--preview` — the 3 reusable types, already excluding promoted/declined ones) and
shows the reviewer a pre-selected checklist. Selected → saved to the vectordb +
`memory_promoted`; deselected → `memory_promotion_declined` (never re-proposed).
After recording the promotion (even with zero candidates) the gate advances F8 and
finalizes the session itself — do NOT present a `reviewer_confirm kind:"phase"`
afterwards: there is nothing left to approve. When the gate answers "sessione
finalizzata", give the reviewer the final summary and end the turn.
3. **Memory review closes the session.** Follow `memory-review.md` to finish any
persisted proposals, then call `reviewer_memory_promote` with the session ID.
The reviewer edits and selects additions, explicit updates and links in one
summary, including the consultative solved question. Only the selected cards
are saved. The gate records `memory_summary_reviewed`, advances F8 and finalizes.
Once it reports finalization, give the session summary and end the turn.
4. If the gate reports an error instead (e.g. the datamart decision is missing),
fix the prerequisite and call `reviewer_memory_promote` again. Only if the gate
says the session is still open, close with `reviewer_confirm kind:"phase"` as a
@@ -478,7 +486,8 @@ Prerequisite: Phase 7 closed.
When the promotion gate (or, as fallback, the F8 phase gate) closes Phase 8, the
gate calls `tht session finalize` automatically.
Finalize also indexes the question→SQL pair in the vectordb (kind `solved_question`,
best-effort — on failure recover with `tht memory solved-index <id>`). The persisted
Exemplars are saved only when selected in the Memory summary. Finalize performs
no additional automatic Memory writes. Pending indexing is recovered through
Memory management. The persisted
state (ledger `review_decisions.jsonl` + artifacts) is the truth: what is not
recorded did not happen.