@warpgogol/forge 2.9.11 → 2.9.23

package/skills/fo/fo-idea-implement/SKILL.md

@@ -100,6 +100,26 @@ Stage only the files touched by this step. Do not stage unrelated changes — an
 - **Compass scaffolding.** New non-trivial source files in `apps/` or `packages/` must carry `MODULE_CONTRACT` and `CHANGE_SUMMARY` scaffolding. Check the project's invariants file for the canonical Compass markup rule.
 - **Compass terminology.** Use Compass (not GRACE) in all new code, documentation, and log messages.
 
+#### 4.3b. Write tests
+
+After implementing each plan step that produces or modifies code, write tests for the new behavior. Tests are written for **agents**, not humans — see `fo-add-tests` for the full process and decision tree.
+
+**Principles:**
+
+- **Test through public interfaces.** Tests verify behavior, not implementation details.
+- **Agent-readable failures.** When a test fails, the error message should tell an agent reading the console output what to fix and where — but only when the fix is not obvious from the assertion itself. If `expect(result).toBe(42)` fails with `received 41`, the fix is obvious. If a complex invariant fails, add a failure message: `expect(result, "Pipeline must skip already-validated entries — check the dedup guard in <function>")`).toEqual(expected)`.
+- **Per-function classification.** Pure functions with verifiable properties get PBT (`*.pbt.test.ts`); everything else gets example-based tests (`*.test.ts`). See `fo-add-tests` §Process step 2.
+- **Do not weaken or delete existing tests** without explicit operator direction.
+- **Run tests after writing them:** `ref(forge.yaml bindings.commands.test) --filter <package>` or `pnpm --filter <package> test`.
+
+Commit tests alongside the implementation they cover, or as a separate commit if the step was large:
+
+```txt
+test: RFC-XXXX step N — cover <module>
+
+Add unit and PBT coverage for <what was implemented in this step>.
+```
+
 #### 4.4. Run heavy checks
 
 After **all** plan steps are complete, run the heavy validation suite in order:
@@ -232,6 +252,26 @@ If the RFC has no `commands.*` changes (e.g. it only changes schemas, docs, or i
 
 This step is MANDATORY for any RFC with `commands.added`, `commands.changed`, or `commands.removed`. A stale manifest causes `RFC-CMD-02` violations that block `rfc.validate` for all implemented RFCs.
 
+#### 4.8c. Regenerate agent files (AGENTS.md)
+
+If the implementation changed contracts, conventions, commands, pipelines, package boundaries, or workflows that agents rely on, regenerate `AGENTS.md` so the generated instructions stay in sync with code:
+
+```sh
+ref(forge.yaml bindings.commands.agentsGenerate)
+```
+
+This regenerates root and nested `AGENTS.md` files from `forge.yaml` and stack profile data. The generated files carry a `<!-- forge:generated -->` marker — hand-written `AGENTS.md` files are never overwritten.
+
+Commit regenerated agent files:
+
+```txt
+docs: regenerate AGENTS.md for RFC-XXXX
+
+Update generated agent instructions after RFC-XXXX implementation changes.
+```
+
+Stage only the regenerated `AGENTS.md` files. If no agent-facing contracts changed (e.g. internal logic refactor with no new commands or conventions), skip this step.
+
 #### 4.9. Documentation audit (fo-doc-audit)
 
 After implementation is complete and all checks pass, invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces (AGENTS.md, README, Compass XML, architecture-dna.md, templates, generated artifacts, COMMANDS.md/PACKAGE_GRAPH.md), applies needed updates, and commits them separately. Wait for it to complete.
@@ -339,6 +379,26 @@ Read the `## Decision` section and implement it in code. **For each decision poi
 
 - If a tool call fails with a recoverable error, recover autonomously: split content, use `edit`/`multi_edit`, decompose files, and retry immediately.
 
