@uniqbit/mate-core 0.15.4-canary.6 → 0.15.4-canary.7

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "mate",
+  "description": "Mate-managed Claude Code hooks: artifact-path guardrail, session banner, and the OpenSpec archive-finish nudge. Ships inside @uniqbit/mate-core and is loaded per managed launch via --plugin-dir; it is never published separately."
+}

package/claude-plugin/hooks/artifact-finish-nudge.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/artifact-finish-nudge.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/artifact-finish-nudge.ts";
+
+process.exitCode = await run();

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner, PostToolUse OpenSpec archive-finish nudge (self-gated at runtime)",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/validate-artifact-path.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-banner.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/artifact-finish-nudge.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin/hooks/session-banner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/session-banner.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/session-banner.ts";
+
+process.exitCode = run();

package/claude-plugin/hooks/validate-artifact-path.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin shim: hook logic lives in src/hooks/validate-artifact-path.ts
+// (loaded via node's native TypeScript type stripping, engines node >= 24).
+import { run } from "../../src/hooks/validate-artifact-path.ts";
+
+process.exitCode = await run();

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.4-canary.6",
+  "version": "0.15.4-canary.7",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
     "src/",
     "wrappers/",
+    "claude-plugin/",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx"
   ],

package/src/cli/main.ts

@@ -128,7 +128,7 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       // Declares into framework.yaml and installs on the spot, so it needs
       // the same gating as `install` — an unambiguous companion, but must
       // stay runnable when installation is otherwise incomplete.
-      if (!(await gate({ companion: true }))) return;
+      if (!(await gate({ updateGuard: true }))) return;
       await runPluginCommand(subcommand, rest);
       return;
     case "artifact":

package/src/hooks/artifact-finish-nudge.ts

