@akira-tl/forgerelay 0.8.9 → 0.9.0

package/docs/roadmap.md

@@ -38,7 +38,7 @@ ForgeRelay does not plan to add:
 - a plugin marketplace/runtime;
 - a second conversation/session runtime;
 - host-owned commands such as plan mode, context inspection, or model selection;
-- automatic installation and management of language servers.
+- automatic or unapproved language-server installation. Agent-managed TypeScript/JavaScript and Pyright installs require explicit user opt-in and remain disabled by default; Rust Analyzer, `gopls`, and `clangd` stay external toolchain/system dependencies.
 
 Shell execution remains a trusted local-user capability. Workspace filesystem
 containment must not be described as a shell sandbox.
@@ -197,11 +197,12 @@ capability
 
 ## 0.4 — LSP code intelligence v1
 
-LSP is moderate implementation complexity if ForgeRelay does not become a
-language-server installer.
-
-The first version should launch only language servers already available on the
-user's machine or explicitly configured by the user/project.
+LSP v1 was designed around language servers already available on the user's machine
+or explicitly configured by the user/project. ForgeRelay later added a narrow managed
+installation path for TypeScript/JavaScript and Pyright: it is disabled by default,
+requires explicit user authorization during setup, installs only into ForgeRelay's
+private config directory, and refreshes live without a server restart. This does not
+turn arbitrary language-server installation into an implicit Agent capability.
 
 During 0.4 development, MCP App UI hardening can land alongside the LSP work when
 it does not distort the code-intelligence scope. In particular, evaluate a more
@@ -245,9 +246,10 @@ and verify publication before work begins on the next boundary:
 The shipping 0.4 LSP v1 contract keeps the canonical nine Core MCP tools unchanged
 and exposes semantic operations only through `code.intelligence`. Deterministic
 fake-LSP coverage remains the primary cross-platform protocol/lifecycle gate, while
-`npm run lsp:interop` exercises `typescript-language-server`, Pyright,
-`rust-analyzer`, `gopls`, and `clangd` only when those external executables are
-already present and otherwise reports explicit skips without installing them.
+`npm run lsp:interop` exercises detected servers only when executables are already
+present and never downloads them. The later managed TypeScript/Pyright installation
+path is a separate explicitly authorized runtime capability and does not change that
+interop-test contract.
 
 ## 0.5 — Durable Activity and batch execution
 
@@ -315,32 +317,40 @@ milestone: the next stage remains blocked until the previous version's tag-trigg
 release workflow has completed successfully. Runtime acceptance uses only the
 reserved 7677/7678 debug instances and never touches the normal 7676 installation.
 
