@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/runtime/framework.ts

@@ -0,0 +1,10 @@
+/**
+ * Framework identity: names everything identity-shaped — state directories
+ * (`~/.mate`, `.mate/`), managed-block markers, `MATE_*` env values, usage
+ * output, command hints, error prefixes, agent guidance, and permission
+ * entries. The distribution is always invoked as `mate`.
+ *
+ * Lives under `runtime/` because the import-isolated runtime subpath derives
+ * repo-local `.mate/` paths from it; `../framework` re-exports it.
+ */
+export const FRAMEWORK_NAME = "mate";

package/src/runtime/freshness.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+
+import { mateVersion } from "./install";
+import { computeProjectionStamp, type ResolvedProjection } from "./projection";
+import { repoLocalRegistryPath } from "./repo-local";
+
+/**
+ * Two independent axes. A stamp answers only "was this written by a mate whose
+ * version, or whose view of the repo-local registry, differs from mine"; it
+ * cannot see a moved or deleted companion, because `companionPath` is not a
+ * stamp input.
+ */
+export interface ProjectionFreshness {
+  stampCurrent: boolean;
+  companionExists: boolean;
+  isCurrent: boolean;
+}
+
+export function projectionFreshness(projection: ResolvedProjection): ProjectionFreshness {
+  const registryContent = (() => {
+    try {
+      return fs.readFileSync(repoLocalRegistryPath(projection.repoRoot), "utf8");
+    } catch {
+      return "";
+    }
+  })();
+
+  const stampCurrent =
+    projection.stamp === computeProjectionStamp({ version: mateVersion(), registryContent });
+
+  const companionExists = (() => {
+    try {
+      return fs.statSync(projection.companionPath).isDirectory();
+    } catch {
+      return false;
+    }
+  })();
+
+  return { stampCurrent, companionExists, isCurrent: stampCurrent && companionExists };
+}
+
+/**
+ * Advisory, never fatal: a reader surfaces these and carries on. Stale is the
+ * steady state under wrap-once, so the repair is named rather than enforced.
+ */
+export function projectionStalenessLines(
+  projection: ResolvedProjection,
+  freshness: ProjectionFreshness,
+): string[] {
+  const lines: string[] = [];
+  if (!freshness.stampCurrent) {
+    lines.push("projection was written by a different mate install — run `mate wrap` to refresh");
+  }
+  if (!freshness.companionExists) {
+    lines.push(`projected companion is missing: ${projection.companionPath} — run \`mate wrap\``);
+  }
+  return lines;
+}

package/src/runtime/index.ts

@@ -1,10 +1,75 @@
+export {
+  GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
+  buildCodebaseExplorationGuidanceSection,
+  buildCompanionGuidance,
+  buildCompanionPolicyXml,
+  buildOpenCodeGuidance,
+  hasGraphifyCapability,
+  hasOpenspecCapability,
+  hasTokensaveCapability,
+  type GuidanceCapability,
+  type GuidanceContext,
+} from "./companion-guidance";
+export {
+  companionForkState,
+  describeGitFailure,
+  forkStateAgainst,
+  gitEnvironment,
+  GIT_QUERY_TIMEOUT_MS,
+  isAuthenticationFailure,
+  outputLines,
+  resolveUpstreamTargetSync,
+  resolveUpstreamTargetWith,
+  runGitSync,
+  stripGitProgress,
+  upstreamTargetSteps,
+  type CompanionForkState,
+  type GitResult,
+  type UpstreamTarget,
+} from "./companion-git";
+export {
+  companionGitStatePath,
+  companionGitStateRoot,
+  COMPANION_SYNC_TTL_MS,
+  FORK_VERDICT_TTL_MS,
+  isCompanionSyncDue,
+  readCachedForkRecord,
+  readCompanionGitRecord,
+  recordCompanionSync,
+  recordForkVerdict,
+  writeCompanionGitRecord,
+  type CompanionForkRecord,
+  type CompanionGitRecord,
+} from "./companion-git-state";
+export {
+  cachedCompanionForkState,
+  companionForkRefusal,
+  COMPANION_SYNC_COMMAND,
+  COMPANION_SYNC_TIMEOUT_MS,
+  forkRefusalMessage,
+  syncCompanionUnattended,
+  unattendedSyncStalenessLines,
+  type ForkGuardOptions,
+  type UnattendedSyncOptions,
+  type UnattendedSyncOutcome,
+  type UnattendedSyncStatus,
+} from "./companion-sync";
+export { FRAMEWORK_NAME } from "./framework";
 export {
   MATE_ENV,
+  hasLaunchEnvironment,
   isManagedCompanionContext,
   readCompanionRuntimeContext,
+  resolveCompanionRuntime,
   type CompanionRuntimeContext,
+  type CompanionRuntimeResolution,
   type MateEnvVariable,
 } from "./env";
