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

package/src/runtime/secret-patterns.ts

@@ -0,0 +1,164 @@
+/**
+ * The one secret-file pattern set every guardrail layer reads: guidance,
+ * projected deny rules, hook and middleware enforcement, indexer exclusion and
+ * the publish scan. Keeping it in one module is what stops the layers from
+ * disagreeing about what a secret file is.
+ */
+
+export const DEFAULT_SECRET_DENY_PATTERNS: readonly string[] = [
+  ".env",
+  ".env.*",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "id_rsa",
+  "id_ecdsa",
+  "id_ed25519",
+  ".netrc",
+  ".pgpass",
+  ".npmrc",
+];
+
+/** Example files that document which variables exist; they never hold values. */
+export const DEFAULT_SECRET_ALLOW_PATTERNS: readonly string[] = [
+  ".env.example",
+  ".env.sample",
+  ".env.template",
+  ".env.dist",
+];
+
+export interface SecretPolicy {
+  /** False only when the companion explicitly opts out. */
+  guardrails: boolean;
+  /** Defaults plus the companion's extra `secrets.deny` patterns. */
+  deny: string[];
+  /** Defaults plus the companion's extra `secrets.allow` patterns. */
+  allow: string[];
+}
+
+export const defaultSecretPolicy = (): SecretPolicy => ({
+  guardrails: true,
+  deny: [...DEFAULT_SECRET_DENY_PATTERNS],
+  allow: [...DEFAULT_SECRET_ALLOW_PATTERNS],
+});
+
+function patternList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "");
+}
+
+/**
+ * Parses the `secrets` block of `framework.yaml`. Anything that is not an
+ * object yields the defaults with guardrails on, and only a literal `false`
+ * turns them off: a broken config never disables protection.
+ */
+export function parseSecretsConfig(value: unknown): SecretPolicy {
+  const policy = defaultSecretPolicy();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return policy;
+  const block = value as Record<string, unknown>;
+  return {
+    guardrails: block.guardrails !== false,
+    deny: [...policy.deny, ...patternList(block.deny)],
+    allow: [...policy.allow, ...patternList(block.allow)],
+  };
+}
+
+const compiled = new Map<string, RegExp>();
+
+/** Gitignore-style subset: `*` and `?` stay inside a segment, `**` crosses them. */
+function patternRegExp(pattern: string): RegExp {
+  const cached = compiled.get(pattern);
+  if (cached) return cached;
+  let source = "";
+  const body = pattern.replace(/^\/+/, "");
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    if (char === "*" && body[i + 1] === "*") {
+      // `**/` matches zero or more whole segments; a bare `**` matches anything.
+      if (body[i + 2] === "/") {
+        source += "(?:.*/)?";
+        i += 2;
+      } else {
+        source += ".*";
+        i += 1;
+      }
+    } else if (char === "*") {
+      source += "[^/]*";
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  // A slash-free pattern matches the basename; one with a slash matches the
+  // trailing segments of the path, since the repository root is not known here.
+  const regExp = body.includes("/") ? new RegExp(`(?:^|/)${source}$`) : new RegExp(`^${source}$`);
+  compiled.set(pattern, regExp);
+  return regExp;
+}
+
+function normalizePath(filePath: string): string {
+  return filePath.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+
+export function matchesSecretPattern(filePath: string, patterns: readonly string[]): boolean {
+  const normalized = normalizePath(filePath);
+  if (!normalized) return false;
+  const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return patterns.some((pattern) => {
+    const regExp = patternRegExp(pattern);
+    return pattern.replace(/^\/+/, "").includes("/")
+      ? regExp.test(normalized)
+      : regExp.test(basename);
+  });
+}
+
+/** A path is a secret file when it matches a deny pattern and no allow pattern. */
+export function isSecretFile(filePath: string, policy: SecretPolicy): boolean {
+  return (
+    matchesSecretPattern(filePath, policy.deny) && !matchesSecretPattern(filePath, policy.allow)
+  );
+}
+
+/**
+ * Narrower stand-ins for a default deny pattern that also matches an allowed
+ * file. Runtime deny rules are evaluated before allow rules, so `.env.*` there
+ * would deny `.env.example` too; these cover the common environment files.
+ */
+const ALLOW_SAFE_EXPANSIONS: Readonly<Record<string, readonly string[]>> = {
+  ".env.*": [".env.local", ".env.development", ".env.production", ".env.test", ".env.*.local"],
+};
+
+/**
+ * The default deny patterns a runtime's own deny rules may carry: every
+ * default that can't match an allow-listed file, with an overlapping pattern
+ * replaced by its narrower stand-ins. Extra `secrets.deny` patterns are never
+ * projected: once removed from config, nothing would mark their rules as Mate's.
+ */
+export function projectableSecretDenyPatterns(): string[] {
+  const overlapsAllow = (pattern: string) =>
+    DEFAULT_SECRET_ALLOW_PATTERNS.some((allowed) => matchesSecretPattern(allowed, [pattern]));
+  return DEFAULT_SECRET_DENY_PATTERNS.flatMap((pattern) =>
+    overlapsAllow(pattern) ? (ALLOW_SAFE_EXPANSIONS[pattern] ?? []) : [pattern],
+  ).filter((pattern) => !overlapsAllow(pattern));
+}
+
+/** Ordinary files a broad glob also matches; a glob matching one is not aimed at secrets. */
+const ORDINARY_SAMPLES = ["index.ts", "README.md", "config.json"];
+
+/**
+ * Whether a search glob is aimed at secret files: it matches a sample name of
+ * some deny pattern that the policy still treats as secret, and no ordinary
+ * file. `.env*` and `*.key` are; `**\/*` and `*.ts` are not. A heuristic for
+ * search tools, which take a glob rather than a path.
+ */
+export function globTargetsSecretFiles(glob: string, policy: SecretPolicy): boolean {
+  const pattern = glob.trim();
+  if (!pattern) return false;
+  if (ORDINARY_SAMPLES.some((sample) => matchesSecretPattern(sample, [pattern]))) return false;
+  return policy.deny.some((deny) => {
+    const sample = deny.slice(deny.lastIndexOf("/") + 1).replace(/[*?]+/g, "x");
+    return isSecretFile(sample, policy) && matchesSecretPattern(sample, [pattern]);
+  });
+}

package/src/runtime/secret-scan.ts

@@ -0,0 +1,90 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { lintSource as LintSourceFn } from "@secretlint/core";
+import type { SecretLintCoreConfig } from "@secretlint/types";
+
+/** One secretlint finding. Deliberately carries no message: messages quote the value. */
+export interface SecretFinding {
+  path: string;
+  line: number;
+  ruleId: string;
+}
+
+type LintSource = typeof LintSourceFn;
+
+let engine: Promise<{ lintSource: LintSource; config: SecretLintCoreConfig }> | undefined;
+
+/**
+ * Loaded on first use only, so hook calls that never scan don't pay for it.
+ * The config is fixed in memory: the recommended preset and nothing else. No
+ * `.secretlintrc` is ever read, so a repository can't weaken the scan.
+ */
+function loadEngine() {
+  engine ??= (async () => {
+    const [{ lintSource }, { creator }] = await Promise.all([
+      import("@secretlint/core"),
+      import("@secretlint/secretlint-rule-preset-recommend"),
+    ]);
+    const config: SecretLintCoreConfig = {
+      rules: [{ id: "@secretlint/secretlint-rule-preset-recommend", rule: creator }],
+    };
+    return { lintSource, config };
+  })();
+  return engine;
+}
+
+/** Scans in-memory content. Throws when the engine fails, so callers can fail closed. */
+export async function scanContent(filePath: string, content: string): Promise<SecretFinding[]> {
+  const { lintSource, config } = await loadEngine();
+  const result = await lintSource({
+    source: { content, filePath, contentType: "text" },
+    options: { config, maskSecrets: true, noPhysicFilePath: true },
+  });
+  return result.messages.map((message) => ({
+    path: filePath,
+    line: message.loc.start.line,
+    ruleId: message.ruleId,
+  }));
+}
+
+/** Every file under a path, in name order; a path that doesn't exist yields none. */
+export async function listFiles(target: string): Promise<string[]> {
+  let stat;
+  try {
+    stat = await fs.stat(target);
+  } catch {
+    return [];
+  }
+  if (stat.isFile()) return [target];
+  if (!stat.isDirectory()) return [];
+  const entries = await fs.readdir(target, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries
+      .toSorted((a, b) => a.name.localeCompare(b.name))
+      .map((entry) => listFiles(path.join(target, entry.name))),
+  );
+  return nested.flat();
+}
+
+/** Scans files and directories on disk; paths that don't exist are skipped. */
+export async function scanFiles(targets: readonly string[]): Promise<SecretFinding[]> {
+  const findings: SecretFinding[] = [];
+  for (const target of targets) {
+    // oxlint-disable-next-line no-await-in-loop -- findings keep the caller's order
+    for (const file of await listFiles(target)) {
+      // oxlint-disable-next-line no-await-in-loop -- one file at a time bounds memory
+      const content = await fs.readFile(file, "utf8");
+      // oxlint-disable-next-line no-await-in-loop -- see above
+      findings.push(...(await scanContent(file, content)));
+    }
+  }
+  return findings;
+}
+
+/** One line per finding, for refusal messages: never the value. Line 0 means the whole file. */
+export function describeSecretFindings(findings: readonly SecretFinding[]): string[] {
+  return findings.map(
+    (finding) => `${finding.path}${finding.line > 0 ? `:${finding.line}` : ""} (${finding.ruleId})`,
+  );
+}

package/src/runtime/session-kind.ts

@@ -0,0 +1,13 @@
+/**
+ * The kind of session a prepare or a delivery plan answers for, shared by every
+ * Agent Runtime. `managed-repo`: a managed launch with a Working Repository; its
+ * prepare just reconciled the wrap, which the launcher asserts.
+ * `managed-companion`: a companion-scoped managed launch. `unmanaged`: a
+ * session with no launch environment.
+ */
+export type SessionKind = "managed-repo" | "managed-companion" | "unmanaged";
+
+/** A managed launch's kind: with a Working Repository, or companion-scoped. */
+export function managedSessionKind(withRepository: boolean): SessionKind {
+  return withRepository ? "managed-repo" : "managed-companion";
+}

package/src/runtime/shell-heredoc.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a heredoc starts, matched at a `<<` outside quotes: an optional `-`,
+ * then the terminator word, optionally quoted. Shared by the secret guard's
+ * shell tokenizer and the artifact guard's redirect scan, so both agree on
+ * what is command text and what is a body.
+ */
+export const HEREDOC_MARKER = /^<<-?\s*(['"]?)([\w.-]+)\1/;
+
+/** The terminators a command line opens, in order; quoted text is skipped. */
+function heredocTerminators(line: string): string[] {
+  const terminators: string[] = [];
+  let quote: string | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else if (char === "\\" && quote === '"') i++;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "\\") {
+      i++;
+    } else if (char === "<" && line[i + 1] === "<") {
+      if (line[i + 2] === "<") {
+        i += 2;
+        continue;
+      }
+      const marker = HEREDOC_MARKER.exec(line.slice(i));
+      if (marker) {
+        terminators.push(marker[2]);
+        i += marker[0].length - 1;
+      } else {
+        i++;
+      }
+    }
+  }
+  return terminators;
+}
+
+/** A heredoc body and the line, in the stripped command, whose marker opened it. */
+export interface HeredocBody {
+  line: number;
+  text: string;
+}
+
+/** The command's own lines and each heredoc body, split in one pass. */
+function splitHeredocs(command: string): { kept: string[]; bodies: HeredocBody[] } {
+  const kept: string[] = [];
+  const bodies: HeredocBody[] = [];
+  const pending: string[] = [];
+  let body: string[] = [];
+  for (const line of command.split("\n")) {
+    if (pending.length > 0) {
+      if (line.trim() === pending[0]) {
+        pending.shift();
+        bodies.push({ line: kept.length - 1, text: body.join("\n") });
+        body = [];
+      } else {
+        body.push(line);
+      }
+      continue;
+    }
+    kept.push(line);
+    pending.push(...heredocTerminators(line));
+  }
+  if (pending.length > 0) bodies.push({ line: kept.length - 1, text: body.join("\n") });
+  return { kept, bodies };
+}
+
+/**
+ * The command with every heredoc body and terminator line removed. Marker
+ * lines stay: a redirect the command performs is spelled there, never in the
+ * body it writes. A heuristic, not a parser, like the tokenizer it mirrors.
+ */
+export function stripHeredocBodies(command: string): string {
+  return splitHeredocs(command).kept.join("\n");
+}
+
+/** Every heredoc body in the command, in order; an unterminated one runs to the end. */
+export function heredocBodies(command: string): HeredocBody[] {
+  return splitHeredocs(command).bodies;
+}

package/src/runtime/wrap-state.ts

@@ -9,6 +9,7 @@ import {
   copies,
   documents,
   links,
+  recordedMapEntries,
   manifestPath,
   parseManifest,
   parseManifestStrict,
@@ -21,13 +22,16 @@ import {
 
 /**
  * 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".
+ * runtimes are wrapped" and "which Claude hook groups and plugin folders 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;
+  /** Capability plugin folders the wrap enables through a `directory` marketplace, as recorded. */
+  readonly carriedClaudePluginDirectories: readonly string[];
   /** MCP server names the wrap declared in `.opencode/opencode.json`; user servers are not listed. */
   readonly openCodeMcpServers: readonly string[];
 }
@@ -43,10 +47,39 @@ function wrappedFor(manifest: Manifest, runtime: WrapRuntime): boolean {
   );
 }
 
-function isHookGroup(value: unknown): value is ClaudeHookGroup {
+/**
+ * The folders of the recorded `directory` marketplaces whose plugin the wrap
+ * also enables: one without the other loads nothing.
+ */
+function carriedPluginDirectories(manifest: Manifest): string[] {
+  const marketplaces = recordedMapEntries(manifest, CLAUDE_SETTINGS_DOCUMENT, [
+    "extraKnownMarketplaces",
+  ]);
+  const enabled = recordedMapEntries(manifest, CLAUDE_SETTINGS_DOCUMENT, ["enabledPlugins"]);
+  const enabledMarketplaces = new Set(
+    Object.entries(enabled)
+      .filter(([, value]) => value === true)
+      .map(([id]) => id.slice(id.lastIndexOf("@") + 1)),
+  );
+  return Object.entries(marketplaces).flatMap(([name, entry]) => {
+    const source = isRecord(entry) ? entry.source : undefined;
+    return enabledMarketplaces.has(name) &&
+      isRecord(source) &&
+      source.source === "directory" &&
+      typeof source.path === "string"
+      ? [source.path]
+      : [];
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isHookGroup(value: unknown): value is ClaudeHookGroup {
+  return isRecord(value);
+}
+
 export function wrapStateOf(manifest: Manifest): WrapState {
   const carried = recordedListValues(manifest, CLAUDE_SETTINGS_DOCUMENT, ["hooks"]).filter(
     isHookGroup,
@@ -56,6 +89,7 @@ export function wrapStateOf(manifest: Manifest): WrapState {
     runtimes: new Set(WRAP_RUNTIMES.filter((runtime) => wrappedFor(manifest, runtime))),
     carriedClaudeHookGroups: carried,
     carriesClaudeHookGroup: (group) => carriedKeys.has(hookGroupKey(group)),
+    carriedClaudePluginDirectories: carriedPluginDirectories(manifest),
     openCodeMcpServers: recordedMapKeys(
       manifest,
       OPENCODE_CONFIG_DOCUMENT,

package/src/runtime/write-atomic.ts

@@ -1,5 +1,7 @@
+// oxlint-disable no-await-in-loop
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 
 /**
  * Writes via a sibling temp file + `fs.rename()` so an interrupted write cannot
@@ -11,17 +13,79 @@ export async function writeAtomic(
   target: string,
   contents: string | Buffer,
   mode?: number,
+): Promise<void> {
+  await replaceViaTemp(target, contents, mode, false);
+}
+
+/** `exactMode`: chmod past the umask, so a replaced file keeps the mode it had. */
+async function replaceViaTemp(
+  target: string,
+  contents: string | Buffer,
+  mode: number | undefined,
+  exactMode: boolean,
 ): Promise<void> {
   const tempPath = `${target}.${crypto.randomUUID()}.tmp`;
   try {
+    /** Created with the mode, so private contents are never readable at a wider one. */
     await fs.writeFile(
       tempPath,
       contents,
       mode === undefined ? "utf8" : { encoding: "utf8", mode },
     );
+    if (exactMode && mode !== undefined) await fs.chmod(tempPath, mode);
     await fs.rename(tempPath, target);
   } catch (error) {
     await fs.rm(tempPath, { force: true }).catch(() => {});
     throw error;
   }
 }
+
+const MAX_LINK_HOPS = 40;
+
+/**
+ * Follows a symlink chain to its end, which may not exist yet: a dangling link names where to create.
+ * Link text is never normalized lexically: `..` after a directory symlink means the real parent.
+ */
+async function resolveLinkEnd(filePath: string): Promise<string> {
+  let current = filePath;
+  for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+    const parent = await fs.realpath(path.dirname(current));
+    const entry = path.join(parent, path.basename(current));
+    const link = await fs.readlink(entry).catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT" || error.code === "EINVAL") return null;
+      throw error;
+    });
+    if (link === null) return entry;
+    current = path.isAbsolute(link) ? link : `${parent}${path.sep}${link}`;
+  }
+  throw Object.assign(new Error(`too many levels of symbolic links: ${filePath}`), {
+    code: "ELOOP",
+  });
+}
+
+/**
+ * As `writeAtomic`, through a symlink: the link stays and its target is
+ * replaced, or created when the link dangles. An existing file keeps its mode.
+ * A read-only file is refused, as a plain write would refuse it. A hardlinked
+ * file is written in place: replacing it would split it from its other links.
+ */
+export async function writeAtomicThroughLink(
+  filePath: string,
+  contents: string | Buffer,
+): Promise<void> {
+  const target = await resolveLinkEnd(filePath);
+  const existing = await fs.stat(target).catch(() => null);
+  if (existing && existing.nlink > 1) return fs.writeFile(target, contents, "utf8");
+  if (existing) await fs.access(target, fs.constants.W_OK);
+  await replaceViaTemp(target, contents, existing ? existing.mode & 0o7777 : undefined, true);
+}
+
+/**
+ * Deletes a file its writer left without content. A symlink stays: deleting it
+ * would leave the old text in its target, so the target is emptied instead.
+ */
+export async function removeEmptiedFile(filePath: string): Promise<void> {
+  const entry = await fs.lstat(filePath);
+  if (entry.isSymbolicLink()) await writeAtomicThroughLink(filePath, "");
+  else await fs.unlink(filePath);
+}

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

@@ -1,5 +1,5 @@
 name: mate-minimal
-version: 3
+version: 4
 description: Mate's short OpenSpec workflow for one-Area, low-risk changes - specs → tasks
 artifacts:
   - id: specs
@@ -27,11 +27,13 @@ artifacts:
         include **Reason** and **Migration**.
 
       Every user story carries an **Area:** marker naming the Areas it binds, using values from
-      the frontmatter scopes - always, even when there is only one Area.
+      the `scopes` in the spec's `mate:delta` comment - always, even when there is only one Area.
 
-      **Obsidian**: Emit YAML frontmatter with `type: delta-spec`, the actual change name, the
-      capability, the `openspec/change`, `openspec/spec`, and `openspec/delta` tags, and paired
-      `scopes` metadata.
+      Start each spec file with a `<!-- mate:delta` comment on its very first line, not YAML
+      frontmatter. The comment holds YAML with the actual change name as `change`, the
+      `capability`, and paired `scopes` metadata, and closes with `-->` on its own line. Between
+      the comment and the first `## ` section, put nothing but blank lines and at most one `# `
+      title line, or `openspec validate --strict` reports the text archive would drop.
     requires: []
   - id: tasks
     generates: tasks.md
@@ -39,7 +41,7 @@ artifacts:
     template: tasks.md
     instruction: |
       Create a flat implementation checklist that satisfies the delta specs. Keep it short: this
-      profile uses the shared `/openspec-explore` and `/openspec-propose` planning steps but
+      profile uses the shared `/mate-explore-change` and `/mate-propose-change` planning steps but
       intentionally writes no explore, proposal, or design artifact.
 
       Number tasks `N.M` and group them under `## N. <group>` headers so apply tracking can address them individually.

package/src/templates/capabilities/openspec-cap/mate-minimal/templates/spec.md

@@ -1,12 +1,10 @@
----
-type: delta-spec
+<!-- mate:delta
 change: <change-name>
 capability: <capability>
-tags: [openspec/change, openspec/spec, openspec/delta]
 scopes:
   - repository: org/repository
     area: .
----
+-->
 
 ## ADDED Requirements
 
@@ -16,7 +14,7 @@ As a <!-- role -->, I want <!-- capability -->, so that <!-- benefit -->.
 The system MUST support this behavior.
 **Area:** `.` <!-- replace with the Area from scopes -->
 
-<!-- Every requirement must bind an Area from the frontmatter scopes. -->
+<!-- Every requirement must bind an Area from the `mate:delta` scopes. -->
 
 #### Acceptance Criteria
 

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

@@ -1,5 +1,5 @@
 name: mate-v1
-version: 9
+version: 10
 description: Mate's complete OpenSpec workflow - proposal → specs → design → tasks
 artifacts:
   - id: proposal
@@ -74,7 +74,7 @@ artifacts:
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
 
-      New capabilities only: after the frontmatter and backlink lines, start the delta spec body with a `## Purpose` section - one or two sentences (50+ characters, or `openspec validate --strict` reports it as too brief) describing what the capability is for. Archive copies it into the main spec it creates; without it the new main spec is left with a `TBD ... Update Purpose after archive.` placeholder to fill in by hand. Do NOT add `## Purpose` to a delta for an existing capability - that spec already has one and the delta's is ignored. To change an existing capability's Purpose - including a leftover `TBD` placeholder - edit `openspec/specs/<capability>/spec.md` directly.
+      New capabilities only: after the `mate:delta` comment and any `#` title, start the delta spec body with a `## Purpose` section - one or two sentences (50+ characters, or `openspec validate --strict` reports it as too brief) describing what the capability is for. Archive copies it into the main spec it creates; without it the new main spec is left with a `TBD ... Update Purpose after archive.` placeholder to fill in by hand. Do NOT add `## Purpose` to a delta for an existing capability - that spec already has one and the delta's is ignored. To change an existing capability's Purpose - including a leftover `TBD` placeholder - edit `openspec/specs/<capability>/spec.md` directly.
 
       MODIFIED requirements workflow:
       1. Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
@@ -84,7 +84,7 @@ artifacts:
 
       Common pitfall: Using MODIFIED with partial content loses detail at archive time. If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example (frontmatter scopes cover `acme` and `packages/api`; every requirement carries an `**Area:**` marker, as always — the first binds both, the second one):
+      Example (scope metadata covers `acme` and `packages/api`; every requirement carries an `**Area:**` marker, as always — the first binds both, the second one):
 
       ```
       ## ADDED Requirements
@@ -107,21 +107,19 @@ artifacts:
 
       Specs should be testable - each scenario is a potential test case.
 
-       **Obsidian**: Emit this YAML frontmatter at the very top of each spec file. Replace `<change-name>`, `<repository>`, `<area>`, and `<capability>` with actual values. Each `scopes` entry MUST preserve its repository/Area pairing:
+      **Obsidian**: Start each spec file with this `mate:delta` comment as its very first line, not YAML frontmatter. Replace `<change-name>`, `<repository>`, `<area>`, and `<capability>` with actual values. Each `scopes` entry MUST preserve its repository/Area pairing:
 
       ```
-      ---
-      type: delta-spec
+      <!-- mate:delta
       change: <change-name>
       capability: <capability>
-      tags: [openspec/change, openspec/spec, openspec/delta]
       scopes:
         - repository: org/repository
           area: .
-      ---
+      -->
       ```
 
-      After the file's `#` title line, add a backlink on the next line: `← [[proposal]]`. If modifying an existing main spec, add on the line after: `Applies to: [[openspec/specs/<capability>/spec]]`.
+      Between the comment and the first `## ` section, put nothing but blank lines and at most one `# ` title line. OpenSpec skips the comment and the title, but `openspec validate --strict` reports any other text there, because archive drops it, so add no backlink or cross-reference lines.
 
       Canonical-spec shape, delta-to-canonical projection, and migration rules live in
       `openspec/mate-conventions.yaml`. Follow that reference when creating or repairing

package/src/templates/capabilities/openspec-cap/mate-v1/templates/spec.md

@@ -1,12 +1,10 @@
----
-type: delta-spec
+<!-- mate:delta
 change: <change-name>
 capability: <capability>
-tags: [openspec/change, openspec/spec, openspec/delta]
 scopes:
   - repository: org/repository
     area: .
----
+-->
 
 ## Purpose
 
@@ -17,7 +15,7 @@ scopes:
 ### Requirement: <!-- requirement name -->
 
 <!-- Write the normative requirement. EVERY requirement carries an **Area:** marker from the
-frontmatter scopes, for example **Area:** `packages/ui`. No **Repository:** marker is ever used.
+`mate:delta` scopes, for example **Area:** `packages/ui`. No **Repository:** marker is ever used.
 See openspec/mate-conventions.yaml for shared scope and canonical-spec rules. -->
 
 #### Scenario: <!-- scenario name -->