oh-my-openagent 5.0.0-beta.7 → 5.0.0-beta.71

package/.agents/command/publish.md

@@ -1,6 +1,6 @@
 ---
 description: Publish oh-my-opencode to npm via GitHub Actions workflow
-argument-hint: <patch|minor|major>
+argument-hint: <patch|minor|major|explicit-semver>
 ---
 
 
@@ -54,15 +54,16 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ## CRITICAL: ARGUMENT REQUIREMENT
 
-**You MUST receive a version bump type from the user.** Valid options:
+**You MUST receive one release selector from the user.** Valid options:
 - `patch`: Bug fixes, backward-compatible (1.1.7 → 1.1.8)
 - `minor`: New features, backward-compatible (1.1.7 → 1.2.0)
 - `major`: Breaking changes (1.1.7 → 2.0.0)
+- An explicit valid semantic version, including a prerelease such as `5.0.0-beta.9`
 
-**If the user did not provide a bump type argument, STOP IMMEDIATELY and ask:**
-> "To proceed with deployment, please specify a version bump type: `patch`, `minor`, or `major`"
+**If the user did not provide a release selector, STOP IMMEDIATELY and ask:**
+> "To proceed with deployment, specify `patch`, `minor`, `major`, or an explicit semantic version such as `5.0.0-beta.9`."
 
-**DO NOT PROCEED without explicit user confirmation of bump type.**
+Reject any other value. Do not infer or repair malformed versions.
 
 ---
 
@@ -72,7 +73,7 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ```
 [
-  { "id": "confirm-bump", "content": "Confirm version bump type with user (patch/minor/major)", "status": "in_progress", "priority": "high" },
+  { "id": "confirm-release-input", "content": "Confirm release selector with user (patch/minor/major or explicit semver)", "status": "in_progress", "priority": "high" },
   { "id": "check-uncommitted", "content": "Check for uncommitted changes and commit if needed", "status": "pending", "priority": "high" },
   { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
   { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
@@ -92,9 +93,23 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ---
 
-## STEP 1: CONFIRM BUMP TYPE
+## STEP 1: CONFIRM AND CLASSIFY THE RELEASE SELECTOR
 
-If the user already named a bump type (argument or message), that IS the confirmation — state it and continue immediately. Only ask and wait when no bump type was given.
+If the user already supplied the selector in the command argument or message, that IS the confirmation. Parse it exactly once:
+
+```bash
+RELEASE_INPUT="${ARGUMENTS}"
+if [[ "$RELEASE_INPUT" =~ ^(patch|minor|major)$ ]]; then
+  RELEASE_KIND=bump
+elif [[ "$RELEASE_INPUT" =~ ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$ ]]; then
+  RELEASE_KIND=version
+else
+  echo "Invalid release selector: $RELEASE_INPUT" >&2
+  exit 1
+fi
+```
+
+Only ask and wait when no selector was provided.
 
 ---
 
@@ -125,16 +140,29 @@ This ensures the GitHub Actions workflow runs on the latest code including all l
 
 ## STEP 3: TRIGGER GITHUB ACTIONS WORKFLOW
 
-Run the publish workflow:
-```bash
-gh workflow run publish -f bump={bump_type}
-```
+Dispatch from `dev`, pass bump selectors through `bump`, and pass exact versions through `version`. The required `bump` input remains `patch` for explicit-version dispatches but is ignored by the workflow because `version` takes precedence.
 
-Wait 3 seconds, then get the run ID:
 ```bash
