@cassiomc1/forgeloop 0.1.1 → 0.1.3

package/src/core/events.js

@@ -0,0 +1,158 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+const EVENT_SCHEMA_VERSION = 1;
+export const LIFECYCLE_MILESTONES = Object.freeze([
+  "CONTRACT_VALIDATED",
+  "ROUTE_VALIDATED",
+  "PREFLIGHT_READY",
+  "EXECUTION_STARTED",
+  "VERIFICATION_STARTED",
+  "VERIFICATION_RECORDED",
+  "COMPLETION_VALIDATED",
+]);
+const REPEATABLE_MILESTONES = new Set(["VERIFICATION_RECORDED"]);
+
+function eventHash(event) {
+  const { hash, ...body } = event;
+  return canonicalFingerprint(body);
+}
+
+function protocolError(code, message, artifacts = [ARTIFACT_PATHS.events]) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+async function readEvents(target, packageRoot) {
+  await assertSafePath(target, ARTIFACT_PATHS.events);
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (!(await fileExists(eventsPath))) return [];
+  const text = await readFile(eventsPath, "utf8");
+  assertJsonBytes(text, ARTIFACT_PATHS.events);
+  const schema = await readSchema("event", packageRoot);
+  const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
+  return lines.map((line, index) => {
+    let event;
+    try {
+      event = JSON.parse(line);
+      assertJsonLimits(event, `${ARTIFACT_PATHS.events}[${index}]`);
+      assertSchema(event, schema, `${ARTIFACT_PATHS.events}[${index}]`);
+    } catch (error) {
+      throw protocolError("E_EVENT_INVALID", `${ARTIFACT_PATHS.events} line ${index + 1}: ${error.message}`);
+    }
+    return event;
+  });
+}
+
+export async function appendProtocolEvent(target, input, packageRoot, options = {}) {
+  if (typeof input?.taskId !== "string" || !input.taskId) throw protocolError("E_EVENT_INVALID", "event taskId is required");
+  if (typeof input?.event !== "string" || !input.event) throw protocolError("E_EVENT_INVALID", "event type is required");
+  const events = await readEvents(target, packageRoot);
+  const previous = events.at(-1) ?? null;
+  const event = {
+    seq: events.length + 1,
+    schemaVersion: EVENT_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    event: input.event,
+    at: input.at ?? new Date().toISOString(),
+    ...(input.fingerprint ? { fingerprint: input.fingerprint } : {}),
+    previousHash: previous?.hash ?? null,
+    ...(input.details ? { details: structuredClone(input.details) } : {}),
+  };
+  assertSecretFree(event);
+  const schema = await readSchema("event", packageRoot);
+  assertSchema(event, schema, ARTIFACT_PATHS.events);
+  event.hash = eventHash(event);
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (!options.dryRun) {
+    await mkdir(path.dirname(eventsPath), { recursive: true });
+    await appendFile(eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
+  }
+  return event;
+}
+
+export async function validateEventLedger(target, packageRoot) {
+  let events;
+  try {
+    events = await readEvents(target, packageRoot);
+  } catch (error) {
+    return { valid: false, events: [], errors: [{ code: error.code ?? "E_EVENT_INVALID", message: error.message }] };
+  }
+  const errors = [];
+  let taskId = null;
+  const seen = new Set();
+  let lastMilestone = -1;
+  const milestoneCounts = new Map();
+  for (const [index, event] of events.entries()) {
+    if (event.seq !== index + 1) {
+      errors.push({ code: "E_EVENT_INVALID", message: `event sequence must be ${index + 1}` });
+    }
+    if (taskId === null) taskId = event.taskId;
+    if (event.taskId !== taskId) errors.push({ code: "E_EVENT_INVALID", message: "event task IDs must remain stable" });
+    if (event.previousHash !== (index === 0 ? null : events[index - 1].hash)) {
+      errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} previousHash does not match` });
+    }
+    if (event.hash !== eventHash(event)) {
+      errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} hash does not match its content` });
+    }
+    const milestoneIndex = LIFECYCLE_MILESTONES.indexOf(event.event);
+    if (milestoneIndex >= 0) {
+      const count = (milestoneCounts.get(event.event) ?? 0) + 1;
+      milestoneCounts.set(event.event, count);
+      if (count > 1 && !REPEATABLE_MILESTONES.has(event.event)) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+      }
+      if (milestoneIndex > lastMilestone + 1) {
+        errors.push({
+          code: "E_PHASE_CHRONOLOGY_INVALID",
+          message: `${event.event} is missing prerequisite milestone: ${LIFECYCLE_MILESTONES[lastMilestone + 1]}`,
+        });
+      } else if (milestoneIndex < lastMilestone) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `${event.event} is out of lifecycle order` });
+      } else if (milestoneIndex === lastMilestone && !REPEATABLE_MILESTONES.has(event.event)) {
+        errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `lifecycle milestone must not repeat: ${event.event}` });
+      }
+      if (milestoneIndex > lastMilestone) lastMilestone = milestoneIndex;
+    }
+    seen.add(event.event);
+    if (event.event === "EXECUTION_STARTED" && !seen.has("ROUTE_VALIDATED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before route validation" });
+    }
+    if (event.event === "EXECUTION_STARTED" && !seen.has("CONTRACT_VALIDATED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before contract validation" });
+    }
+    if (event.event === "EXECUTION_STARTED" && !seen.has("PREFLIGHT_READY")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before preflight readiness" });
+    }
+    if (event.event === "EXECUTION_STARTED") {
+      const preflight = events.slice(0, index).findLast((candidate) => candidate.event === "PREFLIGHT_READY");
+      const requiredGates = preflight?.details?.requiredGates ?? [];
+      const satisfiedGates = new Set(events.slice(0, index)
+        .filter((candidate) => candidate.event === "GATE_SATISFIED")
+        .map((candidate) => candidate.details?.gate));
+      for (const gate of requiredGates) {
+        if (!satisfiedGates.has(gate)) {
+          errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `execution started before gate satisfaction: ${gate}` });
+        }
+      }
+    }
+    if (event.event === "VERIFICATION_RECORDED" && !seen.has("VERIFICATION_STARTED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "verification evidence recorded before verification started" });
+    }
+    if (event.event === "COMPLETION_VALIDATED" && !seen.has("VERIFICATION_RECORDED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion validated before verification evidence" });
+    }
+  }
+  return { valid: errors.length === 0, events, errors };
+}

