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

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

@@ -3,16 +3,41 @@ import path from "node:path";
 
 import { parse } from "yaml";
 
+import {
+  isPublishable,
+  legacyDeliveryWarning,
+  readDeliveryState,
+} from "../../../../lib/delivery/record";
+import {
+  ARCHIVE_RELATIVE_DIR,
+  archiveAnchors,
+  archiveDirOf,
+  CHANGES_RELATIVE_DIR,
+  deltaSpecs,
+  isChangeName,
+  parseAnchor,
+  SPECS_RELATIVE_DIR,
+} from "../../../../lib/change-layout";
+import { FRONTMATTER_PATTERN } from "../../../../lib/frontmatter";
+import { pathIsDirectory } from "../../../../lib/fs-utils";
+import {
+  BOM,
+  DELTA_COMMENT_PATTERN,
+  parseScopes,
+  type ScopePair,
+} from "../../../../lib/openspec-scopes";
 import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
 import { runIndexCapCommand } from "../../cap/index-cmd";
-import { discoverArchives, SPECS_RELATIVE_DIR, unattributedSpecs } from "../pending/discovery";
+import {
+  canonicalSpecsFor,
+  discoverArchives,
+  pendingArchives,
+  unattributedSpecs,
+  type ArchiveEntry,
+} 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);
@@ -22,9 +47,6 @@ async function pathExists(candidate: string): Promise<boolean> {
   }
 }
 
-/** 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
@@ -35,63 +57,41 @@ async function commitPathsForArchive(
   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> => {
-    const entries = await fs.readdir(directory, { withFileTypes: true });
-    for (const entry of entries) {
-      const entryRelative = path.posix.join(relative, entry.name);
-      if (entry.isDirectory()) {
-        await collectDeltaSpecFiles(path.join(directory, entry.name), entryRelative);
-      } else if (entry.isFile()) {
-        canonicalSpecs.push(path.posix.join("openspec", "specs", entryRelative));
-      }
-    }
-  };
-  try {
-    await collectDeltaSpecFiles(deltaSpecsDir);
-  } catch {
-    // Changes without delta specs still commit their active deletion and archive.
-  }
+  const archiveRelative = `${ARCHIVE_RELATIVE_DIR}/${anchorName}`;
+  const activeRelative = `${CHANGES_RELATIVE_DIR}/${name}`;
+  // Changes without delta specs still commit their active deletion and archive.
+  const canonicalSpecs = await deltaSpecs(path.join(companionPath, archiveRelative));
   return [
     ...((await pathExists(path.join(companionPath, activeRelative))) ? [] : [activeRelative]),
     archiveRelative,
-    ...canonicalSpecs.toSorted(),
+    ...canonicalSpecs.map((spec) => spec.canonical),
   ];
 }
 
-const BOM = "";
-
-interface ScopePair {
-  repository: string;
-  area: string;
-}
-
 type ProjectionResult =
   | { ok: true; repository: string; areas: string[] }
   | { ok: false; reason: string };
 
-function parseDeltaScopes(source: string): ScopePair[] {
-  const text = source.startsWith(BOM) ? source.slice(BOM.length) : source;
-  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
-  if (!match) return [];
+/** The opening line of a `mate:delta` comment, closed or not. */
+const DELTA_COMMENT_OPENER = /^<!--[ \t]*mate:delta/;
+
+const DELTA_TAGS = new Set(["openspec/change", "openspec/delta"]);
 
+/**
+ * A header an agent copied from a delta: it declares `type: delta-spec`, carries a
+ * `change` key, or a delta tag. A nested `scopes` key alone does not count, since
+ * legacy canonical specs carry one.
+ */
+function isDeltaShapedFrontmatter(yamlSource: string): boolean {
   try {
-    const parsed = parse(match[1]) as unknown;
-    if (!parsed || typeof parsed !== "object") return [];
-    const scopes = (parsed as Record<string, unknown>).scopes;
-    if (!Array.isArray(scopes)) return [];
-    return scopes.flatMap((entry) => {
-      if (!entry || typeof entry !== "object") return [];
-      const pair = entry as Record<string, unknown>;
-      return typeof pair.repository === "string" && typeof pair.area === "string"
-        ? [{ repository: pair.repository, area: pair.area }]
-        : [];
-    });
+    const parsed = parse(yamlSource) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+    const header = parsed as Record<string, unknown>;
+    if (header.type === "delta-spec" || "change" in header) return true;
+    const tags = Array.isArray(header.tags) ? header.tags : [header.tags];
+    return tags.some((tag) => typeof tag === "string" && DELTA_TAGS.has(tag));
   } catch {
-    return [];
+    return false;
   }
 }
 
