@nick848/fet 1.0.8 → 1.0.10

package/dist/cli/index.js

@@ -179,7 +179,12 @@ function toGitNexusState(detection, previous) {
     setupHandoffPath: previous?.setupHandoffPath ?? null,
     setupHandoffUpdatedAt: previous?.setupHandoffUpdatedAt ?? null,
     handoffPath: previous?.handoffPath ?? null,
-    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null
+    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null,
+    projectContextPath: previous?.projectContextPath ?? null,
+    projectContextUpdatedAt: previous?.projectContextUpdatedAt ?? null,
+    workflowContextPath: previous?.workflowContextPath ?? null,
+    workflowContextUpdatedAt: previous?.workflowContextUpdatedAt ?? null,
+    lastWorkflowGraphQuery: previous?.lastWorkflowGraphQuery ?? null
   };
 }
 async function inspectGitNexusGraph(projectRoot, env = process.env) {
@@ -248,7 +253,8 @@ function resolveGitNexusCommand(env) {
   const raw = env.FET_GITNEXUS_COMMAND?.trim() || env.FET_GITNEXUS_EXECUTABLE?.trim() || "gitnexus";
   const parts = splitCommand(raw);
   const [file = "gitnexus", ...args] = parts;
-  return { file, args, label: raw };
+  const resolvedFile = process.platform === "win32" && raw === "gitnexus" ? "gitnexus.cmd" : file;
+  return { file: resolvedFile, args, label: raw };
 }
 function splitCommand(value) {
   const matches = value.match(/"[^"]+"|'[^']+'|\S+/g);
@@ -442,8 +448,313 @@ FET:END -->
 }
 
 // src/commands/graph.ts
-import { mkdir as mkdir4 } from "fs/promises";
+import { mkdir as mkdir5 } from "fs/promises";
+import { dirname as dirname6, join as join9 } from "path";
+
+// src/graph-context.ts
+import { mkdir as mkdir4, readdir, readFile as readFile5 } from "fs/promises";
 import { dirname as dirname5, join as join8 } from "path";
+var MAX_SOURCE_CONTEXT = 8e3;
+var MAX_GRAPH_OUTPUT = 2e4;
+async function buildProjectGraphContext(ctx, state, trigger) {
+  if (!isGraphReadable(state)) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: ["GitNexus graph exists check did not pass; project graph context was not generated."]
+    };
+  }
+  const query = "FET OpenSpec workflow architecture commands adapters graph integration project structure";
+  const goal = "Summarize the repository modules, workflow entry points, and likely insertion points for future FET/OpenSpec work.";
+  const graphQuery = await runGitNexus(["query", query, "--goal", goal, "--limit", "8"], { cwd: ctx.projectRoot });
+  const status = await runGitNexus(["status"], { cwd: ctx.projectRoot });
+  const warnings = commandWarnings([["gitnexus query", graphQuery], ["gitnexus status", status]]);
+  const relativePath = ".fet/graph-context/project.md";
+  await writeGraphContext(
+    join8(ctx.projectRoot, relativePath),
+    renderProjectContext({
+      trigger,
+      state,
+      query,
+      goal,
+      status: commandText(status),
+      graphOutput: commandText(graphQuery),
+      warnings
+    })
+  );
+  return {
+    generated: true,
+    path: relativePath,
+    query,
+    warnings
+  };
+}
+async function buildWorkflowGraphContext(ctx, options) {
+  const existing = await ctx.stateStore.getOrCreateGlobal();
+  if (!existing.graph?.gitnexus?.graphExists) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: []
+    };
+  }
+  const state = await refreshGitNexusState(ctx);
+  if (!isGraphReadable(state)) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: []
+    };
+  }
+  const sourceContext = await collectOpenSpecContext(ctx.projectRoot, options.changeId);
+  const query = buildWorkflowQuery(options, sourceContext);
+  const goal = workflowGoal(options.command);
+  const graphQuery = await runGitNexus(["query", query, "--goal", goal, "--limit", "8"], { cwd: ctx.projectRoot });
+  const detectChanges = shouldDetectChanges(options.command) ? await runGitNexus(["detect-changes", "--scope", "all"], { cwd: ctx.projectRoot }) : null;
+  const warnings = commandWarnings([
+    ["gitnexus query", graphQuery],
+    ...detectChanges ? [["gitnexus detect-changes", detectChanges]] : []
+  ]);
+  const relativePath = `.fet/graph-context/${sanitizePathPart(options.changeId ?? options.command)}.md`;
+  await writeGraphContext(
+    join8(ctx.projectRoot, relativePath),
+    renderWorkflowContext({
+      state,
+      command: options.command,
+      args: options.args,
+      changeId: options.changeId,
+      query,
+      goal,
+      sourceContext,
+      graphOutput: commandText(graphQuery),
+      detectChanges: detectChanges ? commandText(detectChanges) : null,
+      warnings
+    })
+  );
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  global.graph.gitnexus = {
+    ...state,
+    workflowContextPath: relativePath,
+    workflowContextUpdatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastWorkflowGraphQuery: query
+  };
+  await ctx.stateStore.writeGlobal(global);
+  return {
+    generated: true,
+    path: relativePath,
+    query,
+    warnings
+  };
+}
+async function refreshGitNexusState(ctx) {
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  const detection = await detectGitNexus();
+  const graph2 = await inspectGitNexusGraph(ctx.projectRoot);
+  const state = mergeGitNexusGraphInfo(toGitNexusState(detection, global.graph.gitnexus), graph2);
+  global.graph.gitnexus = state;
+  await ctx.stateStore.writeGlobal(global);
+  return state;
+}
+function isGraphReadable(state) {
+  return Boolean(state.installed && state.graphExists);
+}
+async function writeGraphContext(path, content) {
+  await mkdir4(dirname5(path), { recursive: true });
+  await atomicWrite(path, content);
+}
+function renderProjectContext(options) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-context
+scope: project
+FET:END -->
+
+# FET GitNexus Project Graph Context
+
+Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+Trigger: ${options.trigger}
+
+Use this file before broad repository scans in FET/OpenSpec work. Treat it as graph-derived context: confirm concrete behavior by reading the source files it points to.
+
+## Graph State
+
+- Provider: GitNexus
+- Installed: ${options.state.installed ? "yes" : "no"}
+- Version: ${options.state.version ?? "unknown"}
+- Graph path: ${options.state.graphPath ?? ".gitnexus"}
+- Graph exists: ${options.state.graphExists ? "yes" : "no"}
+- Last indexed at: ${options.state.lastIndexedAt ?? "unknown"}
+
+## GitNexus Status
+
+\`\`\`text
+${clip(options.status, MAX_GRAPH_OUTPUT)}
+\`\`\`
+
+## Project Query
+
+- Query: ${options.query}
+- Goal: ${options.goal}
+
+\`\`\`text
+${clip(options.graphOutput, MAX_GRAPH_OUTPUT)}
+\`\`\`
+${renderWarnings(options.warnings)}
+`;
+}
+function renderWorkflowContext(options) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-context
+scope: workflow
+FET:END -->
+
+# FET GitNexus Workflow Graph Context
+
+Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+Read this before editing or generating OpenSpec artifacts for this workflow. Use the graph output to narrow likely files, symbols, dependencies, and impact areas. If it conflicts with OpenSpec artifacts or source code, OpenSpec artifacts and source code win.
+
+## Workflow
+
+- FET command: ${options.command}
+- Args: ${options.args.length ? options.args.join(" ") : "(none)"}
+- Change: ${options.changeId ?? "(none)"}
+- Graph path: ${options.state.graphPath ?? ".gitnexus"}
+- Last indexed at: ${options.state.lastIndexedAt ?? "unknown"}
+
+## OpenSpec Context Used For Query
+
+\`\`\`text
+${clip(options.sourceContext || "(no change artifacts found yet)", MAX_SOURCE_CONTEXT)}
+\`\`\`
+
+## GitNexus Query
+
+- Query: ${options.query}
+- Goal: ${options.goal}
+
+\`\`\`text
+${clip(options.graphOutput, MAX_GRAPH_OUTPUT)}
+\`\`\`
+${options.detectChanges ? `
+## GitNexus Change Impact
+
+\`\`\`text
+${clip(options.detectChanges, MAX_GRAPH_OUTPUT)}
+\`\`\`
+` : ""}
+${renderWarnings(options.warnings)}
+`;
+}
+function renderWarnings(warnings) {
+  if (!warnings.length) {
+    return "";
+  }
+  return `
+## Warnings
+
+${warnings.map((warning) => `- ${warning}`).join("\n")}
+`;
+}
+async function collectOpenSpecContext(projectRoot, changeId) {
+  if (!changeId) {
+    return "";
+  }
+  const changeRoot = join8(projectRoot, "openspec", "changes", changeId);
+  const chunks = [];
+  for (const file of ["proposal.md", "design.md", "tasks.md", "README.md"]) {
+    const content = await readOptional(join8(changeRoot, file));
+    if (content) {
+      chunks.push(`## ${file}
+${content}`);
+    }
+  }
+  const specsRoot = join8(changeRoot, "specs");
+  for (const spec of await listSpecFiles(specsRoot)) {
+    const content = await readOptional(spec.path);
+    if (content) {
+      chunks.push(`## ${spec.label}
+${content}`);
+    }
+  }
+  return clip(chunks.join("\n\n"), MAX_SOURCE_CONTEXT);
+}
+async function listSpecFiles(specsRoot) {
+  try {
+    const capabilities = await readdir(specsRoot, { withFileTypes: true });
+    return capabilities.filter((entry) => entry.isDirectory()).map((entry) => ({
+      path: join8(specsRoot, entry.name, "spec.md"),
+      label: `specs/${entry.name}/spec.md`
+    }));
+  } catch {
+    return [];
+  }
+}
+async function readOptional(path) {
+  try {
+    return await readFile5(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function buildWorkflowQuery(options, sourceContext) {
+  const artifactTerms = normalizeWhitespace(sourceContext).slice(0, 1200);
+  return normalizeWhitespace(
+    [
+      `FET OpenSpec ${options.command}`,
+      options.changeId ? `change ${options.changeId}` : "",
+      options.args.join(" "),
+      artifactTerms
+    ].join(" ")
+  );
+}
+function workflowGoal(command) {
+  if (command === "apply") {
+    return "Find implementation files, symbols, dependencies, and likely blast radius for the current OpenSpec tasks.";
+  }
+  if (command === "verify") {
+    return "Find affected flows and source areas that should be checked while verifying this OpenSpec change.";
+  }
+  if (["explore", "propose", "new", "continue", "ff"].includes(command)) {
+    return "Find relevant modules, entry points, and existing behavior to make OpenSpec artifacts precise.";
+  }
+  return "Find relevant repository context for this FET/OpenSpec workflow command.";
+}
+function shouldDetectChanges(command) {
+  return ["apply", "verify", "sync"].includes(command);
+}
+function commandText(result) {
+  const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+  return output || `exit ${result.exitCode}`;
+}
+function commandWarnings(results) {
+  return results.filter(([, result]) => result.exitCode !== 0).map(([label, result]) => `${label} exited with ${result.exitCode}: ${firstLine(commandText(result))}`);
+}
+function firstLine(value) {
+  return value.trim().split(/\r?\n/)[0]?.trim() || "no output";
+}
+function clip(value, max) {
+  if (value.length <= max) {
+    return value;
+  }
+  return `${value.slice(0, max)}
+
+[truncated ${value.length - max} characters]`;
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function sanitizePathPart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "workflow";
+}
+
+// src/commands/graph.ts
 async function graphCommand(ctx, action, args = []) {
   switch (action) {
     case "status":
@@ -498,7 +809,7 @@ async function graphDoctorCommand(ctx) {
 }
 async function graphSetupCommand(ctx) {
   let result;
-  const handoffPath = join8(ctx.projectRoot, ".fet", "graph-setup.md");
+  const handoffPath = join9(ctx.projectRoot, ".fet", "graph-setup.md");
   const installCommand = process.env.FET_GITNEXUS_INSTALL_COMMAND?.trim() || null;
   await withProjectLock(ctx.projectRoot, { command: "graph setup", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     result = await refreshGraphState(ctx, { write: false });
@@ -534,7 +845,7 @@ async function graphSetupCommand(ctx) {
 }
 async function graphHandoffCommand(ctx) {
   let result;
-  const handoffPath = join8(ctx.projectRoot, ".fet", "graph-handoff.md");
+  const handoffPath = join9(ctx.projectRoot, ".fet", "graph-handoff.md");
   await withProjectLock(ctx.projectRoot, { command: "graph handoff", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     result = await refreshGraphState(ctx, { runStatus: true, write: false });
     await writeHandoffFile(handoffPath, renderGraphUsageHandoff(result.state, ctx.language));
@@ -581,11 +892,14 @@ async function graphAnalyzeCommand(ctx, mode, args) {
     });
   }
   const result = await refreshGraphState(ctx, { write: false });
+  const graphContext = await buildProjectGraphContext(ctx, result.state, `fet graph ${mode}`);
   const global = await ctx.stateStore.getOrCreateGlobal();
   global.graph ??= {};
   global.graph.gitnexus = {
     ...result.state,
-    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString()
+    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectContextPath: graphContext.path,
+    projectContextUpdatedAt: graphContext.generated ? (/* @__PURE__ */ new Date()).toISOString() : result.state.projectContextUpdatedAt ?? null
   };
   await ctx.stateStore.writeGlobal(global);
   ctx.output.result({
@@ -595,9 +909,10 @@ async function graphAnalyzeCommand(ctx, mode, args) {
     warnings: result.state.graphExists ? [] : [
       ctx.language === "en" ? "GitNexus analyze completed, but the configured graph directory was not found." : "GitNexus analyze \u5DF2\u5B8C\u6210\uFF0C\u4F46\u672A\u53D1\u73B0\u914D\u7F6E\u7684\u4EE3\u7801\u56FE\u76EE\u5F55\u3002"
     ],
-    nextSteps: ctx.language === "en" ? ["Run fet graph status", "Use .fet/graph-handoff.md or generated IDE prompts to prefer graph context"] : ["\u8FD0\u884C fet graph status", "\u4F7F\u7528 .fet/graph-handoff.md \u6216\u751F\u6210\u7684 IDE \u63D0\u793A\uFF0C\u4F18\u5148\u53C2\u8003\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587"],
+    nextSteps: ctx.language === "en" ? ["Run fet graph status", "Read .fet/graph-context/project.md before broad scans", "Use .fet/graph-handoff.md or generated IDE prompts to prefer graph context"] : ["\u8FD0\u884C fet graph status", "\u4F7F\u7528 .fet/graph-handoff.md \u6216\u751F\u6210\u7684 IDE \u63D0\u793A\uFF0C\u4F18\u5148\u53C2\u8003\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587"],
     data: {
       gitnexus: global.graph.gitnexus,
+      graphContext,
       run: {
         command: run.command,
         stdout: run.stdout.trim(),
@@ -617,7 +932,7 @@ async function refreshGraphState(ctx, options = {}) {
     gitnexusStatus = await runGitNexus(["status"], { cwd: ctx.projectRoot });
     state = {
       ...state,
-      lastStatus: firstLine(gitnexusStatus.stdout) || firstLine(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
+      lastStatus: firstLine2(gitnexusStatus.stdout) || firstLine2(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
     };
   }
   if (options.write ?? true) {
@@ -635,7 +950,7 @@ async function refreshGraphState(ctx, options = {}) {
   };
 }
 async function writeHandoffFile(path, content) {
-  await mkdir4(dirname5(path), { recursive: true });
+  await mkdir5(dirname6(path), { recursive: true });
   await atomicWrite(path, content);
 }
 function renderGraphSetupHandoff(state, options) {
@@ -780,24 +1095,24 @@ FET:END -->
 - \u6240\u6709\u751F\u6210\u4EA7\u7269\u4ECD\u5199\u5165\u6B63\u5E38\u7684 OpenSpec change \u76EE\u5F55\u3002
 `;
 }