@@ -0,0 +1,212 @@
+// Nudge the agent into the mate-artifact-finish workflow after a Bash command
+// visibly archived an OpenSpec change. Stateless PostToolUse hook: never denies
+// or blocks; emits additionalContext only on apparent success.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface NudgeOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+const ARCHIVE_PATH_PATTERN =
+  /(?:^|[\s/"'`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^/\s"'`,)]+)/;
+
+// The nudge only applies when the openspec capability is enabled and OpenSpec
+// git auto mode is on; the plugin registers the hook unconditionally, so the
+// gate is evaluated here from launch-injected environment before any parsing.
+export function isGateEnabled(env: HookEnv): boolean {
+  return env.MATE_OPENSPEC_ENABLED === "1" && env.MATE_GIT_AUTO_MODE === "1";
+}
+
+export function shellSplit(command: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: string | null = 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 !== "'") {
+      const next = command[index + 1] || "";
+      if (next === "\\" || /\s/.test(next) || next === "'" || next === '"') {
+        escaping = true;
+        continue;
+      }
+    }
+    if ((char === "'" || char === '"') && !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: string): string | null {
+  const match = value.replaceAll("\\", "/").match(ARCHIVE_PATH_PATTERN);
+  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 SEPARATOR_PATTERN = /^(\|\|?|&&?|;)$/;
+const REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)/;
+const BARE_REDIRECTION_PATTERN = /^(\d*(>>?|<)|&>>?)$/;
+
+export function extractArchiveCommand(command: string): string | null {
+  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 (SEPARATOR_PATTERN.test(part)) return null;
+    if (REDIRECTION_PATTERN.test(part)) {
+      if (BARE_REDIRECTION_PATTERN.test(part)) position += 1;
+      continue;
+    }
+    if (part.startsWith("-")) {
+      if (part === "--store") position += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+const MOVE_COMMANDS = new Set([
+  "mv",
+  "move",
+  "move-item",
+  "cmd",
+  "cmd.exe",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "pwsh.exe",
+]);
+
+function isPython(part: string): boolean {
+  return /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() || part);
+}
+
+export function extractMoveCommand(command: string): string | null {
+  const parts = shellSplit(command);
+  for (let index = 0; index < parts.length; index += 1) {
+    if (MOVE_COMMANDS.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.
+export function isClearFailure(response: unknown): boolean {
+  if (!response || typeof response !== "object") return false;
+  const value = response as Record<string, unknown>;
+  if (value.success === false || value.is_error === true) return true;
+  if (typeof value.error === "string" && value.error) return true;
+  if (value.interrupted === true) return true;
+  const exitCode = value.exit_code ?? value.exitCode;
+  return typeof exitCode === "number" && exitCode !== 0;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): NudgeOutcome {
+  const silent: NudgeOutcome = { exitCode: 0, stdout: "" };
+  if (!isGateEnabled(env)) return silent;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  if (input.hook_event_name !== "PostToolUse" || input.tool_name !== "Bash") return silent;
+
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const change = extractArchiveCommand(command) || extractMoveCommand(command);
+  if (!change) return silent;
+  if (isClearFailure(input.tool_response)) return silent;
+
+  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).";
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: context,
+      },
+    }),
+  };
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry. The gate check precedes stdin parsing so a disabled gate
+// costs one env read.
+export async function run(): Promise<number> {
+  if (!isGateEnabled(process.env)) return 0;
+
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/session-banner.ts

@@ -0,0 +1,25 @@
+// Show the active Mate companion paths in Claude Code.
+import type { HookEnv } from "./validate-artifact-path";
+
+export interface BannerOutcome {
+  exitCode: number;
+  stdout: string;
+}
+
+// Fail-soft outside managed sessions: no MATE_* env, no banner.
+export function buildBanner(env: HookEnv): BannerOutcome {
+  const repoPath = env.MATE_REPO_PATH;
+  const artifactPath = env.MATE_ARTIFACT_PATH;
+  if (!repoPath || !artifactPath) return { exitCode: 0, stdout: "" };
+
+  const mateVersion = env.MATE_VERSION || "unknown";
+  const message = `mate v${mateVersion}\n  repo:     ${repoPath}\n  mate: ${artifactPath}`;
+  return { exitCode: 0, stdout: JSON.stringify({ systemMessage: message }) + "\n" };
+}
+
+// Plugin-shim entry.
+export function run(): number {
+  const outcome = buildBanner(process.env);
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  return outcome.exitCode;
+}

package/src/hooks/validate-artifact-path.ts

@@ -0,0 +1,236 @@
+// Block artifact writes outside the companion framework path.
+//
+// Artifact-like files may be written in the working repository only when the
+// target path is already ignored by git. That keeps local-only scratch files
+// possible without weakening the default repo split.
+//
+// Editing a file that already exists is always allowed: the guard exists to
+// stop new agent artifacts from landing in the working repo, not to freeze
+// files that are already part of it.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type HookEnv = Record<string, string | undefined>;
+
+export interface HookOutcome {
+  exitCode: number;
+  stderr: string;
+}
+
+const KNOWN_ARTIFACT_BASENAMES = new Set([
+  "CLAUDE.md",
+  "CONTEXT.md",
+  "design.md",
+  "explore-brief.md",
+  "proposal.md",
+  "spec.md",
+  "tasks.md",
+]);
+
+const ARTIFACT_PATH_MARKERS = [
+  "/changes/",
+  "/openspec/",
+  "/specs/",
+  "/docs/adr/",
+  "/docs/adrs/",
+  "/docs/decisions/",
+  "/docs/prd/",
+];
+
+const MD_REDIRECT_PATTERN = />{1,2}\s*([^\s;|&<>]+\.md)\b/g;
+const MD_TEE_PATTERN = /\btee\s+(?:-a\s+)?([^\s;|&<>]+\.md)\b/g;
+
+export function artifactLikePath(filePath: string): boolean {
+  if (!filePath) return false;
+
+  const basename = path.basename(filePath);
+  const normalized = "/" + filePath.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (KNOWN_ARTIFACT_BASENAMES.has(basename)) return true;
+
+  if (ARTIFACT_PATH_MARKERS.some((marker) => normalized.includes(marker))) return true;
+
+  if (basename.endsWith(".md") && basename !== "README.md") return true;
+
+  return false;
+}
+
+function repoRoot(env: HookEnv): string {
+  return env.MATE_REPO_PATH || process.cwd();
+}
+
+function companionRoot(env: HookEnv): string | null {
+  const companion = env.MATE_ARTIFACT_PATH;
+  return companion ? path.normalize(companion) : null;
+}
+
+// Claude Code's own config/state directory (plan files, settings, todos).
+// Writes there are agent-runtime state, never Mate artifacts.
+function claudeConfigRoot(env: HookEnv): string {
+  const configured = env.CLAUDE_CONFIG_DIR;
+  if (configured) return path.normalize(configured);
+  return path.normalize(path.join(env.HOME || os.homedir(), ".claude"));
+}
+
+function normalizePath(filePath: string, env: HookEnv): string {
+  if (path.isAbsolute(filePath)) return path.normalize(filePath);
+  return path.normalize(path.join(repoRoot(env), filePath));
+}
+
+function isUnder(target: string, root: string): boolean {
+  const relative = path.relative(path.normalize(root), path.normalize(target));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isGitignored(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "check-ignore", "--no-index", "-q", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+// A file already tracked in the working repo is product code being edited,
+// not a new agent artifact (e.g. packaged SKILL.md/spec.md template sources).
+function isGitTracked(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const result = spawnSync("git", ["-C", root, "ls-files", "--error-unmatch", "--", relPath], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+function isProductDocumentationPath(target: string, env: HookEnv): boolean {
+  const root = repoRoot(env);
+  if (!isUnder(target, root)) return false;
+
+  const relPath = path.relative(root, target);
+  const parts = relPath.split(path.sep).filter(Boolean);
+  for (const [index, part] of parts.entries()) {
+    if (part === ".storybook" || part === "storybook") return true;
+
+    if (part !== "docs") continue;
+
+    const docsRoot = path.join(root, ...parts.slice(0, index + 1));
+    if (fs.existsSync(path.join(docsRoot, "package.json"))) return true;
+  }
+
+  return false;
+}
+
+function blockWrite(target: string, companion: string): HookOutcome {
+  const lines = [
+    "Mate guardrail: artifact writes must go to the companion framework path.",
+    ` target: ${target}`,
+    ` companion: ${companion}`,
+    "Use an absolute path under MATE_ARTIFACT_PATH instead.",
+  ];
+  if (path.basename(target) === "CLAUDE.md") {
+    lines.push(`Note: CLAUDE.md already lives in the companion repo at ${companion}/CLAUDE.md.`);
+  }
+  return { exitCode: 2, stderr: lines.join("\n") + "\n" };
+}
+
+function checkFilePath(
+  filePath: string,
+  companion: string | null,
+  env: HookEnv,
+  allowExisting = false,
+): HookOutcome | null {
+  if (!filePath || !companion) return null;
+
+  const normalized = normalizePath(filePath, env);
+  if (normalized.startsWith(companion)) return null;
+
+  if (isUnder(normalized, claudeConfigRoot(env))) return null;
+
+  if (allowExisting && fs.existsSync(normalized) && fs.statSync(normalized).isFile()) return null;
+
+  if (isProductDocumentationPath(normalized, env)) return null;
+
+  if (!artifactLikePath(filePath)) return null;
+
+  if (
+    isUnder(normalized, repoRoot(env)) &&
+    (isGitignored(normalized, env) || isGitTracked(normalized, env))
+  ) {
+    return null;
+  }
+
+  return blockWrite(filePath, companion);
+}
+
+export function commandMatches(command: string): string[] {
+  const targets: string[] = [];
+  for (const pattern of [MD_REDIRECT_PATTERN, MD_TEE_PATTERN]) {
+    const matcher = new RegExp(pattern.source, pattern.flags);
+    for (const match of command.matchAll(matcher)) {
+      const target = match[1].trim().replace(/^["']+|["']+$/g, "");
+      if (target) targets.push(target);
+    }
+  }
+  return targets;
+}
+
+export function evaluate(payload: unknown, env: HookEnv): HookOutcome {
+  const allow: HookOutcome = { exitCode: 0, stderr: "" };
+
+  const companion = companionRoot(env);
+  if (!companion) return allow;
+
+  const input = payload && typeof payload === "object" ? (payload as Record<string, unknown>) : {};
+  const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+  const toolInput =
+    input.tool_input && typeof input.tool_input === "object"
+      ? (input.tool_input as Record<string, unknown>)
+      : {};
+
+  if (toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    const outcome = checkFilePath(
+      String(toolInput.file_path ?? ""),
+      companion,
+      env,
+      toolName === "Edit" || toolName === "MultiEdit",
+    );
+    return outcome ?? allow;
+  }
+
+  if (toolName === "Bash") {
+    const command = String(toolInput.command ?? "");
+    for (const target of commandMatches(command)) {
+      const outcome = checkFilePath(target, companion, env);
+      if (outcome) return outcome;
+    }
+    return allow;
+  }
+
+  return allow;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Plugin-shim entry: read the hook payload from stdin, evaluate, report.
+export async function run(): Promise<number> {
+  let payload: unknown = {};
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    payload = {};
+  }
+  const outcome = evaluate(payload, process.env);
+  if (outcome.stderr) process.stderr.write(outcome.stderr);
+  return outcome.exitCode;
+}

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

@@ -83,6 +83,7 @@ export abstract class LaunchAdapter {
       MATE_WRAPPER_BIN_PATH: wrapperBinPath,
       PATH: prependPathEntry(process.env.PATH, wrapperBinPath),
       MATE_GRAPHIFY_ENABLED: context.capabilities.some((c) => c.name === "graphify") ? "1" : "0",
+      MATE_OPENSPEC_ENABLED: context.capabilities.some((c) => c.name === "openspec") ? "1" : "0",
       MATE_REACT_DOCTOR_ENABLED: reactDoctorEnabled ? "1" : "0",
       MATE_GIT_AUTO_MODE: context.git === "auto" ? "1" : "0",
       MATE_REPO_ID: context.repository.id,

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

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 
 import { buildCompanionGuidance } from "../../../playbooks/companion-guidance";
 import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
+import { getClaudePluginRoot, validateClaudePluginAssets } from "../../package-paths";
 import {
   getCompanionClaudeMcpConfigPath,
   getCompanionClaudeSettingsPath,
@@ -13,6 +14,17 @@ export class ClaudeAdapter extends LaunchAdapter {
   readonly interactive = true;
 
   async validateLaunch(context: AdapterContext): Promise<void> {
+    // The bundled mate plugin carries the artifact-path guard; never launch a
+    // managed session without it.
+    try {
+      validateClaudePluginAssets();
+    } catch (error) {
+      throw new Error(
+        `Mate Claude plugin is unavailable: ${(error as Error).message}. Reinstall mate to repair it.`,
+        { cause: error },
+      );
+    }
+
     if (context.capabilities.some((capability) => capability.name === "context-mode")) {
       try {
         await validateContextModePackage(context.companionPath);
@@ -56,6 +68,10 @@ export class ClaudeAdapter extends LaunchAdapter {
       buildCompanionGuidance(context),
       ...settingsArgs,
       ...mcpConfigArgs,
+      // Bundled mate plugin (hooks) resolved from the running mate-core
+      // installation, coexisting with the context-mode plugin dir.
+      "--plugin-dir",
+      getClaudePluginRoot(),
       ...contextModeArgs,
       ...args,
     ];

package/src/lib/package-paths.ts

@@ -18,6 +18,42 @@ export function getWrapperBinPath(): string {
   return path.resolve(import.meta.dirname, "../../wrappers/bin");
 }
 
+/**
+ * Resolved bundled Claude plugin root: a distribution asset root that ships
+ * `claude-plugin/` wins over core's bundled default. Loaded per managed
+ * launch via `claude --plugin-dir`, so hooks always match the installed
+ * mate-core version.
+ */
+export function getClaudePluginRoot(): string {
+  for (const root of getActiveDistribution().config.assetRoots ?? []) {
+    const candidate = path.join(root, "claude-plugin");
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return path.resolve(import.meta.dirname, "../../claude-plugin");
+}
+
+export const CLAUDE_PLUGIN_HOOK_SHIMS = [
+  "validate-artifact-path.mjs",
+  "session-banner.mjs",
+  "artifact-finish-nudge.mjs",
+] as const;
+
+/**
+ * Verify the bundled Claude plugin assets exist. Throws naming the missing
+ * assets; managed launches must not start without the artifact-path guard.
+ */
+export function validateClaudePluginAssets(pluginRoot = getClaudePluginRoot()): void {
+  const expected = [
+    path.join(".claude-plugin", "plugin.json"),
+    path.join("hooks", "hooks.json"),
+    ...CLAUDE_PLUGIN_HOOK_SHIMS.map((shim) => path.join("hooks", shim)),
+  ];
+  const missing = expected.filter((asset) => !fs.existsSync(path.join(pluginRoot, asset)));
+  if (missing.length > 0) {
+    throw new Error(`bundled Claude plugin at ${pluginRoot} is missing: ${missing.join(", ")}`);
+  }
+}
+
 export function getReactDoctorBinPath(): string {
   try {
     const entryPath = require.resolve("react-doctor");

package/src/tools/setup/capabilities/openspec.ts

@@ -39,11 +39,6 @@ const MATE_V1_SCHEMA_SOURCE = path.join(
   "../../../templates/capabilities/openspec-cap/mate-v1",
 );
 
-const CLAUDE_HOOK_SOURCE = path.join(
-  import.meta.dirname,
-  "../../../templates/capabilities/openspec-cap/claude/hooks/mate-artifact-finish.sh",
-);
-
 const OPENSPEC_TOOL_DIRS = {
   claude: ".claude",
   opencode: ".opencode",
@@ -347,19 +342,10 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     },
     forProvider: {
       claude: {
+        // The archive-finish nudge hook ships in the bundled mate Claude
+        // plugin and self-gates at runtime; openspec no longer contributes a
+        // Claude hook file. Only legacy per-session nudge state is migrated.
         async apply(ctx: SetupContext) {
-          if (ctx.config.git !== "auto") {
-            return;
-          }
-          const hookDest = path.join(
-            ctx.companionPath,
-            ".claude",
-            "hooks",
-            "mate-artifact-finish.sh",
-          );
-          await fs.mkdir(path.dirname(hookDest), { recursive: true });
-          await fs.copyFile(CLAUDE_HOOK_SOURCE, hookDest);
-          await fs.chmod(hookDest, 0o755);
           const stateDir = path.join(ctx.companionPath, ".claude", "state");
           try {
             const entries = await fs.readdir(stateDir);
@@ -374,17 +360,6 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
           }
         },
         async teardown(ctx: SetupContext) {
-          try {
-            await fs.unlink(
-              path.join(ctx.companionPath, ".claude", "hooks", "mate-artifact-finish.sh"),
-            );
-          } catch {
-            /* not present */
-          }
-          await pruneEmptyAncestors(
-            path.join(ctx.companionPath, ".claude", "hooks"),
-            ctx.companionPath,
-          );
           await teardownToolRuntime(ctx.companionPath, "claude");
         },
       },

package/src/tools/setup/providers/claude.ts

@@ -10,8 +10,8 @@ import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
 import { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "../capabilities/tokensave-shared";
 import type { McpServerDescriptor, ProviderPlugin, SetupContext } from "../plugin";
 import { resolveGitInfoExcludePath } from "../git-utils";
-import { mergeDir, pruneEmptyAncestors, resolveCommandOnPath } from "../utils";
-import { getSetupProvidersRoot, getSetupRootTemplates } from "./utils";
+import { pruneEmptyAncestors, resolveCommandOnPath } from "../utils";
+import { getSetupRootTemplates } from "./utils";
 
 async function configureClaudeGuidance(companionPath: string): Promise<void> {
   const rootTemplates = getSetupRootTemplates();
@@ -43,6 +43,10 @@ const ALL_MANAGED_EXCLUDE_ENTRIES = new Set([
 ]);
 
 // Command substrings that mark a working-repo hook group as Mate-managed.
+// The mate plugin hooks (validate-artifact-path, mate-session-banner,
+// mate-artifact-finish.sh) now ship in the bundled Claude plugin; their
+// markers are retained migration-only so stale managed groups written by
+// earlier releases keep being stripped, and are never re-added.
 const MANAGED_HOOK_MARKERS = [
   "validate-artifact-path",
   "mate-session-banner",
@@ -51,6 +55,26 @@ const MANAGED_HOOK_MARKERS = [
   "tokensave",
 ];
 
+// Hook files earlier releases copied into the companion; the bundled Claude
+// plugin replaced them. Setup and launch sync delete stale copies.
+const LEGACY_MATE_HOOK_FILES = [
+  "validate-artifact-path",
+  "mate-session-banner",
+  "mate-artifact-finish.sh",
+];
+
+async function removeLegacyMateHookFiles(companionPath: string): Promise<void> {
+  const hooksDir = path.join(companionPath, ".claude", "hooks");
+  for (const name of LEGACY_MATE_HOOK_FILES) {
+    try {
+      await fs.unlink(path.join(hooksDir, name));
+    } catch {
+      /* not present */
+    }
+  }
+  await pruneEmptyAncestors(hooksDir, companionPath);
+}
+
 // Base `permissions.allow` entries that Claude gets for Mate-managed workflows.
 // Read/Edit are scoped to the companion path so routine reads and artifact
 // writes of skills, specs, and change artifacts don't prompt for approval on
@@ -260,39 +284,13 @@ function buildManagedClaudeSettings(
 ): WorkingRepoSettings {
   const capabilities = config.capabilities ?? [];
   const enabledNames = new Set(capabilities.map((c) => c.name));
-  const openspecEnabled = enabledNames.has("openspec") && config.git === "auto";
   const reactDoctorEnabled = enabledNames.has("react-doctor");
 
+  // Mate's own hooks (artifact-path guard, session banner, archive-finish
+  // nudge) ship in the bundled Claude plugin loaded at launch; settings-sync
+  // only strips their legacy managed groups (via removeManagedHookGroups) and
+  // reconciles the capability hooks that remain settings-delivered.
   const hooks = removeManagedHookGroups(existing).hooks ?? {};
-  hooks.PreToolUse = [
-    {
-      matcher: "Write|Edit|MultiEdit|Bash",
-      hooks: [
-        { type: "command", command: `${companionPath}/.claude/hooks/validate-artifact-path` },
-      ],
-    },
-    ...(hooks.PreToolUse ?? []),
-  ];
-  hooks.SessionStart = [
-    {
-      hooks: [{ type: "command", command: `${companionPath}/.claude/hooks/mate-session-banner` }],
-    },
-    ...(hooks.SessionStart ?? []),
-  ];
-  if (openspecEnabled) {
-    hooks.PostToolUse = [
-      {
-        matcher: "Bash",
-        hooks: [
-          {
-            type: "command",
-            command: `sh "${companionPath}/.claude/hooks/mate-artifact-finish.sh"`,
-          },
-        ],
-      },
-      ...(hooks.PostToolUse ?? []),
-    ];
-  }
   if (reactDoctorEnabled) {
     // Record edits cheaply, then scan once when the edited turn finishes.
     hooks.PostToolUse = [
@@ -377,6 +375,9 @@ function buildManagedClaudeSettings(
   delete mcpServers.tokensave;
 
   const settings: WorkingRepoSettings = { ...existing, hooks, autoMemoryEnabled: false };
+  if (Object.keys(hooks).length === 0) {
+    delete settings.hooks;
+  }
   if (Object.keys(permissions).length > 0) {
     settings.permissions = permissions;
   } else {
@@ -512,8 +513,11 @@ async function syncWorkingRepoClaudeAdditionalDirectories(
   await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
 }
 
-async function configureClaude(src: string, companionPath: string): Promise<void> {
-  await mergeDir(path.join(src, ".claude"), path.join(companionPath, ".claude"));
+async function configureClaude(companionPath: string): Promise<void> {
+  // Mate hooks are delivered by the bundled Claude plugin at launch; nothing
+  // is copied into `companion/.claude/hooks/` anymore. Stale copies from
+  // earlier releases are stripped so only the plugin-shipped hooks run.
+  await removeLegacyMateHookFiles(companionPath);
 
   // Note: `.claude/settings.local.json` is now Mate-owned and generated by
   // `syncCompanionClaudeSettings`; do not delete it here. `settings.json` is
@@ -524,16 +528,6 @@ async function configureClaude(src: string, companionPath: string): Promise<void
     /* not present */
   }
 
-  const hooksDir = path.join(companionPath, ".claude", "hooks");
-  try {
-    const entries = await fs.readdir(hooksDir);
-    for (const entry of entries) {
-      await fs.chmod(path.join(hooksDir, entry), 0o755);
-    }
-  } catch {
-    // hooks dir may not exist if no hooks are defined
-  }
-
   const agentsMdSrc = path.join(getSetupRootTemplates(), "TEMPLATE_AGENTS.md");
   const agentsMdDest = path.join(companionPath, "AGENTS.md");
   try {
@@ -552,17 +546,9 @@ async function configureClaude(src: string, companionPath: string): Promise<void
 }
 
 async function teardownClaude(companionPath: string, allowedAgents: string[]): Promise<void> {
-  try {
-    await fs.unlink(path.join(companionPath, ".claude", "hooks", "validate-artifact-path"));
-  } catch {
-    /* not present */
-  }
-  try {
-    await fs.unlink(path.join(companionPath, ".claude", "hooks", "mate-session-banner"));
-  } catch {
-    /* not present */
-  }
-  await pruneEmptyAncestors(path.join(companionPath, ".claude", "hooks"), companionPath);
+  // Migration-only: a companion last synced by a pre-plugin release may still
+  // carry copied mate hook files.
+  await removeLegacyMateHookFiles(companionPath);
   try {
     await fs.unlink(path.join(companionPath, ".claude", "settings.local.json"));
   } catch {
@@ -693,7 +679,7 @@ export function createClaudePlugin(): ProviderPlugin {
       },
     },
     async apply(ctx) {
-      await configureClaude(path.join(getSetupProvidersRoot(), "claude"), ctx.companionPath);
+      await configureClaude(ctx.companionPath);
       await configureClaudeGuidance(ctx.companionPath);
       await teardownLegacyClaudeBin(ctx.companionPath);
       await syncCompanionClaudeSettings(ctx.companionPath, ctx.config);

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

@@ -1,160 +0,0 @@
-#!/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/providers/claude/.claude/hooks/mate-session-banner

@@ -1,28 +0,0 @@
-#!/usr/bin/env python3
-"""Show the active Mate companion paths in Claude Code."""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-
-
-def main() -> int:
-    repo_path = os.environ.get("MATE_REPO_PATH")
-    artifact_path = os.environ.get("MATE_ARTIFACT_PATH")
-    if not repo_path or not artifact_path:
-        return 0
-
-    mate_version = os.environ.get("MATE_VERSION", "unknown")
-    message = (
-        f"mate v{mate_version}\n"
-        f"  repo:     {repo_path}\n"
-        f"  mate: {artifact_path}"
-    )
-    print(json.dumps({"systemMessage": message}))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/templates/providers/claude/.claude/hooks/validate-artifact-path

@@ -1,242 +0,0 @@
-#!/usr/bin/env python3
-"""Block artifact writes outside the companion framework path.
-
-Artifact-like files may be written in the working repository only when the
-target path is already ignored by git. That keeps local-only scratch files
-possible without weakening the default repo split.
-
-Editing a file that already exists is always allowed: the guard exists to
-stop new agent artifacts from landing in the working repo, not to freeze
-files that are already part of it.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import pathlib
-import re
-import subprocess
-import sys
-from typing import Any
-
-
-KNOWN_ARTIFACT_BASENAMES = {
-    "CLAUDE.md",
-    "CONTEXT.md",
-    "design.md",
-    "explore-brief.md",
-    "proposal.md",
-    "spec.md",
-    "tasks.md",
-}
-
-ARTIFACT_PATH_MARKERS = (
-    "/changes/",
-    "/openspec/",
-    "/specs/",
-    "/docs/adr/",
-    "/docs/adrs/",
-    "/docs/decisions/",
-    "/docs/prd/",
-)
-MD_REDIRECT_RE = re.compile(r">{1,2}\s*([^\s;|&<>]+\.md)\b")
-MD_TEE_RE = re.compile(r"\btee\s+(?:-a\s+)?([^\s;|&<>]+\.md)\b")
-
-
-def read_payload() -> dict[str, Any]:
-    try:
-        return json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return {}
-
-
-def artifact_like_path(file_path: str) -> bool:
-    if not file_path:
-        return False
-
-    basename = os.path.basename(file_path)
-    normalized = "/" + file_path.replace("\\", "/").lstrip("/")
-    if basename in KNOWN_ARTIFACT_BASENAMES:
-        return True
-
-    if any(marker in normalized for marker in ARTIFACT_PATH_MARKERS):
-        return True
-
-    if basename.endswith(".md") and basename != "README.md":
-        return True
-
-    return False
-
-
-def repo_root() -> str:
-    return os.environ.get("MATE_REPO_PATH") or os.getcwd()
-
-
-def companion_root() -> str | None:
-    companion = os.environ.get("MATE_ARTIFACT_PATH")
-    return os.path.normpath(companion) if companion else None
-
-
-def claude_config_root() -> str:
-    """Claude Code's own config/state directory (plan files, settings, todos).
-    Writes there are agent-runtime state, never Mate artifacts."""
-    configured = os.environ.get("CLAUDE_CONFIG_DIR")
-    if configured:
-        return os.path.normpath(configured)
-    return os.path.normpath(os.path.join(os.path.expanduser("~"), ".claude"))
-
-
-def normalize_path(file_path: str) -> str:
-    if os.path.isabs(file_path):
-        return os.path.normpath(file_path)
-    return os.path.normpath(os.path.join(repo_root(), file_path))
-
-
-def is_under(path: str, root: str) -> bool:
-    try:
-        return os.path.commonpath([os.path.normpath(path), os.path.normpath(root)]) == os.path.normpath(root)
-    except ValueError:
-        return False
-
-
-def is_gitignored(path: str) -> bool:
-    root = repo_root()
-    if not is_under(path, root):
-        return False
-
-    rel_path = os.path.relpath(path, root)
-    try:
-        result = subprocess.run(
-            ["git", "-C", root, "check-ignore", "--no-index", "-q", "--", rel_path],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-    except FileNotFoundError:
-        return False
-    return result.returncode == 0
-
-
-def is_git_tracked(path: str) -> bool:
-    """A file already tracked in the working repo is product code being edited,
-    not a new agent artifact (e.g. packaged SKILL.md/spec.md template sources)."""
-    root = repo_root()
-    if not is_under(path, root):
-        return False
-
-    rel_path = os.path.relpath(path, root)
-    try:
-        result = subprocess.run(
-            ["git", "-C", root, "ls-files", "--error-unmatch", "--", rel_path],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-    except FileNotFoundError:
-        return False
-    return result.returncode == 0
-
-
-def is_product_documentation_path(path: str) -> bool:
-    root = repo_root()
-    if not is_under(path, root):
-        return False
-
-    rel_path = os.path.relpath(path, root)
-    parts = pathlib.Path(rel_path).parts
-    for index, part in enumerate(parts):
-        if part in {".storybook", "storybook"}:
-            return True
-
-        if part != "docs":
-            continue
-
-        docs_root = os.path.join(root, *parts[: index + 1])
-        if os.path.exists(os.path.join(docs_root, "package.json")):
-            return True
-
-    return False
-
-
-def block_write(target: str, companion: str) -> None:
-    print("Mate guardrail: artifact writes must go to the companion framework path.", file=sys.stderr)
-    print(f" target: {target}", file=sys.stderr)
-    print(f" companion: {companion}", file=sys.stderr)
-    print("Use an absolute path under MATE_ARTIFACT_PATH instead.", file=sys.stderr)
-
-    if os.path.basename(target) == "CLAUDE.md":
-        print(
-            f"Note: CLAUDE.md already lives in the companion repo at {companion}/CLAUDE.md.",
-            file=sys.stderr,
-        )
-
-    raise SystemExit(2)
-
-
-def check_file_path(file_path: str, companion: str | None, allow_existing: bool = False) -> None:
-    if not file_path or not companion:
-        return
-
-    normalized = normalize_path(file_path)
-    if normalized.startswith(companion):
-        return
-
-    if is_under(normalized, claude_config_root()):
-        return
-
-    if allow_existing and os.path.isfile(normalized):
-        return
-
-    if is_product_documentation_path(normalized):
-        return
-
-    if not artifact_like_path(file_path):
-        return
-
-    if is_under(normalized, repo_root()) and (
-        is_gitignored(normalized) or is_git_tracked(normalized)
-    ):
-        return
-
-    block_write(file_path, companion)
-
-
-def command_matches(command: str) -> list[str]:
-    targets: list[str] = []
-    for pattern in (MD_REDIRECT_RE, MD_TEE_RE):
-        for match in pattern.finditer(command):
-            target = match.group(1).strip().strip('"\'')
-            if target:
-                targets.append(target)
-    return targets
-
-
-def main() -> int:
-    companion = companion_root()
-    if not companion:
-        return 0
-
-    payload = read_payload()
-    tool_name = payload.get("tool_name", "")
-    tool_input = payload.get("tool_input", {})
-
-    if tool_name in {"Write", "Edit", "MultiEdit"}:
-        check_file_path(
-            str(tool_input.get("file_path", "")),
-            companion,
-            allow_existing=tool_name in {"Edit", "MultiEdit"},
-        )
-        return 0
-
-    if tool_name == "Bash":
-        command = str(tool_input.get("command", ""))
-        for target in command_matches(command):
-            check_file_path(target, companion)
-        return 0
-
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())