@trac3er/oh-my-god 2.0.3 → 2.0.5

package/OMG_COMPAT_CONTRACT.md

@@ -0,0 +1,92 @@
+---
+title: OMG Production Control Plane
+version: 2.0.5
+canonical_hosts:
+  - claude
+  - codex
+status: active
+---
+
+# OMG Production Control Plane
+
+`OMG_COMPAT_CONTRACT.md` is the normative human-readable contract for OMG capability bundles. Machine-readable manifests in `registry/bundles/` are executable inputs and must remain version-locked to this document.
+
+## metadata
+
+Every bundle must declare `id`, `kind`, `version`, `title`, `description`, `hosts`, and `assets`.
+
+## invocation_policy
+
+Every bundle must declare whether it is user invocable, model invocable, and whether implicit invocation is allowed. Production bundles default to explicit invocation only.
+
+## tool_policy
+
+Every bundle must declare `side_effect_level` and host-specific allowed tools. Production policy protects `.omg/`, `.agents/`, `.codex/`, and `.claude/` as control-plane state.
+
+## lifecycle_hooks
+
+Canonical OMG events:
+
+- `SessionStart`
+- `SessionEnd`
+- `PreToolUse`
+- `PostToolUse`
+- `PostToolUseFailure`
+- `Stop`
+- `PreCompact`
+- `ConfigChange`
+- `WorktreeCreate`
+- `WorktreeRemove`
+- `SubagentStart`
+- `SubagentStop`
+- `TaskCompleted`
+
+Hosts compile native events where available and emulate the rest with OMG runtime wrappers.
+
+## mcp_contract
+
+Bundles may declare MCP servers, prompts, resources, and server instructions. `omg-control` is the primary stdio server. HTTP control-plane exposure is loopback-only and not a production launch dependency.
+
+## lsp_contract
+
+LSP packs declare supported languages, diagnostics expectations, and evidence outputs for post-edit checks.
+
+## evidence_outputs
+
+Bundles declare reproducible evidence artifacts under `.omg/evidence/` or `.omg/state/`. Release-ready bundles must emit deterministic outputs suitable for CI drift checks.
+
+## execution_contract
+
+Supported execution modes:
+
+- `embedded`
+- `local_supervisor`
+- `automation`
+- `ephemeral_worktree`
+
+`local_supervisor` means a same-machine orchestrator driving Claude and Codex workers through local CLI or stdio MCP integration. Remote multi-tenant control planes are out of scope for this version.
+
+## host_compilation_rules
+
+Claude outputs compile to:
+
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.mcp.json`
+- generated hook configuration consumed by `settings.json`
+
+Codex outputs compile to:
+
+- `.agents/skills/omg/<bundle>/SKILL.md`
+- `.agents/skills/omg/<bundle>/openai.yaml`
+- generated Codex MCP and rule fragments under `.agents/skills/omg/`
+
+## roadmap_extensions
+
+The contract reserves compilation anchors for:
+
+- `omg.skill-compiler`
+- `omg.hook-governor`
+- `omg.mcp-fabric`
+- `omg.lsp-pack`
+- `omg.secure-worktree-pipeline`

package/README.md

@@ -1,4 +1,4 @@
-# OMG 2.0.3
+# OMG 2.0.5
 
 [![Compat Gate](https://github.com/trac3er00/OMG/actions/workflows/omg-compat-gate.yml/badge.svg)](https://github.com/trac3er00/OMG/actions/workflows/omg-compat-gate.yml)
 [![npm version](https://img.shields.io/npm/v/%40trac3er%2Foh-my-god)](https://www.npmjs.com/package/@trac3er/oh-my-god)
@@ -11,7 +11,7 @@ OMG upgrades your agent host instead of replacing it. It gives Claude Code, Code
 - npm: `@trac3er/oh-my-god`
 - Plugin id: `omg`
 - Marketplace id: `omg`
-- Version: `2.0.3`
+- Version: `2.0.5`
 
 ## Why OMG
 
@@ -20,6 +20,17 @@ OMG upgrades your agent host instead of replacing it. It gives Claude Code, Code
 - Native adoption: setup detects OMC, OMX, and Superpowers-style environments without exposing copycat public migration commands.
 - Proof-first delivery: verification, provider coverage, HUD artifacts, and transcripts are published instead of implied.
 
+## Canonical Contract
+
+OMG now ships a production control-plane contract and generated host artifacts.
+
+- Normative spec: `OMG_COMPAT_CONTRACT.md`
+- Executable registry: `registry/omg-capability.schema.json` and `registry/bundles/*.yaml`
+- Generated Codex pack: `.agents/skills/omg/`
+- Validation: `python3 scripts/omg.py contract validate`
+- Compilation: `python3 scripts/omg.py contract compile --host claude --host codex --channel public`
+- Release gate: `python3 scripts/omg.py release readiness --channel dual`
+
 ![OMG HUD](docs/assets/omg-hud.svg)
 
 ## Quickstart
@@ -50,6 +61,7 @@ Success looks like:
 
 - supported hosts are detected
 - `.mcp.json` is configured
+- `.mcp.json` includes both `omg-memory` and stdio `omg-control`
 - `.omg/state/adoption-report.json` is written when another ecosystem is present
 - OMG reports the selected preset and next step
 
@@ -65,11 +77,17 @@ OMG uses native setup language instead of public migration commands.
 - `coexist`: advanced. OMG preserves non-conflicting third-party surfaces and records overlap instead of overwriting it.
 - Presets: `safe`, `balanced`, `interop`, `labs`.
 
+## Security Notes
+
+- The shipped `safe` preset now registers pre-tool security hooks before the planning helper.
+- `Bash` requests are screened by `firewall.py`, and file reads or edits are screened by `secret-guard.py`.
+- Raw environment dumps, interpreters, and permission-changing commands such as `env`, `node`, `python`, `python3`, `chmod`, and `chown` now require approval instead of being silently allowed.
+
 Compatibility references to OMC, OMX, and Superpowers are documented here: [docs/migration/native-adoption.md](docs/migration/native-adoption.md)
 
 ## Proof
 
-Current local verification for this release: `2425 passed, 2 skipped` on March 6, 2026.
+Current local verification for this release: `2466 passed, 2 skipped` on March 7, 2026.
 
 - Verification and provider matrix: [docs/proof.md](docs/proof.md)
 - Sample setup transcript: [docs/transcripts/setup.md](docs/transcripts/setup.md)
@@ -85,11 +103,13 @@ Primary entry points:
 
 Advanced surfaces stay available for deeper workflows:
 
+- `/OMG:security-check`
+- `/OMG:api-twin`
+- `/OMG:preflight`
 - `/OMG:teams`
 - `/OMG:ccg`
 - `/OMG:compat`
 - `/OMG:ship`
-- `/OMG:security-review`
 
 ## Contributing
 

package/SECURITY.md

@@ -23,3 +23,9 @@ Include:
 ## Supported Versions
 
 Security fixes are prioritized for the latest released version.
+
+## Maintainer Notes
+
+- The shipped `safe` preset is expected to enforce pre-tool security hooks before helper hooks run.
+- `firewall.py` should screen `Bash` usage and `secret-guard.py` should screen `Read`, `Write`, `Edit`, and `MultiEdit`.
+- Sensitive shell commands such as raw `env` dumps, interpreter entry points, and direct permission changes should require approval in the `safe` preset rather than being silently allowed.

package/commands/OMG:api-twin.md

@@ -0,0 +1,22 @@
+---
+description: "Contract replay and fixture-based API simulation with fidelity tracking and live verification requirements."
+allowed-tools: Read, Write, Edit, MultiEdit, Grep, Glob, Bash(python3:*), Bash(rg:*)
+argument-hint: "[ingest|record|serve|verify]"
+---
+
+# /OMG:api-twin — Contract Replay
+
+Build a local API twin from contracts and recorded fixtures without treating simulation as final proof.
+
+## Verbs
+
+- `ingest`: load OpenAPI, Swagger, Postman, or example JSON into OMG state
+- `record`: store approved request/response fixtures and tag fidelity
+- `serve`: replay a fixture locally with optional latency, failure, or schema drift
+- `verify`: compare a twin fixture against a live response before release proof
+
+## Rules
+
+- every fixture carries a fidelity tag such as `schema-only`, `recorded`, `recorded-validated`, or `stale`
+- simulated endpoints are useful for development, not release signoff
+- release proof still requires a final live verification pass

package/commands/OMG:preflight.md

@@ -0,0 +1,26 @@
+---
+description: "Structured OMG router that classifies risk, selects the right route, and emits an execution/evidence plan."
+allowed-tools: Read, Grep, Glob, Bash(python3:*), Bash(rg:*)
+argument-hint: "\"<goal>\""
+---
+
+# /OMG:preflight — Structured Router
+
+Use `preflight` when the goal is clear but the safest execution route is not.
+
+## Output Contract
+
+- restated goal
+- task class
+- risk class
+- recommended route
+- required tools and MCPs
+- missing constraints
+- evidence requirements
+
+## Typical Routes
+
+- `security-check` for security-sensitive or trust-bound work
+- `api-twin` for contract replay and offline integration work
+- `crazy` for parallel execution
+- `teams` for targeted model routing

package/commands/OMG:security-check.md

@@ -0,0 +1,28 @@
+---
+description: "Canonical OMG security pipeline with normalized findings, dependency enrichment, and untrusted-content evidence."
+allowed-tools: Read, Grep, Glob, Bash(python3:*), Bash(pytest:*), Bash(rg:*)
+argument-hint: "[path or '.' for the current project]"
+---
+
+# /OMG:security-check — Canonical Security Pipeline
+
+Run OMG's canonical security pipeline against the current project or a scoped path.
+
+## Usage
+
+```text
+/OMG:security-check
+/OMG:security-check .
+/OMG:security-check app/
+```
+
+## What It Produces
+
+- normalized findings across policy, Python AST checks, and dependency health
+- evidence-ready provenance and trust scores
+- a structured result that can be reused by `ship`, the control plane, and the OMG MCP
+
+## Notes
+
+- Use this for auth, secrets, untrusted-content, or dependency-risk work.
+- `omg secure --command ...` remains the low-level command-risk primitive, not the full audit surface.

package/commands/__init__.py

@@ -0,0 +1 @@
+"""OMG command package marker for packaging parity."""

package/control_plane/__init__.py

@@ -0,0 +1,2 @@
+"""Control plane package for OMG v1."""
+

package/control_plane/openapi.yaml

@@ -0,0 +1,228 @@
+openapi: 3.1.0
+info:
+  title: OMG Control Plane API
+  version: 2.0.5
+  description: Policy/trust/evidence/runtime/registry/lab endpoints for OMG v2, with deprecated v1 aliases for one release.
+servers:
+  - url: https://api.omg.local
+paths:
+  /v2/policy/evaluate:
+    post:
+      summary: Evaluate policy decision
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PolicyInput'
+      responses:
+        '200':
+          description: Decision result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolicyDecision'
+  /v1/policy/evaluate:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/policy/evaluate
+      responses:
+        '200':
+          description: Decision result
+  /v2/trust/review:
+    post:
+      summary: Review trust-sensitive config changes
+      responses:
+        '200':
+          description: Trust review report
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TrustReview'
+  /v1/trust/review:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/trust/review
+      responses:
+        '200':
+          description: Trust review report
+  /v2/evidence/ingest:
+    post:
+      summary: Ingest evidence pack
+      responses:
+        '202':
+          description: Accepted
+  /v1/evidence/ingest:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/evidence/ingest
+      responses:
+        '202':
+          description: Accepted
+  /v2/security/check:
+    post:
+      summary: Run canonical OMG security check
+      responses:
+        '200':
+          description: Security check result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SecurityCheckResult'
+  /v1/security/check:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/security/check
+      responses:
+        '200':
+          description: Security check result
+  /v2/guide/assert:
+    post:
+      summary: Assert output against explicit project rules
+      responses:
+        '200':
+          description: Guide assertion result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GuideAssertionResult'
+  /v1/guide/assert:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/guide/assert
+      responses:
+        '200':
+          description: Guide assertion result
+  /v2/runtime/dispatch:
+    post:
+      summary: Dispatch job to runtime adapter
+      responses:
+        '200':
+          description: Runtime dispatch result
+  /v1/runtime/dispatch:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/runtime/dispatch
+      responses:
+        '200':
+          description: Runtime dispatch result
+  /v2/registry/verify:
+    post:
+      summary: Verify supply-chain artifact
+      responses:
+        '200':
+          description: Verification decision
+  /v1/registry/verify:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/registry/verify
+      responses:
+        '200':
+          description: Verification decision
+  /v2/lab/jobs:
+    post:
+      summary: Create lab pipeline job
+      responses:
+        '201':
+          description: Created
+  /v1/lab/jobs:
+    post:
+      deprecated: true
+      summary: Deprecated alias of /v2/lab/jobs
+      responses:
+        '201':
+          description: Created
+  /v2/scoreboard/baseline:
+    get:
+      summary: Return baseline scorecard
+      responses:
+        '200':
+          description: KPI baseline snapshot
+  /v1/scoreboard/baseline:
+    get:
+      deprecated: true
+      summary: Deprecated alias of /v2/scoreboard/baseline
+      responses:
+        '200':
+          description: KPI baseline snapshot
+components:
+  schemas:
+    PolicyInput:
+      type: object
+      properties:
+        tool:
+          type: string
+        input:
+          type: object
+      additionalProperties: true
+    PolicyDecision:
+      type: object
+      required: [action, risk_level, reason, controls]
+      properties:
+        action:
+          type: string
+          enum: [allow, ask, deny]
+        risk_level:
+          type: string
+          enum: [low, med, high, critical]
+        reason:
+          type: string
+        controls:
+          type: array
+          items:
+            type: string
+    TrustReview:
+      type: object
+      required: [changed_files, mcp_changes, hook_changes, env_changes, risk_score, verdict]
+      properties:
+        changed_files:
+          type: array
+          items: { type: string }
+        mcp_changes:
+          type: array
+          items: { type: object }
+        hook_changes:
+          type: object
+        env_changes:
+          type: array
+          items: { type: object }
+        risk_score:
+          type: integer
+        verdict:
+          type: string
+    SecurityCheckResult:
+      type: object
+      required: [schema, status, scope, findings, summary, provenance, trust_scores]
+      properties:
+        schema:
+          type: string
+        status:
+          type: string
+        scope:
+          type: string
+        findings:
+          type: array
+          items:
+            type: object
+        summary:
+          type: object
+        provenance:
+          type: array
+          items:
+            type: object
+        trust_scores:
+          type: object
+    GuideAssertionResult:
+      type: object
+      required: [schema, verdict, violations, summary]
+      properties:
+        schema:
+          type: string
+        verdict:
+          type: string
+        violations:
+          type: array
+          items:
+            type: object
+        summary:
+          type: object

package/control_plane/server.py

@@ -0,0 +1,123 @@
+"""Lightweight HTTP server for OMG control-plane APIs."""
+from __future__ import annotations
+
+import argparse
+import sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json
+from typing import Any
+
+from control_plane.service import ControlPlaneService
+
+
+def _json_response(handler: BaseHTTPRequestHandler, status: int, payload: dict[str, Any]) -> None:
+    body = json.dumps(payload, ensure_ascii=True).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+def _read_json(handler: BaseHTTPRequestHandler) -> dict[str, Any]:
+    length = int(handler.headers.get("Content-Length", "0"))
+    if length <= 0:
+        return {}
+    raw = handler.rfile.read(length)
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+_POST_ROUTE_TABLE = {
+    "/v2/policy/evaluate": ("policy_evaluate", False),
+    "/v1/policy/evaluate": ("policy_evaluate", True),
+    "/v2/trust/review": ("trust_review", False),
+    "/v1/trust/review": ("trust_review", True),
+    "/v2/evidence/ingest": ("evidence_ingest", False),
+    "/v1/evidence/ingest": ("evidence_ingest", True),
+    "/v2/security/check": ("security_check", False),
+    "/v1/security/check": ("security_check", True),
+    "/v2/guide/assert": ("guide_assert", False),
+    "/v1/guide/assert": ("guide_assert", True),
+    "/v2/runtime/dispatch": ("runtime_dispatch", False),
+    "/v1/runtime/dispatch": ("runtime_dispatch", True),
+    "/v2/registry/verify": ("registry_verify", False),
+    "/v1/registry/verify": ("registry_verify", True),
+    "/v2/lab/jobs": ("lab_jobs", False),
+    "/v1/lab/jobs": ("lab_jobs", True),
+}
+
+_GET_ROUTE_TABLE = {
+    "/v2/scoreboard/baseline": ("scoreboard_baseline", False),
+    "/v1/scoreboard/baseline": ("scoreboard_baseline", True),
+}
+
+
+def _decorate_payload(payload: dict[str, Any], *, deprecated: bool) -> dict[str, Any]:
+    decorated = dict(payload)
+    decorated["api_version"] = "v2"
+    if deprecated:
+        decorated["deprecated"] = True
+        decorated["deprecated_alias"] = "v1"
+    return decorated
+
+
+def make_handler(service: ControlPlaneService):
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            route = _GET_ROUTE_TABLE.get(self.path)
+            if route is not None:
+                method_name, deprecated = route
+                status, payload = getattr(service, method_name)()
+                _json_response(self, status, _decorate_payload(payload, deprecated=deprecated))
+                return
+            _json_response(self, 404, {"status": "error", "message": "Not found"})
+
+        def do_POST(self) -> None:  # noqa: N802
+            payload = _read_json(self)
+            route = _POST_ROUTE_TABLE.get(self.path)
+            if route is not None:
+                method_name, deprecated = route
+                status, out = getattr(service, method_name)(payload)
+                _json_response(self, status, _decorate_payload(out, deprecated=deprecated))
+                return
+
+            _json_response(self, 404, {"status": "error", "message": "Not found"})
+
+        def log_message(self, format: str, *args: Any) -> None:  # noqa: A003
+            # Quiet default request logs; keep response JSON clean for local usage.
+            return
+
+    return Handler
+
+
+def run_server(host: str = "127.0.0.1", port: int = 8787, project_dir: str | None = None) -> None:
+    service = ControlPlaneService(project_dir=project_dir)
+    handler = make_handler(service)
+    server = HTTPServer((host, port), handler)
+    try:
+        server.serve_forever()
+    finally:
+        server.server_close()
+
+
+def _main() -> int:
+    parser = argparse.ArgumentParser(description="Run OMG control-plane API server")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+    parser.add_argument("--project-dir", default=None)
+    args = parser.parse_args()
+    if args.host != "127.0.0.1":
+        print(f"⚠ WARNING: Binding to {args.host} exposes the control plane to the network. No authentication is configured.", file=sys.stderr)
+
+    run_server(args.host, args.port, args.project_dir)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())