teleo-infrastructure/.agents/skills/teleo-reconstruction-recovery/SKILL.md

name	description
teleo-reconstruction-recovery	Use when restoring, rebuilding, recompiling, or incident-recovering Leo's Teleo knowledge database, including snapshot recovery, genesis-plus-ledger replay, source recompilation, parity verification, and honest recovery claim ceilings.

Teleo Reconstruction Recovery

Job

Choose the smallest recovery path that restores a usable Leo knowledge system without confusing snapshot restoration, strict ledger replay, and semantic source recompilation.

Authority

Read docs/kb-rebuild-and-recompile.md first. It is the canonical recovery contract. Use docs/reports/leo-working-state-20260709/current-truth-index.md only for the newest retained proof point, and refresh live state before making a current VPS or GCP claim.

PR #146 is merged and owns the deterministic genesis-plus-ledger reconstruction slice in ops/run_local_genesis_ledger_rebuild.py. PR #147 is merged and owns the current unseen-reasoning verifier in scripts/verify_leo_unseen_reasoning_chain.py. PR #148 is a separate, open GCP least-privilege candidate; do not treat its branch files or proposed live state as canonical main recovery instructions until it merges.

Select The Recovery Mode

Need	Path	Honest result
Restore the latest verified state quickly	ops/run_local_canonical_postgres_rebuild.py	Exact snapshot recovery
Snapshot a Forgejo/text corpus for extraction	ops/run_local_corpus_knowledge_rebuild.py	Content-addressed UTF-8 sources and work items; no claims
Partition verified extraction work	ops/shard_corpus_extraction_work.py	Deterministic exact-once work shards; no source interpretation
Prove strict post-genesis applies replay exactly	ops/run_local_genesis_ledger_rebuild.py	Isolated insert-only ledger replay
Assemble reviewed V3 replay materials	ops/build_v3_genesis_ledger_bundle.py	Hash-pinned V3 ledger; optional operator-supplied admission metadata
Turn one retained source into a reviewed packet	scripts/compile_kb_source_packet.py	Deterministic proposal packet, not canonical knowledge
Rebuild every row from original sources	Follow the semantic recompilation contract in docs/kb-rebuild-and-recompile.md	Partial until every row and receipt is accounted for
Diagnose a live incident before recovery	Use .agents/skills/teleo-vps-runtime-ops/SKILL.md and .agents/skills/teleo-infra-provenance/SKILL.md	Fresh read-only incident map

Safe Order

1. Identify the intended source database, snapshot, manifest, commit, and hashes.
2. Keep private dumps, row payloads, source excerpts, and replay material outside the repository and mode 0600.
3. Inventory text sources before semantic extraction. For a binary original, retain its exact bytes and provide text from a separately pinned extractor; this repository does not yet supply a general PDF/office extractor.
4. Build and independently verify the V3 ledger before running genesis replay. Admission metadata is operator-supplied and is not a cryptographic signature from m3taversal.
5. Run the selected path in an isolated, network-disabled local container.
6. Verify schema, constraints, roles, counts, row hashes, key queries, and exact cleanup.
7. Run the relevant focused tests, then the unseen-reasoning verifier when the restored state is meant to support Leo answers.
8. Separate local reconstruction from VPS restore, GCP restore, service restart, Telegram delivery, promotion, and production apply. Each is its own proof row.

Commands

Use the repository virtual environment documented in README.md:

.venv/bin/python ops/run_local_canonical_postgres_rebuild.py --help
.venv/bin/python ops/run_local_corpus_knowledge_rebuild.py --help
.venv/bin/python ops/shard_corpus_extraction_work.py --help
.venv/bin/python ops/build_v3_genesis_ledger_bundle.py --help
.venv/bin/python ops/run_local_genesis_ledger_rebuild.py --help
.venv/bin/python scripts/compile_kb_source_packet.py --help
.venv/bin/python -m pytest -q \
  tests/test_run_local_corpus_knowledge_rebuild.py \
  tests/test_shard_corpus_extraction_work.py \
  tests/test_v3_source_rebuild_lifecycle_postgres.py \
  tests/test_build_v3_genesis_ledger_bundle.py \
  tests/test_run_local_canonical_postgres_rebuild.py \
  tests/test_run_local_genesis_ledger_rebuild.py \
  tests/test_verify_leo_unseen_reasoning_chain.py

The help and focused-test commands are safe local canaries. A real recovery requires caller-supplied private material and must retain a sanitized receipt without the material itself.

Stop Conditions

Stop before any live restore or restart when the source snapshot is not hash-bound, the source authority is ambiguous, parity fails, private material would enter Git or logs, cleanup cannot be proved, or the requested operation would promote GCP or mutate production without exact authorization.

Claim Ceiling

• Exact snapshot recovery is working when its parity receipt passes.
• Corpus inventory proves exact copied text bytes and extraction work locations, not semantic claims or binary extraction.
• The V3 ledger builder accepts only exact source-normalized applied materials, selects every ordered entry, and never infers admission from proposal status.
• The merged genesis-plus-ledger path proves an isolated insert-only slice.
• Semantic source-to-blank-database recompilation remains incomplete until every canonical row traces to a genesis record or reviewed replay receipt.
• No local receipt proves a live VPS/GCP restore, service restart, Telegram delivery, production apply, or GCP promotion.