cto-legends · module specification · foundation · v0.3.2
legends-empire: SHA-256 Markdown Knowledge Foundation & Vault Stewardship
SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.
GitHub Repository (https://github.com/avalonreset/legends-empire) · Handoff: cto-legends handoff legends-empire
legends-empire is a Python 3.11+ standard-library Markdown knowledge foundation and vault stewardship engine designed to maintain cumulative operational context across coding agent sessions. It separates immutable raw source evidence (.raw/), agent-navigable hot wiki indexes and linked knowledge notes (wiki/), and human-owned project records inside a local Obsidian-compatible directory tree. Rather than allowing an AI agent to overwrite notes directly, every vault initialization, source capture, semantic note update, and knowledge pack attachment executes through a preview-first, journaled transaction engine.
The module ships with three integrated subsystems inside the same installation: the recoverable transaction and capture core (scripts/claude-empire.py), the read-only vault stewardship scanner (invocable directly as legends-vault-stewardship via steward doctor and steward scan), and the optional AI Marketing Hub Home shared-root adapter (home-adapter). On Linux, macOS, and configured WSL mounts it enforces POSIX mode 0600 confinement; on native Windows (Empire 0.3.1+) it executes reviewed transactions on local fixed NTFS volumes using retained NT directory handles, process-lifetime named mutexes, and verified current-user/SYSTEM DACL security descriptors.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Connecting a raw LLM or an unconstrained filesystem MCP server directly to a personal or company Markdown vault inevitably produces silent note overwrites, broken wikilinks, frontmatter corruption, and hallucinated summaries blended indistinguishably with primary source evidence. When an agent is told to 'clean up my vault' without mechanical tooling, it invents ad-hoc Python scripts or deletes orphaned notes that were actually legitimate compliance receipts.
- Recoverable Precondition-Bound Filesystem Transactions: Mutations require a claude-empire.transaction.v1 bundle binding every target path to its expected prior SHA-256 hash and file mode, plus an environment-bound --approved-plan-sha256 token generated by dry-run inspection. Concurrent edits or permission mismatches abort with exit code 75 before any note is modified, and interrupted writes recover deterministically from the private .vault-meta/ journal.
- Content-Addressed .raw/ Quarantine & Provider Evidence Verification: Raw source files placed in inbox/ and exported research bundles from legends-dataforseo (legends-research-evidence/v1) or legends-firecrawl (legends-firecrawl-evidence/v1) are verified byte-for-byte via bounded no-follow readers (rejecting symlinks, duplicate JSON keys, and NaN/Infinity values) and stored as immutable content-addressed payloads in .raw/ before any semantic wiki note is proposed.
- Read-Only Steward Diagnostics & Three-Tier Knowledge Pack Ownership: steward scan computes a deterministic inventory of note roles, link resolution, freshness policies, and SHA-256 file baselines without mutating a single human note. Versioned module knowledge packs (legends.knowledge-pack/v1) attach into wiki/library/ while tracking shipped reference hashes in pack-state.json so future updates refuse to overwrite user-edited reference files.
CLI Subcommands & Capability Surface
claude-empire.py init / adopt / migrate / checkpoint / doctor / contracts — Vault Initialization, Adoption, Migration & Git Checkpointing: Previews and applies non-destructive vault scaffolding (.claude-empire.json, inbox/, .raw/, wiki/, .obsidian/, and privacy-safe .gitignore) for new or existing Obsidian vaults without overwriting user notes. Supports additive provenance migration for legacy layouts and exact single-transaction Git commits via checkpoint <operation-id> using a temporary index that verifies exact Git blob bytes.claude-empire.py capture plan / capture apply / transaction inspect / transaction apply / transaction recover — Immutable Source Capture & Reviewed Semantic Transactions: Copies intake files from inbox/ into content-addressed immutable storage under .raw/ and validates claude-empire.transaction.v1 write bundles against prior file hashes before applying changes to supported wiki/ paths. If a writer process is killed mid-flight, transaction recover validates backup hashes and permission descriptors in the journal to restore the vault cleanly.claude-empire.py steward doctor / steward scan <vault> [--review-limit N] [--baseline observe.json] [--profile empire] — Vault Stewardship & Baseline Delta Scanning (legends-vault-stewardship): Provides a read-only mechanical inventory of vault notes, broken or unlinked routes, role classifications, and vault-configured freshness expectations, outputting structured JSON and Markdown reports outside human notes. Passing --baseline compares current SHA-256 file identities against a prior observe.json snapshot so the agent verifies whether an authorized repair campaign resolved target findings without collateral damage.claude-empire.py knowledge attach <pack.json> --vault <path> --operation-id <id> --generated-at <ISO> [--apply --approved-plan-sha256 <hash>] — Versioned Module Knowledge Pack Attachment: Attaches and updates portable Markdown reference libraries (schema legends.knowledge-pack/v1, up to 256 UTF-8 Markdown files and 8 MiB) from Legends modules into wiki/library/ via reviewed transactions. Separates user-owned index.md files from digest-checked reference/ snapshots in pack-state.json, refusing updates if any owned reference file was hand-edited by the user.claude-empire.py research-evidence verify <package> --workspace <id> / research-evidence plan <package> --workspace <id> --vault <path> — Offline Provider Research Evidence Verification & Intake Planning: Verifies exported DataForSEO (legends-research-evidence/v1) and Firecrawl (legends-firecrawl-evidence/v1) evidence packages offline without requiring either provider dependency at runtime. Recomputes canonical manifest SHA-256 identities, checks raw response.json and README.md byte hashes, enforces client workspace scope isolation, and plans collision-free intake into inbox/research/<evidence-id>.claude-empire.py home-adapter prepare / scaffold / install / compose / inspect / plan / apply / list / check / detach — Optional AI Marketing Hub Home Shared-Root & Separate-Root Adapter: Prepares Home-compatible business and project records (Projects/Active, Workspaces/Clients/Companies, Workspaces/Brands & Sites) in a standalone Empire root and optionally slots in an independently authorized AI Marketing Hub Home (pinned v0.5.2) headless capability layer in bounded 400-file recoverable batches. Composes root AGENTS.md contracts with cryptographic provenance snapshots and verifies project contexts via isolated, digest-checked native resolve-context.py staging.
Raw Frontier LLM vs. legends-empire Execution Matrix
- Write Atomicity, Confinement & Crash Recovery: Raw LLM (Writes directly to Markdown files via naive file tools; partial writes or mid-session crashes corrupt notes with no rollback journal.) vs. Module (Enforces claude-empire.transaction.v1 precondition hashes, POSIX 0600 or native Windows NTFS handle/DACL confinement, and journaled rollback via transaction recover.) — claude-empire.py doctor --vault <path> and contracts --verify --vault <path> validate confinement, ledgers, and journal state.
- Primary Evidence vs. Agent Synthesis Separation: Raw LLM (Summarizes scraped pages or API responses directly into notes, discarding raw payloads and mixing hallucinated claims with facts.) vs. Module (Quarantines immutable content-addressed payloads in .raw/, validates provider manifests via research-evidence verify, and requires source-cited wiki/ links.) — SHA-256 manifest and response verification in .raw/ plus bounded no-follow reader checks.
- Vault Cleanup & Maintenance Safety: Raw LLM (Invents ad-hoc cleanup rules, rewrites timestamps, or deletes unlinked notes that are actually valid receipts or reference records.) vs. Module (steward scan is strictly read-only on human notes, emitting a bounded review queue and observe.json baseline; repairs require a separate hash-locked transaction.) — Post-repair steward scan --baseline before/observe.json verifies exact finding resolution and zero unintended file drift.
- Module Documentation & Runbook Updates: Raw LLM (Copies documentation into a vault once with no provenance tracking, or overwrites user annotations during subsequent updates.) vs. Module (knowledge attach tracks shipped SHA-256 digests in pack-state.json, preserves user-owned index.md, and refuses updates if any reference file was modified locally.) — Repeat attachment of an unchanged pack returns deterministic noop; tampered reference bytes fail closed during transaction preview.
- Cross-Platform Filesystem Security: Raw LLM (Assumes POSIX chmod works on Windows or WSL /mnt/c drives without DrvFS metadata, silently creating world-readable runtime state.) vs. Module (Probes 0600 persistence on POSIX/WSL and enforces local fixed NTFS, current-user token ownership, and reparse-point refusal on native Windows.) — steward doctor and preflight probes fail closed with UNSUPPORTED_FILESYSTEM_PERMISSIONS or UNSAFE_VAULT_IDENTITY on unsupported mounts.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Is legends-vault-stewardship a separate package or skill installation from legends-empire?
- No. Vault stewardship (legends-vault-stewardship) is built directly into legends-empire and shares the exact same installation, runtime, and update lifecycle. Running cto-legends handoff legends-vault-stewardship resolves to module: legends-empire and loads docs/stewardship.md on demand.
- How do native Windows vault transactions differ from POSIX and WSL?
- Starting in Empire 0.3.1, native Windows supports reviewed Python transactions on local fixed NTFS volumes using retained NT directory handles, a process-lifetime named mutex, and owner/SYSTEM DACL preservation. Recovery covers process crashes and killed writers, whereas sudden OS power-loss directory-entry durability remains a POSIX directory-fsync guarantee. Approval hashes bind to the reviewing environment and cannot be replayed across native Windows and WSL.
- What happens when an attached module knowledge pack is updated upstream after I edit a note?
- knowledge attach separates user-owned index.md files from shipped reference/ files tracked in pack-state.json. During an update, every owned reference file is checked against its last shipped SHA-256 digest; if you modified or removed a reference file, the entire transaction refuses cleanly with no force-overwrite flag so your edits are never lost.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.