+export {
+  projectionFreshness,
+  projectionStalenessLines,
+  type ProjectionFreshness,
+} from "./freshness";
 export {
   CODEBASE_EXPLORATION_MARKER,
   COMPANION_POLICY_MARKER,
@@ -14,3 +79,42 @@ export {
   type GuidanceValidation,
   type MateGuidanceFile,
 } from "./guidance";
+export { mateInstallPath, mateVersion } from "./install";
+export { buildProjectedGuidance } from "./projected-guidance";
+export {
+  companionFrameworkConfigPath,
+  emptyCompanionPolicy,
+  isCapabilityEnabled,
+  readCompanionPolicy,
+  type CompanionPolicy,
+} from "./policy";
+export {
+  PROJECTION_ENV_FILE,
+  PROJECTION_ENV_NAMES,
+  PROJECTION_FIELDS,
+  PROJECTION_STAMP_ENV_NAME,
+  PROJECTION_YAML_FILE,
+  computeProjectionStamp,
+  parseProjectionEnv,
+  parseProjectionYaml,
+  projectionEnvPath,
+  projectionYamlPath,
+  readProjectionFile,
+  renderProjectionEnv,
+  renderProjectionYaml,
+  resolveProjection,
+  writeProjectionPair,
+  type MateProjection,
+  type ProjectionFile,
+  type ProjectionStampInputs,
+  type ResolvedProjection,
+} from "./projection";
+export {
+  ancestorDirectories,
+  findRepoLocalRegistryFileSync,
+  repoLocalDirName,
+  repoLocalDirPath,
+  repoLocalFrameworkPath,
+  repoLocalRegistryPath,
+  type RepoLocalRegistryFile,
+} from "./repo-local";

package/src/runtime/install.ts

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Identity of the running mate install, as the projection stamp records it.
+ * It lives inside `runtime/` because the readers that judge a projection's
+ * freshness — hooks and OpenCode plugins — may import nothing else from core;
+ * `lib/package-paths` delegates here so the install has one definition.
+ *
+ * The manifest is read rather than imported: a static `package.json` import
+ * would put a non-`runtime/` module in the isolation walk.
+ */
+export function mateInstallPath(): string {
+  return path.resolve(import.meta.dirname, "..", "..");
+}
+
+export function mateVersion(): string {
+  try {
+    const parsed: unknown = JSON.parse(
+      fs.readFileSync(path.join(mateInstallPath(), "package.json"), "utf8"),
+    );
+    if (parsed && typeof parsed === "object") {
+      const value = (parsed as { version?: unknown }).version;
+      if (typeof value === "string" && value) return value;
+    }
+  } catch {
+    // fall through to the unknown marker
+  }
+  return "unknown";
+}

package/src/runtime/policy.ts

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+/**
+ * Predicates that are never projected: they are read live from the companion
+ * so toggling a Capability takes effect without a projection refresh.
+ */
+export interface CompanionPolicy {
+  allowedAgents: string[];
+  /** Names of the Capabilities the companion has enabled. */
+  enabledCapabilities: string[];
+  gitAutoMode: boolean;
+}
+
+export const emptyCompanionPolicy = (): CompanionPolicy => ({
+  allowedAgents: [],
+  enabledCapabilities: [],
+  gitAutoMode: false,
+});
+
+export function companionFrameworkConfigPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+function capabilityNames(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) =>
+      entry && typeof entry === "object" ? (entry as { name?: unknown }).name : undefined,
+    )
+    .filter((name): name is string => typeof name === "string");
+}
+
+/**
+ * Synchronous so it composes into `readCompanionRuntimeContext`. A missing or
+ * unparseable companion config yields an inert policy rather than throwing.
+ */
+export function readCompanionPolicy(companionPath: string): CompanionPolicy {
+  let parsed: unknown;
+  try {
+    parsed = parse(fs.readFileSync(companionFrameworkConfigPath(companionPath), "utf8"));
+  } catch {
+    return emptyCompanionPolicy();
+  }
+  if (!parsed || typeof parsed !== "object") return emptyCompanionPolicy();
+
+  const config = parsed as Record<string, unknown>;
+  return {
+    allowedAgents: stringList(config.allowedAgents),
+    enabledCapabilities: capabilityNames(config.capabilities),
+    gitAutoMode: config.git === "auto",
+  };
+}
+
+export function isCapabilityEnabled(policy: CompanionPolicy, name: string): boolean {
+  return policy.enabledCapabilities.includes(name);
+}

