@warpgogol/forge 5.3.3 → 6.0.0

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/fixtures/agents-generate-business-before.txt

@@ -110,29 +110,29 @@ When the operator expresses an intent in natural language, the agent routes to t
 | "manage Compass headers", "annotate source files with Compass", "audit Compass module contracts"                                                          | `fo-compass-annotate`                   |
 | "design summit", "multi-persona review", "party mode"                                                                                                     | `fo-design-summit`                      |
 | "audit documentation sync", "update docs after code changes", "check AGENTS.md and README are in sync"                                                    | `fo-doc-audit`                          |
-| "explore this idea", "let me think about this", "what are the options for", "what if we"                                                                  | `fo-explore`                            |
+| "нам надо закрыть открытые вопросы", "explore this idea", "let me think about this", "what are the options for", "what if we"                             | `fo-explore`                            |
 | "extract DNA invariant", "discover architectural invariants", "formalize implicit architectural rules"                                                    | `fo-extract-dna`                        |
-| "fix issues from review", "apply review findings and fix", "iterative fix workflow for code"                                                              | `fo-fix`                                |
+| "исправим", "примени findings", "fix all", "fix issues from review", "apply review findings and fix"                                                      | `fo-fix`                                |
 | "create a handoff document", "compact conversation for next agent", "prepare handoff for another agent"                                                   | `fo-handoff`                            |
 | "harvest portable patterns from code", "extract reusable code pattern to forge", "port this pattern to forge"                                             | `fo-harvest`                            |
 | "I have an idea for a change", "analyze this idea and route it", "decompose this feature idea", "does this need an RFC", "should I write an ADR for this" | `fo-idea`                               |
 | "audit this RFC", "check RFC for ecosystem fit", "review RFC against DNA and forward-only rules"                                                          | `fo-idea-audit`                         |
 | "record this architectural decision", "create an ADR", "document a local technical decision"                                                              | `fo-idea-create-adr`                    |
-| "draft an RFC", "create a full RFC", "scaffold an RFC from template"                                                                                      | `fo-idea-create-rfc`                    |
+| "подготовим RFC", "draft an RFC", "create a full RFC", "scaffold an RFC from template"                                                                    | `fo-idea-create-rfc`                    |
 | "enhance this RFC", "fix audit findings in RFC", "improve RFC based on audit"                                                                             | `fo-idea-enhance`                       |
 | "I just want to see the plan", "plan this feature without implementing", "run idea to plan pipeline"                                                      | `fo-idea-i-just-want-to-see-the-plan`   |
-| "I just want to see the result", "run the full pipeline automatically", "implement this end-to-end without pauses"                                        | `fo-idea-i-just-want-to-see-the-result` |
+| "по полному пайплайну", "на результат", "реализуй RFC", "I just want to see the result", "implement this end-to-end without pauses"                       | `fo-idea-i-just-want-to-see-the-result` |
 | "implement this RFC", "execute the implementation plan", "realize this RFC end-to-end"                                                                    | `fo-idea-implement`                     |
 | "plan the implementation for this RFC", "create implementation plan", "map affected artifacts and draft steps"                                            | `fo-idea-plan`                          |
 | "show RFC and ADR status", "what is the status of this RFC", "list RFCs by status"                                                                        | `fo-idea-status`                        |
 | "distill knowledge", "compact skill knowledge", "knowledge lifecycle", "promote fix patterns"                                                             | `fo-knowledge-distill`                  |
 | "sync memory from codex", "import external agent knowledge", "recall sessions from other tools", "sync memory from claude code"                           | `fo-memory-sync`                        |
 | "I found a bug", "file a GitHub issue for this bug", "report a bug conversationally", "interactive QA session"                                            | `fo-qa`                                 |
-| "review this code diff", "check code against Forge standards", "fitness check on code changes"                                                            | `fo-review`                             |
-| "session retrospective", "triage session discoveries", "Завершаем эту сессию", "End session", "/session-end"                                              | `fo-session-retro`                      |
+| "проверим всё ли сделали правильно", "проверь изменения", "review this session", "review this code diff", "check code against Forge standards"            | `fo-review`                             |
+| "завершаем", "протокол завершения", "Завершаем эту сессию", "session retrospective", "End session"                                                        | `fo-session-retro`                      |
 | "save this session", "enhance session transcript with annotations", "save session with quality checks"                                                    | `fo-session-save`                       |
 | "ingest external specification", "vendor spec package into docs", "author spec skeleton"                                                                  | `fo-spec-ingest`                        |
-| "commit after request", "auto-commit changes", "step commit"                                                                                              | `fo-step-commit`                        |
+| "закоммитим", "commit after request", "auto-commit changes", "step commit"                                                                                | `fo-step-commit`                        |
 | "triage this issue", "categorize incoming bug report", "triage external pull request", "process feature request"                                          | `fo-triage`                             |
 
 The agent uses judgment to calibrate routing — minor edits (typo fixes, small CSS changes) do not require skill invocation, while significant changes (new features, architectural decisions) do.

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/implement-stamp.test.ts

