@uniqbit/mate-core 0.18.3 → 0.18.5

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

@@ -3,6 +3,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 
+import { Document, isMap, isScalar, isSeq, parseDocument, type YAMLMap, type YAMLSeq } from "yaml";
+
 import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
 import { getWrapperBinPath } from "../../../lib/package-paths";
 import { fetchPublicPackageVersion } from "../../../lib/public-npm";
@@ -55,6 +57,25 @@ const MATE_SCHEMA_SOURCE_ROOT = path.join(
 );
 const MATE_CONVENTIONS_SOURCE = path.join(MATE_SCHEMA_SOURCE_ROOT, "openspec-conventions.yaml");
 
+/**
+ * Identifies Mate's own `rules.specs` entry, so a later release can replace its
+ * text instead of adding a second entry.
+ */
+export const MATE_SPECS_RULE_MARKER = "[mate] ";
+
+/**
+ * Delivered through `rules.specs`, the one config hook OpenSpec's archive and
+ * sync workflows read when writing main specs. Propose reads it for delta specs
+ * too, so the text binds main specs only.
+ */
+export const MATE_SPECS_RULE = `${MATE_SPECS_RULE_MARKER}A main spec at openspec/specs/<capability>/spec.md MUST begin with flat frontmatter: type: spec, capability: <capability>, repository: <org/repository> (one scalar), areas: [<area>, ...] (a flat list in the delta's scope order), and tags: [openspec/spec]. Project repository and areas from the delta's paired scopes; never copy scopes, change, or delta tags onto a main spec. Delta specs under openspec/changes/<name>/specs/ keep their delta frontmatter. Full rules: openspec/mate-conventions.yaml.`;
+
+/** What Mate writes besides its entry; anything beyond the two is user content. */
+const MANAGED_CONFIG_SCHEMA_ONLY = "schema: mate-v1";
+
+/** Unfolded output keeps the Mate entry on one line and user scalars unwrapped. */
+const CONFIG_TO_STRING = { lineWidth: 0 } as const;
+
 /**
  * Runtime → OpenSpec CLI tools. OpenCode reads workflow skills from the shared
  * `agents` root; its own tool only contributes the `/opsx-*` commands.
@@ -66,6 +87,13 @@ const OPENSPEC_TOOLS_BY_RUNTIME = {
 
 const OPENSPEC_INSTALL_COMMAND = "npm install -g @fission-ai/openspec@latest";
 
+/**
+ * Store metadata `openspec store register` writes beside the companion. Its id
+ * is machine-local, and companion Git sync would otherwise stash it on every
+ * launch. Persisted: the registration outlives the capability.
+ */
+const OPENSPEC_GITIGNORE_ENTRIES = [".openspec-store/"];
+
 type OpenSpecTool =
   (typeof OPENSPEC_TOOLS_BY_RUNTIME)[keyof typeof OPENSPEC_TOOLS_BY_RUNTIME][number];
 type OpenSpecRunCommand = typeof runCommandSilently;
@@ -286,18 +314,129 @@ async function ensureOpenSpecInstalled(
   return true;
 }
 
