@warpgogol/forge 5.3.3 → 5.3.4

package/src/tests/doctor-skills-unmanaged.test.ts

@@ -0,0 +1,145 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for forge.doctor skills-unmanaged check (RFC-1226): SKILL.md-bearing dirs without .forge-managed are reported as warnings.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1226: initial tests — AC-1 warn on unmanaged, AC-2 pass when all marked, AC-3 skip non-skill dirs, AC-4 skip without config/skillsDir.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDoctor } from "../onboarding/doctor.ts";
+import { buildSkillMarkerContent } from "../onboarding/skill-markers.ts";
+import type { ForgeRuntimeContext, ForgeLogger } from "../types.ts";
+
+const mockLogger: ForgeLogger = {
+  section: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  success: () => {},
+};
+
+const mockContext = (workspaceRoot: string): ForgeRuntimeContext => ({
+  workspaceRoot,
+  logger: mockLogger,
+  dryRun: false,
+  outputFormat: "json",
+});
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-doctor-unmanaged-test-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+const FORGE_YAML = `schema: forge/config@1
+project:
+  name: test
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    validateAdr: null
+    implementStamp: null
+    typecheck: null
+    test: null
+    scopedBuild: null
+    specValidate: null
+    sessionSave: null
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+`;
+
+const SKILL_MD = "---\nname: test-skill\ndescription: test\n---\n# Test\n";
+
+async function writeSkill(dir: string, name: string, managed: boolean): Promise<void> {
+  const skillDir = join(dir, ".agents", "skills", name);
+  await mkdir(skillDir, { recursive: true });
+  await writeFile(join(skillDir, "SKILL.md"), SKILL_MD, "utf8");
+  if (managed) {
+    await writeFile(
+      join(skillDir, ".forge-managed"),
+      buildSkillMarkerContent(["SKILL.md"]),
+      "utf8",
+    );
+  }
+}
+
+function findCheck(result: Awaited<ReturnType<typeof runDoctor>>) {
+  const check = result.data?.checks.find((c) => c.name === "skills-unmanaged");
+  expect(check, "skills-unmanaged check must be present").toBeDefined();
+  return check!;
+}
+
+test("AC-1: skills-unmanaged warns and names SKILL.md-bearing dirs without .forge-managed", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, ".agents", "skills"), { recursive: true });
+  await writeSkill(tempDir, "fo-managed-skill", true);
+  await writeSkill(tempDir, "ask-matt", false);
+  await writeSkill(tempDir, "tdd", false);
+
+  const result = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
+  const check = findCheck(result);
+  expect(check.status).toBe("warn");
+  expect(check.message).toContain("2 unmanaged skill dir(s)");
+  expect(check.message).toContain("ask-matt");
+  expect(check.message).toContain("tdd");
+  expect(check.message).not.toContain("fo-managed-skill");
+});
+
+test("AC-2: skills-unmanaged passes when every SKILL.md-bearing dir carries .forge-managed", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  await mkdir(join(tempDir, ".agents", "skills"), { recursive: true });
+  await writeSkill(tempDir, "fo-managed-skill", true);
+  await writeSkill(tempDir, "grilling", true);
+
+  const result = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
+  const check = findCheck(result);
+  expect(check.status).toBe("pass");
+});
+
+test("AC-3: skills-unmanaged excludes dirs without SKILL.md regardless of markers", async () => {
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const sharedDir = join(tempDir, ".agents", "skills", "_shared");
+  await mkdir(sharedDir, { recursive: true });
+  await writeFile(join(sharedDir, "notes.md"), "# support files\n", "utf8");
+  const knowledgeDir = join(tempDir, ".agents", "skills", "knowledge");
+  await mkdir(knowledgeDir, { recursive: true });
+  await writeFile(join(knowledgeDir, "learned-principles.md"), "# L2\n", "utf8");
+
+  const result = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
+  const check = findCheck(result);
+  expect(check.status).toBe("pass");
+});
+
+test("AC-4: skills-unmanaged passes without scanning when forge.yaml or skillsDir is absent", async () => {
+  // No forge.yaml at all
+  const noConfig = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
+  expect(findCheck(noConfig).status).toBe("pass");
+
+  // forge.yaml present, skillsDir absent
+  await writeFile(join(tempDir, "forge.yaml"), FORGE_YAML, "utf8");
+  const noSkillsDir = await runDoctor({ argv: [], flags: {} }, mockContext(tempDir));
+  expect(findCheck(noSkillsDir).status).toBe("pass");
+});

