@warpgogol/forge 2.8.0 → 2.8.2

package/os/rfc/handlers/list-create.ts

@@ -0,0 +1,296 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/os/site-kernel/src/rfc/handlers/list-create.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 list and create handlers from handlers.ts into handlers/list-create.ts.</item>
+  <item>Post-refactor hardening: require explicit satisfies DNA traces for new architecture/contract RFC drafts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { toKebabCase } from "../../../src/utils/string-utils.ts";
+import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type {
+  RfcListEntry,
+  RfcListResult,
+  RfcCreateResult,
+  RfcNextIdResult,
+  RfcStatus,
+  RfcKind,
+  RfcScope,
+} from "../types.ts";
+import { RFC_DIR, RFC_KINDS, RFC_SCOPES, RFC_METADATA_CUTOFF } from "../types.ts";
+import { DNA_DOCS, loadInvariantIds, toIsoDate, resolveRfcTemplate } from "./shared.ts";
+import { collectDecisionLog, scoreDecisions } from "../decision-log.ts";
+import type { ConsultedDecision } from "../types.ts";
+
+function parseSatisfiesFlag(value: unknown): string[] {
+  if (typeof value !== "string") return [];
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+async function assertSatisfiesIdsExist(workspaceRoot: string, satisfies: string[]): Promise<void> {
+  if (satisfies.length === 0) return;
+
+  const validDnaIds = await loadInvariantIds(workspaceRoot, DNA_DOCS, "DNA");
+  const errors: string[] = [];
+
+  for (const id of satisfies) {
+    if (!/^DNA-\d+$/.test(id)) {
+      errors.push(`Malformed satisfies entry: "${id}". Must match DNA-N.`);
+      continue;
+    }
+    if (!validDnaIds.has(parseInt(id.slice(4), 10))) {
+      errors.push(`Unknown DNA invariant: ${id} (not found in ${DNA_DOCS.join(", ")}).`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join(" "));
+  }
+}
+
+export async function runRfcList(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcListResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const filterStatus = input.flags["status"] as string | undefined;
+  const filterKind = input.flags["kind"] as string | undefined;
+  const filterOwner = input.flags["owner"] as string | undefined;
+  const filterBatch = input.flags["batch"] as string | undefined;
+
+  const files = await listRfcFiles(rfcDirPath);
+  const entries: RfcListEntry[] = [];
+
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    if (!result || "error" in result) continue;
+
+    const fm = result.parsed.frontmatter;
+    const id = String(fm["id"] ?? "");
+    const status = String(fm["status"] ?? "") as RfcStatus;
+    const kind = String(fm["kind"] ?? "") as RfcKind;
+    const scope = String(fm["scope"] ?? "") as RfcScope;
+    const owners = Array.isArray(fm["owners"]) ? (fm["owners"] as string[]) : [];
+
+    if (filterStatus && status !== filterStatus) continue;
+    if (filterKind && kind !== filterKind) continue;
+    if (filterOwner && !owners.includes(filterOwner)) continue;
+    if (filterBatch && String(fm["batch"] ?? "") !== filterBatch) continue;
+
+    entries.push({
+      id,
+      title: String(fm["title"] ?? ""),
+      status,
+      kind,
+      scope,
+      owners,
+      createdAt: String(fm["createdAt"] ?? ""),
+      updatedAt: String(fm["updatedAt"] ?? ""),
+      file: path.join(RFC_DIR, fileName),
+      batch: fm["batch"] ? String(fm["batch"]) : undefined,
+      dependsOn: Array.isArray(fm["dependsOn"]) ? (fm["dependsOn"] as string[]) : undefined,
+    });
+  }
+
+  if (outputFormat === "pretty") {
+    if (entries.length === 0) {
+      logger.info("No RFCs found matching the given filters.");
+    } else {
+      logger.section(`RFCs (${entries.length})`);
+      for (const entry of entries) {
+        const ownerStr = entry.owners.join(", ");
+        logger.info(
+          `${entry.id}  ${entry.status.padEnd(12)} ${entry.kind.padEnd(14)} ${entry.title}  [${ownerStr}]`,
+        );
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "rfc.list",
+      status: "ok",
+      count: entries.length,
+      entries,
+    },
+    summary: `${entries.length} RFC(s) found`,
+  };
+}
+
+export async function runRfcCreate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcCreateResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const title = input.flags["title"] as string | undefined;
+  if (!title) {
+    throw new Error(
+      'rfc.create requires --title flag, e.g. --title "Add structure.validate command"',
+    );
+  }
+
+  const kind = (input.flags["kind"] as string | undefined) ?? "architecture";
+  const scope = (input.flags["scope"] as string | undefined) ?? "workspace";
+  const satisfies = parseSatisfiesFlag(input.flags["satisfies"]);
+
+  if (!RFC_KINDS.includes(kind as RfcKind)) {
+    throw new Error(`Invalid kind: ${kind}. Must be one of: ${RFC_KINDS.join(", ")}`);
+  }
+  if (!RFC_SCOPES.includes(scope as RfcScope)) {
+    throw new Error(`Invalid scope: ${scope}. Must be one of: ${RFC_SCOPES.join(", ")}`);
+  }
+
+  const today = toIsoDate(new Date());
+  const requiresSatisfies =
+    today >= RFC_METADATA_CUTOFF && (kind === "architecture" || kind === "contract");
+
+  if (requiresSatisfies && satisfies.length === 0) {
+    throw new Error(
+      `rfc.create requires --satisfies DNA-N for ${kind} RFCs created on or after ${RFC_METADATA_CUTOFF} (RFC-0331).`,
+    );
+  }
+  await assertSatisfiesIdsExist(workspaceRoot, satisfies);
+
+  const files = await listRfcFiles(rfcDirPath);
+  let maxId = 0;
+  for (const f of files) {
+    const basename = path.basename(f);
+    const match = basename.match(/^rfc-(\d{4})/);
+    if (match) {
+      const num = parseInt(match[1]!, 10);
+      if (num > maxId) maxId = num;
+    }
+  }
+  const nextNum = maxId + 1;
+  const paddedNum = String(nextNum).padStart(4, "0");
+  const nextSlug = `rfc-${paddedNum}`;
+  const nextId = `RFC-${paddedNum}`;
+
+  const templatePath = resolveRfcTemplate(workspaceRoot);
+  let templateContent: string;
+  try {
+    templateContent = await fs.readFile(templatePath, "utf-8");
+  } catch {
+    throw new Error(`RFC template not found at ${templatePath}.`);
+  }
+
+  const kebabTitle = toKebabCase(title);
+  const fileName = `${nextSlug}-${kebabTitle}.md`;
+
+  // RFC-0329: consult decision log before scaffolding
+  let consultedDecisions: ConsultedDecision[] = [];
+  try {
+    const logEntries = await collectDecisionLog(rfcDirPath);
+    consultedDecisions = scoreDecisions(title, logEntries);
+  } catch {
+    // graceful degradation — never block creation
+  }
+
+  if (outputFormat === "pretty") {
+    if (consultedDecisions.length > 0) {
+      logger.info("Prior decisions to consult:");
+      for (const d of consultedDecisions) {
+        logger.info(`  ${d.rfcId} [${d.kind}] (score ${d.score}): ${d.title}`);
+      }
+    } else {
+      logger.info("No related prior decisions found.");
+    }
+  }
+
+  let content = templateContent;
+  content = content.replace(/^id: RFC-0000$/m, `id: ${nextId}`);
+  content = content.replace(/^title: ".*"$/m, `title: "${title}"`);
+  content = content.replace(/^kind: \w+$/m, `kind: ${kind}`);
+  content = content.replace(/^scope: \w+$/m, `scope: ${scope}`);
+  content = content.replace(/^createdAt: YYYY-MM-DD$/m, `createdAt: ${today}`);
+  content = content.replace(/^updatedAt: YYYY-MM-DD$/m, `updatedAt: ${today}`);
+  if (satisfies.length > 0) {
+    content = content.replace(
+      /^satisfies: \[\]$/m,
+      `satisfies:\n${satisfies.map((id) => `  - ${id}`).join("\n")}`,
+    );
+  }
+  content = content.replace(/^# RFC-0000: .+$/m, `# ${nextId}: ${title}`);
+
+  const targetPath = path.join(rfcDirPath, fileName);
+  await fs.writeFile(targetPath, content, "utf-8");
+
+  const relativeFile = path.join(RFC_DIR, fileName);
+
+  if (outputFormat === "pretty") {
+    logger.success(`Created ${nextId}: ${title}`);
+    logger.info(`File: ${relativeFile}`);
+    logger.info(`Template: full`);
+    logger.info("Status: draft (only a human with role 'architecture' may change status)");
+  }
+
+  return {
+    data: {
+      command: "rfc.create",
+      status: "ok",
+      file: relativeFile,
+      id: nextId,
+      satisfies,
+      consultedDecisions,
+    },
+    summary: `Created ${nextId}: ${title}`,
+  };
+}
+
+export async function runRfcNextId(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcNextIdResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const files = await listRfcFiles(rfcDirPath);
+  let maxId = 0;
+  for (const f of files) {
+    const basename = path.basename(f);
+    const match = basename.match(/^rfc-(\d{4})/);
+    if (match) {
+      const num = parseInt(match[1]!, 10);
+      if (num > maxId) maxId = num;
+    }
+  }
+
+  const nextNumber = maxId + 1;
+  const paddedNum = String(nextNumber).padStart(4, "0");
+  const nextId = `RFC-${paddedNum}`;
+  const maxExistingId = maxId > 0 ? `RFC-${String(maxId).padStart(4, "0")}` : "none";
+
+  if (outputFormat === "pretty") {
+    logger.info(`Next free RFC number: ${nextId} (scanned ${files.length} files)`);
+  }
+
+  return {
+    data: {
+      command: "rfc.next-id",
+      nextId,
+      nextNumber,
+      maxExistingId,
+      scannedFiles: files.length,
+    },
+    summary: `Next RFC number: ${nextId}`,
+  };
+}

package/os/rfc/handlers/pipeline-status.ts

@@ -0,0 +1,173 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Reports the pipeline status of RFCs — which steps (audit, enhance, plan, implement) are complete or missing.</purpose>
+<non-goals>
+  <item>Does not validate RFC content — use rfc.validate for that.</item>
+  <item>Does not mutate any files.</item>
+  <item>Does not gate skill execution — skills keep their own prerequisite checks.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Add rfc.pipeline.status command for agents and humans to inspect where an RFC stands in the create → audit → enhance → plan → implement pipeline.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { listRfcFiles, readAndParseRfc } from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type { RfcStatus } from "../types.ts";
+import { RFC_DIR } from "../types.ts";
+
+export type PipelineStage = "audit" | "enhance" | "plan" | "implement";
+
+export interface RfcPipelineStageInfo {
+  stage: PipelineStage;
+  done: boolean;
+  /** File or marker that confirms completion, when applicable. */
+  evidence?: string;
+}
+
+export interface RfcPipelineEntry {
+  id: string;
+  title: string;
+  status: RfcStatus;
+  file: string;
+  stages: RfcPipelineStageInfo[];
+  /** The immediate next missing step, or null if all are done. */
+  nextStep: PipelineStage | null;
+}
+
+export interface RfcPipelineStatusResult {
+  command: "rfc.pipeline.status";
+  status: "ok";
+  count: number;
+  entries: RfcPipelineEntry[];
+}
+
+const TERMINAL_STATUSES: ReadonlySet<string> = new Set(["implemented", "rejected", "superseded"]);
+
+async function findAuditFile(workspaceRoot: string, rfcId: string): Promise<string | undefined> {
+  const auditsDir = path.join(workspaceRoot, "docs/audits");
+  try {
+    const entries = await fs.readdir(auditsDir);
+    const prefix = `audit-${rfcId.toLowerCase()}`;
+    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
+    return match ? path.join("docs/audits", match) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function findPlanFile(workspaceRoot: string, rfcId: string): Promise<string | undefined> {
+  const plansDir = path.join(workspaceRoot, "docs/plans");
+  try {
+    const entries = await fs.readdir(plansDir);
+    const prefix = `plan-${rfcId.toLowerCase()}`;
+    const match = entries.find((e) => e.toLowerCase().startsWith(prefix) && e.endsWith(".md"));
+    return match ? path.join("docs/plans", match) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function runRfcPipelineStatus(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcPipelineStatusResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = path.join(workspaceRoot, RFC_DIR);
+
+  const targetId = input.flags["id"] as string | undefined;
+
+  let files = await listRfcFiles(rfcDirPath);
+  if (targetId) {
+    const lower = targetId.toLowerCase();
+    files = files.filter((f) => path.basename(f).toLowerCase().startsWith(lower));
+    if (files.length === 0) {
+      throw new Error(`No RFC file found for id ${targetId} in ${RFC_DIR}/`);
+    }
+  }
+
+  const entries: RfcPipelineEntry[] = [];
+
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    if (!result || "error" in result) continue;
+    const fm = result.parsed.frontmatter;
+    const id = String(fm["id"] ?? "");
+    const title = String(fm["title"] ?? "");
+    const status = String(fm["status"] ?? "") as RfcStatus;
+    const enhancedAt = fm["enhancedAt"] ? String(fm["enhancedAt"]) : undefined;
+    const implementedAt = fm["implementedAt"] ? String(fm["implementedAt"]) : undefined;
+
+    const isTerminal = TERMINAL_STATUSES.has(status);
+
+    const auditFile = await findAuditFile(workspaceRoot, id);
+    const planFile = await findPlanFile(workspaceRoot, id);
+
+    const stages: RfcPipelineStageInfo[] = [
+      {
+        stage: "audit",
+        done: !!auditFile,
+        evidence: auditFile,
+      },
+      {
+        stage: "enhance",
+        done: !!enhancedAt,
+        evidence: enhancedAt ? `enhancedAt: ${enhancedAt}` : undefined,
+      },
+      {
+        stage: "plan",
+        done: !!planFile,
+        evidence: planFile,
+      },
+      {
+        stage: "implement",
+        done: status === "implemented" || !!implementedAt,
+        evidence: implementedAt ? `implementedAt: ${implementedAt}` : undefined,
+      },
+    ];
+
+    let nextStep: PipelineStage | null = null;
+    if (!isTerminal) {
+      for (const s of stages) {
+        if (!s.done) {
+          nextStep = s.stage;
+          break;
+        }
+      }
+    }
+
+    entries.push({
+      id,
+      title,
+      status,
+      file: path.join(RFC_DIR, fileName),
+      stages,
+      nextStep,
+    });
+  }
+
+  entries.sort((a, b) => a.id.localeCompare(b.id));
+
+  if (outputFormat === "pretty") {
+    logger.section(`RFC pipeline status (${entries.length} RFC(s))`);
+    for (const entry of entries) {
+      const stageStr = entry.stages.map((s) => `${s.stage}:${s.done ? "✓" : "—"}`).join("  ");
+      const next = entry.nextStep ? ` → next: ${entry.nextStep}` : "";
+      const terminal = TERMINAL_STATUSES.has(entry.status) ? " (terminal)" : "";
+      logger.info(`${entry.id} [${entry.status}${terminal}]  ${stageStr}${next}`);
+    }
+  }
+
+  return {
+    data: { command: "rfc.pipeline.status", status: "ok", count: entries.length, entries },
+    summary: `Pipeline status for ${entries.length} RFC(s)`,
+  };
+}

package/os/rfc/handlers/shared.ts

@@ -0,0 +1,121 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared helpers for RFC handler commands — date utils, invariant ID loading, FS path checks, command bucket parsing.</purpose>
+<non-goals>
+  <item>Do not implement command handlers; those live in sibling files.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303: extracted shared helpers from handlers.ts into handlers/shared.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveForgeRoot } from "../../../src/config/forge-config.ts";
+import { RFC_TEMPLATE_FILE, RFC_TEMPLATE_FALLBACK_FILE } from "../types.ts";
+import type { ParsedRfc } from "../frontmatter-io.ts";
+
+export function toIsoDate(date: Date): string {
+  return date.toISOString().split("T")[0]!;
+}
+
+const DNA_DOC = "docs/architecture-dna.md";
+const AP_DOC = "packages/os/site-kernel/docs/anti-patterns.md";
+export const DNA_DOCS = [DNA_DOC];
+export const AP_DOCS = [AP_DOC];
+
+/** Parse `## <PREFIX>-N` headings from the given docs and return the set of N. */
+export async function loadInvariantIds(
+  workspaceRoot: string,
+  relPaths: string[],
+  prefix: string,
+): Promise<Set<number>> {
+  const ids = new Set<number>();
+  const re = new RegExp(`^##\\s+${prefix}-(\\d+)\\b`, "gm");
+  for (const rel of relPaths) {
+    try {
+      const src = await fs.readFile(path.join(workspaceRoot, rel), "utf-8");
+      for (const m of src.matchAll(re)) ids.add(parseInt(m[1]!, 10));
+    } catch {
+      // Doc not present at this path — try the next candidate.
+    }
+  }
+  return ids;
+}
+
+/**
+ * Whether a "File system responsibilities" path is a concrete, checkable file.
+ * Skips glob/placeholder/prose entries that rfc.check must not `fs.access` verbatim:
+ * `apps/*`, `apps/<app>/…`, `{lang}`, `**`, or descriptive phrases with spaces.
+ */
+export function isLiteralFsPath(p: string): boolean {
+  if (/[*<>{}]/.test(p)) return false; // globs / placeholders
+  if (/\s/.test(p)) return false; // prose ("Every generator module")
+  if (!p.includes("/") && !p.includes(".")) return false; // bare words
+  return true;
+}
+
+export function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+export function commandBuckets(fm: Record<string, unknown>): {
+  proposed: string[];
+  added: string[];
+  changed: string[];
+  removed: string[];
+} {
+  const commands = fm["commands"];
+  if (!commands || typeof commands !== "object" || Array.isArray(commands)) {
+    return { proposed: [], added: [], changed: [], removed: [] };
+  }
+  const record = commands as Record<string, unknown>;
+  return {
+    proposed: stringArray(record["proposed"]),
+    added: stringArray(record["added"]),
+    changed: stringArray(record["changed"]),
+    removed: stringArray(record["removed"]),
+  };
+}
+
+export type { ParsedRfc };
+
+// ---------------------------------------------------------------------------
+// RFC template resolver — finds rfc-0000-template.md from project docs/rfcs/
+// first (canonical location, mirroring ADR pattern), then falls back to the
+// forge package copy (npm consumers without a project-level template).
+// ---------------------------------------------------------------------------
+
+export function resolveRfcTemplate(workspaceRoot: string): string {
+  // 1. Try project-level docs/rfcs/rfc-0000-template.md (canonical, like ADR)
+  const projectPath = path.join(workspaceRoot, RFC_TEMPLATE_FILE);
+  if (existsSync(projectPath)) return projectPath;
+
+  // 2. Try forge root (monorepo or npm-installed) — fallback copy
+  try {
+    const forgeRoot = resolveForgeRoot(workspaceRoot);
+    const p = path.join(forgeRoot, RFC_TEMPLATE_FALLBACK_FILE);
+    if (existsSync(p)) return p;
+  } catch {
+    // forge root not resolvable — fall through to module-relative search
+  }
+
+  // 3. Fallback: walk up from this module's location to find os/rfc/rfc-0000-template.md
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  let dir = here;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, "os", "rfc", "rfc-0000-template.md");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(
+    `RFC template not found. Tried ${RFC_TEMPLATE_FILE} relative to ${workspaceRoot}, forge root, and module-relative search from ${here}.`,
+  );
+}