-/** Only the config Mate itself wrote is removed; a user-edited config.yaml is left alone. */
+function isMateSpecsRule(item: unknown): boolean {
+  return (
+    isScalar(item) &&
+    typeof item.value === "string" &&
+    item.value.startsWith(MATE_SPECS_RULE_MARKER)
+  );
+}
+
+/** The config's `rules.specs` sequence, `null` when absent, or `undefined` when a shape is foreign. */
+function readSpecsRules(doc: Document): YAMLSeq | null | undefined {
+  if (doc.contents !== null && !isMap(doc.contents)) return undefined;
+  const rules = doc.get("rules", true);
+  if (rules === undefined || rules === null) return null;
+  if (!isMap(rules)) return undefined;
+  const specs = rules.get("specs", true);
+  if (specs === undefined || specs === null) return null;
+  return isSeq(specs) ? specs : undefined;
+}
+
+/**
+ * Removes Mate's `rules.specs` entry and any `rules.specs` list or `rules` map
+ * that leaves empty. Returns whether the document changed.
+ */
+function removeMateSpecsRule(doc: Document): boolean {
+  const specs = readSpecsRules(doc);
+  if (!specs) return false;
+  const before = specs.items.length;
+  specs.items = specs.items.filter((item) => !isMateSpecsRule(item));
+  if (specs.items.length === before) return false;
+  if (specs.items.length === 0) doc.deleteIn(["rules", "specs"]);
+  const rules = doc.get("rules", true);
+  if (isMap(rules) && rules.items.length === 0) doc.delete("rules");
+  return true;
+}
+
+/**
+ * Ensures exactly one current Mate entry in `rules.specs`: appended when
+ * missing, replaced in place when outdated. Returns whether the document changed.
+ */
+function upsertMateSpecsRule(doc: Document): boolean {
+  if (doc.contents === null) doc.contents = doc.createNode({}) as YAMLMap;
+  const specs = readSpecsRules(doc);
+  if (specs === null) {
+    doc.setIn(["rules", "specs"], doc.createNode([MATE_SPECS_RULE]));
+    return true;
+  }
+  if (!specs) return false;
+
+  const index = specs.items.findIndex(isMateSpecsRule);
+  if (index === -1) {
+    specs.add(doc.createNode(MATE_SPECS_RULE));
+    return true;
+  }
+  let changed = false;
+  const current = specs.items[index];
+  if (isScalar(current) && current.value !== MATE_SPECS_RULE) {
+    current.value = MATE_SPECS_RULE;
+    changed = true;
+  }
+  const deduplicated = specs.items.filter((item, i) => i === index || !isMateSpecsRule(item));
+  if (deduplicated.length !== specs.items.length) {
+    specs.items = deduplicated;
+    changed = true;
+  }
+  return changed;
+}
+
+/**
+ * Removes Mate's own config content: its `rules.specs` entry always, and the
+ * file only when what remains is exactly what Mate writes. User content stays.
+ */
 async function removeManagedOpenSpecConfig(companionPath: string): Promise<void> {
   const configPath = getOpenSpecConfigPath(companionPath);
+  let content: string;
   try {
-    const content = await fs.readFile(configPath, "utf8");
-    if (content.trim() === "schema: mate-v1") {
-      await fs.rm(configPath, { force: true });
-      await pruneEmptyAncestors(path.dirname(configPath), companionPath);
-    }
+    content = await fs.readFile(configPath, "utf8");
+  } catch {
+    return;
+  }
+
+  let remaining = content;
+  if (content.trim() !== MANAGED_CONFIG_SCHEMA_ONLY) {
+    const doc = parseDocument(content);
+    if (doc.errors.length > 0 || !removeMateSpecsRule(doc)) return;
+    remaining = doc.toString(CONFIG_TO_STRING);
+  }
+
+  if (remaining.trim() === MANAGED_CONFIG_SCHEMA_ONLY) {
+    await fs.rm(configPath, { force: true });
+    await pruneEmptyAncestors(path.dirname(configPath), companionPath);
+  } else {
+    await fs.writeFile(configPath, remaining, "utf8");
+  }
+}
+
+/** Writes a fresh Mate config, or merges Mate's entry into an existing one; writes only on change. */
+async function ensureManagedOpenSpecConfig(companionPath: string): Promise<void> {
+  const configPath = getOpenSpecConfigPath(companionPath);
+  let content: string | undefined;
+  try {
+    content = await fs.readFile(configPath, "utf8");
   } catch {
-    /* no managed config present */
+    /* no config yet */
+  }
+
+  if (content === undefined) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    const fresh = new Document({ schema: "mate-v1", rules: { specs: [MATE_SPECS_RULE] } });
+    await fs.writeFile(configPath, fresh.toString(CONFIG_TO_STRING), "utf8");
+    return;
   }
+
+  // config.yaml is user-editable once created; only Mate's own entry is touched.
+  const doc = parseDocument(content);
+  if (doc.errors.length > 0) {
+    process.stderr.write(
+      `openspec: left openspec/config.yaml unchanged, it is not valid YAML: ${doc.errors[0].message.split("\n")[0]}\n`,
+    );
+    return;
+  }
+  if (!upsertMateSpecsRule(doc)) return;
+  const merged = doc.toString(CONFIG_TO_STRING);
+  if (merged !== content) await fs.writeFile(configPath, merged, "utf8");
 }
 
 async function teardownOpenSpecSchema(companionPath: string): Promise<void> {
@@ -333,17 +472,7 @@ async function reconcileOpenSpecSchema(ctx: SetupContext): Promise<void> {
     return;
   }
 
-  const configPath = getOpenSpecConfigPath(ctx.companionPath);
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-
-  // config.yaml is user-editable once created; never overwrite it on re-sync.
-  const configExists = await fs
-    .access(configPath)
-    .then(() => true)
-    .catch(() => false);
-  if (configExists) return;
-
-  await fs.writeFile(configPath, "schema: mate-v1\n", "utf8");
+  await ensureManagedOpenSpecConfig(ctx.companionPath);
 }
 
 export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityPlugin {
@@ -394,6 +523,8 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
         },
       };
     },
