@warpgogol/forge 5.2.4 → 5.3.1

package/os/spec/spec-materialize.ts

@@ -11,8 +11,8 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../src/utils/io.ts";
+import { existsSync } from "../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { toKebabCase } from "../../src/utils/string-utils.ts";
@@ -63,7 +63,7 @@ interface SpecMaterializeResult {
 
 async function readYaml<T>(filePath: string): Promise<T | null> {
   try {
-    const content = await fs.readFile(filePath, "utf8");
+    const content = await fs.readFile(filePath);
     return parseYaml(content) as T;
   } catch {
     return null;
@@ -163,11 +163,11 @@ export async function runSpecMaterialize(
   const amendmentsDir = path.join(specDir, "amendments");
   const amendments: SpecAmendment[] = [];
   if (existsSync(amendmentsDir)) {
-    const amdEntries = await fs.readdir(amendmentsDir);
+    const amdEntries = (await fs.readdir(amendmentsDir)).map((e) => e.name);
     for (const entry of amdEntries) {
       if (!entry.endsWith(".md")) continue;
       try {
-        const content = await fs.readFile(path.join(amendmentsDir, entry), "utf8");
+        const content = await fs.readFile(path.join(amendmentsDir, entry));
         const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
         if (!fmMatch) continue;
         const raw = parseYaml(fmMatch[1]) as unknown;
@@ -197,7 +197,7 @@ export async function runSpecMaterialize(
   const rfcStatuses = new Map<string, string>();
   for (const file of rfcFiles) {
     try {
-      const content = await fs.readFile(path.join(rfcDir, file), "utf8");
+      const content = await fs.readFile(path.join(rfcDir, file));
       const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
       if (!fmMatch) continue;
       const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
@@ -283,7 +283,7 @@ export async function runSpecMaterialize(
   const templatePath = resolveRfcTemplate(workspaceRoot);
   let templateContent: string;
   try {
-    templateContent = await fs.readFile(templatePath, "utf-8");
+    templateContent = await fs.readFile(templatePath);
   } catch {
     return {
       data: {
@@ -335,7 +335,7 @@ export async function runSpecMaterialize(
     content = content.replace(/^---\n\n# /m, `---\n${designSection}\n# `);
 
     const targetPath = path.join(rfcDir, fileName);
-    await fs.writeFile(targetPath, content, "utf-8");
+    await fs.writeFile(targetPath, content);
     maxId = nextNum;
 
     created.push({
@@ -355,7 +355,7 @@ export async function runSpecMaterialize(
       }),
     };
     const yamlContent = stringifyYaml(updatedSpec);
-    await fs.writeFile(forgeSpecPath, yamlContent, "utf-8");
+    await fs.writeFile(forgeSpecPath, yamlContent);
   }
 
   // Report skipped front nodes (beyond the materialized batch)

package/os/spec/spec-status.ts

@@ -10,8 +10,8 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../src/utils/io.ts";
+import { existsSync } from "../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { loadForgeConfig } from "../../src/config/forge-config.ts";
@@ -70,7 +70,7 @@ interface SpecStatusResult {
 
 async function readYaml<T>(filePath: string): Promise<T | null> {
   try {
-    const content = await fs.readFile(filePath, "utf8");
+    const content = await fs.readFile(filePath);
     return parseYaml(content) as T;
   } catch {
     return null;
@@ -79,8 +79,8 @@ async function readYaml<T>(filePath: string): Promise<T | null> {
 
 async function listSpecDirs(specsDir: string): Promise<string[]> {
   if (!existsSync(specsDir)) return [];
-  const entries = await fs.readdir(specsDir, { withFileTypes: true });
-  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  const entries = await fs.readdir(specsDir);
+  return entries.filter((e) => e.isDirectory).map((e) => e.name);
 }
 
 async function loadRfcStatuses(
@@ -88,11 +88,11 @@ async function loadRfcStatuses(
 ): Promise<Map<string, string>> {
   const statuses = new Map<string, string>();
   if (!existsSync(rfcDir)) return statuses;
-  const files = await fs.readdir(rfcDir);
+  const files = (await fs.readdir(rfcDir)).map((e) => e.name);
   for (const file of files) {
     if (!file.endsWith(".md") || file.startsWith("rfc-0000")) continue;
     try {
-      const content = await fs.readFile(path.join(rfcDir, file), "utf8");
+      const content = await fs.readFile(path.join(rfcDir, file));
       const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
       if (!fmMatch) continue;
       const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
@@ -110,13 +110,13 @@ async function loadAmendments(specDir: string): Promise<SpecAmendment[]> {
   const amendmentsDir = path.join(specDir, "amendments");
   if (!existsSync(amendmentsDir)) return [];
 
-  const entries = await fs.readdir(amendmentsDir);
+  const entries = (await fs.readdir(amendmentsDir)).map((e) => e.name);
   const amendments: SpecAmendment[] = [];
 
   for (const entry of entries) {
     if (!entry.endsWith(".md")) continue;
     try {
-      const content = await fs.readFile(path.join(amendmentsDir, entry), "utf8");
+      const content = await fs.readFile(path.join(amendmentsDir, entry));
       const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
       if (!fmMatch) continue;
       const raw = parseYaml(fmMatch[1]) as unknown;

package/os/spec/spec-validate.ts

@@ -13,8 +13,8 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../src/utils/io.ts";
+import { existsSync } from "../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { byteHash } from "../../src/utils/hash.ts";
@@ -43,7 +43,7 @@ import {
 
 async function readYaml<T>(filePath: string): Promise<T | null> {
   try {
-    const content = await fs.readFile(filePath, "utf8");
+    const content = await fs.readFile(filePath);
     return parseYaml(content) as T;
   } catch {
     return null;
@@ -52,8 +52,8 @@ async function readYaml<T>(filePath: string): Promise<T | null> {
 
 async function listSpecDirs(specsDir: string): Promise<string[]> {
   if (!existsSync(specsDir)) return [];
-  const entries = await fs.readdir(specsDir, { withFileTypes: true });
-  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  const entries = await fs.readdir(specsDir);
+  return entries.filter((e) => e.isDirectory).map((e) => e.name);
 }
 
 async function listSnapshotFiles(
@@ -288,13 +288,13 @@ async function loadAmendments(specDir: string): Promise<SpecAmendment[]> {
   const amendmentsDir = path.join(specDir, "amendments");
   if (!existsSync(amendmentsDir)) return [];
 
-  const entries = await fs.readdir(amendmentsDir);
+  const entries = (await fs.readdir(amendmentsDir)).map((e) => e.name);
   const amendments: SpecAmendment[] = [];
 
   for (const entry of entries) {
     if (!entry.endsWith(".md")) continue;
     try {
-      const content = await fs.readFile(path.join(amendmentsDir, entry), "utf8");
+      const content = await fs.readFile(path.join(amendmentsDir, entry));
       const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
       if (!fmMatch) continue;
       const raw = parseYaml(fmMatch[1]) as unknown;

package/os/spec/spec.module.ts

@@ -9,6 +9,7 @@
   <item>RFC-0394: initial forgeSpecModule registering spec.validate.</item>
   <item>RFC-0396: added spec.status and spec.materialize commands.</item>
   <item>RFC-0711: added spec.live.merge, spec.live.list, spec.live.show, spec.live.validate commands.</item>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
 </CHANGE_SUMMARY>
 */
 
@@ -30,6 +31,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
   commands: [
     {
       name: "spec.validate",
+      mutatesState: false,
       contract: "spec",
       rules: [],
       description:
@@ -49,6 +51,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.status",
+      mutatesState: false,
       description:
         "Show roadmap progress for vendored specs. " +
         "Without --spec, summarizes all specs; with it, full per-node table + computed front.",
@@ -70,6 +73,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
       scope: "workspace",
       mutatesState: true,
       writes: ["docs/rfcs/rfc-*.md", "docs/specs/*/forge-spec.yaml"],
+      generates: [],
       reads: ["docs/specs/**/*", "docs/rfcs/**/*.md"],
       flags: {
         spec: { kind: "string", required: true, description: "Spec id to materialize from." },
@@ -90,6 +94,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
       scope: "workspace",
       mutatesState: true,
       writes: ["docs/specs/live/*.md"],
+      generates: [],
       reads: ["docs/rfcs/**/*.md", "docs/specs/live/*.md"],
       flags: {
         id: { kind: "string", required: true, description: "RFC id to merge (e.g. RFC-0711)." },
@@ -99,6 +104,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.live.list",
+      mutatesState: false,
       description:
         "List all living feature specs in docs/specs/live/. " +
         "Returns domain, title, lastMergedRfc, updatedAt, and historyCount for each spec.",
@@ -109,6 +115,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.live.show",
+      mutatesState: false,
       description:
         "Show a single living feature spec by domain. " +
         "Requires --domain=<name>. Returns full frontmatter and body content.",
@@ -121,6 +128,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.live.validate",
+      mutatesState: false,
       contract: "spec",
       rules: [],
       description:

package/os/werkstatt/handlers/lock.ts

@@ -13,8 +13,8 @@ heartbeat, status, and stale-lock removal.</purpose>
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { existsSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import { werkstattLockSchema, type WerkstattLock } from "./schema.ts";
 
@@ -57,11 +57,11 @@ export async function acquireLock(
   const locksDir = resolveLocksDir(workspaceRoot);
 
   if (!existsSync(locksDir)) {
-    await fs.mkdir(locksDir, { recursive: true });
+    await fs.mkdir(locksDir);
   }
 
   if (existsSync(lockPath)) {
-    const raw = await fs.readFile(lockPath, "utf8");
+    const raw = await fs.readFile(lockPath);
     try {
       const existing = werkstattLockSchema.parse(JSON.parse(raw));
       if (existing.pid === process.pid && !isLockStale(existing)) {
@@ -71,7 +71,7 @@ export async function acquireLock(
           heartbeatAt: new Date().toISOString(),
         };
         werkstattLockSchema.parse(updated);
-        await fs.writeFile(lockPath, JSON.stringify(updated, null, 2) + "\n", "utf8");
+        await fs.writeFile(lockPath, JSON.stringify(updated, null, 2) + "\n");
         return updated;
       }
       if (!isLockStale(existing)) {
@@ -98,7 +98,7 @@ export async function acquireLock(
   };
 
   werkstattLockSchema.parse(lock);
-  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n");
   return lock;
 }
 
@@ -106,19 +106,19 @@ export async function releaseLock(workspaceRoot: string, scope: string): Promise
   const lockPath = resolveLockPath(workspaceRoot, scope);
   if (!existsSync(lockPath)) return;
   try {
-    const raw = await fs.readFile(lockPath, "utf8");
+    const raw = await fs.readFile(lockPath);
     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");
+      await fs.writeFile(lockPath, JSON.stringify(decremented, null, 2) + "\n");
       return;
     }
-    await fs.unlink(lockPath);
+    await fs.rm(lockPath);
   } catch {
     // corrupt or missing — try direct delete
     try {
-      await fs.unlink(lockPath);
+      await fs.rm(lockPath);
     } catch {
       /* already gone */
     }
@@ -128,10 +128,10 @@ export async function releaseLock(workspaceRoot: string, scope: string): Promise
 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 raw = await fs.readFile(lockPath);
   const lock = werkstattLockSchema.parse(JSON.parse(raw));
   lock.heartbeatAt = new Date().toISOString();
-  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n");
 }
 
 export async function readAllLocks(
@@ -140,12 +140,12 @@ export async function readAllLocks(
   const locksDir = resolveLocksDir(workspaceRoot);
   if (!existsSync(locksDir)) return [];
 
-  const files = await fs.readdir(locksDir);
+  const files = (await fs.readdir(locksDir)).map((e) => e.name);
   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");
+    const raw = await fs.readFile(path.join(locksDir, file));
     try {
       const lock = werkstattLockSchema.parse(JSON.parse(raw));
       locks.push({ ...lock, stale: isLockStale(lock) });
@@ -160,9 +160,9 @@ export async function readAllLocks(
 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 raw = await fs.readFile(lockPath);
   const lock = werkstattLockSchema.parse(JSON.parse(raw));
   if (!isLockStale(lock)) return false;
-  await fs.unlink(lockPath);
+  await fs.rm(lockPath);
   return true;
 }

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

@@ -19,8 +19,8 @@ Sweep batch 4: 73 Compass headers on headerless engine files (certification, com
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { ambientIo as fs } from "../../../src/utils/io.ts";
+import { existsSync } from "../../../src/utils/sync-fs.ts";
 import path from "node:path";
 import type {
   ForgeCommandInput,
@@ -57,7 +57,7 @@ async function classifyArtifacts(
 
     let entries: string[];
     try {
-      entries = await fs.readdir(rootPath);
+      entries = (await fs.readdir(rootPath)).map((e) => e.name);
     } catch {
       continue;
     }

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

@@ -16,7 +16,8 @@ helper module (RFC-0362 §6).</purpose>
 */
 
 import { basename, join, relative } from "node:path";
-import { readFile } from "node:fs/promises";
+import { resolveIo } from "../../../src/utils/io.ts";
+
 import { collectFiles } from "../../../src/utils/fs.ts";
 import type {
   ForgeCommandInput,
@@ -43,6 +44,7 @@ export async function runWerkstattOperationValidate(
   _input: ForgeCommandInput,
   context: ForgeRuntimeContext,
 ): Promise<ForgeCommandResult<WerkstattOperationValidateData>> {
+  const io = resolveIo(context.io);
   const { workspaceRoot, logger } = context;
   const scanPath = join(workspaceRoot, SCAN_DIR);
   const allowlistPath = join(workspaceRoot, ALLOWLIST_DIR);
@@ -67,7 +69,7 @@ export async function runWerkstattOperationValidate(
 
     let content: string;
     try {
-      content = await readFile(filePath, "utf8");
+      content = await io.readFile(filePath);
     } catch {
       continue;
     }

package/os/werkstatt/handlers/workspace-deps.ts

@@ -9,7 +9,6 @@
 <CHANGE_SUMMARY>
   <item>RFC-0682: extract dynamic-import helper so forge publishes without workspace:* deps.</item>
   <item>RFC-0940: moved from os/core/handlers/ to os/werkstatt/handlers/ — this module imports @warpgogol/werkstatt-engine and belongs in the adapter directory.</item>
-  <item>2026-09-22: fingerprint import switched from @warpgogol/werkstatt-engine/fingerprint to @warpgogol/werkstatt-shared/fingerprint (canonical home since RFC-1104) — breaks the forge↔engine package cycle reported by turbo.</item>
 </CHANGE_SUMMARY>
 */
 

package/os/werkstatt/werkstatt.module.ts

@@ -8,6 +8,7 @@
 <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>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
 </CHANGE_SUMMARY>
 */
 
@@ -20,10 +21,11 @@ export const forgeWerkstattModule: ForgeModule = {
   name: "forge-werkstatt",
   version: "0.1.0",
   runtime: "werkstatt-adapter",
-    declarations: [],
+  declarations: [],
   commands: [
     {
       name: "werkstatt.lock.status",
+      mutatesState: false,
       description: "Report all Werkstatt locks, their age, owner, and staleness (RFC-0362).",
       scope: "workspace",
       supportsAllSites: false,
@@ -46,12 +48,14 @@ export const forgeWerkstattModule: ForgeModule = {
         },
       },
       writes: [".werkstatt/locks/**", "systems/**", "missions/**", "releases/**"],
+      generates: [],
       reads: [".werkstatt/locks/**"],
       cacheable: false,
       execute: runWerkstattLockRecover,
     },
     {
       name: "werkstatt.operation.validate",
+      mutatesState: false,
       contract: "werkstatt",
       rules: [],
       description:
@@ -61,8 +65,7 @@ export const forgeWerkstattModule: ForgeModule = {
       flags: {},
       reads: ["packages/os/site-kernel-handoff/src/**/*.ts"],
       execute: runWerkstattOperationValidate,
-    }
+    },
   ],
-  pipelines: [
-
-  ]};
+  pipelines: [],
+};

package/os/workflow/handlers.ts

@@ -12,7 +12,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs/promises";
+import { ambientIo as fs } from "../../src/utils/io.ts";
 import path from "node:path";
 import YAML from "yaml";
 import type {
@@ -82,7 +82,9 @@ const PENDING_ACCEPTED_RFC_COMMANDS = new Set([
 
 async function pathExists(target: string): Promise<boolean> {
   try {
-    await fs.access(target);
+    await fs.exists(target).then((ok) => {
+      if (!ok) throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+    });
     return true;
   } catch {
     return false;
@@ -91,9 +93,9 @@ async function pathExists(target: string): Promise<boolean> {
 
 async function readWorkflowFiles(workspaceRoot: string, dir: string) {
   const directory = path.join(workspaceRoot, dir);
-  const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+  const entries = await fs.readdir(directory).catch(() => []);
   return entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md")
+    .filter((entry) => entry.isFile && entry.name.endsWith(".md") && entry.name !== "README.md")
     .map((entry) => path.join(directory, entry.name))
     .sort();
 }
@@ -160,7 +162,7 @@ async function loadWorkflows(workspaceRoot: string, chain: WorkflowChain = "gree
   for (const file of files) {
     const relativeFile = path.relative(workspaceRoot, file).replace(/\\/g, "/");
     try {
-      const source = await fs.readFile(file, "utf8");
+      const source = await fs.readFile(file);
       workflows.push({
         relativeFile,
         chain,

package/os/workflow/workflow.module.ts

@@ -8,56 +8,57 @@
 <CHANGE_SUMMARY>
   <item>RFC-0075: Add workflow command module.</item>
   <item>RFC-0374: Migrated from packages/os/site-kernel/src/workflow/ to packages/forge/os/workflow/.</item>
+  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
 </CHANGE_SUMMARY>
 */
 
 import type { ForgeModule } from "../../src/forge-module.ts";
 
 export async function createForgeWorkflowModule(): Promise<ForgeModule> {
-const { runWorkflowLint, runWorkflowList, runWorkflowAmendList } =
-      await import("./handlers.ts");
+  const { runWorkflowLint, runWorkflowList, runWorkflowAmendList } = await import("./handlers.ts");
   return {
-  name: "workflow",
-  version: "0.1.0",
-  runtime: "autonomous",
+    name: "workflow",
+    version: "0.1.0",
+    runtime: "autonomous",
     declarations: [],
-  commands: [
-    {
-      name: "workflow.lint",
-      contract: "workflow",
-      rules: [],
-      description:
-        "Validate .agents/workflows AND .agents/workflows-amend markdown frontmatter, command references, " +
-        "and per-chain phase links (RFC-0075 + RFC-0136).",
-      scope: "workspace",
-      flags: {},
-      supportsAllSites: true,
-      reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
-      execute: runWorkflowLint,
-    },
-    {
-      name: "workflow.list",
-      description:
-        "List .agents/workflows entries with phase, IO summary, and next workflow (RFC-0075).",
-      scope: "workspace",
-      flags: {},
-      supportsAllSites: true,
-      reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
-      execute: runWorkflowList,
-    },
-    {
-      name: "workflow-amend.list",
-      description:
-        "List .agents/workflows-amend entries with phase, IO summary, and next workflow (RFC-0136).",
-      scope: "workspace",
-      flags: {},
-      supportsAllSites: true,
-      reads: [".agents/workflows-amend/**/*.md"],
-      execute: runWorkflowAmendList,
-    }
-  ],
-  pipelines: [
-
-  ]};
+    commands: [
+      {
+        name: "workflow.lint",
+        mutatesState: false,
+        contract: "workflow",
+        rules: [],
+        description:
+          "Validate .agents/workflows AND .agents/workflows-amend markdown frontmatter, command references, " +
+          "and per-chain phase links (RFC-0075 + RFC-0136).",
+        scope: "workspace",
+        flags: {},
+        supportsAllSites: true,
+        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
+        execute: runWorkflowLint,
+      },
+      {
+        name: "workflow.list",
+        mutatesState: false,
+        description:
+          "List .agents/workflows entries with phase, IO summary, and next workflow (RFC-0075).",
+        scope: "workspace",
+        flags: {},
+        supportsAllSites: true,
+        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
+        execute: runWorkflowList,
+      },
+      {
+        name: "workflow-amend.list",
+        mutatesState: false,
+        description:
+          "List .agents/workflows-amend entries with phase, IO summary, and next workflow (RFC-0136).",
+        scope: "workspace",
+        flags: {},
+        supportsAllSites: true,
+        reads: [".agents/workflows-amend/**/*.md"],
+        execute: runWorkflowAmendList,
+      },
+    ],
+    pipelines: [],
+  };
 }
-;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.2.4",
+  "version": "5.3.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/forge-shell.yaml

@@ -525,7 +525,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/godot-game.yaml

@@ -1002,7 +1002,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/knowledge.yaml

@@ -378,7 +378,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/phaser-game.yaml

@@ -605,7 +605,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]

package/profiles/site-workshop.yaml

@@ -516,7 +516,7 @@ workspace:
           "hooks": {
             "pre_user_prompt": [
               {
-                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "command": "node \"${ROOT_WORKSPACE_PATH:-$PWD}/hooks/pre-user-prompt-wrapper.mjs\"",
                 "show_output": true
               }
             ]