package/src/core/execution-prerequisites.js

@@ -0,0 +1,200 @@
+import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { validateEventLedger } from "./events.js";
+import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { stateIdentityErrors } from "./completion-relationships.js";
+import { classifyLoadedWorkState } from "./work-state.js";
+
+const START_EXECUTION_EVENTS = Object.freeze([
+  "CONTRACT_VALIDATED",
+  "ROUTE_VALIDATED",
+  "PREFLIGHT_READY",
+]);
+const POST_EXECUTION_PHASES = new Set([
+  "EXECUTING",
+  "VERIFYING",
+  "DIAGNOSING",
+  "CORRECTING",
+  "REVIEWING",
+  "COMPLETE",
+]);
+export const PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE = "PREFLIGHT_READY event routing fingerprint does not match the current READY preflight and route";
+export const PREFLIGHT_CONTRACT_IDENTITY_ERROR_MESSAGE = "PREFLIGHT_READY event contract fingerprint does not match the current READY preflight";
+
+export function hasExecutionStarted(phase) {
+  return POST_EXECUTION_PHASES.has(phase);
+}
+
+export function prerequisiteError(prerequisites) {
+  const first = prerequisites.errors[0];
+  if (!first) return null;
+  const error = new Error(first.message);
+  error.code = first.code;
+  error.artifacts = first.artifacts;
+  return error;
+}
+
+export async function assertExecutionPrerequisites(input = {}) {
+  const prerequisites = await evaluateStartExecutionPrerequisites(input);
+  const error = prerequisiteError(prerequisites);
+  if (error) throw error;
+  return prerequisites;
+}
+
+function issue(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+function sameStringSet(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  return left.length === new Set(left).size
+    && right.length === new Set(right).size
+    && left.length === right.length
+    && left.every((value) => right.includes(value));
+}
+
+async function load(loadArtifact, code, message, artifacts, errors) {
+  try {
+    return await loadArtifact();
+  } catch (error) {
+    errors.push(issue(code, `${message}: ${error.message}`, artifacts));
+    return null;
+  }
+}
+
+function freshnessErrors(state, freshness) {
+  if (freshness.status !== "REVALIDATION_REQUIRED") return [];
+  return [issue(
+    "E_STATE_REVALIDATION_REQUIRED",
+    `EXECUTING requires a fresh work-state checkpoint: ${freshness.reasons.join(", ")}`,
+    [
+      ARTIFACT_PATHS.state,
+      ARTIFACT_PATHS.contract,
+      ...(state.requiredArtifacts?.map((artifact) => artifact.path) ?? []),
+    ],
+  )];
+}
+
+function prerequisiteLedgerErrors(ledger, taskId, preflight, route) {
+  const errors = (ledger.errors ?? []).map((error) => issue(
+    error.code ?? "E_PHASE_CHRONOLOGY_INVALID",
+    error.message,
+    [ARTIFACT_PATHS.events],
+  ));
+  const events = ledger.events ?? [];
+  if (events.some((event) => event.taskId !== taskId)) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "EXECUTING requires protocol prerequisite events to belong to the current task",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+    ));
+    return errors;
+  }
+  const currentEvents = events.filter((event) => event.taskId === taskId);
+  for (const requiredEvent of START_EXECUTION_EVENTS) {
+    if (!currentEvents.some((event) => event.event === requiredEvent)) {
+      errors.push(issue(
+        "E_PHASE_CHRONOLOGY_INVALID",
+        `EXECUTING requires a ${requiredEvent} protocol event`,
+        [ARTIFACT_PATHS.events],
+      ));
+    }
+  }
+  const preflightEvent = currentEvents.find((event) => event.event === "PREFLIGHT_READY");
+  if (preflightEvent && (!sameStringSet(preflightEvent.details?.requiredGates, preflight.requiredGates)
+    || !sameStringSet(preflightEvent.details?.satisfiedGates, preflight.satisfiedGates))) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "PREFLIGHT_READY event gate sets do not match the current READY preflight",
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight],
+    ));
+  }
+  if (preflightEvent && preflightEvent.fingerprint !== preflight.fingerprints.contract) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      PREFLIGHT_CONTRACT_IDENTITY_ERROR_MESSAGE,
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract],
+    ));
+  }
+  if (preflightEvent && (preflightEvent.details?.routingFingerprint !== preflight.fingerprints.routing
+    || preflightEvent.details?.routingFingerprint !== route.fingerprint)) {
+    errors.push(issue(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      PREFLIGHT_ROUTE_IDENTITY_ERROR_MESSAGE,
+      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.route],
+    ));
+  }
+  return errors;
+}
+
+export async function evaluateStartExecutionPrerequisites({ target, state, packageRoot } = {}) {
+  const errors = [];
+  const requiredArtifacts = [
+    ARTIFACT_PATHS.state,
+    ARTIFACT_PATHS.contract,
+    ARTIFACT_PATHS.route,
+    ARTIFACT_PATHS.preflight,
+    ARTIFACT_PATHS.events,
+  ];
+  if (!state) {
+    return {
+      errors: [issue("E_PHASE_PREREQUISITE_MISSING", "EXECUTING requires a work state", [ARTIFACT_PATHS.state])],
+      requiredArtifacts,
+    };
+  }
+
+  const contract = await load(
+    () => readContract(target, packageRoot),
+    "E_PHASE_PREREQUISITE_MISSING",
+    `EXECUTING requires ${ARTIFACT_PATHS.contract}`,
+    [ARTIFACT_PATHS.contract],
+    errors,
+  );
+  const route = await load(
+    () => readPersistedRoute(target, packageRoot),
+    "E_PHASE_PREREQUISITE_MISSING",
+    `EXECUTING requires ${ARTIFACT_PATHS.route}`,
+    [ARTIFACT_PATHS.route],
+    errors,
+  );
+  if (!contract || !route) return { errors, requiredArtifacts, contract, route };
+
+  if (state.routeFingerprint !== route.fingerprint) {
+    errors.push(issue(
+      "E_ROUTE_STALE",
+      "EXECUTING requires work state and route to match the current contract",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract],
+    ));
+  }
+  errors.push(...stateIdentityErrors({ contract, route, state }));
+
+  const freshness = await classifyLoadedWorkState({
+    target,
+    state,
+    contractFile: ARTIFACT_PATHS.contract,
+  });
+  errors.push(...freshnessErrors(state, freshness));
+
+  const preflight = await evaluatePreflight({ target, packageRoot });
+  let persistedPreflight = null;
+  try {
+    persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+  } catch {
+    // validatePersistedPreflight reports the stable, actionable preflight reason.
+  }
+  const persistedPreflightErrors = validatePersistedPreflight(persistedPreflight?.value, preflight);
+  if (!sameStringSet(state.requiredGates, preflight.requiredGates)
+    || !sameStringSet(state.satisfiedGates, preflight.satisfiedGates)) {
+    errors.push(issue(
+      "E_PREFLIGHT_GATES_STALE",
+      "Work state gate sets do not match the current preflight evaluation",
+      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+    ));
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot);
+  errors.push(...prerequisiteLedgerErrors(ledger, contract.value.taskId, preflight, route));
+  errors.push(...persistedPreflightErrors);
+  return { errors, requiredArtifacts, contract, route, preflight, persistedPreflight, ledger };
+}

