AutoGineer
Generated banner for MirrorArc
Generated logo for MirrorArc

MirrorArc

LLM wiki kit

First committed by cz1993

Published in cz1993/MirrorArc. Publisher page

97 GitHub stars

What it is

Local-first, governed documentation for humans and AI agents—mirror Office, PDF, and GitHub sources into linked Markdown knowledge workspaces.
— the description by cz1993

Summary from the brain’s metadata

Local-first, governed documentation for humans and AI agents—mirror Office, PDF, and GitHub sources into linked Markdown knowledge workspaces. Preserve sources. Minimize derived documents. Generate knowledge views when they are needed.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

Memory model: LLM wiki. Folders: .github (agent config, 3 files); docs (docs, 33 files); examples (examples, 139 files); scripts (scripts, 11 files); src (source code, 126 files); template (templates, 54 files); tests (tests, 57 files). The agent reads README.md, docs/PRODUCT.md. The agent writes CHANGELOG.md.

Folders
FolderRoleFiles
.githubagent-config3
docsdocs33
examplesexamples139
scriptsscripts11
srcsource-code126
templatetemplates54
teststests57
.githooksfolder1
clifolder1

The agent reads

The agent writes

Requirements

Apps: Obsidian

Runtimes: Python >=3.11

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 2 scripts. Review .githooks/pre-commit, scripts/init.sh before opening the folder in Claude Code. No step below turns a hook on for you.

    • .githooks/pre-commit: runs on git pre-commit
    • scripts/init.sh: sh scripts/init.sh

  2. Clone the repository at the commit AutoGineer scanned:

    git clone https://github.com/cz1993/MirrorArc.git && cd MirrorArc && git checkout 1df13ebf6efb33018e29a1ea365cde0cf53d41c7

  3. Point Claude Code at AGENTS.md: it does not read that file on its own.

  4. cd MirrorArc && claude

  5. AutoGineer scanned these files at commit 1df13eb.

  6. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/cz1993/MirrorArc/blob/1df13ebf6efb33018e29a1ea365cde0cf53d41c7/README.md#quick-start

  7. First committed by cz1993. Published in cz1993/MirrorArc. Licence: GNU Affero General Public License v3.0 only.

Usage

From the brain’s own files

  • Create a vault without cloning MirrorArc itself.
  • The installable command requires Python 3.11+; uvx and pipx run will build an isolated environment when they can find a compatible Python.
  • Before the package is published to PyPI, use the Git URL:
  • Once MirrorArc is published to PyPI, the equivalent short forms are uvx mirrorarc init --profile data-product ~/my-data-product and pipx run mirrorarc init --profile data-product ~/my-data-product.
  • For repeated local use, install the console command once:
  • Then open the vault in Obsidian if you want a human UI, point your agent at it (CLAUDE.md routes all agents to _meta/agent-rules.md), and run the installed command from any folder:
  • Run sandbox from a duplicated pilot vault, not the original document folder.
  • It is read-only and checks copy-boundary, mirror isolation, manifest/recovery readiness, and basic backup posture without printing source paths or document text.

Documentation by cz1993

MirrorArc

Image: Python 3.11+ Image: License: AGPL-3.0 Image: Status: technical alpha

Preserve sources. Minimize derived documents. Generate knowledge views when they are needed.

Open the live Ontario Grid demo portal →

MirrorArc is an open-source, local-first Python toolkit that turns changing Office files, PDFs, GitHub repositories, datasets, and Markdown into a governed knowledge-projection system. It keeps original records authoritative, creates deterministic Markdown projections for opaque sources, maintains source-backed relationships, and renders human or agent context without adding a vector database or an AI-generated wiki.

Image: MirrorArc beginner landing page showing the Ontario Electricity evidence tutorial

Why MirrorArc exists

Generative AI made documentation fast and cheap to create. It did not make a growing collection of summaries, entity pages, hubs, and agent notes cheap to verify or maintain. MirrorArc treats every durable derivative as a liability that must justify its existence; the information and knowledge carried by the sources remain the asset.

The product principle is:

Preserve authoritative records. Treat every durable derivative as a maintenance liability. Generate views instead of accumulating documents.

Common failureMirrorArc's response
Office files, PDFs, spreadsheets, repos, and Markdown stay isolated.L1 specular projections: opaque sources receive stable, source-addressed Markdown read models while originals remain authoritative.
AI documentation creates more files than anyone can govern.Anti-proliferation by architecture: relationships are data and synthesis is a view, not another note by default.
Cross-document meaning is hidden or asserted without evidence.Relationship and provenance ledger: typed connections carry evidence anchors, hashes, generation method, confidence, and review state.
Human readers need interpretation rather than raw extraction.L2 knowledge views: many sources produce a few purpose- and audience-specific reading surfaces that are ephemeral unless pinned or reviewed.
Source changes leave summaries and agent context stale.Dependency-aware refresh: changed sources invalidate only affected projections, relationships, views, reviews, and context.
Sensitive or stale material enters an opaque index.Visible governance: authority, licensing, PII boundaries, lifecycle, freshness, and publication gates remain explicit.

See the connected evidence

The self-contained Catalog Explorer provides a relationship map, a provenance and lifecycle inspector, and a rendered document view. When a governed repository is selected, an optional Code view adds revision-bound source evidence, call paths, impact, and affected-test candidates. The catalog panel is resizable, long filenames wrap instead of disappearing, and INDEX.md is pinned as the beginner guide.

Image: MirrorArc relationship map connecting an original Word document and its generated Markdown mirror

Image: MirrorArc metadata view showing provenance, authority, lifecycle state, and source-to-mirror relationships

Flagship demo: Ontario electricity evidence workspace

