@warpgogol/forge 2.7.0 → 2.8.1

package/os/adr/types.ts

@@ -0,0 +1,141 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Defines types and constants for managing Architectural Decision Records (ADRs):
+statuses, scopes, frontmatter shape, validation results, and list output.
+</purpose>
+<non-goals>
+  <item>Do not implement ADR processing or validation logic here.</item>
+  <item>Do not handle user input or command execution related to ADRs.</item>
+  <item>Do not manage the storage or retrieval of ADR documents.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0366: introduce ADR types and constants mirroring the RFC domain contract.</item>
+  <item>RFC-0367: extend AdrStatus with reviewing and implemented; add implementedAt, closedAt, reviewers fields.</item>
+  <item>Post-refactor hardening: document that an ADR may be superseded by a broader RFC.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+  <item>RFC-0727: add AdrImplementStamp types for atomic ADR status transition.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type AdrStatus =
+  "proposed" | "reviewing" | "accepted" | "implemented" | "superseded" | "rejected";
+
+export const ADR_STATUSES: readonly AdrStatus[] = [
+  "proposed",
+  "reviewing",
+  "accepted",
+  "implemented",
+  "superseded",
+  "rejected",
+] as const;
+
+export type AdrScope = "package" | "app" | "workspace";
+
+export const ADR_SCOPES: readonly AdrScope[] = ["package", "app", "workspace"] as const;
+
+export interface AdrFrontmatter {
+  id: string;
+  title: string;
+  status: AdrStatus;
+  scope: AdrScope;
+  decider: string;
+  createdAt: string;
+  updatedAt: string;
+  supersedes?: string[];
+  supersededBy?: string;
+  related?: string[];
+  implementedAt?: string;
+  closedAt?: string;
+  reviewers?: string[];
+}
+
+export interface AdrListEntry {
+  id: string;
+  title: string;
+  status: AdrStatus;
+  scope: AdrScope;
+  decider: string;
+  updatedAt: string;
+  file: string;
+}
+
+export interface AdrListResult {
+  command: "adr.list";
+  status: "ok";
+  count: number;
+  entries: AdrListEntry[];
+}
+
+export interface AdrValidationViolation {
+  adrId: string;
+  file: string;
+  rule: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+export interface AdrValidationResult {
+  command: "adr.validate";
+  status: "pass" | "fail";
+  count: number;
+  violations: AdrValidationViolation[];
+}
+
+export interface AdrCreateResult {
+  command: "adr.create";
+  status: "ok";
+  file: string;
+  id: string;
+}
+
+export const ADR_DIR = "docs/adrs";
+export const ADR_TEMPLATE_FILE = "docs/adrs/adr-0000-template.md";
+export const ADR_ID_PATTERN = /^ADR-\d{4}$/;
+
+export const ADR_REQUIRED_SECTIONS = [
+  "Context",
+  "Decision",
+  "Justification",
+  "Consequences",
+  "Evolution",
+] as const;
+
+export const ADR_KNOWN_KEYS: readonly string[] = [
+  "id",
+  "title",
+  "status",
+  "scope",
+  "decider",
+  "createdAt",
+  "updatedAt",
+  "supersedes",
+  "supersededBy",
+  "related",
+  "implementedAt",
+  "closedAt",
+  "reviewers",
+] as const;
+
+// ─── RFC-0727: adr.implement.stamp types ─────────────────────────────────────
+
+export type AdrImplementStampRule = "ADR-IMP-01" | "ADR-IMP-03" | "ADR-IMP-04" | "ADR-IMP-05";
+
+export interface AdrImplementStampData {
+  adrId: string;
+  implementationCommit: string;
+  stampedAt: string;
+}
+
+export interface AdrImplementStampViolation {
+  rule: AdrImplementStampRule;
+  message: string;
+}
+
+export interface AdrImplementStampResult {
+  command: "adr.implement.stamp";
+  status: "pass" | "fail";
+  data?: AdrImplementStampData;
+  violations: AdrImplementStampViolation[];
+}

package/os/audit/audit.module.ts

@@ -0,0 +1,48 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the audit archive command with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/archive.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial forgeAuditModule registering audit.archive command.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeAuditModule: ForgeModule = {
+  name: "forge-audit",
+  version: "0.1.0",
+  async register(registry) {
+    const { runAuditArchive } = await import("./handlers/archive.ts");
+
+    registry.registerCommand({
+      name: "audit.archive",
+      description:
+        "Move audit files whose parent RFC has terminal status " +
+        "(implemented, rejected, superseded) into docs/audits/archive/<status>/ " +
+        "subdirectories. Bidirectional: moves non-terminal files found in " +
+        "subdirectories back to root. Use --dry-run to preview. " +
+        "Use --status to filter to a single terminal status. " +
+        "Prefer the docs.archive umbrella command unless you need to archive only audits.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/audits/*.md", "docs/audits/archive/**"],
+      reads: ["docs/audits/**/*.md", "docs/rfcs/**/*.md"],
+      cacheable: false,
+      flags: {
+        "dry-run": {
+          kind: "boolean",
+          description: "Preview what would be moved without touching the filesystem.",
+        },
+        status: {
+          kind: "string",
+          description: "Filter to a single terminal status (implemented, rejected, superseded).",
+        },
+      },
+      execute: runAuditArchive,
+    });
+  },
+};