package/src/core/gate-artifact.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+
+import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
+import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { sha256 } from "./manifest.js";
+
+function gateName(value) {
+  if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    const error = new Error(`Invalid gate name: ${value}`);
+    error.code = "E_GATE_INVALID";
+    throw error;
+  }
+  return value;
+}
+
+export function gatePath(gate) {
+  return `${ARTIFACT_PATHS.gates ?? ".forgeloop/gates"}/${gateName(gate)}.json`;
+}
+
+export async function persistGate(target, gate, packageRoot, options = {}) {
+  const relativePath = gatePath(gate.gate);
+  return writeJsonArtifact(target, relativePath, gate, "gate", packageRoot, options);
+}
+
+export async function readGate(target, gate, packageRoot) {
+  const relativePath = gatePath(gate);
+  return readJsonArtifact(target, relativePath, "gate", packageRoot);
+}
+
+export async function readGateIfPresent(target, gate, packageRoot) {
+  const relativePath = gatePath(gate);
+  await assertSafePath(target, relativePath);
+  const filePath = ensureWithin(target, relativePath);
+  if (!(await fileExists(filePath))) return null;
+  return readJsonArtifact(target, relativePath, "gate", packageRoot);
+}
+
+export async function validateGateArtifacts(target, gateValue, packageRoot) {
+  const schema = await readSchema("gate", packageRoot);
+  assertSchema(gateValue, schema, "gate");
+  const stale = [];
+  for (const artifact of gateValue.artifacts ?? []) {
+    await assertSafePath(target, artifact.path);
+    const artifactPath = ensureWithin(target, artifact.path);
+    if (!(await fileExists(artifactPath))) {
+      stale.push({ path: artifact.path, status: "missing" });
+      continue;
+    }
+    const digest = sha256(await readBytes(artifactPath));
+    if (digest !== artifact.sha256) stale.push({ path: artifact.path, status: "changed" });
+  }
+  return stale;
+}