examples/ontario-electricity-evidence-vault/ is the flagship clean-room data-product example, built from OGL Ontario data, metadata-only public references, independently authored Word/Excel artifacts, and a synthetic repository fixture. The current snapshot demonstrates the implemented L1, lifecycle, catalog, and portal foundation. Its large hand-authored Markdown layer predates the knowledge-projection architecture and is now a migration fixture rather than the target output.

The local implementation supports source-addressed L1, evidence relationships, reviewed L2 views, dynamic/frozen context, and dependency invalidation. The checked-in example remains deliberately small. Historical stress tests are recorded separately; current batch proof is documented in the Trustworthy Context handoff when available.

The committed snapshot is an independently assembled educational corpus, not live grid data, forecasting, alerts, or an affiliated Ontario energy product.

Launch the hosted demo and start with the pinned INDEX.md five-minute tour. GitHub Pages rebuilds this content-enabled portal only from the provenance-documented public example and blocks deployment unless both the repository-wide provenance/no-data gate and the generated-artifact scan pass alongside vault lint.

The hosted project is progressively discoverable: the project overview identifies MirrorArc's purpose, differentiators, installation path, licence, and canonical GitHub source in semantic HTML. The demo's initial HTML contains the rendered beginner tour, while documents/ provides one semantic, no-JavaScript page per public record. Search and agent discovery surfaces include sitemap.xml, robots.txt, llms.txt, raw public Markdown, and a metadata-only catalog.json.

Try the demo locally

git clone https://github.com/cz1993/MirrorArc.git
cd MirrorArc
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

mirrorarc --root examples/ontario-electricity-evidence-vault sync
mirrorarc --root examples/ontario-electricity-evidence-vault code doctor
# If Ready, optionally analyze the synthetic repository fixture:
mirrorarc --root examples/ontario-electricity-evidence-vault code analyze --repo repo_252e1077b0082592ba3d --symbol demand_change
mirrorarc --root examples/ontario-electricity-evidence-vault catalog --html --include-content
python -m http.server 8000 --directory examples/ontario-electricity-evidence-vault

Open http://127.0.0.1:8000/CATALOG.html. Start with the pinned INDEX.md, then follow the five-minute tour. The --include-content output embeds bounded Markdown bodies and must remain local for private or proprietary vaults. The hosted MirrorArc demo is a narrow exception: it is built only from the public example corpus and scanned again before every deployment.

Choose a task and export its evidence

From a synced vault, choose a task, inspect what was selected and omitted, then freeze evidence:

mirrorarc --root <vault> context build --lens orientation --mode metadata --query "inspection interval" --json
mirrorarc --root <vault> context build --lens orientation --query "inspection interval" --name inspection-review
# Use the definition ID printed above:
mirrorarc --root <vault> context resolve <definition-id> --json
mirrorarc --root <vault> context freeze --definition <definition-id> --task "Explain the inspection interval with citations."
mirrorarc --root <vault> catalog --html

Query retrieval is opt-in: lexical ranking can miss relevant evidence. Inspect source hashes, exact spans, selected/excluded reasons, warnings and omissions before use. Metadata contains references only. Frozen packs include bounded evidence and report exact serialized bytes plus an estimated token count, not a model-independent token guarantee. A tiny budget can fail because instructions and citations alone do not fit. offline_complete is false if selected evidence is missing or truncated; it is never a guarantee that the sources answer your question.

The portable Catalog's selection download stays metadata-only. Its governed-context panel shows saved tasks, copyable commands and frozen status. HTML does not execute those commands. Use --include-content only when intentionally embedding local evidence; protect the resulting file according to its sensitivity. Source changes require refresh, context resolution, and Catalog regeneration. Frozen bytes remain unchanged and status reports staleness.

Review PDF page evidence

The optional PageIndex integration adds physical-page evidence and unreviewed answer candidates to the same governed workflow. Install its separate pinned runtime using the PageIndex setup and review guide, then start with model-free indexing:

mirrorarc --root /absolute/path/to/copied-vault document doctor
# Use a registered PDF source ID from mirrorarc status --json:
mirrorarc --root /absolute/path/to/copied-vault document index --source SOURCE_ID --context frozen --page 2
mirrorarc --root /absolute/path/to/copied-vault catalog --html --include-content

In the Catalog, select the PDF, then Document metadata → PDF page evidence. Optional questions require an approved model/endpoint and explicit per-command consent; indexing alone does not create an answer. Answer review shows frozen cited excerpts, current/stale state and uncertainty. A valid page address does not establish that a claim is supported. The local results separate tested behavior from real-model quality, owner acceptance and release readiness.

How it works

  1. Register authoritative sources without changing them.

  2. Project each opaque source into one stable, machine-owned L1 Markdown read model.

  3. Connect evidence through typed relationships with provenance and review state rather than creating more notes.

  4. Interpret many sources through a small number of purpose-specific L2 knowledge views.

  5. Assemble dynamic or frozen context for a human review or agent task.

  6. Refresh only affected projections and dependants when sources change, with reconciliation and full sync retained for recovery and verification.

The default data-product profile covers sources, contracts, pipelines, analysis, models, outputs, governance, and operations. Additional packaged profiles support business operations, research/learning, software-project documentation, and minimal blank starts.

Inspired by Andrej Karpathy's "LLM wiki" pattern. See docs/positioning.md for the product landscape and boundaries.

Quick start

Create a vault without cloning MirrorArc itself. The installable command requires Python 3.11+; uvx and pipx run will build an isolated environment when they can find a compatible Python. Before the package is published to PyPI, use the Git URL:

uvx --from git+https://github.com/cz1993/MirrorArc.git mirrorarc init --profile data-product ~/my-data-product

# or, with pipx:
pipx run --spec git+https://github.com/cz1993/MirrorArc.git mirrorarc init --profile data-product ~/my-data-product

