@warpgogol/forge 2.8.0 → 2.8.2

package/os/compass/handlers/compass-audit-handler.ts

@@ -0,0 +1,382 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Compass audit command handlers (plan, record, baseline, validate).
+Moved from @warpgogol/site-kernel-checks to @warpgogol/forge for full autonomous
+mode (RFC-0556). Drives per-file semantic-truth auditing on a revision cadence (RFC-0352).</purpose>
+<non-goals>
+  <item>Do not perform semantic comparison inside a command — commands are deterministic; the code-vs-prose judgment is the agent's.</item>
+  <item>Do not call an LLM or read any API key.</item>
+  <item>Do not replace compass.validate — this adds a heavy truth audit on top.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0352: initial implementation of compass.audit.plan, compass.audit.record, compass.audit.baseline, compass.audit.validate.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createCompassInventoryEntries } from "./compass-inventory.ts";
+import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
+import { getRevisionByPath } from "./git-revision.ts";
+import type { CompassInventoryEntry } from "./compass-inventory.ts";
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
+import { buildGeneratedHeader } from "../../../src/utils/generated-marker.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+
+const execFileAsync = promisify(execFile);
+const LEDGER_PATH = "docs/compass-audit-ledger.generated.yaml";
+const DEFAULT_THRESHOLD = 30;
+
+function resolveRevisionThreshold(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback;
+  const parsed = typeof value === "number" ? value : Number(String(value));
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+type CompassAuditVerdict = "pass" | "repaired" | "baseline";
+
+interface CompassAuditLedgerEntry {
+  path: string;
+  entityId: string;
+  auditedRevision: number;
+  auditedHash: string;
+  auditedAt: string;
+  verdict: CompassAuditVerdict;
+  agent: string;
+}
+
+interface CompassAuditLedger {
+  revisionThreshold: number;
+  entries: CompassAuditLedgerEntry[];
+}
+
+interface CompassAuditWorkOrderItem {
+  path: string;
+  currentRevision: number;
+  auditedRevision: number | null;
+  reason: "never-audited" | "revision-threshold-crossed";
+  moduleContract: string;
+  changeSummary: string;
+}
+
+export function isAuditDue(current: number, audited: number | null, threshold: number): boolean {
+  if (audited === null) return true;
+  return current - audited >= threshold;
+}
+
+const _LEDGER_ADVISORY = { ownerCommand: "compass.audit.record" };
+
+function withLedgerAdvisory(ledger: Partial<CompassAuditLedger>): CompassAuditLedger {
+  return {
+    revisionThreshold: ledger.revisionThreshold ?? DEFAULT_THRESHOLD,
+    entries: Array.isArray(ledger.entries) ? ledger.entries : [],
+  };
+}
+
+async function loadLedger(workspaceRoot: string): Promise<CompassAuditLedger> {
+  const abs = resolve(workspaceRoot, LEDGER_PATH);
+  try {
+    const content = await readFile(abs, "utf8");
+    return withLedgerAdvisory(yamlParse(content) as Partial<CompassAuditLedger>);
+  } catch {
+    return withLedgerAdvisory({});
+  }
+}
+
+async function saveLedger(workspaceRoot: string, ledger: CompassAuditLedger): Promise<void> {
+  const normalized = withLedgerAdvisory(ledger);
+  normalized.entries.sort((a, b) => a.path.localeCompare(b.path));
+  const abs = resolve(workspaceRoot, LEDGER_PATH);
+  const header = buildGeneratedHeader({
+    ownerCommand: "compass.audit.record",
+    filePath: LEDGER_PATH,
+  });
+  const yaml = header + yamlStringify(normalized) + "\n";
+  await writeFileAtomic(abs, yaml);
+}
+
+function extractBlock(source: string, tagName: string): string {
+  const match = source.match(new RegExp(`<${tagName}>[\\s\\S]*?<\\/${tagName}>`));
+  return match?.[0] ?? "";
+}
+
+async function getGitUser(workspaceRoot: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync("git", ["config", "user.name"], {
+      cwd: workspaceRoot,
+    });
+    return `human:${stdout.trim()}`;
+  } catch {
+    return "human:unknown";
+  }
+}
+
+function getAuthoredEntries(entries: CompassInventoryEntry[]): CompassInventoryEntry[] {
+  return entries.filter(
+    (e) => e.authoringStatus === "authored" && e.requiredScaffolding !== "none",
+  );
+}
+
+export async function runCompassAuditPlan(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    threshold: number;
+    dueCount: number;
+    items: CompassAuditWorkOrderItem[];
+  }>
+> {
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const authored = getAuthoredEntries(entries);
+  const ledger = await loadLedger(context.workspaceRoot);
+
+  const threshold = resolveRevisionThreshold(input.flags["threshold"], ledger.revisionThreshold);
+
+  const ledgerMap = new Map<string, CompassAuditLedgerEntry>();
+  for (const e of ledger.entries) {
+    ledgerMap.set(e.path, e);
+  }
+
+  const items: CompassAuditWorkOrderItem[] = [];
+
+  for (const entry of authored) {
+    const ledgerEntry = ledgerMap.get(entry.path);
+    const auditedRevision = ledgerEntry?.auditedRevision ?? null;
+
+    const { revision: currentRevision } = await getRevisionByPath(
+      context.workspaceRoot,
+      entry.path,
+    );
+
+    if (!isAuditDue(currentRevision, auditedRevision, threshold)) {
+      continue;
+    }
+
+    const absPath = resolve(context.workspaceRoot, entry.path);
+    const source = await readFile(absPath, "utf8");
+    const moduleContract = extractBlock(source, "MODULE_CONTRACT");
+    const changeSummary = extractBlock(source, "CHANGE_SUMMARY");
+
+    items.push({
+      path: entry.path,
+      currentRevision,
+      auditedRevision,
+      reason: auditedRevision === null ? "never-audited" : "revision-threshold-crossed",
+      moduleContract,
+      changeSummary,
+    });
+  }
+
+  items.sort((a, b) => a.path.localeCompare(b.path));
+
+  context.logger.info(`[compass.audit.plan] threshold=${threshold}, due=${items.length}`);
+
+  return {
+    data: { threshold, dueCount: items.length, items },
+    exitCode: 0,
+    summary: `[compass.audit.plan] ${items.length} files due for audit (threshold=${threshold})`,
+  };
+}
+
+export async function runCompassAuditRecord(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    path: string;
+    action: "recorded";
+  }>
+> {
+  const rawFilePath = input.flags["file"] as string | undefined;
+  const verdict = input.flags["verdict"] as CompassAuditVerdict | undefined;
+  const agentFlag = input.flags["agent"] as string | undefined;
+
+  if (!rawFilePath) {
+    context.logger.error("[compass.audit.record] --file is required");
+    return { exitCode: 1, data: { path: "", action: "recorded" } };
+  }
+
+  if (!verdict || !["pass", "repaired", "baseline"].includes(verdict)) {
+    context.logger.error("[compass.audit.record] --verdict must be pass|repaired|baseline");
+    return { exitCode: 1, data: { path: rawFilePath, action: "recorded" } };
+  }
+
+  const filePath = relative(context.workspaceRoot, resolve(process.cwd(), rawFilePath));
+
+  const { revision, entityId, contentHash } = await getRevisionByPath(
+    context.workspaceRoot,
+    filePath,
+  );
+
+  const agent = agentFlag ?? (await getGitUser(context.workspaceRoot));
+  const ledger = await loadLedger(context.workspaceRoot);
+
+  const existingIdx = ledger.entries.findIndex((e) => e.path === filePath);
+  const entry: CompassAuditLedgerEntry = {
+    path: filePath,
+    entityId: entityId ?? "",
+    auditedRevision: revision,
+    auditedHash: contentHash,
+    auditedAt: new Date().toISOString(),
+    verdict,
+    agent,
+  };
+
+  if (existingIdx >= 0) {
+    ledger.entries[existingIdx] = entry;
+  } else {
+    ledger.entries.push(entry);
+  }
+
+  if (!context.dryRun) {
+    await saveLedger(context.workspaceRoot, ledger);
+  }
+
+  context.logger.info(
+    `[compass.audit.record] ${filePath}: verdict=${verdict}, revision=${revision}, agent=${agent}`,
+  );
+
+  return {
+    data: { path: filePath, action: "recorded" },
+    exitCode: 0,
+    summary: `[compass.audit.record] ${filePath}: ${verdict} at revision ${revision}`,
+  };
+}
+
+export async function runCompassAuditBaseline(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    seeded: number;
+    total: number;
+  }>
+> {
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const authored = getAuthoredEntries(entries);
+  const ledger = await loadLedger(context.workspaceRoot);
+
+  const existingPaths = new Set(ledger.entries.map((e) => e.path));
+  let seededCount = 0;
+
+  for (const entry of authored) {
+    if (existingPaths.has(entry.path)) {
+      continue;
+    }
+
+    const { revision, entityId, contentHash } = await getRevisionByPath(
+      context.workspaceRoot,
+      entry.path,
+    );
+
+    ledger.entries.push({
+      path: entry.path,
+      entityId: entityId ?? "",
+      auditedRevision: revision,
+      auditedHash: contentHash,
+      auditedAt: new Date().toISOString(),
+      verdict: "baseline",
+      agent: "system:baseline",
+    });
+    seededCount++;
+  }
+
+  ledger.entries.sort((a, b) => a.path.localeCompare(b.path));
+
+  if (!context.dryRun) {
+    await saveLedger(context.workspaceRoot, ledger);
+  }
+
+  context.logger.info(
+    `[compass.audit.baseline] seeded=${seededCount}, total=${ledger.entries.length}`,
+  );
+
+  return {
+    data: { seeded: seededCount, total: ledger.entries.length },
+    exitCode: 0,
+    summary: `[compass.audit.baseline] seeded ${seededCount} entries (total: ${ledger.entries.length})`,
+  };
+}
+
+export async function runCompassAuditValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    strict: boolean;
+    dueCount: number;
+    diagnostics: Array<{
+      ruleId: string;
+      severity: string;
+      file: string;
+      message: string;
+      fix: string;
+    }>;
+  }>
+> {
+  const strict = input.flags["strict"] === true;
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+  const authored = getAuthoredEntries(entries);
+  const ledger = await loadLedger(context.workspaceRoot);
+
+  const ledgerMap = new Map<string, CompassAuditLedgerEntry>();
+  for (const e of ledger.entries) {
+    ledgerMap.set(e.path, e);
+  }
+
+  const diagnostics: Array<{
+    ruleId: string;
+    severity: string;
+    file: string;
+    message: string;
+    fix: string;
+  }> = [];
+
+  for (const entry of authored) {
+    const ledgerEntry = ledgerMap.get(entry.path);
+    const auditedRevision = ledgerEntry?.auditedRevision ?? null;
+
+    const { revision: currentRevision } = await getRevisionByPath(
+      context.workspaceRoot,
+      entry.path,
+    );
+
+    if (!isAuditDue(currentRevision, auditedRevision, ledger.revisionThreshold)) {
+      continue;
+    }
+
+    const severity = strict ? "error" : "warning";
+    context.logger[strict ? "error" : "warn"](
+      `[compass.audit.validate] COMPASS-AUDIT-01: ${entry.path}: audit overdue (current=${currentRevision}, audited=${auditedRevision ?? "never"}, threshold=${ledger.revisionThreshold})`,
+    );
+    diagnostics.push({
+      ruleId: "COMPASS-AUDIT-01",
+      severity,
+      file: entry.path,
+      message: `Compass audit overdue: ${currentRevision - (auditedRevision ?? 0)} revisions since last audit (threshold=${ledger.revisionThreshold})`,
+      fix: "fix: run compass.audit.plan, reconcile the blocks with the code, then compass.audit.record",
+    });
+  }
+
+  const dueCount = diagnostics.length;
+  const hasErrors = strict && dueCount > 0;
+
+  return {
+    data: { strict, dueCount, diagnostics },
+    exitCode: hasErrors ? 1 : 0,
+    summary: dueCount > 0 ? undefined : `[compass.audit.validate] OK (0 files overdue)`,
+  };
+}