package/src/runtime/projected-guidance.ts

@@ -0,0 +1,45 @@
+import { buildCompanionGuidance } from "./companion-guidance";
+import { hasLaunchEnvironment } from "./env";
+import { readCompanionPolicy } from "./policy";
+import { resolveProjection } from "./projection";
+
+/**
+ * The companion guidance for an Unmanaged Session, built from the Projection
+ * Root instead of from a launch.
+ *
+ * Guidance was the one companion concept with no reader form: it is built from
+ * an `AdapterContext`, which exists only inside a `LaunchAdapter`, so it could
+ * not cross into a session Mate did not start. Every field it needs is
+ * available without one — paths from the projection, predicates read live from
+ * the companion — which is what this composes.
+ *
+ * Reading the predicates live rather than projecting the rendered text is what
+ * makes a Capability toggled after a wrap change the guidance with no re-wrap.
+ * A rendered string in the Projection Root would be a snapshot, and rule 2 —
+ * paths only, never predicates — exists to keep exactly that out of it.
+ *
+ * Returns null for a managed session: the launch already injects the guidance
+ * through its own channel, and rule 1 says the environment wins. That is what
+ * lets the same declaration be loaded by both a plugin and a projected
+ * document without emitting twice.
+ */
+export function buildProjectedGuidance(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): string | null {
+  if (hasLaunchEnvironment(env)) return null;
+
+  const projection = resolveProjection(cwd);
+  if (!projection) return null;
+
+  const policy = readCompanionPolicy(projection.companionPath);
+  return buildCompanionGuidance(
+    {
+      companionPath: projection.companionPath,
+      repository: { id: projection.repositoryId, path: projection.repositoryPath },
+      capabilities: policy.enabledCapabilities.map((name) => ({ name })),
+    },
+    /** The projected path, not the running install's: a wrap may be another mate's. */
+    { wrapperBinPath: projection.wrapperBinPath },
+  );
+}

package/src/runtime/projection.ts

