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/TRUSTWORTHY_CONTEXT_EXECUTION_PLAN.md

Trustworthy Context — Execution Plan

Date: 2026-09-18

Status: implemented; final local evidence is in the developer handoff. Planning-session acceptance has not started.

Owner: cz1993. Development: separate Codex session. Review: originating planning session.

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

Related documents:

1. Outcome and scope

Make MirrorArc's context exports trustworthy, task-relevant, measurable, and understandable to a new user. Preserve the source-to-projection-to-ledger-to-view architecture. This is an extension of the current working tree, not a rewrite or restart of the August implementation.

Required work: reproduce and close evidence/policy/resource-boundary defects; implement a compact evaluation loop; add deterministic task-driven retrieval through existing context assembly; improve the first-use and Catalog journey; validate the complete local package; prepare a review handoff. Required experiments: bounded CodeGraph upgrade and difficult-document extraction comparisons. Their adoption is conditional on results, not a predetermined requirement.

Completion states are distinct:

  1. Implemented: required changes exist, with focused verification.

  2. Locally validated: complete local gate and clean-wheel proof pass for a fingerprinted tree.

  3. Accepted: this planning session reviews the evidence and current tree and accepts shipment.

  4. Shipped: the owner-approved consolidated PR is merged, with its resulting SHA recorded.

No development session may label itself independently accepted. Local proof does not establish hosted, Linux, production, universal retrieval superiority, or deployment proof.

2. Operator policy and authority

  • All development and tests are local. No intermediate pushes, per-workstream PRs, hosted CI dispatches, ADS review loops, automatic reviewer sessions, or hosted-CI acceptance dependency.

  • No commit, push, merge, publication, deployment, tag, global installation, or remote setting change during development. Prepare one final shipment only after planning-session acceptance.

  • Preserve the existing dirty tree, including tracked edits, deletions, and untracked modules. Do not reset, stash, discard, broadly reformat, or reconstruct it from HEAD. An ordinary clean worktree from HEAD would omit the current implementation; do not use that as the baseline.

  • Use disposable copies and isolated dependency environments for tests and tools. Downloading verified open-source dependencies for local tests is allowed; no global provider installation.

  • No private corpus ingestion, paid model calls, cloud document upload, or external telemetry is newly authorized by this plan. If measured model evaluation needs an endpoint, obtain explicit endpoint/data/spend approval; continue other work while that prerequisite is unresolved.

  • The planning session remains a planning/review session. Do not start implementation there or create another task automatically from the kickoff document.

3. Baseline and findings

At planning time: branch codex/knowledge-projection; HEAD 15ce475a5077ce9d048a3f38a9a832a08976ffd9; extensive existing uncommitted implementation. Capture fresh state before work. A HEAD SHA alone is not a fingerprint of this batch.

The September review passed diff formatting, no-data scan, and template-copy checks. It did not rerun the full suite, fresh-wheel proof, or browser journeys. Earlier recorded test totals are historical evidence only. Two defects were reproduced using isolated execution of the actual helper functions, not the entire installed product; turn these into public-path regressions.

IDObserved issueInitial locationEvidence level
TC-01Merged line ranges retain only the first excerpt/hash, overstating included evidencecode_intelligence/service.py::_merge_evidenceIsolated helper reproduction
TC-02Frozen and code context paths do not enforce allowed_modes consistentlycontext_assembly/builder.py, code_intelligence/context.pyStatic inspection; reproduce through CLI
TC-03max_tokens * 4 counts excerpt characters, not complete serialized model inputBoth context buildersStatic inspection
TC-04Base-ref diff excludes staged/working-tree changes despite local-tree snapshotsservice.py::_changed_from_baseStaged rename + base HEAD returned no changes
TC-05Catalog frozen-context command discards symbol/base/changed-path requestservice.py::catalog_reportStatic inspection
TC-06Provider output cap is checked after unbounded subprocess bufferingadapter.py::_runStatic inspection
TC-07Source hashing precedes copying; reused snapshot cache is not independently verifiedSnapshot helpers in service.pyRisk identified; controlled race/tamper test required

Function locations are hints, not permanent line numbers. Re-check current behavior; if a finding has already been fixed, show the passing regression rather than duplicate the implementation.

