@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

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

@@ -1,37 +1,28 @@
-import { execFile as execFileCb } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
 
 import { Document, isMap, isScalar, isSeq, parseDocument, type YAMLMap, type YAMLSeq } from "yaml";
 
-import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
+import {
+  locateOpenSpec,
+  runOpenSpec,
+  type OpenSpecLocation,
+  type RunOpenSpec,
+} from "../../../lib/openspec-cli";
 import { getWrapperBinPath } from "../../../lib/package-paths";
-import { fetchPublicPackageVersion } from "../../../lib/public-npm";
-import { isNewer, isPinnedDeployment } from "../../../lib/update-checker";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { confirm } from "../../../cli/confirm";
-import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
-import type { InstallRequirement } from "../install-contract";
-import {
-  isCommandOnPath,
-  mergeDir,
-  pruneEmptyAncestors,
-  resolveCommandOnPath,
-  runCommand,
-  runCommandSilently,
-} from "../utils";
-import { applyMateSkills, MANAGED_MATE_SKILL_NAMES, teardownMateSkills } from "../mate";
-import {
-  getSharedSkillsDir,
-  isSharedSkillRootActive,
-  removeLegacyOpenCodeSkills,
-  removeSharedSkills,
-} from "../providers/agents-skill-root";
-
-export { MATE_ARTIFACT_SKILLS, MATE_SKILLS } from "../mate";
-
-const execFileAsync = promisify(execFileCb);
+import { removeRecorded } from "../managed-output";
+import type {
+  CapabilityPlugin,
+  ManagedOutputRecorder,
+  RuntimeContributionsByRuntime,
+  SetupContext,
+} from "../plugin";
+import { mergeDir, pruneEmptyAncestors } from "../utils";
+import { applyMateSkills, MATE_SKILLS, readSkillAuthor, teardownMateSkills } from "../mate";
+import { getSharedSkillsDir, isSharedSkillRootActive } from "../providers/agents-skill-root";
+
+export { MATE_SKILLS } from "../mate";
 
 export const OPENSPEC_SKILLS = [
   "openspec-explore",
@@ -42,11 +33,30 @@ export const OPENSPEC_SKILLS = [
   "openspec-update-change",
 ] as const;
 
+/** Mate skills without a pre-seeded `Skill(...)` permission. */
+const UNPERMITTED_MATE_SKILLS: ReadonlySet<string> = new Set(["mate-create-report"]);
+
 /** Written by the OpenSpec `agents` tool beside its skills in the shared root. */
 const OPENSPEC_AGENTS_MARKER = ".openspec-target";
 
-/** Skill names the capability owns in any skill root. */
-const MANAGED_SKILL_NAMES = [...OPENSPEC_SKILLS, ...MANAGED_MATE_SKILL_NAMES];
+/** Command ids the OpenSpec CLI writes as `.claude/commands/opsx/<id>.md` and `.opencode/commands/opsx-<id>.md`. */
+const OPENSPEC_COMMAND_IDS = [
+  "explore",
+  "new",
+  "continue",
+  "apply",
+  "update",
+  "ff",
+  "sync",
+  "archive",
+  "bulk-archive",
+  "verify",
+  "onboard",
+  "propose",
+] as const;
+
+/** Skill roots earlier Mate versions let the OpenSpec CLI generate workflow skills into. */
+const GENERATED_SKILL_ROOTS = [".claude", ".agents", ".opencode"] as const;
 
 /** Every Mate-owned schema is installed for availability; only one is ever activated as the companion default. */
 const MATE_SCHEMA_NAMES = ["mate-v1", "mate-minimal"] as const;
@@ -68,25 +78,17 @@ export const MATE_SPECS_RULE_MARKER = "[mate] ";
  * sync workflows read when writing main specs. Propose reads it for delta specs
  * too, so the text binds main specs only.
  */
-export const MATE_SPECS_RULE = `${MATE_SPECS_RULE_MARKER}A main spec at openspec/specs/<capability>/spec.md MUST begin with flat frontmatter: type: spec, capability: <capability>, repository: <org/repository> (one scalar), areas: [<area>, ...] (a flat list in the delta's scope order), and tags: [openspec/spec]. Project repository and areas from the delta's paired scopes; never copy scopes, change, or delta tags onto a main spec. Delta specs under openspec/changes/<name>/specs/ keep their delta frontmatter. Full rules: openspec/mate-conventions.yaml.`;
+export const MATE_SPECS_RULE = `${MATE_SPECS_RULE_MARKER}A main spec at openspec/specs/<capability>/spec.md MUST begin with flat frontmatter: type: spec, capability: <capability>, repository: <org/repository> (one scalar), areas: [<area>, ...] (a flat list in the delta's scope order), and tags: [openspec/spec]. Project repository and areas from the delta's paired scopes; never copy scopes, change, or delta tags onto a main spec. Delta specs under openspec/changes/<name>/specs/ keep their \`mate:delta\` comment. Full rules: openspec/mate-conventions.yaml.`;
 
 /** What Mate writes besides its entry; anything beyond the two is user content. */
 const MANAGED_CONFIG_SCHEMA_ONLY = "schema: mate-v1";
 
+/** The schema a fresh `openspec init` writes into config.yaml. */
+const OPENSPEC_INIT_SCHEMA = "spec-driven";
+
 /** Unfolded output keeps the Mate entry on one line and user scalars unwrapped. */
 const CONFIG_TO_STRING = { lineWidth: 0 } as const;
 
-/**
- * Runtime → OpenSpec CLI tools. OpenCode reads workflow skills from the shared
- * `agents` root; its own tool only contributes the `/opsx-*` commands.
- */
-const OPENSPEC_TOOLS_BY_RUNTIME = {
-  claude: ["claude"],
-  opencode: ["agents", "opencode"],
-} as const;
-
-const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
-
 /**
  * Store metadata `openspec store register` writes beside the companion. Its id
  * is machine-local, and companion Git sync would otherwise stash it on every
@@ -94,47 +96,10 @@ const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
  */
 const OPENSPEC_GITIGNORE_ENTRIES = [".openspec-store/"];
 
-type OpenSpecTool =
-  (typeof OPENSPEC_TOOLS_BY_RUNTIME)[keyof typeof OPENSPEC_TOOLS_BY_RUNTIME][number];
-type OpenSpecRunCommand = typeof runCommandSilently;
-
 export interface OpenSpecPluginDeps {
-  runCommand?: OpenSpecRunCommand;
-  installCommand?: typeof runCommand;
-  isCommandOnPath?: typeof isCommandOnPath;
-  confirm?: typeof confirm;
-  pathValue?: () => string;
+  runOpenSpec?: RunOpenSpec;
+  locateOpenSpec?: () => OpenSpecLocation;
   wrapperBinPath?: () => string;
-  getInstalledVersion?: (pathValue: string) => Promise<string | undefined>;
-  fetchLatestVersion?: () => Promise<string | undefined>;
-  isPinnedDeployment?: () => boolean;
-}
-
-async function defaultGetInstalledVersion(pathValue: string): Promise<string | undefined> {
-  const bin = resolveCommandOnPath("openspec", pathValue);
-  if (!bin) return undefined;
-
-  try {
-    const { stdout } = await execFileAsync(bin, ["--version"], { timeout: 10_000 });
-    return stdout.match(/\d+\.\d+\.\d+/)?.[0];
-  } catch {
-    return undefined;
-  }
-}
-
-async function defaultFetchLatestVersion(): Promise<string | undefined> {
-  try {
-    return await fetchPublicPackageVersion("@fission-ai/openspec");
-  } catch {
-    return undefined;
-  }
-}
-
-export function deriveOpenSpecTools(activeProviders: string[]): OpenSpecTool[] {
-  const active = new Set(activeProviders);
-  return Object.entries(OPENSPEC_TOOLS_BY_RUNTIME).flatMap(([runtime, tools]) =>
-    active.has(runtime) ? tools : [],
-  );
 }
 
 function getClaudeSkillsDir(companionPath: string): string {
@@ -153,165 +118,109 @@ function getMateConventionsPath(companionPath: string): string {
   return path.join(companionPath, "openspec", "mate-conventions.yaml");
 }
 
-async function teardownClaudeSkillRoot(companionPath: string): Promise<void> {
+async function teardownClaudeSkillRoot(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
   const skillsDir = getClaudeSkillsDir(companionPath);
   for (const skill of OPENSPEC_SKILLS) {
     try {
-      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+      await removeRecorded(path.join(skillsDir, skill), "openspec", recorder);
     } catch {
       /* not present */
     }
   }
-  await teardownMateSkills(skillsDir, companionPath);
+  await teardownMateSkills(skillsDir, companionPath, recorder);
   await pruneEmptyAncestors(skillsDir, companionPath);
 }
 
-async function teardownSharedSkillRoot(companionPath: string): Promise<void> {
-  await removeSharedSkills(companionPath, [...MANAGED_SKILL_NAMES, OPENSPEC_AGENTS_MARKER]);
-}
-
-/** Converges earlier layouts and drops the `opencode` tool's duplicate workflow skills. */
-async function removeLegacyOpenCodeCopies(companionPath: string): Promise<void> {
-  await removeLegacyOpenCodeSkills(companionPath, MANAGED_SKILL_NAMES);
-}
-
-async function applyMateOpenspecSkills(
+async function teardownSharedSkillRoot(
   companionPath: string,
-  activeProviders: string[],
+  recorder?: ManagedOutputRecorder,
 ): Promise<void> {
-  if (activeProviders.includes("claude")) {
-    await applyMateSkills(getClaudeSkillsDir(companionPath), "claude");
-  }
-  if (isSharedSkillRootActive(activeProviders)) {
-    await applyMateSkills(getSharedSkillsDir(companionPath), "agents");
+  const skillsDir = getSharedSkillsDir(companionPath);
+  await teardownMateSkills(skillsDir, companionPath, recorder);
+  for (const name of [...OPENSPEC_SKILLS, OPENSPEC_AGENTS_MARKER]) {
+    await removeRecorded(path.join(skillsDir, name), "openspec", recorder);
   }
+  await pruneEmptyAncestors(skillsDir, companionPath);
 }
 
-async function reconcileOpenSpecTools(
-  ctx: SetupContext,
-  runCommand: OpenSpecRunCommand,
+/** Converges the earlier layout that deployed Mate skills into `.opencode/skills`. */
+async function removeLegacyOpenCodeCopies(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
 ): Promise<void> {
-  const tools = deriveOpenSpecTools(ctx.activeProviders);
-  if (tools.length === 0) return;
-  /** Best-effort: `config reset` is missing on older openspec releases. */
-  try {
-    await runCommand("openspec", ["config", "reset", "--all", "-y"], {
-      cwd: ctx.companionPath,
-    });
-  } catch (error) {
-    process.stderr.write(
-      `openspec config reset skipped: ${error instanceof Error ? error.message : String(error)}\n`,
-    );
-  }
-
-  await runCommand("openspec", ["init", "--tools", tools.join(","), "--force", ctx.companionPath], {
-    cwd: ctx.companionPath,
-  });
-  await runCommand("openspec", ["update", "--force", ctx.companionPath], {
-    cwd: ctx.companionPath,
-  });
+  await teardownMateSkills(
+    path.join(companionPath, ".opencode", "skills"),
+    companionPath,
+    recorder,
+  );
+}
 
-  await removeLegacyOpenCodeCopies(ctx.companionPath);
-  await applyMateOpenspecSkills(ctx.companionPath, ctx.activeProviders);
+/** The `openspec-*` skills in `skillsDir` OpenSpec wrote: the known names, or `author: openspec`. */
+async function generatedOpenSpecSkills(skillsDir: string): Promise<string[]> {
+  const names = (await fs.readdir(skillsDir).catch(() => [])).filter((name) =>
+    name.startsWith("openspec-"),
+  );
+  const generated = await Promise.all(
+    names.map(async (name) => {
+      const dir = path.join(skillsDir, name);
+      const known = (OPENSPEC_SKILLS as readonly string[]).includes(name);
+      return known || (await readSkillAuthor(dir)) === "openspec" ? [dir] : [];
+    }),
+  );
+  return generated.flat();
 }
 
-async function updateOpenSpecIfOutdated(
-  ctx: SetupContext,
-  deps: Required<
-    Pick<
-      OpenSpecPluginDeps,
-      | "installCommand"
-      | "pathValue"
-      | "getInstalledVersion"
-      | "fetchLatestVersion"
-      | "isPinnedDeployment"
-    >
-  >,
+/** Removes OpenSpec-generated output by name or authorship; user and third-party entries stay. */
+async function removeGeneratedOpenSpecOutput(
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
 ): Promise<void> {
-  /** Pinned artifacts change tool versions by replacement, never reconciliation. */
-  if (deps.isPinnedDeployment()) return;
-
-  const installed = await deps.getInstalledVersion(deps.pathValue());
-  if (!installed) return;
-
-  const latest = await deps.fetchLatestVersion();
-  if (!latest || !isNewer(latest, installed)) return;
-
-  process.stdout.write(
-    `openspec: installed version ${installed} is outdated (latest ${latest}). Updating now:\n  ${OPENSPEC_INSTALL_COMMAND}\n`,
+  const skills = await Promise.all(
+    GENERATED_SKILL_ROOTS.map((root) =>
+      generatedOpenSpecSkills(path.join(companionPath, root, "skills")),
+    ),
   );
-
-  try {
-    await deps.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"], {
-      cwd: ctx.companionPath,
-    });
-  } catch {
-    process.stderr.write("openspec: upgrade failed - continuing with the installed version\n");
+  const targets = [
+    ...skills.flat(),
+    path.join(getSharedSkillsDir(companionPath), OPENSPEC_AGENTS_MARKER),
+    ...OPENSPEC_COMMAND_IDS.flatMap((id) => [
+      path.join(companionPath, ".claude", "commands", "opsx", `${id}.md`),
+      path.join(companionPath, ".opencode", "commands", `opsx-${id}.md`),
+    ]),
+  ];
+  await Promise.all(targets.map((target) => removeRecorded(target, "openspec", recorder)));
+  // Sequential: the parent directories share ancestors.
+  for (const dir of new Set(targets.map((target) => path.dirname(target)))) {
+    // oxlint-disable-next-line no-await-in-loop
+    await pruneEmptyAncestors(dir, companionPath);
   }
 }
 
-async function ensureOpenSpecInstalled(
-  ctx: SetupContext,
-  deps: Required<
-    Pick<
-      OpenSpecPluginDeps,
-      | "installCommand"
-      | "isCommandOnPath"
-      | "confirm"
-      | "pathValue"
-      | "getInstalledVersion"
-      | "fetchLatestVersion"
-      | "isPinnedDeployment"
-    >
-  >,
-): Promise<boolean> {
-  if (deps.isCommandOnPath("openspec", deps.pathValue())) {
-    await updateOpenSpecIfOutdated(ctx, deps);
-    return true;
-  }
-
-  if (ctx.mode !== "setup") {
-    process.stderr.write(
-      `openspec binary not found. Install it manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
-  }
-
-  if (!deps.isCommandOnPath("npm", deps.pathValue())) {
-    process.stderr.write(
-      `openspec binary not found and npm is not available on PATH. Install it manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
-  }
-
-  process.stdout.write(`openspec binary not found. To install:\n  ${OPENSPEC_INSTALL_COMMAND}\n`);
-  const ok = await deps.confirm("Run this install command now?");
-  if (!ok) {
-    process.stderr.write(
-      `openspec: install skipped - install manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+async function applyMateOpenspecSkills(ctx: SetupContext): Promise<void> {
+  if (ctx.activeProviders.includes("claude")) {
+    await applyMateSkills(getClaudeSkillsDir(ctx.companionPath), "claude", ctx.managedOutput);
   }
-
-  try {
-    await deps.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"], {
-      cwd: ctx.companionPath,
-    });
-  } catch {
-    process.stderr.write(
-      `openspec: install failed - install manually with \`${OPENSPEC_INSTALL_COMMAND}\`\n`,
-    );
-    return false;
+  if (isSharedSkillRootActive(ctx.activeProviders)) {
+    await applyMateSkills(getSharedSkillsDir(ctx.companionPath), "agents", ctx.managedOutput);
   }
+}
 
-  if (!deps.isCommandOnPath("openspec", deps.pathValue())) {
-    process.stderr.write(
-      "openspec install completed but the binary is still not available on PATH\n",
-    );
-    return false;
+/**
+ * Initializes OpenSpec without tool output, so it writes only its `openspec/`
+ * scaffolding: Mate carries the workflow text in its own skills.
+ */
+async function initializeOpenSpec(ctx: SetupContext, run: RunOpenSpec): Promise<void> {
+  const args = ["init", "--tools", "none", "--force", ctx.companionPath];
+  const result = await run(args, { cwd: ctx.companionPath });
+  if (result.code !== 0) {
+    // A missing bundled CLI answers its reinstall message as stderr.
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(`openspec ${args.join(" ")} exited with code ${result.code}: ${detail}`);
   }
-
-  return true;
+  await removeGeneratedOpenSpecOutput(ctx.companionPath, ctx.managedOutput);
 }
 
 function isMateSpecsRule(item: unknown): boolean {
@@ -426,7 +335,7 @@ async function ensureManagedOpenSpecConfig(companionPath: string): Promise<void>
     return;
   }
 
-  // config.yaml is user-editable once created; only Mate's own entry is touched.
+  // config.yaml is user-editable once created; only Mate's entry and a default `schema` are touched.
   const doc = parseDocument(content);
   if (doc.errors.length > 0) {
     process.stderr.write(
@@ -434,7 +343,14 @@ async function ensureManagedOpenSpecConfig(companionPath: string): Promise<void>
     );
     return;
   }
-  if (!upsertMateSpecsRule(doc)) return;
+  const ruleChanged = upsertMateSpecsRule(doc);
+  // Mate's `mate-v1` replaces a missing schema or the one `openspec init` writes; any other is a user choice.
+  const current = isMap(doc.contents) ? doc.get("schema") : undefined;
+  const schemaChanged =
+    isMap(doc.contents) &&
+    (current === undefined || current === null || current === OPENSPEC_INIT_SCHEMA);
+  if (schemaChanged) doc.set("schema", "mate-v1");
+  if (!schemaChanged && !ruleChanged) return;
   const merged = doc.toString(CONFIG_TO_STRING);
   if (merged !== content) await fs.writeFile(configPath, merged, "utf8");
 }
@@ -465,27 +381,14 @@ async function reconcileOpenSpecSchema(ctx: SetupContext): Promise<void> {
   );
   await fs.copyFile(MATE_CONVENTIONS_SOURCE, getMateConventionsPath(ctx.companionPath));
 
-  // Availability is unconditional so any change may select a Mate schema;
-  // activation stays opt-in through the companion-level setup selection.
-  if (getOpenSpecSchemaSelection(ctx.config.capabilities ?? []) !== "mate-v1") {
-    await removeManagedOpenSpecConfig(ctx.companionPath);
-    return;
-  }
-
   await ensureManagedOpenSpecConfig(ctx.companionPath);
 }
 
 export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityPlugin {
   const depsWithDefaults = {
-    runCommand: deps.runCommand ?? runCommandSilently,
-    installCommand: deps.installCommand ?? runCommand,
-    isCommandOnPath: deps.isCommandOnPath ?? isCommandOnPath,
-    confirm: deps.confirm ?? confirm,
-    pathValue: deps.pathValue ?? (() => process.env.PATH ?? ""),
+    runOpenSpec: deps.runOpenSpec ?? runOpenSpec,
+    locateOpenSpec: deps.locateOpenSpec ?? locateOpenSpec,
     wrapperBinPath: deps.wrapperBinPath ?? getWrapperBinPath,
-    getInstalledVersion: deps.getInstalledVersion ?? defaultGetInstalledVersion,
-    fetchLatestVersion: deps.fetchLatestVersion ?? defaultFetchLatestVersion,
-    isPinnedDeployment: deps.isPinnedDeployment ?? (() => isPinnedDeployment()),
   };
 
   return {
@@ -503,19 +406,9 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
       return {
         claude: {
           permissionEntries: [
-            "Skill(openspec-explore)",
-            "Skill(openspec-propose)",
-            "Skill(openspec-apply-change)",
-            "Skill(openspec-archive-change)",
-            "Skill(mate-artifact-publish)",
-            "Skill(mate-openspec-backfill)",
-            "Skill(mate-interview-me)",
-            "Skill(mate-grill-me)",
-            "Skill(mate-grilling)",
-            "Skill(mate-grill-with-docs)",
-            "Skill(mate-domain-modeling)",
-            "Skill(mate-show-me)",
-            "Skill(mate-simplify-code)",
+            ...MATE_SKILLS.filter((skill) => !UNPERMITTED_MATE_SKILLS.has(skill)).map(
+              (skill) => `Skill(${skill})`,
+            ),
             "Bash(openspec:*)",
             `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
             `Bash(${path.join(depsWithDefaults.wrapperBinPath(), "openspec")}:*)`,
@@ -525,54 +418,42 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     },
     gitignoreEntries: () => OPENSPEC_GITIGNORE_ENTRIES,
     persistGitignoreEntries: true,
-    getInstallRequirements: (): InstallRequirement[] => [
-      {
-        id: "capability:openspec",
-        label: "OpenSpec CLI",
-        group: "companion",
-        source: "OpenSpec capability",
-        command: OPENSPEC_INSTALL_COMMAND,
-        fingerprint: `openspec:${OPENSPEC_INSTALL_COMMAND}`,
-        detect: () => depsWithDefaults.isCommandOnPath("openspec", depsWithDefaults.pathValue()),
-        install: () =>
-          depsWithDefaults.installCommand("npm", ["install", "-g", "@fission-ai/openspec@latest"]),
-        verify: () => depsWithDefaults.isCommandOnPath("openspec", depsWithDefaults.pathValue()),
-      },
-    ],
     async apply(ctx) {
-      const tools = deriveOpenSpecTools(ctx.activeProviders);
-      if (ctx.mode === "setup" || tools.length > 0) {
-        if (await ensureOpenSpecInstalled(ctx, depsWithDefaults)) {
-          if (tools.length > 0) {
-            await reconcileOpenSpecTools(ctx, depsWithDefaults.runCommand);
-          }
-        }
+      // OpenSpec output is committed in the companion, so only setup and
+      // `mate companion update` touch it; a launch must leave it alone.
+      if (ctx.mode === "setup" || ctx.regenerateOpenSpec === true) {
+        await initializeOpenSpec(ctx, depsWithDefaults.runOpenSpec);
+      } else {
+        const location = depsWithDefaults.locateOpenSpec();
+        if ("missing" in location) process.stderr.write(`openspec: ${location.missing}\n`);
       }
-      await removeLegacyOpenCodeCopies(ctx.companionPath);
+      await applyMateOpenspecSkills(ctx);
+      await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
       await reconcileOpenSpecSchema(ctx);
     },
     async teardown(ctx) {
-      await teardownClaudeSkillRoot(ctx.companionPath);
-      await teardownSharedSkillRoot(ctx.companionPath);
-      await removeLegacyOpenCodeCopies(ctx.companionPath);
+      await teardownClaudeSkillRoot(ctx.companionPath, ctx.managedOutput);
+      await teardownSharedSkillRoot(ctx.companionPath, ctx.managedOutput);
+      await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
+      await removeGeneratedOpenSpecOutput(ctx.companionPath, ctx.managedOutput);
       await teardownOpenSpecSchema(ctx.companionPath);
     },
     forProvider: {
       claude: {
-        // Publication is explicit (`mate-artifact-publish`), so openspec
+        // Publication is explicit (`mate-publish-artifact`), so openspec
         // contributes no archive-triggered Claude hook and no hook state.
         async apply() {},
         async teardown(ctx: SetupContext) {
-          await teardownClaudeSkillRoot(ctx.companionPath);
+          await teardownClaudeSkillRoot(ctx.companionPath, ctx.managedOutput);
         },
       },
       opencode: {
         async apply() {},
         async teardown(ctx: SetupContext) {
           if (!isSharedSkillRootActive(ctx.activeProviders)) {
-            await teardownSharedSkillRoot(ctx.companionPath);
+            await teardownSharedSkillRoot(ctx.companionPath, ctx.managedOutput);
           }
-          await removeLegacyOpenCodeCopies(ctx.companionPath);
+          await removeLegacyOpenCodeCopies(ctx.companionPath, ctx.managedOutput);
         },
       },
     },

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

@@ -4,6 +4,8 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
+import { resolveSecretPolicy } from "../../../runtime/policy";
+import { DEFAULT_SECRET_DENY_PATTERNS, type SecretPolicy } from "../../../runtime/secret-patterns";
 import { resolveGitInfoExcludePath } from "../git-utils";
 import type { InstallRequirement } from "../install-contract";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime } from "../plugin";
@@ -368,14 +370,40 @@ export async function isTokensaveIndexed(repoPath: string): Promise<boolean> {
   return fileExists(path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_DATABASE_FILE));
 }
 
+function secretExclude(pattern: string): string {
+  return `**/${pattern.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Mate owns the excludes derived from the defaults and from the companion's
+ * current extra patterns. An extra removed from config is no longer
+ * recognizable, so its exclude stays: over-excluding from an index is harmless.
+ */
+function reconcileSecretExcludes(existing: unknown, secrets: SecretPolicy): string[] {
+  const owned = new Set([...DEFAULT_SECRET_DENY_PATTERNS, ...secrets.deny].map(secretExclude));
+  const kept = (Array.isArray(existing) ? existing : []).filter(
+    (entry): entry is string => typeof entry === "string" && !owned.has(entry),
+  );
+  const managed = secrets.guardrails ? [...new Set(secrets.deny.map(secretExclude))] : [];
+  return [...kept, ...managed];
+}
+
 /**
  * Reconciles Mate's single-graph branching posture into the working repo's
  * git-excluded `.tokensave/config.json` and deactivates existing branch
  * metadata. Best-effort by design: the file is created by `tokensave init`,
  * so an absent, unreadable, or unparseable config is left untouched rather
  * than treated as an error. Existing branch databases are never removed.
+ *
+ * With a secret policy, also reconciles the secret-file excludes: Mate's
+ * `**\/<pattern>` entries are appended while guardrails are on and removed
+ * when they are off, by exact value, so user-authored excludes keep their
+ * place. Without one, `exclude` is left as it is.
  */
-export async function ensureTokensaveBranchingPosture(repoPath: string): Promise<void> {
+export async function ensureTokensaveBranchingPosture(
+  repoPath: string,
+  secrets?: SecretPolicy,
+): Promise<void> {
   const configPath = path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_CONFIG_FILE);
 
   let raw: string;
@@ -395,8 +423,13 @@ export async function ensureTokensaveBranchingPosture(repoPath: string): Promise
     return;
   }
 
+  const config = parsed as Record<string, unknown>;
   const next = JSON.stringify(
-    { ...(parsed as Record<string, unknown>), ...TOKENSAVE_OWNED_POSTURE },
+    {
+      ...config,
+      ...TOKENSAVE_OWNED_POSTURE,
+      ...(secrets ? { exclude: reconcileSecretExcludes(config.exclude, secrets) } : {}),
+    },
     null,
     2,
   );
@@ -539,7 +572,7 @@ export function createTokensavePlugin(): CapabilityPlugin {
       ) {
         return;
       }
-      await ensureTokensaveBranchingPosture(targetPath);
+      await ensureTokensaveBranchingPosture(targetPath, resolveSecretPolicy(ctx.companionPath));
       if (ctx.mode === "setup") {
         installTokensaveAgentIntegrations(ctx.activeProviders, targetPath);
       }