@trac3r/oh-my-god 2.2.11

package/docs/install/github-action.md

@@ -0,0 +1,81 @@
+# OMG GitHub Action
+
+The official `OMG PR Reviewer` composite action provides one-step integration for
+evidence-backed PR governance checks. It wraps the full review pipeline into a
+single `action.yml` consumable from any GitHub Actions workflow.
+
+## Quick Setup
+
+Add the action to your workflow:
+
+```yaml
+name: OMG PR Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # ... your build / test steps that produce artifacts/ ...
+
+      - uses: trac3r00/OMG@v2
+        with:
+          repo-full-name: ${{ github.repository }}
+          pr-number: ${{ github.event.pull_request.number }}
+          head-sha: ${{ github.event.pull_request.head.sha }}
+          github-app-id: ${{ vars.OMG_APP_ID }}
+          github-app-installation-id: ${{ vars.OMG_APP_INSTALLATION_ID }}
+          github-app-private-key: ${{ secrets.OMG_APP_PRIVATE_KEY }}
+```
+
+The action is defined in the root `action.yml` of this repository.
+
+## Inputs
+
+| Input | Required | Description |
+| :--- | :---: | :--- |
+| `repo-full-name` | ✅ | Repository full name (`owner/repo`) |
+| `pr-number` | ✅ | Pull request number |
+| `head-sha` | ✅ | PR head commit SHA |
+| `github-app-id` | ✅ | GitHub App ID for posting the review |
+| `github-app-installation-id` | ✅ | GitHub App installation ID |
+| `github-app-private-key` | ✅ | GitHub App private key (PEM format) |
+
+## GitHub App Setup
+
+The action authenticates via a GitHub App. Follow [GitHub App Setup](github-app.md)
+to create the app, generate a private key, and configure the required secrets.
+
+## Stable Check Name
+
+The required-check name for branch protection is **immutable**:
+
+```
+OMG PR Reviewer
+```
+
+This name is defined in `action.yml` and must not be changed. Set it as your
+required status check in **Settings → Branches → Branch protection rules**.
+
+> **Important**: When adding the required check in the GitHub UI, select the
+> entry showing the OMG App icon (not the GitHub Actions icon) to ensure the
+> check is pinned to your App's `app_id`. See [GitHub App Setup](github-app.md)
+> for `app_id` pinning details.
+
+## Reusable Workflow
+
+For repositories that prefer a reusable workflow over a composite action, OMG
+also ships `.github/workflows/evidence-gate.yml`. See [GitHub App Setup](github-app.md)
+for the reusable workflow invocation pattern.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| :--- | :--- | :--- |
+| Check never appears | App not installed on repo | Install the GitHub App on the target repository |
+| `GITHUB_CREDENTIALS_MISSING` | Missing env vars | Verify all three secrets/variables are set |
+| Wrong check selected in branch protection | Selected Actions check instead of App check | Choose the entry with the OMG App icon |

package/docs/install/github-app-required-checks.md

