@warpgogol/forge 2.7.0 → 2.8.1

package/os/rfc/handlers/index-graph.ts

@@ -0,0 +1,237 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/os/site-kernel/src/rfc/handlers/index-graph.ts as an authored site-kernel authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303: extracted index and graph handlers from handlers.ts into handlers/index-graph.ts.</item>
+  <item>Post-refactor hardening: rfc.graph resolves archived RFC files by basename id.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+
+import { listRfcFiles, readAndParseRfc, rfcFileMatchesId } from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type {
+  RfcStatus,
+  RfcKind,
+  RfcIndexEntry,
+  RfcIndexResult,
+  RfcGraphResult,
+} from "../types.ts";
+import { RFC_DIR } from "../types.ts";
+import { toIsoDate } from "./shared.ts";
+
+export async function runRfcIndexGenerate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcIndexResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const files = await listRfcFiles(rfcDirPath);
+  const entries: RfcIndexEntry[] = [];
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    if (!result || "error" in result) continue;
+    const fm = result.parsed.frontmatter;
+    const arr = (k: string): string[] =>
+      Array.isArray(fm[k]) ? (fm[k] as unknown[]).map(String) : [];
+    entries.push({
+      id: String(fm["id"] ?? ""),
+      title: String(fm["title"] ?? ""),
+      status: String(fm["status"] ?? "") as RfcStatus,
+      kind: String(fm["kind"] ?? "") as RfcKind,
+      createdAt: String(fm["createdAt"] ?? ""),
+      implementedAt: String(fm["implementedAt"] ?? ""),
+      closedAt: String(fm["closedAt"] ?? ""),
+      supersedes: arr("supersedes"),
+      supersededBy: String(fm["supersededBy"] ?? ""),
+      amends: arr("amends"),
+      amendedBy: arr("amendedBy"),
+      related: arr("related"),
+      file: path.join(RFC_DIR, fileName),
+    });
+  }
+  entries.sort((a, b) => a.id.localeCompare(b.id));
+
+  let written: string | undefined;
+  if (input.flags["write"] === true) {
+    const outRel = path.join(RFC_DIR, "index.yaml");
+    const payload = {
+      command: "rfc.index.generate",
+      generatedAt: toIsoDate(new Date()),
+      count: entries.length,
+      entries,
+    };
+    await fs.writeFile(path.join(workspaceRoot, outRel), `${yamlStringify(payload)}`, "utf-8");
+    written = outRel;
+  }
+
+  if (outputFormat === "pretty") {
+    logger.section(`RFC index (${entries.length} RFC(s))`);
+    if (written) logger.success(`Wrote ${written}`);
+    else logger.info("Use --json for the index, or --write to persist docs/rfcs/index.yaml.");
+  }
+
+  return {
+    data: { command: "rfc.index.generate", status: "ok", count: entries.length, entries, written },
+    summary: written
+      ? `Wrote ${written} (${entries.length} RFCs)`
+      : `Indexed ${entries.length} RFC(s)`,
+  };
+}
+
+export async function runRfcGraph(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcGraphResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const targetId = input.flags["id"] as string | undefined;
+  if (!targetId) {
+    throw new Error("rfc.graph requires an RFC id, e.g. site-kernel run rfc.graph --id RFC-0152");
+  }
+
+  const files = await listRfcFiles(rfcDirPath);
+  const fileName = files.find((f) => rfcFileMatchesId(f, targetId));
+  if (!fileName) {
+    throw new Error(`No RFC file found for id ${targetId} in ${RFC_DIR}/`);
+  }
+  const result = await readAndParseRfc(rfcDirPath, fileName);
+  if (!result || "error" in result) {
+    throw new Error(`Could not parse RFC ${targetId}: ${result?.error ?? "file not found"}`);
+  }
+  const fm = result.parsed.frontmatter;
+  const arr = (k: string): string[] =>
+    Array.isArray(fm[k]) ? (fm[k] as unknown[]).map(String) : [];
+
+  const data: RfcGraphResult = {
+    command: "rfc.graph",
+    status: "ok",
+    id: targetId,
+    supersedes: arr("supersedes"),
+    supersededBy: String(fm["supersededBy"] ?? ""),
+    amends: arr("amends"),
+    amendedBy: arr("amendedBy"),
+    related: arr("related"),
+  };
+
+  if (outputFormat === "pretty") {
+    logger.section(`${targetId} relationships`);
+    logger.info(`supersedes:   ${data.supersedes.join(", ") || "—"}`);
+    logger.info(`supersededBy: ${data.supersededBy || "—"}`);
+    logger.info(`amends:       ${data.amends.join(", ") || "—"}`);
+    logger.info(`amendedBy:    ${data.amendedBy.join(", ") || "—"}`);
+    logger.info(`related:      ${data.related.join(", ") || "—"}`);
+  }
+
+  return {
+    data,
+    summary: `${targetId}: ${data.supersedes.length} supersedes, ${data.amends.length} amends, ${data.related.length} related`,
+  };
+}
+
+export async function runRfcIndexValidate(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    command: string;
+    status: string;
+    violations: { rule: string; message: string }[];
+  }>
+> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+  const indexPath = path.join(rfcDirPath, "index.yaml");
+
+  const violations: { rule: string; message: string }[] = [];
+
+  // RFC-IDX-01: missing index file
+  let indexContent: string;
+  try {
+    indexContent = await fs.readFile(indexPath, "utf-8");
+  } catch {
+    violations.push({
+      rule: "RFC-IDX-01",
+      message:
+        "docs/rfcs/index.yaml not found. Run `pnpm exec werkstatt run rfc.index.generate --write` to generate it.",
+    });
+    const result = { command: "rfc.index.validate", status: "fail", violations };
+    if (outputFormat === "pretty") {
+      logger.error("RFC-IDX-01: docs/rfcs/index.yaml not found.");
+    }
+    return {
+      data: result,
+      exitCode: 1,
+      summary: "1 error(s) found",
+    };
+  }
+
+  // RFC-IDX-02: unparseable YAML
+  let parsed: { entries?: unknown[] } | null;
+  try {
+    parsed = yamlParse(indexContent) as { entries?: unknown[] } | null;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    violations.push({
+      rule: "RFC-IDX-02",
+      message: `Failed to parse docs/rfcs/index.yaml: ${msg}`,
+    });
+    const result = { command: "rfc.index.validate", status: "fail", violations };
+    if (outputFormat === "pretty") {
+      logger.error(`RFC-IDX-02: Failed to parse index.yaml: ${msg}`);
+    }
+    return {
+      data: result,
+      exitCode: 1,
+      summary: "1 error(s) found",
+    };
+  }
+
+  // RFC-IDX-03: count mismatch
+  const indexCount = Array.isArray(parsed?.entries) ? parsed!.entries!.length : 0;
+  const allFiles = await listRfcFiles(rfcDirPath);
+  const fileCount = allFiles.length;
+
+  if (indexCount !== fileCount) {
+    violations.push({
+      rule: "RFC-IDX-03",
+      message: `Index entry count (${indexCount}) does not match RFC file count (${fileCount}). Run \`pnpm exec werkstatt run rfc.index.generate --write\` to refresh.`,
+    });
+  }
+
+  const hasErrors = violations.length > 0;
+  const resultStatus = hasErrors ? "fail" : "pass";
+  const result = { command: "rfc.index.validate", status: resultStatus, violations };
+
+  if (outputFormat === "pretty") {
+    if (hasErrors) {
+      for (const v of violations) {
+        logger.error(`[${v.rule}] ${v.message}`);
+      }
+      logger.error(`${violations.length} error(s) found`);
+    } else {
+      logger.success(`Index valid — ${indexCount} entries match ${fileCount} RFC files.`);
+    }
+  }
+
+  return {
+    data: result,
+    exitCode: hasErrors ? 1 : 0,
+    summary: hasErrors
+      ? `${violations.length} error(s) found`
+      : `Index valid — ${indexCount} entries match ${fileCount} RFC files`,
+  };
+}

