@warpgogol/forge 4.2.2 → 4.2.3

package/os/compass/handlers/tests/compass-v2-contract.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { runCompassValidation, runCompassInventory } from "../compass-inventory-handler.ts";
+import { runCompassChangeSummaryValidate } from "../compass-change-summary-handler.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../../src/types.ts";
+
+function dataOf<T>(result: ForgeCommandResult<T>): T {
+  if (!result.data) throw new Error("command returned no data payload");
+  return result.data;
+}
+
+function makeContext(workspaceRoot: string, dryRun = false): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    site: undefined,
+    siteExplicit: false,
+    dryRun,
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as ForgeRuntimeContext;
+}
+
+function makeInput(flags: Record<string, unknown> = {}): ForgeCommandInput {
+  return { flags } as ForgeCommandInput;
+}
+
+const MC = (purpose: string) =>
+  `<MODULE_CONTRACT>\n<purpose>${purpose}</purpose>\n<non-goals>\n  <item>Do not perform real validation — fixtures only.</item>\n</non-goals>\n</MODULE_CONTRACT>`;
+const KD = (items: string[]) =>
+  `<KEY_DECISIONS>\n${items.map((i) => `  <item>${i}</item>`).join("\n")}\n</KEY_DECISIONS>`;
+const KD_EMPTY = `<KEY_DECISIONS>\n</KEY_DECISIONS>`;
+const CS = (items: string[], history?: string) =>
+  `<CHANGE_SUMMARY>\n${items.map((i) => `  <item>${i}</item>`).join("\n")}${history ? `\n  <history>${history}</history>` : ""}\n</CHANGE_SUMMARY>`;
+const wrap = (...blocks: string[]) => `/*\n${blocks.join("\n")}\n*/`;
+
+const PURPOSE_WITH_TOKEN =
+  "Validates mission widget fixtures for the compass v2 contract test suite.";
+const KD_ITEM = "Fixtures live in a temp workspace so tests never touch the real repository.";
+const CS_ITEM = "RFC-1094: initial v2 fixture.";
+
+// Medium-risk path: src/components/** maps to layer "component" → riskClass medium.
+const MEDIUM_FILE = "packages/fixture-pkg/src/components/mission-widget.ts";
+// Low-risk path: bare src/** maps to layer "source" → riskClass low.
+const LOW_FILE = "packages/fixture-pkg/src/mission-notes.ts";
+
+describe("compass v2 contract (RFC-1094)", () => {
+  let tempDir: string;
+
+  function writeFixture(relPath: string, header: string): void {
+    const abs = join(tempDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    const body = Array.from({ length: 25 }, (_, i) => `export const fixtureLine${i} = ${i};`).join(
+      "\n",
+    );
+    writeFileSync(abs, `${header}\n\n${body}\n`);
+  }
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "compass-v2-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("AC-1/AC-9: missing KEY_DECISIONS on medium-risk file — warning in default mode, error in --mode error", async () => {
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), CS([CS_ITEM])));
+
+    const warnResult = await runCompassValidation(makeInput(), makeContext(tempDir));
+    const warnDiag = dataOf(warnResult).diagnostics.find((d) => d.ruleId === "COMPASS-KD-01");
+    expect(warnDiag, "KD-01 must fire for medium-risk file without KEY_DECISIONS").toBeDefined();
+    expect(warnDiag!.severity).toBe("warning");
+    expect(warnResult.exitCode).toBe(0);
+
+    const errorResult = await runCompassValidation(
+      makeInput({ mode: "error" }),
+      makeContext(tempDir),
+    );
+    const errorDiag = dataOf(errorResult).diagnostics.find((d) => d.ruleId === "COMPASS-KD-01");
+    expect(errorDiag!.severity).toBe("error");
+    expect(errorResult.exitCode).toBe(1);
+  });
+
+  it("low-risk file without KEY_DECISIONS produces no KD-01", async () => {
+    writeFixture(
+      LOW_FILE,
+      wrap(MC("Tracks mission notes for the compass v2 contract test suite."), CS([CS_ITEM])),
+    );
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    expect(dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-KD-01")).toBeUndefined();
+  });
+
+  it("AC-2: CHANGE_SUMMARY with more than 5 items reports COMPASS-CS-05", async () => {
+    const items = [1, 2, 3, 4, 5, 6].map((n) => `RFC-10${n}0: change number ${n}.`);
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS(items)));
+
+    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-05");
+    expect(diag, "CS-05 must fire when CHANGE_SUMMARY exceeds 5 items").toBeDefined();
+    expect(diag!.severity).toBe("warning");
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("AC-3: CHANGE_SUMMARY item without governance ID reports COMPASS-CS-06", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS(["fixed a bug in the widget"])),
+    );
+
+    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-06");
+    expect(diag, "CS-06 must fire for items lacking a governance ID").toBeDefined();
+  });
+
+  it("AC-4: KEY_DECISIONS item with governance-ID prefix reports COMPASS-KD-05", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(MC(PURPOSE_WITH_TOKEN), KD(["RFC-1094: decided to compress history"]), CS([CS_ITEM])),
+    );
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-KD-05");
+    expect(diag, "KD-05 must fire when a KEY_DECISIONS item starts with an ID").toBeDefined();
+  });
+
+  it("AC-5: compass.inventory emits the new v2 fields per entry", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([CS_ITEM], "RFC-0348, RFC-0349")),
+    );
+
+    const result = await runCompassInventory(makeInput(), makeContext(tempDir, true));
+    const entry = dataOf(result).entries.find((e) => e.path === MEDIUM_FILE);
+    expect(entry, "inventory must include the fixture entry").toBeDefined();
+    expect(entry!.hasKeyDecisions).toBe(true);
+    expect(entry!.keyDecisionsItemCount).toBe(1);
+    expect(entry!.keyDecisionsRequired).toBe(true);
+    expect(entry!.changeSummaryItemCount).toBe(1);
+    expect(entry!.historyIds).toEqual(["RFC-0348", "RFC-0349"]);
+  });
+
+  it("AC-6: boilerplate purpose reports COMPASS-PURPOSE-01; tokenless purpose reports COMPASS-PURPOSE-02", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(
+        MC("This file provides various reusable capabilities for the wider workspace ecosystem."),
+        KD([KD_ITEM]),
+        CS([CS_ITEM]),
+      ),
+    );
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    expect(
+      dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-PURPOSE-01"),
+      "PURPOSE-01 must fire on a boilerplate purpose opener",
+    ).toBeDefined();
+    expect(
+      dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-PURPOSE-02"),
+      "PURPOSE-02 must fire when no file-derived token appears in purpose",
+    ).toBeDefined();
+  });
+
+  it("AC-10: KEY_DECISIONS after CHANGE_SUMMARY reports COMPASS-ORDER-01", async () => {
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), CS([CS_ITEM]), KD([KD_ITEM])));
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    const diag = dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-ORDER-01");
+    expect(diag, "ORDER-01 must fire when blocks violate canonical order").toBeDefined();
+  });
+
+  it("KD-02: empty or TODO-only KEY_DECISIONS block", async () => {
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD_EMPTY, CS([CS_ITEM])));
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    expect(dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-KD-02")).toBeDefined();
+  });
+
+  it("KD-03: KEY_DECISIONS item over 20 words", async () => {
+    const longItem = Array.from({ length: 21 }, (_, i) => `word${i}`).join(" ");
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD([longItem]), CS([CS_ITEM])));
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    expect(dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-KD-03")).toBeDefined();
+  });
+
+  it("KD-04: more than 7 KEY_DECISIONS items", async () => {
+    const items = Array.from({ length: 8 }, (_, i) => `Decision number ${i} stays deterministic.`);
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD(items), CS([CS_ITEM])));
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    expect(dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-KD-04")).toBeDefined();
+  });
+
+  it("CS-07: malformed history — non-ID token, duplicates, and descending order", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([CS_ITEM], "RFC-0350, RFC-0348")),
+    );
+
+    const result = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    expect(
+      dataOf(result).diagnostics.find((d) => d.ruleId === "COMPASS-CS-07"),
+      "CS-07 must fire on descending per-namespace order",
+    ).toBeDefined();
+  });
+
+  it("empty CHANGE_SUMMARY (no items, no history) is legal", async () => {
+    writeFixture(MEDIUM_FILE, wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([])));
+
+    const warnResult = await runCompassValidation(makeInput(), makeContext(tempDir));
+    const csResult = await runCompassChangeSummaryValidate(makeInput(), makeContext(tempDir));
+    expect(
+      dataOf(warnResult).diagnostics.filter((d) => d.ruleId.startsWith("COMPASS-CS-")),
+    ).toHaveLength(0);
+    expect(
+      dataOf(csResult).diagnostics.filter((d) => d.ruleId.startsWith("COMPASS-CS-")),
+    ).toHaveLength(0);
+  });
+
+  it("fully compliant v2 file produces zero v2 diagnostics", async () => {
+    writeFixture(
+      MEDIUM_FILE,
+      wrap(MC(PURPOSE_WITH_TOKEN), KD([KD_ITEM]), CS([CS_ITEM], "RFC-0348, RFC-0349")),
+    );
+
+    const result = await runCompassValidation(makeInput(), makeContext(tempDir));
+    const v2 = dataOf(result).diagnostics.filter((d) =>
+      ["COMPASS-KD-", "COMPASS-ORDER-", "COMPASS-PURPOSE-"].some((p) => d.ruleId.startsWith(p)),
+    );
+    expect(v2, `unexpected v2 diagnostics: ${JSON.stringify(v2)}`).toHaveLength(0);
+    expect(result.exitCode).toBe(0);
+  });
+});