+#### 5.3b. Write tests
+
+After implementing the decision, write tests for the new behavior. Tests are written for **agents**, not humans — see `fo-add-tests` for the full process and decision tree.
+
+**Principles:**
+
+- **Test through public interfaces.** Tests verify behavior, not implementation details.
+- **Agent-readable failures.** When a test fails, the error message should tell an agent reading the console output what to fix and where — but only when the fix is not obvious from the assertion itself. If `expect(result).toBe(42)` fails with `received 41`, the fix is obvious. If a complex invariant fails, add a failure message: `expect(result, "Pipeline must skip already-validated entries — check the dedup guard in <function>")`).toEqual(expected)`.
+- **Per-function classification.** Pure functions with verifiable properties get PBT (`*.pbt.test.ts`); everything else gets example-based tests (`*.test.ts`). See `fo-add-tests` §Process step 2.
+- **Do not weaken or delete existing tests** without explicit operator direction.
+- **Run tests after writing them:** `ref(forge.yaml bindings.commands.test) --filter <package>` or `pnpm --filter <package> test`.
+
+Commit tests alongside the implementation they cover:
+
+```txt
+test: ADR-XXXX — cover <module>
+
+Add unit and PBT coverage for <what was implemented>.
+```
+
 #### 5.4. Run scoped build checks
 
 After implementation is complete, run heavy checks for the impacted workspaces only:
@@ -387,6 +447,26 @@ After implementation is complete and all checks pass, invoke `fo-doc-audit` via
 
 If `fo-doc-audit` reports that no updates are needed, proceed to the next step.
 
+#### 5.6b. Regenerate agent files (AGENTS.md)
+
+If the implementation changed contracts, conventions, commands, pipelines, package boundaries, or workflows that agents rely on, regenerate `AGENTS.md` so the generated instructions stay in sync with code:
+
+```sh
+ref(forge.yaml bindings.commands.agentsGenerate)
+```
+
+This regenerates root and nested `AGENTS.md` files from `forge.yaml` and stack profile data. The generated files carry a `<!-- forge:generated -->` marker — hand-written `AGENTS.md` files are never overwritten.
+
+Commit regenerated agent files:
+
+```txt
+docs: regenerate AGENTS.md for ADR-XXXX
+
+Update generated agent instructions after ADR-XXXX implementation changes.
+```
+
+Stage only the regenerated `AGENTS.md` files. If no agent-facing contracts changed, skip this step.
+
 #### 5.7. Code review (fo-review)
 
 After the documentation audit, invoke `fo-review` via the `skill` tool. It performs a cross-session fitness check of the code diff against Forge standards. The review covers all code changes made in this session.

package/src/compass/contract-registry.ts

@@ -0,0 +1,114 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Compass contract block registry — loads built-in and pack-declared block specs from forge.plugin.yaml manifests. Declarative data only, no executable hooks (RFC-0943).</purpose>
+<non-goals>
+  <item>Do not execute pack-provided validate() functions — block specs are declarative data interpreted by compass.validate.</item>
+  <item>Do not import from os/ or kernel modules — this is a portable contract module.</item>
+  <item>Do not handle FORBIDDEN_PATTERNS — the negative list stays hardcoded in compass-inventory.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0943: initial contract registry with built-in specs and pack-declared block loading.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import picomatch from "picomatch";
+import type { ForgeConfig } from "../config/forge-config.ts";
+import { forgePluginManifestSchema } from "../plugin/ForgePluginManifest.ts";
+import type {
+  CompassContractBlockSpec,
+  CompassContractRegistry,
+  CompassContractRegistryEntry,
+} from "./types.ts";
+
+const BUILT_IN_SPECS: CompassContractBlockSpec[] = [
+  {
+    blockId: "module-contract",
+    requiredFor: ["packages/**/*.ts", "packages/**/*.tsx", "packages/**/*.astro", "packages/**/*.js", "packages/**/*.mjs", "services/**/*.ts", "apps/**/*.ts", "apps/**/*.tsx", "apps/**/*.astro"],
+    requiredTags: [
+      { name: "purpose", minWords: 10 },
+      { name: "non-goals" },
+    ],
+  },
+  {
+    blockId: "change-summary",
+    requiredFor: ["packages/**/*.ts", "packages/**/*.tsx", "packages/**/*.astro", "packages/**/*.js", "packages/**/*.mjs", "services/**/*.ts", "apps/**/*.ts", "apps/**/*.tsx", "apps/**/*.astro"],
+    requiredTags: [],
+  },
+];
+
+export function getBuiltInSpecs(): CompassContractBlockSpec[] {
+  return BUILT_IN_SPECS;
+}
+
+export function loadContractRegistry(
+  workspaceRoot: string,
+  config?: ForgeConfig,
+): CompassContractRegistry {
+  const pack: CompassContractRegistryEntry[] = [];
+  const seenBlockIds = new Set<string>();
+
+  if (config?.skillPacks) {
+    for (const skillPack of config.skillPacks) {
+      const packDir = path.resolve(workspaceRoot, skillPack.dir);
+      const manifestPath = path.join(packDir, "forge.plugin.yaml");
+      if (!fs.existsSync(manifestPath)) continue;
+
+      let manifestRaw: string;
+      try {
+        manifestRaw = fs.readFileSync(manifestPath, "utf-8");
+      } catch {
+        continue;
+      }
+
+      let manifestParsed: unknown;
+      try {
+        manifestParsed = parseYaml(manifestRaw);
+      } catch {
+        continue;
+      }
+
+      const result = forgePluginManifestSchema.safeParse(manifestParsed);
+      if (!result.success) continue;
+
+      const manifest = result.data;
+      const blocks = manifest.extensionPoints?.compass?.contract?.blocks;
+      if (!blocks || blocks.length === 0) continue;
+
+      for (const block of blocks) {
+        if (seenBlockIds.has(block.blockId)) {
+          throw new Error(
+            `COMPASS-PLUGIN-DUP-01: duplicate blockId "${block.blockId}" declared by pack "${manifest.id}" — already declared by another pack. Each blockId must be unique across all packs.`,
+          );
+        }
+        seenBlockIds.add(block.blockId);
+        pack.push({
+          blockId: block.blockId,
+          requiredFor: block.requiredFor,
+          requiredTags: block.requiredTags,
+          packId: manifest.id,
+        });
+      }
+    }
+  }
+
+  return {
+    builtIn: BUILT_IN_SPECS,
+    pack,
+  };
+}
+
+export function fileMatchesGlobs(filePath: string, globs: string[]): boolean {
+  const matchers = globs.map((g) => picomatch(g, { dot: true }));
+  return matchers.some((m) => m(filePath));
+}
+
+export function findApplicablePackSpecs(
+  registry: CompassContractRegistry,
+  filePath: string,
+): CompassContractRegistryEntry[] {
+  return registry.pack.filter((spec) => fileMatchesGlobs(filePath, spec.requiredFor));
+}

package/src/compass/types.ts

@@ -0,0 +1,45 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Compass contract block spec types for plugin-extensible Compass validation (RFC-0943). Declarative data contracts only — no executable hooks.</purpose>
+<non-goals>
+  <item>Do not define validate() functions — block specs are declarative data, interpreted by compass.validate.</item>
+  <item>Do not import from os/ or kernel modules — this is a portable contract module.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0943: initial CompassContractBlockSpec and CompassContractExtensionPoint types.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface CompassContractRequiredTag {
+  name: string;
+  minWords?: number;
+}
+
+export interface CompassContractBlockSpec {
+  blockId: string;
+  requiredFor: string[];
+  requiredTags?: CompassContractRequiredTag[];
+}
+
+export interface CompassContractExtensionPoint {
+  blocks: CompassContractBlockSpec[];
+}
+
+export interface CompassContractRegistryEntry extends CompassContractBlockSpec {
+  packId: string;
+}
+
+export interface CompassContractRegistry {
+  builtIn: CompassContractBlockSpec[];
+  pack: CompassContractRegistryEntry[];
+}
+
+export interface CompassContractValidationDiagnostic {
+  ruleId: string;
+  severity: string;
+  file: string;
+  message: string;
+  fix: string;
+  pack?: string;
+}

package/src/forge-module.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>ForgeModule interfaces — structurally compatible with KernelModule from @warpgogol/site-kernel. Forge does NOT import from site-kernel.</purpose>
+<purpose>ForgeModule interfaces — structurally compatible with KernelModule from @warpgogol/site-kernel. Forge does NOT import from site-kernel. The optional runtime field (RFC-0940) declares whether a module is autonomous or a werkstatt adapter.</purpose>
 <non-goals>
   <item>Do not import from @warpgogol/site-kernel — forge must be installable without it.</item>
   <item>Do not add project-specific fields to ForgeModule — keep it minimal and portable.</item>
@@ -9,6 +9,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial ForgeModule, ForgeModuleRegistry, ForgeCommandDefinition, ForgePipelineStep interfaces.</item>
   <item>Forge autonomy refactor: ForgeCommandDefinition and ForgeCommandResult now reference canonical types from types.ts.</item>
+  <item>RFC-0940: add optional runtime field to ForgeModule for autonomy declaration.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -27,6 +28,7 @@ export interface ForgeModuleRegistry {
 export interface ForgeModule {
   name: string;
   version: string;
+  runtime: "autonomous" | "werkstatt-adapter";
   register(registry: ForgeModuleRegistry): void | Promise<void>;
 }
 

package/src/index.ts

@@ -155,6 +155,22 @@ export {
   detectAdapters,
 } from "./migration-adapters/index.ts";
 
+// Plugin manifest (RFC-0941, RFC-0943)
+export {
+  forgePluginManifestSchema,
+  type ForgePluginManifest,
+} from "./plugin/ForgePluginManifest.ts";
+
+// Compass contract types (RFC-0943)
+export type {
+  CompassContractBlockSpec,
+  CompassContractRequiredTag,
+  CompassContractExtensionPoint,
+  CompassContractRegistry,
+  CompassContractRegistryEntry,
+  CompassContractValidationDiagnostic,
+} from "./compass/types.ts";
+
 // OS modules
 export { forgeCoreModule } from "../os/core/core.module.ts";
 export { forgeRfcModule } from "../os/rfc/rfc.module.ts";
@@ -170,3 +186,4 @@ export { forgeMissionModule } from "../os/mission/mission.module.ts";
 export { forgeExplorationModule } from "../os/exploration/exploration.module.ts";
 export { forgeNotesModule } from "../os/notes/notes.module.ts";
 export { forgeProgramModule } from "../os/program/program.module.ts";
+export { forgePluginModule } from "../os/plugin/plugin.module.ts";

package/src/onboarding/doctor.ts

@@ -22,13 +22,15 @@ Checks for forge.yaml, AGENTS.md, PREFERENCES.md, .agents/skills/, docs/rfcs/,
   <item>RFC-0663: added knowledge-duplicates check (cross-skill L2 duplicate detection) and shared-knowledge-file check (schema/id uniqueness for the shared layer).</item>
   <item>RFC-0664: added memory-layer health check (budget usage, gitignore coverage, daily-file leak risk).</item>
   <item>RFC-0704: added independent-version-packages check — validates that paths in independentVersionPackages exist and contain package.json.</item>
+  <item>RFC-0941: added pack-manifests advisory check — validates forge.plugin.yaml existence and schema for each declared skill pack.</item>
 </CHANGE_SUMMARY>
 */
 
 import { readFile, readdir, stat } from "node:fs/promises";
-import { readFileSync } from "node:fs";
-import { join, relative, dirname } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+import { join, relative, dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { forgePluginManifestSchema } from "../plugin/ForgePluginManifest.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -256,7 +258,12 @@ async function checkStaleKnowledgeFiles(
   }
 
   // RFC-0539: Check pack skill knowledge files
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill checks
+  }
   for (const skill of packSkills) {
     if (!skill.knowledge || skill.knowledge.length === 0) continue;
 
@@ -327,7 +334,12 @@ function checkLegacyKnowledgeSections(
   }
 
   // Check pack skills
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill checks
+  }
   for (const skill of packSkills) {
     if (!skill.knowledge || skill.knowledge.length === 0) continue;
     const skillDir = join(workspaceRoot, skill.dir, dirname(skill.path));
@@ -416,7 +428,12 @@ function checkKnowledgeBudgets(
     }
   }
 
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill checks
+  }
   for (const skill of packSkills) {
     if (!skill.knowledge || skill.knowledge.length === 0) continue;
     const skillDir = join(workspaceRoot, skill.dir, dirname(skill.path));
@@ -503,7 +520,12 @@ function collectL2Files(
     }
   }
 
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill checks
+  }
   for (const skill of packSkills) {
     if (!skill.knowledge || skill.knowledge.length === 0) continue;
     const skillDir = join(workspaceRoot, skill.dir, dirname(skill.path));
@@ -700,7 +722,12 @@ async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
   }
 
   // Check for stale/missing pack skill copies
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill checks
+  }
   const agentsSkillsDir = join(workspaceRoot, config.paths.skillsDir);
 
   for (const skill of packSkills) {
@@ -731,6 +758,57 @@ async function checkPackSkills(workspaceRoot: string): Promise<DoctorCheck> {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Pack manifest diagnostics (RFC-0941)
+// ---------------------------------------------------------------------------
+
+async function checkPackManifests(workspaceRoot: string): Promise<DoctorCheck> {
+  let config;
+  try {
+    config = loadForgeConfig(workspaceRoot);
+  } catch {
+    return {
+      name: "pack-manifests",
+      status: "pass",
+      message: "forge.yaml not loadable — pack manifest check skipped",
+    };
+  }
+
+  if (!config.skillPacks || config.skillPacks.length === 0) {
+    return { name: "pack-manifests", status: "pass", message: "No skill packs declared" };
+  }
+
+  const issues: string[] = [];
+  for (const pack of config.skillPacks) {
+    const packDir = resolve(workspaceRoot, pack.dir);
+    const manifestPath = join(packDir, "forge.plugin.yaml");
+    if (!existsSync(manifestPath)) {
+      issues.push(`pack '${pack.prefix}': forge.plugin.yaml missing at ${pack.dir}`);
+      continue;
+    }
+    try {
+      const raw = readFileSync(manifestPath, "utf-8");
+      const parsed = parseYaml(raw) as unknown;
+      const result = forgePluginManifestSchema.safeParse(parsed);
+      if (!result.success) {
+        const errs = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+        issues.push(`pack '${pack.prefix}': invalid manifest — ${errs}`);
+      }
+    } catch (err) {
+      issues.push(`pack '${pack.prefix}': failed to read manifest — ${(err as Error).message}`);
+    }
+  }
+
+  return {
+    name: "pack-manifests",
+    status: issues.length === 0 ? "pass" : "warn",
+    message:
+      issues.length === 0
+        ? `${config.skillPacks.length} pack manifest(s) valid`
+        : `${issues.length} issue(s): ${issues.join(", ")}`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Nested AGENTS.md diagnostics (RFC-0611)
 // ---------------------------------------------------------------------------
@@ -1225,6 +1303,10 @@ export async function runDoctor(
   const packCheck = await checkPackSkills(workspaceRoot);
   checks.push(packCheck);
 
+  // RFC-0941: Check pack manifests — forge.plugin.yaml existence and validity
+  const packManifestCheck = await checkPackManifests(workspaceRoot);
+  checks.push(packManifestCheck);
+
   // RFC-0704: Check independent version packages — paths must exist and contain package.json
   const independentCheck = await checkIndependentVersionPackages(workspaceRoot);
   checks.push(independentCheck);

package/src/onboarding/init.ts

@@ -20,6 +20,7 @@
   <item>RFC-0640: accept optional domain fields from profile (register, domain, terminology, semanticBindings) and write them into PREFERENCES.md and forge.yaml.</item>
   <item>RFC-0643: accept optional profileId and write it to forge.yaml as the `profile` field.</item>
   <item>RFC-0663: added syncSharedKnowledge step to sync shared knowledge layer to .agents/skills/shared-knowledge/.</item>
+  <item>RFC-0941: create forge.plugin.yaml manifests for skill packs that lack them before calling discoverPackSkills.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -244,7 +245,25 @@ export function runInit(
   // RFC-0539: Copy declared pack skills to .agents/skills/<name>/ for IDE discovery
   // RFC-0552: Detect Forge-vs-pack skill name conflicts, skip pack skills that conflict
   const forgeSkillNames = new Set(FORGE_SKILLS.map((s) => s.name));
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  // RFC-0941: Create forge.plugin.yaml for packs that lack manifests
+  if (config.skillPacks) {
+    for (const pack of config.skillPacks) {
+      const packDir = path.resolve(workspaceRoot, pack.dir);
+      if (!fs.existsSync(packDir)) continue;
+      const manifestPath = path.join(packDir, "forge.plugin.yaml");
+      if (!fs.existsSync(manifestPath)) {
+        const manifest = { id: pack.prefix, version: "1.0.0" };
+        fs.writeFileSync(manifestPath, stringifyYaml(manifest), "utf8");
+        created.push(path.relative(workspaceRoot, manifestPath));
+      }
+    }
+  }
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest creation should prevent this, but catch defensively
+  }
   for (const skill of packSkills) {
     const srcPath = path.join(workspaceRoot, skill.dir, skill.path);
     const skillName = skill.name;

package/src/onboarding/scaffold.ts

@@ -111,6 +111,7 @@ import type { ForgeModule, ForgeCommandDefinition } from "../../src/forge-module
 export const forge${capitalize(name)}Module: ForgeModule = {
   name: "forge-${name}",
   version: "0.1.0",
+  runtime: "autonomous",
   register(registry) {
     registry.registerCommand({
       name: "${name}",

package/src/onboarding/templates/behavioral-layer-core.md

@@ -34,6 +34,15 @@ Session save mechanism:
 
 The agent SHOULD auto-run `fo-review` after implementing a significant change. Review results are presented in creator language — only actionable issues are highlighted.
 
+### Auto-testing
+
+The agent SHOULD write tests for new code it produces. Tests are written for **agents**, not humans — when a test fails, the error message should tell an agent reading the console output what to fix and where, but only when the fix is not obvious from the assertion itself.
+
+- **Significant changes** (new features, new functions, bug fixes) → write tests.
+- **Minor edits** (typo fix, small CSS change, renaming a variable) → no new tests required.
+- Use `fo-add-tests` for the full process and decision tree (example-based vs PBT).
+- Do not weaken or delete existing tests without explicit operator direction.
+
 ### Context awareness
 
 Before starting significant work, the agent SHOULD read recent ADRs, RFCs, and session transcripts (last 5-10 documents) to understand prior decisions and avoid conflicts. Minor edits do not require context reading.

package/src/onboarding/upgrade.ts

@@ -213,7 +213,12 @@ function syncPackSkills(
   const updated: string[] = [];
   const skipped: SkippedSkill[] = [];
   const agentsSkillsDir = path.join(workspaceRoot, skillsDir);
-  const packSkills = discoverPackSkills(workspaceRoot, config);
+  let packSkills: ReturnType<typeof discoverPackSkills> = [];
+  try {
+    packSkills = discoverPackSkills(workspaceRoot, config);
+  } catch {
+    // Manifest missing or invalid — skip pack skill sync
+  }
   const forgeSkillNames = new Set(FORGE_SKILLS.map((s) => s.name));
 
   for (const skill of packSkills) {

package/src/plugin/ForgePluginManifest.ts

@@ -0,0 +1,76 @@
+/*
+<MODULE_CONTRACT>
+<purpose>ForgePluginManifest — pack identity contract for project-declared skill packs (RFC-0941). Strict Zod schema with optional extensionPoints (RFC-0943).</purpose>
+<non-goals>
+  <item>Do not add forgeRange, commands, or skills fields — deferred until real use cases emerge.</item>
+  <item>Do not replace forge.yaml bindings — the manifest declares pack identity and extension points only.</item>
+  <item>Do not allow pack-provided validate() functions — extension points are declarative data, not executable code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0941: initial ForgePluginManifest interface and Zod schema.</item>
+  <item>RFC-0943: added optional extensionPoints.compass.contract field for declarative Compass contract block specs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const SEMVER_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+const compassContractBlockSpecSchema = z.object({
+  blockId: z
+    .string()
+    .regex(KEBAB_CASE_REGEX, "blockId must be kebab-case (lowercase letters, digits, hyphens)"),
+  requiredFor: z.array(z.string().min(1)).min(1),
+  requiredTags: z
+    .array(
+      z.object({
+        name: z.string().min(1),
+        minWords: z.number().int().positive().optional(),
+      }),
+    )
+    .optional(),
+});
+
+const compassContractExtensionPointSchema = z.object({
+  blocks: z.array(compassContractBlockSpecSchema),
+});
+
+const extensionPointsSchema = z
+  .object({
+    compass: z
+      .object({
+        contract: compassContractExtensionPointSchema.optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export const forgePluginManifestSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(KEBAB_CASE_REGEX, "id must be kebab-case (lowercase letters, digits, hyphens)"),
+    version: z.string().regex(SEMVER_REGEX, "version must be a valid semver string (e.g. 1.0.0)"),
+    extensionPoints: extensionPointsSchema.optional(),
+  })
+  .strict();
+
+export interface ForgePluginManifest {
+  id: string;
+  version: string;
+  extensionPoints?: {
+    compass?: {
+      contract?: {
+        blocks: Array<{
+          blockId: string;
+          requiredFor: string[];
+          requiredTags?: Array<{ name: string; minWords?: number }>;
+        }>;
+      };
+    };
+  };
+}