Skip to content

Documentation Synchronization

AncientOS treats documentation freshness as part of operational integrity. The documentation drift checker provides a deterministic, read-only kernel surface for detecting whether core architecture documents still reflect the current strategic vocabulary. Luna remains the interactive assistant/interface layer in that taxonomy.

Scope

The checker inspects:

  • docs/architecture.md
  • docs/luna_master_roadmap.md

Human terminology review also includes docs/canonical_terminology.md as the canonical vocabulary reference.

The checker reports required strategic terms, missing terms, stale language, checked-file status, bounded recommendations, and future-facing consumer contracts. Runtime-kernel documentation must keep the transport-neutral kernel, Discord adapter boundary, pipeline stages, Runtime Cognitive State layer, authority ownership table, and clarification-before-action doctrine synchronized between these documents. Terminology review must keep AncientOS as the governed cognition kernel; Luna as the interactive assistant/interface layer; Rubick, Oracle, Keeper, Beastmaster, LifeVault, Lich, Zeus, Meepo, Clockwerk, LegionCommander, Roshan, Invoker, TrollWarlord, Tinker, Creep, Kunkka, and Nyx as AncientOS kernel services, components, lanes, or candidates; Naga-Siren, Keeper Console, X-feed-worker, Prophet, and future domain packages as applications/workflows; Discord, terminal TUI, CLI, Web, Android, and future clients as interfaces/transports; Ollama, xAI/Grok, OpenAI-compatible APIs, Anthropic, Codex, Claude Code, X API, GitHub, MCP providers, and search/browser providers as wrapped or adapted provider candidates rather than assumed forks, dependencies, or authority sources. Governed Architectural Awareness documentation must keep the awareness/autonomy distinction, capability evidence model, dependency reasoning model, drift warning semantics, and advisory-only next-step synthesis synchronized between architecture, roadmap, and operational awareness documents. Oracle documentation must keep the read-only evidence-synthesis boundary, authority contract, report section model, runtime routing behavior, and relationship to architectural awareness synchronized across the Oracle, architecture, roadmap, and operational awareness documents. Governed inference documentation must keep named text and embedding roles, luna-inference gateway semantics, structured-output expectations, fail-closed fallback behavior, explicit embedding degradation semantics, retrieval-as- evidence boundaries, observability, and residual direct-call debt synchronized across architecture, roadmap, and operational awareness documents. Oracle may consume this report as read-only visibility input, but it does not repair documentation or approve remediation.

Governance Boundaries

The checker does not modify documentation, apply patches, start watchers, run daemons, call paid tools, or implement Oracle or Zeus runtime behavior. It only emits structured JSON for inspection.

Future remediation remains governed:

  1. Oracle may surface drift visibility.
  2. Zeus may propose constitutional review notes or remediation recommendations.
  3. Lich must approve mutations.
  4. Kunkka may apply deterministic patches only after approval.
  5. Roshan may validate dangerous or sensitive changes.
  6. Underlord is involved only for paid escalation paths.

CLI

Run the default check:

python -m app.docs_drift_check

The command exits with 0 when no drift is detected and 1 when missing files, missing terms, or stale language are reported.

The output is stable JSON with schema version 1.0. generated_at is intentionally fixed by default so repeated runs are replayable and diff-friendly.

Governed Commit Requests

Discord commit requests may be written in natural language, but natural language does not execute commits. Governed commit detection has one source of truth: the same normalization step that produces the strict TrollWarlord command shape:

luna execute governed-commit --message "..." --files-staged --validation-status passed

Normalization requires explicit staged-file language, explicit validation-passed language, and either an explicit commit message or a bounded deterministic message derived from a staged object phrase. Supported natural-language forms include commit the staged <object> work, commit the staged <object> changes, commit the staged <object> files, commit staged <object> work, and commit staged <object> changes. The derived message is deterministic: Update <object>, or Add <object> only for narrow additive signals such as new, initial, or first.

The derivation remains fail-closed. It refuses vague object phrases such as this, stuff, things, or bare changes; overlong phrases; paths; quotes; shell metacharacters; secret/token/password language; and newline/control characters. It does not stage files, does not infer validation success, does not approve generated artifacts, and does not bypass Lich/TrollWarlord approval. Before Discord confirmation/resume, Luna stores the canonical strict command as the execution command and preserves the original request text separately for audit provenance. The strict TrollWarlord executor remains the only commit authority.