-function firstLine(value) {
+function firstLine2(value) {
   return value.trim().split(/\r?\n/)[0]?.trim() || null;
 }
 
 // src/commands/init.ts
-import { readFile as readFile7, stat as stat4 } from "fs/promises";
-import { join as join11 } from "path";
+import { readFile as readFile8, stat as stat4 } from "fs/promises";
+import { join as join12 } from "path";
 
 // src/version.ts
 import { existsSync, readFileSync } from "fs";
-import { dirname as dirname6, join as join9, parse } from "path";
+import { dirname as dirname7, join as join10, parse } from "path";
 import { fileURLToPath } from "url";
 var FET_VERSION = readPackageVersion();
 function readPackageVersion() {
-  let currentDir = dirname6(fileURLToPath(import.meta.url));
+  let currentDir = dirname7(fileURLToPath(import.meta.url));
   const root = parse(currentDir).root;
   while (true) {
-    const packageJsonPath = join9(currentDir, "package.json");
+    const packageJsonPath = join10(currentDir, "package.json");
     if (existsSync(packageJsonPath)) {
       const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
       if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
@@ -808,7 +1123,7 @@ function readPackageVersion() {
     if (currentDir === root) {
       throw new Error("\u65E0\u6CD5\u5B9A\u4F4D FET package.json");
     }
-    currentDir = dirname6(currentDir);
+    currentDir = dirname7(currentDir);
   }
 }
 
@@ -1259,18 +1574,18 @@ ${block}
 }
 
 // src/commands/update-context.ts
-import { readFile as readFile6 } from "fs/promises";
-import { join as join10 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join11 } from "path";
 
 // src/config/yaml.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { parseDocument } from "yaml";
 async function mergeFetConfig(configPath, renderedFetYaml) {
   const fetDoc = parseDocument(renderedFetYaml);
   const nextFet = fetDoc.get("fet", true);
   let existing = "";
   try {
-    existing = await readFile5(configPath, "utf8");
+    existing = await readFile6(configPath, "utf8");
   } catch {
     return renderedFetYaml;
   }
@@ -1294,14 +1609,14 @@ async function updateContextCommand(ctx) {
 }
 async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-  const agentsPath = join10(ctx.projectRoot, "AGENTS.md");
-  const configPath = join10(ctx.projectRoot, "openspec", "config.yaml");
-  const claudePath = join10(ctx.projectRoot, "CLAUDE.md");
-  const karpathyHandoffPath = join10(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
-  const karpathyCursorPath = join10(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
-  const existingAgents = await readOptional(agentsPath);
-  const existingClaude = await readOptional(claudePath);
-  const existingKarpathyCursor = await readOptional(karpathyCursorPath);
+  const agentsPath = join11(ctx.projectRoot, "AGENTS.md");
+  const configPath = join11(ctx.projectRoot, "openspec", "config.yaml");
+  const claudePath = join11(ctx.projectRoot, "CLAUDE.md");
+  const karpathyHandoffPath = join11(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
+  const karpathyCursorPath = join11(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
+  const existingAgents = await readOptional2(agentsPath);
+  const existingClaude = await readOptional2(claudePath);
+  const existingKarpathyCursor = await readOptional2(karpathyCursorPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
     throw new FetError({
@@ -1349,9 +1664,9 @@ async function updateContextFiles(ctx) {
   await ctx.stateStore.writeGlobal(state);
   return { warnings };
 }
-async function readOptional(path) {
+async function readOptional2(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch {
     return null;
   }
@@ -1359,7 +1674,7 @@ async function readOptional(path) {
 
 // src/commands/init.ts
 async function initCommand(ctx) {
-  const alreadyInitialized = await exists2(join11(ctx.projectRoot, "openspec", "config.yaml"));
+  const alreadyInitialized = await exists2(join12(ctx.projectRoot, "openspec", "config.yaml"));
   let warnings = [];
   await withProjectLock(ctx.projectRoot, { command: "init", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     const journal = createInitJournal(ctx.fetVersion);
@@ -1411,13 +1726,13 @@ async function initCommand(ctx) {
   });
 }
 async function ensureGitignore(ctx) {
-  const gitignorePath = join11(ctx.projectRoot, ".gitignore");
-  const existing = await readOptional2(gitignorePath);
+  const gitignorePath = join12(ctx.projectRoot, ".gitignore");
+  const existing = await readOptional3(gitignorePath);
   await atomicWrite(gitignorePath, mergeGitignore(existing));
 }
-async function readOptional2(path) {
+async function readOptional3(path) {
   try {
-    return await readFile7(path, "utf8");
+    return await readFile8(path, "utf8");
   } catch {
     return null;
   }
@@ -1432,8 +1747,8 @@ async function exists2(path) {
 }
 
 // src/commands/proxy.ts
-import { readFile as readFile10 } from "fs/promises";
-import { join as join13 } from "path";
+import { readFile as readFile11 } from "fs/promises";
+import { join as join14 } from "path";
 
 // src/state/project.ts
 import { execFile as execFile2 } from "child_process";
@@ -1462,8 +1777,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
-import { join as join12 } from "path";
+import { mkdir as mkdir6, readFile as readFile9 } from "fs/promises";
+import { join as join13 } from "path";
 
 // src/language.ts
 var DEFAULT_LANGUAGE = "zh-CN";
@@ -1581,7 +1896,7 @@ var StateStore = class {
   project;
   async readGlobal() {
     try {
-      const value = JSON.parse(await readFile8(this.globalPath(), "utf8"));
+      const value = JSON.parse(await readFile9(this.globalPath(), "utf8"));
       assertGlobalState(value);
       return value;
     } catch (error) {
@@ -1596,13 +1911,13 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir5(join12(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir6(join13(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
   async readChange(changeId) {
     try {
-      const value = JSON.parse(await readFile8(this.changePath(changeId), "utf8"));
+      const value = JSON.parse(await readFile9(this.changePath(changeId), "utf8"));
       assertChangeState(value);
       return value;
     } catch (error) {
@@ -1617,15 +1932,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir5(join12(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir6(join13(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join12(this.projectRoot, "openspec", "fet-state.json");
+    return join13(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join12(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join13(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -1633,11 +1948,11 @@ function isNotFound(error) {
 }
 
 // src/state/tasks.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 async function readCompletedTaskIds(tasksPath) {
   let content;
   try {
-    content = await readFile9(tasksPath, "utf8");
+    content = await readFile10(tasksPath, "utf8");
   } catch {
     return [];
   }
@@ -1668,71 +1983,94 @@ var phaseByCommand = {
 };
 async function proxyCommand(ctx, command, args) {
   const openSpecArgs = stripFetOptions(args);
-  await withProjectLock(
-    ctx.projectRoot,
-    { command, cwd: ctx.cwd, fetVersion: ctx.fetVersion },
-    async () => {
-      if (["sync", "archive", "bulk-archive"].includes(command)) {
-        await assertVerified(ctx);
-      }
-      const mapped = await mapOpenSpecCommand(ctx, command, openSpecArgs);
-      const targetChangeId = command === "archive" ? mapped.args[0] ?? ctx.changeId ?? null : ctx.changeId ?? null;
-      const changelogEntry = command === "archive" && targetChangeId ? await createChangelogEntry(ctx.projectRoot, targetChangeId) : null;
-      const result = await ctx.openSpec.run(mapped.command, mapped.args, { cwd: ctx.projectRoot, stdio: ctx.json ? "pipe" : "inherit" });
-      if (result.exitCode !== 0) {
-        throw new FetError({
-          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
-          message: `OpenSpec ${command} \u6267\u884C\u5931\u8D25`,
-          details: result,
-          recoverable: true
-        });
-      }
-      if (changelogEntry) {
-        await appendChangelog(ctx.projectRoot, changelogEntry);
-      }
-      const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
-      const state = await ctx.stateStore.getOrCreateGlobal();
-      state.openChangeIds = inspection.changes;
-      if (command === "archive") {
-        if (!state.activeChangeId || state.activeChangeId === targetChangeId || !inspection.changes.includes(state.activeChangeId)) {
-          state.activeChangeId = null;
-        }
-        state.verifyAuthorization = null;
-      } else {
-        if (ctx.changeId && inspection.changes.includes(ctx.changeId)) {
-          state.activeChangeId = ctx.changeId;
-        } else if (state.activeChangeId && !inspection.changes.includes(state.activeChangeId)) {
-          state.activeChangeId = inspection.changes.length === 1 ? inspection.changes[0] ?? null : null;
-        } else if (!state.activeChangeId && inspection.changes.length === 1) {
-          state.activeChangeId = inspection.changes[0] ?? null;
-        }
-      }
-      await ctx.stateStore.writeGlobal(state);
-      const changeId = ctx.changeId ?? state.activeChangeId;
-      if (changeId && inspection.changes.includes(changeId)) {
-        const changeInspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
-        const changeState = await ctx.stateStore.getOrCreateChange(changeId, phaseByCommand[command] ?? "propose");
-        changeState.currentPhase = phaseByCommand[command] ?? changeState.currentPhase;
-        changeState.phases[changeState.currentPhase] = {
-          status: "done",
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        changeState.lastOpenSpecCommand = {
-          command: mapped.command,
-          args: mapped.args,
-          exitCode: result.exitCode,
-          ranAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        changeState.tasks.completedIds = await readCompletedTaskIds(changeInspection.tasksPath);
-        changeState.tasks.lastSyncedAt = (/* @__PURE__ */ new Date()).toISOString();
-        await ctx.stateStore.writeChange(changeState);
+  const runState = {};
+  await withProjectLock(ctx.projectRoot, { command, cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    if (["sync", "archive", "bulk-archive"].includes(command)) {
+      await assertVerified(ctx);
+    }
+    const mapped = await mapOpenSpecCommand(ctx, command, openSpecArgs);
+    await assertOpenSpecCommandSupported(ctx, mapped.command, command);
+    const mappedChangeId = extractChangeId(mapped.args);
+    const targetChangeId = command === "archive" ? mapped.args[0] ?? ctx.changeId ?? mappedChangeId : ctx.changeId ?? mappedChangeId;
+    runState.graphContext = await buildWorkflowGraphContext(ctx, {
+      command,
+      args: mapped.args,
+      changeId: targetChangeId
+    });
+    const changelogEntry = command === "archive" && targetChangeId ? await createChangelogEntry(ctx.projectRoot, targetChangeId) : null;
+    const result = await ctx.openSpec.run(mapped.command, mapped.args, { cwd: ctx.projectRoot, stdio: ctx.json ? "pipe" : "inherit" });
+    if (result.exitCode !== 0) {
+      throw new FetError({
+        code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+        message: `OpenSpec ${command} failed.`,
+        details: result,
+        recoverable: true
+      });
+    }
+    if (changelogEntry) {
+      await appendChangelog(ctx.projectRoot, changelogEntry);
+    }
+    const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
+    const state = await ctx.stateStore.getOrCreateGlobal();
+    state.openChangeIds = inspection.changes;
+    if (command === "archive") {
+      if (!state.activeChangeId || state.activeChangeId === targetChangeId || !inspection.changes.includes(state.activeChangeId)) {
+        state.activeChangeId = null;
       }
+      state.verifyAuthorization = null;
+    } else if (ctx.changeId && inspection.changes.includes(ctx.changeId)) {
+      state.activeChangeId = ctx.changeId;
+    } else if (state.activeChangeId && !inspection.changes.includes(state.activeChangeId)) {
+      state.activeChangeId = inspection.changes.length === 1 ? inspection.changes[0] ?? null : null;
+    } else if (!state.activeChangeId && inspection.changes.length === 1) {
+      state.activeChangeId = inspection.changes[0] ?? null;
     }
-  );
+    await ctx.stateStore.writeGlobal(state);
+    const changeId = ctx.changeId ?? state.activeChangeId;
+    if (changeId && inspection.changes.includes(changeId)) {
+      const changeInspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
+      const changeState = await ctx.stateStore.getOrCreateChange(changeId, phaseByCommand[command] ?? "propose");
+      changeState.currentPhase = phaseByCommand[command] ?? changeState.currentPhase;
+      changeState.phases[changeState.currentPhase] = {
+        status: "done",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      changeState.lastOpenSpecCommand = {
+        command: mapped.command,
+        args: mapped.args,
+        exitCode: result.exitCode,
+        ranAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      changeState.tasks.completedIds = await readCompletedTaskIds(changeInspection.tasksPath);
+      changeState.tasks.lastSyncedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await ctx.stateStore.writeChange(changeState);
+    }
+  });
+  const graphContext = runState.graphContext;
   ctx.output.result({
     ok: true,
     command,
-    summary: `fet ${command} \u5B8C\u6210\u3002`
+    summary: `fet ${command} completed.`,
+    warnings: graphContext?.warnings,
+    nextSteps: graphContext?.generated && graphContext.path ? [`Read ${graphContext.path} before broad source scans or implementation decisions.`] : void 0,
+    data: graphContext ? { graphContext } : void 0
+  });
+}
+async function assertOpenSpecCommandSupported(ctx, openSpecCommand, fetCommand) {
+  const capabilities = await ctx.openSpec.getCapabilities();
+  if (capabilities.commands.includes(openSpecCommand)) {
+    return;
+  }
+  throw new FetError({
+    code: "OPENSPEC_UNSUPPORTED_VERSION" /* OpenSpecUnsupportedVersion */,
+    message: `OpenSpec CLI ${capabilities.version} does not expose command "${openSpecCommand}" required by "fet ${fetCommand}". FET will not substitute another workflow command automatically.`,
+    details: {
+      openSpecVersion: capabilities.version,
+      requiredCommand: openSpecCommand,
+      availableCommands: capabilities.commands,
+      supported: capabilities.supported
+    },
+    suggestedCommand: "Upgrade OpenSpec to a version that supports this command, then rerun FET. Try: npm install -g @fission-ai/openspec@latest && fet doctor. If your OpenSpec version intentionally removed this command, pause and choose a compatible FET workflow instead of running ff automatically."
   });
 }
 async function createChangelogEntry(projectRoot, changeId) {
@@ -1742,10 +2080,12 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join13(projectRoot, "CHANGELOG.md");
-  const existing = await readOptional3(changelogPath);
+  const changelogPath = join14(projectRoot, "CHANGELOG.md");
+  const existing = await readOptional4(changelogPath);
+  const legacyContentLabel = "\u66F4\u65B0\u5185\u5BB9";
   const block = `updateTime: ${entry.updateTime}
-\u66F4\u65B0\u5185\u5BB9:${entry.content}
+changeRequirement:${entry.content}
+${legacyContentLabel}:${entry.content}
 `;
   const next = existing?.trimEnd() ? `${existing.trimEnd()}
 
@@ -1753,12 +2093,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join13(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional3(join13(changeRoot, "proposal.md"));
+  const changeRoot = join14(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional4(join14(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional3(join13(changeRoot, "README.md"));
+  const readme = await readOptional4(join14(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -1766,11 +2106,11 @@ async function readChangeRequirement(projectRoot, changeId) {
 }
 function summarizeMarkdown(content) {
   const normalized = content.replace(/\r\n/g, "\n").split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("<!--") && !line.startsWith("---")).join(" ");
-  return normalized || "\u672A\u63D0\u4F9B\u53D8\u66F4\u9700\u6C42";
+  return normalized || "No change requirement found.";
 }
-async function readOptional3(path) {
+async function readOptional4(path) {
   try {
-    return await readFile10(path, "utf8");
+    return await readFile11(path, "utf8");
   } catch {
     return null;
   }
@@ -1792,7 +2132,7 @@ async function passthroughCommand(ctx, command, args) {
   if (result.exitCode !== 0) {
     throw new FetError({
       code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
-      message: `OpenSpec ${command} \u6267\u884C\u5931\u8D25`,
+      message: `OpenSpec ${command} failed.`,
       details: result
     });
   }
@@ -1834,18 +2174,6 @@ async function mapOpenSpecCommand(ctx, command, args) {
       return { command: "new", args: args[0] === "change" ? args : ["change", ...args] };
     case "archive":
       return { command: "archive", args: [ctx.changeId ?? args[0] ?? await requireChangeId(ctx), ...args.slice(ctx.changeId ? 0 : 1)] };
-    /*
-    case "bulk-archive":
-      throw new FetError({
-        code: ErrorCode.InvalidArguments,
-        message: "OpenSpec 1.2.0 不提供 bulk-archive 顶层命令",
-        suggestedCommand: "逐个执行 fet archive --change <change-id>"
-      });
-    case "explore":
-      return { command: "explore", args: ctx.changeId ? ["--change", ctx.changeId, ...args] : args };
-    case "onboard":
-      return { command: "instructions", args: [] };
-    */
     default:
       return { command, args };
   }
@@ -1865,6 +2193,18 @@ async function withDefaultChange(ctx, args, allowWithArgs = false) {
   }
   return ["--change", await requireChangeId(ctx), ...args];
 }
+function extractChangeId(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--change") {
+      return args[index + 1] ?? null;
+    }
+    if (arg?.startsWith("--change=")) {
+      return arg.slice("--change=".length) || null;
+    }
+  }
+  return null;
+}
 async function requireChangeId(ctx) {
   if (ctx.changeId) {
     return ctx.changeId;
@@ -1879,9 +2219,9 @@ async function requireChangeId(ctx) {
   }
   throw new FetError({
     code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-    message: "\u8BE5\u547D\u4EE4\u9700\u8981\u660E\u786E\u7684 change",
+    message: "No unambiguous OpenSpec change id was found.",
     details: { openChangeIds: inspection.changes },
-    suggestedCommand: "\u6DFB\u52A0 --change <change-id>"
+    suggestedCommand: "Pass --change <change-id>."
   });
 }
 async function assertVerified(ctx) {
@@ -1890,7 +2230,7 @@ async function assertVerified(ctx) {
   if (!changeId) {
     throw new FetError({
       code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-      message: "\u672A\u6307\u5B9A change\uFF0C\u65E0\u6CD5\u68C0\u67E5 verify \u72B6\u6001",
+      message: "A change id is required before this command can check FET verification.",
       suggestedCommand: "fet verify --done --change <change-id>"
     });
   }
@@ -1899,7 +2239,7 @@ async function assertVerified(ctx) {
   if (!inspection.changes.includes(changeId)) {
     throw new FetError({
       code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-      message: "\u6307\u5B9A\u7684 change \u4E0D\u5B58\u5728\u6216\u5DF2\u5F52\u6863",
+      message: "The selected change does not exist in openspec/changes.",
       details: { changeId, openChangeIds: inspection.changes },
       suggestedCommand: "fet doctor"
     });
@@ -1907,7 +2247,7 @@ async function assertVerified(ctx) {
   if (change?.manualVerify?.status !== "declared_done") {
     throw new FetError({
       code: "STATE_CORRUPTED" /* StateCorrupted */,
-      message: "\u5F53\u524D change \u5C1A\u672A\u901A\u8FC7 FET verify",
+      message: "This change has not been marked verified by FET.",
       details: { changeId },
       suggestedCommand: `fet verify --change ${changeId}`
     });
@@ -1916,8 +2256,8 @@ async function assertVerified(ctx) {
 
 // src/commands/verify.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir6, readFile as readFile11, stat as stat5 } from "fs/promises";
-import { join as join14 } from "path";
+import { mkdir as mkdir7, readFile as readFile12, stat as stat5 } from "fs/promises";
+import { join as join15 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -1984,9 +2324,9 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join14(dir, "verify-instructions.md");
-  await mkdir6(dir, { recursive: true });
+  const dir = join15(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join15(dir, "verify-instructions.md");
+  await mkdir7(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -2002,7 +2342,7 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join15(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -2038,7 +2378,7 @@ async function assertChangeExists(ctx, changeId) {
 async function readInstructions(path, changeId) {
   try {
     await stat5(path);
-    const content = await readFile11(path, "utf8");
+    const content = await readFile12(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -2176,9 +2516,9 @@ function renderIdeModelPolicy(command, language = "zh-CN") {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir7, readFile as readFile12, stat as stat6 } from "fs/promises";
+import { mkdir as mkdir8, readFile as readFile13, stat as stat6 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname7, join as join15 } from "path";
+import { dirname as dirname8, join as join16 } from "path";
 
 // src/adapters/commands.ts
 var FET_WORKFLOW_COMMANDS = [
@@ -2489,15 +2829,15 @@ After the command completes, report the GitNexus state, generated handoff files,
 `;
 }
 function renderSlashPrompt(command, language) {
+  if (command === "ff" || command === "propose") {
+    return renderFastForwardSlashPrompt(command, language);
+  }
   if (language !== "en") {
     return renderSlashPromptZh(command);
   }
   if (command === "continue") {
     return renderContinueSlashPrompt(language);
   }
-  if (command === "ff" || command === "propose") {
-    return renderFastForwardSlashPrompt(command, language);
-  }
   if (command === "explore") {
     return renderExploreSlashPrompt(language);
   }
@@ -3097,11 +3437,11 @@ Guardrails:
   );
 }
 function renderFastForwardSlashPrompt(command, language) {
-  const title = command === "propose" ? "Propose a new FET/OpenSpec change" : "Fast-forward FET/OpenSpec artifact creation";
+  const title = language === "en" ? command === "propose" ? "Propose a new FET/OpenSpec change" : "Fast-forward FET/OpenSpec artifact creation" : command === "propose" ? "\u521B\u5EFA\u5E76\u8865\u9F50 FET/OpenSpec \u63D0\u6848\u4EA7\u7269" : "\u5FEB\u901F\u751F\u6210 FET/OpenSpec \u6240\u9700\u4EA7\u7269";
   const commandLine = command === "propose" ? "fet propose <change-id-or-description>" : "fet ff --change <change-id>";
   return renderManagedSlashPrompt(
     `fet ${command} [...args]`,
-    command === "propose" ? "Create a change and generate required OpenSpec artifacts" : "Generate required OpenSpec artifacts for a change",
+    language === "en" ? command === "propose" ? "Create a change and generate required OpenSpec artifacts" : "Generate required OpenSpec artifacts for a change" : command === "propose" ? "\u521B\u5EFA\u5E76\u8865\u9F50 FET/OpenSpec \u63D0\u6848\u4EA7\u7269" : "\u5FEB\u901F\u751F\u6210 FET/OpenSpec \u6240\u9700\u4EA7\u7269",
     `${title}.
 
 Input after the slash command may be a change id or a description of what the user wants to build. For ff, it may be omitted when the active OpenSpec change is unambiguous.
@@ -3116,6 +3456,7 @@ Steps:
    \`\`\`
 4. Follow the native output. If it asks for clarification, ask the user rather than inventing details.
 5. If the native output includes artifact paths or templates to write, create only those files and preserve OpenSpec structure.
+6. If FET reports that the OpenSpec CLI does not expose the requested command, stop immediately. Do not run \`fet ff\`, \`openspec ff\`, \`openspec change\`, or any alternative workflow command unless the user explicitly chooses that fallback after seeing the error.
 
 Artifact rules:
 - Follow the instruction field from OpenSpec/FET for each artifact.
@@ -3127,7 +3468,11 @@ Output:
 - Change id and location.
 - Artifacts created.
 - Current status.
-- Next recommended command, usually /prompts:fet-apply <change-id>.`,
+- Next recommended command, usually /prompts:fet-apply <change-id>.
+
+Guardrails:
+- Do not substitute one FET/OpenSpec workflow command for another after a command-not-found or unsupported-version error.
+- If OpenSpec appears outdated or incompatible, report the detected version and suggest \`npm install -g @fission-ai/openspec@latest\` or \`fet doctor\`, then wait for the user's decision.`,
     void 0,
     language
   );
@@ -3165,7 +3510,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists3(join15(projectRoot, ".codex")) || await exists3(join15(projectRoot, "AGENTS.md")),
+      detected: await exists3(join16(projectRoot, ".codex")) || await exists3(join16(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -3204,7 +3549,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir7(dirname7(target), { recursive: true });
+      await mkdir8(dirname8(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -3231,9 +3576,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join15(resolveCodexHome(), file.path);
+    return join16(resolveCodexHome(), file.path);
   }
-  return join15(projectRoot, file.path);
+  return join16(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -3242,11 +3587,11 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join15(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join16(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile12(path, "utf8");
+    return await readFile13(path, "utf8");
   } catch {
     return null;
   }
@@ -3261,8 +3606,8 @@ async function exists3(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir8, readFile as readFile13, stat as stat7 } from "fs/promises";
-import { dirname as dirname8, join as join16 } from "path";
+import { mkdir as mkdir9, readFile as readFile14, stat as stat7 } from "fs/promises";
+import { dirname as dirname9, join as join17 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorSkillFiles(language = DEFAULT_LANGUAGE) {
@@ -3396,7 +3741,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists4(join16(projectRoot, ".cursor")),
+      detected: await exists4(join17(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -3413,7 +3758,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join16(projectRoot, file.path);
+      const target = join17(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -3426,7 +3771,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir8(dirname8(target), { recursive: true });
+      await mkdir9(dirname9(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -3436,7 +3781,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join16(projectRoot, file.path);
+      const target = join17(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -3452,7 +3797,7 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile13(path, "utf8");
+    return await readFile14(path, "utf8");
   } catch {
     return null;
   }
@@ -3471,13 +3816,13 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir, stat as stat8 } from "fs/promises";
-import { join as join17 } from "path";
+import { readdir as readdir2, stat as stat8 } from "fs/promises";
+import { join as join18 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join17(projectRoot, "openspec");
-  const changesPath = join17(openspecPath, "changes");
-  const legacyArchivePath = join17(openspecPath, "archive");
-  const changesArchivePath = join17(changesPath, "archive");
+  const openspecPath = join18(projectRoot, "openspec");
+  const changesPath = join18(openspecPath, "changes");
+  const legacyArchivePath = join18(openspecPath, "archive");
+  const changesArchivePath = join18(changesPath, "archive");
   return {
     exists: await exists5(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -3485,13 +3830,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join17(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join17(changePath, "tasks.md");
-  const specsPath = join17(changePath, "specs");
+  const changePath = join18(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join18(changePath, "tasks.md");
+  const specsPath = join18(changePath, "specs");
   return {
     changeId,
     exists: await exists5(changePath),
-    hasProposal: await exists5(join17(changePath, "proposal.md")),
+    hasProposal: await exists5(join18(changePath, "proposal.md")),
     hasTasks: await exists5(tasksPath),
     hasSpecs: await exists5(specsPath),
     tasksPath,
@@ -3500,7 +3845,7 @@ async function inspectOpenSpecChange(projectRoot, changeId) {
 }
 async function listDirectories(path, options = {}) {
   try {
-    const entries = await readdir(path, { withFileTypes: true });
+    const entries = await readdir2(path, { withFileTypes: true });
     const excluded = new Set(options.exclude ?? []);
     return entries.filter((entry) => entry.isDirectory() && !excluded.has(entry.name)).map((entry) => entry.name);
   } catch {
@@ -3533,7 +3878,7 @@ async function findExecutable() {
   const command = process.platform === "win32" ? "where.exe" : "which";
   try {
     const { stdout } = await exec(command, ["openspec"]);
-    const first = stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+    const first = stdout.split(/\r?\n/).map((line) => line.trim()).sort((left, right) => executablePreference(left) - executablePreference(right)).find(Boolean);
     if (first) {
       return first;
     }
@@ -3550,6 +3895,12 @@ async function findExecutable() {
     });
   }
 }
+function executablePreference(path) {
+  if (process.platform === "win32" && path.toLowerCase().endsWith(".cmd")) {
+    return 0;
+  }
+  return 1;
+}
 async function readVersion(executablePath) {
   const command = executablePath === "npx openspec" ? "npx" : executablePath;
   const args = executablePath === "npx openspec" ? ["openspec", "--version"] : ["--version"];
@@ -3664,16 +4015,19 @@ function parseCommands(help) {
     "bulk-archive",
     "onboard"
   ];
-  return known.filter((command) => help.includes(command));
+  return known.filter((command) => new RegExp(`\\b${escapeRegExp(command)}\\b`).test(help));
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
 // src/scanner/package.ts
-import { readFile as readFile14, stat as stat9 } from "fs/promises";
-import { join as join18 } from "path";
+import { readFile as readFile15, stat as stat9 } from "fs/promises";
+import { join as join19 } from "path";
 import { parse as parse2 } from "yaml";
 async function readPackageJson(projectRoot) {
   try {
-    return JSON.parse(await readFile14(join18(projectRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile15(join19(projectRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -3739,7 +4093,7 @@ function detectFramework(pkg) {
 }
 async function detectLanguage(projectRoot, pkg) {
   const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
-  if (deps.typescript || await exists6(join18(projectRoot, "tsconfig.json"))) {
+  if (deps.typescript || await exists6(join19(projectRoot, "tsconfig.json"))) {
     return "typescript";
   }
   return "javascript";
@@ -3754,7 +4108,7 @@ async function detectWorkspaces(projectRoot, pkg) {
     return packageWorkspaces;
   }
   try {
-    const workspace = parse2(await readFile14(join18(projectRoot, "pnpm-workspace.yaml"), "utf8"));
+    const workspace = parse2(await readFile15(join19(projectRoot, "pnpm-workspace.yaml"), "utf8"));
     return (workspace?.packages ?? []).map((path) => ({
       name: path,
       path,
@@ -3774,7 +4128,7 @@ async function detectLockManagers(projectRoot) {
   ];
   const found = [];
   for (const [file, manager] of lockFiles) {
-    if (await exists6(join18(projectRoot, file))) {
+    if (await exists6(join19(projectRoot, file))) {
       found.push(manager);
     }
   }
@@ -3799,13 +4153,13 @@ async function exists6(path) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir2, stat as stat10 } from "fs/promises";
-import { join as join19, relative, sep } from "path";
+import { readdir as readdir3, stat as stat10 } from "fs/promises";
+import { join as join20, relative, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join19(projectRoot, candidate);
+    const root = join20(projectRoot, candidate);
     if (!await exists7(root)) {
       continue;
     }
@@ -3830,10 +4184,10 @@ function inferRoutePath(relativePath) {
   return `/${withoutIndex}`.replace(/\/+/g, "/");
 }
 async function listFiles(root) {
-  const entries = await readdir2(root, { withFileTypes: true });
+  const entries = await readdir3(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join19(root, entry.name);
+    const path = join20(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {