Architecture

Planner to execution flow

flowchart TD U[User request] --> P[LegionCommander planner] P --> L[Lich review] L -->|allow| E[Executor or creep worker] L -->|require confirmation| C[Confirmation gate] C --> E E --> V[Validation] V --> R[Discord result]

Creep job lifecycle

stateDiagram-v2 [*] --> queued queued --> running running --> completed running --> failed running --> waiting_for_confirmation waiting_for_confirmation --> running

Keeper

See the detailed Keeper architecture page: Keeper Architecture

Keeper Lifecycle

See the runtime state flow: Keeper Lifecycle

Discord session context

Discord chat requests include a bounded per-channel or per-thread session window before the current user turn. See Session Context.

Natural Luna context

Natural questions about Luna's roadmap, architecture, state, limitations, capabilities, live system, or checkpoints use deterministic intent matching. When matched, Discord asks luna-tools to read the fixed context index and one fixed allowlisted source file. The retrieved text is bounded and injected only into the current model request.

Discord does not perform direct filesystem reads, accept user-provided paths, write files, mutate memory, or route through shell for this context path. See Natural Context Retrieval (includes Phase 6C Core Runtime Context Tools + Phase 6D Operational Awareness Layer).

Current Operational Architecture

graph TD U[User in Discord] --> D[discord-luna] D --> I[Intent Detection] I -->|roadmap/system question| T[luna-tools governed retrieval] T --> C[Authoritative Context Files] C --> D D --> L[luna-inference] L --> O[Ollama] D -->|governed execution requests| G[luna-interop] G --> P[Patch Plans / Validation / Rollback] P --> X[Tinker Local Execution]

Current Execution Reality

Luna now operates through governed artifact flows instead of direct autonomous execution.

Current implemented capabilities: - bounded Discord session context - governed operational memory - natural-language self-context retrieval - governed live Tinker bridge - sandboxed mutation capability - patch-aware structured editing - rollback-aware execution receipts - validation contracts and review artifacts

Current blocked capabilities: - arbitrary shell execution - unrestricted filesystem access - recursive autonomous execution - unrestricted network operations - uncontrolled self-modification - Discord-owned execution semantics

The system remains intentionally fail-closed and governance-first.

Operational Awareness (Phase 6D)

Additive read-only layer in context_retrieval provides deterministic health, container, repo, update, limitation, source, and degraded-state summaries. All gated behind natural language intent detection, bounded, request-scoped, using only luna-tools governed reads from fixed docs. No new authority; fully compatible with existing Tinker governance.

Intent detection now uses expanded deterministic term groups with explicit self-state priority (runtime, operational, continuity, state, checkpoint) so that Luna/SER6BUZZ/self queries reliably win over generic completion. Clock awareness, tools, limitations, operational state, and recent activity now route correctly to governed sources.

Task Continuity Layer (Phase 6E)

Further additive extension for coherent cross-session continuity: current task, latest checkpoint, capabilities/skills awareness, recent activity (success vs degraded). Uses only existing fixed allowlisted sources (current_task, checkpoint.md, luna_capabilities.md). Deterministic intent classification, bounded, fail-closed, request-scoped. Preserves all governance, rollback, and thin-transport properties. No write authority or autonomous loops introduced.

Phase 6F Structured Operational Inventories

Canonical governed maps (GOVERNED_TOOLS, GOVERNED_SKILLS, etc.) plus deterministic renderers (tools_inventory_summary, operational_state_summary, runtime_clock_summary, etc.) provide structured, bounded answers instead of raw prose. All inventories are static, auditable, and sourced from allowlisted governed documents only.

Current Architecture Status: Governed Operational Intelligence

Luna has moved beyond simple retrieval-backed self-description into a layered governed cognition stack.

Current implemented layers:

Governed runtime registry
Operational awareness context
Task continuity context
Governed operational intent routing
Structured operational inventories
Governed action intelligence
Governed multi-step plan state
Governed workflow cognition
Multi-workflow arbitration
Coordination kernel
Governed simulation engine
Governed policy engine
Branch evaluation and safest-path selection

