omega-review 0.2.1

Local-first, evidence-backed product reality-review harness

OMEGA

OMEGA is a local-first, evidence-backed product reality-review harness.

Your AI says the product is done. OMEGA checks whether reality agrees.

Install and run

pip install omega-review
omega

Running omega with no arguments starts an interactive first run:

1. Choose how OMEGA should use intelligence: connect an existing AI through MCP, configure your own OpenAI-compatible API (base URL, model, and an environment variable name holding your key -- OMEGA never stores or prints the raw key), or continue with deterministic checks only. This is asked once per machine, not per project.
2. Name the project to review (a local path or a deployed URL). OMEGA creates and manages its own workspace automatically, outside the reviewed project, keyed to that exact project so repeated runs reuse the same history -- you never need to run omega init or pick a workspace directory yourself.
3. OMEGA determines applicability (source, browser, or HTTP-only) rather than silently guessing: a deployed URL defaults to a real browser review when a browser runtime is available, and explicitly discloses a downgrade to HTTP-only inspection when it is not.
4. Review the previewed scope and authorize it.

omega scan --path <project> ... and omega report|status|retest latest --path <project> work the same way non-interactively, resolving the same managed workspace automatically. --workspace <dir> remains available as an advanced override, and omega init remains available for that advanced path. Provider credentials are never read from a project's own .env; pass --env-file <path> explicitly if you want OMEGA to load one.

OMEGA reviews products as users, builders, operators, and authorized adversarial testers would experience them. It combines product testing, UX judgment, adoption analysis, claim verification, security/privacy review, and focused retesting in one organized workflow.

OMEGA is not a dashboard, a generic vulnerability scanner, or an autonomous attack bot. The conversational harness is the control plane; durable artifacts are the memory and audit trail.

Why OMEGA exists

AI-assisted builders can produce working software quickly, but “the code exists” is not the same as “the product works.” Common gaps include:

• the happy path works while onboarding or recovery fails;
• features exist but users cannot understand or discover them;
• marketing claims exceed deployed behavior;
• permissions, data handling, or generated code create avoidable risk;
• automated reviews confidently repeat unsupported conclusions;
• fixes are made without preserving evidence or performing focused retests;
• each new agent must rediscover the architecture and prior decisions.

OMEGA addresses those gaps by sealing the target identity, compiling authorization, collecting bounded evidence, recording limitations, separating candidates from verified findings, and preserving everything required for another agent to continue safely.

The nine default pillars

Every product begins with the same nine pillars:

1. Functionality — Do the important journeys work, including failure and recovery paths?
2. User experience — Can intended users understand, complete, and recover from those journeys?
3. Trust — Does the product communicate risk, state, cost, privacy, and recovery honestly?
4. Adoption — Can users reach first value, understand differentiation, and find a reason to return?
5. Reliability — Does behavior remain coherent across retries, expired sessions, partial failures, and changing dependencies?
6. Performance — Is the product responsive within realistic user and resource constraints?
7. Accessibility — Can essential journeys be completed with keyboard, zoom, assistive technology, and clear semantics?
8. Security and privacy — Are permissions, data flows, authorization, secrets, boundaries, and misuse resistance appropriate?
9. Claim versus reality — Do public promises, documentation, pricing, and product behavior agree?

Product-specific lenses add depth without replacing these defaults. Examples include browser-extension isolation, AI prompt boundaries, generated-code safety, billing trust, first-value friction, and conversion-funnel analysis.

Core workflow

target intake
    ↓
exact identity + signed scope
    ↓
finite nine-pillar plan
    ↓
brokered evidence collection
    ↓
candidate review and independent verification
    ↓
report + SARIF + fix prompts + limitations
    ↓
focused retest and durable reconciliation

The implementation uses this operational spine:

scope → test → evidence → findings → report → retest

No model may grant authority, silently expand scope, invoke effects outside the Tool Broker, or confirm a finding without sufficient evidence.

Operating modes

Fixture mode

Fixture mode is an offline deterministic demonstration of the complete lifecycle. It proves orchestration, state transitions, evidence sealing, finding verification, reporting, and retesting without touching a production product.

Fixture results are not evidence about real-world containment or a real product.

Source mode

Source mode reviews an exact local repository without importing, building, executing, or contacting it. OMEGA:

• computes the bounded source identity;
• creates a content-addressed read-only snapshot outside the target;
• reverifies the snapshot before and after collection;
• inventories files under strict budgets;
• redacts credential-like material;
• detects technology stacks from sealed manifest names;
• runs the built-in deterministic source-hygiene scanner;
• records evidence-linked security candidates;
• produces SARIF, reports, limitations, and a harness packet.