package/src/core/gates.js

@@ -0,0 +1,55 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import path from "node:path";
+
+export const GATE_SCHEMA_VERSION = 1;
+export const GATE_STATUSES = Object.freeze(["satisfied", "unverified", "blocked"]);
+
+function stringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+  return [...value];
+}
+
+function artifactList(value) {
+  if (!Array.isArray(value)) throw new Error("Gate artifacts must be an array");
+  return value.map((artifact) => {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+      throw new Error("Gate artifact entries must be objects");
+    }
+    if (typeof artifact.path !== "string" || !artifact.path) throw new Error("Gate artifact path is required");
+    const portable = artifact.path.replaceAll("\\", "/");
+    const normalized = path.posix.normalize(portable);
+    if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable) || normalized === ".." || normalized.startsWith("../")) {
+      throw new Error(`Gate artifact path escapes the target: ${artifact.path}`);
+    }
+    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(artifact.sha256)) {
+      throw new Error(`Gate artifact hash is invalid: ${artifact.path}`);
+    }
+    return { path: normalized.replace(/^\.\//, ""), sha256: artifact.sha256 };
+  });
+}
+
+export function createGate(input = {}) {
+  if (typeof input.taskId !== "string" || !input.taskId) throw new Error("Gate taskId is required");
+  if (typeof input.gate !== "string" || !input.gate) throw new Error("Gate name is required");
+  if (!GATE_STATUSES.includes(input.status)) throw new Error(`Unknown gate status: ${input.status}`);
+  const artifacts = artifactList(input.artifacts ?? []);
+  return {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    gate: input.gate,
+    status: input.status,
+    requiredBy: stringArray(input.requiredBy ?? [], "Gate requiredBy"),
+    artifacts,
+    decisions: stringArray(input.decisions ?? [], "Gate decisions"),
+    unknowns: stringArray(input.unknowns ?? [], "Gate unknowns"),
+    approvedAssumptions: stringArray(input.approvedAssumptions ?? [], "Gate approvedAssumptions"),
+    evidence: Array.isArray(input.evidence) ? input.evidence.map((item) => ({ ...item })) : [],
+  };
+}
+
+export function requiredGatePaths(gates) {
+  return [...new Set(gates)].sort().map((gate) => `.forgeloop/gates/${gate}.json`);
+}

