@uniqbit/mate-core 0.18.3-canary.1 → 0.18.4

package/src/runtime/session-prepare-runner.ts

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Client side of `mate session prepare`, shared by the OpenCode plugin and the
+ * Claude session-prepare hook: spawned through the runtime-directory launcher,
+ * so a crash or stale module never reaches the session that asked.
+ */
+
+export interface PrepareRun {
+  ok: boolean;
+  /** Failed or warned steps, already worded for the operator. */
+  notes: string[];
+  /** The sync fast-forwarded the companion and re-projected it. */
+  changed?: boolean;
+}
+
+export interface PrepareRequest {
+  /** `--sync`: fast-forward the companion, re-project when it moved. */
+  sync: boolean;
+  /** Stop waiting after this long; the prepare itself is never terminated. */
+  timeoutMs?: number;
+}
+
+export type PrepareRunner = (request: PrepareRequest) => Promise<PrepareRun>;
+
+/** A guard against a hung local phase; it contains no network work. */
+export const PREPARE_TIMEOUT_MS = 30_000;
+
+interface PrepareJson {
+  ok?: boolean;
+  steps?: Array<{ step?: string; outcome?: string; detail?: string }>;
+  warnings?: string[];
+  companionChanged?: boolean;
+}
+
+export function parsePrepareOutput(stdout: string, exitCode: number | null): PrepareRun {
+  let parsed: PrepareJson | null = null;
+  try {
+    parsed = JSON.parse(stdout) as PrepareJson;
+  } catch {
+    /* not JSON: the command failed before it could report */
+  }
+  if (!parsed) {
+    const tail = stdout.trim().split("\n").slice(-3).join(" ");
+    return { ok: false, notes: [`exited ${exitCode ?? "abnormally"}${tail ? `: ${tail}` : ""}`] };
+  }
+  const notes = [
+    ...(parsed.steps ?? [])
+      .filter((step) => step.outcome === "failed")
+      .map((step) => `${step.step}: ${step.detail ?? "failed"}`),
+    ...(parsed.warnings ?? []),
+  ];
+  const changed = parsed.companionChanged === true;
+  return { ok: parsed.ok === true && exitCode === 0, notes, ...(changed ? { changed } : {}) };
+}
+
+function quoteForCmd(arg: string): string {
+  return /[\s"&|<>^()]/.test(arg) ? `"${arg.replaceAll('"', '""')}"` : arg;
+}
+
+/**
+ * How to run the runtime launcher without a shell, so a path with spaces stays
+ * one argument. Windows cannot execute the `.cmd` launcher directly, so it goes
+ * through `cmd.exe` with the line quoted here rather than by a shell.
+ */
+export function launcherInvocation(
+  mateBin: string,
+  args: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+): { command: string; args: string[]; verbatim: boolean } {
+  if (platform !== "win32") return { command: mateBin, args: [...args], verbatim: false };
+  const line = [mateBin, ...args].map(quoteForCmd).join(" ");
+  return { command: "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+}
+
+/** `stdio` is the caller's, so `spawn` still types the pipes it asked for. */
+function prepareSpawn(mateBin: string, repoPath: string, sync: boolean) {
+  const invocation = launcherInvocation(mateBin, [
+    "session",
+    "prepare",
+    "--repo",
+    repoPath,
+    "--json",
+    ...(sync ? ["--sync"] : []),
+  ]);
+  const options = {
+    cwd: repoPath,
+    shell: false,
+    detached: sync,
+    windowsHide: true,
+    windowsVerbatimArguments: invocation.verbatim,
+  };
+  return { command: invocation.command, args: invocation.args, options };
+}
+
+/**
+ * Spawns `mate session prepare` through the runtime-directory launcher. The
+ * sync is detached so it outlives a closing location: a pull must not be cut
+ * off, and the companion lock stays held until its Git work ends.
+ */
+export function spawnPrepareRunner(mateBin: string, repoPath: string): PrepareRunner {
+  return ({ sync, timeoutMs }) =>
+    new Promise((resolve) => {
+      const { command, args, options } = prepareSpawn(mateBin, repoPath, sync);
+      const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+      if (sync) child.unref();
+      let settled = false;
+      const settle = (run: PrepareRun) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(run);
+      };
+      let stdout = "";
+      let stderr = "";
+      child.stdout.setEncoding("utf8").on("data", (chunk: string) => (stdout += chunk));
+      child.stderr.setEncoding("utf8").on("data", (chunk: string) => (stderr += chunk));
+      const timer =
+        timeoutMs === undefined
+          ? undefined
+          : setTimeout(() => {
+              /** Released, not killed, so a caller about to exit does not wait on it. */
+              child.unref();
+              for (const stream of [child.stdout, child.stderr]) {
+                (stream as unknown as { unref?: () => void }).unref?.();
+              }
+              settle({ ok: false, notes: [`timed out after ${timeoutMs / 1000}s`] });
+            }, timeoutMs);
+      child.once("error", (error) =>
+        settle({ ok: false, notes: [`cannot run ${mateBin}: ${error.message}`] }),
+      );
+      child.once("close", (code) => {
+        const run = parsePrepareOutput(stdout, code);
+        settle(run.ok || stdout.trim() ? run : { ok: false, notes: [...run.notes, stderr.trim()] });
+      });
+    });
+}
+
+/**
+ * The `--sync` variant for a caller about to exit: detached and unref'd with no
+ * pipes, so the caller's exit neither waits on it nor cuts its Git work short.
+ */
+export function startDetachedPrepareSync(mateBin: string, repoPath: string): void {
+  const { command, args, options } = prepareSpawn(mateBin, repoPath, true);
+  const child = spawn(command, args, { ...options, stdio: "ignore" });
+  child.once("error", () => {});
+  child.unref();
+}

package/src/runtime/wrap-state.ts

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+
+import { hookGroupKey, type ClaudeHookGroup } from "./claude-hook-group";
+import {
+  CLAUDE_SETTINGS_DOCUMENT,
+  EMPTY_MANIFEST,
+  OPENCODE_CONFIG_DOCUMENT,
+  OPENCODE_MCP_SERVERS_AT,
+  copies,
+  documents,
+  links,
+  manifestPath,
+  parseManifest,
+  parseManifestStrict,
+  readManifestText,
+  recordedListValues,
+  recordedAudience,
+  recordedMapKeys,
+  type Manifest,
+  type WrapRuntime,
+} from "./runtime-document-manifest";
+
+/**
+ * Wrap State: the one read model over the runtime document manifest for "which
+ * runtimes are wrapped" and "which Claude hook groups does the wrap carry".
+ * Mate's own plugin groups are not folded in; `isMateGuardHookGroup` owns those.
+ */
+export interface WrapState {
+  readonly runtimes: ReadonlySet<WrapRuntime>;
+  readonly carriedClaudeHookGroups: readonly ClaudeHookGroup[];
+  carriesClaudeHookGroup(group: ClaudeHookGroup): boolean;
+  /** MCP server names the wrap declared in `.opencode/opencode.json`; user servers are not listed. */
+  readonly openCodeMcpServers: readonly string[];
+  /** The audience the checkout is wrapped for; `null` for base only. */
+  readonly audience: string | null;
+}
+
+export const WRAP_RUNTIMES: readonly WrapRuntime[] = ["claude", "opencode"];
+
+/** Wrapped for a runtime: a document, a copy or a link is recorded for it. */
+function wrappedFor(manifest: Manifest, runtime: WrapRuntime): boolean {
+  return (
+    documents(manifest, runtime).length > 0 ||
+    Object.keys(copies(manifest, runtime)).length > 0 ||
+    Object.keys(links(manifest, runtime)).length > 0
+  );
+}
+
+function isHookGroup(value: unknown): value is ClaudeHookGroup {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function wrapStateOf(manifest: Manifest): WrapState {
+  const carried = recordedListValues(manifest, CLAUDE_SETTINGS_DOCUMENT, ["hooks"]).filter(
+    isHookGroup,
+  );
+  const carriedKeys = new Set(carried.map(hookGroupKey));
+  return {
+    runtimes: new Set(WRAP_RUNTIMES.filter((runtime) => wrappedFor(manifest, runtime))),
+    carriedClaudeHookGroups: carried,
+    carriesClaudeHookGroup: (group) => carriedKeys.has(hookGroupKey(group)),
+    openCodeMcpServers: recordedMapKeys(
+      manifest,
+      OPENCODE_CONFIG_DOCUMENT,
+      OPENCODE_MCP_SERVERS_AT,
+    ),
+    audience: recordedAudience(manifest),
+  };
+}
+
+/** Where no Projection Root resolves: nothing is wrapped. */
+export const NOT_WRAPPED: WrapState = wrapStateOf(EMPTY_MANIFEST);
+
+/**
+ * Lenient, for session-start readers that must never fail: an absent or
+ * unreadable manifest reads as not wrapped.
+ */
+export function readWrapStateSync(repoPath: string): WrapState {
+  let raw: string | null = null;
+  try {
+    raw = fs.readFileSync(manifestPath(repoPath), "utf8");
+  } catch {
+    /* absent or unreadable: not wrapped */
+  }
+  return wrapStateOf(parseManifest(raw));
+}
+
+/**
+ * Strict, for writers: a manifest that exists but cannot be read or parsed
+ * throws, so a rewrite never strips wrap-placed content it could not see.
+ */
+export async function readWrapState(repoPath: string): Promise<WrapState> {
+  return wrapStateOf(parseManifestStrict(await readManifestText(repoPath)));
+}

package/src/runtime/write-atomic.ts

@@ -0,0 +1,27 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+
+/**
+ * Writes via a sibling temp file + `fs.rename()` so an interrupted write cannot
+ * leave a half-written document behind. A reader racing this one — a Claude
+ * Code session holding `~/.claude.json` open — observes the old file or the new
+ * one, never a truncated one.
+ */
+export async function writeAtomic(
+  target: string,
+  contents: string | Buffer,
+  mode?: number,
+): Promise<void> {
+  const tempPath = `${target}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(
+      tempPath,
+      contents,
+      mode === undefined ? "utf8" : { encoding: "utf8", mode },
+    );
+    await fs.rename(tempPath, target);
+  } catch (error) {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}

package/src/templates/capabilities/openspec-cap/mate-minimal/schema.yaml

@@ -1,5 +1,5 @@
 name: mate-minimal
-version: 2
+version: 3
 description: Mate's short OpenSpec workflow for one-Area, low-risk changes - specs → tasks
 artifacts:
   - id: specs
@@ -55,3 +55,4 @@ apply:
   instruction: |
     Read the delta specs and work through pending tasks only within the affected Areas. Mark complete as you go.
     Pause if you hit blockers or need clarification.
+    Before reporting the change complete, follow the verification rules in `openspec/mate-conventions.yaml`.

package/src/templates/capabilities/openspec-cap/mate-v1/schema.yaml

@@ -1,5 +1,5 @@
 name: mate-v1
-version: 8
+version: 9
 description: Mate's complete OpenSpec workflow - proposal → specs → design → tasks
 artifacts:
   - id: proposal
@@ -242,3 +242,4 @@ apply:
   instruction: |
     Read context files and work through pending tasks only within the proposal's affected Areas. Mark complete as you go.
     Pause if you hit blockers or need clarification.
+    Before reporting the change complete, follow the verification rules in `openspec/mate-conventions.yaml`.

package/src/templates/capabilities/openspec-cap/openspec-conventions.yaml

@@ -15,6 +15,11 @@ rules: |
   - Every requirement MUST carry an Area marker whose values appear in the delta frontmatter. This survives archive, which copies requirement blocks but discards delta frontmatter.
   - A canonical spec uses flat frontmatter: type: spec, capability, scalar repository, areas list, and tags: [openspec/spec]. It MUST NOT retain a nested scopes list or delta-only change and delta tags.
   - To project a delta, all its scope entries MUST name the same repository. Emit that repository as the canonical scalar and distinct Areas as areas in their original order. If repositories differ, split the capability before archive.
+verification: |
+  Verification skills check a change before it is reported complete. They apply only when the skill is available in the current session; a skill that is not available adds no task and no step.
+  - mate-react-doctor: when writing tasks, end the task list of every Area whose tasks change React code (components, hooks, or other .tsx/.jsx modules) with one verification task, numbered like its neighbours, for example `- [ ] N.M Verify React changes with React Doctor [skill:mate-react-doctor]`. Areas whose tasks do not change React code get no verification task.
+  - During apply, a tagged verification task is worked like any other task by invoking its skill.
+  - Before reporting a change complete, check every Area that changed React code: if its tagged verification task is already checked, do nothing more; otherwise invoke the skill once for that Area.
 example_delta_frontmatter: |
   ---
   type: delta-spec

package/src/templates/capabilities/react-doctor/mate-react-doctor/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: mate-react-doctor
+description: Verify React changes with Mate's pinned React Doctor. Use when a task is tagged `[skill:mate-react-doctor]`, when the shared Mate verification rules call for it before finishing an OpenSpec change, or when the user asks to scan, check, or triage React diagnostics for the current changes.
+metadata:
+  credits:
+    skill: react-doctor
+    author: Million Software, Inc.
+    url: "https://github.com/millionco/react-doctor"
+---
+
+# Mate React Doctor
+
+Scan the React code the current change touched, fix the regressions this change introduced, and report the rest. React Doctor covers correctness, accessibility, performance, security, and maintainability.
+
+## Mate Workflow
+
+- Run only Mate's pinned React Doctor binary. Never run `npx react-doctor`, never install another version, and never fetch remote prompts or playbooks.
+- Scan the Working Repository, not the Companion Repository.
+- Fix only what this change introduced. Leave findings that existed before the change alone.
+- Never create issues, commits, or pull requests.
+- Run `mate cap index --tokensave` after code changes.
+
+## Steps
+
+### 1. Resolve the binary
+
+Print the path first, then call the absolute path it prints, so the command matches Mate's pre-seeded permission:
+
+```bash
+printf '%s\n' "$MATE_REACT_DOCTOR_BIN_PATH"
+```
+
+If the variable is empty or the path is not executable, stop. Report "React Doctor skipped: the pinned binary is unavailable (MATE_REACT_DOCTOR_BIN_PATH is not set; is the react-doctor capability enabled?)". A verification task may be checked with that note.
+
+### 2. Choose the base
+
+Compare against the point where the change's branch left the default branch, so work already committed during apply is included:
+
+```bash
+default_branch=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)
+git merge-base HEAD "$default_branch"
+```
+
+If no merge-base resolves, or HEAD is on the default branch, use `HEAD` (uncommitted changes only).
+
+### 3. Scan
+
+Run from the root of the Area being verified (the package that holds the React code):
+
+```bash
+<absolute-bin> --yes --verbose --scope changed --base <base> --no-score
+```
+
+Add `--include-untracked` when the change created new files that are not committed yet.
+
+### 4. Separate environment problems from findings
+
+These outputs mean the scan could not run, not that the code is wrong. Report a skip with the reason and change nothing:
+
+| Output contains             | Meaning                                   |
+| --------------------------- | ----------------------------------------- |
+| `No React dependency found` | The Area is not a React project           |
+| `Could not resolve config`  | The React Doctor config could not be read |
+| `is not a git repository`   | The scan root is outside a git checkout   |
+
+### 5. Fix regressions introduced by the change
+
+For each remaining finding:
+
+1. Confirm it is in code this change added or modified (`git diff <base> -- <file>`). If the finding predates the change, leave it and do not list it as a regression.
+2. Understand the rule before changing code: `<absolute-bin> rules explain <rule>`.
+3. Make the smallest fix that satisfies the rule and keeps the change's intended behavior. Run the relevant tests.
+
+Then run the scan from step 3 again. Repeat until nothing introduced by the change remains, or only findings you cannot fix in scope are left.
+
+### 6. Report
+
+Finish with a short summary:
+
+- **Result:** passed, fixed (N findings), skipped (reason), or findings left.
+- **Fixed:** rule and file:line for each fix.
+- **Left:** rule, file:line, and why it was not fixed here. Typical reasons are that it needs a design decision, changes behavior outside the change's scope, or is a false positive. Do not file these anywhere.
+
+Do not disable or downgrade rules to make a scan pass. Change the React Doctor configuration only when the user asks. For that, follow [references/explain.md](references/explain.md).

package/src/templates/capabilities/react-doctor/{skill → mate-react-doctor}/references/explain.md

@@ -1,19 +1,22 @@
 # Explaining and configuring rules
 
 Explain React Doctor rules and edit `doctor.config.*` safely. Use this when a user
-wants to understand a rule or change which rules run — not for fixing diagnostics
-(that is the main `react-doctor` skill / `/doctor`).
+wants to understand a rule or change which rules run, not for fixing diagnostics
+(that is the main `mate-react-doctor` workflow).
 
 Triggers: "why did this rule fire", "I disagree with this rule", "turn this rule off",
 "stop flagging X", "too noisy", "disable design rules".
 
+In every command below, `<bin>` is the absolute path printed by
+`printf '%s\n' "$MATE_REACT_DOCTOR_BIN_PATH"`. Never substitute `npx react-doctor`.
+
 ## Workflow
 
 1. Identify the rule key from the diagnostic (e.g. `react-doctor/no-array-index-as-key`).
 2. Explain it before changing anything:
 
 ```bash
-npx react-doctor@latest rules explain react-doctor/no-array-index-as-key
+<bin> rules explain react-doctor/no-array-index-as-key
 ```
 
 3. Pick the narrowest control that matches the user's intent (see decision guide).
@@ -21,22 +24,22 @@ npx react-doctor@latest rules explain react-doctor/no-array-index-as-key
 5. Validate the change did what they wanted:
 
 ```bash
-npx react-doctor@latest --verbose --diff
+<bin> --verbose --scope changed --no-score
 ```
 
 ## Commands
 
 ```bash
-npx react-doctor@latest rules list                         # every rule + its effective severity
-npx react-doctor@latest rules list --configured            # only what your config changed
-npx react-doctor@latest rules list --category Performance   # filter by category
-npx react-doctor@latest rules explain <rule>               # why it matters + how to configure
-npx react-doctor@latest rules disable <rule>               # rule never runs
-npx react-doctor@latest rules enable <rule>                # turn back on at its recommended severity
-npx react-doctor@latest rules set <rule> warn              # off | warn | error
-npx react-doctor@latest rules category "React Native" off   # whole category
-npx react-doctor@latest rules ignore-tag design            # skip a rule family (design, test-noise, …)
-npx react-doctor@latest rules unignore-tag design
+<bin> rules list                         # every rule + its effective severity
+<bin> rules list --configured            # only what your config changed
+<bin> rules list --category Performance  # filter by category
+<bin> rules explain <rule>               # why it matters + how to configure
+<bin> rules disable <rule>               # rule never runs
+<bin> rules enable <rule>                # turn back on at its recommended severity
+<bin> rules set <rule> warn              # off | warn | error
+<bin> rules category "React Native" off  # whole category
+<bin> rules ignore-tag design            # skip a rule family (design, test-noise, …)
+<bin> rules unignore-tag design
 ```
 
 Rule references accept the full key (`react-doctor/no-danger`), the bare id (`no-danger`), or a legacy key (`react/no-danger`).
@@ -69,4 +72,4 @@ export default {
 
 ## Educating the user
 
-When explaining a rule, lead with the "Why it matters" guidance from `rules explain` and, when they want depth, the per-rule recipe at `https://www.react.doctor/prompts/rules/<plugin>/<rule>.md`. Only after they understand it should you offer to disable it — many "bad" rules are catching real issues.
+When explaining a rule, lead with the "Why it matters" guidance from `<bin> rules explain <rule>`. Only after they understand it should you offer to disable it — many "bad" rules are catching real issues.

package/src/templates/mate-skills/agents/mate-openspec-backfill/SKILL.md

@@ -1,26 +1,26 @@
 ---
 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:*)
+description: Reverse-engineer an OpenSpec spec for one existing feature and write it directly to the canonical spec, ready to publish. 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:*), Bash(git remote:*), Bash(git diff:*)
 license: MIT
 compatibility: Requires the mate CLI and the openspec capability enabled.
 metadata:
   author: mate
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Mate OpenSpec Backfill
 
-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.
+Specify one feature that already exists in the working repository. A backfill records behavior that already shipped, so the run writes the canonical spec `openspec/specs/<capability>/spec.md` directly and leaves it uncommitted. It never creates a change and never publishes; publication happens afterwards through `mate-artifact-publish`.
 
 ## 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.
+- **Interactive by design.** Every ambiguity and every suspected bug becomes a user question, and nothing is written before the user approves the review table. 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.
+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 in place 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)
@@ -30,38 +30,54 @@ Create a spec for one feature that already exists in the working repository. The
    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.
