@warpgogol/forge 2.16.0 → 2.17.0

package/dist/os/compass/handlers/compass-change-summary-handler.js

@@ -0,0 +1,222 @@
+/*
+<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.js";
+import { resolveCompassScanRoot } from "./resolve-scan-root.js";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.js";
+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 function classifyChangeSummaryItem(text) {
+    if (PROTECTED_RE.test(text))
+        return "protected";
+    if (BOILERPLATE_RE.test(text.trim()))
+        return "boilerplate";
+    return "unprotected";
+}
+function extractChangeSummaryBlock(source) {
+    const match = source.match(/<CHANGE_SUMMARY>[\s\S]*?<\/CHANGE_SUMMARY>/);
+    return match?.[0] ?? null;
+}
+function extractItems(block) {
+    const items = [];
+    const re = /<item>([\s\S]*?)<\/item>/g;
+    let m;
+    while ((m = re.exec(block)) !== null) {
+        items.push(m[1].trim());
+    }
+    return items;
+}
+function getLineCommentPrefix(filePath) {
+    if (filePath.endsWith(".gd"))
+        return "# ";
+    if (filePath.endsWith(".tscn") || filePath.endsWith(".tres"))
+        return "; ";
+    return null;
+}
+function rebuildChangeSummaryBlock(items, filePath) {
+    const prefix = getLineCommentPrefix(filePath);
+    const lines = ["<CHANGE_SUMMARY>"];
+    for (const item of items) {
+        lines.push(`  <item>${item}</item>`);
+    }
+    lines.push("</CHANGE_SUMMARY>");
+    if (prefix) {
+        return lines.map((line, i) => (i === 0 ? line : prefix + line)).join("\n");
+    }
+    return lines.join("\n");
+}
+function replaceChangeSummaryBlock(source, newBlock) {
+    return source.replace(/<CHANGE_SUMMARY>[\s\S]*?<\/CHANGE_SUMMARY>/, newBlock);
+}
+const MAX_TOTAL_ITEMS = 30;
+export async function runCompassChangeSummaryValidate(input, context) {
+    const scanRoot = resolveCompassScanRoot(input, context);
+    const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+    const diagnostics = [];
+    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, context) {
+    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 = [];
+    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 = [];
+        const removedItems = [];
+        const unprotectedItems = [];
+        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();
+        for (const item of unprotectedToKeep) {
+            keepSet.add(item.text);
+        }
+        const finalItems = [];
+        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, entry.path);
+        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)}`,
+        nextSteps: [
+            {
+                action: `Commit the trimmed headers: pnpm exec forge run ecosystem.commit`,
+                kind: "optional",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=compass-change-summary-handler.js.map

package/dist/os/compass/handlers/compass-change-summary-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compass-change-summary-handler.js","sourceRoot":"","sources":["../../../../os/compass/handlers/compass-change-summary-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;EAgBE;AAEF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAQzE,MAAM,YAAY,GAAG,2BAA2B,CAAC;AACjD,MAAM,cAAc,GAClB,+IAA+I,CAAC;AAIlJ,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC;IAChD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,aAAa,CAAC;IAC3D,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,SAAS,yBAAyB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACzE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,EAAE,GAAG,2BAA2B,CAAC;IACvC,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAe,EAAE,QAAgB;IAClE,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,SAAS,CAAC,CAAC;IACvC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,yBAAyB,CAAC,MAAc,EAAE,QAAgB;IACjE,OAAO,MAAM,CAAC,OAAO,CAAC,4CAA4C,EAAE,QAAQ,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,KAAwB,EACxB,OAA4B;IAS5B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,6BAA6B,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE5F,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,eAAe,KAAK,UAAU,IAAI,KAAK,CAAC,mBAAmB,KAAK,MAAM,EAAE,CAAC;YACjF,SAAS;QACX,CAAC;QAED,YAAY,EAAE,CAAC;QAEf,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,SAAS;QAErB,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;gBAC1B,cAAc,GAAG,IAAI,CAAC;YACxB,CAAC;YACD,UAAU,EAAE,CAAC;QACf,CAAC;QAED,IAAI,cAAc,EAAE,CAAC;YACnB,WAAW,CAAC,IAAI,CAAC;gBACf,MAAM,EAAE,eAAe;gBACvB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,4CAA4C;gBACrD,OAAO,EAAE,+BAA+B;aACzC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;YACjC,WAAW,CAAC,IAAI,CAAC;gBACf,MAAM,EAAE,eAAe;gBACvB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,sBAAsB,UAAU,wBAAwB,eAAe,GAAG;gBACnF,OAAO,EAAE,yCAAyC,eAAe,eAAe;aACjF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;IAEtC,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,OAAO;QACL,IAAI,EAAE;YACJ,OAAO,EAAE,gCAAgC;YACzC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAChC,WAAW;YACX,YAAY;SACb;QACD,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,EAAE,MAAM;YACb,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,wCAAwC,YAAY,0BAA0B;KACnF,CAAC;AACJ,CAAC;AAED,MAAM,kBAAkB,GAAG,oEAAoE,CAAC;AAEhG,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAwB,EACxB,OAA4B;IAQ5B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,6BAA6B,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE5F,MAAM,OAAO,GAA6D,EAAE,CAAC;IAE7E,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,eAAe,KAAK,UAAU,IAAI,KAAK,CAAC,mBAAmB,KAAK,MAAM,EAAE,CAAC;YACjF,SAAS;QACX,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK;YAAE,SAAS;QAErB,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,MAAM,gBAAgB,GAA2C,EAAE,CAAC;QAEpE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACvB,MAAM,GAAG,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;YAE5C,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;gBACxB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;iBAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;gBACjC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,CAAC;QACxC,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC,CAAC;QAC3E,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,oBAAoB,CAAC,CAAC;QACxE,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC;QAE7E,KAAK,MAAM,IAAI,IAAI,mBAAmB,EAAE,CAAC;YACvC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,iBAAiB,EAAE,CAAC;YACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAED,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAEvE,KAAK,MAAM,YAAY,IAAI,KAAK,EAAE,CAAC;YACjC,IAAI,cAAc,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC3E,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,QAAQ,GAAG,yBAAyB,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,WAAW,GAAG,yBAAyB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAEhE,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,mCAAmC,KAAK,CAAC,IAAI,aAAa,YAAY,CAAC,MAAM,UAAU,UAAU,CAAC,MAAM,GAAG,CAC5G,CAAC;QAEF,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,YAAY;YACrB,IAAI,EAAE,UAAU,CAAC,MAAM;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,IAAI,EAAE;YACJ,OAAO,EAAE,sBAAsB;YAC/B,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,OAAO;SACf;QACD,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,gCAAgC,OAAO,CAAC,MAAM,aAAa,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE;QAC3H,SAAS,EAAE;YACT;gBACE,MAAM,EAAE,kEAAkE;gBAC1E,IAAI,EAAE,UAAU;aACjB;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/os/compass/handlers/compass-inventory-handler.d.ts

@@ -0,0 +1,28 @@
+import type { ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext } from "../../../src/types.ts";
+interface CompassInventorySummary {
+    scannedFiles: number;
+    authoredFiles: number;
+    excludedFiles: number;
+    standardRequiredFiles: number;
+    compliantFiles: number;
+    nonCompliantFiles: number;
+}
+export declare function runCompassInventory(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<{
+    entries: number;
+    outputPath: string;
+    summary: CompassInventorySummary;
+}>>;
+export declare function runCompassValidation(input: ForgeCommandInput, context: ForgeRuntimeContext): Promise<ForgeCommandResult<{
+    checkedFiles: number;
+    failures: number;
+    summary: CompassInventorySummary;
+    diagnostics: Array<{
+        ruleId: string;
+        severity: string;
+        file: string;
+        message: string;
+        fix: string;
+    }>;
+}>>;
+export {};
+//# sourceMappingURL=compass-inventory-handler.d.ts.map

package/dist/os/compass/handlers/compass-inventory-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compass-inventory-handler.d.ts","sourceRoot":"","sources":["../../../../os/compass/handlers/compass-inventory-handler.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AA8D/B,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAgHD,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CACR,kBAAkB,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,uBAAuB,CAAA;CAAE,CAAC,CAC9F,CA8CA;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CACR,kBAAkB,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,uBAAuB,CAAC;IACjC,WAAW,EAAE,KAAK,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC,CAAC;CACJ,CAAC,CACH,CAiMA"}

package/dist/os/compass/handlers/compass-inventory-handler.js

@@ -0,0 +1,377 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Compass inventory and validation command handlers. Moved from
+@warpgogol/site-kernel-checks to @warpgogol/forge for full autonomous mode (RFC-0556).
+Provides runCompassInventory (XML report generation) and runCompassValidation
+(compliance diagnostics with COMPASS-* rules). RFC-0943: validates pack-declared
+contract block specs alongside built-in MODULE_CONTRACT and CHANGE_SUMMARY checks.</purpose>
+<non-goals>
+  <item>Do not handle raw file parsing or content analysis.</item>
+  <item>Do not manage configuration or orchestration of external services.</item>
+  <item>Do not execute pack-provided validate() functions — pack block specs are declarative data interpreted here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0348: v2 two-block contract — XML output updated, compass.validate emits COMPASS-* diagnostics, summary uses standard-required-files.</item>
+  <item>RFC-0350: added COMPASS-TODO-01 diagnostic for unfilled Compass TODO sentinels.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode.</item>
+  <item>Game extensions: added COMPASS-SYNTAX-01 diagnostic validating comment syntax per file type (.gd needs # prefix, .tscn/.tres need ; prefix, .ts/.cs need block comment).</item>
+  <item>RFC-0943: added COMPASS-PLUGIN-01/02/03 diagnostics for pack-declared contract block specs from forge.plugin.yaml extensionPoints.</item>
+</CHANGE_SUMMARY>
+*/
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { createCompassInventoryEntries } from "./compass-inventory.js";
+import { resolveCompassScanRoot } from "./resolve-scan-root.js";
+import { writeFileIfChanged } from "../../../src/utils/fs-idempotent.js";
+import { loadForgeConfig } from "../../../src/config/forge-config.js";
+import { loadContractRegistry, findApplicablePackSpecs, } from "../../../src/compass/contract-registry.js";
+function extractBlockContentForPlugin(source, tagName) {
+    const escapedTag = tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = source.match(new RegExp(`<${escapedTag}>[\\s\\S]*?<\/${escapedTag}>`));
+    return match?.[0] ?? null;
+}
+const INVENTORY_OUTPUT_PATH = "docs/compass-inventory.xml";
+function getExpectedCommentSyntax(filePath) {
+    if (filePath.endsWith(".gd"))
+        return "hash";
+    if (filePath.endsWith(".tscn") || filePath.endsWith(".tres"))
+        return "semicolon";
+    if (filePath.endsWith(".ts") ||
+        filePath.endsWith(".tsx") ||
+        filePath.endsWith(".js") ||
+        filePath.endsWith(".mjs") ||
+        filePath.endsWith(".mts") ||
+        filePath.endsWith(".css") ||
+        filePath.endsWith(".cs"))
+        return "block";
+    return null;
+}
+function checkCommentSyntax(source, filePath) {
+    const syntax = getExpectedCommentSyntax(filePath);
+    if (!syntax)
+        return null;
+    const hasModuleContract = source.includes("<MODULE_CONTRACT>");
+    if (!hasModuleContract)
+        return null;
+    if (syntax === "block") {
+        const blockStart = source.indexOf("/*");
+        const blockEnd = source.lastIndexOf("*/");
+        const tagPos = source.indexOf("<MODULE_CONTRACT>");
+        if (blockStart === -1 || blockEnd === -1 || blockStart > tagPos || tagPos > blockEnd) {
+            return "MODULE_CONTRACT must be inside a /* ... */ block comment for this file type";
+        }
+    }
+    else if (syntax === "hash") {
+        const lines = source.split(/\r?\n/);
+        for (const line of lines) {
+            if (line.includes("<MODULE_CONTRACT>")) {
+                if (!line.trimStart().startsWith("# ")) {
+                    return "MODULE_CONTRACT lines must be prefixed with '# ' for .gd files";
+                }
+            }
+        }
+    }
+    else if (syntax === "semicolon") {
+        const lines = source.split(/\r?\n/);
+        for (const line of lines) {
+            if (line.includes("<MODULE_CONTRACT>")) {
+                if (!line.trimStart().startsWith("; ")) {
+                    return "MODULE_CONTRACT lines must be prefixed with '; ' for .tscn/.tres files";
+                }
+            }
+        }
+    }
+    return null;
+}
+function summarizeInventory(entries) {
+    let authoredFiles = 0;
+    let excludedFiles = 0;
+    let standardRequiredFiles = 0;
+    let compliantFiles = 0;
+    let nonCompliantFiles = 0;
+    for (const entry of entries) {
+        if (entry.authoringStatus === "excluded") {
+            excludedFiles += 1;
+            continue;
+        }
+        authoredFiles += 1;
+        if (entry.requiredScaffolding === "standard")
+            standardRequiredFiles += 1;
+        if (entry.compliant) {
+            compliantFiles += 1;
+        }
+        else {
+            nonCompliantFiles += 1;
+        }
+    }
+    return {
+        scannedFiles: entries.length,
+        authoredFiles,
+        excludedFiles,
+        standardRequiredFiles,
+        compliantFiles,
+        nonCompliantFiles,
+    };
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function renderInventoryXml(entries, summary) {
+    const lines = [];
+    lines.push("<compass-inventory>");
+    lines.push("  <meta>");
+    lines.push("    <document-id>compass-inventory</document-id>");
+    lines.push("    <version>2.0.0</version>");
+    lines.push("    <status>generated</status>");
+    lines.push("    <scope>repository-root</scope>");
+    lines.push(`    <generated-at>null</generated-at>`);
+    lines.push("    <generator>@warpgogol/forge:compass.inventory</generator>");
+    lines.push("  </meta>");
+    lines.push("  <summary>");
+    lines.push(`    <scanned-files>${summary.scannedFiles}</scanned-files>`);
+    lines.push(`    <authored-files>${summary.authoredFiles}</authored-files>`);
+    lines.push(`    <excluded-files>${summary.excludedFiles}</excluded-files>`);
+    lines.push(`    <standard-required-files>${summary.standardRequiredFiles}</standard-required-files>`);
+    lines.push(`    <compliant-files>${summary.compliantFiles}</compliant-files>`);
+    lines.push(`    <non-compliant-files>${summary.nonCompliantFiles}</non-compliant-files>`);
+    lines.push("  </summary>");
+    lines.push("  <entries>");
+    for (const entry of entries) {
+        lines.push(`    <entry path="${escapeXml(entry.path)}" workspace-kind="${entry.workspaceKind}" workspace-name="${escapeXml(entry.workspaceName)}" layer="${escapeXml(entry.layer)}" extension="${escapeXml(entry.extension)}" authoring-status="${entry.authoringStatus}" risk-class="${entry.riskClass}" complexity="${entry.complexity}" required-scaffolding="${entry.requiredScaffolding}" compliant="${entry.compliant ? "true" : "false"}">`);
+        lines.push(`      <non-empty-lines>${entry.nonEmptyLineCount}</non-empty-lines>`);
+        if (entry.exclusionReason) {
+            lines.push(`      <exclusion-reason>${escapeXml(entry.exclusionReason)}</exclusion-reason>`);
+        }
+        lines.push(`      <has-module-contract>${entry.hasModuleContract ? "true" : "false"}</has-module-contract>`);
+        lines.push(`      <has-change-summary>${entry.hasChangeSummary ? "true" : "false"}</has-change-summary>`);
+        lines.push(`      <has-ai-invariant>${entry.hasAiInvariant ? "true" : "false"}</has-ai-invariant>`);
+        lines.push(`      <has-purpose>${entry.hasPurpose ? "true" : "false"}</has-purpose>`);
+        lines.push(`      <has-non-goals>${entry.hasNonGoals ? "true" : "false"}</has-non-goals>`);
+        if (entry.forbiddenPresent.length > 0) {
+            lines.push("      <forbidden-markers>");
+            for (const marker of entry.forbiddenPresent) {
+                lines.push(`        <marker>${escapeXml(marker)}</marker>`);
+            }
+            lines.push("      </forbidden-markers>");
+        }
+        if (entry.violations.length > 0) {
+            lines.push("      <violations>");
+            for (const violation of entry.violations) {
+                lines.push(`        <violation>${escapeXml(violation)}</violation>`);
+            }
+            lines.push("      </violations>");
+        }
+        lines.push("    </entry>");
+    }
+    lines.push("  </entries>");
+    lines.push("</compass-inventory>");
+    lines.push("");
+    return lines.join("\n");
+}
+export async function runCompassInventory(input, context) {
+    const scanRoot = resolveCompassScanRoot(input, context) ?? context.workspaceRoot;
+    const entries = await createCompassInventoryEntries(scanRoot, input);
+    const summary = summarizeInventory(entries);
+    context.logger.info(`[compass.inventory] scanned=${summary.scannedFiles} authored=${summary.authoredFiles} excluded=${summary.excludedFiles} standard=${summary.standardRequiredFiles}`);
+    if (context.dryRun) {
+        context.logger.warn(`[compass.inventory] dry-run active — skipped writing ${INVENTORY_OUTPUT_PATH}`);
+        return {
+            data: { entries: entries.length, outputPath: INVENTORY_OUTPUT_PATH, summary },
+            summary: `[compass.inventory] previewed ${INVENTORY_OUTPUT_PATH}`,
+            nextSteps: [
+                {
+                    action: `Write the inventory: pnpm exec forge run compass.inventory`,
+                    kind: "optional",
+                },
+            ],
+        };
+    }
+    const xml = renderInventoryXml(entries, summary);
+    const outputPath = resolve(context.workspaceRoot, INVENTORY_OUTPUT_PATH);
+    await writeFileIfChanged(outputPath, xml);
+    return {
+        data: { entries: entries.length, outputPath, summary },
+        summary: `[compass.inventory] ${context.dryRun ? "previewed" : "wrote"} ${INVENTORY_OUTPUT_PATH}`,
+        nextSteps: context.dryRun
+            ? [
+                {
+                    action: `Write for real: pnpm exec forge run compass.inventory`,
+                    kind: "optional",
+                },
+            ]
+            : [
+                {
+                    action: `Validate compass headers: pnpm exec forge run compass.validate`,
+                    kind: "optional",
+                },
+            ],
+    };
+}
+export async function runCompassValidation(input, context) {
+    const scanRoot = resolveCompassScanRoot(input, context);
+    const entries = await createCompassInventoryEntries(context.workspaceRoot, input, scanRoot);
+    const summary = summarizeInventory(entries);
+    const failures = entries.filter((entry) => entry.authoringStatus === "authored" &&
+        entry.requiredScaffolding !== "none" &&
+        !entry.compliant);
+    const diagnostics = [];
+    for (const failure of failures) {
+        for (const violation of failure.violations) {
+            let ruleId = "COMPASS-CONTRACT-01";
+            let fix = "fix: add a MODULE_CONTRACT block with <purpose> and <non-goals>";
+            if (violation.includes("purpose missing")) {
+                ruleId = "COMPASS-CONTRACT-02";
+                fix = "fix: write a <purpose> of at least 10 words";
+            }
+            else if (violation.includes("non-goals")) {
+                ruleId = "COMPASS-CONTRACT-03";
+                fix = "fix: add at least one <non-goals><item>";
+            }
+            else if (violation.includes("CHANGE_SUMMARY")) {
+                ruleId = "COMPASS-CONTRACT-04";
+                fix = "fix: add a CHANGE_SUMMARY with at least one <item>";
+            }
+            else if (violation.includes("@ai-invariant")) {
+                ruleId = "COMPASS-INVARIANT-01";
+                fix = "fix: add // @ai-invariant capturing the non-obvious constraint";
+            }
+            else if (violation.includes("forbidden")) {
+                ruleId = "COMPASS-FORBIDDEN-01";
+                const marker = violation.replace(/forbidden: ([^ ]+) present/, "$1");
+                fix = `fix: remove ${marker}; run fo-compass-annotate skill`;
+            }
+            context.logger.error(`[compass.validate] ${ruleId}: ${failure.path}: ${violation}`);
+            diagnostics.push({
+                ruleId,
+                severity: "error",
+                file: failure.path,
+                message: violation,
+                fix,
+            });
+        }
+    }
+    const compassTodoLabel = "TODO" + "(compass)";
+    const TODO_COMPASS_RE = new RegExp("TODO" + "\\\\(compass\\\\)");
+    for (const entry of entries) {
+        if (entry.authoringStatus !== "authored" || entry.requiredScaffolding === "none") {
+            continue;
+        }
+        if (!entry.hasModuleContract && !entry.hasChangeSummary) {
+            continue;
+        }
+        const absPath = resolve(context.workspaceRoot, entry.path);
+        const source = await readFile(absPath, "utf8");
+        if (TODO_COMPASS_RE.test(source)) {
+            context.logger.error(`[compass.validate] COMPASS-TODO-01: ${entry.path}: unfilled ${compassTodoLabel} sentinel in Compass block`);
+            diagnostics.push({
+                ruleId: "COMPASS-TODO-01",
+                severity: "error",
+                file: entry.path,
+                message: `Unfilled ${compassTodoLabel} sentinel in Compass block`,
+                fix: `fix: replace the ${compassTodoLabel} sentinel with a real value`,
+            });
+        }
+        const syntaxError = checkCommentSyntax(source, entry.path);
+        if (syntaxError) {
+            context.logger.error(`[compass.validate] COMPASS-SYNTAX-01: ${entry.path}: ${syntaxError}`);
+            diagnostics.push({
+                ruleId: "COMPASS-SYNTAX-01",
+                severity: "error",
+                file: entry.path,
+                message: syntaxError,
+                fix: "fix: use the correct comment syntax for this file type (see comment-styles.md)",
+            });
+        }
+    }
+    let registry = { builtIn: [], pack: [] };
+    try {
+        const config = loadForgeConfig(context.workspaceRoot, context.forgeRoot);
+        registry = loadContractRegistry(context.workspaceRoot, config);
+    }
+    catch {
+        // No forge.yaml or invalid config — skip pack-declared blocks
+    }
+    if (registry.pack.length > 0) {
+        for (const entry of entries) {
+            if (entry.authoringStatus !== "authored" || entry.requiredScaffolding === "none") {
+                continue;
+            }
+            const applicableSpecs = findApplicablePackSpecs(registry, entry.path);
+            if (applicableSpecs.length === 0)
+                continue;
+            const absPath = resolve(context.workspaceRoot, entry.path);
+            const source = await readFile(absPath, "utf8");
+            for (const spec of applicableSpecs) {
+                const blockMarker = `<${spec.blockId.toUpperCase().replace(/-/g, "_")}>`;
+                if (!source.includes(blockMarker)) {
+                    context.logger.error(`[compass.validate] COMPASS-PLUGIN-01: ${entry.path}: missing ${spec.blockId} block (declared by pack ${spec.packId})`);
+                    diagnostics.push({
+                        ruleId: "COMPASS-PLUGIN-01",
+                        severity: "error",
+                        file: entry.path,
+                        message: `missing ${spec.blockId} block (declared by pack ${spec.packId})`,
+                        fix: `fix: add a ${blockMarker} block to this file`,
+                        pack: spec.packId,
+                    });
+                    continue;
+                }
+                if (spec.requiredTags && spec.requiredTags.length > 0) {
+                    const blockContent = extractBlockContentForPlugin(source, spec.blockId.toUpperCase().replace(/-/g, "_"));
+                    for (const tag of spec.requiredTags) {
+                        const tagMarker = `<${tag.name}>`;
+                        if (!blockContent || !blockContent.includes(tagMarker)) {
+                            context.logger.error(`[compass.validate] COMPASS-PLUGIN-02: ${entry.path}: missing <${tag.name}> tag in ${spec.blockId} block (declared by pack ${spec.packId})`);
+                            diagnostics.push({
+                                ruleId: "COMPASS-PLUGIN-02",
+                                severity: "error",
+                                file: entry.path,
+                                message: `missing <${tag.name}> tag in ${spec.blockId} block (declared by pack ${spec.packId})`,
+                                fix: `fix: add a <${tag.name}> tag inside the ${blockMarker} block`,
+                                pack: spec.packId,
+                            });
+                            continue;
+                        }
+                        if (tag.minWords) {
+                            const tagContent = extractBlockContentForPlugin(blockContent, tag.name);
+                            if (tagContent) {
+                                const text = tagContent.replace(/<[^>]+>/g, " ");
+                                const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
+                                if (wordCount < tag.minWords) {
+                                    context.logger.error(`[compass.validate] COMPASS-PLUGIN-03: ${entry.path}: <${tag.name}> in ${spec.blockId} has ${wordCount} words (minimum ${tag.minWords}, declared by pack ${spec.packId})`);
+                                    diagnostics.push({
+                                        ruleId: "COMPASS-PLUGIN-03",
+                                        severity: "error",
+                                        file: entry.path,
+                                        message: `<${tag.name}> in ${spec.blockId} has ${wordCount} words (minimum ${tag.minWords}, declared by pack ${spec.packId})`,
+                                        fix: `fix: write at least ${tag.minWords} words in the <${tag.name}> tag`,
+                                        pack: spec.packId,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const hasFailures = diagnostics.length > 0;
+    return {
+        data: {
+            checkedFiles: summary.authoredFiles,
+            failures: failures.length,
+            summary,
+            diagnostics,
+        },
+        exitCode: hasFailures ? 1 : 0,
+        summary: hasFailures
+            ? undefined
+            : `[compass.validate] OK (${summary.authoredFiles} authored files checked)`,
+    };
+}
+//# sourceMappingURL=compass-inventory-handler.js.map