@@ -133,7 +133,10 @@ async function archivedChangeUsesMateSchema(
   }
 }
 
-/** Scope keys are omitted when the delta had none — a partial block beats no frontmatter. */
+/**
+ * The block through its closing line. Scope keys are omitted when the delta had
+ * none — a partial block beats no frontmatter.
+ */
 function renderCanonicalFrontmatter(
   capability: string,
   scope: { repository: string; areas: string[] } | null,
@@ -146,14 +149,15 @@ function renderCanonicalFrontmatter(
     "tags: [openspec/spec]",
     "---",
     "",
-    "",
   ].join("\n");
 }
 
 /**
  * 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.
+ * archive run created bare, and replaces a delta-shaped header or `mate:delta` comment an
+ * agent copied onto one.
+ * 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
@@ -166,66 +170,50 @@ async function reconcileMainSpecFrontmatter(
 ): Promise<string[]> {
   if (!(await archivedChangeUsesMateSchema(companionPath, anchorName))) return [];
 
-  const deltaSpecsDir = path.join(
-    companionPath,
-    "openspec",
-    "changes",
-    "archive",
-    anchorName,
-    "specs",
-  );
+  const archiveDir = path.join(archiveDirOf(companionPath), anchorName);
   const reconciled: string[] = [];
 
-  const walk = async (directory: string, relative = ""): Promise<void> => {
-    let entries;
+  for (const { file, canonical: canonicalRelative, capability } of await deltaSpecs(archiveDir)) {
+    if (capability === null) continue;
+    const canonicalPath = path.join(companionPath, canonicalRelative);
+
     try {
-      entries = await fs.readdir(directory, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const entryRelative = path.posix.join(relative, entry.name);
-      if (entry.isDirectory()) {
-        await walk(path.join(directory, entry.name), entryRelative);
-        continue;
+      const canonical = (await fs.readFile(canonicalPath, "utf8")).replace(BOM, "");
+      /** The body that follows the written block: the whole file, or what trails a delta-shaped header. */
+      let body = `\n${canonical}`;
+      if (DELTA_COMMENT_OPENER.test(canonical)) {
+        const header = DELTA_COMMENT_PATTERN.exec(canonical);
+        if (!header) continue;
+        body = canonical.slice(header[0].length);
+      } else if (canonical.startsWith("---")) {
+        const header = FRONTMATTER_PATTERN.exec(canonical);
+        if (!header || !isDeltaShapedFrontmatter(header[1])) continue;
+        body = canonical.slice(header[0].length);
       }
-      if (!entry.isFile() || entry.name !== "spec.md") continue;
-
-      const capability = path.posix.dirname(entryRelative);
-      if (capability === ".") continue;
-      const canonicalRelative = path.posix.join("openspec", "specs", entryRelative);
-      const canonicalPath = path.join(companionPath, canonicalRelative);
-
-      try {
-        const canonical = await fs.readFile(canonicalPath, "utf8");
-        if (canonical.replace(BOM, "").startsWith("---")) continue;
-
-        const deltaSource = await fs.readFile(path.join(directory, entry.name), "utf8");
-        const scopes = parseDeltaScopes(deltaSource);
-        const projected = projectDeltaScopes(scopes);
-
-        /** Multi-repository is invalid input, so skip; absent scopes still earn a partial block. */
-        if (!projected.ok && scopes.length > 0) {
-          process.stderr.write(
-            `mate: skipped frontmatter for ${canonicalRelative}: ${projected.reason}\n`,
-          );
-          continue;
-        }
-        const head = renderCanonicalFrontmatter(
-          capability,
-          projected.ok ? { repository: projected.repository, areas: projected.areas } : null,
-        );
-        await fs.writeFile(canonicalPath, head + canonical.replace(BOM, ""), "utf8");
-        reconciled.push(canonicalRelative);
-      } catch (error) {
+
+      const deltaSource = await fs.readFile(path.join(archiveDir, "specs", file), "utf8");
+      const scopes = parseScopes(deltaSource);
+      const projected = projectDeltaScopes(scopes);
+
+      /** Multi-repository is invalid input, so skip; absent scopes still earn a partial block. */
+      if (!projected.ok && scopes.length > 0) {
         process.stderr.write(
-          `mate: could not reconcile frontmatter for ${canonicalRelative}: ${String(error)}\n`,
+          `mate: skipped frontmatter for ${canonicalRelative}: ${projected.reason}\n`,
         );
+        continue;
       }
+      const head = renderCanonicalFrontmatter(
+        capability,
+        projected.ok ? { repository: projected.repository, areas: projected.areas } : null,
+      );
+      await fs.writeFile(canonicalPath, head + body, "utf8");
+      reconciled.push(canonicalRelative);
+    } catch (error) {
+      process.stderr.write(
+        `mate: could not reconcile frontmatter for ${canonicalRelative}: ${String(error)}\n`,
+      );
     }
