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

package/src/cli/commands/artifact/delivery/branch-flags.ts

@@ -0,0 +1,55 @@
+import type { DeliveryEnvironment } from "../../../../lib/delivery/environment";
+import { sameRepository } from "../../../../lib/delivery/record";
+import type { DeliveryEdit } from "../../../../lib/delivery/record-delivery";
+import { type CliFlags, malformedValueFlag, stringFlag } from "../../../parse-flags";
+
+/** `--branch` with `--direct`, or `--not-applicable`, as `artifact link` and `archive` take them. */
+export interface BranchFlags {
+  branch?: string;
+  direct: boolean;
+  notApplicable?: string;
+}
+
+export function branchFlagsFrom(flags: CliFlags): BranchFlags {
+  return {
+    branch: stringFlag(flags.branch),
+    direct: flags.direct === true,
+    notApplicable: stringFlag(flags["not-applicable"]),
+  };
+}
+
+export const DIRECT_NEEDS_BRANCH = "mate: --direct records a direct delivery and needs --branch.";
+
+/** The delivery edit the branch flags ask for; `--branch` wins over `--not-applicable`. */
+export function deliveryEditFrom(flags: BranchFlags): DeliveryEdit["delivery"] {
+  if (flags.branch !== undefined) return { branch: flags.branch, direct: flags.direct };
+  if (flags.notApplicable !== undefined) return { notApplicable: flags.notApplicable };
+  return undefined;
+}
+
+/** Refuses a value flag given bare or repeated, which would otherwise read as absent. */
+export function valueFlagError(flags: CliFlags, names: readonly string[]): string | undefined {
+  const name = malformedValueFlag(flags, names);
+  return name === undefined ? undefined : `mate: --${name} takes exactly one value.`;
+}
+
+/** `--repository <org/repo>`, or the refusal for a malformed one. */
+export function repositoryFlag(flags: CliFlags): { repository?: string } | { error: string } {
+  const repository = stringFlag(flags.repository);
+  if (repository !== undefined && !/^[\w.-]+(?:\/[\w.-]+)+$/.test(repository)) {
+    return {
+      error:
+        "mate: --repository expects a repository path such as <org/repo> or <group/subgroup/repo>.",
+    };
+  }
+  return repository === undefined ? {} : { repository };
+}
+
+/** GitHub slugs are case-insensitive; the Working Repository's own spelling keeps one delivery. */
+export function canonicalRepository(
+  environment: DeliveryEnvironment,
+  requested: string | undefined,
+): string | undefined {
+  const own = environment.workingRepo?.slug;
+  return own && requested !== undefined && sameRepository(requested, own) ? own : requested;
+}

package/src/cli/commands/artifact/delivery/environment.ts

