@warpgogol/forge 2.8.0 → 2.8.2

package/src/registry.ts

@@ -0,0 +1,185 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Skill registry — machine-readable array of all forge skills, used by forge.skill.validate and forge.create. Also provides discoverPackSkills helper for project-declared skill packs (RFC-0539).</purpose>
+<non-goals>
+  <item>Do not include third-party skills — only forge-managed skills belong here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial ForgeSkillEntry interface and FORGE_SKILLS registry (17 migrated + 3 meta = 20).</item>
+  <item>Added fo-add-tests skill (11th fo skill) — absorbs tdd + PBT conventions from RFC-0347.</item>
+  <item>Skill consolidation: added fo-architecture, fo-handoff, fo-triage, fo-qa (15 fo skills). Removed handoff, improve-codebase-architecture, to-spec from shared (absorbed into fo-). Shared skills reduced to 4 (grilling, my-preferences, windows-ai-tooling, writing-great-skills).</item>
+  <item>Renamed skill prefix wg- → fo- across all skills, paths, and categories. Added fo-idea-status, fo-idea-i-just-want-to-see-the-plan, fo-idea-i-just-want-to-see-the-result (18 fo skills total).</item>
+  <item>Added fo-doc-audit skill (19th fo skill) — centralized documentation audit replacing inline AGENTS/README update steps in fo-fix and fo-idea-implement.</item>
+  <item>RFC-0395: added fo-spec-ingest skill (20th fo skill) — spec package ingest/authoring with validation, grilling, and acceptance gate.</item>
+  <item>Added fo-session-retro skill (21st fo skill) — session-end insight triage, categorizes discoveries and routes to AGENTS.md / ADR / DNA / forge / memory.</item>
+  <item>RFC-0523: expanded concerns enum from binary (document-only | implementation) to four-level taxonomy (read-only | document-only | content-mutation | code-mutation). All 30 skills reclassified.</item>
+  <item>RFC-0524: added optional knowledge?: string[] field for cumulative knowledge system. Added knowledge arrays to fo-site-scan and grilling.</item>
+  <item>RFC-0538: added fo-compass-annotate skill (22nd fo skill) — full-lifecycle Compass header management replacing removed compass.annotate, compass.clear, compass.markup.migrate, compass.invariant.add kernel commands.</item>
+  <item>RFC-0539: added discoverPackSkills helper and PackSkillEntry interface for project-declared skill packs. Removed mission-complete and fo-site-scan entries (relocated to warpgogol-skills as wg- pack skills).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeConfig } from "./config/forge-config.ts";
+
+/**
+ * Every entry MUST be portable — it runs in any forge-bootstrapped project
+ * using only forge commands, forge bindings, and standard project files.
+ * Ecosystem-bound skills belong in project skill packs (RFC-0539), not here.
+ */
+export interface ForgeSkillEntry {
+  name: string;
+  category: "fo" | "shared" | "meta";
+  invocation: "user" | "model";
+  concerns: "read-only" | "document-only" | "content-mutation" | "code-mutation";
+  dependsOn: string[];
+  path: string;
+  knowledge?: string[];
+  triggers?: string[];
+}
+
+/**
+ * A skill discovered in a project-declared skill pack (RFC-0539).
+ * Unlike ForgeSkillEntry, pack skills are discovered at runtime by scanning
+ * the pack directory rather than being statically registered.
+ */
+export interface PackSkillEntry {
+  name: string;
+  pack: string;
+  dir: string;
+  path: string;
+  knowledge?: string[];
+}
+
+/**
+ * Discover skills in project-declared skill packs by scanning each pack's
+ * directory for `<prefix>-<name>/SKILL.md` entries (RFC-0539).
+ *
+ * This is the single source of truth for pack skill discovery — used by
+ * forge.create, forge.skill.validate, forge.doctor, and forge.skill.list.
+ */
+export function discoverPackSkills(workspaceRoot: string, config: ForgeConfig): PackSkillEntry[] {
+  const result: PackSkillEntry[] = [];
+  if (!config.skillPacks) return result;
+
+  for (const pack of config.skillPacks) {
+    const packDir = path.resolve(workspaceRoot, pack.dir);
+    if (!fs.existsSync(packDir)) continue;
+
+    const entries = fs.readdirSync(packDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (!entry.name.startsWith(`${pack.prefix}-`)) continue;
+
+      const skillMdPath = path.join(packDir, entry.name, "SKILL.md");
+      if (!fs.existsSync(skillMdPath)) continue;
+
+      const relPath = path.relative(packDir, skillMdPath).replace(/\\/g, "/");
+      const skillEntry: PackSkillEntry = {
+        name: entry.name,
+        pack: pack.prefix,
+        dir: pack.dir,
+        path: relPath,
+      };
+
+      // Extract knowledge files from frontmatter if present
+      const content = fs.readFileSync(skillMdPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (fmMatch) {
+        try {
+          const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+          if (Array.isArray(fm["knowledge"])) {
+            skillEntry.knowledge = (fm["knowledge"] as unknown[]).filter(
+              (v): v is string => typeof v === "string",
+            );
+          }
+        } catch {
+          // Frontmatter parse error — SKILL-01 will catch this in validation
+        }
+      }
+
+      result.push(skillEntry);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Auto-discover forge skills by scanning the skills/ directory for SKILL.md
+ * files and parsing their frontmatter. This replaces the hand-maintained
+ * FORGE_SKILLS array — the frontmatter is the single source of truth.
+ *
+ * Skills are organized as skills/{category}/{name}/SKILL.md.
+ */
+function discoverForgeSkills(skillsRoot: string): ForgeSkillEntry[] {
+  const result: ForgeSkillEntry[] = [];
+  if (!fs.existsSync(skillsRoot)) return result;
+
+  for (const categoryDir of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!categoryDir.isDirectory()) continue;
+    const category = categoryDir.name;
+    const catDirPath = path.join(skillsRoot, category);
+
+    for (const skillDir of fs.readdirSync(catDirPath, { withFileTypes: true })) {
+      if (!skillDir.isDirectory()) continue;
+      const skillMdPath = path.join(catDirPath, skillDir.name, "SKILL.md");
+      if (!fs.existsSync(skillMdPath)) continue;
+
+      const content = fs.readFileSync(skillMdPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (!fmMatch) continue;
+
+      let fm: Record<string, unknown>;
+      try {
+        fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+
+      const relPath = path.relative(skillsRoot, skillMdPath).replace(/\\/g, "/");
+      result.push({
+        name: fm["name"] as string,
+        category: fm["category"] as ForgeSkillEntry["category"],
+        invocation: fm["invocation"] as ForgeSkillEntry["invocation"],
+        concerns: fm["concerns"] as ForgeSkillEntry["concerns"],
+        dependsOn: Array.isArray(fm["dependsOn"])
+          ? (fm["dependsOn"] as unknown[]).filter((v): v is string => typeof v === "string")
+          : [],
+        path: `skills/${relPath}`,
+        ...(Array.isArray(fm["knowledge"])
+          ? {
+              knowledge: (fm["knowledge"] as unknown[]).filter(
+                (v): v is string => typeof v === "string",
+              ),
+            }
+          : {}),
+        ...(Array.isArray(fm["triggers"])
+          ? {
+              triggers: (fm["triggers"] as unknown[]).filter(
+                (v): v is string => typeof v === "string",
+              ),
+            }
+          : {}),
+      });
+    }
+  }
+
+  return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function resolveSkillsRoot(): string {
+  const candidates = [
+    path.resolve(import.meta.dirname, "..", "skills"),
+    path.resolve(import.meta.dirname, "..", "..", "skills"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return candidates[0];
+}
+const SKILLS_ROOT = resolveSkillsRoot();
+export const FORGE_SKILLS: ForgeSkillEntry[] = discoverForgeSkills(SKILLS_ROOT);

package/src/skill-schema.ts

@@ -0,0 +1,37 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Define the Zod frontmatter schema used by forge skill validation commands.</purpose>
+<non-goals>
+  <item>Do not validate SKILL.md body content — that is handled by pattern matching in the validator.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial skillFrontmatterSchema with name, description, invocation, category, concerns, dependsOn, languagePolicy.</item>
+  <item>RFC-0393: added optional bindings field (requires/optional arrays of binding keys).</item>
+  <item>RFC-0523: expanded concerns enum from binary to four-level taxonomy (read-only | document-only | content-mutation | code-mutation).</item>
+  <item>RFC-0524: added optional knowledge field (array of file names relative to SKILL.md directory).</item>
+  <item>RFC-0548: added optional triggers field (array of natural-language trigger phrases, max 5 entries, each 5-100 chars) for intent-to-skill routing.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const skillFrontmatterSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1).max(200),
+  invocation: z.enum(["user", "model"]),
+  category: z.enum(["fo", "shared", "meta"]),
+  concerns: z.enum(["read-only", "document-only", "content-mutation", "code-mutation"]),
+  dependsOn: z.array(z.string()).default([]),
+  languagePolicy: z.literal("ref(PREFERENCES.md)"),
+  bindings: z
+    .object({
+      requires: z.array(z.string()).default([]),
+      optional: z.array(z.string()).default([]),
+    })
+    .optional(),
+  knowledge: z.array(z.string()).optional(),
+  triggers: z.array(z.string().min(5).max(100)).max(5).optional(),
+});
+
+export type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;

package/src/tests/acceptance-criteria.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import {
+  evaluateAcceptanceCriteria,
+  extractAcceptanceCriteriaSection,
+} from "../../os/rfc/handlers/validate-rules.ts";
+
+const BODY_WITH_SECTION = `# RFC-0001: Test
+
+## Context
+
+Some context.
+
+## Acceptance criteria
+
+- [x] First criterion (evidence: src/foo.ts:10, unit test)
+- [x] Second criterion (evidence: src/bar.ts:20, integration test)
+- [ ] Third criterion
+
+## Risks
+
+None.
+`;
+
+const BODY_NO_SECTION = `# RFC-0001: Test
+
+## Context
+
+No acceptance criteria section here.
+`;
+
+const BODY_ALL_CHECKED_WITH_EVIDENCE = `# RFC-0001: Test
+
+## Acceptance criteria
+
+- [x] First (evidence: src/a.ts:1, test)
+- [x] Second (evidence: src/b.ts:2, test)
+
+## Risks
+
+None.
+`;
+
+const BODY_CHECKED_WITHOUT_EVIDENCE = `# RFC-0001: Test
+
+## Acceptance criteria
+
+- [x] First criterion without evidence
+- [x] Second (evidence: src/b.ts:2, test)
+
+## Risks
+
+None.
+`;
+
+describe("extractAcceptanceCriteriaSection", () => {
+  it("extracts the section text when present", () => {
+    const section = extractAcceptanceCriteriaSection(BODY_WITH_SECTION);
+    expect(section).toBeDefined();
+    expect(section).toContain("- [x] First criterion");
+    expect(section).toContain("- [ ] Third criterion");
+  });
+
+  it("returns undefined when section is absent", () => {
+    const section = extractAcceptanceCriteriaSection(BODY_NO_SECTION);
+    expect(section).toBeUndefined();
+  });
+});
+
+describe("evaluateAcceptanceCriteria", () => {
+  it("counts checked and unchecked criteria", () => {
+    const result = evaluateAcceptanceCriteria(BODY_WITH_SECTION);
+    expect(result.totalChecked).toBe(2);
+    expect(result.totalUnchecked).toBe(1);
+    expect(result.uncheckedLines).toHaveLength(1);
+    expect(result.uncheckedLines[0]).toBe("- [ ] Third criterion");
+  });
+
+  it("returns zeros when section is absent", () => {
+    const result = evaluateAcceptanceCriteria(BODY_NO_SECTION);
+    expect(result.totalChecked).toBe(0);
+    expect(result.totalUnchecked).toBe(0);
+    expect(result.uncheckedLines).toEqual([]);
+    expect(result.checkedWithoutEvidence).toEqual([]);
+  });
+
+  it("detects checked criteria without evidence", () => {
+    const result = evaluateAcceptanceCriteria(BODY_CHECKED_WITHOUT_EVIDENCE);
+    expect(result.totalChecked).toBe(2);
+    expect(result.checkedWithoutEvidence).toHaveLength(1);
+    expect(result.checkedWithoutEvidence[0]).toContain("First criterion without evidence");
+  });
+
+  it("returns empty checkedWithoutEvidence when all have evidence", () => {
+    const result = evaluateAcceptanceCriteria(BODY_ALL_CHECKED_WITH_EVIDENCE);
+    expect(result.totalChecked).toBe(2);
+    expect(result.totalUnchecked).toBe(0);
+    expect(result.checkedWithoutEvidence).toEqual([]);
+  });
+});

package/src/tests/adr-implement-stamp.test.ts

@@ -0,0 +1,368 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { runAdrImplementStamp } from "../../os/adr/handlers/implement-stamp.ts";
+import type { ForgeCommandInput, ForgeRuntimeContext, ForgeLogger } from "../../src/types.ts";
+
+// ─── Test helpers ─────────────────────────────────────────────────────────────
+
+const noopLogger: ForgeLogger = {
+  section: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  success: () => {},
+};
+
+function makeContext(workspaceRoot: string): ForgeRuntimeContext {
+  return {
+    workspaceRoot,
+    logger: noopLogger,
+    dryRun: false,
+    outputFormat: "json",
+  };
+}
+
+function makeInput(id: string, commit: string, dryRun?: boolean): ForgeCommandInput {
+  return {
+    argv: [],
+    flags: {
+      id,
+      "implementation-commit": commit,
+      ...(dryRun ? { "dry-run": true } : {}),
+    },
+  };
+}
+
+const ADR_BODY = (id: string, status: string): string => `---
+id: ${id}
+title: "Test ADR"
+status: ${status}
+scope: workspace
+decider: human:test
+createdAt: 2026-08-01
+updatedAt: 2026-08-01
+---
+
+# ${id}: Test ADR
+
+## Context
+
+Test context.
+
+## Decision
+
+Test decision.
+
+## Justification
+
+Test justification.
+
+## Consequences
+
+Test consequences.
+
+## Evolution
+
+Test evolution.
+`;
+
+async function makeGitRepo(dir: string): Promise<void> {
+  execFileSync("git", ["init"], { cwd: dir, timeout: 5000 });
+  execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: dir, timeout: 5000 });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: dir, timeout: 5000 });
+}
+
+async function commitAll(dir: string, message: string): Promise<string> {
+  execFileSync("git", ["add", "-A"], { cwd: dir, timeout: 5000 });
+  execFileSync("git", ["commit", "-m", message], { cwd: dir, timeout: 5000 });
+  return execFileSync("git", ["rev-parse", "HEAD"], { cwd: dir, timeout: 5000 }).toString().trim();
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("adr.implement.stamp", () => {
+  let workspaceRoot: string;
+
+  beforeEach(async () => {
+    workspaceRoot = await mkdtemp(join(tmpdir(), "adr-stamp-test-"));
+    await mkdir(join(workspaceRoot, "docs", "adrs"), { recursive: true });
+    await makeGitRepo(workspaceRoot);
+  });
+
+  afterEach(async () => {
+    await rm(workspaceRoot, { recursive: true, force: true });
+  });
+
+  // ── ADR-IMP-01: status checks ───────────────────────────────────────────────
+
+  it("rejects ADR with status superseded", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "superseded"),
+    );
+    const sha = await commitAll(workspaceRoot, "initial");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-01")).toBe(true);
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("rejects ADR with status reviewing", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "reviewing"),
+    );
+    const sha = await commitAll(workspaceRoot, "initial");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-01")).toBe(true);
+  });
+
+  it("rejects ADR with status implemented (already done)", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "implemented"),
+    );
+    const sha = await commitAll(workspaceRoot, "initial");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-01")).toBe(true);
+  });
+
+  it("rejects ADR not found", async () => {
+    await writeFile(join(workspaceRoot, "dummy.txt"), "test");
+    const sha = await commitAll(workspaceRoot, "initial");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-9999", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-01")).toBe(true);
+  });
+
+  // ── ADR-IMP-03: commit validation ───────────────────────────────────────────
+
+  it("rejects commit not reachable from HEAD", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    await commitAll(workspaceRoot, "initial commit ADR-0001");
+
+    // Create a divergent commit
+    await writeFile(join(workspaceRoot, "dummy.txt"), "test");
+    const sha1 = await commitAll(workspaceRoot, "first");
+    execFileSync("git", ["reset", "--hard", "HEAD~1"], { cwd: workspaceRoot, timeout: 5000 });
+    await writeFile(join(workspaceRoot, "other.txt"), "test");
+    await commitAll(workspaceRoot, "second");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha1),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-03")).toBe(true);
+  });
+
+  it("rejects commit that does not reference ADR id", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    await commitAll(workspaceRoot, "add ADR");
+
+    await writeFile(join(workspaceRoot, "code.ts"), "console.log('hello');");
+    const sha = await commitAll(workspaceRoot, "add code without ADR reference");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-03")).toBe(true);
+  });
+
+  it("passes when commit message references ADR id", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    await commitAll(workspaceRoot, "add ADR-0001");
+
+    await writeFile(join(workspaceRoot, "code.ts"), "console.log('hello');");
+    const sha = await commitAll(workspaceRoot, "implement: ADR-0001 add feature");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("pass");
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("passes when commit changed files contain ADR slug", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    await commitAll(workspaceRoot, "add ADR-0001");
+
+    // Commit touches the ADR file itself (slug "adr-0001" is in the path)
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted") + "\n<!-- update -->\n",
+    );
+    const sha = await commitAll(workspaceRoot, "update adr-0001 file");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("pass");
+  });
+
+  // ── ADR-IMP-04: file cleanliness ─────────────────────────────────────────────
+
+  it("rejects when ADR file has uncommitted changes", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    const sha = await commitAll(workspaceRoot, "add ADR-0001");
+
+    // Make uncommitted change to the ADR file
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted") + "\n<!-- dirty -->\n",
+    );
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-04")).toBe(true);
+  });
+
+  // ── ADR-IMP-05: concurrent lock ──────────────────────────────────────────────
+
+  it("rejects when a concurrent lock is held", async () => {
+    await writeFile(
+      join(workspaceRoot, "docs", "adrs", "adr-0001-test.md"),
+      ADR_BODY("ADR-0001", "accepted"),
+    );
+    const sha = await commitAll(workspaceRoot, "implement: ADR-0001 add feature");
+
+    // Pre-create the lock file to simulate a concurrent stamp
+    await mkdir(join(workspaceRoot, ".adr-locks"), { recursive: true });
+    await writeFile(
+      join(workspaceRoot, ".adr-locks", "adr-0001.lock"),
+      JSON.stringify({ pid: 99999, acquiredAt: new Date().toISOString() }),
+    );
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("fail");
+    expect(result.data?.violations.some((v) => v.rule === "ADR-IMP-05")).toBe(true);
+  });
+
+  // ── Dry-run ──────────────────────────────────────────────────────────────────
+
+  it("dry-run checks preconditions without mutating file", async () => {
+    const adrPath = join(workspaceRoot, "docs", "adrs", "adr-0001-test.md");
+    await writeFile(adrPath, ADR_BODY("ADR-0001", "accepted"));
+    await commitAll(workspaceRoot, "add ADR-0001");
+
+    await writeFile(join(workspaceRoot, "code.ts"), "console.log('hello');");
+    const sha = await commitAll(workspaceRoot, "implement: ADR-0001 add feature");
+
+    const originalContent = await readFile(adrPath, "utf-8");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha, true),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("pass");
+    expect(result.data?.data?.adrId).toBe("ADR-0001");
+
+    // File should not be mutated
+    const afterContent = await readFile(adrPath, "utf-8");
+    expect(afterContent).toBe(originalContent);
+  });
+
+  // ── Atomic stamp: accepted → implemented ─────────────────────────────────────
+
+  it("atomically stamps accepted ADR as implemented", async () => {
+    const adrPath = join(workspaceRoot, "docs", "adrs", "adr-0001-test.md");
+    await writeFile(adrPath, ADR_BODY("ADR-0001", "accepted"));
+    await commitAll(workspaceRoot, "add ADR-0001");
+
+    await writeFile(join(workspaceRoot, "code.ts"), "console.log('hello');");
+    const sha = await commitAll(workspaceRoot, "implement: ADR-0001 add feature");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0001", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("pass");
+    expect(result.data?.data?.adrId).toBe("ADR-0001");
+    expect(result.data?.data?.implementationCommit).toBe(sha);
+    expect(result.exitCode).toBe(0);
+
+    // Verify file was mutated
+    const afterContent = await readFile(adrPath, "utf-8");
+    expect(afterContent).toContain("status: implemented");
+    expect(afterContent).toContain("implementedAt:");
+    expect(afterContent).toContain("updatedAt:");
+  });
+
+  // ── Post-hoc ADR: proposed → implemented ─────────────────────────────────────
+
+  it("stamps proposed ADR as implemented (post-hoc)", async () => {
+    const adrPath = join(workspaceRoot, "docs", "adrs", "adr-0002-test.md");
+    await writeFile(adrPath, ADR_BODY("ADR-0002", "proposed"));
+    const sha = await commitAll(workspaceRoot, "add ADR-0002");
+
+    const result = await runAdrImplementStamp(
+      makeInput("ADR-0002", sha),
+      makeContext(workspaceRoot),
+    );
+
+    expect(result.data?.status).toBe("pass");
+    expect(result.data?.data?.adrId).toBe("ADR-0002");
+
+    const afterContent = await readFile(adrPath, "utf-8");
+    expect(afterContent).toContain("status: implemented");
+  });
+});