-  };
-
-  await walk(deltaSpecsDir);
+  }
   return reconciled;
 }
 
@@ -258,14 +246,102 @@ async function capSync(context: FinishContext): Promise<boolean> {
   }
 }
 
-async function resolved(
+/** Why an archive's delivery keeps it unpublished, or null when it may be published. */
+async function deliveryHold(companionPath: string, anchorName: string): Promise<string | null> {
+  const delivery = await readDeliveryState(path.join(archiveDirOf(companionPath), anchorName));
+  if (delivery.error) return `mate: refusing to publish ${anchorName}: ${delivery.error}`;
+  if (isPublishable(delivery.status)) return null;
+  const waiting = delivery.unsettled.length > 0 ? ` (${delivery.unsettled.join(", ")})` : "";
+  // The dated anchor, since a bare name resolves to an active change or the newest archive.
+  const [missing] = delivery.missing;
+  const remedy = missing
+    ? `Its scopes name ${delivery.missing.join(", ")} without a delivery; record each with \`mate artifact link ${anchorName} --repository ${missing} --branch <branch>\` or \`--not-applicable <reason>\`, then publish.`
+    : `Record or settle it with \`mate artifact link ${anchorName}\`, then publish.`;
+  return `mate: ${anchorName} is held back: its delivery is ${delivery.status}${waiting}. ${remedy}`;
+}
+
+/**
+ * Per-run memo of each archive's canonical specs, delivery hold, and the pending archives.
+ * None changes the answer while a run publishes: a published archive was not held, so it
+ * never held another back. `publish --all` thus reads each archive and Git status once.
+ */
+export interface PublicationHoldCache {
+  specs: Map<string, Promise<string[]>>;
+  holds: Map<string, Promise<string | null>>;
+  pending?: Promise<ArchiveEntry[]>;
+}
+
+export function publicationHoldCache(): PublicationHoldCache {
+  return { specs: new Map(), holds: new Map() };
+}
+
+function memo<T>(cache: Map<string, Promise<T>>, key: string, load: () => Promise<T>): Promise<T> {
+  let value = cache.get(key);
+  if (!value) {
+    value = load();
+    cache.set(key, value);
+  }
+  return value;
+}
+
+/**
+ * The merge gate, whoever asks: an archive whose delivery is not settled stays unpublished,
+ * and so does one sharing a canonical spec with a pending held-back archive, since its
+ * commit would carry that archive's unmerged requirements along. Null when publishable.
+ */
+export async function publicationHold(
   companionPath: string,
+  anchorName: string,
+  changedPaths?: () => Promise<string[]>,
+  cache: PublicationHoldCache = publicationHoldCache(),
+): Promise<string | null> {
+  const holdOf = (anchor: string): Promise<string | null> =>
+    memo(cache.holds, anchor, () => deliveryHold(companionPath, anchor));
+  const specsOf = (anchor: string): Promise<string[]> =>
+    memo(cache.specs, anchor, () => canonicalSpecsFor(companionPath, anchor));
+
+  const own = await holdOf(anchorName);
+  if (own || !changedPaths) return own;
+
+  const specs = new Set(await specsOf(anchorName));
+  if (specs.size === 0) return null;
+  cache.pending ??= changedPaths().then(async (changed) =>
+    pendingArchives(await discoverArchives(companionPath, changed)),
+  );
+  const others = (await cache.pending).filter((entry) => entry.anchor !== anchorName);
+  for (const other of others) {
+    const shared = (await specsOf(other.anchor)).filter((spec) => specs.has(spec));
+    if (shared.length === 0) continue;
+    if ((await holdOf(other.anchor)) === null) continue;
+    return `mate: ${anchorName} is held back: ${shared.join(", ")} also carries edits from ${other.anchor}, which is not publishable yet. Publish it after ${other.anchor} settles.`;
+  }
+  return null;
+}
+
+async function resolved(
+  context: FinishContext,
   name: string,
   anchorName: string,
 ): Promise<ResolveResult> {
+  const { companionPath } = context;
+  const hold = await publicationHold(
+    companionPath,
+    anchorName,
+    context.changedPaths,
+    context.holdCache,
+  );
+  if (hold) return { ok: false, message: hold };
+  const delivery = await readDeliveryState(path.join(archiveDirOf(companionPath), anchorName));
   const commitPaths = await commitPathsForArchive(companionPath, name, anchorName);
   await reconcileMainSpecFrontmatter(companionPath, anchorName);
-  return { ok: true, resolved: { anchorName, commitPaths } };
+  return {
+    ok: true,
+    resolved: {
+      anchorName,
+      commitPaths,
+      ...(delivery.status === "legacy" ? { warning: legacyDeliveryWarning(anchorName) } : {}),
+    },
+  };
 }
 
 /** Tag namespace segregating spec publications from dated change anchors. */
@@ -436,35 +512,30 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
       return hasOpenspecCapability(capabilities);
     },
     async resolve(target) {
-      const archiveRoot = path.join(companionPath, "openspec", "changes", "archive");
-      const anchor = ANCHOR_PATTERN.exec(target);
+      /** A path-like target names no archive; refuse before touching the filesystem. */
+      if (!isChangeName(target)) {
+        return {
+          ok: false,
+          message: `mate: no archived change matches "${target}". Pass a change name or a dated archive anchor.`,
+        };
+      }
+      const anchor = parseAnchor(target);
 
       /** A dated anchor names exactly one directory; no name matching can widen it. */
       if (anchor) {
-        if (!(await pathExists(path.join(archiveRoot, target)))) {
+        if (!(await pathIsDirectory(path.join(archiveDirOf(companionPath), target)))) {
           return {
             ok: false,
-            message: `mate: no archive at openspec/changes/archive/${target}. Archive the change first with \`openspec archive ${anchor[2]}\`.`,
+            message: `mate: no archive at ${ARCHIVE_RELATIVE_DIR}/${target}. Archive the change first with \`openspec archive ${anchor.name}\`.`,
           };
         }
-        return resolved(companionPath, anchor[2], target);
+        return resolved(context, anchor.name, target);
       }
 
-      const pattern = new RegExp(`^\\d{4}-\\d{2}-\\d{2}-${escapeRegExp(target)}$`);
-      let matches: string[] = [];
-      try {
-        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);
-        }
-        matches = matches.toSorted();
-      } catch {
-        /** No archive directory at all: nothing can match. */
-      }
+      const matches = await archiveAnchors(companionPath, target);
 
       if (matches.length === 0) {
-        const active = await pathExists(path.join(companionPath, "openspec", "changes", target));
+        const active = await pathExists(path.join(companionPath, CHANGES_RELATIVE_DIR, target));
         return {
           ok: false,
           message: active
@@ -479,7 +550,7 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
           message: `mate: "${target}" matches ${matches.length} archives (${matches.join(", ")}). Pass one anchor explicitly.`,
         };
       }