package/os/compass/handlers/compass-change-summary-handler.ts

@@ -0,0 +1,272 @@
+/*
+<MODULE_CONTRACT>
+<purpose>CHANGE_SUMMARY classification, validation, and deterministic tidy logic
+per RFC-0349. Moved from @warpgogol/site-kernel-checks to @warpgogol/forge for full
+autonomous mode (RFC-0556). Provides compass.changesummary.validate and compass.summary.trim.</purpose>
+<non-goals>
+  <item>Do not audit truthfulness of CHANGE_SUMMARY items against code — that is RFC-0352.</item>
+  <item>Do not delete protected (RFC/code-referencing) items under any circumstance.</item>
+  <item>Do not use an LLM — classification and tidy are purely deterministic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0349: initial implementation of classifyChangeSummaryItem, compass.changesummary.validate, and compass.changesummary.tidy.</item>
+  <item>RFC-0538: renamed compass.changesummary.tidy to compass.summary.trim, raised cap from 3 unprotected to 30 total items, aligned validate cap to 30 total.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { createCompassInventoryEntries } from "./compass-inventory.ts";
+import { resolveCompassScanRoot } from "./resolve-scan-root.ts";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.ts";
+import type {
+  Diagnostic,
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const PROTECTED_RE = /\b([A-Z][A-Z0-9]*-)+\d+\b/;
+const BOILERPLATE_RE =
+  /^(Wave\s+\d|Backfill\b|Annotate Compass|Annotation revision|Initial creation|Compass scaffolding|Created as part of|Enhance .* with Compass)/i;
+
+export type ChangeSummaryItemClass = "protected" | "boilerplate" | "unprotected";
+
+export function classifyChangeSummaryItem(text: string): ChangeSummaryItemClass {
+  if (PROTECTED_RE.test(text)) return "protected";
+  if (BOILERPLATE_RE.test(text.trim())) return "boilerplate";
+  return "unprotected";
+}
+
+function extractChangeSummaryBlock(source: string): string | null {
+  const match = source.match(/<CHANGE_SUMMARY>[\s\S]*?<\/CHANGE_SUMMARY>/);
+  return match?.[0] ?? null;
+}
+
+function extractItems(block: string): string[] {
+  const items: string[] = [];
+  const re = /<item>([\s\S]*?)<\/item>/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block)) !== null) {
+    items.push(m[1]!.trim());
+  }
+  return items;
+}
+
+function rebuildChangeSummaryBlock(items: string[]): string {
+  const lines = ["<CHANGE_SUMMARY>"];
+  for (const item of items) {
+    lines.push(`  <item>${item}</item>`);
+  }
+  lines.push("</CHANGE_SUMMARY>");
+  return lines.join("\n");
+}
+
+function replaceChangeSummaryBlock(source: string, newBlock: string): string {
+  return source.replace(/<CHANGE_SUMMARY>[\s\S]*?<\/CHANGE_SUMMARY>/, newBlock);
+}
+
+const MAX_TOTAL_ITEMS = 30;
+
+export async function runCompassChangeSummaryValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    command: string;
+    status: "pass" | "fail";
+    diagnostics: Diagnostic[];
+    checkedFiles: number;
+  }>
+> {
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+
+  const diagnostics: Diagnostic[] = [];
+  let checkedFiles = 0;
+
+  for (const entry of entries) {
+    if (entry.authoringStatus !== "authored" || entry.requiredScaffolding === "none") {
+      continue;
+    }
+
+    checkedFiles++;
+
+    if (!entry.hasChangeSummary) {
+      continue;
+    }
+
+    const absPath = resolve(context.workspaceRoot, entry.path);
+    const source = await readFile(absPath, "utf8");
+    const block = extractChangeSummaryBlock(source);
+    if (!block) continue;
+
+    const items = extractItems(block);
+    let hasBoilerplate = false;
+    let totalItems = 0;
+
+    for (const item of items) {
+      const cls = classifyChangeSummaryItem(item);
+      if (cls === "boilerplate") {
+        hasBoilerplate = true;
+      }
+      totalItems++;
+    }
+
+    if (hasBoilerplate) {
+      diagnostics.push({
+        ruleId: "COMPASS-CS-01",
+        severity: "error",
+        file: entry.path,
+        message: "CHANGE_SUMMARY contains a boilerplate item",
+        fixHint: "fix: run compass.summary.trim",
+      });
+    }
+
+    if (totalItems > MAX_TOTAL_ITEMS) {
+      diagnostics.push({
+        ruleId: "COMPASS-CS-02",
+        severity: "error",
+        file: entry.path,
+        message: `CHANGE_SUMMARY has ${totalItems} total items (cap is ${MAX_TOTAL_ITEMS})`,
+        fixHint: `fix: run compass.summary.trim (cap is ${MAX_TOTAL_ITEMS} total items)`,
+      });
+    }
+  }
+
+  const failed = diagnostics.length > 0;
+
+  for (const d of diagnostics) {
+    context.logger.error(`[compass.changesummary.validate] ${d.ruleId}: ${d.file}: ${d.message}`);
+  }
+
+  return {
+    data: {
+      command: "compass.changesummary.validate",
+      status: failed ? "fail" : "pass",
+      diagnostics,
+      checkedFiles,
+    },
+    exitCode: failed ? 1 : 0,
+    summary: failed
+      ? undefined
+      : `[compass.changesummary.validate] OK (${checkedFiles} authored files checked)`,
+  };
+}
+
+const TRIM_FALLBACK_ITEM = "Tidied by compass.summary.trim; see git history for prior entries.";
+
+export async function runCompassSummaryTrim(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<
+  ForgeCommandResult<{
+    command: string;
+    status: "ok";
+    files: Array<{ path: string; removed: string[]; kept: number }>;
+  }>
+> {
+  if (context.dryRun) {
+    context.logger.info(`[compass.summary.trim] dry-run active — will not apply changes`);
+  }
+
+  const scanRoot = resolveCompassScanRoot(input, context);
+  const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+
+  const results: Array<{ path: string; removed: string[]; kept: number }> = [];
+
+  for (const entry of entries) {
+    if (entry.authoringStatus !== "authored" || entry.requiredScaffolding === "none") {
+      continue;
+    }
+
+    if (!entry.hasChangeSummary) {
+      continue;
+    }
+
+    const absPath = resolve(context.workspaceRoot, entry.path);
+    const source = await readFile(absPath, "utf8");
+    const block = extractChangeSummaryBlock(source);
+    if (!block) continue;
+
+    const items = extractItems(block);
+    const keptItems: string[] = [];
+    const removedItems: string[] = [];
+
+    const unprotectedItems: Array<{ index: number; text: string }> = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const text = items[i]!;
+      const cls = classifyChangeSummaryItem(text);
+
+      if (cls === "protected") {
+        keptItems.push(text);
+      } else if (cls === "boilerplate") {
+        removedItems.push(text);
+      } else {
+        unprotectedItems.push({ index: i, text });
+      }
+    }
+
+    const protectedCount = keptItems.length;
+    const maxUnprotectedToKeep = Math.max(0, MAX_TOTAL_ITEMS - protectedCount);
+    const unprotectedToKeep = unprotectedItems.slice(-maxUnprotectedToKeep);
+    const unprotectedToRemove = unprotectedItems.slice(0, -maxUnprotectedToKeep);
+
+    for (const item of unprotectedToRemove) {
+      removedItems.push(item.text);
+    }
+
+    const keepSet = new Set<string>();
+    for (const item of unprotectedToKeep) {
+      keepSet.add(item.text);
+    }
+
+    const finalItems: string[] = [];
+    const protectedTexts = new Set(keptItems);
+    const unprotectedTexts = new Set(unprotectedToKeep.map((u) => u.text));
+
+    for (const originalItem of items) {
+      if (protectedTexts.has(originalItem) || unprotectedTexts.has(originalItem)) {
+        finalItems.push(originalItem);
+      }
+    }
+
+    if (finalItems.length === 0) {
+      finalItems.push(TRIM_FALLBACK_ITEM);
+    }
+
+    const newBlock = rebuildChangeSummaryBlock(finalItems);
+    const transformed = replaceChangeSummaryBlock(source, newBlock);
+
+    if (transformed === source) {
+      continue;
+    }
+
+    if (!context.dryRun) {
+      await writeFileIfChanged(absPath, transformed);
+    }
+
+    context.logger.info(
+      `[compass.summary.trim] trimmed: ${entry.path} (removed ${removedItems.length}, kept ${finalItems.length})`,
+    );
+
+    results.push({
+      path: entry.path,
+      removed: removedItems,
+      kept: finalItems.length,
+    });
+  }
+
+  return {
+    data: {
+      command: "compass.summary.trim",
+      status: "ok",
+      files: results,
+    },
+    exitCode: 0,
+    summary: `[compass.summary.trim] files=${results.length}, removed=${results.reduce((sum, r) => sum + r.removed.length, 0)}`,
+  };
+}