diff --git a/DEV-LEDGER.md b/DEV-LEDGER.md index 12e6c49..d972c22 100644 --- a/DEV-LEDGER.md +++ b/DEV-LEDGER.md @@ -149,6 +149,7 @@ One branch `codex/extractor-eval-loop` for Day 1-5, a second `codex/retrieval-ha ## Recent Decisions +- **2026-04-22** **Wiki reorg reframed as read-only operator orientation.** The earlier `docs/plans/wiki-reorg-plan.md` (5 additions W-1…W-5 adding `/wiki/interactions`, `/wiki/memories`, project-page restructure, recent feed, topnav exposure) is **superseded** and marked as such in-tree. Successor is `docs/plans/operator-orientation-plan.md` in the `ATOCore-clean` workspace: no `/wiki` surface, no Human Mirror implementation, no new API routes, no schema changes, no new source of truth. First deliverables are docs-only: `docs/where-things-live.md` (operator map of source/staged/machine/registry/trusted-state/memories/interactions/logs/backups with explicit edit-vs-don't-edit boundaries) and `docs/operator-home.md` (short daily starting page indexing those docs + a 4-command read-only orientation sequence). README and operations.md link both. Optional future work (`project-overview` and `memory-candidates` CLI helpers over existing endpoints) is gated on the docs proving useful in practice. *Proposed by:* Antoine. *Drafted by:* Claude. *Pending Codex review.* - **2026-04-22** **V1-0 done: approved, merged, deployed, prod backfilled.** Codex pulled `f16cd52`, re-ran the two original probes (both pass), re-ran the three targeted regression suites (all pass). Squash-merged to main as `2712c5d`. Dalidou deployed via canonical deploy script; `/health` reports build_sha=`2712c5d2d03cb2a6af38b559664afd1c4cd0e050`, status=ok. Validated backup snapshot taken at `/srv/storage/atocore/backups/snapshots/20260422T190624Z` before backfill. Prod backfill: `--dry-run` found 31 active/superseded entities with no provenance; list reviewed and sane; live run updated 31 rows via the default `hand_authored=1` flag path; follow-up dry-run returned 0 rows remaining. Residual logged as R14 (P2): `POST /entities/{id}/promote` HTTP route doesn't translate the new service-layer `ValueError` into a 400 — legacy bad candidate promotes via the API return 500 instead. Does not block V1-0 acceptance. V1-0 closed. Next: V1-A (Q-001 subsystem-scoped variant + Q-6 integration). V1-A holds until the soak window ends ~2026-04-26 and the 100-memory density target is hit. *Approved + landed by:* Codex. *Ratified by:* Antoine. - **2026-04-22** **Engineering V1 Completion Plan — Codex sign-off (third round)**. Codex's third-round audit closed the remaining five open questions with concrete resolutions, patched inline in `docs/plans/engineering-v1-completion-plan.md`: (1) F-7 row rewritten with ground truth — schema + preserve-original + test coverage already exist (`graduated_to_entity_id` at `database.py:143-146`, `graduated` status in memory service, promote hook at `service.py:354-356,389-451`, tests at `test_engineering_v1_phase5.py:67-90`); **real gaps** are missing direct `POST /memory/{id}/graduate` route and spec's `knowledge→Fact` mismatch (no `fact` entity type exists; reconcile to `parameter` or similar); V1-E 2 → **3–4 days**; (2) Q-5 determinism reframed — don't stabilize the call to `datetime.now()`, inject regenerated timestamp + checksum as renderer inputs, remove DB iteration ordering dependencies; V1-D scope updated; (3) `project` vs `project_id` — doc note only, no rename, resolved; (4) total estimate 16.5–17.5 → **17.5–19.5 focused days** with calendar buffer on top; (5) "Minions" must not be canonized in D-3 release notes — neutral wording ("queued background processing / async workers") only. **Agreement reached**: Claude + Codex + Antoine aligned. V1-0 is ready to start once the current pipeline soak window ends (~2026-04-26) and the 100-memory density target is hit. *Patched by:* Codex. *Signed off by:* Codex ("with those edits, I'd sign off on the five questions"). *Accepted by:* Antoine. *Executor (V1-0 onwards):* Claude. - **2026-04-22** **Engineering V1 Completion Plan revised per Codex second-round file-level audit** — three findings folded in, all with exact file:line refs from Codex: (1) F-1 downgraded from ✅ to 🟡 — `extractor_version` and `canonical_home` missing from `Entity` dataclass and `entities` table per `engineering-v1-acceptance.md:45`; V1-0 scope now adds both fields via additive migration + doc note that `project` IS `project_id` per "fields equivalent to" spec wording; (2) F-2 replaced with ground-truth per-query status: 9 of 20 v1-required queries done (Q-004/Q-005/Q-006/Q-008/Q-009/Q-011/Q-013/Q-016/Q-017), 1 partial (Q-001 needs subsystem-scoped variant), 10 missing (Q-002/003/007/010/012/014/018/019/020); V1-A scope shrank to Q-001 shape fix + Q-6 integration (pillar queries already implemented); V1-C closes the 8 remaining new queries + Q-020 deferred to V1-D; (3) F-5 reframed — generic `conflicts` + `conflict_members` schema already present at `database.py:190`, no migration needed; divergence is detector body (per-type dispatch needs generalization) + routes (`/admin/conflicts/*` needs `/conflicts/*` alias). Total revised to 16.5–17.5 days, ~60 tests. Plan: `docs/plans/engineering-v1-completion-plan.md` at commit `ce3a878` (Codex pulled clean). Three of Codex's eight open questions now answered; remaining: F-7 graduation depth, mirror determinism, `project` rename question, velocity calibration, minions naming. *Proposed by:* Claude. *Reviewed by:* Codex (two rounds). diff --git a/docs/plans/wiki-reorg-plan.md b/docs/plans/wiki-reorg-plan.md new file mode 100644 index 0000000..9455546 --- /dev/null +++ b/docs/plans/wiki-reorg-plan.md @@ -0,0 +1,216 @@ +# Wiki Reorg Plan — Human-Readable Navigation of AtoCore State + +> **SUPERSEDED — 2026-04-22.** Do not implement this plan. It has been +> replaced by the read-only operator orientation work at +> `docs/plans/operator-orientation-plan.md` (in the `ATOCore-clean` +> workspace). The successor reframes the problem as orientation over +> existing APIs and docs rather than a new `/wiki` surface, and drops +> interaction browser / memory index / project-page restructure from +> scope. Nothing below should be picked up as a work item. Kept in tree +> for context only. + +**Date:** 2026-04-22 +**Author:** Claude (after walking the live wiki at `http://dalidou:8100/wiki` +and reading `src/atocore/engineering/wiki.py` + `/wiki/*` routes in +`src/atocore/api/routes.py`) +**Status:** SUPERSEDED (see banner above). Previously: Draft, pending Codex review +**Scope boundary:** This plan does NOT touch Inbox / Global / Emerging. +Those three surfaces stay exactly as they are today — the registration +flow and scope semantics around them are load-bearing and out of scope +for this reorg. + +--- + +## Position + +The wiki is Layer 3 of the engineering architecture (Human Mirror — +see `docs/architecture/engineering-knowledge-hybrid-architecture.md`). +It is a **derived view** over the same database the LLM reads via +`atocore_context` / `atocore_search`. There is no parallel store; if a +fact is in the DB it is reachable from the wiki. + +The user-facing problem is not representation, it is **findability and +structure**. Content the operator produced (proposals, decisions, +constraints, captured conversations) is in the DB but is not reachable +along a natural human reading path. Today the only routes to it are: + +- typing the right keyword into `/wiki/search` +- remembering which project it lived under and scrolling the auto- + generated mirror markdown on `/wiki/projects/{id}` +- the homepage "What the brain is doing" strip, which shows counts of + audit actions but no content + +There is no "recent conversations" view, no memory index, no way to +browse by memory type (decision vs preference vs episodic), and the +topnav only exposes Home / Activity / Triage / Dashboard. + +## Goal + +Make the wiki a surface the operator actually uses to answer three +recurring questions: + +1. **"Where did I say / decide / propose X?"** — find a memory or + interaction by topic, not by exact-string search. +2. **"What is the current state of project Y?"** — read decisions, + constraints, and open questions as distinct sections, not as one + wall of auto-generated markdown. +3. **"What happened in the system recently, and what does it mean?"** + — a human-meaningful recent feed (captures, promotions, decisions + recorded), not a count of audit-action names. + +Success criterion: for each of the three questions above, a first-time +visitor reaches a useful answer in **≤ 2 clicks from `/wiki`**. + +## Non-goals + +- No schema changes. All data already exists. +- No change to ingestion, extraction, promotion, or the trust rules. +- No change to Inbox / Global / Emerging surfaces or semantics. +- No change to `/admin/triage` or `/admin/dashboard`. +- No change to the `atocore_context` / `atocore_search` LLM-facing APIs. +- No new storage. Every new page is a new render function over existing + service-layer calls. + +## What it will do + +Five additions, in priority order. Each is independently mergeable and +independently revertable. + +### W-1 — Interaction browser: `/wiki/interactions` + +The DB holds 234 captured interactions (per ledger `2026-04-22`). None +are readable in the wiki. Add a paginated list view and a detail view. + +- `/wiki/interactions?project=&client=&since=` — list, newest first, + showing timestamp, client (claude-code / openclaw / test), inferred + project, and the first ~160 chars of the user prompt. +- `/wiki/interactions/{id}` — full prompt + response, plus any + candidate / active memories extracted from it (back-link from the + memory → interaction relation if present, else a "no extractions" + note). +- Filters: project (multi), client, date range, "has extractions" boolean. + +Answers Q1 ("where did I say X") by giving the user a time-ordered +stream of their own conversations, not just extracted summaries. + +### W-2 — Memory index: `/wiki/memories` + +Today `/wiki/memories/{id}` exists but there is no list view. Add one. + +- `/wiki/memories?project=&type=&status=&tag=` — filterable list. + Status defaults to `active`. Types: decision, preference, episodic, + knowledge, identity, adaptation. +- Faceted counts in the sidebar (e.g. "decision: 14 · preference: 7"). +- Each row links to `/wiki/memories/{id}` and, where present, the + originating interaction. + +### W-3 — Project page restructure (tabbed, not flat) + +`/wiki/projects/{id}` today renders the full mirror markdown in one +scroll. Restructure to tabs (or anchored sections, same thing +semantically) over the data already produced by +`generate_project_overview`: + +- **Overview** — stage, client, type, description, headline state. +- **Decisions** — memories of type `decision` for this project. +- **Constraints** — project_state entries in the `constraints` category. +- **Proposals** — memories tagged `proposal` or type `preference` with + proposal semantics (exact filter TBD during W-3; see Open Questions). +- **Entities** — current list, already rendered inline today. +- **Memories** — all memories, reusing the W-2 list component filtered + to this project. +- **Timeline** — interactions for this project, reusing W-1 filtered + to this project. + +No new data is produced; this is purely a slicing change. + +### W-4 — Recent feed on homepage + +Replace the current "What the brain is doing" strip (which shows audit +action counts) with a **content** feed: the last N events that a human +cares about — + +- new active memory (not candidate) +- memory promoted candidate → active +- state entry added / changed +- new registered project +- interaction captured (optional, may be noisy — gate behind a toggle) + +Each feed row links to the thing it describes. The audit-count strip +can move to `/wiki/activity` where the full audit timeline already lives. + +### W-5 — Topnav exposure + +Surface the new pages in the topnav so they are discoverable: + +Current: `🏠 Home · 📡 Activity · 🔀 Triage · 📊 Dashboard` +Proposed: `🏠 Home · 💬 Interactions · 🧠 Memories · 📡 Activity · 🔀 Triage · 📊 Dashboard` + +Domain pages (`/wiki/domains/{tag}`) stay reachable via tag chips on +memory rows, as today — no new topnav entry for them. + +## Outcome + +- Every captured interaction is readable in the wiki, with a clear + path from interaction → extracted memories and back. +- Memories are browsable without knowing a keyword in advance. +- A project page separates decisions, constraints, and proposals + instead of interleaving them in auto-generated markdown. +- The homepage tells the operator what **content** is new, not which + audit action counters incremented. +- Nothing in the Inbox / Global / Emerging flow changes. +- Nothing the LLM reads changes. + +## Non-outcomes (explicitly) + +- This plan does not improve retrieval quality. It does not touch the + extractor, ranking, or harness. +- This plan does not change what is captured or when. +- This plan does not replace `/admin/triage`. Candidate review stays there. + +## Sequencing + +1. **W-1 first.** Interaction browser is the biggest findability win + and has no coupling to memory code. +2. **W-2 next.** Memory index reuses list/filter infra from W-1. +3. **W-3** depends on W-2 (reuses the memory list component). +4. **W-4** is independent; can land any time after W-1. +5. **W-5** lands last so topnav only exposes pages that exist. + +Each step ships with at least one render test (HTML contains expected +anchors / row counts against a seeded fixture), following the pattern +already in `tests/engineering/` for existing wiki renders. + +## Risk & reversibility + +- All additions are new routes / new render functions. Reverting any + step is a file delete + a topnav edit. +- Project page restructure (W-3) is the only edit to an existing + surface. Keep the flat-markdown render behind a query flag + (`?layout=flat`) for one release so regressions are observable. +- No DB migrations. No service-layer signatures change. + +## Open questions for Codex + +1. **"Proposal" as a first-class filter** (W-3) — is this a memory type, + a domain tag, a structural field we should add, or should it stay + derived by filter? Current DB has no explicit proposal type; we'd be + inferring from tags/content. If that inference is unreliable, W-3's + Proposals tab becomes noise. +2. **Interaction → memory back-link** (W-1) — does the current schema + already record which interaction an extracted memory came from? If + not, is exposing that link in the wiki worth a schema addition, or + should W-1 ship without it? +3. **Recent feed noise floor** (W-4) — should every captured + interaction appear in the feed, or only interactions that produced + at least one candidate memory? The former is complete but may drown + out signal at current capture rates (~10/day). +4. **Ordering vs V1 Completion track** — should any of this land before + V1-A (currently gated on soak ~2026-04-26 + density 100+), or is it + strictly after V1 closes? + +## Workspace note + +Canonical dev workspace is `C:\Users\antoi\ATOCore` (per `CLAUDE.md`). +Any Codex audit of this plan should sync from `origin/main` at or after +`2712c5d` before reviewing.