+    gitignoreEntries: () => OPENSPEC_GITIGNORE_ENTRIES,
+    persistGitignoreEntries: true,
     getInstallRequirements: (): InstallRequirement[] => [
       {
         id: "capability:openspec",

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

@@ -14,6 +14,8 @@ export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
 export const TOKENSAVE_STORE_CONFIG_FILE = "config.json";
+/** The index itself: `tokensave sync` refuses a store without it. */
+const TOKENSAVE_STORE_DATABASE_FILE = "tokensave.db";
 export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
 /** Single-graph posture Mate owns in the per-project store config; every other key is left as found. */
 const TOKENSAVE_OWNED_POSTURE = { auto_track: false, suppress_scope_warning: true } as const;
@@ -357,6 +359,15 @@ async function deactivateTokensaveBranchMetadata(repoPath: string): Promise<void
   }
 }
 
+/**
+ * Whether the working repo holds a TokenSave index `tokensave sync` accepts.
+ * The database, not the store folder: an empty or half-initialized
+ * `.tokensave/` must still get `tokensave init`, or every pass fails on sync.
+ */
+export async function isTokensaveIndexed(repoPath: string): Promise<boolean> {
+  return fileExists(path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_DATABASE_FILE));
+}
+
 /**
  * Reconciles Mate's single-graph branching posture into the working repo's
  * git-excluded `.tokensave/config.json` and deactivates existing branch

package/src/tools/setup/dynamic-plugins/audiences.ts

@@ -4,10 +4,19 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "../../../framework";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { ConfigError, type PluginDeclaration } from "../../../lib/orchestrator/types";
 
 export const AUDIENCE_ENV = "MATE_AUDIENCE";
 
+/**
+ * Mate 0.18.4 saved the base set under `audiences.base`. That shape is read
+ * back for compatibility, never written: the next save uses the root shape.
+ */
+export const BASE_AUDIENCE = "base";
+
+/** The keys 0.18.4 moved under `audiences.base`; companion-wide keys stayed at the root. */
+export const BASE_AUDIENCE_KEYS = ["capabilities", "plugins", "studio"] as const;
+
 export type AudienceResolution =
   | { ok: true; active: string | null }
   | { ok: false; requested: string; declared: string[] };
@@ -21,7 +30,8 @@ function pluginList(value: unknown): unknown[] {
 }
 
 function audienceEntry(raw: unknown, audience: string | null): unknown {
-  if (audience === null || !isRecord(raw) || !isRecord(raw.audiences)) return undefined;
+  if (audience === null || audience === BASE_AUDIENCE) return undefined;
+  if (!isRecord(raw) || !isRecord(raw.audiences)) return undefined;
   return Object.hasOwn(raw.audiences, audience) ? raw.audiences[audience] : undefined;
 }
 
@@ -32,6 +42,38 @@ function studioAgent(value: unknown): unknown {
   return value.studio.terminal.agent;
 }
 