Source mode deliberately completes only the static security/privacy coverage it actually earned. Runtime-dependent pillars remain not_tested until deployed-product evidence exists.

If unresolved scanner candidates exist, the run stops at awaiting_harness_review; it must not be represented as a verified vulnerability or a clean completed security assessment.

Deployed-product review

Browser, HTTP, authenticated, A3 active-verification, and A4 adversarial-lab phases require target-specific authorization and execution evidence. Contracts exist for these phases, but catalog presence never makes a capability executable.

Architecture

Operator / conversational harness
              │
              ▼
        OmegaApplication
              │
       ┌──────┼─────────┐
       ▼      ▼         ▼
  Scope &   Run state   Review plan
  approval  manager     and pillars
       │      │         │
       └──────┼─────────┘
              ▼
         Policy Gate
              │
              ▼
         Tool Broker
              │
     ┌────────┼──────────────┐
     ▼        ▼              ▼
 Local A0   Contained     Remote/lab
 adapters   tool boundary contracts
     │        │              │
     └────────┼──────────────┘
              ▼
       Immutable evidence index
              │
       ┌──────┴─────────┐
       ▼                ▼
 Candidate review   Integrity/verifier gates
       └──────┬─────────┘
              ▼
 Reports, SARIF, prompts, limitations,
 retest ledger, and harness packet

Important boundaries:

• Scope Compiler normalizes exact targets, action classes, capabilities, budgets, data rules, and time windows.
• Signed approvals bind permitted actions to one exact scope hash.
• Policy Gate decides authorization; it is not a containment mechanism.
• Tool Broker is the sole adapter-dispatch and evidence-capture path.
• Adapters enforce their own target, budget, cancellation, and containment contracts.
• Evidence Store writes append-only metadata and verifies artifact hashes.
• Reviewers may propose conclusions but cannot promote unsupported findings.
• Harness packet exposes a redacted, machine-readable control-plane view for the conversational agent.

Security execution model

OMEGA uses five action classes:

Class	Purpose	Typical examples
A0	Local passive inspection	Source inventory, static hygiene, manifest analysis
A1	Remote passive observation	Bounded HTTP observation, headers, public pages
A2	Normal user interaction	Signup, onboarding, ordinary browser journeys
A3	Active verification	Exact candidate verification with structured cleanup
A4	Disposable adversarial lab	Contained realistic testing against an isolated resettable target

Non-negotiable rules:

• No permission, no test.
• Authorization must name the exact target and capability.
• Third-party services are not automatically included because the product integrates with them.
• No load, stress, destructive, billing, or high-cost testing without explicit authorization and containment.
• Secrets and real-user data must not enter prompts, reports, logs, packets, or public case studies.
• A3 requires exact authorization, budgets, evidence, and a structured cleanup contract.
• A4 requires a disposable isolated lab, signed evidence-bound proof, synthetic data, reset verification, residue checks, teardown, and mandatory abort conditions.
• Every redirect, DNS resolution, credential handle, request, page, duration, byte, concurrency, and rate budget must remain within its contract.
• External tools require authenticated release evidence; caller-supplied booleans cannot release them.
• Findings remain candidates until evidence and verifier/refuter records support promotion.

Repository organization

Omega/
├── src/omega/                 # Application and library source
│   ├── adapters/              # Local, container, build, remote, and lab boundaries
│   ├── application/           # Orchestration, planning, state, scope, and review workflow
│   ├── evidence/              # Evidence storage and redaction
│   ├── policy/                # Scope taxonomy, approvals, and Policy Gate
│   ├── reporting/             # Reports, fix prompts, limitations, and SARIF
│   ├── security/              # Catalog, playbooks, scanner definitions, and findings
│   ├── snapshots/             # Content-addressed source snapshots
│   └── schemas/               # Schemas bundled into the release wheel
├── schemas/                   # Canonical artifact contracts
├── playbooks/                 # Canonical bounded test playbooks
├── scripts/                   # Operator entry points
├── tests/                     # Unit, contract, integration, and acceptance tests
├── docs/                      # Architecture, workflow, threat model, and implementation status
├── .omega/context/            # Durable team and agent context
├── .omega/logs/               # Historical build, decision, review, and session logs
└── dist/                      # Verified release wheel

Generated review data lives outside the target source:

