Skip to content

Architecture Documentation Migration Plan

This audit classifies the current architecture documentation against the current AncientOS kernel model. It is a planning and traceability document for the documentation pass; it does not add runtime behavior.

Classification

Document Classification Reason
docs/architecture.md substantial rewrite It was historically accumulative and described AncientOS as a continuity layer/app runtime instead of the governed cognition kernel.
docs/canonical_terminology.md substantial rewrite It classified Keeper as an app/workflow and used substrate/app language that blurred kernel services.
docs/app_component_boundary_model.md substantial rewrite It needed replacement framing around kernel services, applications, providers, and transports.
docs/architecture/kernel_services.md new canonical support page No concise role map existed for Keeper, Beastmaster, Lich, Zeus, execution lanes, and provider selection.
docs/architecture/keeper.md substantial rewrite Keeper needed correction from task system behind Luna to objective/task kernel service.
docs/rubick_capability_registry.md minor edits Rubick was mostly accurate but needed repository/knowledge graph and kernel role language.
docs/oracle_visibility.md minor edits Oracle needed kernel evidence synthesis language instead of Luna standalone service framing.
docs/memory_architecture.md minor edits LifeVault was accurate but needed explicit kernel-service wording.
docs/inference_doctrine.md minor edits It needed current local-first/frontier escalation posture and model-mode language.
docs/operational_cognition_routing.md minor edits It needed runtime-kernel framing rather than Luna-owned routing.
docs/terminal_transport.md minor edits It needed the current host-run TUI URL override behavior.
docs/architecture/rubick_repository_intelligence_and_handoff.md minor edits It was current but needed kernel capability wording.
docs/architecture/rubick_knowledge_graph.md minor edits It was current but needed kernel relationship wording.
docs/architecture/governance_kernel.md no broad change It is already the canonical lifecycle authority document.
docs/architecture/keeper_calendar_boundary.md no broad change It already treats Keeper calendar behavior as a governed boundary.
docs/architecture/keeper_handoff.md no broad change It already describes read-only, evidence-preserving handoff behavior.
docs/architecture/keeper_import_boundary.md no broad change It already preserves import boundaries and approval constraints.
docs/architecture/keeper_import_proposal.md no broad change It is a bounded Keeper import proposal rather than canonical kernel taxonomy.
docs/architecture/keeper_import_review.md no broad change It remains a review artifact and does not redefine architecture.
docs/architecture/keeper_inbox_triage.md no broad change It already frames triage as planning support, not execution authority.
docs/architecture/keeper_lifecycle.md no broad change It already describes objective state without changing approval authority.
docs/architecture/keeper_objective_instantiation.md no broad change It already preserves objective instantiation as governed planning.
docs/architecture/keeper_operational_planning_doctrine.md no broad change It already keeps planning separate from execution and approval.
docs/architecture/keeper_scheduling.md no broad change It already treats scheduling as bounded Keeper planning behavior.
docs/architecture/lich_intake_gate.md no broad change It already describes Lich as the approval gate.
docs/architecture/loop_layer.md no broad change It already keeps loop behavior observational and governed.
docs/architecture/objective_intake.md no broad change It already defines governed intake without transport-specific runtime assumptions.
docs/architecture/objective_intake_resolver.md no broad change It already preserves resolver behavior as read-only classification/planning support.
docs/architecture/ser6buzz_maintenance_dashboard.md no broad change It is an app-specific architecture note and does not redefine kernel services.
docs/architecture/strategy_selection.md no broad change It is app/objective strategy documentation and remains outside this canonical kernel pass.
Proposal documents under docs/proposals/ leave as historical debt They are proposal/rationale records. Do not rewrite them as current doctrine in this pass.
Generated docs under docs/api/, docs/_build/, and site/ no manual edits Generated output should only change through the docs build workflow.

Dependency Order

  1. Establish kernel vocabulary in architecture.md and canonical_terminology.md.
  2. Correct application/provider/transport boundaries in app_component_boundary_model.md.
  3. Add the compact kernel service responsibility map.
  4. Correct role-specific pages: Keeper, Rubick, Oracle, LifeVault, inference, runtime routing, terminal transport, repository reasoning, and knowledge graph.
  5. Leave historical proposals and roadmap debt explicitly identified instead of mixing historical evolution with current doctrine.

Remaining Debt

  • docs/luna_master_roadmap.md is still historically accumulative and should eventually be split into current architecture, roadmap, and historical notes.
  • Proposal documents that have been adopted should gain a standard historical banner pointing to canonical docs.
  • Knowledge surface files under knowledge/ may still carry older classifications and should be audited separately.
  • Machine-readable manifests may need a later schema pass to reflect ancientos_kernel_service classifications consistently.