@@ -0,0 +1,107 @@
+# GitHub App Required Checks
+
+## Required Check Context Name
+
+The OMG PR Reviewer creates a check-run with a deterministic name:
+
+```
+OMG PR Reviewer
+```
+
+This name is the **context** string used for required status checks in branch protection rules.
+
+## Pinning Required Checks to `app_id`
+
+GitHub allows any integration or workflow to create a check-run with any name. To prevent spoofing of the `OMG PR Reviewer` check, pin the required check to the OMG GitHub App's `app_id` in your branch protection settings.
+
+### REST API (branch protection)
+
+```json
+PUT /repos/{owner}/{repo}/branches/{branch}/protection
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [],
+    "checks": [
+      {
+        "context": "OMG PR Reviewer",
+        "app_id": YOUR_OMG_APP_ID
+      }
+    ]
+  }
+}
+```
+
+When `app_id` is set, only check-runs created by that specific GitHub App are considered authoritative. A workflow or third-party App posting a check-run with the same name but a different `app_id` will not satisfy the requirement.
+
+> **Important**: The `app_id` field **must** be specified in the branch protection API call. Omitting it leaves the check unpinned.
+
+> **Warning**: Never leave required checks unpinned — any actor can spoof an unpinned check name. Always specify `app_id` to bind the check to the OMG GitHub App.
+
+### Repository Settings UI
+
+1. Go to **Settings > Branches > Branch protection rules**.
+2. Edit the rule for your default branch.
+3. Under **Require status checks to pass before merging**, search for `OMG PR Reviewer`.
+4. Select the entry that shows the OMG App icon (not the GitHub Actions icon).
+
+## Merge-Readiness Evaluation via `isRequired` GraphQL Field
+
+Do **not** rely on the raw `mergeable` field from the REST API to determine merge readiness. The `mergeable` field conflates merge conflict status with required-check status and can produce false positives.
+
+Instead, use the GraphQL `statusCheckRollup` with the `isRequired` field to query whether each required check has passed:
+
+```graphql
+query MergeReadiness($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              contexts(first: 50) {
+                nodes {
+                  ... on CheckRun {
+                    name
+                    conclusion
+                    isRequired(pullRequestNumber: $pr)
+                  }
+                  ... on StatusContext {
+                    context
+                    state
+                    isRequired(pullRequestNumber: $pr)
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The `isRequired` field returns `true` only for checks that are configured as required for the target branch. A PR is merge-ready when every context where `isRequired: true` also has `conclusion: "SUCCESS"` (for check-runs) or `state: "SUCCESS"` (for status contexts).
+
+## Split-Lane Security Model
+
+The OMG CI pipeline uses a split-lane model to isolate untrusted analysis from trusted posting:
+
+| Job | Permissions | Checkout | Purpose |
+|---|---|---|---|
+| `pr-analyze` | `contents: read` | PR head (default) | Runs analysis on PR code, produces review artifacts |
+| `post-review` | `contents: read`, `pull-requests: write`, `checks: write` | **Base SHA** (`github.event.pull_request.base.sha`) | Posts review and check-run using App credentials |
+
+The `post-review` job checks out the **base branch SHA**, not the PR head. This ensures the posting code is from the trusted base branch and cannot be tampered with by the PR author. App credentials (`OMG_APP_ID`, `OMG_APP_PRIVATE_KEY`, `OMG_APP_INSTALLATION_ID`) are only available in the trusted posting job.
+
+## Check-Run Conclusions
+
+The OMG PR Reviewer maps verdict statuses to GitHub check-run conclusions:
+
+| Verdict Status | GitHub Conclusion | PR UI Effect |
+|---|---|---|
+| `pass` | `success` | Green checkmark |
+| `fail` | `failure` | Red X |
+| `action_required` | `action_required` | "Take action" button |
+| `pending` | `neutral` | Grey dash |

package/docs/install/github-app.md

@@ -0,0 +1,161 @@
+# GitHub App Setup
+
+The PR Reviewer Bot uses a GitHub App to securely interact with your repositories. This method is preferred over personal access tokens as it provides fine-grained permissions and short-lived installation tokens.
+
+## Setup
+
+### 1. Create the GitHub App
+1. Navigate to **Settings** -> **Developer settings** -> **GitHub Apps** -> **New GitHub App**.
+2. **GitHub App name**: Choose a unique name (e.g., `OMG-Reviewer-Bot`).
+3. **Homepage URL**: Use your repository URL.
+4. **Webhook**: Uncheck **Active** unless you are using a custom webhook listener.
+5. **Permissions**: Grant the following minimum repository permissions:
+   - **Pull requests**: Read & write (to post reviews and comments)
+   - **Checks**: Read & write (to create check runs)
+   - **Contents**: Read-only (to analyze code)
+6. **Where can this GitHub App be installed?**: Select **Only on this account** or **Any account** based on your needs.
+7. Click **Create GitHub App**.
+
+### 2. Generate Private Key and Installation ID
+1. After creation, scroll down to the **Private keys** section and click **Generate a private key**. A `.pem` file will download.
+2. Note the **App ID** displayed at the top of the app settings page.
+3. Navigate to **Install App** in the sidebar and install it on your target repository or organization.
+4. After installation, the URL will look like `https://github.com/settings/installations/12345678`. The number at the end is your `GITHUB_INSTALLATION_ID`.
+
+### 3. Configure Environment Variables
+The bot requires three configuration variables.
+
+| Variable | Type | Description |
+| :--- | :--- | :--- |
+| `OMG_APP_ID` | Config Variable | The App ID from your GitHub App settings. |
+| `OMG_APP_PRIVATE_KEY` | Secret | The full content of the downloaded `.pem` file. |
+| `OMG_APP_INSTALLATION_ID` | Config Variable | The ID from the installation URL. |
+
+#### Local Development
+Store the private key in a file and load it:
+```bash
+export GITHUB_APP_ID="123456"
+export GITHUB_INSTALLATION_ID="78901234"
+export GITHUB_APP_PRIVATE_KEY="$(cat path/to/your-app.private-key.pem)"
+```
+
+#### GitHub Actions
+Add the App ID and Installation ID as **Variables** and the Private Key as a **Secret**.
+GitHub Actions forbids secret names starting with `GITHUB_`, so we use the `OMG_` prefix for stored values and map them to the `GITHUB_`-prefixed env vars the runtime expects:
+```yaml
+env:
+  GITHUB_APP_ID: ${{ vars.OMG_APP_ID }}
+  GITHUB_INSTALLATION_ID: ${{ vars.OMG_APP_INSTALLATION_ID }}
+  GITHUB_APP_PRIVATE_KEY: ${{ secrets.OMG_APP_PRIVATE_KEY }}
+```
+
+## Reusable Workflow
+
+OMG ships a reusable GitHub Actions workflow at `.github/workflows/evidence-gate.yml` that wraps the trusted PR review and check-run posting steps. Consumer repositories can call it from their own workflow instead of duplicating the posting logic:
+
+```yaml
+jobs:
+  evidence-gate:
+    uses: trac3r00/OMG/.github/workflows/evidence-gate.yml@main
+    with:
+      repo-full-name: ${{ github.repository }}
+      pr-number: ${{ github.event.pull_request.number }}
+      head-sha: ${{ github.event.pull_request.head.sha }}
+    secrets:
+      GITHUB_APP_ID: ${{ secrets.OMG_APP_ID }}
+      GITHUB_APP_PRIVATE_KEY: ${{ secrets.OMG_APP_PRIVATE_KEY }}
+      GITHUB_INSTALLATION_ID: ${{ secrets.OMG_APP_INSTALLATION_ID }}
+```
+
+The reusable workflow accepts three inputs (`repo-full-name`, `pr-number`, `head-sha`) and three secrets (`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_INSTALLATION_ID`). The caller is responsible for ensuring the checkout happens from the trusted base SHA — the reusable workflow itself only runs the posting step.
+
+> **Tip**: Pin the workflow reference to a specific commit SHA or tag rather than `@main` for production use: `uses: trac3r00/OMG/.github/workflows/evidence-gate.yml@<sha>`.
+
+## Pinning Required Checks by `app_id`
+
+GitHub allows any integration or workflow to create a check-run with any name. To prevent spoofing of the `OMG PR Reviewer` check, you **must** pin the required check to the OMG GitHub App's `app_id` in your branch protection settings.
+
+When using the REST API to configure branch protection, specify `app_id` in the `checks` array:
+
+```json
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [],
+    "checks": [
+      {
+        "context": "OMG PR Reviewer",
+        "app_id": YOUR_OMG_APP_ID
+      }
+    ]
+  }
+}
+```
+
+When `app_id` is set, only check-runs created by that specific GitHub App are considered authoritative. A workflow or third-party App posting a check-run with the same name but a different `app_id` will **not** satisfy the requirement.
+
+In the repository settings UI, select the entry showing the OMG App icon (not the GitHub Actions icon) when adding the required check.
+
+See [Required Checks Reference](github-app-required-checks.md) for the full API shape and GraphQL merge-readiness queries.
+
+## Stable Check Name
+
+The required-check name used by OMG is **immutable**:
+
+```
+OMG PR Reviewer
+```
+
+This value is baked into `action.yml` and the reusable workflow. It must never be
+renamed — branch protection rules, merge queues, and downstream integrations
+depend on this exact string. If you need to change how the check behaves, modify
+the review logic, not the name.
+
+> **New**: The root `action.yml` is now the recommended consumable entrypoint for
+> GitHub Actions integration. See [GitHub Action Setup](github-action.md) for the
+> turnkey guide.
+
+## Security Hardening
+
+### Secret Management
+- **GITHUB_APP_ID**: This is non-sensitive. Store it as a repository or organization configuration variable.
+- **GITHUB_APP_PRIVATE_KEY**: This is highly sensitive. Store it as an encrypted secret. Never commit this key to version control.
+- **Rotation**: Regularly rotate your private keys in the GitHub App settings and delete old, unused keys.
+
+### Execution Safety
+- **Untrusted PRs**: Never expose `GITHUB_APP_PRIVATE_KEY` to `pull_request` event jobs that check out untrusted code. Secrets are unavailable to forks by default, but you must ensure your workflow does not manually bypass this.
+- **Workflow Triggers**: Avoid using `pull_request_target` with an explicit checkout of the PR head if you are using app secrets. This combination can allow malicious PRs to exfiltrate your secrets.
+- **Token Expiry**: The bot caches installation access tokens in memory for the duration of their 1-hour TTL and regenerates automatically when they expire. Do not persist tokens to disk or share them across processes.
+
+## Verify
+
+Confirm your setup with this checklist:
+- [ ] **Token Generation**: Run the bot locally or in a test workflow. It should successfully exchange the JWT for an installation token.
+- [ ] **Review Posting**: Create a test PR. The bot should post a review or comment.
+- [ ] **Stale Review Dismissal**: Push a new commit to the test PR. The bot should dismiss or update its prior approval.
+- [ ] **Permissions**: Verify the bot can only access the repositories it was explicitly installed on.
+
+## Troubleshooting
+
+| Error Code | Cause | Resolution |
+| :--- | :--- | :--- |
+| `GITHUB_CREDENTIALS_MISSING` | One or more env vars are empty. | Check that `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, and `GITHUB_INSTALLATION_ID` are set. |
+| `GITHUB_APP_PRIVATE_KEY_INVALID` | The PEM key is malformed or not RSA. | Ensure the secret contains the full `<RSA PRIVATE KEY PEM HEADER>` block and no extra whitespace. |
+| `GITHUB_JWT_SIGNING_FAILED` | Cryptography error during signing. | Verify your environment has the required dependencies installed. |
+| `GITHUB_TOKEN_REQUEST_FAILED` | Network error or GitHub API downtime. | Check your internet connection and GitHub Status. |
+| `GITHUB_TOKEN_REQUEST_REJECTED` | 403/404 error from GitHub. | Verify the `GITHUB_INSTALLATION_ID` is correct and the app is installed on the repo. |
+| `GITHUB_TOKEN_RESPONSE_INVALID` | Unexpected response from GitHub. | Check if GitHub API versions have changed or if there is a proxy interference. |
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->

package/docs/install/kimi.md

@@ -0,0 +1,43 @@
+# Install OMG for Kimi CLI
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->
+
+<details><summary>Restricted environments / manual setup</summary>
+
+```bash
+git clone https://github.com/trac3r00/OMG
+cd OMG
+./OMG-setup.sh install --mode=omg-only --preset=interop
+```
+
+Optional browser capability:
+
+```bash
+./OMG-setup.sh install --mode=omg-only --preset=interop --enable-browser
+```
+
+</details>
+
+## Verify
+
+- `kimi mcp list` should include `omg-control`
+- `~/.kimi/mcp.json` should contain `mcpServers.omg-control`
+- the configured command should point at `~/.claude/omg-runtime/.venv/bin/python`
+- if browser capability is enabled, `~/.claude/omg-runtime/browser/capability.json` should exist
+
+## Notes
+
+- Kimi uses native MCP registration; it does not consume Claude `/OMG:*` slash commands
+- OMG support on Kimi is the shared runtime plus MCP control plane

package/docs/install/opencode.md

@@ -0,0 +1,38 @@
+# Install OMG for OpenCode
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->
+
+<details><summary>Restricted environments / manual setup</summary>
+
+```bash
+git clone https://github.com/trac3r00/OMG
+cd OMG
+./OMG-setup.sh install --mode=omg-only --preset=interop
+```
+
+</details>
+
+## Verify
+
+- OpenCode is supported as a compatibility host in v1 (not a canonical contract host)
+- global config path: `~/.config/opencode/opencode.json`
+- project config path: `opencode.json`
+- MCP entries use the `mcp` key (not `mcpServers`)
+- plugin discovery reads `.opencode/plugins/`
+
+## Notes
+
+- OpenCode consumes OMG through compatibility-host MCP registration
+- canonical v2.2.10 behavior-parity hosts are Claude Code, Codex, Gemini CLI, and Kimi CLI

package/docs/proof.md

@@ -0,0 +1,182 @@
+# OMG Proof Surface
+
+[![Compat Gate](https://github.com/trac3r00/OMG/actions/workflows/omg-compat-gate.yml/badge.svg)](https://github.com/trac3r00/OMG/actions/workflows/omg-compat-gate.yml)
+[![npm version](https://img.shields.io/npm/v/%40trac3r%2Foh-my-god)](https://www.npmjs.com/package/@trac3r/oh-my-god)
+
+## How to Read Your Proof
+
+<!-- OMG:GENERATED:proof-quickstart -->
+## Proof Quickstart
+
+```bash
+npx omg proof open --html
+npx omg blocked --last
+npx omg explain run --run-id <id>
+```
+
+Use the HTML view first, then inspect blockers or explain a specific run.
+<!-- /OMG:GENERATED:proof-quickstart -->
+
+OMG generates machine-backed evidence for every claim. Here is what the outputs mean.
+
+### Quick Verdict
+
+Run `npx omg proof open --html` to see a rendered summary, or `npx omg proof` for a terminal summary. The output tells you:
+
+- **Status**: `pass` or `fail` — whether all required evidence was produced and valid
+- **Blockers**: What failed and why, in plain language
+- **Evidence Coverage**: Which verification areas have evidence and which are missing
+
+### What "Pass" Means
+
+A passing proof means:
+1. All required evidence artifacts were generated and are fresh (not stale)
+2. The claim-judge verified every claim has backing evidence
+3. Test-intent-lock confirmed tests match stated intentions
+4. No governance blockers are active
+
+### What "Fail" Means
+
+A failing proof means one or more of:
+- Missing evidence artifacts (check `.omg/evidence/` for gaps)
+- Stale evidence (re-run the relevant workflow)
+- Claim without backing evidence (the claim-judge rejected a claim)
+- Active governance blockers (run `npx omg blocked --last` for details)
+
+### Common Commands
+
+| Goal | Command |
+|:-----|:--------|
+| See proof summary | `npx omg proof` |
+| Open HTML report | `npx omg proof open --html` |
+| See what is blocked | `npx omg blocked --last` |
+| Explain a specific run | `npx omg explain run --run-id <id>` |
+| Check budget usage | `npx omg budget simulate --enforce` |
+
+## Verification Status
+
+OMG keeps verification visible instead of burying it in implementation details.
+
+- Runtime evidence root: `.omg/evidence/`
+- Doctor output: `.omg/evidence/doctor.json`
+- Plugin diagnostics: `.omg/evidence/plugin-diagnostics.json` (via `diagnose-plugins`)
+- Security-check artifacts: `.omg/evidence/security-check-*.json`
+- Trust and external input artifacts: `.omg/evidence/trust-*.json`
+- Truth bundles:
+  - `claim-judge`: `.omg/evidence/claim-judge-*.json` (verifies claim-to-evidence mapping)
+  - `test-intent-lock`: `.omg/evidence/test-intent-lock-*.json` (verifies test-to-intent alignment)
+  - `proof-gate`: `.omg/evidence/proof-gate-*.json` (verifies final release readiness)
+- Release execution primitives required by `omg release readiness`:
+  - canonical evidence profile registry: `runtime.evidence_requirements.EVIDENCE_REQUIREMENTS_BY_PROFILE` (release-facing labels derive from this map)
+  - run coordinator state: `.omg/state/release_run_coordinator/<run_id>.json`
+  - TDD lock evidence: `.omg/state/test-intent-lock/*.json`
+  - rollback manifest: `.omg/state/rollback_manifest/*.json`
+  - session health: `.omg/state/session_health/<run_id>.json`
+  - council verdicts: `.omg/state/council_verdicts/<run_id>.json`
+  - Forge starter proof (`proof_backed: true`): `.omg/evidence/forge-specialists-*.json`
+  - exec kernel state: `.omg/state/exec-kernel/<run_id>.json`
+  - worker watchdog replay: `.omg/evidence/subagents/<run_id>-replay.json`
+  - merge writer provenance: `.omg/evidence/merge-writer-<run_id>.json`
+  - tool fabric ledger: `.omg/state/ledger/tool-ledger.jsonl`
+  - budget envelope state: `.omg/state/budget-envelopes/<run_id>.json`
+  - issue report: `.omg/evidence/issues/<run_id>.json`
+  - host parity report: `.omg/evidence/host-parity-<run_id>.json`
+  - music OMR testbed evidence: `.omg/evidence/music-omr-<run_id>.json`
+
+## Certification Lanes
+
+OMG proof is multi-lane. Each lane binds a user-facing claim to a freshness policy,
+required evidence, and a release-facing verdict. Music OMR is Lane 1 and the
+permanent flagship gate because it is the hardest continuously enforced daily
+testbed in the system: real-time optical music recognition, transcription
+accuracy, and live transposition under production-style constraints.
+
+- Lane 1 / flagship: Music OMR daily gate for deterministic score parsing and live transposition
+- Planned lane: install/apply correctness for launcher previews versus applied mutations
+- Planned lane: uninstall cleanliness for rollback and host cleanup guarantees
+- Planned lane: host parity for canonical provider behavior normalization
+- Planned lane: trust-chain verification for signed approvals, ledgering, and provenance
+- Planned lane: proof-surface integrity for generated docs, artifacts, and release surfaces
+
+## Permanent Music OMR Daily Gate
+
+Music OMR is the permanent daily release gate artifact. Release readiness requires a fresh Music OMR evidence file tied to the active run id.
+
+- Gate cadence: daily scheduled run via `.github/workflows/omg-release-readiness.yml`
+- Run scope: `run_id` must match the active release evidence pack run
+- Freshness metadata: `freshness.generated_at`, `freshness.max_age_seconds`, `freshness.expires_at`, `freshness.is_fresh`
+- Fixture inventory: `fixture_inventory` must include deterministic fixture ids (for this gate: `simple_c_major.json`, `simple_g_major.json`, `chromatic_fragment.json`, `waltz_three_four.json`, `transposition_pressure_fixture.json`); minimum 5 fixtures required (`fixture_inventory_valid` must be `true`)
+- Trace metadata: `trace.trace_id`, `trace.gate=music-omr-daily`, `trace.run_scope=release-run`, `trace_metadata.testbed`, `trace_metadata.fixture_count`, `trace_metadata.run_id_linkage`
+- Freshness threshold: `freshness_threshold_secs`, `freshness.freshness_threshold_secs`
+- Run linkage: `run_id` must match the active release run, `trace_metadata.run_id_linkage` must equal `run_id`
+
+### What This Means
+
+The Music OMR daily gate ensures the OMR (Optical Music Recognition) engine produces correct, deterministic results. If the gate passes, the transposition and score-parsing logic is verified against known fixtures. If it fails, check the `freshness` and `fixture_inventory_valid` fields in the evidence JSON for the specific failure reason.
+
+## Forge v0.3 Evidence
+
+Forge v0.3 introduces richer evidence artifacts for domain-specific training and evaluation.
+
+- Forge starter proof: `.omg/evidence/forge-specialists-{run_id}.json`
+- Artifact contracts schema:
+  - `dataset_lineage`: provenance for training data
+  - `model_card`: model metadata and intended use
+  - `checkpoint_hash`: integrity for model weights
+  - `regression_scoreboard`: evaluation results vs baselines
+  - `promotion_decision`: automated or human-in-the-loop release signal
+- Domain pack enforcement: Forge ensures that domain-specific constraints (e.g., robotics safety, algorithm determinism) are satisfied before emitting a release-ready claim.
+
+- Release readiness machine output includes `checks.execution_primitives` with `missing`, `invalid`, and `evidence_paths`
+- Browser evidence: `.omg/evidence/browser-*.png` and `.omg/evidence/browser-*.json` (Playwright-backed verification)
+- Canonical browser command: `/OMG:browser` with `/OMG:playwright` as a compatibility alias
+- Trace records and evidence links: `.omg/tracebank/events.jsonl`, `.omg/tracebank/evidence-links.jsonl`
+- Eval gate artifacts and trace links: `.omg/evals/latest.json`, `.omg/evals/history.jsonl`, `.omg/evals/trace-links.jsonl`
+- Lineage manifests: `.omg/lineage/*.json`
+- Release readiness output links these machine artifacts instead of prose-only pass counts.
+
+## Provider Matrix
+
+| Provider | Tier | Detect | Auth Check | MCP Config | Host Priority |
+|----------|------|--------|------------|------------|---------------|
+| Claude Code | Canonical | host-native | host-native | yes | primary |
+| Codex | Canonical | yes | yes | yes | primary |
+| Gemini | Canonical | yes | yes | yes | primary |
+| Kimi | Canonical | yes | yes | yes | primary |
+| OpenCode | Compatibility-only | yes | yes | yes | supported |
+
+## Adoption Evidence
+
+- Native setup writes `.omg/state/adoption-report.json`
+- Native setup writes `.omg/state/cli-config.yaml`
+- Plugin allowlist: `.omg/state/plugins-allowlist.yaml`
+- `OMG-only` and `coexist` are both covered in setup tests
+- Canonical modes: `chill`, `focused`, `exploratory`
+- OMC, OMX, and Superpowers references stay limited to compatibility and adoption guidance
+
+## HUD Artifact
+
+![OMG HUD](assets/omg-hud.svg)
+
+## Benchmark Tasks
+
+Representative benchmark tasks for this release:
+
+- host detection and auth wiring
+- canonical security-check routing and evidence emission
+- narrowed stdio OMG control MCP wiring
+- truth bundle verification (claim-judge, test-intent-lock, proof-gate)
+- plan-council role compilation and execution
+- adoption detection with overlapping ecosystems
+- plugin install and uninstall correctness
+- `crazy` orchestration smoke coverage
+
+## Sample Transcripts
+
+- Setup: [docs/transcripts/setup.md](transcripts/setup.md)
+- Crazy: [docs/transcripts/crazy.md](transcripts/crazy.md)
+
+## Release Discipline
+
+- Public launch checklist: [docs/release-checklist.md](release-checklist.md)
+- Changelog: [CHANGELOG.md](../CHANGELOG.md)