The system remains non-autonomous. These layers reason about workflows, policies, simulations, rollback readiness, validation needs, governance cost, and safest paths, but they do not execute actions automatically.

graph TD U[User / Discord] --> D[Thin Discord Transport] D --> R[Governed Intent Router] R --> G[Runtime Registry] R --> P[Governed Plan State] R --> W[Workflow Cognition] W --> A[Workflow Arbitration] A --> C[Coordination Kernel] C --> PE[Policy Engine] C --> SE[Simulation Engine] SE --> B[Branch Evaluation] B --> S[Semantic Response Renderer] S --> D PE -. denies .-> X[Unsafe Authority] SE -. forecasts .-> Y[Rollback / Validation / Review Needs]

Core boundary: Luna can now reason about operational futures under governance constraints, but execution remains gated, explicit, and non-automatic.

Governed Entity Cognition Architecture (Phase 8E Extension)

Luna evolves its governed operational intelligence into a full governed operational cognition substrate with persistent semantic continuity. This is a strict extension — not a replacement — of existing layers.

1. Luna Core (Authoritative)

Bounded deterministic runtime
Governed execution lanes (Invoker, Tinker, Roshan, Lich, Commander, Kunkka, Codex)
Capability manifests
Selector / proposal layers
Artifact lineage and audit logs
All execution remains approval-gated and replayable

2. Entity Cognition Layer (Derived)

Entity registry (people, systems, projects, decisions, incidents, capabilities)
Relationship edges with evidence/provenance links
Semantic provenance tracking
Entity timelines and state summaries
Semantic deltas and entity revisions
Derived Markdown export generation
All surfaces are projections of canonical artifacts

3. Human Cognitive Surface (Presentation Only)

Obsidian-compatible Markdown vault
Backlinks and readable summaries
Local-first inspection and navigation
Versionable, discardable, and fully regeneratable
Never treated as source of truth

4. Governance Boundary (Enforced)

Capability visibility ≠ authority
Semantic summary ≠ truth
Markdown view ≠ source of truth
Proposal ≠ approval
Approval ≠ execution until bounded executor applies validated operation
Semantic provenance must accompany every derived surface

5. Anti-Patterns / Prohibited Directions

Markdown-as-authority
Autonomous uncontrolled background agents
Opaque memory mutation
Direct entity graph writes bypassing governance
Electron-first architecture
SaaS dependency for core memory or cognition
Unrestricted self-modification
Hidden semantic drift
Unreplayable cognition transforms

This layered model ensures Luna remains: - governed - deterministic-first - artifact-backed - replayable - transport-neutral - bounded execution - offline-safe - fail-closed - approval-gated

while adding persistent semantic continuity through derived, inspectable surfaces.

Governed artifact materialization (roadmap, 99416a07401a)

Capability

Governed artifact materialization produces reviewed documentation updates for artifact, materialization, bundle, lineage, lich, confirmation.
Materialized content is generated from deterministic templates, not copied from the operator prompt.

Governance Model

The roadmap artifact remains bounded to approved documentation roots.
Governance metadata records target selection, content digest, and materialization lineage.
Replay metadata preserves the selected target, content hash, and intent classification.

Execution Flow

LegionCommander classifies the objective into artifact intents.
The materializer selects a bounded documentation target for each intent.
confirmation_runner queues artifact_execute only after Lich approval.
artifact_patch_safe writes the approved bundle and records worker result metadata.

Safety Boundaries

Runtime code execution policy is not broadened by artifact materialization.
Source, test, script, generated API, secret, absolute, and traversal paths remain denied.
Architecture impact is limited to the governed artifact lane and its audit metadata.

Current Limitations

Generated prose is intentionally template-bounded and does not infer unobserved implementation details.
Ambiguous equal-score targets fail closed for human repair instead of guessing.

Future Roadmap

Track follow-up milestones as explicit documentation artifacts instead of runtime code changes.

Governed artifact materialization (roadmap, 0d7502af4462)