@uniqbit/mate-core 0.15.0 → 0.15.1-canary.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.0",
+  "version": "0.15.1-canary.1",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/doctor.ts

@@ -127,10 +127,10 @@ function getSelectedToolChecks(config: {
     checks.push({ name: "tokensave", command: "tokensave", source: "capability" });
   }
   if (selectedCapabilities.has("headroom")) {
-    checks.push(
-      { name: "headroom", command: "headroom", source: "capability" },
-      { name: "rtk", command: "rtk", source: "headroom dependency" },
-    );
+    checks.push({ name: "headroom", command: "headroom", source: "capability" });
+  }
+  if (selectedCapabilities.has("rtk")) {
+    checks.push({ name: "rtk", command: "rtk", source: "capability" });
   }
   if (selectedCapabilities.has("graphify")) {
     checks.push({ name: "graphify", command: "graphify", source: "capability" });

package/src/cli/commands/report/index.ts

@@ -74,6 +74,7 @@ export async function runReportCommand(
 
   const tokensaveEnabled = enabledCapabilities.includes("tokensave");
   const headroomEnabled = enabledCapabilities.includes("headroom");
+  const rtkEnabled = enabledCapabilities.includes("rtk");
 
   // Collect spending via ccusage (covers all agents: Claude, OpenCode, Codex, etc.)
   const ccusageResult = await collectCcusageSpending(options.days, deps);
@@ -92,7 +93,7 @@ export async function runReportCommand(
   };
   let rtkResult: Awaited<ReturnType<typeof collectRTKSavings>> = {
     entry: null,
-    status: { name: "rtk", enabled: false, status: "not installed" },
+    status: { name: "rtk", enabled: false, status: "not enabled" },
   };
   let headroomResult: Awaited<ReturnType<typeof collectHeadroomSavings>> = {
     entry: null,
@@ -106,8 +107,9 @@ export async function runReportCommand(
     ]);
   }
 
-  // RTK savings
-  rtkResult = await collectRTKSavings(workingRepoPath, deps);
+  if (rtkEnabled) {
+    rtkResult = await collectRTKSavings(workingRepoPath, deps);
+  }
 
   if (headroomEnabled) {
     headroomResult = await collectHeadroomSavings(options.days, deps);

package/src/index.ts

@@ -24,6 +24,7 @@ export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli
 export type {
   CapabilityPlugin,
   InstructionsService,
+  LaunchPreflightContext,
   McpServerDescriptor,
   McpService,
   Plugin,

package/src/lib/context-mode-package.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { PUBLIC_NPM_REGISTRY } from "./public-npm";
+
+export const CONTEXT_MODE_PACKAGE_NAME = "context-mode";
+export const CONTEXT_MODE_VERSION = "1.0.169";
+export const CONTEXT_MODE_NODE_REQUIREMENT = ">=22.5.0";
+
+export function getContextModePackageReference(): string {
+  return `${CONTEXT_MODE_PACKAGE_NAME}@${CONTEXT_MODE_VERSION}`;
+}
+
+export function isContextModePackageReference(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value === CONTEXT_MODE_PACKAGE_NAME || value.startsWith(`${CONTEXT_MODE_PACKAGE_NAME}@`))
+  );
+}
+
+export function getContextModeInstallDir(companionPath: string): string {
+  return path.join(companionPath, ".mate", "dependencies", CONTEXT_MODE_PACKAGE_NAME);
+}
+
+export function getContextModePackageRoot(companionPath: string): string {
+  return path.join(
+    getContextModeInstallDir(companionPath),
+    "node_modules",
+    CONTEXT_MODE_PACKAGE_NAME,
+  );
+}
+
+export function isContextModeNodeVersionSupported(version: string): boolean {
+  const [major = 0, minor = 0] = version.replace(/^v/, "").split(".").map(Number);
+  return major > 22 || (major === 22 && minor >= 5);
+}
+
+export function validateContextModeNodeRuntime(): void {
+  const result = spawnSync("node", ["--version"], { encoding: "utf8" });
+  const version = result.stdout?.trim() ?? "";
+  if (result.status !== 0 || !isContextModeNodeVersionSupported(version)) {
+    throw new Error(
+      `context-mode ${CONTEXT_MODE_VERSION} requires Node.js ${CONTEXT_MODE_NODE_REQUIREMENT}; found ${version || "no usable node executable"}.`,
+    );
+  }
+}
+
+export async function validateContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const root = getContextModePackageRoot(companionPath);
+  const manifest = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8")) as {
+    version?: string;
+  };
+  if (manifest.version !== CONTEXT_MODE_VERSION) {
+    throw new Error(
+      `Expected ${getContextModePackageReference()} at ${root}; found ${manifest.version ?? "an unknown version"}. Re-run \`mate companion setup\`.`,
+    );
+  }
+  await Promise.all(
+    [
+      ".claude-plugin/plugin.json",
+      "hooks/hooks.json",
+      "skills/context-mode/SKILL.md",
+      "build/adapters/opencode/plugin.js",
+    ].map((asset) => fs.access(path.join(root, asset))),
+  );
+}
+
+export async function installContextModePackage(companionPath: string): Promise<void> {
+  validateContextModeNodeRuntime();
+  const installDir = getContextModeInstallDir(companionPath);
+  await fs.mkdir(installDir, { recursive: true });
+  await fs.writeFile(
+    path.join(installDir, "package.json"),
+    JSON.stringify(
+      { private: true, dependencies: { [CONTEXT_MODE_PACKAGE_NAME]: CONTEXT_MODE_VERSION } },
+      null,
+      2,
+    ) + "\n",
+    "utf8",
+  );
+  const result = spawnSync(
+    "npm",
+    ["install", "--no-audit", "--no-fund", "--silent", "--registry", PUBLIC_NPM_REGISTRY],
+    { cwd: installDir, encoding: "utf8" },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `Could not install ${getContextModePackageReference()}: ${result.error?.message ?? result.stderr?.trim() ?? `npm exited with ${result.status}`}`,
+    );
+  }
+  await validateContextModePackage(companionPath);
+}