package/os/core/core.module.ts

@@ -27,6 +27,9 @@
   <item>RFC-0877: forge.create --in-place required, --profile required, --name optional (derived from folder), strict empty-directory check (only .git/ tolerated).</item>
   <item>RFC-0940: register forge.autonomy.validate command enforcing FORGE-AUTONOMY-01 (no @warpgogol/werkstatt-engine imports outside os/werkstatt/).</item>
   <item>RFC-1080: register forge.public-surface.validate command for README/package.json consistency checks (SURFACE-01..05).</item>
+  <item>RFC-1088: register forge.file-size.lint command for portable SIZE-01 line-count validation.</item>
+  <item>RFC-1088 fix: add writes field to forge.file-size.lint registration per fo-review.</item>
+  <item>RFC-1089: rename forge.file-size.lint to file.size.lint (domain validator, no forge. prefix).</item>
 </CHANGE_SUMMARY>
 */
 
@@ -69,6 +72,7 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
   const { runPackageHealth } = await import("./handlers/package-health.ts");
   const { runForgeAutonomyValidate } = await import("./handlers/forge-autonomy-validate.ts");
   const { runPublicSurfaceValidate } = await import("./handlers/public-surface.ts");
+  const { runFileSizeLint } = await import("./handlers/file-size-lint.ts");
 
   const scaffoldWrapper = async (
     input: ForgeCommandInput,
@@ -746,6 +750,30 @@ export async function createForgeCoreModule(): Promise<ForgeModule> {
         flags: {},
         execute: runPublicSurfaceValidate,
       },
+      {
+        name: "file.size.lint",
+        contract: "file",
+        rules: ["SIZE-01"],
+        description:
+          "SIZE-01: flags a packages/** .ts/.tsx source file exceeding a 600-line threshold (warning 601-1200, error 1200+), against a shrink-only ratchet baseline. Pass --write-baseline to regenerate the baseline. Pass --baseline-path to override the default baseline location (RFC-1088).",
+        scope: "workspace",
+        supportsAllSites: false,
+        reads: ["packages/*/src/**/*.ts", "packages/*/src/**/*.tsx"],
+        writes: ["file-size-lint.baseline.yaml"],
+        cacheable: false,
+        flags: {
+          "write-baseline": {
+            kind: "boolean",
+            description: "Regenerate the oversized-file baseline instead of validating against it.",
+          },
+          "baseline-path": {
+            kind: "string",
+            description:
+              "Override the baseline file path (default: file-size-lint.baseline.yaml at workspace root).",
+          },
+        },
+        execute: runFileSizeLint,
+      },
       {
         name: "docs.archive",
         description:

package/os/core/handlers/file-size-lint.ts

@@ -0,0 +1,200 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+forge.file-size.lint — RFC-1088: portable two-tier severity for .ts/.tsx source files
+under packages/** exceeding a line-count threshold. 601-1200 lines → warning (SIZE-01);
+above 1200 lines → error (SIZE-01). Autonomous: no @warpgogol/* imports. Inlined
+collectFiles and diagnosticsResult. Ratcheted baseline at workspace root.
+</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable (FORGE-AUTONOMY-01).</item>
+  <item>Do not parse a real AST — a physical line count is sufficient.</item>
+  <item>Do not split files — that is a manual action, one file per commit.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1088: initial implementation — ported from packages/werkstatt-site/src/checks/file-size-lint.ts to forge for autonomy.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import type {
+  CheckResult,
+  Diagnostic,
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const SCAN_ROOT = "packages";
+const DEFAULT_BASELINE_PATH = "file-size-lint.baseline.yaml";
+const WARNING_THRESHOLD = 600;
+const ERROR_THRESHOLD = 1200;
+
+interface FileSizeLintBaseline {
+  meta: { schemaVersion: 1; threshold: 600 };
+  /** Workspace-relative file path → accepted line-count ceiling (shrink-only). */
+  ceilings: Record<string, number>;
+}
+
+/** Pure: physical line count of a source string. */
+export function countLines(source: string): number {
+  if (source.length === 0) return 0;
+  return source.split("\n").length;
+}
+
+/** Inlined recursive file collector — no @warpgogol/werkstatt-shared dependency. */
+async function collectSourceFiles(root: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith("-") || entry.name.startsWith("old-")) continue;
+      if (entry.name === "tests" || entry.name === "node_modules" || entry.name === "dist") continue;
+      if (entry.name === ".astro" || entry.name.endsWith(".d.ts")) continue;
+      if (entry.name.endsWith(".generated.yaml")) continue;
+
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx")) continue;
+
+      results.push(full);
+    }
+  }
+
+  await walk(root);
+  return results;
+}
+
+async function readBaseline(
+  workspaceRoot: string,
+  baselinePath: string,
+): Promise<FileSizeLintBaseline | undefined> {
+  try {
+    const raw = await readFile(join(workspaceRoot, baselinePath), "utf8");
+    return yamlParse(raw) as FileSizeLintBaseline;
+  } catch {
+    return undefined;
+  }
+}
+
+function renderBaseline(ceilings: Record<string, number>): string {
+  const baseline: FileSizeLintBaseline = {
+    meta: { schemaVersion: 1, threshold: WARNING_THRESHOLD },
+    ceilings,
+  };
+  return yamlStringify(baseline);
+}
+
+async function findOversizedFiles(workspaceRoot: string): Promise<Map<string, number>> {
+  const files = await collectSourceFiles(join(workspaceRoot, SCAN_ROOT));
+  const oversized = new Map<string, number>();
+  for (const filePath of files) {
+    let source: string;
+    try {
+      source = await readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = countLines(source);
+    if (lines > WARNING_THRESHOLD) {
+      const relFile = relative(workspaceRoot, filePath).replace(/\\/g, "/");
+      oversized.set(relFile, lines);
+    }
+  }
+  return oversized;
+}
+
+/** Inlined diagnosticsResult — constructs a CheckResult from Diagnostic[]. */
+function diagnosticsResult(
+  command: string,
+  diagnostics: Diagnostic[],
+): ForgeCommandResult<CheckResult> {
+  const summary = {
+    error: diagnostics.filter((d) => d.severity === "error").length,
+    warning: diagnostics.filter((d) => d.severity === "warning").length,
+    info: diagnostics.filter((d) => d.severity === "info").length,
+  };
+  const status: CheckResult["status"] =
+    summary.error > 0 ? "fail" : summary.warning > 0 ? "warn" : "pass";
+  const counts: string[] = [];
+  if (summary.error > 0) counts.push(`${summary.error} error${summary.error === 1 ? "" : "s"}`);
+  if (summary.warning > 0) counts.push(`${summary.warning} warning${summary.warning === 1 ? "" : "s"}`);
+  const summaryStr = counts.length > 0 ? `[${command}] ${counts.join(", ")}` : `[${command}]`;
+  return {
+    data: { command, status, diagnostics, summary },
+    exitCode: summary.error > 0 ? 1 : 0,
+    summary: summaryStr,
+    nextSteps:
+      summary.error > 0
+        ? [
+            {
+              action: `Fix the error diagnostics reported by ${command} above, then re-run the pipeline`,
+              kind: "required" as const,
+            },
+          ]
+        : undefined,
+  };
+}
+
+export async function runFileSizeLint(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<CheckResult | { file: string; files: number }>> {
+  const { workspaceRoot } = context;
+  const baselinePath =
+    (input.flags["baseline-path"] as string | undefined) ?? DEFAULT_BASELINE_PATH;
+  const oversized = await findOversizedFiles(workspaceRoot);
+
+  if (input.flags["write-baseline"] === true) {
+    const ceilings: Record<string, number> = {};
+    for (const [file, lines] of oversized) ceilings[file] = lines;
+    await writeFile(join(workspaceRoot, baselinePath), renderBaseline(ceilings), "utf8");
+    return {
+      data: { file: baselinePath, files: oversized.size },
+      exitCode: 0,
+      summary: `forge.file-size.lint: wrote ${oversized.size} oversized file(s) to ${baselinePath}`,
+    };
+  }
+
+  const baseline = await readBaseline(workspaceRoot, baselinePath);
+  const ceilings = baseline?.ceilings ?? {};
+  const diagnostics: Diagnostic[] = [];
+
+  for (const [file, lines] of oversized) {
+    const ceiling = ceilings[file];
+    if (ceiling !== undefined && lines <= ceiling) continue;
+
+    const severity: "warning" | "error" = lines > ERROR_THRESHOLD ? "error" : "warning";
+
+    diagnostics.push({
+      ruleId: "SIZE-01",
+      severity,
+      file,
+      message:
+        ceiling !== undefined
+          ? `File grew from the baselined ${ceiling} to ${lines} lines, exceeding the ${WARNING_THRESHOLD}-line threshold.`
+          : `New file has ${lines} lines, exceeding the ${WARNING_THRESHOLD}-line threshold.`,
+      fixHint:
+        "Split the file into a sibling folder-of-files with a thin re-export shim, or shrink the baseline ceiling after review.",
+      data: { lines, threshold: WARNING_THRESHOLD, ceiling: ceiling ?? null },
+    });
+  }
+
+  return diagnosticsResult("forge.file-size.lint", diagnostics);
+}

package/os/core/handlers/public-surface.ts

@@ -9,6 +9,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-1080: initial public-surface consistency validator — README length, Node version match, .tgz absence, docs/ structure, required root files.</item>
   <item>RFC-1080: add monorepo auto-detection — resolve packages/forge/ when run from monorepo root.</item>
+  <item>RFC-1088: raise SURFACE-01 README threshold from 300 to 600 lines.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -76,11 +77,11 @@ export async function runPublicSurfaceValidate(
 
   const pkg = readJsonFile(packageJsonPath);
 
-  // SURFACE-01: README length (warning)
+  // SURFACE-01: README length (warning, RFC-1088: raised from 300 to 600)
   checks.push({
     rule: "SURFACE-01",
-    message: `README.md is ${readmeLines} lines (${readmeLines <= 300 ? "under 300" : "over 300"})`,
-    status: readmeLines <= 300 ? "pass" : "warn",
+    message: `README.md is ${readmeLines} lines (${readmeLines <= 600 ? "under 600" : "over 600"})`,
+    status: readmeLines <= 600 ? "pass" : "warn",
   });
 
   // SURFACE-02: Node version consistency (error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "4.2.2",
+  "version": "4.2.3",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -177,22 +177,22 @@
     "test:tarball:node24": "node test-fixtures/node24-consumer/smoke.mjs"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.1116.0",
+    "@aws-sdk/client-s3": "^3.1131.0",
     "ajv": "^8.20.0",
-    "picomatch": "^4.0.5",
+    "picomatch": "^4.0.7",
     "trash": "^10.1.1",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.5.1",
     "@types/picomatch": "^4.0.3",
-    "eslint": "^10.9.0",
-    "fast-check": "^4.9.0",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "8.68.0",
-    "@vitest/coverage-v8": "^4.1.11",
-    "vitest": "^4.1.11"
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "fast-check": "^4.10.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "8.70.0",
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=24 <25"

package/skills/fo/fo-compass-annotate/SKILL.md

@@ -56,10 +56,11 @@ For each discovered file, determine the required action:
 If the file has no `MODULE_CONTRACT` and no `CHANGE_SUMMARY` block:
 
 1. Read the file content and understand its purpose.
-2. Use `templates/header-prompt.md` to generate a `MODULE_CONTRACT` block with `<purpose>` and `<non-goals>`.
-3. Create a `CHANGE_SUMMARY` block with a single `<item>` noting the initial creation.
-4. Insert both blocks at the top of the file, after any existing license/comment header but before imports.
-5. Use `reference/comment-styles.md` to determine the correct comment syntax for the file extension.
+2. Use `templates/header-prompt.md` to generate a `MODULE_CONTRACT` block with `<purpose>` and `<non-goals>`. The `<purpose>` must contain a file-derived token (stem segment, parent-directory segment for generic stems, or exported symbol).
+3. If the file's `riskClass` is `medium` or `high`, generate a `KEY_DECISIONS` block with 1–7 current-state design items (no governance-ID prefixes — current truth, not history).
+4. Create a `CHANGE_SUMMARY` block with a single `<item>` carrying the governing RFC/ADR/ticket ID.
+5. Insert the blocks at the top of the file in canonical order `MODULE_CONTRACT` → `KEY_DECISIONS` → `CHANGE_SUMMARY`, after any existing license/comment header but before imports.
+6. Use `reference/comment-styles.md` to determine the correct comment syntax for the file extension.
 
 #### 2b. Update (file has headers but content has changed)
 
@@ -67,17 +68,18 @@ If the file has Compass headers but the content has significantly changed:
 
 1. Read the current `MODULE_CONTRACT` and compare with the file's actual purpose.
 2. Use `templates/header-prompt.md` to regenerate the `MODULE_CONTRACT` if the purpose has shifted.
-3. Add a new `<item>` to `CHANGE_SUMMARY` referencing the current RFC or change.
-4. Run `compass.summary.trim` if the `CHANGE_SUMMARY` exceeds 30 total items.
+3. Rewrite `KEY_DECISIONS` items in place when the change alters a recorded decision — never append chronologically.
+4. Add a new `<item>` to `CHANGE_SUMMARY` referencing the current RFC/ADR/ticket ID. When the block exceeds 5 items, collapse the oldest IDs into the `<history>` element (comma-separated, deduplicated, per-namespace ascending).
 
 #### 2c. Audit (semantic check)
 
 For each file with Compass headers:
 
-1. Use `templates/audit-prompt.md` to audit the `MODULE_CONTRACT` against the file's actual content.
+1. Use `templates/audit-prompt.md` to audit the `MODULE_CONTRACT` (and `KEY_DECISIONS` when present) against the file's actual content.
 2. Check that `<purpose>` accurately describes what the file does.
 3. Check that `<non-goals>` lists at least one boundary the file does not cross.
-4. Flag files where the header is stale, misleading, or empty.
+4. Check that `KEY_DECISIONS` items still describe current design truth.
+5. Flag files where the header is stale, misleading, or empty.
 
 #### 2d. Risk flag
 
@@ -91,8 +93,8 @@ For each file with Compass headers:
 
 After processing all files:
 
-1. Run `compass.validate` to verify all headers are well-formed.
-2. If any violations are found, attempt to fix them automatically (missing `<non-goals>`, empty `<purpose>`, etc.).
+1. Run `compass.validate` to verify all headers are well-formed. v2 rules emit warnings by default (`--mode warning`); use `--mode error` to check post-migration compliance.
+2. If any violations are found, attempt to fix them automatically (missing `<non-goals>`, empty `<purpose>`, missing `KEY_DECISIONS` on medium/high-risk files, etc.).
 3. Re-run `compass.validate` to confirm fixes.
 4. If violations persist after 3 retry attempts, report them to the operator.
 
@@ -122,7 +124,7 @@ Output a summary:
 
 ## Completion criteria
 
-- All discovered files have `MODULE_CONTRACT` and `CHANGE_SUMMARY` blocks.
+- All discovered files have `MODULE_CONTRACT` and `CHANGE_SUMMARY` blocks in canonical order; medium/high-risk files also carry `KEY_DECISIONS`.
 - Pack-declared Compass contract blocks (RFC-0943, if any are declared in `forge.plugin.yaml` `extensionPoints.compass.contract`) are present in matching files.
 - `compass.validate` passes with zero errors.
 - No `TODO(compass)` sentinels remain (if `--cleanup` was used).

package/skills/fo/fo-compass-annotate/templates/audit-prompt.md

@@ -1,11 +1,12 @@
 # Semantic Audit Prompt
 
-You are auditing a Compass `MODULE_CONTRACT` block against the file's actual content. Determine whether the header is accurate, complete, and not misleading.
+You are auditing a Compass `MODULE_CONTRACT` block (and `KEY_DECISIONS` when present) against the file's actual content. Determine whether the header is accurate, complete, and not misleading.
 
 ## Input
 
 - File path: `{path}`
 - Current `MODULE_CONTRACT` block: `{header}`
+- Current `KEY_DECISIONS` block (may be empty): `{key_decisions}`
 - File content (full): `{content}`
 
 ## Audit axes
@@ -25,6 +26,11 @@ You are auditing a Compass `MODULE_CONTRACT` block against the file's actual con
    - Removed functionality is still mentioned in the purpose.
    - The file's role has shifted (e.g., from validator to generator).
 
+4. **KEY_DECISIONS truth** (when the block is present) — do the items still describe current design truth? Flag if:
+   - An item records a decision the code no longer follows.
+   - An item is really history (references what changed rather than what is true now).
+   - A load-bearing invariant visible in the code is missing from the block.
+
 ## Output
 
 ```