Operational Awareness And Knowledge Ingestion

Luna's operational awareness layer is read-only, artifact-authoritative, and governance-first. It gives Luna local context without granting repair authority, autonomous execution, direct live Tinker execution, or hidden prompt mutation.

Time Awareness

Time artifacts capture current time, freshness, staleness, maintenance windows, schedule windows, and clock snapshots.

flowchart LR Clock[System clock] --> Snapshot[operational_clock_snapshot] Snapshot --> TimeReport[time_context_report] Observation[Observed artifact time] --> Fresh[freshness_report] Fresh --> Stale[staleness_assessment] Window[Maintenance input] --> Maint[maintenance_window] Maint --> Schedule[schedule_window]

Freshness and staleness are reports, not authorities. Stale data can fail closed, but it cannot trigger repair or mutation by itself.

Entity cognition surfaces (Phase 8E) follow the same principle: derived summaries and timelines are reports only and remain fully governed.

Knowledge Ingestion

Ingestion supports local Markdown, text, JSON, CSV, PDF text extraction, and exported document trees. Notion, Airtable, CRM, roadmap, and local documentation exports enter through the same local snapshot path.

flowchart LR Source[source] --> Normalize[normalized_document] Normalize --> Classify[classification] Classify --> Chunk[chunk_manifest] Chunk --> Index[embedding_index_record] Index --> Review[ingestion_review] Review -->|approve| Promote[ingestion_promotion] Review -->|reject| Reject[ingestion_rejection] Promote --> Retrieval[governed retrieval eligibility]

The ingestion job remains awaiting_governance_review until reviewed. Ingestion does not mutate prompts, tools, Discord runtime behavior, or execution plans.

Context Assembly

Operational context assembly uses promoted memory only and writes explainable artifacts for scoring, prioritization, budgeting, and traceability.

flowchart TD Query[Query] --> Candidates[context_candidate] Candidates --> Score[context_relevance_score] Score --> Priority[context_priority_report] Priority --> Budget[context_budget_report] Budget --> Trace[retrieval_trace] Trace --> Window[retrieval_context_window]

Signals include semantic similarity, recency, freshness, trust, governance, archive penalties, active project relevance, roadmap relevance, and operational state relevance.

Operational Awareness

Operational reports observe local state without mutation:

operational_state_report
container_health_snapshot
repo_status_report
update_status_report
operational_drift_report
reboot_requirement_report

These reports are explicitly read_only and do not include autonomous repair actions.

Relationship Mapping

The relationship layer is a lightweight artifact graph, not an external graph database.

flowchart LR Entity[entity_snapshot] --> Edge[relationship_edge] Edge --> Project[project_context_map] Edge --> Dependencies[operational_dependency_map]

Relationships can connect projects, repos, artifacts, roadmap phases, ingestion sources, memory entries, and operational entities while preserving provenance and replayability.

Reporting

Operational reports cover stale context, orphaned artifacts, retrieval drift, memory pressure, archive pressure, storage growth, and failed ingestion jobs. Reports surface state for review; they do not execute repairs.

Request-Scoped Operational State Retrieval (Phase 6D)

Operational awareness is exposed only through natural-language intent detection in the governed context retrieval layer. Queries about service health, degraded state, tool availability, pending restarts, runtime limitations, or confidence levels trigger deterministic classification and bounded read from fixed allowlisted sources (luna_state.md, luna_live_system.md, context_index.md).

flowchart LR Query[health or status query] --> Detect[operational intent] Detect --> Source[fixed allowlist read] Source --> Truncate[bounded truncate] Truncate --> Inject[request-scoped prompt injection] Inject --> Discard[discard after response]

No background polling, no watchers, no persistent state, no mutation. All awareness is read-only, request-scoped, and fails closed. This layer augments Phase 6C runtime tools without introducing autonomy.

Phase 6E Task Continuity Extension

The Operational Awareness doc now incorporates Task Continuity Layer (Phase 6E) via shared retrieval engine. Continuity provides governed summaries of active tasks, checkpoints, capabilities, skills, and recent activity from fixed sources only. Same fail-closed, bounded, request-scoped guarantees apply. No autonomous execution or memory mutation added.

Intent priority was strengthened so that self-referential queries about tools, capabilities, limitations, operational state, clock/time, and recent governed activity now deterministically trigger the appropriate Phase 6C/6D/6E retrieval paths instead of falling through to generic LLM knowledge.

Phase 6F adds structured inventory renderers that produce clean, canonical, bounded output (e.g. bullet lists of tools, skills, limitations) instead of synthesized prose. All data originates from governed maps synchronized with the allowlisted Markdown sources.

Explicit Capability Helpers (Phase 6D)

The following pure request-scoped helpers are implemented in context_retrieval:

service_health_summary(read_text): bounded answer for "Are your services healthy?"
container_health_snapshot(read_text): Docker/runtime container state
repo_status_summary(read_text): git cleanliness and repo health
update_status_summary(read_text): pending maintenance / update needs
runtime_limitations_summary(read_text): current restrictions and capabilities
context_source_status(read_text): visibility into indexed context sources
operational_degraded_state_summary(read_text): explicit degraded/nominal state

All map to fixed allowlisted Markdown sources only, truncate output, and return clear degraded markers on failure. They integrate automatically via intent detection in retrieve_luna_context / retrieve_operational_awareness.

Current Operational Intelligence Layer

Operational awareness now includes policy-native workflow reasoning.

Implemented capabilities include:

runtime registry synthesis
plan state synthesis
workflow readiness analysis
governance bottleneck analysis
multi-workflow arbitration
coordination health synthesis
policy evaluation
simulation forecasting
branch comparison
safest-path recommendation

These capabilities are cognitive only. They do not execute, mutate, schedule, or remediate automatically.

Default user-facing responses must remain semantic. Internal IR such as inspect, validate, rollback, dependency_failed, and lane assignments stays hidden unless explicitly requested.

Governed artifact materialization (architecture, 6bfafbff8d91)

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 architecture 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.
The architecture boundary separates intent decomposition, artifact synthesis, Lich approval, and worker execution.

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

Use roadmap artifacts to sequence future expansion after governed documentation is reviewed.

Governed artifact materialization (governance, 3ec3ead1d01e)