oh-my-opencode 5.0.0-beta.8 → 5.0.0-beta.81

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)
+  }
+}

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("")
+  })
+})

package/.agents/skills/tech-debt-audit/SKILL.md

@@ -1,24 +1,11 @@
 ---
 name: tech-debt-audit
-description: "Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, language-native tooling, and optionally CodeGraph knowledge graph. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase health check, tech debt audit, architecture review, code quality assessment, or cleanup planning. Triggers: 'tech debt', 'technical debt', 'debt audit', 'code health', 'technical debt audit', 'codebase health check', 'find tech debt', 'debt analysis', 'audit code quality'."
+description: "Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, LSP, and language-native tooling. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase health check, tech debt audit, architecture review, code quality assessment, or cleanup planning. Triggers: 'tech debt', 'technical debt', 'debt audit', 'code health', 'technical debt audit', 'codebase health check', 'find tech debt', 'debt analysis', 'audit code quality'."
 ---
 
 # Tech Debt Audit Protocol
 
-Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`grep`, `glob`, `bash` with `sg`, `read`, `lsp_diagnostics`, `task`) plus **optional CodeGraph MCP** for enhanced code graph analysis when available. Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.
-
-## CodeGraph Enhancement (Optional)
-
-If you have [CodeGraph](https://github.com/colbymchenry/codegraph) installed (check with `codegraph status`), its MCP tools (`codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_explore`, etc.) can supersede or augment the standard tool searches in the dimensions marked below. CodeGraph gives you:
-- **Symbol search** — instant by-name lookup via FTS5
-- **Call graph analysis** — callers/callees for any function
-- **Impact analysis** — blast radius before changing any symbol
-- **Smart context building** — entry points, related symbols, and snippets in one call
-- **Framework-aware routes** — URL patterns linked to their handlers
-
-To use CodeGraph, ensure the `codegraph` MCP server is configured in your project's `.mcp.json` or global MCP config. The skill will auto-detect CodeGraph by checking if `codegraph` MCP tools are available. Sub-agents spawned via `task()` cannot use CodeGraph — they use the standard tool fallback.
-
----
+Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (`grep`, `glob`, `bash` with `sg`, `read`, `lsp_diagnostics`, `task`). Produces a grounded, citable `TECH_DEBT_AUDIT.md` artifact.
 
 ## Output
 
@@ -42,19 +29,6 @@ Write results to `TECH_DEBT_AUDIT.md` in the repo root with:
 5. Cross-reference high-churn + large = debt hot zones
 6. Write the mental model paragraph in your own working context
 
-### CodeGraph Enhancement (if available)
-Instead of guessing module boundaries, query the code graph:
-
-```
-codegraph_explore(query="architecture overview and main modules")
-```
-This returns symbol relationships and source grouped by file. Use the structure as your architectural mental model instead of hand-inferring it from directory names.
-
-```
-codegraph_explore(query="main entry points and execution flow")
-```
-This surfaces entry points and call chains. Use these to understand how the code actually flows vs how the directory layout suggests it flows.
-
 ## Phase 1: Audit Across 9 Dimensions
 
 Use OMO tools for each dimension. Run parallel tool calls within each dimension. Every finding MUST cite `file:line:col`.
@@ -68,33 +42,12 @@ Use OMO tools for each dimension. Run parallel tool calls within each dimension.
 - `grep("async|await")` on sync-looking files — misplaced async boundaries
 - `bash("wc -l <file>")` on each large file found in Phase 0
 
-#### CodeGraph Enhancement (if available)
-
-**Dead code detection:**
-```
-codegraph_callers(symbol="<suspected-dead-function>")
-codegraph_callers(symbol="<suspected-dead-class>")
-```
-Run `codegraph_callers` on suspected dead exports found via grep/glob. If the result shows zero callers (excluding test files), it's dead code.
-
-**Circular dependency detection:**
-```
-codegraph_impact(target="<module-or-file>", direction="upstream")
-```
-Use `codegraph_impact` on key modules to trace their dependents. If A depends on B and B depends on A, that's a cycle.
-
-**Architecture boundaries:**
-```
-codegraph_explore(query="module dependencies and architecture boundaries")
-```
-Use `codegraph_explore` to survey actual module structure.
-
 #### What to flag
 - Files > 500 LOC (god files)
 - Functions > 80 LOC or > 4 nesting levels
 - Classes with > 15 methods or > 400 LOC
 - Import cycles (A → B → A)
-- Dead exports: function/class defined but never imported elsewhere (CodeGraph: `codegraph_callers`)
+- Dead exports: function/class defined but never imported elsewhere (confirm with `lsp_find_references`)
 - Commented-out code blocks (>3 consecutive consecutive lines)
 
 ### 2. Consistency Rot
@@ -148,14 +101,6 @@ Use `codegraph_explore` to survey actual module structure.
 - `grep(".env|process.env|Bun.env")` — env var usage
 - `grep("API_KEY|SECRET|PASSWORD|TOKEN")` in non-config files — hardcoded config
 
-#### CodeGraph Enhancement (if available)
-
-**Blast radius of core dependencies:**
-```
-codegraph_impact(target="<core-utility-function>", direction="upstream")
-```
-Run this on a few key internal modules (logger, config loader, HTTP client) to see how widely they're used. A widely-depended-on module with poor error handling or type safety is a high-priority refactor target because changes to it ripple everywhere.
-
 #### What to flag
 - Outdated major-version deps
 - Dependencies that do the same thing (duplicate libraries)
@@ -184,21 +129,6 @@ Run this on a few key internal modules (logger, config loader, HTTP client) to s
 - `grep("console.error|logger\\.error|log\\.error")` — actual error logging
 - `bash("sg -p \"throw new $ERR($$$)\" -l ts .")` — error types used
 
-#### CodeGraph Enhancement (if available)
-
-**Trace error propagation through call chains:**
-```
-codegraph_callers(symbol="<key-error-handler-or-middleware>")
-codegraph_explore(query="how errors propagate through <key-error-handler>")
-```
-Use `codegraph_callers` to find who calls your error handlers. If errors are caught and swallowed at multiple levels, that's a finding.
-
-**Impact of changing error types:**
-```
-codegraph_impact(target="<error-class-or-interface>", direction="upstream")
-```
-Check the blast radius of custom error classes. If changing an error type would break 20+ consumers, the error contract is too tight.
-
 #### What to flag
 - Empty catch blocks (worst offense)
 - Generic `catch (e) { console.error(e) }` without recovery
@@ -237,18 +167,18 @@ Check the blast radius of custom error classes. If changing an error type would
 
 ## Phase 2: Deeper Dives (Parallel Sub-Agents)
 
-For large codebases (>50k LOC), delegate heavy dimensions to parallel sub-agents. Sub-agents CANNOT use CodeGraph — they use standard tools only:
+For large codebases (>50k LOC), delegate heavy dimensions to parallel sub-agents. Each sub-agent runs the standard tool passes for its dimensions:
 
 ```
 task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
 task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")
 ```
 
-Spawn 2-3 sub-agents for the heaviest dimensions, collect results in parallel, then synthesize. The main agent handles CodeGraph queries itself while sub-agents run the standard tool passes.
+Spawn 2-3 sub-agents for the heaviest dimensions, collect results in parallel, then synthesize.
 
 ## Phase 3: Synthesize & Deliver
 
-1. Collect all findings from direct tool calls, CodeGraph queries (if available), and sub-agent results
+1. Collect all findings from direct tool calls and sub-agent results
 2. Deduplicate — same issue mentioned by multiple dimensions
 3. Classify severity:
    - **Critical** — Causes incorrect behavior, data loss, or security vulnerability

package/.opencode/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/.opencode/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}