Metadata-Version: 2.4
Name: omega-review
Version: 0.2.1
Summary: Local-first, evidence-backed product reality-review harness
Requires-Python: <4,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: filelock<4,>=3.20
Requires-Dist: cryptography<47,>=45.0.7
Requires-Dist: playwright<2,>=1.55
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: pytest-timeout==2.4.0; extra == "test"
Requires-Dist: pytest-asyncio==1.4.0; extra == "test"
Requires-Dist: fastapi==0.138.0; extra == "test"
Requires-Dist: uvicorn==0.49.0; extra == "test"
Requires-Dist: httpx==0.28.1; extra == "test"
Dynamic: license-file

# 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

```bash
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

```text
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:

```text
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

```text
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

```text
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:

```text
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:

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

Install the verified wheel:

```powershell
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
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:

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

An explicit workspace and product may be supplied:

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

## Manual CLI workflow

```powershell
$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:

```text
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](.omega/context/EVIDENCE_FIRST.md). 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`](docs/README.md) — documentation index
- [`docs/SYSTEM_ARCHITECTURE.md`](docs/SYSTEM_ARCHITECTURE.md) — system boundaries and components
- [`docs/SECURITY_EXECUTION_MODEL.md`](docs/SECURITY_EXECUTION_MODEL.md) — A0–A4 execution model
- [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) — threats and controls
- [`docs/ARTIFACT_CONTRACTS.md`](docs/ARTIFACT_CONTRACTS.md) — artifact and schema contracts
- [`docs/TEST_WORKFLOW.md`](docs/TEST_WORKFLOW.md) — end-to-end review workflow
- [`docs/PILLAR_CONTRACTS.md`](docs/PILLAR_CONTRACTS.md) — pillar definitions
- [`docs/MODEL_ORCHESTRATION.md`](docs/MODEL_ORCHESTRATION.md) — bounded model roles
- [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md) — released and gated capability status
- [`.omega/context/KNOWN_HOLES.md`](.omega/context/KNOWN_HOLES.md) — explicit unresolved gaps
- [`.omega/context/BUILDER_COMFORT.md`](.omega/context/BUILDER_COMFORT.md) — collaboration and operating preferences
- [`docs/IMPLEMENTATION_STATUS.md`](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](LICENSE).
