| F-1 | 12 V1 entity types, 4 relationship families, shared header fields, 4-state lifecycle | 🟡 partial (per Codex 2026-04-22 audit) | `service.py:16-36` has 16 types (superset of V1's 12), `service.py:38-62` has 18 relationship types, `service.py:64` statuses, `Entity` dataclass at line 67. **Gaps vs `engineering-v1-acceptance.md:45`**: `extractor_version` missing from dataclass and `entities` table; `canonical_home` missing from dataclass and table; `project` field is the project identifier but not named `project_id` as spec uses — spec says "fields equivalent to" so naming flexibility is allowed but needs an explicit doc note. Remediation lands in V1-0 |
| F-2 | All v1-required Q-001 through Q-020 implemented, with provenance where required | 🟡 partial (per Codex 2026-04-22 per-function audit) | **Ground truth from per-function read of `queries.py` + `routes.py:2092+`:** Q-001 partial (`system_map()` returns project-wide tree, not the catalog's subsystem-scoped `GET /entities/Subsystem/<id>?expand=contains` shape per `engineering-query-catalog.md:71`); Q-002 missing; Q-003 missing; Q-004 done (covered by `system_map()`); Q-005 done (`requirements_for()`); Q-006 done (`orphan_requirements()`); Q-007 missing; Q-008 done (`decisions_affecting()`); Q-009 done (`risky_decisions()`); Q-010 missing; Q-011 done (`unsupported_claims()`); Q-012 missing; Q-013 done (`recent_changes()`); Q-014 missing; Q-016 done (`impact_analysis()`); Q-017 done (`evidence_chain()`); Q-018 missing; Q-019 missing; Q-020 missing (mirror route in spec shape). **Net: 9 of 20 v1-required queries done, 1 partial (Q-001), 10 missing.** Q-015 is v1-stretch, out of scope |
| F-3 | `POST /ingest/kb-cad/export` and `POST /ingest/kb-fem/export` | ❌ missing | No `/ingest/kb-cad` or `/ingest/kb-fem` route in `api/routes.py`. No schema doc under `docs/architecture/` |
| F-4 | Candidate review queue end-to-end (list/promote/reject/edit) | 🟡 partial for entities | Memory side shipped in Phase 9 Commit C. Entity side has `promote_entity`, `supersede_entity`, `invalidate_active_entity` but reject path and editable-before-promote may not match spec shape. Need to verify `GET /entities?status=candidate` returns spec shape |
| F-6 | Mirror: `/mirror/{project}/overview`, `/decisions`, `/subsystems/{id}`, `/regenerate`; files under `/srv/storage/atocore/data/mirror/`; disputed + curated markers; deterministic output | 🟡 partial | `mirror.py` has `generate_project_overview` with header/state/system/decisions/requirements/materials/vendors/memories/footer sections. API at `/projects/{project_name}/mirror` and `.html`. **Gaps**: no separate `/mirror/{project}/decisions` or `/mirror/{project}/subsystems/{id}` routes, no `POST /regenerate` endpoint, no debounced-async-on-write, no daily refresh, no `⚠ disputed` markers wired to conflicts, no `(curated)` override annotations verified, no golden-file test for determinism |
| F-7 | Memory→entity graduation: `POST /memory/{id}/graduate` + `graduated` status + forward pointer + original preserved | 🟡 partial (per Codex 2026-04-22 third-round audit) | `_graduation_prompt.py` exists; `scripts/graduate_memories.py` creates entity candidates from active memories; `database.py:143-146` adds `graduated_to_entity_id`; `memory.service` already has a `graduated` status; `service.py:354-356,389-451` preserves the original memory and marks it `graduated` with a forward pointer on entity promote; `tests/test_engineering_v1_phase5.py:67-90` covers that flow. **Gaps vs spec**: no direct `POST /memory/{id}/graduate` route yet (current surface is batch/admin-driven via `/admin/graduation/request`); no explicit acceptance tests yet for `adaptation→decision` and `project→requirement`; spec wording `knowledge→Fact` does not match the current ontology (there is no `fact` entity type in `service.py` / `_graduation_prompt.py`) and should be reconciled to an actual V1 type such as `parameter` or another ontology-defined entity. |
| F-8 | Every active entity has `source_refs`; Q-017 returns ≥1 row for every active entity | 🟡 partial | `Entity.source_refs` field exists; Q-017 (`evidence_chain`) exists. **Gap**: is provenance enforced at write time (not NULL), or just encouraged? Per spec it must be mandatory |
### Quality (Q-1 through Q-6)
| ID | Criterion | Status | Evidence |
|----|-----------|--------|----------|
| Q-1 | All pre-V1 tests still pass | ✅ presumed | 533 tests passing per DEV-LEDGER line 12 |
| Q-2 | Each F criterion has happy-path + error-path test, <10s each, <30s total | 🟡 partial | 16 + 15 + 15 + 12 = 58 tests in engineering/queries/v1-phase5/patch files. Need to verify coverage of each F criterion one-for-one |
| Q-3 | Conflict invariants enforced by tests (contradictory imports produce conflict, can't promote both, flag-never-block) | 🟡 partial | Tests likely exist in `test_engineering_v1_phase5.py` — verify explicit coverage of the three invariants |
| Q-4 | Trust hierarchy enforced by tests (candidates never in context, active-only reinforcement, no auto-project-state writes) | 🟡 partial | Phase 9 Commit B covered the memory side; verify entity side has equivalent tests |
| Q-5 | Mirror has golden-file test, deterministic output | ❌ missing | No golden file seen; mirror output reads wall-clock time inside `_footer()` (`mirror.py:320-327`). Determinism should come from injecting the regenerated timestamp/checksum as inputs to the renderer and pinning them in the golden-file test, not from calling `datetime.now()` inside render code |
| Q-6 | Killer correctness queries pass against seeded real-ish data (5 seed cases per Q-006/Q-009/Q-011) | ❌ likely missing | No fixture file named for this seen. The three queries exist but there's no evidence of the single integration test described in Q-6 |
### Operational (O-1 through O-5)
| ID | Criterion | Status | Evidence |
|----|-----------|--------|----------|
| O-1 | Schema migration additive, idempotent, tested against fresh + prod-copy DB | 🟡 presumed | `_apply_migrations` pattern is in use per CLAUDE.md sessions; tables exist. Need one confirmation run against a Dalidou backup copy |
| O-2 | Backup includes new tables; full restore drill passes; post-restore Q-001 works | ❌ not done | No evidence a restore drill has been run on V1 entity state. `docs/backup-restore-procedure.md` exists but drill is an explicit V1 prerequisite |
| O-3 | Performance bounds: write <100ms p99, query <500ms p99 at 1000 entities, mirror <5s per project | 🟡 unmeasured | 35 entities in system — bounds unmeasured at scale. Spec says "sanity-checked, not benchmarked", so this is a one-off manual check |
| O-4 | No new manual ops burden | 🟡 | Mirror regen auto-triggers not wired yet (see F-6 gap) — they must be wired for O-4 to pass |
| O-5 | Phase 9 reflection loop unchanged for identity/preference/episodic | ✅ presumed | `memory-vs-entities.md` says these three types don't interact with engineering layer. No recent change to memory extractor for these types |
### Documentation (D-1 through D-4)
| ID | Criterion | Status | Evidence |
|----|-----------|--------|----------|
| D-1 | 12 per-entity-type spec docs under `docs/architecture/entities/` | ❌ missing | No `docs/architecture/entities/` folder |
| D-2 | `kb-cad-export-schema.md` + `kb-fem-export-schema.md` | ❌ missing | No such files in `docs/architecture/` |
| D-3 | `docs/v1-release-notes.md` | ❌ missing | Not written yet (appropriately — it's written when V1 is done) |
| D-4 | `master-plan-status.md` + `current-state.md` updated with V1 completion | ❌ not yet | `master-plan-status.md:179` still has V1 under **Next** |
- **Functional:** 0/8 ✅, 7/8 🟡 partial (F-1 downgraded from ✅ — two header fields missing; F-2 through F-7 partial), 1/8 ❌ missing (F-3 ingest endpoints) → the entity layer shape is real but not yet spec-clean; write-time invariants come first, then everything builds on stable invariants
- Branch strategy: one branch per phase (V1-0 → V1-F), each squash-merged
to main after Codex review. Phases sequential because each builds on
the previous. **V1-0 is a hard prerequisite for all later phases** —
nothing starts until V1-0 lands.
---
## Sequencing with the `master-plan-status.md` Now list
The **Now** list from master-plan-status.md:159-169 is:
1. Observe the enhanced pipeline (1 week soak — first F4 confidence decay
run was 2026-04-19 per Trusted State, so soak window ends ~2026-04-26)
2. Knowledge density — batch extract over 234 interactions, target 100+
active memories (currently 84)
3. Multi-model triage (Phase 11 entry)
4. Fix p04-constraints harness failure
**Principle (revised per Codex review):** V1 work and the Now list are
**less disjoint than the first draft claimed**. Real collision points:
| V1 phase | Collides with Now list at |
|---|---|
| V1-0 provenance enforcement | memory extractor write path if it shares helper functions; context assembly for the Q-4 partial trust test |
| V1-0 F-5 hooks | any write path that creates active rows (limited collision; entity writes are separate from memory writes) |
| V1-B KB-CAD/FEM ingest | none on the Now list, but adds an ingest surface that becomes operational burden (ties to O-4 "no new manual ops") |
| V1-D mirror regen triggers | scheduling / ops behavior that intersects with "boring and dependable" gate — mirror regen failures become an observable that the pipeline soak must accommodate |
| V1-E graduation | memory module (new `graduated` status, memory→entity flow); direct collision with memory extractor + triage |
| V1-F F-5 migration | conflicts.py touches the write path shared with memory promotion |
**Recommended schedule (revised):**
- **This week (2026-04-22 to 2026-04-26):** Pipeline soak continues.
Density batch-extract continues. V1 work **waits** — V1-0 would start
touching write paths, which is explicitly something we should not do
during a soak window. Density target (100+ active memories) and the
pipeline soak complete first.
- **Week of 2026-04-27:** If soak is clean and density reached, V1-0
starts. V1-0 is a hard prerequisite and cannot be skipped or parallelized.
- **Weeks of 2026-05-04 and 2026-05-11:** V1-A through V1-D in order.
Multi-model triage work (Now list item 3) continues in parallel only
if its touch-surface is triage-path-only (memory side). Any memory
extractor change pauses V1-E.
- **Week of 2026-05-18 approx:** V1-E (graduation). **This phase must
not run in parallel with memory extractor changes** — it directly
modifies memory module semantics. Multi-model triage should be settled
before V1-E starts.
- **Week of 2026-05-25:** V1-F.
- **End date target:** ~2026-06-01, four weeks later than the first
draft's 2026-05-18 soft target. The shift is deliberate — the first
draft's "parallel / disjoint" claim understated the real collisions.
**Pause points (explicit):**
- Any Now-list item that regresses the pipeline → V1 pauses immediately.
- Memory extractor changes in flight → V1-E pauses until they land and
soak.
- p04-constraints fix requires retrieval ranking changes → V1 does not
pause (retrieval is genuinely disjoint from entities).
- Multi-model triage work touching the entity extractor path (if one
gets prototyped) → V1-0 pauses until the triage decision settles.
---
## Test project
Per `engineering-v1-acceptance.md:379`, the recommended test bed is
**p05-interferometer** — "the optical/structural domain has the cleanest
entity model". I agree. Every F-2, F-3, F-6 criterion asserts against this
project.
p06-polisher is the backup test bed if p05 turns out to have data gaps
(polisher suite is actively worked and has more content).
---
## What V1 completion does NOT include
Per the negative list in `engineering-v1-acceptance.md:351-373`, all of the
following are **explicitly out of scope** for this plan:
- LLM extractor for entities (rule-based is V1)
- Auto-promotion of candidates (human-only in V1)
- Write-back to KB-CAD / KB-FEM
- Multi-user auth
- Real-time UI (API + Mirror markdown only)
- Cross-project rollups
- Time-travel queries (Q-015 stays stretch)
- Nightly conflict sweep (synchronous only)
- Incremental Chroma snapshots
- Retention cleanup script
- Backup encryption
- Off-Dalidou backup target (already exists at clawdbot per ledger, but
| V1 work slows the Now list | V1 pauses on any Now-list blocker. Codex veto on any V1 PR that touches memory extractor, retrieval ranking, or triage paths |
| F-5 detector generalization harder than estimated | Codex audit confirmed schema is already spec-compliant; only detector body + routes need work. If detector generalization still slips, keep per-type detectors and document as a V1.1 cleanup (detection correctness is unaffected, only code organization) |
| Mirror determinism regresses existing mirror output | Keep `/projects/{project_name}/mirror` alias returning the current shape; new `/mirror/{project}/overview` is the spec-compliant one. Deprecate old in V1 release notes |
| Golden file churn as templates evolve | Standard workflow: updating a golden file is a normal part of template work, documented in V1-C commit message |
| Backup drill on Dalidou is disruptive | Run against a clone of the Dalidou DB at a safe hour; no production drill required for V1 acceptance |
| p05-interferometer data gaps | Fall back to p06-polisher per this plan's test-project section |
| Scope creep during V1-A query audit | Any query that isn't in the v1-required set (Q-021 onward) is out of scope, period |
---
## What this plan is **for**
1. A checklist Claude can follow to close V1.
2. A review target for Codex — every phase has explicit acceptance
criteria tied to the acceptance doc.
3. A communication artifact for Antoine — "here's what's left, here's why,
here's the order, here's the risk."
## What this plan is **not**
1. Not a commitment to start tomorrow. Pipeline soak + density density
come first in parallel; V1-A can start this week only because it's
zero-risk additive work.
2. Not a rewrite. Every phase builds on existing code.
3. Not an ontology debate. The ontology is fixed in
`engineering-ontology-v1.md`. Any desire to change it is V2 material.
## Workspace note (for Codex audit)
Codex's first-round review (2026-04-22) flagged that
`docs/plans/engineering-v1-completion-plan.md` and `DEV-LEDGER.md` were
**not visible** in the Playground workspace they were running against,
and that `src/atocore/engineering/` appeared empty there.
The canonical dev workspace for AtoCore is the Windows path
`C:\Users\antoi\ATOCore` (per `CLAUDE.md`). The engineering layer code