-## Later: first-class subagent MCP
-
-ForgeRelay already owns provider adapters and resumable local agent sessions. A
-future release may remove the current `bash -> forgerelay agents ...` indirection
-for MCP hosts.
-
-First-class subagent operations should reuse the Capability Gateway rather than
-add another top-level MCP tool. The parent agent should continue choosing from
-available provider/profile metadata while ForgeRelay owns provider-backed worker
-lifecycle state. This remains provider-backed delegation, not an attempt to
-emulate a Host-native subagent implementation.
-
-## Worktree and history refinements
-
-These can land alongside the main release lines when the underlying interfaces
-are ready:
-
-- `.worktreeinclude`-style explicit copying of selected gitignored files;
-- hook-backed worktree close verification;
-- stale managed-worktree recovery and cleanup;
-- checkpoint/list/restore primitives based on the existing Git snapshot engine;
-- retention/GC for stale workspace sessions, conversation bindings, and review
-  refs.
-
-Checkpoint restore must protect concurrent/external user edits rather than
-blindly overwriting a working tree.
+## 0.9 — Workspace Recovery & History
+
+0.9 builds on persistent Workspace identity, first-class `subagent.session`, and the
+existing Hook-backed managed-worktree finalize lifecycle. It does not add another Core
+MCP tool. Each stage is release-gated: the following stage begins only after the prior
+version's tag-triggered Linux/macOS/Windows verification and publication succeed.
+
+- **0.9.0** — add bounded read-only managed-worktree recovery observations to
+  `open_workspace(action="list"|"inspect")`, distinguishing healthy, recoverable,
+  and manual-intervention states without repairing or pruning Git state; align current
+  Roadmap/product documentation with already-shipped Subagent, worktree verification,
+  and explicitly authorized managed-LSP behavior;
+- **0.9.1** — add Workspace-scoped safe managed-worktree repair and cleanup through
+  the Capability Gateway. Recovery must preserve surviving managed-branch work and
+  refuse ambiguous ownership rather than guessing;
+- **0.9.2** — add persistent Workspace checkpoints with explicit create/list/inspect/
+  delete lifecycle, stored outside normal project history and surviving Workspace
+  close/reopen;
+- **0.9.3** — add checkpoint restore with optimistic-concurrency preflight so external
+  or user edits made after inspection cannot be silently overwritten. Restore changes
+  working-tree content without moving branch HEAD or using `git reset --hard`;
+- **0.9.4** — add owner-facing retention inspection and explicitly authorized prune
+  through the CLI. Audit retention remains unlimited by default, persistent Workspace
+  identity/Tasks are not ordinary GC targets, and destructive global maintenance is
+  not exposed as an ordinary Agent MCP Capability.
+
+Workspace Relay continues to treat the Execution ForgeRelay as the owner of Git,
+recovery, checkpoint, and retention facts; the Gateway only routes and presents bounded
+results. Development acceptance remains on isolated 7677/7678 instances and never uses
+the normal 7676 installation.
+
+Later refinements may add `.worktreeinclude`-style explicit copying of selected
+Git-ignored files. Native PowerShell/`cmd.exe` shell execution is also a separate
+compatibility decision rather than part of the 0.9 recovery/history line.
 
 ## Workspace Task Lists
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -23,7 +23,6 @@
     "docs/*.md",
     "examples",
     "scripts",
-    "skills",
     "capabilities",
     "README.md",
     "CHANGELOG.md",
