@warpgogol/forge 2.8.0 → 2.8.2

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 };

package/os/compass/compass.module.ts

@@ -0,0 +1,186 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register the forge Compass command family against the Site OS kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement compass handler logic — delegate to handlers/ inlined by RFC-0556.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial forgeCompassModule registering 12 compass commands.</item>
+  <item>RFC-0538: renamed compass.changesummary.tidy to compass.summary.trim, removed compass.annotate, compass.clear, compass.markup.migrate, compass.invariant.add.</item>
+  <item>RFC-0556: removed dynamic import of @warpgogol/site-kernel-checks, all handlers now inlined in forge/os/compass/handlers/.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+import type { ForgeFlagSpec } from "../../src/types.ts";
+import { runCompassInventory, runCompassValidation } from "./handlers/compass-inventory-handler.ts";
+import {
+  runCompassAuditPlan,
+  runCompassAuditRecord,
+  runCompassAuditBaseline,
+  runCompassAuditValidate,
+} from "./handlers/compass-audit-handler.ts";
+import {
+  runCompassChangeSummaryValidate,
+  runCompassSummaryTrim,
+} from "./handlers/compass-change-summary-handler.ts";
+
+const compassScanFlags = {
+  packages: {
+    kind: "boolean",
+    description: "Scan packages/ instead of the inferred app or default workspace scope.",
+  },
+  package: {
+    kind: "string",
+    description: "With --packages, scan one package by directory/name.",
+  },
+  workpiece: {
+    kind: "string",
+    description:
+      "Scan a mission workpiece directory (RFC-0617). Mutually exclusive with --packages and --site.",
+  },
+} satisfies Record<string, ForgeFlagSpec>;
+
+export const forgeCompassModule: ForgeModule = {
+  name: "forge-compass",
+  version: "0.1.0",
+  async register(registry) {
+    registry.registerCommand({
+      name: "compass.inventory",
+      description: "Generate the repository-wide Compass source inventory XML report.",
+      scope: "workspace",
+      supportsAllSites: true,
+      flags: { ...compassScanFlags },
+      reads: ["packages/**/*.{ts,tsx,md}", "apps/**/*.{ts,tsx,md}", "services/**/*.{ts,tsx,md}"],
+      execute: runCompassInventory,
+    });
+    registry.registerCommand({
+      name: "compass.validate",
+      description:
+        "Validate authored source files against current Compass scaffolding requirements.",
+      scope: "workspace",
+      supportsAllSites: true,
+      flags: { ...compassScanFlags },
+      reads: [
+        "packages/**/*.{ts,tsx,md}",
+        "apps/**/*.{ts,tsx,md}",
+        "services/**/*.{ts,tsx,md}",
+        "docs/source-markup.xml",
+      ],
+      execute: runCompassValidation,
+    });
+    registry.registerCommand({
+      name: "compass.changesummary.validate",
+      description:
+        "Validate CHANGE_SUMMARY blocks for boilerplate items and over-cap unprotected items (RFC-0349).",
+      scope: "workspace",
+      supportsAllSites: true,
+      flags: { ...compassScanFlags },
+      reads: ["packages/**/*.{ts,tsx,md}", "apps/**/*.{ts,tsx,md}", "services/**/*.{ts,tsx,md}"],
+      execute: runCompassChangeSummaryValidate,
+    });
+    registry.registerCommand({
+      name: "compass.summary.trim",
+      description:
+        "Deterministically trim CHANGE_SUMMARY blocks: remove boilerplate, cap total items to 30, preserve protected items (RFC-0538).",
+      scope: "workspace",
+      mutatesState: true,
+      supportsAllSites: true,
+      writes: [
+        "apps/**/*.{astro,ts,tsx,md}",
+        "packages/**/*.{astro,ts,tsx,md}",
+        "services/**/*.{ts,tsx,md}",
+      ],
+      reads: ["packages/**/*.{ts,tsx,md}", "apps/**/*.{ts,tsx,md}", "services/**/*.{ts,tsx,md}"],
+      cacheable: false,
+      flags: { ...compassScanFlags },
+      execute: runCompassSummaryTrim,
+    });
+    registry.registerCommand({
+      name: "compass.audit.plan",
+      description:
+        "Emit a deterministic work-order of files whose revision has advanced past the threshold since their last Compass audit (RFC-0352). Read-only, no LLM.",
+      scope: "workspace",
+      supportsAllSites: true,
+      flags: {
+        ...compassScanFlags,
+        threshold: {
+          kind: "string",
+          description: "Revision distance that makes a file audit-overdue.",
+        },
+      },
+      reads: [
+        "packages/**/*.{ts,tsx,md}",
+        "apps/**/*.{ts,tsx,md}",
+        "services/**/*.{ts,tsx,md}",
+        "docs/compass-audit-ledger.generated.yaml",
+      ],
+      execute: runCompassAuditPlan,
+    });
+    registry.registerCommand({
+      name: "compass.audit.record",
+      description:
+        "Stamp a file's audit verdict and current revision into the compass-audit ledger (RFC-0352). Mutating.",
+      scope: "workspace",
+      mutatesState: true,
+      supportsAllSites: true,
+      writes: ["docs/compass-audit-ledger.generated.yaml"],
+      reads: ["docs/compass-audit-ledger.generated.yaml"],
+      cacheable: false,
+      flags: {
+        file: { kind: "string", required: true, description: "Authored file path to stamp." },
+        verdict: {
+          kind: "string",
+          required: true,
+          description: "Audit verdict: pass, repaired, or baseline.",
+        },
+        agent: { kind: "string", description: "Agent identity to record in the ledger." },
+      },
+      execute: runCompassAuditRecord,
+    });
+    registry.registerCommand({
+      name: "compass.audit.baseline",
+      description:
+        "Seed the compass-audit ledger for every authored file at its current revision with verdict=baseline (RFC-0352). One-time bootstrap.",
+      scope: "workspace",
+      mutatesState: true,
+      supportsAllSites: true,
+      writes: ["docs/compass-audit-ledger.generated.yaml"],
+      reads: ["packages/**/*.{ts,tsx,md}", "apps/**/*.{ts,tsx,md}", "services/**/*.{ts,tsx,md}"],
+      cacheable: false,
+      flags: { ...compassScanFlags },
+      execute: runCompassAuditBaseline,
+    });
+    registry.registerCommand({
+      name: "compass.audit.validate",
+      description:
+        "Validate that no authored file is audit-overdue per the revision threshold (RFC-0352). Warns by default, fails with --strict.",
+      scope: "workspace",
+      supportsAllSites: true,
+      flags: {
+        ...compassScanFlags,
+        strict: {
+          kind: "boolean",
+          description: "Fail when audit-overdue authored files are found.",
+        },
+      },
+      reads: [
+        "packages/**/*.{ts,tsx,md}",
+        "apps/**/*.{ts,tsx,md}",
+        "services/**/*.{ts,tsx,md}",
+        "docs/compass-audit-ledger.generated.yaml",
+      ],
+      execute: runCompassAuditValidate,
+      gate: {
+        severity: "mixed",
+        phase: "author",
+        conditional: {
+          kind: "flag",
+          ref: "--strict",
+          description: "Warns by default, fails with --strict",
+        },
+      },
+    });
+  },
+};