package/src/tests/forge-config.test.ts

@@ -6,6 +6,8 @@
   <item>RFC-0391: initial config tests.</item>
   <item>RFC-0538: added compass binding section tests.</item>
   <item>RFC-0540: added CLI binding defaults, pm-runner, and package-manager-aware defaultForgeConfig tests.</item>
+  <item>RFC-1224: adrImplementStamp binding, schema passthrough retention, applyForgeYamlPatches tests.</item>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
 </CHANGE_SUMMARY>
 */
 
@@ -20,6 +22,7 @@ import {
   forgeConfigSchema,
   forgeBindingsSchema,
   resolveBinding,
+  applyForgeYamlPatches,
   FORGE_CLI_BINDING_DEFAULTS,
   resolvePmRunner,
   applyCliBindingDefaults,
@@ -63,12 +66,13 @@ test("resolvePmRunner falls back to npx for unknown", () => {
   expect(resolvePmRunner("")).toBe("npx");
 });
 
-test("FORGE_CLI_BINDING_DEFAULTS has 5 entries with correct keys", () => {
-  expect(FORGE_CLI_BINDING_DEFAULTS).toHaveLength(5);
+test("FORGE_CLI_BINDING_DEFAULTS has 6 entries with correct keys", () => {
+  expect(FORGE_CLI_BINDING_DEFAULTS).toHaveLength(6);
   const keys = FORGE_CLI_BINDING_DEFAULTS.map((e) => e.key);
   expect(keys).toContain("commands.validateRfc");
   expect(keys).toContain("commands.validateAdr");
   expect(keys).toContain("commands.implementStamp");
+  expect(keys).toContain("commands.adrImplementStamp");
   expect(keys).toContain("commands.specValidate");
   expect(keys).toContain("commands.sessionSave");
 });
@@ -134,6 +138,9 @@ test("applyCliBindingDefaults returns forge-CLI bindings non-null and stack bind
   expect(commands.validateRfc).not.toBeNull();
   expect(commands.validateAdr).not.toBeNull();
   expect(commands.implementStamp).not.toBeNull();
+  expect(commands.adrImplementStamp).toBe(
+    "pnpm exec forge adr.implement.stamp --id {id} --implementation-commit {commit}",
+  );
   expect(commands.specValidate).not.toBeNull();
   expect(commands.sessionSave).not.toBeNull();
   expect(commands.typecheck).toBeNull();
@@ -418,3 +425,100 @@ bindings:
   expect(config.bindings?.compass?.fileExtensions).toEqual([".ts", ".astro"]);
   expect(config.bindings?.compass?.testPatterns).toEqual(["*.test.ts", "*.spec.ts"]);
 });
+
+// ---------------------------------------------------------------------------
+// RFC-1224: schema passthrough + forge.yaml document patching
+// ---------------------------------------------------------------------------
+
+test("RFC-1224: schema retains adrImplementStamp and consumer-defined command keys", async () => {
+  const yaml = `schema: forge/config@1
+project:
+  name: consumer-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null
+    adrImplementStamp: pnpm exec forge adr.implement.stamp --id {id} --implementation-commit {commit}
+    createRfc: pnpm exec forge rfc.create
+    manifestGenerate: pnpm exec forge manifest.generate
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+plugins:
+  - name: my-plugin
+`;
+  await writeFile(join(tempDir, "forge.yaml"), yaml, "utf8");
+  const config = loadForgeConfig(tempDir);
+
+  // Promoted key resolves through the typed interface
+  expect(config.bindings?.commands.adrImplementStamp).toBe(
+    "pnpm exec forge adr.implement.stamp --id {id} --implementation-commit {commit}",
+  );
+  // Consumer-defined keys stay resolvable via passthrough
+  expect(resolveBinding(config, "commands.createRfc")).toBe("pnpm exec forge rfc.create");
+  expect(resolveBinding(config, "commands.manifestGenerate")).toBe(
+    "pnpm exec forge manifest.generate",
+  );
+  // Unknown top-level sections survive the schema parse
+  expect((config as unknown as Record<string, unknown>)["plugins"]).toEqual([
+    { name: "my-plugin" },
+  ]);
+});
+
+test("RFC-1224: applyForgeYamlPatches preserves comments and consumer content", () => {
+  const raw = `schema: forge/config@1
+# operator comment — must survive
+project:
+  name: consumer-project
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: null  # inline comment
+    customKey: keep-me
+plugins:
+  - name: my-plugin
+forge:
+  syncedVersion: 0.1.0
+`;
+  const patched = applyForgeYamlPatches(raw, [
+    { path: ["forge", "syncedVersion"], value: "0.2.0" },
+    { path: ["bindings", "commands", "adrImplementStamp"], value: "forge adr.implement.stamp" },
+  ]);
+
+  expect(patched).not.toBeNull();
+  expect(patched).toContain("syncedVersion: 0.2.0");
+  expect(patched).toContain("adrImplementStamp: forge adr.implement.stamp");
+  expect(patched).toContain("customKey: keep-me");
+  expect(patched).toContain("# operator comment — must survive");
+  expect(patched).toContain("# inline comment");
+  expect(patched).toContain("my-plugin");
+});
+
+test("RFC-1224: applyForgeYamlPatches creates missing intermediate maps", () => {
+  const patched = applyForgeYamlPatches("schema: forge/config@1\n", [
+    { path: ["forge", "syncedVersion"], value: "0.2.0" },
+    { path: ["bindings", "commands", "adrImplementStamp"], value: "x" },
+  ]);
+  expect(patched).toContain("syncedVersion: 0.2.0");
+  expect(patched).toContain("adrImplementStamp: x");
+});
+
+test("RFC-1224: applyForgeYamlPatches returns null on invalid YAML", () => {
+  const patched = applyForgeYamlPatches("a: [unclosed\n  : :", [
+    { path: ["a"], value: 1 },
+  ]);
+  expect(patched).toBeNull();
+});

package/src/tests/skill-validate.test.ts

@@ -259,3 +259,183 @@ describe("SKILL-21: knowledge layer token budget warnings (RFC-0661)", () => {
     expect(skill21Warnings).toEqual([]);
   });
 });
