134 lines
5.0 KiB
Markdown
134 lines
5.0 KiB
Markdown
# AtoCore Operations
|
|
|
|
This is the current operating playbook for making AtoCore more dependable and higher-signal.
|
|
|
|
## Order of Work
|
|
|
|
1. Retrieval-quality pass
|
|
2. Wave 2 trusted-operational ingestion
|
|
3. AtoDrive clarification
|
|
4. 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. Record current `health`, `stats`, and `projects` output.
|
|
2. Restore SQLite metadata and project registry from backup.
|
|
3. Decide whether Chroma is restored from backup or rebuilt from source.
|
|
4. Run project refresh for active projects.
|
|
5. Compare vector/doc counts and run retrieval audits again.
|
|
|
|
Commands to capture the before/after baseline:
|
|
|
|
```bash
|
|
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.
|