package/src/lib/opencode-plugin-package.ts

@@ -44,53 +44,50 @@ export const opencodePluginCacheDeps = {
     }),
 };
 
-/**
- * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
- * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
- * layout, so the first managed launch after a setup or update does not depend
- * on registry access. Best effort: failures are reported, never thrown.
- */
-export async function warmOpenCodePluginCache(
-  version: string = getCurrentVersion(),
+export async function warmOpenCodePackageCache(
+  packageName: string,
+  packageReference: string,
   env: NodeJS.ProcessEnv = process.env,
   registry = PUBLIC_NPM_REGISTRY,
 ): Promise<WarmPluginCacheResult> {
-  // Escape hatch for tests and intentionally offline environments: skip the
-  // pre-fetch entirely instead of attempting a registry install.
   if (env.MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH === "1") {
     return { ok: true, detail: "pre-fetch disabled via MATE_DISABLE_OPENCODE_PLUGIN_PREFETCH" };
   }
-
-  const reference = getOpenCodePluginPackageReference(version);
-  const specDir = path.join(getOpenCodeCacheDir(env), "packages", reference);
-
+  const version = packageReference.slice(packageName.length + 1);
+  const specDir = path.join(getOpenCodeCacheDir(env), "packages", packageReference);
   try {
     await fs.mkdir(specDir, { recursive: true });
     await fs.writeFile(
       path.join(specDir, "package.json"),
-      JSON.stringify({ dependencies: { [OPENCODE_PLUGIN_PACKAGE_NAME]: version } }, null, 2) + "\n",
+      JSON.stringify({ dependencies: { [packageName]: version } }, null, 2) + "\n",
       "utf8",
     );
-
     const result = opencodePluginCacheDeps.runInstall(specDir, registry);
-    if (result.error) {
-      return { ok: false, detail: result.error.message };
-    }
+    if (result.error) return { ok: false, detail: result.error.message };
     if (result.status !== 0) {
-      const output = `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`;
-      return { ok: false, detail: output };
+      return {
+        ok: false,
+        detail: `${result.stderr ?? ""}`.trim() || `npm install exited with ${result.status}`,
+      };
     }
-
-    await fs.access(
-      path.join(
-        specDir,
-        "node_modules",
-        ...OPENCODE_PLUGIN_PACKAGE_NAME.split("/"),
-        "package.json",
-      ),
-    );
+    await fs.access(path.join(specDir, "node_modules", ...packageName.split("/"), "package.json"));
     return { ok: true };
   } catch (error) {
     return { ok: false, detail: (error as Error).message };
   }
 }
+
+/**
+ * Pre-fetch the pinned plugin package into OpenCode's npm plugin environment
+ * (`<cache>/packages/<spec>/`), mirroring OpenCode's own on-demand install
+ * layout, so the first managed launch after a setup or update does not depend
+ * on registry access. Best effort: failures are reported, never thrown.
+ */
+export async function warmOpenCodePluginCache(
+  version: string = getCurrentVersion(),
+  env: NodeJS.ProcessEnv = process.env,
+  registry = PUBLIC_NPM_REGISTRY,
+): Promise<WarmPluginCacheResult> {
+  const reference = getOpenCodePluginPackageReference(version);
+  return warmOpenCodePackageCache(OPENCODE_PLUGIN_PACKAGE_NAME, reference, env, registry);
+}

package/src/lib/orchestrator/adapters/claude.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 
 import { buildCompanionGuidance } from "../../../playbooks/companion-guidance";
+import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
 import {
   getCompanionClaudeMcpConfigPath,
   getCompanionClaudeSettingsPath,
@@ -11,6 +12,19 @@ export class ClaudeAdapter extends LaunchAdapter {
   readonly toolName = "claude";
   readonly interactive = true;
 
+  async validateLaunch(context: AdapterContext): Promise<void> {
+    if (context.capabilities.some((capability) => capability.name === "context-mode")) {
+      try {
+        await validateContextModePackage(context.companionPath);
+      } catch (error) {
+        throw new Error(
+          `Claude context-mode plugin is unavailable: ${(error as Error).message} Repair it with \`mate companion setup\`.`,
+          { cause: error },
+        );
+      }
+    }
+  }
+
   buildArgs(context: AdapterContext, args: string[]): string[] {
     // Load Mate-managed Claude config from companion settings when present,
     // layered on top of the user's user/project/local sources so global
@@ -29,6 +43,11 @@ export class ClaudeAdapter extends LaunchAdapter {
     const mcpConfigArgs = existsSync(companionMcpConfigPath)
       ? ["--mcp-config", companionMcpConfigPath]
       : [];
+    const contextModeArgs = context.capabilities.some(
+      (capability) => capability.name === "context-mode",
+    )
+      ? ["--plugin-dir", getContextModePackageRoot(context.companionPath)]
+      : [];
 
     return [
       "--add-dir",
@@ -37,6 +56,7 @@ export class ClaudeAdapter extends LaunchAdapter {
       buildCompanionGuidance(context),
       ...settingsArgs,
       ...mcpConfigArgs,
+      ...contextModeArgs,
       ...args,
     ];
   }

package/src/lib/orchestrator/adapters/opencode.ts

@@ -171,7 +171,6 @@ export class OpenCodeAdapter extends LaunchAdapter {
       )),
       ...this.validateGuidance(context),
     ];
-
     if (errors.length > 0) {
       throw new LaunchPreflightError(
         [
@@ -197,9 +196,11 @@ export class OpenCodeAdapter extends LaunchAdapter {
     } catch {
       return [`Unreadable OpenCode configuration: ${configPath}`];
     }
+    if (!isRecord(config)) {
+      return [`Unreadable OpenCode configuration: ${configPath}`];
+    }
 
-    const plugins =
-      isRecord(config) && Array.isArray(config.plugin) ? (config.plugin as unknown[]) : [];
+    const plugins = Array.isArray(config.plugin) ? (config.plugin as unknown[]) : [];
     const mateReferences = plugins.filter(isMateOpenCodePluginReference) as string[];
 
     if (mateReferences.includes(expectedPluginReference)) {

package/src/lib/orchestrator/config-store.ts

@@ -5,6 +5,8 @@ import { getDefaultSetupSelections } from "./setup-compatibilities";
 import { YamlFileStore } from "./yaml-file-store";
 import { type FrameworkConfig } from "./types";
 
+export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
+
 function defaultConfigPath(): string {
   return `.${frameworkConfig.name}/config/framework.yaml`;
 }
@@ -38,17 +40,35 @@ export function mergeWithDefaults(existing: FrameworkConfig): FrameworkConfig {
   };
 }
 
+export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkConfig {
+  const migrations = config.migrations ?? [];
+  if (migrations.includes(RTK_CAPABILITY_SPLIT_MIGRATION)) return config;
+
+  const capabilities = config.capabilities ?? [];
+  const hasHeadroom = capabilities.some((capability) => capability.name === "headroom");
+  const hasRtk = capabilities.some((capability) => capability.name === "rtk");
+  return {
+    ...config,
+    capabilities: hasHeadroom && !hasRtk ? [...capabilities, { name: "rtk" }] : capabilities,
+    migrations: [...migrations, RTK_CAPABILITY_SPLIT_MIGRATION],
+  };
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
   }
 
   override async load(): Promise<FrameworkConfig> {
-    return mergeWithDefaults(await super.load());
+    const merged = mergeWithDefaults(await super.load());
+    const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
+    const config = migrateRtkCapabilitySplit(merged);
+    if (needsMigration) await this.save(config);
+    return config;
   }
 
   protected async onMissing(): Promise<FrameworkConfig> {
-    const config = defaultConfig();
+    const config = migrateRtkCapabilitySplit(defaultConfig());
     await this.save(config);
     return config;
   }

package/src/lib/orchestrator/launcher.ts

@@ -1,5 +1,7 @@
 // oxlint-disable no-underscore-dangle
 import { syncCompanionFiles, syncWorkingRepoClaudeSettings } from "../../tools/setup";
+import { getActiveDistribution } from "../../distribution";
+import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
 import type { LaunchAdapter, AdapterContext } from "./adapters/base";
 import { ClaudeAdapter } from "./adapters/claude";
 import { OpenCodeAdapter } from "./adapters/opencode";
@@ -8,6 +10,7 @@ import { syncCompanionGit } from "./companion-git-sync";
 import { resolveForLaunch, type LaunchContext } from "./framework-context";
 import {
   RepositoryNotSelectedError,
+  LaunchPreflightError,
   ToolNotAllowedError,
   type FrameworkConfig,
   type LaunchRequest,
@@ -70,6 +73,7 @@ export class FrameworkLauncher {
       state.companionPath,
       state.config,
     );
+    await this.runCapabilityPreflight(state, request.tool);
     await state.adapter.validateLaunch(adapterContext);
 
     return {
@@ -127,6 +131,54 @@ export class FrameworkLauncher {
     };
   }
 
+  private async runCapabilityPreflight(
+    state: ResolvedLaunchState,
+    providerId: string,
+  ): Promise<void> {
+    const context: LaunchPreflightContext = {
+      companionPath: state.companionPath,
+      config: state.config,
+      repository: state.repository,
+      providerId,
+    };
+    const preflights = getActiveDistribution()
+      .registry.getAll()
+      .reduce<
+        Array<{
+          capability: CapabilityPlugin;
+          preflight: NonNullable<NonNullable<CapabilityPlugin["forProvider"]>[string]["preflight"]>;
+        }>
+      >((entries, plugin) => {
+        if (plugin.kind !== "capability" || !plugin.isEnabled(state.config)) return entries;
+        const capability = plugin as CapabilityPlugin;
+        const preflight = capability.forProvider?.[providerId]?.preflight;
+        if (preflight) entries.push({ capability, preflight });
+        return entries;
+      }, []);
+    const results = await Promise.all(
+      preflights.map(async ({ capability, preflight }) => {
+        try {
+          return await preflight(context);
+        } catch (error) {
+          const detail = error instanceof Error ? error.message : String(error);
+          throw new LaunchPreflightError(
+            `Capability preflight failed for ${capability.id} on ${providerId}: ${detail}`,
+            { cause: error },
+          );
+        }
+      }),
+    );
+    const diagnostics = results.flat();
+
+    if (diagnostics.length > 0) {
+      throw new LaunchPreflightError(
+        ["Capability launch preflight failed.", ...diagnostics.map((item) => `- ${item}`)].join(
+          "\n",
+        ),
+      );
+    }
+  }
+
   private async resolveConfig(): Promise<LaunchContext> {
     return resolveForLaunch(process.cwd());
   }

package/src/lib/orchestrator/setup-compatibilities.ts

@@ -193,6 +193,14 @@ export const BUILTIN_SETUP_COMPATIBILITIES: SetupCompatibility[] = [
     description: "Wrap supported agent launches through Headroom when the binary is installed.",
     defaultSelected: false,
   },
+  {
+    id: "rtk",
+    kind: "capability",
+    capability: { name: "rtk" },
+    label: "RTK",
+    description: "Patch supported agent providers with RTK independently from Headroom.",
+    defaultSelected: false,
+  },
   {
     id: "graphify",
     kind: "capability",

package/src/lib/orchestrator/types.ts

@@ -86,6 +86,7 @@ export interface FrameworkConfig {
   git?: GitModeProfile;
   profiles: Record<string, PolicyProfile>;
   capabilities?: CapabilityConfig[];
+  migrations?: string[];
   cliTools?: CliToolConfig[];
   packageManagers?: string[];
   engines?: EngineConstraints;

package/src/opencode/companion-hooks.ts

@@ -211,7 +211,7 @@ function appendOpenSpecFinishNudge(
   const nudges = uniqueChanges.map(
     (change) =>
       `ACTION REQUIRED: An openspec change (${change}) was just archived. ` +
-      `Immediately invoke the mate-openspec-artifact-finish skill to complete the finish pipeline ` +
+      `Immediately invoke the mate-artifact-finish skill to complete the finish pipeline ` +
       "(invoke the CLI as `mate`, never through a companion-local wrapper path or as `" +
       "$MATE_COMPANION_BIN_PATH/mate`). " +
       "`mate artifact finish` resumes from the already-archived change and completes the commit, dated tag, and push itself — " +

package/src/plugins.ts

@@ -12,5 +12,7 @@ export { createOpenspecPlugin } from "./tools/setup/capabilities/openspec";
 export { createReactDoctorPlugin } from "./tools/setup/capabilities/react-doctor";
 export { createTokensavePlugin } from "./tools/setup/capabilities/tokensave";
 export { createHeadroomPlugin } from "./tools/setup/capabilities/headroom";
+export { createRtkPlugin } from "./tools/setup/capabilities/rtk";
 export { createGraphifyPlugin } from "./tools/setup/capabilities/graphify";
+export { createContextModePlugin } from "./tools/setup/capabilities/context-mode";
 export { createGitignorePlugin } from "./tools/setup/plugins/gitignore";

package/src/templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh

@@ -0,0 +1,160 @@
+#!/bin/sh
+set -u
+
+input_file=$(mktemp "${TMPDIR:-/tmp}/mate-artifact-finish.XXXXXX")
+trap 'rm -f "$input_file"' EXIT
+cat >"$input_file"
+
+node -e '
+const fs = require("node:fs");
+
+const inputFile = process.argv[1];
+const archivePathPattern = /(?:^|[\s\/"\x27`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^\/\s"\x27`,)]+)/;
+
+function shellSplit(command) {
+  const parts = [];
+  const singleQuote = String.fromCharCode(39);
+  let current = "";
+  let quote = null;
+  let escaping = false;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\" && quote !== singleQuote) {
+      const next = command[index + 1] || "";
+      if (next === "\\" || /\s/.test(next) || next === singleQuote || next === String.fromCharCode(34)) {
+        escaping = true;
+        continue;
+      }
+    }
+    if ((char === singleQuote || char === String.fromCharCode(34)) && !quote) {
+      quote = char;
+      continue;
+    }
+    if (quote === char) {
+      quote = null;
+      continue;
+    }
+    const next = command[index + 1] || "";
+    const previous = command[index - 1] || "";
+    const isControlOperator = !quote && (
+      char === ";" || char === "|" ||
+      (char === "&" && next !== ">" && previous !== ">" && previous !== "<")
+    );
+    if (isControlOperator) {
+      if (current) parts.push(current);
+      current = "";
+      if ((char === "|" || char === "&") && next === char) {
+        parts.push(char + next);
+        index += 1;
+      } else {
+        parts.push(char);
+      }
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+function extractChangeFromPath(value) {
+  const match = value.replace(/\\/g, "/").match(archivePathPattern);
+  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
+}
+
+// Shell syntax tokens are never change-name positionals: separators end the
+// archive invocation, redirections are skipped (a bare operator also consumes
+// its target token).
+const separatorPattern = /^(\|\|?|&&?|;)$/;
+const redirectionPattern = /^(\d*(>>?|<)|&>>?)/;
+const bareRedirectionPattern = /^(\d*(>>?|<)|&>>?)$/;
+
+function extractArchiveCommand(command) {
+  const parts = shellSplit(command);
+  const index = parts.findIndex((part, position) =>
+    part === "archive" && position > 0 &&
+    (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")));
+  if (index < 0) return null;
+  for (let position = index + 1; position < parts.length; position += 1) {
+    const part = parts[position];
+    if (!part || part === "--") continue;
+    if (separatorPattern.test(part)) return null;
+    if (redirectionPattern.test(part)) {
+      if (bareRedirectionPattern.test(part)) position += 1;
+      continue;
+    }
+    if (part.startsWith("-")) {
+      if (part === "--store") position += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+function extractMoveCommand(command) {
+  const parts = shellSplit(command);
+  const moveCommands = new Set([
+    "mv", "move", "move-item", "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
+  ]);
+  const isPython = (part) => /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
+  for (let index = 0; index < parts.length; index += 1) {
+    if (moveCommands.has(parts[index].toLowerCase())) {
+      for (const part of parts.slice(index + 1)) {
+        const change = extractChangeFromPath(part);
+        if (change) return change;
+      }
+    }
+    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
+      return extractChangeFromPath(command);
+    }
+  }
+  return null;
+}
+
+// Nudge only on apparent success: stay silent on a clear failure indication,
+// nudge when success is indicated or indeterminate.
+function isClearFailure(response) {
+  if (!response || typeof response !== "object") return false;
+  if (response.success === false || response.is_error === true) return true;
+  if (typeof response.error === "string" && response.error) return true;
+  if (response.interrupted === true) return true;
+  const exitCode = response.exit_code ?? response.exitCode;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
+let input = {};
+try {
+  input = JSON.parse(fs.readFileSync(inputFile, "utf8") || "{}");
+} catch {}
+
+if (input.hook_event_name !== "PostToolUse" || input.tool_name !== "Bash") process.exit(0);
+const command = input.tool_input && typeof input.tool_input.command === "string"
+  ? input.tool_input.command
+  : "";
+const change = extractArchiveCommand(command) || extractMoveCommand(command);
+if (!change) process.exit(0);
+if (isClearFailure(input.tool_response)) process.exit(0);
+
+const context =
+  "OpenSpec change " + change + " was just archived. Invoke the mate-artifact-finish " +
+  "skill, then run `mate artifact finish \"" + change + "\" --json` to complete the " +
+  "finish workflow (commit, tag, and push).";
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: context,
+  },
+}));
+' "$input_file"
+exit 0

package/src/templates/capabilities/openspec-cap/mate-skills/{mate-openspec-artifact-finish → mate-artifact-finish}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mate-openspec-artifact-finish
+name: mate-artifact-finish
 description: Finish a completed artifact in one step via `mate artifact finish`. Use when the user wants to finish, ship, or archive-and-push a completed artifact and anchor it with a dated revert tag.
 allowed-tools: Bash(mate:*), Bash(git:*), Bash(openspec:*)
 license: MIT

package/src/templates/capabilities/openspec-cap/mate-skills/{mate-openspec-artifact-finish → mate-artifact-finish}/references/openspec.md

@@ -1,6 +1,6 @@
 # OpenSpec Finish Reference
 
-Use this reference when you need the OpenSpec-specific parts of `mate-openspec-artifact-finish`: change lookup, resumable archive behavior, JSON field meanings, and conflict recovery.
+Use this reference when you need the OpenSpec-specific parts of `mate-artifact-finish`: change lookup, resumable archive behavior, JSON field meanings, and conflict recovery.
 
 ## OpenSpec Input Rules