@@ -429,6 +429,44 @@ describe("rfc.implement.stamp", () => {
     expect(result.data?.violations).toEqual([]);
   });
 
+  it("auto-selects the sole implement/feat-prefixed commit among multiple candidates", async () => {
+    const rfcFile = join(workspaceRoot, "docs", "rfcs", "rfc-0001-test-rfc.md");
+    await writeFile(rfcFile, RFC_BODY("RFC-0001", "accepted", true));
+    await commitAll(workspaceRoot, "docs: audit RFC-0001");
+    await writeFile(join(workspaceRoot, "src.txt"), "impl");
+    const implCommit = await commitAll(workspaceRoot, "implement: RFC-0001 — the change");
+    await writeFile(join(workspaceRoot, "src.txt"), "evidence");
+    await commitAll(workspaceRoot, "docs: RFC-0001 evidence sweep");
+
+    const result = await runRfcImplementStamp(
+      makeInputAutoDetect("RFC-0001"),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.data?.status).toBe("pass");
+    expect(implCommit.startsWith(result.data?.data?.implementationCommit ?? "")).toBe(true);
+  });
+
+  it("still blocks with annotated candidates when several implement-prefixed commits exist", async () => {
+    const rfcFile = join(workspaceRoot, "docs", "rfcs", "rfc-0001-test-rfc.md");
+    await writeFile(rfcFile, RFC_BODY("RFC-0001", "accepted", true));
+    await commitAll(workspaceRoot, "implement: RFC-0001 step 1");
+    await writeFile(join(workspaceRoot, "src.txt"), "step 2");
+    await commitAll(workspaceRoot, "implement: RFC-0001 step 2");
+
+    const result = await runRfcImplementStamp(
+      makeInputAutoDetect("RFC-0001"),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.exitCode).toBe(1);
+    const imp03 = result.data?.violations.find((v) => v.rule === "RFC-IMP-03");
+    expect(imp03?.message).toContain("Multiple commits reference RFC-0001");
+    expect(imp03?.message).toContain("[implementation-shaped]");
+    expect(imp03?.message).toContain("Likely:");
+  });
+
   // ── RFC-0795: RFC-IMP-07 dependsOn dependency gate tests ──────────────────
 
   it("blocks stamping when a dependsOn RFC is not implemented (RFC-IMP-07)", async () => {

package/src/tests/session-handlers.test.ts

@@ -99,6 +99,39 @@ describe("session.save", () => {
     expect(data2.skipped[0]).toHaveProperty("reason", "already converted");
   });
 
+  test("ignores non-.atif files — claim intermediates and writer temp files are skipped", async () => {
+    const rawDir = join(dir, "docs/sessions/.raw");
+    await writeFile(join(rawDir, "orphan.atif.claim-999"), SAMPLE_ATIF, "utf-8");
+    await writeFile(join(rawDir, "half-written.atif.tmp"), SAMPLE_ATIF, "utf-8");
+
+    const result = await runSessionSave(makeInput(), makeContext(dir));
+    const data = result.data as SessionSaveResult & { skipped: Array<{ rawFile: string }> };
+
+    // Neither junk file was converted, claimed, or deleted.
+    const touched = data.skipped.map((s) => s.rawFile);
+    expect(touched).not.toContain("orphan.atif.claim-999");
+    expect(touched).not.toContain("half-written.atif.tmp");
+    const remaining = await readdir(rawDir);
+    expect(remaining).toContain("orphan.atif.claim-999");
+    expect(remaining).toContain("half-written.atif.tmp");
+  });
+
+  test("--keep-raw restores the original filename after the atomic claim", async () => {
+    const rawDir = join(dir, "docs/sessions/.raw");
+    const uniqueAtif = `2026-07-28T10:00:00+02:00
+User: keep-raw claim restore test.
+Assistant: Done.
+Commands: session.save`;
+    await writeFile(join(rawDir, "keepraw-claim.atif"), uniqueAtif, "utf-8");
+
+    const result = await runSessionSave(makeInput({ "keep-raw": true }), makeContext(dir));
+    expect(result.data.id).not.toBe("");
+
+    const remaining = await readdir(rawDir);
+    expect(remaining).toContain("keepraw-claim.atif");
+    expect(remaining.filter((n) => n.startsWith("keepraw-claim.atif.claim-"))).toHaveLength(0);
+  });
+
   test("deletes raw file on skip when --keep-raw is not set (idempotency cleanup)", async () => {
     const uniqueAtif = `2026-07-27T09:15:00+02:00
 User: Fix the session.save idempotency bug in save.ts.

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([]);
+  });
+});