oh-my-openagent 5.0.0-beta.9 → 5.0.0

package/.agents/command/publish.md

@@ -203,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/command/remove-deadcode.md

@@ -113,7 +113,7 @@ For EACH batch, fire a deep agent:
 
 ```
 task(
-  category="deep",
+  category="deep-low",
   load_skills=["typescript-programmer", "git-master"],
   run_in_background=true,
   description="Remove dead code batch N: [brief description]",

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

@@ -34,6 +34,8 @@ Verified against `codex-cli 0.140.0` (node, jq, tmux, bun on macOS). Confirm wit
   [references/app-server.md](references/app-server.md).
 - **The captured JSON / pane IS the evidence** — write it under
   `.omo/evidence/<YYYYMMDD>-<slug>/` (no evidence file == the QA did not happen).
+  That directory is gitignored: the files stay local, the PR body carries the
+  summary and decisive excerpts, and nothing under it is ever committed.
 
 ## Setup
 

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/hyperplan/SKILL.md

@@ -26,15 +26,15 @@ Before starting, verify:
 
 Each member is a `kind: "category"` team member. They route through `sisyphus-junior` with the category's model and prompt-append shaping their behavior. The `prompt` field below is the **system prompt** that establishes their adversarial identity.
 
-Required categories are `unspecified-low`, `unspecified-high`, `ultrabrain`, and `artistry`. Include `deep` only when that category is enabled; if `deep` is disabled or unavailable, retry without only the researcher member and state the degraded roster.
+Required categories are `unspecified-low`, `unspecified-high`, `ultrabrain`, and `artistry`. Include `deep-low` only when that category is enabled; if `deep-low` is disabled or unavailable, retry without only the researcher member and state the degraded roster.
 
 ### CATEGORY CHARACTERISTICS REFERENCE
 
 | Category | Model | Native Mindset | Why This Adversarial Role Fits |
 |----------|-------|----------------|--------------------------------|
 | `unspecified-low` | gpt-5.6-luna xhigh | Mid-tier, simplicity-leaning, structure-demanding | Pragmatist Skeptic — model bias toward simplicity makes it the natural enemy of over-engineering |
-| `unspecified-high` | kimi-k3 max -> claude-opus-5 xhigh -> gpt-5.6-sol high | High-effort, broad-impact, coordination-aware | Integration Tester — max-tier broad-scope thinking exposes cross-module fragility |
-| `deep` | gpt-5.6-sol medium | Autonomous, exploration-heavy, evidence-driven | Autonomous Researcher — natural exploration bias attacks unfounded claims |
+| `unspecified-high` | claude-opus-5-5 medium -> glm-5.3 max -> kimi-k3 max | High-effort, broad-impact, coordination-aware | Integration Tester — broad-scope thinking exposes cross-module fragility |
+| `deep-low` | gpt-5.6-sol medium | Autonomous, exploration-heavy, evidence-driven | Autonomous Researcher — natural exploration bias attacks unfounded claims |
 | `ultrabrain` | gpt-5.6-sol xhigh | Hard-logic, simplicity-biased, strategic advisor | Architect Strategist — xhigh reasoning sees structural flaws others miss |
 | `artistry` | claude-fable-5 xhigh | Unconventional, pattern-breaking, lateral | Creative Challenger — pattern-breaking bias attacks orthodox thinking |
 
@@ -95,7 +95,7 @@ When you receive others' findings, default position: assume they missed somethin
 Output format: numbered findings/critiques, each ≤3 sentences. Cite specific edge cases and integration points. No prose.
 ```
 
-### MEMBER 3: `researcher` (category: `deep`)
+### MEMBER 3: `researcher` (category: `deep-low`)
 
 **Role**: The Autonomous Researcher.
 **Position**: Enemy of unfounded claims. Evidence demander.
