AtoCore Operations

This is the current operating playbook for making AtoCore more dependable and higher-signal.

Order of Work

Retrieval-quality pass
Wave 2 trusted-operational ingestion
AtoDrive clarification
Restore and ops validation

1. Retrieval-Quality Pass

Observed behavior from the live service:

broad prompts like gigabit and polisher still surface archive/history noise
meaningful prompts like mirror frame stiffness requirements and selected architecture are much sharper
now that the corpus is large enough, ranking quality matters more than raw corpus presence

Use these commands first:

python atocore.py audit-query "gigabit" 5
python atocore.py audit-query "polisher" 5
python atocore.py audit-query "mirror frame stiffness requirements and selected architecture" 5 p04-gigabit
python atocore.py audit-query "interferometer error budget and vendor selection constraints" 5 p05-interferometer
python atocore.py audit-query "polisher system map shared contracts and calibration workflow" 5 p06-polisher

What to fix in the retrieval pass:

reduce _archive, pre-cleanup, pre-migration, and History prominence
prefer current-status, decision, requirement, architecture-freeze, and milestone docs
prefer trusted project-state over freeform notes when both speak to current truth
keep broad prompts from matching stale or generic chunks too easily

Suggested acceptance bar:

top 5 for active-project prompts contain at least one current-status or next-focus item
top 5 contain at least one decision or architecture-baseline item
top 5 contain at least one requirement or constraints item
broad single-word prompts no longer lead with archive/history chunks

2. Wave 2 Trusted-Operational Ingestion

Do not ingest the whole PKM vault next.

Wave 2 should ingest trusted operational truth for each active project:

current status dashboard or status note
current decisions / decision log
requirements baseline
architecture freeze / current baseline
milestone plan
next actions / near-term focus

Recommended helper flow:

python atocore.py project-state p04-gigabit
python atocore.py project-state p05-interferometer
python atocore.py project-state p06-polisher
python atocore.py project-state-set p04-gigabit status next_focus "Continue curated support and frame-context buildout." "Wave 2 status dashboard" 1.0
python atocore.py project-state-set p05-interferometer requirement key_constraints "Preserve current error-budget, thermal, and vendor-selection constraints as the working baseline." "Wave 2 requirements baseline" 1.0
python atocore.py project-state-set p06-polisher decision system_boundary "The suite remains a three-layer chain with explicit planning, translation, and execution boundaries." "Wave 2 decision log" 1.0
python atocore.py refresh-project p04-gigabit
python atocore.py refresh-project p05-interferometer
python atocore.py refresh-project p06-polisher

Use project-state for the most authoritative "current truth" fields, then refresh the registered project roots after curated Wave 2 documents land.

3. AtoDrive Clarification

AtoDrive should become a trusted-operational source, not a generic corpus dump.

Good AtoDrive candidates:

current dashboards
current baselines
approved architecture docs
decision logs
milestone and next-step views
operational source-of-truth files that humans actively maintain

Avoid as default AtoDrive ingest:

large generic archives
duplicated exports
stale snapshots when a newer baseline exists
exploratory notes that are not designated current truth

Rule of thumb:

if the file answers "what is true now?" it may belong in trusted-operational
if the file mostly answers "what did we think at some point?" it belongs in the broader corpus, not Wave 2

4. Restore and Ops Validation

Backups are not enough until restore has been tested.

Validate these explicitly:

SQLite metadata restore
Chroma restore or rebuild
registry restore
source-root refresh after restore
health and stats consistency after recovery

Recommended restore drill:

Record current health, stats, and projects output.
Restore SQLite metadata and project registry from backup.
Decide whether Chroma is restored from backup or rebuilt from source.
Run project refresh for active projects.
Compare vector/doc counts and run retrieval audits again.

Commands to capture the before/after baseline:

python atocore.py health
python atocore.py stats
python atocore.py projects
python atocore.py audit-query "gigabit" 5
python atocore.py audit-query "interferometer error budget and vendor selection constraints" 5 p05-interferometer

Recovery policy decision still needed:

prefer Chroma backup restore for fast recovery when backup integrity is trusted
prefer Chroma rebuild when backups are suspect, schema changed, or ranking behavior drifts unexpectedly

The important part is to choose one policy on purpose and validate it, not leave it implicit.

5.0 KiB Raw Permalink Blame History