package/os/rfc/handlers/lifecycle.test.ts

@@ -0,0 +1,127 @@
+import { test, expect, describe } from "vitest";
+import { collectRfcCommandLifecycleViolations } from "./lifecycle.ts";
+import type { ParsedRfc } from "../frontmatter-io.ts";
+import type { CommandRegistry } from "../../../src/types.ts";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testWorkspaceRoot = join(tmpdir(), "test");
+
+function makeParsed(
+  status: string,
+  createdAt: string,
+  commands: { added?: string[]; changed?: string[] },
+): ParsedRfc {
+  return {
+    frontmatter: {
+      id: "RFC-9999",
+      title: "Test RFC",
+      status,
+      kind: "policy",
+      scope: "workspace",
+      owners: ["architecture"],
+      createdAt,
+      updatedAt: createdAt,
+      commands,
+    },
+    body: "",
+  };
+}
+
+function mockRegistry(commandNames: string[]): CommandRegistry {
+  return {
+    listCommands: () => commandNames.map((name) => ({ name, description: "" })),
+  } as unknown as CommandRegistry;
+}
+
+describe("RFC-CMD-02/03 cutoff behavior", () => {
+  test("pre-cutoff RFC with unregistered command.added → no violation", async () => {
+    const parsed = makeParsed("implemented", "2026-01-01", {
+      added: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd02 = violations.filter((v) => v.rule === "RFC-CMD-02");
+    expect(cmd02).toHaveLength(0);
+  });
+
+  test("post-cutoff RFC with unregistered command.added → violation", async () => {
+    const parsed = makeParsed("implemented", "2026-07-08", {
+      added: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd02 = violations.filter((v) => v.rule === "RFC-CMD-02");
+    expect(cmd02).toHaveLength(1);
+  });
+
+  test("pre-cutoff RFC with unregistered command.changed → no violation", async () => {
+    const parsed = makeParsed("implemented", "2026-01-01", {
+      changed: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd03 = violations.filter((v) => v.rule === "RFC-CMD-03");
+    expect(cmd03).toHaveLength(0);
+  });
+
+  test("post-cutoff RFC with unregistered command.changed → violation", async () => {
+    const parsed = makeParsed("implemented", "2026-07-08", {
+      changed: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd03 = violations.filter((v) => v.rule === "RFC-CMD-03");
+    expect(cmd03).toHaveLength(1);
+  });
+
+  test("exact cutoff date (2026-07-07) → violation (>= cutoff)", async () => {
+    const parsed = makeParsed("implemented", "2026-07-07", {
+      added: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd02 = violations.filter((v) => v.rule === "RFC-CMD-02");
+    expect(cmd02).toHaveLength(1);
+  });
+
+  test("day before cutoff (2026-07-06) → no violation", async () => {
+    const parsed = makeParsed("implemented", "2026-07-06", {
+      added: ["nonexistent.command"],
+    });
+    const preParsed = new Map([["rfc-9999-test.md", { fileName: "rfc-9999-test.md", parsed }]]);
+    const { violations } = await collectRfcCommandLifecycleViolations(
+      testWorkspaceRoot,
+      ["rfc-9999-test.md"],
+      preParsed,
+      mockRegistry([]),
+    );
+    const cmd02 = violations.filter((v) => v.rule === "RFC-CMD-02");
+    expect(cmd02).toHaveLength(0);
+  });
+});

package/os/rfc/handlers/lifecycle.ts

@@ -0,0 +1,249 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC command lifecycle validation — collects and reports RFC-CMD-* violations.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303: extracted lifecycle logic from handlers.ts into handlers/lifecycle.ts.</item>
+  <item>Post-refactor hardening: targeted lifecycle validation resolves RFC ids inside archive subdirectories.</item>
+  <item>RFC-0465: added RFC_METADATA_CUTOFF check to RFC-CMD-02 and RFC-CMD-03 rules — pre-cutoff RFCs are exempt from command registration checks.</item>
+  <item>RFC-0465 fix: added manifest-based fallback in getLiveCommands — reads docs/command-manifest.generated.yaml when commandRegistry returns empty (site-kernel mode).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as yamlParse } from "yaml";
+
+import type { CommandRegistry } from "../../../src/types.ts";
+import {
+  listRfcFiles,
+  readAndParseRfc,
+  rfcFileMatchesId,
+  type ParsedRfc,
+} from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type {
+  RfcStatus,
+  RfcCommandLifecycleViolation,
+  RfcCommandLifecycleValidationResult,
+} from "../types.ts";
+import { RFC_DIR, RFC_METADATA_CUTOFF } from "../types.ts";
+import { commandBuckets } from "./shared.ts";
+
+async function loadManifestCommandNames(workspaceRoot: string): Promise<Set<string>> {
+  const manifestPath = path.join(workspaceRoot, "docs", "command-manifest.generated.yaml");
+  try {
+    const raw = await readFile(manifestPath, "utf-8");
+    const manifest = yamlParse(raw) as { commands?: Array<{ name: string }> };
+    return new Set((manifest.commands ?? []).map((c) => c.name));
+  } catch {
+    return new Set();
+  }
+}
+
+export async function collectRfcCommandLifecycleViolations(
+  workspaceRoot: string,
+  filesToValidate?: string[],
+  preParsed?: Map<string, { fileName: string; parsed: ParsedRfc }>,
+  commandRegistry?: CommandRegistry,
+): Promise<{ checkedCount: number; violations: RfcCommandLifecycleViolation[] }> {
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+  const files = filesToValidate ?? (await listRfcFiles(rfcDirPath));
+
+  let liveCommandsPromise: Promise<Set<string>> | undefined;
+  async function getLiveCommands(): Promise<Set<string>> {
+    if (!liveCommandsPromise) {
+      const cmds = commandRegistry?.listCommands() ?? [];
+      const registryNames = new Set(cmds.map((c) => c.name));
+      const manifestNames = await loadManifestCommandNames(workspaceRoot);
+      const names = new Set([...registryNames, ...manifestNames]);
+      liveCommandsPromise = Promise.resolve(names);
+    }
+    return liveCommandsPromise;
+  }
+
+  const violations: RfcCommandLifecycleViolation[] = [];
+
+  const addViolation = (
+    rfcId: string,
+    file: string,
+    rule: RfcCommandLifecycleViolation["rule"],
+    message: string,
+    severity: "error" | "warning",
+    data: RfcCommandLifecycleViolation["data"],
+  ): void => {
+    violations.push({ rfcId, file, rule, message, severity, data });
+  };
+
+  let checkedCount = 0;
+  for (const fileName of files) {
+    const result = preParsed?.get(fileName) ?? (await readAndParseRfc(rfcDirPath, fileName));
+    if (!result || "error" in result) continue;
+
+    checkedCount += 1;
+    const fm = result.parsed.frontmatter;
+    const rfcId = String(fm["id"] ?? "UNKNOWN");
+    const status = String(fm["status"] ?? "") as RfcStatus;
+    const relFile = path.join(RFC_DIR, fileName);
+    const buckets = commandBuckets(fm);
+    const removed = new Set(buckets.removed);
+    const createdAt = String(fm["createdAt"] ?? "");
+    const isPostCutoff = createdAt >= RFC_METADATA_CUTOFF;
+    const isArchived = fileName.startsWith("archive/");
+
+    // Skip command lifecycle checks for archived RFCs — commands were
+    // renamed/removed during ecosystem consolidation (RFC-0776) and archived
+    // RFCs are frozen historical records that cannot be updated.
+    if (isArchived) continue;
+
+    for (const command of buckets.proposed) {
+      if (
+        status === "implemented" &&
+        (await getLiveCommands()).has(command) &&
+        !buckets.added.includes(command)
+      ) {
+        addViolation(
+          rfcId,
+          relFile,
+          "RFC-CMD-01",
+          `implemented RFC lists live command "${command}" under commands.proposed but not commands.added`,
+          "error",
+          { rfcId, command, status, bucket: "proposed" },
+        );
+      }
+    }
+
+    for (const command of buckets.added) {
+      if (
+        isPostCutoff &&
+        status === "implemented" &&
+        !(await getLiveCommands()).has(command) &&
+        !removed.has(command)
+      ) {
+        addViolation(
+          rfcId,
+          relFile,
+          "RFC-CMD-02",
+          `implemented RFC lists "${command}" under commands.added, but no live command is registered`,
+          "error",
+          { rfcId, command, status, bucket: "added" },
+        );
+      }
+      if ((status === "draft" || status === "reviewing") && !result.parsed.body.includes(command)) {
+        addViolation(
+          rfcId,
+          relFile,
+          "RFC-CMD-04",
+          `non-accepted RFC lists "${command}" under commands.added without body rationale`,
+          "warning",
+          { rfcId, command, status, bucket: "added" },
+        );
+      }
+    }
+
+    for (const command of buckets.changed) {
+      if (
+        isPostCutoff &&
+        status === "implemented" &&
+        !(await getLiveCommands()).has(command) &&
+        !removed.has(command)
+      ) {
+        addViolation(
+          rfcId,
+          relFile,
+          "RFC-CMD-03",
+          `implemented RFC lists "${command}" under commands.changed, but no live command is registered`,
+          "error",
+          { rfcId, command, status, bucket: "changed" },
+        );
+      }
+    }
+
+    for (const command of new Set([...buckets.added, ...buckets.changed])) {
+      if (removed.has(command)) continue;
+      const bucketCount =
+        Number(buckets.added.includes(command)) + Number(buckets.changed.includes(command));
+      if (bucketCount > 1) {
+        addViolation(
+          rfcId,
+          relFile,
+          "RFC-CMD-05",
+          `command "${command}" appears in conflicting lifecycle buckets without commands.removed transition`,
+          "warning",
+          { rfcId, command, status, bucket: buckets.added.includes(command) ? "added" : "changed" },
+        );
+      }
+    }
+  }
+
+  return { checkedCount, violations };
+}
+
+export async function runRfcCommandLifecycleValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcCommandLifecycleValidationResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+  const targetId = input.flags["id"] as string | undefined;
+  const allFiles = await listRfcFiles(rfcDirPath);
+  const filesToValidate = targetId
+    ? allFiles.filter((f) => rfcFileMatchesId(f, targetId))
+    : allFiles;
+
+  if (filesToValidate.length === 0) {
+    if (targetId) {
+      throw new Error(`No RFC file found for id ${targetId} in ${RFC_DIR}/`);
+    }
+    return {
+      data: {
+        command: "rfc.command-lifecycle.validate",
+        status: "pass",
+        count: 0,
+        violations: [],
+      },
+      summary: "No RFC files found to validate",
+    };
+  }
+
+  const { checkedCount, violations } = await collectRfcCommandLifecycleViolations(
+    workspaceRoot,
+    filesToValidate,
+    undefined,
+    context.commandRegistry,
+  );
+  const hasErrors = violations.some((v) => v.severity === "error");
+
+  if (outputFormat === "pretty") {
+    if (violations.length === 0) {
+      logger.success(`All ${checkedCount} RFC(s) passed command lifecycle validation.`);
+    } else {
+      logger.section(`RFC Command Lifecycle Validation (${checkedCount} file(s))`);
+      for (const v of violations) {
+        logger[v.severity === "error" ? "error" : "warn"](
+          `[${v.severity === "error" ? "ERROR" : "WARN"}] ${v.rfcId} ${v.rule}: ${v.message}`,
+        );
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "rfc.command-lifecycle.validate",
+      status: hasErrors ? "fail" : "pass",
+      count: checkedCount,
+      violations,
+    },
+    exitCode: hasErrors ? 1 : 0,
+    summary: hasErrors
+      ? `${violations.filter((v) => v.severity === "error").length} command lifecycle error(s) found`
+      : `All ${checkedCount} RFC(s) passed command lifecycle validation`,
+  };
+}