@@ -210,7 +210,7 @@ team_create({
     members: [
       { name: "skeptic",    kind: "category", category: "unspecified-low",  prompt: "<full Skeptic system prompt>" },
       { name: "validator",  kind: "category", category: "unspecified-high", prompt: "<full Validator system prompt>" },
-      { name: "researcher", kind: "category", category: "deep",             prompt: "<full Researcher system prompt>" },
+      { name: "researcher", kind: "category", category: "deep-low",         prompt: "<full Researcher system prompt>" },
       { name: "architect",  kind: "category", category: "ultrabrain",       prompt: "<full Architect system prompt>" },
       { name: "creative",   kind: "category", category: "artistry",         prompt: "<full Creative system prompt>" }
     ]
@@ -220,7 +220,7 @@ team_create({
 
 Capture the returned `teamRunId`. You will use it for every subsequent call.
 
-If `team_create` errors because `deep` is disabled or unavailable, retry once without the `researcher` member. Do not drop `unspecified-low`, `unspecified-high`, `ultrabrain`, or `artistry`.
+If `team_create` errors because `deep-low` is disabled or unavailable, retry once without the `researcher` member. Do not drop `unspecified-low`, `unspecified-high`, `ultrabrain`, or `artistry`.
 
 ### Phase 2: Round 1 — Independent analysis
 

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

@@ -202,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/remove-deadcode/SKILL.md

@@ -113,7 +113,7 @@ For EACH batch, fire a deep agent:
 
 ```
 task(
-  category="deep",
+  category="deep-low",
   load_skills=["typescript-programmer", "git-master"],
   run_in_background=true,
   description="Remove dead code batch N: [brief description]",

package/.agents/skills/security-research/SKILL.md

@@ -42,11 +42,11 @@ Create one Team Mode run with these 5 members:
 
 | Member | Kind | Category | Role |
 |--------|------|----------|------|
-| `surface-hunter` | category | `deep` | Map entry points, trust boundaries, and reachable attack surfaces. |
+| `surface-hunter` | category | `deep-low` | Map entry points, trust boundaries, and reachable attack surfaces. |
 | `auth-data-hunter` | category | `ultrabrain` | Hunt auth, authorization, data isolation, injection, and secret handling flaws. |
 | `runtime-supply-hunter` | category | `unspecified-high` | Hunt filesystem, subprocess, archive, dependency, hook, MCP, and config risks. |
 | `poc-engineer-a` | category | `unspecified-high` | Build minimal PoCs for the strongest candidate findings. |
-| `poc-engineer-b` | category | `deep` | Independently reproduce, falsify, or downgrade candidate findings. |
+| `poc-engineer-b` | category | `deep-high` | Independently reproduce, falsify, or downgrade candidate findings. |
 
 Call `team_create` with an inline spec:
 
@@ -59,7 +59,7 @@ team_create({
       {
         name: "surface-hunter",
         kind: "category",
-        category: "deep",
+        category: "deep-low",
         prompt: "You map attack surface. Enumerate entry points, trust boundaries, attacker-controlled inputs, data sinks, privilege transitions, and sensitive assets. Return evidence with file paths and exact functions. Do not assign severity unless you can name an attack path."
       },
       {
@@ -83,7 +83,7 @@ team_create({
       {
         name: "poc-engineer-b",
         kind: "category",
-        category: "deep",
+        category: "deep-high",
         prompt: "You independently reproduce candidate findings and try to falsify them. Downgrade anything without a working path. If a PoC is unsafe to run, design a safe static or dry-run proof and explain the limit."
       }
     ]

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

@@ -0,0 +1,86 @@
+---
+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/` or a `.qa-evidence/` at
+  the worktree root, which is outside the ignored root and gets committed by
+  accident (#8703).
+- **Evidence stays local.** `.omo/evidence/` is gitignored and the
+  tracked-evidence audit test fails the build if any evidence path is tracked.
+  Never `git add -f` an artifact; the PR body carries the summary and the
+  decisive excerpts.
+- **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. The file proves the run on the
+  machine that made it; it is not something the commit carries.
+
+## 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 AGENTS.md rule points at, and it is gitignored,
+// so a hand-typed alternative (local-ignore/qa-evidence/..., .qa-evidence/ at the worktree root, a temp
+// dir, a traversal) either strands the evidence or lands it in a commit (#8703). 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)
+  }
+}

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

@@ -0,0 +1,171 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, relative } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+import { EVIDENCE_RELATIVE_ROOT, resolveEvidenceDir } from "./resolve-evidence-dir.mjs"
+
+const cleanupRoots = []
+const cliPath = fileURLToPath(new URL("./resolve-evidence-dir.mjs", import.meta.url))
+
+afterEach(() => {
+  for (const root of cleanupRoots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function makeGitRoot() {
+  const root = mkdtempSync(join(tmpdir(), "senpi-qa-evidence-"))
+  cleanupRoots.push(root)
+  mkdirSync(join(root, ".git"))
+  return root
+}
+
+describe("resolveEvidenceDir", () => {
+  test("#given a git worktree and a safe slug #when resolved #then it returns the canonical adapter evidence directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot, slug: "20260820-senpi-qa-contract" })
+
+    // then
+    expect(resolved).toBe(join(repoRoot, ".omo", "evidence", "omo-senpi-adapter", "20260820-senpi-qa-contract"))
+  })
+
+  test("#given a relative git worktree path #when resolved #then it still returns an absolute evidence directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const relativeRoot = relative(process.cwd(), repoRoot)
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot: relativeRoot, slug: "20260820-relative-root" })
+
+    // then
+    expect(resolved).toBe(join(repoRoot, ".omo", "evidence", "omo-senpi-adapter", "20260820-relative-root"))
+  })
+
+  test("#given a resolved evidence path #when the resolver returns #then it has created no directory", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const resolved = resolveEvidenceDir({ repoRoot, slug: "20260820-senpi-qa-contract" })
+
+    // then
+    expect(existsSync(resolved)).toBe(false)
+    expect(existsSync(join(repoRoot, ".omo"))).toBe(false)
+  })
+
+  test("#given the adapter evidence root #when it is the declared relative root #then it stays under .omo/evidence", () => {
+    // given / when / then
+    expect(EVIDENCE_RELATIVE_ROOT).toBe(join(".omo", "evidence", "omo-senpi-adapter"))
+  })
+
+  test("#given an unsafe slug #when resolved #then it is rejected before any path is produced", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const unsafeSlugs = [
+      "",
+      "   ",
+      ".",
+      "..",
+      "../escape",
+      "nested/slug",
+      "nested\\slug",
+      "/absolute",
+      join(repoRoot, "absolute"),
+      "local-ignore/qa-evidence/20260819-senpi",
+      "..%2Fescape",
+      "-leading-hyphen",
+      "trailing-hyphen-",
+      "Upper-Case",
+      "under_score",
+    ]
+
+    // when / then
+    for (const slug of unsafeSlugs) {
+      expect(() => resolveEvidenceDir({ repoRoot, slug }), `must reject ${JSON.stringify(slug)}`).toThrow()
+    }
+  })
+
+  test("#given a directory that is not a git worktree #when resolved #then it is rejected", () => {
+    // given
+    const notARepo = mkdtempSync(join(tmpdir(), "senpi-qa-not-git-"))
+    cleanupRoots.push(notARepo)
+
+    // when / then
+    expect(() => resolveEvidenceDir({ repoRoot: notARepo, slug: "20260820-senpi-qa-contract" })).toThrow(/git/i)
+  })
+
+  test("#given a rejected slug #when the error surfaces #then it names the offending slug for the operator", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when / then
+    expect(() => resolveEvidenceDir({ repoRoot, slug: "local-ignore/qa-evidence/x" })).toThrow(
+      /local-ignore\/qa-evidence\/x/,
+    )
+  })
+
+  test("#given the documented Node CLI #when valid and invalid slugs run #then stdout and exit codes enforce the contract", () => {
+    // given
+    const repoRoot = makeGitRoot()
+
+    // when
+    const valid = spawnSync("node", [cliPath, "--repo-root", repoRoot, "--slug", "20260820-node-cli"], {
+      encoding: "utf8",
+    })
+    const invalid = spawnSync(
+      "node",
+      [cliPath, "--repo-root", repoRoot, "--slug", "local-ignore/qa-evidence/x"],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(valid.status).toBe(0)
+    expect(valid.stdout.trim()).toBe(join(repoRoot, EVIDENCE_RELATIVE_ROOT, "20260820-node-cli"))
+    expect(invalid.status).toBe(1)
+    expect(invalid.stderr).toContain("local-ignore/qa-evidence/x")
+  })
+
+  test("#given a symlink to the documented Node CLI #when invoked #then the entrypoint still enforces the contract", () => {
+    // given
+    const repoRoot = makeGitRoot()
+    const symlinkPath = join(repoRoot, "resolve-evidence-dir.mjs")
+    symlinkSync(cliPath, symlinkPath)
+
+    // when
+    const result = spawnSync(
+      "node",
+      [symlinkPath, "--repo-root", repoRoot, "--slug", "20260820-symlink-cli"],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(result.status).toBe(0)
+    expect(result.stdout.trim()).toBe(join(repoRoot, EVIDENCE_RELATIVE_ROOT, "20260820-symlink-cli"))
+  })
+
+  test("#given an embedding runner with a missing argv path #when the module is imported #then exports still load", () => {
+    // given
+    const missingEntrypoint = join(tmpdir(), `missing-senpi-qa-entrypoint-${process.pid}.mjs`)
+    const moduleUrl = pathToFileURL(cliPath).href
+
+    // when
+    const result = spawnSync(
+      "node",
+      [
+        "--input-type=module",
+        "--eval",
+        `process.argv[1] = ${JSON.stringify(missingEntrypoint)}; await import(${JSON.stringify(moduleUrl)})`,
+      ],
+      { encoding: "utf8" },
+    )
+
+    // then
+    expect(result.status).toBe(0)
+    expect(result.stdout).toBe("")
+    expect(result.stderr).toBe("")
+  })
+})