@uniqbit/mate-core 0.15.3 → 0.15.4-canary.3

package/src/lib/orchestrator/framework-context.ts

@@ -1,14 +1,17 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
+import { parse } from "yaml";
 import { CompanionResolver } from "./companion-resolver";
 import { ConfigStore } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
-import { migrateConfigDir } from "./migration";
 import { findRepoLocalLinkedRepository } from "./repo-local-registry";
 import {
   AmbiguousCompanionError,
+  ConfigError,
+  type FrameworkConfig,
+  type HubConfig,
   type LinkedRepository,
   RepositoryNotFoundError,
   WorkingRepoRequiredError,
@@ -20,7 +23,8 @@ export interface FrameworkContext {
   workingRepoStore: WorkingRepoStore;
   companionPath: string;
   repository?: LinkedRepository;
-  contextKind: "env" | "working-repo" | "companion-root";
+  contextKind: "env" | "working-repo" | "companion-root" | "hub";
+  hub?: HubConfig;
 }
 
 export interface LaunchContext extends FrameworkContext {
@@ -44,6 +48,7 @@ function makeContext(
   companionPath: string,
   contextKind: FrameworkContext["contextKind"],
   repository?: LinkedRepository,
+  hub?: HubConfig,
 ): FrameworkContext {
   const configDir = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config");
   return {
@@ -52,9 +57,90 @@ function makeContext(
     companionPath,
     repository,
     contextKind,
+    hub,
   };
 }
 
+function isStrictChildPath(parentPath: string, candidatePath: string): boolean {
+  const relative = path.relative(parentPath, candidatePath);
+  return relative !== "" && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+}
+
+async function validateHubMember(
+  resolvedRoot: string,
+  realRoot: string,
+  member: HubConfig["companions"][number],
+): Promise<ConfigError | null> {
+  const memberPath = path.resolve(resolvedRoot, member.path);
+  if (!isStrictChildPath(resolvedRoot, memberPath)) {
+    return new ConfigError(
+      `Hub member "${member.id}" path resolves outside the hub root: ${member.path}`,
+    );
+  }
+
+  const stats = await fs.stat(memberPath).catch(() => null);
+  if (!stats?.isDirectory()) {
+    return new ConfigError(`Hub member "${member.id}" directory is missing: ${memberPath}`);
+  }
+
+  const realMemberPath = await fs.realpath(memberPath).catch(() => memberPath);
+  if (!isStrictChildPath(realRoot, realMemberPath)) {
+    return new ConfigError(
+      `Hub member "${member.id}" path resolves outside the hub root: ${member.path}`,
+    );
+  }
+
+  const childConfigPath = path.join(memberPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+  let childConfig: Partial<FrameworkConfig> | null;
+  try {
+    childConfig = parse(
+      await fs.readFile(childConfigPath, "utf8"),
+    ) as Partial<FrameworkConfig> | null;
+  } catch {
+    return new ConfigError(
+      `Hub member "${member.id}" must contain a framework.yaml declaring type "companion".`,
+    );
+  }
+
+  if (childConfig?.type !== "companion") {
+    return new ConfigError(
+      `Hub member "${member.id}" must declare type "companion" in ${childConfigPath}.`,
+    );
+  }
+
+  return null;
+}
+
+async function validateHubMembers(hubRoot: string, hub: HubConfig): Promise<void> {
+  const resolvedRoot = path.resolve(hubRoot);
+  const realRoot = await fs.realpath(resolvedRoot).catch(() => resolvedRoot);
+  const errors = await Promise.all(
+    hub.companions.map((member) => validateHubMember(resolvedRoot, realRoot, member)),
+  );
+  const firstError = errors.find((error): error is ConfigError => error !== null);
+  if (firstError) throw firstError;
+}
+
+async function withResolvedHub(context: FrameworkContext): Promise<FrameworkContext> {
+  let rawConfig: Partial<FrameworkConfig> | null;
+  try {
+    rawConfig = parse(
+      await fs.readFile(context.configStore.configPath, "utf8"),
+    ) as Partial<FrameworkConfig> | null;
+  } catch {
+    return context;
+  }
+
+  if (rawConfig?.type !== "hub") return context;
+
+  const config = await context.configStore.load();
+  if (!config.hub) {
+    throw new ConfigError('A "hub" framework requires a hub.companions array.');
+  }
+  await validateHubMembers(context.companionPath, config.hub);
+  return { ...context, contextKind: "hub", hub: config.hub };
+}
+
 // Resolves the companion framework context without a repositoryId. Used by commands
 // that only need companion config (e.g. `mate doctor`, `mate config`, `mate report`). Resolution order:
 // 1. MATE_ARTIFACT_PATH env var (agent-launched sessions)
@@ -67,31 +153,32 @@ export async function resolveFrameworkContext(
   const envCompanionPath = process.env.MATE_ARTIFACT_PATH;
   if (envCompanionPath) {
     const repository = repositoryFromEnvironment() ?? (await findRepoLocalLinkedRepository(cwd));
-    return makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined);
+    return withResolvedHub(
+      makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined),
+    );
   }
 
   const match = await new CompanionResolver(globalConfigStore).resolve(cwd);
   if (match) {
-    return makeContext(
-      match.companionPath,
-      "working-repo",
-      (await findRepoLocalLinkedRepository(cwd)) ?? undefined,
+    return withResolvedHub(
+      makeContext(
+        match.companionPath,
+        "working-repo",
+        (await findRepoLocalLinkedRepository(cwd)) ?? undefined,
+      ),
     );
   }
 
   const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
-  const localLegacyDirs = frameworkConfig.legacyNames.map((n) => path.join(cwd, `.${n}`));
-  await migrateConfigDir(localDir, localLegacyDirs);
 
   const localConfigPath = path.join(localDir, "config", "framework.yaml");
   try {
     await fs.access(localConfigPath);
-    return makeContext(cwd, "companion-root");
   } catch {
     // no local config
+    throw new RepositoryNotFoundError(`No companion found for current directory: ${cwd}`);
   }
-
-  throw new RepositoryNotFoundError(`No companion found for current directory: ${cwd}`);
+  return withResolvedHub(makeContext(cwd, "companion-root"));
 }
 
 // Resolves context for agent-launch commands. Returns a LaunchContext with repositoryId.
@@ -108,8 +195,11 @@ export async function resolveForLaunch(
   if (envCompanionPath) {
     const repository = repositoryFromEnvironment() ?? (await findRepoLocalLinkedRepository(cwd));
     const repositoryId = process.env.MATE_REPO_ID ?? repository?.id ?? "";
+    const context = await withResolvedHub(
+      makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined),
+    );
     return {
-      ...makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined),
+      ...context,
       repositoryId,
     };
   }
@@ -123,8 +213,11 @@ export async function resolveForLaunch(
 
   if (resolution.match) {
     const repository = (await findRepoLocalLinkedRepository(cwd)) ?? undefined;
+    const context = await withResolvedHub(
+      makeContext(resolution.match.companionPath, "working-repo", repository),
+    );
     return {
-      ...makeContext(resolution.match.companionPath, "working-repo", repository),
+      ...context,
       repositoryId: resolution.match.repositoryId,
     };
   }
@@ -143,7 +236,9 @@ export async function resolveForCapability(
   const envCompanionPath = process.env.MATE_ARTIFACT_PATH;
   if (envCompanionPath) {
     const repository = repositoryFromEnvironment() ?? (await findRepoLocalLinkedRepository(cwd));
-    const ctx = makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined);
+    const ctx = await withResolvedHub(
+      makeContext(path.resolve(envCompanionPath), "env", repository ?? undefined),
+    );
     const repositoryId = process.env.MATE_REPO_ID;
     if (repositoryId) {
       return { ...ctx, repositoryId };
@@ -158,12 +253,15 @@ export async function resolveForCapability(
 
   const match = await new CompanionResolver(globalConfigStore).resolve(cwd);
   if (match) {
-    return {
-      ...makeContext(
+    const context = await withResolvedHub(
+      makeContext(
         match.companionPath,
         "working-repo",
         (await findRepoLocalLinkedRepository(cwd)) ?? undefined,
       ),
+    );
+    return {
+      ...context,
       repositoryId: match.repositoryId,
     };
   }
@@ -171,16 +269,14 @@ export async function resolveForCapability(
   // Fallback: cwd is the companion directory — resolve from its local config.
   // This is specific to mate cap; resolveForLaunch does NOT get this fallback.
   const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
-  const localLegacyDirs = frameworkConfig.legacyNames.map((n) => path.join(cwd, `.${n}`));
-  await migrateConfigDir(localDir, localLegacyDirs);
 
   const localConfigPath = path.join(localDir, "config", "framework.yaml");
   try {
     await fs.access(localConfigPath);
-    return { ...makeContext(cwd, "companion-root"), repositoryId: process.env.MATE_REPO_ID ?? "" };
   } catch {
     // no local config
+    throw new WorkingRepoRequiredError("cap");
   }
-
-  throw new WorkingRepoRequiredError("cap");
+  const context = await withResolvedHub(makeContext(cwd, "companion-root"));
+  return { ...context, repositoryId: process.env.MATE_REPO_ID ?? "" };
 }

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

@@ -1,9 +1,8 @@
 import os from "node:os";
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { YamlFileStore } from "./yaml-file-store";
-import { migrateConfigDir } from "./migration";
 
 interface CompanionEntry {
   path: string;
@@ -35,9 +34,6 @@ export class GlobalConfigStore extends YamlFileStore<GlobalConfig> {
   }
 
   override async load(): Promise<GlobalConfig> {
-    const currentDir = path.dirname(this.configPath);
-    const legacyDirs = frameworkConfig.legacyNames.map((n) => path.join(os.homedir(), `.${n}`));
-    await migrateConfigDir(currentDir, legacyDirs);
     return normalizeGlobalConfig(await super.load());
   }
 

package/src/lib/orchestrator/migration.ts

@@ -1,6 +1,4 @@
-// oxlint-disable no-await-in-loop
 import fs from "node:fs/promises";
-import path from "node:path";
 
 import { parse, stringify } from "yaml";
 
@@ -18,24 +16,3 @@ export async function migrateRegistryData(filePath: string): Promise<void> {
     await fs.writeFile(filePath, stringify(rest), "utf8");
   }
 }
-
-export async function migrateConfigDir(currentDir: string, legacyDirs: string[]): Promise<void> {
-  try {
-    await fs.access(currentDir);
-    return;
-  } catch {
-    // current dir missing — check legacy locations
-  }
-
-  for (const legacyDir of legacyDirs) {
-    try {
-      await fs.access(legacyDir);
-      await fs.mkdir(path.dirname(currentDir), { recursive: true });
-      await fs.rename(legacyDir, currentDir);
-      process.stderr.write(`[migration] ${legacyDir} → ${currentDir}\n`);
-      return;
-    } catch {
-      // this legacy dir also absent, try next
-    }
-  }
-}

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

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { parse } from "yaml";
 
-import { FRAMEWORK_NAME, frameworkCommandName, frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { fileExists } from "../fs-utils";
 import { GlobalConfigStore } from "./global-config-store";
 import { CompanionResolver, type CompanionMatch } from "./companion-resolver";
@@ -126,20 +126,7 @@ export async function looksLikeWorkingRepo(cwd: string): Promise<boolean> {
 
 export async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
   const resolvedCwd = path.resolve(cwd);
-  const candidatePaths = [
-    path.join(resolvedCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
-    ...frameworkConfig.legacyNames.map((name) =>
-      path.join(resolvedCwd, `.${name}`, "config", "framework.yaml"),
-    ),
-  ];
-
-  for (const candidatePath of candidatePaths) {
-    if (await fileExists(candidatePath)) {
-      return true;
-    }
-  }
-
-  return false;
+  return fileExists(path.join(resolvedCwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
 }
 
 async function hasWorkingRepoConfig(cwd: string): Promise<boolean> {
@@ -190,7 +177,7 @@ export async function inspectSetupPreflight(
 
 export function formatSetupGuardrailError(cwd: string, match: CompanionMatch): string {
   return [
-    `\`${frameworkCommandName()} setup\` cannot run here: ${path.resolve(cwd)} is inside linked working repo \`${match.repositoryId}\`.`,
-    `Run \`${frameworkCommandName()} setup\` from the companion repo instead: ${match.companionPath}`,
+    `\`${FRAMEWORK_NAME} setup\` cannot run here: ${path.resolve(cwd)} is inside linked working repo \`${match.repositoryId}\`.`,
+    `Run \`${FRAMEWORK_NAME} setup\` from the companion repo instead: ${match.companionPath}`,
   ].join("\n");
 }

package/src/lib/orchestrator/types.ts

@@ -74,6 +74,26 @@ export interface CapabilityConfig {
   schemaProfile?: OpenSpecSchemaProfile;
 }
 
+export type FrameworkType = "working" | "companion" | "hub";
+
+export interface HubMemberSource {
+  kind: "git" | "local";
+  url?: string;
+  ref?: string;
+  path?: string;
+}
+
+export interface HubMember {
+  id: string;
+  path: string;
+  source: HubMemberSource;
+  materializedCommit?: string;
+}
+
+export interface HubConfig {
+  companions: HubMember[];
+}
+
 /**
  * Distribution-name-keyed semver ranges (e.g. `{ mate: ">=0.15.0" }` or
  * `{ "acme-mate": ">=1.2.0" }`). A running CLI only checks the key matching
@@ -88,9 +108,10 @@ export type EngineConstraints = Record<string, string>;
 export type PluginDeclarationPolicy = "default" | "optional";
 
 /**
- * A companion-declared npm plugin: installed by setup/install into
- * `.mate/dependencies/plugins/` and loaded on every invocation. Declaration
- * registers the plugin; enablement stays in the `capabilities` list.
+ * A companion-declared npm plugin: installed by setup/install into the
+ * companion's own shared plugin workspace (`.mate/plugins/`) and loaded
+ * from there on every invocation. Declaration registers the plugin;
+ * enablement stays in the `capabilities` list.
  */
 export interface PluginDeclaration {
   /** npm package name (e.g. `@acme/custom-plugin`). */
@@ -104,8 +125,9 @@ export interface PluginDeclaration {
 }
 
 export interface FrameworkConfig {
-  type?: "working" | "companion";
+  type?: FrameworkType;
   git?: GitModeProfile;
+  hub?: HubConfig;
   profiles: Record<string, PolicyProfile>;
   capabilities?: CapabilityConfig[];
   plugins?: PluginDeclaration[];

package/src/lib/orchestrator/working-repo-store.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { migrateRegistryData } from "./migration";
 import { YamlFileStore } from "./yaml-file-store";
 import { ConfigError, type WorkingRepoConfig } from "./types";
@@ -21,7 +21,7 @@ export class WorkingRepoStore extends YamlFileStore<WorkingRepoConfig> {
 
   protected async onMissing(): Promise<WorkingRepoConfig> {
     throw new ConfigError(
-      `Working repo config not found. Please run \`${frameworkCommandName()} companion setup\` to initialize the framework.`,
+      `Working repo config not found. Please run \`${FRAMEWORK_NAME} companion setup\` to initialize the framework.`,
     );
   }
 

package/src/lib/update-checker.ts

@@ -2,7 +2,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { getActiveDistribution, type DistributionUpdateConfig } from "../distribution";
-import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import { fetchPublicPackageVersion, PUBLIC_NPM_REGISTRY } from "./public-npm";
 import { YamlFileStore } from "./orchestrator/yaml-file-store";
 
@@ -77,9 +77,9 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
     const current = getCurrentVersion();
     if (!isNewer(state.latestVersion, current)) return;
     process.stderr.write(
-      `\n${frameworkCommandName()}: update available (${current} → ${state.latestVersion})\n`,
+      `\n${FRAMEWORK_NAME}: update available (${current} → ${state.latestVersion})\n`,
     );
-    process.stderr.write(`  Run \`${frameworkCommandName()} update\` to upgrade.\n\n`);
+    process.stderr.write(`  Run \`${FRAMEWORK_NAME} update\` to upgrade.\n\n`);
   } catch {
     // never block the main command
   }
@@ -98,9 +98,9 @@ export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<
     const current = getCurrentVersion();
     if (!isNewer(state.latestVersion, current)) return false;
     process.stderr.write(
-      `\n${frameworkCommandName()}: update required (${current} → ${state.latestVersion})\n`,
+      `\n${FRAMEWORK_NAME}: update required (${current} → ${state.latestVersion})\n`,
     );
-    process.stderr.write(`  Run \`${frameworkCommandName()} update\` before continuing.\n\n`);
+    process.stderr.write(`  Run \`${FRAMEWORK_NAME} update\` before continuing.\n\n`);
     return true;
   } catch {
     return false;

package/src/playbooks/companion-guidance.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import type { AdapterContext } from "../lib/orchestrator/adapters/base";
 import {
   hasGraphifyCapability,
@@ -35,7 +35,7 @@ export function buildCodebaseExplorationGuidanceSection(
 2. If tokensave is empty/file-only/irrelevant, run graphify query "<question>"; use graphify path/explain to deepen.
 3. Use grep/glob/read only after tokensave and graphify were tried.</order>
 <notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run ${frameworkCommandName()} cap index.</post-edit>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index.</post-edit>
 </codebase-exploration-rules>`;
   }
 
@@ -48,7 +48,7 @@ export function buildCodebaseExplorationGuidanceSection(
 2. Use graphify path "<A>" "<B>" or graphify explain "<concept>" to deepen.
 3. Use grep/glob/read only after graphify was tried.</order>
 <notes>Dirty graph files are expected. Use wiki/index.md for broad navigation; GRAPH_REPORT.md only if query/path/explain fall short.</notes>
-<post-edit>After code changes, run ${frameworkCommandName()} cap index --graphify.</post-edit>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --graphify.</post-edit>
 </codebase-exploration-rules>`;
   }
 
@@ -57,7 +57,7 @@ export function buildCodebaseExplorationGuidanceSection(
 <order>tokensave -> grep/glob/read. MUST try tokensave before raw source.
 1. tokensave_context first.
 2. Use grep/glob/read only after tokensave is empty or irrelevant.</order>
-<post-edit>After code changes, run ${frameworkCommandName()} cap index --tokensave.</post-edit>
+<post-edit>After code changes, run ${FRAMEWORK_NAME} cap index --tokensave.</post-edit>
 </codebase-exploration-rules>`;
 }
 
@@ -88,7 +88,7 @@ export function buildCompanionPolicyXml(
     "    <cli-tools>",
     `      <cli name="openspec" type="wrapper" invokeAs="${path.join(wrapperBinPath, "openspec")}" />`,
     `      <cli name="graphify" type="wrapper" invokeAs="${path.join(wrapperBinPath, "graphify")}" />`,
-    `      <cli name="${FRAMEWORK_NAME}" type="global" invokeAs="${frameworkCommandName()}" />`,
+    `      <cli name="${FRAMEWORK_NAME}" type="global" invokeAs="${FRAMEWORK_NAME}" />`,
     "    </cli-tools>",
     `    <linked-repository id="${context.repository.id}" profile="${context.repository.profile}" />`,
     "  </context>",
@@ -103,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${frameworkCommandName()} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${FRAMEWORK_NAME} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
     );
   }
 

package/src/runtime/env.ts

@@ -6,7 +6,6 @@
  */
 export const MATE_ENV = {
   frameworkName: "MATE_NAME",
-  commandName: "MATE_COMMAND",
   version: "MATE_VERSION",
   companionPath: "MATE_ARTIFACT_PATH",
   wrapperBinPath: "MATE_WRAPPER_BIN_PATH",

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

@@ -4,12 +4,17 @@ set -u
 input_file=$(mktemp "${TMPDIR:-/tmp}/mate-artifact-finish.XXXXXX")
 trap 'rm -f "$input_file"' EXIT
 cat >"$input_file"
+companion_path="${MATE_ARTIFACT_PATH:-}"
 
 node -e '
 const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
 
 const inputFile = process.argv[1];
+const companionPath = process.argv[2] || "";
 const archivePathPattern = /(?:^|[\s\/"\x27`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^\/\s"\x27`,)]+)/;
+const archiveEntryPattern = /^\d{4}-\d{2}-\d{2}-.+$/;
 
 function shellSplit(command) {
   const parts = [];
@@ -133,11 +138,83 @@ function isClearFailure(response) {
   return typeof exitCode === "number" && exitCode !== 0;
 }
 
+// A change is finished once `mate artifact finish` has tagged it; this never
+// runs, denies, or auto-invokes the finish pipeline itself — it only checks
+// whether that already happened, so it cannot be steered by injected content.
+function hasFinishTag(entryName) {
+  if (!companionPath) return true; // cannot verify — do not block on it
+  const result = spawnSync(
+    "git",
+    ["-C", companionPath, "rev-parse", "-q", "--verify", "refs/tags/openspec/" + entryName],
+    { stdio: "ignore" },
+  );
+  return result.status === 0;
+}
+
+function handleStop(input) {
+  if (!companionPath) return;
+  const archiveDir = path.join(companionPath, "openspec", "changes", "archive");
+  let entries;
+  try {
+    entries = fs.readdirSync(archiveDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && archiveEntryPattern.test(entry.name))
+      .map((entry) => entry.name);
+  } catch {
+    return;
+  }
+  const unfinished = entries.filter((name) => !hasFinishTag(name));
+  if (unfinished.length === 0) return;
+
+  // Warn about each unfinished change at most once per session: if the user
+  // declines to finish now, repeating the block on every later Stop would
+  // make the session impossible to end.
+  const sessionId = typeof input.session_id === "string" && input.session_id ? input.session_id : null;
+  const stateDir = path.join(companionPath, ".claude", "state");
+  const stateFile = path.join(
+    stateDir,
+    "mate-artifact-finish-stop." +
+      (sessionId ? sessionId.replace(/[^a-zA-Z0-9_-]/g, "_") : "archive-snapshot") +
+      ".json",
+  );
+  let flagged = [];
+  try {
+    const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    if (state && Array.isArray(state.flagged)) flagged = state.flagged;
+  } catch {}
+  const flaggedSet = new Set(flagged);
+  const toWarn = unfinished.filter((name) => !flaggedSet.has(name));
+  if (toWarn.length === 0) return;
+
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(
+      stateFile,
+      JSON.stringify({ version: 1, flagged: [...flaggedSet, ...toWarn] }) + "\n",
+    );
+  } catch {
+    return; // cannot record the warning — do not block without being able to dedupe it
+  }
+
+  const names = toWarn.map((name) => name.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
+  const reason =
+    "Archived OpenSpec change(s) not yet finished (no dated finish tag): " + names.join(", ") +
+    ". Invoke the mate-artifact-finish skill now — it will ask you to confirm before it " +
+    "commits, tags, and pushes — then run `mate artifact finish \"<name>\" --json` for each. " +
+    "Do not hand-commit or hand-tag. If the user declines, you may end the turn; this check " +
+    "will not repeat for the same change(s) in this session.";
+  process.stdout.write(JSON.stringify({ decision: "block", reason }));
+}
+
 let input = {};
 try {
   input = JSON.parse(fs.readFileSync(inputFile, "utf8") || "{}");
 } catch {}
 
+if (input.hook_event_name === "Stop") {
+  handleStop(input);
+  process.exit(0);
+}
+
 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
@@ -146,10 +223,9 @@ const change = extractArchiveCommand(command) || extractMoveCommand(command);
 if (!change) process.exit(0);
 if (isClearFailure(input.tool_response)) process.exit(0);
 
-const mateCommand = process.env.MATE_COMMAND || "mate";
 const context =
   "OpenSpec change " + change + " was just archived. Invoke the mate-artifact-finish " +
-  "skill, then run `" + mateCommand + " artifact finish \"" + change + "\" --json` to complete the " +
+  "skill, then run `mate artifact finish \"" + change + "\" --json` to complete the " +
   "finish workflow (commit, tag, and push).";
 process.stdout.write(JSON.stringify({
   hookSpecificOutput: {
@@ -157,5 +233,5 @@ process.stdout.write(JSON.stringify({
     additionalContext: context,
   },
 }));
-' "$input_file"
+' "$input_file" "$companion_path"
 exit 0

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

@@ -1,9 +1,9 @@
 ---
 name: mate-artifact-finish
-description: Finish a completed artifact in one step via `{{MATE_COMMAND}} 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_COMMAND}}:*), Bash(git:*), Bash(openspec:*)
+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
-compatibility: Requires the {{MATE_COMMAND}} CLI and the openspec capability enabled.
+compatibility: Requires the mate CLI and the openspec capability enabled.
 metadata:
   author: mate
   version: "1.2"
@@ -13,7 +13,7 @@ Finish a completed artifact as one deterministic mate workflow and leave a dated
 
 ## Workflow
 
-`{{MATE_COMMAND}} artifact finish` is the deterministic, non-interactive finish pipeline.
+`mate artifact finish` is the deterministic, non-interactive finish pipeline.
 
 The CLI performs normal work; only conflict recovery requires agent judgment.
 
@@ -24,10 +24,10 @@ The CLI performs normal work; only conflict recovery requires agent judgment.
 2. **Run the CLI.**
 
    ```bash
-   {{MATE_COMMAND}} artifact finish "<artifact-name>" --json
+   mate artifact finish "<artifact-name>" --json
    ```
 
-   Run it from the companion repository. Finish mutates only that repository; the linked working repository is capability-indexing context. Do not manually invoke `{{MATE_COMMAND}} cap index`.
+   Run it from the companion repository. Finish mutates only that repository; the linked working repository is capability-indexing context. Do not manually invoke `mate cap index`.
 
    Add `--force` only if the user explicitly wants to override the not-complete guard (validation is never bypassable). Unrelated companion changes are preserved and do not require `--force`. Add `--no-push` for a local-only finish.
 
@@ -44,8 +44,8 @@ The CLI performs normal work; only conflict recovery requires agent judgment.
 
 - **CRITICAL — no manual finishing**: Never hand-commit or hand-tag instead of this skill. For a still-active change the finish pipeline applies delta specs itself (via `openspec archive`) — do not pre-apply them, or produce fails with "already exists". A change whose specs were already synced (e.g. via `openspec-sync-specs`) must be archived first; finish then resumes from the archive without re-applying delta specs.
 - Always pass `--json` and parse the result; do not scrape human-readable output.
-- Never re-run `{{MATE_COMMAND}} artifact finish` blindly after a `conflict`.
+- Never re-run `mate artifact finish` blindly after a `conflict`.
 - Never auto-resolve a provider-specific conflict you do not understand — ask the user.
 - Use the JSON fields the CLI returns; do not recompute names, dates, or tags by hand.
-- Invoke the CLI as `{{MATE_COMMAND}}`, never through a companion-local wrapper.
+- Invoke the CLI as `mate`, never through a companion-local wrapper.
 - Only the companion repository is a finish Git target; the working repository is an index input.