Public research preview · Approach

How MetaAware works—from evidence to accountable action.

MetaAware turns observable project state and explicit policy into deterministic findings. AI helps people ask questions and understand results, but it does not create the governing fact, silently change the rule, or grant authority.

Operating model

One governance loop, seven separable stages.

MetaAware separates observation, judgment, explanation, and authority so that every failure can be located and challenged.

01 · Ask or declare intent
A person or agent asks about the current state, requests an audit, or declares an intended action. The initial MVP remains read-only: asking what should happen next does not perform the action.
02 · Capture an evidence snapshot
Read-only adapters inspect Git, project declarations, review records, release provenance, and—where later integrations are approved—CI, security, infrastructure, or runtime evidence.
03 · Normalize evidence
Evidence is connected to exact object identities, revisions, versions, timestamps, and sources. Observed facts remain distinct from project declarations and AI interpretations.
04 · Evaluate pinned policy
The deterministic engine applies a named, versioned policy pack. The same evidence and policy version must produce the same semantic result.
05 · Produce a bounded finding
The result records what was observed, which rule applies, why it matters, its epistemic status, severity, safe next step, recovery test, and what the evidence does not prove.
06 · Explain without changing the judgment
AI or a human-readable catalog can translate the structured finding into natural language, compare options, and teach the underlying concept. Explanation cannot suppress the finding, change policy, or approve an exception.
07 · Decide, act, and verify
A human retains authority over consequential action. After the state changes, MetaAware observes again and verifies whether the stated recovery condition is now satisfied.

Evidence contract

Four kinds of input, kept deliberately separate.

Observed facts

Facts reproducibly obtained from Git, files, tool outputs, provider APIs, or runtime observations.

Declared context

Project intent that cannot be inferred safely: target release, branch purpose, required reviewers, approved artifact, business invariant, or accepted exception.

Imported evidence

Versioned results from CI, scanners, SBOM systems, infrastructure providers, identity services, or payment test environments. Imported evidence remains attributed to its producer and observation time.

Versioned policy

Explicit rules defining which evidence is required, how it is evaluated, what severity applies, and which recovery condition closes the finding.

A fluent explanation cannot substitute for any missing input.

Finding contract

A finding is a bounded argument, not a score.

This conceptual example shows the minimum reasoning chain a user or another system should be able to inspect.

FINDINGreview.stale

Observed fact: Current HEAD is not the commit identified by the recorded review.
Applicable rule: Review evidence must be bound to the revision being considered for integration.
Epistemic status: Observed Git fact combined with declared review evidence.
Why it matters: Later commits fall outside the scope of the recorded review.
Next safe step: Review the difference and record a new review against current HEAD.
Verify recovery: Confirm that the new review record identifies the current revision.

Does not prove: A fresh review does not prove that the code is correct, secure, valuable, or ready for production.

The wording is not the judgment.

This structure allows a developer, reviewer, CI system, or agent to inspect the same judgment without relying on the wording of one AI response.

Epistemic state

Uncertainty is part of the output.

Observed

The system reproduced the fact directly.

Declared

The project or an authorized person supplied the context.

Inferred

The result includes an explicit, challengeable interpretation.

Conflicting

Available evidence supports incompatible states.

Unknown

Required evidence is absent, inaccessible, stale, or insufficient.

Unknown is not automatically pass or fail. A policy may conservatively prevent an action while evidence is missing, but the system must distinguish that policy response from a claim that a defect has been proven.

Natural-language boundary

Natural language sits above the deterministic core.

Human question
or intent→Natural-language
adapter→Stable CLI and
evidence query→Deterministic engine
+ pinned policy→Structured
finding→Contextual
explanation→Accountable human
decision

A developer may ask, “Why is this release unsafe?” or “What should I do next?” The adapter translates the question into a bounded query. The answer must remain traceable to the resulting evidence and rule.

Natural language improves accessibility. It does not become the source of governance authority.

Responsibility separation

Each component has a limited responsibility.

Adapters observe

They obtain evidence from a defined source and report its identity, version, freshness, and limitations.

The deterministic engine judges

It applies versioned rules only to the evidence available. It must return unknown when the required evidence is missing.

AI explains

It translates findings, retrieves relevant guidance, compares recovery options, and adapts explanation depth to the user.

Humans constitute and authorize

Humans define policy, approve exceptions, accept consequential risk, and remain accountable for the decision.

Independent evidence challenges the system

External outcomes, independent oracles, blind scenarios, expert review, and prospective use test whether the rule and explanation were actually adequate.

Governance stack

Project governance is only one layer of the system.

External reality

Incidents, user outcomes, independent review, and the environment can contradict the system.

Meta-governance

Evidence and governed revision test whether MetaAware's rules, explanations, and boundaries remain adequate.

Project governance

Versioned policy converts bounded evidence into findings and recovery conditions.

Development activity

People and agents create changes, reviews, releases, declarations, and observable outcomes.

Domain expansion

The core stays stable while evidence sources change.

Observe through adapters

Security tools, cloud systems, runtime services, identity providers, and payment sandboxes remain specialist evidence producers.

Judge through policy packs

Versioned rules and project business invariants define what the available evidence supports.

Preserve the boundary

AI explains; humans authorize. Missing evidence produces unknown, and integrated findings do not become certification.

Capability improvement

MetaAware improves through governed revision.

Candidate
problem→Curated
evidence→Reproducible
scenario→Independent
expected result→Versioned rule
proposal→Development +
negative controls→Blind holdout
evaluation→Prospective
read-only use→Human promotion
or rollback

A new rule, a stronger AI model, or a larger number of warnings does not by itself demonstrate improved governance capability.

An improvement claim must identify the previous failure, the new evidence, the regression scenario, the blind result, changes in false positives, false negatives and unknown, and the remaining limitation.

Present tense

Current implementation boundary.

MetaAware does not yet have a released governance CLI.

The approved MVP is limited to six read-only capabilities—status, audit, next, why, explain, and doctor—and three rule families: branch and worktree safety, review freshness, and release provenance.

Assist and enforce modes, security policy packs, provider integrations, runtime observation, identity governance, and payment-integrity governance are accepted directions or design possibilities, not implemented capabilities.

Authoritative sourceGOV-PHILOSOPHY / TECHNICAL-DESIGN / ADR-013 / ADR-014 · Operating model, assurance boundary, and governed capability expansion · 2026-09-13