package/src/core/guide-metadata.js

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const GUIDE_FILES = Object.freeze({
+  premium: "ENG/premium-sites-studio-eng.md",
+  clean: "ENG/clean-code-eng.md",
+  test: "ENG/test-code-eng.md",
+  security: "ENG/sec-code-eng.md",
+  design: "ENG/design-code-eng.md",
+  performance: "ENG/perf-code-eng.md",
+  accessibility: "ENG/accessibility-eng.md",
+  games: "ENG/games-code-design-web-eng.md",
+});
+
+function parseList(frontmatter, key) {
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `${key}:`);
+  if (start < 0) return [];
+  const values = [];
+  for (const line of lines.slice(start + 1)) {
+    if (!/^\s+-\s+/.test(line)) break;
+    values.push(line.replace(/^\s+-\s+/, "").trim());
+  }
+  return values.filter(Boolean);
+}
+
+function parseFrontmatter(text, relativePath) {
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!match) throw new Error(`${relativePath} is missing YAML frontmatter`);
+  const frontmatter = match[1];
+  const guideId = frontmatter.match(/^guide-id:\s*([^\s]+)\s*$/m)?.[1] ?? null;
+  return {
+    guideId,
+    requiresGates: parseList(frontmatter, "requires-gates"),
+    completionEvidence: parseList(frontmatter, "completion-evidence"),
+  };
+}
+
+export async function readGuideMetadata(packageRoot) {
+  const metadata = {};
+  for (const [id, relativePath] of Object.entries(GUIDE_FILES)) {
+    const text = await readFile(path.join(packageRoot, relativePath), "utf8");
+    const parsed = parseFrontmatter(text, relativePath);
+    metadata[id] = {
+      guideId: parsed.guideId ?? id,
+      requiresGates: [...parsed.requiresGates],
+      completionEvidence: [...parsed.completionEvidence],
+      path: relativePath,
+    };
+  }
+  return metadata;
+}
+
+export async function requiredGatesForGuides(guides, packageRoot) {
+  const metadata = await readGuideMetadata(packageRoot);
+  return [...new Set(guides.flatMap((guide) => metadata[guide]?.requiresGates ?? []))].sort();
+}
+
+export async function completionEvidenceForGuides(guides, packageRoot) {
+  const metadata = await readGuideMetadata(packageRoot);
+  return [...new Set(guides.flatMap((guide) => metadata[guide]?.completionEvidence ?? []))].sort();
+}