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

package/claude-plugin/hooks/companion-instructions.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Thin shim for src/hooks/companion-instructions.ts, loaded through ts-loader.mjs: the
+ * installed plugin sits inside node_modules, where node's native type stripping is off.
+ */
+import "./ts-loader.mjs";
+
+const { run } = await import("../../src/hooks/companion-instructions.ts");
+process.exitCode = await run();

package/claude-plugin/hooks/hooks.json

@@ -1,9 +1,9 @@
 {
-  "description": "Mate hooks \u2014 PreToolUse artifact-path guardrail, SessionStart banner, companion guidance and session prepare",
+  "description": "Mate hooks \u2014 PreToolUse artifact-path and secret guardrail, SessionStart banner, companion guidance, session prepare then companion instructions, SubagentStart companion instructions",
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit|Bash",
+        "matcher": "Read|Grep|Write|Edit|MultiEdit|NotebookEdit|Bash",
         "hooks": [
           {
             "type": "command",
@@ -38,6 +38,16 @@
           }
         ]
       }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/companion-instructions.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.5",
+  "version": "1.0.0-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,8 @@
     "./runtime": "./src/runtime/index.ts",
     "./opencode": "./src/opencode/index.ts",
     "./opencode/tui": "./src/opencode/tui.tsx",
-    "./tui": "./src/tui.ts"
+    "./tui": "./src/tui.ts",
+    "./brand": "./src/brand/index.ts"
   },
   "publishConfig": {
     "access": "public",
@@ -32,6 +33,8 @@
   },
   "scripts": {
     "test": "CI=1 bun ../../test/run-isolated.ts",
+    "test:unit": "CI=1 bun ../../test/run-isolated.ts --suite=unit",
+    "test:integration": "CI=1 bun ../../test/run-isolated.ts --suite=integration",
     "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/ opencode-plugin/",
     "lint:fix": "oxlint src/ opencode-plugin/ --fix",
@@ -39,10 +42,14 @@
     "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" --check"
   },
   "dependencies": {
+    "@fission-ai/openspec": "1.15.0",
     "@opencode/plugin": "^2.0.23",
     "@opentui/core": "^0.5.14",
     "@opentui/keymap": "^0.5.14",
     "@opentui/solid": "^0.5.14",
+    "@secretlint/core": "13.0.7",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.7",
+    "@secretlint/types": "13.0.7",
     "@tanstack/highlight": "0.0.10",
     "@xterm/addon-clipboard": "^0.2.0",
     "@xterm/addon-fit": "^0.11.0",
@@ -51,6 +58,7 @@
     "@xterm/xterm": "^6.0.0",
     "hono": "^4.13.5",
     "ink": "^7.1.0",
+    "marked": "^18.1.1",
     "react": "^19.2.7",
     "react-doctor": "0.9.13",
     "semver": "^7.8.5",

package/src/brand/art.generated.ts

@@ -0,0 +1,69 @@
+// Generated by scripts/brand/generate.ts from assets/logo-kit. Do not edit.
+import type { LogoArt, LogoForm } from "./types";
+
+export const LOGO_ART: Record<LogoForm, LogoArt> = {
+  lockup: {
+    block: [
+      [{"kind":"pane","text":"▄███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"                          "},{"kind":"word","text":"▄▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▄▄▄▄▄"},{"kind":"space","text":"                          "},{"kind":"word","text":"██"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"    "},{"kind":"word","text":"▄█▀▀██▀▀█▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀██"},{"kind":"space","text":"   "},{"kind":"word","text":"▀██▀▀"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀█▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▀▀▀▀▀"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██▄▄██"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"}],
+      [{"kind":"pane","text":"▀███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▀"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄██▄"},{"kind":"space","text":"   "},{"kind":"word","text":"▀█▄▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄▄▄"}],
+    ],
+    ascii: [
+      " ####### ####",
+      "######## #####                          ##",
+      "########                                ##",
+      "######## #####     ########    #####   #####   #####",
+      "######## #####    ##  ##  ##  ##  ##    ##    ##   ##",
+      "########          ##  ##  ##  ##  ##    ##    #######",
+      "######## #####    ##  ##  ##  ##  ##    ##    ##",
+      " ####### ####     ##  ##  ##   ######    ###   ######",
+    ],
+    columns: 52,
+  },
+  symbol: {
+    block: [
+      [{"kind":"pane","text":"▄███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▄▄▄▄▄"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"▀▀▀▀▀"}],
+      [{"kind":"pane","text":"████████"},{"kind":"space","text":" "},{"kind":"note","text":"█████"}],
+      [{"kind":"pane","text":"▀███████"},{"kind":"space","text":" "},{"kind":"note","text":"████▀"}],
+    ],
+    ascii: [
+      " ####### ####",
+      "######## #####",
+      "########",
+      "######## #####",
+      "######## #####",
+      "########",
+      "######## #####",
+      " ####### ####",
+    ],
+    columns: 14,
+  },
+  wordmark: {
+    block: [
+      [{"kind":"space","text":"                      "},{"kind":"word","text":"▄▄"}],
+      [{"kind":"space","text":"                      "},{"kind":"word","text":"██"}],
+      [{"kind":"word","text":"▄█▀▀██▀▀█▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀██"},{"kind":"space","text":"   "},{"kind":"word","text":"▀██▀▀"},{"kind":"space","text":"  "},{"kind":"word","text":"▄█▀▀█▄"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██▄▄██"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"},{"kind":"space","text":"    "},{"kind":"word","text":"██"}],
+      [{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"██"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄██▄"},{"kind":"space","text":"   "},{"kind":"word","text":"▀█▄▄"},{"kind":"space","text":"  "},{"kind":"word","text":"▀█▄▄▄▄"}],
+    ],
+    ascii: [
+      "                      ##",
+      "                      ##",
+      " ########    #####   #####   #####",
+      "##  ##  ##  ##  ##    ##    ##   ##",
+      "##  ##  ##  ##  ##    ##    #######",
+      "##  ##  ##  ##  ##    ##    ##",
+      "##  ##  ##   ######    ###   ######",
+    ],
+    columns: 34,
+  },
+};

package/src/brand/index.ts

@@ -0,0 +1,12 @@
+export { LOGO_ART } from "./art.generated";
+export { BRAND_ACCENT, BRAND_COLORS, type BrandColor, type BrandColorName } from "./palette";
+export { BRAND_SVGS } from "./svg.generated";
+export {
+  LOGO_WORD,
+  chooseLogo,
+  colorEnabled,
+  renderLogo,
+  type LogoChoice,
+  type LogoOptions,
+} from "./terminal";
+export type { BrandSvgs, LogoArt, LogoForm, LogoRow, LogoSegment, LogoSegmentKind } from "./types";

package/src/brand/palette.ts

@@ -0,0 +1,19 @@
+/** A brand colour as a 24-bit hex value plus its nearest xterm 256-colour index. */
+export interface BrandColor {
+  hex: string;
+  ansi256: number;
+}
+
+/** The five colours of the Mate identity, as defined in `assets/logo-kit/BRAND.md`. */
+export const BRAND_COLORS = {
+  ink: { hex: "#1F2421", ansi256: 235 },
+  mateGreen: { hex: "#2E7D5B", ansi256: 29 },
+  cream: { hex: "#F4F0E8", ansi256: 255 },
+  lightGreen: { hex: "#7FD0A6", ansi256: 115 },
+  night: { hex: "#15191A", ansi256: 234 },
+} as const satisfies Record<string, BrandColor>;
+
+export type BrandColorName = keyof typeof BRAND_COLORS;
+
+/** The accent used on surfaces whose background is unknown; it reads on both light and dark. */
+export const BRAND_ACCENT = BRAND_COLORS.mateGreen.hex;

package/src/brand/svg.generated.ts

@@ -0,0 +1,8 @@
+// Generated by scripts/brand/generate.ts from assets/logo-kit. Do not edit.
+import type { BrandSvgs } from "./types";
+
+export const BRAND_SVGS: BrandSvgs = {
+  symbolColor: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><g id=\"symbol\"><path fill=\"#1F2421\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#2E7D5B\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+  symbolOnDark: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><g id=\"symbol\"><path fill=\"#F4F0E8\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#7FD0A6\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+  favicon: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 256 256\" width=\"256\" height=\"256\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">mate logo</title><rect width=\"256\" height=\"256\" rx=\"48\" fill=\"#1F2421\"/><g id=\"symbol\" transform=\"translate(32 32) scale(0.75)\"><path fill=\"#F4F0E8\" d=\"M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z\"/><path fill=\"#7FD0A6\" d=\"M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z\"/></g></svg>",
+};

package/src/brand/terminal.ts

@@ -0,0 +1,83 @@
+import { LOGO_ART } from "./art.generated";
+import { BRAND_COLORS } from "./palette";
+import type { LogoForm, LogoRow } from "./types";
+
+export interface LogoOptions {
+  /** The largest form wanted; it falls back to smaller forms when it does not fit. */
+  form: LogoForm;
+  /** Columns available on the target stream. */
+  columns: number;
+  isTTY: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export type LogoChoice =
+  | { kind: "block"; form: LogoForm; rows: readonly LogoRow[]; color: boolean }
+  | { kind: "ascii"; form: LogoForm; rows: readonly string[] }
+  | { kind: "word" };
+
+/** The word that stands in for the logo when no art fits. */
+export const LOGO_WORD = "mate";
+
+const FALLBACKS: Record<LogoForm, readonly LogoForm[]> = {
+  lockup: ["lockup", "symbol"],
+  symbol: ["symbol"],
+  wordmark: ["wordmark"],
+};
+
+function asciiWidth(rows: readonly string[]): number {
+  return Math.max(...rows.map((row) => row.length));
+}
+
+/** Whether colour is allowed, following https://no-color.org: any non-empty NO_COLOR disables it. */
+export function colorEnabled(
+  isTTY: boolean,
+  env: Record<string, string | undefined> = {},
+): boolean {
+  return isTTY && !env.NO_COLOR;
+}
+
+/**
+ * Picks the logo encoding for a stream: block art on a TTY (coloured unless NO_COLOR is set),
+ * ASCII otherwise, falling back from the lockup to the symbol to the word `mate` as width runs
+ * out.
+ */
+export function chooseLogo({ form, columns, isTTY, env = {} }: LogoOptions): LogoChoice {
+  for (const candidate of FALLBACKS[form]) {
+    const art = LOGO_ART[candidate];
+    if (!isTTY) {
+      if (asciiWidth(art.ascii) <= columns)
+        return { kind: "ascii", form: candidate, rows: art.ascii };
+    } else if (art.columns <= columns) {
+      return { kind: "block", form: candidate, rows: art.block, color: colorEnabled(isTTY, env) };
+    }
+  }
+  return { kind: "word" };
+}
+
+function hexToRgb(hex: string): string {
+  const value = Number.parseInt(hex.slice(1), 16);
+  return `${(value >> 16) & 255};${(value >> 8) & 255};${value & 255}`;
+}
+
+const NOTE_ON = `\x1b[38;2;${hexToRgb(BRAND_COLORS.mateGreen.hex)}m`;
+const NOTE_OFF = "\x1b[39m";
+
+/** Renders the logo as a string ready to write to a stream, rows separated by newlines. */
+export function renderLogo(options: LogoOptions): string {
+  const choice = chooseLogo(options);
+  if (choice.kind === "word") return LOGO_WORD;
+  if (choice.kind === "ascii") return choice.rows.join("\n");
+
+  return choice.rows
+    .map((row) =>
+      row
+        .map((segment) =>
+          choice.color && segment.kind === "note"
+            ? `${NOTE_ON}${segment.text}${NOTE_OFF}`
+            : segment.text,
+        )
+        .join(""),
+    )
+    .join("\n");
+}

package/src/brand/types.ts

@@ -0,0 +1,33 @@
+/**
+ * What a run of logo cells belongs to. Notes are the three bars of the right pane and the
+ * only cells coloured on an unknown background; panes and the wordmark keep the default
+ * foreground.
+ */
+export type LogoSegmentKind = "pane" | "note" | "word";
+
+/** A run of adjacent cells that share a kind. Spaces between runs are their own segments. */
+export interface LogoSegment {
+  kind: LogoSegmentKind | "space";
+  text: string;
+}
+
+export type LogoRow = readonly LogoSegment[];
+
+/** One logo form in every terminal encoding the kit provides. */
+export interface LogoArt {
+  /** Unicode half-block art, one entry per row. */
+  readonly block: readonly LogoRow[];
+  /** 7-bit ASCII art for streams that are not a TTY. */
+  readonly ascii: readonly string[];
+  /** Width in columns of the block art. */
+  readonly columns: number;
+}
+
+export type LogoForm = "lockup" | "symbol" | "wordmark";
+
+/** The SVG markup a web surface embeds, generated verbatim from the kit. */
+export interface BrandSvgs {
+  readonly symbolColor: string;
+  readonly symbolOnDark: string;
+  readonly favicon: string;
+}

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

@@ -1,4 +1,6 @@
 import { usage } from "../../usage";
+import { runArtifactArchiveCommand } from "./delivery/archive";
+import { runArtifactLinkCommand } from "./delivery/link";
 import { runArtifactPublishCommand } from "./finish";
 import { runArtifactPendingCommand } from "./pending";
 
@@ -30,6 +32,12 @@ export async function runArtifactCommand(
     case "pending":
       await runArtifactPendingCommand(argv);
       return;
+    case "link":
+      await runArtifactLinkCommand(argv);
+      return;
+    case "archive":
+      await runArtifactArchiveCommand(argv);
+      return;
     default:
       console.error(`Unknown artifact command: ${subcommand ?? ""}`);
       console.error(usage());

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

@@ -0,0 +1,117 @@
+import {
+  archiveChange,
+  type ArchiveChangeDeps,
+  type ArchiveResult,
+} from "../../../../lib/delivery/archive-change";
+import type { DeliveryRefusal } from "../../../../lib/delivery/record-delivery";
+import { type BooleanFlagSet, parseFlags, positionalArgs } 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 ArchiveCommandDeps
+  extends DeliveryEnvironmentDeps, Omit<ArchiveChangeDeps, "onWarnings"> {
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+const BOOLEAN_FLAGS: BooleanFlagSet = new Set(["json", "direct", "skip-branch"]);
+
+function refusalMessage(refusal: DeliveryRefusal): string {
+  if (refusal.reason === "unknown-change") {
+    return `mate: no active change named "${refusal.change}" to archive.`;
+  }
+  return sharedRefusalMessage(refusal);
+}
+
+/** Warnings are not repeated here: they go to stderr before anything is archived. */
+function renderHuman(result: ArchiveResult): string[] {
+  return [
+    result.message,
+    ...result.record.deliveries.map(renderDelivery),
+    `  delivery: ${result.settlement.status}`,
+  ];
+}
+
+/**
+ * @command mate artifact archive <change>
+ * @description Archives an active change whether or not its delivery is merged, so a
+ * feature's later changes build on its canonical specs. Writes overlap, dependency, and
+ * incomplete-planning warnings to stderr before archiving, refreshes merge state from the forge when a token
+ * is available, always leaves a `delivery.yaml` (unlinked when none was recorded), then
+ * runs `openspec archive` with the bundled CLI. Merge state is reported, never a refusal.
+ * @flags
+ * - `--repository <org/repo>` — the delivery `--branch` or `--not-applicable` records; defaults
+ *   to the Working Repository.
+ * - `--branch <branch>` / `--direct` — record the delivery branch first, as `artifact link`.
+ * - `--not-applicable <reason>` — record that no branch delivers this change.
+ * - `--skip-branch` — archive with an unlinked record when the user skips the question.
+ * - `--json` — emit an {@link ArchiveResult}.
+ * @remarks Without a recorded delivery and none of the branch flags, nothing is archived:
+ * the result is `needs-branch`, a question rather than a refusal (exit 0), with
+ * `change/<change-name>` suggested when that branch exists, so the caller can ask the user.
+ */
+export async function runArtifactArchiveCommand(
+  argv: string[],
+  deps: ArchiveCommandDeps = {},
+): Promise<void> {
+  const { emitOut, emitErr, refuse } = commandOutput(deps);
+  const flags = parseFlags(argv, BOOLEAN_FLAGS);
+  const flagError = valueFlagError(flags, ["repository", "branch", "not-applicable"]);
+  if (flagError) return refuse(flagError);
+  const json = flags.json === true;
+  const [change] = positionalArgs(argv, BOOLEAN_FLAGS);
+  const branchFlags = branchFlagsFrom(flags);
+  const { branch, notApplicable } = branchFlags;
+  const skip = flags["skip-branch"] === true;
+
+  if (!change) return refuse("mate: artifact archive requires a change name.");
+  if ([branch !== undefined, notApplicable !== undefined, skip].filter(Boolean).length > 1) {
+    return refuse("mate: pass only one of --branch, --not-applicable, or --skip-branch.");
+  }
+  if (branchFlags.direct && branch === undefined) return refuse(DIRECT_NEEDS_BRANCH);
+  const requested = repositoryFlag(flags);
+  if ("error" in requested) return refuse(requested.error);
+  if (requested.repository !== undefined && branch === undefined && notApplicable === undefined) {
+    return refuse("mate: --repository names the delivery --branch or --not-applicable records.");
+  }
+
+  const environment = await resolveDeliveryEnvironment(deps);
+  if ("error" in environment) return refuse(environment.error);
+  const repository = canonicalRepository(environment, requested.repository);
+  const delivery = deliveryEditFrom(branchFlags);
+  const outcome = await archiveChange(
+    environment,
+    {
+      change,
+      ...(repository ? { repository } : {}),
+      ...(delivery ? { delivery } : {}),
+      skipBranch: skip,
+    },
+    {
+      ...deps,
+      onWarnings: (warnings, unscoped) => {
+        for (const warning of warnings) emitErr(`warning: ${warning.message}`);
+        for (const entry of unscoped) emitErr(unscopedDeliveryWarning(change, entry));
+      },
+    },
+  );
+  if ("refusal" in outcome) return refuse(refusalMessage(outcome.refusal));
+
+  const { result } = outcome;
+  if (result.status === "failed") process.exitCode = 1;
+  if (json) emitOut(JSON.stringify(result));
+  else for (const line of renderHuman(result)) emitOut(line);
+}

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,
+  };
+}