workspace/
└── product-testing/
    └── <product>/
        ├── product.json
        ├── product.md
        ├── architecture.md
        ├── builder-comfort.md
        ├── known-holes.md
        ├── decisions.md
        ├── build-log.md
        ├── change-log.md
        ├── review-history.md
        ├── versions.md
        └── runs/<run-id>/
            ├── run.json
            ├── scope.json
            ├── product-map.json
            ├── review-plan.json
            ├── task-events.jsonl
            ├── approvals.jsonl
            ├── evidence/
            ├── findings/
            ├── snapshots/
            ├── logs/
            ├── report.md
            ├── findings.sarif
            ├── fix-prompts.md
            └── limitations.md

Canonical evidence remains inside its run. Product-level documents link to or summarize run artifacts rather than copying evidence into multiple places.

Agent operating model

OMEGA is designed so strong reasoning can be converted into durable artifacts that reduce reasoning requirements for later agents.

• Conversational architect/harness: clarifies product intent, scope, judgment standards, and unresolved decisions.
• Implementation agent: changes code, maintains tests, rebuilds releases, and updates durable documentation.
• Review harness: consumes the harness packet, coordinates approved tools, challenges candidates, and writes evidence-backed conclusions.
• Lighter agents: follow schemas, plans, fix prompts, logs, and bounded tasks without reopening frozen architecture.

Before implementation or review work, agents must read:

1. README.md
2. docs/IMPLEMENTATION_STATUS.md
3. .omega/context/OMEGA_CONTEXT.md
4. .omega/context/FOLDER_ARCHITECTURE.md
5. .omega/context/KNOWN_HOLES.md
6. .omega/context/BUILDER_COMFORT.md
7. the latest applicable build and decision logs
8. any AGENTS.md or repository-local instructions

Historical task logs should not be rewritten. Newer records must explicitly supersede outdated guidance.

Installation

Requirements:

• Windows, Linux, or macOS with Python 3.12
• Dependencies declared in pyproject.toml
• PowerShell for the convenience wrapper shown below
• Docker only for release-gated external scanner/build execution

Editable development installation:

python -m pip install -e ".[test]"
python -m pytest -q

Install the verified wheel:

python -m pip install .\dist\omega_review-0.2.1-py3-none-any.whl
omega --version
omega --json doctor
omega --json security status

Review a builder project

From this repository:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\review-project.ps1 `
  -ProjectPath "D:\Codes\YourProject"

The wrapper:

• resolves the exact project path;
• creates a collision-resistant default workspace using the project name and path hash;
• initializes the workspace when required;
• creates or reuses the matching product record;
• creates, authorizes, plans, executes, and reports a source-mode run;
• returns the report, SARIF, harness packet, candidates, target identity, and required next inputs.

Default artifacts are stored under:

%LOCALAPPDATA%\Omega\workspaces\<project>-<path-hash>

An explicit workspace and product may be supplied:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\review-project.ps1 `
  -ProjectPath "D:\Codes\YourProject" `
  -Workspace "D:\OmegaData\your-project" `
  -Product "your-project"

Manual CLI workflow

$workspace = "D:\OmegaData\example"
$project = "D:\Codes\ExampleProduct"

omega --json init $workspace
omega --json --workspace $workspace product create example --target $project
omega --json --workspace $workspace run create example --mode source

# Copy the run_id returned by the preceding command.
$run = "run_REPLACE_ME"

omega --json --workspace $workspace run validate $run --authorize-local
omega --json --workspace $workspace run plan $run
omega --json --workspace $workspace run execute $run
omega --json --workspace $workspace run report $run
omega --json --workspace $workspace run packet $run

--authorize-local is an explicit acknowledgement for passive inspection of the exact local source identity. It does not authorize building, executing, networking, mutation, or testing unrelated services.

Starting a deployed-product review

The harness packet lists target-specific prerequisites. A normal deployed review requires:

• builder project directory or repository artifact;
• deployment URL and exact allowed origins, paths, and query keys;
• critical user journeys and expected outcomes;
• explicit allowed and forbidden actions;
• request, duration, generation, and cost budgets;
• opaque test-account handles when authenticated testing is needed;
• billing sandbox before payment-edge testing;
• for A4 only, a disposable lab and signed reset/isolation/synthetic-data proof.

Integrations with Google, TradingView, YouTube, payment providers, social networks, or other third parties do not grant permission to test those third parties.

Reports and finding semantics

OMEGA separates:

• observation: directly captured evidence;
• candidate: a plausible issue requiring review;
• needs more evidence: not supportable yet;
• verified finding: independently supported and promoted;
• rejected finding: challenged and refuted;
• limitation: an explicit untested, blocked, partial, or integrity-constrained surface.

Reports include:

• executive verdict;
• exact tested identity and scope;
• nine-pillar coverage;
• verified findings;
• unresolved candidates;
• limitations and prerequisites;
• fix prompts;
• focused retest state;
• SARIF for supported security records;
• artifact and evidence references.