@@ -53,7 +52,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/runtime/config/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/release/publish.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -28,6 +28,7 @@ if (head !== tagHead) {
 if (!gitSucceeds(["merge-base", "--is-ancestor", tagHead, "origin/main"])) {
   throw new Error(`${releaseTag} does not point to a commit contained in origin/main`);
 }
+const notesPath = prepareReleaseNotes(releaseTag);
 
 const packages = readdirSync(packageDir).filter((name) => name.endsWith(".tgz"));
 if (packages.length !== 1) {
@@ -53,7 +54,6 @@ if (npmPackageExists(packageSpec)) {
 if (ghReleaseExists(releaseTag)) {
   console.log(`GitHub Release ${releaseTag} already exists; leaving it unchanged.`);
 } else {
-  const notesPath = prepareReleaseNotes(releaseTag);
   const args = [
     "release",
     "create",
@@ -128,13 +128,16 @@ function ghReleaseExists(tag) {
 
 function prepareReleaseNotes(tag) {
   const manualNotes = join(repoRoot, "docs", "releases", `${tag}.md`);
-  const notes = existsSync(manualNotes)
-    ? readFileSync(manualNotes, "utf8")
-    : execFileSync(process.execPath, ["scripts/release-version.mjs", "notes", tag], {
-        cwd: repoRoot,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "inherit"],
-      });
+  let notes;
+  try {
+    notes = readFileSync(manualNotes, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`Missing dedicated release notes: docs/releases/${tag}.md`);
+    }
+    throw error;
+  }
+  if (!notes.trim()) throw new Error(`Dedicated release notes are empty: docs/releases/${tag}.md`);
   const tempRoot = resolve(process.env.RUNNER_TEMP ?? join(repoRoot, ".forgerelay-debug"));
   mkdirSync(tempRoot, { recursive: true });
   const notesPath = join(tempRoot, `release-notes-${tag}.md`);

package/scripts/release/release-gate.test.mjs

@@ -69,7 +69,9 @@ test("release runtime and local parity share the checked-in Node contract", asyn
 
   const source = await readFile(resolve(repoRoot, "scripts/release-parity.mjs"), "utf8");
   assert.match(source, /readFileSync\(join\(repoRoot, "\.nvmrc"\), "utf8"\)/);
-  assert.match(source, /const NPM_VERSION = "10\.9\.3"/);
+  assert.match(source, /const NPM_VERSION = "11\.19\.1"/);
+  const ciWorkflow = await readFile(resolve(repoRoot, ".github/workflows/ci.yml"), "utf8");
+  assert.match(ciWorkflow, /npm install --global npm@11\.19\.1/);
   assert.ok(source.includes('["npm", "ci", "--no-audit", "--no-fund"]'));
   assert.ok(source.includes('["npm", "run", "ci:verify"]'));
   assert.ok(source.includes('["npm", "run", "release:pack"]'));

package/scripts/release/release-version.test.mjs

@@ -14,6 +14,7 @@ async function createFixture(t) {
   const root = await mkdtemp(join(tmpdir(), "forgerelay-release-version-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   await mkdir(join(root, "scripts"), { recursive: true });
+  await mkdir(join(root, "docs", "releases"), { recursive: true });
   await cp(sourceScript, join(root, "scripts", "release-version.mjs"));
 
   const pkg = {
@@ -88,8 +89,19 @@ test("release version tooling prepares and validates an rc release", async (t) =
   const checked = await runRelease(root, "check");
   assert.match(checked.stdout, /release metadata is consistent at 0\.6\.0-rc\.1/);
 
+  await assert.rejects(
+    () => runRelease(root, "tag", "v0.6.0-rc.1"),
+    (error) => {
+      assert.match(String(error.stderr ?? error), /missing dedicated release notes: docs\/releases\/v0\.6\.0-rc\.1\.md/);
+      return true;
+    },
+  );
+  await writeFile(
+    join(root, "docs", "releases", "v0.6.0-rc.1.md"),
+    "# ForgeRelay v0.6.0-rc.1\n\nRelease candidate notes.\n",
+  );
   const tagged = await runRelease(root, "tag", "v0.6.0-rc.1");
-  assert.match(tagged.stdout, /release tag v0\.6\.0-rc\.1 matches package version and changelog/);
+  assert.match(tagged.stdout, /release tag v0\.6\.0-rc\.1 matches package version, changelog, and dedicated release notes/);
 
   const notes = await runRelease(root, "notes", "v0.6.0-rc.1");
   assert.match(notes.stdout, /Release candidate behavior/);

package/scripts/release-parity.mjs

@@ -5,7 +5,7 @@ import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const NPM_VERSION = "10.9.3";
+const NPM_VERSION = "11.19.1";
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const NODE_VERSION = readFileSync(join(repoRoot, ".nvmrc"), "utf8").trim();
 const debugRoot = join(repoRoot, ".forgerelay-debug");

package/scripts/release-proof.mjs

@@ -29,6 +29,20 @@ function packageVersion() {
   return pkg.version;
 }
 
+function requireDedicatedReleaseNotes(version) {
+  const path = join(process.cwd(), "docs", "releases", `v${version}.md`);
+  let notes;
+  try {
+    notes = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`missing dedicated release notes: docs/releases/v${version}.md`);
+    }
+    throw error;
+  }
+  if (!notes.trim()) throw new Error(`dedicated release notes are empty: docs/releases/v${version}.md`);
+}
+
 function gitDir() {
   const path = git(["rev-parse", "--git-dir"]);
   return path.startsWith("/") ? path : join(process.cwd(), path);
@@ -138,6 +152,7 @@ function checkHookTag() {
   if (tag !== expectedTag) {
     throw new Error(`tag ${tag} does not match package version ${version}; expected ${expectedTag}`);
   }
+  requireDedicatedReleaseNotes(version);
 
   let tagHead;
   try {

package/scripts/release-proof.test.mjs

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -25,6 +25,8 @@ test("release tag hook gate uses repository facts instead of requiring a local p
   const root = await mkdtemp(join(tmpdir(), "forgerelay-release-proof-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   await writeFile(join(root, "package.json"), JSON.stringify({ version: "1.2.3" }) + "\n");
+  await mkdir(join(root, "docs", "releases"), { recursive: true });
+  await writeFile(join(root, "docs", "releases", "v1.2.3.md"), "# v1.2.3\n\nDedicated notes.\n");
   await writeFile(join(root, "tracked.txt"), "verified\n");
   await git(root, ["init"]);
   await git(root, ["config", "user.email", "proof@example.com"]);
@@ -102,10 +104,34 @@ test("release tag hook gate uses repository facts instead of requiring a local p
   );
 });
 
+test("release tag hook gate rejects a matching tag when dedicated notes are missing", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "forgerelay-release-proof-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  await writeFile(join(root, "package.json"), JSON.stringify({ version: "1.4.0" }) + "\n");
+  await git(root, ["init"]);
+  await git(root, ["config", "user.email", "proof@example.com"]);
+  await git(root, ["config", "user.name", "Release Proof Test"]);
+  await git(root, ["add", "."]);
+  await git(root, ["commit", "-m", "release 1.4.0"]);
+  await git(root, ["tag", "v1.4.0"]);
+
+  await assert.rejects(
+    () => runProof(root, "check-hook", {
+      FORGERELAY_HOOK_PAYLOAD: JSON.stringify({ command: "git push origin v1.4.0" }),
+    }),
+    (error) => {
+      assert.match(String(error.stderr ?? error), /missing dedicated release notes: docs\/releases\/v1\.4\.0\.md/);
+      return true;
+    },
+  );
+});
+
 test("release tag hook gate accepts an rc tag for the package version", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "forgerelay-release-proof-"));
   t.after(() => rm(root, { recursive: true, force: true }));
   await writeFile(join(root, "package.json"), JSON.stringify({ version: "0.6.0-rc.1" }) + "\n");
+  await mkdir(join(root, "docs", "releases"), { recursive: true });
+  await writeFile(join(root, "docs", "releases", "v0.6.0-rc.1.md"), "# v0.6.0-rc.1\n\nDedicated RC notes.\n");
   await git(root, ["init"]);
   await git(root, ["config", "user.email", "proof@example.com"]);
   await git(root, ["config", "user.name", "Release Proof Test"]);

package/scripts/release-version.mjs

@@ -35,7 +35,8 @@ switch (command) {
     if (value !== expectedTag) {
       fail(`tag ${JSON.stringify(value)} does not match package version; expected ${expectedTag}`);
     }
-    console.log(`release tag ${value} matches package version and changelog`);
+    await requireReleaseNotes(state.pkg.version);
+    console.log(`release tag ${value} matches package version, changelog, and dedicated release notes`);
     break;
   }
   case "prepare": {
@@ -203,6 +204,20 @@ function getUnreleasedBody(changelog) {
   return changelog.slice(bodyStart, bodyEnd).trim();
 }
 
+async function requireReleaseNotes(version) {
+  const path = resolve(repoRoot, "docs", "releases", `v${version}.md`);
+  let content;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      fail(`missing dedicated release notes: docs/releases/v${version}.md`);
+    }
+    throw error;
+  }
+  if (!content.trim()) fail(`dedicated release notes are empty: docs/releases/v${version}.md`);
+}
+
 function getReleaseBody(changelog, version) {
   const heading = `## [${version}]`;
   const headingIndex = changelog.indexOf(heading);

package/skills/subagent-delegation/SKILL.md

@@ -1,132 +0,0 @@
----
-name: subagent-delegation
-description: Delegate coding tasks to user-configured ForgeRelay subagents.
----
-
-# Subagent Delegation
-
-Use this skill when the user explicitly asks to delegate work to another coding
-agent, use a named subagent, get a second opinion, compare approaches, or run
-a subagent-like workflow.
-
-Do not use subagents silently. Tell the user when another subagent is
-being used.
-
-## Core commands
-
-Use only these commands for normal delegation:
-
-```bash
-forgerelay agents ls
-forgerelay agents run <profile-or-provider-or-id> "<prompt>"
-forgerelay agents show <id>
-```
-
-`ls` shows existing subagent sessions for the current workspace. ForgeRelay scopes
-it automatically from the shell environment injected by the workspace tool.
-
-`run <profile> "<prompt>"` starts a new configured profile and prints a
-ForgeRelay agent id.
-
-`run <provider> "<prompt>"` starts a raw built-in provider when no configured
-profile is needed. Built-in providers are listed by `open_workspace`.
-
-`run <id> "<prompt>"` sends a follow-up to an existing agent.
-
-`show <id>` prints status and the latest response. If the agent is still
-running, `show` waits briefly. If there is still no final response, call `show`
-again later.
-
-Do not run provider CLIs such as `codex`, `claude`, `opencode`, `pi`,
-`cursor-agent`, or `copilot` directly unless you are explicitly debugging
-ForgeRelay agent integration.
-
-## Choosing a profile
-
-Choose profiles from the compact subagent profile catalog returned by
-`open_workspace`. Use the profile name with `forgerelay agents run`. If no
-profile fits and delegation is still appropriate, use a built-in provider name
-from `open_workspace`.
-
-Profiles may declare a model and optional thinking level. To override the
-configured/default provider model or thinking level for a run, pass `--model`
-or `--thinking`:
-
-```bash
-forgerelay agents run <profile-or-provider> --model <model> "<prompt>"
-forgerelay agents run <profile-or-provider> --thinking <level> "<prompt>"
-```
-
-Use `--thinking` only when the user asks for a specific reasoning depth or when
-the task clearly needs a different effort than the configured profile default.
-Thinking values are provider-specific passthrough values. Use names supported by
-the selected local agent harness; ForgeRelay does not translate values between
-providers.
-
-Good delegation targets:
-
-- `reviewer`: second opinion, bug risk, security risk, test gaps.
-- `explorer`: read-only codebase investigation.
-- `implementer`: focused implementation when the user asked for delegation.
-
-Do not delegate ordinary coding work just because a profile exists. Use normal
-ForgeRelay tools unless the user asked for delegation, another agent's opinion,
-parallel work, or a named subagent.
-
-## Worker prompts
-
-Agents start with only the prompt you send plus their configured profile
-instructions. Make prompts self-contained.
-
-Implementation prompt shape:
-
-```text
-Goal:
-<clear goal>
-
-Context:
-<repo/module/user constraints>
-
-Relevant files:
-<paths and why they matter>
-
-Acceptance criteria:
-- <criterion>
-
-Rules:
-- Keep changes focused.
-- Do not perform unrelated refactors.
-- Report blockers clearly.
-```
-
-Read-only investigation prompt shape:
-
-```text
-Question:
-<specific question>
-
-Scope:
-<files/directories/modules to inspect>
-
-Rules:
-- Do not modify files.
-- Cite relevant file paths and symbols.
-- Separate facts from guesses.
-```
-
-## After the worker responds
-
-Always review the result before presenting it as verified.
-
-For write-capable tasks, inspect changed files and run or explain relevant
-tests. For read-only tasks, verify that important claims are supported by repo
-evidence.
-
-Be transparent in the final response:
-
-```text
-I used <profile>. It reported <summary>. I verified <checks>. Remaining risk:
-<risk or none>.
-```
-
-Never hide that a subagent was used.