@@ -0,0 +1,104 @@
+import {
+  workingRepoGit,
+  configuredProtectedPatterns,
+  type WorkingRepoGit,
+} from "../../../../lib/delivery/branches";
+import type { DeliveryEnvironment, WorkingRepoInfo } from "../../../../lib/delivery/environment";
+import { parseRemote, repositoryPath, type ForgeRepo } from "../../../../lib/delivery/forge";
+import { sameRepository } from "../../../../lib/delivery/record";
+import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
+import {
+  resolveForCapability,
+  type LaunchContext,
+} from "../../../../lib/orchestrator/framework-context";
+import type { CapabilityConfig, LinkedRepository } from "../../../../lib/orchestrator/types";
+import { WorkingRepoRequiredError } from "../../../../lib/orchestrator/types";
+import { ensureUnambiguousCompanion } from "../../shared/companion-selection";
+
+export interface DeliveryEnvironmentDeps {
+  ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
+  resolveContext?: (cwd: string) => Promise<LaunchContext>;
+  loadCapabilities?: (context: LaunchContext) => Promise<CapabilityConfig[]>;
+  workingRepoGit?: (repoPath: string) => WorkingRepoGit;
+  loadLinkedRepositories?: (context: LaunchContext) => Promise<LinkedRepository[]>;
+}
+
+async function defaultLoadLinkedRepositories(context: LaunchContext): Promise<LinkedRepository[]> {
+  return (await context.workingRepoStore.load()).repos;
+}
+
+async function defaultLoadCapabilities(context: LaunchContext): Promise<CapabilityConfig[]> {
+  const config = await context.configStore.load();
+  return config.capabilities ?? [];
+}
+
+/**
+ * The companion, the Working Repository with its remote identity, and the configured
+ * protected-branch patterns. `error` explains why the command cannot run; it is null
+ * when the companion check has already reported the problem.
+ */
+export async function resolveDeliveryEnvironment(
+  deps: DeliveryEnvironmentDeps,
+): Promise<DeliveryEnvironment | { error: string | null }> {
+  const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
+  if (!(await ensureCompanion(process.cwd()))) return { error: null };
+
+  let context: LaunchContext;
+  try {
+    context = await (deps.resolveContext ?? ((cwd: string) => resolveForCapability(cwd)))(
+      process.cwd(),
+    );
+  } catch (err) {
+    if (err instanceof WorkingRepoRequiredError) return { error: err.message };
+    throw err;
+  }
+
+  const capabilities = await (deps.loadCapabilities ?? defaultLoadCapabilities)(context);
+  if (!hasOpenspecCapability(capabilities)) {
+    return { error: "mate: the openspec capability must be enabled to record delivery." };
+  }
+
+  const openGit = deps.workingRepoGit ?? workingRepoGit;
+  const repoPath = context.repository?.path ?? process.env.MATE_REPO_PATH;
+  let workingRepo: WorkingRepoInfo | null = null;
+  if (repoPath) {
+    const git = openGit(repoPath);
+    const remote = await git.remoteUrl();
+    const forgeRepo = remote ? parseRemote(remote) : null;
+    workingRepo = {
+      path: repoPath,
+      slug: forgeRepo ? repositoryPath(forgeRepo) : null,
+      forgeRepo,
+      git,
+    };
+  }
+
+  let linkedRemotes: Promise<ForgeRepo[]> | undefined;
+  // Read once, and only when a repository other than the Working Repository needs a host.
+  const linked = (): Promise<ForgeRepo[]> =>
+    (linkedRemotes ??= (async () => {
+      // An unreadable registry only loses host hints; the Working Repository's host remains.
+      const repositories = await (deps.loadLinkedRepositories ?? defaultLoadLinkedRepositories)(
+        context,
+      ).catch(() => []);
+      const remotes = await Promise.all(
+        repositories
+          .filter((repository) => repository.path !== repoPath)
+          .map((repository) => openGit(repository.path).remoteUrl()),
+      );
+      return remotes.flatMap((remote) => (remote ? (parseRemote(remote) ?? []) : []));
+    })());
+  const hostOf = async (repository: string): Promise<string | null> => {
+    const match = (await linked()).find((remote) =>
+      sameRepository(repositoryPath(remote), repository),
+    );
+    return match?.host ?? workingRepo?.forgeRepo?.host ?? null;
+  };
+
+  return {
+    companionPath: context.companionPath,
+    workingRepo,
+    protectedPatterns: configuredProtectedPatterns(capabilities),
+    hostOf,
+  };
+}

package/src/cli/commands/artifact/delivery/link.ts