-gh run list --workflow=publish --limit=1 --json databaseId,status --jq '.[0]'
+if [ "$RELEASE_KIND" = bump ]; then
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f "bump=${RELEASE_INPUT}")"
+else
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f bump=patch -f "version=${RELEASE_INPUT}")"
+fi
+
+if ! [[ "$RUN_URL" =~ ^https://github.com/code-yeongyu/oh-my-openagent/actions/runs/[0-9]+$ ]]; then
+  echo "Publish dispatch did not return an exact workflow run URL: $RUN_URL" >&2
+  exit 1
+fi
+RUN_ID="${RUN_URL##*/}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "Publish dispatch returned an invalid run ID: $RUN_ID" >&2
+  exit 1
+fi
+gh run view "${RUN_ID}" --json databaseId,status,url --jq '{databaseId,status,url}'
 ```
 
+The returned run ID owns this release attempt. Never replace it with a latest-run lookup.
+
 ---
 
 ## STEP 4: WAIT FOR WORKFLOW COMPLETION
@@ -150,14 +178,14 @@ The publish run is a single workflow with sequential stages. Expected timeline (
 
 Poll job-level status every 30 seconds and report stage transitions to the user:
 ```bash
-gh run view {run_id} --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
+gh run view "${RUN_ID}" --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
 ```
 
 **IMPORTANT: Use polling loop, NOT sleep commands.** Use the waiting time to draft the enhanced release summary (Step 6) — do not sit idle, and do not start any review activity.
 
 If conclusion is `failure`, show error and stop:
 ```bash
-gh run view {run_id} --log-failed
+gh run view "${RUN_ID}" --log-failed
 ```
 
 ---
@@ -175,22 +203,30 @@ NEW_VERSION=$(node -p "require('./package.json').version")
 gh release view "v${NEW_VERSION}" --json tagName,url --jq '{tag: .tagName, url: .url}'
 ```
 
-**After verifying, generate a local preview of the auto-generated content:**
+**Release notes are written BEFORE the release, not after.**
+
+The release body is extracted from the `CHANGELOG.md` section for this version. Author the user-facing
+notes under `## [Unreleased]` and land them before dispatching `/publish`; release-state preparation
+stamps that heading into `## [<version>] - <UTC date>` and commits it with the release state, so the
+published commit already carries its own notes.
+
+Preview exactly what the release body will be:
 
 ```bash
-bun run script/generate-changelog.ts
+bun run script/generate-changelog.ts > /tmp/contributors.md
+bun run script/print-release-notes.ts "${NEW_VERSION}" /tmp/contributors.md
 ```
 
 <agent-instruction>
 After running the preview, present the output to the user and say:
 
-> **The following content is ALREADY included in the release automatically:**
-> - Commit changelog (grouped by feat/fix/refactor)
-> - Contributor thank-you messages (for non-team contributors)
+> **This is the exact body the release will publish:** the notes you authored under `[Unreleased]`,
+> then contributor thank-yous for non-team contributors, then the install footer.
 >
-> You do NOT need to write any of this. It's handled.
+> Both steps are fail-closed: an absent, empty, or duplicated section aborts the release instead of
+> publishing blank notes, and re-stamping a version that already has a section is refused.
 >
-> **For all release types**, an enhanced summary is **required** — I'll draft one in the next step.
+> If the `[Unreleased]` section is empty, STOP and write the notes first — the release cannot proceed.
 
 **APPROVAL GATE (single, binary):** The user's initial publish request with a named bump type IS the only approval this workflow requires. Do NOT wait for a separate acknowledgement here. Present the preview, then IMMEDIATELY proceed to Step 6. The only exception: if the user explicitly said "let me review the changelog before you continue" (or equivalent), stop and wait. Otherwise continue without ending the turn.
 </agent-instruction>

package/.agents/skills/codex-qa/scripts/lsp-e2e.sh

@@ -1752,7 +1752,7 @@ rewrite_codex_mcp_config() {
 import { readFileSync, writeFileSync } from "node:fs";
 const path = process.argv[2];
 let text = readFileSync(path, "utf8");
-for (const name of ["context7", "codegraph"]) {
+for (const name of ["context7"]) {
   const header = `[plugins."omo@sisyphuslabs".mcp_servers.${name}]`;
   const start = text.indexOf(header);
   if (start < 0) throw new Error(`missing ${header}`);
@@ -1790,7 +1790,6 @@ const path = process.argv[2];
 const disabled = new Set([
   "session-start-checking-auto-update.json",
   "session-start-checking-bootstrap-provisioning.json",
-  "session-start-checking-codegraph-bootstrap.json",
 ]);
 const manifest = JSON.parse(readFileSync(path, "utf8"));
 if (!Array.isArray(manifest.hooks)) throw new Error("installed plugin hook list is missing");
@@ -2635,7 +2634,6 @@ const result = {
   disabledSideEffectHooks: [
     "session-start-checking-auto-update.json",
     "session-start-checking-bootstrap-provisioning.json",
-    "session-start-checking-codegraph-bootstrap.json",
   ],
   hookStarted: app.hookStarted === true,
   hookCompleted: app.hookCompleted === true,

package/.agents/skills/opencode-qa/scripts/lsp-e2e.sh

@@ -1485,7 +1485,7 @@ const opencode = {
   permission: permissions,
 };
 const omo = {
-  disabled_mcps: ["websearch", "context7", "grep_app", "codegraph"],
+  disabled_mcps: ["websearch", "context7", "grep_app"],
   disabled_hooks: ["auto-update-checker"],
 };
 writeFileSync(opencodePath, `${JSON.stringify(opencode, null, 2)}\n`);

package/.agents/skills/pre-publish-review/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: pre-publish-review
-description: "Nuclear-grade 16-agent pre-publish release gate. Runs /get-unpublished-changes to detect all changes since last npm release, spawns up to 10 ultrabrain agents for deep per-change analysis, invokes /review-work (5 agents) for holistic review, and 1 oracle for overall release synthesis. Runs ONLY when the user explicitly asks for a pre-publish review — a plain publish/release request MUST NOT trigger this; /publish ships directly. Triggers: 'pre-publish review', 'review before publish', 'release review', 'pre-release review', 'ready to publish?', 'can I publish?', 'pre-publish', 'safe to publish', 'publishing review', 'pre-publish check'."
+description: "Nuclear-grade 12-agent pre-publish release gate. Runs /get-unpublished-changes to detect all changes since last npm release, spawns up to 10 ultrabrain agents for deep per-change analysis, invokes /review-work (orchestrator manual QA plus one gate reviewer) for holistic review, and 1 oracle for overall release synthesis. Runs ONLY when the user explicitly asks for a pre-publish review — a plain publish/release request MUST NOT trigger this; /publish ships directly. Triggers: 'pre-publish review', 'review before publish', 'release review', 'pre-release review', 'ready to publish?', 'can I publish?', 'pre-publish', 'safe to publish', 'publishing review', 'pre-publish check'."
 ---
 
-# Pre-Publish Review — 16-Agent Release Gate
+# Pre-Publish Review — 12-Agent Release Gate
 
 Three-agent-layer review before publishing to npm. Every layer covers a different angle, and every result is mapped onto the release layers below.
 
 | Layer | Agents | Type | What They Check |
 |-------|--------|------|-----------------|
 | Per-Change Deep Dive | up to 10 | ultrabrain | Each logical change group individually — correctness, edge cases, pattern adherence |
-| Holistic Review | 5 | review-work | Goal compliance, QA execution, code quality, security, context mining across full changeset |
+| Holistic Review | 1 (+ orchestrator QA) | review-work | Manual QA by the review orchestrator, then one gate reviewer covering goal compliance, code quality, security, and missed context across the full changeset |
 | Release Synthesis | 1 | oracle | Overall release readiness, version bump, breaking changes, deployment risk |
 
 ## Release Layer Taxonomy
@@ -159,9 +159,9 @@ OUTPUT FORMAT:
 """)
 ```
 
-### Layer 2: Holistic Review via /review-work (5 agents)
+### Layer 2: Holistic Review via /review-work (one gate reviewer)
 
-Spawn a sub-agent that loads the `/review-work` skill. The review-work skill internally launches 5 parallel agents: Oracle (goal verification), unspecified-high (QA execution), Oracle (code quality), Oracle (security), unspecified-high (context mining). All 5 must pass for the review to pass.
+Spawn a sub-agent that loads the `/review-work` skill. The review-work skill runs manual QA on the real surface itself, then launches ONE gate reviewer (oracle) that audits goal compliance, code quality, security, missed context, and the QA evidence. The review passes only on a clean QA matrix plus APPROVE.
 
 ```
 task(
@@ -186,7 +186,7 @@ BACKGROUND: Pre-publish review of oh-my-opencode, an OpenCode plugin with 1268 T
 
 The diff base is: git diff v{PUBLISHED}..HEAD
 
-Follow the /review-work skill flow exactly — launch all 5 review agents and collect results. Do NOT skip any of the 5 agents.
+Follow the /review-work skill flow exactly — run the manual QA phase, launch the gate reviewer, and collect its verdict. Do NOT skip the QA phase or the reviewer.
 """)
 ```
 
@@ -228,7 +228,7 @@ task(
 {Read and include full content of KEY changed files — focus on public API surfaces, config schemas, agent definitions, hook registrations, tool registrations}
 </file_contents>
 
-You are the final gate before an npm publish. 10 ultrabrain agents are reviewing individual changes and 5 review-work agents are doing holistic review. Your job is the bird's-eye view that those focused reviews might miss.
+You are the final gate before an npm publish. 10 ultrabrain agents are reviewing individual changes and the review-work gate reviewer is doing the holistic review. Your job is the bird's-eye view that those focused reviews might miss.
 
 SYNTHESIS CHECKLIST:
 
@@ -378,11 +378,8 @@ Compile the final report:
 
 | # | Review Area | Verdict | Confidence |
 |---|------------|---------|------------|
-| 1 | Goal & Constraint Verification | PASS/FAIL | HIGH/MED/LOW |
-| 2 | QA Execution | PASS/FAIL | HIGH/MED/LOW |
-| 3 | Code Quality | PASS/FAIL | HIGH/MED/LOW |
-| 4 | Security | PASS/FAIL | Severity |
-| 5 | Context Mining | PASS/FAIL | HIGH/MED/LOW |
+| 1 | Manual QA (orchestrator, real surface) | PASS/FAIL | - |
+| 2 | Gate Review (goal, code quality, security, context, QA audit) | APPROVE/REJECT | HIGH/MED/LOW |
 
 ### Blocking Issues from Holistic Review
 {Aggregated from review-work}

package/.agents/skills/publish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: publish
-description: "Publish oh-my-opencode to npm by triggering the GitHub Actions publish workflow and verifying its artifacts. Ship-only: never runs pre-publish-review or re-reviews merged code unless the user explicitly asks. Argument: <patch|minor|major>. Triggers: publish, release, deploy, npm publish."
+description: "Publish oh-my-opencode to npm by triggering the GitHub Actions publish workflow and verifying its artifacts. Ship-only: never runs pre-publish-review or re-reviews merged code unless the user explicitly asks. Argument: <patch|minor|major|explicit-semver>. Triggers: publish, release, deploy, npm publish."
 ---
 
 You are the release manager for oh-my-opencode. Execute the FULL publish workflow from start to finish.
@@ -53,15 +53,16 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ## CRITICAL: ARGUMENT REQUIREMENT
 
-**You MUST receive a version bump type from the user.** Valid options:
+**You MUST receive one release selector from the user.** Valid options:
 - `patch`: Bug fixes, backward-compatible (1.1.7 → 1.1.8)
 - `minor`: New features, backward-compatible (1.1.7 → 1.2.0)
 - `major`: Breaking changes (1.1.7 → 2.0.0)
+- An explicit valid semantic version, including a prerelease such as `5.0.0-beta.9`
 
-**If the user did not provide a bump type argument, STOP IMMEDIATELY and ask:**
-> "To proceed with deployment, please specify a version bump type: `patch`, `minor`, or `major`"
+**If the user did not provide a release selector, STOP IMMEDIATELY and ask:**
+> "To proceed with deployment, specify `patch`, `minor`, `major`, or an explicit semantic version such as `5.0.0-beta.9`."
 
-**DO NOT PROCEED without explicit user confirmation of bump type.**
+Reject any other value. Do not infer or repair malformed versions.
 
 ---
 
@@ -71,7 +72,7 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ```
 [
-  { "id": "confirm-bump", "content": "Confirm version bump type with user (patch/minor/major)", "status": "in_progress", "priority": "high" },
+  { "id": "confirm-release-input", "content": "Confirm release selector with user (patch/minor/major or explicit semver)", "status": "in_progress", "priority": "high" },
   { "id": "check-uncommitted", "content": "Check for uncommitted changes and commit if needed", "status": "pending", "priority": "high" },
   { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
   { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
@@ -91,9 +92,23 @@ This contract applies to the slash-command copies (`.agents/command/publish.md`,
 
 ---
 
-## STEP 1: CONFIRM BUMP TYPE
+## STEP 1: CONFIRM AND CLASSIFY THE RELEASE SELECTOR
 
-If the user already named a bump type (argument or message), that IS the confirmation — state it and continue immediately. Only ask and wait when no bump type was given.
+If the user already supplied the selector in the command argument or message, that IS the confirmation. Parse it exactly once:
+
+```bash
+RELEASE_INPUT="${ARGUMENTS}"
+if [[ "$RELEASE_INPUT" =~ ^(patch|minor|major)$ ]]; then
+  RELEASE_KIND=bump
+elif [[ "$RELEASE_INPUT" =~ ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+(\.[0-9A-Za-z]+)*)?$ ]]; then
+  RELEASE_KIND=version
+else
+  echo "Invalid release selector: $RELEASE_INPUT" >&2
+  exit 1
+fi
+```
+
+Only ask and wait when no selector was provided.
 
 ---
 
@@ -124,16 +139,29 @@ This ensures the GitHub Actions workflow runs on the latest code including all l
 
 ## STEP 3: TRIGGER GITHUB ACTIONS WORKFLOW
 
-Run the publish workflow:
-```bash
-gh workflow run publish -f bump={bump_type}
-```
+Dispatch from `dev`, pass bump selectors through `bump`, and pass exact versions through `version`. The required `bump` input remains `patch` for explicit-version dispatches but is ignored by the workflow because `version` takes precedence.
 
-Wait 3 seconds, then get the run ID:
 ```bash
-gh run list --workflow=publish --limit=1 --json databaseId,status --jq '.[0]'
+if [ "$RELEASE_KIND" = bump ]; then
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f "bump=${RELEASE_INPUT}")"
+else
+  RUN_URL="$(gh workflow run publish.yml --ref dev -f bump=patch -f "version=${RELEASE_INPUT}")"
+fi
+
+if ! [[ "$RUN_URL" =~ ^https://github.com/code-yeongyu/oh-my-openagent/actions/runs/[0-9]+$ ]]; then
+  echo "Publish dispatch did not return an exact workflow run URL: $RUN_URL" >&2
+  exit 1
+fi
+RUN_ID="${RUN_URL##*/}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "Publish dispatch returned an invalid run ID: $RUN_ID" >&2
+  exit 1
+fi
+gh run view "${RUN_ID}" --json databaseId,status,url --jq '{databaseId,status,url}'
 ```
 
+The returned run ID owns this release attempt. Never replace it with a latest-run lookup.
+
 ---
 
 ## STEP 4: WAIT FOR WORKFLOW COMPLETION
@@ -149,14 +177,14 @@ The publish run is a single workflow with sequential stages. Expected timeline (
 
 Poll job-level status every 30 seconds and report stage transitions to the user:
 ```bash
-gh run view {run_id} --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
+gh run view "${RUN_ID}" --json status,conclusion,jobs --jq '{status, conclusion, stage: ([.jobs[] | select(.status=="in_progress") | .name] | join(", "))}'
 ```
 
 **IMPORTANT: Use polling loop, NOT sleep commands.** Use the waiting time to draft the enhanced release summary (Step 6) — do not sit idle, and do not start any review activity.
 
 If conclusion is `failure`, show error and stop:
 ```bash
-gh run view {run_id} --log-failed
+gh run view "${RUN_ID}" --log-failed
 ```
 
 ---
@@ -174,22 +202,30 @@ NEW_VERSION=$(node -p "require('./package.json').version")
 gh release view "v${NEW_VERSION}" --json tagName,url --jq '{tag: .tagName, url: .url}'
 ```
 
-**After verifying, generate a local preview of the auto-generated content:**
+**Release notes are written BEFORE the release, not after.**
+
+The release body is extracted from the `CHANGELOG.md` section for this version. Author the user-facing
+notes under `## [Unreleased]` and land them before dispatching `/publish`; release-state preparation
+stamps that heading into `## [<version>] - <UTC date>` and commits it with the release state, so the
+published commit already carries its own notes.
+
+Preview exactly what the release body will be:
 
 ```bash
-bun run script/generate-changelog.ts
+bun run script/generate-changelog.ts > /tmp/contributors.md
+bun run script/print-release-notes.ts "${NEW_VERSION}" /tmp/contributors.md
 ```
 
 <agent-instruction>
 After running the preview, present the output to the user and say:
 
-> **The following content is ALREADY included in the release automatically:**
-> - Commit changelog (grouped by feat/fix/refactor)
-> - Contributor thank-you messages (for non-team contributors)
+> **This is the exact body the release will publish:** the notes you authored under `[Unreleased]`,
+> then contributor thank-yous for non-team contributors, then the install footer.
 >
-> You do NOT need to write any of this. It's handled.
+> Both steps are fail-closed: an absent, empty, or duplicated section aborts the release instead of
+> publishing blank notes, and re-stamping a version that already has a section is refused.
 >
-> **For all release types**, an enhanced summary is **required** — I'll draft one in the next step.
+> If the `[Unreleased]` section is empty, STOP and write the notes first — the release cannot proceed.
 
 **APPROVAL GATE (single, binary):** The user's initial publish request with a named bump type IS the only approval this workflow requires. Do NOT wait for a separate acknowledgement here. Present the preview, then IMMEDIATELY proceed to Step 6. The only exception: if the user explicitly said "let me review the changelog before you continue" (or equivalent), stop and wait. Otherwise continue without ending the turn.
 </agent-instruction>

package/.agents/skills/senpi-qa/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: senpi-qa
+description: "QA the omo Senpi adapter (packages/omo-senpi, packages/senpi-task) against the REAL senpi binary in strict isolation, and write every artifact to the one canonical evidence path .omo/evidence/omo-senpi-adapter/<slug>/. The live drivers under packages/omo-senpi/scripts/qa/ create their own isolated SENPI_CODING_AGENT_DIR and ignore the caller's, so the real ~/.senpi/agent is never written. Ships scripts/resolve-evidence-dir.mjs, which is the ONLY sanctioned way to pick an evidence directory: it rejects traversal, separators, absolute paths, and stray roots such as local-ignore/qa-evidence. Use whenever someone changes anything under packages/omo-senpi or packages/senpi-task, or wants to QA, smoke-test, verify, or debug the Senpi adapter, the task/team engine, the DAG, task RPC, or skill delivery. Triggers: senpi qa, qa senpi, senpi-qa, test senpi adapter, verify senpi task, senpi task e2e, senpi team e2e, task dag qa, live senpi driver, senpi evidence path."
+---
+
+# Senpi QA
+
+QA the omo Senpi adapter (`packages/omo-senpi/`) and the task engine
+(`packages/senpi-task/`) by driving the REAL `senpi` binary. Unit tests never
+count as live QA here: `bun run test:senpi` is the package gate, the drivers in
+`packages/omo-senpi/scripts/qa/` are the harness proof.
+
+## Golden rules
+
+- **Evidence lives at exactly one path.** Every artifact goes under
+  `.omo/evidence/omo-senpi-adapter/<slug>/`. Pick it with
+  `scripts/resolve-evidence-dir.mjs` and nothing else — a hand-typed path is how
+  runs end up somewhere like `local-ignore/qa-evidence/`, which no reviewer reads
+  and the PR cannot cite.
+- **The real agent dir stays untouched.** The live drivers build their own
+  isolated `SENPI_CODING_AGENT_DIR` and deliberately IGNORE a caller-provided
+  one, so `~/.senpi/agent` is never used as the sandbox. Report the driver's
+  `realSenpiUntouched` / changed-path fields and the isolated agent-dir path;
+  treat a whole-directory digest as supporting evidence, not proof by itself.
+- **No binary means SKIP, not silence.** When `senpi` is absent the live drivers
+  report `SKIP` or `FAIL` in their final JSON rather than degrading to the real
+  home. A `SKIP` is not a pass — say so in the evidence README.
+- **The captured JSON is the evidence.** No file on disk means the QA did not
+  happen, which means no commit and no push.
+
+## Resolve the evidence directory first
+
+```bash
+ev="$(node .agents/skills/senpi-qa/scripts/resolve-evidence-dir.mjs \
+  --repo-root "$(git rev-parse --show-toplevel)" --slug <YYYYMMDD>-<short-slug>)"
+mkdir -p "$ev"
+```
+
+The resolver returns an absolute path and creates nothing, so the caller decides
+when the directory appears. A slug is ONE relative segment of lowercase letters,
+digits, and hyphens (`20260820-senpi-qa-contract`). Separators, `.`/`..`,
+traversal, absolute paths, and a non-git root are rejected with a non-zero exit
+and a message naming the offending slug.
+
+## Router: pick your case
+
+| You changed… | Run | Proves |
+|---|---|---|
+| Any adapter code, as the fast precondition | `node packages/omo-senpi/scripts/qa/drive.mjs --self-test` | the driver + isolation harness itself works |
+| Adapter wiring reaching a live session | `node packages/omo-senpi/scripts/qa/drive.mjs` | a real senpi run with the plugin loaded, isolated agent dir, and no attributed real-home changes |
+| Task lifecycle (single + batch) | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/task-e2e.mjs` | live task start/stream/terminal states |
+| Team delivery, shutdown, reclaim, restart recovery | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/team-e2e.mjs` | injection delivery and exactly-once recovery |
+| Task RPC driver scripts | `node packages/omo-senpi/scripts/qa/task-rpc-e2e.mjs --self-test` | the RPC surface contract |
+| Skill delivery into a task | `SENPI_BIN="$(command -v senpi)" node packages/omo-senpi/scripts/qa/task-load-skills-e2e.mjs` | skills reach the child |
+| Continuation behavior | `node packages/omo-senpi/scripts/qa/probe-continuation.mjs` | turns continue as expected |
+| DAG state machine / runners | `bun test packages/senpi-task` | unit + chaos invariants (NOT live proof) |
+
+Point a driver's output at the resolved directory, e.g.:
+
+```bash
+TASK_E2E_OUT_DIR="$ev/live-task-dag" SENPI_BIN="$(command -v senpi)" \
+  node packages/omo-senpi/scripts/qa/task-e2e.mjs
+```
+
+## Package gate
+
+```bash
+tsgo --noEmit -p packages/omo-senpi/tsconfig.json
+bun run test:senpi
+```
+
+## Write the evidence README
+
+Every run leaves `$ev/README.md` a reviewer can read without rerunning anything.
+The required sections are the repo-wide evidence rules in the root
+[`AGENTS.md`](../../../AGENTS.md) (what was tested / observed / why it is enough /
+what was omitted). For Senpi, record the driver's changed-path/isolation fields
+and sandbox agent-dir path. Some drivers report sandbox paths without removing
+them; the caller must delete every task-owned sandbox and verify child PIDs are
+terminal before writing the cleanup receipt.

package/.agents/skills/senpi-qa/scripts/resolve-evidence-dir.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// resolve-evidence-dir.mjs - pick the canonical evidence directory for a live Senpi QA run.
+//
+// Live Senpi QA artifacts belong under .omo/evidence/omo-senpi-adapter/<slug>/ and nowhere else.
+// That path is the repository-standard location every reviewer and AGENTS.md rule points at, so a
+// hand-typed alternative (local-ignore/qa-evidence/..., a temp dir, a traversal) silently strands
+// the evidence where the PR cannot cite it. Resolving through this script makes the path a checked
+// contract instead of a convention.
+//
+// The resolver COMPUTES and VALIDATES only; creating the directory stays the caller's decision, so
+// a rejected slug never leaves a stray directory behind.
+//
+//   node resolve-evidence-dir.mjs --repo-root "$(git rev-parse --show-toplevel)" --slug 20260820-my-run
+//
+// Prints the absolute path to stdout. Exit 0 iff the root is a git worktree and the slug is safe.
+import { existsSync, realpathSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const EVIDENCE_RELATIVE_ROOT = join(".omo", "evidence", "omo-senpi-adapter")
+
+// One relative segment: lowercase alphanumerics joined by single hyphens. This is what makes the
+// path predictable - it also rejects every separator, traversal, and absolute form outright, since
+// none of them can match.
+const SAFE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/**
+ * @param {{ repoRoot: string, slug: string }} input
+ * @returns {string} absolute evidence directory; NOT created
+ */
+export function resolveEvidenceDir({ repoRoot, slug }) {
+  if (typeof repoRoot !== "string" || repoRoot.length === 0) {
+    throw new Error("repoRoot must be a non-empty path to a git worktree")
+  }
+  if (!existsSync(join(repoRoot, ".git"))) {
+    throw new Error(`repoRoot is not a git worktree: ${repoRoot}`)
+  }
+  if (typeof slug !== "string" || !SAFE_SLUG.test(slug)) {
+    throw new Error(
+      `slug must be one lowercase alphanumeric-and-hyphen segment (got ${JSON.stringify(slug)}); ` +
+        `evidence lives under ${EVIDENCE_RELATIVE_ROOT}/<slug>`,
+    )
+  }
+  return resolve(repoRoot, EVIDENCE_RELATIVE_ROOT, slug)
+}
+
+const isDirectRun =
+  process.argv[1] !== undefined &&
+  existsSync(process.argv[1]) &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+
+if (isDirectRun) {
+  const args = process.argv.slice(2)
+  const read = (flag) => {
+    const at = args.indexOf(flag)
+    return at === -1 ? undefined : args[at + 1]
+  }
+  try {
+    const dir = resolveEvidenceDir({ repoRoot: read("--repo-root") ?? process.cwd(), slug: read("--slug") })
+    process.stdout.write(`${dir}\n`)
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exit(1)
+  }
+}