4. Invariants and non-goals

  • L0 originals remain authoritative and unchanged. Native Markdown/text is not duplicated to satisfy a projection count. One active opaque source normally has one active L1 projection.

  • Relationships are evidence/state in the existing ledger. Proposed or rejected edges cannot become accepted retrieval authority. Reviewed views are preserved and marked stale.

  • Keep one watcher, lifecycle authority, connector/sync path, and governed storage architecture. No vector DB, second code provider, bulk AST import, generic plugin framework, new daemon, MCP dependency, autonomous relationship acceptance, or hosted service.

  • Catalog stays passive, portable, safe-rendered, and metadata-only by default. Content inclusion is explicit and sensitivity-aware. Browser selection is not governed context creation.

  • Source text is untrusted data. It cannot change policy, execute commands, request credentials, authorize external calls, or control review decisions.

  • CodeGraph remains an optional pinned ordinary-CLI subprocess with telemetry/update checks off: DO_NOT_TRACK=1, CODEGRAPH_TELEMETRY=0, CODEGRAPH_NO_UPDATE_CHECK=1.

  • Do not make deterministic integrity dependent on model judgment or generated summaries.

5. Workstreams and exit gates

W0 — Capture a reproducible baseline

Read applicable agent rules, README, whitepaper, product, this plan, security, recovery, profile, context and benchmark contracts. Inspect package, tests, template-copy tooling, all workflow triggers, and existing synthetic fixtures before changing behavior.

Record branch/HEAD, porcelain status including untracked paths, relevant content hashes, Python, platform and dependency versions, provider availability, and pre-existing test failures. Keep raw logs/caches outside the publication tree. Establish a small reproducible local dependency setup (tested constraints or equivalent), without over-pinning consumer dependencies blindly.

Exit: baseline distinguished from this batch's changes; focused tests runnable; no existing work lost. Missing dependencies require an isolated setup attempt, not an immediate blocker claim.

W1 — Evidence, policy, budgets, and process integrity

Implement TC-01 through TC-07 with focused regression tests before broad feature work:

  • Store exact span-to-text correspondence. Merge overlapping/disjoint spans deterministically; recompute appropriate hashes; explicitly report removed files/spans and truncation. Distinguish source citations from content actually present. offline_complete must mean what it says.

  • Apply allowed modes, sensitivity, and content inclusion consistently at public and internal creation boundaries. A metadata-only profile must not create a frozen body through another CLI path, saved definition, or code-analysis option. No side effects on rejected requests.

  • Budget the final exported context representation, including instructions, metadata, citations, and omissions. Either support an explicitly named tokenizer/version for a strict token ceiling, or label a deterministic byte/character ceiling and token estimate honestly. Do not advertise a model-independent hard token guarantee. Handle overhead-only overflow without invalid output; report effective limits and method. Include non-ASCII/code and tiny-budget cases.

  • Define base semantics explicitly. Preserve compatibility where possible: distinguish committed base-to-HEAD changes from staged/unstaged/untracked changes. Whichever mode is selected must match the analyzed tree. Handle rename/deletion/binary/ignored paths with visible omissions; deleted files cannot be cited as current source bodies.

  • Preserve the exact analysis selection in Catalog context actions, safely quoting paths and arguments, or reuse its stored governed definition. Test spaces and option-like input.

  • Bound stdout/stderr while reading, enforce timeout, clean up child processes on supported platforms, and avoid publishing partial invalid results. Test excessive output and a hung child.

  • Verify copied snapshot content against its recorded tree identity; detect mutation during copy and cache tampering. Use a bounded retry/fail-stale path, not an infinite reconciliation loop. Traverse excluded directories efficiently and keep resource ceilings explicit.

Exit: public-path regressions demonstrate correct excerpts, denied policy bypasses, honest budget semantics, correct change scope, preserved selection, bounded execution, and verified snapshots. Update affected profile/security/recovery contracts and historical proof qualifications.

W2 — A compact, reusable evaluation loop

Extend benchmark.py and the existing benchmark contract; do not create a second results system. Use a small fixed pack (initial target 12 tasks) across three small synthetic/rights-cleared collections: mixed documents, conflicting/revised documents, and the existing synthetic code repository. Reuse existing fixtures; no large corpus or language matrix. Cover answer, reconcile, update, audit, consolidation, insufficient-evidence, and document-instruction attacks.

Before tuning, fix task IDs, expected evidence/answers, source revisions, scoring rules, and a small held-out subset. Compare raw sources, plain conversion, and governed MirrorArc context with the same model, prompt, tool permissions and budget where comparable. Record unsupported input differences rather than silently giving one mode privileged access. Separate deterministic retrieval tests from model outcome evaluation; manual invented results are never measured results.

Record correctness (existing 0–2 scoring), citation accuracy, evidence coverage, stale-evidence use, abstention, privacy/prompt-safety failures, latency, token count, and human corrections. Use deterministic checks for hashes/spans/policies and human calibration for semantic grading. Report per-task outcomes and repeats for stochastic runs; do not claim significance from a tiny sample.