+
+describe("RFC-1225: forge root + workspace config resolution", () => {
+  function createConsumerWorkspace(): { tmpDir: string; forgePkg: string } {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-skill-consumer-"));
+    const forgePkg = path.join(tmpDir, "node_modules", "@warpgogol", "forge");
+    fs.mkdirSync(forgePkg, { recursive: true });
+    fs.writeFileSync(
+      path.join(forgePkg, "package.json"),
+      JSON.stringify({ name: "@warpgogol/forge", version: "9.9.9" }),
+      "utf8",
+    );
+    return { tmpDir, forgePkg };
+  }
+
+  test("AC-1: consumer layout validates skills under node_modules/@warpgogol/forge", async () => {
+    const { FORGE_SKILLS } = await import("../registry.ts");
+    const { tmpDir, forgePkg } = createConsumerWorkspace();
+    try {
+      // Materialize one registry skill inside the installed package copy —
+      // the others stay absent and produce SKILL-01, which is honest.
+      const entry = FORGE_SKILLS.find((s) => !(s.knowledge && s.knowledge.length > 0))!;
+      const skillPath = path.join(forgePkg, entry.path);
+      fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+      fs.writeFileSync(
+        skillPath,
+        `---\nname: ${entry.name}\ndescription: Fixture skill for consumer root resolution\ninvocation: ${entry.invocation}\ncategory: ${entry.category}\nconcerns: ${entry.concerns}\ndependsOn: []\nlanguagePolicy: ref(PREFERENCES.md)\n---\n\nBefore starting, read \`PREFERENCES.md\` at the repository root.\n`,
+        "utf8",
+      );
+
+      const result = runSkillValidate({}, { workspaceRoot: tmpDir });
+      // The materialized skill was found → no SKILL-01 for it. Under the old
+      // hardcoded <workspaceRoot>/packages/forge path it could never exist.
+      const skill01 = result.violations.filter(
+        (v) => v.rule === "SKILL-01" && v.skill === entry.name,
+      );
+      expect(skill01).toEqual([]);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-2: unresolvable forge root fails with a single SKILL-00", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-skill-noroot-"));
+    try {
+      const result = runSkillValidate({}, { workspaceRoot: tmpDir });
+      expect(result.status).toBe("fail");
+      expect(result.violations).toHaveLength(1);
+      expect(result.violations[0].rule).toBe("SKILL-00");
+      expect(result.violations[0].message).toContain("forge root not resolvable");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-3: pack discovery reads forge.yaml from the workspace root", () => {
+    const { tmpDir } = createConsumerWorkspace();
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, "forge.yaml"),
+        `schema: forge/config@1
+project:
+  name: consumer
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+skillPacks:
+  - prefix: wg
+    dir: packs/wg-skills
+`,
+        "utf8",
+      );
+      const packDir = path.join(tmpDir, "packs", "wg-skills");
+      fs.mkdirSync(path.join(packDir, "wg-broken"), { recursive: true });
+      fs.writeFileSync(path.join(packDir, "forge.plugin.yaml"), "id: wg-skills\nversion: 1.0.0\n");
+      // Deliberately invalid pack skill — discovery proves itself by flagging it.
+      fs.writeFileSync(path.join(packDir, "wg-broken", "SKILL.md"), "# no frontmatter\n");
+
+      const result = runSkillValidate({}, { workspaceRoot: tmpDir });
+      const packViolations = result.violations.filter(
+        (v) => v.pack === "wg" && v.skill === "wg-broken",
+      );
+      expect(packViolations.length).toBeGreaterThan(0);
+      expect(packViolations.some((v) => v.rule === "SKILL-01")).toBe(true);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-4: monorepo invocation resolves the real forge package root — no SKILL-01", async () => {
+    const { resolveForgeRoot } = await import("../config/forge-config.ts");
+    const root = process.cwd();
+    // cwd may be the repo root (packages/forge layout) or packages/forge
+    // itself (scoped test runs) — both must resolve to a root with skills/.
+    const forgeRoot = resolveForgeRoot(root);
+    expect(fs.existsSync(path.join(forgeRoot, "skills"))).toBe(true);
+    const result = runSkillValidate({}, { workspaceRoot: root });
+    const skill01 = result.violations.filter((v) => v.rule === "SKILL-01" && !v.pack);
+    expect(skill01).toEqual([]);
+  });
+});
+
+describe("RFC-1227: SKILL-17 comment-region exemption", () => {
+  // Access the checker through a fabricated skill on disk? checkSkill17 is not
+  // exported — exercise it via a consumer fixture containing a registry skill
+  // whose SKILL.md carries the content under test.
+  async function fixtureRun(bodyLines: string[]): Promise<ReturnType<typeof runSkillValidate>> {
+    const { FORGE_SKILLS } = await import("../registry.ts");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "forge-skill17-"));
+    const forgePkg = path.join(tmpDir, "node_modules", "@warpgogol", "forge");
+    fs.mkdirSync(forgePkg, { recursive: true });
+    fs.writeFileSync(
+      path.join(forgePkg, "package.json"),
+      JSON.stringify({ name: "@warpgogol/forge", version: "9.9.9" }),
+      "utf8",
+    );
+    const entry = FORGE_SKILLS.find((s) => !(s.knowledge && s.knowledge.length > 0))!;
+    const skillPath = path.join(forgePkg, entry.path);
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+    fs.writeFileSync(
+      skillPath,
+      [
+        "---",
+        `name: ${entry.name}`,
+        "description: Fixture skill for SKILL-17 scope tests",
+        `invocation: ${entry.invocation}`,
+        `category: ${entry.category}`,
+        `concerns: ${entry.concerns}`,
+        "dependsOn: []",
+        "languagePolicy: ref(PREFERENCES.md)",
+        "---",
+        ...bodyLines,
+        "Before starting, read `PREFERENCES.md` at the repository root.",
+      ].join("\n"),
+      "utf8",
+    );
+    try {
+      return runSkillValidate({}, { workspaceRoot: tmpDir });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  test("AC-1: RFC ids inside HTML comment regions produce no SKILL-17 violation", async () => {
+    const result = await fixtureRun([
+      "<!--",
+      "<CHANGE_SUMMARY>",
+      "  <item>RFC-1097: sweep — SKILL.md headers + classification fixes</item>",
+      "</CHANGE_SUMMARY>",
+      "-->",
+      "Run `forge doctor` to inspect bindings. <!-- operator note: see RFC-0553 -->",
+    ]);
+    const idViolations = result.violations.filter((v) => v.rule === "SKILL-17");
+    expect(idViolations).toEqual([]);
+  });
+
+  test("AC-2: RFC ids in instruction text still violate SKILL-17", async () => {
+    const result = await fixtureRun([
+      "Stamp the implementation via `rfc.implement.stamp` (RFC-0756).",
+    ]);
+    const idViolations = result.violations.filter((v) => v.rule === "SKILL-17");
+    expect(idViolations.length).toBeGreaterThan(0);
+    expect(idViolations[0].message).toContain("RFC-0756");
+  });
+
+  test("AC-4: the file-level disable marker still suppresses all SKILL-17 violations", async () => {
+    const result = await fixtureRun([
+      "<!-- skill-lint-disable SKILL-17 -->",
+      "Referencing RFC-0996 in body text is suppressed by the marker.",
+    ]);
+    const idViolations = result.violations.filter((v) => v.rule === "SKILL-17");
+    expect(idViolations).toEqual([]);
+  });
+});