Once MirrorArc is published to PyPI, the equivalent short forms are uvx mirrorarc init --profile data-product ~/my-data-product and pipx run mirrorarc init --profile data-product ~/my-data-product.

For repeated local use, install the console command once:

uv tool install git+https://github.com/cz1993/MirrorArc.git
mirrorarc --version

# or, with pipx:
pipx install git+https://github.com/cz1993/MirrorArc.git
mirrorarc --version

Then open the vault in Obsidian if you want a human UI, point your agent at it (CLAUDE.md routes all agents to _meta/agent-rules.md), and run the installed command from any folder:

mirrorarc --root ~/my-data-product doctor          # check dependencies and vault structure
mirrorarc --root ~/my-data-product plan            # inspect proposed mirror actions first
mirrorarc --root ~/my-data-product sync            # mirror Office files and configured repos
mirrorarc --root ~/my-data-product status          # review manifest-backed lifecycle state
mirrorarc --root ~/my-data-product sync --json     # machine-readable sync evidence for agents/pilots
mirrorarc --root ~/my-data-product status --json   # machine-readable lifecycle status
mirrorarc --root ~/my-data-product doctor --json   # machine-readable preflight report
mirrorarc --root ~/my-data-product conversion --guide   # read-only conversion spot-check + guide
mirrorarc --root ~/my-data-product conversion --init-results # private quality review scaffold
mirrorarc --root ~/my-data-product conversion --results _meta/conversion-quality-results.yml --require-reviewed # after filling scaffold
mirrorarc --root ~/my-data-product migration       # dry-run report for legacy/unknown folders
mirrorarc --root ~/my-data-product migration --runbook  # legacy folder move protocol
mirrorarc --root ~/my-data-product migration --normalize-frontmatter-domains --worksheet # review domain alias cleanup
mirrorarc --root ~/my-data-product recovery --worksheet # review manifest recovery actions
mirrorarc --root ~/my-data-product sandbox --source-root /path/to/original-documents
mirrorarc --root ~/my-data-product catalog         # generate CATALOG.md inventory gateway
mirrorarc --root ~/my-data-product catalog --html  # generate the interactive CATALOG.html explorer
mirrorarc --root ~/my-data-product catalog --html --include-content # local content-review portal
mirrorarc --root ~/my-data-product code doctor     # optional local repository-analysis readiness
mirrorarc --root ~/my-data-product code analyze --repo <repo-id> # bounded revision evidence
mirrorarc --root ~/my-data-product code status --json # current/stale/failed analysis state
mirrorarc --root ~/my-data-product m365            # Microsoft 365/Copilot handoff readiness
mirrorarc --root ~/my-data-product review --json   # summarize metadata-only human review decisions
mirrorarc --root ~/my-data-product overlap         # calibrate overlap thresholds without note bodies
mirrorarc --root ~/my-data-product pilot           # aggregate pilot evidence, no source content
mirrorarc --root ~/my-data-product pilot --worksheet    # redacted Markdown private-pilot summary
mirrorarc --root ~/my-data-product benchmark            # validate agent-readiness task pack, if present
mirrorarc --root ~/my-data-product benchmark --init-tasks    # create private task scaffold
mirrorarc --root ~/my-data-product benchmark --worksheet     # print private benchmark run sheet
mirrorarc --root ~/my-data-product benchmark --init-results  # create private result scaffold
mirrorarc --root ~/my-data-product benchmark --results _meta/agent-readiness-results.yml --require-prompt-safety # after scoring
# edit tools/repos.yml, then:
mirrorarc --root ~/my-data-product sync           # mirror configured GitHub repos too
mirrorarc --root ~/my-data-product lint           # health check

Run sandbox from a duplicated pilot vault, not the original document folder. It is read-only and checks copy-boundary, mirror isolation, manifest/recovery readiness, and basic backup posture without printing source paths or document text.

Use review after spot-checking mirrors, catalogs, or handoff reports. It appends metadata-only decisions to _meta/review-ledger.jsonl with artifact hashes, so later changes are reported as stale reviews instead of silently preserving old approvals.

The generated CATALOG.html is a self-contained Catalog Explorer. It opens on INDEX.md, offers separate relationship-map, document-metadata, rendered-document, and contextual Code views, preserves explicit original-to-mirror lineage, and keeps local context-pack exports metadata-only. Repository analysis runs before generation; the passive HTML never starts a process or fetches data. The safe default does not embed document bodies. Use catalog --html --include-content only for a local review copy; that opt-in mode embeds bounded Markdown and generated-mirror bodies, so the resulting HTML must be protected like the vault itself. The public GitHub Pages demo is built from the explicitly public, provenance-documented example and passes the no-data gate before deployment. Neither mode requires an application server or creates an evidence index.

Source checkout fallback:

git clone https://github.com/cz1993/MirrorArc.git mirrorarc && cd mirrorarc
python3.11 -m pip install -e .
mirrorarc --version
mirrorarc profile list
mirrorarc init --profile data-product ~/my-data-product
mirrorarc init --profile business-operations ~/my-business-vault
mirrorarc init --profile research-learning ~/my-research-vault
mirrorarc init --profile software-project ~/my-software-vault
mirrorarc init --profile blank ~/my-blank-vault
mirrorarc --root ~/my-data-product profile validate
mirrorarc --root ~/my-data-product profile diff 0.2.0
mirrorarc --root ~/my-data-product profile migrate --plan
mirrorarc --root ~/my-data-product profile migrate --write
mirrorarc --root ~/my-data-product profile views --check
mirrorarc --root ~/my-data-product migrate annotations --plan
mirrorarc --root ~/my-data-product plan

The packaged v1 profiles are data-product (the default), business-operations, research-learning, software-project, and blank. Each initializes from the installable package with profile-owned folders, _meta/profile.yml, generated scaffold docs, and only the templates declared by its contract.

