flowchart TD
    subgraph Human_or_AI ["AI Agent or Developer"]
        Init["omnistate init<br>(Mounts pre-commit hook)"] --> Begin
        Begin["omnistate begin<br>(Declare Intent & Scope)"]
        Begin --> Step["omnistate step<br>(Record Milestones)"]
        Step --> CodeEdit["Perform Code Edits"]
        CodeEdit --> Audit["omnistate audit<br>(Deterministic Gates)"]
    end

    subgraph Gates ["Quality & Security Gates"]
        Audit --> G1["Gate 1: Scope Enclosure Check"]
        Audit --> G2["Gate 2: Anti-Laziness Critic (Diff Scan)"]
        Audit --> G3["Gate 3: Anti-Bloat Ratio Check"]
        Audit --> G4["Gate 4: Automated Test Runner"]
        Audit --> G5["Gate 5: Empirical Evidence Verification"]
    end

    subgraph State_Engine ["OMNISTATE Engine"]
        G1 & G2 & G3 & G4 & G5 -->|All Passed| AuditPassed["Status: AUDITED<br>(Freezes SHA-256 Fingerprints)"]
        AuditPassed --> Finish["omnistate finish"]
        Finish --> TamperCheck{"Anti-Tamper Check:<br>Files changed since audit?"}
        TamperCheck -->|No| Clearance["Issue Commit Clearance Token<br>OMNI_CLEAR_XXXXXXXX<br>Archive rev_XXXX.json"]
        TamperCheck -->|Yes| TamperFail["🚨 Tamper Violation<br>Require Re-Audit"]
    end

    subgraph Git_Warden ["Git Pre-Commit Warden Hook"]
        Clearance --> GitCommit["git commit -m '...'"]
        GitCommit --> PreCommitHook[".git/hooks/pre-commit"]
        PreCommitHook --> WardenScan{"Warden Verification:<br>1. Active session completed?<br>2. Valid clearance token?<br>3. Staged hashes == Audited hashes?"}
        WardenScan -->|Yes| CommitAllowed["✅ Commit Permitted"]
        WardenScan -->|No| CommitBlocked["❌ COMMIT BLOCKED"]
    end

git clone https://github.com/cwen0224/omnistate.git
cd omnistate
pip install -e .

pip install omnistate

cd /path/to/your/project
omnistate init

{
  "mcpServers": {
    "omnistate": {
      "command": "omnistate-mcp",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

{
  "name": "omnistate",
  "command": "python",
  "args": ["-m", "omnistate.mcp", "--workspace", "."]
}

omnistate begin --intent "Implement OAuth login" --scope "auth/,tests/" --risk standard

omnistate step --action "Implemented JWT token parser" --details "Added unit test in test_auth.py"

omnistate status

==================================================================
  🌐 OMNISTATE STATE GOVERNANCE DASHBOARD (v1.0.0)
==================================================================
  Project Root     : /home/dev/my-project
  State Directory  : /home/dev/my-project/.omnistate
  Current Revision : #0012
  Git HEAD Commit  : a4b91ef201
------------------------------------------------------------------
  Transaction ID   : sess_3f1a92b810de
  Transaction State: 🟡 [ IN_PROGRESS ]
  Intent Summary   : Implement OAuth login
  Scope Boundary   : ['auth/', 'tests/']
  Risk Tier        : STANDARD
  Steps Recorded   : 3
  Audit Status     : ⏳ PENDING (Run 'omnistate audit' when edits complete)
------------------------------------------------------------------
  Working Tree Mod : 2 files modified
    • auth/oauth.py
    • tests/test_oauth.py
==================================================================

omnistate audit

================ OMNISTATE AUDIT RESULTS ================
  ✅ PASS | ScopeEnclosureGate
  ✅ PASS | AntiLazinessCritic
  ✅ PASS | AntiBloatCritic
  ✅ PASS | TestRunnerGate
=========================================================
🎉 All quality gates PASSED! Ready to execute 'omnistate finish'.

omnistate finish --evidence "tests/report.txt" --note "All tests green"

🎉 [OMNISTATE] Transaction COMPLETED: sess_3f1a92b810de
🛡️  Commit Clearance Token: OMNI_CLEAR_8A90F1BC24D7A19E
📦 Archived Revision     : #0013
🚀 You are now cleared to commit your changes with git!

git commit -m "feat(auth): implement OAuth login"
# Output:
# 🛡️  [OMNISTATE WARDEN PASSED] Clearance Token verified: OMNI_CLEAR_8A90F1BC24D7A19E

{
  "state_dir": ".omnistate",
  "ignored_paths": [
    ".git",
    ".venv",
    "node_modules",
    "__pycache__",
    "dist",
    "build"
  ],
  "gates": {
    "scope_enforcement": true,
    "anti_laziness": true,
    "anti_bloat": true,
    "max_file_growth_ratio": 2.0,
    "max_line_growth": 600,
    "test_command": "pytest -q",
    "evidence_required": false
  },
  "warden": {
    "enforce_pre_commit": true,
    "block_unclear_commits": true
  }
}

from pathlib import Path
from omnistate import OmniStateCoordinator

coord = OmniStateCoordinator(Path("."))

# 1. Begin
session = coord.begin(
    intent_summary="Refactor database models",
    scope_paths=["models/", "migrations/"],
    risk_tier="standard"
)

# 2. Record step
coord.record_step("Generated Alembic migration")

# 3. Audit
passed, gate_results = coord.audit(run_tests=True)
if passed:
    # 4. Finish
    finished_session = coord.finish(note="Migrations verified")
    print("Clearance Token:", finished_session.commit_clearance)
else:
    print("Audit failed! Gate errors:", [g.errors for g in gate_results if not g.passed])

python -m unittest discover -s tests