@@ -0,0 +1,224 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse, stringify } from "yaml";
+
+import { MATE_ENV } from "./env-names";
+import { FRAMEWORK_NAME } from "./framework";
+import { findRepoLocalRegistryFileSync, repoLocalDirPath } from "./repo-local";
+
+/** Generated projection files, directly under the repo-local `.mate/`. */
+export const PROJECTION_YAML_FILE = "projection.yaml";
+export const PROJECTION_ENV_FILE = "projection.env";
+
+/**
+ * Paths a session needs, projected to disk at the Projection Root. Paths only:
+ * a predicate would go stale between refreshes, so predicates are read live
+ * from the companion instead. No predicate field is expressible here.
+ */
+export interface MateProjection {
+  version: string;
+  companionPath: string;
+  repositoryPath: string;
+  repositoryId: string;
+  wrapperBinPath: string;
+  reactDoctorBinPath: string;
+  graphifyOut: string;
+}
+
+/**
+ * Env variable each projected field materializes as. `GRAPHIFY_OUT` is
+ * graphify's own variable rather than part of the `MATE_*` contract, so it is
+ * spelled here instead of in `MATE_ENV`.
+ */
+export const PROJECTION_ENV_NAMES: Record<keyof MateProjection, string> = {
+  version: MATE_ENV.version,
+  companionPath: MATE_ENV.companionPath,
+  repositoryPath: MATE_ENV.repositoryPath,
+  repositoryId: MATE_ENV.repositoryId,
+  wrapperBinPath: MATE_ENV.wrapperBinPath,
+  reactDoctorBinPath: MATE_ENV.reactDoctorBinPath,
+  graphifyOut: "GRAPHIFY_OUT",
+};
+
+/** Stable field order; both renderers iterate it so the forms cannot diverge. */
+export const PROJECTION_FIELDS = Object.keys(PROJECTION_ENV_NAMES) as Array<keyof MateProjection>;
+
+export const PROJECTION_STAMP_ENV_NAME = "MATE_PROJECTION_STAMP";
+
+/**
+ * Stamp inputs. The companion's `framework.yaml` is deliberately absent: no
+ * predicate is projected, so nothing derived from it can go stale.
+ *
+ * The running install's path is absent for a stronger reason: the readers
+ * cannot agree on it. Every input has to be computable identically by the
+ * writer and by each reader, and several copies of one Mate version coexist by
+ * design — the global CLI writes the stamp, the OpenCode plugin runs from
+ * OpenCode's own npm cache, and each resolves its own location. Including the
+ * path made the plugin report every projection as another install's, session
+ * after session, with `mate wrap` unable to fix what it had just written. The
+ * version alone answers what the stamp is for.
+ */
+export interface ProjectionStampInputs {
+  version: string;
+  registryContent: string;
+}
+
+/** Both generated files carry the same stamp; a reader regenerates on mismatch. */
+export interface ProjectionFile {
+  stamp: string;
+  projection: MateProjection;
+}
+
+export function computeProjectionStamp(inputs: ProjectionStampInputs): string {
+  return crypto
+    .createHash("sha256")
+    .update(inputs.version)
+    .update("\0")
+    .update(inputs.registryContent)
+    .digest("hex");
+}
+
+export function projectionYamlPath(repoRoot: string): string {
+  return path.join(repoLocalDirPath(repoRoot), PROJECTION_YAML_FILE);
+}
+
+export function projectionEnvPath(repoRoot: string): string {
+  return path.join(repoLocalDirPath(repoRoot), PROJECTION_ENV_FILE);
+}
+
+const generatedHeader = () => `# generated by ${FRAMEWORK_NAME} — do not edit`;
+
+export function renderProjectionYaml(file: ProjectionFile): string {
+  const document: Record<string, string> = { stamp: file.stamp };
+  for (const field of PROJECTION_FIELDS) document[field] = file.projection[field];
+  return `${generatedHeader()}\n${stringify(document)}`;
+}
+
+export function parseProjectionYaml(raw: string): ProjectionFile | null {
+  let parsed: unknown;
+  try {
+    parsed = parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  return readProjectionRecord(parsed as Record<string, unknown>, (field) => field);
+}
+
+/**
+ * Single-quoted for `sh`: inside single quotes nothing expands or word-splits,
+ * so a path containing spaces survives sourcing intact.
+ */
+function quoteShellValue(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function unquoteShellValue(value: string): string | null {
+  if (value.length < 2 || !value.startsWith("'") || !value.endsWith("'")) return null;
+  return value.slice(1, -1).replaceAll(`'\\''`, "'");
+}
+
+export function renderProjectionEnv(file: ProjectionFile): string {
+  const lines = [generatedHeader(), `${PROJECTION_STAMP_ENV_NAME}=${quoteShellValue(file.stamp)}`];
+  for (const field of PROJECTION_FIELDS) {
+    lines.push(`${PROJECTION_ENV_NAMES[field]}=${quoteShellValue(file.projection[field])}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function parseProjectionEnv(raw: string): ProjectionFile | null {
+  const values: Record<string, unknown> = {};
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const separator = trimmed.indexOf("=");
+    if (separator <= 0) return null;
+    const unquoted = unquoteShellValue(trimmed.slice(separator + 1));
+    if (unquoted === null) return null;
+    values[trimmed.slice(0, separator)] = unquoted;
+  }
+
+  const stamp = values[PROJECTION_STAMP_ENV_NAME];
+  if (typeof stamp !== "string") return null;
+  return readProjectionRecord({ ...values, stamp }, (field) => PROJECTION_ENV_NAMES[field]);
+}
+
+function readProjectionRecord(
+  record: Record<string, unknown>,
+  keyOf: (field: keyof MateProjection) => string,
+): ProjectionFile | null {
+  const stamp = record.stamp;
+  if (typeof stamp !== "string") return null;
+
+  const projection = {} as MateProjection;
+  for (const field of PROJECTION_FIELDS) {
+    const value = record[keyOf(field)];
+    if (typeof value !== "string") return null;
+    projection[field] = value;
+  }
+  return { stamp, projection };
+}
+
+/**
+ * Writes both forms as one unit: rendered in memory, written to temporary
+ * siblings, then renamed into place, so a reader never observes a fresh
+ * `.yaml` beside a stale `.env`. Default file mode — the projection holds only
+ * paths already visible in the working tree's config, so it is not restricted.
+ */
+export function writeProjectionPair(repoRoot: string, file: ProjectionFile): void {
+  const yamlPath = projectionYamlPath(repoRoot);
+  const envPath = projectionEnvPath(repoRoot);
+  const suffix = `.${crypto.randomUUID()}.tmp`;
+  const yamlTempPath = `${yamlPath}${suffix}`;
+  const envTempPath = `${envPath}${suffix}`;
+
+  fs.mkdirSync(path.dirname(yamlPath), { recursive: true });
+  try {
+    fs.writeFileSync(yamlTempPath, renderProjectionYaml(file), "utf8");
+    fs.writeFileSync(envTempPath, renderProjectionEnv(file), "utf8");
+    fs.renameSync(yamlTempPath, yamlPath);
+    fs.renameSync(envTempPath, envPath);
+  } catch (error) {
+    for (const tempPath of [yamlTempPath, envTempPath]) {
+      try {
+        fs.rmSync(tempPath, { force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    throw error;
+  }
+}
+
+export function readProjectionFile(repoRoot: string): ProjectionFile | null {
+  try {
+    return parseProjectionYaml(fs.readFileSync(projectionYamlPath(repoRoot), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export interface ResolvedProjection extends MateProjection {
+  repoRoot: string;
+  /** Recorded, never judged here: the verdict needs inputs this module lacks. */
+  stamp: string;
+}
+
+/**
+ * Synchronous, paths only, so a hook or shell that cannot await can use it.
+ * Anchored to the directory holding the repo-local `registry.yaml` rather than
+ * walking independently for `projection.yaml`, so it cannot resolve a
+ * projection belonging to a different ancestor than the registry does. The
+ * projected `companionPath` is not stat-ed: a reader that needs the companion
+ * to exist fails in its own terms.
+ */
+export function resolveProjection(cwd: string): ResolvedProjection | null {
+  const found = findRepoLocalRegistryFileSync(cwd);
+  if (!found) return null;
+
+  const file = readProjectionFile(found.repoRoot);
+  if (!file) return null;
+  return { repoRoot: found.repoRoot, stamp: file.stamp, ...file.projection };
+}

package/src/runtime/repo-local.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+export const repoLocalDirName = () => `.${FRAMEWORK_NAME}`;
+
+export function repoLocalDirPath(repoPath: string): string {
+  return path.join(path.resolve(repoPath), repoLocalDirName());
+}
+
+export function repoLocalRegistryPath(repoPath: string): string {
+  return path.join(repoLocalDirPath(repoPath), "config", "registry.yaml");
+}
+
+export function repoLocalFrameworkPath(repoPath: string): string {
+  return path.join(repoLocalDirPath(repoPath), "config", "framework.yaml");
+}
+
+/**
+ * Where the Companion Repository is reachable from inside the Working
+ * Repository by ordinary path traversal. Spelled here rather than beside the
+ * writer so a synchronous reader — a hook, a shell — names it without loading
+ * the projection owner.
+ */
+export function companionLinkPath(repoPath: string): string {
+  return path.join(repoLocalDirPath(repoPath), "companion");
+}
+
+/**
+ * `cwd` and each of its ancestors, nearest first, ending at the filesystem
+ * root. Shared by the async and sync registry walks so the two cannot land on
+ * different ancestors.
+ */
+export function* ancestorDirectories(cwd: string): Generator<string> {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    yield dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+
+export interface RepoLocalRegistryFile {
+  repoRoot: string;
+  registryPath: string;
+}
+
+/**
+ * Synchronous sibling of `findRepoLocalRegistryFile`. Differs only in I/O;
+ * hooks and shells that cannot await resolve their Projection Root through it.
+ */
+export function findRepoLocalRegistryFileSync(cwd: string): RepoLocalRegistryFile | null {
+  for (const dir of ancestorDirectories(cwd)) {
+    const candidate = repoLocalRegistryPath(dir);
+    try {
+      if (fs.statSync(candidate).isFile()) return { repoRoot: dir, registryPath: candidate };
+    } catch {
+      // keep walking up
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,56 @@
+name: mate-minimal
+version: 2
+description: Mate's short OpenSpec workflow for one-Area, low-risk changes - specs → tasks
+artifacts:
+  - id: specs
+    generates: specs/**/*.md
+    description: Delta specification answering what behavior must change through a concise user story
+    template: spec.md
+    instruction: |
+      This schema is a deliberate shortcut, not an optional subset of mate-v1. Use it only when
+      the change passes the documented gate: one repository and one Area; no new dependency,
+      data migration, public API change, breaking behavior, or cross-cutting design decision.
+      Use mate-v1 if any gate item is false or uncertain.
+
+      Read `openspec/mate-conventions.yaml` before writing the artifact. Create one delta spec
+      per affected capability under `specs/<capability>/spec.md`, using a kebab-case capability
+      name. Never place specs under an Area folder.
+
+      Write requirements as user stories: `As a <role>, I want <capability>, so that <benefit>.`
+      Keep the OpenSpec parser contract around each story:
+      - Use `## ADDED Requirements`, `## MODIFIED Requirements`, and `## REMOVED Requirements`.
+      - Start every story with `### Requirement: <story title>`. `### User Story:` is ignored.
+      - Follow the story with one SHALL/MUST sentence so `openspec validate --strict` can check it.
+      - Give every story an `#### Acceptance Criteria` block using `- **Given**`, `- **When**`,
+        `- **Then**` bullets. This is the minimal profile's readable form of a scenario.
+      - MODIFIED entries MUST include the full updated story and criteria. REMOVED entries MUST
+        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.
+
+      **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.
+    requires: []
+  - id: tasks
+    generates: tasks.md
+    description: Short task list answering how to complete and verify the delta
+    template: tasks.md
+    instruction: |
+      Create a flat implementation checklist that satisfies the delta specs. Keep it short: this
+      workflow intentionally has no explore, proposal, or design artifact.
+
+      Number tasks `N.M` and group them under `## N. <group>` headers so apply tracking can address them individually.
+      Read `openspec/mate-conventions.yaml` before writing the artifact and preserve its scope rules.
+
+      **Obsidian**: Emit YAML frontmatter with `type: change-tasks`, the actual change name, `schema: mate-minimal`, and the `openspec/change` and `openspec/tasks` tags. At the end of the file, add a `## References` section with `[[wiki-links]]` for each affected spec area.
+    requires:
+      - specs
+apply:
+  requires:
+    - tasks
+  tracks: tasks.md
+  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.