Profile contract details: docs/PROFILE_SCHEMA.md.

Step-by-step: docs/quickstart.md.

Documentation

The whitepaper defines architectural principles; the current Trustworthy Context plan governs this local batch. Earlier implementation plans record historical evidence, not current acceptance.

  • Product contract — audience, workflow, outcomes, and non-goals.

  • Quickstart — demo-first setup and daily workflow.

  • Sync specification — authority, mirroring, manifests, and refresh behavior.

  • Security model — trust boundaries, prompt safety, and local-review rules.

  • Profile schema — configurable domains, note types, folders, and policies.

  • Methodology — L0/L1, relationships, L2, context, review, and promotion discipline.

  • Positioning — where MirrorArc fits relative to LLM wikis, RAG, PKM, and document-management tools.

Status

v0 - technical alpha. Source-preserving L1 mirrors, manifests, lifecycle state, audit logs, journaled changed-file materialization, reconciliation, full recovery sync, profiles, lint/safety guards, the portable catalog, stable projection identities, and the versioned evidence-backed relationship ledger work today.

Dependency invalidation, L2 knowledge views, dynamic/frozen context assembly, and optional revision-bound Repository Intelligence are implemented locally. The current Ontario example is retained as migration and regression evidence; do not interpret its curated Markdown count as the target MirrorArc model. This remains a technical alpha, and local proof is not hosted or production proof.

License

MirrorArc is licensed under the GNU Affero General Public License v3.0 or later for the open core, with a separate commercial license planned for enterprise/closed use and consulting. LICENSE contains the full AGPL-3.0 text; commercial terms and contribution policy still require owner/counsel finalization before accepting outside contributions. See LICENSING.md. "MirrorArc" is a trademark — see TRADEMARK.md.

Credits

The "LLM wiki" pattern (Andrej Karpathy), markitdown (Microsoft), and Obsidian. Interoperates with — rather than competes with — tools like basic-memory and Copilot for Obsidian.

docs/PRODUCT_IMPLEMENTATION_PLAN.md

MirrorArc Knowledge-Projection Implementation Plan

Status: implemented and locally verified through Workstream 10; not released or published

Date: 2026-07-21

Architecture source: MIRRORARC_WHITEPAPER.md

Execution prompt: prompts/KNOWLEDGE_PROJECTION_KICKOFF.md

Repository: /Users/cz/workspaces/cz1993/MirrorArc

Local proof completed: 2026-07-21. The repository gate, fresh-install smoke test, deterministic rebuild comparison, 280-source mixed-format Ontario lifecycle exercise, and automated plus human portal validation passed locally. Commit, push, hosted CI, independent review, deployment, and publication remain separate operator-gated delivery steps.

1. Objective

Implement MirrorArc as a governed knowledge-projection system that:

  • preserves authoritative sources;

  • gives each opaque source one stable L1 Markdown projection;

  • stores typed, evidence-backed relationships as data rather than Markdown notes;

  • generates many-to-few L2 knowledge views that are ephemeral unless pinned or reviewed;

  • invalidates only affected relationships, views, reviews, and context when a source changes;

  • assembles dynamic and frozen context packs;

  • exposes the complete model in the portal;

  • proves the result against an expanded, mixed-format Ontario electricity corpus.

The goal is not complete when the code compiles or unit tests pass. It is complete only after the post-implementation Ontario corpus and portal validation in Workstream 10 passes.

2. Binding Principles

  1. L0 is authoritative. Original files, repositories, exports, and intentionally authored records are never silently replaced by a mirror or model output.

  2. L1 is one source identity to one projection identity. A clean projection can still be lossy; conversion warnings remain visible.

  3. Native readable sources are not duplicated without a reason. Markdown and plain text may be registered directly as readable source records.

  4. Relationships are ledger records, not notes. Every semantic relation carries evidence, method, hashes, freshness, and review state.

  5. L2 is many-to-few. It must not become a second one-file-per-source mirror.

  6. Derived output is ephemeral by default. Persistence requires a pin, review, audit, or reproducibility reason.

  7. Reviewed output is never silently overwritten. Source changes mark it stale and may create a replacement candidate.

  8. INDEX.md is the manual guide exception. It carries scope and navigation, not an unmaintainable factual summary.

  9. The deterministic core works without a model. AI may propose semantics and views but cannot own source truth or lifecycle correctness.

  10. No vector database. SQLite, explicit graph tables, and bounded text search are sufficient until evidence proves otherwise.

  11. No-data and rights gates remain release blockers. Public examples contain only synthetic or permissively licensed material with provenance.

3. Current Baseline

The repository already has:

  • package-owned Office/PDF and repository mirror engines;

  • source and repository manifests, hashes, lifecycle states, audits, and recovery behavior;

  • journaled changed-file capture, replay, reconciliation, locking, and full-sync recovery;

  • profile contracts and packaged template copies;

  • catalog and self-contained HTML portal generation;

  • lint, no-data, conversion review, human review, benchmark, pilot, and release checks;

  • the Ontario electricity example and public-safe provenance register.

The repository does not yet have:

  • a first-class semantic relationship/provenance store;

  • a dependency graph shared by journal, views, reviews, context, and portal;

  • L2 lens definitions or generated/reviewed/stale view lifecycle;

  • execution-grade dynamic and frozen context packs;

  • portal support for evidenced semantic relationships and L2 views;

  • linter rules that reject unexplained user-facing Markdown;

  • a migration from the existing curated-note model;

  • complex mixed-format end-to-end proof of the new architecture.

4. Scope and Non-Goals

In scope

  • canonical contract convergence;

  • migration reporting and safe compatibility handling;

  • L1 identity/cardinality enforcement;

  • relationship and provenance ledger;

  • dependency invalidation;

  • L2 knowledge-view definitions, rendering, review, pinning, and staleness;

  • context assembly;

  • portal/catalog integration;

  • template/profile/example migration;

  • tests, documentation, and Ontario corpus validation.