A clean passive source report means only that the bounded released checks produced no promotable finding. It does not mean the product is secure, reliable, accessible, or ready to launch.

Current release status

Current package version: 0.2.1

Verified release artifact:

dist/omega_review-0.2.1-py3-none-any.whl
SHA-256: 052b1d3ab9eb001b321626f5806f99312eccbfc4632be44a84838201ebbc95c8

Release verification:

• Python 3.12.10 on Windows
• 963 unit, contract, integration, acceptance, and real-Chromium tests passed with 0 skipped and 0 failed
• all nine default pillars have at least two operationally proven playbooks on owned fixtures
• 18 of 56 catalog packages are operationally proven; remaining packages retain their explicit maturity state
• catalog conformance passed: 251 tests
• clean-wheel CLI and 13-tool MCP smoke tests passed from an external project
• installed and source catalogs matched across all 56 packages
• deterministic catalog digest: f205addb88048517deffa7b82a51a0091c4c956a5d6847caa339801367ffed41

Released

• signed exact local authorization;
• dispatch-time structured policy decisions;
• content-addressed, reverified source snapshots;
• bounded source inventory and redaction;
• built-in deterministic source-hygiene scanning;
• stack detection from sealed manifests;
• evidence-linked security candidates;
• deterministic reporting and SARIF;
• harness packet export;
• organized durable product/run artifacts.

Implemented but release-gated

• fixed Semgrep, Bandit, Gitleaks, TruffleHog, OSV-Scanner, Trivy, and Checkov container definitions and normalizers;
• digest-pinned, non-root, no-network, read-only container contracts;
• fixed build/runtime profiles for Python, Node, Rust, Go, Java, .NET, Ruby, and PHP;
• exact browser/HTTP/A3 request contracts;
• DNS freshness, redirect, credential, authorization, and complete remote-budget contracts;
• signed evidence-bound A4 lab/reset/abort contracts.

These capabilities require their exact runtime, signed release evidence, provenance, licensing, containment, benchmark, current authorization, and target inputs. The current development machine has a Docker client but no verified running Docker daemon.

Deliberately not included

• hosted dashboard or SaaS control plane;
• multi-user tenancy;
• database server or distributed queue;
• uncontrolled autonomous testing;
• load/stress testing by default;
• automatic public disclosure;
• automatic claims of compliance or complete security.

Team completion discipline

The governing rule is evidence before claims. Architecture, contracts, fixture tests, real integration, operational proof, and release are separate maturity levels and must never be collapsed into one completion claim.

For every material implementation task:

1. Inspect current repository state and preserve unrelated changes.
2. Identify exact scope and affected contracts.
3. Implement through existing boundaries.
4. Add focused regression tests.
5. Run the focused suite.
6. Run the complete suite before claiming release readiness.
7. Rebuild and install-smoke the wheel when packaged code changes.
8. Record commands, counts, duration, platform, artifact hashes, failures, and limitations.
9. Update architecture, build log, builder comfort, known holes, decisions, change log, and review history as applicable.
10. Stop honestly at missing authorization, target inputs, release evidence, or containment—not at a fabricated clean result.

Case studies and disclosure

Sanitized case studies require explicit builder permission. Before publication:

• remove product/user identifiers unless separately approved;
• exclude real-user data, credentials, session content, and private evidence;
• provide the builder a draft;
• allow remediation of live security issues;
• distinguish verified evidence from interpretation;
• preserve the agreed disclosure window.

Further documentation

• docs/README.md — documentation index
• docs/SYSTEM_ARCHITECTURE.md — system boundaries and components
• docs/SECURITY_EXECUTION_MODEL.md — A0–A4 execution model
• docs/THREAT_MODEL.md — threats and controls
• docs/ARTIFACT_CONTRACTS.md — artifact and schema contracts
• docs/TEST_WORKFLOW.md — end-to-end review workflow
• docs/PILLAR_CONTRACTS.md — pillar definitions
• docs/MODEL_ORCHESTRATION.md — bounded model roles
• docs/IMPLEMENTATION_STATUS.md — released and gated capability status
• .omega/context/KNOWN_HOLES.md — explicit unresolved gaps
• .omega/context/BUILDER_COMFORT.md — collaboration and operating preferences
• docs/IMPLEMENTATION_STATUS.md — current release evidence and maturity boundaries

Principle

OMEGA should be demanding about product reality and conservative about authority.

Realistic testing is valuable only when its scope, evidence, containment, limitations, and consequences remain clear.

License

OMEGA is licensed under the MIT License.