Promptfoo is an optional dev-only runner if it reduces code, never a runtime dependency. Disable unneeded external features; model calls require the approval in section 2. Keep raw private result packs outside the repo and preserve current no-data restrictions; commit only allowed synthetic fixtures and sanitized aggregate evidence.

Exit: runnable deterministic benchmark, reproducible task manifest, baseline results and honest model-evaluation status. If endpoint/spend approval is unavailable, label empirical agent outcome evaluation pending, with an exact rerun command; do not falsely claim superiority or full acceptance.

W3 — Task-driven retrieval through existing context assembly

Implement deterministic lexical/heading retrieval using SQLite FTS5/BM25 in the existing derived storage architecture, not a second authoritative database. Probe FTS5 availability and give a clear supported fallback/error. Index allowed authoritative text/L1; preserve source identity, hashes, provenance, sensitivity, and freshness. Index schema/version is disposable and rebuildable.

Add a task/query input to existing context commands rather than a parallel command family. Rank matches with stable tie-breaking, deduplicate source identities, and expand only through permitted current deterministic/accepted relationships. Bound hops, candidates, files, and export size; prevent cycles. Never let a retrieval cache elevate rejected/proposed/stale edges into authority.

Show why each result was selected, source spans, score/ranking method, freshness, and exclusions. Propagate changed/deleted sources via existing invalidation. Do not offer opaque confidence as truth. Preserve compatibility for existing saved contexts and explicit selections.

Exit: same task/tree yields stable selection; cache deletion rebuilds equivalent results; source change invalidates affected selections; held-out evaluation compares retrieval to the baseline. If gains are absent, report that result and keep the old default or gate the new mode as opt-in.

W4 — One understandable user journey

Consolidate README/quickstart/INDEX and the existing synthetic-code walkthrough around: choose a task → inspect selected evidence → understand warnings/omissions → export context. Keep the existing short optional code doctor / code analyze / catalog --html flow.

Catalog must explain selected/not selected, included/reference-only, source revision/freshness, mode and sensitivity. Preserve the request in the next action. No backend execution or network fetch in HTML. Avoid a UI rewrite: extract shared policy/report semantics only when needed. Remove stale future-tense claims and outdated hubs/entity-page benchmark descriptions.

Exit: verify three browser journeys (setup/empty, useful current selection/export, stale/failure) at desktop and narrow width, including keyboard focus, long paths, safe rendering, and metadata versus content-inclusive output. Record screenshots and exact commands. An agent-run walkthrough is not evidence of an independent novice usability study; obtain operator feedback at review.

W5 — Evidence-gated upstream experiments

  1. CodeGraph: compare pinned v1.5.0 with researched v1.6.0 in disposable installations on the same small repository. Verify machine-readable contracts, symbol/call/impact/affected-test results, edit/rename/delete refresh, cache recovery, telemetry suppression, and failure behavior. Re-verify upstream installer/checksums before documenting a new pin. Promote only on a green contract suite and concrete benefit; otherwise retain v1.5.0 with reasons. No agent installer.

  2. Docling: compare with current MarkItDown on a handful of synthetic difficult PDFs/tables/ scans. Record extraction errors, source/page anchors, time, peak memory where measurable, package/model versions, licensing, and model-download/network behavior. A useful measured result permits a narrow optional converter path through existing L1 lifecycle; otherwise record a no-adoption decision. Never change the default merely because the tool is popular.

  3. PageIndex: design reference or isolated optional comparison only. Its local SDK may use a remote model. Runtime integration and model-dependent retrieval authority are out of scope.

Timebox each primary experiment to one representative comparison and at most one bounded fix per concrete failure hypothesis. If upstream remains unsuitable, record evidence and stop that experiment without expanding to another provider. Required outcome is a decision, not adoption.

Exit: versioned comparison records and adopt/defer decisions; promoted changes rerun impacted gates. No unsupported claims about untested platforms or extractors.

W6 — Final local validation and developer handoff

Run focused tests while iterating; run the complete repository gate near completion, not after every edit. Derive local parity from the current CI/release scripts, without dispatching them. Minimum final checks:

  • git diff --check

  • python scripts/no_data_scan.py

  • python scripts/sync_template_copies.py --check

  • Python compilation and POSIX shell syntax checks for applicable files.

  • Full python -m pytest with exact counts, duration, failures/skips, and dependency versions.

  • Template lint and regenerated disposable Ontario example lint using the installed runtime and each copy's tools/lint_vault.py; record all warnings. Do not overwrite example source files.

  • Scan generated artifacts separately for no-data/provenance safety.

  • Build wheel in a temporary output directory, install into a fresh Python 3.11 environment, run dependency consistency checks and CLI help/initialization smoke outside the source checkout.

  • Fresh-wheel journey: sync source → select task → inspect correct current evidence → create allowed context → view portable Catalog → mutate synthetic source → detect staleness → rebuild.

  • Real pinned-provider smoke and cache-delete/rebuild; required W4 browser checks; W2/W3 evaluation.

  • Hash originals before/after; confirm no global configuration edits, telemetry, tracked caches, secrets, private results, or unexpected network requests.

