Anto01
d6ce6128cf
Session 4 of the four-session plan. Final two engineering planning
docs, plus master-plan-status.md updated to reflect that the
engineering layer planning sprint is now complete.
docs/architecture/human-mirror-rules.md
---------------------------------------
The Layer 3 derived markdown view spec:
- The non-negotiable rule: the Mirror is read-only from the
human's perspective; edits go to the canonical home and the
Mirror picks them up on regeneration
- 3 V1 template families: Project Overview, Decision Log,
Subsystem Detail
- Explicit V1 exclusions: per-component pages, per-decision
pages, cross-project rollups, time-series pages, diff pages,
conflict queue render, per-memory pages
- Mirror files live in /srv/storage/atocore/data/mirror/ NOT in
the source vault (sources stay read-only per the operating
model)
- 3 regeneration triggers: explicit POST, debounced async on
entity write, daily scheduled refresh
- "Do not edit" header banner with checksum so unchanged inputs
skip work
- Conflicts and project_state overrides surface inline so the
trust hierarchy is visible in the human reading experience
- Templates checked in under templates/mirror/, edited via PR
- Deterministic output is a V1 requirement so future Mirror
diffing works without rework
- Open questions for V1: debounce window, scheduler integration,
template testing approach, directory listing endpoint, empty
state rendering
docs/architecture/engineering-v1-acceptance.md
----------------------------------------------
The measurable done definition:
- Single-sentence definition: V1 is done when every v1-required
query in engineering-query-catalog.md returns a correct result
for one chosen test project, the Human Mirror renders a
coherent overview, and a real KB-CAD or KB-FEM export round-
trips through ingest -> review queue -> active entity without
violating any conflict or trust invariant
- 23 acceptance criteria across 4 categories:
* Functional (8): entity store, all 20 v1-required queries,
tool ingest endpoints, candidate review queue, conflict
detection, Human Mirror, memory-to-entity graduation,
complete provenance chain
* Quality (6): existing tests pass, V1 has its own coverage,
conflict invariants enforced, trust hierarchy enforced,
Mirror reproducible via golden file, killer correctness
queries pass against representative data
* Operational (5): safe migration, backup/restore drill,
performance bounds, no new manual ops burden, Phase 9 not
regressed
* Documentation (4): per-entity-type spec docs, KB schema docs,
V1 release notes, master-plan-status updated
- Explicit negative list of things V1 does NOT need to do:
no LLM extractor, no auto-promotion, no write-back, no
multi-user, no real-time UI, no cross-project rollups,
no time-travel, no nightly conflict sweep, no incremental
Chroma, no retention cleanup, no encryption, no off-Dalidou
backup target
- Recommended implementation order: F-1 -> F-8 in sequence,
with the graduation flow (F-7) saved for last as the most
cross-cutting change
- Anticipated friction points called out in advance:
graduation cross-cuts memory module, Mirror determinism trap,
conflict detector subtle correctness, provenance backfill
for graduated entities
master-plan-status.md updated
-----------------------------
- Engineering Layer Planning Sprint section now marked complete
with all 8 architecture docs listed
- Note that the next concrete step is the V1 implementation
sprint following engineering-v1-acceptance.md as its checklist
Pure doc work. No code, no schema, no behavior changes.
After this commit, the engineering planning sprint is fully done
(8/8 docs) and Phase 9 is fully complete (Commits A/B/C all
shipped, validated, and pushed). AtoCore is ready for either
the engineering V1 implementation sprint OR a pause for real-
world Phase 9 usage, depending on which the user prefers next.
5.4 KiB
5.4 KiB
AtoCore Master Plan Status
Current Position
AtoCore is currently between Phase 7 and Phase 8.
The platform is no longer just a proof of concept. The local engine exists, the core correctness pass is complete, Dalidou hosts the canonical runtime and machine database, and OpenClaw on the T420 can consume AtoCore safely in read-only additive mode.
Phase Status
Completed
- Phase 0 - Foundation
- Phase 0.5 - Proof of Concept
- Phase 1 - Ingestion
Baseline Complete
- Phase 2 - Memory Core
- Phase 3 - Retrieval
- Phase 5 - Project State
- Phase 7 - Context Builder
Partial
- Phase 4 - Identity / Preferences
- Phase 8 - OpenClaw Integration
Baseline Complete
- Phase 9 - Reflection (all three foundation commits landed: A capture, B reinforcement, C candidate extraction + review queue)
Not Yet Complete In The Intended Sense
- Phase 6 - AtoDrive
- Phase 10 - Write-back
- Phase 11 - Multi-model
- Phase 12 - Evaluation
- Phase 13 - Hardening
Engineering Layer Planning Sprint
Status: complete. All 8 architecture docs are drafted. The engineering layer is now ready for V1 implementation against the active project set.
- engineering-query-catalog.md — the 20 v1-required queries the engineering layer must answer
- memory-vs-entities.md — canonical home split between memory and entity tables
- promotion-rules.md — Layer 0 → Layer 2 pipeline, triggers, review queue mechanics
- conflict-model.md — detection, representation, and resolution of contradictory facts
- tool-handoff-boundaries.md — KB-CAD / KB-FEM one-way mirror stance, ingest endpoints, drift handling
- representation-authority.md — canonical home matrix across PKM / KB / repos / AtoCore for 22 fact kinds
- human-mirror-rules.md — templates, regeneration triggers, edit flow, "do not edit" enforcement
- engineering-v1-acceptance.md — measurable done definition with 23 acceptance criteria
- engineering-knowledge-hybrid-architecture.md — the 5-layer model (from the previous planning wave)
- engineering-ontology-v1.md — the initial V1 object and relationship inventory (previous wave)
The next concrete next step is the V1 implementation sprint, which should follow engineering-v1-acceptance.md as its checklist.
What Is Real Today
- canonical AtoCore runtime on Dalidou
- canonical machine DB and vector store on Dalidou
- project registry with:
- template
- proposal preview
- register
- update
- refresh
- read-only additive OpenClaw helper on the T420
- seeded project corpus for:
p04-gigabitp05-interferometerp06-polisher
- conservative Trusted Project State for those active projects
- first operational backup foundation for SQLite + project registry
- implementation-facing architecture notes for future engineering knowledge work
- first organic routing layer in OpenClaw via:
detect-projectauto-context
Now
These are the current practical priorities.
- Finish practical OpenClaw integration
- make the helper lifecycle feel natural in daily use
- use the new organic routing layer for project-knowledge questions
- confirm fail-open behavior remains acceptable
- keep AtoCore clearly additive
- Tighten retrieval quality
- reduce cross-project competition
- improve ranking on short or ambiguous prompts
- add only a few anchor docs where retrieval is still weak
- Continue controlled ingestion
- deepen active projects selectively
- avoid noisy bulk corpus growth
- Strengthen operational boringness
- backup and restore procedure
- Chroma rebuild / backup policy
- retention and restore validation
Next
These are the next major layers after the current practical pass.
- Clarify AtoDrive as a real operational truth layer
- Mature identity / preferences handling
- Improve observability for:
- retrieval quality
- context-pack inspection
- comparison of behavior with and without AtoCore
Later
These are the deliberate future expansions already supported by the architecture direction, but not yet ready for immediate implementation.
- Minimal engineering knowledge layer
- driven by
docs/architecture/engineering-knowledge-hybrid-architecture.md - guided by
docs/architecture/engineering-ontology-v1.md
- driven by
- Minimal typed objects and relationships
- Evidence-linking and provenance-rich structured records
- Human mirror generation from structured state
Not Yet
These remain intentionally deferred.
- automatic write-back from OpenClaw into AtoCore
- automatic memory promotion
- reflection loop integration
- replacing OpenClaw's own memory system
- live machine-DB sync between machines
- full ontology / graph expansion before the current baseline is stable
Working Rule
The next sensible implementation threshold for the engineering ontology work is:
- after the current ingestion, retrieval, registry, OpenClaw helper, organic routing, and backup baseline feels boring and dependable
Until then, the architecture docs should shape decisions, not force premature schema work.