Skip to content

Operational Awareness And Knowledge Ingestion

AncientOS operational awareness is read-only, artifact-authoritative, and governance-first. It gives Luna local context as the Discord assistant app/interface without granting repair authority, autonomous execution, direct live Tinker execution, or hidden prompt mutation.

Operational awareness exists to make personal AI continuity trustworthy. It lets the operator and Luna understand current state, recent drift, memory posture, provider readiness, and safe next inspections across changing transports and models.

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.

Governed File Awareness (Phase integration)

File awareness is strictly derived from app/path_policy.py allowed_read_roots. - generate_permitted_inventory produces machine-readable permitted file list + metadata. - summarize_permitted_file produces bounded summaries with sha256, mtime, reason (binary/oversize/denied). - Conversational questions ("What files can you see?", "Tell me about AncientOS", "SER6BUZZ codebase", "Refresh your file awareness") are answered from this layer only. - Policy change requests generate proposal artifacts only (see app/policy_proposal.py); no direct mutation. - All paths fail-closed. Denied files never surface. Discord is thin transport only. - Citations: inventory artifact paths, sha256, policy source.

Evidence references are always included when file context is returned.

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.

Governed Architectural Awareness

Architectural awareness is a request-scoped operational report family. It answers bounded questions about AncientOS/Luna architecture, roadmap, capabilities, dependency gaps, governance layers, runtime coupling, and architectural debt.

Implemented report types include:

  • capability summary
  • roadmap readiness report
  • dependency gap report
  • architectural debt report
  • governance layer inventory
  • runtime coupling inventory
  • subsystem topology summary
  • safest-next-step recommendation
  • recently added capability summary

These reports are generated from app/architecture/* registries and direct runtime/test evidence. They do not use Discord objects, mutate roadmap state, launch background loops, enqueue work, or approve execution. Recommendations are advisory only and include dependency rationale.

Docs are treated as derived evidence. Runtime code and tests are stronger evidence for verified capability claims. Missing or ambiguous evidence produces a warning or omission rather than a promoted capability.

Oracle Visibility Plane

Oracle is the first-class operational ergonomics service over these awareness surfaces. It answers operator status questions through bounded reports rather than execution plans.

Oracle report synthesis separates:

  • verified facts
  • inferred readiness
  • warnings
  • advisory recommendations

Oracle can summarize operational state, capabilities, roadmap readiness, governance layers, subsystem topology, runtime coupling, architectural debt, recent changes, blockers, risks, and safest next roadmap direction.

Oracle preserves clarification-before-action semantics because it never turns a status question into a plan, delegate request, confirmation approval, commit, or runtime mutation. Follow-up remediation must enter the normal governed path.

Luna Operational Console Routing

Luna now has an explicit operational cognition routing layer for operator ergonomics. app/routing/operational_cognition_router.py classifies introspection requests before plan/delegate/governance-preview staging. The handled classes include operational awareness, coordination awareness, topology inspection, replay inspection, capability inspection, governance inspection, workflow-state analysis, coordination proposal review, and constitutional inspection.

app/oracle/operational_console.py renders route explanations and transport-neutral cards around Oracle narration. Operational inspection remains advisory-only and cannot create execution plans, approval previews, rollback staging, hidden workflows, or mutation authority.

Governed Inference Awareness

AncientOS runtime cognition now uses a governed inference substrate for eligible model-backed text generation. app/inference/* defines named roles, policy checks, fail-closed client behavior, and inference audit summaries.

Operationally:

  • deterministic routing still happens before inference
  • governance decisions stay outside inference
  • model output is advisory text or structured data only
  • unavailable luna-inference produces explicit degradation
  • disallowed roles and invalid structured output fail closed
  • Oracle remains read-only even when the oracle_synthesis role exists
  • embedding generation uses explicit roles for generic embedding generation, retrieval query embedding, memory fact embedding, and architecture evidence embedding
  • unavailable embedding service produces explicit degraded state instead of a direct backend fallback
  • retrieval results are evidence inputs only and cannot approve, execute, mutate, or bypass governance

This avoids direct subsystem-owned chat or embedding model calls and hidden unsafe fallback to model backends.

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.