@uniqbit/mate-core 0.15.4-canary.10 → 0.15.4-canary.12

package/package.json

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

package/src/cli/commands/cap/openspec.ts

@@ -79,7 +79,26 @@ export async function runOpenspecCapCommand(
     readOpenSpecProjectSchema(companionPath),
   );
 
-  const result = spawnSync("openspec", forwardedArgs, { cwd, stdio: "inherit" });
+  if (forwardedArgs[0] === "init" || forwardedArgs[0] === "update") {
+    const reset = spawnSync("openspec", ["config", "reset", "--all", "-y"], {
+      cwd,
+      stdio: "inherit",
+    });
+    if (reset.error) {
+      process.stderr.write(`Failed to reset openspec config: ${reset.error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    if (reset.status !== 0) {
+      process.exitCode = reset.status ?? 1;
+      return;
+    }
+  }
+
+  const result = spawnSync("openspec", forwardedArgs, {
+    cwd,
+    stdio: "inherit",
+  });
   if (result.error) {
     process.stderr.write(`Failed to run openspec: ${result.error.message}\n`);
     process.exitCode = 1;

package/src/cli/commands/companion/hub.ts

@@ -50,6 +50,7 @@ async function selectRegisteredCompanion(): Promise<string> {
 async function runHubInit(argv: string[]): Promise<void> {
   const folder = positionalArgs(argv)[0] ?? process.cwd();
   const hubPath = await initializeCompanionHub(folder);
+  await updateHubPlugins(hubPath);
   console.log(`Initialized companion hub: ${hubPath}`);
 }
 

package/src/cli/commands/plugin/install.ts

@@ -2,8 +2,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
+import { backfillHubAllowedAgents } from "../../../lib/orchestrator/companion-hub";
 import { ConfigStore } from "../../../lib/orchestrator/config-store";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { FrameworkConfig, PluginDeclaration } from "../../../lib/orchestrator/types";
+import { applySetupCompatibilities } from "../../../tools/setup";
 import { hydrateDynamicPlugins } from "../../../tools/setup/dynamic-plugins/hydrate";
 import {
   installDeclaredPlugins,
@@ -33,6 +35,7 @@ function withDeclaration(
 export interface PluginInstallCommandDeps {
   cwd?: string;
   installDeps?: PluginInstallDeps;
+  setupHub?: (companionPath: string, config: FrameworkConfig) => Promise<void>;
 }
 
 /**
@@ -78,8 +81,10 @@ export async function runPluginInstallCommand(
   );
   const store = new ConfigStore(configPath);
   const nextPlugins = withDeclaration(context.config.plugins ?? [], packageName, version);
-  if (nextPlugins !== context.config.plugins) {
-    await store.save({ ...context.config, plugins: nextPlugins });
+  const nextConfig = { ...context.config, plugins: nextPlugins };
+  const agentsBackfilled = context.kind === "hub" && backfillHubAllowedAgents(nextConfig);
+  if (nextPlugins !== context.config.plugins || agentsBackfilled) {
+    await store.save(nextConfig);
   }
 
   const results = await installDeclaredPlugins(
@@ -89,6 +94,13 @@ export async function runPluginInstallCommand(
   );
   reportPluginInstallResults(results);
   await hydrateDynamicPlugins({ companionPath: context.companionPath });
+  if (context.kind === "hub") {
+    await (
+      deps.setupHub ??
+      ((companionPath, config) =>
+        applySetupCompatibilities(companionPath, config, "sync", undefined, undefined, "hub"))
+    )(context.companionPath, nextConfig);
+  }
 
   return results.find((result) => result.package === packageName)?.status !== "failed";
 }

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

@@ -79,6 +79,36 @@ function extractChangeFromPath(value: string): string | null {
   return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
 }
 
+// Best-effort shell variable substitution, NOT a shell interpreter: a change
+// name is often built up through variables (DEST="...archive/$TARGET"; mv a
+// "$DEST") rather than appearing as a literal path next to mv/archive. This
+// resolves $NAME/${NAME} references against preceding literal NAME=value
+// assignment tokens in the same command string; unresolved references are
+// left as-is, which keeps prior (silent) behavior for anything it can't follow.
+const ASSIGNMENT_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/;
+const VARIABLE_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function substituteVariables(value: string, vars: Map<string, string>): string {
+  return value.replace(VARIABLE_REFERENCE_PATTERN, (match, braced: string, bare: string) => {
+    const name = braced ?? bare;
+    return vars.has(name) ? vars.get(name)! : match;
+  });
+}
+
+// Assignments are collected in left-to-right token order so a later
+// assignment (e.g. DEST) can reference an earlier one (e.g. TARGET) the same
+// way the shell would resolve it at that point in the script.
+function collectVariableAssignments(parts: string[]): Map<string, string> {
+  const vars = new Map<string, string>();
+  for (const part of parts) {
+    const match = part.match(ASSIGNMENT_PATTERN);
+    if (!match) continue;
+    const [, name, rawValue] = match;
+    vars.set(name, substituteVariables(rawValue, vars));
+  }
+  return vars;
+}
+
 // Shell syntax tokens are never change-name positionals: separators end the
 // archive invocation, redirections are skipped (a bare operator also consumes
 // its target token).
@@ -95,6 +125,7 @@ export function extractArchiveCommand(command: string): string | null {
       (parts[position - 1] === "openspec" || parts[position - 1].endsWith("/openspec")),
   );
   if (index < 0) return null;
+  const vars = collectVariableAssignments(parts);
   for (let position = index + 1; position < parts.length; position += 1) {
     const part = parts[position];
     if (!part || part === "--") continue;
@@ -107,7 +138,7 @@ export function extractArchiveCommand(command: string): string | null {
       if (part === "--store") position += 1;
       continue;
     }
-    return part;
+    return substituteVariables(part, vars);
   }
   return null;
 }
@@ -130,15 +161,16 @@ function isPython(part: string): boolean {
 
 export function extractMoveCommand(command: string): string | null {
   const parts = shellSplit(command);
+  const vars = collectVariableAssignments(parts);
   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);
+        const change = extractChangeFromPath(substituteVariables(part, vars));
         if (change) return change;
       }
     }
     if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(command)) {
-      return extractChangeFromPath(command);
+      return extractChangeFromPath(substituteVariables(command, vars));
     }
   }
   return null;

package/src/lib/orchestrator/companion-git-sync.ts

@@ -9,6 +9,9 @@ import { LaunchPreflightError } from "./types";
 
 const execFile = promisify(execFileCallback);
 
+/** Bounded but far above any diagnostic output; default 1 MiB kills git mid-merge on large trees. */
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
 export interface GitCommandResult {
   status: number;
   stdout: string;
@@ -26,22 +29,30 @@ export interface CompanionGitSyncResult {
 export class CompanionGitSyncError extends LaunchPreflightError {
   readonly companionPath: string;
   readonly conflictingPaths: string[];
+  readonly reason: string;
+  readonly recovery: string;
+  readonly stashRef: string | undefined;
 
   constructor(
     companionPath: string,
     reason: string,
     conflictingPaths: string[] = [],
     recovery = "Resolve or abort the Git operation, then retry the launch.",
+    stashRef?: string,
   ) {
     const conflicts = conflictingPaths.length
       ? `\n  Conflicting paths:\n${conflictingPaths.map((entry) => `    - ${entry}`).join("\n")}`
       : "";
+    const stash = stashRef
+      ? `  Local changes were stashed as ${stashRef}. Recover with \`git stash apply ${stashRef}\` in the companion.`
+      : "";
     super(
       [
         "mate: companion Git synchronization failed.",
         `  Companion: ${companionPath}`,
         `  ${reason}`,
         conflicts,
+        stash,
         `  ${recovery}`,
         "  Bypass: `mate claude -- --no-git` or `mate opencode -- --no-git`.",
       ]
@@ -51,6 +62,9 @@ export class CompanionGitSyncError extends LaunchPreflightError {
     this.name = "CompanionGitSyncError";
     this.companionPath = companionPath;
     this.conflictingPaths = conflictingPaths;
+    this.reason = reason;
+    this.recovery = recovery;
+    this.stashRef = stashRef;
   }
 }
 
@@ -68,6 +82,7 @@ export const companionGitSyncDeps: { runGit: GitRunner } = {
         cwd,
         encoding: "utf8",
         env: gitEnv,
+        maxBuffer: GIT_MAX_BUFFER,
       });
       return { status: 0, stdout: String(result.stdout), stderr: String(result.stderr) };
     } catch (error) {
@@ -106,6 +121,21 @@ function outputLines(stdout: string): string[] {
     .filter(Boolean);
 }
 
+/** Matches Git progress-meter lines such as `Updating files:  76% (11340/14790)` or `..., done.` */
+const GIT_PROGRESS_LINE = /^\S.*?: +\d+% \(\d+\/\d+\)(?:, done\.)?$/;
+
+function stripGitProgress(text: string): string {
+  return text
+    .split(/\r\n|\r|\n/)
+    .filter((line) => !GIT_PROGRESS_LINE.test(line.trim()))
+    .join("\n")
+    .trim();
+}
+
+export function describeGitFailure(result: GitCommandResult): string {
+  return stripGitProgress(result.stderr) || stripGitProgress(result.stdout) || "unknown Git error";
+}
+
 export class CompanionGitSync {
   constructor(private readonly runGit: GitRunner = companionGitSyncDeps.runGit) {}
 
@@ -160,7 +190,42 @@ export class CompanionGitSync {
       stashRef = ref.stdout.trim();
     }
 
-    const merge = await this.command(companionPath, ["merge", target.ref, "--no-edit"]);
+    const headBefore = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    try {
+      await this.mergeAndRestore(companionPath, target, stashRef);
+    } catch (error) {
+      if (stashRef && error instanceof CompanionGitSyncError && !error.stashRef) {
+        throw new CompanionGitSyncError(
+          error.companionPath,
+          error.reason,
+          error.conflictingPaths,
+          error.recovery,
+          stashRef,
+        );
+      }
+      throw error;
+    }
+
+    const headAfter = await this.command(companionPath, ["rev-parse", "HEAD"]);
+    return {
+      skipped: false,
+      changed: headBefore.stdout.trim() !== headAfter.stdout.trim(),
+      companionPath,
+    };
+  }
+
+  private async mergeAndRestore(
+    companionPath: string,
+    target: SyncTarget,
+    stashRef: string | undefined,
+  ): Promise<void> {
+    const merge = await this.command(companionPath, [
+      "merge",
+      target.ref,
+      "--no-stat",
+      "--no-progress",
+      "--no-edit",
+    ]);
     if (merge.status !== 0) {
       await this.resolveManagedConflicts(companionPath, target.ref);
       const conflicts = await this.unresolvedPaths(companionPath);
@@ -220,12 +285,6 @@ export class CompanionGitSync {
       // Keep the stash if dropping it fails; it remains a recoverable backup.
       await this.command(companionPath, ["stash", "drop", stashRef]);
     }
-
-    return {
-      skipped: false,
-      changed: merge.status === 0 && merge.stdout.trim() !== "",
-      companionPath,
-    };
   }
 
   private async assertSafeCompanionRoot(
@@ -410,7 +469,7 @@ export class CompanionGitSync {
   }
 
   private detail(result: GitCommandResult): string {
-    return (result.stderr || result.stdout || "unknown Git error").trim();
+    return describeGitFailure(result);
   }
 
   private failure(

package/src/lib/orchestrator/companion-hub.ts

@@ -8,12 +8,14 @@ import { FRAMEWORK_NAME } from "../../framework";
 import { ConfigStore, validateHubConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import type { FrameworkConfig, HubMember, HubMemberSource } from "./types";
+import { listSetupProviderCompatibilities } from "./setup-compatibilities";
 import {
   installDeclaredPlugins,
   type PluginInstallDeps,
   type PluginInstallResult,
 } from "../../tools/setup/dynamic-plugins/install";
 import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import { applySetupCompatibilities } from "../../tools/setup";
 import { findRepoLocalRegistryFile } from "./repo-local-registry";
 
 export interface GitCommandResult {
@@ -41,6 +43,7 @@ export interface HubSyncResult {
 export interface HubPluginSyncDeps {
   installDeps?: PluginInstallDeps;
   hydrate?: (options: { companionPath: string }) => Promise<void>;
+  setup?: (companionPath: string, config: FrameworkConfig, mode: "setup" | "sync") => Promise<void>;
 }
 
 export function defaultGitCommand(cwd: string, args: string[]): GitCommandResult {
@@ -123,7 +126,7 @@ export async function initializeCompanionHub(
   } else {
     const config: FrameworkConfig = {
       type: "hub",
-      allowedAgents: [],
+      allowedAgents: listSetupProviderCompatibilities().map((entry) => entry.agent),
       packageManagers: [],
       capabilities: [],
       hub: { companions: [] },
@@ -365,16 +368,35 @@ export async function syncHub(
   return results;
 }
 
+/**
+ * Hubs persisted before provider bootstrapping carry `allowedAgents: []`;
+ * an empty list on a hub means "all built-in agents", not "none".
+ */
+export function backfillHubAllowedAgents(config: FrameworkConfig): boolean {
+  if (config.type !== "hub" || config.allowedAgents.length > 0) return false;
+  config.allowedAgents = listSetupProviderCompatibilities().map((entry) => entry.agent);
+  return true;
+}
+
 export async function updateHubPlugins(
   hubPath: string,
   deps: HubPluginSyncDeps = {},
 ): Promise<PluginInstallResult[]> {
-  const { config } = await assertHubRoot(hubPath);
+  const { config, store } = await assertHubRoot(hubPath);
+  if (backfillHubAllowedAgents(config)) await store.save(config);
   const declarations = config.plugins ?? [];
-  if (declarations.length === 0) return [];
-
   const resolvedHubPath = path.resolve(hubPath);
-  const results = await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps);
-  await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  const results =
+    declarations.length > 0
+      ? await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps)
+      : [];
+  if (declarations.length > 0) {
+    await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  }
+  await (
+    deps.setup ??
+    ((companionPath, setupConfig, mode) =>
+      applySetupCompatibilities(companionPath, setupConfig, mode, undefined, undefined, "hub"))
+  )(resolvedHubPath, config, "sync");
   return results;
 }

package/src/lib/orchestrator/types.ts

@@ -96,8 +96,8 @@ export type PluginDeclarationPolicy = "default" | "optional";
 /**
  * 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.
+ * from there on every invocation. Declaration both registers and activates
+ * the plugin; dynamic plugins do not need a separate `capabilities` entry.
  */
 export interface PluginDeclaration {
   /** npm package name (e.g. `@acme/custom-plugin`). */

package/src/opencode/companion-hooks.ts

@@ -179,15 +179,12 @@ function detectCommandArchive(input: unknown, output: unknown): string | null {
 
 function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
   const current = readArchiveEntries(archiveDir);
-  const newlyArchived = [...current].filter((entry) => !snapshot.has(entry)).toSorted();
-  snapshot.clear();
-  for (const entry of current) snapshot.add(entry);
-  return newlyArchived;
+  return [...current].filter((entry) => !snapshot.has(entry)).toSorted();
 }
 
 function appendOpenSpecFinishNudge(
   context: CompanionContext,
-  archiveSnapshot: Set<string>,
+  archiveSnapshot: Set<string> | undefined,
   nudgedCommandChanges: Set<string>,
   input: { tool?: unknown },
   output: { output?: string },
@@ -196,8 +193,10 @@ function appendOpenSpecFinishNudge(
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
   const changes: string[] = [];
-  for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
-    changes.push(entry.slice("YYYY-MM-DD-".length));
+  if (archiveSnapshot) {
+    for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
+      changes.push(entry.slice("YYYY-MM-DD-".length));
+    }
   }
   const commandChange =
     String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
@@ -313,22 +312,36 @@ async function runReactDoctorScan(
 }
 
 type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
+type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
+type ToolBeforeOutput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[1];
 type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
 
+interface ArchiveCallSnapshot {
+  sessionID: string;
+  entries: Set<string>;
+}
+
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
   if (!context.companionPath || !context.repositoryPath) return {};
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const archiveSnapshot = readArchiveEntries(archiveDir);
+  const archiveCallSnapshots = new Map<string, ArchiveCallSnapshot>();
   const nudgedCommandChanges = new Set<string>();
   const dirtyReactDoctorSessions = new Set<string>();
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
     event: async ({ event }: PluginEventInput) => {
+      if (event.type === "session.deleted") {
+        const sessionID = event.properties.info.id;
+        for (const [callID, snapshot] of archiveCallSnapshots) {
+          if (snapshot.sessionID === sessionID) archiveCallSnapshots.delete(callID);
+        }
+        return;
+      }
       if (event.type !== "session.idle") return;
       const sessionID = event.properties.sessionID;
       if (
@@ -340,10 +353,7 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
       }
       await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
     },
-    "tool.execute.before": async (
-      input: { tool: unknown },
-      output: { args: { filePath?: unknown; patchText?: unknown } | undefined },
-    ) => {
+    "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
       if (["write", "edit"].includes(toolName)) {
@@ -359,13 +369,24 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           }
         }
       }
+      if (context.gitAutoModeEnabled) {
+        archiveCallSnapshots.set(input.callID, {
+          sessionID: input.sessionID,
+          entries: readArchiveEntries(archiveDir),
+        });
+      }
     },
     "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
       if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
         dirtyReactDoctorSessions.add(input.sessionID);
       }
+      const archiveSnapshot = archiveCallSnapshots.get(input.callID)?.entries;
+      archiveCallSnapshots.delete(input.callID);
       appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
     },
+    dispose: async () => {
+      archiveCallSnapshots.clear();
+    },
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -103,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      `    <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>`,
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run ${FRAMEWORK_NAME} artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and 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/templates/capabilities/openspec-cap/mate-skills/agents/mate-openspec-backfill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mate-openspec-backfill
+description: Reverse-engineer an OpenSpec spec for one existing feature and emit a ready-to-finish backfill change. Use when the user wants to backfill, document, or spec existing or legacy behavior that has no spec yet.
+allowed-tools: Bash(openspec:*), Bash(mate:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+Create a spec for one feature that already exists in the working repository. The run ends with a standard ready-to-finish change — it never edits main specs and never finishes.
+
+## Scope rules
+
+- **One named feature per run.** Refuse Area-wide or repository-wide sweeps; ask the user to name a single feature and run the skill once per feature.
+- **Interactive by design.** Every ambiguity and every suspected bug becomes a user question. Do not run this skill unattended.
+
+## Steps
+
+1. **Scope.** Map the named feature to code: entry points, callees, tests. Use whatever exploration tooling this project has enabled (code-graph or index tools when present, otherwise search and targeted reading) — assume no specific capability is installed. Then check `openspec/specs/` for an existing capability covering this domain — prefer extending it (`MODIFIED`/`ADDED` deltas) over minting a new capability id.
+
+2. **Sweep.** Extract candidate behaviors and tag each finding:
+   - `[test-backed]` — an existing test verifies it (strongest; scenarios translate almost directly from tests)
+   - `[code-only]` — observable in code but untested
+   - `[inferred]` — assumed intent without direct evidence
+
+   Every candidate requirement needs at least one citation: a test name or `file:line`. Docs and comments corroborate but never stand alone. `[inferred]` findings are not requirements — they become questions for step 3.
+
+3. **Ask.** Batch the open questions to the user:
+   - Behavior that looks unintended → the user rules **spec the actual behavior** or **spec the intent** (with a follow-up fix change). Suspected bugs never silently become requirements.
+   - `[inferred]` findings → confirm, demote to out-of-scope, or convert to a question the emitted proposal records as open.
+
+4. **Emit.** Create the change and build its artifacts in dependency order:
+
+   ```bash
+   openspec new change "backfill-spec-<capability>"
+   openspec status --change "backfill-spec-<capability>" --json
+   openspec instructions <artifact-id> --change "backfill-spec-<capability>" --json
+   ```
+
+   The artifact set comes from the active schema (`schemaName` in the status JSON) — never assume a fixed artifact list. Follow each artifact's returned instructions and template, and state the active schema in the proposal so reviewers know which workflow produced the change. Map the backfill roles onto whatever artifacts the schema defines:
+
+   | Backfill role                                                                                  | Typical artifact (mate-v1 example) |
+   | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
+   | Scope decisions and rulings from step 3                                                        | explore-brief.md                   |
+   | "Documents existing behavior, no code changes" + open questions                                | proposal.md                        |
+   | `ADDED`/`MODIFIED` requirements, behavior only, one citation each                              | specs/                             |
+   | As-built evidence dossier: entry points, test inventory, `file:line` citations per requirement | design.md                          |
+   | Verification checklist: one task per requirement, "confirm behavior at <citation>"             | tasks.md                           |
+
+   The verification task artifact MUST open with this rule, verbatim, so the applying agent sees it without knowing this skill: "These are verification tasks for a docs-only backfill change. If a requirement fails verification, update the delta spec (reword, drop, or re-cite the requirement) — never modify code in this change. A real bug found here becomes a separate fix change."
+
+   Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync").
+
+5. **Stop.** Report the change as ready-to-finish and hand off:
+   - Verify: `openspec-apply-change` works through tasks.md, checking each requirement against the code.
+   - Finish: `mate-artifact-finish` applies the deltas to main specs and anchors the change.
+
+## Guardrails
+
+- Never write files under `openspec/specs/` — main specs change only through finished changes.
+- Never invoke any finish flow (`mate artifact finish`, `openspec archive`); stop at ready-to-finish.
+- Never emit a requirement without a citation, and never spec a suspected bug without the user's ruling.
+- Keep capability ids opaque kebab-case; extend existing capabilities before creating new ones.

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -12,6 +12,6 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 - Code comments: JSDoc format only (`/** ... */`), never `//`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
-- Never run database queries or other destructive/irreversible operations (writes, deletes, migrations, force-push, `rm -rf`, deploys) without asking the user first.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -14,6 +14,6 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 - The root `CLAUDE.md` in the companion repo is intentional and loaded by Mate. Do not create another project-level `CLAUDE.md` in the working repo unless the user explicitly asks for one.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
-- Never run database queries or other destructive/irreversible operations (writes, deletes, migrations, force-push, `rm -rf`, deploys) without asking the user first.
+- Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.
 
 <!-- MATE:COMPANION:END -->