@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

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

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -6,34 +5,38 @@ import { parse } from "yaml";
 
 import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
 import { runIndexCapCommand } from "../../cap/index-cmd";
-import type { ArtifactFinisher, FinishContext } from "./finisher";
-
-function run(
-  companionPath: string,
-  args: string[],
-): { status: number; stdout: string; stderr: string } {
-  const result = spawnSync(args[0], args.slice(1), {
-    cwd: companionPath,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  return {
-    status: result.status ?? 1,
-    stdout: result.stdout ?? "",
-    stderr: result.stderr ?? "",
-  };
-}
+import { discoverArchives, SPECS_RELATIVE_DIR, unattributedSpecs } from "../pending/discovery";
+import type { ArtifactFinisher, FinishContext, Produced, ResolveResult } from "./finisher";
+import type { GitOps } from "./git";
 
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+async function pathExists(candidate: string): Promise<boolean> {
+  try {
+    await fs.stat(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** A dated archive anchor; group 1 is the change name the archive was created from. */
+const ANCHOR_PATTERN = /^(\d{4}-\d{2}-\d{2})-(.+)$/;
+
+/**
+ * The publication commit's exact scope. The active-change path is included only when it
+ * is gone from disk — that absence IS the deletion archiving produced. A path that still
+ * exists belongs to a same-name change started after archiving, which is unrelated work.
+ */
 async function commitPathsForArchive(
   companionPath: string,
   name: string,
   anchorName: string,
 ): Promise<string[]> {
   const archiveRelative = path.posix.join("openspec", "changes", "archive", anchorName);
+  const activeRelative = path.posix.join("openspec", "changes", name);
   const deltaSpecsDir = path.join(companionPath, archiveRelative, "specs");
   const canonicalSpecs: string[] = [];
   const collectDeltaSpecFiles = async (directory: string, relative = ""): Promise<void> => {
@@ -53,7 +56,7 @@ async function commitPathsForArchive(
     // Changes without delta specs still commit their active deletion and archive.
   }
   return [
-    path.posix.join("openspec", "changes", name),
+    ...((await pathExists(path.join(companionPath, activeRelative))) ? [] : [activeRelative]),
     archiveRelative,
     ...canonicalSpecs.toSorted(),
   ];
@@ -108,7 +111,7 @@ function projectDeltaScopes(scopes: ScopePair[]): ProjectionResult {
   };
 }
 
-async function archivedChangeUsesMateV1(
+async function archivedChangeUsesMateSchema(
   companionPath: string,
   anchorName: string,
 ): Promise<boolean> {
@@ -124,7 +127,7 @@ async function archivedChangeUsesMateV1(
     const parsed = parse(await fs.readFile(metadataPath, "utf8")) as unknown;
     if (!parsed || typeof parsed !== "object") return false;
     const schema = (parsed as Record<string, unknown>).schema;
-    return typeof schema === "string" && schema.trim() === "mate-v1";
+    return typeof schema === "string" && ["mate-v1", "mate-minimal"].includes(schema.trim());
   } catch {
     return false;
   }
@@ -148,18 +151,20 @@ function renderCanonicalFrontmatter(
 }
 
 /**
- * Prepends canonical frontmatter to main specs born during this archive.
+ * Repairs `openspec archive` output: prepends canonical frontmatter to main specs the
+ * archive run created bare. Publish does not archive, so this runs the first time publish
+ * resolves that archive, however the archive was made.
  *
  * `openspec archive` rebuilds a brand-new main spec from a skeleton with no frontmatter slot,
  * so scope metadata dies exactly once, at spec birth; existing specs keep theirs because only
- * requirement blocks are spliced. Best-effort by design — the archive already succeeded, so a
- * failure here warns rather than stranding the change archived-but-unfinished.
+ * requirement blocks are spliced. Idempotent, and best-effort by design — the archive is
+ * durable input, so a failure here warns rather than refusing the publication.
  */
 async function reconcileMainSpecFrontmatter(
   companionPath: string,
   anchorName: string,
 ): Promise<string[]> {
-  if (!(await archivedChangeUsesMateV1(companionPath, anchorName))) return [];
+  if (!(await archivedChangeUsesMateSchema(companionPath, anchorName))) return [];
 
   const deltaSpecsDir = path.join(
     companionPath,
@@ -253,16 +258,171 @@ async function capSync(context: FinishContext): Promise<boolean> {
   }
 }
 
+async function resolved(
+  companionPath: string,
+  name: string,
+  anchorName: string,
+): Promise<ResolveResult> {
+  const commitPaths = await commitPathsForArchive(companionPath, name, anchorName);
+  await reconcileMainSpecFrontmatter(companionPath, anchorName);
+  return { ok: true, resolved: { anchorName, commitPaths } };
+}
+
+/** Tag namespace segregating spec publications from dated change anchors. */
+export const SPEC_TAG_NAMESPACE = "openspec/specs";
+/** Spec ids named individually before the remainder collapses into a count. */
+const SPEC_LABEL_LIMIT = 3;
+
+/** `openspec/specs/<id>/...` -> `<id>`: the capability directory is the spec's identity. */
+function specId(candidate: string): string {
+  return candidate.slice(`${SPECS_RELATIVE_DIR}/`.length).split("/")[0];
+}
+
+/** Unique ids in path order, so anchor and subject always name the same specs. */
+function specIds(paths: string[]): string[] {
+  return [...new Set(paths.map(specId))];
+}
+
 /**
- * The openspec artifact finisher: validate/complete guards over the change, `openspec
- * archive` as the terminal transform, an openspec-scoped cap sync, and a commit scoped
- * to `openspec/`. Resumable detection reads the dated `openspec/changes/archive/` folder
- * openspec actually created so the tag is never a computed date.
+ * The spec ids a publication ships, as `<a>+<b>+<c>+<n>-more`. A dated anchor alone
+ * says when a publication ran but never what it shipped; naming the specs makes the tag
+ * readable without checking out its commit, and the cap keeps a wide sync from growing
+ * an unbounded ref name. Empty for an empty publication, which then anchors on its date.
  */
-export function openspecFinisher(
+function specLabel(paths: string[]): string {
+  const ids = specIds(paths);
+  const named = ids.slice(0, SPEC_LABEL_LIMIT);
+  const remaining = ids.length - named.length;
+  return [...named, ...(remaining > 0 ? [`${remaining}-more`] : [])].join("+");
+}
+
+/** Commit subject for a spec publication; it belongs to no change, so it names specs, never an anchor. */
+export function specCommitSubject(paths: string[]): string {
+  const ids = specIds(paths);
+  const named = ids.slice(0, SPEC_LABEL_LIMIT);
+  const remaining = ids.length - named.length;
+  if (named.length === 0) return "chore(openspec): sync canonical specs";
+  const listed = remaining > 0 ? `${named.join(", ")} and ${remaining} more` : named.join(", ");
+  return `chore(openspec): sync canonical specs (${listed})`;
+}
+
+/** Working-tree reads a spec publication needs; nothing here mutates the repository. */
+export type SpecDriftGit = Pick<GitOps, "changedPaths" | "changedPathKinds">;
+
+export type DriftResolution = { ok: true; paths: string[] } | { ok: false; message: string };
+
+function pad2(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+/** Local calendar date as `YYYY-MM-DD`. */
+function calendarDate(now: Date): string {
+  return `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`;
+}
+
+function withoutTrailingSlash(candidate: string): string {
+  return candidate.endsWith("/") ? candidate.slice(0, -1) : candidate;
+}
+
+/**
+ * Canonical specs that drifted: uncommitted under `openspec/specs/` and claimed by no
+ * pending change. Delegates to the same discovery `mate artifact pending` reports from,
+ * so the two commands can never disagree about what is drifted. Only paths and
+ * working-tree status are read — never spec or archived file content.
+ *
+ * `requested` narrows the set rather than being trusted: a path that is not drifted, or
+ * sits outside the canonical spec tree, refuses the whole invocation instead of
+ * publishing a surprising subset.
+ */
+export async function resolveDriftedSpecs(
+  companionPath: string,
+  git: SpecDriftGit,
+  requested: string[] = [],
+): Promise<DriftResolution> {
+  const changed = await git.changedPaths();
+  const changeKinds = (await git.changedPathKinds?.()) ?? {};
+  const archives = await discoverArchives(companionPath, changed, changeKinds);
+  const drifted = (await unattributedSpecs(companionPath, changed, archives, changeKinds)).map(
+    (spec) => spec.path,
+  );
+
+  if (requested.length === 0) return { ok: true, paths: drifted };
+
+  const normalized = requested.map(withoutTrailingSlash);
+  const outside = normalized.filter((candidate) => !candidate.startsWith(`${SPECS_RELATIVE_DIR}/`));
+  if (outside.length > 0) {
+    return {
+      ok: false,
+      message: `mate: not a canonical spec: ${outside.join(", ")}. Only specs under ${SPECS_RELATIVE_DIR}/ are spec publication targets.`,
+    };
+  }
+  const driftedPaths = new Set(drifted);
+  const notDrifted = normalized.filter((candidate) => !driftedPaths.has(candidate));
+  if (notDrifted.length > 0) {
+    return {
+      ok: false,
+      message: `mate: not drifted: ${notDrifted.join(", ")}. Run \`mate artifact pending\` to see which canonical specs are uncommitted and unaccounted for.`,
+    };
+  }
+  return { ok: true, paths: normalized.toSorted() };
+}
+
+/**
+ * The spec publication finisher. Its target is already resolved by
+ * {@link resolveDriftedSpecs}, because an empty drift set is a clean no-op rather than a
+ * refusal and the engine's resolve step can only succeed or fail.
+ *
+ * This is the one publication unit that computes its own anchor: it has no archive
+ * directory to read one from. The anchor is the calendar date plus the {@link specLabel}
+ * of the specs it ships. The segregated {@link SPEC_TAG_NAMESPACE} keeps that computed
+ * anchor out of the dated change anchors, which still never compute one.
+ */
+export function openspecSpecsFinisher(
   contextOrPath: FinishContext | string,
-  runCommand: typeof run = run,
+  paths: string[],
+  now: () => Date = () => new Date(),
 ): ArtifactFinisher {
+  const context: FinishContext =
+    typeof contextOrPath === "string"
+      ? { companionPath: contextOrPath, repositoryId: "" }
+      : contextOrPath;
+
+  return {
+    type: "openspec",
+    disabledReason: "mate: the openspec capability must be enabled to run artifact publish.",
+    isEnabled(capabilities) {
+      return hasOpenspecCapability(capabilities);
+    },
+    async resolve() {
+      const label = specLabel(paths);
+      const publication: Produced = {
+        anchorName: `${calendarDate(now())}${label === "" ? "" : `-${label}`}`,
+        commitPaths: paths,
+        tagNamespace: SPEC_TAG_NAMESPACE,
+        commitSubject: specCommitSubject(paths),
+        tagCollision: "suffix",
+      };
+      return { ok: true, resolved: publication };
+    },
+    capSync() {
+      return capSync(context);
+    },
+  };
+}
+
+/**
+ * The openspec artifact finisher: resolution of an already-archived change, an
+ * openspec-scoped cap sync, and a commit scoped to `openspec/`. Validation and
+ * completeness belong to `openspec archive`, which performs both and is the only step
+ * that can — an archived change is neither validatable nor listed as active.
+ *
+ * Resolution reads the dated `openspec/changes/archive/` directory names openspec
+ * actually created, so a change publication's tag is never a computed date and archived
+ * prose is never read. Spec publications are the documented exception: having no archive
+ * directory to read a date from, {@link openspecSpecsFinisher} computes one, in its own
+ * segregated tag namespace.
+ */
+export function openspecFinisher(contextOrPath: FinishContext | string): ArtifactFinisher {
   const context: FinishContext =
     typeof contextOrPath === "string"
       ? { companionPath: contextOrPath, repositoryId: "" }
@@ -271,87 +431,55 @@ export function openspecFinisher(
 
   return {
     type: "openspec",
-    disabledReason: "mate: the openspec capability must be enabled to run artifact finish.",
+    disabledReason: "mate: the openspec capability must be enabled to run artifact publish.",
     isEnabled(capabilities) {
       return hasOpenspecCapability(capabilities);
     },
-    async validate(name) {
-      const res = runCommand(companionPath, ["openspec", "validate", name, "--json"]);
-      try {
-        const parsed = JSON.parse(res.stdout) as {
-          items?: Array<{ id: string; valid: boolean; issues?: Array<{ message: string }> }>;
-        };
-        const item = parsed.items?.find((entry) => entry.id === name) ?? parsed.items?.[0];
-        if (!item) {
-          return { valid: false, errors: [res.stderr.trim() || "no validation result"] };
+    async resolve(target) {
+      const archiveRoot = path.join(companionPath, "openspec", "changes", "archive");
+      const anchor = ANCHOR_PATTERN.exec(target);
+
+      /** A dated anchor names exactly one directory; no name matching can widen it. */
+      if (anchor) {
+        if (!(await pathExists(path.join(archiveRoot, target)))) {
+          return {
+            ok: false,
+            message: `mate: no archive at openspec/changes/archive/${target}. Archive the change first with \`openspec archive ${anchor[2]}\`.`,
+          };
         }
-        return { valid: item.valid, errors: (item.issues ?? []).map((issue) => issue.message) };
-      } catch {
-        return {
-          valid: res.status === 0,
-          errors: res.status === 0 ? [] : [res.stderr.trim() || "validation failed"],
-        };
+        return resolved(companionPath, anchor[2], target);
       }
-    },
-    async isComplete(name) {
-      const res = runCommand(companionPath, ["openspec", "list", "--json"]);
+
+      const pattern = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(target)}$`);
+      let matches: string[] = [];
       try {
-        const parsed = JSON.parse(res.stdout) as {
-          changes?: Array<{ name: string; completedTasks: number; totalTasks: number }>;
-        };
-        const change = parsed.changes?.find((entry) => entry.name === name);
-        if (!change) {
-          return { complete: false, total: 0, remaining: 0 };
+        const entries = await fs.readdir(archiveRoot, { withFileTypes: true });
+        matches = [];
+        for (const entry of entries) {
+          if (entry.isDirectory() && pattern.test(entry.name)) matches.push(entry.name);
         }
-        const remaining = change.totalTasks - change.completedTasks;
-        return { complete: remaining <= 0, total: change.totalTasks, remaining };
-      } catch {
-        return { complete: false, total: 0, remaining: 0 };
-      }
-    },
-    async detectProduced(name) {
-      const archiveDir = path.join(companionPath, "openspec", "changes", "archive");
-      let entries;
-      try {
-        entries = await fs.readdir(archiveDir, { withFileTypes: true });
+        matches = matches.toSorted();
       } catch {
-        return null;
+        /** No archive directory at all: nothing can match. */
       }
-      const pattern = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(name)}$`);
-      const matches = entries
-        .filter((entry) => entry.isDirectory() && pattern.test(entry.name))
-        .map((entry) => entry.name)
-        .toSorted();
+
       if (matches.length === 0) {
-        return null;
-      }
-      // Latest dated folder wins if the same change name was ever archived twice.
-      const anchorName = matches[matches.length - 1];
-      const commitPaths = await commitPathsForArchive(companionPath, name, anchorName);
-      await reconcileMainSpecFrontmatter(companionPath, anchorName);
-      return { anchorName, commitPaths };
-    },
-    async produce(name) {
-      const res = runCommand(companionPath, ["openspec", "archive", name, "--yes"]);
-      if (res.status !== 0) {
+        const active = await pathExists(path.join(companionPath, "openspec", "changes", target));
         return {
           ok: false,
-          produced: null,
-          message: res.stderr.trim() || res.stdout.trim() || "archive failed",
+          message: active
+            ? `mate: ${target} is still active and cannot be published. Run \`openspec archive ${target}\` first; publish only publishes archived changes.`
+            : `mate: no archived change matches "${target}". Archive it first with \`openspec archive ${target}\`, or pass a dated archive anchor.`,
         };
       }
-      // openspec prints: Change '<name>' archived as '<date>-<name>'.
-      const match = res.stdout.match(/archived as '([^']+)'/);
-      if (!match) {
-        return { ok: false, produced: null, message: "could not detect archived folder name" };
+      /** Two archives, no tiebreaker: picking one would publish an anchor nobody chose. */
+      if (matches.length > 1) {
+        return {
+          ok: false,
+          message: `mate: "${target}" matches ${matches.length} archives (${matches.join(", ")}). Pass one anchor explicitly.`,
+        };
       }
-      const commitPaths = await commitPathsForArchive(companionPath, name, match[1]);
-      await reconcileMainSpecFrontmatter(companionPath, match[1]);
-      return {
-        ok: true,
-        produced: { anchorName: match[1], commitPaths },
-        message: res.stdout.trim(),
-      };
+      return resolved(companionPath, target, matches[0]);
     },
     capSync() {
       return capSync(context);

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

@@ -0,0 +1,175 @@
+import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
+import { resolveForCapability } from "../../../../lib/orchestrator/framework-context";
+import type { LaunchContext } from "../../../../lib/orchestrator/framework-context";
+import type { CapabilityConfig } from "../../../../lib/orchestrator/types";
+import { WorkingRepoRequiredError } from "../../../../lib/orchestrator/types";
+import { type BooleanFlagSet, parseFlags } from "../../../parse-flags";
+import { ensureUnambiguousCompanion } from "../../shared/companion-selection";
+import { defaultGitOps, type GitOps, type WorkingTreeChange } from "../finish/git";
+import {
+  discoverArchives,
+  pendingArchives,
+  unattributedSpecs,
+  type ArchiveEntry,
+  type UnattributedSpec,
+} from "./discovery";
+
+export interface PendingCommandDeps {
+  ensureUnambiguousCompanion?: (cwd: string) => Promise<boolean>;
+  resolveContext?: (cwd: string) => Promise<LaunchContext>;
+  loadCapabilities?: (context: LaunchContext) => Promise<CapabilityConfig[]>;
+  git?: (companionPath: string, workingRepoPath?: string) => GitOps;
+  discover?: (
+    companionPath: string,
+    uncommittedPaths: string[],
+    changeKinds?: Readonly<Record<string, WorkingTreeChange>>,
+  ) => Promise<ArchiveEntry[]>;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+}
+
+/** Presence-only flags; every other `--flag` consumes the following token as its value. */
+const BOOLEAN_FLAGS: BooleanFlagSet = new Set(["json"]);
+
+/**
+ * Whether `mate artifact publish --all` would publish this entry. Discovery does not know
+ * about publication modes, so the marking is applied here rather than in the entry types.
+ */
+export interface AllCoverage {
+  coveredByAll: boolean;
+}
+
+/** Machine-readable result emitted with `--json`. */
+export interface PendingResult {
+  type: string;
+  companionPath: string;
+  count: number;
+  pending: Array<ArchiveEntry & AllCoverage>;
+  /** Uncommitted canonical specs no pending change accounts for, each with its attribution. */
+  unattributedSpecs: Array<UnattributedSpec & AllCoverage>;
+}
+
+/**
+ * `--all` publishes every pending change and then every remaining drifted spec, so both
+ * reported sets are covered in full — an unattributed spec included, whatever its
+ * attribution, because a spec publication needs no archive to carry it.
+ */
+function markCoveredByAll<T>(entries: T[]): Array<T & AllCoverage> {
+  return entries.map((entry) => ({ ...entry, coveredByAll: true }));
+}
+
+async function defaultLoadCapabilities(context: LaunchContext): Promise<CapabilityConfig[]> {
+  const config = await context.configStore.load();
+  return config.capabilities ?? [];
+}
+
+/** Attribution is printed as candidate archives, never as a claim about which one is responsible. */
+function renderUnattributed(specs: Array<UnattributedSpec & AllCoverage>): string[] {
+  if (specs.length === 0) return [];
+  return [
+    "",
+    `${specs.length} uncommitted spec${specs.length === 1 ? "" : "s"} not accounted for by a pending change:`,
+    ...specs.flatMap((spec) => [
+      `  ${spec.path}  [${spec.kind}]${spec.coveredByAll ? "  [--all]" : ""}`,
+      ...(spec.touchedByArchives.length === 0
+        ? ["       no archive names this spec"]
+        : spec.touchedByArchives.map(
+            (archive) => `       publishes via ${archive.anchor}  (archive ${archive.state})`,
+          )),
+    ]),
+  ];
+}
+
+function renderHuman(result: PendingResult): string[] {
+  const pending =
+    result.count === 0
+      ? ["No archived changes have uncommitted content."]
+      : [
+          `${result.count} archived change${result.count === 1 ? "" : "s"} pending publication:`,
+          ...result.pending.flatMap((entry, index) => [
+            `  ${index + 1}. ${entry.name}  ${entry.tag}  ${entry.path}${entry.coveredByAll ? "  [--all]" : ""}`,
+            ...entry.uncommittedPaths.map((uncommitted) => `       ${uncommitted}`),
+            ...entry.uncommittedSpecs.map((spec) => `       ${spec}`),
+          ]),
+        ];
+  return [...pending, ...renderUnattributed(result.unattributedSpecs)];
+}
+
+/**
+ * @command mate artifact pending
+ * @description Lists archived OpenSpec changes whose own files — the archive directory or
+ * the active directory archiving deleted — are still uncommitted in the companion working
+ * tree, each with the uncommitted canonical specs it applied to, so the publication
+ * workflow can offer exact selectable entries instead of parsing OpenSpec prose.
+ * Uncommitted specs no pending change accounts for are reported separately, each with the
+ * archives whose delta specs name it. Every reported entry carries `coveredByAll`, marking
+ * what `mate artifact publish --all` would publish. Read-only:
+ * nothing is validated, produced, committed, tagged, or pushed.
+ * @flags
+ * - `--json` — emit a machine-readable {@link PendingResult} instead of human-readable text.
+ * @remarks No-ops (with a message on stderr) when the openspec capability is disabled for
+ * this repo. Exits non-zero only when the companion, launch context, or Git guard rejects.
+ */
+export async function runArtifactPendingCommand(
+  argv: string[],
+  deps: PendingCommandDeps = {},
+): Promise<void> {
+  const emitOut = deps.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const emitErr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const json = parseFlags(argv, BOOLEAN_FLAGS).json === true;
+
+  const ensureCompanion = deps.ensureUnambiguousCompanion ?? ensureUnambiguousCompanion;
+  if (!(await ensureCompanion(process.cwd()))) {
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolveContext = deps.resolveContext ?? ((cwd: string) => resolveForCapability(cwd));
+  let context: LaunchContext;
+  try {
+    context = await resolveContext(process.cwd());
+  } catch (err) {
+    if (err instanceof WorkingRepoRequiredError) {
+      emitErr(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
+  if (!hasOpenspecCapability(await loadCapabilities(context))) {
+    emitErr("mate: the openspec capability must be enabled to list pending artifacts.");
+    return;
+  }
+
+  let git: GitOps;
+  try {
+    git = (deps.git ?? defaultGitOps)(
+      context.companionPath,
+      context.repository?.path ?? process.env.MATE_REPO_PATH,
+    );
+  } catch (err) {
+    emitErr(`mate: pending Git guard rejected the target: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const discover = deps.discover ?? discoverArchives;
+  const changed = await git.changedPaths();
+  const changeKinds = (await git.changedPathKinds?.()) ?? {};
+  const archives = await discover(context.companionPath, changed, changeKinds);
+  const pending = pendingArchives(archives);
+  const result: PendingResult = {
+    type: "openspec",
+    companionPath: context.companionPath,
+    count: pending.length,
+    pending: markCoveredByAll(pending),
+    unattributedSpecs: markCoveredByAll(
+      await unattributedSpecs(context.companionPath, changed, archives, changeKinds),
+    ),
+  };
+
+  if (json) emitOut(JSON.stringify(result));
+  else for (const line of renderHuman(result)) emitOut(line);
+}