Report host/platform truthfully. Local Linux validation may use an already available disposable container/runtime; do not claim Linux proof if unavailable or make hosted CI a substitute.

Create docs/TRUSTWORTHY_CONTEXT_HANDOFF.md only when actual evidence exists. Include W0–W6 status, TC-01–TC-07 regressions, changed-file scope, test commands/results, benchmark outcomes, dependency/ provider versions, UI evidence paths, original-source preservation, known limitations, unresolved approvals, and precise reproduction instructions. Include SHA-256 manifest of intended shipping files (including untracked additions and a deleted-path list) outside generated output; record its digest in the handoff. Exclude the handoff/manifest themselves from self-referential hashing and state that exclusion. Do not record credentials or private source bodies.

Exit: handoff ready for this planning session, not self-approved or shipped. A failed required gate stays failed with concrete evidence; no softened criteria to obtain a green summary.

6. Post-development review and single shipment

This session uses the review checklist, inspects the live tree independently, and records acceptance or bounded corrections. Development addresses corrections locally; review repeats on the new tree fingerprint. No GitHub round trips are needed.

After acceptance, the operator activates final shipment. Reconcile exact intended additions, edits and deletions across the old dirty baseline and this batch; do not blindly stage the entire workspace. Preserve owner identity and author one consolidated PR, then merge the accepted head. No history rewrite or force-push is implied. Record branch/base/head/merge SHAs and final status.

Before any push, inspect live remote state and local workflow triggers. At planning time:

  • ci.yml runs on PR events and pushes to main;

  • pages.yml can deploy on relevant main changes and manual dispatch;

  • release.yml runs on version tags.

Hosted checks are not required by this project policy, but an existing remote protection may still enforce them. Do not falsify status, use an admin bypass, or weaken remote rules automatically. If zero hosted runs are required, prepare a narrowly scoped manual-only workflow change for review before shipping. If protections or deployment intent are unresolved, stop before the push and ask the owner to choose. Do not rely on skip markers to suppress every workflow. Code PR merge does not imply permission for Pages deployment, release tags, package publication, or global install.

7. Research basis and adoption discipline

Sources reviewed 2026-09-18; re-check contracts at implementation time, not floating versions at runtime. Upstream claims are experiment hypotheses, not MirrorArc benchmark results.

  • CodeGraph v1.6.0: incremental index correctness, graph fixes, and WAL recovery justify a compatibility experiment.

  • SQLite FTS5: mature BM25/snippet functionality supports a small deterministic lexical baseline, not a new external service.

  • Promptfoo: optional evaluation/red-team runner.

  • Docling: structured extraction and OCR candidate.

  • PageIndex: hierarchical/vectorless retrieval reference; local storage must not be confused with offline model inference.

  • Context engineering: selective just-in-time context informs the task-first direction.

  • Official Codex prompting guidance: kickoff specifies the outcome, relevant repository context, constraints, and verification evidence explicitly.

8. Progress ledger

Update evidence/status only after work occurs. Use pending, active, passed, failed, or conditional; include a reason and evidence path for conditional work. Never pre-fill passing results.

WorkstreamInitial stateEvidence
W0 baselinecompleteInitial dirty status/diff/hashes and 14-pass baseline retained; see handoff.
W1 integrityimplemented / locally checkedTC-01–TC-07 public regressions, streaming/snapshot/byte-budget checks and actual provider proof.
W2 evaluationdeterministic complete; empirical pendingFixed 12-task pack before tuning; model metrics null without endpoint/data/spend approval. See results.
W3 retrievalcomplete, opt-inExisting FTS5 store, stable/current accepted selection, rebuilds and invalidation; coverage 0.55 → 0.90, held-out tc11 regression retained.
W4 user journeyimplemented / browser checkedFresh-wheel empty/current/stale/failure, desktop/narrow and keyboard proof; independent novice feedback pending.
W5 upstream experimentscomplete, no adoptionCodeGraph 1.5.0 retained; Docling missing offline models after one retry; MarkItDown scan/column limitations recorded.
W6 final local proof/handoffdeveloper evidence supplied; not acceptedSee handoff, exact final logs and file manifest. Planning review and shipment checkpoint remain pending.
Planning-session acceptancepending—
Single GitHub shipmentnot authorized to start—

Developer evidence: handoff, benchmark results, upstream decisions. No reviewer acceptance is implied.

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