+   - Behavior that looks unintended → the user rules **spec the actual behavior** or **spec the intent** (and the user may open a separate fix change). Suspected bugs never silently become requirements.
+   - `[inferred]` findings → confirm, demote to out-of-scope, or drop.
 
-4. **Emit.** Create the change and build its artifacts in dependency order:
+4. **Review.** Before writing any file, present every drafted requirement in one table and wait for the user's approval:
+
+   | Requirement                     | Evidence        | Citation                         |
+   | ------------------------------- | --------------- | -------------------------------- |
+   | Propagates the child exit code  | `[test-backed]` | `launch.test.ts` › "exits with…" |
+   | Refuses an unknown framework id | `[code-only]`   | `src/launch.ts:142`              |
+
+   Write only the requirements the user approves, worded as approved. A rejected requirement is not written. This table is the only place citations and evidence tags appear — they never go into the spec.
+
+5. **Learn the spec format.** Never assume a spec format. Read it from the schema active in this OpenSpec root, so the run follows whichever workflow the project uses:
 
    ```bash
-   openspec new change "backfill-spec-<capability>"
-   openspec status --change "backfill-spec-<capability>" --json
-   openspec instructions <artifact-id> --change "backfill-spec-<capability>" --json
+   openspec schema which <schema-name> --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:
+   - The active schema name is the `schema:` key in `openspec/config.yaml`. When the file or key is absent, it is OpenSpec's default, `spec-driven`.
+   - In the returned `path`, read `schema.yaml` and find the artifact that generates the specs (`generates: specs/**/*.md`). Read its `instruction`, its `template` under `templates/`, and every reference file the instruction tells you to read (for example `openspec/mate-conventions.yaml`).
+   - Those sources usually describe the **delta** a change writes. You write the **canonical** spec that archive would produce from it, so apply the schema's own delta-to-canonical rules: requirement blocks go under `## Requirements` instead of `## ADDED Requirements`, and frontmatter, per-requirement markers, and `## Purpose` take the canonical shape the schema or its references define. Leave out delta-only elements such as change backlinks and change or delta tags.
+   - When a spec already exists under `openspec/specs/`, use it as a concrete example of the canonical shape, but follow the schema where the two disagree.
+   - Derive any repository identity the format needs from the Git remote (`git remote get-url origin`), and any Area or scope value from the schema's rules. Never invent a format element the schema does not define.
+
+6. **Write.** Write the approved requirements to `openspec/specs/<capability>/spec.md` in the format from step 5.
+
+   **New capability.** Create the file with the schema's canonical frontmatter (when it defines one), a `## Purpose` section of one or two sentences, and a `## Requirements` section holding the approved requirements with their scenarios.
 