Out of scope unless required by an acceptance criterion

  • embeddings or vector databases;

  • hosted services or SaaS;

  • broad connector development;

  • package-part DOCX/PPTX/XLSX/PDF incrementality;

  • an Obsidian plugin;

  • a desktop shell;

  • autonomous promotion of model output into authority;

  • public deployment;

  • importing private, proprietary, personal, client, or company data;

  • private Ontario Grid analytics, forecasts, alerts, or client deliverables.

5. Technical Shape

The exact module split may change during implementation, but the intended ownership is:

src/mirrorarc/
  relationships/
    model.py          # relationship types, evidence, state, validation
    store.py          # SQLite schema/migrations and repository API
    deterministic.py  # MIRRORS, domain, lifecycle, dependency edges
    proposals.py      # optional semantic proposal admission and review
    invalidation.py   # affected-subgraph calculation
  knowledge_views/
    definitions.py    # profile-owned lens contract
    render.py         # bounded source-backed view generation
    lifecycle.py      # generated/reviewed/stale/superseded transitions
    store.py          # definitions, outputs, versions, dependency hashes
  context.py          # dynamic definitions and frozen evidence packs

Shared derived state should remain in .mirrorarc/state.sqlite behind versioned migrations. Do not create a second watcher, lifecycle authority, or unrelated database. Large bodies stay in source/L1/L2 artifacts; the database stores metadata, bounded evidence anchors, hashes, and state.

Preferred CLI convergence:

mirrorarc relationships refresh|status|review
mirrorarc view list|render|pin|review
mirrorarc context build|freeze|status
mirrorarc catalog --html [--include-content]

Names may be adjusted for consistency with src/mirrorarc/cli.py, but new behavior should be grouped instead of creating one top-level command per report.

6. Workstream 0 — Contract Convergence

Goal

Remove the old curated-wiki assumptions from all controlling contracts before code begins relying on new semantics.

Required changes

  • Update docs/PRODUCT.md:

    • replace curated hubs/entity pages with relationship ledger and L2 views;

    • distinguish selection manifests from executable context packs;

    • describe the portal as current foundation plus planned semantic capability.

  • Rewrite docs/methodology.md around L0, L1, relationships, L2, and context.

  • Update docs/information-architecture.md so folders classify sources and controls rather than require one note per conceptual object.

  • Update docs/PROFILE_SCHEMA.md with relationship vocabulary, knowledge lenses, Markdown categories, persistence policy, context budgets, and review rules.

  • Update docs/SYNC_SPEC.md, docs/RECOVERY.md, and docs/SECURITY_MODEL.md with dependency invalidation, view state, context sensitivity, and rebuild behavior.

  • Update root/template AGENTS.md, _meta/agent-rules.md, _meta/conventions.md, and templates so agents no longer create MOCs, entity pages, or durable knowledge notes by default.

  • Reduce or retire note templates that exist only to encourage derived Markdown proliferation.

  • Update CHANGELOG.md and any README/quickstart statements that still overstate the semantic graph or context-pack implementation.

  • Run scripts/sync_template_copies.py --write after canonical template changes.

Exit criteria

  • rg -n -i 'create.*(MOC|entity page|curated note|knowledge note)' finds no active instruction to generate those artifacts by default outside migration/history text.

  • Every canonical document uses the same authority and state terminology.

  • All Markdown links resolve and template-copy checks pass.

7. Workstream 1 — Inventory and Migration Contract

Goal

Understand every existing Markdown category before enforcing the new policy, and provide a safe, reviewable migration path.

Required changes

  • Extend the migration/reporting surface to classify each .md file as one of:

    • index;

    • authoritative_markdown_source;

    • l1_projection;

    • l2_generated_view;

    • l2_reviewed_view;

    • operational_control;

    • legacy_curated_derivative;

    • unknown.

  • Classify by declared source roots, manifest ownership, generated sentinels, frontmatter, and profile policy—not filename guesses alone.

  • Produce a machine-readable report and a human worksheet showing recommended disposition: register as source, regenerate, convert to lens definition, pin/review, archive, or remove.

  • Never delete or rewrite user content during a planning run.

  • Add a reviewed write mode only after tests prove idempotence and recoverability.

  • Preserve provenance when a reviewed L2 view is promoted to an authoritative Markdown source.

Exit criteria

  • The root template, packaged template, every built-in profile fixture, and Ontario example produce a complete classification with no unexplained Markdown.

  • Re-running the migration report is deterministic.

  • Write-mode tests prove that a backup/review gate is required and that unrelated files are not changed.

8. Workstream 2 — L1 Identity and Anti-Proliferation Invariants

Goal

Make the one-source/one-projection rule and allowed Markdown categories enforceable.

Required changes

  • Add stable projection identity to the manifest if current mirror path alone is insufficient.

  • Enforce at most one active L1 projection for each opaque source identity.

  • Detect sibling mirrors, orphan mirrors, manual generated-body edits, and mirror/source hash drift.

  • Register native Markdown/text sources as readable source records without mandatory duplication.

  • Add profile policy for cases where native source isolation or immutable projection is required.

  • Extend lint to reject unexplained user-facing Markdown while excluding declared operational controls, source Markdown, INDEX.md, L1, and governed L2 artifacts.

  • Add explicit count/inventory output so operators can see:

    • authoritative source records;

    • opaque sources requiring L1;

    • active L1 projections;

    • L2 generated/reviewed/stale views;

    • unexplained Markdown.

