Assistant/docs/EXTERNAL_AUDIT_EXPLORATION_PROPOSAL.md

External audit and exploration proposal

Status: accepted in ADR-0018 Task: ARCH-000011 Date: 2026-08-22

Problem

When an external cognitive provider is unavailable, Domovoy must still remain useful: understand an ordinary request, inspect its own approved diagnostic surface, formulate hypotheses, compare recovery options, preserve evidence and explain the next practical action. A local cognitive path must not collapse into canned availability notices merely because a stronger provider is absent.

The testing goal is wider internal freedom for research and learning, paired with stronger independent observation of actions. It is not a request for an unattributed path from model output to external mutation.

Recommended decision: exploration-with-external-audit-v1

1. Introduce a test-only Exploration profile. It authorizes Domovoy to reason over available local context, run allowlisted read-only diagnostics, create hypotheses and alternatives, record non-secret evidence, and return a concrete recovery or research plan.
2. The profile must prefer semantic intent and current situation over a second keyword parser. Missing capability is itself a topic to investigate: the response must state what is unavailable, what was observed, what can still be done locally, and the smallest next action.
3. Exploration output is provisional. It may become a typed Work plan, Capability gap, or ActionProposal only through the existing semantic owner; it is never an implicit external action.
4. Each proposed state-changing or external action emits a compact, redacted, append-only audit event. An independently deployed audit consumer builds a rebuildable projection containing: action/proposal identity, source situation and intent references, requested capability, evidence references, declared scope, outcome state, and external-review verdict.
5. The external reviewer may return ALLOW, REVIEW_REQUIRED, or STOP as a signed/attributed observation. For configured action classes, Commit uses the current ALLOW observation as an additional precondition before it authorizes execution. The reviewer never receives executor credentials and cannot execute an action itself.
6. If the reviewer is unavailable, all exploratory and read-only work remains available. A state-changing action configured for review remains a typed pending proposal; it is not silently executed and not reclassified as a failure.
7. Secrets, raw credentials, and full private payloads do not enter the audit stream. Audit receives stable references, classifications, hashes and redacted summaries only. Audit data is a derived projection, never the canonical owner of decisions, authority or outcomes.

Responsibilities

Concern	Owner	Role
Intent, plan and durable decision	work	Canonical semantic owner.
Hypothesis, observation and evidence	epistemics	Canonical evidence owner.
Capability gap and cognitive selection	capability	Registry and selection owner.
Proposal, authorization and execution	commit	Only privileged path to a real external action.
Audit projection and reviewer evidence	external audit deployment	Independent, rebuildable consumer; no executor authority.

What becomes freer in testing

• The local cognitive path answers ordinary conversation and configuration inventory requests from its typed local context.
• Provider loss starts a recovery investigation rather than a generic refusal.
• It may inspect approved health, model registry, capability health, recent non-secret evidence and local deployment diagnostics.
• It may generate several alternatives, rank them with stated uncertainty and propose the smallest reversible experiment.
• It may create a reviewable Work/Capability proposal through the normal owner boundary.

What remains an invariant

• No raw secret crosses into cognition, audit, logs or a provider.
• Model/advisory output does not directly mutate canonical state or call an executor.
• Every external mutation remains attributable, revision-checked and reconcilable; UNKNOWN_OUTCOME remains distinct from success and failure.
• Audit cannot rewrite canonical history, impersonate a principal, or acquire broader authority than the action it observes.

Delivery slices after acceptance

1. Add typed semantic routes for ordinary local conversation, configuration inventory and provider-recovery investigation; remove duplicate raw-text routing from Work and the cognitive gateway.
2. Register the built-in local route in capability telemetry so selection and use observations have one source of truth.
3. Add owner-local evidence/decision persistence needed to connect a proposal to its alternatives and review result.
4. Publish redacted outbox events and implement an external audit projection, including rebuild and outage tests.
5. Add a Commit precondition that consumes an attributed external ALLOW observation for specifically configured action classes; test STOP, reviewer outage and UNKNOWN_OUTCOME recovery.

Alternatives rejected

• Disable every internal boundary: removes the evidence and attribution needed for meaningful external review, and permits a model to mutate the world without a recoverable decision record.
• Audit process calls the executor directly: makes an observer a competing authority and breaks the Commit boundary.
• Only log after execution: detects incidents too late to control actions.
• One global analytics database as source of truth: violates canonical ownership; the audit view must remain rebuildable from owner events.

Explicit acceptance required

Before implementation, accept the recommended decision and choose the first review-governed action class. The initial implementation can safely enable the Exploration profile and audit-only observation first; execution gating must not be inferred for every future capability.