ATOCore/docs/plans/engineering-v1-completion-plan.md

Engineering V1 Completion Plan

Date: 2026-04-22 Author: Claude (after reading the four V1 architecture docs + promotion-rules, conflict-model, human-mirror-rules, tool-handoff-boundaries end-to-end) Status: Draft, pending Codex review Replaces: the rejected "Phase 8 Minions + typed edges" plan (see docs/decisions/2026-04-22-gbrain-plan-rejection.md)

Position

This is not a plan to start Engineering V1. It is a plan to finish V1.

Against what criterion? Each F/Q/O/D item in engineering-v1-acceptance.md gets scored individually in the Gap audit table below with exact code/test/doc references. No global percentage. The headline framing from the first draft ("50–70% built") is withdrawn — it's either done per-criterion or it isn't.

The relevant observation is narrower: the entity schema, the full relationship type set, the 4-state lifecycle, basic CRUD and most of the killer-correctness query functions are already implemented in src/atocore/engineering/*.py in the Windows working tree at C:\Users\antoi\ATOCore (the canonical dev workspace, per CLAUDE.md). The recent commits e147ab2, b94f9df, 081c058, 069d155, b1a3dd0 are V1 entity-layer work. Codex auditors working in a different workspace / branch should sync from the canonical dev tree before per-file review — see the "Workspace note" at the end of this doc.

The question this plan answers: given the current code state, in what order should the remaining V1 acceptance criteria be closed so that every phase builds on invariants the earlier phases already enforced?

Corrected sequencing principle (post-Codex review 2026-04-22)

The first draft ordered phases F-1 → F-2 → F-3 → F-4 → F-5 → F-6 → F-7 → F-8 following the acceptance doc's suggested reading order. Codex rejected that ordering. The correct dependency order, which this revision adopts, is:

1. Write-time invariants come first. Every later phase creates active entities. Provenance-at-write (F-8) and synchronous conflict-detection hooks (F-5 minimal) must be enforced before any phase that writes entities at scale (ingest, graduation, or broad query coverage that depends on the model being populated).
2. Query closure sits on top of the schema + invariants, not ahead of them. A minimum query slice that proves the model is fine early. The full catalog closure waits until after the write paths are invariant-safe.
3. Mirror is a derived consumer of the entity layer, not a midstream milestone. It comes after the entity layer produces enforced, correct data.
4. Graduation and full conflict-spec compliance are finishing work that depend on everything above being stable.

The acceptance criteria are unchanged. Only the order of closing them changes.

How this plan respects the rejected-plan lessons

• No new predicates. The V1 ontology in engineering-ontology-v1.md:112-137 already defines 18 relationship types; service.py:38-62 already implements them. Nothing added, nothing reshaped.
• No new canonical boundary. Typed entities + typed relationships with promotion-based candidate flow per memory-vs-entities.md. Not edges-over-wikilinks.
• No leapfrog of master-plan-status.md Now list. This plan is in parallel with (not ahead of) the Now items because V1 entity work is already happening alongside them. The sequencing section below is explicit.
• Queue/worker infrastructure is explicitly out of scope. The "flag it for later" note at the end of this doc is the only mention, per engineering-v1-acceptance.md:378 negative list.

---

Gap audit against engineering-v1-acceptance.md

Each criterion marked: ✅ done / 🟡 partial / ❌ missing. "Partial" means the capability exists but does not yet match spec shape or coverage.

Functional (F-1 through F-8)

ID	Criterion	Status	Evidence
F-1	12 V1 entity types, 4 relationship families, shared header fields, 4-state lifecycle	✅ done	service.py:16-36 (16 types, superset of V1 minimum), service.py:38-62 (18 relationship types), service.py:64 statuses, Entity dataclass at line 67
F-2	All v1-required Q-001 through Q-020 implemented, with provenance where required	🟡 partial	queries.py has system_map (Q-004), decisions_affecting (Q-008), requirements_for (Q-005 component side), recent_changes (Q-013), orphan_requirements (Q-006 killer), risky_decisions (Q-009 killer), unsupported_claims (Q-011 killer), impact_analysis (Q-016), evidence_chain (Q-017). Likely missing or partial: Q-001 (expand=contains), Q-002 (expand=parents), Q-003 (interfaces), Q-007 (constraints on component), Q-010 (supports trace), Q-012 (conflicting results), Q-014 (decision-log ordered chain), Q-018 (include=superseded chain), Q-019 (material→components), Q-020 (project overview mirror endpoint in V1-required shape)
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-5	Conflict detector fires synchronously; POST /conflicts/{id}/resolve + dismiss	🟡 partial	conflicts.py has detect_conflicts_for_entity, list_open_conflicts, resolve_conflict. API at /admin/conflicts + /admin/conflicts/{id}/resolve. Gap vs spec: spec wants generic slot-key model with conflicts + conflict_members tables; current code has per-type detectors (_check_component_conflicts, _check_requirement_conflicts) — need to verify schema, and spec routes are /conflicts/* not /admin/conflicts/*
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	_graduation_prompt.py exists; api_request_graduation + api_graduation_status + api_graduation_stats routes exist (routes.py:1573, 1607, 2065). Need to verify full flow against F-7 spec — original preserved? graduated status row added? forward pointer column present?
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 includes now timestamp (line 326) which is non-deterministic — would fail Q-5 as written
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

Summary

• Functional: 1/8 ✅, 6/8 🟡 partial, 1/8 ❌ missing → the entity layer is real; the ingest + mirror + graduation surfaces need completion
• Quality: 1/6 ✅, 3/6 🟡 partial, 2/6 ❌ missing → golden file + killer-correctness integration test are the two clear gaps
• Operational: 0/5 ✅ (none marked fully verified), 3/5 🟡, 1/5 ❌ → backup drill is the one hard blocker here
• Documentation: 0/4 ✅, 4/4 ❌ → all 4 docs need writing, D-3/D-4 at the end, D-1/D-2 as part of their respective F criteria

---

Proposed completion order (revised post-Codex review)

Seven phases instead of six. The new V1-0 establishes the write-time invariants (provenance enforcement F-8 + synchronous conflict hooks F-5 minimal) that every later phase depends on. V1-A becomes a minimal query slice that proves the model on one project, not a full catalog closure. Full query catalog closure moves to V1-C. Full F-5 spec compliance (the generic conflicts/conflict_members slot-key schema) stays in V1-F because that's the final shape, but the minimal hooks that fire synchronously on writes land in V1-0.

Skipped by construction: F-1 core schema (already implemented) and O-5 (identity/preference/episodic don't touch the engineering layer).

Phase V1-0: Write-time invariants (F-8 + F-5 minimal + F-1 audit)

Scope:

• F-1 audit (Codex action). Before any code change, Codex does a per-file audit of src/atocore/engineering/service.py, conflicts.py, mirror.py, queries.py against the acceptance doc's F-1 shared-header-field list (id, type, name, project_id, status, confidence, source_refs, created_at, updated_at, extractor_version, canonical_home). Confirm which fields exist, which are missing. This becomes the ground-truth F-1 row in the gap audit table below.
• F-8 provenance enforcement. Add a NOT-NULL invariant at create_entity and promote_entity that source_refs is non-empty OR an explicit hand_authored=True flag is set (per promotion-rules.md:253). Backfill any existing active entities that fail the invariant — either attach provenance, flag as hand-authored, or invalidate. Every future active entity has provenance by schema, not by discipline.
• F-5 minimal hooks. Wire synchronous conflict detection into every active-entity write path (create_entity with status=active, promote_entity, supersede_entity). The detector can stay in its current per-type form (_check_component_conflicts, _check_requirement_conflicts); the hook must fire on every write. Full generic slot-keyed schema lands in V1-F; the hook shape must be generic enough that V1-F is a detector-body swap, not an API refactor.
• Q-3 "flag never block" test. The hook must return conflict-id in the response body but never 4xx-block the write. One test per write path demonstrating this.
• Q-4 trust-hierarchy test for candidates. One test: entity candidates never appear in /context/build output. (Full trust tests land in V1-E; this is the one that V1-0 can cover without graduation being ready.)

Acceptance: F-8 ✅, F-5 minimal hooks ✅, Q-3 ✅, partial Q-4 ✅, F-1 row in gap table is accurate.

Estimated size: 3 days (the audit is the biggest unknown; the enforcement patches are small).

Tests added: ~10.

Why first: every later phase writes entities. Without F-8 + F-5 hooks, V1-A through V1-F can leak invalid state into the store that must then be cleaned up.

Phase V1-A: Minimal query slice that proves the model (partial F-2 + Q-6)

Scope:

• Pick the four queries that prove the model on p05-interferometer: Q-001 (subsystem contents), Q-005 (component satisfies requirements), Q-006 (orphan requirements — killer correctness), Q-017 (evidence chain). These four exercise structural + intent + killer-correctness + provenance, which are the four pillars of the V1 shape.
• Seed p05-interferometer with Q-6 integration data (one satisfying Component + one orphan Requirement + one Decision on flagged Assumption + one supported ValidationClaim + one unsupported ValidationClaim).
• Verify each of the four queries returns correct results against the seeded data. The three killer-correctness queries (Q-006, Q-009, Q-011) run as a single integration test. Q-009 and Q-011 are implemented against the seed data here even though they're not in the "four pillars" list, because Q-6 requires all three.
• Any query function the Codex F-1 audit found to be missing fields required by Q-001/Q-005/Q-006/Q-017 gets filled in here, not in V1-C.

Acceptance: The four pillar queries + Q-006/Q-009/Q-011 killer correctness all return correct results. Q-6 ✅ passes. Partial F-2 (the remaining queries land in V1-C).

Estimated size: 2 days.

Tests added: ~6.

Why second: proves the entity layer shape works end-to-end on real data before we start bolting ingest, graduation, or mirror onto it. If the four pillar queries don't work, stopping here is cheap.

Phase V1-B: KB-CAD / KB-FEM ingest (F-3) + D-2 schema docs

Scope:

• Write docs/architecture/kb-cad-export-schema.md and kb-fem-export-schema.md (matches D-2).
• Implement POST /ingest/kb-cad/export and POST /ingest/kb-fem/export per tool-handoff-boundaries.md sketches. Validator + entity-candidate producer + provenance population using the F-8 invariant from V1-0.
• Hand-craft one real KB-CAD export for p05-interferometer and round-trip it: export → candidate queue → reviewer promotes → queryable via V1-A's four pillar queries.
• Tests: valid export → candidates created; invalid export → 400; duplicate re-export → no duplicate candidates; re-export with changed value → new candidate + conflict row (exercises V1-0's F-5 hook on a real workload).

Acceptance: F-3 ✅, D-2 ✅.

Estimated size: 2 days.

Tests added: ~8.

Why third: ingest is the first real stress test of the V1-0 invariants. A re-import that creates a conflict must trigger the V1-0 hook; if it doesn't, V1-0 is incomplete and we catch it before going further.

Phase V1-C: Close the rest of the query catalog (remaining F-2)

Scope:

• Implement remaining v1-required queries: Q-002 (component parents), Q-003 (subsystem interfaces, with Interface as simple string label), Q-004 (project system-map tree), Q-007 (component constraints), Q-008 (decisions affecting an entity, full shape), Q-010 (supports trace to AnalysisModel), Q-012 (conflicting results on same claim — exercises V1-0's F-5 hook), Q-013 (recent changes with window), Q-014 (decision log ordered + superseded chain), Q-016 (impact analysis — likely already done, just verify shape), Q-018 (include=superseded), Q-019 (material → components).
• Q-020 (project overview mirror route) is deferred to V1-D where the mirror lands in full.

Acceptance: F-2 ✅ (all 19 of 20 v1-required queries; Q-020 in V1-D).

Estimated size: 2 days.

Tests added: ~12.

Why fourth: with the model proven (V1-A) and ingest exercising the write invariants (V1-B), filling in the remaining queries is mechanical. They all sit on top of the same entity store and V1-0 invariants.

Phase V1-D: Full Mirror surface (F-6) + determinism golden file (Q-5) + Q-020

Scope:

• Split the single /projects/{project_name}/mirror route into the three spec routes: /mirror/{project}/overview (= Q-020), /mirror/{project}/decisions, /mirror/{project}/subsystems/{subsystem}.
• Add POST /mirror/{project}/regenerate.
• Move generated files to /srv/storage/atocore/data/mirror/{project}/.
• Deterministic output: stabilize the now timestamp (input parameter pinned by golden tests), sort every iteration, remove dict ordering dependencies.
• ⚠ disputed markers inline wherever an open conflict touches a rendered field (uses V1-0's F-5 hook output).
• (curated) annotations where project_state overrides entity state.
• Regeneration triggers: synchronous on regenerate, debounced async on entity write (30s window), daily scheduled refresh via existing nightly cron (one new cron line, not a new queue).
• mirror_regeneration_failures table.
• Golden-file test: fixture project state → render → bytes equal.

Acceptance: F-6 ✅, Q-5 ✅, Q-020 ✅, O-4 moves toward ✅.

Estimated size: 3–4 days.

Tests added: ~15.

Why fifth: mirror is a derived consumer. It cannot be correct before the entity store + queries + conflict hooks are correct. It lands after everything it depends on is stable.

Phase V1-E: Memory→entity graduation end-to-end (F-7) + remaining Q-4

Scope:

• Verify and close F-7 spec gaps:
  • Original memory gets status="graduated" (new status).
  • Forward-pointer column from graduated memory to entity candidate id.
  • Promote-entity preserves original memory.
  • Flow tested for adaptation → Decision, project → Requirement, knowledge → Fact.
• Minimal schema additions: one column + one new status value; additive migration only.
• Q-4 full trust-hierarchy tests: no auto-write to project_state from any promote path; active-only reinforcement for entities; etc. (The entity-candidates-excluded-from-context test shipped in V1-0.)

Acceptance: F-7 ✅, Q-4 ✅.

Estimated size: 2 days.

Tests added: ~8.

Why sixth: graduation touches memory-layer semantics (adds a graduated status, flows memory→entity, requires memory-module changes). Doing it after the entity layer is fully invariant-safe + query-complete

• mirror-derived means the memory side only has to deal with one shape: a stable, tested entity layer.

Phase V1-F: Full F-5 spec compliance + O-1/O-2/O-3 + D-1/D-3/D-4

Scope:

• F-5 full spec compliance. Audit conflicts.py against conflict-model.md. The spec wants a generic conflicts + conflict_members table with slot-keyed detection. V1-0 put the hook in place; V1-F is where the detector body gets swapped to the generic shape if the audit shows divergence.
  • If schema already matches spec: no work.
  • If divergent: migrate additively (new tables alongside existing, dual-read, drop old after one stable release).
  • Rename /admin/conflicts/* routes to /conflicts/* per spec, keep /admin/conflicts/* as aliases for one release, deprecate in D-3 release notes.
• O-1: Run the full migration against a Dalidou backup copy. Confirm additive, idempotent, safe to run twice.
• O-2: Run a full restore drill on the test project per docs/backup-restore-procedure.md. Post-restore, Q-001 returns correct shape. POST /admin/backup snapshot includes the new tables.
• O-3: Manual sanity-check of the three performance bounds.
• D-1: Write 12 short spec docs under docs/architecture/entities/ (one per V1 entity type).
• D-3: Write docs/v1-release-notes.md.
• D-4: Update master-plan-status.md and current-state.md — move engineering V1 from Next to What Is Real Today.

Acceptance: F-5 ✅, O-1 ✅, O-2 ✅, O-3 ✅, D-1 ✅, D-3 ✅, D-4 ✅ → V1 is done.

Estimated size: 3 days (F-5 migration if needed is the main unknown; D-1 entity docs at ~30 min each ≈ 6 hours; verification is fast).

Tests added: ~6 (F-5 spec-shape tests; verification adds no automated tests).

Total (revised)

• Estimated 12–17 days of focused work across seven phases — up from the original 11–14 days to reflect V1-0 overhead and Codex's objection that the first estimate was too tight.
• Adds roughly 65 tests (533 → ~600).
• 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 not a V1 criterion)
• Async job queue / minions pattern (the rejected plan's centerpiece — explicitly deferred to post-V1 per the negative list)

---

Open questions for Codex

1. Is the parallel schedule with the Now list acceptable? Claude's read is that V1 work and Now items touch disjoint surfaces so they run in parallel without conflict. Codex may see collisions Claude missed.

2. Phase V1-A query audit scope. Claude listed Q-001, Q-002, Q-003, Q-007, Q-010, Q-012, Q-014, Q-018, Q-019, Q-020 as likely gaps without reading each query function end-to-end. Codex's per-file audit may find more already done (or more missing).

3. F-5 conflicts schema divergence. The current code uses per-type detectors (_check_component_conflicts, _check_requirement_conflicts) whereas the spec wants a generic slot-keyed conflicts + conflict_members. Is the existing schema equivalent (just implemented differently) or divergent (needs migration)? This is a one-read decision for Codex.

4. Should F-5 route rename (/admin/conflicts/* → /conflicts/*) be breaking? Spec route path differs from current. Proposal: add /conflicts/* as aliases, keep /admin/conflicts/* for one release, deprecate in V1 release notes, remove in V1.1.

5. Mirror determinism — where does now go? The current mirror footer has a live timestamp (line 326 of mirror.py). Spec says deterministic output, spec also shows a Regenerated: header with timestamp (line 265 of human-mirror-rules.md). Reconciliation: timestamp is allowed in the header banner but must be an input parameter so the golden-file test can pin it. Sound right?

6. F-7 graduation gap depth. Without running the existing graduation flow end-to-end against a real memory, Claude can't tell how close the existing code is to F-7 spec. Codex's audit of _graduation_prompt.py + api_request_graduation + DB schema would close this question in one read.

7. Estimated 11–14 days honest? Given recent phase velocities (Phase 7A was a week, Phase 7D fit in a single session), 2–3 days per phase across 6 phases may be light or heavy. Codex's calibration against actual repo velocity would help.

8. After V1, the minions/queue mechanic we rejected returns as a candidate V2 item. Should we note it explicitly in V1 release notes (D-3) as a future track, or leave it unnamed until V2 planning starts?

---

Risks

Risk	Mitigation
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 schema migration is bigger than estimated	If Codex audit shows material divergence, split V1-E into two phases (schema migration separate from provenance enforcement)
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 (src/atocore/engineering/service.py, queries.py, conflicts.py, mirror.py, _graduation_prompt.py, wiki.py, triage_ui.py) exists there and is what the recent commits (e147ab2, b94f9df, 081c058, 069d155, b1a3dd0) touched. The Windows working tree is what this plan was written against.

Before the file-level audit:

1. Confirm which branch / SHA Codex is reviewing. The Windows working tree has uncommitted changes to this plan + DEV-LEDGER as of 2026-04-22; commit will be made only after Antoine approves sync.
2. If Codex is reviewing ATOCore-clean or a Playground snapshot, that tree may lag the canonical dev tree. Sync or re-clone from the Windows working tree / current origin/main before per-file audit.
3. The three visible-to-Codex file paths for this plan are:
   • docs/plans/engineering-v1-completion-plan.md (this file)
   • docs/decisions/2026-04-22-gbrain-plan-rejection.md (prior decision)
   • DEV-LEDGER.md (Recent Decisions + Session Log entries 2026-04-22)

References

• docs/architecture/engineering-ontology-v1.md
• docs/architecture/engineering-query-catalog.md
• docs/architecture/memory-vs-entities.md
• docs/architecture/engineering-v1-acceptance.md
• docs/architecture/promotion-rules.md
• docs/architecture/conflict-model.md
• docs/architecture/human-mirror-rules.md
• docs/architecture/tool-handoff-boundaries.md
• docs/master-plan-status.md (Now/Next/Later list)
• docs/decisions/2026-04-22-gbrain-plan-rejection.md (the rejected plan)
• src/atocore/engineering/service.py (current V1 entity service)
• src/atocore/engineering/queries.py (current V1 query implementations)
• src/atocore/engineering/conflicts.py (current conflicts module)
• src/atocore/engineering/mirror.py (current mirror module)