Exit criteria

  • Every opaque active source has exactly one current L1 or a declared conversion failure.

  • Native Markdown sources do not acquire redundant siblings by default.

  • A second sync is idempotent and creates no new Markdown.

  • Adding an unclassified generated note fails lint.

  • Existing source preservation, annotation, move/delete, recovery, and journal tests remain green.

9. Workstream 3 — Relationship and Provenance Ledger

Goal

Provide one shared, rebuildable source of derived relationship state.

Required changes

  • Add versioned SQLite tables for:

    • entities/artifact identities;

    • relationships;

    • evidence anchors;

    • relationship reviews;

    • dependency edges;

    • invalidation records;

    • schema metadata.

  • Implement deterministic relationships first: MIRRORS, DERIVED_FROM, IN_DOMAIN, lifecycle, profile membership, review dependency, and context membership.

  • Add typed semantic relationships: MENTIONS, SAME_ENTITY, SUPPORTS, CONTRADICTS, SUPERSEDES, DEPENDS_ON, and GOVERNS.

  • Store source/mirror hashes, bounded evidence anchor, generation method/version, optional model/prompt version, confidence, state, timestamps, and invalidation reason.

  • Treat model-derived relations as proposals until policy or review admits them.

  • Make rebuild deterministic when only deterministic rules are enabled.

  • Expose structured JSON status and export without copying full source bodies.

Exit criteria

  • The same source/manifests produce the same deterministic graph after deletion and rebuild.

  • No relationship can be displayed as accepted without a deterministic rule or evidence/review record.

  • Rejected and invalidated relationships remain auditable but are excluded from current views.

  • Database migrations work from an existing technical-alpha journal database.

  • No second event watcher or authority path is introduced.

10. Workstream 4 — Dependency Invalidation

Goal

Make source changes propagate accurately and only as far as necessary.

Required changes

  • Connect successful journal application to the relationship dependency graph.

  • On source create/change/move/delete:

    • update L1 and deterministic relations;

    • invalidate semantic relations tied to old hashes;

    • mark dependent reviewed views stale;

    • queue eligible generated views for replacement;

    • mark frozen context freshness appropriately;

    • keep dynamic context definitions intact so they resolve current state next time.

  • Record the journal sequence and source hash that caused each invalidation.

  • Add bounded affected-subgraph traversal and cycle protection.

  • Keep full reconciliation able to repair missed invalidations.

Exit criteria

  • Changing one source does not scan, hash, reinterpret, or rewrite unrelated source bodies or views.

  • A reviewed view is preserved and marked stale rather than overwritten.

  • Move-only changes preserve semantic identity where evidence still resolves.

  • Missed events followed by reconciliation produce the same final state as live capture.

11. Workstream 5 — L2 Knowledge Views

Goal

Implement many-to-few human interpretation without returning to a curated-note factory.

Required changes

  • Add profile-owned lens definitions with:

    • purpose and audience;

    • source/relationship query;

    • required relationship/review state;

    • output structure;

    • citation rules;

    • content/token budget;

    • refresh and persistence policy.

  • Implement deterministic lens rendering where possible before model synthesis.

  • Add bounded model-assisted rendering behind an interface that records model and prompt versions.

  • Implement states generated, reviewed, stale, superseded, and failed.

  • Store view definition, dependency hashes, citations, generation record, and output hash.

  • Default to cache/on-demand rendering; create a durable file only for pin, review, audit, or reproducibility.

  • Add promotion workflow from reviewed view to new authoritative source, requiring explicit human intent and preserving derivation history.

  • Prevent one-lens-per-source defaults in built-in profiles.

Exit criteria

  • One view can synthesize many sources and cite each factual section.

  • Re-rendering unchanged dependencies is idempotent.

  • Reviewed, stale, and generated candidates are visibly distinct.

  • A profile cannot silently enable automatic promotion into authority.

  • Tests demonstrate fewer persistent L2 artifacts than input sources for representative workflows.

12. Workstream 6 — Context Assembly

Goal

Turn selection manifests into useful, governed task context.

Required changes

  • Preserve metadata-only export as a safe selection-manifest mode.

  • Add dynamic context definitions that store purpose, selection rules, budgets, freshness policy, and permitted artifact types.

  • Add frozen evidence packs containing bounded excerpts or resolvable content, citations, source and mirror hashes, relationship evidence, view versions, timestamps, sensitivity, and warnings.

  • Enforce content/token/file-count budgets.

  • Record omitted items and reasons rather than silently truncating.

  • Make context construction deterministic when inputs and ordering are unchanged.

  • Treat document content as untrusted evidence and prevent prompt instructions from changing selection or policy.

Exit criteria

  • A dynamic pack resolves newly current evidence after a source change.

  • A frozen pack remains byte-stable and reports that newer source versions exist.

  • A receiving agent can execute a defined offline task from a frozen pack without needing undocumented external context.

  • Metadata-only mode never copies source, mirror, or view bodies.

  • Content-inclusive modes inherit and display the vault's sensitivity and redistribution policy.

13. Workstream 7 — Portal and Catalog Integration

Goal

Expose the new architecture without duplicating relationship or lifecycle logic in JavaScript.

Required changes

  • Extend the shared catalog report model to include governed relationship, evidence, view, and context state.

  • Keep the safe catalog metadata-only by default.

  • Collapse source/L1 pairs into one evidence card by default, with lineage expansion.

  • Add filters for relationship type, evidence state, confidence, lifecycle, view state, source format, and freshness.

  • Show evidence anchors and why a relationship exists.

  • Add knowledge-view navigation and generated/reviewed/stale labels.

  • Add dynamic/frozen context builder modes and budget feedback.

  • Use clustering and progressive disclosure to avoid graph hairballs.

  • Retain keyboard navigation, responsive layout, safe Markdown rendering, and no-network portable behavior.

  • Do not add an independent portal database or relationship inference code.

