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

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

@@ -28,6 +28,7 @@ export type ProjectionEntryId =
   | "openspec-store-exclude"
   | "openspec-store-pointer"
   | "claude-skill-links"
+  | "claude-command-links"
   | "workspace-document"
   | "capability-excludes"
   | "claude-working-settings"
@@ -41,6 +42,8 @@ export type ProjectionEntryId =
 export interface ProjectionInput {
   repoPath: string;
   companionPath?: string;
+  /** Every companion folder the workspace document lists, in order; `[companionPath]` when absent. */
+  workspaceCompanionPaths?: string[];
   repository?: LinkedRepository;
   source?: CompanionSource;
   config?: FrameworkConfig;

package/src/lib/orchestrator/refresh-working-claude-links.ts

@@ -0,0 +1,87 @@
+import { readWrapState } from "../../runtime/wrap-state";
+import { GlobalConfigStore } from "./global-config-store";
+import { reconcileWorkingRepoClaudeCommandLinks } from "./projection-claude-commands";
+import { reconcileWorkingRepoClaudeSkillLinks } from "./projection-claude-skills";
+import { readCompanionRegistry } from "./repository-link";
+import type { FrameworkConfig, LinkedRepository } from "./types";
+import { errorMessage } from "../../runtime/error-message";
+
+export interface LinkRefreshResult {
+  /** Null when the companion's list of linked repositories could not be read. */
+  repository: LinkedRepository | null;
+  outcome: "written" | "current" | "failed";
+  error?: string;
+}
+
+export interface LinkRefreshDeps {
+  readRegistry: (companionPath: string) => Promise<LinkedRepository[]>;
+  isWrappedForClaude: (repoPath: string) => Promise<boolean>;
+  registeredCompanionPaths: () => Promise<string[]>;
+  reconcileSkillLinks: typeof reconcileWorkingRepoClaudeSkillLinks;
+  reconcileCommandLinks: typeof reconcileWorkingRepoClaudeCommandLinks;
+}
+
+const linkRefreshDeps: LinkRefreshDeps = {
+  readRegistry: async (companionPath) => {
+    try {
+      return (await readCompanionRegistry(companionPath)).repos;
+    } catch (error) {
+      // No registry file means no linked repositories.
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+  },
+  isWrappedForClaude: async (repoPath) => (await readWrapState(repoPath)).runtimes.has("claude"),
+  registeredCompanionPaths: () => new GlobalConfigStore().list(),
+  reconcileSkillLinks: reconcileWorkingRepoClaudeSkillLinks,
+  reconcileCommandLinks: reconcileWorkingRepoClaudeCommandLinks,
+};
+
+/**
+ * Re-links the companion's Claude skills and commands into every linked Claude-wrapped
+ * Working Repository. Links only; runtime documents wait for the wrap pass. Failures
+ * are reported per repository, never thrown.
+ */
+export async function refreshWorkingClaudeLinks(
+  companionPath: string,
+  config: FrameworkConfig,
+  deps: LinkRefreshDeps = linkRefreshDeps,
+): Promise<LinkRefreshResult[]> {
+  const enabled = config.allowedAgents?.includes("claude") ?? false;
+  const results: LinkRefreshResult[] = [];
+  let registered: string[] | undefined;
+  let repositories: LinkedRepository[];
+  try {
+    repositories = await deps.readRegistry(companionPath);
+  } catch (error) {
+    return [{ repository: null, outcome: "failed", error: errorMessage(error) }];
+  }
+
+  for (const repository of repositories) {
+    try {
+      if (!(await deps.isWrappedForClaude(repository.path))) continue;
+      registered ??= await deps.registeredCompanionPaths();
+      const skills = await deps.reconcileSkillLinks(
+        repository.path,
+        companionPath,
+        enabled,
+        registered,
+      );
+      const commands = await deps.reconcileCommandLinks(
+        repository.path,
+        companionPath,
+        enabled,
+        registered,
+      );
+      const written = skills === "written" || commands === "written";
+      results.push({ repository, outcome: written ? "written" : "current" });
+    } catch (error) {
+      results.push({
+        repository,
+        outcome: "failed",
+        error: errorMessage(error),
+      });
+    }
+  }
+  return results;
+}

package/src/lib/orchestrator/session-prepare.ts

@@ -1,5 +1,6 @@
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
+import { launchPassesClaudePluginFolders } from "../../runtime/claude-delivery-plan";
 import { recordCompanionSyncUnfinished } from "../../runtime/companion-git-state";
 import { withCompanionLock, type CompanionLockOptions } from "../../runtime/companion-lock";
 import {
@@ -7,9 +8,11 @@ import {
   syncCompanionUnattended,
   type UnattendedSyncOutcome,
 } from "../../runtime/companion-sync";
+import { managedSessionKind, type SessionKind } from "../../runtime/session-kind";
 import type { WrapState } from "../../runtime/wrap-state";
 import { syncCompanionFiles } from "../../tools/setup";
 import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
+import type { ClaudePluginFolders } from "../../tools/setup/providers/claude-plugin-folders";
 import { attendedLockOptions, syncCompanionGit } from "./companion-git-sync";
 import { readCompanionConfig } from "./config-store";
 import { entryFailureMessage, firstFailure, type ProjectionChangedPaths } from "./projection-types";
@@ -61,6 +64,8 @@ export interface PrepareResult {
   failure?: unknown;
   /** The wrap state the `working-target` step's pass left; a launch reads no manifest itself. */
   wrapState?: WrapState;
+  /** The Claude plugin folders the `file-sync` step gathered; a launch gathers none itself. */
+  claudePluginDirectories?: string[];
 }
 
 export interface PrepareSessionInput {
@@ -123,7 +128,8 @@ export const sessionPrepareDeps = {
   syncCompanionGit,
   syncCompanionUnattended,
   recordCompanionSyncUnfinished,
-  syncCompanionFiles,
+  syncCompanionFiles: async (...args: Parameters<typeof syncCompanionFiles>) =>
+    (await syncCompanionFiles(...args)).claudePluginFolders,
   projectLaunch: (input: Parameters<typeof project>[1]) => project("launch", input),
   /**
    * The Projection Root a Claude launch guarantees for itself. Companion
@@ -149,6 +155,7 @@ class StepLog {
   readonly warnings: string[] = [];
   failure: unknown;
   wrapState: WrapState | undefined;
+  claudePluginDirectories: string[] | undefined;
   stopped = false;
   companionChanged = false;
 
@@ -176,10 +183,18 @@ async function runFileSync(
 ): Promise<void> {
   const deps = sessionPrepareDeps;
   try {
-    if (input.repository) {
-      await deps.syncCompanionFiles(input.companionPath, config, input.repository.path);
-    } else {
-      await deps.syncCompanionFiles(input.companionPath, config);
+    const folders = input.repository
+      ? await deps.syncCompanionFiles(input.companionPath, config, input.repository.path)
+      : await deps.syncCompanionFiles(input.companionPath, config);
+    run.claudePluginDirectories = [...folders.launch];
+    /**
+     * The Claude plan speaks for Claude sessions only; OpenCode loads no plugin
+     * folder. With a Working Repository the wrap pass reports publication;
+     * without one no wrap pass runs, so this step does.
+     */
+    if (reportsClaudePluginFolders(input)) {
+      run.warnings.push(...folders.loadWarnings);
+      if (!input.repository) run.warnings.push(...publicationWarnings(folders));
     }
     run.push({ step: "file-sync", outcome: "ok" });
   } catch (error) {
@@ -199,6 +214,24 @@ function wrapDetail(wrapped: {
   return parts.length > 0 ? `updated (${parts.join("; ")})` : "updated";
 }
 
+/** A managed Claude launch; plain sessions' prepares and OpenCode report no plugin-folder problem. */
+function reportsClaudePluginFolders(input: PrepareSessionInput): boolean {
+  return input.runtime === "claude" && launchPassesClaudePluginFolders(sessionKindOf(input));
+}
+
+/** What a publication left undone, one sentence per folder. */
+function publicationWarnings(folders: ClaudePluginFolders | undefined): string[] {
+  const publication = folders?.publication;
+  if (!publication) return [];
+  return [...publication.unpublished.map((entry) => entry.warning), ...publication.warnings];
+}
+
+/** Attended is a managed launch, with or without a Working Repository; the rest serve plain sessions. */
+function sessionKindOf(input: PrepareSessionInput): SessionKind {
+  if (input.mode !== "attended") return "unmanaged";
+  return managedSessionKind(Boolean(input.repository));
+}
+
 function runtimesOf(input: PrepareSessionInput): PrepareRuntime[] {
   return input.mode !== "attended" && input.runtimes?.length
     ? [...input.runtimes]
@@ -225,6 +258,9 @@ async function reconcileWrap(
     return;
   }
   run.warnings.push(...wrapped.warnings);
+  if (reportsClaudePluginFolders(input)) {
+    run.warnings.push(...publicationWarnings(wrapped.claudePluginFolders));
+  }
   run.wrapState = wrapped.wrapState;
   run.push({
     step: "working-target",
@@ -308,6 +344,7 @@ async function runLocal(
         config,
         repository: input.repository,
         providerId: runtime,
+        sessionKind: sessionKindOf(input),
       }),
     ),
   );
@@ -401,6 +438,9 @@ export async function prepareSession(input: PrepareSessionInput): Promise<Prepar
     ...(run.companionChanged ? { companionChanged: true as const } : {}),
     ...(run.failure === undefined ? {} : { failure: run.failure }),
     ...(run.wrapState ? { wrapState: run.wrapState } : {}),
+    ...(run.claudePluginDirectories
+      ? { claudePluginDirectories: run.claudePluginDirectories }
+      : {}),
   });
 
   const locked = await deps.withCompanionLock(input.companionPath, lockOptions(input), async () => {

package/src/lib/orchestrator/setup-compatibilities.ts

@@ -1,23 +1,8 @@
-import type {
-  CapabilityConfig,
-  CliToolConfig,
-  FrameworkConfig,
-  GitModeProfile,
-  OpenSpecSchemaProfile,
-} from "./types";
+import type { CapabilityConfig, CliToolConfig, FrameworkConfig, GitModeProfile } from "./types";
 
-export type OpenSpecSchemaSelection = OpenSpecSchemaProfile | "default";
 export type GitModeSelection = GitModeProfile | "default";
-const DEFAULT_OPENSPEC_SCHEMA_SELECTION: OpenSpecSchemaSelection = "default";
 export const DEFAULT_GIT_MODE_SELECTION: GitModeSelection = "default";
 
-export interface OpenSpecSchemaCompatibility {
-  id: OpenSpecSchemaSelection;
-  label: string;
-  description: string;
-  defaultSelected: boolean;
-}
-
 export interface GitModeCompatibility {
   id: GitModeSelection;
   label: string;
@@ -25,21 +10,6 @@ export interface GitModeCompatibility {
   defaultSelected: boolean;
 }
 
-const BUILTIN_OPENSPEC_SCHEMA_COMPATIBILITIES: OpenSpecSchemaCompatibility[] = [
-  {
-    id: "default",
-    label: "Default (vanilla OpenSpec)",
-    description: "Use OpenSpec's built-in spec-driven workflow.",
-    defaultSelected: true,
-  },
-  {
-    id: "mate-v1",
-    label: "Mate v1",
-    description: "Use Mate's schema with proposal, design, spec, and task artifacts.",
-    defaultSelected: false,
-  },
-];
-
 const BUILTIN_GIT_MODE_COMPATIBILITIES: GitModeCompatibility[] = [
   {
     id: "default",
@@ -59,33 +29,9 @@ export interface SetupSelections {
   allowedAgents: string[];
   packageManagers: string[];
   capabilities: CapabilityConfig[];
-  selectedOpenSpecSchema: OpenSpecSchemaSelection;
   selectedGitMode: GitModeSelection;
 }
 
-export function getOpenSpecSchemaSelection(
-  capabilities: CapabilityConfig[],
-): OpenSpecSchemaSelection {
-  const openspec = capabilities.find((capability) => capability.name === "openspec");
-  return openspec?.schemaProfile ?? DEFAULT_OPENSPEC_SCHEMA_SELECTION;
-}
-
-export function applyOpenSpecSchemaSelection(
-  capabilities: CapabilityConfig[],
-  schemaSelection: OpenSpecSchemaSelection | undefined,
-): CapabilityConfig[] {
-  if (schemaSelection === undefined) return capabilities;
-
-  return capabilities.map((capability) => {
-    if (capability.name !== "openspec") return capability;
-    if (schemaSelection === "default") {
-      const { schemaProfile: _schemaProfile, ...rest } = capability;
-      return rest;
-    }
-    return { ...capability, schemaProfile: schemaSelection };
-  });
-}
-
 interface SetupCompatibilityBase {
   id: string;
   label: string;
@@ -222,24 +168,6 @@ export function listSetupPackageManagerCompatibilities(): SetupPackageManagerCom
   );
 }
 
-export function listSetupOpenSpecSchemaCompatibilities(
-  activeSchemaProfile?: OpenSpecSchemaSelection,
-): OpenSpecSchemaCompatibility[] {
-  const compatibilities = [...BUILTIN_OPENSPEC_SCHEMA_COMPATIBILITIES];
-  if (
-    activeSchemaProfile !== undefined &&
-    !BUILTIN_OPENSPEC_SCHEMA_COMPATIBILITIES.some((entry) => entry.id === activeSchemaProfile)
-  ) {
-    compatibilities.push({
-      id: activeSchemaProfile,
-      label: "Custom",
-      description: `Keep the project's current custom schema profile ("${activeSchemaProfile}"). Selecting Default or Mate v1 replaces it.`,
-      defaultSelected: false,
-    });
-  }
-  return compatibilities;
-}
-
 export function listSetupGitModeCompatibilities(): GitModeCompatibility[] {
   return [...BUILTIN_GIT_MODE_COMPATIBILITIES];
 }
@@ -272,7 +200,6 @@ export function getDefaultSetupSelections(): SetupSelections {
     allowedAgents,
     packageManagers,
     capabilities,
-    selectedOpenSpecSchema: DEFAULT_OPENSPEC_SCHEMA_SELECTION,
     selectedGitMode: DEFAULT_GIT_MODE_SELECTION,
   };
 }
@@ -284,11 +211,27 @@ export function getSetupSelectionsFromConfig(config: FrameworkConfig): SetupSele
       ...new Set([...getLockedPackageManagers(), ...(config.packageManagers ?? [])]),
     ],
     capabilities: dedupeCapabilities(config.capabilities ?? []),
-    selectedOpenSpecSchema: getOpenSpecSchemaSelection(config.capabilities ?? []),
     selectedGitMode: config.git ?? DEFAULT_GIT_MODE_SELECTION,
   };
 }
 
+/**
+ * Re-selected capabilities keep their saved settings (such as openspec's
+ * `protectedBranches`); pickers and flags only name the capabilities.
+ */
+export function keepCapabilitySettings(
+  selected: CapabilityConfig[],
+  saved: CapabilityConfig[],
+): CapabilityConfig[] {
+  const byName = new Map(saved.map((capability) => [capability.name, capability]));
+  return selected.map((capability) => {
+    // `schemaProfile` is a removed setting; a re-save drops it.
+    const { schemaProfile: _removed, ...settings } = (byName.get(capability.name) ??
+      {}) as CapabilityConfig & { schemaProfile?: unknown };
+    return { ...capability, ...settings };
+  });
+}
+
 export function dedupeCapabilities(capabilities: CapabilityConfig[]): CapabilityConfig[] {
   const seen = new Set<string>();
   const result: CapabilityConfig[] = [];

package/src/lib/orchestrator/types.ts

@@ -58,12 +58,12 @@ export interface CliToolConfig {
   redirectCwd: "companionRoot" | false;
 }
 
-export type OpenSpecSchemaProfile = "mate-v1" | (string & {});
 export type GitModeProfile = "auto";
 
 export interface CapabilityConfig {
   name: string;
-  schemaProfile?: OpenSpecSchemaProfile;
+  /** openspec only: branch glob patterns (`release/*`) treated as protected besides the default branch. */
+  protectedBranches?: string[];
 }
 
 export type FrameworkType = "working" | "companion" | "hub";

package/src/lib/orchestrator/wrap-pass.ts

@@ -1,6 +1,10 @@
 import path from "node:path";
 
-import { renderWorkingRuntimeDocuments } from "../../tools/setup";
+import {
+  publishWorkingClaudePluginMarketplaces,
+  renderWorkingRuntimeDocuments,
+} from "../../tools/setup";
+import type { ClaudePluginFolders } from "../../tools/setup/providers/claude-plugin-folders";
 import { readCompanionConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import { entryFailureMessage, firstFailure, type ProjectionChangedPaths } from "./projection-types";
@@ -10,6 +14,7 @@ import type { FrameworkConfig, LinkedRepository } from "./types";
 import { project } from "./working-repo-projection";
 
 export interface WrapPassDependencies {
+  publishWorkingClaudePluginMarketplaces: typeof publishWorkingClaudePluginMarketplaces;
   renderWorkingRuntimeDocuments: typeof renderWorkingRuntimeDocuments;
   readCompanionConfig: typeof readCompanionConfig;
   project: typeof project;
@@ -18,6 +23,7 @@ export interface WrapPassDependencies {
 }
 
 export const wrapPassDeps: WrapPassDependencies = {
+  publishWorkingClaudePluginMarketplaces,
   renderWorkingRuntimeDocuments,
   readCompanionConfig,
   project,
@@ -47,6 +53,11 @@ export type WrapPassResult =
       runtimes: ReadonlySet<WrapRuntime>;
       /** The wrap state as this pass left it. */
       wrapState: WrapState;
+      /**
+       * The Claude plugin folders this pass published, when it covered Claude;
+       * what publication left undone is the caller's to present, never in `warnings`.
+       */
+      claudePluginFolders?: ClaudePluginFolders;
     }
   | { kind: "failed"; message: string };
 
@@ -63,6 +74,15 @@ export async function runWrapPass(
 ): Promise<WrapPassResult> {
   const resolvedCompanionPath = path.resolve(companionPath);
   const config = options.config ?? (await deps.readCompanionConfig(resolvedCompanionPath));
+  /** The render reads the marketplace files, so they are written first. */
+  const published =
+    !options.runtimes || options.runtimes.includes("claude")
+      ? await deps.publishWorkingClaudePluginMarketplaces(
+          resolvedCompanionPath,
+          config,
+          repository.path,
+        )
+      : undefined;
   const rendered = await deps.renderWorkingRuntimeDocuments(
     resolvedCompanionPath,
     config,
@@ -131,5 +151,6 @@ export async function runWrapPass(
     ],
     runtimes,
     wrapState,
+    ...(published ? { claudePluginFolders: published } : {}),
   };
 }

package/src/lib/package-paths.ts

@@ -32,10 +32,18 @@ export function getClaudePluginRoot(): string {
   return path.resolve(import.meta.dirname, "../../claude-plugin");
 }
 
+/**
+ * The `name` in the bundled Claude plugin's manifest. Claude Code identifies a
+ * plugin by its name, so a contributed folder using this one could take the
+ * place of Mate's plugin and its guardrail hooks.
+ */
+export const MATE_CLAUDE_PLUGIN_NAME = "mate-claude-plugin";
+
 const CLAUDE_PLUGIN_HOOK_SHIMS = [
   "validate-artifact-path.mjs",
   "session-banner.mjs",
   "session-guidance.mjs",
+  "companion-instructions.mjs",
 ] as const;
 
 /**

package/src/opencode/companion-hooks.ts

@@ -2,6 +2,8 @@ import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
 
+import { resolveArtifactTarget } from "../runtime/artifact-refusal";
+import { checkCommitAttribution } from "../runtime/commit-attribution-guard";
 import {
   companionForkRefusal,
   syncCompanionUnattended,
@@ -10,12 +12,14 @@ import {
 import { hasLaunchEnvironment } from "../runtime/env";
 import { MATE_ENV } from "../runtime/env-names";
 import { resolveProjection } from "../runtime/projection";
+import { checkSecretAccess, type SecretToolCall } from "../runtime/secret-guard";
 import { readWrapStateSync } from "../runtime/wrap-state";
 import {
   buildArtifactError,
+  extractPatchAdditions,
   extractPatchPaths,
   isArtifactPath,
-  normalizeTargetPath,
+  isCompanionTarget,
   shouldBlockArtifactWrite,
   type CompanionContext,
 } from "./companion-policy";
@@ -87,14 +91,55 @@ export async function refuseForkedCompanionWrite(
   env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   if (!filePath || !isArtifactPath(filePath)) return;
-  if (!normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
-    return;
-  }
+  if (!isCompanionTarget(context, filePath)) return;
   const refusal = await companionForkRefusal(env, context.companionPath);
   if (refusal) throw new Error(refusal);
 }
 
-/** Rejects when the tool call would write an artifact outside the companion. */
+/** OpenCode tool inputs in the shape the shared secret guard reads. */
+function secretToolCall(
+  context: CompanionContext,
+  tool: string,
+  args: Record<string, unknown>,
+): SecretToolCall | null {
+  const text = (value: unknown) => (typeof value === "string" ? value : "");
+  const target = (value: unknown) =>
+    text(value) ? resolveArtifactTarget(text(value), context.repositoryPath) : "";
+  switch (tool) {
+    case "read":
+      return { kind: "read", paths: [target(args.filePath)] };
+    case "write":
+      return {
+        kind: "write",
+        writes: [{ path: target(args.filePath), content: text(args.content) }],
+      };
+    case "edit":
+      return {
+        kind: "write",
+        writes: [{ path: target(args.filePath), content: text(args.newString) }],
+      };
+    case "apply_patch":
+      return {
+        kind: "write",
+        writes: extractPatchAdditions(text(args.patchText)).map((addition) => ({
+          path: target(addition.path),
+          content: addition.content,
+        })),
+      };
+    case "bash":
+      return { kind: "shell", command: text(args.command) };
+    case "grep":
+      return { kind: "search", paths: [target(args.path)], globs: [text(args.include)] };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Rejects when the tool call touches a secret, commits with a model co-author
+ * trailer, or would write an artifact outside the companion. Checked in that
+ * order, as in the Claude hook.
+ */
 export async function guardToolInput(
   context: CompanionContext,
   tool: string,
@@ -102,6 +147,20 @@ export async function guardToolInput(
   env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const args = (input ?? {}) as Record<string, unknown>;
+
+  const secretCall = context.companionPath ? secretToolCall(context, tool, args) : null;
+  if (secretCall) {
+    const companionRoot = path.normalize(context.companionPath);
+    const refusal = await checkSecretAccess(secretCall, {
+      companionPath: context.companionPath,
+      isCompanionPath: (filePath) => filePath.startsWith(companionRoot),
+    });
+    if (refusal) throw new Error(refusal);
+  }
+  if (tool === "bash") {
+    const refusal = checkCommitAttribution(String(args.command ?? ""));
+    if (refusal) throw new Error(refusal);
+  }
   const filePaths =
     tool === "write" || tool === "edit"
       ? [String(args.filePath ?? "")]

package/src/opencode/companion-policy.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
+import { artifactRefusal, resolveArtifactTarget } from "../runtime/artifact-refusal";
 import { persistedCompanionGitStalenessLines } from "../runtime/companion-sync";
 import { resolveCompanionRuntime, type CompanionRuntimeContext } from "../runtime/env";
 import { projectionFreshness, projectionStalenessLines } from "../runtime/freshness";
@@ -60,7 +61,7 @@ export function isArtifactPath(filePath: string): boolean {
 }
 
 export function isProductDocumentationPath(context: CompanionContext, filePath: string): boolean {
-  const normalized = normalizeTargetPath(context, filePath);
+  const normalized = resolveArtifactTarget(filePath, context.repositoryPath);
   const relativePath = path.relative(context.repositoryPath, normalized);
   if (!relativePath || relativePath.startsWith("..")) {
     return false;
@@ -86,12 +87,10 @@ export function isProductDocumentationPath(context: CompanionContext, filePath:
   return false;
 }
 
-export function normalizeTargetPath(context: CompanionContext, filePath: string): string {
-  if (path.isAbsolute(filePath)) {
-    return path.normalize(filePath);
-  }
-
-  return path.normalize(path.join(context.repositoryPath, filePath));
+export function isCompanionTarget(context: CompanionContext, filePath: string): boolean {
+  return resolveArtifactTarget(filePath, context.repositoryPath).startsWith(
+    path.normalize(context.companionPath),
+  );
 }
 
 export function isGitignored(context: CompanionContext, filePath: string): boolean {
@@ -99,7 +98,7 @@ export function isGitignored(context: CompanionContext, filePath: string): boole
     return false;
   }
 
-  const normalized = normalizeTargetPath(context, filePath);
+  const normalized = resolveArtifactTarget(filePath, context.repositoryPath);
   if (!normalized.startsWith(path.normalize(context.repositoryPath))) {
     return false;
   }
@@ -126,7 +125,7 @@ export function shouldBlockArtifactWrite(context: CompanionContext, filePath: st
     return false;
   }
 
-  if (normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
+  if (isCompanionTarget(context, filePath)) {
     return false;
   }
 
@@ -155,16 +154,36 @@ export function extractPatchPaths(patchText: string): string[] {
   return paths;
 }
 
-export function buildArtifactError(context: CompanionContext, filePath: string): string {
-  const rel = path.relative(context.repositoryPath, filePath);
-  const suggested = path.join(context.companionPath, rel);
+/**
+ * What a patch would add to each file it touches: the `+` lines of every
+ * section, keyed by the section's target (a move's destination when present).
+ */
+export function extractPatchAdditions(patchText: string): { path: string; content: string }[] {
+  const additions: { path: string; content: string[] }[] = [];
+  let current: { path: string; content: string[] } | undefined;
+  for (const line of patchText.split("\n")) {
+    const marker = /^\*\*\* (Add|Update|Delete|Move to) File:\s*(.+)$/.exec(line);
+    if (marker) {
+      if (marker[1] === "Move to" && current) {
+        current.path = marker[2].trim();
+      } else {
+        current = { path: marker[2].trim(), content: [] };
+        additions.push(current);
+      }
+      continue;
+    }
+    if (current && line.startsWith("+")) current.content.push(line.slice(1));
+  }
+  return additions.map((entry) => ({ path: entry.path, content: entry.content.join("\n") }));
+}
 
-  return [
-    `${context.frameworkName} guardrail: artifact writes must go to the companion framework path.`,
-    `  target:   ${filePath}`,
-    `  suggested: ${suggested}`,
-    `Rewrite to ${suggested} and retry.`,
-  ].join("\n");
+export function buildArtifactError(context: CompanionContext, filePath: string): string {
+  return artifactRefusal({
+    target: filePath,
+    resolved: resolveArtifactTarget(filePath, context.repositoryPath),
+    companion: context.companionPath,
+    repoRoot: context.repositoryPath,
+  });
 }
 
 /**

package/src/opencode/projected-guidance.ts

@@ -44,6 +44,9 @@ export function resolveOpenCodeGuidance(
   if (!projection) return { guidance: null, errors: [] };
 
   const policy = readCompanionPolicy(projection.companionPath);
-  const guidance = buildOpenCodeGuidance(policy.enabledCapabilities.map((name) => ({ name })));
+  const guidance = buildOpenCodeGuidance(
+    policy.enabledCapabilities.map((name) => ({ name })),
+    { secretGuardrails: policy.secrets.guardrails },
+  );
   return { guidance: guidance.errors.length > 0 ? null : guidance, errors: guidance.errors };
 }