+/**
+ * The base set at the root, whichever shape the file uses: `audiences.base`
+ * keys are lifted to the root and `base` leaves `audiences`. A file in the
+ * root shape is returned as it is. Throws when a key is declared in both
+ * places, or `audiences.base` holds a key the base set does not have.
+ */
+export function normalizeBaseAudience<T>(raw: T): T {
+  if (!isRecord(raw) || !isRecord(raw.audiences) || !Object.hasOwn(raw.audiences, BASE_AUDIENCE)) {
+    return raw;
+  }
+  const { [BASE_AUDIENCE]: baseEntry, ...others } = raw.audiences;
+  const lifted: Record<string, unknown> = { ...raw };
+  if (isRecord(baseEntry)) {
+    for (const [key, value] of Object.entries(baseEntry)) {
+      if (!(BASE_AUDIENCE_KEYS as readonly string[]).includes(key)) {
+        throw new ConfigError(
+          `audiences.${BASE_AUDIENCE} may contain only ${BASE_AUDIENCE_KEYS.join(", ")}; "${key}" belongs at the root of framework.yaml.`,
+        );
+      }
+      if (Object.hasOwn(raw, key)) {
+        throw new ConfigError(
+          `"${key}" is declared both at the root of framework.yaml and under audiences.${BASE_AUDIENCE}; keep one.`,
+        );
+      }
+      lifted[key] = value;
+    }
+  }
+  if (Object.keys(others).length > 0) lifted.audiences = others;
+  else delete lifted.audiences;
+  return lifted as T;
+}
+
 /** `MATE_AUDIENCE` from the environment; unset, empty or blank means none. */
 export function readAudienceSelection(env: Record<string, string | undefined>): string | null {
   const value = env[AUDIENCE_ENV]?.trim();
@@ -40,11 +82,13 @@ export function readAudienceSelection(env: Record<string, string | undefined>):
 
 /** Audience names declared by raw parsed `framework.yaml`, in declared order. */
 export function declaredAudiences(raw: unknown): string[] {
-  return isRecord(raw) && isRecord(raw.audiences) ? Object.keys(raw.audiences) : [];
+  return isRecord(raw) && isRecord(raw.audiences)
+    ? Object.keys(raw.audiences).filter((name) => name !== BASE_AUDIENCE)
+    : [];
 }
 
 export function resolveAudience(raw: unknown, audience: string | null): AudienceResolution {
-  if (audience === null) return { ok: true, active: null };
+  if (audience === null || audience === BASE_AUDIENCE) return { ok: true, active: null };
   const declared = declaredAudiences(raw);
   if (declared.includes(audience)) return { ok: true, active: audience };
   return { ok: false, requested: audience, declared };
@@ -55,7 +99,7 @@ export function resolveAudience(raw: unknown, audience: string | null): Audience
  * its own `policy` and `config`. An unknown audience contributes nothing.
  */
 export function effectivePluginDeclarations(raw: unknown, audience: string | null): unknown[] {
-  return [...pluginList(raw), ...pluginList(audienceEntry(raw, audience))];
+  return [...pluginList(normalizeBaseAudience(raw)), ...pluginList(audienceEntry(raw, audience))];
 }
 
 /**
@@ -64,7 +108,7 @@ export function effectivePluginDeclarations(raw: unknown, audience: string | nul
  * version. Runtime declarations must come from `effectivePluginDeclarations`.
  */
 export function allPluginDeclarations(raw: unknown): unknown[] {
-  const all = [...pluginList(raw)];
+  const all = [...pluginList(normalizeBaseAudience(raw))];
   for (const name of declaredAudiences(raw)) {
     all.push(...pluginList(audienceEntry(raw, name)));
   }
@@ -96,24 +140,28 @@ export function installPluginDeclarations(config: unknown): PluginDeclaration[]
  * as found: the caller owns rejecting a value that is not a safe name.
  */
 export function effectiveStudioAgent(raw: unknown, audience: string | null): unknown {
-  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(raw);
+  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(normalizeBaseAudience(raw));
 }
 
 /**
- * Raw read of the companion's `framework.yaml`. Deliberately avoids
- * `ConfigStore.load()` — hydration runs on every invocation and must never
- * create or migrate config files as a side effect.
+ * Raw read of the companion's `framework.yaml`, the base set at the root
+ * whichever shape the file uses. Deliberately avoids `ConfigStore.load()` —
+ * hydration runs on every invocation and must never create or migrate config
+ * files as a side effect.
  */
 export async function readFrameworkRaw(companionPath: string): Promise<unknown> {
+  let raw: unknown;
   try {
     const text = await fs.readFile(
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    return (parse(text) as unknown) ?? null;
+    raw = (parse(text) as unknown) ?? null;
   } catch {
     return null;
   }
+  /** Outside the catch: a base key in both places is the operator's to fix, never silently base-less. */
+  return normalizeBaseAudience(raw);
 }
 
 export async function readEffectiveDeclarations(

package/src/tools/setup/dynamic-plugins/declarations.ts

@@ -6,6 +6,7 @@ import { parse } from "yaml";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { normalizeBaseAudience } from "./audiences";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -22,7 +23,7 @@ export async function readDeclarations(companionPath: string): Promise<unknown[]
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    const parsed = parse(raw) as unknown;
+    const parsed = normalizeBaseAudience(parse(raw) as unknown);
     if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
     return parsed.plugins;
   } catch {

package/src/tools/setup/working-repo-cleanup.ts

@@ -18,6 +18,7 @@ const REPORTED_AS: Partial<
 > = {
   "projection-root": { as: "removed", label: ".mate" },
   "git-excludes": { as: "removed", label: "git-excludes" },
+  "openspec-store-pointer": { as: "removed", label: "openspec/config.yaml" },
   "claude-working-settings": { as: "updated", label: "claude-settings" },
   "legacy-tokensave-claude-md": { as: "updated", label: "claude-settings" },
 };
@@ -36,6 +37,7 @@ export async function cleanupWorkingRepository(
       retained.push(entry.id);
       continue;
     }
+    if (entry.retains && !retained.includes(entry.retains)) retained.push(entry.retains);
     if (entry.state !== "removed") continue;
     const reported = REPORTED_AS[entry.id];
     if (!reported) continue;

package/src/tools/setup/working-repo-local-state.ts

@@ -118,8 +118,16 @@ export async function reconcileWorkingRepoCapabilityExcludes(
   if (!excludePath) return false;
   const existing = await readExclude(excludePath);
   const managed = new Set(managedEntries);
+  const desired = new Set(desiredEntries);
+  /**
+   * A desired line stays where it stands: re-appending it would trade places
+   * with a block written after it, like the companion copies', on every pass.
+   */
   const lines = trimTrailingEmptyLines(
-    contentLines(existing).filter((line) => !managed.has(line.trim())),
+    contentLines(existing).filter((line) => {
+      const entry = line.trim();
+      return desired.has(entry) || !managed.has(entry);
+    }),
   );
   for (const entry of desiredEntries) {
     if (!lines.some((line) => line.trim() === entry)) lines.push(entry);

package/wrappers/bin/openspec

@@ -30,10 +30,12 @@ _mate_same_dir() {
 }
 
 _companion="$MATE_ARTIFACT_PATH"
+_repo="$MATE_REPO_PATH"
 if [ -z "$_companion" ]; then
   _projection="$(_mate_projection_file)"
   if [ -n "$_projection" ]; then
     _companion="$(_mate_projected "$_projection" MATE_ARTIFACT_PATH)"
+    _repo="$(_mate_projected "$_projection" MATE_REPO_PATH)"
     _projected_wrapper_dir="$(_mate_projected "$_projection" MATE_WRAPPER_BIN_PATH)"
     if [ -n "$_companion" ] && ! _mate_same_dir "$_projected_wrapper_dir" "$_this_dir"; then
       {
@@ -92,4 +94,43 @@ if [ "$command" = "templates" ]; then
     fi
   fi
 fi
-exec env -C "$_companion" "$_real" "$@"
+
+_mate_is_under() {
+  case "$1/" in "$2"/*) return 0 ;; esac
+  return 1
+}
+
+# Moves _cwd to the Working Repository root when the caller is inside that
+# repository, outside the companion, and the root carries Mate's pointer.
+_mate_use_store_pointer() {
+  [ -n "$_repo" ] && [ -d "$_repo" ] || return 0
+  local repo_root here companion_root pointer first
+  repo_root="$(cd "$_repo" && pwd -P)"
+  here="$(pwd -P)"
+  companion_root="$(cd "$_companion" 2>/dev/null && pwd -P)"
+  _mate_is_under "$here" "$repo_root" || return 0
+  [ -n "$companion_root" ] && _mate_is_under "$here" "$companion_root" && return 0
+  pointer="$repo_root/openspec/config.yaml"
+  if [ -f "$pointer" ]; then
+    IFS= read -r first < "$pointer" || true
+    case "$first" in
+      "# generated by "*" — do not edit") _cwd="$repo_root" ;;
+    esac
+  elif [ ! -f "$repo_root/openspec/config.yml" ]; then
+    echo "openspec: no OpenSpec store pointer in $repo_root, so edits are scoped to the companion — run \`mate wrap\` to enable Working Repository edit roots" >&2
+  fi
+}
+
+# Commands that resolve an OpenSpec root run from the Working Repository root
+# when it carries Mate's store pointer: OpenSpec then plans in the companion's
+# store and names the repository as the edit root. The root, not the caller's
+# cwd, so a nested openspec/ cannot win. Every other case — including
+# templates, init and update, which do not resolve stores — stays on the
+# companion, exactly as before.
+_cwd="$_companion"
+case "$command" in
+  new|status|instructions|list|show|validate|archive|doctor|context|schemas|view)
+    _mate_use_store_pointer
+    ;;
+esac
+exec env -C "$_cwd" "$_real" "$@"