package/src/tests/upgrade.test.ts

@@ -5,6 +5,8 @@
 <CHANGE_SUMMARY>
   <item>RFC-0543: initial upgrade handler and VERSION sourcing tests.</item>
   <item>RFC-0552: add test for Forge-vs-pack skill name conflict detection in upgrade.</item>
+  <item>RFC-1224: forge.yaml preservation test — consumer keys, comments, and unknown sections survive upgrade rewrites.</item>
+  <item>RFC-1224: preserve operator forge.yaml content on upgrade, promote adrImplementStamp binding</item>
 </CHANGE_SUMMARY>
 */
 
@@ -21,6 +23,7 @@ import type { WorkspaceIO } from "@warpgogol/werkstatt-shared/kernel/workspace-i
 import { runInit } from "../onboarding/init.ts";
 import {
   loadForgeConfig,
+  resolveBinding,
   FORGE_CLI_BINDING_DEFAULTS,
   resolvePmRunner,
 } from "../config/forge-config.ts";
@@ -206,6 +209,63 @@ test("forge.upgrade never overwrites a non-null operator-set binding", async ()
   expect(addedKeys).toContain("commands.implementStamp");
   expect(addedKeys).toContain("commands.specValidate");
   expect(addedKeys).toContain("commands.sessionSave");
+  expect(addedKeys).toContain("commands.adrImplementStamp");
+});
+
+test("RFC-1224: forge.upgrade preserves consumer-owned keys and comments in forge.yaml", async () => {
+  await setupForgeSource(tempDir, "0.2.0");
+  // Hand-write forge.yaml the way an operator would: a consumer-defined command
+  // binding, a schema-unknown top-level section, and comments.
+  const yaml = `schema: forge/config@1
+# operator comment — must survive upgrade
+project:
+  name: consumer-project
+  stack: []
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  plansDir: docs/plans
+  auditsDir: docs/audits
+  specsDir: docs/specs
+  skillsDir: .agents/skills
+  sessionsDir: docs/sessions
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: pnpm exec forge rfc.validate --id {id} --json  # inline comment
+    customRegistryCmd: custom registry command
+  paths:
+    invariantsFile: null
+    compassDocs: []
+    reviewsDir: null
+    handoffsDir: null
+    sessionsDir: null
+plugins:
+  - name: my-plugin
+forge:
+  syncedVersion: 0.1.0
+`;
+  await writeFile(join(tempDir, "forge.yaml"), yaml, "utf8");
+
+  const result = await runUpgrade({ argv: [], flags: {} }, makeContext(tempDir, false));
+
+  expect(result.data?.status).toBe("pass");
+  const written = await readFile(join(tempDir, "forge.yaml"), "utf8");
+  // Synced version updated, operator content untouched
+  expect(written).toContain("syncedVersion: 0.2.0");
+  expect(written).toContain("customRegistryCmd: custom registry command");
+  expect(written).toContain("plugins:");
+  expect(written).toContain("my-plugin");
+  expect(written).toContain("# operator comment — must survive upgrade");
+  expect(written).toContain("# inline comment");
+  // Newly promoted forge default is added in place
+  expect(written).toContain("adrImplementStamp:");
+
+  const config = loadForgeConfig(tempDir);
+  expect(config.forge?.syncedVersion).toBe("0.2.0");
+  // Consumer-defined keys stay resolvable after passthrough parsing
+  expect(resolveBinding(config, "commands.customRegistryCmd")).toBe("custom registry command");
 });
 
 test("forge.upgrade refuses when forge.yaml is missing", async () => {

package/src/validators/skill-validate.ts

@@ -6,6 +6,8 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1225: forgeRoot resolves via resolveForgeRoot (monorepo or npm-installed package); unresolvable root returns a single SKILL-00; pack discovery loads forge.yaml from workspaceRoot.</item>
+  <item>RFC-1227: SKILL-17 exempts HTML comment regions (file metadata written by the platform's own changelog tooling); pack-skill loop drops SKILL-17 (RFC-0553 scoped it to shipped canonical skills only).</item>
   <item>RFC-0642: added SKILL-18 — forge skill instruction lines must not reference software-specific binding keys (typecheck, scopedBuild, test); use semantic keys (validate, produce, verify) instead.</item>
   <item>RFC-0660: added SKILL-19 (knowledge entry schema validity) and SKILL-20 (entry identifier uniqueness) for structured knowledge files.</item>
   <item>RFC-0661: added SKILL-21 (knowledge layer token budget warnings), refactored warning handling — warnings go to separate `warnings` array, not `violations`.</item>
@@ -67,14 +69,35 @@ const PREFERENCES_PATTERN = /Read `PREFERENCES\.md`/i;
 export function runSkillValidate(_input: unknown, context: unknown): SkillValidateResult {
   const ctx = context as { workspaceRoot?: string };
   const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
-  const forgeRoot = path.join(workspaceRoot, "packages", "forge");
+
+  // RFC-1225: skill sources live under the forge package root — monorepo
+  // packages/forge or the consumer's node_modules/@warpgogol/forge — while
+  // forge.yaml lives under the workspace root. An unresolvable forge root
+  // surfaces as a single SKILL-00, never N cascading SKILL-01 ghosts.
+  let forgeRoot: string;
+  try {
+    forgeRoot = resolveForgeRoot(workspaceRoot);
+  } catch (err) {
+    return {
+      command: "forge.skill.validate",
+      status: "fail",
+      violations: [
+        {
+          skill: "*",
+          rule: "SKILL-00",
+          message: `forge root not resolvable: ${(err as Error).message}`,
+        },
+      ],
+      warnings: [],
+    };
+  }
   const skillsDir = path.join(forgeRoot, "skills");
 
-  // RFC-0539: Load config to discover declared skill packs
+  // RFC-0539: Load config to discover declared skill packs — from the
+  // workspace root, where forge.yaml actually lives (RFC-1225).
   let packSkills: PackSkillEntry[] = [];
   try {
-    const forgeConfigRoot = resolveForgeRoot(workspaceRoot);
-    const config = loadForgeConfig(forgeConfigRoot);
+    const config = loadForgeConfig(workspaceRoot, forgeRoot);
     packSkills = discoverPackSkills(workspaceRoot, config);
   } catch {
     // Config not found or invalid — skip pack skill validation
@@ -493,14 +516,10 @@ export function runSkillValidate(_input: unknown, context: unknown): SkillValida
       });
     }
 
-    // SKILL-17: No internal platform RFC/ADR id references or platform names (RFC-0553)
-    {
-      const skill17Violations = checkSkill17(entry.name, content);
-      for (const v of skill17Violations) {
-        v.pack = entry.pack;
-      }
-      violations.push(...skill17Violations);
-    }
+    // SKILL-17 is intentionally absent here: RFC-0553 scopes the rule to
+    // shipped canonical skills (packages/forge/skills) — pack skills are
+    // project-domain by design (same asymmetry as SKILL-18). The check was
+    // dead code until RFC-1225 enabled pack validation.
   }
 
   // Check: every SKILL.md on disk has a registry entry
@@ -642,12 +661,20 @@ function checkSkill17(skillName: string, content: string): Violation[] {
     return result;
   }
 
-  const lines = content.split(/\r?\n/);
-
-  for (const line of lines) {
-    if (line.includes(SKILL17_DISABLE_MARKER)) {
+  const rawLines = content.split(/\r?\n/);
+  // RFC-1227: HTML comment regions (MODULE_CONTRACT, CHANGE_SUMMARY, inline
+  // notes) are file metadata, not agent instructions — the platform's own
+  // change-summarizer writes RFC ids there by convention. Blank them
+  // line-stably so instruction text keeps full enforcement and reported
+  // line numbers stay correct.
+  const stripped = content.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
+  const lines = stripped.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    if (rawLines[i].includes(SKILL17_DISABLE_MARKER)) {
       continue;
     }
+    const line = lines[i];
 
     for (const pattern of SKILL17_ID_PATTERNS) {
       const re = new RegExp(pattern.source, pattern.flags);