Exit criteria

  • Every displayed semantic edge resolves to a ledger record and evidence state.

  • Source authority and generated/reviewed/stale status are distinguishable without opening raw metadata.

  • The portal remains usable with hundreds of sources and thousands of relationships.

  • Metadata-only output contains no source or mirror bodies.

  • Content-inclusive output is visibly labeled local/sensitive.

  • Automated browser checks cover the critical navigation and context-building paths.

14. Workstream 8 — Templates, Profiles, and Ontario Migration

Goal

Make new vaults start correctly and migrate the existing Ontario example without hiding the legacy problem.

Required changes

  • Update built-in profiles to declare source roots, allowed Markdown categories, relationship vocabulary, lenses, persistence rules, and context budgets.

  • Replace proliferation-oriented note templates with source-record, lens-definition, review, and promotion workflows.

  • Keep INDEX.md short and manually understandable.

  • Run the migration inventory against the existing Ontario vault.

  • Convert valuable reusable structures into lens definitions or deterministic relations.

  • Remove or archive legacy curated derivatives only after their disposition is reviewed and the new product can regenerate the intended knowledge from sources.

  • Do not invent missing originals to justify legacy Markdown.

  • Preserve the existing Ontario directory as the one flagship topic; do not create a parallel competing Ontario example.

  • Update examples/DATA_PROVENANCE.md, examples/README.md, screenshots, and portal assets only after the migrated output is correct.

Exit criteria

  • A fresh mirrorarc init creates no default user-facing knowledge-note pile.

  • Every Ontario Markdown file has an allowed category and provenance/state.

  • The Ontario baseline contains source records, L1, operational controls, INDEX.md, and only deliberately generated/pinned/reviewed L2 views.

  • Removing all derived state and rebuilding produces the same current L1, deterministic graph, and deterministic views.

15. Workstream 9 — Full Validation and Release Readiness

Required automated gates

Run the narrowest relevant tests during development, then the complete local gate before any push:

python3.11 -m pytest
mirrorarc --root examples/ontario-electricity-evidence-vault lint
python3.11 scripts/sync_template_copies.py --check
python3.11 scripts/no_data_scan.py
python3.11 -m build
python3.11 -m pip check
git diff --check

Run these commands from an isolated Python 3.11 environment with the package and build tooling installed. Adjust an invocation only if the package's canonical command surface changes, and do not substitute a template-only check for the full suite.

Required test matrix

  • schema migrations from the current journal database;

  • unit tests for identities, relations, evidence anchors, invalidation, view state, and context;

  • property/idempotence tests for replay, rebuild, and unchanged regeneration;

  • migration tests for every built-in profile and the Ontario example;

  • no-proliferation lint tests;

  • deterministic rebuild tests;

  • one-changed-source structural performance tests;

  • prompt-injection and untrusted-content tests;

  • path, symlink, secret, PII, rights, and public-export tests;

  • browser tests for the portal;

  • packaging and fresh-install smoke tests on a disposable vault.

Exit criteria

  • All local tests and repository gates pass.

  • Documentation and CLI help match implemented behavior.

  • No generated cache, source data, portal output, or test residue is accidentally tracked.

  • The current working tree is reviewed for unrelated pre-existing changes before staging.

  • Hosted CI is used as confirmation only after the local gate passes and shipping is authorized.

16. Workstream 10 — Post-Implementation Ontario Corpus and Portal Proof

This is a post-code validation phase but part of the overall goal's finish line. Do not mark the goal complete before it passes.

16.1 Corpus boundary

Continue using examples/ontario-electricity-evidence-vault/ as the canonical Ontario electricity topic and profile. Do not create a second flagship example with the same subject.

Two corpus tiers are permitted:

  1. Committed public subset: synthetic or genuinely public, permissively licensed files with exact provenance and licence records. This subset may support the public demo.

  2. Large local stress corpus: an operator-controlled disposable copy of the same Ontario vault for public but non-redistributable, very large, or uncertain-rights material. It remains outside Git and public portal artifacts. Prefer metadata-only references when the content cannot be stored safely.

Official publication does not prove redistribution rights. Non-official material requires the same licence and provenance review. Never import private GuildBuild/Data Lab material, unpublished IESO work, personal information, client data, forecasts, alerts, credentials, or proprietary analysis.

16.2 Acquisition scope

Research current sources live after the implementation is complete. Build a diverse evidence set covering, where rights permit:

  • Ontario government energy policy, planning, legislation, open data, and methodology;

  • IESO public market rules, planning outlooks, reliability material, historical reports, and data directories;

  • OEB public decisions, rate/regulatory material, open-data resources, and consumer guidance;

  • federal or interprovincial energy context relevant to Ontario;

  • municipal, academic, standards, industry, NGO, and other non-official analysis;

  • historical datasets, glossaries, maps, technical reports, workbooks, and public repositories.

Exercise at least these source classes:

PDF
DOCX
XLSX
CSV/TSV
Markdown/plain text
HTML or metadata-only web reference
PPTX when a relevant rights-cleared source is available
Git repository or structured code/config fixture

Target a minimum of 200 eligible source records and enough diversity to include at least five opaque/readable format classes, ten independent publishers or source series, multiple dates or versions, duplicate/superseded records, cross-source agreement and disagreement, and at least one large file. A 500–1,000 record local stress corpus is encouraged when acquisition rights, storage, and runtime remain reasonable. The committed public subset may be smaller.

For each acquired item record:

  • publisher and title;

  • canonical URL;

  • retrieval date;

  • licence and attribution;

  • redistribution disposition;

  • original filename and format;

  • SHA-256;

  • topic/date/version;

  • whether the item is committed, metadata-only, synthetic, or local-validation-only.

Update examples/DATA_PROVENANCE.md for committed material. Store a machine-readable acquisition manifest alongside the local validation evidence without committing restricted bodies.

