@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/lib/orchestrator/openspec-store.ts

@@ -0,0 +1,202 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { parse as parseYaml } from "yaml";
+
+import { MATE_ENV } from "../../runtime/env-names";
+import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
+import { resolveCommandOnPath } from "../../tools/setup/utils";
+import { getWrapperBinPath } from "../package-paths";
+
+/**
+ * The Companion Repository as an OpenSpec store. OpenSpec reports the Working
+ * Repository as an edit root only when the CLI runs inside a project whose
+ * `openspec/config.yaml` declares a registered store, so the store has to be
+ * registered before any pointer may name it.
+ *
+ * Registration is checked by reading OpenSpec's registry file, never by
+ * spawning: the check runs on every session refresh. The CLI is spawned only to
+ * register, which OpenSpec answers authoritatively.
+ */
+
+const execFileAsync = promisify(execFile);
+
+/** OpenSpec's one id grammar, shared by store and change ids. */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+const STORE_METADATA_FILE = path.join(".openspec-store", "store.yaml");
+
+/** Injectable so the suite never touches the developer's registry or binary. */
+export const openSpecStoreDeps = {
+  env: (): NodeJS.ProcessEnv => process.env,
+  platform: (): NodeJS.Platform => process.platform,
+  homedir: (): string => os.homedir(),
+  /** Mate's own `openspec` wrappers, which must never answer a registration. */
+  wrapperBinDirs: (): string[] => {
+    const launched = openSpecStoreDeps.env()[MATE_ENV.wrapperBinPath];
+    return [getWrapperBinPath(), runtimeWrapperBinPath(), ...(launched ? [launched] : [])];
+  },
+  resolveBinary: (): string | undefined => {
+    const excluded = new Set(openSpecStoreDeps.wrapperBinDirs().map((dir) => path.resolve(dir)));
+    const searchPath = (openSpecStoreDeps.env().PATH ?? "")
+      .split(path.delimiter)
+      .filter((dir) => dir && !excluded.has(path.resolve(dir)))
+      .join(path.delimiter);
+    return resolveCommandOnPath("openspec", searchPath);
+  },
+};
+
+export type StoreRegistrationCheck =
+  | { state: "registered" }
+  | { state: "absent" }
+  | { state: "conflict"; path: string }
+  | { state: "unreadable" };
+
+export type StoreRegistration =
+  | { state: "written" | "current"; id: string }
+  | { state: "skipped"; reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function canonicalPath(candidate: string): Promise<string> {
+  return fs.realpath(candidate).catch(() => path.resolve(candidate));
+}
+
+async function isDirectory(candidate: string): Promise<boolean> {
+  return fs
+    .stat(candidate)
+    .then((stats) => stats.isDirectory())
+    .catch(() => false);
+}
+
+function sanitizeStoreId(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * The id a registration already recorded beside the companion, else the
+ * companion folder name made into a valid id. Machine-local on purpose: no
+ * artifact embeds it, and a committed one would collide across clones.
+ */
+export async function deriveStoreId(companionPath: string): Promise<string> {
+  const metadata = await fs
+    .readFile(path.join(companionPath, STORE_METADATA_FILE), "utf8")
+    .then((content) => parseYaml(content) as unknown)
+    .catch(() => null);
+  if (isRecord(metadata) && typeof metadata.id === "string" && KEBAB_ID.test(metadata.id)) {
+    return metadata.id;
+  }
+  const folder = path.basename(path.resolve(companionPath));
+  const id = sanitizeStoreId(folder);
+  if (!KEBAB_ID.test(id)) {
+    throw new Error(`cannot derive an OpenSpec store id from the companion folder "${folder}"`);
+  }
+  return id;
+}
+
+/** Mirrors OpenSpec's `getGlobalDataDir`, so Mate reads the registry OpenSpec writes. */
+export function openSpecDataDir(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  homedir: string,
+): string {
+  if (env.XDG_DATA_HOME) return path.join(env.XDG_DATA_HOME, "openspec");
+  if (platform === "win32") {
+    return path.join(env.LOCALAPPDATA ?? path.join(homedir, "AppData", "Local"), "openspec");
+  }
+  return path.join(homedir, ".local", "share", "openspec");
+}
+
+function registryPath(): string {
+  return path.join(
+    openSpecDataDir(
+      openSpecStoreDeps.env(),
+      openSpecStoreDeps.platform(),
+      openSpecStoreDeps.homedir(),
+    ),
+    "stores",
+    "registry.yaml",
+  );
+}
+
+/** Read-only: what the registry says about `id`, compared by canonical path. */
+export async function checkStoreRegistration(
+  companionPath: string,
+  id: string,
+): Promise<StoreRegistrationCheck> {
+  let content: string;
+  try {
+    content = await fs.readFile(registryPath(), "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { state: "absent" }
+      : { state: "unreadable" };
+  }
+  let registry: unknown;
+  try {
+    registry = parseYaml(content);
+  } catch {
+    return { state: "unreadable" };
+  }
+  if (!isRecord(registry) || !isRecord(registry.stores)) return { state: "unreadable" };
+  const entry = registry.stores[id];
+  if (entry === undefined) return { state: "absent" };
+  const localPath =
+    isRecord(entry) && isRecord(entry.backend) ? entry.backend.local_path : undefined;
+  if (typeof localPath !== "string") return { state: "unreadable" };
+  return (await canonicalPath(localPath)) === (await canonicalPath(companionPath))
+    ? { state: "registered" }
+    : { state: "conflict", path: localPath };
+}
+
+function commandOutput(error: unknown): string {
+  const { stderr, stdout, message } = error as {
+    stderr?: string;
+    stdout?: string;
+    message: string;
+  };
+  return (stderr || stdout || message).trim();
+}
+
+/**
+ * Registers the companion when the registry lacks it. A conflicting id fails
+ * rather than silently picking another one; OpenSpec without stores, or a
+ * companion that is no OpenSpec root, is skipped.
+ */
+export async function ensureStoreRegistration(companionPath: string): Promise<StoreRegistration> {
+  const companion = await canonicalPath(companionPath);
+  if (!(await isDirectory(path.join(companion, "openspec")))) {
+    return { state: "skipped", reason: `${companion} is not an OpenSpec root` };
+  }
+  const id = await deriveStoreId(companion);
+  const check = await checkStoreRegistration(companion, id);
+  if (check.state === "registered") return { state: "current", id };
+  if (check.state === "conflict") {
+    throw new Error(`OpenSpec store id "${id}" is already registered at ${check.path}`);
+  }
+
+  const bin = openSpecStoreDeps.resolveBinary();
+  if (!bin) return { state: "skipped", reason: "the openspec CLI is not on PATH" };
+  try {
+    await execFileAsync(bin, ["store", "register", companion, "--id", id, "--yes"], {
+      cwd: companion,
+      env: openSpecStoreDeps.env(),
+      timeout: 30_000,
+    });
+  } catch (error) {
+    const output = commandOutput(error);
+    if (/unknown command/i.test(output)) {
+      return { state: "skipped", reason: "the openspec CLI does not support stores" };
+    }
+    throw new Error(`openspec store register failed: ${output}`, { cause: error });
+  }
+  return { state: "written", id };
+}

package/src/lib/orchestrator/projection-claude-skills.ts

@@ -1,6 +1,8 @@
+// oxlint-disable no-await-in-loop
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { CURRENT_LAYER_LINK } from "../../runtime/audience-layer";
 import { readProjectionFile } from "../../runtime/projection";
 import { realLinkTarget, realOrResolved } from "../fs-utils";
 import {
@@ -64,63 +66,114 @@ async function createSkillLink(target: string, link: string): Promise<void> {
   await fs.symlink(target, link, process.platform === "win32" ? "junction" : "dir");
 }
 
+const CLAUDE_AGENTS_PATH = path.join(".claude", "agents");
+
+/** The manifest key of an agent link: repo-relative, POSIX separators. */
+function agentKey(file: string): string {
+  return `.claude/agents/${file}`;
+}
+
+async function agentFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md"))
+    .map((entry) => entry.name);
+}
+
+/**
+ * Every link the wrap wants, by manifest key: the companion's skills, then the
+ * wrapped audience's skills and agents. An audience link targets the layer
+ * through its `current` link, so a re-rendered layer never strands it. A
+ * companion skill wins a name both provide.
+ */
+async function wantedLinks(
+  currentRoot: string | null,
+  layerRoot: string | null,
+): Promise<Map<string, string>> {
+  const wanted = new Map<string, string>();
+  if (currentRoot) {
+    for (const name of await skillNames(currentRoot)) {
+      wanted.set(recordKey(name), path.join(currentRoot, name));
+    }
+  }
+  if (layerRoot) {
+    const layerSkills = path.join(layerRoot, "skills");
+    for (const name of await skillNames(layerSkills)) {
+      if (!wanted.has(recordKey(name))) wanted.set(recordKey(name), path.join(layerSkills, name));
+    }
+    const layerAgents = path.join(layerRoot, "agents");
+    for (const file of await agentFiles(layerAgents)) {
+      wanted.set(agentKey(file), path.join(layerAgents, file));
+    }
+  }
+  return wanted;
+}
+
 /**
  * Recorded link: Mate's while it resolves to its recorded target. Unrecorded:
- * adopted only when it resolves into a registered, current or projected
- * companion. Records follow the filesystem, so a partial failure re-adopts.
+ * a skill link is adopted only when it resolves into a registered, current or
+ * projected companion; an agent link never is. Records follow the filesystem,
+ * so a partial failure re-adopts.
  */
 export async function reconcileWorkingRepoClaudeSkillLinks(
   repoPath: string,
   companionPath: string | null,
   enabled: boolean,
   registeredCompanionPaths: string[] = [],
+  audienceLayerDir: string | null = null,
 ): Promise<"written" | "current"> {
+  const repoRoot = path.resolve(repoPath);
   const currentRoot = companionPath ? path.resolve(companionPath, CLAUDE_SKILLS_PATH) : null;
+  const layerRoot =
+    audienceLayerDir && enabled ? path.join(audienceLayerDir, CURRENT_LAYER_LINK, ".claude") : null;
   const roots = await registeredSkillRoots(repoPath, companionPath, registeredCompanionPaths);
-  const targetRoot = path.join(path.resolve(repoPath), CLAUDE_SKILLS_PATH);
   const recorded = links(await readManifest(repoPath), "claude");
-  const existing = await fs.readdir(targetRoot, { withFileTypes: true }).catch(() => []);
-  const sourceNames: Set<string> =
-    currentRoot && enabled ? new Set(await skillNames(currentRoot)) : new Set<string>();
+  const wanted = await wantedLinks(enabled ? currentRoot : null, layerRoot);
   const records: Record<string, LinkRecord> = {};
   let changed = false;
 
-  for (const entry of existing) {
-    if (!entry.isSymbolicLink()) continue;
-    const link = path.join(targetRoot, entry.name);
-    const target = await linkTarget(link);
-    if (target === null) continue;
-    const record = recorded[recordKey(entry.name)];
-    const owned = record
-      ? (await realOrResolved(record.target)) === target
-      : roots.some((root) => path.dirname(target) === root);
-    if (!owned) continue;
-
-    const wanted = currentRoot ? path.join(currentRoot, entry.name) : null;
-    if (wanted && sourceNames.has(entry.name) && (await realOrResolved(wanted)) === target) {
-      records[recordKey(entry.name)] = { runtime: "claude", target: wanted };
-      continue;
-    }
+  const linkDirs = [
+    { dir: path.join(repoRoot, CLAUDE_SKILLS_PATH), keyOf: recordKey, adoptable: true },
+    { dir: path.join(repoRoot, CLAUDE_AGENTS_PATH), keyOf: agentKey, adoptable: false },
+  ];
+  for (const { dir, keyOf, adoptable } of linkDirs) {
+    const existing = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of existing) {
+      if (!entry.isSymbolicLink()) continue;
+      const link = path.join(dir, entry.name);
+      const target = await linkTarget(link);
+      if (target === null) continue;
+      const key = keyOf(entry.name);
+      const record = recorded[key];
+      const owned = record
+        ? (await realOrResolved(record.target)) === target
+        : adoptable && roots.some((root) => path.dirname(target) === root);
+      if (!owned) continue;
 
-    await fs.unlink(link);
-    changed = true;
-  }
+      const want = wanted.get(key);
+      if (want && (await realOrResolved(want)) === target) {
+        records[key] = { runtime: "claude", target: want };
+        continue;
+      }
 
-  if (currentRoot && sourceNames.size > 0) {
-    await fs.mkdir(targetRoot, { recursive: true });
-    for (const name of sourceNames) {
-      const link = path.join(targetRoot, name);
-      const existingLink = await fs.lstat(link).catch(() => null);
-      if (existingLink) continue;
-      const target = path.join(currentRoot, name);
-      await createSkillLink(target, link);
-      records[recordKey(name)] = { runtime: "claude", target };
+      await fs.unlink(link);
       changed = true;
     }
   }
 
+  for (const [key, target] of wanted) {
+    const link = path.join(repoRoot, ...key.split("/"));
+    const existingLink = await fs.lstat(link).catch(() => null);
+    if (existingLink) continue;
+    await fs.mkdir(path.dirname(link), { recursive: true });
+    if (key.startsWith(".claude/agents/")) await fs.symlink(target, link, "file");
+    else await createSkillLink(target, link);
+    records[key] = { runtime: "claude", target };
+    changed = true;
+  }
+
   if (changed || !enabled) {
-    await pruneEmptyAncestors(targetRoot, path.resolve(repoPath));
+    for (const { dir } of linkDirs) await pruneEmptyAncestors(dir, repoRoot);
   }
   if (JSON.stringify(sortedEntries(records)) !== JSON.stringify(sortedEntries(recorded))) {
     await updateManifest(repoPath, (manifest) => withLinks(manifest, "claude", records));

package/src/lib/orchestrator/projection-entries.ts

@@ -37,6 +37,15 @@ import {
   removeCompanionCopies,
   withdrawCompanionCopies,
 } from "./projection-opencode-copies";
+import {
+  OPENSPEC_POINTER_EXCLUDE,
+  OPENSPEC_POINTER_PATH,
+  projectStorePointer,
+  reconcileStorePointerExclude,
+  removeStorePointer,
+  removeStorePointerExclude,
+  storePointerPresent,
+} from "./projection-openspec-store";
 import { buildProjection } from "./projection-record";
 import {
   CLAUDE_WORKING_SETTINGS_PATH,
@@ -245,6 +254,42 @@ function buildEntries(): readonly ProjectionEntry[] {
         input.companionPath && input.repository ? writeProjectionPairEntry(input) : "skipped",
       removal: { by: "entry", entry: "projection-root" },
     },
+    /**
+     * The OpenSpec store pointer's exclusion, then the pointer: the line is on
+     * disk before the file it hides. Its own line outside the managed block,
+     * disjoint from `capability-excludes`, so neither strips the other's.
+     */
+    {
+      id: "openspec-store-exclude",
+      kind: "merged",
+      path: path.join(".git", "info", "exclude"),
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        (await reconcileStorePointerExclude(input.repoPath)) ? "written" : "current",
+      degradable: true,
+      removal: { by: "self", remove: (input) => removeStorePointerExclude(input.repoPath) },
+      present: (repoPath) =>
+        workingRepoCapabilityExcludesPresent(repoPath, [OPENSPEC_POINTER_EXCLUDE]),
+    },
+    /**
+     * Degradable: without it OpenSpec still plans in the companion, it only
+     * names no Working Repository edit root — and the wrapper says so.
+     */
+    {
+      id: "openspec-store-pointer",
+      kind: "owned",
+      path: OPENSPEC_POINTER_PATH,
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        input.companionPath ? projectStorePointer(input.repoPath, input.companionPath) : "skipped",
+      degradable: true,
+      removal: {
+        by: "self",
+        remove: (input) => removeStorePointer(input.repoPath),
+        retains: "openspec-store-registration",
+      },
+      present: storePointerPresent,
+    },
     {
       id: "claude-skill-links",
       kind: "merged",
@@ -262,6 +307,7 @@ function buildEntries(): readonly ProjectionEntry[] {
           input.companionPath ?? null,
           input.config.allowedAgents?.includes("claude") ?? false,
           registeredCompanionPaths,
+          input.audienceLayerDir ?? null,
         );
       },
       removal: {

package/src/lib/orchestrator/projection-openspec-store.ts

@@ -0,0 +1,164 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { generatedHeader } from "../../runtime/projection";
+import { reconcileWorkingRepoCapabilityExcludes } from "../../tools/setup/working-repo-local-state";
+import { ensureStoreRegistration } from "./openspec-store";
+import type { ProjectionWriteReport, ProjectionWriteState } from "./projection-types";
+
+/**
+ * The store pointer: an `openspec/config.yaml` in the Working Repository that
+ * declares the companion's OpenSpec store. Run from inside the repository,
+ * OpenSpec then plans in the store and names the repository as the edit root.
+ *
+ * The pointer's whole `openspec/` folder is hidden only through
+ * `.git/info/exclude`, never the repository's own `.gitignore`: all planning
+ * lives in the store, so nothing under it belongs to the repository. Mate
+ * never writes it where the repository already owns an OpenSpec root.
+ */
+
+const execFileAsync = promisify(execFile);
+
+export const OPENSPEC_POINTER_PATH = path.join("openspec", "config.yaml");
+/** The exclusion line, outside the managed block so a core-block rewrite keeps it. */
+export const OPENSPEC_POINTER_EXCLUDE = "/openspec/";
+/** The earlier file-only line; still managed so a refresh replaces it. */
+const LEGACY_POINTER_EXCLUDE = "/openspec/config.yaml";
+const MANAGED_POINTER_EXCLUDES = [OPENSPEC_POINTER_EXCLUDE, LEGACY_POINTER_EXCLUDE];
+
+export type StorePointer = { kind: "absent" } | { kind: "foreign" } | { kind: "mate"; id: string };
+
+function pointerFile(repoPath: string): string {
+  return path.join(repoPath, OPENSPEC_POINTER_PATH);
+}
+
+function renderPointer(id: string): string {
+  return `${generatedHeader()}\nstore: ${id}\n`;
+}
+
+async function exists(candidate: string): Promise<boolean> {
+  return fs
+    .access(candidate)
+    .then(() => true)
+    .catch(() => false);
+}
+
+export async function readStorePointer(repoPath: string): Promise<StorePointer> {
+  const content = await fs.readFile(pointerFile(repoPath), "utf8").catch(() => null);
+  if (content === null) return { kind: "absent" };
+  const [first, ...rest] = content.split(/\r?\n/);
+  if (first !== generatedHeader()) return { kind: "foreign" };
+  const store = rest.map((line) => /^store:\s*(\S+)\s*$/.exec(line)?.[1]).find(Boolean);
+  return { kind: "mate", id: store ?? "" };
+}
+
+/**
+ * Why Mate may not point this repository at a store, or `null` when it may: a
+ * config Mate did not write, or a planning root of the repository's own.
+ */
+export async function storePointerIneligibility(repoPath: string): Promise<string | null> {
+  if ((await readStorePointer(repoPath)).kind === "foreign") {
+    return `${pointerFile(repoPath)} is not Mate's`;
+  }
+  for (const dir of ["specs", "changes"]) {
+    const planningRoot = path.join(repoPath, "openspec", dir);
+    // oxlint-disable-next-line no-await-in-loop -- two probes, first hit wins
+    if (await exists(planningRoot)) return `${planningRoot} is the repository's own OpenSpec root`;
+  }
+  return null;
+}
+
+/**
+ * Whether Git would show the pointer, asked of Git itself so a re-including
+ * rule anywhere above the exclude file counts. `null` when the pointer stays
+ * out of every diff, including outside a Git work tree.
+ */
+export async function pointerIgnoreProblem(repoPath: string): Promise<string | null> {
+  const pointer = OPENSPEC_POINTER_PATH.split(path.sep).join("/");
+  try {
+    await execFileAsync("git", ["check-ignore", "-q", pointer], { cwd: repoPath });
+    return null;
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== 1) return null;
+  }
+  const { stdout } = await execFileAsync("git", ["check-ignore", "-v", "-n", pointer], {
+    cwd: repoPath,
+  }).catch(() => ({ stdout: "" }));
+  const [source, line, pattern] = stdout.split("\t")[0]?.split(":") ?? [];
+  return pattern
+    ? `${pointer} is re-included by "${pattern}" (${source}:${line})`
+    : `${pointer} is not ignored by Git`;
+}
+
+async function persistPointer(repoPath: string, id: string): Promise<void> {
+  await fs.mkdir(path.dirname(pointerFile(repoPath)), { recursive: true });
+  await fs.writeFile(pointerFile(repoPath), renderPointer(id), "utf8");
+}
+
+export async function writeStorePointer(
+  repoPath: string,
+  id: string,
+): Promise<"written" | "current"> {
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === id) return "current";
+  await persistPointer(repoPath, id);
+  return "written";
+}
+
+/** Only Mate's pointer; `openspec/` goes too when nothing else is left in it. */
+export async function removeStorePointer(repoPath: string): Promise<"removed" | "absent"> {
+  if ((await readStorePointer(repoPath)).kind !== "mate") return "absent";
+  await fs.rm(pointerFile(repoPath));
+  await fs.rmdir(path.dirname(pointerFile(repoPath))).catch(() => {});
+  return "removed";
+}
+
+export async function storePointerPresent(repoPath: string): Promise<boolean> {
+  return (await readStorePointer(repoPath)).kind === "mate";
+}
+
+/** Keeps the exclusion line exactly while the repository may carry Mate's pointer. */
+export async function reconcileStorePointerExclude(repoPath: string): Promise<boolean> {
+  const eligible = (await storePointerIneligibility(repoPath)) === null;
+  return reconcileWorkingRepoCapabilityExcludes(
+    repoPath,
+    eligible ? [OPENSPEC_POINTER_EXCLUDE] : [],
+    MANAGED_POINTER_EXCLUDES,
+  );
+}
+
+export async function removeStorePointerExclude(repoPath: string): Promise<"removed" | "absent"> {
+  return (await reconcileWorkingRepoCapabilityExcludes(repoPath, [], MANAGED_POINTER_EXCLUDES))
+    ? "removed"
+    : "absent";
+}
+
+function pointerNotWritten(reason: string): ProjectionWriteReport {
+  return { state: "skipped", warnings: [`OpenSpec store pointer not written: ${reason}`] };
+}
+
+/**
+ * Eligibility, then registration, then the pointer: a pointer naming a store
+ * OpenSpec cannot resolve would break every root-resolving command. Git is
+ * asked about the pointer only before it is created or rewritten, so a
+ * steady-state refresh spawns nothing.
+ */
+export async function projectStorePointer(
+  repoPath: string,
+  companionPath: string,
+): Promise<ProjectionWriteState | ProjectionWriteReport> {
+  /** A companion without OpenSpec has no store to point at; nothing to say. */
+  if (!(await exists(path.join(companionPath, "openspec")))) return "skipped";
+  const ineligible = await storePointerIneligibility(repoPath);
+  if (ineligible) return pointerNotWritten(ineligible);
+  const registration = await ensureStoreRegistration(companionPath);
+  if (registration.state === "skipped") return pointerNotWritten(registration.reason);
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === registration.id) return registration.state;
+  const ignoreProblem = await pointerIgnoreProblem(repoPath);
+  if (ignoreProblem) return pointerNotWritten(ignoreProblem);
+  await persistPointer(repoPath, registration.id);
+  return "written";
+}

package/src/lib/orchestrator/projection-types.ts

@@ -25,6 +25,8 @@ export type ProjectionEntryId =
   | "repo-local-framework"
   | "repo-local-registry"
   | "projection-pair"
+  | "openspec-store-exclude"
+  | "openspec-store-pointer"
   | "claude-skill-links"
   | "workspace-document"
   | "capability-excludes"
@@ -48,6 +50,8 @@ export interface ProjectionInput {
   runtimeDocuments?: readonly RenderedRuntimeDocument[];
   /** Restricts runtime-tagged entries to these runtimes; every runtime when absent. */
   runtimes?: readonly WrapRuntime[];
+  /** The layer directory of the audience the checkout is wrapped for; `null` or absent for base only. */
+  audienceLayerDir?: string | null;
 }
 
 export interface ProjectionRemovalInput {
@@ -85,6 +89,8 @@ export type ProjectionEntryRemoval =
   | {
       readonly by: "self";
       remove(input: ProjectionRemovalInput): Promise<"removed" | "absent">;
+      /** What removing this path deliberately leaves outside the repository, named in the outcome. */
+      readonly retains?: string;
     }
   | { readonly by: "entry"; readonly entry: ProjectionEntryId }
   | { readonly by: "retained"; readonly because: string };
@@ -130,6 +136,8 @@ export interface ProjectionEntryOutcome {
   warnings?: string[];
   /** Present only when the entry wrote or withdrew paths it reports one by one. */
   changed?: ProjectionChangedPaths;
+  /** Present only on a removal that leaves something outside the repository behind. */
+  retains?: string;
 }
 
 export interface ProjectionResult {
@@ -157,7 +165,7 @@ export interface ProjectionDescription {
   projection: ProjectionFile | null;
 }
 
-/** A degradable entry's failure is reported in the outcomes and nowhere else. */
+/** Skips a degradable entry's failure: it never fails a pass, only shows in the outcomes. */
 export function firstFailure(outcomes: ProjectionEntryOutcome[]): ProjectionEntryOutcome | null {
   return outcomes.find((outcome) => outcome.state === "failed" && !outcome.degradable) ?? null;
 }