-   | 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                           |
+   **Existing capability.** Edit its `spec.md` in place: append new requirements under `## Requirements` and rewrite only the requirements the user's rulings change. Preserve every other requirement, the frontmatter, and the Purpose exactly.
 
-   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."
+   In both cases every requirement you write carries each per-requirement marker the schema requires (for example an `**Area:**` marker whose value appears in the spec's frontmatter). Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync"). The spec contains no citations, no `file:line` references, and no evidence tags.
+
+7. **Validate.** Run:
+
+   ```bash
+   openspec validate <capability> --type spec
+   ```
 
-   Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync").
+   Fix every reported error and re-validate until it passes. Do not hand off a spec that fails validation.
 
-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.
-   - Publish: `mate-artifact-publish` applies the deltas to main specs and anchors the change.
+8. **Hand off.** Report the written path and show the uncommitted diff (`git diff -- openspec/specs/<capability>/`, or the file itself when it is new). Point the user to `mate-artifact-publish`: the spec appears there under **Drifted specs** and can be published on its own or with the rest.
 
 ## Guardrails
 
-- Never write files under `openspec/specs/` — main specs change only through finished changes.
-- Never invoke any finish flow (`mate artifact publish`, `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.
+- Never create an OpenSpec change, change artifacts, or verification tasks, and never archive.
+- Never commit, tag, push, or publish — never run `mate artifact publish`. Publication belongs to `mate-artifact-publish`.
+- Never write any file before the user approves the review table.
+- Never write a requirement without a citation in the review table, and never spec a suspected bug without the user's ruling.
+- Never write citations or evidence tags into the canonical spec.
+- Never hard-code a spec format: take it from the active schema on every run.
+- Keep capability ids opaque kebab-case; extend existing capabilities in place before creating new ones, and never drop or reword requirements outside the named feature.

package/src/templates/mate-skills/agents/mate-show-me/SKILL.md

@@ -137,7 +137,7 @@ If the document fails contract validation, report the diagnostic and correct the
 - Use Mermaid whenever the user asks for a diagram or the subject has meaningful control flow, sequencing, lifecycle, or relationships. A `text` payload is a deliberate fallback, not the default for runtime flows.
 - Pick the diagram type that matches the question: `classDiagram` for structure, `sequenceDiagram` for interaction between components, `stateDiagram-v2` for lifecycles, `flowchart TD` for control flow and call trees.
 - Keep labels short enough to read at report width. A label that needs a sentence belongs in the neighbouring `text` section.
-- Do not use ELK-only layouts or math labels. The report inlines the self-contained mermaid bundle, which may not carry those chunks.
+- Do not use ELK-only layouts or math labels. The report loads the single-file mermaid build from a CDN, which does not carry those chunks.
 - Pair each Mermaid visual with a short neighbouring `text` section that calls out the ownership boundary or invariant the reader should notice.
 - Prefer the `text` payload for pseudocode, shallow file trees, or cases where a picture would genuinely obscure the point.