ATOCore/docs/architecture/human-mirror-rules.md

Human Mirror Rules (Layer 3 → derived markdown views)

Why this document exists

The engineering layer V1 stores facts as typed entities and relationships in a SQL database. That representation is excellent for queries, conflict detection, and automated reasoning, but it's terrible for the human reading experience. People want to read prose, not crawl JSON.

The Human Mirror is the layer that turns the typed entity store into human-readable markdown pages. It's strictly a derived view — nothing in the Human Mirror is canonical, every page is regenerated from current entity state on demand.

This document defines:

• what the Human Mirror generates
• when it regenerates
• how the human edits things they see in the Mirror
• how the canonical-vs-derived rule is enforced (so editing the derived markdown can't silently corrupt the entity store)

The non-negotiable rule

The Human Mirror is read-only from the human's perspective.

If the human wants to change a fact they see in the Mirror, they change it in the canonical home (per representation-authority.md), NOT in the Mirror page. The next regeneration picks up the change.

This rule is what makes the whole derived-view approach safe. If the human is allowed to edit Mirror pages directly, the canonical-vs-derived split breaks and the Mirror becomes a second source of truth that disagrees with the entity store.

The technical enforcement is that every Mirror page carries a header banner that says "this file is generated from AtoCore entity state, do not edit", and the file is regenerated from the entity store on every change to its underlying entities. Manual edits will be silently overwritten on the next regeneration.

What the Mirror generates in V1

Three template families, each producing one or more pages per project:

1. Project Overview

One page per registered project. Renders:

• Project header (id, aliases, description)
• Subsystem tree (from Q-001 / Q-004 in the query catalog)
• Active Decisions affecting this project (Q-008, ordered by date)
• Open Requirements with coverage status (Q-005, Q-006)
• Open ValidationClaims with support status (Q-010, Q-011)
• Currently flagged conflicts (from the conflict model)
• Recent changes (Q-013) — last 14 days

This is the most important Mirror page. It's the page someone opens when they want to know "what's the state of this project right now". It deliberately mirrors what current-state.md does for AtoCore itself but generated entirely from typed state.

2. Decision Log

One page per project. Renders:

• All active Decisions in chronological order (newest first)
• Each Decision shows: id, what was decided, when, the affected Subsystem/Component, the supporting evidence (Q-014, Q-017)
• Superseded Decisions appear as collapsed "history" entries with a forward link to whatever superseded them
• Conflicting Decisions get a "⚠ disputed" marker

This is the human-readable form of the engineering query catalog's Q-014 query.

3. Subsystem Detail

One page per Subsystem (so a few per project). Renders:

• Subsystem header
• Components contained in this subsystem (Q-001)
• Interfaces this subsystem has (Q-003)
• Constraints applying to it (Q-007)
• Decisions affecting it (Q-008)
• Validation status: which Requirements are satisfied, which are open (Q-005, Q-006)
• Change history within this subsystem (Q-013 scoped)

Subsystem detail pages are what someone reads when they're working on a specific part of the system and want everything relevant in one place.

What the Mirror does NOT generate in V1

Intentionally excluded so the V1 implementation stays scoped:

• Per-component detail pages. Components are listed in Subsystem pages but don't get their own pages. Reduces page count from hundreds to dozens.
• Per-Decision detail pages. Decisions appear inline in Project Overview and Decision Log; their full text plus evidence chain is shown there, not on a separate page.
• Cross-project rollup pages. No "all projects at a glance" page in V1. Each project is its own report.
• Time-series / historical pages. The Mirror is always "current state". History is accessible via Decision Log and superseded chains, but no "what was true on date X" page exists in V1 (Q-015 is v1-stretch in the query catalog for the same reason).
• Diff pages between two timestamps. Same reasoning.
• Render of the conflict queue itself. Conflicts appear inline in the relevant Mirror pages with the "⚠ disputed" marker and a link to /conflicts/{id}, but there's no Mirror page that lists all conflicts. Use GET /conflicts.
• Per-memory pages. Memories are not engineering entities; they appear in context packs and the review queue, not in the Human Mirror.

Where Mirror pages live

Two options were considered. The chosen V1 path is option B:

Option A — write Mirror pages back into the source vault. Generate /srv/storage/atocore/sources/vault/mirror/p05/overview.md so the human reads them in their normal Obsidian / markdown viewer. Rejected because writing into the source vault violates the "sources are read-only" rule from tool-handoff-boundaries.md and the operating model.

Option B (chosen) — write Mirror pages into a dedicated AtoCore output dir, served via the API. Generate under /srv/storage/atocore/data/mirror/p05/overview.md. The human reads them via:

• the API endpoints GET /mirror/{project}/overview, GET /mirror/{project}/decisions, GET /mirror/{project}/subsystems/{subsystem} (all return rendered markdown as text/markdown)
• a future "Mirror viewer" in the Claude Code slash command /atocore-mirror <project> that fetches the rendered markdown and displays it inline
• direct file access on Dalidou for power users: cat /srv/storage/atocore/data/mirror/p05/overview.md

The dedicated dir keeps the Mirror clearly separated from the canonical sources and makes regeneration safe (it's just a directory wipe + write).

When the Mirror regenerates

Three triggers, in order from cheapest to most expensive:

1. On explicit human request

POST /mirror/{project}/regenerate

Returns the timestamp of the regeneration and the list of files written. This is the path the human takes when they've just curated something into project_state and want to see the Mirror reflect it immediately.

2. On entity write (debounced, async, per project)

When any entity in a project changes status (candidate → active, active → superseded), a regeneration of that project's Mirror is queued. The queue is debounced — multiple writes within a 30-second window only trigger one regeneration. This keeps the Mirror "close to current" without generating a Mirror update on every single API call.

The implementation is a simple dict of "next regeneration time" per project, checked by a background task. No cron, no message queue, no Celery. Just a dict[str, datetime] and a thread.

3. On scheduled refresh (daily)

Once per day at a quiet hour, every project's Mirror regenerates unconditionally. This catches any state drift from manual project_state edits that bypassed the entity write hooks, and provides a baseline guarantee that the Mirror is at most 24 hours stale.

The schedule runs from the same machinery as the future backup retention job, so we get one cron-equivalent system to maintain instead of two.

What if regeneration fails

The Mirror has to be resilient. If regeneration fails for a project (e.g. a query catalog query crashes, a template rendering error), the existing Mirror files are not deleted. The existing files stay in place (showing the last successful state) and a regeneration error is recorded in:

• the API response if the trigger was explicit
• a log entry at warning level for the async path
• a mirror_regeneration_failures table for the daily refresh

This means the human can always read the Mirror, even if the last 5 minutes of changes haven't made it in yet. Stale is better than blank.

How the human curates "around" the Mirror

The Mirror reflects the current entity state. If the human doesn't like what they see, the right edits go into one of:

What you want to change	Where you change it
A Decision's text	PUT /entities/Decision/{id} (or PUT /memory/{id} if it's still memory-layer)
A Decision's status (active → superseded)	POST /entities/Decision/{id}/supersede (V1 entity API)
Whether a Component "satisfies" a Requirement	edit the relationship directly via the entity API (V1)
The current trusted next focus shown on the Project Overview	POST /project/state with category=status, key=next_focus
A typo in a generated heading or label	edit the template, not the rendered file. Templates live in templates/mirror/ (V1 implementation)
Source of a fact ("this came from KB-CAD on day X")	not editable by hand — it's automatically populated from provenance

The rule is consistent: edit the canonical home, regenerate (or let the auto-trigger fire), see the change reflected in the Mirror.

Templates

The Mirror uses Jinja2-style templates checked into the repo under templates/mirror/. Each template is a markdown file with placeholders that the renderer fills from query catalog results.

Template list for V1:

• templates/mirror/project-overview.md.j2
• templates/mirror/decision-log.md.j2
• templates/mirror/subsystem-detail.md.j2

Editing a template is a code change, reviewed via normal git PRs. The templates are deliberately small and readable so the human can tweak the output format without touching renderer code.

The renderer is a thin module:

# src/atocore/mirror/renderer.py (V1, not yet implemented)

def render_project_overview(project: str) -> str:
    """Generate the project overview markdown for one project."""
    facts = collect_project_overview_facts(project)
    template = load_template("project-overview.md.j2")
    return template.render(**facts)

The "do not edit" header

Every generated Mirror file starts with a fixed banner:

<!--
  This file is generated by AtoCore from current entity state.
  DO NOT EDIT — manual changes will be silently overwritten on
  the next regeneration.
  Edit the canonical home instead. See:
    https://docs.atocore.../representation-authority.md
  Regenerated: 2026-04-07T12:34:56Z
  Source entities: <commit-like checksum of input data>
-->

The checksum at the end lets the renderer skip work when nothing relevant has changed since the last regeneration. If the inputs match the previous run's checksum, the existing file is left untouched.

Conflicts in the Mirror

Per the conflict model, any open conflict on a fact that appears in the Mirror gets a visible disputed marker:

- Lateral support material: **GF-PTFE** ⚠ disputed
  - The KB-CAD import on 2026-04-07 reported PEEK; conflict #c-039.

The disputed marker is a hyperlink (in renderer terms; the markdown output is a relative link) to the conflict detail page in the API or to the conflict id for direct lookup. The reviewer follows the link, resolves the conflict via POST /conflicts/{id}/resolve, and on the next regeneration the marker disappears.

Project-state overrides in the Mirror

When a Mirror page would show a value derived from entities, but project_state has an override on the same key, the Mirror shows the project_state value with a small annotation noting the override:

- Next focus: **Wave 2 trusted-operational ingestion** (curated)

The (curated) annotation tells the reader "this is from the trusted-state Layer 3, not from extracted entities". This makes the trust hierarchy visible in the human reading experience.

The "Mirror diff" workflow (post-V1, but designed for)

A common workflow after V1 ships will be:

1. Reviewer has curated some new entities
2. They want to see "what changed in the Mirror as a result"
3. They want to share that diff with someone else as evidence

To support this, the Mirror generator writes its output deterministically (sorted iteration, stable timestamp formatting) so a git diff between two regenerated states is meaningful.

V1 doesn't add an explicit "diff between two Mirror snapshots" endpoint — that's deferred. But the deterministic-output property is a V1 requirement so future diffing works without re-renderer-design work.

What the Mirror enables

With the Mirror in place:

• OpenClaw can read project state in human form. The read-only AtoCore helper skill on the T420 already calls /context/build; in V1 it gains the option to call /mirror/{project}/overview to get a fully-rendered markdown page instead of just retrieved chunks. This is much faster than crawling individual entities for general questions.
• The human gets a daily-readable artifact. Every morning, Antoine can cat /srv/storage/atocore/data/mirror/p05/overview.md and see the current state of p05 in his preferred reading format. No API calls, no JSON parsing.
• Cross-collaborator sharing. If you ever want to send someone a project overview without giving them AtoCore access, the Mirror file is a self-contained markdown document they can read in any markdown viewer.
• Claude Code integration. A future /atocore-mirror <project> slash command renders the Mirror inline, complementing the existing /atocore-context command with a human-readable view of "what does AtoCore think about this project right now".

Open questions for V1 implementation

1. What's the regeneration debounce window? 30 seconds is the starting value but should be tuned with real usage.
2. Does the daily refresh need a separate trigger mechanism, or is it just a long-period entry in the same in-process scheduler that handles the debounced async refreshes? Probably the latter — keep it simple.
3. How are templates tested? Likely a small set of fixture project states + golden output files, with a single test that asserts render(fixture) == golden. Updating golden files is a normal part of template work.
4. Are Mirror pages discoverable via a directory listing endpoint? GET /mirror/{project} returns the list of available pages for that project. Probably yes; cheap to add.
5. How does the Mirror handle a project that has zero entities yet? Render an empty-state page that says "no curated facts yet — add some via /memory or /entities/Decision". Better than a blank file.

TL;DR

• The Human Mirror generates 3 template families per project (Overview, Decision Log, Subsystem Detail) from current entity state
• It's strictly read-only from the human's perspective; edits go to the canonical home and the Mirror picks them up on regeneration
• Three regeneration triggers: explicit POST, debounced async-on-write, daily scheduled refresh
• Mirror files live in /srv/storage/atocore/data/mirror/ (NOT in the source vault — sources stay read-only)
• Conflicts and project_state overrides are visible inline in the rendered markdown so the trust hierarchy shows through
• Templates are checked into the repo and edited via PR; the rendered files are derived and never canonical
• Deterministic output is a V1 requirement so future diffing works without rework