@warpgogol/forge 2.7.0 → 2.8.1

package/os/werkstatt/handlers/lock.ts

@@ -0,0 +1,168 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Werkstatt lock helpers. Moved from @warpgogol/site-kernel-handoff to
+@warpgogol/forge for full autonomous mode (RFC-0556). Provides acquire, release,
+heartbeat, status, and stale-lock removal.</purpose>
+<non-goals>
+  <item>Do not implement distributed locks — local process-level only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0362: initial lock helpers (acquire, release, heartbeat, status).</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-handoff to @warpgogol/forge for autonomous mode.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { werkstattLockSchema, type WerkstattLock } from "./schema.ts";
+
+const LOCKS_DIR = path.join(".werkstatt", "locks");
+const DEFAULT_TIMEOUT_SECONDS = 900;
+
+function resolveLocksDir(workspaceRoot: string): string {
+  return path.join(workspaceRoot, LOCKS_DIR);
+}
+
+function resolveLockPath(workspaceRoot: string, scope: string): string {
+  const safeScope = scope.replace(/[^a-zA-Z0-9:_-]/g, "_");
+  return path.join(resolveLocksDir(workspaceRoot), `${safeScope}.lock.json`);
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isLockStale(lock: WerkstattLock, now: Date = new Date()): boolean {
+  if (!isProcessAlive(lock.pid)) return true;
+  const heartbeatAge = (now.getTime() - new Date(lock.heartbeatAt).getTime()) / 1000;
+  return heartbeatAge >= lock.timeoutSeconds;
+}
+
+export async function acquireLock(
+  workspaceRoot: string,
+  scope: string,
+  operationId: string,
+  command: string,
+  owner: string,
+  timeoutSeconds: number = DEFAULT_TIMEOUT_SECONDS,
+): Promise<WerkstattLock> {
+  const lockPath = resolveLockPath(workspaceRoot, scope);
+  const locksDir = resolveLocksDir(workspaceRoot);
+
+  if (!existsSync(locksDir)) {
+    await fs.mkdir(locksDir, { recursive: true });
+  }
+
+  if (existsSync(lockPath)) {
+    const raw = await fs.readFile(lockPath, "utf8");
+    try {
+      const existing = werkstattLockSchema.parse(JSON.parse(raw));
+      if (existing.pid === process.pid && !isLockStale(existing)) {
+        const updated = {
+          ...existing,
+          depth: (existing.depth ?? 1) + 1,
+          heartbeatAt: new Date().toISOString(),
+        };
+        werkstattLockSchema.parse(updated);
+        await fs.writeFile(lockPath, JSON.stringify(updated, null, 2) + "\n", "utf8");
+        return updated;
+      }
+      if (!isLockStale(existing)) {
+        throw new Error(
+          `[werkstatt.lock] lock '${scope}' held by operation '${existing.operationId}' (pid: ${existing.pid})`,
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("held by")) throw err;
+    }
+  }
+
+  const now = new Date().toISOString();
+  const lock: WerkstattLock = {
+    schemaVersion: "1.0.0",
+    scope,
+    operationId,
+    command,
+    owner,
+    pid: process.pid,
+    startedAt: now,
+    heartbeatAt: now,
+    timeoutSeconds,
+  };
+
+  werkstattLockSchema.parse(lock);
+  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  return lock;
+}
+
+export async function releaseLock(workspaceRoot: string, scope: string): Promise<void> {
+  const lockPath = resolveLockPath(workspaceRoot, scope);
+  if (!existsSync(lockPath)) return;
+  try {
+    const raw = await fs.readFile(lockPath, "utf8");
+    const lock = werkstattLockSchema.parse(JSON.parse(raw));
+    if (lock.pid === process.pid && (lock.depth ?? 1) > 1) {
+      const decremented = { ...lock, depth: (lock.depth ?? 1) - 1 };
+      werkstattLockSchema.parse(decremented);
+      await fs.writeFile(lockPath, JSON.stringify(decremented, null, 2) + "\n", "utf8");
+      return;
+    }
+    await fs.unlink(lockPath);
+  } catch {
+    // corrupt or missing — try direct delete
+    try {
+      await fs.unlink(lockPath);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+export async function heartbeatLock(workspaceRoot: string, scope: string): Promise<void> {
+  const lockPath = resolveLockPath(workspaceRoot, scope);
+  if (!existsSync(lockPath)) return;
+  const raw = await fs.readFile(lockPath, "utf8");
+  const lock = werkstattLockSchema.parse(JSON.parse(raw));
+  lock.heartbeatAt = new Date().toISOString();
+  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+}
+
+export async function readAllLocks(
+  workspaceRoot: string,
+): Promise<Array<WerkstattLock & { stale: boolean }>> {
+  const locksDir = resolveLocksDir(workspaceRoot);
+  if (!existsSync(locksDir)) return [];
+
+  const files = await fs.readdir(locksDir);
+  const locks: Array<WerkstattLock & { stale: boolean }> = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".lock.json")) continue;
+    const raw = await fs.readFile(path.join(locksDir, file), "utf8");
+    try {
+      const lock = werkstattLockSchema.parse(JSON.parse(raw));
+      locks.push({ ...lock, stale: isLockStale(lock) });
+    } catch {
+      // skip corrupt lock files
+    }
+  }
+
+  return locks;
+}
+
+export async function removeStaleLock(workspaceRoot: string, scope: string): Promise<boolean> {
+  const lockPath = resolveLockPath(workspaceRoot, scope);
+  if (!existsSync(lockPath)) return false;
+  const raw = await fs.readFile(lockPath, "utf8");
+  const lock = werkstattLockSchema.parse(JSON.parse(raw));
+  if (!isLockStale(lock)) return false;
+  await fs.unlink(lockPath);
+  return true;
+}

package/os/werkstatt/handlers/schema.ts

@@ -0,0 +1,47 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Werkstatt Zod schemas inlined from @warpgogol/werkstatt-shared/ontology/operations for
+full autonomous mode (RFC-0556). Provides werkstattLockSchema and
+werkstattOperationRecordSchema without a dependency on @warpgogol/ontology.</purpose>
+<non-goals>
+  <item>Do not perform file IO — pure shape only.</item>
+  <item>Do not define hash-chain Bordbuch format — that is RFC-0276/RFC-0355.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0362: initial Werkstatt schemas (WerkstattLock, WerkstattOperationRecord).</item>
+  <item>RFC-0556: inlined from @warpgogol/werkstatt-shared/ontology/operations into forge for autonomous mode.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const werkstattLockSchema = z.object({
+  schemaVersion: z.literal("1.0.0"),
+  scope: z.string().min(1),
+  operationId: z.string().min(1),
+  command: z.string().min(1),
+  owner: z.string().min(1),
+  pid: z.number().int(),
+  startedAt: z.string().datetime(),
+  heartbeatAt: z.string().datetime(),
+  timeoutSeconds: z.number().positive(),
+  depth: z.number().int().positive().optional(),
+});
+
+export const werkstattOperationRecordSchema = z.object({
+  schemaVersion: z.literal("1.0.0"),
+  operationId: z.string().min(1),
+  command: z.string().min(1),
+  scopes: z.array(z.string().min(1)),
+  state: z.enum(["started", "completed", "failed"]),
+  startedAt: z.string().datetime(),
+  completedAt: z.string().datetime().nullable(),
+  inputHash: z.string().min(1),
+  resultHash: z.string().nullable(),
+  artifacts: z.array(z.string()),
+  error: z.string().nullable(),
+});
+
+export type WerkstattLock = z.infer<typeof werkstattLockSchema>;
+export type WerkstattOperationRecord = z.infer<typeof werkstattOperationRecordSchema>;

package/os/werkstatt/handlers/werkstatt-lock-recover.ts

@@ -0,0 +1,175 @@
+/*
+<MODULE_CONTRACT>
+<purpose>werkstatt.lock.recover command handler. Moved from
+@warpgogol/site-kernel-handoff to @warpgogol/forge for full autonomous mode (RFC-0556).
+Classifies and cleans stale locks and staging artifacts (RFC-0362 §8).</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0362: initial lock.recover command handler.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-handoff to @warpgogol/forge for autonomous mode.</item>
+  <item>Replace fs.unlink/fs.rm with trashPath for artifact cleanup (trash bin for LLM-initiated deletions).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { trashPath } from "../../../src/utils/fs-trash.ts";
+import { readAllLocks, removeStaleLock, acquireLock, releaseLock } from "./lock.ts";
+
+export interface WerkstattLockRecoverData {
+  recovered: Array<{ scope?: string; artifact?: string; action: string }>;
+  failed: Array<{ scope?: string; artifact?: string; error: string }>;
+}
+
+function flagString(input: ForgeCommandInput, key: string): string | undefined {
+  const v = input.flags[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+async function classifyArtifacts(
+  workspaceRoot: string,
+  purge: boolean,
+): Promise<{
+  recovered: Array<{ artifact: string; action: string }>;
+  failed: Array<{ artifact: string; error: string }>;
+}> {
+  const recovered: Array<{ artifact: string; action: string }> = [];
+  const failed: Array<{ artifact: string; error: string }> = [];
+
+  const scanRoots = ["systems", "missions", "releases"];
+  for (const root of scanRoots) {
+    const rootPath = path.join(workspaceRoot, root);
+    if (!existsSync(rootPath)) continue;
+
+    let entries: string[];
+    try {
+      entries = await fs.readdir(rootPath);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(rootPath, entry);
+      const relPath = path.relative(workspaceRoot, entryPath).replace(/\\/g, "/");
+
+      if (entry.endsWith(".tmp")) {
+        if (purge) {
+          try {
+            await trashPath(entryPath);
+            recovered.push({ artifact: relPath, action: "trashed-tmp" });
+          } catch (err) {
+            failed.push({ artifact: relPath, error: (err as Error).message });
+          }
+        } else {
+          recovered.push({ artifact: relPath, action: "classified-tmp (use --purge to remove)" });
+        }
+      } else if (entry.includes(".staging-")) {
+        if (purge) {
+          try {
+            await trashPath(entryPath);
+            recovered.push({ artifact: relPath, action: "trashed-staging" });
+          } catch (err) {
+            failed.push({ artifact: relPath, error: (err as Error).message });
+          }
+        } else {
+          recovered.push({
+            artifact: relPath,
+            action: "classified-staging (use --purge to remove)",
+          });
+        }
+      } else if (entry.includes(".incomplete")) {
+        if (purge) {
+          const failedDir = entryPath.replace(".incomplete", `.failed-${Date.now()}`);
+          try {
+            await fs.rename(entryPath, failedDir);
+            recovered.push({ artifact: relPath, action: "renamed-to-failed" });
+          } catch (err) {
+            failed.push({ artifact: relPath, error: (err as Error).message });
+          }
+        } else {
+          recovered.push({
+            artifact: relPath,
+            action: "classified-incomplete (use --purge to rename)",
+          });
+        }
+      }
+    }
+  }
+
+  return { recovered, failed };
+}
+
+export async function runWerkstattLockRecover(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<WerkstattLockRecoverData>> {
+  const { workspaceRoot, logger } = context;
+  const scopeFilter = flagString(input, "scope");
+  const purge = input.flags["purge"] === true;
+
+  const metaOperationId = `recover-${Date.now()}`;
+  try {
+    await acquireLock(
+      workspaceRoot,
+      "werkstatt-recovery",
+      metaOperationId,
+      "werkstatt.lock.recover",
+      "system",
+    );
+  } catch {
+    throw new Error("[werkstatt.lock.recover] another recovery operation is in progress");
+  }
+
+  try {
+    const locks = await readAllLocks(workspaceRoot);
+    const staleLocks = locks.filter((l) => l.stale && (!scopeFilter || l.scope === scopeFilter));
+
+    const recovered: Array<{ scope?: string; artifact?: string; action: string }> = [];
+    const failed: Array<{ scope?: string; artifact?: string; error: string }> = [];
+
+    for (const lock of staleLocks) {
+      try {
+        await removeStaleLock(workspaceRoot, lock.scope);
+        recovered.push({ scope: lock.scope, action: "removed-stale-lock" });
+        logger.info(`  [removed] lock '${lock.scope}'`);
+      } catch (err) {
+        failed.push({ scope: lock.scope, error: (err as Error).message });
+      }
+    }
+
+    const { recovered: artifactRecovered, failed: artifactFailed } = await classifyArtifacts(
+      workspaceRoot,
+      purge,
+    );
+    for (const r of artifactRecovered) {
+      recovered.push({ artifact: r.artifact, action: r.action });
+    }
+    for (const f of artifactFailed) {
+      failed.push({ artifact: f.artifact, error: f.error });
+    }
+
+    if (recovered.length === 0 && failed.length === 0) {
+      logger.success("[werkstatt.lock.recover] no stale locks or artifacts found");
+    } else {
+      logger.success(
+        `[werkstatt.lock.recover] ${recovered.length} recovered, ${failed.length} failed`,
+      );
+    }
+
+    return {
+      data: { recovered, failed },
+      summary: `[werkstatt.lock.recover] ${recovered.length} artifact${recovered.length === 1 ? "" : "s"} recovered, ${failed.length} failure${failed.length === 1 ? "" : "s"}`,
+    };
+  } finally {
+    await releaseLock(workspaceRoot, "werkstatt-recovery");
+  }
+}

package/os/werkstatt/handlers/werkstatt-lock-status.ts

@@ -0,0 +1,73 @@
+/*
+<MODULE_CONTRACT>
+<purpose>werkstatt.lock.status command handler. Moved from
+@warpgogol/site-kernel-handoff to @warpgogol/forge for full autonomous mode (RFC-0556).
+Reports all Werkstatt locks, their age, owner, and staleness (RFC-0362).</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0362: initial lock.status command handler.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-handoff to @warpgogol/forge for autonomous mode.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { readAllLocks } from "./lock.ts";
+
+export interface WerkstattLockStatusData {
+  locks: Array<{
+    scope: string;
+    operationId: string;
+    command: string;
+    owner: string;
+    pid: number;
+    startedAt: string;
+    heartbeatAt: string;
+    timeoutSeconds: number;
+    stale: boolean;
+  }>;
+  count: number;
+  staleCount: number;
+}
+
+export async function runWerkstattLockStatus(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<WerkstattLockStatusData>> {
+  const { workspaceRoot, logger } = context;
+  const locks = await readAllLocks(workspaceRoot);
+
+  const staleCount = locks.filter((l) => l.stale).length;
+
+  for (const lock of locks) {
+    const status = lock.stale ? "STALE" : "active";
+    logger.info(
+      `  ${lock.scope.padEnd(32)} ${status.padEnd(6)} pid:${lock.pid} op:${lock.operationId}`,
+    );
+  }
+
+  return {
+    data: {
+      locks: locks.map((l) => ({
+        scope: l.scope,
+        operationId: l.operationId,
+        command: l.command,
+        owner: l.owner,
+        pid: l.pid,
+        startedAt: l.startedAt,
+        heartbeatAt: l.heartbeatAt,
+        timeoutSeconds: l.timeoutSeconds,
+        stale: l.stale,
+      })),
+      count: locks.length,
+      staleCount,
+    },
+    summary: `[werkstatt.lock.status] ${locks.length} lock${locks.length === 1 ? "" : "s"}, ${staleCount} stale`,
+  };
+}

package/os/werkstatt/handlers/werkstatt-operation-validate.ts

@@ -0,0 +1,104 @@
+/*
+<MODULE_CONTRACT>
+<purpose>werkstatt.operation.validate command handler. Moved from
+@warpgogol/site-kernel-checks to @warpgogol/forge for full autonomous mode (RFC-0556).
+Scans command source files for direct shared-state writes outside the allowlisted
+helper module (RFC-0362 §6).</purpose>
+<non-goals>
+  <item>Does not load command implementations — reads source files with regex only.</item>
+  <item>Does not scan files outside packages/os/site-kernel-handoff/src/.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0362: initial operation.validate command handler.</item>
+  <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode. Uses node:fs/promises directly instead of context.io.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { basename, join, relative } from "node:path";
+import { readFile } from "node:fs/promises";
+import { collectFiles } from "../../../src/utils/fs.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+const SCAN_DIR = "packages/os/site-kernel-handoff/src";
+const ALLOWLIST_DIR = "packages/os/site-kernel-handoff/src/werkstatt";
+
+const DIRECT_WRITE_PATTERNS: Array<{ regex: RegExp; label: string }> = [
+  { regex: /\bwriteFile\s*\(/g, label: "writeFile" },
+  { regex: /\bappendFile\s*\(/g, label: "appendFile" },
+  { regex: /\brename\s*\(/g, label: "rename" },
+  { regex: /\bcp\s*\(/g, label: "cp" },
+];
+
+export interface WerkstattOperationValidateData {
+  scannedFiles: number;
+  violations: Array<{ file: string; line: number; pattern: string }>;
+}
+
+export async function runWerkstattOperationValidate(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<WerkstattOperationValidateData>> {
+  const { workspaceRoot, logger } = context;
+  const scanPath = join(workspaceRoot, SCAN_DIR);
+  const allowlistPath = join(workspaceRoot, ALLOWLIST_DIR);
+
+  const files = await collectFiles(scanPath, {
+    ignore: (name) =>
+      name.startsWith(".") || name === "node_modules" || name === "dist" || name === "tests",
+  });
+
+  const violations: Array<{ file: string; line: number; pattern: string }> = [];
+
+  const PRE_EXISTING_ALLOWLIST = new Set(["handoff-pack.ts", "materialize.ts", "bundle-io.ts"]);
+
+  for (const filePath of files) {
+    if (filePath.startsWith(allowlistPath) || filePath.includes("werkstatt")) continue;
+
+    const fileName = basename(filePath);
+    if (fileName.endsWith(".test.ts") || fileName.endsWith(".spec.ts")) continue;
+    if (PRE_EXISTING_ALLOWLIST.has(fileName)) continue;
+
+    const relPath = relative(workspaceRoot, filePath).replace(/\\/g, "/");
+
+    let content: string;
+    try {
+      content = await readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
+
+      for (const { regex, label } of DIRECT_WRITE_PATTERNS) {
+        const testRegex = new RegExp(regex.source, regex.flags);
+        if (testRegex.test(line)) {
+          violations.push({ file: relPath, line: i + 1, pattern: label });
+          logger.error(
+            `${relPath}:${i + 1}: direct ${label} — use the shared atomic-write helper in packages/os/site-kernel-handoff/src/werkstatt/`,
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    data: {
+      scannedFiles: files.length,
+      violations,
+    },
+    exitCode: violations.length > 0 ? 1 : 0,
+    summary:
+      violations.length > 0
+        ? undefined
+        : `[werkstatt.operation.validate] ${files.length} files scanned, 0 violations`,
+  };
+}

package/os/werkstatt/index.ts

@@ -0,0 +1,39 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Expose forge Werkstatt kernel commands through a stable package subpath.</purpose>
+<non-goals>
+  <item>Do not implement werkstatt handler logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial werkstatt module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeWerkstattModule } from "./werkstatt.module.ts";
+export {
+  werkstattLockSchema,
+  werkstattOperationRecordSchema,
+  type WerkstattLock,
+  type WerkstattOperationRecord,
+} from "./handlers/schema.ts";
+export {
+  acquireLock,
+  releaseLock,
+  heartbeatLock,
+  readAllLocks,
+  isLockStale,
+  removeStaleLock,
+} from "./handlers/lock.ts";
+export {
+  runWerkstattLockStatus,
+  type WerkstattLockStatusData,
+} from "./handlers/werkstatt-lock-status.ts";
+export {
+  runWerkstattLockRecover,
+  type WerkstattLockRecoverData,
+} from "./handlers/werkstatt-lock-recover.ts";
+export {
+  runWerkstattOperationValidate,
+  type WerkstattOperationValidateData,
+} from "./handlers/werkstatt-operation-validate.ts";

package/os/werkstatt/werkstatt.module.ts

@@ -0,0 +1,62 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register forge Werkstatt lock and operation validation commands with the kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement werkstatt handler logic — delegate to handlers/ inlined by RFC-0556.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial forgeWerkstattModule registering 3 werkstatt commands.</item>
+  <item>RFC-0556: removed dynamic imports of @warpgogol/site-kernel-handoff and @warpgogol/site-kernel-checks, all handlers now inlined in forge/os/werkstatt/handlers/.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+import { runWerkstattLockStatus } from "./handlers/werkstatt-lock-status.ts";
+import { runWerkstattLockRecover } from "./handlers/werkstatt-lock-recover.ts";
+import { runWerkstattOperationValidate } from "./handlers/werkstatt-operation-validate.ts";
+
+export const forgeWerkstattModule: ForgeModule = {
+  name: "forge-werkstatt",
+  version: "0.1.0",
+  async register(registry) {
+    registry.registerCommand({
+      name: "werkstatt.lock.status",
+      description: "Report all Werkstatt locks, their age, owner, and staleness (RFC-0362).",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {},
+      reads: [".werkstatt/locks/**"],
+      execute: runWerkstattLockStatus,
+    });
+    registry.registerCommand({
+      name: "werkstatt.lock.recover",
+      description:
+        "Classify and clean stale locks and staging artifacts (RFC-0362). Flags: --scope, --purge.",
+      scope: "workspace",
+      supportsAllSites: false,
+      mutatesState: true,
+      flags: {
+        scope: { kind: "string", description: "Recover only a single lock scope." },
+        purge: {
+          kind: "boolean",
+          description: "Remove stale artifacts instead of classifying them.",
+        },
+      },
+      writes: [".werkstatt/locks/**", "systems/**", "missions/**", "releases/**"],
+      reads: [".werkstatt/locks/**"],
+      cacheable: false,
+      execute: runWerkstattLockRecover,
+    });
+    registry.registerCommand({
+      name: "werkstatt.operation.validate",
+      description:
+        "Validate that mutating Werkstatt commands use shared lock/idempotency/atomic-write helpers (RFC-0362).",
+      scope: "workspace",
+      supportsAllSites: false,
+      flags: {},
+      reads: ["packages/os/site-kernel-handoff/src/**/*.ts"],
+      execute: runWerkstattOperationValidate,
+    });
+  },
+};