docs: land wiki-reorg supersession record (was in working tree)
- DEV-LEDGER Recent Decisions: the wiki-reorg plan drafted earlier 2026-04-22 is superseded by a read-only operator-orientation plan in the ATOCore-clean workspace. Decision authored by Antoine, drafted by Claude in a parallel session. - docs/plans/wiki-reorg-plan.md: new file, carries a SUPERSEDED banner at the top pointing to operator-orientation-plan.md. Kept in-tree for historical context; explicitly marked do-not-implement. Syncing working-tree state — no authoring from this session beyond committing what was already on disk. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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).
|
||||
|
||||
216
docs/plans/wiki-reorg-plan.md
Normal file
216
docs/plans/wiki-reorg-plan.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user