@warpgogol/forge 2.9.13 → 2.9.23

package/os/plugin/plugin.module.ts

@@ -0,0 +1,261 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forgePluginModule — registers forge.plugin.validate and forge.plugin.discover commands for pack manifest validation (RFC-0941).</purpose>
+<non-goals>
+  <item>Do not implement skill discovery logic — delegate to discoverPackSkills in registry.ts.</item>
+  <item>Do not modify forge.yaml — this module reads config only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0941: initial forgePluginModule with forge.plugin.validate and forge.plugin.discover commands.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import fs from "node:fs";
+import { parse as parseYaml } from "yaml";
+import type { ForgeModule } from "../../src/forge-module.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../src/types.ts";
+import { loadForgeConfig } from "../../src/config/forge-config.ts";
+import { forgePluginManifestSchema } from "../../src/plugin/ForgePluginManifest.ts";
+
+export interface PluginValidateResult {
+  command: "forge.plugin.validate";
+  status: "pass" | "fail";
+  packs: Array<{
+    prefix: string;
+    dir: string;
+    manifestPath: string;
+    valid: boolean;
+    errors: string[];
+  }>;
+}
+
+export interface PluginDiscoverResult {
+  command: "forge.plugin.discover";
+  packs: Array<{
+    prefix: string;
+    dir: string;
+    manifestPath: string;
+    id: string;
+    version: string;
+  }>;
+  count: number;
+}
+
+function runPluginValidate(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): ForgeCommandResult<PluginValidateResult> {
+  const workspaceRoot = context.workspaceRoot;
+  const packs: PluginValidateResult["packs"] = [];
+  let allValid = true;
+
+  try {
+    const config = loadForgeConfig(workspaceRoot);
+
+    if (!config.skillPacks || config.skillPacks.length === 0) {
+      return {
+        data: {
+          command: "forge.plugin.validate",
+          status: "pass",
+          packs: [],
+        },
+        summary: "[forge.plugin.validate] OK — 0 packs declared",
+      };
+    }
+
+    for (const pack of config.skillPacks) {
+      const packDir = path.resolve(workspaceRoot, pack.dir);
+      const manifestPath = path.join(packDir, "forge.plugin.yaml");
+
+      if (!fs.existsSync(manifestPath)) {
+        allValid = false;
+        packs.push({
+          prefix: pack.prefix,
+          dir: pack.dir,
+          manifestPath,
+          valid: false,
+          errors: ["forge.plugin.yaml not found at pack root"],
+        });
+        continue;
+      }
+
+      let raw: string;
+      try {
+        raw = fs.readFileSync(manifestPath, "utf-8");
+      } catch (err) {
+        allValid = false;
+        packs.push({
+          prefix: pack.prefix,
+          dir: pack.dir,
+          manifestPath,
+          valid: false,
+          errors: [`Failed to read manifest: ${(err as Error).message}`],
+        });
+        continue;
+      }
+
+      let parsed: unknown;
+      try {
+        parsed = parseYaml(raw);
+      } catch (err) {
+        allValid = false;
+        packs.push({
+          prefix: pack.prefix,
+          dir: pack.dir,
+          manifestPath,
+          valid: false,
+          errors: [`YAML parse error: ${(err as Error).message}`],
+        });
+        continue;
+      }
+
+      const result = forgePluginManifestSchema.safeParse(parsed);
+      if (!result.success) {
+        allValid = false;
+        packs.push({
+          prefix: pack.prefix,
+          dir: pack.dir,
+          manifestPath,
+          valid: false,
+          errors: result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`),
+        });
+        continue;
+      }
+
+      packs.push({
+        prefix: pack.prefix,
+        dir: pack.dir,
+        manifestPath,
+        valid: true,
+        errors: [],
+      });
+    }
+  } catch (err) {
+    return {
+      data: {
+        command: "forge.plugin.validate",
+        status: "fail",
+        packs: [],
+      },
+      exitCode: 1,
+      summary: `[forge.plugin.validate] FAIL — ${(err as Error).message}`,
+    };
+  }
+
+  const status = allValid ? "pass" : "fail";
+  return {
+    data: {
+      command: "forge.plugin.validate",
+      status,
+      packs,
+    },
+    ...(status === "fail" ? { exitCode: 1 } : {}),
+    summary:
+      status === "pass"
+        ? `[forge.plugin.validate] OK — ${packs.length} pack(s) valid`
+        : `[forge.plugin.validate] FAIL — ${packs.filter((p) => !p.valid).length} pack(s) with errors`,
+  };
+}
+
+function runPluginDiscover(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): ForgeCommandResult<PluginDiscoverResult> {
+  const workspaceRoot = context.workspaceRoot;
+  const packs: PluginDiscoverResult["packs"] = [];
+
+  try {
+    const config = loadForgeConfig(workspaceRoot);
+
+    if (!config.skillPacks || config.skillPacks.length === 0) {
+      return {
+        data: {
+          command: "forge.plugin.discover",
+          packs: [],
+          count: 0,
+        },
+        summary: "[forge.plugin.discover] 0 packs discovered",
+      };
+    }
+
+    for (const pack of config.skillPacks) {
+      const packDir = path.resolve(workspaceRoot, pack.dir);
+      const manifestPath = path.join(packDir, "forge.plugin.yaml");
+
+      if (!fs.existsSync(manifestPath)) continue;
+
+      let raw: string;
+      try {
+        raw = fs.readFileSync(manifestPath, "utf-8");
+      } catch {
+        continue;
+      }
+
+      let parsed: unknown;
+      try {
+        parsed = parseYaml(raw);
+      } catch {
+        continue;
+      }
+
+      const result = forgePluginManifestSchema.safeParse(parsed);
+      if (!result.success) continue;
+
+      packs.push({
+        prefix: pack.prefix,
+        dir: pack.dir,
+        manifestPath,
+        id: result.data.id,
+        version: result.data.version,
+      });
+    }
+  } catch {
+    // Config not found or invalid — return empty
+  }
+
+  return {
+    data: {
+      command: "forge.plugin.discover",
+      packs,
+      count: packs.length,
+    },
+    summary: `[forge.plugin.discover] ${packs.length} pack(s) discovered`,
+  };
+}
+
+export const forgePluginModule: ForgeModule = {
+  name: "forge-plugin",
+  version: "0.1.0",
+  runtime: "autonomous",
+  async register(registry) {
+    registry.registerCommand({
+      name: "forge.plugin.validate",
+      description:
+        "Validate forge.plugin.yaml manifests for all declared skill packs (RFC-0941). Checks manifest schema (id: kebab-case, version: semver) and reports missing or invalid manifests.",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {},
+      reads: ["forge.yaml", "**/forge.plugin.yaml"],
+      cacheable: false,
+      execute: runPluginValidate,
+    });
+
+    registry.registerCommand({
+      name: "forge.plugin.discover",
+      description:
+        "Enumerate all project-declared skill packs with valid forge.plugin.yaml manifests (RFC-0941). Returns pack id, version, prefix, and directory.",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {},
+      reads: ["forge.yaml", "**/forge.plugin.yaml"],
+      cacheable: false,
+      execute: runPluginDiscover,
+    });
+  },
+};

package/os/program/program.module.ts

@@ -16,6 +16,7 @@ import type { ForgeModule } from "../../src/forge-module.ts";
 export const forgeProgramModule: ForgeModule = {
   name: "forge-program",
   version: "0.1.0",
+  runtime: "autonomous",
 
   async register(registry) {
     const { runValidate } = await import("./handlers/validate.ts");

package/os/rfc/rfc.module.ts

@@ -18,6 +18,7 @@ import type { ForgeModule } from "../../src/forge-module.ts";
 export const forgeRfcModule: ForgeModule = {
   name: "rfc",
   version: "0.1.0",
+  runtime: "autonomous",
 
   async register(registry) {
     const {

package/os/session/session.module.ts

@@ -15,6 +15,7 @@ import type { ForgeModule } from "../../src/forge-module.ts";
 export const forgeSessionModule: ForgeModule = {
   name: "forge-session",
   version: "0.1.0",
+  runtime: "autonomous",
   async register(registry) {
     const { runSessionSave } = await import("./handlers/save.ts");
     const { runSessionArchive } = await import("./handlers/archive.ts");

package/os/spec/spec.module.ts

@@ -17,6 +17,7 @@ import type { ForgeModule } from "../../src/forge-module.ts";
 export const forgeSpecModule: ForgeModule = {
   name: "forge-spec",
   version: "0.2.0",
+  runtime: "autonomous",
   async register(registry) {
     const { runSpecValidate } = await import("./spec-validate.ts");
     const { runSpecStatus } = await import("./spec-status.ts");

package/os/{core → werkstatt}/handlers/workspace-deps.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Lazy dynamic-import bridge for @warpgogol/werkstatt/fingerprint and @warpgogol/werkstatt-shared/share/fs. These workspace packages are not published to npm — when forge is installed standalone from npm, they are unavailable and handlers that depend on them must degrade gracefully.</purpose>
+<purpose>Lazy dynamic-import bridge for @warpgogol/werkstatt-engine/fingerprint and @warpgogol/werkstatt-shared/share/fs. These workspace packages are not published to npm — when forge is installed standalone from npm, they are unavailable and handlers that depend on them must degrade gracefully.</purpose>
 <non-goals>
   <item>Do not re-export types from @warpgogol/* — only runtime functions.</item>
   <item>Do not use static imports — that would break npm installs without workspace deps.</item>
@@ -8,6 +8,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0682: extract dynamic-import helper so forge publishes without workspace:* deps.</item>
+  <item>RFC-0940: moved from os/core/handlers/ to os/werkstatt/handlers/ — this module imports @warpgogol/werkstatt-engine and belongs in the adapter directory.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -39,7 +40,7 @@ export async function loadWorkspaceDeps(): Promise<WorkspaceDeps> {
     const shareMod = await import("@warpgogol/werkstatt-shared/share/fs");
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore — workspace dep, may not be installed when forge is used standalone from npm
-    const fpMod = await import("@warpgogol/werkstatt/fingerprint");
+    const fpMod = await import("@warpgogol/werkstatt-engine/fingerprint");
     cached = {
       collectFiles: shareMod.collectFiles as CollectFilesFn,
       byteHashFile: fpMod.byteHashFile as ByteHashFileFn,
@@ -47,7 +48,7 @@ export async function loadWorkspaceDeps(): Promise<WorkspaceDeps> {
     return cached;
   } catch (err) {
     loadError =
-      `@warpgogol/werkstatt/fingerprint and @warpgogol/werkstatt-shared/share are required for this command but not installed. ` +
+      `@warpgogol/werkstatt-engine/fingerprint and @warpgogol/werkstatt-shared/share are required for this command but not installed. ` +
       `When using forge standalone from npm, install them separately or use forge within the warpgogol workspace. ` +
       `Error: ${(err as Error).message}`;
     throw new Error(loadError);

package/os/werkstatt/werkstatt.module.ts

@@ -19,6 +19,7 @@ import { runWerkstattOperationValidate } from "./handlers/werkstatt-operation-va
 export const forgeWerkstattModule: ForgeModule = {
   name: "forge-werkstatt",
   version: "0.1.0",
+  runtime: "werkstatt-adapter",
   async register(registry) {
     registry.registerCommand({
       name: "werkstatt.lock.status",

package/os/workflow/workflow.module.ts

@@ -16,6 +16,7 @@ import type { ForgeModule } from "../../src/forge-module.ts";
 export const forgeWorkflowModule: ForgeModule = {
   name: "workflow",
   version: "0.1.0",
+  runtime: "autonomous",
   async register(registry) {
     const { runWorkflowLint, runWorkflowList, runWorkflowAmendList } =
       await import("./handlers.ts");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.9.13",
+  "version": "2.9.23",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -140,6 +140,10 @@
     "./os/program": {
       "types": "./os/program/program.module.ts",
       "default": "./os/program/program.module.ts"
+    },
+    "./os/plugin": {
+      "types": "./os/plugin/plugin.module.ts",
+      "default": "./os/plugin/plugin.module.ts"
     }
   },
   "files": [
@@ -166,14 +170,16 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
+    "picomatch": "^4.0.5",
     "trash": "^10.1.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "@warpgogol/werkstatt": "*",
-    "@warpgogol/werkstatt-shared": "*",
+    "@types/picomatch": "^4.0.2",
+    "@warpgogol/werkstatt-engine": "*",
+    "@warpgogol/werkstatt-shared": "^0.8.6",
     "eslint": "^10.8.0",
     "fast-check": "^4.9.0",
     "typescript": "^6.0.3",
@@ -303,6 +309,10 @@
       "./os/program": {
         "types": "./dist/os/program/program.module.d.ts",
         "default": "./dist/os/program/program.module.js"
+      },
+      "./os/plugin": {
+        "types": "./dist/os/plugin/plugin.module.d.ts",
+        "default": "./dist/os/plugin/plugin.module.js"
       }
     }
   },

package/profiles/forge-shell.yaml

@@ -165,7 +165,7 @@ workspace:
         console.log(`Cleaned ${toDelete.length} directories.`)
     - path: tools/kernel.config.ts
       content: |
-        import { defineKernelConfig } from "@warpgogol/werkstatt/kernel/types";
+        import { defineKernelConfig } from "@warpgogol/werkstatt-engine/kernel/types";
 
         export default defineKernelConfig({
           name: "__PROJECT_NAME__",

package/profiles/godot-csharp.yaml

@@ -374,7 +374,7 @@ workspace:
             "turbo": "^2.3.0",
             "prettier": "^3.4.0",
             "@warpgogol/forge": "^2.2.0",
-            "@warpgogol/werkstatt": "^1.2.0",
+            "@warpgogol/werkstatt-engine": "^1.2.0",
             "@warpgogol/werkstatt-godot-game": "^0.6.0"
           }
         }
@@ -625,7 +625,7 @@ workspace:
         console.log(`Cleaned ${toDelete.length} directories.`);
     - path: tools/kernel.config.ts
       content: |
-        import { defineKernelConfig } from "@warpgogol/werkstatt/kernel/types";
+        import { defineKernelConfig } from "@warpgogol/werkstatt-engine/kernel/types";
         import { werkstattGodotPlugin } from "@warpgogol/werkstatt-godot-game";
 
         export default defineKernelConfig({
@@ -646,16 +646,16 @@ workspace:
             "forge-exploration": async () => (await import("@warpgogol/forge/os/exploration")).forgeExplorationModule,
             "forge-program": async () => (await import("@warpgogol/forge/os/program")).forgeProgramModule,
             "forge-werkstatt": async () => (await import("@warpgogol/forge/os/werkstatt")).forgeWerkstattModule,
-            mission: async () => (await import("@warpgogol/werkstatt/mission-module")).createMissionModule(),
-            sternsystem: async () => (await import("@warpgogol/werkstatt/sternsystem-module")).createSternsystemModule(),
-            bordbuch: async () => (await import("@warpgogol/werkstatt/bordbuch-module")).createBordbuchModule(),
-            "artifact-store": async () => (await import("@warpgogol/werkstatt/artifact-store-module")).createArtifactStoreModule(),
-            release: async () => (await import("@warpgogol/werkstatt/release-module")).createReleaseModule(),
-            leitstand: async () => (await import("@warpgogol/werkstatt/leitstand-module")).createLeitstandModule(),
-            notausgang: async () => (await import("@warpgogol/werkstatt/notausgang-module")).createNotausgangModule(),
-            evidence: async () => (await import("@warpgogol/werkstatt/evidence-module")).createEvidenceModule(),
-            "werkstatt-plugin": async () => (await import("@warpgogol/werkstatt/os/werkstatt-plugin-module")).forgeWerkstattPluginModule,
-            "werkstatt-autonomy": async () => (await import("@warpgogol/werkstatt/os/werkstatt-autonomy-module")).werkstattAutonomyModule,
+            mission: async () => (await import("@warpgogol/werkstatt-engine/mission-module")).createMissionModule(),
+            sternsystem: async () => (await import("@warpgogol/werkstatt-engine/sternsystem-module")).createSternsystemModule(),
+            bordbuch: async () => (await import("@warpgogol/werkstatt-engine/bordbuch-module")).createBordbuchModule(),
+            "artifact-store": async () => (await import("@warpgogol/werkstatt-engine/artifact-store-module")).createArtifactStoreModule(),
+            release: async () => (await import("@warpgogol/werkstatt-engine/release-module")).createReleaseModule(),
+            leitstand: async () => (await import("@warpgogol/werkstatt-engine/leitstand-module")).createLeitstandModule(),
+            notausgang: async () => (await import("@warpgogol/werkstatt-engine/notausgang-module")).createNotausgangModule(),
+            evidence: async () => (await import("@warpgogol/werkstatt-engine/evidence-module")).createEvidenceModule(),
+            "werkstatt-plugin": async () => (await import("@warpgogol/werkstatt-engine/os/werkstatt-plugin-module")).forgeWerkstattPluginModule,
+            "werkstatt-autonomy": async () => (await import("@warpgogol/werkstatt-engine/os/werkstatt-autonomy-module")).werkstattAutonomyModule,
             "__PROJECT_NAME__-plugin": async () => werkstattGodotPlugin,
           },
         });
@@ -792,7 +792,7 @@ workspace:
 
         ## Stack
 
-        - Engine: @warpgogol/werkstatt
+        - Engine: @warpgogol/werkstatt-engine
         - Plugin: @warpgogol/werkstatt-godot-game
         - Stack profile: godot-csharp
 install:

package/profiles/knowledge-typescript-turborepo.yaml

@@ -104,7 +104,7 @@ plugin:
   id: werkstatt-knowledge
   package: "@warpgogol/werkstatt-knowledge"
 install:
-  - pnpm add -wD @warpgogol/forge @warpgogol/werkstatt @warpgogol/werkstatt-knowledge prettier
+  - pnpm add -wD @warpgogol/forge @warpgogol/werkstatt-engine @warpgogol/werkstatt-knowledge prettier
 agents:
   root: |
     # Knowledge Base Workshop

package/profiles/phaser-turborepo.yaml

@@ -228,7 +228,7 @@ workspace:
         console.log(`Cleaned ${toDelete.length} directories.`);
     - path: tools/kernel.config.ts
       content: |
-        import { defineKernelConfig } from "@warpgogol/werkstatt/kernel/types";
+        import { defineKernelConfig } from "@warpgogol/werkstatt-engine/kernel/types";
         import { werkstattPhaserPlugin } from "@warpgogol/werkstatt-phaser-game";
 
         export default defineKernelConfig({
@@ -249,16 +249,16 @@ workspace:
             "forge-exploration": async () => (await import("@warpgogol/forge/os/exploration")).forgeExplorationModule,
             "forge-program": async () => (await import("@warpgogol/forge/os/program")).forgeProgramModule,
             "forge-werkstatt": async () => (await import("@warpgogol/forge/os/werkstatt")).forgeWerkstattModule,
-            mission: async () => (await import("@warpgogol/werkstatt/mission-module")).createMissionModule(),
-            sternsystem: async () => (await import("@warpgogol/werkstatt/sternsystem-module")).createSternsystemModule(),
-            bordbuch: async () => (await import("@warpgogol/werkstatt/bordbuch-module")).createBordbuchModule(),
-            "artifact-store": async () => (await import("@warpgogol/werkstatt/artifact-store-module")).createArtifactStoreModule(),
-            release: async () => (await import("@warpgogol/werkstatt/release-module")).createReleaseModule(),
-            leitstand: async () => (await import("@warpgogol/werkstatt/leitstand-module")).createLeitstandModule(),
-            notausgang: async () => (await import("@warpgogol/werkstatt/notausgang-module")).createNotausgangModule(),
-            evidence: async () => (await import("@warpgogol/werkstatt/evidence-module")).createEvidenceModule(),
-            "werkstatt-plugin": async () => (await import("@warpgogol/werkstatt/os/werkstatt-plugin-module")).forgeWerkstattPluginModule,
-            "werkstatt-autonomy": async () => (await import("@warpgogol/werkstatt/os/werkstatt-autonomy-module")).werkstattAutonomyModule,
+            mission: async () => (await import("@warpgogol/werkstatt-engine/mission-module")).createMissionModule(),
+            sternsystem: async () => (await import("@warpgogol/werkstatt-engine/sternsystem-module")).createSternsystemModule(),
+            bordbuch: async () => (await import("@warpgogol/werkstatt-engine/bordbuch-module")).createBordbuchModule(),
+            "artifact-store": async () => (await import("@warpgogol/werkstatt-engine/artifact-store-module")).createArtifactStoreModule(),
+            release: async () => (await import("@warpgogol/werkstatt-engine/release-module")).createReleaseModule(),
+            leitstand: async () => (await import("@warpgogol/werkstatt-engine/leitstand-module")).createLeitstandModule(),
+            notausgang: async () => (await import("@warpgogol/werkstatt-engine/notausgang-module")).createNotausgangModule(),
+            evidence: async () => (await import("@warpgogol/werkstatt-engine/evidence-module")).createEvidenceModule(),
+            "werkstatt-plugin": async () => (await import("@warpgogol/werkstatt-engine/os/werkstatt-plugin-module")).forgeWerkstattPluginModule,
+            "werkstatt-autonomy": async () => (await import("@warpgogol/werkstatt-engine/os/werkstatt-autonomy-module")).werkstattAutonomyModule,
             "__PROJECT_NAME__-plugin": async () => werkstattPhaserPlugin,
           },
         });
@@ -360,11 +360,11 @@ workspace:
 
         ## Stack
 
-        - Engine: @warpgogol/werkstatt
+        - Engine: @warpgogol/werkstatt-engine
         - Plugin: @warpgogol/werkstatt-phaser-game
         - Stack profile: phaser-turborepo
 install:
-  - pnpm add -wD typescript turbo @warpgogol/forge @warpgogol/werkstatt @warpgogol/werkstatt-shared @warpgogol/werkstatt-phaser-game prettier
+  - pnpm add -wD typescript turbo @warpgogol/forge @warpgogol/werkstatt-engine @warpgogol/werkstatt-shared @warpgogol/werkstatt-phaser-game prettier
 firstWorkspace:
   path: apps/my-game
   files:

package/skills/fo/fo-add-tests/SKILL.md

@@ -15,6 +15,60 @@ Before starting, read `PREFERENCES.md` at the repository root. If the file is mi
 
 Write tests for code that was produced in the current session, or for a file/module the operator points at. The skill decides per-function whether to write example-based tests, property based tests (PBT), or both — following the RFC-XXXX decision tree and the TDD discipline absorbed from the former `tdd` skill.
 
+## Tests are written for agents, not humans
+
+The primary reader of test output is an **AI agent** looking at a console — not a human reading a test file. This changes how tests should be written:
+
+### Agent-readable failure messages
+
+When a test fails, the agent reading the console output needs to know **what to fix and where**. Vitest's default output shows the assertion, the expected value, and the received value. For simple assertions this is enough — `expect(result).toBe(42)` failing with `received 41` makes the fix obvious.
+
+For **non-obvious failures** — complex invariants, multi-step pipelines, domain-specific rules — add a failure message that tells the agent what went wrong and where to look:
+
+```ts
+// Good: obvious failure — no message needed
+expect(normalized).toBe("hello world");
+
+// Good: non-obvious failure — message guides the agent
+expect(
+  result.deduplicatedCount,
+  "Pipeline must skip already-validated entries. If count > 0, check the dedup guard in validateEntry() — entries with a matching hash in the seen-set should be skipped, not re-processed.",
+).toBe(0);
+
+// Good: invariant failure — message explains the contract
+expect(
+  manifest.entries.length,
+  "Every published Nachweis must produce exactly one manifest entry. Missing entries indicate nachweis-publish.ts skipped a record — check the bordbuch filter.",
+).toBe(publishedCount);
+```
+
+### When to add a message
+
+- **Obvious from the assertion** (simple equality, type check, presence check) → no message needed. The assertion itself is the documentation.
+- **Non-obvious invariant** (multi-step pipeline, domain rule, cross-module contract) → add a message explaining what the invariant is and where to look if it fails.
+- **PBT property** → the comment above the property already explains the algebraic property. No additional failure message needed unless the property name is unclear.
+
+### What makes a good failure message
+
+A good failure message answers two questions for the agent:
+
+1. **What is the invariant?** — state the contract in plain language.
+2. **Where to look** — name the function, file, or logic branch that is likely wrong.
+
+Bad: `"test failed"` — tells the agent nothing. Bad: `"count should be zero"` — restates the assertion, adds no information. Good: `"Pipeline must skip already-validated entries — check the dedup guard in validateEntry()"` — states the invariant and points to the likely fix location.
+
+### Test naming
+
+Test names are specifications — they describe behavior, not implementation. An agent scanning test names should understand what the system does without reading the test body.
+
+```ts
+// Bad — describes implementation
+test("calls validateEntry with correct args", () => { ... });
+
+// Good — describes behavior
+test("pipeline skips entries that were already validated in a previous run", () => { ... });
+```
+
 ## Preconditions
 
 - The code to test must exist in the workspace — either produced earlier in this session, or at a path the operator provides.

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

@@ -123,6 +123,7 @@ Output a summary:
 ## Completion criteria
 
 - All discovered files have `MODULE_CONTRACT` and `CHANGE_SUMMARY` blocks.
+- 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).
 - All changes are committed with message `compass: update headers for changed files`.