-      return resolved(companionPath, target, matches[0]);
+      return resolved(context, target, matches[0]);
     },
     capSync() {
       return capSync(context);

package/src/cli/commands/artifact/finish/secret-scan.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+
+import { resolveSecretPolicy } from "../../../../runtime/policy";
+import { isSecretFile } from "../../../../runtime/secret-patterns";
+import { listFiles, scanFiles, type SecretFinding } from "../../../../runtime/secret-scan";
+
+/** Rule id reported for a staged path that is itself a secret file. */
+export const SECRET_FILE_RULE_ID = "mate/secret-file";
+
+export type PublicationSecretScan =
+  | { skipped: true }
+  | { skipped: false; findings: SecretFinding[] };
+
+/**
+ * Scans exactly what a publication would stage: every file under the commit
+ * paths that exists on disk (a deleted path has nothing to leak). A staged
+ * secret file counts as a finding of its own. Paths are reported relative to
+ * the companion; values never leave this function. Throws when the scanner
+ * fails, which the engine treats like a finding.
+ */
+export async function scanPublication(
+  companionPath: string,
+  commitPaths: readonly string[],
+): Promise<PublicationSecretScan> {
+  const policy = resolveSecretPolicy(companionPath);
+  if (!policy.guardrails) return { skipped: true };
+
+  const files = (
+    await Promise.all(
+      commitPaths.map((commitPath) => listFiles(path.join(companionPath, commitPath))),
+    )
+  ).flat();
+  const relative = (file: string) => path.relative(companionPath, file).split(path.sep).join("/");
+  const secretFiles: SecretFinding[] = files
+    .map(relative)
+    .filter((file) => isSecretFile(file, policy))
+    .map((file) => ({ path: file, line: 0, ruleId: SECRET_FILE_RULE_ID }));
+  const contentFindings = (await scanFiles(files)).map((finding) => ({
+    ...finding,
+    path: relative(finding.path),
+  }));
+  return { skipped: false, findings: [...secretFiles, ...contentFindings] };
+}

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

@@ -1,3 +1,6 @@
+import path from "node:path";
+
+import { readDeliveryState, type DeliveryState } from "../../../../lib/delivery/record";
 import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
 import { resolveForCapability } from "../../../../lib/orchestrator/framework-context";
 import type { LaunchContext } from "../../../../lib/orchestrator/framework-context";
@@ -39,12 +42,20 @@ export interface AllCoverage {
   coveredByAll: boolean;
 }
 
+/**
+ * The archive's Delivery Record and its settlement; held back unless `isPublishable`.
+ * `error` names an unreadable record.
+ */
+export interface PendingDelivery {
+  delivery: DeliveryState;
+}
+
 /** Machine-readable result emitted with `--json`. */
 export interface PendingResult {
   type: string;
   companionPath: string;
   count: number;
-  pending: Array<ArchiveEntry & AllCoverage>;
+  pending: Array<ArchiveEntry & AllCoverage & PendingDelivery>;
   /** Uncommitted canonical specs no pending change accounts for, each with its attribution. */
   unattributedSpecs: Array<UnattributedSpec & AllCoverage>;
 }
@@ -80,6 +91,23 @@ function renderUnattributed(specs: Array<UnattributedSpec & AllCoverage>): strin
   ];
 }
 