16.3 End-to-end simulation

Create a disposable working copy from the canonical Ontario vault when destructive lifecycle tests or non-committable sources are involved. Then run the product as a user would:

  1. clean install or build the package in an isolated Python 3.11 environment;

  2. run doctor and source-boundary checks;

  3. run plan and inspect proposed admission and L1 actions;

  4. run a full baseline sync;

  5. build deterministic relationships and eligible semantic proposals;

  6. generate the configured L2 views;

  7. build dynamic and frozen context packs;

  8. run status, lint, conversion-quality, review, and safety reports;

  9. regenerate the local content-inclusive portal;

  10. run a second unchanged pass and prove idempotence;

  11. change one source and prove bounded refresh/invalidation;

  12. move, delete, and restore selected sources and prove reconciliation/recovery;

  13. rebuild derived state from sources and compare current hashes and counts.

Capture machine-readable evidence for source counts, L1 cardinality, relationship counts by type and state, L2 counts and dependency sizes, invalidation fan-out, context budgets, warnings/errors, converter calls, files read/hashed, and elapsed time.

16.4 Portal validation

Serve the generated portal locally and validate it with automated browser checks plus human visual inspection. Required scenarios:

  • start at INDEX.md and reach evidence within three interactions;

  • search and filter hundreds of source records;

  • inspect a collapsed source/L1 pair and expand its lineage;

  • follow a typed semantic relationship to its evidence anchor;

  • distinguish deterministic, proposed, accepted, rejected, and invalidated edges;

  • open generated, reviewed, and stale knowledge views;

  • observe a source change propagate to edge/view/context freshness;

  • create a dynamic context definition and a frozen evidence pack;

  • confirm metadata-only mode contains no bodies;

  • confirm content-inclusive mode carries a local/sensitive warning;

  • validate keyboard navigation, responsive layout, readable long filenames, no clipped cards or relationship labels, and no graph hairball at scale;

  • verify all links and downloaded packs resolve correctly.

Use screenshots only as supporting visual evidence. Portal correctness must be backed by report, ledger, hash, and browser-test evidence.

Do not deploy or update GitHub Pages during this phase unless the operator separately authorizes a public release after rights, no-data, local tests, independent review, and hosted CI are green.

16.5 Final acceptance criteria

The implementation goal is complete only when:

  • the complex Ontario corpus passes source, licence, provenance, and no-data gates;

  • opaque-source/L1 cardinality is correct with no sibling or orphan mirrors;

  • unexplained user-facing Markdown count is zero;

  • deterministic relationships rebuild identically;

  • semantic relationships carry evidence and explicit state;

  • persisted L2 views remain materially fewer than source records;

  • reviewed-view staleness and replacement behavior is proven;

  • dynamic and frozen context behavior is proven;

  • changed-source work is bounded to the affected dependency graph;

  • recovery produces a consistent final state;

  • the portal scenarios pass at target scale;

  • all local repository, packaging, template, lint, and safety gates pass;

  • the final report distinguishes implemented proof, known limitations, and any work still gated.

17. Delivery Sequence and Stop Rules

Workstreams are ordered. A later workstream may begin only when the contracts it depends on are stable and its predecessor's tests pass.

0 contracts
  → 1 migration inventory
  → 2 L1 invariants
  → 3 relationship ledger
  → 4 invalidation
  → 5 L2 views
  → 6 context
  → 7 portal
  → 8 templates/Ontario migration
  → 9 full local gate
  → 10 expanded Ontario proof

Stop and report a binding blocker when:

  • safe migration would require deleting or reclassifying user-owned content without a review gate;

  • a required source lacks redistribution or local-use rights;

  • a model/provider is required for a mandatory deterministic acceptance criterion;

  • source or derived content would cross a private/public boundary;

  • an unchanged failing gate repeats with no new hypothesis;

  • completion would require deployment, outreach, commit, push, merge, or another external action not explicitly authorized.

Do not call the goal complete because documentation is updated, a schema exists, synthetic unit tests pass, or the portal renders a small fixture. The Ontario end-to-end proof is the finish line.

18. Required Completion Report

The final execution report must include:

  • files and modules changed;

  • architecture and migration decisions made;

  • automated test commands and exact results;

  • corpus composition and rights disposition;

  • source/L1/L2/relationship/context counts;

  • changed-source performance and invalidation evidence;

  • portal URL used locally and browser scenarios passed;

  • screenshots or visual evidence paths when created;

  • remaining known limitations;

  • git status and explicit statement of whether anything was committed, pushed, deployed, or published.

439 files · 404 not served here

Advantages

Limitations

  • No ZIP download: install it from its source (a rule-derived fact from the brain’s files)

Security

Risk level: Low risk

This brain runs

Git hooks (1)

  • .githooks/pre-commit (pre-commit): runs on git pre-commit

Agent instructions that run or fetch something (2)

  • AGENTS.md: Operator direction (2026-09-18): project development and validation run locally.
  • AGENTS.md: Every behavior change: run the package-owned vault lint through the example's tool shim, run the test suite, and update `CHANGELOG.md` and relevant docs.

Install scripts (1)

  • scripts/init.sh: sh scripts/init.sh
  • Low risk: scripts-present (.githooks/pre-commit)
  • Low risk: scripts-present (scripts/init.sh)

Attribution and licence

First committed by
GitHub avatar of cz1993cz1993
Declared authors
  • cz1993 (declared in pyproject.toml)
Publisher
Ci Zhu (Community)
Source
cz1993/MirrorArc · commit 1df13eb
Licence
GNU Affero General Public License v3.0 only (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
cz1993

AutoGineer is not affiliated with or endorsed by cz1993.

Install from source

404 of its files are not served here, so there is no ZIP. cz1993/MirrorArc at 1df13eb