@@ -0,0 +1,154 @@
+import {
+  recordDelivery,
+  type DeliveryRefusal,
+  type DeliveryResult,
+  type RecordDeliveryDeps,
+} from "../../../../lib/delivery/record-delivery";
+import { applyWarnings, type DependencyWarning } from "../../../../lib/delivery/overlap";
+import type { MergeState } from "../../../../lib/delivery/record";
+import { type BooleanFlagSet, parseFlags, positionalArgs, stringFlag } from "../../../parse-flags";
+import {
+  branchFlagsFrom,
+  canonicalRepository,
+  deliveryEditFrom,
+  DIRECT_NEEDS_BRANCH,
+  repositoryFlag,
+  valueFlagError,
+} from "./branch-flags";
+import { resolveDeliveryEnvironment, type DeliveryEnvironmentDeps } from "./environment";
+import {
+  commandOutput,
+  renderDelivery,
+  sharedRefusalMessage,
+  unscopedDeliveryWarning,
+} from "./output";
+
+export interface LinkCommandDeps extends DeliveryEnvironmentDeps, RecordDeliveryDeps {
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+const BOOLEAN_FLAGS: BooleanFlagSet = new Set([
+  "json",
+  "refresh",
+  "direct",
+  "confirm-merged",
+  "confirm-open",
+  "confirm-dropped",
+]);
+
+const CONFIRMATIONS: Record<string, MergeState> = {
+  "confirm-merged": "merged",
+  "confirm-open": "open",
+  "confirm-dropped": "closed-unmerged",
+};
+
+/** `warnings`: declared dependencies not implemented yet; they inform and never block. */
+export type LinkResult = DeliveryResult & { warnings: DependencyWarning[] };
+
+function refusalMessage(refusal: DeliveryRefusal): string {
+  if (refusal.reason === "unknown-change") {
+    return `mate: no active or archived change named "${refusal.change}".`;
+  }
+  return sharedRefusalMessage(refusal);
+}
+
+function renderHuman(result: LinkResult): string[] {
+  const lines = [`${result.change}: ${result.settlement.status}`];
+  lines.push(...result.record.deliveries.map(renderDelivery));
+  for (const repository of result.settlement.missing) {
+    lines.push(`  ${repository}: no delivery recorded (named in the change's scopes)`);
+  }
+  for (const outcome of result.outcomes.filter((entry) => entry.needsAnswer)) {
+    lines.push(`  ${outcome.branch}: needs an answer (${outcome.answerReason})`);
+    if (outcome.failure) lines.push(`    ${outcome.failure.message}`);
+    for (const candidate of outcome.candidates ?? []) {
+      lines.push(`    #${candidate.number} ${candidate.state}  ${candidate.url}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * @command mate artifact link <change>...
+ * @description Writes a change's Delivery Record (`delivery.yaml`), with `artifact archive`
+ * the only writer of that file, for active and archived changes. Records the delivery branch or a
+ * not-applicable reason per Working Repository, an informational PR URL, merge results
+ * from the forge (`--refresh`), or the user's answer (`--confirm-*`, source `user`).
+ * @flags
+ * - `--repository <org/repo>` — the delivery to edit; defaults to the Working Repository.
+ * - `--branch <branch>` — record the delivery branch; a protected branch needs `--direct`.
+ * - `--direct` — with `--branch`, record a direct delivery, settled only by the user's answer; required for a protected branch.
+ * - `--not-applicable <reason>` — no branch delivers this change in the repository.
+ * - `--pr <url>` — record the PR URL; with `--refresh`, picks that PR among several.
+ * - `--refresh` — ask the forge for the merge state of each recorded branch; a direct delivery
+ *   is reported as needing the user's answer.
+ * - `--confirm-merged` / `--confirm-open` / `--confirm-dropped` — the user's answer.
+ * - `--json` — emit an array of {@link LinkResult}, one per change.
+ * @remarks Warns, without blocking, about each `dependsOn` change that is neither archived nor
+ * fully implemented, since apply records the branch before writing code. Without an edit flag or `--refresh` it only reads the record and writes nothing.
+ * Network requests go only to the forge API: with `--refresh`, and with `--branch` for
+ * another repository's default branch. The forge token is never
+ * printed, logged, or written.
+ */
+export async function runArtifactLinkCommand(
+  argv: string[],
+  deps: LinkCommandDeps = {},
+): Promise<void> {
+  const { emitOut, emitErr, refuse } = commandOutput(deps);
+  const flags = parseFlags(argv, BOOLEAN_FLAGS);
+  const flagError = valueFlagError(flags, ["repository", "branch", "not-applicable", "pr"]);
+  if (flagError) return refuse(flagError);
+  const changes = positionalArgs(argv, BOOLEAN_FLAGS);
+  const branchFlags = branchFlagsFrom(flags);
+  const { branch, notApplicable } = branchFlags;
+  const pr = stringFlag(flags.pr);
+  const confirmations = Object.keys(CONFIRMATIONS).filter((flag) => flags[flag] === true);
+
+  if (changes.length === 0) return refuse("mate: artifact link requires a change name.");
+  if (branch !== undefined && notApplicable !== undefined) {
+    return refuse("mate: --branch and --not-applicable exclude each other.");
+  }
+  if (confirmations.length > 1) {
+    return refuse("mate: pass one of --confirm-merged, --confirm-open, or --confirm-dropped.");
+  }
+  if (branchFlags.direct && branch === undefined) return refuse(DIRECT_NEEDS_BRANCH);
+  if (pr !== undefined && !/^https?:\/\/\S+$/.test(pr)) {
+    return refuse("mate: --pr expects the PR's URL.");
+  }
+  const requested = repositoryFlag(flags);
+  if ("error" in requested) return refuse(requested.error);
+
+  const environment = await resolveDeliveryEnvironment(deps);
+  if ("error" in environment) return refuse(environment.error);
+  const repository = canonicalRepository(environment, requested.repository);
+  const confirm = confirmations.length === 1 ? CONFIRMATIONS[confirmations[0]] : undefined;
+  const delivery = deliveryEditFrom(branchFlags);
+  const outcome = await recordDelivery(
+    environment,
+    {
+      changes,
+      ...(repository ? { repository } : {}),
+      edit: {
+        ...(delivery ? { delivery } : {}),
+        ...(pr !== undefined ? { pr } : {}),
+        ...(confirm ? { confirm } : {}),
+      },
+      refresh: flags.refresh === true,
+      includeArchived: true,
+    },
+    deps,
+  );
+  if ("refusal" in outcome) return refuse(refusalMessage(outcome.refusal));
+  const results: LinkResult[] = [];
+  for (const result of "results" in outcome ? outcome.results : []) {
+    const warnings = await applyWarnings(environment.companionPath, result.change);
+    for (const warning of warnings) emitErr(`warning: ${warning.message}`);
+    for (const entry of result.settlement.unscoped) {
+      emitErr(unscopedDeliveryWarning(result.change, entry));
+    }
+    results.push({ ...result, warnings });
+  }
+  if (flags.json === true) emitOut(JSON.stringify(results));
+  else for (const result of results) for (const line of renderHuman(result)) emitOut(line);
+}

package/src/cli/commands/artifact/delivery/output.ts

@@ -0,0 +1,58 @@
+import type { Delivery, UnscopedDelivery } from "../../../../lib/delivery/record";
+import type { DeliveryRefusal } from "../../../../lib/delivery/record-delivery";
+
+export interface CommandOutput {
+  emitOut: (line: string) => void;
+  emitErr: (line: string) => void;
+  /** Writes `message`, when given, to stderr and sets a failing exit code. */
+  refuse: (message?: string | null) => void;
+}
+
+export function commandOutput(deps: {
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}): CommandOutput {
+  const emitOut = deps.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const emitErr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  return {
+    emitOut,
+    emitErr,
+    refuse: (message) => {
+      if (message) emitErr(message);
+      process.exitCode = 1;
+    },
+  };
+}
+
+/** One delivery as `<repository>  <branch or reason>  <merge>  <pr>`. */
+export function renderDelivery(delivery: Delivery): string {
+  if (delivery.notApplicable !== undefined) {
+    return `  ${delivery.repository}  not applicable: ${delivery.notApplicable}`;
+  }
+  const branch = `${delivery.branch ?? "?"}${delivery.direct ? " [direct]" : ""}`;
+  const merge = delivery.merge
+    ? `${delivery.merge.state} (${delivery.merge.source})`
+    : "no merge recorded";
+  const pr = delivery.pr ? `  ${delivery.pr}` : "";
+  return `  ${delivery.repository}  ${branch}  ${merge}${pr}`;
+}
+
+/** Wording for the refusals `link` and `archive` share; `unknown-change` names each command. */
+export function sharedRefusalMessage(
+  refusal: Exclude<DeliveryRefusal, { reason: "unknown-change" }>,
+): string {
+  if (refusal.reason === "no-repository") {
+    return "mate: the Working Repository has no origin remote to identify it; pass --repository <org/repo>.";
+  }
+  if (refusal.reason === "protected-branch") {
+    return `mate: ${refusal.branch} is a protected branch (${refusal.protection}); record it only as an explicit direct delivery with --direct.`;
+  }
+  return refusal.for === "pr"
+    ? `mate: ${refusal.change} has no delivery branch for ${refusal.repository}; pass --branch first.`
+    : `mate: ${refusal.change} has no delivery branch for ${refusal.repository} to confirm.`;
+}
+
+export function unscopedDeliveryWarning(change: string, entry: UnscopedDelivery): string {
+  const hint = entry.closest ? `; did you mean ${entry.closest}?` : ".";
+  return `warning: ${entry.repository} matches none of ${change}'s scopes${hint}`;
+}

package/src/cli/commands/artifact/finish/command.ts

@@ -8,8 +8,14 @@ import { discoverArchives, pendingArchives } from "../pending/discovery";
 import { type FinishResult, runFinishEngine } from "./engine";
 import type { ArtifactFinisher, FinishContext, FinisherFactory } from "./finisher";
 import { defaultGitOps, type GitOps } from "./git";
-import { openspecSpecsFinisher, resolveDriftedSpecs } from "./openspec";
+import {
+  openspecSpecsFinisher,
+  publicationHold,
+  publicationHoldCache,
+  resolveDriftedSpecs,
+} from "./openspec";
 import { DEFAULT_FINISHER_TYPE, knownFinisherTypes, selectFinisher } from "./registry";
+import { type PublicationSecretScan, scanPublication } from "./secret-scan";
 
 export interface PublishCommandDeps {
   ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
@@ -21,6 +27,11 @@ export interface PublishCommandDeps {
   now?: () => Date;
   /** Injectable spec-publication finisher; mirrors `selectFinisher` for the other unit. */
   specsFinisher?: (context: FinishContext, paths: string[], now: () => Date) => ArtifactFinisher;
+  /** Injectable pre-commit secret scan over a publication's staged outputs. */
+  scanPublication?: (
+    companionPath: string,
+    commitPaths: string[],
+  ) => Promise<PublicationSecretScan>;
   stdout?: (line: string) => void;
   stderr?: (line: string) => void;
 }
@@ -99,7 +110,8 @@ function refusalResult(type: string, name: string, message: string): FinishResul
  *   new `openspec/specs/<date>-<specs>` tag. Bare, it publishes every drifted spec; with paths, only
  *   those. A bare name alongside it is a change target and is refused.
  * - `--all` — publish every pending change in discovery order, then one spec publication for
- *   the drift that remains. Halts at the first conflict or error; with `--json` it emits a
+ *   the drift that remains. Skips an archive the merge gate holds back, reporting why, and
+ *   halts at the first conflict or error; with `--json` it emits a
  *   single array of results in execution order.
  * - `--type <type>` — finisher type to use; see `knownFinisherTypes()`. `--specs` and
  *   `--all` are openspec-only.
@@ -188,10 +200,14 @@ export async function runArtifactPublishCommand(
   const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
   const capabilities = await loadCapabilities(context);
 
+  let git: GitOps;
   const finishContext: FinishContext = {
     companionPath: context.companionPath,
     repositoryId: context.repositoryId,
     repository: context.repository,
+    // Resolution runs only after `git` is set below.
+    changedPaths: () => git.changedPaths(),
+    holdCache: publicationHoldCache(),
   };
   const finisher = finisherFactory(finishContext);
   if (!finisher.isEnabled(capabilities)) {
@@ -200,7 +216,6 @@ export async function runArtifactPublishCommand(
     return;
   }
 
-  let git: GitOps;
   try {
     git = (deps.git ?? defaultGitOps)(
       context.companionPath,
@@ -220,11 +235,13 @@ export async function runArtifactPublishCommand(
    * suppressed; every other mode lets the engine report each publication as it finishes.
    */
   const quiet = allMode && json;
+  const scanPublicationFn = deps.scanPublication ?? scanPublication;
   const engineDeps = {
     git,
     json: !allMode && json,
     stdout: quiet ? (): void => {} : emitOut,
     stderr: quiet ? (): void => {} : emitErr,
+    secretScan: (commitPaths: string[]) => scanPublicationFn(context.companionPath, commitPaths),
   };
 
   const runChange = (target: string): Promise<FinishResult> =>
@@ -253,6 +270,19 @@ export async function runArtifactPublishCommand(
     const archives = await discoverArchives(context.companionPath, changed, changeKinds);
 
     for (const entry of pendingArchives(archives)) {
+      // A held-back archive waits for its merge; it does not stop the merged ones.
+      // Same cache as the finisher's resolve step, so both see one pending set and agree.
+      const hold = await publicationHold(
+        context.companionPath,
+        entry.anchor,
+        async () => changed,
+        finishContext.holdCache,
+      );
+      if (hold) {
+        if (!quiet) emitErr(hold);
+        results.push(nothingToPublish(entry.anchor, hold));
+        continue;
+      }
       const result = await runChange(entry.anchor);
       results.push(result);
       if (halted(result)) {

package/src/cli/commands/artifact/finish/engine.ts

@@ -1,11 +1,14 @@
+import { describeSecretFindings, type SecretFinding } from "../../../../runtime/secret-scan";
 import type { ArtifactFinisher, Produced } from "./finisher";
 import type { GitOps } from "./git";
+import type { PublicationSecretScan } from "./secret-scan";
 
 /** Pipeline step a {@link FinishResult} refers to (generic across artifact kinds). */
 export type FinishStep =
   | "resolve"
   | "branch-guard"
   | "cap-sync"
+  | "secret-scan"
   | "commit"
   | "sync-remote"
   | "tag"
@@ -31,6 +34,10 @@ export interface FinishResult {
   conflictedPaths: string[];
   local: { committed: boolean; tagged: boolean; pushed: boolean };
   message: string;
+  /** Set when the secret scan stopped the publication: where and which rule, never the value. */
+  secretFindings?: SecretFinding[];
+  /** The finisher's warning about what it resolved; publication continued. */
+  warning?: string;
 }
 
 export interface EngineOptions {
@@ -43,13 +50,15 @@ export interface EngineDeps {
   json: boolean;
   stdout: (line: string) => void;
   stderr: (line: string) => void;
+  /** Scans the staged outputs for secrets; absent means no scan step. */
+  secretScan?: (commitPaths: string[]) => Promise<PublicationSecretScan>;
 }
 
 /**
  * Runs the fixed publication pipeline for a resolved {@link ArtifactFinisher}:
- * resolve → branch guard → cap sync → scoped commit → sync-remote → tag → push. The
- * git, remote-sync, and conflict-handoff machinery is identical for every artifact
- * kind — only the finisher's resolution and cap sync vary.
+ * resolve → branch guard → cap sync → secret scan → scoped commit → sync-remote → tag →
+ * push. The git, remote-sync, and conflict-handoff machinery is identical for every
+ * artifact kind — only the finisher's resolution and cap sync vary.
  *
  * Isolation is a clean abort, not a rollback: the resolved artifact is durable input
  * the pipeline never produced, so no step resets, restores, or deletes a path.
@@ -111,6 +120,10 @@ export async function runFinishEngine(
   }
   const resolved: Produced = resolution.resolved;
   result.anchorName = resolved.anchorName;
+  if (resolved.warning) {
+    result.warning = resolved.warning;
+    if (!deps.json) deps.stderr(`warning: ${resolved.warning}`);
+  }
   const baseTag = `${resolved.tagNamespace ?? finisher.type}/${resolved.anchorName}`;
   // Provisional: a `suffix` publication only learns its final name at the tag
   // step, once the remote sync has revealed tags created elsewhere. Early exits
@@ -151,6 +164,37 @@ export async function runFinishEngine(
     }
   }
 
+  // Secret scan — the last pre-commit step, over exactly what the commit would stage.
+  // A finding or a scanner failure stops here like any pre-commit failure: no commit,
+  // no tag, no push, and the archive stays on disk.
+  if (deps.secretScan) {
+    result.step = "secret-scan";
+    let scan: PublicationSecretScan;
+    try {
+      scan = await deps.secretScan(resolved.commitPaths);
+    } catch (err) {
+      fail(
+        "secret-scan",
+        `mate: the secret scan failed (${String(err)}); nothing was committed — re-run \`mate artifact publish\` to retry.`,
+      );
+      return result;
+    }
+    if (scan.skipped) {
+      deps.stderr("mate: secret scan skipped (secrets.guardrails is false in framework.yaml).");
+    } else if (scan.findings.length > 0) {
+      result.secretFindings = scan.findings;
+      fail(
+        "secret-scan",
+        [
+          "mate: refusing to publish: the staged outputs contain secrets. Nothing was committed; the archive was left in place.",
+          ...describeSecretFindings(scan.findings).map((line) => ` ${line}`),
+          "Replace each value with a placeholder or variable name, then re-run `mate artifact publish`.",
+        ].join("\n"),
+      );
+      return result;
+    }
+  }
+
   // Commit — stage only the finisher's scoped paths. Nothing to stage means a prior
   // publication already committed this anchor, which is a resume rather than an error.
   result.step = "commit";

package/src/cli/commands/artifact/finish/finisher.ts

@@ -1,9 +1,17 @@
 import type { CapabilityConfig, LinkedRepository } from "../../../../lib/orchestrator/types";
+import type { PublicationHoldCache } from "./openspec";
 
 export interface FinishContext {
   companionPath: string;
   repositoryId: string;
   repository?: LinkedRepository;
+  /**
+   * The companion's uncommitted paths (porcelain). Without it, publication cannot tell
+   * which other archives are pending and skips the shared-spec check.
+   */
+  changedPaths?: () => Promise<string[]>;
+  /** Shared by every publication of one run; a fresh memo per call without it. */
+  holdCache?: PublicationHoldCache;
 }
 
 /**
@@ -26,6 +34,8 @@ export interface Produced {
    * run reuses under either value: its commit is the tagged one already.
    */
   tagCollision?: "reuse" | "suffix";
+  /** Published anyway, but reported: e.g. a legacy archive whose merge was not checked. */
+  warning?: string;
 }
 
 /** Outcome of {@link ArtifactFinisher.resolve}; the failure carries the user-facing refusal. */