+async function withDelivery<T extends ArchiveEntry>(
+  companionPath: string,
+  entries: T[],
+): Promise<Array<T & PendingDelivery>> {
+  return Promise.all(
+    entries.map(async (entry) => {
+      const delivery = await readDeliveryState(path.join(companionPath, entry.path));
+      return { ...entry, delivery };
+    }),
+  );
+}
+
+/** A damaged record is shown with its error, so it is fixed rather than re-linked over. */
+function renderDeliveryStatus(delivery: DeliveryState): string {
+  return delivery.error === undefined ? delivery.status : `unreadable (${delivery.error})`;
+}
+
 function renderHuman(result: PendingResult): string[] {
   const pending =
     result.count === 0
@@ -87,7 +115,7 @@ function renderHuman(result: PendingResult): string[] {
       : [
           `${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]" : ""}`,
+            `  ${index + 1}. ${entry.name}  ${entry.tag}  ${entry.path}${entry.coveredByAll ? "  [--all]" : ""}  delivery: ${renderDeliveryStatus(entry.delivery)}`,
             ...entry.uncommittedPaths.map((uncommitted) => `       ${uncommitted}`),
             ...entry.uncommittedSpecs.map((spec) => `       ${spec}`),
           ]),
@@ -164,7 +192,7 @@ export async function runArtifactPendingCommand(
     type: "openspec",
     companionPath: context.companionPath,
     count: pending.length,
-    pending: markCoveredByAll(pending),
+    pending: await withDelivery(context.companionPath, markCoveredByAll(pending)),
     unattributedSpecs: markCoveredByAll(
       await unattributedSpecs(context.companionPath, changed, archives, changeKinds),
     ),

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

@@ -1,6 +1,15 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 
+import {
+  ARCHIVE_RELATIVE_DIR,
+  archiveAnchors,
+  archiveDirOf,
+  CHANGES_RELATIVE_DIR,
+  changeNameOf,
+  deltaSpecs,
+  filesBelow,
+  SPECS_RELATIVE_DIR,
+} from "../../../../lib/change-layout";
 import type { WorkingTreeChange } from "../finish/git";
 
 /** Whether an archived change still has uncommitted content in the companion working tree. */
@@ -48,13 +57,6 @@ export interface ArchiveEntry {
   state: CommitState;
 }
 
-/** Only dated archive directories are publishable; everything else is ignored. */
-const ARCHIVE_ANCHOR_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
-const ARCHIVE_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
-
-const ARCHIVE_RELATIVE_DIR = "openspec/changes/archive";
-export const SPECS_RELATIVE_DIR = "openspec/specs";
-
 /** The tag `mate artifact publish` creates, never a recomputed date. */
 export function finishMarker(anchor: string): string {
   return `openspec/${anchor}`;
@@ -109,38 +111,16 @@ function changeKindFor(
   );
 }
 
-/**
- * Every file beneath `directory`, as POSIX paths under `relativeRoot`. Reads directory
- * entry names only, never file contents. Throws when `directory` cannot be read.
- */
-async function filesUnder(directory: string, relativeRoot: string): Promise<string[]> {
-  const entries = await fs.readdir(directory, { withFileTypes: true });
-  const nested = await Promise.all(
-    entries.map(async (entry) => {
-      const entryRelative = path.posix.join(relativeRoot, entry.name);
-      if (entry.isDirectory()) return filesUnder(path.join(directory, entry.name), entryRelative);
-      return entry.isFile() ? [entryRelative] : [];
-    }),
-  );
-  return nested.flat();
-}
-
 /**
  * Canonical specs the change's delta specs applied to. Only directory entry names under
  * the archive's `specs/` tree are read — never any file contents — so archived prose
  * cannot influence discovery.
  */
-async function canonicalSpecsFor(companionPath: string, anchor: string): Promise<string[]> {
-  try {
-    const specs = await filesUnder(
-      path.join(companionPath, ARCHIVE_RELATIVE_DIR, anchor, "specs"),
-      SPECS_RELATIVE_DIR,
-    );
-    return specs.toSorted();
-  } catch {
-    // A change without delta specs still owns its archive and active directories.
-    return [];
-  }
+export async function canonicalSpecsFor(companionPath: string, anchor: string): Promise<string[]> {
+  // A change without delta specs still owns its archive and active directories.
+  return (await deltaSpecs(path.join(archiveDirOf(companionPath), anchor))).map(
+    (spec) => spec.canonical,
+  );
 }
 
 /**
@@ -156,24 +136,12 @@ export async function discoverArchives(
   uncommittedPaths: string[],
   changeKinds: Readonly<Record<string, WorkingTreeChange>> = {},
 ): Promise<ArchiveEntry[]> {
-  let entries;
-  try {
-    entries = await fs.readdir(path.join(companionPath, "openspec", "changes", "archive"), {
-      withFileTypes: true,
-    });
-  } catch {
-    return [];
-  }
-
-  const anchors = entries
-    .filter((entry) => entry.isDirectory() && ARCHIVE_ANCHOR_PATTERN.test(entry.name))
-    .map((entry) => entry.name)
-    .toSorted();
+  const anchors = await archiveAnchors(companionPath);
 
   return Promise.all(
     anchors.map(async (anchor) => {
-      const name = anchor.replace(ARCHIVE_DATE_PREFIX, "");
-      const ownedPaths = [`${ARCHIVE_RELATIVE_DIR}/${anchor}`, `openspec/changes/${name}`];
+      const name = changeNameOf(anchor);
+      const ownedPaths = [`${ARCHIVE_RELATIVE_DIR}/${anchor}`, `${CHANGES_RELATIVE_DIR}/${name}`];
       const owned = matching(uncommittedPaths, ownedPaths);
       const ownedDirectories = matchingDirectories(uncommittedPaths, ownedPaths);
       const specs =
@@ -237,13 +205,9 @@ async function specFilesFor(
   }
   const collapsed = withoutTrailingSlash(worktreePath);
   const root = collapsed.startsWith(`${SPECS_RELATIVE_DIR}/`) ? collapsed : SPECS_RELATIVE_DIR;
-  try {
-    const files = await filesUnder(path.join(companionPath, root), root);
-    return files.map((file) => ({ path: file, kind: "new" as const }));
-  } catch {
-    // A collapsed ancestor such as `openspec/` need not contain a spec tree at all.
-    return [];
-  }
+  // A collapsed ancestor such as `openspec/` need not contain a spec tree at all.
+  const files = await filesBelow(path.join(companionPath, root));
+  return files.map((file) => ({ path: `${root}/${file}`, kind: "new" as const }));
 }
 
 /**