package/os/audit/frontmatter-io.ts

@@ -0,0 +1,84 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Audit frontmatter file I/O — recursive file discovery and YAML frontmatter
+parsing for audit files under docs/audits/. Only files matching the
+audit-rfc-XXXX-* pattern are candidates for archiving; standalone audits
+are silently excluded.
+</purpose>
+<non-goals>
+  <item>Do not validate audit content.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial audit frontmatter I/O.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { AUDIT_RFC_FILE_PATTERN } from "./types.ts";
+
+export interface ParsedAudit {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseAuditFile(source: string): ParsedAudit {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: source };
+  }
+  return {
+    frontmatter: (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>,
+    body: match[2] ?? "",
+  };
+}
+
+export async function listAuditFiles(auditDirPath: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await scanDir(path.join(dirPath, entry.name), relativePath);
+        } else if (
+          entry.isFile() &&
+          entry.name.endsWith(".md") &&
+          !entry.name.startsWith("audit-0000") &&
+          entry.name !== "README.md" &&
+          AUDIT_RFC_FILE_PATTERN.test(entry.name)
+        ) {
+          results.push(relativePath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or is unreadable — return empty
+    }
+  }
+
+  await scanDir(auditDirPath, "");
+  return results.sort();
+}
+
+export async function readAndParseAudit(
+  auditDirPath: string,
+  fileName: string,
+): Promise<{ fileName: string; parsed: ParsedAudit } | undefined> {
+  try {
+    const filePath = path.join(auditDirPath, fileName);
+    const content = await fs.readFile(filePath, "utf-8");
+    return { fileName, parsed: parseAuditFile(content) };
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractRfcIdFromAuditFile(fileName: string): string | undefined {
+  const match = path.basename(fileName).match(/^audit-(rfc-\d{4})-/i);
+  return match ? match[1]!.toUpperCase() : undefined;
+}

package/os/audit/handlers/archive.ts

@@ -0,0 +1,239 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Audit archive handler — moves audit files whose parent RFC has terminal status
+into status-specific subdirectories under docs/audits/archive/ and moves
+non-terminal files found in subdirectories back to the root. Standalone audit
+files (not matching audit-rfc-XXXX-*) are silently excluded.
+</purpose>
+<non-goals>
+  <item>Does not validate audit content.</item>
+  <item>Does not change audit frontmatter — only moves files on disk.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: implement audit.archive command.</item>
+  <item>RFC-0733: add pinned-files pre-check — skip pinned files with warning instead of moving them.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { listAuditFiles, extractRfcIdFromAuditFile } from "../frontmatter-io.ts";
+import { loadRfcStatusMap } from "../../rfc/frontmatter-io.ts";
+import type { ArchiveMove, ArchiveSkip } from "../../rfc/handlers/archive.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { AUDIT_DIR } from "../types.ts";
+import type { AuditArchiveResult } from "../types.ts";
+import { loadPinnedManifest, isPinned, isIntraDirMove } from "../../core/handlers/pinned-check.ts";
+
+const TERMINAL_STATUSES = ["implemented", "rejected", "superseded"] as const;
+
+export async function runAuditArchive(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<AuditArchiveResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const auditDirPath = path.join(workspaceRoot, AUDIT_DIR);
+  const rfcDirPath = path.join(workspaceRoot, "docs", "rfcs");
+
+  const dryRun = context.dryRun || input.flags["dry-run"] === true;
+  const statusFilter = input.flags["status"] as string | undefined;
+
+  if (statusFilter && !TERMINAL_STATUSES.includes(statusFilter as never)) {
+    throw new Error(
+      `Invalid --status "${statusFilter}". Must be one of: ${TERMINAL_STATUSES.join(", ")}`,
+    );
+  }
+
+  const files = await listAuditFiles(auditDirPath);
+  const rfcStatusMap = await loadRfcStatusMap(rfcDirPath);
+  const moved: ArchiveMove[] = [];
+  const skipped: ArchiveSkip[] = [];
+
+  // RFC-0733: Load pinned manifest once per invocation
+  let pinnedManifest = null;
+  try {
+    pinnedManifest = await loadPinnedManifest(workspaceRoot);
+  } catch {
+    // Malformed manifest — skip pre-check
+  }
+
+  for (const fileName of files) {
+    const rfcId = extractRfcIdFromAuditFile(fileName);
+    const relFile = path.join(AUDIT_DIR, fileName);
+    const basename = path.basename(fileName);
+
+    if (!rfcId) {
+      skipped.push({ id: "UNKNOWN", file: relFile, reason: "no RFC id in filename" });
+      continue;
+    }
+
+    const rfcStatus = rfcStatusMap.get(rfcId);
+    if (!rfcStatus) {
+      skipped.push({ id: rfcId, file: relFile, reason: "parent RFC not found" });
+      continue;
+    }
+
+    const isTerminal =
+      rfcStatus === "implemented" || rfcStatus === "rejected" || rfcStatus === "superseded";
+    const isInArchive = fileName.includes("/");
+
+    if (statusFilter && rfcStatus !== statusFilter) {
+      skipped.push({
+        id: rfcId,
+        file: relFile,
+        reason: `parent RFC status ${rfcStatus} does not match --status ${statusFilter}`,
+      });
+      continue;
+    }
+
+    if (isTerminal && !isInArchive) {
+      const targetDir = path.join(auditDirPath, "archive", rfcStatus);
+      const targetPath = path.join(targetDir, basename);
+      const targetRel = path.join(AUDIT_DIR, "archive", rfcStatus, basename);
+
+      // RFC-0733: Check if file is pinned before moving
+      // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+      if (
+        pinnedManifest &&
+        isPinned(pinnedManifest, relFile) &&
+        !isIntraDirMove(pinnedManifest, relFile, targetRel)
+      ) {
+        skipped.push({
+          id: rfcId,
+          file: relFile,
+          reason: "pinned (protected by .forge/pinned.yaml)",
+        });
+        if (outputFormat === "pretty") {
+          logger.warn(`  pinned: skipping ${relFile} (protected)`);
+        }
+        continue;
+      }
+
+      try {
+        await fs.access(targetPath);
+        skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
+        continue;
+      } catch {
+        // destination doesn't exist — proceed
+      }
+
+      if (!dryRun) {
+        await fs.mkdir(targetDir, { recursive: true });
+        try {
+          await fs.rename(path.join(auditDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id: rfcId, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id: rfcId,
+        file: targetRel,
+        status: rfcStatus,
+        from: relFile,
+        to: targetRel,
+        direction: "into-archive",
+      });
+    } else if (!isTerminal && isInArchive) {
+      const targetPath = path.join(auditDirPath, basename);
+      const targetRel = path.join(AUDIT_DIR, basename);
+
+      // RFC-0733: Check if file is pinned before moving
+      // Gap fix: exempt intra-directory moves (file stays within the same pinned dir)
+      if (
+        pinnedManifest &&
+        isPinned(pinnedManifest, relFile) &&
+        !isIntraDirMove(pinnedManifest, relFile, targetRel)
+      ) {
+        skipped.push({
+          id: rfcId,
+          file: relFile,
+          reason: "pinned (protected by .forge/pinned.yaml)",
+        });
+        if (outputFormat === "pretty") {
+          logger.warn(`  pinned: skipping ${relFile} (protected)`);
+        }
+        continue;
+      }
+
+      try {
+        await fs.access(targetPath);
+        skipped.push({ id: rfcId, file: relFile, reason: "destination exists" });
+        continue;
+      } catch {
+        // destination doesn't exist — proceed
+      }
+
+      if (!dryRun) {
+        try {
+          await fs.rename(path.join(auditDirPath, fileName), targetPath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+            skipped.push({ id: rfcId, file: relFile, reason: "already moved by another process" });
+            continue;
+          }
+          throw err;
+        }
+      }
+
+      moved.push({
+        id: rfcId,
+        file: targetRel,
+        status: rfcStatus,
+        from: relFile,
+        to: targetRel,
+        direction: "out-of-archive",
+      });
+    } else if (isTerminal && isInArchive) {
+      skipped.push({ id: rfcId, file: relFile, reason: `already archived (${rfcStatus})` });
+    } else {
+      skipped.push({
+        id: rfcId,
+        file: relFile,
+        reason: `parent RFC status ${rfcStatus} is non-terminal`,
+      });
+    }
+  }
+
+  if (outputFormat === "pretty") {
+    if (dryRun) {
+      logger.info(
+        `[dry-run] audit.archive: would move ${moved.length} file(s), skip ${skipped.length}`,
+      );
+    } else {
+      logger.success(`audit.archive: moved ${moved.length} file(s), skipped ${skipped.length}`);
+    }
+    for (const m of moved) {
+      logger.info(`  ${m.direction}: ${m.id} (${m.status}) ${m.from} → ${m.to}`);
+    }
+  }
+
+  return {
+    data: {
+      command: "audit.archive",
+      status: "ok",
+      moved,
+      skipped,
+      dryRun,
+    },
+    summary: dryRun
+      ? `[dry-run] Would move ${moved.length} file(s), skip ${skipped.length}`
+      : `Moved ${moved.length} file(s), skipped ${skipped.length}`,
+    nextSteps: [
+      {
+        action: "Run: pnpm exec werkstatt run audit.list --json to verify archive status",
+        kind: "optional",
+      },
+    ],
+  };
+}

package/os/audit/index.ts

@@ -0,0 +1,23 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the audit domain — types, module, and handlers.</purpose>
+<non-goals>
+  <item>Do not implement audit logic here; delegate to handlers/ and audit.module.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial audit module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeAuditModule } from "./audit.module.ts";
+export { runAuditArchive } from "./handlers/archive.ts";
+export {
+  listAuditFiles,
+  parseAuditFile,
+  readAndParseAudit,
+  extractRfcIdFromAuditFile,
+  type ParsedAudit,
+} from "./frontmatter-io.ts";
+export type { AuditArchiveResult, AuditArchiveMove, AuditArchiveSkip } from "./types.ts";
+export { AUDIT_DIR, AUDIT_RFC_FILE_PATTERN } from "./types.ts";

package/os/audit/types.ts

@@ -0,0 +1,29 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Type definitions for the audit archive domain — audit file discovery, parsing,
+and archive result shapes.
+</purpose>
+<non-goals>
+  <item>Do not define archive handler logic here — that lives in handlers/archive.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0521: initial audit archive types.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ArchiveMove, ArchiveSkip } from "../rfc/handlers/archive.ts";
+
+export const AUDIT_DIR = "docs/audits";
+export const AUDIT_RFC_FILE_PATTERN = /^audit-rfc-\d{4}-/;
+
+export interface AuditArchiveResult {
+  command: "audit.archive";
+  status: "ok";
+  moved: ArchiveMove[];
+  skipped: ArchiveSkip[];
+  dryRun: boolean;
+}
+
+export type { ArchiveMove as AuditArchiveMove, ArchiveSkip as AuditArchiveSkip };