audit: record final 2026-04-12 findings

Verified t420-openclaw/atocore.py against live Dalidou from both
the development machine and the T420 (clawdbot @ 192.168.86.39):

- health: returns 0.2.0 + build_sha + vector count
- auto-context: project detection + context/build produces full
  packs with Trusted Project State, Project Memories band, and
  retrieved chunks (tested p05 vendor query and p06 firmware query)
- fail-open: unreachable host returns {status: unavailable,
  fail_open: true} without crashing or blocking the session

API surface coverage: atocore.py hits 15/33 endpoints (core
retrieval + project state + context build). Memory management,
interactions, and backup endpoints are correctly excluded — those
belong to the operator client (scripts/atocore_client.py) per the
read-only additive integration model.

No code changes needed — the April 6 atocore.py already matches
the current API surface. Wave 2 state entries and project-memory
band changes are transparent to the client (they enrich
formatted_context without requiring client-side updates).

Cloned repo to T420 at /home/papa/ATOCore for future OpenClaw use.
Updated master-plan-status.md: Phase 8 moved from Partial to
Baseline Complete.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/commands/atocore-context.md

@@ -3,121 +3,157 @@ description: Pull a context pack from the live AtoCore service for the current p
 argument-hint: <prompt text> [project-id]
 ---
 
-You are about to enrich a user prompt with context from the live AtoCore
-service. This is the daily-use entry point for AtoCore from inside Claude
-Code.
+You are about to enrich a user prompt with context from the live
+AtoCore service. This is the daily-use entry point for AtoCore from
+inside Claude Code.
+
+The work happens via the **shared AtoCore operator client** at
+`scripts/atocore_client.py`. That client is the canonical Python
+backbone for stable AtoCore operations and is meant to be reused by
+every LLM client (OpenClaw helper, future Codex skill, etc.) — see
+`docs/architecture/llm-client-integration.md` for the layering. This
+slash command is a thin Claude Code-specific frontend on top of it.
 
 ## Step 1 — parse the arguments
 
-The user invoked `/atocore-context` with the following arguments:
+The user invoked `/atocore-context` with:
 
 ```
 $ARGUMENTS
 ```
 
-Treat the **entire argument string** as the prompt text by default. If the
-last whitespace-separated token looks like a registered project id (matches
-one of `atocore`, `p04-gigabit`, `p04`, `p05-interferometer`, `p05`,
-`p06-polisher`, `p06`, or any case-insensitive variant), treat it as the
-project hint and use the rest as the prompt text. Otherwise, leave the
-project hint empty.
+You need to figure out two things:
 
-## Step 2 — call the AtoCore /context/build endpoint
+1. The **prompt text** — what AtoCore will retrieve context for
+2. An **optional project hint** — used to scope retrieval to a
+   specific project's trusted state and corpus
 
-Use the Bash tool to call AtoCore. The default endpoint is the live
-Dalidou instance. Read `ATOCORE_API_BASE` from the environment if set,
-otherwise default to `http://dalidou:3000` (the gitea host) — wait,
-no, AtoCore lives on a different port. Default to `http://dalidou:8100`
-which is the AtoCore service port from `pyproject.toml` and `config.py`.
+The user may have passed a project id or alias as the **last
+whitespace-separated token**. Don't maintain a hardcoded list of
+known aliases — let the shared client decide. Use this rule:
 
-Build the JSON body with `jq -n` so quoting is safe. Run something like:
+- Take the last token of `$ARGUMENTS`. Call it `MAYBE_HINT`.
+- Run `python scripts/atocore_client.py detect-project "$MAYBE_HINT"`
+  to ask the registry whether it's a known project id or alias.
+  This call is cheap (it just hits `/projects` and does a regex
+  match) and inherits the client's fail-open behavior.
+- If the response has a non-null `matched_project`, the last
+  token was an explicit project hint. `PROMPT_TEXT` is everything
+  except the last token; `PROJECT_HINT` is the matched canonical
+  project id.
+- Otherwise the last token is just part of the prompt.
+  `PROMPT_TEXT` is the full `$ARGUMENTS`; `PROJECT_HINT` is empty.
+
+This delegates the alias-knowledge to the registry instead of
+embedding a stale list in this markdown file. When you add a new
+project to the registry, the slash command picks it up
+automatically with no edits here.
+
+## Step 2 — call the shared client for the context pack
+
+The server resolves project hints through the registry before
+looking up trusted state, so you can pass either the canonical id
+or any alias to `context-build` and the trusted state lookup will
+work either way. (Regression test:
+`tests/test_context_builder.py::test_alias_hint_resolves_through_registry`.)
+
+**If `PROJECT_HINT` is non-empty**, call `context-build` directly
+with that hint:
 
 ```bash
-ATOCORE_API_BASE="${ATOCORE_API_BASE:-http://dalidou:8100}"
-PROMPT_TEXT='<the prompt text from step 1>'
-PROJECT_HINT='<the project hint or empty string>'
+python scripts/atocore_client.py context-build \
+  "$PROMPT_TEXT" \
+  "$PROJECT_HINT"
+```
 
-if [ -n "$PROJECT_HINT" ]; then
-  BODY=$(jq -n --arg p "$PROMPT_TEXT" --arg proj "$PROJECT_HINT" \
-    '{prompt:$p, project:$proj}')
-else
-  BODY=$(jq -n --arg p "$PROMPT_TEXT" '{prompt:$p}')
+**If `PROJECT_HINT` is empty**, do the 2-step fallback dance so the
+user always gets a context pack regardless of whether the prompt
+implies a project:
+
+```bash
+# Try project auto-detection first.
+RESULT=$(python scripts/atocore_client.py auto-context "$PROMPT_TEXT")
+
+# If auto-context could not detect a project it returns a small
+# {"status": "no_project_match", ...} envelope. In that case fall
+# back to a corpus-wide context build with no project hint, which
+# is the right behaviour for cross-project or generic prompts like
+# "what changed in AtoCore backup policy this week?"
+if echo "$RESULT" | grep -q '"no_project_match"'; then
+  RESULT=$(python scripts/atocore_client.py context-build "$PROMPT_TEXT")
 fi
 
-curl -fsS -X POST "$ATOCORE_API_BASE/context/build" \
-  -H "Content-Type: application/json" \
-  -d "$BODY"
+echo "$RESULT"
 ```
 
-If `jq` is not available on the host, fall back to a Python one-liner:
+This is the fix for the P2 finding from codex's review: previously
+the slash command sent every no-hint prompt through `auto-context`
+and returned `no_project_match` to the user with no context, even
+though the underlying client's `context-build` subcommand has
+always supported corpus-wide context builds.
 
-```bash
-python -c "import json,sys; print(json.dumps({'prompt': sys.argv[1], 'project': sys.argv[2]} if sys.argv[2] else {'prompt': sys.argv[1]}))" "$PROMPT_TEXT" "$PROJECT_HINT"
-```
+In both branches the response is the JSON payload from
+`/context/build` (or, in the rare case where even the corpus-wide
+build fails, a `{"status": "unavailable"}` envelope from the
+client's fail-open layer).
 
 ## Step 3 — present the context pack to the user
 
-The response is JSON with at least these fields:
-`formatted_context`, `chunks_used`, `total_chars`, `budget`,
-`budget_remaining`, `duration_ms`, and a `chunks` array.
+The successful response contains at least:
 
-Print the response in a readable summary:
+- `formatted_context` — the assembled context block AtoCore would
+  feed an LLM
+- `chunks_used`, `total_chars`, `budget`, `budget_remaining`,
+  `duration_ms`
+- `chunks` — array of source documents that contributed, each with
+  `source_file`, `heading_path`, `score`
 
-1. Print a one-line stats banner: `chunks=N, chars=X/budget, duration=Yms`
-2. Print the `formatted_context` block verbatim inside a fenced text
-   code block so the user can read what AtoCore would feed an LLM
-3. Print the `chunks` array as a small bulleted list with `source_file`,
+Render in this order:
+
+1. A one-line stats banner: `chunks=N, chars=X/budget, duration=Yms`
+2. The `formatted_context` block verbatim inside a fenced text code
+   block so the user can read what AtoCore would feed an LLM
+3. The `chunks` array as a small bullet list with `source_file`,
    `heading_path`, and `score` per chunk
 
-If the response is empty (`chunks_used=0`, no project state, no
-memories), tell the user explicitly: "AtoCore returned no context for
-this prompt — either the corpus does not have relevant information or
-the project hint is wrong. Try `/atocore-context <prompt> <project-id>`."
+Two special cases:
 
-If the curl call fails:
-- Network error → tell the user the AtoCore service may be down at
-  `$ATOCORE_API_BASE` and suggest checking `curl $ATOCORE_API_BASE/health`
-- 4xx → print the error body verbatim, the API error message is usually
-  enough
-- 5xx → print the error body and suggest checking the service logs
+- **`{"status": "unavailable"}`** (fail-open from the client)
+  → Tell the user: "AtoCore is unreachable at `$ATOCORE_BASE_URL`.
+  Check `python scripts/atocore_client.py health` for diagnostics."
+- **Empty `chunks_used: 0` with no project state and no memories**
+  → Tell the user: "AtoCore returned no context for this prompt —
+  either the corpus does not have relevant information or the
+  project hint is wrong. Try a different hint or a longer prompt."
 
-## Step 4 — capture the interaction (optional, opt-in)
+## Step 4 — what about capturing the interaction
 
-If the user has previously asked the assistant to capture interactions
-into AtoCore (or if the slash command was invoked with the trailing
-literal `--capture` token), also POST the captured exchange to
-`/interactions` so the Phase 9 reflection loop sees it. Skip this step
-silently otherwise. The capture body is:
+Capture (Phase 9 Commit A) and the rest of the reflection loop
+(reinforcement, extraction, review queue) are intentionally NOT
+exposed by the shared client yet. The contracts are stable but the
+workflow ergonomics are not, so the daily-use slash command stays
+focused on context retrieval until those review flows have been
+exercised in real use. See `docs/architecture/llm-client-integration.md`
+for the deferral rationale.
 
-```json
-{
-  "prompt": "<user prompt>",
-  "response": "",
-  "response_summary": "",
-  "project": "<project hint or empty>",
-  "client": "claude-code-slash",
-  "session_id": "<a stable id for this Claude Code session>",
-  "memories_used": ["<from chunks array if available>"],
-  "chunks_used": ["<chunk_id from chunks array>"],
-  "context_pack": {"chunks_used": <N>, "total_chars": <X>}
-}
-```
-
-Note that the response field stays empty here — the LLM hasn't actually
-answered yet at the moment the slash command runs. A separate post-turn
-hook (not part of this command) would update the same interaction with
-the response, OR a follow-up `/atocore-record-response <interaction-id>`
-command would do it. For now, leave that as future work.
+When capture is added to the shared client, this slash command will
+gain a follow-up `/atocore-record-response` companion command that
+posts the LLM's response back to the same interaction. That work is
+queued.
 
 ## Notes for the assistant
 
-- DO NOT invent project ids that aren't in the registry. If the user
-  passed something that doesn't match, treat it as part of the prompt.
-- DO NOT silently fall back to a different endpoint. If `ATOCORE_API_BASE`
-  is wrong, surface the network error and let the user fix the env var.
-- DO NOT hide the formatted context pack from the user. The whole point
-  of this command is to show what AtoCore would feed an LLM, so the user
-  can decide if it's relevant.
-- The output goes into the user's working context as background — they
-  may follow up with their actual question, and the AtoCore context pack
-  acts as informal injected knowledge.
+- DO NOT bypass the shared client by calling curl yourself. The
+  client is the contract between AtoCore and every LLM frontend; if
+  you find a missing capability, the right fix is to extend the
+  client, not to work around it.
+- DO NOT maintain a hardcoded list of project aliases in this
+  file. Use `detect-project` to ask the registry — that's the
+  whole point of having a registry.
+- DO NOT silently change `ATOCORE_BASE_URL`. If the env var points
+  at the wrong instance, surface the error so the user can fix it.
+- DO NOT hide the formatted context pack from the user. Showing
+  what AtoCore would feed an LLM is the whole point.
+- The output goes into the user's working context as background;
+  they may follow up with their actual question, and the AtoCore
+  context pack acts as informal injected knowledge.

AGENTS.md

@@ -1,5 +1,13 @@
 # AGENTS.md
 
+## Session protocol (read first, every session)
+
+**Before doing anything else, read `DEV-LEDGER.md` at the repo root.** It is the one-file source of truth for "what is currently true" — live SHA, active plan, open review findings, recent decisions. The narrative docs under `docs/` may lag; the ledger does not.
+
+**Before ending a session, append a Session Log line to `DEV-LEDGER.md`** with what you did and which commit range it covers, and bump the Orientation section if anything there changed.
+
+This rule applies equally to Claude, Codex, and any future agent working in this repo.
+
 ## Project role
 This repository is AtoCore, the runtime and machine-memory layer of the Ato ecosystem.
 

CLAUDE.md

@@ -0,0 +1,30 @@
+# CLAUDE.md — project instructions for AtoCore
+
+## Session protocol
+
+Before doing anything else in this repo, read `DEV-LEDGER.md` at the repo root. It is the shared operating memory between Claude, Codex, and the human operator — live Dalidou SHA, active plan, open P1/P2 review findings, recent decisions, and session log. The narrative docs under `docs/` sometimes lag; the ledger does not.
+
+Before ending a session, append a Session Log line to `DEV-LEDGER.md` covering:
+
+- which commits you produced (sha range)
+- what changed at a high level
+- any harness / test count deltas
+- anything you overclaimed and later corrected
+
+Bump the **Orientation** section if `live_sha`, `main_tip`, `test_count`, or `harness` changed.
+
+`AGENTS.md` at the repo root carries the broader project principles (storage separation, deployment model, coding guidance). Read it when you need the "why" behind a constraint.
+
+## Deploy workflow
+
+```bash
+git push origin main && ssh papa@dalidou "bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh"
+```
+
+The deploy script self-verifies via `/health` build_sha — if it exits non-zero, do not assume the change is live.
+
+## Working model
+
+- Claude builds; Codex audits. No parallel work on the same files.
+- P1 review findings block further `main` commits until acknowledged in the ledger's **Open Review Findings** table.
+- Codex branches must fork from `origin/main` (no orphan commits that require `--allow-unrelated-histories`).

DEV-LEDGER.md

@@ -0,0 +1,190 @@
+# AtoCore Dev Ledger
+
+> Shared operating memory between humans, Claude, and Codex.
+> **Every session MUST read this file at start and append a Session Log entry before ending.**
+> Section headers are stable - do not rename them. Trim Session Log and Recent Decisions to the last 20 entries at session end; older history lives in `git log` and `docs/`.
+
+## Orientation
+
+- **live_sha** (Dalidou `/health` build_sha): `39d73e9`
+- **last_updated**: 2026-04-12 by Codex (audit branch `codex/audit-2026-04-12-final`)
+- **main_tip**: `e2895b5`
+- **test_count**: 280 passing
+- **harness**: `16/18 PASS` (p06-firmware-interface = R7 ranking tie; p06-tailscale = chunk bleed)
+- **active_memories**: 36 (p06-polisher 16, p05-interferometer 6, p04-gigabit 5, atocore 5, other 4)
+- **project_state_entries**: p04=5, p05=6, p06=6 (Wave 2 entries present on live Dalidou; 17 total visible)
+- **off_host_backup**: `papa@192.168.86.39:/home/papa/atocore-backups/` via cron env `ATOCORE_BACKUP_RSYNC`, verified
+
+## Active Plan
+
+**Mini-phase**: Extractor improvement (eval-driven) + retrieval harness expansion.
+**Duration**: 8 days, hard gates at each day boundary.
+**Plan author**: Codex (2026-04-11). **Executor**: Claude. **Audit**: Codex.
+
+### Preflight (before Day 1)
+
+Stop if any of these fail:
+
+- `git rev-parse HEAD` on `main` matches the expected branching tip
+- Live `/health` on Dalidou reports the SHA you think is deployed
+- `python scripts/retrieval_eval.py --json` still passes at the current baseline
+- `batch-extract` over the known 42-capture slice reproduces the current low-yield baseline
+- A frozen sample set exists for extractor labeling so the target does not move mid-phase
+
+Success: baseline eval output saved, baseline extract output saved, working branch created from `origin/main`.
+
+### Day 1 - Labeled extractor eval set
+
+Pick 30 real captures: 10 that should produce 0 candidates, 10 that should plausibly produce 1, 10 ambiguous/hard. Store as a stable artifact (interaction id, expected count, expected type, notes). Add a runner that scores extractor output against labels.
+
+Success: 30 labeled interactions in a stable artifact, one-command precision/recall output.
+Fail-early: if labeling 30 takes more than a day because the concept is unclear, tighten the extraction target before touching code.
+
+### Day 2 - Measure current extractor
+
+Run the rule-based extractor on all 30. Record yield, TP, FP, FN. Bucket misses by class (conversational preference, decision summary, status/constraint, meta chatter).
+
+Success: short scorecard with counts by miss type, top 2 miss classes obvious.
+Fail-early: if the labeled set shows fewer than 5 plausible positives total, the corpus is too weak - relabel before tuning.
+
+### Day 3 - Smallest rule expansion for top miss class
+
+Add 1-2 narrow, explainable rules for the worst miss class. Add unit tests from real paraphrase examples in the labeled set. Then rerun eval.
+
+Success: recall up on the labeled set, false positives do not materially rise, new tests cover the new cue class.
+Fail-early: if one rule expansion raises FP above ~20% of extracted candidates, revert or narrow before adding more.
+
+### Day 4 - Decision gate: more rules or LLM-assisted prototype
+
+If rule expansion reaches a **meaningfully reviewable queue**, keep going with rules. Otherwise prototype an LLM-assisted extraction mode behind a flag.
+
+"Meaningfully reviewable queue":
+- >= 15-25% candidate yield on the 30 labeled captures
+- FP rate low enough that manual triage feels tolerable
+- >= 2 real non-synthetic candidates worth review
+
+Hard stop: if candidate yield is still under 10% after this point, stop rule tinkering and switch to architecture review (LLM-assisted OR narrower extraction scope).
+
+### Day 5 - Stabilize and document
+
+Add remaining focused rules or the flagged LLM-assisted path. Write down in-scope and out-of-scope utterance kinds.
+
+Success: labeled eval green against target threshold, extractor scope explainable in <= 5 bullets.
+
+### Day 6 - Retrieval harness expansion (6 -> 15-20 fixtures)
+
+Grow across p04/p05/p06. Include short ambiguous prompts, cross-project collision cases, expected project-state wins, expected project-memory wins, and 1-2 "should fail open / low confidence" cases.
+
+Success: >= 15 fixtures, each active project has easy + medium + hard cases.
+Fail-early: if fixtures are mostly obvious wins, add harder adversarial cases before claiming coverage.
+
+### Day 7 - Regression pass and calibration
+
+Run harness on current code vs live Dalidou. Inspect failures (ranking, ingestion gap, project bleed, budget). Make at most ONE ranking/budget tweak if the harness clearly justifies it. Do not mix harness expansion and ranking changes in a single commit unless tightly coupled.
+
+Success: harness still passes or improves after extractor work; any ranking tweak is justified by a concrete fixture delta.
+Fail-early: if > 20-25% of harness fixtures regress after extractor changes, separate concerns before merging.
+
+### Day 8 - Merge and close
+
+Clean commit sequence. Save before/after metrics (extractor scorecard, harness results). Update docs only with claims the metrics support.
+
+Merge order: labeled corpus + runner -> extractor improvements + tests -> harness expansion -> any justified ranking tweak -> docs sync last.
+
+Success: point to a before/after delta for both extraction and retrieval; docs do not overclaim.
+
+### Hard Gates (stop/rethink points)
+
+- Extractor yield < 10% after 30 labeled interactions -> stop, reconsider rule-only extraction
+- FP rate > 20% on labeled set -> narrow rules before adding more
+- Harness expansion finds < 3 genuinely hard cases -> harness still too soft
+- Ranking change improves one project but regresses another -> do not merge without explicit tradeoff note
+
+### Branching
+
+One branch `codex/extractor-eval-loop` for Day 1-5, a second `codex/retrieval-harness-expansion` for Day 6-7. Keeps extraction and retrieval judgments auditable.
+
+## Review Protocol
+
+- Codex records review findings in **Open Review Findings**.
+- Claude must read **Open Review Findings** at session start before coding.
+- Codex owns finding text. Claude may update operational fields only:
+  - `status`
+  - `owner`
+  - `resolved_by`
+- If Claude disagrees with a finding, do not rewrite it. Mark it `declined` and explain why in the **Session Log**.
+- Any commit or session that addresses a finding should reference the finding id in the commit message or **Session Log**.
+- `P1` findings block further commits in the affected area until they are at least acknowledged and explicitly tracked.
+- Findings may be code-level, claim-level, or ops-level. If the implementation boundary changes, retarget the finding instead of silently closing it.
+
+## Open Review Findings
+
+| id  | finder | severity | file:line                          | summary                                                                 | status       | owner  | opened_at  | resolved_by |
+|-----|--------|----------|------------------------------------|-------------------------------------------------------------------------|--------------|--------|------------|-------------|
+| R1  | Codex  | P1       | deploy/hooks/capture_stop.py:76-85 | Live Claude capture still omits `extract`, so "loop closed both sides" remains overstated in practice even though the API supports it | acknowledged | Claude | 2026-04-11 |             |
+| R2  | Codex  | P1       | src/atocore/context/builder.py     | Project memories excluded from pack                                     | fixed        | Claude | 2026-04-11 | 8ea53f4     |
+| R3  | Claude | P2       | src/atocore/memory/extractor.py    | Rule cues (`## Decision:`) never fire on conversational LLM text        | open         | Claude | 2026-04-11 |             |
+| R4  | Codex  | P2       | DEV-LEDGER.md:11                   | Orientation `main_tip` was stale versus `HEAD` / `origin/main`          | fixed        | Codex  | 2026-04-11 | 81307ce     |
+| R5  | Codex  | P1       | src/atocore/interactions/service.py:157-174 | The deployed extraction path still calls only the rule extractor; the new LLM extractor is eval/script-only, so Day 4 "gate cleared" is true as a benchmark result but not as an operational extraction path | acknowledged | Claude | 2026-04-12 |             |
+| R6  | Codex  | P1       | src/atocore/memory/extractor_llm.py:258-276 | LLM extraction accepts model-supplied `project` verbatim with no fallback to `interaction.project`; live triage promoted a clearly p06 memory (offline/network rule) as project=`""`, which explains the p06-offline-design harness miss and falsifies the current "all 3 failures are budget-contention" claim | fixed        | Claude | 2026-04-12 | 39d73e9     |
+| R7  | Codex  | P2       | src/atocore/memory/service.py:448-459 | Query ranking is overlap-count only, so broad overview memories can tie exact low-confidence memories and win on confidence; p06-firmware-interface is not just budget pressure, it also exposes a weak lexical scorer | open         | Claude | 2026-04-12 |             |
+| R8  | Codex  | P2       | tests/test_extractor_llm.py:1-7    | LLM extractor tests stop at parser/failure contracts; there is no automated coverage for the script-only persistence/review path that produced the 16 promoted memories, including project-scope preservation | open         | Claude | 2026-04-12 |             |
+| R9  | Codex  | P2       | src/atocore/memory/extractor_llm.py:258-259 | The R6 fallback only repairs empty project output. A wrong non-empty model project still overrides the interaction's known scope, so project attribution is improved but not yet trust-preserving. | open         | Claude | 2026-04-12 |             |
+| R10 | Codex  | P2       | docs/master-plan-status.md:31-33   | "Phase 8 - OpenClaw Integration" is fair as a baseline milestone, but not as a "primary" integration claim. `t420-openclaw/atocore.py` currently covers a narrow read-oriented subset (13 request shapes vs 32 API routes) plus fail-open health, while memory/interactions/admin write paths remain out of surface. | open         | Claude | 2026-04-12 |             |
+
+## Recent Decisions
+
+- **2026-04-12** Day 4 gate cleared: LLM-assisted extraction via `claude -p` (OAuth, no API key) is the path forward. Rule extractor stays as default for structural cues. *Proposed by:* Claude. *Ratified by:* Antoine.
+- **2026-04-12** First live triage: 16 promoted, 35 rejected from 51 LLM-extracted candidates. 31% accept rate. Active memory count 20->36. *Executed by:* Claude. *Ratified by:* Antoine.
+- **2026-04-12** No API keys allowed in AtoCore — LLM-assisted features use OAuth via `claude -p` or equivalent CLI-authenticated paths. *Proposed by:* Antoine.
+- **2026-04-12** Multi-model extraction direction: extraction/triage should be model-agnostic, with Codex/Gemini/Ollama as second-pass reviewers for robustness. *Proposed by:* Antoine.
+- **2026-04-11** Adopt this ledger as shared operating memory between Claude and Codex. *Proposed by:* Antoine. *Ratified by:* Antoine.
+- **2026-04-11** Accept Codex's 8-day mini-phase plan verbatim as Active Plan. *Proposed by:* Codex. *Ratified by:* Antoine.
+- **2026-04-11** Review findings live in `DEV-LEDGER.md` with Codex owning finding text and Claude updating status fields only. *Proposed by:* Codex. *Ratified by:* Antoine.
+- **2026-04-11** Project memories land in the pack under `--- Project Memories ---` at 25% budget ratio, gated on canonical project hint. *Proposed by:* Claude.
+- **2026-04-11** Extraction stays off the capture hot path. Batch / manual only. *Proposed by:* Antoine.
+- **2026-04-11** 4-step roadmap: extractor -> harness expansion -> Wave 2 ingestion -> OpenClaw finish. Steps 1+2 as one mini-phase. *Ratified by:* Antoine.
+- **2026-04-11** Codex branches must fork from `main`, not be orphan commits. *Proposed by:* Claude. *Agreed by:* Codex.
+
+## Session Log
+
+- **2026-04-12 Codex (audit branch `codex/audit-2026-04-12-final`)** audited `c5bad99..e2895b5` against origin/main, live Dalidou, and the OpenClaw client script. Live state checked: build `39d73e9`, harness reproducible at **16/18 PASS**, active memories **36**, and `t420-openclaw/atocore.py health` fails open correctly with `fail_open=true`. Spot-checks of Wave 2 project-state entries matched their cited vault docs. Updated R5-R8 status reality (R6 fixed by `39d73e9`), added R9-R10, and corrected Orientation `main_tip` to `e2895b5` because the ledger had drifted behind origin/main. Note: live Dalidou is still on `39d73e9`, so branch-truth and deploy-truth are not the same yet.
+- **2026-04-12 Claude** Wave 2 trusted operational ingestion + codex audit response. Read 6 vault docs, created 8 new Trusted Project State entries (p04 +2, p05 +3, p06 +3). Fixed R6 (project fallback in LLM extractor) per codex audit. Fixed misscoped p06 offline memory on live Dalidou. Merged codex/audit-2026-04-12. Switched default LLM model from haiku to sonnet. Harness 15/18 -> 16/18. Tests 278 -> 280. main_tip 146f2e4 -> 39d73e9.
+
+- **2026-04-12 Codex (audit branch `codex/audit-2026-04-12`)** audited `c5bad99..146f2e4` against code, live Dalidou, and the 36 active memories. Confirmed: `claude -p` invocation is not shell-injection-prone (`subprocess.run(args)` with no shell), off-host backup wiring matches the ledger, and R1 remains unresolved in practice. Added R5-R8. Corrected Orientation `main_tip` (`146f2e4`, not `5c69f77`) and tightened the harness note: p06-firmware-interface is a ranking-tie issue, p06-offline-design comes from a project-scope miss in live triage, and p06-tailscale is retrieved-chunk bleed rather than memory-band budget contention.
+- **2026-04-12 Claude** `06792d8..5c69f77` Day 5-8 close. Documented extractor scope (5 in-scope, 6 out-of-scope categories). Expanded harness from 6 to 18 fixtures (p04 +1, p05 +1, p06 +7, adversarial +2). Per-entry memory cap at 250 chars fixed 1 of 4 budget-contention failures. Final harness: 15/18 PASS. Mini-phase complete. Before/after: rule extractor 0% recall -> LLM 100%; harness 6/6 -> 15/18; active memories 20 -> 36.
+- **2026-04-12 Claude** `330ecfb..06792d8` (merged eval-loop branch + triage). Day 1-4 of the mini-phase completed in one session. Day 2 baseline: rule extractor 0% recall, 5 distinct miss classes. Day 4 gate cleared: LLM extractor (claude -p haiku, OAuth) hit 100% recall, 2.55 yield/interaction. Refactored from anthropic SDK to subprocess after "no API key" rule. First live triage: 51 candidates -> 16 promoted, 35 rejected. Active memories 20->36. p06-polisher went from 2 to 16 memories (firmware/telemetry architecture set). POST /memory now accepts status field. Test count 264->278.
+- **2026-04-11 Claude** `claude/extractor-eval-loop @ 7d8d599` — Day 1+2 of the mini-phase. Froze a 64-interaction snapshot (`scripts/eval_data/interactions_snapshot_2026-04-11.json`) and labeled 20 by length-stratified random sample (5 positive, 15 zero; 7 total expected candidates). Built `scripts/extractor_eval.py` as a file-based eval runner. **Day 2 baseline: rule extractor hit 0% yield / 0% recall / 0% precision on the labeled set; 5 false negatives across 5 distinct miss classes (recommendation_prose, architectural_change_summary, spec_update_announcement, layered_recommendation, alignment_assertion).** This is the Day 4 hard-stop signal arriving two days early — a single rule expansion cannot close a 5-way miss, and widening rules blindly will collapse precision. The Day 4 decision gate is escalated to Antoine for ratification before Day 3 touches any extractor code. No extractor code on main has changed.
+- **2026-04-11 Codex (ledger audit)** fixed stale `main_tip`, retargeted R1 from the API surface to the live Claude Stop hook, and formalized the review write protocol so Claude can consume findings without rewriting them.
+- **2026-04-11 Claude** `b3253f3..59331e5` (1 commit). Wired the DEV-LEDGER, added session protocol to AGENTS.md, created project-local CLAUDE.md, deleted stale `codex/port-atocore-ops-client` remote branch. No code changes, no redeploy needed.
+- **2026-04-11 Claude** `c5bad99..b3253f3` (11 commits + 1 merge). Length-aware reinforcement, project memories in pack, query-relevance memory ranking, hyphenated-identifier tokenizer, retrieval eval harness seeded, off-host backup wired end-to-end, docs synced, codex integration-pass branch merged. Harness went 0->6/6 on live Dalidou.
+- **2026-04-11 Codex (async review)** identified 2 P1s against a stale checkout. R1 was fair (extraction not automated), R2 was outdated (project memories already landed on main). Delivered the 8-day execution plan now in Active Plan.
+- **2026-04-06 Antoine** created `codex/atocore-integration-pass` with the `t420-openclaw/` workspace (merged 2026-04-11).
+
+## Working Rules
+
+- Claude builds; Codex audits. No parallel work on the same files.
+- Codex branches fork from `main`: `git fetch origin && git checkout -b codex/<topic> origin/main`.
+- P1 findings block further main commits until acknowledged in Open Review Findings.
+- Every session appends at least one Session Log line and bumps Orientation.
+- Trim Session Log and Recent Decisions to the last 20 at session end.
+- Docs in `docs/` may overclaim stale status; the ledger is the one-file source of truth for "what is true right now."
+
+## Quick Commands
+
+```bash
+# Check live state
+ssh papa@dalidou "curl -s http://localhost:8100/health"
+
+# Run the retrieval harness
+python scripts/retrieval_eval.py            # human-readable
+python scripts/retrieval_eval.py --json     # machine-readable
+
+# Deploy a new main tip
+git push origin main && ssh papa@dalidou "bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh"
+
+# Reflection-loop ops
+python scripts/atocore_client.py batch-extract '' '' 200 false   # preview
+python scripts/atocore_client.py batch-extract '' '' 200 true    # persist
+python scripts/atocore_client.py triage
+```

deploy/dalidou/cron-backup.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+#
+# deploy/dalidou/cron-backup.sh
+# ------------------------------
+# Daily backup + retention cleanup via the AtoCore API.
+#
+# Intended to run from cron on Dalidou:
+#
+#   # Daily at 03:00 UTC
+#   0 3 * * * /srv/storage/atocore/app/deploy/dalidou/cron-backup.sh >> /var/log/atocore-backup.log 2>&1
+#
+# What it does:
+#   1. Creates a runtime backup (db + registry, no chroma by default)
+#   2. Runs retention cleanup with --confirm to delete old snapshots
+#   3. Logs results to stdout (captured by cron into the log file)
+#
+# Fail-open: exits 0 even on API errors so cron doesn't send noise
+# emails. Check /var/log/atocore-backup.log for diagnostics.
+#
+# Environment variables:
+#   ATOCORE_URL             default http://127.0.0.1:8100
+#   ATOCORE_BACKUP_CHROMA   default false (set to "true" for cold chroma copy)
+#   ATOCORE_BACKUP_DIR      default /srv/storage/atocore/backups
+#   ATOCORE_BACKUP_RSYNC    optional rsync destination for off-host copies
+#                           (e.g. papa@laptop:/home/papa/atocore-backups/)
+#                           When set, the local snapshots tree is rsynced to
+#                           the destination after cleanup. Unset = skip.
+#                           SSH key auth must already be configured from this
+#                           host to the destination.
+
+set -euo pipefail
+
+ATOCORE_URL="${ATOCORE_URL:-http://127.0.0.1:8100}"
+INCLUDE_CHROMA="${ATOCORE_BACKUP_CHROMA:-false}"
+BACKUP_DIR="${ATOCORE_BACKUP_DIR:-/srv/storage/atocore/backups}"
+RSYNC_TARGET="${ATOCORE_BACKUP_RSYNC:-}"
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+log() { printf '[%s] %s\n' "$TIMESTAMP" "$*"; }
+
+log "=== AtoCore daily backup starting ==="
+
+# Step 1: Create backup
+log "Step 1: creating backup (chroma=$INCLUDE_CHROMA)"
+BACKUP_RESULT=$(curl -sf -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"include_chroma\": $INCLUDE_CHROMA}" \
+    "$ATOCORE_URL/admin/backup" 2>&1) || {
+    log "ERROR: backup creation failed: $BACKUP_RESULT"
+    exit 0
+}
+log "Backup created: $BACKUP_RESULT"
+
+# Step 2: Retention cleanup (confirm=true to actually delete)
+log "Step 2: running retention cleanup"
+CLEANUP_RESULT=$(curl -sf -X POST \
+    -H "Content-Type: application/json" \
+    -d '{"confirm": true}' \
+    "$ATOCORE_URL/admin/backup/cleanup" 2>&1) || {
+    log "ERROR: cleanup failed: $CLEANUP_RESULT"
+    exit 0
+}
+log "Cleanup result: $CLEANUP_RESULT"
+
+# Step 3: Off-host rsync (optional). Fail-open: log but don't abort
+# the cron so a laptop being offline at 03:00 UTC never turns the
+# local backup path red.
+if [[ -n "$RSYNC_TARGET" ]]; then
+    log "Step 3: rsyncing snapshots to $RSYNC_TARGET"
+    if [[ ! -d "$BACKUP_DIR/snapshots" ]]; then
+        log "WARN: $BACKUP_DIR/snapshots does not exist, skipping rsync"
+    else
+        RSYNC_OUTPUT=$(rsync -a --delete \
+            -e "ssh -o ConnectTimeout=10 -o BatchMode=yes -o StrictHostKeyChecking=accept-new" \
+            "$BACKUP_DIR/snapshots/" "$RSYNC_TARGET" 2>&1) && {
+            log "Rsync complete"
+        } || {
+            log "WARN: rsync to $RSYNC_TARGET failed (offline or auth?): $RSYNC_OUTPUT"
+        }
+    fi
+else
+    log "Step 3: ATOCORE_BACKUP_RSYNC not set, skipping off-host copy"
+fi
+
+log "=== AtoCore daily backup complete ==="

deploy/dalidou/deploy.sh

@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+#
+# deploy/dalidou/deploy.sh
+# -------------------------
+# One-shot deploy script for updating the running AtoCore container
+# on Dalidou from the current Gitea main branch.
+#
+# The script is idempotent and safe to re-run. It handles both the
+# first-time deploy (where /srv/storage/atocore/app may not yet be
+# a git checkout) and the ongoing update case (where it is).
+#
+# Usage
+# -----
+#
+#   # Normal update from main (most common)
+#   bash deploy/dalidou/deploy.sh
+#
+#   # Deploy a specific branch or tag
+#   ATOCORE_BRANCH=codex/some-feature bash deploy/dalidou/deploy.sh
+#
+#   # Dry-run: show what would happen without touching anything
+#   ATOCORE_DEPLOY_DRY_RUN=1 bash deploy/dalidou/deploy.sh
+#
+# Environment variables
+# ---------------------
+#
+#   ATOCORE_APP_DIR      default /srv/storage/atocore/app
+#   ATOCORE_GIT_REMOTE   default http://127.0.0.1:3000/Antoine/ATOCore.git
+#                        This is the local Dalidou gitea, reached
+#                        via loopback. Override only when running
+#                        the deploy from a remote host. The default
+#                        is loopback (not the hostname "dalidou")
+#                        because the hostname doesn't reliably
+#                        resolve on the host itself — Dalidou
+#                        Claude's first deploy had to work around
+#                        exactly this.
+#   ATOCORE_BRANCH       default main
+#   ATOCORE_DEPLOY_DRY_RUN  if set to 1, report only, no mutations
+#   ATOCORE_HEALTH_URL   default http://127.0.0.1:8100/health
+#
+# Safety rails
+# ------------
+#
+# - If the app dir exists but is NOT a git repo, the script renames
+#   it to <dir>.pre-git-<timestamp> before re-cloning, so you never
+#   lose the pre-existing snapshot to a git clobber.
+# - If the health check fails after restart, the script exits
+#   non-zero and prints the container logs tail for diagnosis.
+# - Dry-run mode is the default recommendation for the first deploy
+#   on a new environment: it shows the planned git operations and
+#   the compose command without actually running them.
+#
+# What this script does NOT do
+# ----------------------------
+#
+# - Does not manage secrets / .env files. The caller is responsible
+#   for placing deploy/dalidou/.env before running.
+# - Does not run a backup before deploying. Run the backup endpoint
+#   first if you want a pre-deploy snapshot.
+# - Does not roll back on health-check failure. If deploy fails,
+#   the previous container is already stopped; you need to redeploy
+#   a known-good commit to recover.
+# - Does not touch the database. The Phase 9 schema migrations in
+#   src/atocore/models/database.py::_apply_migrations are idempotent
+#   ALTER TABLE ADD COLUMN calls that run at service startup via the
+#   lifespan handler. Stale pre-Phase-9 schema is upgraded in place.
+
+set -euo pipefail
+
+APP_DIR="${ATOCORE_APP_DIR:-/srv/storage/atocore/app}"
+GIT_REMOTE="${ATOCORE_GIT_REMOTE:-http://127.0.0.1:3000/Antoine/ATOCore.git}"
+BRANCH="${ATOCORE_BRANCH:-main}"
+HEALTH_URL="${ATOCORE_HEALTH_URL:-http://127.0.0.1:8100/health}"
+DRY_RUN="${ATOCORE_DEPLOY_DRY_RUN:-0}"
+COMPOSE_DIR="$APP_DIR/deploy/dalidou"
+
+log() { printf '==> %s\n' "$*"; }
+run() {
+    if [ "$DRY_RUN" = "1" ]; then
+        printf '    [dry-run] %s\n' "$*"
+    else
+        eval "$@"
+    fi
+}
+
+log "AtoCore deploy starting"
+log "  app dir:    $APP_DIR"
+log "  git remote: $GIT_REMOTE"
+log "  branch:     $BRANCH"
+log "  health url: $HEALTH_URL"
+log "  dry run:    $DRY_RUN"
+
+# ---------------------------------------------------------------------
+# Step 0: pre-flight permission check
+# ---------------------------------------------------------------------
+#
+# If $APP_DIR exists but the current user cannot write to it (because
+# a previous manual deploy left it root-owned, for example), the git
+# fetch / reset in step 1 will fail with cryptic errors. Detect this
+# up front and give the operator a clean remediation command instead
+# of letting git produce half-state on partial failure. This was the
+# exact workaround the 2026-04-08 Dalidou redeploy needed — pre-
+# existing root ownership from the pre-phase9 manual schema fix.
+
+if [ -d "$APP_DIR" ] && [ "$DRY_RUN" != "1" ]; then
+    if [ ! -w "$APP_DIR" ] || [ ! -r "$APP_DIR/.git" ] 2>/dev/null; then
+        log "WARNING: app dir exists but may not be writable by current user"
+    fi
+    current_owner="$(stat -c '%U:%G' "$APP_DIR" 2>/dev/null || echo unknown)"
+    current_user="$(id -un 2>/dev/null || echo unknown)"
+    current_uid_gid="$(id -u 2>/dev/null):$(id -g 2>/dev/null)"
+    log "Step 0: permission check"
+    log "  app dir owner: $current_owner"
+    log "  current user:  $current_user ($current_uid_gid)"
+    # Try to write a tiny marker file. If it fails, surface a clean
+    # remediation message and exit before git produces confusing
+    # half-state.
+    marker="$APP_DIR/.deploy-permission-check"
+    if ! ( : > "$marker" ) 2>/dev/null; then
+        log "FATAL: cannot write to $APP_DIR as $current_user"
+        log ""
+        log "The app dir is owned by $current_owner and the current user"
+        log "doesn't have write permission. This usually happens after a"
+        log "manual workaround deploy that ran as root."
+        log ""
+        log "Remediation (pick the one that matches your setup):"
+        log ""
+        log "  # If you have passwordless sudo and gitea runs as UID 1000:"
+        log "  sudo chown -R 1000:1000 $APP_DIR"
+        log ""
+        log "  # If you're running deploy.sh itself as root:"
+        log "  sudo bash $0"
+        log ""
+        log "  # If neither works, do it via a throwaway container:"
+        log "  docker run --rm -v $APP_DIR:/app alpine \\"
+        log "      chown -R 1000:1000 /app"
+        log ""
+        log "Then re-run deploy.sh."
+        exit 5
+    fi
+    rm -f "$marker" 2>/dev/null || true
+fi
+
+# ---------------------------------------------------------------------
+# Step 1: make sure $APP_DIR is a proper git checkout of the branch
+# ---------------------------------------------------------------------
+
+if [ -d "$APP_DIR/.git" ]; then
+    log "Step 1: app dir is already a git checkout; fetching latest"
+    run "cd '$APP_DIR' && git fetch origin '$BRANCH'"
+    run "cd '$APP_DIR' && git reset --hard 'origin/$BRANCH'"
+else
+    log "Step 1: app dir is NOT a git checkout; converting"
+    if [ -d "$APP_DIR" ]; then
+        BACKUP="${APP_DIR}.pre-git-$(date -u +%Y%m%dT%H%M%SZ)"
+        log "       backing up existing snapshot to $BACKUP"
+        run "mv '$APP_DIR' '$BACKUP'"
+    fi
+    log "       cloning $GIT_REMOTE -> $APP_DIR (branch: $BRANCH)"
+    run "git clone --branch '$BRANCH' '$GIT_REMOTE' '$APP_DIR'"
+fi
+
+# ---------------------------------------------------------------------
+# Step 1.5: self-update re-exec guard
+# ---------------------------------------------------------------------
+#
+# When deploy.sh itself changes in the commit we just pulled, the bash
+# process running this script is still executing the OLD deploy.sh
+# from memory — git reset --hard updated the file on disk but our
+# in-memory instructions are stale. That's exactly how the first
+# 2026-04-09 Dalidou deploy silently wrote "unknown" build_sha: old
+# Step 2 logic ran against fresh source. Detect the mismatch and
+# re-exec into the fresh copy so every post-update run exercises the
+# new script.
+#
+# Guard rails:
+# - Only runs when $APP_DIR exists, holds a git checkout, and a
+#   deploy.sh exists there (i.e. after Step 1 succeeded).
+# - Uses a sentinel env var ATOCORE_DEPLOY_REEXECED=1 to make sure
+#   we only re-exec once, never recurse.
+# - Skipped in dry-run mode (no mutation).
+# - Skipped if $0 isn't a readable file (bash -c pipe inputs, etc.).
+
+if [ "$DRY_RUN" != "1" ] \
+    && [ -z "${ATOCORE_DEPLOY_REEXECED:-}" ] \
+    && [ -r "$0" ] \
+    && [ -f "$APP_DIR/deploy/dalidou/deploy.sh" ]; then
+    ON_DISK_HASH="$(sha1sum "$APP_DIR/deploy/dalidou/deploy.sh" 2>/dev/null | awk '{print $1}')"
+    RUNNING_HASH="$(sha1sum "$0" 2>/dev/null | awk '{print $1}')"
+    if [ -n "$ON_DISK_HASH" ] \
+        && [ -n "$RUNNING_HASH" ] \
+        && [ "$ON_DISK_HASH" != "$RUNNING_HASH" ]; then
+        log "Step 1.5: deploy.sh changed in the pulled commit; re-exec'ing"
+        log "  running script hash: $RUNNING_HASH"
+        log "  on-disk script hash: $ON_DISK_HASH"
+        log "  re-exec -> $APP_DIR/deploy/dalidou/deploy.sh"
+        export ATOCORE_DEPLOY_REEXECED=1
+        exec bash "$APP_DIR/deploy/dalidou/deploy.sh" "$@"
+    fi
+fi
+
+# ---------------------------------------------------------------------
+# Step 2: capture build provenance to pass to the container
+# ---------------------------------------------------------------------
+#
+# We compute the full SHA, the short SHA, the UTC build timestamp,
+# and the source branch. These get exported as env vars before
+# `docker compose up -d --build` so the running container can read
+# them at startup and report them via /health. The post-deploy
+# verification step (Step 6) reads /health and compares the
+# reported SHA against this value to detect any silent drift.
+
+log "Step 2: capturing build provenance"
+if [ "$DRY_RUN" != "1" ] && [ -d "$APP_DIR/.git" ]; then
+    DEPLOYING_SHA_FULL="$(cd "$APP_DIR" && git rev-parse HEAD)"
+    DEPLOYING_SHA="$(echo "$DEPLOYING_SHA_FULL" | cut -c1-7)"
+    DEPLOYING_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    DEPLOYING_BRANCH="$BRANCH"
+    log "  commit:    $DEPLOYING_SHA ($DEPLOYING_SHA_FULL)"
+    log "  built at:  $DEPLOYING_TIME"
+    log "  branch:    $DEPLOYING_BRANCH"
+    ( cd "$APP_DIR" && git log --oneline -1 ) | sed 's/^/  /'
+    export ATOCORE_BUILD_SHA="$DEPLOYING_SHA_FULL"
+    export ATOCORE_BUILD_TIME="$DEPLOYING_TIME"
+    export ATOCORE_BUILD_BRANCH="$DEPLOYING_BRANCH"
+else
+    log "  [dry-run] would read git log from $APP_DIR"
+    DEPLOYING_SHA="dry-run"
+    DEPLOYING_SHA_FULL="dry-run"
+fi
+
+# ---------------------------------------------------------------------
+# Step 3: preserve the .env file (it's not in git)
+# ---------------------------------------------------------------------
+
+ENV_FILE="$COMPOSE_DIR/.env"
+if [ "$DRY_RUN" != "1" ] && [ ! -f "$ENV_FILE" ]; then
+    log "Step 3: WARNING — $ENV_FILE does not exist"
+    log "       the compose workflow needs this file to map mount points"
+    log "       copy deploy/dalidou/.env.example to $ENV_FILE and edit it"
+    log "       before re-running this script"
+    exit 2
+fi
+
+# ---------------------------------------------------------------------
+# Step 4: rebuild and restart the container
+# ---------------------------------------------------------------------
+
+log "Step 4: rebuilding and restarting the atocore container"
+run "cd '$COMPOSE_DIR' && docker compose up -d --build"
+
+if [ "$DRY_RUN" = "1" ]; then
+    log "dry-run complete — no mutations performed"
+    exit 0
+fi
+
+# ---------------------------------------------------------------------
+# Step 5: wait for the service to come up and pass the health check
+# ---------------------------------------------------------------------
+
+log "Step 5: waiting for /health to respond"
+for i in 1 2 3 4 5 6 7 8 9 10; do
+    if curl -fsS "$HEALTH_URL" > /tmp/atocore-health.json 2>/dev/null; then
+        log "       service is responding"
+        break
+    fi
+    log "       not ready yet ($i/10); waiting 3s"
+    sleep 3
+done
+
+if ! curl -fsS "$HEALTH_URL" > /tmp/atocore-health.json 2>/dev/null; then
+    log "FATAL: service did not come up within 30 seconds"
+    log "       container logs (last 50 lines):"
+    cd "$COMPOSE_DIR" && docker compose logs --tail=50 atocore || true
+    exit 3
+fi
+
+# ---------------------------------------------------------------------
+# Step 6: verify the deployed build matches what we just shipped
+# ---------------------------------------------------------------------
+#
+# Two layers of comparison:
+#
+# - code_version: matches src/atocore/__init__.py::__version__.
+#   Coarse: any commit between version bumps reports the same value.
+# - build_sha: full git SHA the container was built from. Set as
+#   an env var by Step 2 above and read by /health from
+#   ATOCORE_BUILD_SHA. This is the precise drift signal — if the
+#   live build_sha doesn't match $DEPLOYING_SHA_FULL, the build
+#   didn't pick up the new source.
+
+log "Step 6: verifying deployed build"
+log "  /health response:"
+if command -v jq >/dev/null 2>&1; then
+    jq . < /tmp/atocore-health.json | sed 's/^/    /'
+    REPORTED_VERSION="$(jq -r '.code_version // .version' < /tmp/atocore-health.json)"
+    REPORTED_SHA="$(jq -r '.build_sha // "unknown"' < /tmp/atocore-health.json)"
+    REPORTED_BUILD_TIME="$(jq -r '.build_time // "unknown"' < /tmp/atocore-health.json)"
+else
+    cat /tmp/atocore-health.json | sed 's/^/    /'
+    echo
+    REPORTED_VERSION="$(grep -o '"code_version":"[^"]*"' /tmp/atocore-health.json | head -1 | cut -d'"' -f4)"
+    if [ -z "$REPORTED_VERSION" ]; then
+        REPORTED_VERSION="$(grep -o '"version":"[^"]*"' /tmp/atocore-health.json | head -1 | cut -d'"' -f4)"
+    fi
+    REPORTED_SHA="$(grep -o '"build_sha":"[^"]*"' /tmp/atocore-health.json | head -1 | cut -d'"' -f4)"
+    REPORTED_SHA="${REPORTED_SHA:-unknown}"
+    REPORTED_BUILD_TIME="$(grep -o '"build_time":"[^"]*"' /tmp/atocore-health.json | head -1 | cut -d'"' -f4)"
+    REPORTED_BUILD_TIME="${REPORTED_BUILD_TIME:-unknown}"
+fi
+
+EXPECTED_VERSION="$(grep -oE "__version__ = \"[^\"]+\"" "$APP_DIR/src/atocore/__init__.py" | head -1 | cut -d'"' -f2)"
+
+log "  Layer 1 — coarse version:"
+log "    expected code_version: $EXPECTED_VERSION (from src/atocore/__init__.py)"
+log "    reported code_version: $REPORTED_VERSION (from live /health)"
+
+if [ "$REPORTED_VERSION" != "$EXPECTED_VERSION" ]; then
+    log "FATAL: code_version mismatch"
+    log "       the container may not have picked up the new image"
+    log "       try: docker compose down && docker compose up -d --build"
+    exit 4
+fi
+
+log "  Layer 2 — precise build SHA:"
+log "    expected build_sha: $DEPLOYING_SHA_FULL (from this deploy.sh run)"
+log "    reported build_sha: $REPORTED_SHA (from live /health)"
+log "    reported build_time: $REPORTED_BUILD_TIME"
+
+if [ "$REPORTED_SHA" != "$DEPLOYING_SHA_FULL" ]; then
+    log "FATAL: build_sha mismatch"
+    log "       the live container is reporting a different commit than"
+    log "       the one this deploy.sh run just shipped. Possible causes:"
+    log "       - the container is using a cached image instead of the"
+    log "         freshly-built one (try: docker compose build --no-cache)"
+    log "       - the env vars didn't propagate (check that"
+    log "         deploy/dalidou/docker-compose.yml has the environment"
+    log "         section with ATOCORE_BUILD_SHA)"
+    log "       - another process restarted the container between the"
+    log "         build and the health check"
+    exit 6
+fi
+
+log "Deploy complete."
+log "  commit:       $DEPLOYING_SHA ($DEPLOYING_SHA_FULL)"
+log "  code_version: $REPORTED_VERSION"
+log "  build_sha:    $REPORTED_SHA"
+log "  build_time:   $REPORTED_BUILD_TIME"
+log "  health:       ok"

deploy/dalidou/docker-compose.yml

@@ -9,6 +9,15 @@ services:
       - "${ATOCORE_PORT:-8100}:8100"
     env_file:
       - .env
+    environment:
+      # Build provenance — set by deploy/dalidou/deploy.sh on each
+      # rebuild so /health can report exactly which commit is live.
+      # Defaults to 'unknown' for direct `docker compose up` runs that
+      # bypass deploy.sh; in that case the operator should run
+      # deploy.sh instead so the deployed SHA is recorded.
+      ATOCORE_BUILD_SHA: "${ATOCORE_BUILD_SHA:-unknown}"
+      ATOCORE_BUILD_TIME: "${ATOCORE_BUILD_TIME:-unknown}"
+      ATOCORE_BUILD_BRANCH: "${ATOCORE_BUILD_BRANCH:-unknown}"
     volumes:
       - ${ATOCORE_DB_DIR}:${ATOCORE_DB_DIR}
       - ${ATOCORE_CHROMA_DIR}:${ATOCORE_CHROMA_DIR}

deploy/hooks/capture_stop.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Claude Code Stop hook: capture interaction to AtoCore.
+
+Reads the Stop hook JSON from stdin, extracts the last user prompt
+from the transcript JSONL, and POSTs to the AtoCore /interactions
+endpoint with reinforcement enabled (no extraction).
+
+Fail-open: always exits 0, logs errors to stderr only.
+
+Environment variables:
+    ATOCORE_URL     Base URL of the AtoCore instance (default: http://dalidou:8100)
+    ATOCORE_CAPTURE_DISABLED  Set to "1" to disable capture (kill switch)
+
+Usage in ~/.claude/settings.json:
+    "Stop": [{
+        "matcher": "",
+        "hooks": [{
+            "type": "command",
+            "command": "python /path/to/capture_stop.py",
+            "timeout": 15
+        }]
+    }]
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+ATOCORE_URL = os.environ.get("ATOCORE_URL", "http://dalidou:8100")
+TIMEOUT_SECONDS = 10
+
+# Minimum prompt length to bother capturing. Single-word acks,
+# slash commands, and empty lines aren't useful interactions.
+MIN_PROMPT_LENGTH = 15
+
+# Maximum response length to capture. Truncate very long assistant
+# responses to keep the interactions table manageable.
+MAX_RESPONSE_LENGTH = 50_000
+
+
+def main() -> None:
+    """Entry point. Always exits 0."""
+    try:
+        _capture()
+    except Exception as exc:
+        print(f"capture_stop: {exc}", file=sys.stderr)
+
+
+def _capture() -> None:
+    if os.environ.get("ATOCORE_CAPTURE_DISABLED") == "1":
+        return
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return
+
+    hook_data = json.loads(raw)
+
+    session_id = hook_data.get("session_id", "")
+    assistant_message = hook_data.get("last_assistant_message", "")
+    transcript_path = hook_data.get("transcript_path", "")
+    cwd = hook_data.get("cwd", "")
+
+    prompt = _extract_last_user_prompt(transcript_path)
+    if not prompt or len(prompt.strip()) < MIN_PROMPT_LENGTH:
+        return
+
+    response = assistant_message or ""
+    if len(response) > MAX_RESPONSE_LENGTH:
+        response = response[:MAX_RESPONSE_LENGTH] + "\n\n[truncated]"
+
+    project = _infer_project(cwd)
+
+    payload = {
+        "prompt": prompt,
+        "response": response,
+        "client": "claude-code",
+        "session_id": session_id,
+        "project": project,
+        "reinforce": True,
+    }
+
+    body = json.dumps(payload, ensure_ascii=True).encode("utf-8")
+    req = urllib.request.Request(
+        f"{ATOCORE_URL}/interactions",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    resp = urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS)
+    result = json.loads(resp.read().decode("utf-8"))
+    print(
+        f"capture_stop: recorded interaction {result.get('id', '?')} "
+        f"(project={project or 'none'}, prompt_chars={len(prompt)}, "
+        f"response_chars={len(response)})",
+        file=sys.stderr,
+    )
+
+
+def _extract_last_user_prompt(transcript_path: str) -> str:
+    """Read the JSONL transcript and return the last real user prompt.
+
+    Skips meta messages (isMeta=True) and system/command messages
+    (content starting with '<').
+    """
+    if not transcript_path:
+        return ""
+
+    # Normalize path for the current OS
+    path = os.path.normpath(transcript_path)
+    if not os.path.isfile(path):
+        return ""
+
+    last_prompt = ""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                if entry.get("type") != "user":
+                    continue
+                if entry.get("isMeta", False):
+                    continue
+
+                msg = entry.get("message", {})
+                if not isinstance(msg, dict):
+                    continue
+
+                content = msg.get("content", "")
+
+                if isinstance(content, str):
+                    text = content.strip()
+                elif isinstance(content, list):
+                    # Content blocks: extract text blocks
+                    parts = []
+                    for block in content:
+                        if isinstance(block, str):
+                            parts.append(block)
+                        elif isinstance(block, dict) and block.get("type") == "text":
+                            parts.append(block.get("text", ""))
+                    text = "\n".join(parts).strip()
+                else:
+                    continue
+
+                # Skip system/command XML and very short messages
+                if text.startswith("<") or len(text) < MIN_PROMPT_LENGTH:
+                    continue
+
+                last_prompt = text
+    except OSError:
+        pass
+
+    return last_prompt
+
+
+# Project inference from working directory.
+# Maps known repo paths to AtoCore project IDs. The user can extend
+# this table or replace it with a registry lookup later.
+_PROJECT_PATH_MAP: dict[str, str] = {
+    # Add mappings as needed, e.g.:
+    # "C:\\Users\\antoi\\gigabit": "p04-gigabit",
+    # "C:\\Users\\antoi\\interferometer": "p05-interferometer",
+}
+
+
+def _infer_project(cwd: str) -> str:
+    """Try to map the working directory to an AtoCore project."""
+    if not cwd:
+        return ""
+    norm = os.path.normpath(cwd).lower()
+    for path_prefix, project_id in _PROJECT_PATH_MAP.items():
+        if norm.startswith(os.path.normpath(path_prefix).lower()):
+            return project_id
+    return ""
+
+
+if __name__ == "__main__":
+    main()

docs/architecture/llm-client-integration.md

@@ -0,0 +1,333 @@
+# LLM Client Integration (the layering)
+
+## Why this document exists
+
+AtoCore must be reachable from many different LLM client contexts:
+
+- **OpenClaw** on the T420 (already integrated via the read-only
+  helper skill at `/home/papa/clawd/skills/atocore-context/`)
+- **Claude Code** on the laptop (via the slash command shipped in
+  this repo at `.claude/commands/atocore-context.md`)
+- **Codex** sessions (future)
+- **Direct API consumers** — scripts, Python code, ad-hoc curl
+- **The eventual MCP server** when it's worth building
+
+Without an explicit layering rule, every new client tends to
+reimplement the same routing logic (project detection, context
+build, retrieval audit, project-state inspection) in slightly
+different ways. That is exactly what almost happened in the first
+draft of the Claude Code slash command, which started as a curl +
+jq script that duplicated capabilities the existing operator client
+already had.
+
+This document defines the layering so future clients don't repeat
+that mistake.
+
+## The layering
+
+Three layers, top to bottom:
+
+```
+        +----------------------------------------------------+
+        |  Per-agent thin frontends                          |
+        |                                                    |
+        |  - Claude Code slash command                       |
+        |    (.claude/commands/atocore-context.md)           |
+        |  - OpenClaw helper skill                           |
+        |    (/home/papa/clawd/skills/atocore-context/)      |
+        |  - Codex skill (future)                            |
+        |  - MCP server (future)                             |
+        +----------------------------------------------------+
+                              |
+                              | shells out to / imports
+                              v
+        +----------------------------------------------------+
+        |  Shared operator client                            |
+        |  scripts/atocore_client.py                         |
+        |                                                    |
+        |  - subcommands for stable AtoCore operations       |
+        |  - fail-open on network errors                     |
+        |  - consistent JSON output across all subcommands   |
+        |  - environment-driven configuration                |
+        |    (ATOCORE_BASE_URL, ATOCORE_TIMEOUT_SECONDS,     |
+        |     ATOCORE_REFRESH_TIMEOUT_SECONDS,               |
+        |     ATOCORE_FAIL_OPEN)                             |
+        +----------------------------------------------------+
+                              |
+                              | HTTP
+                              v
+        +----------------------------------------------------+
+        |  AtoCore HTTP API                                  |
+        |  src/atocore/api/routes.py                         |
+        |                                                    |
+        |  - the universal interface to AtoCore              |
+        |  - everything else above is glue                   |
+        +----------------------------------------------------+
+```
+
+## The non-negotiable rules
+
+These rules are what make the layering work.
+
+### Rule 1 — every per-agent frontend is a thin wrapper
+
+A per-agent frontend exists to do exactly two things:
+
+1. **Translate the agent platform's command/skill format** into an
+   invocation of the shared client (or a small sequence of them)
+2. **Render the JSON response** into whatever shape the agent
+   platform wants (markdown for Claude Code, plaintext for
+   OpenClaw, MCP tool result for an MCP server, etc.)
+
+Everything else — talking to AtoCore, project detection, retrieval
+audit, fail-open behavior, configuration — is the **shared
+client's** job.
+
+If a per-agent frontend grows logic beyond the two responsibilities
+above, that logic is in the wrong place. It belongs in the shared
+client where every other frontend gets to use it.
+
+### Rule 2 — the shared client never duplicates the API
+
+The shared client is allowed to **compose** API calls (e.g.
+`auto-context` calls `detect-project` then `context-build`), but
+it never reimplements API logic. If a useful operation can't be
+expressed via the existing API endpoints, the right fix is to
+extend the API, not to embed the logic in the client.
+
+This rule keeps the API as the single source of truth for what
+AtoCore can do.
+
+### Rule 3 — the shared client only exposes stable operations
+
+A subcommand only makes it into the shared client when:
+
+- the API endpoint behind it has been exercised by at least one
+  real workflow
+- the request and response shapes are unlikely to change
+- the operation is one that more than one frontend will plausibly
+  want
+
+This rule keeps the client surface stable so frontends don't have
+to chase changes. New endpoints land in the API first, get
+exercised in real use, and only then get a client subcommand.
+
+## What's in scope for the shared client today
+
+The currently shipped scope (per `scripts/atocore_client.py`):
+
+### Stable operations (shipped since the client was introduced)
+
+| Subcommand | Purpose | API endpoint(s) |
+|---|---|---|
+| `health` | service status, mount + source readiness | `GET /health` |
+| `sources` | enabled source roots and their existence | `GET /sources` |
+| `stats` | document/chunk/vector counts | `GET /stats` |
+| `projects` | registered projects | `GET /projects` |
+| `project-template` | starter shape for a new project | `GET /projects/template` |
+| `propose-project` | preview a registration | `POST /projects/proposal` |
+| `register-project` | persist a registration | `POST /projects/register` |
+| `update-project` | update an existing registration | `PUT /projects/{name}` |
+| `refresh-project` | re-ingest a project's roots | `POST /projects/{name}/refresh` |
+| `project-state` | list trusted state for a project | `GET /project/state/{name}` |
+| `project-state-set` | curate trusted state | `POST /project/state` |
+| `project-state-invalidate` | supersede trusted state | `DELETE /project/state` |
+| `query` | raw retrieval | `POST /query` |
+| `context-build` | full context pack | `POST /context/build` |
+| `auto-context` | detect-project then context-build | composes `/projects` + `/context/build` |
+| `detect-project` | match a prompt to a registered project | composes `/projects` + local regex |
+| `audit-query` | retrieval-quality audit with classification | composes `/query` + local labelling |
+| `debug-context` | last context pack inspection | `GET /debug/context` |
+| `ingest-sources` | ingest configured source dirs | `POST /ingest/sources` |
+
+### Phase 9 reflection loop (shipped after migration safety work)
+
+These were explicitly deferred in earlier versions of this doc
+pending "exercised workflow". The constraint was real — premature
+API freeze would have made it harder to iterate on the ergonomics —
+but the deferral ran into a bootstrap problem: you can't exercise
+the workflow in real Claude Code sessions without a usable client
+surface to drive it from. The fix is to ship a minimal Phase 9
+surface now and treat it as stable-but-refinable: adding new
+optional parameters is fine, renaming subcommands is not.
+
+| Subcommand | Purpose | API endpoint(s) |
+|---|---|---|
+| `capture` | record one interaction round-trip | `POST /interactions` |
+| `extract` | run the rule-based extractor (preview or persist) | `POST /interactions/{id}/extract` |
+| `reinforce-interaction` | backfill reinforcement on an existing interaction | `POST /interactions/{id}/reinforce` |
+| `list-interactions` | paginated list with filters | `GET /interactions` |
+| `get-interaction` | fetch one interaction by id | `GET /interactions/{id}` |
+| `queue` | list the candidate review queue | `GET /memory?status=candidate` |
+| `promote` | move a candidate memory to active | `POST /memory/{id}/promote` |
+| `reject` | mark a candidate memory invalid | `POST /memory/{id}/reject` |
+
+All 8 Phase 9 subcommands have test coverage in
+`tests/test_atocore_client.py` via mocked `request()`, including
+an end-to-end test that drives the full capture → extract → queue
+→ promote/reject cycle through the client.
+
+### Coverage summary
+
+That covers everything in the "stable operations" set AND the
+full Phase 9 reflection loop: project lifecycle, ingestion,
+project-state curation, retrieval, context build,
+retrieval-quality audit, health and stats inspection, interaction
+capture, candidate extraction, candidate review queue.
+
+## What's intentionally NOT in scope today
+
+Two families of operations remain deferred:
+
+### 1. Backup and restore admin operations
+
+Phase 9 Commit B shipped these endpoints:
+
+- `POST /admin/backup` (with `include_chroma`)
+- `GET /admin/backup` (list)
+- `GET /admin/backup/{stamp}/validate`
+
+The backup endpoints are stable, but the documented operational
+procedure (`docs/backup-restore-procedure.md`) intentionally uses
+direct curl rather than the shared client. The reason is that
+backup operations are *administrative* and benefit from being
+explicit about which instance they're targeting, with no
+fail-open behavior. The shared client's fail-open default would
+hide a real backup failure.
+
+If we later decide to add backup commands to the shared client,
+they would set `ATOCORE_FAIL_OPEN=false` for the duration of the
+call so the operator gets a real error on failure rather than a
+silent fail-open envelope.
+
+### 2. Engineering layer entity operations
+
+The engineering layer is in planning, not implementation. When
+V1 ships per `engineering-v1-acceptance.md`, the shared client
+will gain entity, relationship, conflict, and Mirror commands.
+None of those exist as stable contracts yet, so they are not in
+the shared client today.
+
+## How a new agent platform integrates
+
+When a new LLM client needs AtoCore (e.g. Codex, ChatGPT custom
+GPT, a Cursor extension), the integration recipe is:
+
+1. **Don't reimplement.** Don't write a new HTTP client. Use the
+   shared client.
+2. **Write a thin frontend** that translates the platform's
+   command/skill format into a shell call to
+   `python scripts/atocore_client.py <subcommand> <args...>`.
+3. **Render the JSON response** in the platform's preferred shape.
+4. **Inherit fail-open and env-var behavior** from the shared
+   client. Don't override unless the platform explicitly needs
+   to (e.g. an admin tool that wants to see real errors).
+5. **If a needed capability is missing**, propose adding it to
+   the shared client. If the underlying API endpoint also
+   doesn't exist, propose adding it to the API first. Don't
+   add the logic to your frontend.
+
+The Claude Code slash command in this repo is a worked example:
+~50 lines of markdown that does argument parsing, calls the
+shared client, and renders the result. It contains zero AtoCore
+business logic of its own.
+
+## How OpenClaw fits
+
+OpenClaw's helper skill at `/home/papa/clawd/skills/atocore-context/`
+on the T420 currently has its own implementation of `auto-context`,
+`detect-project`, and the project lifecycle commands. It predates
+this layering doc.
+
+The right long-term shape is to **refactor the OpenClaw helper to
+shell out to the shared client** instead of duplicating the
+routing logic. This isn't urgent because:
+
+- OpenClaw's helper works today and is in active use
+- The duplication is on the OpenClaw side; AtoCore itself is not
+  affected
+- The shared client and the OpenClaw helper are in different
+  repos (AtoCore vs OpenClaw clawd), so the refactor is a
+  cross-repo coordination
+
+The refactor is queued as a follow-up. Until then, **the OpenClaw
+helper and the Claude Code slash command are parallel
+implementations** of the same idea. The shared client is the
+canonical backbone going forward; new clients should follow the
+new pattern even though the existing OpenClaw helper still has
+its own.
+
+## How this connects to the master plan
+
+| Layer | Phase home | Status |
+|---|---|---|
+| AtoCore HTTP API | Phases 0/0.5/1/2/3/5/7/9 | shipped |
+| Shared operator client (`scripts/atocore_client.py`) | implicitly Phase 8 (OpenClaw integration) infrastructure | shipped via codex/port-atocore-ops-client merge |
+| OpenClaw helper skill (T420) | Phase 8 — partial | shipped (own implementation, refactor queued) |
+| Claude Code slash command (this repo) | precursor to Phase 11 (multi-model) | shipped (refactored to use the shared client) |
+| Codex skill | Phase 11 | future |
+| MCP server | Phase 11 | future |
+| Web UI / dashboard | Phase 11+ | future |
+
+The shared client is the **substrate Phase 11 will build on**.
+Every new client added in Phase 11 should be a thin frontend on
+the shared client, not a fresh reimplementation.
+
+## Versioning and stability
+
+The shared client's subcommand surface is **stable**. Adding new
+subcommands is non-breaking. Changing or removing existing
+subcommands is breaking and would require a coordinated update
+of every frontend that depends on them.
+
+The current shared client has no explicit version constant; the
+implicit contract is "the subcommands and JSON shapes documented
+in this file". When the client surface meaningfully changes,
+add a `CLIENT_VERSION = "x.y.z"` constant to
+`scripts/atocore_client.py` and bump it per semver:
+
+- patch: bug fixes, no surface change
+- minor: new subcommands or new optional fields
+- major: removed subcommands, renamed fields, changed defaults
+
+## Open follow-ups
+
+1. **Refactor the OpenClaw helper** to shell out to the shared
+   client. Cross-repo coordination, not blocking anything in
+   AtoCore itself. With the Phase 9 subcommands now in the shared
+   client, the OpenClaw refactor can reuse all the reflection-loop
+   work instead of duplicating it.
+2. **Real-usage validation of the Phase 9 loop**, now that the
+   client surface exists. First capture → extract → review cycle
+   against the live Dalidou instance, likely via the Claude Code
+   slash command flow. Findings feed back into subcommand
+   refinement (new optional flags are fine, renames require a
+   semver bump).
+3. **Add backup admin subcommands** if and when we decide the
+   shared client should be the canonical backup operator
+   interface (with fail-open disabled for admin commands).
+4. **Add engineering-layer entity subcommands** as part of the
+   engineering V1 implementation sprint, per
+   `engineering-v1-acceptance.md`.
+5. **Tag a `CLIENT_VERSION` constant** the next time the shared
+   client surface meaningfully changes. Today's surface with the
+   Phase 9 loop added is the v0.2.0 baseline (v0.1.0 was the
+   stable-ops-only version).
+
+## TL;DR
+
+- AtoCore HTTP API is the universal interface
+- `scripts/atocore_client.py` is the canonical shared Python
+  backbone for stable AtoCore operations
+- Per-agent frontends (Claude Code slash command, OpenClaw
+  helper, future Codex skill, future MCP server) are thin
+  wrappers that shell out to the shared client
+- The shared client today covers project lifecycle, ingestion,
+  retrieval, context build, project-state, retrieval audit, AND
+  the full Phase 9 reflection loop (capture / extract /
+  reinforce / list / queue / promote / reject)
+- Backup admin and engineering-entity commands remain deferred
+- The OpenClaw helper is currently a parallel implementation and
+  the refactor to the shared client is a queued follow-up
+- New LLM clients should never reimplement HTTP calls — they
+  follow the shell-out pattern documented here

docs/architecture/project-identity-canonicalization.md

@@ -0,0 +1,462 @@
+# Project Identity Canonicalization
+
+## Why this document exists
+
+AtoCore identifies projects by name in many places: trusted state
+rows, memories, captured interactions, query/context API parameters,
+extractor candidates, future engineering entities. Without an
+explicit rule, every callsite would have to remember to canonicalize
+project names through the registry — and the recent codex review
+caught exactly the bug class that follows when one of them forgets.
+
+The fix landed in `fb6298a` and works correctly today. This document
+exists to make the rule **explicit and discoverable** so the
+engineering layer V1 implementation, future entity write paths, and
+any new agent integration don't reintroduce the same fragmentation
+when nobody is looking.
+
+## The contract
+
+> **Every read/write that takes a project name MUST canonicalize it
+> through `resolve_project_name()` before the value crosses a service
+> boundary.**
+
+The boundary is wherever a project name becomes a database row, a
+query filter, an attribute on a stored object, or a key for any
+lookup. The canonicalization happens **once**, at that boundary,
+before the underlying storage primitive is called.
+
+Symbolically:
+
+```
+HTTP layer (raw user input)
+    ↓
+   service entry point
+    ↓
+   project_name = resolve_project_name(project_name)   ← ONLY canonical from this point
+    ↓
+   storage / queries / further service calls
+```
+
+The rule is intentionally simple. There's no per-call exception,
+no "trust me, the caller already canonicalized it" shortcut, no
+opt-out flag. Every service-layer entry point applies the helper
+the moment it receives a project name from outside the service.
+
+## The helper
+
+```python
+# src/atocore/projects/registry.py
+
+def resolve_project_name(name: str | None) -> str:
+    """Canonicalize a project name through the registry.
+
+    Returns the canonical project_id if the input matches any
+    registered project's id or alias. Returns the input unchanged
+    when it's empty or not in the registry — the second case keeps
+    backwards compatibility with hand-curated state, memories, and
+    interactions that predate the registry, or for projects that
+    are intentionally not registered.
+    """
+    if not name:
+        return name or ""
+    project = get_registered_project(name)
+    if project is not None:
+        return project.project_id
+    return name
+```
+
+Three behaviors worth keeping in mind:
+
+1. **Empty / None input → empty string output.** Callers don't have
+   to pre-check; passing `""` or `None` to a query filter still
+   works as "no project scope".
+2. **Registered alias → canonical project_id.** The helper does the
+   case-insensitive lookup and returns the project's `id` field
+   (e.g. `"p05" → "p05-interferometer"`).
+3. **Unregistered name → input unchanged.** This is the
+   backwards-compatibility path. Hand-curated state, memories, or
+   interactions created under a name that isn't in the registry
+   keep working. The retrieval is then "best effort" — the raw
+   string is used as the SQL key, which still finds the row that
+   was stored under the same raw string. This path exists so the
+   engineering layer V1 doesn't have to also be a data migration.
+
+## Where the helper is currently called
+
+As of `fb6298a`, the helper is invoked at exactly these eight
+service-layer entry points:
+
+| Module | Function | What gets canonicalized |
+|---|---|---|
+| `src/atocore/context/builder.py` | `build_context` | the `project_hint` parameter, before the trusted state lookup |
+| `src/atocore/context/project_state.py` | `set_state` | `project_name`, before `ensure_project()` |
+| `src/atocore/context/project_state.py` | `get_state` | `project_name`, before the SQL lookup |
+| `src/atocore/context/project_state.py` | `invalidate_state` | `project_name`, before the SQL lookup |
+| `src/atocore/interactions/service.py` | `record_interaction` | `project`, before insert |
+| `src/atocore/interactions/service.py` | `list_interactions` | `project` filter parameter, before WHERE clause |
+| `src/atocore/memory/service.py` | `create_memory` | `project`, before insert |
+| `src/atocore/memory/service.py` | `get_memories` | `project` filter parameter, before WHERE clause |
+
+Every one of those is the **first** thing the function does after
+input validation. There is no path through any of those eight
+functions where a project name reaches storage without passing
+through `resolve_project_name`.
+
+## Where the helper is NOT called (and why that's correct)
+
+These places intentionally do not canonicalize:
+
+1. **`update_memory`'s project field.** The API does not allow
+   changing a memory's project after creation, so there's no
+   project to canonicalize. The function only updates `content`,
+   `confidence`, and `status`.
+2. **The retriever's `_project_match_boost` substring matcher.** It
+   already calls `get_registered_project` internally to expand the
+   hint into the candidate set (canonical id + all aliases + last
+   path segments). It accepts the raw hint by design.
+3. **`_rank_chunks`'s secondary substring boost in
+   `builder.py`.** Still uses the raw hint. This is a multiplicative
+   factor on top of correct retrieval, not a filter, so it cannot
+   drop relevant chunks. Tracked as a future cleanup but not
+   critical.
+4. **Direct SQL queries for the projects table itself** (e.g.
+   `ensure_project`'s lookup). These are intentional case-insensitive
+   raw lookups against the column the canonical id is stored in.
+   `set_state` already canonicalized before reaching `ensure_project`,
+   so the value passed is the canonical id by definition.
+5. **Hand-authored project names that aren't in the registry.**
+   The helper returns those unchanged. This is the backwards-compat
+   path mentioned above; it is *not* a violation of the rule, it's
+   the rule applied to a name with no registry record.
+
+## Why this is the trust hierarchy in action
+
+The whole point of AtoCore is the trust hierarchy from the operating
+model:
+
+1. Trusted Project State (Layer 3) is the most authoritative layer
+2. Memories (active) are second
+3. Source chunks (raw retrieved content) are last
+
+If a caller passes the alias `p05` and Layer 3 was written under
+`p05-interferometer`, and the lookup fails to find the canonical
+row, **the trust hierarchy collapses**. The most-authoritative
+layer is silently invisible to the caller. The system would still
+return *something* — namely, lower-trust retrieved chunks — and the
+human would never know they got a degraded answer.
+
+The canonicalization helper is what makes the trust hierarchy
+**dependable**. Layer 3 is supposed to win every time. To win it
+has to be findable. To be findable, the lookup key has to match
+how the row was stored. And the only way to guarantee that match
+across every entry point is to canonicalize at every boundary.
+
+## Compatibility gap: legacy alias-keyed rows
+
+The canonicalization rule fixes new writes going forward, but it
+does NOT fix rows that were already written under a registered
+alias before `fb6298a` landed. Those rows have a real, concrete
+gap that must be closed by a one-time migration before the
+engineering layer V1 ships.
+
+The exact failure mode:
+
+```
+        time T0 (before fb6298a):
+            POST /project/state {project: "p05", ...}
+            -> set_state("p05", ...)        # no canonicalization
+            -> ensure_project("p05")        # creates a "p05" row
+            -> writes state with project_id pointing at the "p05" row
+
+        time T1 (after fb6298a):
+            POST /project/state {project: "p05", ...}     (or any read)
+            -> set_state("p05", ...)
+            -> resolve_project_name("p05") -> "p05-interferometer"
+            -> ensure_project("p05-interferometer")        # creates a SECOND row
+            -> writes new state under the canonical row
+            -> the T0 state is still in the "p05" row, INVISIBLE to every
+               canonicalized read
+```
+
+The unregistered-name fallback path saves you when the project was
+never in the registry: a row stored under `"orphan-project"` is read
+back via `"orphan-project"`, both pass through `resolve_project_name`
+unchanged, and the strings line up. **It does not save you when the
+name is a registered alias** — the helper rewrites the read key but
+not the storage key, and the legacy row becomes invisible.
+
+What is at risk on the live Dalidou DB:
+
+1. **`projects` table**: any rows whose `name` column matches a
+   registered alias (one row per alias actually written under
+   before the fix landed). These shadow the canonical project row
+   and silently fragment the projects namespace.
+2. **`project_state` table**: any rows whose `project_id` points
+   at one of those shadow project rows. **This is the highest-risk
+   case** because it directly defeats the trust hierarchy: Layer 3
+   trusted state becomes invisible to every canonicalized lookup.
+3. **`memories` table**: any rows whose `project` column is a
+   registered alias. Reinforcement and extraction queries will
+   miss them.
+4. **`interactions` table**: any rows whose `project` column is a
+   registered alias. Listing and downstream reflection will miss
+   them.
+
+How to find out the actual blast radius on the live Dalidou DB:
+
+```sql
+-- inspect the projects table for alias-shadow rows
+SELECT id, name FROM projects;
+
+-- count alias-keyed memories per known alias
+SELECT project, COUNT(*) FROM memories
+  WHERE project IN ('p04','p05','p06','gigabit','interferometer','polisher','ato core')
+  GROUP BY project;
+
+-- count alias-keyed interactions
+SELECT project, COUNT(*) FROM interactions
+  WHERE project IN ('p04','p05','p06','gigabit','interferometer','polisher','ato core')
+  GROUP BY project;
+
+-- count alias-shadowed project_state rows by project name
+SELECT p.name, COUNT(*) FROM project_state ps
+  JOIN projects p ON ps.project_id = p.id
+  WHERE p.name IN ('p04','p05','p06','gigabit','interferometer','polisher','ato core');
+```
+
+The migration that closes the gap has to:
+
+1. For each registered project, find all `projects` rows whose
+   name matches one of the project's aliases AND is not the
+   canonical id itself. These are the "shadow" rows.
+2. For each shadow row, MERGE its dependent state into the
+   canonical project's row:
+   - rekey `project_state.project_id` from shadow → canonical
+   - if the merge would create a `(project_id, category, key)`
+     collision (a state row already exists under the canonical
+     id with the same category+key), the migration must surface
+     the conflict via the existing conflict model and pause
+     until the human resolves it
+   - delete the now-empty shadow `projects` row
+3. For `memories` and `interactions`, the fix is simpler because
+   the alias appears as a string column (not a foreign key):
+   `UPDATE memories SET project = canonical WHERE project = alias`,
+   then same for interactions.
+4. The migration must run in dry-run mode first, printing the
+   exact rows it would touch and the canonical destinations they
+   would be merged into.
+5. The migration must be idempotent — running it twice produces
+   the same final state as running it once.
+
+This work is **required before the engineering layer V1 ships**
+because V1 will add new `entities`, `relationships`, `conflicts`,
+and `mirror_regeneration_failures` tables that all key on the
+canonical project id. Any leaked alias-keyed rows in the existing
+tables would show up in V1 reads as silently missing data, and
+the killer-correctness queries from `engineering-query-catalog.md`
+(orphan requirements, decisions on flagged assumptions,
+unsupported claims) would report wrong results against any project
+that has shadow rows.
+
+The migration script does NOT exist yet. The open follow-ups
+section below tracks it as the next concrete step.
+
+## The rule for new entry points
+
+When you add a new service-layer function that takes a project name,
+follow this checklist:
+
+1. **Does the function read or write a row keyed by project?** If
+   yes, you must call `resolve_project_name`. If no (e.g. it only
+   takes `project` as a label for logging), you may skip the
+   canonicalization but you should add a comment explaining why.
+2. **Where does the canonicalization go?** As the first statement
+   after input validation. Not later, not "before storage", not
+   "in the helper that does the actual write". As the first
+   statement, so any subsequent service call inside the function
+   sees the canonical value.
+3. **Add a regression test that uses an alias.** Use the
+   `project_registry` fixture from `tests/conftest.py` to set up
+   a temp registry with at least one project + aliases, then
+   verify the new function works when called with the alias and
+   when called with the canonical id.
+4. **If the function can be called with `None` or empty string,
+   verify that path too.** The helper handles it correctly but
+   the function-under-test might not.
+
+## How the `project_registry` test fixture works
+
+`tests/conftest.py::project_registry` returns a callable that
+takes one or more `(project_id, [aliases])` tuples (or just a bare
+`project_id` string), writes them into a temp registry file,
+points `ATOCORE_PROJECT_REGISTRY_PATH` at it, and reloads
+`config.settings`. Use it like:
+
+```python
+def test_my_new_thing_canonicalizes(project_registry):
+    project_registry(("p05-interferometer", ["p05", "interferometer"]))
+
+    # ... call your service function with "p05" ...
+    # ... assert it works the same as if you'd passed "p05-interferometer" ...
+```
+
+The fixture is reused by all 12 alias-canonicalization regression
+tests added in `fb6298a`. Following the same pattern for new
+features is the cheapest way to keep the contract intact.
+
+## What this rule does NOT cover
+
+1. **Alias creation / management.** This document is about reading
+   and writing project-keyed data. Adding new projects or new
+   aliases is the registry's own write path
+   (`POST /projects/register`, `PUT /projects/{name}`), which
+   already enforces collision detection and atomic file writes.
+2. **Registry hot-reloading.** The helper calls
+   `load_project_registry()` on every invocation, which reads the
+   JSON file each time. There is no in-process cache. If the
+   registry file changes, the next call sees the new contents.
+   Performance is fine for the current registry size but if it
+   becomes a bottleneck, add a versioned cache here, not at every
+   call site.
+3. **Cross-project deduplication.** If two different projects in
+   the registry happen to share an alias, the registry's collision
+   detection blocks the second one at registration time, so this
+   case can't arise in practice. The helper does not handle it
+   defensively.
+4. **Time-bounded canonicalization.** A project's canonical id is
+   stable. Aliases can be added or removed via
+   `PUT /projects/{name}`, but the canonical `id` field never
+   changes after registration. So a row written today under the
+   canonical id will always remain findable under that id, even
+   if the alias set evolves.
+5. **Migration of legacy data.** If the live Dalidou DB has rows
+   that were written under aliases before the canonicalization
+   landed (e.g. a `memories` row with `project = "p05"` from
+   before `fb6298a`), those rows are **NOT** automatically
+   reachable from the canonicalized read path. The unregistered-
+   name fallback only helps for project names that were never
+   registered at all; it does **NOT** help for names that are
+   registered as aliases. See the "Compatibility gap" section
+   below for the exact failure mode and the migration path that
+   has to run before the engineering layer V1 ships.
+
+## What this enables for the engineering layer V1
+
+When the engineering layer ships per `engineering-v1-acceptance.md`,
+it adds at least these new project-keyed surfaces:
+
+- `entities` table with a `project_id` column
+- `relationships` table that joins entities, indirectly project-keyed
+- `conflicts` table with a `project` column
+- `mirror_regeneration_failures` table with a `project` column
+- new endpoints: `POST /entities/...`, `POST /ingest/kb-cad/export`,
+  `POST /ingest/kb-fem/export`, `GET /mirror/{project}/...`,
+  `GET /conflicts?project=...`
+
+**Every one of those write/read paths needs to call
+`resolve_project_name` at its service-layer entry point**, following
+the same pattern as the eight existing call sites listed above. The
+implementation sprint should:
+
+1. Apply the helper at each new service entry point as the first
+   statement after input validation
+2. Add a regression test using the `project_registry` fixture that
+   exercises an alias against each new entry point
+3. Treat any new service function that takes a project name without
+   calling `resolve_project_name` as a code review failure
+
+The pattern is simple enough to follow without thinking, which is
+exactly the property we want for a contract that has to hold
+across many independent additions.
+
+## Open follow-ups
+
+These are things the canonicalization story still has open. None
+are blockers, but they're the rough edges to be aware of.
+
+1. **Legacy alias data migration — REQUIRED before engineering V1
+   ships, NOT optional.** If the live Dalidou DB has any rows
+   written under aliases before `fb6298a` landed, they are
+   silently invisible to the canonicalized read path (see the
+   "Compatibility gap" section above for the exact failure mode).
+   This is a real correctness issue, not a theoretical one: any
+   trusted state, memory, or interaction stored under `p05`,
+   `gigabit`, `polisher`, etc. before the fix landed is currently
+   unreachable from any service-layer query. The migration script
+   has to walk `projects`, `project_state`, `memories`, and
+   `interactions`, merge shadow rows into their canonical
+   counterparts (with conflict-model handling for any collisions),
+   and run in dry-run mode first. Estimated cost: ~150 LOC for
+   the migration script + ~50 LOC of tests + a one-time supervised
+   run on the live Dalidou DB. **This migration is the next
+   concrete pre-V1 step.**
+2. **Registry file caching.** `load_project_registry()` reads the
+   JSON file on every `resolve_project_name` call. With ~5
+   projects this is fine; with 50+ it would warrant a versioned
+   cache (cache key = file mtime + size). Defer until measured.
+3. **Case sensitivity audit.** The helper uses
+   `get_registered_project` which lowercases for comparison. The
+   stored canonical id keeps its original casing. No bug today
+   because every test passes, but worth re-confirming when the
+   engineering layer adds entity-side storage.
+4. **`_rank_chunks`'s secondary substring boost.** Mentioned
+   earlier; still uses the raw hint. Replace it with the same
+   helper-driven approach the retriever uses, OR delete it as
+   redundant once we confirm the retriever's primary boost is
+   sufficient.
+5. **Documentation discoverability.** This doc lives under
+   `docs/architecture/`. The contract is also restated in the
+   docstring of `resolve_project_name` and referenced from each
+   call site's comment. That redundancy is intentional — the
+   contract is too easy to forget to live in only one place.
+
+## Quick reference card
+
+Copy-pasteable for new service functions:
+
+```python
+from atocore.projects.registry import resolve_project_name
+
+
+def my_new_service_entry_point(
+    project_name: str,
+    other_args: ...,
+) -> ...:
+    # Validate inputs first
+    if not project_name:
+        raise ValueError("project_name is required")
+
+    # Canonicalize through the registry as the first thing after
+    # validation. Every subsequent operation in this function uses
+    # the canonical id, so storage and queries are guaranteed
+    # consistent across alias and canonical-id callers.
+    project_name = resolve_project_name(project_name)
+
+    # ... rest of the function ...
+```
+
+## TL;DR
+
+- One helper, one rule: `resolve_project_name` at every service-layer
+  entry point that takes a project name
+- Currently called in 8 places across builder, project_state,
+  interactions, and memory; all 8 listed in this doc
+- Backwards-compat path returns **unregistered** names unchanged
+  (e.g. `"orphan-project"`); this does NOT cover **registered
+  alias** names that were used as storage keys before `fb6298a`
+- **Real compatibility gap**: any row whose `project` column is a
+  registered alias from before the canonicalization landed is
+  silently invisible to the new read path. A one-time migration
+  is required before engineering V1 ships. See the "Compatibility
+  gap" section.
+- The trust hierarchy depends on this helper being applied
+  everywhere — Layer 3 trusted state has to be findable for it to
+  win the trust battle
+- Use the `project_registry` test fixture to add regression tests
+  for any new service function that takes a project name
+- The engineering layer V1 implementation must follow the same
+  pattern at every new service entry point
+- Open follow-ups (in priority order): **legacy alias data
+  migration (required pre-V1)**, redundant substring boost
+  cleanup, registry caching when projects scale

docs/backup-restore-procedure.md

@@ -146,141 +146,193 @@ of bytes.
 
 ## Restore procedure
 
+Since 2026-04-09 the restore is implemented as a proper module
+function plus CLI entry point: `restore_runtime_backup()` in
+`src/atocore/ops/backup.py`, invoked as
+`python -m atocore.ops.backup restore <STAMP> --confirm-service-stopped`.
+It automatically takes a pre-restore safety snapshot (your rollback
+anchor), handles SQLite WAL/SHM cleanly, restores the registry, and
+runs `PRAGMA integrity_check` on the restored db. This replaces the
+earlier manual `sudo cp` sequence.
+
+The function refuses to run without `--confirm-service-stopped`.
+This is deliberate: hot-restoring into a running service corrupts
+SQLite state.
+
 ### Pre-flight (always)
 
 1. Identify which snapshot you want to restore. List available
    snapshots and pick by timestamp:
    ```bash
-   curl -fsS http://dalidou:8100/admin/backup | jq '.backups[].stamp'
+   curl -fsS http://127.0.0.1:8100/admin/backup | jq '.backups[].stamp'
    ```
 2. Validate it. Refuse to restore an invalid backup:
    ```bash
-   STAMP=20260407T060000Z
-   curl -fsS http://dalidou:8100/admin/backup/$STAMP/validate | jq .
+   STAMP=20260409T060000Z
+   curl -fsS http://127.0.0.1:8100/admin/backup/$STAMP/validate | jq .
    ```
 3. **Stop AtoCore.** SQLite cannot be hot-restored under a running
    process and Chroma will not pick up new files until the process
    restarts.
    ```bash
-   docker compose stop atocore
-   # or: sudo systemctl stop atocore
-   ```
-4. **Take a safety snapshot of the current state** before overwriting
-   it. This is your "if the restore makes things worse, here's the
-   undo" backup.
-   ```bash
-   PRESERVE_STAMP=$(date -u +%Y%m%dT%H%M%SZ)
-   sudo cp /srv/storage/atocore/data/db/atocore.db \
-           /srv/storage/atocore/backups/pre-restore-$PRESERVE_STAMP.db
-   sudo cp /srv/storage/atocore/config/project-registry.json \
-           /srv/storage/atocore/backups/pre-restore-$PRESERVE_STAMP.registry.json 2>/dev/null || true
+   cd /srv/storage/atocore/app/deploy/dalidou
+   docker compose down
+   docker compose ps   # atocore should be Exited/gone
    ```
 
-### Restore the SQLite database
+### Run the restore
+
+Use a one-shot container that reuses the live service's volume
+mounts so every path (`db_path`, `chroma_path`, backup dir) resolves
+to the same place the main service would see:
 
 ```bash
-SNAPSHOT_DIR=/srv/storage/atocore/backups/snapshots/$STAMP
-sudo cp $SNAPSHOT_DIR/db/atocore.db \
-        /srv/storage/atocore/data/db/atocore.db
-sudo chown 1000:1000 /srv/storage/atocore/data/db/atocore.db
-sudo chmod 600 /srv/storage/atocore/data/db/atocore.db
+cd /srv/storage/atocore/app/deploy/dalidou
+docker compose run --rm --entrypoint python atocore \
+    -m atocore.ops.backup restore \
+        $STAMP \
+        --confirm-service-stopped
 ```
 
-The chown should match the gitea/atocore container user. Verify
-by checking the existing perms before overwriting:
+Output is a JSON document. The critical fields:
 
-```bash
-stat -c '%U:%G %a' /srv/storage/atocore/data/db/atocore.db
-```
+- `pre_restore_snapshot`: stamp of the safety snapshot of live
+  state taken right before the restore. **Write this down.** If
+  the restore was the wrong call, this is how you roll it back.
+- `db_restored`: should be `true`
+- `registry_restored`: `true` if the backup captured a registry
+- `chroma_restored`: `true` if the backup captured a chroma tree
+  and include_chroma resolved to true (default)
+- `restored_integrity_ok`: **must be `true`** — if this is false,
+  STOP and do not start the service; investigate the integrity
+  error first. The restored file is still on disk but untrusted.
 
-### Restore the project registry
+### Controlling the restore
 
-```bash
-if [ -f $SNAPSHOT_DIR/config/project-registry.json ]; then
-  sudo cp $SNAPSHOT_DIR/config/project-registry.json \
-          /srv/storage/atocore/config/project-registry.json
-  sudo chown 1000:1000 /srv/storage/atocore/config/project-registry.json
-  sudo chmod 644 /srv/storage/atocore/config/project-registry.json
-fi
-```
+The CLI supports a few flags for finer control:
 
-If the snapshot does not contain a registry, the current registry is
-preserved. The pre-flight safety copy still gives you a recovery path
-if you need to roll back.
+- `--no-pre-snapshot` skips the pre-restore safety snapshot. Use
+  this only when you know you have another rollback path.
+- `--no-chroma` restores only SQLite + registry, leaving the
+  current Chroma dir alone. Useful if Chroma is consistent but
+  SQLite needs a rollback.
+- `--chroma` forces Chroma restoration even if the metadata
+  doesn't clearly indicate the snapshot has it (rare).
 
-### Restore the Chroma vector store (if it was in the snapshot)
+### Chroma restore and bind-mounted volumes
 
-```bash
-if [ -d $SNAPSHOT_DIR/chroma ]; then
-  # Move the current chroma dir aside as a safety copy
-  sudo mv /srv/storage/atocore/data/chroma \
-          /srv/storage/atocore/data/chroma.pre-restore-$PRESERVE_STAMP
+The Chroma dir on Dalidou is a bind-mounted Docker volume. The
+restore cannot `rmtree` the destination (you can't unlink a mount
+point — it raises `OSError [Errno 16] Device or resource busy`),
+so the function clears the dir's CONTENTS and uses
+`copytree(dirs_exist_ok=True)` to copy the snapshot back in. The
+regression test `test_restore_chroma_does_not_unlink_destination_directory`
+in `tests/test_backup.py` captures the destination inode before
+and after restore and asserts it's stable — the same invariant
+that protects the bind mount.
 
-  # Copy the snapshot in
-  sudo cp -a $SNAPSHOT_DIR/chroma /srv/storage/atocore/data/chroma
-  sudo chown -R 1000:1000 /srv/storage/atocore/data/chroma
-fi
-```
-
-If the snapshot does NOT contain a Chroma dir but the SQLite
-restore would leave the vector store and the SQL store inconsistent
-(e.g. SQL has chunks the vector store doesn't), you have two
-options:
-
-- **Option 1: rebuild the vector store from source documents.** Run
-  ingestion fresh after the SQL restore. This regenerates embeddings
-  from the actual source files. Slow but produces a perfectly
-  consistent state.
-- **Option 2: accept the inconsistency and live with stale-vector
-  filtering.** The retriever already drops vector results whose
-  SQL row no longer exists (`_existing_chunk_ids` filter), so the
-  inconsistency surfaces as missing results, not bad ones.
-
-For an unplanned restore, Option 2 is the right immediate move.
-Then schedule a fresh ingestion pass to rebuild the vector store
-properly.
+This was discovered during the first real Dalidou restore drill
+on 2026-04-09. If you see a new restore failure with
+`Device or resource busy`, something has regressed this fix.
 
 ### Restart AtoCore
 
 ```bash
-docker compose up -d atocore
-# or: sudo systemctl start atocore
+cd /srv/storage/atocore/app/deploy/dalidou
+docker compose up -d
+# Wait for /health to come up
+for i in 1 2 3 4 5 6 7 8 9 10; do
+    curl -fsS http://127.0.0.1:8100/health \
+        && break || { echo "not ready ($i/10)"; sleep 3; }
+done
+```
+
+**Note on build_sha after restore:** The one-shot `docker compose run`
+container does not carry the build provenance env vars that `deploy.sh`
+exports at deploy time. After a restore, `/health` will report
+`build_sha: "unknown"` until you re-run `deploy.sh` or manually
+re-deploy. This is cosmetic — the data is correctly restored — but if
+you need `build_sha` to be accurate, run a redeploy after the restore:
+
+```bash
+cd /srv/storage/atocore/app
+bash deploy/dalidou/deploy.sh
 ```
 
 ### Post-restore verification
 
 ```bash
 # 1. Service is healthy
-curl -fsS http://dalidou:8100/health | jq .
+curl -fsS http://127.0.0.1:8100/health | jq .
 
 # 2. Stats look right
-curl -fsS http://dalidou:8100/stats | jq .
+curl -fsS http://127.0.0.1:8100/stats | jq .
 
 # 3. Project registry loads
-curl -fsS http://dalidou:8100/projects | jq '.projects | length'
+curl -fsS http://127.0.0.1:8100/projects | jq '.projects | length'
 
 # 4. A known-good context query returns non-empty results
-curl -fsS -X POST http://dalidou:8100/context/build \
+curl -fsS -X POST http://127.0.0.1:8100/context/build \
   -H "Content-Type: application/json" \
   -d '{"prompt": "what is p05 about", "project": "p05-interferometer"}' | jq '.chunks_used'
 ```
 
 If any of these are wrong, the restore is bad. Roll back using the
-pre-restore safety copy:
+pre-restore safety snapshot whose stamp you recorded from the
+restore output. The rollback is the same procedure — stop the
+service and restore that stamp:
 
 ```bash
-docker compose stop atocore
-sudo cp /srv/storage/atocore/backups/pre-restore-$PRESERVE_STAMP.db \
-        /srv/storage/atocore/data/db/atocore.db
-sudo cp /srv/storage/atocore/backups/pre-restore-$PRESERVE_STAMP.registry.json \
-        /srv/storage/atocore/config/project-registry.json 2>/dev/null || true
-# If you also restored chroma:
-sudo rm -rf /srv/storage/atocore/data/chroma
-sudo mv /srv/storage/atocore/data/chroma.pre-restore-$PRESERVE_STAMP \
-        /srv/storage/atocore/data/chroma
-docker compose up -d atocore
+docker compose down
+docker compose run --rm --entrypoint python atocore \
+    -m atocore.ops.backup restore \
+        $PRE_RESTORE_SNAPSHOT_STAMP \
+        --confirm-service-stopped \
+        --no-pre-snapshot
+docker compose up -d
 ```
 
+(`--no-pre-snapshot` because the rollback itself doesn't need one;
+you already have the original snapshot as a fallback if everything
+goes sideways.)
+
+### Restore drill
+
+The restore is exercised at three levels:
+
+1. **Unit tests.** `tests/test_backup.py` has six restore tests
+   (refuse-without-confirm, invalid backup, full round-trip,
+   Chroma round-trip, inode-stability regression, WAL sidecar
+   cleanup, skip-pre-snapshot). These run in CI on every commit.
+2. **Module-level round-trip.**
+   `test_restore_round_trip_reverses_post_backup_mutations` is
+   the canonical drill in code form: seed baseline, snapshot,
+   mutate, restore, assert mutation reversed + baseline survived
+   + pre-restore snapshot captured the mutation.
+3. **Live drill on Dalidou.** Periodically run the full procedure
+   against the real service with a disposable drill-marker
+   memory (created via `POST /memory` with `memory_type=episodic`
+   and `project=drill`), following the sequence above and then
+   verifying the marker is gone afterward via
+   `GET /memory?project=drill`. The first such drill on
+   2026-04-09 surfaced the bind-mount bug; future runs
+   primarily exist to verify the fix stays fixed.
+
+Run the live drill:
+
+- **Before** enabling any new write-path automation (auto-capture,
+  automated ingestion, reinforcement sweeps).
+- **After** any change to `src/atocore/ops/backup.py` or to
+  schema migrations in `src/atocore/models/database.py`.
+- **After** a Dalidou OS upgrade or docker version bump.
+- **At least once per quarter** as a standing operational check.
+- **After any incident** that touched the storage layer.
+
+Record each drill run (stamp, pre-restore snapshot stamp, pass/fail,
+any surprises) somewhere durable — a line in the project journal
+or a git commit message is enough. A drill you ran once and never
+again is barely more than a drill you never ran.
+
 ## Retention policy
 
 - **Last 7 daily backups**: kept verbatim
@@ -296,32 +348,26 @@ A simple cron-based cleanup script is the next step:
 0 4 * * * /srv/storage/atocore/scripts/cleanup-old-backups.sh
 ```
 
-## Drill schedule
-
-A backup that has never been restored is theoretical. The schedule:
-
-- **At least once per quarter**, perform a full restore drill on a
-  staging environment (or a temporary container with a separate
-  data dir) and verify the post-restore checks pass.
-- **After every breaking schema migration**, perform a restore drill
-  to confirm the migration is reversible.
-- **After any incident** that touched the storage layer (the EXDEV
-  bug from April 2026 is a good example), confirm the next backup
-  validates clean.
-
 ## Common failure modes and what to do about them
 
 | Symptom | Likely cause | Action |
 |---|---|---|
 | `db_integrity_check_failed` on validation | SQLite snapshot copied while a write was in progress, or disk corruption | Take a fresh backup and validate again. If it fails twice, suspect the underlying disk. |
 | `registry_invalid_json` | Registry was being edited at backup time | Take a fresh backup. The registry is small so this is cheap. |
-| `chroma_snapshot_missing` after a restore | Snapshot was DB-only and the restore didn't move the existing chroma dir | Either rebuild via fresh ingestion or restore an older snapshot that includes Chroma. |
+| Restore: `restored_integrity_ok: false` | Source snapshot was itself corrupt (validation should have caught it — file a bug) or copy was interrupted mid-write | Do NOT start the service. Validate the snapshot directly with `python -m atocore.ops.backup validate <STAMP>`, try a different older snapshot, or roll back to the pre-restore safety snapshot. |
+| Restore: `OSError [Errno 16] Device or resource busy` on Chroma | Old code tried to `rmtree` the Chroma mount point. Fixed on 2026-04-09 by `test_restore_chroma_does_not_unlink_destination_directory` | Ensure you're running commit 2026-04-09 or later; if you need to work around an older build, use `--no-chroma` and restore Chroma contents manually. |
+| `chroma_snapshot_missing` after a restore | Snapshot was DB-only | Either rebuild via fresh ingestion or restore an older snapshot that includes Chroma. |
 | Service won't start after restore | Permissions wrong on the restored files | Re-run `chown 1000:1000` (or whatever the gitea/atocore container user is) on the data dir. |
 | `/stats` returns 0 documents after restore | The SQL store was restored but the source paths in `source_documents` don't match the current Dalidou paths | This means the backup came from a different deployment. Don't trust this restore — it's pulling from the wrong layout. |
+| Drill marker still present after restore | Wrong stamp, service still writing during `docker compose down`, or the restore JSON didn't report `db_restored: true` | Roll back via the pre-restore safety snapshot and retry with the correct source snapshot. |
 
 ## Open follow-ups (not yet implemented)
 
-1. **Retention cleanup script**: see the cron entry above.
+Tracked separately in `docs/next-steps.md` — the list below is the
+backup-specific subset.
+
+1. **Retention cleanup script**: see the cron entry above. The
+   snapshots directory grows monotonically until this exists.
 2. **Off-Dalidou backup target**: currently snapshots live on the
    same disk as the live data. A real disaster-recovery story
    needs at least one snapshot on a different physical machine.
@@ -338,23 +384,59 @@ A backup that has never been restored is theoretical. The schedule:
    improvement would be incremental snapshots via filesystem-level
    snapshotting (LVM, btrfs, ZFS).
 
+**Done** (kept for historical reference):
+
+- ~~Implement `restore_runtime_backup()` as a proper module
+  function so the restore isn't a manual `sudo cp` dance~~ —
+  landed 2026-04-09 in commit 3362080, followed by the
+  Chroma bind-mount fix from the first real drill.
+
 ## Quickstart cheat sheet
 
 ```bash
 # Daily backup (DB + registry only — fast)
-curl -fsS -X POST http://dalidou:8100/admin/backup \
+curl -fsS -X POST http://127.0.0.1:8100/admin/backup \
   -H "Content-Type: application/json" -d '{}'
 
 # Weekly backup (DB + registry + Chroma — slower, holds ingestion lock)
-curl -fsS -X POST http://dalidou:8100/admin/backup \
+curl -fsS -X POST http://127.0.0.1:8100/admin/backup \
   -H "Content-Type: application/json" -d '{"include_chroma": true}'
 
 # List backups
-curl -fsS http://dalidou:8100/admin/backup | jq '.backups[].stamp'
+curl -fsS http://127.0.0.1:8100/admin/backup | jq '.backups[].stamp'
 
 # Validate the most recent backup
-LATEST=$(curl -fsS http://dalidou:8100/admin/backup | jq -r '.backups[-1].stamp')
-curl -fsS http://dalidou:8100/admin/backup/$LATEST/validate | jq .
+LATEST=$(curl -fsS http://127.0.0.1:8100/admin/backup | jq -r '.backups[-1].stamp')
+curl -fsS http://127.0.0.1:8100/admin/backup/$LATEST/validate | jq .
 
-# Full restore — see the "Restore procedure" section above
+# Full restore (service must be stopped first)
+cd /srv/storage/atocore/app/deploy/dalidou
+docker compose down
+docker compose run --rm --entrypoint python atocore \
+    -m atocore.ops.backup restore $STAMP --confirm-service-stopped
+docker compose up -d
+
+# Live drill: exercise the full create -> mutate -> restore flow
+# against the running service. The marker memory uses
+# memory_type=episodic (valid types: identity, preference, project,
+# episodic, knowledge, adaptation) and project=drill so it's easy
+# to find via GET /memory?project=drill before and after.
+#
+# See the "Restore drill" section above for the full sequence.
+STAMP=$(curl -fsS -X POST http://127.0.0.1:8100/admin/backup \
+    -H 'Content-Type: application/json' \
+    -d '{"include_chroma": true}' | jq -r '.backup_root' | awk -F/ '{print $NF}')
+
+curl -fsS -X POST http://127.0.0.1:8100/memory \
+    -H 'Content-Type: application/json' \
+    -d '{"memory_type":"episodic","content":"DRILL-MARKER","project":"drill","confidence":1.0}'
+
+cd /srv/storage/atocore/app/deploy/dalidou
+docker compose down
+docker compose run --rm --entrypoint python atocore \
+    -m atocore.ops.backup restore $STAMP --confirm-service-stopped
+docker compose up -d
+
+# Marker should be gone:
+curl -fsS 'http://127.0.0.1:8100/memory?project=drill' | jq .
 ```

docs/current-state.md

@@ -200,10 +200,30 @@ The runtime has now been hardened in a few practical ways:
 - SQLite connections use a configurable busy timeout
 - SQLite uses WAL mode to reduce transient lock pain under normal concurrent use
 - project registry writes are atomic file replacements rather than in-place rewrites
-- a first runtime backup path now exists for:
-  - SQLite
-  - project registry
+- a full runtime backup and restore path now exists and has been exercised on
+  live Dalidou:
+  - SQLite (hot online backup via `conn.backup()`)
+  - project registry (file copy)
+  - Chroma vector store (cold directory copy under `exclusive_ingestion()`)
   - backup metadata
+  - `restore_runtime_backup()` with CLI entry point
+    (`python -m atocore.ops.backup restore <STAMP>
+    --confirm-service-stopped`), pre-restore safety snapshot for
+    rollback, WAL/SHM sidecar cleanup, `PRAGMA integrity_check`
+    on the restored file
+  - the first live drill on 2026-04-09 surfaced and fixed a Chroma
+    restore bug on Docker bind-mounted volumes (`shutil.rmtree`
+    on a mount point); a regression test now asserts the
+    destination inode is stable across restore
+- deploy provenance is visible end-to-end:
+  - `/health` reports `build_sha`, `build_time`, `build_branch`
+    from env vars wired by `deploy.sh`
+  - `deploy.sh` Step 6 verifies the live `build_sha` matches the
+    just-built commit (exit code 6 on drift) so "live is current?"
+    can be answered precisely, not just by `__version__`
+  - `deploy.sh` Step 1.5 detects that the script itself changed
+    in the pulled commit and re-execs into the fresh copy, so
+    the deploy never silently runs the old script against new source
 
 This does not eliminate every concurrency edge, but it materially improves the
 current operational baseline.
@@ -224,15 +244,23 @@ This separation is healthy:
 
 ## Immediate Next Focus
 
-1. Use the new T420-side organic routing layer in real OpenClaw workflows
-2. Tighten retrieval quality for the now fully ingested active project corpora
-3. Move to Wave 2 trusted-operational ingestion instead of blindly widening raw corpus further
-4. Keep the new engineering-knowledge architecture docs as implementation guidance while avoiding premature schema work
-5. Expand the boring operations baseline:
-   - restore validation
-   - Chroma rebuild / backup policy
-   - retention
-6. Only later consider write-back, reflection, or deeper autonomous behaviors
+1. ~~Re-run the full backup/restore drill~~ — DONE 2026-04-11,
+   full pass (db, registry, chroma, integrity all true)
+2. ~~Turn on auto-capture of Claude Code sessions in conservative
+   mode~~ — DONE 2026-04-11, Stop hook wired via
+   `deploy/hooks/capture_stop.py` → `POST /interactions`
+   with `reinforce=false`; kill switch via
+   `ATOCORE_CAPTURE_DISABLED=1`
+3. Run a short real-use pilot with auto-capture on, verify
+   interactions are landing in Dalidou, review quality
+4. Use the new T420-side organic routing layer in real OpenClaw workflows
+4. Tighten retrieval quality for the now fully ingested active project corpora
+5. Move to Wave 2 trusted-operational ingestion instead of blindly widening raw corpus further
+6. Keep the new engineering-knowledge architecture docs as implementation guidance while avoiding premature schema work
+7. Expand the remaining boring operations baseline:
+   - retention policy cleanup script
+   - off-Dalidou backup target (rsync or similar)
+8. Only later consider write-back, reflection, or deeper autonomous behaviors
 
 See also:
 

docs/dalidou-deployment.md

@@ -50,26 +50,205 @@ starting from:
 deploy/dalidou/.env.example
 ```
 
-## Deployment steps
+## First-time deployment steps
+
+1. Place the repository under `/srv/storage/atocore/app` — ideally as a
+   proper git clone so future updates can be pulled, not as a static
+   snapshot:
+
+   ```bash
+   sudo git clone http://dalidou:3000/Antoine/ATOCore.git \
+       /srv/storage/atocore/app
+   ```
 
-1. Place the repository under `/srv/storage/atocore/app`.
 2. Create the canonical directories listed above.
 3. Copy `deploy/dalidou/.env.example` to `deploy/dalidou/.env`.
 4. Adjust the source paths if your AtoVault/AtoDrive mirrors live elsewhere.
 5. Run:
 
-```bash
-cd /srv/storage/atocore/app/deploy/dalidou
-docker compose up -d --build
-```
+   ```bash
+   cd /srv/storage/atocore/app/deploy/dalidou
+   docker compose up -d --build
+   ```
 
 6. Validate:
 
+   ```bash
+   curl http://127.0.0.1:8100/health
+   curl http://127.0.0.1:8100/sources
+   ```
+
+## Updating a running deployment
+
+**Use `deploy/dalidou/deploy.sh` for every code update.** It is the
+one-shot sync script that:
+
+- fetches latest main from Gitea into `/srv/storage/atocore/app`
+- (if the app dir is not a git checkout) backs it up as
+  `<dir>.pre-git-<timestamp>` and re-clones
+- rebuilds the container image
+- restarts the container
+- waits for `/health` to respond
+- compares the reported `code_version` against the
+  `__version__` in the freshly-pulled source, and exits non-zero
+  if they don't match (deployment drift detection)
+
 ```bash
-curl http://127.0.0.1:8100/health
-curl http://127.0.0.1:8100/sources
+# Normal update from main
+bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh
+
+# Deploy a specific branch or tag
+ATOCORE_BRANCH=codex/some-feature \
+    bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh
+
+# Dry-run: show what would happen without touching anything
+ATOCORE_DEPLOY_DRY_RUN=1 \
+    bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh
+
+# Deploy from a remote host (e.g. the laptop) using the Tailscale
+# or LAN address instead of loopback
+ATOCORE_GIT_REMOTE=http://192.168.86.50:3000/Antoine/ATOCore.git \
+    bash /srv/storage/atocore/app/deploy/dalidou/deploy.sh
 ```
 
+The script is idempotent and safe to re-run. It never touches the
+database directly — schema migrations are applied automatically at
+service startup by the lifespan handler in `src/atocore/main.py`
+which calls `init_db()` (which in turn runs the ALTER TABLE
+statements in `_apply_migrations`).
+
+### Troubleshooting hostname resolution
+
+`deploy.sh` defaults `ATOCORE_GIT_REMOTE` to
+`http://127.0.0.1:3000/Antoine/ATOCore.git` (loopback) because the
+hostname "dalidou" doesn't reliably resolve on the host itself —
+the first real Dalidou deploy hit exactly this on 2026-04-08. If
+you need to override (e.g. running deploy.sh from a laptop against
+the Dalidou LAN), set `ATOCORE_GIT_REMOTE` explicitly.
+
+The same applies to `scripts/atocore_client.py`: its default
+`ATOCORE_BASE_URL` is `http://dalidou:8100` for remote callers, but
+when running the client on Dalidou itself (or inside the container
+via `docker exec`), override to loopback:
+
+```bash
+ATOCORE_BASE_URL=http://127.0.0.1:8100 \
+    python scripts/atocore_client.py health
+```
+
+If you see `{"status": "unavailable", "fail_open": true}` from the
+client, the first thing to check is whether the base URL resolves
+from where you're running the client.
+
+### The deploy.sh self-update race
+
+When `deploy.sh` itself changes in the commit being pulled, the
+first run after the update is still executing the *old* script from
+the bash process's in-memory copy. `git reset --hard` updates the
+file on disk, but the running bash has already loaded the
+instructions. On 2026-04-09 this silently shipped an "unknown"
+`build_sha` because the old Step 2 (which predated env-var export)
+ran against fresh source.
+
+`deploy.sh` now detects this: Step 1.5 compares the sha1 of `$0`
+(the running script) against the sha1 of
+`$APP_DIR/deploy/dalidou/deploy.sh` (the on-disk copy) after the
+git reset. If they differ, it sets `ATOCORE_DEPLOY_REEXECED=1` and
+`exec`s the fresh copy so the rest of the deploy runs under the new
+script. The sentinel env var prevents infinite recursion.
+
+You'll see this in the logs as:
+
+```text
+==> Step 1.5: deploy.sh changed in the pulled commit; re-exec'ing
+==>   running script hash: <old>
+==>   on-disk script hash: <new>
+==>   re-exec -> /srv/storage/atocore/app/deploy/dalidou/deploy.sh
+```
+
+To opt out (debugging, for example), pre-set
+`ATOCORE_DEPLOY_REEXECED=1` before invoking `deploy.sh` and the
+self-update guard will be skipped.
+
+### Deployment drift detection
+
+`/health` reports drift signals at three increasing levels of
+precision:
+
+| Field | Source | Precision | When to use |
+|---|---|---|---|
+| `version` / `code_version` | `atocore.__version__` (manual bump) | coarse — same value across many commits | quick smoke check that the right *release* is running |
+| `build_sha` | `ATOCORE_BUILD_SHA` env var, set by `deploy.sh` per build | precise — changes per commit | the canonical drift signal |
+| `build_time` / `build_branch` | same env var path | per-build | forensics when multiple branches in flight |
+
+The **precise** check (run on the laptop or any host that can curl
+the live service AND has the source repo at hand):
+
+```bash
+# What's actually running on Dalidou
+LIVE_SHA=$(curl -fsS http://dalidou:8100/health | grep -o '"build_sha":"[^"]*"' | cut -d'"' -f4)
+
+# What the deployed branch tip should be
+EXPECTED_SHA=$(cd /srv/storage/atocore/app && git rev-parse HEAD)
+
+# Compare
+if [ "$LIVE_SHA" = "$EXPECTED_SHA" ]; then
+    echo "live is current at $LIVE_SHA"
+else
+    echo "DRIFT: live $LIVE_SHA vs expected $EXPECTED_SHA"
+    echo "run deploy.sh to sync"
+fi
+```
+
+The `deploy.sh` script does exactly this comparison automatically
+in its post-deploy verification step (Step 6) and exits non-zero
+on mismatch. So the **simplest drift check** is just to run
+`deploy.sh` — if there's nothing to deploy, it succeeds quickly;
+if the live service is stale, it deploys and verifies.
+
+If `/health` reports `build_sha: "unknown"`, the running container
+was started without `deploy.sh` (probably via `docker compose up`
+directly), and the build provenance was never recorded. Re-run
+via `deploy.sh` to fix.
+
+The coarse `code_version` check is still useful as a quick visual
+sanity check — bumping `__version__` from `0.2.0` to `0.3.0`
+signals a meaningful release boundary even if the precise
+`build_sha` is what tools should compare against:
+
+```bash
+# Quick sanity check (coarse)
+curl -s http://127.0.0.1:8100/health | grep -o '"code_version":"[^"]*"'
+grep '__version__' /srv/storage/atocore/app/src/atocore/__init__.py
+```
+
+### Schema migrations on redeploy
+
+When updating from an older `__version__`, the first startup after
+the redeploy runs the idempotent ALTER TABLE migrations in
+`_apply_migrations`. For a pre-0.2.0 → 0.2.0 upgrade the migrations
+add these columns to existing tables (all with safe defaults so no
+data is touched):
+
+- `memories.project TEXT DEFAULT ''`
+- `memories.last_referenced_at DATETIME`
+- `memories.reference_count INTEGER DEFAULT 0`
+- `interactions.response TEXT DEFAULT ''`
+- `interactions.memories_used TEXT DEFAULT '[]'`
+- `interactions.chunks_used TEXT DEFAULT '[]'`
+- `interactions.client TEXT DEFAULT ''`
+- `interactions.session_id TEXT DEFAULT ''`
+- `interactions.project TEXT DEFAULT ''`
+
+Plus new indexes on the new columns. No row data is modified. The
+migration is safe to run against a database that already has the
+columns — the `_column_exists` check makes each ALTER a no-op in
+that case.
+
+Backup the database before any redeploy (via `POST /admin/backup`)
+if you want a pre-upgrade snapshot. The migration is additive and
+reversible by restoring the snapshot.
+
 ## Deferred
 
 - backup automation

docs/master-plan-status.md

@@ -27,12 +27,34 @@ read-only additive mode.
 ### Partial
 
 - Phase 4 - Identity / Preferences
-- Phase 8 - OpenClaw Integration
+
+### Baseline Complete
+
+- Phase 8 - OpenClaw Integration. As of 2026-04-12 the T420 OpenClaw
+  helper (`t420-openclaw/atocore.py`) is verified end-to-end against
+  live Dalidou: health check, auto-context with project detection,
+  Trusted Project State surfacing, project-memory band, fail-open on
+  unreachable host. Tested from both the development machine and the
+  T420 via SSH. The helper covers 15 of the 33 API endpoints — the
+  excluded endpoints (memory management, interactions, backup) are
+  correctly scoped to the operator client (`scripts/atocore_client.py`)
+  per the read-only additive integration model.
 
 ### Baseline Complete
 
 - Phase 9 - Reflection (all three foundation commits landed:
-  A capture, B reinforcement, C candidate extraction + review queue)
+  A capture, B reinforcement, C candidate extraction + review queue).
+  As of 2026-04-11 the capture → reinforce half runs automatically on
+  every Stop-hook capture (length-aware token-overlap matcher handles
+  paragraph-length memories), and project-scoped memories now reach
+  the context pack via a dedicated `--- Project Memories ---` band
+  between identity/preference and retrieved chunks. The extract half
+  is still a manual / batch flow by design (`scripts/atocore_client.py
+  batch-extract` + `triage`). First live batch-extract run over 42
+  captured interactions produced 1 candidate (rule extractor is
+  conservative and keys on structural cues like `## Decision:`
+  headings that rarely appear in conversational LLM responses) —
+  extractor tuning is a known follow-up.
 
 ### Not Yet Complete In The Intended Sense
 
@@ -68,9 +90,32 @@ active project set.
   the 5-layer model (from the previous planning wave)
 - [engineering-ontology-v1.md](architecture/engineering-ontology-v1.md) —
   the initial V1 object and relationship inventory (previous wave)
+- [project-identity-canonicalization.md](architecture/project-identity-canonicalization.md) —
+  the helper-at-every-service-boundary contract that keeps the
+  trust hierarchy dependable across alias and canonical-id callers;
+  required reading before adding new project-keyed entity surfaces
+  in the V1 implementation sprint
 
 The next concrete next step is the V1 implementation sprint, which
-should follow engineering-v1-acceptance.md as its checklist.
+should follow engineering-v1-acceptance.md as its checklist, and
+must apply the project-identity-canonicalization contract at every
+new service-layer entry point.
+
+### LLM Client Integration
+
+A separate but related architectural concern: how AtoCore is reachable
+from many different LLM client contexts (OpenClaw, Claude Code, future
+Codex skills, future MCP server). The layering rule is documented in:
+
+- [llm-client-integration.md](architecture/llm-client-integration.md) —
+  three-layer shape: HTTP API → shared operator client
+  (`scripts/atocore_client.py`) → per-agent thin frontends; the
+  shared client is the canonical backbone every new client should
+  shell out to instead of reimplementing HTTP calls
+
+This sits implicitly between Phase 8 (OpenClaw) and Phase 11
+(multi-model). Memory-review and engineering-entity commands are
+deferred from the shared client until their workflows are exercised.
 
 ## What Is Real Today
 
@@ -144,7 +189,9 @@ These remain intentionally deferred.
 
 - automatic write-back from OpenClaw into AtoCore
 - automatic memory promotion
-- reflection loop integration
+- ~~reflection loop integration~~ — baseline now in (capture→reinforce
+  auto, extract batch/manual). Extractor tuning and scheduled batch
+  extraction still open.
 - replacing OpenClaw's own memory system
 - live machine-DB sync between machines
 - full ontology / graph expansion before the current baseline is stable

docs/next-steps.md

@@ -20,45 +20,65 @@ This working list should be read alongside:
 
 ## Immediate Next Steps
 
-1. Use the T420 `atocore-context` skill and the new organic routing layer in
+1. ~~Re-run the backup/restore drill~~ — DONE 2026-04-11, full pass
+2. ~~Turn on auto-capture of Claude Code sessions~~ — DONE 2026-04-11,
+   Stop hook via `deploy/hooks/capture_stop.py` → `POST /interactions`
+   with `reinforce=false`; kill switch: `ATOCORE_CAPTURE_DISABLED=1`
+2a. Run a short real-use pilot with auto-capture on
+   - verify interactions are landing in Dalidou
+   - check prompt/response quality and truncation
+   - confirm fail-open: no user-visible impact when Dalidou is down
+3. Use the T420 `atocore-context` skill and the new organic routing layer in
    real OpenClaw workflows
    - confirm `auto-context` feels natural
    - confirm project inference is good enough in practice
    - confirm the fail-open behavior remains acceptable in practice
-2. Review retrieval quality after the first real project ingestion batch
+4. Review retrieval quality after the first real project ingestion batch
    - check whether the top hits are useful
    - check whether trusted project state remains dominant
    - reduce cross-project competition and prompt ambiguity where needed
    - use `debug-context` to inspect the exact last AtoCore supplement
-3. Treat the active-project full markdown/text wave as complete
+5. Treat the active-project full markdown/text wave as complete
    - `p04-gigabit`
    - `p05-interferometer`
    - `p06-polisher`
-4. Define a cleaner source refresh model
+6. Define a cleaner source refresh model
    - make the difference between source truth, staged inputs, and machine store
      explicit
    - move toward a project source registry and refresh workflow
    - foundation now exists via project registry + per-project refresh API
    - registration policy + template + proposal + approved registration are now
      the normal path for new projects
-5. Move to Wave 2 trusted-operational ingestion
+7. Move to Wave 2 trusted-operational ingestion
    - curated dashboards
    - decision logs
    - milestone/current-status views
    - operational truth, not just raw project notes
-6. Integrate the new engineering architecture docs into active planning, not immediate schema code
+8. Integrate the new engineering architecture docs into active planning, not immediate schema code
    - keep `docs/architecture/engineering-knowledge-hybrid-architecture.md` as the target layer model
    - keep `docs/architecture/engineering-ontology-v1.md` as the V1 structured-domain target
    - do not start entity/relationship persistence until the ingestion, retrieval, registry, and backup baseline feels boring and stable
-7. Define backup and export procedures for Dalidou
-   - exercise the new SQLite + registry snapshot path on Dalidou
-   - Chroma backup or rebuild policy
-   - retention and restore validation
-   - admin backup endpoint now supports `include_chroma` cold snapshot
-     under the ingestion lock and `validate` confirms each snapshot is
-     openable; remaining work is the operational retention policy
-8. Keep deeper automatic runtime integration modest until the organic read-only
-   model has proven value
+9. Finish the boring operations baseline around backup
+   - retention policy cleanup script (snapshots dir grows
+     monotonically today)
+   - off-Dalidou backup target (at minimum an rsync to laptop or
+     another host so a single-disk failure isn't terminal)
+   - automatic post-backup validation (have `create_runtime_backup`
+     call `validate_backup` on its own output and refuse to
+     declare success if validation fails)
+   - DONE in commits be40994 / 0382238 / 3362080 / this one:
+     - `create_runtime_backup` + `list_runtime_backups` +
+       `validate_backup` + `restore_runtime_backup` with CLI
+     - `POST /admin/backup` with `include_chroma=true` under
+       the ingestion lock
+     - `/health` build_sha / build_time / build_branch provenance
+     - `deploy.sh` self-update re-exec guard + build_sha drift
+       verification
+     - live drill procedure in `docs/backup-restore-procedure.md`
+       with failure-mode table and the memory_type=episodic
+       marker pattern from the 2026-04-09 drill
+10. Keep deeper automatic runtime integration modest until the organic read-only
+    model has proven value
 
 ## Trusted State Status
 
@@ -117,7 +137,12 @@ P06:
 
 - automatic write-back from OpenClaw into AtoCore
 - automatic memory promotion
-- reflection loop integration
+- ~~reflection loop integration~~ — baseline now landed (2026-04-11):
+  Stop hook runs reinforce automatically, project memories are folded
+  into the context pack, batch-extract and triage CLIs exist. What
+  remains deferred: scheduled/automatic batch extraction and extractor
+  rule tuning (rule-based extractor produced 1 candidate from 42 real
+  captures — needs new cues for conversational LLM content).
 - replacing OpenClaw's own memory system
 - syncing the live machine DB between machines
 
@@ -139,6 +164,116 @@ The next batch is successful if:
 - project ingestion remains controlled rather than noisy
 - the canonical Dalidou instance stays stable
 
+## Retrieval Quality Review — 2026-04-11
+
+First sweep with real project-hinted queries on Dalidou. Used
+`POST /context/build` against p04, p05, p06 with representative
+questions and inspected `formatted_context`.
+
+Findings:
+
+- **Trusted Project State is surfacing correctly.** The DECISION and
+  REQUIREMENT categories appear at the top of the pack and include
+  the expected key facts (e.g. p04 "Option B conical-back mirror
+  architecture"). This is the strongest signal in the pack today.
+- **Chunk retrieval is relevant on-topic but broad.** Top chunks for
+  the p04 architecture query are PDR intro, CAD assembly overview,
+  and the index — all on the right project but none of them directly
+  answer the "why was Option B chosen" question. The authoritative
+  answer sits in Project State, not in the chunks.
+- **Active memories are NOT reaching the pack.** The context builder
+  surfaces Trusted Project State and retrieved chunks but does not
+  include the 21 active project/knowledge memories. Reinforcement
+  (Phase 9 Commit B) bumps memory confidence without the memory ever
+  being read back into a prompt — the reflection loop has no outlet
+  on the retrieval side. This is a design gap, not a bug: needs a
+  decision on whether memories should feed into context assembly,
+  and if so at what trust level (below project_state, above chunks).
+- **Cross-project bleed is low.** The p04 query did pull one p05
+  chunk (CGH_Design_Input_for_AOM) as the bottom hit but the top-4
+  were all p04.
+
+Proposed follow-ups (not yet scheduled):
+
+1. ~~Decide whether memories should be folded into `formatted_context`
+   and under what section header.~~ DONE 2026-04-11 (commits 8ea53f4,
+   5913da5, 1161645). A `--- Project Memories ---` band now sits
+   between identity/preference and retrieved chunks, gated on a
+   canonical project hint to prevent cross-project bleed. Budget
+   ratio 0.25 (tuned empirically — paragraph memories are ~400 chars
+   and earlier 0.15 ratio starved the first entry by one char).
+   Verified live: p04 architecture query surfaces the Option B memory.
+2. Re-run the same three queries after any builder change and compare
+   `formatted_context` diffs — still open, and is the natural entry
+   point for the retrieval eval harness on the roadmap.
+
+## Reflection Loop Live Check — 2026-04-11
+
+First real run of `batch-extract` across 42 captured Claude Code
+interactions on Dalidou produced exactly **1 candidate**, and that
+candidate was a synthetic test capture from earlier in the session
+(rejected). Finding:
+
+- The rule-based extractor in `src/atocore/memory/extractor.py` keys
+  on explicit structural cues (decision headings like
+  `## Decision: ...`, preference sentences, etc.). Real Claude Code
+  responses are conversational and almost never contain those cues.
+- This means the capture → extract half of the reflection loop is
+  effectively inert against organic LLM sessions until either the
+  rules are broadened (new cue families: "we chose X because...",
+  "the selected approach is...", etc.) or an LLM-assisted extraction
+  path is added alongside the rule-based one.
+- Capture → reinforce is working correctly on live data (length-aware
+  matcher verified on live paraphrase of a p04 memory).
+
+Follow-up candidates:
+
+1. ~~Extractor rule expansion~~ — Day 2 baseline showed 0% recall
+   across 5 distinct miss classes; rule expansion cannot close a
+   5-way miss. Deprioritized.
+2. ~~LLM-assisted extractor~~ — DONE 2026-04-12. `extractor_llm.py`
+   shells out to `claude -p` (Haiku, OAuth, no API key). First live
+   run: 100% recall, 2.55 yield/interaction on a 20-interaction
+   labeled set. First triage: 51 candidates → 16 promoted, 35
+   rejected (31% accept rate). Active memories 20 → 36.
+3. ~~Retrieval eval harness~~ — DONE 2026-04-11 (scripts/retrieval_eval.py,
+   6/6 passing). Expansion to 15-20 fixtures is mini-phase Day 6.
+
+## Extractor Scope — 2026-04-12
+
+What the LLM-assisted extractor (`src/atocore/memory/extractor_llm.py`)
+extracts from conversational Claude Code captures:
+
+**In scope:**
+
+- Architectural commitments (e.g. "Z-axis is engage/retract, not
+  continuous position")
+- Ratified decisions with project scope (e.g. "USB SSD mandatory on
+  RPi for telemetry storage")
+- Durable engineering facts (e.g. "telemetry data rate ~29 MB/hour")
+- Working rules and adaptation patterns (e.g. "extraction stays off
+  the capture hot path")
+- Interface invariants (e.g. "controller-job.v1 in, run-log.v1 out;
+  no firmware change needed")
+
+**Out of scope (intentionally rejected by triage):**
+
+- Transient roadmap / plan steps that will be stale in a week
+- Operational instructions ("run this command to deploy")
+- Process rules that live in DEV-LEDGER.md / AGENTS.md, not in memory
+- Implementation details that are too granular (individual field names
+  when the parent concept is already captured)
+- Already-fixed review findings (P1/P2 that no longer apply)
+- Duplicates of existing active memories with wrong project tags
+
+**Trust model:**
+
+- Extraction stays off the capture hot path (batch / manual only)
+- All candidates land as `status=candidate`, never auto-promoted
+- Human or auto-triage reviews before promotion to active
+- Future direction: multi-model extraction + triage (Codex/Gemini as
+  second-pass reviewers for robustness against single-model bias)
+
 ## Long-Run Goal
 
 The long-run target is:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atocore"
-version = "0.1.0"
+version = "0.2.0"
 description = "Personal context engine for LLM interactions"
 requires-python = ">=3.11"
 dependencies = [

scripts/atocore_client.py

@@ -1,8 +1,43 @@
 """Operator-facing API client for live AtoCore instances.
 
-This script is intentionally external to the app runtime. It is for admins and
-operators who want a convenient way to inspect live project state, refresh
-projects, audit retrieval quality, and manage trusted project-state entries.
+This script is intentionally external to the app runtime. It is for admins
+and operators who want a convenient way to inspect live project state,
+refresh projects, audit retrieval quality, manage trusted project-state
+entries, and drive the Phase 9 reflection loop (capture, extract, queue,
+promote, reject).
+
+Environment variables
+---------------------
+
+ATOCORE_BASE_URL
+    Base URL of the AtoCore service (default: ``http://dalidou:8100``).
+
+    When running ON the Dalidou host itself or INSIDE the Dalidou
+    container, override this with loopback or the real IP::
+
+        ATOCORE_BASE_URL=http://127.0.0.1:8100 \\
+            python scripts/atocore_client.py health
+
+    The default hostname "dalidou" is meant for cases where the
+    caller is a remote machine (laptop, T420/OpenClaw, etc.) with
+    "dalidou" in its /etc/hosts or resolvable via Tailscale. It does
+    NOT reliably resolve on the host itself or inside the container,
+    and when it fails the client returns
+    ``{"status": "unavailable", "fail_open": true}`` — the right
+    diagnosis when that happens is to set ATOCORE_BASE_URL explicitly
+    to 127.0.0.1:8100 and retry.
+
+ATOCORE_TIMEOUT_SECONDS
+    Request timeout for most operations (default: 30).
+
+ATOCORE_REFRESH_TIMEOUT_SECONDS
+    Longer timeout for project refresh operations which can be slow
+    (default: 1800).
+
+ATOCORE_FAIL_OPEN
+    When "true" (default), network errors return a small fail-open
+    envelope instead of raising. Set to "false" for admin operations
+    where you need the real error.
 """
 
 from __future__ import annotations
@@ -23,6 +58,15 @@ TIMEOUT = int(os.environ.get("ATOCORE_TIMEOUT_SECONDS", "30"))
 REFRESH_TIMEOUT = int(os.environ.get("ATOCORE_REFRESH_TIMEOUT_SECONDS", "1800"))
 FAIL_OPEN = os.environ.get("ATOCORE_FAIL_OPEN", "true").lower() == "true"
 
+# Bumped when the subcommand surface or JSON output shapes meaningfully
+# change. See docs/architecture/llm-client-integration.md for the
+# semver rules. History:
+#   0.1.0  initial stable-ops-only client
+#   0.2.0  Phase 9 reflection loop added: capture, extract,
+#          reinforce-interaction, list-interactions, get-interaction,
+#          queue, promote, reject
+CLIENT_VERSION = "0.2.0"
+
 
 def print_json(payload: Any) -> None:
     print(json.dumps(payload, ensure_ascii=True, indent=2))
@@ -243,6 +287,75 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("top_k", nargs="?", type=int, default=5)
     p.add_argument("project", nargs="?", default="")
 
+    # --- Phase 9 reflection loop surface --------------------------------
+    #
+    # capture: record one interaction (prompt + response + context used).
+    #   Mirrors POST /interactions. response is positional so shell
+    #   callers can pass it via $(cat file.txt) or heredoc. project,
+    #   client, and session_id are optional positionals with empty
+    #   defaults, matching the existing script's style.
+    p = sub.add_parser("capture")
+    p.add_argument("prompt")
+    p.add_argument("response", nargs="?", default="")
+    p.add_argument("project", nargs="?", default="")
+    p.add_argument("client", nargs="?", default="")
+    p.add_argument("session_id", nargs="?", default="")
+    p.add_argument("reinforce", nargs="?", default="true")
+
+    # extract: run the Phase 9 C rule-based extractor against an
+    #   already-captured interaction. persist='true' writes the
+    #   candidates as status='candidate' memories; default is
+    #   preview-only.
+    p = sub.add_parser("extract")
+    p.add_argument("interaction_id")
+    p.add_argument("persist", nargs="?", default="false")
+
+    # reinforce: backfill reinforcement on an already-captured interaction.
+    p = sub.add_parser("reinforce-interaction")
+    p.add_argument("interaction_id")
+
+    # list-interactions: paginated listing with filters.
+    p = sub.add_parser("list-interactions")
+    p.add_argument("project", nargs="?", default="")
+    p.add_argument("session_id", nargs="?", default="")
+    p.add_argument("client", nargs="?", default="")
+    p.add_argument("since", nargs="?", default="")
+    p.add_argument("limit", nargs="?", type=int, default=50)
+
+    # get-interaction: fetch one by id
+    p = sub.add_parser("get-interaction")
+    p.add_argument("interaction_id")
+
+    # queue: list the candidate review queue
+    p = sub.add_parser("queue")
+    p.add_argument("memory_type", nargs="?", default="")
+    p.add_argument("project", nargs="?", default="")
+    p.add_argument("limit", nargs="?", type=int, default=50)
+
+    # promote: candidate -> active
+    p = sub.add_parser("promote")
+    p.add_argument("memory_id")
+
+    # reject: candidate -> invalid
+    p = sub.add_parser("reject")
+    p.add_argument("memory_id")
+
+    # batch-extract: fan out /interactions/{id}/extract?persist=true across
+    #   recent interactions. Idempotent — the extractor create_memory path
+    #   silently skips duplicates, so re-running is safe.
+    p = sub.add_parser("batch-extract")
+    p.add_argument("since", nargs="?", default="")
+    p.add_argument("project", nargs="?", default="")
+    p.add_argument("limit", nargs="?", type=int, default=100)
+    p.add_argument("persist", nargs="?", default="true")
+
+    # triage: interactive candidate review loop. Fetches the queue, shows
+    #   each candidate, accepts p/r/s (promote / reject / skip) / q (quit).
+    p = sub.add_parser("triage")
+    p.add_argument("memory_type", nargs="?", default="")
+    p.add_argument("project", nargs="?", default="")
+    p.add_argument("limit", nargs="?", type=int, default=50)
+
     return parser
 
 
@@ -304,10 +417,214 @@ def main() -> int:
         print_json(request("POST", "/context/build", {"prompt": args.prompt, "project": args.project or None, "budget": args.budget}))
     elif cmd == "audit-query":
         print_json(audit_query(args.prompt, args.top_k, args.project or None))
+    # --- Phase 9 reflection loop surface ------------------------------
+    elif cmd == "capture":
+        body: dict[str, Any] = {
+            "prompt": args.prompt,
+            "response": args.response,
+            "project": args.project,
+            "client": args.client or "atocore-client",
+            "session_id": args.session_id,
+            "reinforce": args.reinforce.lower() in {"1", "true", "yes", "y"},
+        }
+        print_json(request("POST", "/interactions", body))
+    elif cmd == "extract":
+        persist = args.persist.lower() in {"1", "true", "yes", "y"}
+        print_json(
+            request(
+                "POST",
+                f"/interactions/{urllib.parse.quote(args.interaction_id, safe='')}/extract",
+                {"persist": persist},
+            )
+        )
+    elif cmd == "reinforce-interaction":
+        print_json(
+            request(
+                "POST",
+                f"/interactions/{urllib.parse.quote(args.interaction_id, safe='')}/reinforce",
+                {},
+            )
+        )
+    elif cmd == "list-interactions":
+        query_parts: list[str] = []
+        if args.project:
+            query_parts.append(f"project={urllib.parse.quote(args.project)}")
+        if args.session_id:
+            query_parts.append(f"session_id={urllib.parse.quote(args.session_id)}")
+        if args.client:
+            query_parts.append(f"client={urllib.parse.quote(args.client)}")
+        if args.since:
+            query_parts.append(f"since={urllib.parse.quote(args.since)}")
+        query_parts.append(f"limit={int(args.limit)}")
+        query = "?" + "&".join(query_parts)
+        print_json(request("GET", f"/interactions{query}"))
+    elif cmd == "get-interaction":
+        print_json(
+            request(
+                "GET",
+                f"/interactions/{urllib.parse.quote(args.interaction_id, safe='')}",
+            )
+        )
+    elif cmd == "queue":
+        query_parts = ["status=candidate"]
+        if args.memory_type:
+            query_parts.append(f"memory_type={urllib.parse.quote(args.memory_type)}")
+        if args.project:
+            query_parts.append(f"project={urllib.parse.quote(args.project)}")
+        query_parts.append(f"limit={int(args.limit)}")
+        query = "?" + "&".join(query_parts)
+        print_json(request("GET", f"/memory{query}"))
+    elif cmd == "promote":
+        print_json(
+            request(
+                "POST",
+                f"/memory/{urllib.parse.quote(args.memory_id, safe='')}/promote",
+                {},
+            )
+        )
+    elif cmd == "reject":
+        print_json(
+            request(
+                "POST",
+                f"/memory/{urllib.parse.quote(args.memory_id, safe='')}/reject",
+                {},
+            )
+        )
+    elif cmd == "batch-extract":
+        print_json(run_batch_extract(args.since, args.project, args.limit, args.persist))
+    elif cmd == "triage":
+        return run_triage(args.memory_type, args.project, args.limit)
     else:
         return 1
     return 0
 
 
+def run_batch_extract(since: str, project: str, limit: int, persist_flag: str) -> dict:
+    """Fetch recent interactions and run the extractor against each one.
+
+    Returns an aggregated summary. Safe to re-run: the server-side
+    persist path catches ValueError on duplicates and the endpoint
+    reports per-interaction candidate counts either way.
+    """
+    persist = persist_flag.lower() in {"1", "true", "yes", "y"}
+    query_parts: list[str] = []
+    if project:
+        query_parts.append(f"project={urllib.parse.quote(project)}")
+    if since:
+        query_parts.append(f"since={urllib.parse.quote(since)}")
+    query_parts.append(f"limit={int(limit)}")
+    query = "?" + "&".join(query_parts)
+
+    listing = request("GET", f"/interactions{query}")
+    interactions = listing.get("interactions", []) if isinstance(listing, dict) else []
+
+    processed = 0
+    total_candidates = 0
+    total_persisted = 0
+    errors: list[dict] = []
+    per_interaction: list[dict] = []
+
+    for item in interactions:
+        iid = item.get("id") or ""
+        if not iid:
+            continue
+        try:
+            result = request(
+                "POST",
+                f"/interactions/{urllib.parse.quote(iid, safe='')}/extract",
+                {"persist": persist},
+            )
+        except Exception as exc:  # pragma: no cover - network errors land here
+            errors.append({"interaction_id": iid, "error": str(exc)})
+            continue
+        processed += 1
+        count = int(result.get("candidate_count", 0) or 0)
+        persisted_ids = result.get("persisted_ids") or []
+        total_candidates += count
+        total_persisted += len(persisted_ids)
+        if count:
+            per_interaction.append(
+                {
+                    "interaction_id": iid,
+                    "candidate_count": count,
+                    "persisted_count": len(persisted_ids),
+                    "project": item.get("project") or "",
+                }
+            )
+
+    return {
+        "processed": processed,
+        "total_candidates": total_candidates,
+        "total_persisted": total_persisted,
+        "persist": persist,
+        "errors": errors,
+        "interactions_with_candidates": per_interaction,
+    }
+
+
+def run_triage(memory_type: str, project: str, limit: int) -> int:
+    """Interactive review of candidate memories.
+
+    Loads the queue once, walks through entries, prompts for
+    (p)romote / (r)eject / (s)kip / (q)uit. Stateless between runs —
+    re-running picks up whatever is still status=candidate.
+    """
+    query_parts = ["status=candidate"]
+    if memory_type:
+        query_parts.append(f"memory_type={urllib.parse.quote(memory_type)}")
+    if project:
+        query_parts.append(f"project={urllib.parse.quote(project)}")
+    query_parts.append(f"limit={int(limit)}")
+    listing = request("GET", "/memory?" + "&".join(query_parts))
+    memories = listing.get("memories", []) if isinstance(listing, dict) else []
+
+    if not memories:
+        print_json({"status": "empty_queue", "count": 0})
+        return 0
+
+    promoted = 0
+    rejected = 0
+    skipped = 0
+    stopped_early = False
+
+    print(f"Triage queue: {len(memories)} candidate(s)\n", file=sys.stderr)
+    for idx, mem in enumerate(memories, 1):
+        mid = mem.get("id", "")
+        print(f"[{idx}/{len(memories)}] {mem.get('memory_type','?')}  project={mem.get('project','')}  conf={mem.get('confidence','?')}", file=sys.stderr)
+        print(f"  id: {mid}", file=sys.stderr)
+        print(f"  {mem.get('content','')}", file=sys.stderr)
+        try:
+            choice = input("  (p)romote / (r)eject / (s)kip / (q)uit > ").strip().lower()
+        except EOFError:
+            stopped_early = True
+            break
+        if choice in {"q", "quit"}:
+            stopped_early = True
+            break
+        if choice in {"p", "promote"}:
+            request("POST", f"/memory/{urllib.parse.quote(mid, safe='')}/promote", {})
+            promoted += 1
+            print("  -> promoted", file=sys.stderr)
+        elif choice in {"r", "reject"}:
+            request("POST", f"/memory/{urllib.parse.quote(mid, safe='')}/reject", {})
+            rejected += 1
+            print("  -> rejected", file=sys.stderr)
+        else:
+            skipped += 1
+            print("  -> skipped", file=sys.stderr)
+
+    print_json(
+        {
+            "reviewed": promoted + rejected + skipped,
+            "promoted": promoted,
+            "rejected": rejected,
+            "skipped": skipped,
+            "stopped_early": stopped_early,
+            "remaining_in_queue": len(memories) - (promoted + rejected + skipped) - (1 if stopped_early else 0),
+        }
+    )
+    return 0
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

scripts/eval_data/candidate_queue_snapshot.jsonl

@@ -0,0 +1,51 @@
+{"id": "0dd85386-cace-4f9a-9098-c6732f3c64fa", "type": "project", "project": "atocore", "confidence": 0.5, "content": "AtoCore roadmap: (1) extractor improvement, (2) harness expansion, (3) Wave 2 ingestion, (4) OpenClaw finish; steps 1+2 are current mini-phase"}
+{"id": "8939b875-152c-4c90-8614-3cfdc64cd1d6", "type": "knowledge", "project": "atocore", "confidence": 0.5, "content": "AtoCore is FastAPI (Python 3.12, SQLite + ChromaDB) on Dalidou home server (dalidou:8100), repo C:\\Users\\antoi\\ATOCore, data /srv/storage/atocore/, ingests Obsidian vault + Google Drive into vector memory system."}
+{"id": "93e37d2a-b512-4a97-b230-e64ac913d087", "type": "knowledge", "project": "atocore", "confidence": 0.5, "content": "Deploy AtoCore: git push origin main, then ssh papa@dalidou and run /srv/storage/atocore/app/deploy/dalidou/deploy.sh"}
+{"id": "4b82fe01-4393-464a-b935-9ad5d112d3d8", "type": "adaptation", "project": "atocore", "confidence": 0.5, "content": "Do not add memory extraction to interaction capture hot path; keep extraction as separate batch/manual step. Reason: latency and queue noise before review rhythm is comfortable."}
+{"id": "c873ec00-063e-488c-ad32-1233290a3feb", "type": "project", "project": "atocore", "confidence": 0.5, "content": "As of 2026-04-11, approved roadmap in order: observe reinforcement, batch extraction, candidate triage, off-Dalidou backup, retrieval quality review."}
+{"id": "665cdd27-0057-4e73-82f5-5d4f47189b5d", "type": "project", "project": "atocore", "confidence": 0.5, "content": "AtoCore adopts DEV-LEDGER.md as shared operating memory with stable headers; updated at session boundaries"}
+{"id": "5f89c51d-7e8b-4fb9-830d-a35bb649f9f7", "type": "adaptation", "project": "atocore", "confidence": 0.5, "content": "Codex branches for AtoCore fork from main (never orphan); use naming pattern codex/<topic>"}
+{"id": "25ac367c-8bbe-4ba4-8d8e-d533db33f2d9", "type": "adaptation", "project": "atocore", "confidence": 0.5, "content": "In AtoCore, Claude builds and Codex audits; never work in parallel on same files"}
+{"id": "89446ebe-fd42-4177-80db-3657bc41d048", "type": "adaptation", "project": "atocore", "confidence": 0.5, "content": "In AtoCore, P1-severity findings in DEV-LEDGER.md block further main commits until acknowledged"}
+{"id": "1f077e98-f945-4480-96ab-110b0671ebc6", "type": "adaptation", "project": "atocore", "confidence": 0.5, "content": "Every AtoCore session appends to DEV-LEDGER.md Session Log and updates Orientation before ending"}
+{"id": "89f60018-c23b-4b2f-80ca-e6f7d02c5cd3", "type": "preference", "project": "atocore", "confidence": 0.5, "content": "User prefers receiving standalone testing prompts they can paste into Claude Code on target deployments rather than having the assistant run tests directly."}
+{"id": "2f69a6ed-6de2-4565-87df-1ea3e8c42963", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "USB SSD on RPi is mandatory for polishing telemetry storage; must be independent of network for data integrity during runs."}
+{"id": "6bcaebde-9e45-4de5-a220-65d9c4cd451e", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Use Tailscale mesh for RPi remote access to provide SSH, file transfer, and NAT traversal without port forwarding."}
+{"id": "82f17880-92da-485e-a24a-0599ab1836e7", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Auto-sync telemetry data via rsync over Tailscale after runs complete; fire-and-forget pattern with automatic retry on network interruption."}
+{"id": "2dd36f74-db47-4c72-a185-fec025d07d4f", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Real-time telemetry monitoring should target 10 Hz downsampling; full 100 Hz streaming over network is not necessary."}
+{"id": "7519d82b-8065-41f0-812e-9c1a3573d7b9", "type": "knowledge", "project": "p06-polisher", "confidence": 0.5, "content": "Polishing telemetry data rate is approximately 29 MB per hour (100 Hz × 20 channels × 4 bytes = 8 KB/s)."}
+{"id": "78678162-5754-478b-b1fc-e25f22e0ee03", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Machine spec (shareable) + Atomaste spec (internal) separate concerns. Machine spec hides program generation as 'separate scope' to protect IP/business strategy."}
+{"id": "6657b4ae-d4ec-4fec-a66f-2975cdb10d13", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Firmware interface contract is invariant: controller-job.v1 input, run-log.v1 + telemetry output. No firmware changes needed regardless of program generation implementation."}
+{"id": "6d6f4fe9-73e5-449f-a802-6dc0a974f87b", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Atomaste sim spec documents forward/return paths, calibration model (Preston k), translation loss, and service/IP strategy—details hidden from shareable machine spec."}
+{"id": "932f38df-58f3-49c2-9968-8d422dc54b42", "type": "project", "project": "", "confidence": 0.5, "content": "USB SSD mandatory for storage (not SD card); directory structure /data/runs/{id}/, /data/manual/{id}/; status.json for machine state"}
+{"id": "2b3178e8-fe38-4338-b2b0-75a01da18cea", "type": "project", "project": "", "confidence": 0.5, "content": "RPi joins Tailscale mesh for remote access over SSH VPN; no public IP or port forwarding; fully offline operation"}
+{"id": "254c394d-3f80-4b34-a891-9f1cbfec74d7", "type": "project", "project": "", "confidence": 0.5, "content": "Data synchronization via rsync over Tailscale, failure-tolerant and non-blocking; USB stick as manual fallback"}
+{"id": "ee626650-1ee0-439c-85c9-6d32a876f239", "type": "project", "project": "", "confidence": 0.5, "content": "Machine design principle: works fully offline and independently; network connection is for remote access only"}
+{"id": "34add99d-8d2e-4586-b002-fc7b7d22bcb3", "type": "project", "project": "", "confidence": 0.5, "content": "No cloud, no real-time streaming, no remote control features in design scope"}
+{"id": "993e0afe-9910-4984-b608-f5e9de7c0453", "type": "project", "project": "atocore", "confidence": 0.5, "content": "P1: Reflection loop integration incomplete—extraction remains manual (POST /interactions/{id}/extract), not auto-triggered with reinforcement. Live capture won't auto-populate candidate review queue."}
+{"id": "bdf488d7-9200-441e-afbf-5335020ea78b", "type": "project", "project": "atocore", "confidence": 0.5, "content": "P1: Project memories excluded from context injection; build_context() requests [\"identity\", \"preference\"] only. Reinforcement signal doesn't reach assembled context packs."}
+{"id": "188197af-a61d-4616-9e39-712aeaaadf61", "type": "project", "project": "atocore", "confidence": 0.5, "content": "Current batch-extract rules produce only 1 candidate from 42 real captures. Extractor needs conversational-cue detection or LLM-assisted path to improve yield."}
+{"id": "acffcaa4-5966-4ec1-a0b2-3b8dcebe75bd", "type": "project", "project": "atocore", "confidence": 0.5, "content": "Next priority: extractor rule expansion (cheapest validation of reflection loop), then Wave 2 trusted operational ingestion (master-plan priority). Defer retrieval eval harness focus."}
+{"id": "1b44a886-a5af-4426-bf10-a92baf3a6502", "type": "knowledge", "project": "atocore", "confidence": 0.5, "content": "Alias canonicalization fix (resolve_project_name() boundary) is consistently applied across project state, memories, interactions, and context lookup. Code review approved directionally."}
+{"id": "e8f4e704-367b-4759-b20c-da0ccf06cf7d", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Machine capabilities now define z_type: engage_retract and cam_type: mechanical_with_encoder instead of actuator-driven setpoints."}
+{"id": "ab2b607c-52b1-405f-a874-c6078393c21c", "type": "knowledge", "project": "", "confidence": 0.5, "content": "Codex is an audit agent; communicate with it via markdown prompts with numbered steps; it updates findings via commits to codex/* branches or direct messages."}
+{"id": "5a5fd29d-291f-4e22-88fe-825cf55f745a", "type": "preference", "project": "", "confidence": 0.5, "content": "Audit-first workflow recommended: have codex audit DEV-LEDGER.md and recent commits before execution; validates round-trip, catches errors early."}
+{"id": "4c238106-017e-4283-99a1-639497b6ddde", "type": "knowledge", "project": "", "confidence": 0.5, "content": "DEV-LEDGER.md at repo root is the shared coordination document with Orientation, Active Plan, and Open Review Findings sections."}
+{"id": "83aed988-4257-4220-b612-6c725d6cd95a", "type": "project", "project": "atocore", "confidence": 0.5, "content": "Roadmap: Extractor improvement → Harness expansion → Wave 2 trusted operational ingestion → Finish OpenClaw integration (in that order)"}
+{"id": "95d87d1a-5daa-414d-95ff-a344a62e0b6b", "type": "project", "project": "atocore", "confidence": 0.5, "content": "Phase 1 (Extractor): eval-driven loop—label captures, improve rules/add LLM mode, measure yield & FP, stop when queue reviewable (not coverage metrics)"}
+{"id": "7aafb588-51b0-4536-a414-ebaaea924b98", "type": "project", "project": "atocore", "confidence": 0.5, "content": "Phases 1 & 2 (Extractor + Harness) are a mini-phase; without harness, extractor improvements are blind edits"}
+{"id": "aa50c51a-27d7-4db9-b7a3-7ca75dba2118", "type": "knowledge", "project": "", "confidence": 0.5, "content": "Dalidou stores Claude Code interactions via a Stop hook that fires after each turn and POSTs to http://dalidou:8100/interactions with client=claude-code parameter"}
+{"id": "5951108b-3a5e-49d0-9308-dfab449664d3", "type": "adaptation", "project": "", "confidence": 0.5, "content": "Interaction capture system is passive and automatic; no manual action required, interactions accumulate automatically during normal Claude Code usage"}
+{"id": "9d2cbbe9-cf2e-4aab-9cb8-c4951da70826", "type": "project", "project": "", "confidence": 0.5, "content": "Session Log/Ledger system tracks work state across sessions so future sessions immediately know what is true and what is next; phases marked by git SHAs."}
+{"id": "db88eecf-e31a-4fee-b07d-0b51db7e315e", "type": "project", "project": "atocore", "confidence": 0.5, "content": "atocore uses multi-model coordination: Claude and codex share DEV-LEDGER.md (current state / active plan / P1+P2 findings / recent decisions / commit log) read at session start, appended at session end"}
+{"id": "8748f071-ff28-47a6-8504-65ca30a8336a", "type": "project", "project": "atocore", "confidence": 0.5, "content": "atocore starts with manual-event-loop (/audit or /status prompts) using DEV-LEDGER.md before upgrading to automated git hooks/CI review"}
+{"id": "f9210883-67a8-4dae-9f27-6b5ae7bd8a6b", "type": "project", "project": "atocore", "confidence": 0.5, "content": "atocore development involves coordinating between Claude and codex models with shared plan/review strategy and counter-validation to improve system quality"}
+{"id": "85f008b9-2d6d-49ad-81a1-e254dac2a2ac", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Z-axis is a binary engage/retract mechanism (z_engaged bool), not continuous position control; confirmation timeout z_engage_timeout_s required."}
+{"id": "0cc417ed-ac38-4231-9786-a9582ac6a60f", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Cam amplitude and offset are mechanically set by operator and read via encoders; no actuators control them, controller receives encoder telemetry only."}
+{"id": "2e001aaf-0c5c-4547-9b96-ebc4172b258d", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Cam parameters in controller are expected_cam_amplitude_deg and expected_cam_offset_deg (read-only reference for verification), not command setpoints."}
+{"id": "47778126-b0cf-41d9-9e21-f2418f53e792", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Manual mode UI displays cam encoder readings (cam_amplitude_deg, cam_offset_deg) as read-only for operator verification of mechanical setting."}
+{"id": "410e4a70-ae12-4de2-8f31-071ffee3cad4", "type": "project", "project": "p06-polisher", "confidence": 0.5, "content": "Manual session log records cam_setting measured at session start; run-log segment actual block includes cam_amplitude_deg_mean and cam_offset_deg_mean."}
+{"id": "e94f94f0-3538-40dd-aef2-0189eacc7eb7", "type": "knowledge", "project": "atocore", "confidence": 0.5, "content": "AtoCore deployments to dalidou use the script /srv/storage/atocore/app/deploy/dalidou/deploy.sh instead of manual docker commands"}
+{"id": "23fa6fdf-cfb9-4850-ad04-3ea56551c30a", "type": "project", "project": "", "confidence": 0.5, "content": "Retrieval/extraction evaluation follows 8-day mini-phase plan with hard gates to prevent scope drift. Preflight checks must validate git SHAs, baselines, and fixture stability before coding."}
+{"id": "3e1fad28-031b-4670-a9d0-0af2e8ba1361", "type": "project", "project": "", "confidence": 0.5, "content": "Day 1: Create labeled extractor eval set from 30 captures (10 zero-candidate, 10 single-candidate, 10 ambiguous) with metadata; create scoring tool to measure precision/recall."}
+{"id": "d49378a4-d03c-4730-be87-f0fcb2d199db", "type": "project", "project": "", "confidence": 0.5, "content": "Day 2: Measure current extractor against labeled set, recording yield, true/false positives, and false negatives by pattern."}

scripts/eval_data/extractor_labels_2026-04-11.json

@@ -0,0 +1,145 @@
+{
+  "version": "0.1",
+  "frozen_at": "2026-04-11",
+  "snapshot_file": "scripts/eval_data/interactions_snapshot_2026-04-11.json",
+  "labeled_count": 20,
+  "plan_deviation": "Codex's plan called for 30 labeled interactions (10 zero / 10 plausible / 10 ambiguous). Actual corpus is heavily skewed toward instructional/status content; after reading 20 drawn by length-stratified random sample, the honest positive rate is ~25% (5/20). Labeling more would mostly add zeros; the Day 2 measurement is not bottlenecked on sample size.",
+  "positive_count": 5,
+  "labels": [
+    {
+      "id": "ab239158-d6ac-4c51-b6e4-dd4ccea384a2",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Instructional deploy guidance. No durable claim."
+    },
+    {
+      "id": "da153f2a-b20a-4dee-8c72-431ebb71f08c",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "'Deploy still in progress.' Pure status."
+    },
+    {
+      "id": "7d8371ee-c6d3-4dfe-a7b0-2d091f075c15",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Git command walkthrough. No durable claim."
+    },
+    {
+      "id": "14bf3f90-e318-466e-81ac-d35522741ba5",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Ledger status update. Transient fact, not a durable memory candidate."
+    },
+    {
+      "id": "8f855235-c38d-4c27-9f2b-8530ebe1a2d8",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Short-term recommendation ('merge to main and deploy'), not a standing decision."
+    },
+    {
+      "id": "04a96eb5-cd00-4e9f-9252-b2cc919000a4",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Dev server config table. Operational detail, not a memory."
+    },
+    {
+      "id": "79d606ed-8981-454a-83af-c25226b1b65c",
+      "expected_count": 1,
+      "expected_type": "adaptation",
+      "expected_project": "",
+      "expected_snippet": "shared DEV-LEDGER as operating memory",
+      "miss_class": "recommendation_prose",
+      "notes": "A recommendation that later became a ratified decision. Rule extractor would need a 'simplest version that could work today' / 'I'd start with' cue class."
+    },
+    {
+      "id": "a6b0d279-c564-4bce-a703-e476f4a148ad",
+      "expected_count": 2,
+      "expected_type": "project",
+      "expected_project": "p06-polisher",
+      "expected_snippet": "z_engaged bool; cam amplitude set mechanically and read by encoders",
+      "miss_class": "architectural_change_summary",
+      "notes": "Two durable architectural facts about the polisher machine (Z-axis is engage/retract, cam is read-only). Extractor would need to recognize 'A is now B' / 'X removed, Y added' patterns."
+    },
+    {
+      "id": "4e00e398-2e89-4653-8ee5-3f65c7f4d2d3",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Clarification question to user."
+    },
+    {
+      "id": "a6a7816a-7590-4616-84f4-49d9054c2a91",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Instructional response offering two next moves."
+    },
+    {
+      "id": "03527502-316a-4a3e-989c-00719392c7d1",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Troubleshooting a paste failure. Ephemeral."
+    },
+    {
+      "id": "1fff59fc-545f-42df-9dd1-a0e6dec1b7ee",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Agreement + follow-up question. No durable claim."
+    },
+    {
+      "id": "eb65dc18-0030-4720-ace7-f55af9df719d",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Explanation of how the capture hook works. Instructional."
+    },
+    {
+      "id": "52c8c0f3-32fb-4b48-9065-73c778a08417",
+      "expected_count": 1,
+      "expected_type": "project",
+      "expected_project": "p06-polisher",
+      "expected_snippet": "USB SSD mandatory on RPi; Tailscale for remote access",
+      "miss_class": "spec_update_announcement",
+      "notes": "Concrete architectural commitments just added to the polisher spec. Phrased as '§17.1 Local Storage - USB SSD mandatory, not SD card.' The '§' section markers could be a new cue."
+    },
+    {
+      "id": "32d40414-15af-47ee-944b-2cceae9574b8",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Session recap. Historical summary, not a durable memory."
+    },
+    {
+      "id": "b6d2cdfc-37fb-459a-96bd-caefb9beaab4",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Deployment prompt for Dalidou. Operational, not a memory."
+    },
+    {
+      "id": "ee03d823-931b-4d4e-9258-88b4ed5eeb07",
+      "expected_count": 2,
+      "expected_type": "knowledge",
+      "expected_project": "p06-polisher",
+      "expected_snippet": "USB SSD is non-negotiable for local storage; Tailscale mesh for SSH/file transfer",
+      "miss_class": "layered_recommendation",
+      "notes": "Layered infra recommendation with 'non-negotiable' / 'strongly recommended' strength markers. The 'non-negotiable' token could be a new cue class."
+    },
+    {
+      "id": "dd234d9f-0d1c-47e8-b01c-eebcb568c7e7",
+      "expected_count": 1,
+      "expected_type": "project",
+      "expected_project": "p06-polisher",
+      "expected_snippet": "interface contract is identical regardless of who generates the programs; machine is a standalone box",
+      "miss_class": "alignment_assertion",
+      "notes": "Architectural invariant assertion. '**Alignment verified**' / 'nothing changes for X' style. Likely too subtle for rule matching without LLM assistance."
+    },
+    {
+      "id": "1f95891a-cf37-400e-9d68-4fad8e04dcbb",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Huge session handoff prompt. Informational only."
+    },
+    {
+      "id": "5580950f-d010-4544-be4b-b3071271a698",
+      "expected_count": 0,
+      "miss_class": "n/a",
+      "notes": "Ledger schema sketch. Structural design proposal, later ratified — but the same idea was already captured as a ratified decision in the recent decisions section, so not worth re-extracting from this conversational form."
+    }
+  ]
+}

scripts/eval_data/extractor_llm_baseline_2026-04-11.json

@@ -0,0 +1,518 @@
+{
+  "summary": {
+    "total": 20,
+    "exact_match": 6,
+    "positive_expected": 5,
+    "total_expected_candidates": 7,
+    "total_actual_candidates": 51,
+    "yield_rate": 2.55,
+    "recall": 1.0,
+    "precision": 0.357,
+    "false_positive_interactions": 9,
+    "false_negative_interactions": 0,
+    "miss_classes": {},
+    "mode": "llm"
+  },
+  "results": [
+    {
+      "id": "ab239158-d6ac-4c51-b6e4-dd4ccea384a2",
+      "expected_count": 0,
+      "actual_count": 1,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Instructional deploy guidance. No durable claim.",
+      "actual_candidates": [
+        {
+          "memory_type": "knowledge",
+          "content": "AtoCore deployments to dalidou use the script /srv/storage/atocore/app/deploy/dalidou/deploy.sh instead of manual docker commands",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "da153f2a-b20a-4dee-8c72-431ebb71f08c",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "'Deploy still in progress.' Pure status.",
+      "actual_candidates": []
+    },
+    {
+      "id": "7d8371ee-c6d3-4dfe-a7b0-2d091f075c15",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "Git command walkthrough. No durable claim.",
+      "actual_candidates": []
+    },
+    {
+      "id": "14bf3f90-e318-466e-81ac-d35522741ba5",
+      "expected_count": 0,
+      "actual_count": 4,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Ledger status update. Transient fact, not a durable memory candidate.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "Retrieval/extraction evaluation follows 8-day mini-phase plan with hard gates to prevent scope drift. Preflight checks must validate git SHAs, baselines, and fixture stability before coding.",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Day 1: Create labeled extractor eval set from 30 captures (10 zero-candidate, 10 single-candidate, 10 ambiguous) with metadata; create scoring tool to measure precision/recall.",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Day 2: Measure current extractor against labeled set, recording yield, true/false positives, and false negatives by pattern.",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Session Log/Ledger system tracks work state across sessions so future sessions immediately know what is true and what is next; phases marked by git SHAs.",
+          "project": "",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "8f855235-c38d-4c27-9f2b-8530ebe1a2d8",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "Short-term recommendation ('merge to main and deploy'), not a standing decision.",
+      "actual_candidates": []
+    },
+    {
+      "id": "04a96eb5-cd00-4e9f-9252-b2cc919000a4",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "Dev server config table. Operational detail, not a memory.",
+      "actual_candidates": []
+    },
+    {
+      "id": "79d606ed-8981-454a-83af-c25226b1b65c",
+      "expected_count": 1,
+      "actual_count": 3,
+      "ok": false,
+      "miss_class": "recommendation_prose",
+      "notes": "A recommendation that later became a ratified decision. Rule extractor would need a 'simplest version that could work today' / 'I'd start with' cue class.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "atocore uses multi-model coordination: Claude and codex share DEV-LEDGER.md (current state / active plan / P1+P2 findings / recent decisions / commit log) read at session start, appended at session end",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "atocore starts with manual-event-loop (/audit or /status prompts) using DEV-LEDGER.md before upgrading to automated git hooks/CI review",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "atocore development involves coordinating between Claude and codex models with shared plan/review strategy and counter-validation to improve system quality",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "a6b0d279-c564-4bce-a703-e476f4a148ad",
+      "expected_count": 2,
+      "actual_count": 6,
+      "ok": false,
+      "miss_class": "architectural_change_summary",
+      "notes": "Two durable architectural facts about the polisher machine (Z-axis is engage/retract, cam is read-only). Extractor would need to recognize 'A is now B' / 'X removed, Y added' patterns.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "Z-axis is a binary engage/retract mechanism (z_engaged bool), not continuous position control; confirmation timeout z_engage_timeout_s required.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Cam amplitude and offset are mechanically set by operator and read via encoders; no actuators control them, controller receives encoder telemetry only.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Cam parameters in controller are expected_cam_amplitude_deg and expected_cam_offset_deg (read-only reference for verification), not command setpoints.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Manual mode UI displays cam encoder readings (cam_amplitude_deg, cam_offset_deg) as read-only for operator verification of mechanical setting.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Manual session log records cam_setting measured at session start; run-log segment actual block includes cam_amplitude_deg_mean and cam_offset_deg_mean.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Machine capabilities now define z_type: engage_retract and cam_type: mechanical_with_encoder instead of actuator-driven setpoints.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "4e00e398-2e89-4653-8ee5-3f65c7f4d2d3",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "Clarification question to user.",
+      "actual_candidates": []
+    },
+    {
+      "id": "a6a7816a-7590-4616-84f4-49d9054c2a91",
+      "expected_count": 0,
+      "actual_count": 3,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Instructional response offering two next moves.",
+      "actual_candidates": [
+        {
+          "memory_type": "knowledge",
+          "content": "Codex is an audit agent; communicate with it via markdown prompts with numbered steps; it updates findings via commits to codex/* branches or direct messages.",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "preference",
+          "content": "Audit-first workflow recommended: have codex audit DEV-LEDGER.md and recent commits before execution; validates round-trip, catches errors early.",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "knowledge",
+          "content": "DEV-LEDGER.md at repo root is the shared coordination document with Orientation, Active Plan, and Open Review Findings sections.",
+          "project": "",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "03527502-316a-4a3e-989c-00719392c7d1",
+      "expected_count": 0,
+      "actual_count": 0,
+      "ok": true,
+      "miss_class": "n/a",
+      "notes": "Troubleshooting a paste failure. Ephemeral.",
+      "actual_candidates": []
+    },
+    {
+      "id": "1fff59fc-545f-42df-9dd1-a0e6dec1b7ee",
+      "expected_count": 0,
+      "actual_count": 3,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Agreement + follow-up question. No durable claim.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "Roadmap: Extractor improvement → Harness expansion → Wave 2 trusted operational ingestion → Finish OpenClaw integration (in that order)",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Phase 1 (Extractor): eval-driven loop—label captures, improve rules/add LLM mode, measure yield & FP, stop when queue reviewable (not coverage metrics)",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Phases 1 & 2 (Extractor + Harness) are a mini-phase; without harness, extractor improvements are blind edits",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "eb65dc18-0030-4720-ace7-f55af9df719d",
+      "expected_count": 0,
+      "actual_count": 2,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Explanation of how the capture hook works. Instructional.",
+      "actual_candidates": [
+        {
+          "memory_type": "knowledge",
+          "content": "Dalidou stores Claude Code interactions via a Stop hook that fires after each turn and POSTs to http://dalidou:8100/interactions with client=claude-code parameter",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "Interaction capture system is passive and automatic; no manual action required, interactions accumulate automatically during normal Claude Code usage",
+          "project": "",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "52c8c0f3-32fb-4b48-9065-73c778a08417",
+      "expected_count": 1,
+      "actual_count": 5,
+      "ok": false,
+      "miss_class": "spec_update_announcement",
+      "notes": "Concrete architectural commitments just added to the polisher spec. Phrased as '§17.1 Local Storage - USB SSD mandatory, not SD card.' The '§' section markers could be a new cue.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "USB SSD mandatory for storage (not SD card); directory structure /data/runs/{id}/, /data/manual/{id}/; status.json for machine state",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "RPi joins Tailscale mesh for remote access over SSH VPN; no public IP or port forwarding; fully offline operation",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Data synchronization via rsync over Tailscale, failure-tolerant and non-blocking; USB stick as manual fallback",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Machine design principle: works fully offline and independently; network connection is for remote access only",
+          "project": "",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "No cloud, no real-time streaming, no remote control features in design scope",
+          "project": "",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "32d40414-15af-47ee-944b-2cceae9574b8",
+      "expected_count": 0,
+      "actual_count": 5,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Session recap. Historical summary, not a durable memory.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "P1: Reflection loop integration incomplete—extraction remains manual (POST /interactions/{id}/extract), not auto-triggered with reinforcement. Live capture won't auto-populate candidate review queue.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "P1: Project memories excluded from context injection; build_context() requests [\"identity\", \"preference\"] only. Reinforcement signal doesn't reach assembled context packs.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Current batch-extract rules produce only 1 candidate from 42 real captures. Extractor needs conversational-cue detection or LLM-assisted path to improve yield.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Next priority: extractor rule expansion (cheapest validation of reflection loop), then Wave 2 trusted operational ingestion (master-plan priority). Defer retrieval eval harness focus.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "knowledge",
+          "content": "Alias canonicalization fix (resolve_project_name() boundary) is consistently applied across project state, memories, interactions, and context lookup. Code review approved directionally.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "b6d2cdfc-37fb-459a-96bd-caefb9beaab4",
+      "expected_count": 0,
+      "actual_count": 1,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Deployment prompt for Dalidou. Operational, not a memory.",
+      "actual_candidates": [
+        {
+          "memory_type": "preference",
+          "content": "User prefers receiving standalone testing prompts they can paste into Claude Code on target deployments rather than having the assistant run tests directly.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "ee03d823-931b-4d4e-9258-88b4ed5eeb07",
+      "expected_count": 2,
+      "actual_count": 5,
+      "ok": false,
+      "miss_class": "layered_recommendation",
+      "notes": "Layered infra recommendation with 'non-negotiable' / 'strongly recommended' strength markers. The 'non-negotiable' token could be a new cue class.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "USB SSD on RPi is mandatory for polishing telemetry storage; must be independent of network for data integrity during runs.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Use Tailscale mesh for RPi remote access to provide SSH, file transfer, and NAT traversal without port forwarding.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Auto-sync telemetry data via rsync over Tailscale after runs complete; fire-and-forget pattern with automatic retry on network interruption.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Real-time telemetry monitoring should target 10 Hz downsampling; full 100 Hz streaming over network is not necessary.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "knowledge",
+          "content": "Polishing telemetry data rate is approximately 29 MB per hour (100 Hz × 20 channels × 4 bytes = 8 KB/s).",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "dd234d9f-0d1c-47e8-b01c-eebcb568c7e7",
+      "expected_count": 1,
+      "actual_count": 3,
+      "ok": false,
+      "miss_class": "alignment_assertion",
+      "notes": "Architectural invariant assertion. '**Alignment verified**' / 'nothing changes for X' style. Likely too subtle for rule matching without LLM assistance.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "Machine spec (shareable) + Atomaste spec (internal) separate concerns. Machine spec hides program generation as 'separate scope' to protect IP/business strategy.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Firmware interface contract is invariant: controller-job.v1 input, run-log.v1 + telemetry output. No firmware changes needed regardless of program generation implementation.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "Atomaste sim spec documents forward/return paths, calibration model (Preston k), translation loss, and service/IP strategy—details hidden from shareable machine spec.",
+          "project": "p06-polisher",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "1f95891a-cf37-400e-9d68-4fad8e04dcbb",
+      "expected_count": 0,
+      "actual_count": 4,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Huge session handoff prompt. Informational only.",
+      "actual_candidates": [
+        {
+          "memory_type": "knowledge",
+          "content": "AtoCore is FastAPI (Python 3.12, SQLite + ChromaDB) on Dalidou home server (dalidou:8100), repo C:\\Users\\antoi\\ATOCore, data /srv/storage/atocore/, ingests Obsidian vault + Google Drive into vector memory system.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "knowledge",
+          "content": "Deploy AtoCore: git push origin main, then ssh papa@dalidou and run /srv/storage/atocore/app/deploy/dalidou/deploy.sh",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "Do not add memory extraction to interaction capture hot path; keep extraction as separate batch/manual step. Reason: latency and queue noise before review rhythm is comfortable.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "As of 2026-04-11, approved roadmap in order: observe reinforcement, batch extraction, candidate triage, off-Dalidou backup, retrieval quality review.",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    },
+    {
+      "id": "5580950f-d010-4544-be4b-b3071271a698",
+      "expected_count": 0,
+      "actual_count": 6,
+      "ok": false,
+      "miss_class": "n/a",
+      "notes": "Ledger schema sketch. Structural design proposal, later ratified — but the same idea was already captured as a ratified decision in the recent decisions section, so not worth re-extracting from this conversational form.",
+      "actual_candidates": [
+        {
+          "memory_type": "project",
+          "content": "AtoCore adopts DEV-LEDGER.md as shared operating memory with stable headers; updated at session boundaries",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "Codex branches for AtoCore fork from main (never orphan); use naming pattern codex/<topic>",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "In AtoCore, Claude builds and Codex audits; never work in parallel on same files",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "In AtoCore, P1-severity findings in DEV-LEDGER.md block further main commits until acknowledged",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "adaptation",
+          "content": "Every AtoCore session appends to DEV-LEDGER.md Session Log and updates Orientation before ending",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        },
+        {
+          "memory_type": "project",
+          "content": "AtoCore roadmap: (1) extractor improvement, (2) harness expansion, (3) Wave 2 ingestion, (4) OpenClaw finish; steps 1+2 are current mini-phase",
+          "project": "atocore",
+          "rule": "llm_extraction"
+        }
+      ]
+    }
+  ]
+}

scripts/eval_data/triage_verdict_2026-04-12.json

@@ -0,0 +1 @@
+{"promote": ["4b82fe01-4393-464a-b935-9ad5d112d3d8", "665cdd27-0057-4e73-82f5-5d4f47189b5d", "5f89c51d-7e8b-4fb9-830d-a35bb649f9f7", "25ac367c-8bbe-4ba4-8d8e-d533db33f2d9", "2f69a6ed-6de2-4565-87df-1ea3e8c42963", "6bcaebde-9e45-4de5-a220-65d9c4cd451e", "2dd36f74-db47-4c72-a185-fec025d07d4f", "7519d82b-8065-41f0-812e-9c1a3573d7b9", "78678162-5754-478b-b1fc-e25f22e0ee03", "6657b4ae-d4ec-4fec-a66f-2975cdb10d13", "ee626650-1ee0-439c-85c9-6d32a876f239", "1b44a886-a5af-4426-bf10-a92baf3a6502", "aa50c51a-27d7-4db9-b7a3-7ca75dba2118", "5951108b-3a5e-49d0-9308-dfab449664d3", "85f008b9-2d6d-49ad-81a1-e254dac2a2ac", "0cc417ed-ac38-4231-9786-a9582ac6a60f"], "reject": ["0dd85386-cace-4f9a-9098-c6732f3c64fa", "8939b875-152c-4c90-8614-3cfdc64cd1d6", "93e37d2a-b512-4a97-b230-e64ac913d087", "c873ec00-063e-488c-ad32-1233290a3feb", "89446ebe-fd42-4177-80db-3657bc41d048", "1f077e98-f945-4480-96ab-110b0671ebc6", "89f60018-c23b-4b2f-80ca-e6f7d02c5cd3", "82f17880-92da-485e-a24a-0599ab1836e7", "6d6f4fe9-73e5-449f-a802-6dc0a974f87b", "932f38df-58f3-49c2-9968-8d422dc54b42", "2b3178e8-fe38-4338-b2b0-75a01da18cea", "254c394d-3f80-4b34-a891-9f1cbfec74d7", "34add99d-8d2e-4586-b002-fc7b7d22bcb3", "993e0afe-9910-4984-b608-f5e9de7c0453", "bdf488d7-9200-441e-afbf-5335020ea78b", "188197af-a61d-4616-9e39-712aeaaadf61", "acffcaa4-5966-4ec1-a0b2-3b8dcebe75bd", "e8f4e704-367b-4759-b20c-da0ccf06cf7d", "ab2b607c-52b1-405f-a874-c6078393c21c", "5a5fd29d-291f-4e22-88fe-825cf55f745a", "4c238106-017e-4283-99a1-639497b6ddde", "83aed988-4257-4220-b612-6c725d6cd95a", "95d87d1a-5daa-414d-95ff-a344a62e0b6b", "7aafb588-51b0-4536-a414-ebaaea924b98", "9d2cbbe9-cf2e-4aab-9cb8-c4951da70826", "db88eecf-e31a-4fee-b07d-0b51db7e315e", "8748f071-ff28-47a6-8504-65ca30a8336a", "f9210883-67a8-4dae-9f27-6b5ae7bd8a6b", "2e001aaf-0c5c-4547-9b96-ebc4172b258d", "47778126-b0cf-41d9-9e21-f2418f53e792", "410e4a70-ae12-4de2-8f31-071ffee3cad4", "e94f94f0-3538-40dd-aef2-0189eacc7eb7", "23fa6fdf-cfb9-4850-ad04-3ea56551c30a", "3e1fad28-031b-4670-a9d0-0af2e8ba1361", "d49378a4-d03c-4730-be87-f0fcb2d199db"]}

scripts/extractor_eval.py

@@ -0,0 +1,274 @@
+"""Extractor eval runner — scores the rule-based extractor against a
+labeled interaction corpus.
+
+Pulls full interaction content from a frozen snapshot, runs each through
+``extract_candidates_from_interaction``, and compares the output to the
+expected counts from a labels file. Produces a per-label scorecard plus
+aggregate precision / recall / yield numbers.
+
+This harness deliberately stays file-based: snapshot + labels + this
+runner. No Dalidou HTTP dependency once the snapshot is frozen, so the
+eval is reproducible run-to-run even as live captures drift.
+
+Usage:
+
+    python scripts/extractor_eval.py                # human report
+    python scripts/extractor_eval.py --json         # machine-readable
+    python scripts/extractor_eval.py \\
+        --snapshot scripts/eval_data/interactions_snapshot_2026-04-11.json \\
+        --labels   scripts/eval_data/extractor_labels_2026-04-11.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Force UTF-8 on stdout so real LLM output (arrows, em-dashes, CJK)
+# doesn't crash the human report on Windows cp1252 consoles.
+if hasattr(sys.stdout, "buffer"):
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace", line_buffering=True)
+
+# Make src/ importable without requiring an install.
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_REPO_ROOT / "src"))
+
+from atocore.interactions.service import Interaction  # noqa: E402
+from atocore.memory.extractor import extract_candidates_from_interaction  # noqa: E402
+from atocore.memory.extractor_llm import extract_candidates_llm  # noqa: E402
+
+DEFAULT_SNAPSHOT = _REPO_ROOT / "scripts" / "eval_data" / "interactions_snapshot_2026-04-11.json"
+DEFAULT_LABELS = _REPO_ROOT / "scripts" / "eval_data" / "extractor_labels_2026-04-11.json"
+
+
+@dataclass
+class LabelResult:
+    id: str
+    expected_count: int
+    actual_count: int
+    ok: bool
+    miss_class: str
+    notes: str
+    actual_candidates: list[dict] = field(default_factory=list)
+
+
+def load_snapshot(path: Path) -> dict[str, dict]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {item["id"]: item for item in data.get("interactions", [])}
+
+
+def load_labels(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def interaction_from_snapshot(snap: dict) -> Interaction:
+    return Interaction(
+        id=snap["id"],
+        prompt=snap.get("prompt", "") or "",
+        response=snap.get("response", "") or "",
+        response_summary="",
+        project=snap.get("project", "") or "",
+        client=snap.get("client", "") or "",
+        session_id=snap.get("session_id", "") or "",
+        created_at=snap.get("created_at", "") or "",
+    )
+
+
+def score(snapshot: dict[str, dict], labels_doc: dict, mode: str = "rule") -> list[LabelResult]:
+    results: list[LabelResult] = []
+    for label in labels_doc["labels"]:
+        iid = label["id"]
+        snap = snapshot.get(iid)
+        if snap is None:
+            results.append(
+                LabelResult(
+                    id=iid,
+                    expected_count=int(label.get("expected_count", 0)),
+                    actual_count=-1,
+                    ok=False,
+                    miss_class="not_in_snapshot",
+                    notes=label.get("notes", ""),
+                )
+            )
+            continue
+        interaction = interaction_from_snapshot(snap)
+        if mode == "llm":
+            candidates = extract_candidates_llm(interaction)
+        else:
+            candidates = extract_candidates_from_interaction(interaction)
+        actual_count = len(candidates)
+        expected_count = int(label.get("expected_count", 0))
+        results.append(
+            LabelResult(
+                id=iid,
+                expected_count=expected_count,
+                actual_count=actual_count,
+                ok=(actual_count == expected_count),
+                miss_class=label.get("miss_class", "n/a"),
+                notes=label.get("notes", ""),
+                actual_candidates=[
+                    {
+                        "memory_type": c.memory_type,
+                        "content": c.content,
+                        "project": c.project,
+                        "rule": c.rule,
+                    }
+                    for c in candidates
+                ],
+            )
+        )
+    return results
+
+
+def aggregate(results: list[LabelResult]) -> dict:
+    total = len(results)
+    exact_match = sum(1 for r in results if r.ok)
+    true_positive = sum(1 for r in results if r.expected_count > 0 and r.actual_count > 0)
+    false_positive_interactions = sum(
+        1 for r in results if r.expected_count == 0 and r.actual_count > 0
+    )
+    false_negative_interactions = sum(
+        1 for r in results if r.expected_count > 0 and r.actual_count == 0
+    )
+    positive_expected = sum(1 for r in results if r.expected_count > 0)
+    total_expected_candidates = sum(r.expected_count for r in results)
+    total_actual_candidates = sum(max(r.actual_count, 0) for r in results)
+    yield_rate = total_actual_candidates / total if total else 0.0
+    # Recall over interaction count that had at least one expected candidate:
+    recall = true_positive / positive_expected if positive_expected else 0.0
+    # Precision over interaction count that produced any candidate:
+    precision_denom = true_positive + false_positive_interactions
+    precision = true_positive / precision_denom if precision_denom else 0.0
+    # Miss class breakdown
+    miss_classes: dict[str, int] = {}
+    for r in results:
+        if r.expected_count > 0 and r.actual_count == 0:
+            key = r.miss_class or "unlabeled"
+            miss_classes[key] = miss_classes.get(key, 0) + 1
+    return {
+        "total": total,
+        "exact_match": exact_match,
+        "positive_expected": positive_expected,
+        "total_expected_candidates": total_expected_candidates,
+        "total_actual_candidates": total_actual_candidates,
+        "yield_rate": round(yield_rate, 3),
+        "recall": round(recall, 3),
+        "precision": round(precision, 3),
+        "false_positive_interactions": false_positive_interactions,
+        "false_negative_interactions": false_negative_interactions,
+        "miss_classes": miss_classes,
+    }
+
+
+def print_human(results: list[LabelResult], summary: dict) -> None:
+    print("=== Extractor eval ===")
+    print(
+        f"labeled={summary['total']}  "
+        f"exact_match={summary['exact_match']}  "
+        f"positive_expected={summary['positive_expected']}"
+    )
+    print(
+        f"yield={summary['yield_rate']}  "
+        f"recall={summary['recall']}  "
+        f"precision={summary['precision']}"
+    )
+    print(
+        f"false_positives={summary['false_positive_interactions']}  "
+        f"false_negatives={summary['false_negative_interactions']}"
+    )
+    print()
+    print("miss class breakdown (FN):")
+    if summary["miss_classes"]:
+        for k, v in sorted(summary["miss_classes"].items(), key=lambda kv: -kv[1]):
+            print(f"  {v:3d}  {k}")
+    else:
+        print("  (none)")
+    print()
+    print("per-interaction:")
+    for r in results:
+        marker = "OK  " if r.ok else "MISS"
+        iid_short = r.id[:8]
+        print(f"  {marker}  {iid_short}  expected={r.expected_count}  actual={r.actual_count}  class={r.miss_class}")
+        if r.actual_candidates:
+            for c in r.actual_candidates:
+                preview = (c["content"] or "")[:80]
+                print(f"         [{c['memory_type']}] {preview}")
+
+
+def print_json(results: list[LabelResult], summary: dict) -> None:
+    payload = {
+        "summary": summary,
+        "results": [
+            {
+                "id": r.id,
+                "expected_count": r.expected_count,
+                "actual_count": r.actual_count,
+                "ok": r.ok,
+                "miss_class": r.miss_class,
+                "notes": r.notes,
+                "actual_candidates": r.actual_candidates,
+            }
+            for r in results
+        ],
+    }
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="AtoCore extractor eval")
+    parser.add_argument("--snapshot", type=Path, default=DEFAULT_SNAPSHOT)
+    parser.add_argument("--labels", type=Path, default=DEFAULT_LABELS)
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="write JSON result to this file (bypasses log/stdout interleaving)",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["rule", "llm"],
+        default="rule",
+        help="which extractor to score (default: rule)",
+    )
+    args = parser.parse_args()
+
+    snapshot = load_snapshot(args.snapshot)
+    labels = load_labels(args.labels)
+    results = score(snapshot, labels, mode=args.mode)
+    summary = aggregate(results)
+    summary["mode"] = args.mode
+
+    if args.output is not None:
+        payload = {
+            "summary": summary,
+            "results": [
+                {
+                    "id": r.id,
+                    "expected_count": r.expected_count,
+                    "actual_count": r.actual_count,
+                    "ok": r.ok,
+                    "miss_class": r.miss_class,
+                    "notes": r.notes,
+                    "actual_candidates": r.actual_candidates,
+                }
+                for r in results
+            ],
+        }
+        args.output.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        print(f"wrote {args.output}  ({summary['mode']}: recall={summary['recall']} precision={summary['precision']})")
+    elif args.json:
+        print_json(results, summary)
+    else:
+        print_human(results, summary)
+
+    return 0 if summary["false_negative_interactions"] == 0 and summary["false_positive_interactions"] == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/persist_llm_candidates.py

@@ -0,0 +1,89 @@
+"""Persist LLM-extracted candidates from a baseline JSON to Dalidou.
+
+One-shot script: reads a saved extractor eval output file, filters to
+candidates the LLM actually produced, and POSTs each to the Dalidou
+memory API with ``status=candidate``. Deduplicates against already-
+existing candidate content so the script is safe to re-run.
+
+Usage:
+
+    python scripts/persist_llm_candidates.py \\
+        scripts/eval_data/extractor_llm_baseline_2026-04-11.json
+
+Then triage via:
+
+    python scripts/atocore_client.py triage
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE_URL = os.environ.get("ATOCORE_BASE_URL", "http://dalidou:8100")
+TIMEOUT = int(os.environ.get("ATOCORE_TIMEOUT_SECONDS", "10"))
+
+
+def post_json(path: str, body: dict) -> dict:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url=f"{BASE_URL}{path}",
+        method="POST",
+        headers={"Content-Type": "application/json"},
+        data=data,
+    )
+    with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(f"usage: {sys.argv[0]} <baseline_json>", file=sys.stderr)
+        return 1
+
+    data = json.loads(open(sys.argv[1], encoding="utf-8").read())
+    results = data.get("results", [])
+
+    persisted = 0
+    skipped = 0
+    errors = 0
+
+    for r in results:
+        for c in r.get("actual_candidates", []):
+            content = (c.get("content") or "").strip()
+            if not content:
+                continue
+            mem_type = c.get("memory_type", "knowledge")
+            project = c.get("project", "")
+            confidence = c.get("confidence", 0.5)
+
+            try:
+                resp = post_json("/memory", {
+                    "memory_type": mem_type,
+                    "content": content,
+                    "project": project,
+                    "confidence": float(confidence),
+                    "status": "candidate",
+                })
+                persisted += 1
+                print(f"  + {resp.get('id','?')[:8]}  [{mem_type}]  {content[:80]}")
+            except urllib.error.HTTPError as exc:
+                if exc.code == 400:
+                    skipped += 1
+                else:
+                    errors += 1
+                    print(f"  ! error {exc.code}: {content[:60]}", file=sys.stderr)
+            except Exception as exc:
+                errors += 1
+                print(f"  ! {exc}: {content[:60]}", file=sys.stderr)
+
+    print(f"\npersisted={persisted}  skipped={skipped}  errors={errors}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/retrieval_eval.py

@@ -0,0 +1,194 @@
+"""Retrieval quality eval harness.
+
+Runs a fixed set of project-hinted questions against
+``POST /context/build`` on a live AtoCore instance and scores the
+resulting ``formatted_context`` against per-question expectations.
+The goal is a diffable scorecard that tells you, run-to-run,
+whether a retrieval / builder / ingestion change moved the needle.
+
+Design notes
+------------
+- Fixtures live in ``scripts/retrieval_eval_fixtures.json`` so new
+  questions can be added without touching Python. Each fixture
+  names the project, the prompt, and a checklist of substrings that
+  MUST appear in ``formatted_context`` (``expect_present``) and
+  substrings that MUST NOT appear (``expect_absent``). The absent
+  list catches cross-project bleed and stale content.
+- The checklist is deliberately substring-based (not regex, not
+  embedding-similarity) so a failure is always a trivially
+  reproducible "this string is not in that string". Richer scoring
+  can come later once we know the harness is useful.
+- The harness is external to the app runtime and talks to AtoCore
+  over HTTP, so it works against dev, staging, or prod. It follows
+  the same environment-variable contract as ``atocore_client.py``
+  (``ATOCORE_BASE_URL``, ``ATOCORE_TIMEOUT_SECONDS``).
+- Exit code 0 on all-pass, 1 on any fixture failure. Intended for
+  manual runs today; a future cron / CI hook can consume the
+  JSON output via ``--json``.
+
+Usage
+-----
+
+    python scripts/retrieval_eval.py            # human-readable report
+    python scripts/retrieval_eval.py --json     # machine-readable
+    python scripts/retrieval_eval.py --fixtures path/to/custom.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_BASE_URL = os.environ.get("ATOCORE_BASE_URL", "http://dalidou:8100")
+DEFAULT_TIMEOUT = int(os.environ.get("ATOCORE_TIMEOUT_SECONDS", "30"))
+DEFAULT_BUDGET = 3000
+DEFAULT_FIXTURES = Path(__file__).parent / "retrieval_eval_fixtures.json"
+
+
+@dataclass
+class Fixture:
+    name: str
+    project: str
+    prompt: str
+    budget: int = DEFAULT_BUDGET
+    expect_present: list[str] = field(default_factory=list)
+    expect_absent: list[str] = field(default_factory=list)
+    notes: str = ""
+
+
+@dataclass
+class FixtureResult:
+    fixture: Fixture
+    ok: bool
+    missing_present: list[str]
+    unexpected_absent: list[str]
+    total_chars: int
+    error: str = ""
+
+
+def load_fixtures(path: Path) -> list[Fixture]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, list):
+        raise ValueError(f"{path} must contain a JSON array of fixtures")
+    fixtures: list[Fixture] = []
+    for i, raw in enumerate(data):
+        if not isinstance(raw, dict):
+            raise ValueError(f"fixture {i} is not an object")
+        fixtures.append(
+            Fixture(
+                name=raw["name"],
+                project=raw.get("project", ""),
+                prompt=raw["prompt"],
+                budget=int(raw.get("budget", DEFAULT_BUDGET)),
+                expect_present=list(raw.get("expect_present", [])),
+                expect_absent=list(raw.get("expect_absent", [])),
+                notes=raw.get("notes", ""),
+            )
+        )
+    return fixtures
+
+
+def run_fixture(fixture: Fixture, base_url: str, timeout: int) -> FixtureResult:
+    payload = {
+        "prompt": fixture.prompt,
+        "project": fixture.project or None,
+        "budget": fixture.budget,
+    }
+    req = urllib.request.Request(
+        url=f"{base_url}/context/build",
+        method="POST",
+        headers={"Content-Type": "application/json"},
+        data=json.dumps(payload).encode("utf-8"),
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        return FixtureResult(
+            fixture=fixture,
+            ok=False,
+            missing_present=list(fixture.expect_present),
+            unexpected_absent=[],
+            total_chars=0,
+            error=f"http_error: {exc}",
+        )
+
+    formatted = body.get("formatted_context") or ""
+    missing = [s for s in fixture.expect_present if s not in formatted]
+    unexpected = [s for s in fixture.expect_absent if s in formatted]
+    return FixtureResult(
+        fixture=fixture,
+        ok=not missing and not unexpected,
+        missing_present=missing,
+        unexpected_absent=unexpected,
+        total_chars=len(formatted),
+    )
+
+
+def print_human_report(results: list[FixtureResult]) -> None:
+    total = len(results)
+    passed = sum(1 for r in results if r.ok)
+    print(f"Retrieval eval: {passed}/{total} fixtures passed")
+    print()
+    for r in results:
+        marker = "PASS" if r.ok else "FAIL"
+        print(f"[{marker}] {r.fixture.name}  project={r.fixture.project}  chars={r.total_chars}")
+        if r.error:
+            print(f"       error: {r.error}")
+        for miss in r.missing_present:
+            print(f"       missing expected: {miss!r}")
+        for bleed in r.unexpected_absent:
+            print(f"       unexpected present: {bleed!r}")
+        if r.fixture.notes and not r.ok:
+            print(f"       notes: {r.fixture.notes}")
+
+
+def print_json_report(results: list[FixtureResult]) -> None:
+    payload = {
+        "total": len(results),
+        "passed": sum(1 for r in results if r.ok),
+        "fixtures": [
+            {
+                "name": r.fixture.name,
+                "project": r.fixture.project,
+                "ok": r.ok,
+                "total_chars": r.total_chars,
+                "missing_present": r.missing_present,
+                "unexpected_absent": r.unexpected_absent,
+                "error": r.error,
+            }
+            for r in results
+        ],
+    }
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="AtoCore retrieval quality eval harness")
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
+    parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT)
+    parser.add_argument("--fixtures", type=Path, default=DEFAULT_FIXTURES)
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    args = parser.parse_args()
+
+    fixtures = load_fixtures(args.fixtures)
+    results = [run_fixture(f, args.base_url, args.timeout) for f in fixtures]
+
+    if args.json:
+        print_json_report(results)
+    else:
+        print_human_report(results)
+
+    return 0 if all(r.ok for r in results) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/retrieval_eval_fixtures.json

@@ -0,0 +1,225 @@
+[
+  {
+    "name": "p04-architecture-decision",
+    "project": "p04-gigabit",
+    "prompt": "what mirror architecture was selected for GigaBIT M1 and why",
+    "expect_present": [
+      "--- Trusted Project State ---",
+      "Option B",
+      "conical",
+      "--- Project Memories ---"
+    ],
+    "expect_absent": [
+      "p06-polisher",
+      "folded-beam"
+    ],
+    "notes": "Canonical p04 decision — should surface both Trusted Project State and the project-memory band"
+  },
+  {
+    "name": "p04-constraints",
+    "project": "p04-gigabit",
+    "prompt": "what are the key GigaBIT M1 program constraints",
+    "expect_present": [
+      "--- Trusted Project State ---",
+      "Zerodur",
+      "1.2"
+    ],
+    "expect_absent": [
+      "polisher suite"
+    ],
+    "notes": "Key constraints are in Trusted Project State and in the mission-framing memory"
+  },
+  {
+    "name": "p04-short-ambiguous",
+    "project": "p04-gigabit",
+    "prompt": "current status",
+    "expect_present": [
+      "--- Trusted Project State ---"
+    ],
+    "expect_absent": [],
+    "notes": "Short ambiguous prompt — at minimum project state should surface. Hard case: the prompt is generic enough that chunks may not rank well."
+  },
+  {
+    "name": "p05-configuration",
+    "project": "p05-interferometer",
+    "prompt": "what is the selected interferometer configuration",
+    "expect_present": [
+      "folded-beam",
+      "CGH"
+    ],
+    "expect_absent": [
+      "Option B",
+      "conical back",
+      "polisher suite"
+    ],
+    "notes": "P05 architecture memory covers folded-beam + CGH. GigaBIT M1 legitimately appears in p05 source docs."
+  },
+  {
+    "name": "p05-vendor-signal",
+    "project": "p05-interferometer",
+    "prompt": "what is the current vendor signal for the interferometer procurement",
+    "expect_present": [
+      "4D",
+      "Zygo"
+    ],
+    "expect_absent": [
+      "polisher"
+    ],
+    "notes": "Vendor memory mentions 4D as strongest technical candidate and Zygo Verifire SV as value path"
+  },
+  {
+    "name": "p05-cgh-calibration",
+    "project": "p05-interferometer",
+    "prompt": "how does CGH calibration work for the interferometer",
+    "expect_present": [
+      "CGH"
+    ],
+    "expect_absent": [
+      "polisher-sim",
+      "polisher-post"
+    ],
+    "notes": "CGH is a core p05 concept. Should surface via chunks and possibly the architecture memory. Must not bleed p06 polisher-suite terms."
+  },
+  {
+    "name": "p06-suite-split",
+    "project": "p06-polisher",
+    "prompt": "how is the polisher software suite split across layers",
+    "expect_present": [
+      "polisher-sim",
+      "polisher-post",
+      "polisher-control"
+    ],
+    "expect_absent": [
+      "GigaBIT"
+    ],
+    "notes": "The three-layer split is in multiple p06 memories"
+  },
+  {
+    "name": "p06-control-rule",
+    "project": "p06-polisher",
+    "prompt": "what is the polisher control design rule",
+    "expect_present": [
+      "interlocks"
+    ],
+    "expect_absent": [
+      "interferometer"
+    ],
+    "notes": "Control design rule memory mentions interlocks and state transitions"
+  },
+  {
+    "name": "p06-firmware-interface",
+    "project": "p06-polisher",
+    "prompt": "what is the firmware interface contract for the polisher machine",
+    "expect_present": [
+      "controller-job"
+    ],
+    "expect_absent": [
+      "interferometer",
+      "GigaBIT"
+    ],
+    "notes": "New p06 memory from the first triage: firmware interface contract is invariant controller-job.v1 in, run-log.v1 out"
+  },
+  {
+    "name": "p06-z-axis",
+    "project": "p06-polisher",
+    "prompt": "how does the polisher Z-axis work",
+    "expect_present": [
+      "engage"
+    ],
+    "expect_absent": [
+      "interferometer"
+    ],
+    "notes": "New p06 memory: Z-axis is binary engage/retract, not continuous position. The word 'engage' should appear."
+  },
+  {
+    "name": "p06-cam-mechanism",
+    "project": "p06-polisher",
+    "prompt": "how is cam amplitude controlled on the polisher",
+    "expect_present": [
+      "encoder"
+    ],
+    "expect_absent": [
+      "GigaBIT"
+    ],
+    "notes": "New p06 memory: cam set mechanically by operator, read by encoders. The word 'encoder' should appear."
+  },
+  {
+    "name": "p06-telemetry-rate",
+    "project": "p06-polisher",
+    "prompt": "what is the expected polishing telemetry data rate",
+    "expect_present": [
+      "29 MB"
+    ],
+    "expect_absent": [
+      "interferometer"
+    ],
+    "notes": "New p06 knowledge memory: approximately 29 MB per hour at 100 Hz"
+  },
+  {
+    "name": "p06-offline-design",
+    "project": "p06-polisher",
+    "prompt": "does the polisher machine need network to operate",
+    "expect_present": [
+      "offline"
+    ],
+    "expect_absent": [
+      "CGH"
+    ],
+    "notes": "New p06 memory: machine works fully offline and independently; network is for remote access only"
+  },
+  {
+    "name": "p06-short-ambiguous",
+    "project": "p06-polisher",
+    "prompt": "current status",
+    "expect_present": [
+      "--- Trusted Project State ---"
+    ],
+    "expect_absent": [],
+    "notes": "Short ambiguous prompt — project state should surface at minimum"
+  },
+  {
+    "name": "cross-project-no-bleed",
+    "project": "p04-gigabit",
+    "prompt": "what telemetry rate should we target",
+    "expect_present": [],
+    "expect_absent": [
+      "29 MB",
+      "polisher"
+    ],
+    "notes": "Adversarial: telemetry rate is a p06 fact. A p04 query for 'telemetry rate' must NOT surface p06 memories. Tests cross-project gating."
+  },
+  {
+    "name": "no-project-hint",
+    "project": "",
+    "prompt": "tell me about the current projects",
+    "expect_present": [],
+    "expect_absent": [
+      "--- Project Memories ---"
+    ],
+    "notes": "Without a project hint, project memories must not appear (cross-project bleed guard). Chunks may appear if any match."
+  },
+  {
+    "name": "p06-usb-ssd",
+    "project": "p06-polisher",
+    "prompt": "what storage solution is specified for the polisher RPi",
+    "expect_present": [
+      "USB SSD"
+    ],
+    "expect_absent": [
+      "interferometer"
+    ],
+    "notes": "New p06 memory from triage: USB SSD mandatory, not SD card"
+  },
+  {
+    "name": "p06-tailscale",
+    "project": "p06-polisher",
+    "prompt": "how do we access the polisher machine remotely",
+    "expect_present": [
+      "Tailscale"
+    ],
+    "expect_absent": [
+      "GigaBIT"
+    ],
+    "notes": "New p06 memory: Tailscale mesh for RPi remote access"
+  }
+]

src/atocore/__init__.py

@@ -1,3 +1,15 @@
 """AtoCore — Personal Context Engine."""
 
-__version__ = "0.1.0"
+# Bumped when a commit meaningfully changes the API surface, schema, or
+# user-visible behavior. The /health endpoint reports this value so
+# deployment drift is immediately visible: if the running service's
+# /health reports an older version than the main branch's __version__,
+# the deployment is stale and needs a redeploy (see
+# docs/dalidou-deployment.md and deploy/dalidou/deploy.sh).
+#
+# History:
+#   0.1.0  Phase 0/0.5/1/2/3/5/7 baseline
+#   0.2.0  Phase 9 reflection loop (capture/reinforce/extract + review
+#          queue), shared client v0.2.0, project identity
+#          canonicalization at every service-layer entry point
+__version__ = "0.2.0"

src/atocore/api/routes.py

@@ -49,6 +49,7 @@ from atocore.memory.service import (
 )
 from atocore.observability.logger import get_logger
 from atocore.ops.backup import (
+    cleanup_old_backups,
     create_runtime_backup,
     list_runtime_backups,
     validate_backup,
@@ -140,6 +141,7 @@ class MemoryCreateRequest(BaseModel):
     content: str
     project: str = ""
     confidence: float = 1.0
+    status: str = "active"
 
 
 class MemoryUpdateRequest(BaseModel):
@@ -343,6 +345,7 @@ def api_create_memory(req: MemoryCreateRequest) -> dict:
             content=req.content,
             project=req.project,
             confidence=req.confidence,
+            status=req.status,
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
@@ -511,6 +514,7 @@ class InteractionRecordRequest(BaseModel):
     chunks_used: list[str] = []
     context_pack: dict | None = None
     reinforce: bool = True
+    extract: bool = False
 
 
 @router.post("/interactions")
@@ -536,6 +540,7 @@ def api_record_interaction(req: InteractionRecordRequest) -> dict:
             chunks_used=req.chunks_used,
             context_pack=req.context_pack,
             reinforce=req.reinforce,
+            extract=req.extract,
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
@@ -731,6 +736,25 @@ def api_list_backups() -> dict:
     }
 
 
+class BackupCleanupRequest(BaseModel):
+    confirm: bool = False
+
+
+@router.post("/admin/backup/cleanup")
+def api_cleanup_backups(req: BackupCleanupRequest | None = None) -> dict:
+    """Apply retention policy to old backup snapshots.
+
+    Dry-run by default. Pass ``confirm: true`` to actually delete.
+    Retention: last 7 daily, last 4 weekly (Sundays), last 6 monthly (1st).
+    """
+    payload = req or BackupCleanupRequest()
+    try:
+        return cleanup_old_backups(confirm=payload.confirm)
+    except Exception as e:
+        log.error("admin_cleanup_failed", error=str(e))
+        raise HTTPException(status_code=500, detail=f"Cleanup failed: {e}")
+
+
 @router.get("/admin/backup/{stamp}/validate")
 def api_validate_backup(stamp: str) -> dict:
     """Validate that a previously created backup is structurally usable."""
@@ -742,12 +766,45 @@ def api_validate_backup(stamp: str) -> dict:
 
 @router.get("/health")
 def api_health() -> dict:
-    """Health check."""
+    """Health check.
+
+    Three layers of version reporting, in increasing precision:
+
+    - ``version`` / ``code_version``: ``atocore.__version__`` (e.g.
+      "0.2.0"). Bumped manually on commits that change the API
+      surface, schema, or user-visible behavior. Coarse — any
+      number of commits can land between bumps without changing
+      this value.
+    - ``build_sha``: full git SHA of the commit the running
+      container was built from. Set by ``deploy/dalidou/deploy.sh``
+      via the ``ATOCORE_BUILD_SHA`` env var on every rebuild.
+      Reports ``"unknown"`` for builds that bypass deploy.sh
+      (direct ``docker compose up`` etc.). This is the precise
+      drift signal: if the live ``build_sha`` doesn't match the
+      tip of the deployed branch on Gitea, the service is stale
+      regardless of what ``code_version`` says.
+    - ``build_time`` / ``build_branch``: when and from which branch
+      the live container was built. Useful for forensics when
+      multiple branches are in flight or when build_sha is
+      ambiguous (e.g. a force-push to the same SHA).
+
+    The deploy.sh post-deploy verification step compares the live
+    ``build_sha`` to the SHA it just set, and exits non-zero on
+    mismatch.
+    """
+    import os
+
+    from atocore import __version__
+
     store = get_vector_store()
     source_status = get_source_status()
     return {
         "status": "ok",
-        "version": "0.1.0",
+        "version": __version__,
+        "code_version": __version__,
+        "build_sha": os.environ.get("ATOCORE_BUILD_SHA", "unknown"),
+        "build_time": os.environ.get("ATOCORE_BUILD_TIME", "unknown"),
+        "build_branch": os.environ.get("ATOCORE_BUILD_BRANCH", "unknown"),
         "vectors_count": store.count,
         "env": _config.settings.env,
         "machine_paths": {

src/atocore/context/builder.py

@@ -14,6 +14,7 @@ import atocore.config as _config
 from atocore.context.project_state import format_project_state, get_state
 from atocore.memory.service import get_memories_for_context
 from atocore.observability.logger import get_logger
+from atocore.projects.registry import resolve_project_name
 from atocore.retrieval.retriever import ChunkResult, retrieve
 
 log = get_logger("context_builder")
@@ -29,6 +30,12 @@ SYSTEM_PREFIX = (
 #   identity: 5%, preferences: 5%, project state: 20%, retrieval: 60%+
 PROJECT_STATE_BUDGET_RATIO = 0.20
 MEMORY_BUDGET_RATIO = 0.10  # 5% identity + 5% preference
+# Project-scoped memories (project/knowledge/episodic) are the outlet
+# for the Phase 9 reflection loop on the retrieval side. Budget sits
+# between identity/preference and retrieved chunks so a reinforced
+# memory can actually reach the model.
+PROJECT_MEMORY_BUDGET_RATIO = 0.25
+PROJECT_MEMORY_TYPES = ["project", "knowledge", "episodic"]
 
 # Last built context pack for debug inspection
 _last_context_pack: "ContextPack | None" = None
@@ -50,6 +57,8 @@ class ContextPack:
     project_state_chars: int = 0
     memory_text: str = ""
     memory_chars: int = 0
+    project_memory_text: str = ""
+    project_memory_chars: int = 0
     total_chars: int = 0
     budget: int = 0
     budget_remaining: int = 0
@@ -84,8 +93,16 @@ def build_context(
         max(0, int(budget * PROJECT_STATE_BUDGET_RATIO)),
     )
 
-    if project_hint:
-        state_entries = get_state(project_hint)
+    # Canonicalize the project hint through the registry so callers
+    # can pass an alias (`p05`, `gigabit`) and still find trusted
+    # state stored under the canonical project id. The same helper
+    # is used everywhere a project name crosses a trust boundary
+    # (project_state, memories, interactions). When the registry has
+    # no entry the helper returns the input unchanged so hand-curated
+    # state that predates the registry still works.
+    canonical_project = resolve_project_name(project_hint) if project_hint else ""
+    if canonical_project:
+        state_entries = get_state(canonical_project)
         if state_entries:
             project_state_text = format_project_state(state_entries)
             project_state_text, project_state_chars = _truncate_text_block(
@@ -98,10 +115,32 @@ def build_context(
     memory_text, memory_chars = get_memories_for_context(
         memory_types=["identity", "preference"],
         budget=memory_budget,
+        query=user_prompt,
     )
 
+    # 2b. Get project-scoped memories (third precedence). Only
+    # populated when a canonical project is in scope — cross-project
+    # memory bleed would rot the pack. Active-only filtering is
+    # handled by the shared min_confidence=0.5 gate inside
+    # get_memories_for_context.
+    project_memory_text = ""
+    project_memory_chars = 0
+    if canonical_project:
+        project_memory_budget = min(
+            int(budget * PROJECT_MEMORY_BUDGET_RATIO),
+            max(budget - project_state_chars - memory_chars, 0),
+        )
+        project_memory_text, project_memory_chars = get_memories_for_context(
+            memory_types=PROJECT_MEMORY_TYPES,
+            project=canonical_project,
+            budget=project_memory_budget,
+            header="--- Project Memories ---",
+            footer="--- End Project Memories ---",
+            query=user_prompt,
+        )
+
     # 3. Calculate remaining budget for retrieval
-    retrieval_budget = budget - project_state_chars - memory_chars
+    retrieval_budget = budget - project_state_chars - memory_chars - project_memory_chars
 
     # 4. Retrieve candidates
     candidates = (
@@ -121,11 +160,14 @@ def build_context(
     selected = _select_within_budget(scored, max(retrieval_budget, 0))
 
     # 7. Format full context
-    formatted = _format_full_context(project_state_text, memory_text, selected)
+    formatted = _format_full_context(
+        project_state_text, memory_text, project_memory_text, selected
+    )
     if len(formatted) > budget:
         formatted, selected = _trim_context_to_budget(
             project_state_text,
             memory_text,
+            project_memory_text,
             selected,
             budget,
         )
@@ -135,6 +177,7 @@ def build_context(
 
     project_state_chars = len(project_state_text)
     memory_chars = len(memory_text)
+    project_memory_chars = len(project_memory_text)
     retrieval_chars = sum(c.char_count for c in selected)
     total_chars = len(formatted)
     duration_ms = int((time.time() - start) * 1000)
@@ -145,6 +188,8 @@ def build_context(
         project_state_chars=project_state_chars,
         memory_text=memory_text,
         memory_chars=memory_chars,
+        project_memory_text=project_memory_text,
+        project_memory_chars=project_memory_chars,
         total_chars=total_chars,
         budget=budget,
         budget_remaining=budget - total_chars,
@@ -162,6 +207,7 @@ def build_context(
         chunks_used=len(selected),
         project_state_chars=project_state_chars,
         memory_chars=memory_chars,
+        project_memory_chars=project_memory_chars,
         retrieval_chars=retrieval_chars,
         total_chars=total_chars,
         budget_remaining=budget - total_chars,
@@ -241,6 +287,7 @@ def _select_within_budget(
 def _format_full_context(
     project_state_text: str,
     memory_text: str,
+    project_memory_text: str,
     chunks: list[ContextChunk],
 ) -> str:
     """Format project state + memories + retrieved chunks into full context block."""
@@ -256,7 +303,12 @@ def _format_full_context(
         parts.append(memory_text)
         parts.append("")
 
-    # 3. Retrieved chunks (lowest trust)
+    # 3. Project-scoped memories (third trust level)
+    if project_memory_text:
+        parts.append(project_memory_text)
+        parts.append("")
+
+    # 4. Retrieved chunks (lowest trust)
     if chunks:
         parts.append("--- AtoCore Retrieved Context ---")
         if project_state_text:
@@ -268,7 +320,7 @@ def _format_full_context(
             parts.append(chunk.content)
             parts.append("")
         parts.append("--- End Context ---")
-    elif not project_state_text and not memory_text:
+    elif not project_state_text and not memory_text and not project_memory_text:
         parts.append("--- AtoCore Context ---\nNo relevant context found.\n--- End Context ---")
 
     return "\n".join(parts)
@@ -290,6 +342,7 @@ def _pack_to_dict(pack: ContextPack) -> dict:
         "project_hint": pack.project_hint,
         "project_state_chars": pack.project_state_chars,
         "memory_chars": pack.memory_chars,
+        "project_memory_chars": pack.project_memory_chars,
         "chunks_used": len(pack.chunks_used),
         "total_chars": pack.total_chars,
         "budget": pack.budget,
@@ -297,6 +350,7 @@ def _pack_to_dict(pack: ContextPack) -> dict:
         "duration_ms": pack.duration_ms,
         "has_project_state": bool(pack.project_state_text),
         "has_memories": bool(pack.memory_text),
+        "has_project_memories": bool(pack.project_memory_text),
         "chunks": [
             {
                 "source_file": c.source_file,
@@ -326,26 +380,45 @@ def _truncate_text_block(text: str, budget: int) -> tuple[str, int]:
 def _trim_context_to_budget(
     project_state_text: str,
     memory_text: str,
+    project_memory_text: str,
     chunks: list[ContextChunk],
     budget: int,
 ) -> tuple[str, list[ContextChunk]]:
-    """Trim retrieval first, then memory, then project state until formatted context fits."""
+    """Trim retrieval → project memories → identity/preference → project state."""
     kept_chunks = list(chunks)
-    formatted = _format_full_context(project_state_text, memory_text, kept_chunks)
+    formatted = _format_full_context(
+        project_state_text, memory_text, project_memory_text, kept_chunks
+    )
     while len(formatted) > budget and kept_chunks:
         kept_chunks.pop()
-        formatted = _format_full_context(project_state_text, memory_text, kept_chunks)
+        formatted = _format_full_context(
+            project_state_text, memory_text, project_memory_text, kept_chunks
+        )
 
     if len(formatted) <= budget:
         return formatted, kept_chunks
 
+    # Drop project memories next (they were the most recently added
+    # tier and carry less trust than identity/preference).
+    project_memory_text, _ = _truncate_text_block(
+        project_memory_text,
+        max(budget - len(project_state_text) - len(memory_text), 0),
+    )
+    formatted = _format_full_context(
+        project_state_text, memory_text, project_memory_text, kept_chunks
+    )
+    if len(formatted) <= budget:
+        return formatted, kept_chunks
+
     memory_text, _ = _truncate_text_block(memory_text, max(budget - len(project_state_text), 0))
-    formatted = _format_full_context(project_state_text, memory_text, kept_chunks)
+    formatted = _format_full_context(
+        project_state_text, memory_text, project_memory_text, kept_chunks
+    )
     if len(formatted) <= budget:
         return formatted, kept_chunks
 
     project_state_text, _ = _truncate_text_block(project_state_text, budget)
-    formatted = _format_full_context(project_state_text, "", [])
+    formatted = _format_full_context(project_state_text, "", "", [])
     if len(formatted) > budget:
         formatted, _ = _truncate_text_block(formatted, budget)
     return formatted, []

src/atocore/context/project_state.py

@@ -18,6 +18,7 @@ from datetime import datetime, timezone
 
 from atocore.models.database import get_connection
 from atocore.observability.logger import get_logger
+from atocore.projects.registry import resolve_project_name
 
 log = get_logger("project_state")
 
@@ -101,11 +102,19 @@ def set_state(
     source: str = "",
     confidence: float = 1.0,
 ) -> ProjectStateEntry:
-    """Set or update a project state entry. Upsert semantics."""
+    """Set or update a project state entry. Upsert semantics.
+
+    The ``project_name`` is canonicalized through the registry so a
+    caller passing an alias (``p05``) ends up writing into the same
+    row as the canonical id (``p05-interferometer``). Without this
+    step, alias and canonical names would create two parallel
+    project rows and fragmented state.
+    """
     if category not in CATEGORIES:
         raise ValueError(f"Invalid category '{category}'. Must be one of: {CATEGORIES}")
     _validate_confidence(confidence)
 
+    project_name = resolve_project_name(project_name)
     project_id = ensure_project(project_name)
     entry_id = str(uuid.uuid4())
     now = datetime.now(timezone.utc).isoformat()
@@ -153,7 +162,12 @@ def get_state(
     category: str | None = None,
     active_only: bool = True,
 ) -> list[ProjectStateEntry]:
-    """Get project state entries, optionally filtered by category."""
+    """Get project state entries, optionally filtered by category.
+
+    The lookup is canonicalized through the registry so an alias hint
+    finds the same rows as the canonical id.
+    """
+    project_name = resolve_project_name(project_name)
     with get_connection() as conn:
         project = conn.execute(
             "SELECT id FROM projects WHERE lower(name) = lower(?)", (project_name,)
@@ -191,7 +205,12 @@ def get_state(
 
 
 def invalidate_state(project_name: str, category: str, key: str) -> bool:
-    """Mark a project state entry as superseded."""
+    """Mark a project state entry as superseded.
+
+    The lookup is canonicalized through the registry so an alias is
+    treated as the canonical project for the invalidation lookup.
+    """
+    project_name = resolve_project_name(project_name)
     with get_connection() as conn:
         project = conn.execute(
             "SELECT id FROM projects WHERE lower(name) = lower(?)", (project_name,)

src/atocore/interactions/service.py

@@ -18,15 +18,24 @@ violating the AtoCore trust hierarchy.
 from __future__ import annotations
 
 import json
+import re
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 
 from atocore.models.database import get_connection
 from atocore.observability.logger import get_logger
+from atocore.projects.registry import resolve_project_name
 
 log = get_logger("interactions")
 
+# Stored timestamps use 'YYYY-MM-DD HH:MM:SS' (no timezone offset, UTC by
+# convention) so they sort lexically and compare cleanly with the SQLite
+# CURRENT_TIMESTAMP default. The since filter accepts ISO 8601 strings
+# (with 'T', optional 'Z' or +offset, optional fractional seconds) and
+# normalizes them to the storage format before the SQL comparison.
+_STORAGE_TIMESTAMP_FORMAT = "%Y-%m-%d %H:%M:%S"
+
 
 @dataclass
 class Interaction:
@@ -54,6 +63,7 @@ def record_interaction(
     chunks_used: list[str] | None = None,
     context_pack: dict | None = None,
     reinforce: bool = True,
+    extract: bool = False,
 ) -> Interaction:
     """Persist a single interaction to the audit trail.
 
@@ -72,6 +82,13 @@ def record_interaction(
     if not prompt or not prompt.strip():
         raise ValueError("Interaction prompt must be non-empty")
 
+    # Canonicalize the project through the registry so an alias and
+    # the canonical id store under the same bucket. Without this,
+    # reinforcement and extraction (which both query by raw
+    # interaction.project) would silently miss memories and create
+    # candidates in the wrong project.
+    project = resolve_project_name(project)
+
     interaction_id = str(uuid.uuid4())
     # Store created_at explicitly so the same string lives in both the DB
     # column and the returned dataclass. SQLite's CURRENT_TIMESTAMP uses
@@ -147,6 +164,30 @@ def record_interaction(
                 error=str(exc),
             )
 
+    if extract and (response or response_summary):
+        try:
+            from atocore.memory.extractor import extract_candidates_from_interaction
+            from atocore.memory.service import create_memory
+
+            candidates = extract_candidates_from_interaction(interaction)
+            for candidate in candidates:
+                try:
+                    create_memory(
+                        memory_type=candidate.memory_type,
+                        content=candidate.content,
+                        project=candidate.project,
+                        confidence=candidate.confidence,
+                        status="candidate",
+                    )
+                except ValueError:
+                    pass  # duplicate or validation error — skip silently
+        except Exception as exc:  # pragma: no cover - extraction must never block capture
+            log.error(
+                "extraction_failed_on_capture",
+                interaction_id=interaction_id,
+                error=str(exc),
+            )
+
     return interaction
 
 
@@ -159,9 +200,14 @@ def list_interactions(
 ) -> list[Interaction]:
     """List captured interactions, optionally filtered.
 
-    ``since`` is an ISO timestamp string; only interactions created at or
-    after that time are returned. ``limit`` is hard-capped at 500 to keep
-    casual API listings cheap.
+    ``since`` accepts an ISO 8601 timestamp string (with ``T``, an
+    optional ``Z`` or numeric offset, optional fractional seconds).
+    The value is normalized to the storage format (UTC,
+    ``YYYY-MM-DD HH:MM:SS``) before the SQL comparison so external
+    callers can pass any of the common ISO shapes without filter
+    drift. ``project`` is canonicalized through the registry so an
+    alias finds rows stored under the canonical project id.
+    ``limit`` is hard-capped at 500 to keep casual API listings cheap.
     """
     if limit <= 0:
         return []
@@ -172,7 +218,7 @@ def list_interactions(
 
     if project:
         query += " AND project = ?"
-        params.append(project)
+        params.append(resolve_project_name(project))
     if session_id:
         query += " AND session_id = ?"
         params.append(session_id)
@@ -181,7 +227,7 @@ def list_interactions(
         params.append(client)
     if since:
         query += " AND created_at >= ?"
-        params.append(since)
+        params.append(_normalize_since(since))
 
     query += " ORDER BY created_at DESC LIMIT ?"
     params.append(limit)
@@ -243,3 +289,41 @@ def _safe_json_dict(raw: str | None) -> dict:
     if not isinstance(value, dict):
         return {}
     return value
+
+
+def _normalize_since(since: str) -> str:
+    """Normalize an ISO 8601 ``since`` filter to the storage format.
+
+    Stored ``created_at`` values are ``YYYY-MM-DD HH:MM:SS`` (no
+    timezone, UTC by convention). External callers naturally pass
+    ISO 8601 with ``T`` separator, optional ``Z`` suffix, optional
+    fractional seconds, and optional ``+HH:MM`` offsets. A naive
+    string comparison between the two formats fails on the same
+    day because the lexically-greater ``T`` makes any ISO value
+    sort after any space-separated value.
+
+    This helper accepts the common ISO shapes plus the bare
+    storage format and returns the storage format. On a parse
+    failure it returns the input unchanged so the SQL comparison
+    fails open (no rows match) instead of raising and breaking
+    the listing endpoint.
+    """
+    if not since:
+        return since
+    candidate = since.strip()
+    # Python's fromisoformat understands trailing 'Z' from 3.11+ but
+    # we replace it explicitly for safety against earlier shapes.
+    if candidate.endswith("Z"):
+        candidate = candidate[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(candidate)
+    except ValueError:
+        # Already in storage format, or unparseable: best-effort
+        # match the storage format with a regex; if that fails too,
+        # return the raw input.
+        if re.fullmatch(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}", since):
+            return since
+        return since
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(timezone.utc).replace(tzinfo=None)
+    return dt.strftime(_STORAGE_TIMESTAMP_FORMAT)

src/atocore/main.py

@@ -4,6 +4,7 @@ from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 
+from atocore import __version__
 from atocore.api.routes import router
 import atocore.config as _config
 from atocore.context.project_state import init_project_state_schema
@@ -43,7 +44,7 @@ async def lifespan(app: FastAPI):
 app = FastAPI(
     title="AtoCore",
     description="Personal Context Engine for LLM interactions",
-    version="0.1.0",
+    version=__version__,
     lifespan=lifespan,
 )
 

src/atocore/memory/extractor_llm.py

@@ -0,0 +1,283 @@
+"""LLM-assisted candidate-memory extraction via the Claude Code CLI.
+
+Day 4 of the 2026-04-11 mini-phase: the rule-based extractor hit 0%
+recall against real conversational claude-code captures (Day 2 baseline
+scorecard in ``scripts/eval_data/extractor_labels_2026-04-11.json``),
+with false negatives spread across 5 distinct miss classes. A single
+rule expansion cannot close that gap, so this module adds an optional
+LLM-assisted mode that shells out to the ``claude -p`` (Claude Code
+non-interactive) CLI with a focused extraction system prompt. That
+path reuses the user's existing Claude.ai OAuth credentials — no API
+key anywhere, per the 2026-04-11 decision.
+
+Trust rules carried forward from the rule-based extractor:
+
+- Candidates are NEVER auto-promoted. Caller persists with
+  ``status="candidate"`` and a human reviews via the triage CLI.
+- This path is additive. The rule-based extractor keeps working
+  exactly as before; callers opt in by importing this module.
+- Extraction stays off the capture hot path — this is batch / manual
+  only, per the 2026-04-11 decision.
+- Failure is silent. Missing CLI, non-zero exit, malformed JSON,
+  timeout — all return an empty list and log an error. Never raises
+  into the caller; the capture audit trail must not break on an
+  optional side effect.
+
+Configuration:
+
+- Requires the ``claude`` CLI on PATH (``claude --version`` should work).
+- ``ATOCORE_LLM_EXTRACTOR_MODEL`` overrides the model alias (default
+  ``sonnet``).
+- ``ATOCORE_LLM_EXTRACTOR_TIMEOUT_S`` overrides the per-call timeout
+  (default 90 seconds — first invocation is slow because Node.js
+  startup plus OAuth check is non-trivial).
+
+Implementation notes:
+
+- We run ``claude -p`` with ``--model <alias>``,
+  ``--append-system-prompt`` for the extraction instructions,
+  ``--no-session-persistence`` so we don't pollute session history,
+  and ``--disable-slash-commands`` so stray ``/foo`` in an extracted
+  response never triggers something.
+- The CLI is invoked from a temp working directory so it does not
+  auto-discover ``CLAUDE.md`` / ``DEV-LEDGER.md`` / ``AGENTS.md``
+  from the repo root. We want a bare extraction context, not the
+  full project briefing. We can't use ``--bare`` because that
+  forces API-key auth; the temp-cwd trick is the lightest way to
+  keep OAuth auth while skipping project context loading.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from functools import lru_cache
+
+from atocore.interactions.service import Interaction
+from atocore.memory.extractor import MemoryCandidate
+from atocore.memory.service import MEMORY_TYPES
+from atocore.observability.logger import get_logger
+
+log = get_logger("extractor_llm")
+
+LLM_EXTRACTOR_VERSION = "llm-0.2.0"
+DEFAULT_MODEL = os.environ.get("ATOCORE_LLM_EXTRACTOR_MODEL", "sonnet")
+DEFAULT_TIMEOUT_S = float(os.environ.get("ATOCORE_LLM_EXTRACTOR_TIMEOUT_S", "90"))
+MAX_RESPONSE_CHARS = 8000
+MAX_PROMPT_CHARS = 2000
+
+_SYSTEM_PROMPT = """You extract durable memory candidates from LLM conversation turns for a personal context engine called AtoCore.
+
+Your job is to read one user prompt plus the assistant's response and decide which durable facts, decisions, preferences, architectural rules, or project invariants should be remembered across future sessions.
+
+Rules:
+
+1. Only surface durable claims. Skip transient status ("deploy is still running"), instructional guidance ("here is how to run the command"), troubleshooting tactics, ephemeral recommendations ("merge this PR now"), and session recaps.
+2. A candidate is durable when a reader coming back in two weeks would still need to know it. Architectural choices, named rules, ratified decisions, invariants, procurement commitments, and project-level constraints qualify. Conversational fillers and step-by-step instructions do not.
+3. Each candidate must stand alone. Rewrite the claim in one sentence under 200 characters with enough context that a reader without the conversation understands it.
+4. Each candidate must have a type from this closed set: project, knowledge, preference, adaptation.
+5. If the conversation is clearly scoped to a project (p04-gigabit, p05-interferometer, p06-polisher, atocore), set ``project`` to that id. Otherwise leave ``project`` empty.
+6. If the response makes no durable claim, return an empty list. It is correct and expected to return [] on most conversational turns.
+7. Confidence should be 0.5 by default so human review workload is honest. Raise to 0.6 only when the response states the claim in an unambiguous, committed form (e.g. "the decision is X", "the selected approach is Y", "X is non-negotiable").
+8. Output must be a raw JSON array and nothing else. No prose before or after. No markdown fences. No explanations.
+
+Each array element has exactly this shape:
+
+{"type": "project|knowledge|preference|adaptation", "content": "...", "project": "...", "confidence": 0.5}
+
+Return [] when there is nothing to extract."""
+
+
+@dataclass
+class LLMExtractionResult:
+    candidates: list[MemoryCandidate]
+    raw_output: str
+    error: str = ""
+
+
+@lru_cache(maxsize=1)
+def _sandbox_cwd() -> str:
+    """Return a stable temp directory for ``claude -p`` invocations.
+
+    We want the CLI to run from a directory that does NOT contain
+    ``CLAUDE.md`` / ``DEV-LEDGER.md`` / ``AGENTS.md``, so every
+    extraction call starts with a clean context instead of the full
+    AtoCore project briefing. Cached so the directory persists for
+    the lifetime of the process.
+    """
+    return tempfile.mkdtemp(prefix="ato-llm-extract-")
+
+
+def _cli_available() -> bool:
+    return shutil.which("claude") is not None
+
+
+def extract_candidates_llm(
+    interaction: Interaction,
+    model: str | None = None,
+    timeout_s: float | None = None,
+) -> list[MemoryCandidate]:
+    """Run the LLM-assisted extractor against one interaction.
+
+    Returns a list of ``MemoryCandidate`` objects, empty on any
+    failure path. The caller is responsible for persistence.
+    """
+    return extract_candidates_llm_verbose(
+        interaction,
+        model=model,
+        timeout_s=timeout_s,
+    ).candidates
+
+
+def extract_candidates_llm_verbose(
+    interaction: Interaction,
+    model: str | None = None,
+    timeout_s: float | None = None,
+) -> LLMExtractionResult:
+    """Like ``extract_candidates_llm`` but also returns the raw
+    subprocess output and any error encountered, for eval / debugging.
+    """
+    if not _cli_available():
+        return LLMExtractionResult(
+            candidates=[],
+            raw_output="",
+            error="claude_cli_missing",
+        )
+
+    response_text = (interaction.response or "").strip()
+    if not response_text:
+        return LLMExtractionResult(candidates=[], raw_output="", error="empty_response")
+
+    prompt_excerpt = (interaction.prompt or "")[:MAX_PROMPT_CHARS]
+    response_excerpt = response_text[:MAX_RESPONSE_CHARS]
+    user_message = (
+        f"PROJECT HINT (may be empty): {interaction.project or ''}\n\n"
+        f"USER PROMPT:\n{prompt_excerpt}\n\n"
+        f"ASSISTANT RESPONSE:\n{response_excerpt}\n\n"
+        "Return the JSON array now."
+    )
+
+    args = [
+        "claude",
+        "-p",
+        "--model",
+        model or DEFAULT_MODEL,
+        "--append-system-prompt",
+        _SYSTEM_PROMPT,
+        "--no-session-persistence",
+        "--disable-slash-commands",
+        user_message,
+    ]
+
+    try:
+        completed = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            timeout=timeout_s or DEFAULT_TIMEOUT_S,
+            cwd=_sandbox_cwd(),
+            encoding="utf-8",
+            errors="replace",
+        )
+    except subprocess.TimeoutExpired:
+        log.error("llm_extractor_timeout", interaction_id=interaction.id)
+        return LLMExtractionResult(candidates=[], raw_output="", error="timeout")
+    except Exception as exc:  # pragma: no cover - unexpected subprocess failure
+        log.error("llm_extractor_subprocess_failed", error=str(exc))
+        return LLMExtractionResult(candidates=[], raw_output="", error=f"subprocess_error: {exc}")
+
+    if completed.returncode != 0:
+        log.error(
+            "llm_extractor_nonzero_exit",
+            interaction_id=interaction.id,
+            returncode=completed.returncode,
+            stderr_prefix=(completed.stderr or "")[:200],
+        )
+        return LLMExtractionResult(
+            candidates=[],
+            raw_output=completed.stdout or "",
+            error=f"exit_{completed.returncode}",
+        )
+
+    raw_output = (completed.stdout or "").strip()
+    candidates = _parse_candidates(raw_output, interaction)
+    log.info(
+        "llm_extractor_done",
+        interaction_id=interaction.id,
+        candidate_count=len(candidates),
+        model=model or DEFAULT_MODEL,
+    )
+    return LLMExtractionResult(candidates=candidates, raw_output=raw_output)
+
+
+def _parse_candidates(raw_output: str, interaction: Interaction) -> list[MemoryCandidate]:
+    """Parse the model's JSON output into MemoryCandidate objects.
+
+    Tolerates common model glitches: surrounding whitespace, stray
+    markdown fences, leading/trailing prose. Silently drops malformed
+    array elements rather than raising.
+    """
+    text = raw_output.strip()
+    if text.startswith("```"):
+        text = text.strip("`")
+        first_newline = text.find("\n")
+        if first_newline >= 0:
+            text = text[first_newline + 1 :]
+        if text.endswith("```"):
+            text = text[:-3]
+        text = text.strip()
+
+    if not text or text == "[]":
+        return []
+
+    if not text.lstrip().startswith("["):
+        start = text.find("[")
+        end = text.rfind("]")
+        if start >= 0 and end > start:
+            text = text[start : end + 1]
+
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as exc:
+        log.error("llm_extractor_parse_failed", error=str(exc), raw_prefix=raw_output[:120])
+        return []
+
+    if not isinstance(parsed, list):
+        return []
+
+    results: list[MemoryCandidate] = []
+    for item in parsed:
+        if not isinstance(item, dict):
+            continue
+        mem_type = str(item.get("type") or "").strip().lower()
+        content = str(item.get("content") or "").strip()
+        project = str(item.get("project") or "").strip()
+        if not project and interaction.project:
+            project = interaction.project
+        confidence_raw = item.get("confidence", 0.5)
+        if mem_type not in MEMORY_TYPES:
+            continue
+        if not content:
+            continue
+        try:
+            confidence = float(confidence_raw)
+        except (TypeError, ValueError):
+            confidence = 0.5
+        confidence = max(0.0, min(1.0, confidence))
+        results.append(
+            MemoryCandidate(
+                memory_type=mem_type,
+                content=content[:1000],
+                rule="llm_extraction",
+                source_span=content[:200],
+                project=project,
+                confidence=confidence,
+                source_interaction_id=interaction.id,
+                extractor_version=LLM_EXTRACTOR_VERSION,
+            )
+        )
+    return results

src/atocore/memory/reinforcement.py

@@ -8,10 +8,11 @@ given memory, without ever promoting anything new into trusted state.
 
 Design notes
 ------------
-- Matching is intentionally simple and explainable:
-    * normalize both sides (lowercase, collapse whitespace)
-    * require the normalized memory content (or its first 80 chars) to
-      appear as a substring in the normalized response
+- Matching uses token-overlap: tokenize both sides (lowercase, stem,
+  drop stop words), then check whether >= 70 % of the memory's content
+  tokens appear in the response token set. This handles natural
+  paraphrases (e.g. "prefers" vs "prefer", "because history" vs
+  "because the history") that substring matching missed.
 - Candidates and invalidated memories are NEVER considered — reinforcement
   must not revive history.
 - Reinforcement is capped at 1.0 and monotonically non-decreasing.
@@ -43,9 +44,21 @@ log = get_logger("reinforcement")
 # memories like "prefers Python".
 _MIN_MEMORY_CONTENT_LENGTH = 12
 
-# When a memory's content is very long, match on its leading window only
-# to avoid punishing small paraphrases further into the body.
-_MATCH_WINDOW_CHARS = 80
+# Token-overlap matching constants.
+_STOP_WORDS: frozenset[str] = frozenset({
+    "the", "a", "an", "and", "or", "of", "to", "is", "was",
+    "that", "this", "with", "for", "from", "into",
+})
+_MATCH_THRESHOLD = 0.70
+
+# Long memories can't realistically hit 70% overlap through organic
+# paraphrase — a 40-token memory would need 28 stemmed tokens echoed
+# verbatim. Above this token count the matcher switches to an absolute
+# overlap floor plus a softer fraction floor so paragraph-length memories
+# still reinforce when the response genuinely uses them.
+_LONG_MEMORY_TOKEN_COUNT = 15
+_LONG_MODE_MIN_OVERLAP = 12
+_LONG_MODE_MIN_FRACTION = 0.35
 
 DEFAULT_CONFIDENCE_DELTA = 0.02
 
@@ -144,12 +157,85 @@ def _normalize(text: str) -> str:
     return collapsed.strip()
 
 
+def _stem(word: str) -> str:
+    """Aggressive suffix-folding so inflected forms collapse.
+
+    Handles trailing ``ing``, ``ed``, and ``s`` — good enough for
+    reinforcement matching without pulling in nltk/snowball.
+    """
+    # Order matters: try longest suffix first.
+    if word.endswith("ing") and len(word) >= 6:
+        return word[:-3]
+    if word.endswith("ed") and len(word) > 4:
+        stem = word[:-2]
+        # "preferred" → "preferr" → "prefer" (doubled consonant before -ed)
+        if len(stem) >= 3 and stem[-1] == stem[-2]:
+            stem = stem[:-1]
+        return stem
+    if word.endswith("s") and len(word) > 3:
+        return word[:-1]
+    return word
+
+
+def _tokenize(text: str) -> set[str]:
+    """Split normalized text into a stemmed token set.
+
+    Strips punctuation, drops words shorter than 3 chars and stop
+    words. Hyphenated and slash-separated identifiers
+    (``polisher-control``, ``twyman-green``, ``2-projects/interferometer``)
+    produce both the full form AND each sub-token, so a query for
+    "polisher control" can match a memory that wrote
+    "polisher-control" without forcing callers to guess the exact
+    hyphenation.
+    """
+    tokens: set[str] = set()
+    for raw in text.split():
+        word = raw.strip(".,;:!?\"'()[]{}-/")
+        if not word:
+            continue
+        _add_token(tokens, word)
+        # Also add sub-tokens split on internal '-' or '/' so
+        # hyphenated identifiers match queries that don't hyphenate.
+        if "-" in word or "/" in word:
+            for sub in re.split(r"[-/]+", word):
+                _add_token(tokens, sub)
+    return tokens
+
+
+def _add_token(tokens: set[str], word: str) -> None:
+    if len(word) < 3:
+        return
+    if word in _STOP_WORDS:
+        return
+    tokens.add(_stem(word))
+
+
 def _memory_matches(memory_content: str, normalized_response: str) -> bool:
-    """Return True if the memory content appears in the response."""
+    """Return True if enough of the memory's tokens appear in the response.
+
+    Dual-mode token overlap:
+    - Short memories (<= _LONG_MEMORY_TOKEN_COUNT stems): require
+      >= 70 % of memory tokens echoed.
+    - Long memories (paragraphs): require an absolute floor of
+      _LONG_MODE_MIN_OVERLAP distinct stems echoed AND a softer
+      fraction of _LONG_MODE_MIN_FRACTION, so organic paraphrase
+      of a real project memory can reinforce without the response
+      quoting the paragraph verbatim.
+    """
     if not memory_content:
         return False
     normalized_memory = _normalize(memory_content)
     if len(normalized_memory) < _MIN_MEMORY_CONTENT_LENGTH:
         return False
-    window = normalized_memory[:_MATCH_WINDOW_CHARS]
-    return window in normalized_response
+    memory_tokens = _tokenize(normalized_memory)
+    if not memory_tokens:
+        return False
+    response_tokens = _tokenize(normalized_response)
+    overlap = memory_tokens & response_tokens
+    fraction = len(overlap) / len(memory_tokens)
+    if len(memory_tokens) <= _LONG_MEMORY_TOKEN_COUNT:
+        return fraction >= _MATCH_THRESHOLD
+    return (
+        len(overlap) >= _LONG_MODE_MIN_OVERLAP
+        and fraction >= _LONG_MODE_MIN_FRACTION
+    )

src/atocore/memory/service.py

@@ -29,6 +29,7 @@ from datetime import datetime, timezone
 
 from atocore.models.database import get_connection
 from atocore.observability.logger import get_logger
+from atocore.projects.registry import resolve_project_name
 
 log = get_logger("memory")
 
@@ -84,6 +85,13 @@ def create_memory(
         raise ValueError(f"Invalid status '{status}'. Must be one of: {MEMORY_STATUSES}")
     _validate_confidence(confidence)
 
+    # Canonicalize the project through the registry so an alias and
+    # the canonical id store under the same bucket. This keeps
+    # reinforcement queries (which use the interaction's project) and
+    # context retrieval (which uses the registry-canonicalized hint)
+    # consistent with how memories are created.
+    project = resolve_project_name(project)
+
     memory_id = str(uuid.uuid4())
     now = datetime.now(timezone.utc).isoformat()
 
@@ -162,8 +170,13 @@ def get_memories(
         query += " AND memory_type = ?"
         params.append(memory_type)
     if project is not None:
+        # Canonicalize on the read side so a caller passing an alias
+        # finds rows that were stored under the canonical id (and
+        # vice versa). resolve_project_name returns the input
+        # unchanged for unregistered names so empty-string queries
+        # for "no project scope" still work.
         query += " AND project = ?"
-        params.append(project)
+        params.append(resolve_project_name(project))
     if status is not None:
         query += " AND status = ?"
         params.append(status)
@@ -331,6 +344,9 @@ def get_memories_for_context(
     memory_types: list[str] | None = None,
     project: str | None = None,
     budget: int = 500,
+    header: str = "--- AtoCore Memory ---",
+    footer: str = "--- End Memory ---",
+    query: str | None = None,
 ) -> tuple[str, int]:
     """Get formatted memories for context injection.
 
@@ -338,38 +354,81 @@ def get_memories_for_context(
 
     Budget allocation per Master Plan section 9:
       identity: 5%, preference: 5%, rest from retrieval budget
+
+    The caller can override ``header`` / ``footer`` to distinguish
+    multiple memory blocks in the same pack (e.g. identity/preference
+    vs project/knowledge memories).
+
+    When ``query`` is provided, candidates within each memory type
+    are ranked by lexical overlap against the query (stemmed token
+    intersection, ties broken by confidence). Without a query,
+    candidates fall through in the order ``get_memories`` returns
+    them — which is effectively "by confidence desc".
     """
     if memory_types is None:
         memory_types = ["identity", "preference"]
 
     if budget <= 0:
         return "", 0
-
-    header = "--- AtoCore Memory ---"
-    footer = "--- End Memory ---"
     wrapper_chars = len(header) + len(footer) + 2
     if budget <= wrapper_chars:
         return "", 0
 
     available = budget - wrapper_chars
     selected_entries: list[str] = []
+    used = 0
 
-    for index, mtype in enumerate(memory_types):
-        type_budget = available if index == len(memory_types) - 1 else max(0, available // (len(memory_types) - index))
-        type_used = 0
+    # Pre-tokenize the query once. ``_score_memory_for_query`` is a
+    # free function below that reuses the reinforcement tokenizer so
+    # lexical scoring here matches the reinforcement matcher.
+    query_tokens: set[str] | None = None
+    if query:
+        from atocore.memory.reinforcement import _normalize, _tokenize
+
+        query_tokens = _tokenize(_normalize(query))
+        if not query_tokens:
+            query_tokens = None
+
+    # Collect ALL candidates across the requested types into one
+    # pool, then rank globally before the budget walk. Ranking per
+    # type and walking types in order would starve later types when
+    # the first type's candidates filled the budget — even if a
+    # later-type candidate matched the query perfectly. Type order
+    # is preserved as a stable tiebreaker inside
+    # ``_rank_memories_for_query`` via Python's stable sort.
+    pool: list[Memory] = []
+    seen_ids: set[str] = set()
+    for mtype in memory_types:
         for mem in get_memories(
             memory_type=mtype,
             project=project,
             min_confidence=0.5,
-            limit=10,
+            limit=30,
         ):
-            entry = f"[{mem.memory_type}] {mem.content}"
-            entry_len = len(entry) + 1
-            if entry_len > type_budget - type_used:
+            if mem.id in seen_ids:
                 continue
-            selected_entries.append(entry)
-            type_used += entry_len
-        available -= type_used
+            seen_ids.add(mem.id)
+            pool.append(mem)
+
+    if query_tokens is not None:
+        pool = _rank_memories_for_query(pool, query_tokens)
+
+    # Per-entry cap prevents a single long memory from monopolizing
+    # the band. With 16 p06 memories competing for ~700 chars, an
+    # uncapped 530-char overview memory fills the entire budget before
+    # a query-relevant 150-char memory gets a slot. The cap ensures at
+    # least 2-3 entries fit regardless of individual memory length.
+    max_entry_chars = 250
+    for mem in pool:
+        content = mem.content
+        if len(content) > max_entry_chars:
+            content = content[:max_entry_chars - 3].rstrip() + "..."
+        entry = f"[{mem.memory_type}] {content}"
+        entry_len = len(entry) + 1
+        if entry_len > available - used:
+            continue
+        selected_entries.append(entry)
+        used += entry_len
 
     if not selected_entries:
         return "", 0
@@ -381,6 +440,28 @@ def get_memories_for_context(
     return text, len(text)
 
 
+def _rank_memories_for_query(
+    memories: list["Memory"],
+    query_tokens: set[str],
+) -> list["Memory"]:
+    """Rerank a memory list by lexical overlap with a pre-tokenized query.
+
+    Ordering key: (overlap_count DESC, confidence DESC). When a query
+    shares no tokens with a memory, overlap is zero and confidence
+    acts as the sole tiebreaker — which matches the pre-query
+    behaviour and keeps no-query calls stable.
+    """
+    from atocore.memory.reinforcement import _normalize, _tokenize
+
+    scored: list[tuple[int, float, Memory]] = []
+    for mem in memories:
+        mem_tokens = _tokenize(_normalize(mem.content))
+        overlap = len(mem_tokens & query_tokens) if mem_tokens else 0
+        scored.append((overlap, mem.confidence, mem))
+    scored.sort(key=lambda t: (t[0], t[1]), reverse=True)
+    return [mem for _, _, mem in scored]
+
+
 def _row_to_memory(row) -> Memory:
     """Convert a DB row to Memory dataclass."""
     keys = row.keys() if hasattr(row, "keys") else []

src/atocore/models/database.py

@@ -71,14 +71,18 @@ CREATE TABLE IF NOT EXISTS interactions (
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
+-- Indexes that reference columns guaranteed to exist since the first
+-- release ship here. Indexes that reference columns added by later
+-- migrations (memories.project, interactions.project,
+-- interactions.session_id) are created inside _apply_migrations AFTER
+-- the corresponding ALTER TABLE, NOT here. Creating them here would
+-- fail on upgrade from a pre-migration schema because CREATE TABLE
+-- IF NOT EXISTS is a no-op on an existing table, so the new columns
+-- wouldn't be added before the CREATE INDEX runs.
 CREATE INDEX IF NOT EXISTS idx_chunks_document ON source_chunks(document_id);
 CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(memory_type);
-CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
 CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
 CREATE INDEX IF NOT EXISTS idx_interactions_project ON interactions(project_id);
-CREATE INDEX IF NOT EXISTS idx_interactions_project_name ON interactions(project);
-CREATE INDEX IF NOT EXISTS idx_interactions_session ON interactions(session_id);
-CREATE INDEX IF NOT EXISTS idx_interactions_created_at ON interactions(created_at);
 """
 
 

src/atocore/ops/backup.py

@@ -103,12 +103,27 @@ def create_runtime_backup(
         encoding="utf-8",
     )
 
+    # Automatic post-backup validation. Failures log a warning but do
+    # not raise — the backup files are still on disk and may be useful.
+    validation = validate_backup(stamp)
+    validated = validation.get("valid", False)
+    validation_errors = validation.get("errors", [])
+    if not validated:
+        log.warning(
+            "post_backup_validation_failed",
+            backup_root=str(backup_root),
+            errors=validation_errors,
+        )
+    metadata["validated"] = validated
+    metadata["validation_errors"] = validation_errors
+
     log.info(
         "runtime_backup_created",
         backup_root=str(backup_root),
         db_snapshot=str(db_snapshot_path),
         chroma_included=include_chroma,
         chroma_bytes=chroma_bytes_copied,
+        validated=validated,
     )
     return metadata
 
@@ -216,6 +231,286 @@ def validate_backup(stamp: str) -> dict:
     return result
 
 
+def restore_runtime_backup(
+    stamp: str,
+    *,
+    include_chroma: bool | None = None,
+    pre_restore_snapshot: bool = True,
+    confirm_service_stopped: bool = False,
+) -> dict:
+    """Restore a previously captured runtime backup.
+
+    CRITICAL: the AtoCore service MUST be stopped before calling this.
+    Overwriting a live SQLite database corrupts state and can break
+    the running container's open connections. The caller must pass
+    ``confirm_service_stopped=True`` as an explicit acknowledgment —
+    otherwise this function refuses to run.
+
+    The restore procedure:
+
+    1. Validate the backup via ``validate_backup``; refuse on any error.
+    2. (default) Create a pre-restore safety snapshot of the CURRENT
+       state so the restore itself is reversible. The snapshot stamp
+       is returned in the result for the operator to record.
+    3. Remove stale SQLite WAL/SHM sidecar files next to the target db
+       before copying — the snapshot is a self-contained main-file
+       image from ``conn.backup()``, and leftover WAL/SHM from the old
+       live db would desync against the restored main file.
+    4. Copy the snapshot db over the target db path.
+    5. Restore the project registry file if the snapshot captured one.
+    6. Restore the Chroma directory if ``include_chroma`` resolves to
+       true. When ``include_chroma is None`` the function defers to
+       whether the snapshot captured Chroma (the common case).
+    7. Run ``PRAGMA integrity_check`` on the restored db and report
+       the result.
+
+    Returns a dict describing what was restored. On refused restore
+    (service still running, validation failed) raises ``RuntimeError``.
+    """
+    if not confirm_service_stopped:
+        raise RuntimeError(
+            "restore_runtime_backup refuses to run without "
+            "confirm_service_stopped=True — stop the AtoCore container "
+            "first (e.g. `docker compose down` from deploy/dalidou) "
+            "before calling this function"
+        )
+
+    validation = validate_backup(stamp)
+    if not validation.get("valid"):
+        raise RuntimeError(
+            f"backup {stamp} failed validation: {validation.get('errors')}"
+        )
+    metadata = validation.get("metadata") or {}
+
+    pre_snapshot_stamp: str | None = None
+    if pre_restore_snapshot:
+        pre = create_runtime_backup(include_chroma=False)
+        pre_snapshot_stamp = Path(pre["backup_root"]).name
+
+    target_db = _config.settings.db_path
+    source_db = Path(metadata.get("db_snapshot_path", ""))
+    if not source_db.exists():
+        raise RuntimeError(
+            f"db snapshot not found at {source_db} — backup "
+            f"metadata may be stale"
+        )
+
+    # Force sqlite to flush any lingering WAL into the main file and
+    # release OS-level file handles on -wal/-shm before we swap the
+    # main file. Passing through conn.backup() in the pre-restore
+    # snapshot can leave sidecars momentarily locked on Windows;
+    # an explicit checkpoint(TRUNCATE) is the reliable way to flush
+    # and release. Best-effort: if the target db can't be opened
+    # (missing, corrupt), fall through and trust the copy step.
+    if target_db.exists():
+        try:
+            with sqlite3.connect(str(target_db)) as checkpoint_conn:
+                checkpoint_conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        except sqlite3.DatabaseError as exc:
+            log.warning(
+                "restore_pre_checkpoint_failed",
+                target_db=str(target_db),
+                error=str(exc),
+            )
+
+    # Remove stale WAL/SHM sidecars from the old live db so SQLite
+    # can't read inconsistent state on next open. Tolerant to
+    # Windows file-lock races — the subsequent copy replaces the
+    # main file anyway, and the integrity check afterward is the
+    # actual correctness signal.
+    wal_path = target_db.with_name(target_db.name + "-wal")
+    shm_path = target_db.with_name(target_db.name + "-shm")
+    for stale in (wal_path, shm_path):
+        if stale.exists():
+            try:
+                stale.unlink()
+            except OSError as exc:
+                log.warning(
+                    "restore_sidecar_unlink_failed",
+                    path=str(stale),
+                    error=str(exc),
+                )
+
+    target_db.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source_db, target_db)
+
+    registry_restored = False
+    registry_snapshot_path = metadata.get("registry_snapshot_path", "")
+    if registry_snapshot_path:
+        src_reg = Path(registry_snapshot_path)
+        if src_reg.exists():
+            dst_reg = _config.settings.resolved_project_registry_path
+            dst_reg.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_reg, dst_reg)
+            registry_restored = True
+
+    chroma_snapshot_path = metadata.get("chroma_snapshot_path", "")
+    if include_chroma is None:
+        include_chroma = bool(chroma_snapshot_path)
+    chroma_restored = False
+    if include_chroma and chroma_snapshot_path:
+        src_chroma = Path(chroma_snapshot_path)
+        if src_chroma.exists() and src_chroma.is_dir():
+            dst_chroma = _config.settings.chroma_path
+            # Do NOT rmtree the destination itself: in a Dockerized
+            # deployment the chroma dir is a bind-mounted volume, and
+            # unlinking a mount point raises
+            #   OSError [Errno 16] Device or resource busy.
+            # Instead, clear the directory's CONTENTS and copytree into
+            # it with dirs_exist_ok=True. This is equivalent to an
+            # rmtree+copytree for restore purposes but stays inside the
+            # mount boundary. Discovered during the first real restore
+            # drill on Dalidou (2026-04-09).
+            dst_chroma.mkdir(parents=True, exist_ok=True)
+            for item in dst_chroma.iterdir():
+                if item.is_dir() and not item.is_symlink():
+                    shutil.rmtree(item)
+                else:
+                    item.unlink()
+            shutil.copytree(src_chroma, dst_chroma, dirs_exist_ok=True)
+            chroma_restored = True
+
+    restored_integrity_ok = False
+    integrity_error: str | None = None
+    try:
+        with sqlite3.connect(str(target_db)) as conn:
+            row = conn.execute("PRAGMA integrity_check").fetchone()
+            restored_integrity_ok = bool(row and row[0] == "ok")
+            if not restored_integrity_ok:
+                integrity_error = row[0] if row else "no_row"
+    except sqlite3.DatabaseError as exc:
+        integrity_error = f"db_open_failed: {exc}"
+
+    result: dict = {
+        "stamp": stamp,
+        "pre_restore_snapshot": pre_snapshot_stamp,
+        "target_db": str(target_db),
+        "db_restored": True,
+        "registry_restored": registry_restored,
+        "chroma_restored": chroma_restored,
+        "restored_integrity_ok": restored_integrity_ok,
+    }
+    if integrity_error:
+        result["integrity_error"] = integrity_error
+
+    log.info(
+        "runtime_backup_restored",
+        stamp=stamp,
+        pre_restore_snapshot=pre_snapshot_stamp,
+        registry_restored=registry_restored,
+        chroma_restored=chroma_restored,
+        integrity_ok=restored_integrity_ok,
+    )
+    return result
+
+
+def cleanup_old_backups(*, confirm: bool = False) -> dict:
+    """Apply retention policy and remove old snapshots.
+
+    Retention keeps:
+    - Last 7 daily snapshots (most recent per calendar day)
+    - Last 4 weekly snapshots (most recent on each Sunday)
+    - Last 6 monthly snapshots (most recent on the 1st of each month)
+
+    All other snapshots are candidates for deletion. Runs as dry-run by
+    default; pass ``confirm=True`` to actually delete.
+
+    Returns a dict with kept/deleted counts and any errors.
+    """
+    snapshots_root = _config.settings.resolved_backup_dir / "snapshots"
+    if not snapshots_root.exists() or not snapshots_root.is_dir():
+        return {"kept": 0, "deleted": 0, "would_delete": 0, "dry_run": not confirm, "errors": []}
+
+    # Parse all stamp directories into (datetime, dir_path) pairs.
+    stamps: list[tuple[datetime, Path]] = []
+    unparseable: list[str] = []
+    for entry in sorted(snapshots_root.iterdir()):
+        if not entry.is_dir():
+            continue
+        try:
+            dt = datetime.strptime(entry.name, "%Y%m%dT%H%M%SZ").replace(tzinfo=UTC)
+            stamps.append((dt, entry))
+        except ValueError:
+            unparseable.append(entry.name)
+
+    if not stamps:
+        return {
+            "kept": 0, "deleted": 0, "would_delete": 0,
+            "dry_run": not confirm, "errors": [],
+            "unparseable": unparseable,
+        }
+
+    # Sort newest first so "most recent per bucket" is a simple first-seen.
+    stamps.sort(key=lambda t: t[0], reverse=True)
+
+    keep_set: set[Path] = set()
+
+    # Last 7 daily: most recent snapshot per calendar day.
+    seen_days: set[str] = set()
+    for dt, path in stamps:
+        day_key = dt.strftime("%Y-%m-%d")
+        if day_key not in seen_days:
+            seen_days.add(day_key)
+            keep_set.add(path)
+            if len(seen_days) >= 7:
+                break
+
+    # Last 4 weekly: most recent snapshot that falls on a Sunday.
+    seen_weeks: set[str] = set()
+    for dt, path in stamps:
+        if dt.weekday() == 6:  # Sunday
+            week_key = dt.strftime("%Y-W%W")
+            if week_key not in seen_weeks:
+                seen_weeks.add(week_key)
+                keep_set.add(path)
+                if len(seen_weeks) >= 4:
+                    break
+
+    # Last 6 monthly: most recent snapshot on the 1st of a month.
+    seen_months: set[str] = set()
+    for dt, path in stamps:
+        if dt.day == 1:
+            month_key = dt.strftime("%Y-%m")
+            if month_key not in seen_months:
+                seen_months.add(month_key)
+                keep_set.add(path)
+                if len(seen_months) >= 6:
+                    break
+
+    to_delete = [path for _, path in stamps if path not in keep_set]
+
+    errors: list[str] = []
+    deleted_count = 0
+    if confirm:
+        for path in to_delete:
+            try:
+                shutil.rmtree(path)
+                deleted_count += 1
+            except OSError as exc:
+                errors.append(f"{path.name}: {exc}")
+
+    result: dict = {
+        "kept": len(keep_set),
+        "dry_run": not confirm,
+        "errors": errors,
+    }
+    if confirm:
+        result["deleted"] = deleted_count
+    else:
+        result["would_delete"] = len(to_delete)
+    if unparseable:
+        result["unparseable"] = unparseable
+
+    log.info(
+        "cleanup_old_backups",
+        kept=len(keep_set),
+        deleted=deleted_count if confirm else 0,
+        would_delete=len(to_delete) if not confirm else 0,
+        dry_run=not confirm,
+    )
+    return result
+
+
 def _backup_sqlite_db(source_path: Path, dest_path: Path) -> None:
     source_conn = sqlite3.connect(str(source_path))
     dest_conn = sqlite3.connect(str(dest_path))
@@ -242,7 +537,98 @@ def _copy_directory_tree(source: Path, dest: Path) -> tuple[int, int]:
 
 
 def main() -> None:
-    result = create_runtime_backup()
+    """CLI entry point for the backup module.
+
+    Supports four subcommands:
+
+    - ``create``   run ``create_runtime_backup`` (default if none given)
+    - ``list``     list all runtime backup snapshots
+    - ``validate`` validate a specific snapshot by stamp
+    - ``restore``  restore a specific snapshot by stamp
+
+    The restore subcommand is the one used by the backup/restore drill
+    and MUST be run only when the AtoCore service is stopped. It takes
+    ``--confirm-service-stopped`` as an explicit acknowledgment.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="python -m atocore.ops.backup",
+        description="AtoCore runtime backup create/list/validate/restore",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_create = sub.add_parser("create", help="create a new runtime backup")
+    p_create.add_argument(
+        "--chroma",
+        action="store_true",
+        help="also snapshot the Chroma vector store (cold copy)",
+    )
+
+    sub.add_parser("list", help="list runtime backup snapshots")
+
+    p_validate = sub.add_parser("validate", help="validate a snapshot by stamp")
+    p_validate.add_argument("stamp", help="snapshot stamp (e.g. 20260409T010203Z)")
+
+    p_cleanup = sub.add_parser("cleanup", help="remove old snapshots per retention policy")
+    p_cleanup.add_argument(
+        "--confirm",
+        action="store_true",
+        help="actually delete (default is dry-run)",
+    )
+
+    p_restore = sub.add_parser(
+        "restore",
+        help="restore a snapshot by stamp (service must be stopped)",
+    )
+    p_restore.add_argument("stamp", help="snapshot stamp to restore")
+    p_restore.add_argument(
+        "--confirm-service-stopped",
+        action="store_true",
+        help="explicit acknowledgment that the AtoCore container is stopped",
+    )
+    p_restore.add_argument(
+        "--no-pre-snapshot",
+        action="store_true",
+        help="skip the pre-restore safety snapshot of current state",
+    )
+    chroma_group = p_restore.add_mutually_exclusive_group()
+    chroma_group.add_argument(
+        "--chroma",
+        dest="include_chroma",
+        action="store_true",
+        default=None,
+        help="force-restore the Chroma snapshot",
+    )
+    chroma_group.add_argument(
+        "--no-chroma",
+        dest="include_chroma",
+        action="store_false",
+        help="skip the Chroma snapshot even if it was captured",
+    )
+
+    args = parser.parse_args()
+    command = args.command or "create"
+
+    if command == "create":
+        include_chroma = getattr(args, "chroma", False)
+        result = create_runtime_backup(include_chroma=include_chroma)
+    elif command == "list":
+        result = {"backups": list_runtime_backups()}
+    elif command == "validate":
+        result = validate_backup(args.stamp)
+    elif command == "cleanup":
+        result = cleanup_old_backups(confirm=getattr(args, "confirm", False))
+    elif command == "restore":
+        result = restore_runtime_backup(
+            args.stamp,
+            include_chroma=args.include_chroma,
+            pre_restore_snapshot=not args.no_pre_snapshot,
+            confirm_service_stopped=args.confirm_service_stopped,
+        )
+    else:  # pragma: no cover — argparse guards this
+        parser.error(f"unknown command: {command}")
+
     print(json.dumps(result, indent=2, ensure_ascii=True))
 
 

src/atocore/projects/registry.py

@@ -254,6 +254,30 @@ def get_registered_project(project_name: str) -> RegisteredProject | None:
     return None
 
 
+def resolve_project_name(name: str | None) -> str:
+    """Canonicalize a project name through the registry.
+
+    Returns the canonical ``project_id`` if the input matches any
+    registered project's id or alias. Returns the input unchanged
+    when it's empty or not in the registry — the second case keeps
+    backwards compatibility with hand-curated state, memories, and
+    interactions that predate the registry, or for projects that
+    are intentionally not registered.
+
+    This helper is the single canonicalization boundary for project
+    names across the trust hierarchy. Every read/write that takes a
+    project name should pass it through ``resolve_project_name``
+    before storing or querying. The contract is documented in
+    ``docs/architecture/representation-authority.md``.
+    """
+    if not name:
+        return name or ""
+    project = get_registered_project(name)
+    if project is not None:
+        return project.project_id
+    return name
+
+
 def refresh_registered_project(project_name: str, purge_deleted: bool = False) -> dict:
     """Ingest all configured source roots for a registered project.
 

t420-openclaw/AGENTS.md

@@ -0,0 +1,234 @@
+# AGENTS.md - Your Workspace
+
+This folder is home. Treat it that way.
+
+## First Run
+
+If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
+
+## Every Session
+
+Before doing anything else:
+1. Read `SOUL.md` — this is who you are
+2. Read `USER.md` — this is who you're helping
+3. Read `MODEL-ROUTING.md` — follow the auto-routing policy for model selection
+4. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+5. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`
+
+Don't ask permission. Just do it.
+
+## Memory
+
+You wake up fresh each session. These files are your continuity:
+- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
+- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
+
+Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
+
+### 🧠 MEMORY.md - Your Long-Term Memory
+- **ONLY load in main session** (direct chats with your human)
+- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
+- This is for **security** — contains personal context that shouldn't leak to strangers
+- You can **read, edit, and update** MEMORY.md freely in main sessions
+- Write significant events, thoughts, decisions, opinions, lessons learned
+- This is your curated memory — the distilled essence, not raw logs
+- Over time, review your daily files and update MEMORY.md with what's worth keeping
+
+### 📝 Write It Down - No "Mental Notes"!
+- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
+- "Mental notes" don't survive session restarts. Files do.
+- When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
+- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
+- When you make a mistake → document it so future-you doesn't repeat it
+- **Text > Brain** 📝
+
+## Safety
+
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- `trash` > `rm` (recoverable beats gone forever)
+- When in doubt, ask.
+
+## External vs Internal
+
+**Safe to do freely:**
+- Read files, explore, organize, learn
+- Search the web, check calendars
+- Work within this workspace
+
+**Ask first:**
+- Sending emails, tweets, public posts
+- Anything that leaves the machine
+- Anything you're uncertain about
+
+## Group Chats
+
+You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
+
+### 💬 Know When to Speak!
+In group chats where you receive every message, be **smart about when to contribute**:
+
+**Respond when:**
+- Directly mentioned or asked a question
+- You can add genuine value (info, insight, help)
+- Something witty/funny fits naturally
+- Correcting important misinformation
+- Summarizing when asked
+
+**Stay silent (HEARTBEAT_OK) when:**
+- It's just casual banter between humans
+- Someone already answered the question
+- Your response would just be "yeah" or "nice"
+- The conversation is flowing fine without you
+- Adding a message would interrupt the vibe
+
+**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it.
+
+**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments.
+
+Participate, don't dominate.
+
+### 😊 React Like a Human!
+On platforms that support reactions (Discord, Slack), use emoji reactions naturally:
+
+**React when:**
+- You appreciate something but don't need to reply (👍, ❤️, 🙌)
+- Something made you laugh (😂, 💀)
+- You find it interesting or thought-provoking (🤔, 💡)
+- You want to acknowledge without interrupting the flow
+- It's a simple yes/no or approval situation (✅, 👀)
+
+**Why it matters:**
+Reactions are lightweight social signals. Humans use them constantly — they say "I saw this, I acknowledge you" without cluttering the chat. You should too.
+
+**Don't overdo it:** One reaction per message max. Pick the one that fits best.
+
+## Tools
+
+When a task is contextual and project-dependent, use the `atocore-context` skill to query Dalidou-hosted AtoCore for trusted project state, retrieval, context-building, registered project refresh, or project registration discovery when that will improve accuracy. Treat AtoCore as additive and fail-open; do not replace OpenClaw's own memory with it. Prefer `projects` and `refresh-project <id>` when a known project needs a clean source refresh, and use `project-template` when proposing a new project registration, and `propose-project ...` when you want a normalized preview before editing the registry manually.
+
+### Organic AtoCore Routing
+
+For normal project knowledge questions, use AtoCore by default without waiting for the human to ask for the helper explicitly.
+
+Use AtoCore first when the prompt:
+- mentions a registered project id or alias
+- asks about architecture, constraints, status, requirements, vendors, planning, prior decisions, or current project truth
+- would benefit from cross-source context instead of only the local repo
+
+Preferred flow:
+1. `auto-context "<prompt>" 3000` for most project knowledge questions
+2. `project-state <project>` when the user is clearly asking for trusted current truth
+3. `audit-query "<prompt>" 5 [project]` when broad prompts drift, archive/history noise appears, or retrieval quality is being evaluated
+4. `refresh-project <id>` before answering if the user explicitly asked to refresh or ingest project changes
+
+For AtoCore improvement work, prefer this sequence:
+1. retrieval-quality pass
+2. Wave 2 trusted-operational ingestion
+3. AtoDrive clarification
+4. restore and ops validation
+
+Wave 2 trusted-operational truth should prioritize:
+- current status
+- current decisions
+- requirements baseline
+- milestone plan
+- next actions
+
+Do not ingest the whole PKM vault before the trusted-operational layer is in good shape. Treat AtoDrive as curated operational truth, not a generic dump.
+
+Do not force AtoCore for purely local coding actions like fixing a function, editing one file, or running tests, unless broader project context is likely to matter.
+
+If `auto-context` returns `no_project_match` or AtoCore is unavailable, continue normally with OpenClaw's own tools and memory.
+
+Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
+
+**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
+
+**📝 Platform Formatting:**
+- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
+- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
+- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
+
+## 💓 Heartbeats - Be Proactive!
+
+When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
+
+Default heartbeat prompt:
+`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
+
+You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.
+
+### Heartbeat vs Cron: When to Use Each
+
+**Use heartbeat when:**
+- Multiple checks can batch together (inbox + calendar + notifications in one turn)
+- You need conversational context from recent messages
+- Timing can drift slightly (every ~30 min is fine, not exact)
+- You want to reduce API calls by combining periodic checks
+
+**Use cron when:**
+- Exact timing matters ("9:00 AM sharp every Monday")
+- Task needs isolation from main session history
+- You want a different model or thinking level for the task
+- One-shot reminders ("remind me in 20 minutes")
+- Output should deliver directly to a channel without main session involvement
+
+**Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.
+
+**Things to check (rotate through these, 2-4 times per day):**
+- **Emails** - Any urgent unread messages?
+- **Calendar** - Upcoming events in next 24-48h?
+- **Mentions** - Twitter/social notifications?
+- **Weather** - Relevant if your human might go out?
+
+**Track your checks** in `memory/heartbeat-state.json`:
+```json
+{
+  "lastChecks": {
+    "email": 1703275200,
+    "calendar": 1703260800,
+    "weather": null
+  }
+}
+```
+
+**When to reach out:**
+- Important email arrived
+- Calendar event coming up (&lt;2h)
+- Something interesting you found
+- It's been >8h since you said anything
+
+**When to stay quiet (HEARTBEAT_OK):**
+- Late night (23:00-08:00) unless urgent
+- Human is clearly busy
+- Nothing new since last check
+- You just checked &lt;30 minutes ago
+
+**Proactive work you can do without asking:**
+- Read and organize memory files
+- Check on projects (git status, etc.)
+- Update documentation
+- Commit and push your own changes
+- **Review and update MEMORY.md** (see below)
+
+### 🔄 Memory Maintenance (During Heartbeats)
+Periodically (every few days), use a heartbeat to:
+1. Read through recent `memory/YYYY-MM-DD.md` files
+2. Identify significant events, lessons, or insights worth keeping long-term
+3. Update `MEMORY.md` with distilled learnings
+4. Remove outdated info from MEMORY.md that's no longer relevant
+
+Think of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.
+
+The goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.
+
+## Make It Yours
+
+This is a starting point. Add your own conventions, style, and rules as you figure out what works.
+
+## Orchestration Completion Protocol
+After any orchestration chain completes (research → review → condensation):
+1. Secretary MUST be the final agent tasked
+2. Secretary produces the condensation file AND posts a distillate to Discord #reports
+3. Manager should include in Secretary's task: "Post a distillate to Discord #reports summarizing this orchestration"

t420-openclaw/ATOCORE-OPERATIONS.md

@@ -0,0 +1,133 @@
+# AtoCore Operations
+
+This is the current operating playbook for making AtoCore more dependable and higher-signal.
+
+## Order of Work
+
+1. Retrieval-quality pass
+2. Wave 2 trusted-operational ingestion
+3. AtoDrive clarification
+4. Restore and ops validation
+
+## 1. Retrieval-Quality Pass
+
+Observed behavior from the live service:
+
+- broad prompts like `gigabit` and `polisher` still surface archive/history noise
+- meaningful prompts like `mirror frame stiffness requirements and selected architecture` are much sharper
+- now that the corpus is large enough, ranking quality matters more than raw corpus presence
+
+Use these commands first:
+
+```bash
+python atocore.py audit-query "gigabit" 5
+python atocore.py audit-query "polisher" 5
+python atocore.py audit-query "mirror frame stiffness requirements and selected architecture" 5 p04-gigabit
+python atocore.py audit-query "interferometer error budget and vendor selection constraints" 5 p05-interferometer
+python atocore.py audit-query "polisher system map shared contracts and calibration workflow" 5 p06-polisher
+```
+
+What to fix in the retrieval pass:
+
+- reduce `_archive`, `pre-cleanup`, `pre-migration`, and `History` prominence
+- prefer current-status, decision, requirement, architecture-freeze, and milestone docs
+- prefer trusted project-state over freeform notes when both speak to current truth
+- keep broad prompts from matching stale or generic chunks too easily
+
+Suggested acceptance bar:
+
+- top 5 for active-project prompts contain at least one current-status or next-focus item
+- top 5 contain at least one decision or architecture-baseline item
+- top 5 contain at least one requirement or constraints item
+- broad single-word prompts no longer lead with archive/history chunks
+
+## 2. Wave 2 Trusted-Operational Ingestion
+
+Do not ingest the whole PKM vault next.
+
+Wave 2 should ingest trusted operational truth for each active project:
+
+- current status dashboard or status note
+- current decisions / decision log
+- requirements baseline
+- architecture freeze / current baseline
+- milestone plan
+- next actions / near-term focus
+
+Recommended helper flow:
+
+```bash
+python atocore.py project-state p04-gigabit
+python atocore.py project-state p05-interferometer
+python atocore.py project-state p06-polisher
+python atocore.py project-state-set p04-gigabit status next_focus "Continue curated support and frame-context buildout." "Wave 2 status dashboard" 1.0
+python atocore.py project-state-set p05-interferometer requirement key_constraints "Preserve current error-budget, thermal, and vendor-selection constraints as the working baseline." "Wave 2 requirements baseline" 1.0
+python atocore.py project-state-set p06-polisher decision system_boundary "The suite remains a three-layer chain with explicit planning, translation, and execution boundaries." "Wave 2 decision log" 1.0
+python atocore.py refresh-project p04-gigabit
+python atocore.py refresh-project p05-interferometer
+python atocore.py refresh-project p06-polisher
+```
+
+Use project-state for the most authoritative "current truth" fields, then refresh the registered project roots after curated Wave 2 documents land.
+
+## 3. AtoDrive Clarification
+
+AtoDrive should become a trusted-operational source, not a generic corpus dump.
+
+Good AtoDrive candidates:
+
+- current dashboards
+- current baselines
+- approved architecture docs
+- decision logs
+- milestone and next-step views
+- operational source-of-truth files that humans actively maintain
+
+Avoid as default AtoDrive ingest:
+
+- large generic archives
+- duplicated exports
+- stale snapshots when a newer baseline exists
+- exploratory notes that are not designated current truth
+
+Rule of thumb:
+
+- if the file answers "what is true now?" it may belong in trusted-operational
+- if the file mostly answers "what did we think at some point?" it belongs in the broader corpus, not Wave 2
+
+## 4. Restore and Ops Validation
+
+Backups are not enough until restore has been tested.
+
+Validate these explicitly:
+
+- SQLite metadata restore
+- Chroma restore or rebuild
+- registry restore
+- source-root refresh after restore
+- health and stats consistency after recovery
+
+Recommended restore drill:
+
+1. Record current `health`, `stats`, and `projects` output.
+2. Restore SQLite metadata and project registry from backup.
+3. Decide whether Chroma is restored from backup or rebuilt from source.
+4. Run project refresh for active projects.
+5. Compare vector/doc counts and run retrieval audits again.
+
+Commands to capture the before/after baseline:
+
+```bash
+python atocore.py health
+python atocore.py stats
+python atocore.py projects
+python atocore.py audit-query "gigabit" 5
+python atocore.py audit-query "interferometer error budget and vendor selection constraints" 5 p05-interferometer
+```
+
+Recovery policy decision still needed:
+
+- prefer Chroma backup restore for fast recovery when backup integrity is trusted
+- prefer Chroma rebuild when backups are suspect, schema changed, or ranking behavior drifts unexpectedly
+
+The important part is to choose one policy on purpose and validate it, not leave it implicit.

t420-openclaw/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: atocore-context
+description: Use Dalidou-hosted AtoCore as a read-only external context service for project state, retrieval, and context-building without touching OpenClaw's own memory.
+---
+
+# AtoCore Context
+
+Use this skill when you need trusted project context, retrieval help, or AtoCore
+health/status from the canonical Dalidou instance.
+
+## Purpose
+
+AtoCore is an additive external context service.
+
+- It does not replace OpenClaw's own memory.
+- It should be used for contextual work, not trivial prompts.
+- It is read-only in this first integration batch.
+- If AtoCore is unavailable, continue normally.
+
+## Canonical Endpoint
+
+Default base URL:
+
+```bash
+http://dalidou:8100
+```
+
+Override with:
+
+```bash
+ATOCORE_BASE_URL=http://host:port
+```
+
+## Safe Usage
+
+Use AtoCore for:
+- project-state checks
+- automatic project detection for normal project questions
+- retrieval-quality audits before declaring a project corpus "good enough"
+- retrieval over ingested project/ecosystem docs
+- context-building for complex project prompts
+- verifying current AtoCore hosting and architecture state
+- listing registered projects and refreshing a known project source set
+- inspecting the project registration template before proposing a new project entry
+- generating a proposal preview for a new project registration without writing it
+- registering an approved project entry when explicitly requested
+- updating an existing registered project when aliases or description need refinement
+
+Do not use AtoCore for:
+- automatic memory write-back
+- replacing OpenClaw memory
+- silent ingestion of broad new corpora without approval
+- ingesting the whole PKM vault before trusted operational truth is staged
+- mutating the registry automatically without human approval
+
+## Commands
+
+```bash
+~/clawd/skills/atocore-context/scripts/atocore.sh health
+~/clawd/skills/atocore-context/scripts/atocore.sh sources
+~/clawd/skills/atocore-context/scripts/atocore.sh stats
+~/clawd/skills/atocore-context/scripts/atocore.sh projects
+~/clawd/skills/atocore-context/scripts/atocore.sh project-template
+~/clawd/skills/atocore-context/scripts/atocore.sh detect-project "what's the interferometer error budget?"
+~/clawd/skills/atocore-context/scripts/atocore.sh auto-context "what's the interferometer error budget?" 3000
+~/clawd/skills/atocore-context/scripts/atocore.sh debug-context
+~/clawd/skills/atocore-context/scripts/atocore.sh audit-query "gigabit" 5
+~/clawd/skills/atocore-context/scripts/atocore.sh audit-query "mirror frame stiffness requirements and selected architecture" 5 p04-gigabit
+~/clawd/skills/atocore-context/scripts/atocore.sh propose-project p07-example "p07,example-project" vault incoming/projects/p07-example "Example project" "Primary staged project docs"
+~/clawd/skills/atocore-context/scripts/atocore.sh register-project p07-example "p07,example-project" vault incoming/projects/p07-example "Example project" "Primary staged project docs"
+~/clawd/skills/atocore-context/scripts/atocore.sh update-project p05 "Curated staged docs for the P05 interferometer architecture, vendors, and error-budget project."
+~/clawd/skills/atocore-context/scripts/atocore.sh refresh-project p05
+~/clawd/skills/atocore-context/scripts/atocore.sh project-state atocore
+~/clawd/skills/atocore-context/scripts/atocore.sh project-state-set p05-interferometer status next_focus "Freeze current error-budget baseline and vendor downselect." "Wave 2 status dashboard" 1.0
+~/clawd/skills/atocore-context/scripts/atocore.sh project-state-invalidate p05-interferometer status next_focus
+~/clawd/skills/atocore-context/scripts/atocore.sh query "What is AtoDrive?"
+~/clawd/skills/atocore-context/scripts/atocore.sh context-build "Need current AtoCore architecture" atocore 3000
+```
+
+Direct Python entrypoint for non-Bash environments:
+
+```bash
+python ~/clawd/skills/atocore-context/scripts/atocore.py health
+```
+
+## Contract
+
+- prefer AtoCore only when additional context is genuinely useful
+- trust AtoCore as additive context, not as a hard runtime dependency
+- fail open if the service errors or times out
+- cite when information came from AtoCore rather than local OpenClaw memory
+- for normal project knowledge questions, prefer `auto-context "<prompt>" 3000` before answering
+- use `detect-project "<prompt>"` when you want to inspect project inference explicitly
+- use `debug-context` right after `auto-context` or `context-build` when you want
+  to inspect the exact last AtoCore context pack
+- use `audit-query "<prompt>" 5 [project]` when retrieval quality is in question, especially for broad prompts
+- prefer `projects` plus `refresh-project <id>` over long ad hoc ingest instructions when the project is already registered
+- use `project-template` when preparing a new project registration proposal
+- use `propose-project ...` to draft a normalized entry and review collisions first
+- use `register-project ...` only after the proposal has been reviewed and approved
+- use `update-project ...` when a registered project's description or aliases need refinement before refresh
+- use `project-state-set` for trusted operational truth such as current status, current decisions, frozen requirements, milestone baselines, and next actions
+- do Wave 2 before broad PKM expansion: status dashboards, decision logs, milestone views, current baseline docs, and next-step views
+- treat AtoDrive as a curated trusted-operational source, not a generic dump of miscellaneous drive files
+- validate restore posture explicitly; a backup is not trusted until restore or rebuild steps have been exercised successfully

t420-openclaw/TOOLS.md

@@ -0,0 +1,279 @@
+# TOOLS.md - Local Notes
+
+
+## AtoCore (External Context Service)
+
+- **Canonical Host:** http://dalidou:8100
+- **Role:** Read-only external context service for trusted project state, retrieval, context-building, registered project refresh, project registration discovery, and retrieval-quality auditing
+- **Machine state lives on:** Dalidou (/srv/storage/atocore/data/...)
+- **Rule:** Use AtoCore as additive context only; do not treat it as a replacement for OpenClaw memory
+- **Helper script:** /home/papa/clawd/skills/atocore-context/scripts/atocore.sh
+- **Python fallback:** `/home/papa/clawd/skills/atocore-context/scripts/atocore.py` for non-Bash environments
+- **Key commands:** `projects`, `project-template`, `detect-project "<prompt>"`, `auto-context "<prompt>" [budget] [project]`, `debug-context`, `audit-query "<prompt>" [top_k] [project]`, `propose-project ...`, `register-project ...`, `update-project <id> "description" ["aliases"]`, `refresh-project <id>`, `project-state <id> [category]`, `project-state-set <project> <category> <key> <value> [source] [confidence]`, `project-state-invalidate <project> <category> <key>`, `context-build ...`
+- **Fail-open rule:** If AtoCore is unavailable, continue normal OpenClaw behavior
+
+### Organic Usage Rule
+
+- For normal project knowledge questions, try `auto-context` first.
+- For retrieval complaints or broad-prompt drift, run `audit-query` before changing ingestion scope.
+- Use `project-state` when you want trusted current truth only.
+- Use `project-state-set` for current status, current decisions, baseline requirements, milestone views, and next actions.
+- Use `query` for quick probing/debugging.
+- Use `context-build` when you already know the project and want the exact context pack.
+- Use `debug-context` right after `auto-context` or `context-build` if you want
+  to inspect the exact AtoCore supplement being fed into the workflow.
+- Do Wave 2 trusted-operational ingestion before broad PKM expansion.
+- Treat AtoDrive as a curated operational-truth source, not a generic bulk ingest target.
+- Keep purely local coding tasks local unless broader project context is likely to help.
+
+## PKM / Obsidian Vault
+
+- **Local Path:** `/home/papa/obsidian-vault/`
+- **Name:** Antoine Brain Extension
+- **Sync:** Syncthing (syncs from dalidou)
+- **Access:** ✅ Direct local access — no SSH needed!
+
+## ATODrive (Work Documents)
+
+- **Local Path:** `/home/papa/ATODrive/`
+- **Sync:** Syncthing (syncs from dalidou SeaDrive)
+- **Access:** ✅ Direct local access
+
+## Atomaste (Business/Templates)
+
+- **Local Path:** `/home/papa/Atomaste/`
+- **Sync:** Syncthing (syncs from dalidou SeaDrive)
+- **Access:** ✅ Direct local access
+
+## Atomaste Finance (Canonical Expense System)
+
+- **Single home:** `/home/papa/Atomaste/03_Finances/Expenses/`
+- **Rule:** If it is expense-related, it belongs under `Expenses/`, not `Documents/Receipts/`
+- **Per-year structure:**
+  - `YYYY/Inbox/` — unprocessed incoming receipts/screenshots
+  - `YYYY/receipts/` — final home for processed raw receipt files
+  - `YYYY/expenses_master.csv` — main structured expense table
+  - `YYYY/reports/` — derived summaries, exports, tax packages
+- **Workflow:** Inbox → `expenses_master.csv` → `receipts/`
+- **Legacy path:** `/home/papa/Atomaste/03_Finances/Documents/Receipts/` is deprecated and should stay unused except for the migration note
+
+## Odile Inc (Corporate)
+
+- **Local Path:** `/home/papa/Odile Inc/`
+- **Sync:** Syncthing (syncs from dalidou SeaDrive `My Libraries\Odile\Odile Inc`)
+- **Access:** ✅ Direct local access
+- **Entity:** Odile Bérubé O.D. Inc. (SPCC, optometrist)
+- **Fiscal year end:** July 31
+- **Structure:** `01_Finances/` (BankStatements, Expenses, Payroll, Revenue, Taxes), `02_Admin/`, `Inbox/`
+- **Rule:** Corporate docs go here, personal docs go to `Impôts Odile/Dossier_Fiscal_YYYY/`
+
+## Impôts Odile (Personal Tax)
+
+- **Local Path:** `/home/papa/Impôts Odile/`
+- **Sync:** Syncthing (syncs from dalidou SeaDrive)
+- **Access:** ✅ Direct local access
+- **Structure:** `Dossier_Fiscal_YYYY/` (9 sections: revenus, dépenses, crédits, feuillets, REER, dons, comptable, frais médicaux, budget)
+- **Cron:** Monthly receipt processing (1st of month, 2 PM ET) scans mario@atomaste.ca for Odile's emails
+
+## Git Repos (via Gitea)
+
+- **Gitea URL:** http://100.80.199.40:3000
+- **Auth:** Token in `~/.gitconfig` — **ALWAYS use auth for API calls** (private repos won't show without it)
+- **API Auth Header:** `Authorization: token $(git config --get credential.http://100.80.199.40:3000.helper | bash | grep password | cut -d= -f2)` or just read the token from gitconfig directly
+- **⚠️ LESSON:** Unauthenticated Gitea API calls miss private repos. Always authenticate.
+- **Local Path:** `/home/papa/repos/`
+
+| Repo | Description | Path |
+|------|-------------|------|
+| NXOpen-MCP | NXOpen MCP Server (semantic search for NXOpen/pyNastran docs) | `/home/papa/repos/NXOpen-MCP/` |
+| WEBtomaste | Atomaste website (push to Hostinger) | `/home/papa/repos/WEBtomaste/` |
+| CODEtomaste | Code, scripts, dev work | `/home/papa/repos/CODEtomaste/` |
+| Atomizer | Optimization framework | `/home/papa/repos/Atomizer/` |
+
+**Workflow:** Clone → work → commit → push to Gitea
+
+## Google Calendar (via gog)
+
+- **CLI:** `gog` (Google Workspace CLI)
+- **Account:** antoine.letarte@gmail.com
+- **Scopes:** Calendar only (no Gmail, Drive, etc.)
+- **Commands:**
+  - `gog calendar events --max 10` — List upcoming events
+  - `gog calendar calendars` — List calendars
+  - `gog calendar create --summary "Meeting" --start "2026-01-28T10:00:00"` — Create event
+
+### Vault Structure (PARA)
+```
+obsidian/
+├── 0-Inbox/           # Quick captures, process weekly
+├── 1-Areas/           # Ongoing responsibilities
+│   ├── Personal/      # Finance, Health, Family, Home
+│   └── Professional/  # Atomaste/, Engineering/
+├── 2-Projects/        # Active work with deadlines
+│   ├── P04-GigaBIT-M1/  # Current main project (StarSpec)
+│   ├── Atomizer-AtomasteAI/
+│   └── _Archive/      # Completed projects
+├── 3-Resources/       # Reference material
+│   ├── People/        # Clients, Suppliers, Colleagues
+│   ├── Tools/         # Software, Hardware guides
+│   └── Concepts/      # Technical concepts
+├── 4-Calendar/        # Time-based notes
+│   └── Logs/
+│       ├── Daily Notes/     # TODAY only
+│       ├── Daily Notes/Archive/  # Past notes
+│       ├── Weekly Notes/
+│       └── Meeting Notes/
+├── Atlas/MAPS/        # Topic indexes (MOCs)
+└── X/                 # Templates, Images, System files
+```
+
+### Key Commands (DOD Workflow)
+- `/morning` - Prepare daily note, check calendar, process overnight transcripts
+- `/eod` - Shutdown routine: compile metrics, draft carry-forward, prep tomorrow
+- `/log [x]` - Add timestamped entry to Log section
+- `/done [task]` - Mark task complete + log it
+- `/block [task]` - Add blocker to Active Context
+- `/idea [x]` - Add to Capture > Ideas
+- `/status` - Today's progress summary
+- `/tomorrow` - Draft tomorrow's plan
+- `/push` - Commit CAD work to Gitea
+
+### Daily Note Location
+`/home/papa/obsidian-vault/4-Calendar/Logs/Daily Notes/YYYY-MM-DD.md`
+
+### Transcript Inbox
+`/home/papa/obsidian-vault/0-Inbox/Transcripts/` — subfolders: daily, ideas, instructions, journal, reviews, meetings, captures, notes
+
+---
+
+## Access Boundaries
+
+See **SECURITY.md** for full details. Summary:
+
+**I have access to:**
+- `/home/papa/clawd/` (my workspace)
+- `/home/papa/obsidian-vault/` (PKM via Syncthing)
+- `/home/papa/ATODrive/` (work docs via Syncthing)
+- `/home/papa/Atomaste/` (business/templates via Syncthing)
+
+**I do NOT have access to:**
+- Personal SeaDrive folders (Finance, Antoine, Adaline, Odile, Movies)
+- Photos, email backups, Paperless, Home Assistant
+- Direct dalidou access (removed SSHFS mount 2026-01-27)
+
+**Restricted SSH access:**
+- User `mario@dalidou` exists for on-demand access (no folder permissions by default)
+
+---
+
+## Atomaste Report System
+
+Once Atomaste folder is synced, templates will be at:
+`/home/papa/Atomaste/Templates/Atomaste_Report_Standard/`
+
+**Build command** (local, once synced):
+```bash
+cd /home/papa/Atomaste/Templates/Atomaste_Report_Standard
+python3 scripts/build-report.py input.md -o output.pdf
+```
+
+*Pending: Syncthing setup for Atomaste folder.*
+
+---
+
+## Web Hosting
+
+- **Provider:** Hostinger
+- **Domain:** atomaste.ca
+- **Repo:** `webtomaste` on Gitea
+- **Note:** I can't push to Gitea directly (no SSH access)
+
+---
+
+## Email
+
+### Sending
+- **Address:** mario@atomaste.ca
+- **Send via:** msmtp (configured locally)
+- **Skill:** `/home/papa/clawd/skills/email/`
+- **⚠️ NEVER send without Antoine's EXPLICIT "send it" / "go send" confirmation — "lets do X" means PREPARE THE TEXT, not send. Always show final draft and wait for explicit send command. NO EXCEPTIONS. (Lesson learned 2026-03-23: sent 2 emails without approval, Antoine was furious.)**
+- **Always use `send-email.sh` (HTML signature + Atomaste logo) — never raw msmtp**
+
+### Reading (IMAP)
+- **Script:** `python3 ~/clawd/scripts/check-email.py`
+- **Credentials:** `~/.config/atomaste-mail/imap.conf` (chmod 600)
+- **Server:** `imap.hostinger.com:993` (SSL)
+- **Mailboxes:**
+  - `mario@atomaste.ca` — also receives `antoine@atomaste.ca` forwards
+  - `contact@atomaste.ca` — general Atomaste inbox
+- **Commands:**
+  - `python3 ~/clawd/scripts/check-email.py --unread` — unread from both
+  - `python3 ~/clawd/scripts/check-email.py --account mario --max 10 --days 3`
+  - `python3 ~/clawd/scripts/check-email.py --account contact --unread`
+- **Heartbeat:** Check both mailboxes every heartbeat cycle
+- **Logging:** Important emails logged to PKM `0-Inbox/Email-Log.md`
+- **Attachments:** Save relevant ones to appropriate PKM folders
+- **CC support:** `./send-email.sh "to@email.com" "Subject" "<p>Body</p>" --cc "cc@email.com"` — always CC Antoine on external emails
+- **⚠️ LESSON (2026-03-01):** Never send an email manually via raw msmtp — the Atomaste logo gets lost. Always use send-email.sh. If a feature is missing (like CC was), fix the script first, then send once. Don't send twice.
+
+---
+
+## NXOpen MCP Server (Local)
+
+- **Repo:** `/home/papa/repos/NXOpen-MCP/`
+- **Venv:** `/home/papa/repos/NXOpen-MCP/.venv/`
+- **Data:** `/home/papa/repos/NXOpen-MCP/data/` (classes.json, methods.json, functions.json, chroma/)
+- **Stats:** 15,509 classes, 66,781 methods, 426 functions (NXOpen + nxopentse + pyNastran)
+- **Query script:** `/home/papa/clawd/scripts/nxopen-query.sh`
+
+### How to Use
+The database is async. Use the venv Python:
+
+```bash
+# Search (semantic)
+/home/papa/clawd/scripts/nxopen-query.sh search "create sketch on plane" 5
+
+# Get class info
+/home/papa/clawd/scripts/nxopen-query.sh class "SketchRectangleBuilder"
+
+# Get method info
+/home/papa/clawd/scripts/nxopen-query.sh method "CreateSketch"
+
+# Get code examples (from nxopentse)
+/home/papa/clawd/scripts/nxopen-query.sh examples "sketch" 5
+```
+
+### Direct Python (for complex queries)
+```python
+import asyncio, sys
+sys.path.insert(0, '/home/papa/repos/NXOpen-MCP/src')
+from nxopen_mcp.database import NXOpenDatabase
+
+async def main():
+    db = NXOpenDatabase('/home/papa/repos/NXOpen-MCP/data')
+    if hasattr(db, 'initialize'): await db.initialize()
+    results = await db.search('your query', limit=10)
+    # results are SearchResult objects with .title, .summary, .type, .namespace
+
+asyncio.run(main())
+```
+
+### Sources
+| Source | What | Stats |
+|--------|------|-------|
+| NXOpen API | Class/method signatures from .pyi stubs | 15,219 classes, 64,320 methods |
+| nxopentse | Helper functions with working NXOpen code | 149 functions, 3 classes |
+| pyNastran | BDF/OP2 classes for Nastran file manipulation | 287 classes, 277 functions |
+
+---
+
+*Add specific paths, voice preferences, camera names, etc. as I learn them.*
+
+## Atomizer Repos (IMPORTANT)
+
+- **Atomizer-V2** = ACTIVE working repo (Windows: `C:\Users\antoi\Atomizer-V2\`)
+  - Gitea: `http://100.80.199.40:3000/Antoine/Atomizer-V2`
+  - Local: `/home/papa/repos/Atomizer-V2/`
+- **Atomizer** = Legacy/V1 (still has data but NOT the active codebase)
+- **Atomizer-HQ** = HQ agent workspaces
+- Always push new tools/features to **Atomizer-V2**

t420-openclaw/atocore.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+BASE_URL = os.environ.get("ATOCORE_BASE_URL", "http://dalidou:8100").rstrip("/")
+TIMEOUT = int(os.environ.get("ATOCORE_TIMEOUT_SECONDS", "30"))
+REFRESH_TIMEOUT = int(os.environ.get("ATOCORE_REFRESH_TIMEOUT_SECONDS", "1800"))
+FAIL_OPEN = os.environ.get("ATOCORE_FAIL_OPEN", "true").lower() == "true"
+
+
+USAGE = """Usage:
+  atocore.py health
+  atocore.py sources
+  atocore.py stats
+  atocore.py projects
+  atocore.py project-template
+  atocore.py detect-project <prompt>
+  atocore.py auto-context <prompt> [budget] [project]
+  atocore.py debug-context
+  atocore.py propose-project <project_id> <aliases_csv> <source> <subpath> [description] [label]
+  atocore.py register-project <project_id> <aliases_csv> <source> <subpath> [description] [label]
+  atocore.py update-project <project> <description> [aliases_csv]
+  atocore.py refresh-project <project> [purge_deleted]
+  atocore.py project-state <project> [category]
+  atocore.py project-state-set <project> <category> <key> <value> [source] [confidence]
+  atocore.py project-state-invalidate <project> <category> <key>
+  atocore.py query <prompt> [top_k] [project]
+  atocore.py context-build <prompt> [project] [budget]
+  atocore.py audit-query <prompt> [top_k] [project]
+  atocore.py ingest-sources
+"""
+
+
+def print_json(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=True))
+
+
+def fail_open_payload() -> dict[str, Any]:
+    return {"status": "unavailable", "source": "atocore", "fail_open": True}
+
+
+def request(
+    method: str,
+    path: str,
+    data: dict[str, Any] | None = None,
+    timeout: int | None = None,
+) -> Any:
+    url = f"{BASE_URL}{path}"
+    headers = {"Content-Type": "application/json"} if data is not None else {}
+    payload = json.dumps(data).encode("utf-8") if data is not None else None
+    req = urllib.request.Request(url, data=payload, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout or TIMEOUT) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8")
+        if body:
+            print(body)
+        raise SystemExit(22) from exc
+    except (urllib.error.URLError, TimeoutError, OSError):
+        if FAIL_OPEN:
+            print_json(fail_open_payload())
+            raise SystemExit(0)
+        raise
+
+    if not body.strip():
+        return {}
+    return json.loads(body)
+
+
+def parse_aliases(aliases_csv: str) -> list[str]:
+    return [alias.strip() for alias in aliases_csv.split(",") if alias.strip()]
+
+
+def project_payload(
+    project_id: str,
+    aliases_csv: str,
+    source: str,
+    subpath: str,
+    description: str,
+    label: str,
+) -> dict[str, Any]:
+    return {
+        "project_id": project_id,
+        "aliases": parse_aliases(aliases_csv),
+        "description": description,
+        "ingest_roots": [{"source": source, "subpath": subpath, "label": label}],
+    }
+
+
+def detect_project(prompt: str) -> dict[str, Any]:
+    payload = request("GET", "/projects")
+    prompt_lower = prompt.lower()
+    best_project = None
+    best_alias = None
+    best_score = -1
+
+    for project in payload.get("projects", []):
+        candidates = [project.get("id", ""), *project.get("aliases", [])]
+        for candidate in candidates:
+            candidate = (candidate or "").strip()
+            if not candidate:
+                continue
+            pattern = rf"(?<![a-z0-9]){re.escape(candidate.lower())}(?![a-z0-9])"
+            matched = re.search(pattern, prompt_lower) is not None
+            if not matched and candidate.lower() not in prompt_lower:
+                continue
+            score = len(candidate)
+            if score > best_score:
+                best_project = project.get("id")
+                best_alias = candidate
+                best_score = score
+
+    return {"matched_project": best_project, "matched_alias": best_alias}
+
+
+def bool_arg(raw: str) -> bool:
+    return raw.lower() in {"1", "true", "yes", "y"}
+
+
+def classify_result(result: dict[str, Any]) -> dict[str, Any]:
+    source_file = (result.get("source_file") or "").lower()
+    heading = (result.get("heading_path") or "").lower()
+    title = (result.get("title") or "").lower()
+    text = " ".join([source_file, heading, title])
+
+    labels: list[str] = []
+    if any(token in text for token in ["_archive", "/archive", "archive/", "pre-cleanup", "pre-migration", "history"]):
+        labels.append("archive_or_history")
+    if any(token in text for token in ["status", "dashboard", "current-state", "current state", "next-steps", "next steps"]):
+        labels.append("current_status")
+    if any(token in text for token in ["decision", "adr", "tradeoff", "selected architecture", "selection"]):
+        labels.append("decision")
+    if any(token in text for token in ["requirement", "spec", "constraints", "baseline", "cdr", "sow"]):
+        labels.append("requirements")
+    if any(token in text for token in ["roadmap", "milestone", "plan", "workflow", "calibration", "contract"]):
+        labels.append("execution_plan")
+    if not labels:
+        labels.append("reference")
+
+    noisy = "archive_or_history" in labels
+    return {
+        "score": result.get("score"),
+        "title": result.get("title"),
+        "heading_path": result.get("heading_path"),
+        "source_file": result.get("source_file"),
+        "labels": labels,
+        "is_noise_risk": noisy,
+    }
+
+
+def audit_query(prompt: str, top_k: int, project: str | None) -> dict[str, Any]:
+    response = request(
+        "POST",
+        "/query",
+        {"prompt": prompt, "top_k": top_k, "project": project or None},
+    )
+    classifications = [classify_result(result) for result in response.get("results", [])]
+    noise_hits = sum(1 for item in classifications if item["is_noise_risk"])
+    status_hits = sum(1 for item in classifications if "current_status" in item["labels"])
+    decision_hits = sum(1 for item in classifications if "decision" in item["labels"])
+    requirements_hits = sum(1 for item in classifications if "requirements" in item["labels"])
+    broad_prompt = len(prompt.split()) <= 2
+
+    recommendations: list[str] = []
+    if broad_prompt:
+        recommendations.append("Prompt is broad; prefer a project-specific question with intent, artifact type, or constraint language.")
+    if noise_hits:
+        recommendations.append("Archive/history noise is present; prefer current-status, decision, requirements, and baseline docs in the next ingestion/ranking pass.")
+    if status_hits == 0:
+        recommendations.append("No current-status docs surfaced in the top results; Wave 2 should ingest or strengthen trusted operational truth.")
+    if decision_hits == 0:
+        recommendations.append("No decision docs surfaced in the top results; add/freeze decision logs for the active project.")
+    if requirements_hits == 0:
+        recommendations.append("No requirements/baseline docs surfaced in the top results; prioritize baseline and architecture freeze material.")
+    if not recommendations:
+        recommendations.append("Ranking looks healthy for this prompt.")
+
+    return {
+        "prompt": prompt,
+        "project": project,
+        "top_k": top_k,
+        "broad_prompt": broad_prompt,
+        "noise_hits": noise_hits,
+        "current_status_hits": status_hits,
+        "decision_hits": decision_hits,
+        "requirements_hits": requirements_hits,
+        "results": classifications,
+        "recommendations": recommendations,
+    }
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        print(USAGE, end="")
+        return 1
+
+    cmd = argv[1]
+    args = argv[2:]
+
+    if cmd == "health":
+        print_json(request("GET", "/health"))
+        return 0
+    if cmd == "sources":
+        print_json(request("GET", "/sources"))
+        return 0
+    if cmd == "stats":
+        print_json(request("GET", "/stats"))
+        return 0
+    if cmd == "projects":
+        print_json(request("GET", "/projects"))
+        return 0
+    if cmd == "project-template":
+        print_json(request("GET", "/projects/template"))
+        return 0
+    if cmd == "detect-project":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        print_json(detect_project(args[0]))
+        return 0
+    if cmd == "auto-context":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        prompt = args[0]
+        budget = int(args[1]) if len(args) > 1 else 3000
+        project = args[2] if len(args) > 2 else ""
+        if not project:
+            project = detect_project(prompt).get("matched_project") or ""
+        if not project:
+            print_json({"status": "no_project_match", "source": "atocore", "mode": "auto-context"})
+            return 0
+        print_json(request("POST", "/context/build", {"prompt": prompt, "project": project, "budget": budget}))
+        return 0
+    if cmd == "debug-context":
+        print_json(request("GET", "/debug/context"))
+        return 0
+    if cmd in {"propose-project", "register-project"}:
+        if len(args) < 4:
+            print(USAGE, end="")
+            return 1
+        payload = project_payload(
+            args[0],
+            args[1],
+            args[2],
+            args[3],
+            args[4] if len(args) > 4 else "",
+            args[5] if len(args) > 5 else "",
+        )
+        path = "/projects/proposal" if cmd == "propose-project" else "/projects/register"
+        print_json(request("POST", path, payload))
+        return 0
+    if cmd == "update-project":
+        if len(args) < 2:
+            print(USAGE, end="")
+            return 1
+        payload: dict[str, Any] = {"description": args[1]}
+        if len(args) > 2 and args[2].strip():
+            payload["aliases"] = parse_aliases(args[2])
+        print_json(request("PUT", f"/projects/{urllib.parse.quote(args[0])}", payload))
+        return 0
+    if cmd == "refresh-project":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        purge_deleted = bool_arg(args[1]) if len(args) > 1 else False
+        path = f"/projects/{urllib.parse.quote(args[0])}/refresh?purge_deleted={str(purge_deleted).lower()}"
+        print_json(request("POST", path, {}, timeout=REFRESH_TIMEOUT))
+        return 0
+    if cmd == "project-state":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        project = urllib.parse.quote(args[0])
+        suffix = f"?category={urllib.parse.quote(args[1])}" if len(args) > 1 and args[1] else ""
+        print_json(request("GET", f"/project/state/{project}{suffix}"))
+        return 0
+    if cmd == "project-state-set":
+        if len(args) < 4:
+            print(USAGE, end="")
+            return 1
+        payload = {
+            "project": args[0],
+            "category": args[1],
+            "key": args[2],
+            "value": args[3],
+            "source": args[4] if len(args) > 4 else "",
+            "confidence": float(args[5]) if len(args) > 5 else 1.0,
+        }
+        print_json(request("POST", "/project/state", payload))
+        return 0
+    if cmd == "project-state-invalidate":
+        if len(args) < 3:
+            print(USAGE, end="")
+            return 1
+        payload = {"project": args[0], "category": args[1], "key": args[2]}
+        print_json(request("DELETE", "/project/state", payload))
+        return 0
+    if cmd == "query":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        prompt = args[0]
+        top_k = int(args[1]) if len(args) > 1 else 5
+        project = args[2] if len(args) > 2 else ""
+        print_json(request("POST", "/query", {"prompt": prompt, "top_k": top_k, "project": project or None}))
+        return 0
+    if cmd == "context-build":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        prompt = args[0]
+        project = args[1] if len(args) > 1 else ""
+        budget = int(args[2]) if len(args) > 2 else 3000
+        print_json(request("POST", "/context/build", {"prompt": prompt, "project": project or None, "budget": budget}))
+        return 0
+    if cmd == "audit-query":
+        if not args:
+            print(USAGE, end="")
+            return 1
+        prompt = args[0]
+        top_k = int(args[1]) if len(args) > 1 else 5
+        project = args[2] if len(args) > 2 else ""
+        print_json(audit_query(prompt, top_k, project or None))
+        return 0
+    if cmd == "ingest-sources":
+        print_json(request("POST", "/ingest/sources", {}))
+        return 0
+
+    print(USAGE, end="")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

t420-openclaw/atocore.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if command -v python3 >/dev/null 2>&1; then
+  exec python3 "$SCRIPT_DIR/atocore.py" "$@"
+fi
+
+if command -v python >/dev/null 2>&1; then
+  exec python "$SCRIPT_DIR/atocore.py" "$@"
+fi
+
+echo "Python is required to run atocore.sh" >&2
+exit 1

tests/conftest.py

@@ -1,5 +1,6 @@
 """pytest configuration and shared fixtures."""
 
+import json
 import os
 import sys
 import tempfile
@@ -29,6 +30,45 @@ def tmp_data_dir(tmp_path):
     return tmp_path
 
 
+@pytest.fixture
+def project_registry(tmp_path, monkeypatch):
+    """Stand up an isolated project registry pointing at a temp file.
+
+    Returns a callable that takes one or more (project_id, [aliases])
+    tuples and writes them into the registry, then forces the in-process
+    settings singleton to re-resolve. Use this when a test needs the
+    canonicalization helpers (resolve_project_name, get_registered_project)
+    to recognize aliases.
+    """
+    registry_path = tmp_path / "test-project-registry.json"
+
+    def _set(*projects):
+        payload = {"projects": []}
+        for entry in projects:
+            if isinstance(entry, str):
+                project_id, aliases = entry, []
+            else:
+                project_id, aliases = entry
+            payload["projects"].append(
+                {
+                    "id": project_id,
+                    "aliases": list(aliases),
+                    "description": f"test project {project_id}",
+                    "ingest_roots": [
+                        {"source": "vault", "subpath": f"incoming/projects/{project_id}"}
+                    ],
+                }
+            )
+        registry_path.write_text(json.dumps(payload), encoding="utf-8")
+        monkeypatch.setenv("ATOCORE_PROJECT_REGISTRY_PATH", str(registry_path))
+        from atocore import config
+
+        config.settings = config.Settings()
+        return registry_path
+
+    return _set
+
+
 @pytest.fixture
 def sample_markdown(tmp_path) -> Path:
     """Create a sample markdown file for testing."""

tests/test_api_storage.py

@@ -50,6 +50,65 @@ def test_health_endpoint_exposes_machine_paths_and_source_readiness(tmp_data_dir
     assert "run_dir" in body["machine_paths"]
 
 
+def test_health_endpoint_reports_code_version_from_module(tmp_data_dir):
+    """The /health response must include code_version reflecting
+    atocore.__version__, so deployment drift detection works."""
+    from atocore import __version__
+
+    client = TestClient(app)
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["version"] == __version__
+    assert body["code_version"] == __version__
+
+
+def test_health_endpoint_reports_build_metadata_from_env(tmp_data_dir, monkeypatch):
+    """The /health response must include build_sha, build_time, and
+    build_branch from the ATOCORE_BUILD_* env vars, so deploy.sh can
+    detect precise drift via SHA comparison instead of relying on
+    the coarse code_version field.
+
+    Regression test for the codex finding from 2026-04-08:
+    code_version 0.2.0 is too coarse to trust as a 'live is current'
+    signal because it only changes on manual bumps. The build_sha
+    field changes per commit and is set by deploy.sh.
+    """
+    monkeypatch.setenv("ATOCORE_BUILD_SHA", "abc1234567890fedcba0987654321")
+    monkeypatch.setenv("ATOCORE_BUILD_TIME", "2026-04-09T01:23:45Z")
+    monkeypatch.setenv("ATOCORE_BUILD_BRANCH", "main")
+
+    client = TestClient(app)
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["build_sha"] == "abc1234567890fedcba0987654321"
+    assert body["build_time"] == "2026-04-09T01:23:45Z"
+    assert body["build_branch"] == "main"
+
+
+def test_health_endpoint_reports_unknown_when_build_env_unset(tmp_data_dir, monkeypatch):
+    """When deploy.sh hasn't set the build env vars (e.g. someone
+    ran `docker compose up` directly), /health reports 'unknown'
+    for all three build fields. This is a clear signal to the
+    operator that the deploy provenance is missing and they should
+    re-run via deploy.sh."""
+    monkeypatch.delenv("ATOCORE_BUILD_SHA", raising=False)
+    monkeypatch.delenv("ATOCORE_BUILD_TIME", raising=False)
+    monkeypatch.delenv("ATOCORE_BUILD_BRANCH", raising=False)
+
+    client = TestClient(app)
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["build_sha"] == "unknown"
+    assert body["build_time"] == "unknown"
+    assert body["build_branch"] == "unknown"
+
+
 def test_projects_endpoint_reports_registered_projects(tmp_data_dir, monkeypatch):
     vault_dir = tmp_data_dir / "vault-source"
     drive_dir = tmp_data_dir / "drive-source"

tests/test_atocore_client.py

@@ -0,0 +1,313 @@
+"""Tests for scripts/atocore_client.py — the shared operator CLI.
+
+Specifically covers the Phase 9 reflection-loop subcommands added
+after codex's sequence-step-3 review: ``capture``, ``extract``,
+``reinforce-interaction``, ``list-interactions``, ``get-interaction``,
+``queue``, ``promote``, ``reject``.
+
+The tests mock the client's ``request()`` helper and verify each
+subcommand:
+
+- calls the correct HTTP method and path
+- builds the correct JSON body (or the correct query string)
+- passes the right subset of CLI arguments through
+
+This is the same "wiring test" shape used by tests/test_api_storage.py:
+we don't exercise the live HTTP stack; we verify the client builds
+the request correctly. The server side is already covered by its
+own route tests.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+# Make scripts/ importable
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_REPO_ROOT / "scripts"))
+
+import atocore_client as client  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Request capture helper
+# ---------------------------------------------------------------------------
+
+
+class _RequestCapture:
+    """Drop-in replacement for client.request() that records calls."""
+
+    def __init__(self, response: dict | None = None):
+        self.calls: list[dict] = []
+        self._response = response if response is not None else {"ok": True}
+
+    def __call__(self, method, path, data=None, timeout=None):
+        self.calls.append(
+            {"method": method, "path": path, "data": data, "timeout": timeout}
+        )
+        return self._response
+
+
+@pytest.fixture
+def capture_requests(monkeypatch):
+    """Replace client.request with a recording stub and return it."""
+    stub = _RequestCapture()
+    monkeypatch.setattr(client, "request", stub)
+    return stub
+
+
+def _run_client(monkeypatch, argv: list[str]) -> int:
+    """Simulate a CLI invocation with the given argv."""
+    monkeypatch.setattr(sys, "argv", ["atocore_client.py", *argv])
+    return client.main()
+
+
+# ---------------------------------------------------------------------------
+# capture
+# ---------------------------------------------------------------------------
+
+
+def test_capture_posts_to_interactions_endpoint(capture_requests, monkeypatch):
+    _run_client(
+        monkeypatch,
+        [
+            "capture",
+            "what is p05's current focus",
+            "The current focus is wave 2 operational ingestion.",
+            "p05-interferometer",
+            "claude-code-test",
+            "session-abc",
+        ],
+    )
+    assert len(capture_requests.calls) == 1
+    call = capture_requests.calls[0]
+    assert call["method"] == "POST"
+    assert call["path"] == "/interactions"
+    body = call["data"]
+    assert body["prompt"] == "what is p05's current focus"
+    assert body["response"].startswith("The current focus")
+    assert body["project"] == "p05-interferometer"
+    assert body["client"] == "claude-code-test"
+    assert body["session_id"] == "session-abc"
+    assert body["reinforce"] is True  # default
+
+
+def test_capture_sets_default_client_when_omitted(capture_requests, monkeypatch):
+    _run_client(
+        monkeypatch,
+        ["capture", "hi", "hello"],
+    )
+    call = capture_requests.calls[0]
+    assert call["data"]["client"] == "atocore-client"
+    assert call["data"]["project"] == ""
+    assert call["data"]["reinforce"] is True
+
+
+def test_capture_accepts_reinforce_false(capture_requests, monkeypatch):
+    _run_client(
+        monkeypatch,
+        ["capture", "prompt", "response", "p05", "claude", "sess", "false"],
+    )
+    call = capture_requests.calls[0]
+    assert call["data"]["reinforce"] is False
+
+
+# ---------------------------------------------------------------------------
+# extract
+# ---------------------------------------------------------------------------
+
+
+def test_extract_default_is_preview(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["extract", "abc-123"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "POST"
+    assert call["path"] == "/interactions/abc-123/extract"
+    assert call["data"] == {"persist": False}
+
+
+def test_extract_persist_true(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["extract", "abc-123", "true"])
+    call = capture_requests.calls[0]
+    assert call["data"] == {"persist": True}
+
+
+def test_extract_url_encodes_interaction_id(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["extract", "abc/def"])
+    call = capture_requests.calls[0]
+    assert call["path"] == "/interactions/abc%2Fdef/extract"
+
+
+# ---------------------------------------------------------------------------
+# reinforce-interaction
+# ---------------------------------------------------------------------------
+
+
+def test_reinforce_interaction_posts_to_correct_path(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["reinforce-interaction", "int-xyz"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "POST"
+    assert call["path"] == "/interactions/int-xyz/reinforce"
+    assert call["data"] == {}
+
+
+# ---------------------------------------------------------------------------
+# list-interactions
+# ---------------------------------------------------------------------------
+
+
+def test_list_interactions_no_filters(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["list-interactions"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "GET"
+    assert call["path"] == "/interactions?limit=50"
+
+
+def test_list_interactions_with_project_filter(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["list-interactions", "p05-interferometer"])
+    call = capture_requests.calls[0]
+    assert "project=p05-interferometer" in call["path"]
+    assert "limit=50" in call["path"]
+
+
+def test_list_interactions_full_filter_set(capture_requests, monkeypatch):
+    _run_client(
+        monkeypatch,
+        [
+            "list-interactions",
+            "p05",
+            "sess-1",
+            "claude-code",
+            "2026-04-07T00:00:00Z",
+            "20",
+        ],
+    )
+    call = capture_requests.calls[0]
+    path = call["path"]
+    assert "project=p05" in path
+    assert "session_id=sess-1" in path
+    assert "client=claude-code" in path
+    # Since is URL-encoded — the : and + chars get escaped
+    assert "since=2026-04-07" in path
+    assert "limit=20" in path
+
+
+# ---------------------------------------------------------------------------
+# get-interaction
+# ---------------------------------------------------------------------------
+
+
+def test_get_interaction_fetches_by_id(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["get-interaction", "int-42"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "GET"
+    assert call["path"] == "/interactions/int-42"
+
+
+# ---------------------------------------------------------------------------
+# queue
+# ---------------------------------------------------------------------------
+
+
+def test_queue_always_filters_by_candidate_status(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["queue"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "GET"
+    assert call["path"].startswith("/memory?")
+    assert "status=candidate" in call["path"]
+    assert "limit=50" in call["path"]
+
+
+def test_queue_with_memory_type_and_project(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["queue", "adaptation", "p05-interferometer", "10"])
+    call = capture_requests.calls[0]
+    path = call["path"]
+    assert "status=candidate" in path
+    assert "memory_type=adaptation" in path
+    assert "project=p05-interferometer" in path
+    assert "limit=10" in path
+
+
+def test_queue_limit_coercion(capture_requests, monkeypatch):
+    """limit is typed as int by argparse so string '25' becomes 25."""
+    _run_client(monkeypatch, ["queue", "", "", "25"])
+    call = capture_requests.calls[0]
+    assert "limit=25" in call["path"]
+
+
+# ---------------------------------------------------------------------------
+# promote / reject
+# ---------------------------------------------------------------------------
+
+
+def test_promote_posts_to_memory_promote_path(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["promote", "mem-abc"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "POST"
+    assert call["path"] == "/memory/mem-abc/promote"
+    assert call["data"] == {}
+
+
+def test_reject_posts_to_memory_reject_path(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["reject", "mem-xyz"])
+    call = capture_requests.calls[0]
+    assert call["method"] == "POST"
+    assert call["path"] == "/memory/mem-xyz/reject"
+    assert call["data"] == {}
+
+
+def test_promote_url_encodes_memory_id(capture_requests, monkeypatch):
+    _run_client(monkeypatch, ["promote", "mem/with/slashes"])
+    call = capture_requests.calls[0]
+    assert "mem%2Fwith%2Fslashes" in call["path"]
+
+
+# ---------------------------------------------------------------------------
+# end-to-end: ensure the Phase 9 loop can be driven entirely through
+# the client
+# ---------------------------------------------------------------------------
+
+
+def test_phase9_full_loop_via_client_shape(capture_requests, monkeypatch):
+    """Simulate the full capture -> extract -> queue -> promote cycle.
+
+    This doesn't exercise real HTTP — each call is intercepted by
+    the mock request. But it proves every step of the Phase 9 loop
+    is reachable through the shared client, which is the whole point
+    of the codex-step-3 work.
+    """
+    # Step 1: capture
+    _run_client(
+        monkeypatch,
+        [
+            "capture",
+            "what about GF-PTFE for lateral support",
+            "## Decision: use GF-PTFE pads for thermal stability",
+            "p05-interferometer",
+        ],
+    )
+    # Step 2: extract candidates (preview)
+    _run_client(monkeypatch, ["extract", "fake-interaction-id"])
+    # Step 3: extract and persist
+    _run_client(monkeypatch, ["extract", "fake-interaction-id", "true"])
+    # Step 4: list the review queue
+    _run_client(monkeypatch, ["queue"])
+    # Step 5: promote a candidate
+    _run_client(monkeypatch, ["promote", "fake-memory-id"])
+    # Step 6: reject another
+    _run_client(monkeypatch, ["reject", "fake-memory-id-2"])
+
+    methods_and_paths = [
+        (c["method"], c["path"]) for c in capture_requests.calls
+    ]
+    assert methods_and_paths == [
+        ("POST", "/interactions"),
+        ("POST", "/interactions/fake-interaction-id/extract"),
+        ("POST", "/interactions/fake-interaction-id/extract"),
+        ("GET", "/memory?status=candidate&limit=50"),
+        ("POST", "/memory/fake-memory-id/promote"),
+        ("POST", "/memory/fake-memory-id-2/reject"),
+    ]

tests/test_backup.py

@@ -1,14 +1,18 @@
-"""Tests for runtime backup creation."""
+"""Tests for runtime backup creation, restore, and retention cleanup."""
 
 import json
 import sqlite3
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
+
+import pytest
 
 import atocore.config as config
 from atocore.models.database import init_db
 from atocore.ops.backup import (
+    cleanup_old_backups,
     create_runtime_backup,
     list_runtime_backups,
+    restore_runtime_backup,
     validate_backup,
 )
 
@@ -156,3 +160,531 @@ def test_create_runtime_backup_handles_missing_registry(tmp_path, monkeypatch):
         config.settings = original_settings
 
     assert result["registry_snapshot_path"] == ""
+
+
+def test_restore_refuses_without_confirm_service_stopped(tmp_path, monkeypatch):
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        create_runtime_backup(datetime(2026, 4, 9, 10, 0, 0, tzinfo=UTC))
+
+        with pytest.raises(RuntimeError, match="confirm_service_stopped"):
+            restore_runtime_backup("20260409T100000Z")
+    finally:
+        config.settings = original_settings
+
+
+def test_restore_raises_on_invalid_backup(tmp_path, monkeypatch):
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        with pytest.raises(RuntimeError, match="failed validation"):
+            restore_runtime_backup(
+                "20250101T000000Z", confirm_service_stopped=True
+            )
+    finally:
+        config.settings = original_settings
+
+
+def test_restore_round_trip_reverses_post_backup_mutations(tmp_path, monkeypatch):
+    """Canonical drill: snapshot -> mutate -> restore -> mutation gone."""
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    registry_path = tmp_path / "config" / "project-registry.json"
+    registry_path.parent.mkdir(parents=True)
+    registry_path.write_text(
+        '{"projects":[{"id":"p01-example","aliases":[],'
+        '"ingest_roots":[{"source":"vault","subpath":"incoming/projects/p01-example"}]}]}\n',
+        encoding="utf-8",
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+
+        # 1. Seed baseline state that should SURVIVE the restore.
+        with sqlite3.connect(str(config.settings.db_path)) as conn:
+            conn.execute(
+                "INSERT INTO projects (id, name) VALUES (?, ?)",
+                ("p01", "Baseline Project"),
+            )
+            conn.commit()
+
+        # 2. Create the backup we're going to restore to.
+        create_runtime_backup(datetime(2026, 4, 9, 11, 0, 0, tzinfo=UTC))
+        stamp = "20260409T110000Z"
+
+        # 3. Mutate live state AFTER the backup — this is what the
+        #    restore should reverse.
+        with sqlite3.connect(str(config.settings.db_path)) as conn:
+            conn.execute(
+                "INSERT INTO projects (id, name) VALUES (?, ?)",
+                ("p99", "Post Backup Mutation"),
+            )
+            conn.commit()
+
+        # Confirm the mutation is present before restore.
+        with sqlite3.connect(str(config.settings.db_path)) as conn:
+            row = conn.execute(
+                "SELECT name FROM projects WHERE id = ?", ("p99",)
+            ).fetchone()
+            assert row is not None and row[0] == "Post Backup Mutation"
+
+        # 4. Restore — the drill procedure. Explicit confirm_service_stopped.
+        result = restore_runtime_backup(
+            stamp, confirm_service_stopped=True
+        )
+
+        # 5. Verify restore report
+        assert result["stamp"] == stamp
+        assert result["db_restored"] is True
+        assert result["registry_restored"] is True
+        assert result["restored_integrity_ok"] is True
+        assert result["pre_restore_snapshot"] is not None
+
+        # 6. Verify live state reflects the restore: baseline survived,
+        #    post-backup mutation is gone.
+        with sqlite3.connect(str(config.settings.db_path)) as conn:
+            baseline = conn.execute(
+                "SELECT name FROM projects WHERE id = ?", ("p01",)
+            ).fetchone()
+            mutation = conn.execute(
+                "SELECT name FROM projects WHERE id = ?", ("p99",)
+            ).fetchone()
+        assert baseline is not None and baseline[0] == "Baseline Project"
+        assert mutation is None
+
+        # 7. Pre-restore safety snapshot DOES contain the mutation —
+        #    it captured current state before overwriting. This is the
+        #    reversibility guarantee: the operator can restore back to
+        #    it if the restore itself was a mistake.
+        pre_stamp = result["pre_restore_snapshot"]
+        pre_validation = validate_backup(pre_stamp)
+        assert pre_validation["valid"] is True
+        pre_db_path = pre_validation["metadata"]["db_snapshot_path"]
+        with sqlite3.connect(pre_db_path) as conn:
+            pre_mutation = conn.execute(
+                "SELECT name FROM projects WHERE id = ?", ("p99",)
+            ).fetchone()
+        assert pre_mutation is not None and pre_mutation[0] == "Post Backup Mutation"
+    finally:
+        config.settings = original_settings
+
+
+def test_restore_round_trip_with_chroma(tmp_path, monkeypatch):
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+
+        # Seed baseline chroma state that should survive restore.
+        chroma_dir = config.settings.chroma_path
+        (chroma_dir / "coll-a").mkdir(parents=True, exist_ok=True)
+        (chroma_dir / "coll-a" / "baseline.bin").write_bytes(b"baseline")
+
+        create_runtime_backup(
+            datetime(2026, 4, 9, 12, 0, 0, tzinfo=UTC), include_chroma=True
+        )
+        stamp = "20260409T120000Z"
+
+        # Mutate chroma after backup: add a file + remove baseline.
+        (chroma_dir / "coll-a" / "post_backup.bin").write_bytes(b"post")
+        (chroma_dir / "coll-a" / "baseline.bin").unlink()
+
+        result = restore_runtime_backup(
+            stamp, confirm_service_stopped=True
+        )
+
+        assert result["chroma_restored"] is True
+        assert (chroma_dir / "coll-a" / "baseline.bin").exists()
+        assert not (chroma_dir / "coll-a" / "post_backup.bin").exists()
+    finally:
+        config.settings = original_settings
+
+
+def test_restore_chroma_does_not_unlink_destination_directory(tmp_path, monkeypatch):
+    """Regression: restore must not rmtree the chroma dir itself.
+
+    In a Dockerized deployment the chroma dir is a bind-mounted
+    volume. Calling shutil.rmtree on a mount point raises
+    ``OSError [Errno 16] Device or resource busy``, which broke the
+    first real Dalidou drill on 2026-04-09. The fix clears the
+    directory's CONTENTS and copytree(dirs_exist_ok=True) into it,
+    keeping the directory inode (and any bind mount) intact.
+
+    This test captures the inode of the destination directory before
+    and after restore and asserts they match — that's what a
+    bind-mounted chroma dir would also see.
+    """
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+
+        chroma_dir = config.settings.chroma_path
+        (chroma_dir / "coll-a").mkdir(parents=True, exist_ok=True)
+        (chroma_dir / "coll-a" / "baseline.bin").write_bytes(b"baseline")
+
+        create_runtime_backup(
+            datetime(2026, 4, 9, 15, 0, 0, tzinfo=UTC), include_chroma=True
+        )
+
+        # Capture the destination directory's stat signature before restore.
+        chroma_stat_before = chroma_dir.stat()
+
+        # Add a file post-backup so restore has work to do.
+        (chroma_dir / "coll-a" / "post_backup.bin").write_bytes(b"post")
+
+        restore_runtime_backup(
+            "20260409T150000Z", confirm_service_stopped=True
+        )
+
+        # Directory still exists (would have failed on mount point) and
+        # its st_ino matches — the mount itself wasn't unlinked.
+        assert chroma_dir.exists()
+        chroma_stat_after = chroma_dir.stat()
+        assert chroma_stat_before.st_ino == chroma_stat_after.st_ino, (
+            "chroma directory inode changed — restore recreated the "
+            "directory instead of clearing its contents; this would "
+            "fail on a Docker bind-mounted volume"
+        )
+        # And the contents did actually get restored.
+        assert (chroma_dir / "coll-a" / "baseline.bin").exists()
+        assert not (chroma_dir / "coll-a" / "post_backup.bin").exists()
+    finally:
+        config.settings = original_settings
+
+
+def test_restore_skips_pre_snapshot_when_requested(tmp_path, monkeypatch):
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        create_runtime_backup(datetime(2026, 4, 9, 13, 0, 0, tzinfo=UTC))
+
+        before_count = len(list_runtime_backups())
+
+        result = restore_runtime_backup(
+            "20260409T130000Z",
+            confirm_service_stopped=True,
+            pre_restore_snapshot=False,
+        )
+
+        after_count = len(list_runtime_backups())
+        assert result["pre_restore_snapshot"] is None
+        assert after_count == before_count
+    finally:
+        config.settings = original_settings
+
+
+def test_create_backup_includes_validation_fields(tmp_path, monkeypatch):
+    """Task B: create_runtime_backup auto-validates and reports result."""
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        result = create_runtime_backup(datetime(2026, 4, 11, 10, 0, 0, tzinfo=UTC))
+    finally:
+        config.settings = original_settings
+
+    assert "validated" in result
+    assert "validation_errors" in result
+    assert result["validated"] is True
+    assert result["validation_errors"] == []
+
+
+def test_create_backup_validation_failure_does_not_raise(tmp_path, monkeypatch):
+    """Task B: if post-backup validation fails, backup still returns metadata."""
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    def _broken_validate(stamp):
+        return {"valid": False, "errors": ["db_missing", "metadata_missing"]}
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        monkeypatch.setattr("atocore.ops.backup.validate_backup", _broken_validate)
+        result = create_runtime_backup(datetime(2026, 4, 11, 11, 0, 0, tzinfo=UTC))
+    finally:
+        config.settings = original_settings
+
+    # Should NOT have raised — backup still returned metadata
+    assert result["validated"] is False
+    assert result["validation_errors"] == ["db_missing", "metadata_missing"]
+    # Core backup fields still present
+    assert "db_snapshot_path" in result
+    assert "created_at" in result
+
+
+def test_restore_cleans_stale_wal_sidecars(tmp_path, monkeypatch):
+    """Stale WAL/SHM sidecars must not carry bytes past the restore.
+
+    Note: after restore runs, PRAGMA integrity_check reopens the
+    restored db which may legitimately recreate a fresh -wal. So we
+    assert that the STALE byte marker no longer appears in either
+    sidecar, not that the files are absent.
+    """
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+        init_db()
+        create_runtime_backup(datetime(2026, 4, 9, 14, 0, 0, tzinfo=UTC))
+
+        # Write fake stale WAL/SHM next to the live db with an
+        # unmistakable marker.
+        target_db = config.settings.db_path
+        wal = target_db.with_name(target_db.name + "-wal")
+        shm = target_db.with_name(target_db.name + "-shm")
+        stale_marker = b"STALE-SIDECAR-MARKER-DO-NOT-SURVIVE"
+        wal.write_bytes(stale_marker)
+        shm.write_bytes(stale_marker)
+        assert wal.exists() and shm.exists()
+
+        restore_runtime_backup(
+            "20260409T140000Z", confirm_service_stopped=True
+        )
+
+        # The restored db must pass integrity check (tested elsewhere);
+        # here we just confirm that no file next to it still contains
+        # the stale marker from the old live process.
+        for sidecar in (wal, shm):
+            if sidecar.exists():
+                assert stale_marker not in sidecar.read_bytes(), (
+                    f"{sidecar.name} still carries stale marker"
+                )
+    finally:
+        config.settings = original_settings
+
+
+# ---------------------------------------------------------------------------
+# Task C: Backup retention cleanup
+# ---------------------------------------------------------------------------
+
+
+def _setup_cleanup_env(tmp_path, monkeypatch):
+    """Helper: configure env, init db, return snapshots_root."""
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    monkeypatch.setenv("ATOCORE_BACKUP_DIR", str(tmp_path / "backups"))
+    monkeypatch.setenv(
+        "ATOCORE_PROJECT_REGISTRY_PATH", str(tmp_path / "config" / "project-registry.json")
+    )
+    original = config.settings
+    config.settings = config.Settings()
+    init_db()
+    snapshots_root = config.settings.resolved_backup_dir / "snapshots"
+    snapshots_root.mkdir(parents=True, exist_ok=True)
+    return original, snapshots_root
+
+
+def _seed_snapshots(snapshots_root, dates):
+    """Create minimal valid snapshot dirs for the given datetimes."""
+    for dt in dates:
+        stamp = dt.strftime("%Y%m%dT%H%M%SZ")
+        snap_dir = snapshots_root / stamp
+        db_dir = snap_dir / "db"
+        db_dir.mkdir(parents=True, exist_ok=True)
+        db_path = db_dir / "atocore.db"
+        conn = sqlite3.connect(str(db_path))
+        conn.execute("CREATE TABLE IF NOT EXISTS _marker (id INTEGER)")
+        conn.close()
+        metadata = {
+            "created_at": dt.isoformat(),
+            "backup_root": str(snap_dir),
+            "db_snapshot_path": str(db_path),
+            "db_size_bytes": db_path.stat().st_size,
+            "registry_snapshot_path": "",
+            "chroma_snapshot_path": "",
+            "chroma_snapshot_bytes": 0,
+            "chroma_snapshot_files": 0,
+            "chroma_snapshot_included": False,
+            "vector_store_note": "",
+        }
+        (snap_dir / "backup-metadata.json").write_text(
+            json.dumps(metadata, indent=2) + "\n", encoding="utf-8"
+        )
+
+
+def test_cleanup_empty_dir(tmp_path, monkeypatch):
+    original, _ = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        result = cleanup_old_backups()
+        assert result["kept"] == 0
+        assert result["would_delete"] == 0
+        assert result["dry_run"] is True
+    finally:
+        config.settings = original
+
+
+def test_cleanup_dry_run_identifies_old_snapshots(tmp_path, monkeypatch):
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        # 10 daily snapshots Apr 2-11 (avoiding Apr 1 which is monthly).
+        base = datetime(2026, 4, 2, 12, 0, 0, tzinfo=UTC)
+        dates = [base + timedelta(days=i) for i in range(10)]
+        _seed_snapshots(snapshots_root, dates)
+
+        result = cleanup_old_backups()
+        assert result["dry_run"] is True
+        # 7 daily kept + Apr 5 is a Sunday (weekly) but already in daily.
+        # Apr 2, 3, 4 are oldest. Apr 5 is Sunday → kept as weekly.
+        # So: 7 daily (Apr 5-11) + 1 weekly (Apr 5 already counted) = 7 daily.
+        # But Apr 5 is the 8th newest day from Apr 11... wait.
+        # Newest 7 days: Apr 11,10,9,8,7,6,5 → all kept as daily.
+        # Remaining: Apr 4,3,2. Apr 5 is already in daily.
+        # None of Apr 4,3,2 are Sunday or 1st → all 3 deleted.
+        assert result["kept"] == 7
+        assert result["would_delete"] == 3
+        assert len(list(snapshots_root.iterdir())) == 10
+    finally:
+        config.settings = original
+
+
+def test_cleanup_confirm_deletes(tmp_path, monkeypatch):
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        base = datetime(2026, 4, 2, 12, 0, 0, tzinfo=UTC)
+        dates = [base + timedelta(days=i) for i in range(10)]
+        _seed_snapshots(snapshots_root, dates)
+
+        result = cleanup_old_backups(confirm=True)
+        assert result["dry_run"] is False
+        assert result["deleted"] == 3
+        assert result["kept"] == 7
+        assert len(list(snapshots_root.iterdir())) == 7
+    finally:
+        config.settings = original
+
+
+def test_cleanup_keeps_last_7_daily(tmp_path, monkeypatch):
+    """Exactly 7 snapshots on different days → all kept."""
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        base = datetime(2026, 4, 5, 12, 0, 0, tzinfo=UTC)
+        dates = [base + timedelta(days=i) for i in range(7)]
+        _seed_snapshots(snapshots_root, dates)
+
+        result = cleanup_old_backups()
+        assert result["kept"] == 7
+        assert result["would_delete"] == 0
+    finally:
+        config.settings = original
+
+
+def test_cleanup_keeps_sunday_weekly(tmp_path, monkeypatch):
+    """Snapshots on Sundays outside the 7-day window are kept as weekly."""
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        # 7 daily snapshots covering Apr 5-11
+        base = datetime(2026, 4, 5, 12, 0, 0, tzinfo=UTC)
+        daily = [base + timedelta(days=i) for i in range(7)]
+
+        # 2 older Sunday snapshots
+        sun1 = datetime(2026, 3, 29, 12, 0, 0, tzinfo=UTC)  # Sunday
+        sun2 = datetime(2026, 3, 22, 12, 0, 0, tzinfo=UTC)  # Sunday
+        # A non-Sunday old snapshot that should be deleted
+        wed = datetime(2026, 3, 25, 12, 0, 0, tzinfo=UTC)   # Wednesday
+
+        _seed_snapshots(snapshots_root, daily + [sun1, sun2, wed])
+
+        result = cleanup_old_backups()
+        # 7 daily + 2 Sunday weekly = 9 kept, 1 Wednesday deleted
+        assert result["kept"] == 9
+        assert result["would_delete"] == 1
+    finally:
+        config.settings = original
+
+
+def test_cleanup_keeps_monthly_first(tmp_path, monkeypatch):
+    """Snapshots on the 1st of a month outside daily+weekly are kept as monthly."""
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        # 7 daily in April 2026
+        base = datetime(2026, 4, 5, 12, 0, 0, tzinfo=UTC)
+        daily = [base + timedelta(days=i) for i in range(7)]
+
+        # Old monthly 1st snapshots
+        m1 = datetime(2026, 1, 1, 12, 0, 0, tzinfo=UTC)
+        m2 = datetime(2025, 12, 1, 12, 0, 0, tzinfo=UTC)
+        # Old non-1st, non-Sunday snapshot — should be deleted
+        old = datetime(2026, 1, 15, 12, 0, 0, tzinfo=UTC)
+
+        _seed_snapshots(snapshots_root, daily + [m1, m2, old])
+
+        result = cleanup_old_backups()
+        # 7 daily + 2 monthly = 9 kept, 1 deleted
+        assert result["kept"] == 9
+        assert result["would_delete"] == 1
+    finally:
+        config.settings = original
+
+
+def test_cleanup_unparseable_stamp_skipped(tmp_path, monkeypatch):
+    """Directories with unparseable names are ignored, not deleted."""
+    original, snapshots_root = _setup_cleanup_env(tmp_path, monkeypatch)
+    try:
+        base = datetime(2026, 4, 5, 12, 0, 0, tzinfo=UTC)
+        _seed_snapshots(snapshots_root, [base])
+
+        bad_dir = snapshots_root / "not-a-timestamp"
+        bad_dir.mkdir()
+
+        result = cleanup_old_backups(confirm=True)
+        assert result.get("unparseable") == ["not-a-timestamp"]
+        assert bad_dir.exists()
+        assert result["kept"] == 1
+    finally:
+        config.settings = original

tests/test_capture_stop.py

@@ -0,0 +1,249 @@
+"""Tests for deploy/hooks/capture_stop.py — Claude Code Stop hook."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import textwrap
+from io import StringIO
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+# The hook script lives outside of the normal package tree, so import
+# it by manipulating sys.path.
+_HOOK_DIR = str(Path(__file__).resolve().parent.parent / "deploy" / "hooks")
+if _HOOK_DIR not in sys.path:
+    sys.path.insert(0, _HOOK_DIR)
+
+import capture_stop  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _write_transcript(tmp: Path, entries: list[dict]) -> str:
+    """Write a JSONL transcript and return the path."""
+    path = tmp / "transcript.jsonl"
+    with open(path, "w", encoding="utf-8") as f:
+        for entry in entries:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    return str(path)
+
+
+def _user_entry(content: str, *, is_meta: bool = False) -> dict:
+    return {
+        "type": "user",
+        "isMeta": is_meta,
+        "message": {"role": "user", "content": content},
+    }
+
+
+def _assistant_entry() -> dict:
+    return {
+        "type": "assistant",
+        "message": {
+            "role": "assistant",
+            "content": [{"type": "text", "text": "Sure, here's the answer."}],
+        },
+    }
+
+
+def _system_entry() -> dict:
+    return {"type": "system", "message": {"role": "system", "content": "system init"}}
+
+
+# ---------------------------------------------------------------------------
+# _extract_last_user_prompt
+# ---------------------------------------------------------------------------
+
+class TestExtractLastUserPrompt:
+    def test_returns_last_real_prompt(self, tmp_path):
+        path = _write_transcript(tmp_path, [
+            _user_entry("First prompt that is long enough to capture"),
+            _assistant_entry(),
+            _user_entry("Second prompt that should be the one we capture"),
+            _assistant_entry(),
+        ])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert result == "Second prompt that should be the one we capture"
+
+    def test_skips_meta_messages(self, tmp_path):
+        path = _write_transcript(tmp_path, [
+            _user_entry("Real prompt that is definitely long enough"),
+            _user_entry("<local-command>some system stuff</local-command>"),
+            _user_entry("Meta message that looks real enough", is_meta=True),
+        ])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert result == "Real prompt that is definitely long enough"
+
+    def test_skips_xml_content(self, tmp_path):
+        path = _write_transcript(tmp_path, [
+            _user_entry("Actual prompt from a real human user"),
+            _user_entry("<command-name>/help</command-name>"),
+        ])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert result == "Actual prompt from a real human user"
+
+    def test_skips_short_messages(self, tmp_path):
+        path = _write_transcript(tmp_path, [
+            _user_entry("This prompt is long enough to be captured"),
+            _user_entry("yes"),  # too short
+        ])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert result == "This prompt is long enough to be captured"
+
+    def test_handles_content_blocks(self, tmp_path):
+        entry = {
+            "type": "user",
+            "message": {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "First paragraph of the prompt."},
+                    {"type": "text", "text": "Second paragraph continues here."},
+                ],
+            },
+        }
+        path = _write_transcript(tmp_path, [entry])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert "First paragraph" in result
+        assert "Second paragraph" in result
+
+    def test_empty_transcript(self, tmp_path):
+        path = _write_transcript(tmp_path, [])
+        result = capture_stop._extract_last_user_prompt(path)
+        assert result == ""
+
+    def test_missing_file(self):
+        result = capture_stop._extract_last_user_prompt("/nonexistent/path.jsonl")
+        assert result == ""
+
+    def test_empty_path(self):
+        result = capture_stop._extract_last_user_prompt("")
+        assert result == ""
+
+
+# ---------------------------------------------------------------------------
+# _infer_project
+# ---------------------------------------------------------------------------
+
+class TestInferProject:
+    def test_empty_cwd(self):
+        assert capture_stop._infer_project("") == ""
+
+    def test_unknown_path(self):
+        assert capture_stop._infer_project("C:\\Users\\antoi\\random") == ""
+
+    def test_mapped_path(self):
+        with mock.patch.dict(capture_stop._PROJECT_PATH_MAP, {
+            "C:\\Users\\antoi\\gigabit": "p04-gigabit",
+        }):
+            result = capture_stop._infer_project("C:\\Users\\antoi\\gigabit\\src")
+            assert result == "p04-gigabit"
+
+
+# ---------------------------------------------------------------------------
+# _capture (integration-style, mocking HTTP)
+# ---------------------------------------------------------------------------
+
+class TestCapture:
+    def _hook_input(self, *, transcript_path: str = "", **overrides) -> str:
+        data = {
+            "session_id": "test-session-123",
+            "transcript_path": transcript_path,
+            "cwd": "C:\\Users\\antoi\\ATOCore",
+            "permission_mode": "default",
+            "hook_event_name": "Stop",
+            "last_assistant_message": "Here is the answer to your question about the code.",
+            "turn_number": 3,
+        }
+        data.update(overrides)
+        return json.dumps(data)
+
+    @mock.patch("capture_stop.urllib.request.urlopen")
+    def test_posts_to_atocore(self, mock_urlopen, tmp_path):
+        transcript = _write_transcript(tmp_path, [
+            _user_entry("Please explain how the backup system works in detail"),
+            _assistant_entry(),
+        ])
+        mock_resp = mock.MagicMock()
+        mock_resp.read.return_value = json.dumps({"id": "int-001", "status": "recorded"}).encode()
+        mock_urlopen.return_value = mock_resp
+
+        with mock.patch("sys.stdin", StringIO(self._hook_input(transcript_path=transcript))):
+            capture_stop._capture()
+
+        mock_urlopen.assert_called_once()
+        req = mock_urlopen.call_args[0][0]
+        body = json.loads(req.data.decode())
+        assert body["prompt"] == "Please explain how the backup system works in detail"
+        assert body["client"] == "claude-code"
+        assert body["session_id"] == "test-session-123"
+        assert body["reinforce"] is True
+
+    @mock.patch("capture_stop.urllib.request.urlopen")
+    def test_skips_when_disabled(self, mock_urlopen, tmp_path):
+        transcript = _write_transcript(tmp_path, [
+            _user_entry("A prompt that would normally be captured"),
+        ])
+        with mock.patch.dict(os.environ, {"ATOCORE_CAPTURE_DISABLED": "1"}):
+            with mock.patch("sys.stdin", StringIO(self._hook_input(transcript_path=transcript))):
+                capture_stop._capture()
+        mock_urlopen.assert_not_called()
+
+    @mock.patch("capture_stop.urllib.request.urlopen")
+    def test_skips_short_prompt(self, mock_urlopen, tmp_path):
+        transcript = _write_transcript(tmp_path, [
+            _user_entry("yes"),
+        ])
+        with mock.patch("sys.stdin", StringIO(self._hook_input(transcript_path=transcript))):
+            capture_stop._capture()
+        mock_urlopen.assert_not_called()
+
+    @mock.patch("capture_stop.urllib.request.urlopen")
+    def test_truncates_long_response(self, mock_urlopen, tmp_path):
+        transcript = _write_transcript(tmp_path, [
+            _user_entry("Tell me everything about the entire codebase architecture"),
+        ])
+        long_response = "x" * 60_000
+        mock_resp = mock.MagicMock()
+        mock_resp.read.return_value = json.dumps({"id": "int-002"}).encode()
+        mock_urlopen.return_value = mock_resp
+
+        with mock.patch("sys.stdin", StringIO(
+            self._hook_input(transcript_path=transcript, last_assistant_message=long_response)
+        )):
+            capture_stop._capture()
+
+        req = mock_urlopen.call_args[0][0]
+        body = json.loads(req.data.decode())
+        assert len(body["response"]) <= capture_stop.MAX_RESPONSE_LENGTH + 20
+        assert body["response"].endswith("[truncated]")
+
+    def test_main_never_raises(self):
+        """main() must always exit 0, even on garbage input."""
+        with mock.patch("sys.stdin", StringIO("not json at all")):
+            # Should not raise
+            capture_stop.main()
+
+    @mock.patch("capture_stop.urllib.request.urlopen")
+    def test_uses_atocore_url_env(self, mock_urlopen, tmp_path):
+        transcript = _write_transcript(tmp_path, [
+            _user_entry("Please help me with this particular problem in the code"),
+        ])
+        mock_resp = mock.MagicMock()
+        mock_resp.read.return_value = json.dumps({"id": "int-003"}).encode()
+        mock_urlopen.return_value = mock_resp
+
+        with mock.patch.dict(os.environ, {"ATOCORE_URL": "http://localhost:9999"}):
+            # Re-read the env var
+            with mock.patch.object(capture_stop, "ATOCORE_URL", "http://localhost:9999"):
+                with mock.patch("sys.stdin", StringIO(self._hook_input(transcript_path=transcript))):
+                    capture_stop._capture()
+
+        req = mock_urlopen.call_args[0][0]
+        assert req.full_url == "http://localhost:9999/interactions"

tests/test_context_builder.py

@@ -1,5 +1,8 @@
 """Tests for the context builder."""
 
+import json
+
+import atocore.config as config
 from atocore.context.builder import build_context, get_last_context_pack
 from atocore.context.project_state import init_project_state_schema, set_state
 from atocore.ingestion.pipeline import ingest_file
@@ -162,3 +165,184 @@ def test_no_project_state_without_hint(tmp_data_dir, sample_markdown):
     pack = build_context("What is AtoCore?")
     assert pack.project_state_chars == 0
     assert "--- Trusted Project State ---" not in pack.formatted_context
+
+
+def test_alias_hint_resolves_through_registry(tmp_data_dir, sample_markdown, monkeypatch):
+    """An alias hint like 'p05' should find project state stored under 'p05-interferometer'.
+
+    This is the regression test for the P1 finding from codex's review:
+    /context/build was previously doing an exact-name lookup that
+    silently dropped trusted project state when the caller passed an
+    alias instead of the canonical project id.
+    """
+    init_db()
+    init_project_state_schema()
+    ingest_file(sample_markdown)
+
+    # Stand up a minimal project registry that knows the aliases.
+    # The registry lives in a JSON file pointed to by
+    # ATOCORE_PROJECT_REGISTRY_PATH; the dataclass-driven loader picks
+    # it up on every call (no in-process cache to invalidate).
+    registry_path = tmp_data_dir / "project-registry.json"
+    registry_path.write_text(
+        json.dumps(
+            {
+                "projects": [
+                    {
+                        "id": "p05-interferometer",
+                        "aliases": ["p05", "interferometer"],
+                        "description": "P05 alias-resolution regression test",
+                        "ingest_roots": [
+                            {"source": "vault", "subpath": "incoming/projects/p05"}
+                        ],
+                    }
+                ]
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("ATOCORE_PROJECT_REGISTRY_PATH", str(registry_path))
+    config.settings = config.Settings()
+
+    # Trusted state is stored under the canonical id (the way the
+    # /project/state endpoint always writes it).
+    set_state(
+        "p05-interferometer",
+        "status",
+        "next_focus",
+        "Wave 2 trusted-operational ingestion",
+    )
+
+    # The bug: pack with alias hint used to silently miss the state.
+    pack_with_alias = build_context("status?", project_hint="p05", budget=2000)
+    assert "Wave 2 trusted-operational ingestion" in pack_with_alias.formatted_context
+    assert pack_with_alias.project_state_chars > 0
+
+    # The canonical id should still work the same way.
+    pack_with_canonical = build_context(
+        "status?", project_hint="p05-interferometer", budget=2000
+    )
+    assert "Wave 2 trusted-operational ingestion" in pack_with_canonical.formatted_context
+
+    # A second alias should also resolve.
+    pack_with_other_alias = build_context(
+        "status?", project_hint="interferometer", budget=2000
+    )
+    assert "Wave 2 trusted-operational ingestion" in pack_with_other_alias.formatted_context
+
+
+def test_unknown_hint_falls_back_to_raw_lookup(tmp_data_dir, sample_markdown, monkeypatch):
+    """A hint that isn't in the registry should still try the raw name.
+
+    This preserves backwards compatibility with hand-curated
+    project_state entries that predate the project registry.
+    """
+    init_db()
+    init_project_state_schema()
+    ingest_file(sample_markdown)
+
+    # Empty registry — the hint won't resolve through it.
+    registry_path = tmp_data_dir / "project-registry.json"
+    registry_path.write_text('{"projects": []}', encoding="utf-8")
+    monkeypatch.setenv("ATOCORE_PROJECT_REGISTRY_PATH", str(registry_path))
+    config.settings = config.Settings()
+
+    set_state("orphan-project", "status", "phase", "Solo run")
+
+    pack = build_context("status?", project_hint="orphan-project", budget=2000)
+    assert "Solo run" in pack.formatted_context
+
+
+def test_project_memories_included_in_pack(tmp_data_dir, sample_markdown):
+    """Active project-scoped memories for the target project should
+    land in a dedicated '--- Project Memories ---' band so the
+    Phase 9 reflection loop has a retrieval outlet."""
+    from atocore.memory.service import create_memory
+
+    init_db()
+    init_project_state_schema()
+    ingest_file(sample_markdown)
+
+    mem = create_memory(
+        memory_type="project",
+        content="the mirror architecture is Option B conical back for p04-gigabit",
+        project="p04-gigabit",
+        confidence=0.9,
+    )
+    # A sibling memory for a different project must NOT leak into the pack.
+    create_memory(
+        memory_type="project",
+        content="polisher suite splits into sim, post, control, contracts",
+        project="p06-polisher",
+        confidence=0.9,
+    )
+
+    pack = build_context(
+        "remind me about the mirror architecture",
+        project_hint="p04-gigabit",
+        budget=3000,
+    )
+    assert "--- Project Memories ---" in pack.formatted_context
+    assert "Option B conical back" in pack.formatted_context
+    assert "polisher suite splits" not in pack.formatted_context
+    assert pack.project_memory_chars > 0
+    assert mem.project == "p04-gigabit"
+
+
+def test_project_memories_absent_without_project_hint(tmp_data_dir, sample_markdown):
+    """Without a project hint, project memories stay out of the pack —
+    cross-project bleed would rot the signal."""
+    from atocore.memory.service import create_memory
+
+    init_db()
+    init_project_state_schema()
+    ingest_file(sample_markdown)
+
+    create_memory(
+        memory_type="project",
+        content="scoped project knowledge that should not leak globally",
+        project="p04-gigabit",
+        confidence=0.9,
+    )
+
+    pack = build_context("tell me something", budget=3000)
+    assert "--- Project Memories ---" not in pack.formatted_context
+    assert pack.project_memory_chars == 0
+
+
+def test_project_memories_query_relevance_ordering(tmp_data_dir, sample_markdown):
+    """When the budget only fits one memory, query-relevance ordering
+    should pick the one the query is actually about — even if another
+    memory has higher confidence.
+
+    Regression for the 2026-04-11 p05-vendor-signal harness failure:
+    memory selection was fixed-order by confidence, so a lower-ranked
+    vendor memory got starved out of the budget when a query was
+    specifically about vendors.
+    """
+    from atocore.memory.service import create_memory
+
+    init_db()
+    init_project_state_schema()
+    ingest_file(sample_markdown)
+
+    create_memory(
+        memory_type="project",
+        content="the folded-beam interferometer uses a CGH stage and fold mirror",
+        project="p05-interferometer",
+        confidence=0.97,
+    )
+    create_memory(
+        memory_type="knowledge",
+        content="vendor signal: Zygo Verifire SV is the strongest value path for the interferometer",
+        project="p05-interferometer",
+        confidence=0.85,
+    )
+
+    pack = build_context(
+        "what is the current vendor signal for the interferometer",
+        project_hint="p05-interferometer",
+        budget=1200,  # tight enough that only one project memory fits
+    )
+    assert "Zygo Verifire SV" in pack.formatted_context
+    assert pack.project_memory_chars > 0

tests/test_database.py

@@ -47,3 +47,138 @@ def test_get_connection_uses_configured_timeout_value(tmp_path, monkeypatch):
 
     assert calls
     assert calls[0] == 2.5
+
+
+def test_init_db_upgrades_pre_phase9_schema_without_failing(tmp_path, monkeypatch):
+    """Regression test for the schema init ordering bug caught during
+    the first real Dalidou deploy (report from 2026-04-08).
+
+    Before the fix, SCHEMA_SQL contained CREATE INDEX statements that
+    referenced columns (memories.project, interactions.project,
+    interactions.session_id) added by _apply_migrations later in
+    init_db. On a fresh install this worked because CREATE TABLE
+    created the tables with the new columns before the CREATE INDEX
+    ran, but on UPGRADE from a pre-Phase-9 schema the CREATE TABLE
+    IF NOT EXISTS was a no-op and the CREATE INDEX hit
+    OperationalError: no such column.
+
+    This test seeds the tables with the OLD pre-Phase-9 shape then
+    calls init_db() and verifies that:
+
+    - init_db does not raise
+    - The new columns were added via _apply_migrations
+    - The new indexes exist
+
+    If the bug is reintroduced by moving a CREATE INDEX for a
+    migration column back into SCHEMA_SQL, this test will fail
+    with OperationalError before reaching the assertions.
+    """
+    monkeypatch.setenv("ATOCORE_DATA_DIR", str(tmp_path / "data"))
+    original_settings = config.settings
+    try:
+        config.settings = config.Settings()
+
+        # Step 1: create the data dir and open a direct connection
+        config.ensure_runtime_dirs()
+        db_path = config.settings.db_path
+
+        # Step 2: seed the DB with the old pre-Phase-9 shape. No
+        # project/last_referenced_at/reference_count on memories; no
+        # project/client/session_id/response/memories_used/chunks_used
+        # on interactions. We also need the prerequisite tables
+        # (projects, source_documents, source_chunks) because the
+        # memories table has an FK to source_chunks.
+        with sqlite3.connect(str(db_path)) as conn:
+            conn.executescript(
+                """
+                CREATE TABLE source_documents (
+                    id TEXT PRIMARY KEY,
+                    file_path TEXT UNIQUE NOT NULL,
+                    file_hash TEXT NOT NULL,
+                    title TEXT,
+                    doc_type TEXT DEFAULT 'markdown',
+                    tags TEXT DEFAULT '[]',
+                    ingested_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE TABLE source_chunks (
+                    id TEXT PRIMARY KEY,
+                    document_id TEXT NOT NULL REFERENCES source_documents(id) ON DELETE CASCADE,
+                    chunk_index INTEGER NOT NULL,
+                    content TEXT NOT NULL,
+                    heading_path TEXT DEFAULT '',
+                    char_count INTEGER NOT NULL,
+                    metadata TEXT DEFAULT '{}',
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE TABLE memories (
+                    id TEXT PRIMARY KEY,
+                    memory_type TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    source_chunk_id TEXT REFERENCES source_chunks(id),
+                    confidence REAL DEFAULT 1.0,
+                    status TEXT DEFAULT 'active',
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE TABLE projects (
+                    id TEXT PRIMARY KEY,
+                    name TEXT UNIQUE NOT NULL,
+                    description TEXT DEFAULT '',
+                    status TEXT DEFAULT 'active',
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE TABLE interactions (
+                    id TEXT PRIMARY KEY,
+                    prompt TEXT NOT NULL,
+                    context_pack TEXT DEFAULT '{}',
+                    response_summary TEXT DEFAULT '',
+                    project_id TEXT REFERENCES projects(id),
+                    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+                );
+                """
+            )
+            conn.commit()
+
+        # Step 3: call init_db — this used to raise on the upgrade
+        # path. After the fix it should succeed.
+        init_db()
+
+        # Step 4: verify the migrations ran — Phase 9 columns present
+        with sqlite3.connect(str(db_path)) as conn:
+            conn.row_factory = sqlite3.Row
+            memories_cols = {
+                row["name"] for row in conn.execute("PRAGMA table_info(memories)")
+            }
+            interactions_cols = {
+                row["name"]
+                for row in conn.execute("PRAGMA table_info(interactions)")
+            }
+
+            assert "project" in memories_cols
+            assert "last_referenced_at" in memories_cols
+            assert "reference_count" in memories_cols
+
+            assert "project" in interactions_cols
+            assert "client" in interactions_cols
+            assert "session_id" in interactions_cols
+            assert "response" in interactions_cols
+            assert "memories_used" in interactions_cols
+            assert "chunks_used" in interactions_cols
+
+            # Step 5: verify the indexes on migration columns exist
+            index_rows = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='index' AND tbl_name IN ('memories','interactions')"
+            ).fetchall()
+            index_names = {row["name"] for row in index_rows}
+
+            assert "idx_memories_project" in index_names
+            assert "idx_interactions_project_name" in index_names
+            assert "idx_interactions_session" in index_names
+    finally:
+        config.settings = original_settings

tests/test_extractor_llm.py

@@ -0,0 +1,177 @@
+"""Tests for the LLM-assisted extractor path.
+
+Focused on the parser and failure-mode contracts — the actual network
+call is exercised out of band by running
+``python scripts/extractor_eval.py --mode llm`` against the frozen
+labeled corpus with ``ANTHROPIC_API_KEY`` set. These tests only
+exercise the pieces that don't need network.
+"""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from atocore.interactions.service import Interaction
+from atocore.memory.extractor_llm import (
+    LLM_EXTRACTOR_VERSION,
+    _parse_candidates,
+    extract_candidates_llm,
+    extract_candidates_llm_verbose,
+)
+import atocore.memory.extractor_llm as extractor_llm
+
+
+def _make_interaction(prompt: str = "p", response: str = "r") -> Interaction:
+    return Interaction(
+        id="test-id",
+        prompt=prompt,
+        response=response,
+        response_summary="",
+        project="",
+        client="test",
+        session_id="",
+    )
+
+
+def test_parser_handles_empty_array():
+    result = _parse_candidates("[]", _make_interaction())
+    assert result == []
+
+
+def test_parser_handles_malformed_json():
+    result = _parse_candidates("{ not valid json", _make_interaction())
+    assert result == []
+
+
+def test_parser_strips_markdown_fences():
+    raw = "```json\n[{\"type\": \"knowledge\", \"content\": \"x is y\", \"project\": \"\", \"confidence\": 0.5}]\n```"
+    result = _parse_candidates(raw, _make_interaction())
+    assert len(result) == 1
+    assert result[0].memory_type == "knowledge"
+    assert result[0].content == "x is y"
+
+
+def test_parser_strips_surrounding_prose():
+    raw = "Here are the candidates:\n[{\"type\": \"project\", \"content\": \"foo\", \"project\": \"p04\", \"confidence\": 0.6}]\nThat's it."
+    result = _parse_candidates(raw, _make_interaction())
+    assert len(result) == 1
+    assert result[0].memory_type == "project"
+    assert result[0].project == "p04"
+
+
+def test_parser_drops_invalid_memory_types():
+    raw = '[{"type": "nonsense", "content": "x"}, {"type": "project", "content": "y"}]'
+    result = _parse_candidates(raw, _make_interaction())
+    assert len(result) == 1
+    assert result[0].memory_type == "project"
+
+
+def test_parser_drops_empty_content():
+    raw = '[{"type": "knowledge", "content": "   "}, {"type": "knowledge", "content": "real"}]'
+    result = _parse_candidates(raw, _make_interaction())
+    assert len(result) == 1
+    assert result[0].content == "real"
+
+
+def test_parser_clamps_confidence_to_unit_interval():
+    raw = '[{"type": "knowledge", "content": "c1", "confidence": 2.5}, {"type": "knowledge", "content": "c2", "confidence": -0.4}]'
+    result = _parse_candidates(raw, _make_interaction())
+    assert result[0].confidence == 1.0
+    assert result[1].confidence == 0.0
+
+
+def test_parser_defaults_confidence_on_missing_field():
+    raw = '[{"type": "knowledge", "content": "c1"}]'
+    result = _parse_candidates(raw, _make_interaction())
+    assert result[0].confidence == 0.5
+
+
+def test_parser_tags_version_and_rule():
+    raw = '[{"type": "project", "content": "c1"}]'
+    result = _parse_candidates(raw, _make_interaction())
+    assert result[0].rule == "llm_extraction"
+    assert result[0].extractor_version == LLM_EXTRACTOR_VERSION
+    assert result[0].source_interaction_id == "test-id"
+
+
+def test_parser_falls_back_to_interaction_project():
+    """R6: when the model returns empty project but the interaction
+    has one, the candidate should inherit the interaction's project."""
+    raw = '[{"type": "project", "content": "machine works offline"}]'
+    interaction = _make_interaction()
+    interaction.project = "p06-polisher"
+    result = _parse_candidates(raw, interaction)
+    assert result[0].project == "p06-polisher"
+
+
+def test_parser_keeps_model_project_when_provided():
+    """Model-supplied project takes precedence over interaction."""
+    raw = '[{"type": "project", "content": "x", "project": "p04-gigabit"}]'
+    interaction = _make_interaction()
+    interaction.project = "p06-polisher"
+    result = _parse_candidates(raw, interaction)
+    assert result[0].project == "p04-gigabit"
+
+
+def test_missing_cli_returns_empty(monkeypatch):
+    """If ``claude`` is not on PATH the extractor returns empty, never raises."""
+    monkeypatch.setattr(extractor_llm, "_cli_available", lambda: False)
+    result = extract_candidates_llm_verbose(_make_interaction("p", "some real response"))
+    assert result.candidates == []
+    assert result.error == "claude_cli_missing"
+
+
+def test_empty_response_returns_empty(monkeypatch):
+    monkeypatch.setattr(extractor_llm, "_cli_available", lambda: True)
+    result = extract_candidates_llm_verbose(_make_interaction("p", ""))
+    assert result.candidates == []
+    assert result.error == "empty_response"
+
+
+def test_subprocess_timeout_returns_empty(monkeypatch):
+    """A subprocess timeout must not raise into the caller."""
+    monkeypatch.setattr(extractor_llm, "_cli_available", lambda: True)
+
+    import subprocess as _sp
+
+    def _boom(*a, **kw):
+        raise _sp.TimeoutExpired(cmd=a[0] if a else "claude", timeout=1)
+
+    monkeypatch.setattr(extractor_llm.subprocess, "run", _boom)
+    result = extract_candidates_llm_verbose(_make_interaction("p", "real response"))
+    assert result.candidates == []
+    assert result.error == "timeout"
+
+
+def test_subprocess_nonzero_exit_returns_empty(monkeypatch):
+    """A non-zero CLI exit (auth failure, etc.) must not raise."""
+    monkeypatch.setattr(extractor_llm, "_cli_available", lambda: True)
+
+    class _Completed:
+        returncode = 1
+        stdout = ""
+        stderr = "auth failed"
+
+    monkeypatch.setattr(extractor_llm.subprocess, "run", lambda *a, **kw: _Completed())
+    result = extract_candidates_llm_verbose(_make_interaction("p", "real response"))
+    assert result.candidates == []
+    assert result.error == "exit_1"
+
+
+def test_happy_path_parses_stdout(monkeypatch):
+    monkeypatch.setattr(extractor_llm, "_cli_available", lambda: True)
+
+    class _Completed:
+        returncode = 0
+        stdout = '[{"type": "project", "content": "p04 selected Option B", "project": "p04-gigabit", "confidence": 0.6}]'
+        stderr = ""
+
+    monkeypatch.setattr(extractor_llm.subprocess, "run", lambda *a, **kw: _Completed())
+    result = extract_candidates_llm_verbose(_make_interaction("p", "r"))
+    assert len(result.candidates) == 1
+    assert result.candidates[0].memory_type == "project"
+    assert result.candidates[0].project == "p04-gigabit"
+    assert abs(result.candidates[0].confidence - 0.6) < 1e-9

tests/test_interactions.py

@@ -209,3 +209,96 @@ def test_list_interactions_endpoint_returns_summaries(tmp_data_dir):
     assert body["interactions"][0]["response_chars"] == 50
     # The list endpoint never includes the full response body
     assert "response" not in body["interactions"][0]
+
+
+# --- alias canonicalization on interaction capture/list -------------------
+
+
+def test_record_interaction_canonicalizes_project(project_registry):
+    """Capturing under an alias should store the canonical project id.
+
+    Regression for codex's P2 finding: reinforcement and extraction
+    query memories by interaction.project; if the captured project is
+    a raw alias they would silently miss memories stored under the
+    canonical id.
+    """
+    init_db()
+    project_registry(("p05-interferometer", ["p05", "interferometer"]))
+
+    interaction = record_interaction(
+        prompt="quick capture", response="response body", project="p05", reinforce=False
+    )
+    assert interaction.project == "p05-interferometer"
+
+    fetched = get_interaction(interaction.id)
+    assert fetched.project == "p05-interferometer"
+
+
+def test_list_interactions_canonicalizes_project_filter(project_registry):
+    init_db()
+    project_registry(("p06-polisher", ["p06", "polisher"]))
+
+    record_interaction(prompt="a", response="ra", project="p06-polisher", reinforce=False)
+    record_interaction(prompt="b", response="rb", project="polisher", reinforce=False)
+    record_interaction(prompt="c", response="rc", project="atocore", reinforce=False)
+
+    # Query by an alias should still find both p06 captures
+    via_alias = list_interactions(project="p06")
+    via_canonical = list_interactions(project="p06-polisher")
+    assert len(via_alias) == 2
+    assert len(via_canonical) == 2
+    assert {i.prompt for i in via_alias} == {"a", "b"}
+
+
+# --- since filter format normalization ------------------------------------
+
+
+def test_list_interactions_since_accepts_iso_with_t_separator(tmp_data_dir):
+    init_db()
+    record_interaction(prompt="early", response="r", reinforce=False)
+    time.sleep(1.05)
+    pivot = record_interaction(prompt="late", response="r", reinforce=False)
+
+    # pivot.created_at is in storage format 'YYYY-MM-DD HH:MM:SS'.
+    # Build the equivalent ISO 8601 with 'T' that an external client
+    # would naturally send.
+    iso_with_t = pivot.created_at.replace(" ", "T")
+    items = list_interactions(since=iso_with_t)
+    assert any(i.id == pivot.id for i in items)
+    # The early row must also be excluded if its timestamp is strictly
+    # before the pivot — since is inclusive on the cutoff
+    early_ids = {i.id for i in items if i.prompt == "early"}
+    assert early_ids == set() or len(items) >= 1
+
+
+def test_list_interactions_since_accepts_z_suffix(tmp_data_dir):
+    init_db()
+    pivot = record_interaction(prompt="pivot", response="r", reinforce=False)
+    time.sleep(1.05)
+    after = record_interaction(prompt="after", response="r", reinforce=False)
+
+    iso_with_z = pivot.created_at.replace(" ", "T") + "Z"
+    items = list_interactions(since=iso_with_z)
+    ids = {i.id for i in items}
+    assert pivot.id in ids
+    assert after.id in ids
+
+
+def test_list_interactions_since_accepts_offset(tmp_data_dir):
+    init_db()
+    pivot = record_interaction(prompt="pivot", response="r", reinforce=False)
+    time.sleep(1.05)
+    after = record_interaction(prompt="after", response="r", reinforce=False)
+
+    iso_with_offset = pivot.created_at.replace(" ", "T") + "+00:00"
+    items = list_interactions(since=iso_with_offset)
+    assert any(i.id == after.id for i in items)
+
+
+def test_list_interactions_since_storage_format_still_works(tmp_data_dir):
+    """The bare storage format must still work for backwards compatibility."""
+    init_db()
+    pivot = record_interaction(prompt="pivot", response="r", reinforce=False)
+
+    items = list_interactions(since=pivot.created_at)
+    assert any(i.id == pivot.id for i in items)

tests/test_migrate_legacy_aliases.py

@@ -0,0 +1,802 @@
+"""Tests for scripts/migrate_legacy_aliases.py.
+
+The migration script closes the compatibility gap documented in
+docs/architecture/project-identity-canonicalization.md. These tests
+cover:
+
+- empty/clean database behavior
+- shadow projects detection
+- state rekey without collisions
+- state collision detection + apply refusal
+- memory rekey + supersession of duplicates
+- interaction rekey
+- end-to-end apply on a realistic shadow
+- idempotency (running twice produces the same final state)
+- report artifact is written
+- the pre-fix regression gap is actually closed after migration
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+import uuid
+from pathlib import Path
+
+import pytest
+
+from atocore.context.project_state import (
+    get_state,
+    init_project_state_schema,
+)
+from atocore.models.database import init_db
+
+# Make scripts/ importable
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_REPO_ROOT / "scripts"))
+
+import migrate_legacy_aliases as mig  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Helpers that seed "legacy" rows the way they would have looked before fb6298a
+# ---------------------------------------------------------------------------
+
+
+def _open_db_connection():
+    """Open a direct SQLite connection to the test data dir's DB."""
+    import atocore.config as config
+
+    conn = sqlite3.connect(str(config.settings.db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def _seed_shadow_project(
+    conn: sqlite3.Connection, shadow_name: str
+) -> str:
+    """Insert a projects row keyed under an alias, like the old set_state would have."""
+    project_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO projects (id, name, description) VALUES (?, ?, ?)",
+        (project_id, shadow_name, f"shadow row for {shadow_name}"),
+    )
+    conn.commit()
+    return project_id
+
+
+def _seed_state_row(
+    conn: sqlite3.Connection,
+    project_id: str,
+    category: str,
+    key: str,
+    value: str,
+    status: str = "active",
+) -> str:
+    row_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO project_state "
+        "(id, project_id, category, key, value, source, confidence, status) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+        (row_id, project_id, category, key, value, "legacy-test", 1.0, status),
+    )
+    conn.commit()
+    return row_id
+
+
+def _seed_memory_row(
+    conn: sqlite3.Connection,
+    memory_type: str,
+    content: str,
+    project: str,
+    status: str = "active",
+) -> str:
+    row_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO memories "
+        "(id, memory_type, content, project, source_chunk_id, confidence, status) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (row_id, memory_type, content, project, None, 1.0, status),
+    )
+    conn.commit()
+    return row_id
+
+
+def _seed_interaction_row(
+    conn: sqlite3.Connection, prompt: str, project: str
+) -> str:
+    row_id = str(uuid.uuid4())
+    conn.execute(
+        "INSERT INTO interactions "
+        "(id, prompt, context_pack, response_summary, response, "
+        " memories_used, chunks_used, client, session_id, project, created_at) "
+        "VALUES (?, ?, '{}', '', '', '[]', '[]', 'legacy-test', '', ?, '2026-04-01 12:00:00')",
+        (row_id, prompt, project),
+    )
+    conn.commit()
+    return row_id
+
+
+# ---------------------------------------------------------------------------
+# plan-building tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _setup(tmp_data_dir):
+    init_db()
+    init_project_state_schema()
+
+
+def test_dry_run_on_empty_registry_reports_empty_plan(tmp_data_dir):
+    """Empty registry -> empty alias map -> empty plan."""
+    registry_path = tmp_data_dir / "empty-registry.json"
+    registry_path.write_text('{"projects": []}', encoding="utf-8")
+
+    conn = _open_db_connection()
+    try:
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    assert plan.alias_map == {}
+    assert plan.is_empty
+    assert not plan.has_collisions
+    assert plan.counts() == {
+        "shadow_projects": 0,
+        "state_rekey_rows": 0,
+        "state_collisions": 0,
+        "state_historical_drops": 0,
+        "memory_rekey_rows": 0,
+        "memory_supersede_rows": 0,
+        "interaction_rekey_rows": 0,
+    }
+
+
+def test_dry_run_on_clean_registered_db_reports_empty_plan(project_registry):
+    """A registry with projects but no legacy rows -> empty plan."""
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    assert plan.alias_map != {}
+    assert plan.is_empty
+
+
+def test_dry_run_finds_shadow_project(project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        _seed_shadow_project(conn, "p05")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    assert len(plan.shadow_projects) == 1
+    assert plan.shadow_projects[0].shadow_name == "p05"
+    assert plan.shadow_projects[0].canonical_project_id == "p05-interferometer"
+
+
+def test_dry_run_plans_state_rekey_without_collisions(project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        _seed_state_row(conn, shadow_id, "status", "next_focus", "Wave 1 ingestion")
+        _seed_state_row(conn, shadow_id, "decision", "lateral_support", "GF-PTFE")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    assert len(plan.state_plans) == 1
+    sp = plan.state_plans[0]
+    assert len(sp.rows_to_rekey) == 2
+    assert sp.collisions == []
+    assert not plan.has_collisions
+
+
+def test_dry_run_detects_state_collision(project_registry):
+    """Shadow and canonical both have state under the same (category, key) with different values."""
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        canonical_id = _seed_shadow_project(conn, "p05-interferometer")
+        _seed_state_row(conn, shadow_id, "status", "next_focus", "Wave 1")
+        _seed_state_row(
+            conn, canonical_id, "status", "next_focus", "Wave 2"
+        )
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    assert plan.has_collisions
+    collision = plan.state_plans[0].collisions[0]
+    assert collision["shadow"]["value"] == "Wave 1"
+    assert collision["canonical"]["value"] == "Wave 2"
+
+
+def test_dry_run_plans_memory_rekey_and_supersession(project_registry):
+    registry_path = project_registry(
+        ("p04-gigabit", ["p04", "gigabit"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        # A clean memory under the alias that will just be rekeyed
+        _seed_memory_row(conn, "project", "clean rekey memory", "p04")
+        # A memory that collides with an existing canonical memory
+        _seed_memory_row(conn, "project", "duplicate content", "p04")
+        _seed_memory_row(conn, "project", "duplicate content", "p04-gigabit")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    # There's exactly one memory plan (one alias matched)
+    assert len(plan.memory_plans) == 1
+    mp = plan.memory_plans[0]
+    # Two rows are candidates for rekey or supersession — one clean,
+    # one duplicate. The duplicate is handled via to_supersede; the
+    # other via rows_to_rekey.
+    total_affected = len(mp.rows_to_rekey) + len(mp.to_supersede)
+    assert total_affected == 2
+
+
+def test_dry_run_plans_interaction_rekey(project_registry):
+    registry_path = project_registry(
+        ("p06-polisher", ["p06", "polisher"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        _seed_interaction_row(conn, "quick capture under alias", "polisher")
+        _seed_interaction_row(conn, "another alias-keyed row", "p06")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    total = sum(len(p.rows_to_rekey) for p in plan.interaction_plans)
+    assert total == 2
+
+
+# ---------------------------------------------------------------------------
+# apply tests
+# ---------------------------------------------------------------------------
+
+
+def test_apply_refuses_on_state_collision(project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        canonical_id = _seed_shadow_project(conn, "p05-interferometer")
+        _seed_state_row(conn, shadow_id, "status", "next_focus", "Wave 1")
+        _seed_state_row(conn, canonical_id, "status", "next_focus", "Wave 2")
+
+        plan = mig.build_plan(conn, registry_path)
+        assert plan.has_collisions
+
+        with pytest.raises(mig.MigrationRefused):
+            mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+
+def test_apply_migrates_clean_shadow_end_to_end(project_registry):
+    """The happy path: one shadow project with clean state rows, rekey into a freshly-created canonical row, verify reachability via get_state."""
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        _seed_state_row(
+            conn, shadow_id, "status", "next_focus", "Wave 1 ingestion"
+        )
+        _seed_state_row(
+            conn, shadow_id, "decision", "lateral_support", "GF-PTFE"
+        )
+
+        plan = mig.build_plan(conn, registry_path)
+        assert not plan.has_collisions
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["state_rows_rekeyed"] == 2
+    assert summary["shadow_projects_deleted"] == 1
+    assert summary["canonical_rows_created"] == 1
+
+    # The regression gap is now closed: the service layer can see
+    # the state under the canonical id via either the alias OR the
+    # canonical.
+    via_alias = get_state("p05")
+    via_canonical = get_state("p05-interferometer")
+    assert len(via_alias) == 2
+    assert len(via_canonical) == 2
+    values = {entry.value for entry in via_canonical}
+    assert values == {"Wave 1 ingestion", "GF-PTFE"}
+
+
+def test_apply_drops_shadow_state_duplicate_without_collision(project_registry):
+    """Shadow and canonical both have the same (category, key, value) — shadow gets marked superseded rather than hitting the UNIQUE constraint."""
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        canonical_id = _seed_shadow_project(conn, "p05-interferometer")
+        _seed_state_row(
+            conn, shadow_id, "status", "next_focus", "Wave 1 ingestion"
+        )
+        _seed_state_row(
+            conn, canonical_id, "status", "next_focus", "Wave 1 ingestion"
+        )
+
+        plan = mig.build_plan(conn, registry_path)
+        assert not plan.has_collisions
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["state_rows_merged_as_duplicate"] == 1
+
+    via_canonical = get_state("p05-interferometer")
+    # Exactly one active row survives
+    assert len(via_canonical) == 1
+    assert via_canonical[0].value == "Wave 1 ingestion"
+
+
+def test_apply_preserves_superseded_shadow_state_when_no_collision(project_registry):
+    """Regression test for the codex-flagged data-loss bug.
+
+    Before the fix, plan_state_migration only selected status='active'
+    rows. Any superseded or invalid row on the shadow project was
+    invisible to the plan and got silently cascade-deleted when the
+    shadow projects row was dropped at the end of apply. That's
+    exactly the kind of audit loss a cleanup migration must not cause.
+
+    This test seeds a shadow project with a superseded state row on
+    a triple the canonical project doesn't have, runs the migration,
+    and verifies the row survived and is now attached to the
+    canonical project (still with status='superseded').
+    """
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        # Superseded row on a triple the canonical won't have
+        _seed_state_row(
+            conn,
+            shadow_id,
+            "status",
+            "historical_phase",
+            "Phase 0 legacy",
+            status="superseded",
+        )
+
+        plan = mig.build_plan(conn, registry_path)
+        assert not plan.has_collisions
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    # The superseded row should have been rekeyed, not dropped
+    assert summary["state_rows_rekeyed"] == 1
+    assert summary["state_rows_historical_dropped"] == 0
+
+    # Verify via raw SQL that the row is now attached to the canonical
+    # projects row and still has status='superseded'
+    conn = _open_db_connection()
+    try:
+        row = conn.execute(
+            "SELECT ps.status, ps.value, p.name "
+            "FROM project_state ps JOIN projects p ON ps.project_id = p.id "
+            "WHERE ps.category = ? AND ps.key = ?",
+            ("status", "historical_phase"),
+        ).fetchone()
+    finally:
+        conn.close()
+
+    assert row is not None, "superseded shadow row was lost during migration"
+    assert row["status"] == "superseded"
+    assert row["value"] == "Phase 0 legacy"
+    assert row["name"] == "p05-interferometer"
+
+
+def test_apply_drops_shadow_inactive_row_when_canonical_holds_same_triple(project_registry):
+    """Shadow is inactive (superseded) and collides with an active canonical row.
+
+    The canonical wins by definition of the UPSERT schema. The shadow
+    row is recorded as a historical_drop in the plan so the operator
+    sees the audit loss, and the apply cascade-deletes it via the
+    shadow projects row. This is the unavoidable data-loss case
+    documented in the migration module docstring.
+    """
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        canonical_id = _seed_shadow_project(conn, "p05-interferometer")
+
+        # Shadow has a superseded value on a triple where the canonical
+        # has a different active value. Can't preserve both: UNIQUE
+        # allows only one row per triple.
+        _seed_state_row(
+            conn,
+            shadow_id,
+            "status",
+            "next_focus",
+            "Old wave 1",
+            status="superseded",
+        )
+        _seed_state_row(
+            conn,
+            canonical_id,
+            "status",
+            "next_focus",
+            "Wave 2 trusted-operational",
+            status="active",
+        )
+
+        plan = mig.build_plan(conn, registry_path)
+        assert not plan.has_collisions  # not an active-vs-active collision
+        assert plan.counts()["state_historical_drops"] == 1
+
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["state_rows_historical_dropped"] == 1
+
+    # The canonical's active row survives unchanged
+    via_canonical = get_state("p05-interferometer")
+    active_next_focus = [
+        e
+        for e in via_canonical
+        if e.category == "status" and e.key == "next_focus"
+    ]
+    assert len(active_next_focus) == 1
+    assert active_next_focus[0].value == "Wave 2 trusted-operational"
+
+
+def test_apply_replaces_inactive_canonical_with_active_shadow(project_registry):
+    """Shadow is active, canonical has an inactive row at the same triple.
+
+    The shadow wins: canonical inactive row is deleted, shadow is
+    rekeyed into canonical's project_id. This covers the
+    cross-contamination case where the old alias path was used for
+    the live value while the canonical path had a stale row.
+    """
+    registry_path = project_registry(
+        ("p06-polisher", ["p06", "polisher"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p06")
+        canonical_id = _seed_shadow_project(conn, "p06-polisher")
+
+        # Canonical has a stale invalid row; shadow has the live value.
+        _seed_state_row(
+            conn,
+            canonical_id,
+            "decision",
+            "frame",
+            "Old frame (no longer current)",
+            status="invalid",
+        )
+        _seed_state_row(
+            conn,
+            shadow_id,
+            "decision",
+            "frame",
+            "kinematic mount frame",
+            status="active",
+        )
+
+        plan = mig.build_plan(conn, registry_path)
+        assert not plan.has_collisions
+        assert plan.counts()["state_historical_drops"] == 0
+
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["state_rows_replaced_inactive_canonical"] == 1
+
+    # The active shadow value now lives on the canonical row
+    via_canonical = get_state("p06-polisher")
+    frame_entries = [
+        e for e in via_canonical if e.category == "decision" and e.key == "frame"
+    ]
+    assert len(frame_entries) == 1
+    assert frame_entries[0].value == "kinematic mount frame"
+
+    # Confirm via raw SQL that the previously-inactive canonical row
+    # no longer exists
+    conn = _open_db_connection()
+    try:
+        stale = conn.execute(
+            "SELECT COUNT(*) AS c FROM project_state WHERE value = ?",
+            ("Old frame (no longer current)",),
+        ).fetchone()
+    finally:
+        conn.close()
+    assert stale["c"] == 0
+
+
+def test_apply_migrates_memories(project_registry):
+    registry_path = project_registry(
+        ("p04-gigabit", ["p04", "gigabit"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        _seed_memory_row(conn, "project", "lateral support uses GF-PTFE", "p04")
+        _seed_memory_row(conn, "preference", "I prefer descriptive commits", "gigabit")
+        plan = mig.build_plan(conn, registry_path)
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["memory_rows_rekeyed"] == 2
+
+    # Both memories should now read as living under the canonical id
+    from atocore.memory.service import get_memories
+
+    rows = get_memories(project="p04-gigabit", limit=50)
+    contents = {m.content for m in rows}
+    assert "lateral support uses GF-PTFE" in contents
+    assert "I prefer descriptive commits" in contents
+
+
+def test_apply_migrates_interactions(project_registry):
+    registry_path = project_registry(
+        ("p06-polisher", ["p06", "polisher"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        _seed_interaction_row(conn, "alias-keyed 1", "polisher")
+        _seed_interaction_row(conn, "alias-keyed 2", "p06")
+        plan = mig.build_plan(conn, registry_path)
+        summary = mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    assert summary["interaction_rows_rekeyed"] == 2
+
+    from atocore.interactions.service import list_interactions
+
+    rows = list_interactions(project="p06-polisher", limit=50)
+    prompts = {i.prompt for i in rows}
+    assert prompts == {"alias-keyed 1", "alias-keyed 2"}
+
+
+def test_apply_is_idempotent(project_registry):
+    """Running apply twice produces the same final state as running it once."""
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        _seed_state_row(conn, shadow_id, "status", "next_focus", "Wave 1")
+        _seed_memory_row(conn, "project", "m1", "p05")
+        _seed_interaction_row(conn, "i1", "p05")
+
+        # first apply
+        plan_a = mig.build_plan(conn, registry_path)
+        summary_a = mig.apply_plan(conn, plan_a)
+
+        # second apply: plan should be empty
+        plan_b = mig.build_plan(conn, registry_path)
+        assert plan_b.is_empty
+
+        # forcing a second apply on the empty plan via the function
+        # directly should also succeed as a no-op (caller normally
+        # has to pass --allow-empty through the CLI, but apply_plan
+        # itself doesn't enforce that — the refusal is in run())
+        summary_b = mig.apply_plan(conn, plan_b)
+    finally:
+        conn.close()
+
+    assert summary_a["state_rows_rekeyed"] == 1
+    assert summary_a["memory_rows_rekeyed"] == 1
+    assert summary_a["interaction_rows_rekeyed"] == 1
+    assert summary_b["state_rows_rekeyed"] == 0
+    assert summary_b["memory_rows_rekeyed"] == 0
+    assert summary_b["interaction_rows_rekeyed"] == 0
+
+
+def test_apply_refuses_with_integrity_errors(project_registry):
+    """If the projects table has two case-variant rows for the canonical id, refuse.
+
+    The projects.name column has a case-sensitive UNIQUE constraint,
+    so exact duplicates can't exist. But case-variant rows
+    ``p05-interferometer`` and ``P05-Interferometer`` can both
+    survive the UNIQUE constraint while both matching the
+    case-insensitive ``lower(name) = lower(?)`` lookup that the
+    migration uses to find the canonical row. That ambiguity
+    (which canonical row should dependents rekey into?) is exactly
+    the integrity failure the migration is guarding against.
+    """
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        _seed_shadow_project(conn, "p05-interferometer")
+        _seed_shadow_project(conn, "P05-Interferometer")
+        plan = mig.build_plan(conn, registry_path)
+        assert plan.integrity_errors
+        with pytest.raises(mig.MigrationRefused):
+            mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# reporting tests
+# ---------------------------------------------------------------------------
+
+
+def test_plan_to_json_dict_is_serializable(project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        _seed_state_row(conn, shadow_id, "status", "next_focus", "Wave 1")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    payload = mig.plan_to_json_dict(plan)
+    # Must be JSON-serializable
+    json_str = json.dumps(payload, default=str)
+    assert "p05-interferometer" in json_str
+    assert payload["counts"]["state_rekey_rows"] == 1
+
+
+def test_write_report_creates_file(tmp_path, project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    report_dir = tmp_path / "reports"
+    report_path = mig.write_report(
+        plan,
+        summary=None,
+        db_path=Path("/tmp/fake.db"),
+        registry_path=registry_path,
+        mode="dry-run",
+        report_dir=report_dir,
+    )
+    assert report_path.exists()
+    payload = json.loads(report_path.read_text(encoding="utf-8"))
+    assert payload["mode"] == "dry-run"
+    assert "plan" in payload
+
+
+def test_render_plan_text_on_empty_plan(project_registry):
+    registry_path = project_registry()  # empty
+    conn = _open_db_connection()
+    try:
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    text = mig.render_plan_text(plan)
+    assert "nothing to plan" in text.lower()
+
+
+def test_render_plan_text_on_collision(project_registry):
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        canonical_id = _seed_shadow_project(conn, "p05-interferometer")
+        _seed_state_row(conn, shadow_id, "status", "phase", "A")
+        _seed_state_row(conn, canonical_id, "status", "phase", "B")
+        plan = mig.build_plan(conn, registry_path)
+    finally:
+        conn.close()
+
+    text = mig.render_plan_text(plan)
+    assert "COLLISION" in text.upper()
+    assert "REFUSE" in text.upper() or "refuse" in text.lower()
+
+
+# ---------------------------------------------------------------------------
+# gap-closed companion test — the flip side of
+# test_legacy_alias_keyed_state_is_invisible_until_migrated in
+# test_project_state.py. After running this migration, the legacy row
+# IS reachable via the canonical id.
+# ---------------------------------------------------------------------------
+
+
+def test_legacy_alias_gap_is_closed_after_migration(project_registry):
+    """End-to-end regression test for the canonicalization gap.
+
+    Simulates the exact scenario from
+    test_legacy_alias_keyed_state_is_invisible_until_migrated in
+    test_project_state.py — a shadow projects row with a state row
+    pointing at it. Runs the migration. Verifies the state is now
+    reachable via the canonical id.
+    """
+    registry_path = project_registry(
+        ("p05-interferometer", ["p05", "interferometer"])
+    )
+
+    conn = _open_db_connection()
+    try:
+        shadow_id = _seed_shadow_project(conn, "p05")
+        _seed_state_row(
+            conn, shadow_id, "status", "legacy_focus", "Wave 1 ingestion"
+        )
+
+        # Before migration: the legacy row is invisible to get_state
+        # (this is the documented gap, covered in test_project_state.py)
+        assert all(
+            entry.value != "Wave 1 ingestion" for entry in get_state("p05")
+        )
+        assert all(
+            entry.value != "Wave 1 ingestion"
+            for entry in get_state("p05-interferometer")
+        )
+
+        # Run the migration
+        plan = mig.build_plan(conn, registry_path)
+        mig.apply_plan(conn, plan)
+    finally:
+        conn.close()
+
+    # After migration: the row is reachable via canonical AND alias
+    via_canonical = get_state("p05-interferometer")
+    via_alias = get_state("p05")
+    assert any(e.value == "Wave 1 ingestion" for e in via_canonical)
+    assert any(e.value == "Wave 1 ingestion" for e in via_alias)

tests/test_project_state.py

@@ -131,3 +131,139 @@ def test_format_project_state():
 def test_format_empty():
     """Test formatting empty state."""
     assert format_project_state([]) == ""
+
+
+# --- Alias canonicalization regression tests --------------------------------
+
+
+def test_set_state_canonicalizes_alias(project_registry):
+    """Writing state via an alias should land under the canonical project id.
+
+    Regression for codex's P1 finding: previously /project/state with
+    project="p05" created a separate alias row that later context builds
+    (which canonicalize the hint) would never see.
+    """
+    project_registry(("p05-interferometer", ["p05", "interferometer"]))
+
+    set_state("p05", "status", "next_focus", "Wave 2 ingestion")
+
+    # The state must be reachable via every alias AND the canonical id
+    via_alias = get_state("p05")
+    via_canonical = get_state("p05-interferometer")
+    via_other_alias = get_state("interferometer")
+
+    assert len(via_alias) == 1
+    assert len(via_canonical) == 1
+    assert len(via_other_alias) == 1
+    # All three reads return the same row id (no fragmented duplicates)
+    assert via_alias[0].id == via_canonical[0].id == via_other_alias[0].id
+    assert via_canonical[0].value == "Wave 2 ingestion"
+
+
+def test_get_state_canonicalizes_alias_after_canonical_write(project_registry):
+    """Reading via an alias should find state written under the canonical id."""
+    project_registry(("p04-gigabit", ["p04", "gigabit"]))
+
+    set_state("p04-gigabit", "status", "phase", "Phase 1 baseline")
+    via_alias = get_state("gigabit")
+
+    assert len(via_alias) == 1
+    assert via_alias[0].value == "Phase 1 baseline"
+
+
+def test_invalidate_state_canonicalizes_alias(project_registry):
+    """Invalidating via an alias should hit the canonical row."""
+    project_registry(("p06-polisher", ["p06", "polisher"]))
+
+    set_state("p06-polisher", "decision", "frame", "kinematic mounts")
+    success = invalidate_state("polisher", "decision", "frame")
+
+    assert success is True
+    active = get_state("p06-polisher")
+    assert len(active) == 0
+
+
+def test_unregistered_project_state_still_works(project_registry):
+    """Hand-curated state for an unregistered project must still round-trip.
+
+    Backwards compatibility with state created before the project
+    registry existed: resolve_project_name returns the input unchanged
+    when the registry has no record, so the raw name is used as-is.
+    """
+    project_registry()  # empty registry
+
+    set_state("orphan-project", "status", "phase", "Standalone")
+    entries = get_state("orphan-project")
+    assert len(entries) == 1
+    assert entries[0].value == "Standalone"
+
+
+def test_legacy_alias_keyed_state_is_invisible_until_migrated(project_registry):
+    """Documents the compatibility gap from project-identity-canonicalization.md.
+
+    Rows that were written under a registered alias BEFORE the
+    canonicalization landed in fb6298a are stored in the projects
+    table under the alias name (not the canonical id). Every read
+    path now canonicalizes to the canonical id, so those legacy
+    rows become invisible.
+
+    This test simulates the legacy state by inserting a shadow
+    project row and a state row that points at it via raw SQL,
+    bypassing set_state() which now canonicalizes. Then it
+    verifies the canonicalized get_state() does NOT find the
+    legacy row.
+
+    When the legacy alias migration script lands (see the open
+    follow-ups in docs/architecture/project-identity-canonicalization.md),
+    this test must be inverted: after running the migration the
+    legacy state should be reachable via the canonical project,
+    not invisible. The migration is required before engineering
+    V1 ships.
+    """
+    import uuid
+
+    from atocore.models.database import get_connection
+
+    project_registry(("p05-interferometer", ["p05", "interferometer"]))
+
+    # Simulate a pre-fix legacy row by writing directly under the
+    # alias name. This is what the OLD set_state would have done
+    # before fb6298a added canonicalization.
+    legacy_project_id = str(uuid.uuid4())
+    legacy_state_id = str(uuid.uuid4())
+    with get_connection() as conn:
+        conn.execute(
+            "INSERT INTO projects (id, name, description) VALUES (?, ?, ?)",
+            (legacy_project_id, "p05", "shadow row created before canonicalization"),
+        )
+        conn.execute(
+            "INSERT INTO project_state "
+            "(id, project_id, category, key, value, source, confidence) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                legacy_state_id,
+                legacy_project_id,
+                "status",
+                "legacy_focus",
+                "Wave 1 ingestion",
+                "pre-canonicalization",
+                1.0,
+            ),
+        )
+
+    # The canonicalized read path looks under "p05-interferometer"
+    # and cannot see the legacy row. THIS IS THE GAP.
+    via_alias = get_state("p05")
+    via_canonical = get_state("p05-interferometer")
+    assert all(entry.value != "Wave 1 ingestion" for entry in via_alias)
+    assert all(entry.value != "Wave 1 ingestion" for entry in via_canonical)
+
+    # The legacy row is still in the database — it's just unreachable
+    # from the canonicalized read path. The migration script (open
+    # follow-up) is what closes the gap.
+    with get_connection() as conn:
+        row = conn.execute(
+            "SELECT value FROM project_state WHERE id = ?", (legacy_state_id,)
+        ).fetchone()
+    assert row is not None
+    assert row["value"] == "Wave 1 ingestion"

tests/test_reinforcement.py

@@ -6,6 +6,8 @@ from atocore.interactions.service import record_interaction
 from atocore.main import app
 from atocore.memory.reinforcement import (
     DEFAULT_CONFIDENCE_DELTA,
+    _stem,
+    _tokenize,
     reinforce_from_interaction,
 )
 from atocore.memory.service import (
@@ -314,3 +316,231 @@ def test_api_post_interactions_accepts_reinforce_false(tmp_data_dir):
     reloaded = [m for m in get_memories(memory_type="preference", limit=20) if m.id == mem.id][0]
     assert reloaded.confidence == 0.5
     assert reloaded.reference_count == 0
+
+
+# --- alias canonicalization end-to-end -------------------------------------
+
+
+def test_reinforcement_works_when_capture_uses_alias(project_registry):
+    """End-to-end: capture under an alias, seed memory under canonical id,
+    verify reinforcement still finds and bumps the memory.
+
+    Regression for codex's P2 finding: previously interaction.project
+    was stored verbatim and reinforcement queried memories using that
+    raw value, so capturing under "p05" while memories live under
+    "p05-interferometer" silently missed everything.
+    """
+    init_db()
+    project_registry(("p05-interferometer", ["p05", "interferometer"]))
+
+    # Seed an active memory under the CANONICAL id
+    mem = create_memory(
+        memory_type="project",
+        content="the lateral support pads use GF-PTFE for thermal stability",
+        project="p05-interferometer",
+        confidence=0.5,
+    )
+
+    # Capture an interaction under the ALIAS — this is the bug case
+    record_interaction(
+        prompt="status update",
+        response=(
+            "Quick note: the lateral support pads use GF-PTFE for thermal "
+            "stability and that's still the current selection."
+        ),
+        project="p05",
+    )
+
+    # The seeded memory should have been reinforced
+    reloaded = [
+        m
+        for m in get_memories(memory_type="project", project="p05-interferometer", limit=20)
+        if m.id == mem.id
+    ][0]
+    assert reloaded.confidence > 0.5
+    assert reloaded.reference_count == 1
+
+
+def test_get_memories_filter_by_alias(project_registry):
+    """Filtering memories by an alias should find rows stored under canonical."""
+    init_db()
+    project_registry(("p04-gigabit", ["p04", "gigabit"]))
+
+    create_memory(memory_type="project", content="m1", project="p04-gigabit")
+    create_memory(memory_type="project", content="m2", project="gigabit")
+
+    via_alias = get_memories(memory_type="project", project="p04")
+    via_canonical = get_memories(memory_type="project", project="p04-gigabit")
+
+    assert len(via_alias) == 2
+    assert len(via_canonical) == 2
+    assert {m.content for m in via_alias} == {"m1", "m2"}
+
+
+# --- token-overlap matcher: unit tests -------------------------------------
+
+
+def test_stem_folds_s_ed_ing():
+    assert _stem("prefers") == "prefer"
+    assert _stem("preferred") == "prefer"
+    assert _stem("services") == "service"
+    assert _stem("processing") == "process"
+    # Short words must not be over-stripped
+    assert _stem("red") == "red"  # 3 chars, don't strip "ed"
+    assert _stem("bus") == "bus"  # 3 chars, don't strip "s"
+    assert _stem("sing") == "sing"  # 4 chars, don't strip "ing"
+    assert _stem("being") == "being"  # 5 chars, "ing" strip leaves "be" (2) — too short
+
+
+def test_tokenize_removes_stop_words():
+    tokens = _tokenize("the quick brown fox jumps over the lazy dog")
+    assert "the" not in tokens
+    assert "quick" in tokens
+    assert "brown" in tokens
+    assert "fox" in tokens
+    assert "dog" in tokens
+    # "over" has len 4, not a stop word → kept (stemmed: "over")
+    assert "over" in tokens
+
+
+# --- token-overlap matcher: paraphrase matching ----------------------------
+
+
+def test_reinforce_matches_paraphrase_prefers_vs_prefer(tmp_data_dir):
+    """The canonical rebase case from phase9-first-real-use.md."""
+    init_db()
+    mem = create_memory(
+        memory_type="preference",
+        content="prefers rebase-based workflows because history stays linear",
+        confidence=0.5,
+    )
+    interaction = _make_interaction(
+        response=(
+            "I prefer rebase-based workflows because the history stays "
+            "linear and reviewers have an easier time."
+        ),
+    )
+    results = reinforce_from_interaction(interaction)
+    assert any(r.memory_id == mem.id for r in results)
+
+
+def test_reinforce_matches_paraphrase_with_articles_and_ed(tmp_data_dir):
+    init_db()
+    mem = create_memory(
+        memory_type="preference",
+        content="preferred structured logging across all backend services",
+        confidence=0.5,
+    )
+    interaction = _make_interaction(
+        response=(
+            "I set up structured logging across all the backend services, "
+            "which the team prefers for consistency."
+        ),
+    )
+    results = reinforce_from_interaction(interaction)
+    assert any(r.memory_id == mem.id for r in results)
+
+
+def test_reinforce_rejects_low_overlap(tmp_data_dir):
+    init_db()
+    mem = create_memory(
+        memory_type="preference",
+        content="always uses Python for data processing scripts",
+        confidence=0.5,
+    )
+    interaction = _make_interaction(
+        response=(
+            "The CI pipeline runs on Node.js and deploys to Kubernetes "
+            "using Helm charts."
+        ),
+    )
+    results = reinforce_from_interaction(interaction)
+    assert all(r.memory_id != mem.id for r in results)
+
+
+def test_reinforce_matches_at_70_percent_threshold(tmp_data_dir):
+    """Exactly 7 of 10 content tokens present → should match."""
+    init_db()
+    # After stop-word removal and stemming, this has 10 tokens:
+    # alpha, bravo, charlie, delta, echo, foxtrot, golf, hotel, india, juliet
+    mem = create_memory(
+        memory_type="preference",
+        content="alpha bravo charlie delta echo foxtrot golf hotel india juliet",
+        confidence=0.5,
+    )
+    # Echo 7 of 10 tokens (70%) plus some noise
+    interaction = _make_interaction(
+        response="alpha bravo charlie delta echo foxtrot golf noise words here",
+    )
+    results = reinforce_from_interaction(interaction)
+    assert any(r.memory_id == mem.id for r in results)
+
+
+def test_reinforce_long_memory_matches_on_absolute_overlap(tmp_data_dir):
+    """A paragraph-length memory should reinforce when the response
+    echoes a substantive subset of its distinctive tokens, even though
+    the overlap fraction stays well under 70%."""
+    init_db()
+    mem = create_memory(
+        memory_type="project",
+        content=(
+            "Interferometer architecture: a folded-beam configuration with a "
+            "fixed horizontal interferometer, a forty-five degree fold mirror, "
+            "a six-DOF CGH stage, and the mirror on its own tilting platform. "
+            "The fold mirror redirects the beam while the CGH shapes the wavefront."
+        ),
+        project="p05-interferometer",
+        confidence=0.5,
+    )
+    interaction = _make_interaction(
+        project="p05-interferometer",
+        response=(
+            "For the interferometer we keep the folded-beam layout: horizontal "
+            "interferometer, fold mirror at forty-five degrees, CGH stage with "
+            "six DOF, and the mirror sitting on its tilting platform. The fold "
+            "mirror redirects the beam and the CGH shapes the wavefront."
+        ),
+    )
+    results = reinforce_from_interaction(interaction)
+    assert any(r.memory_id == mem.id for r in results)
+
+
+def test_reinforce_long_memory_rejects_thin_overlap(tmp_data_dir):
+    """Long memory + a response that only brushes a few generic terms
+    must NOT reinforce — otherwise the reflection loop rots."""
+    init_db()
+    mem = create_memory(
+        memory_type="project",
+        content=(
+            "Polisher control system executes approved controller jobs, "
+            "enforces state transitions and interlocks, supports pause "
+            "resume and abort, and records auditable run logs while "
+            "never reinterpreting metrology or inventing new strategies."
+        ),
+        project="p06-polisher",
+        confidence=0.5,
+    )
+    interaction = _make_interaction(
+        project="p06-polisher",
+        response=(
+            "I updated the polisher docs and fixed a typo in the run logs section."
+        ),
+    )
+    results = reinforce_from_interaction(interaction)
+    assert all(r.memory_id != mem.id for r in results)
+
+
+def test_reinforce_rejects_below_70_percent(tmp_data_dir):
+    """Only 6 of 10 content tokens present (60%) → should NOT match."""
+    init_db()
+    mem = create_memory(
+        memory_type="preference",
+        content="alpha bravo charlie delta echo foxtrot golf hotel india juliet",
+        confidence=0.5,
+    )
+    # Echo 6 of 10 tokens (60%) plus noise
+    interaction = _make_interaction(
+        response="alpha bravo charlie delta echo foxtrot noise words here only",
+    )
+    results = reinforce_from_interaction(interaction)
+    assert all(r.memory_id != mem.id for r in results)