@nick848/fet 1.1.9 → 1.1.11

package/dist/cli/index.js

@@ -188,18 +188,18 @@ function toGitNexusState(detection, previous) {
   };
 }
 async function inspectGitNexusGraph(projectRoot, env = process.env) {
-  const relative5 = env.FET_GITNEXUS_GRAPH_PATH?.trim() || DEFAULT_GRAPH_PATH;
-  const graphPath = join5(projectRoot, relative5);
+  const relative6 = env.FET_GITNEXUS_GRAPH_PATH?.trim() || DEFAULT_GRAPH_PATH;
+  const graphPath = join5(projectRoot, relative6);
   try {
     const info = await stat2(graphPath);
     return {
-      graphPath: relative5,
+      graphPath: relative6,
       graphExists: true,
       lastIndexedAt: info.mtime.toISOString()
     };
   } catch {
     return {
-      graphPath: relative5,
+      graphPath: relative6,
       graphExists: false,
       lastIndexedAt: null
     };
@@ -2085,6 +2085,17 @@ function renderFetConfig(scan, language = "zh-CN") {
       uiDisplayContract: {
         enabled: true
       },
+      tdd: {
+        enabled: true,
+        mode: "require_before_apply",
+        whenNoTestScript: "block"
+      },
+      visual: {
+        enabled: true,
+        compareMode: "layout-only",
+        requireBeforeVerify: "when_figma",
+        whenNoCapture: "warn"
+      },
       specLanguage: {
         style: "layered_bilingual",
         canonical: "en",
@@ -2250,6 +2261,267 @@ fet verify --done --change ${changeId}
 `;
 }
 
+// src/tdd/paths.ts
+function tddFetDirRelative(changeId) {
+  return `openspec/changes/${changeId}/.fet`;
+}
+function tddManifestRelativePath(changeId) {
+  return `${tddFetDirRelative(changeId)}/tdd-manifest.yaml`;
+}
+function tddSpecRelativePath(changeId) {
+  return `${tddFetDirRelative(changeId)}/tdd-spec.md`;
+}
+function tddInstructionsRelativePath(changeId) {
+  return `${tddFetDirRelative(changeId)}/tdd-instructions.md`;
+}
+function tddResultsRelativePath(changeId) {
+  return `${tddFetDirRelative(changeId)}/tdd-results.json`;
+}
+
+// src/templates/tdd.ts
+function renderTddInstructions(changeId, manifest, language) {
+  const manifestPath3 = tddManifestRelativePath(changeId);
+  const specPath = tddSpecRelativePath(changeId);
+  const caseList = manifest.cases.map((item) => `- \`${item.id}\`: ${item.title} \u2192 \`${item.testFile}\` (${item.testIds.join(", ")})`).join("\n");
+  if (language === "en") {
+    return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: tdd-instructions
+generatedAt: ${manifest.generatedAt}
+---
+
+# TDD instructions (this change)
+
+Create or update unit tests **before** marking implementation tasks done in \`tasks.md\`.
+
+## Sources
+${manifest.sources.map((s) => `- ${s}`).join("\n")}
+
+## Cases (from ${manifestPath3})
+${caseList}
+
+## Rules
+1. Each case must map to a real test file under the repo test tree.
+2. Tests should fail until implementation lands (red \u2192 green).
+3. Do not edit \`${manifestPath3}\` by hand unless fixing IDs; re-run \`fet tdd --change ${changeId}\` after planning changes.
+4. When tests exist, run \`fet test --change ${changeId}\` before \`fet verify\`.
+
+Human-readable matrix: \`${specPath}\`
+`;
+  }
+  return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: tdd-instructions
+generatedAt: ${manifest.generatedAt}
+---
+
+# TDD \u6307\u4EE4\uFF08\u672C change\uFF09
+
+\u5728\u5C06 \`tasks.md\` \u4E2D\u7684\u4EFB\u52A1\u6807\u4E3A\u5B8C\u6210\u4E4B\u524D\uFF0C\u5148\u521B\u5EFA\u6216\u66F4\u65B0\u5355\u5143\u6D4B\u8BD5\u3002
+
+## \u6765\u6E90
+${manifest.sources.map((s) => `- ${s}`).join("\n")}
+
+## \u7528\u4F8B\uFF08\u89C1 ${manifestPath3}\uFF09
+${caseList}
+
+## \u89C4\u5219
+1. \u6BCF\u4E2A\u7528\u4F8B\u5FC5\u987B\u5BF9\u5E94\u4ED3\u5E93\u5185\u771F\u5B9E\u6D4B\u8BD5\u6587\u4EF6\u3002
+2. \u5B9E\u73B0\u843D\u5730\u524D\u6D4B\u8BD5\u5E94\u5904\u4E8E\u5931\u8D25\uFF08\u7EA2\uFF09\u72B6\u6001\uFF0C\u843D\u5730\u540E\u5E94\u53D8\u7EFF\u3002
+3. \u9664\u975E\u4FEE\u6B63 ID\uFF0C\u4E0D\u8981\u624B\u6539 \`${manifestPath3}\`\uFF1B\u89C4\u5212\u53D8\u66F4\u540E\u8BF7\u91CD\u65B0\u6267\u884C \`fet tdd --change ${changeId}\`\u3002
+4. \u6D4B\u8BD5\u5C31\u7EEA\u540E\u5148 \`fet test --change ${changeId}\`\uFF0C\u518D \`fet verify\`\u3002
+
+\u53EF\u8BFB\u77E9\u9635\u89C1 \`${specPath}\`
+`;
+}
+function renderTddSpec(changeId, manifest, language) {
+  const rows = manifest.cases.map((item) => renderSpecRow(item, language)).join("\n");
+  if (language === "en") {
+    return `---
+schemaVersion: 1
+changeId: ${changeId}
+generatedAt: ${manifest.generatedAt}
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# TDD case matrix
+
+| ID | Scenario | Spec reference | Test file | Required |
+|----|----------|----------------|-----------|----------|
+${rows}
+`;
+  }
+  return `---
+schemaVersion: 1
+changeId: ${changeId}
+generatedAt: ${manifest.generatedAt}
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# TDD \u7528\u4F8B\u77E9\u9635
+
+| ID | \u573A\u666F | Spec \u5F15\u7528 | \u6D4B\u8BD5\u6587\u4EF6 | \u5FC5\u9700 |
+|----|------|-----------|----------|------|
+${rows}
+`;
+}
+function renderSpecRow(item, language) {
+  const required = language === "en" ? item.required ? "yes" : "no" : item.required ? "\u662F" : "\u5426";
+  return `| ${item.id} | ${escapeTable(item.title)} | ${escapeTable(item.specRef)} | \`${item.testFile}\` | ${required} |`;
+}
+function escapeTable(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function renderTddApplyNextSteps(changeId, language) {
+  const manifestPath3 = tddManifestRelativePath(changeId);
+  if (language === "en") {
+    return [
+      `Read ${manifestPath3} and tdd-instructions.md; implement code until fet test passes for this change.`,
+      `Run fet test --change ${changeId} before fet verify.`
+    ];
+  }
+  return [
+    `\u9605\u8BFB ${manifestPath3} \u4E0E tdd-instructions.md\uFF1B\u5B9E\u73B0\u4EE3\u7801\u76F4\u81F3\u672C change \u7684 fet test \u901A\u8FC7\u3002`,
+    `\u5728 fet verify \u4E4B\u524D\u5148\u6267\u884C fet test --change ${changeId}\u3002`
+  ];
+}
+
+// src/visual/paths.ts
+function visualFetDirRelative(changeId) {
+  return `openspec/changes/${changeId}/.fet`;
+}
+function visualManifestRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-manifest.yaml`;
+}
+function visualSpecRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-spec.md`;
+}
+function visualInstructionsRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-instructions.md`;
+}
+function visualCaptureRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-capture.json`;
+}
+function visualResultsRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-results.json`;
+}
+function visualBaselinesDirRelative(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-baselines`;
+}
+function visualPageScreenshotRelative(changeId, pageId) {
+  return `${visualBaselinesDirRelative(changeId)}/${pageId}/implementation.png`;
+}
+
+// src/templates/visual.ts
+function renderVisualInstructions(changeId, manifest, language) {
+  const pages = manifest.pages.map(
+    (page) => `- \`${page.id}\`: ${page.title} \u2192 \`${page.route}\` (ignore: ${page.ignoreSelectors.join(", ") || "none"})`
+  ).join("\n");
+  if (language === "en") {
+    return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: visual-instructions
+generatedAt: ${manifest.generatedAt}
+compareMode: layout-only
+---
+
+# Visual verification (layout-only)
+
+Compare **layout / spacing / shell regions** only. Do **not** pixel-match dynamic API text, list rows, or images.
+
+## Figma references
+${manifest.figmaUrls.map((url) => `- ${url}`).join("\n") || "- (none detected)"}
+
+## Pages
+${pages}
+
+## Default command
+
+\`\`\`sh
+fet visual --change ${changeId}
+\`\`\`
+
+Runs manifest refresh, capture (Playwright + \`--base-url\`), and layout checks in one step.
+
+See \`${visualSpecRelativePath(changeId)}\` for the human-readable matrix.
+`;
+  }
+  return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: visual-instructions
+generatedAt: ${manifest.generatedAt}
+compareMode: layout-only
+---
+
+# \u89C6\u89C9\u9A8C\u6536\uFF08\u4EC5 layout-only\uFF09
+
+\u53EA\u9A8C\u6536 **\u6392\u7248 / \u95F4\u8DDD / \u58F3\u5C42\u533A\u57DF**\uFF0C**\u4E0D\u8981**\u5BF9\u52A8\u6001\u63A5\u53E3\u6587\u6848\u3001\u5217\u8868\u884C\u3001\u56FE\u7247\u505A\u50CF\u7D20\u7EA7\u5BF9\u6BD4\u3002
+
+## Figma \u5F15\u7528
+${manifest.figmaUrls.map((url) => `- ${url}`).join("\n") || "- \uFF08\u672A\u68C0\u6D4B\u5230\uFF09"}
+
+## \u9875\u9762
+${pages}
+
+## \u9ED8\u8BA4\u547D\u4EE4
+
+\`\`\`sh
+fet visual --change ${changeId}
+\`\`\`
+
+\u4E00\u6761\u547D\u4EE4\u5B8C\u6210\u6E05\u5355\u66F4\u65B0\u3001\u622A\u56FE\uFF08Playwright + \`--base-url\`\uFF09\u4E0E\u5E03\u5C40\u68C0\u67E5\u3002
+
+\u8BE6\u89C1 \`${visualSpecRelativePath(changeId)}\`\u3002
+`;
+}
+function renderVisualSpec(changeId, manifest, language) {
+  const rows = manifest.pages.flatMap(
+    (page) => page.checkRegions.map(
+      (region) => `| ${page.id} | ${page.route} | \`${region.selector}\` | ${region.checks.join(", ")} | ${page.ignoreSelectors.join(", ") || "-"} |`
+    )
+  ).join("\n");
+  if (language === "en") {
+    return `---
+changeId: ${changeId}
+compareMode: layout-only
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# Visual case matrix (layout-only)
+
+| Page | Route | Region | Checks | Ignored dynamic |
+|------|-------|--------|--------|-----------------|
+${rows}
+`;
+  }
+  return `---
+changeId: ${changeId}
+compareMode: layout-only
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# \u89C6\u89C9\u7528\u4F8B\u77E9\u9635\uFF08\u4EC5 layout-only\uFF09
+
+| \u9875\u9762 | \u8DEF\u7531 | \u533A\u57DF | \u68C0\u67E5\u9879 | \u5FFD\u7565\u7684\u52A8\u6001\u533A |
+|------|------|------|--------|--------------|
+${rows}
+`;
+}
+function renderVisualVerifyNextSteps(changeId, language) {
+  if (language === "en") {
+    return [`Run fet visual --change ${changeId} before fet verify when this change references Figma.`];
+  }
+  return [`\u82E5\u672C change \u5F15\u7528 Figma\uFF0C\u8BF7\u5728 fet verify \u4E4B\u524D\u6267\u884C fet visual --change ${changeId}\u3002`];
+}
+
 // src/templates/figma-guard.ts
 var FIGMA_URL_PATTERN = /https?:\/\/(?:www\.)?figma\.com\/(?:file|design|proto)\/[^\s)\]"'<>]+/gi;
 function figmaStopHandoffRelativePath(changeId) {
@@ -2889,8 +3161,8 @@ async function exists4(path) {
 }
 
 // src/commands/proxy.ts
-import { readFile as readFile14 } from "fs/promises";
-import { join as join19 } from "path";
+import { readFile as readFile17 } from "fs/promises";
+import { join as join22 } from "path";
 
 // src/figma-guard.ts
 import { readdir as readdir3, readFile as readFile10, stat as stat7 } from "fs/promises";
@@ -3339,6 +3611,259 @@ async function readOptional4(path) {
   }
 }
 
+// src/commands/change-id.ts
+function toKebabId(value) {
+  return value.trim().toLowerCase().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function msg(language, zh, en) {
+  return language === "en" ? en : zh;
+}
+async function resolveChangeId(ctx) {
+  if (ctx.changeId) {
+    return ctx.changeId;
+  }
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  if (global.activeChangeId) {
+    return global.activeChangeId;
+  }
+  const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
+  if (inspection.changes.length === 1 && inspection.changes[0]) {
+    return inspection.changes[0];
+  }
+  throw new FetError({
+    code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+    message: msg(ctx.language, "\u65E0\u6CD5\u786E\u5B9A\u76EE\u6807 change", "Cannot determine which change to use"),
+    details: { openChangeIds: inspection.changes },
+    suggestedCommand: "fet <command> --change <change-id>"
+  });
+}
+async function assertChangeExists(ctx, changeId) {
+  const inspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
+  if (!inspection.exists) {
+    throw new FetError({
+      code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+      message: msg(ctx.language, "\u6307\u5B9A\u7684 change \u4E0D\u5B58\u5728", "The specified change does not exist"),
+      details: { changeId },
+      suggestedCommand: `fet doctor`
+    });
+  }
+}
+
+// src/tdd/config.ts
+import { readFile as readFile12 } from "fs/promises";
+import { join as join18 } from "path";
+import { parseDocument as parseDocument4 } from "yaml";
+var DEFAULT_CONFIG3 = {
+  enabled: true,
+  mode: "require_before_apply",
+  whenNoTestScript: "block"
+};
+async function loadTddConfig(projectRoot) {
+  try {
+    const raw = await readFile12(join18(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument4(raw);
+    const fetNode = doc.get("fet", true);
+    const node = fetNode?.get?.("tdd");
+    if (!node || typeof node.get !== "function") {
+      return DEFAULT_CONFIG3;
+    }
+    const enabled = node.get("enabled");
+    const modeRaw = node.get("mode");
+    const whenNoTestScriptRaw = node.get("whenNoTestScript");
+    return {
+      enabled: enabled === void 0 ? true : Boolean(enabled),
+      mode: parseGateMode(modeRaw),
+      whenNoTestScript: parseWhenNoTestScript(whenNoTestScriptRaw)
+    };
+  } catch {
+    return DEFAULT_CONFIG3;
+  }
+}
+function parseGateMode(value) {
+  if (value === "off" || value === "optional" || value === "require_before_apply") {
+    return value;
+  }
+  return DEFAULT_CONFIG3.mode;
+}
+function parseWhenNoTestScript(value) {
+  if (value === "warn" || value === "skip") {
+    return value;
+  }
+  return DEFAULT_CONFIG3.whenNoTestScript;
+}
+function isTddRequired(config) {
+  return config.enabled && config.mode === "require_before_apply";
+}
+
+// src/tdd/fingerprint.ts
+import { createHash } from "crypto";
+import { readdir as readdir5, readFile as readFile13, stat as stat9 } from "fs/promises";
+import { join as join19, relative as relative4 } from "path";
+async function collectPlanningSources(projectRoot, changeId) {
+  const changeRoot = join19(projectRoot, "openspec", "changes", changeId);
+  const sources = [];
+  const rootFiles = ["proposal.md", "tasks.md", "design.md"];
+  for (const name of rootFiles) {
+    const path = join19(changeRoot, name);
+    if (await exists5(path)) {
+      sources.push(relative4(projectRoot, path).replace(/\\/g, "/"));
+    }
+  }
+  const specsDir = join19(changeRoot, "specs");
+  if (await exists5(specsDir)) {
+    for (const file of await walkFiles(specsDir)) {
+      if (file.endsWith(".md")) {
+        sources.push(relative4(projectRoot, file).replace(/\\/g, "/"));
+      }
+    }
+  }
+  return sources.sort();
+}
+async function computePlanningFingerprint(projectRoot, changeId) {
+  const sources = await collectPlanningSources(projectRoot, changeId);
+  const hash = createHash("sha256");
+  for (const source of sources) {
+    const content = await readFile13(join19(projectRoot, source), "utf8");
+    hash.update(source);
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+async function walkFiles(dir) {
+  const entries = await readdir5(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const path = join19(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkFiles(path));
+    } else if (entry.isFile()) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+async function exists5(path) {
+  try {
+    await stat9(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/tdd/manifest.ts
+import { mkdir as mkdir6, readFile as readFile14, stat as stat10 } from "fs/promises";
+import { dirname as dirname8, join as join20 } from "path";
+import { parse as parse4, stringify as stringify3 } from "yaml";
+function tddManifestPath(projectRoot, changeId) {
+  return join20(projectRoot, tddManifestRelativePath(changeId));
+}
+async function readTddManifest(projectRoot, changeId) {
+  const path = tddManifestPath(projectRoot, changeId);
+  try {
+    await stat10(path);
+  } catch {
+    return null;
+  }
+  const doc = parse4(await readFile14(path, "utf8"));
+  if (!doc || doc.schemaVersion !== 1 || doc.changeId !== changeId) {
+    return null;
+  }
+  return doc;
+}
+async function writeTddManifest(projectRoot, manifest) {
+  const relative6 = tddManifestRelativePath(manifest.changeId);
+  const path = join20(projectRoot, relative6);
+  await mkdir6(dirname8(path), { recursive: true });
+  await atomicWrite(path, stringify3(manifest));
+  return relative6;
+}
+async function writeTddResults(projectRoot, results) {
+  const relative6 = tddResultsRelativePath(results.changeId);
+  const path = join20(projectRoot, relative6);
+  await mkdir6(dirname8(path), { recursive: true });
+  await atomicWrite(path, `${JSON.stringify(results, null, 2)}
+`);
+  return relative6;
+}
+function createTddManifest(input) {
+  return {
+    schemaVersion: 1,
+    changeId: input.changeId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    fetVersion: FET_VERSION,
+    planningFingerprint: input.planningFingerprint,
+    sources: input.sources,
+    cases: input.cases,
+    run: {
+      mode: input.cases.length ? "manifest" : "workspace",
+      fallbackCommand: input.testCommand
+    }
+  };
+}
+
+// src/tdd/gates.ts
+async function assertTddReady(ctx, changeId) {
+  const config = await loadTddConfig(ctx.projectRoot);
+  if (!isTddRequired(config)) {
+    return;
+  }
+  const manifest = await readTddManifest(ctx.projectRoot, changeId);
+  if (!manifest) {
+    throw new FetError({
+      code: "STATE_CORRUPTED" /* StateCorrupted */,
+      message: msg(ctx.language, "\u7F3A\u5C11 TDD \u4EA7\u7269\uFF0C\u65E0\u6CD5\u8FDB\u5165 apply\u3002", "TDD artifacts are missing; cannot run apply."),
+      details: { changeId, expected: tddManifestRelativePath(changeId) },
+      suggestedCommand: `fet tdd --change ${changeId}`,
+      recoverable: true
+    });
+  }
+  const fingerprint2 = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  if (manifest.planningFingerprint !== fingerprint2) {
+    throw new FetError({
+      code: "STATE_CORRUPTED" /* StateCorrupted */,
+      message: msg(
+        ctx.language,
+        "\u89C4\u5212\u4EA7\u7269\u5DF2\u53D8\u66F4\uFF0CTDD \u6E05\u5355\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u751F\u6210\u3002",
+        "Planning artifacts changed; TDD manifest is stale. Regenerate it."
+      ),
+      details: { changeId, manifestFingerprint: manifest.planningFingerprint, currentFingerprint: fingerprint2 },
+      suggestedCommand: `fet tdd --change ${changeId}`,
+      recoverable: true
+    });
+  }
+}
+async function assertTestPassed(ctx, changeId) {
+  const config = await loadTddConfig(ctx.projectRoot);
+  if (!config.enabled || config.mode === "off") {
+    return;
+  }
+  const change = await ctx.stateStore.readChange(changeId);
+  const testRun = change?.testRun;
+  if (testRun?.status === "skipped") {
+    return;
+  }
+  if (testRun?.status === "passed" && await fingerprintMatches(ctx, changeId, testRun)) {
+    return;
+  }
+  throw new FetError({
+    code: "STATE_CORRUPTED" /* StateCorrupted */,
+    message: msg(ctx.language, "\u672C change \u5C1A\u672A\u901A\u8FC7 fet test\u3002", "This change has not passed fet test yet."),
+    details: { changeId, testRun: testRun ?? null },
+    suggestedCommand: `fet test --change ${changeId}`,
+    recoverable: true
+  });
+}
+async function fingerprintMatches(ctx, changeId, testRun) {
+  const current = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  return testRun.planningFingerprint === current;
+}
+function invalidateTestRun(state) {
+  state.testRun = null;
+}
+
 // src/state/project.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
@@ -3366,8 +3891,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir6, readFile as readFile12 } from "fs/promises";
-import { join as join18 } from "path";
+import { mkdir as mkdir7, readFile as readFile15 } from "fs/promises";
+import { join as join21 } from "path";
 
 // src/language.ts
 var DEFAULT_LANGUAGE = "zh-CN";
@@ -3429,6 +3954,10 @@ function createChangeState(fetVersion, changeId, phase) {
       lastSyncedAt: null
     },
     manualVerify: null,
+    tdd: null,
+    testRun: null,
+    visual: null,
+    visualRun: null,
     lastOpenSpecCommand: null,
     warnings: []
   };
@@ -3485,7 +4014,7 @@ var StateStore = class {
   project;
   async readGlobal() {
     try {
-      const value = JSON.parse(await readFile12(this.globalPath(), "utf8"));
+      const value = JSON.parse(await readFile15(this.globalPath(), "utf8"));
       assertGlobalState(value);
       return value;
     } catch (error) {
@@ -3500,13 +4029,13 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir6(join18(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir7(join21(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
   async readChange(changeId) {
     try {
-      const value = JSON.parse(await readFile12(this.changePath(changeId), "utf8"));
+      const value = JSON.parse(await readFile15(this.changePath(changeId), "utf8"));
       assertChangeState(value);
       return value;
     } catch (error) {
@@ -3521,15 +4050,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir6(join18(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir7(join21(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join18(this.projectRoot, "openspec", "fet-state.json");
+    return join21(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join18(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join21(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -3537,11 +4066,11 @@ function isNotFound(error) {
 }
 
 // src/state/tasks.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 async function readCompletedTaskIds(tasksPath) {
   let content;
   try {
-    content = await readFile13(tasksPath, "utf8");
+    content = await readFile16(tasksPath, "utf8");
   } catch {
     return [];
   }
@@ -3675,6 +4204,7 @@ async function applyWorkflowCommand(ctx, args) {
   await withProjectLock(ctx.projectRoot, { command: "apply", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     await assertOpenSpecCommandSupported(ctx, "status", "apply");
     await assertOpenSpecCommandSupported(ctx, "instructions", "apply");
+    await assertTddReady(ctx, changeId);
     runState.graphContext = await buildWorkflowGraphContext(ctx, {
       command: "apply",
       args: ["tasks", "--change", changeId],
@@ -3706,6 +4236,7 @@ async function applyWorkflowCommand(ctx, args) {
     const applyNextSteps = [
       `Read openspec/changes/${changeId}/tasks.md and the instructions output.`,
       "Implement pending tasks and update task checkboxes only after the work is done.",
+      ...renderTddApplyNextSteps(changeId, ctx.language),
       `Run fet verify --change ${changeId}`
     ];
     if (uiContract) {
@@ -3713,6 +4244,7 @@ async function applyWorkflowCommand(ctx, args) {
     }
     if (figmaGuard) {
       applyNextSteps.unshift(...renderFigmaApplyNextSteps(changeId, ctx.language, figmaGuard.mode));
+      applyNextSteps.splice(applyNextSteps.length - 1, 0, ...renderVisualVerifyNextSteps(changeId, ctx.language));
     }
     ctx.output.result({
       ok: true,
@@ -3850,7 +4382,7 @@ async function onboardWorkflowCommand(ctx) {
     summary: "fet onboard loaded local FET/OpenSpec workflow context.",
     nextSteps: [
       inspection.changes.length ? `Open changes: ${inspection.changes.join(", ")}` : "No open changes found. Run fet propose <change-id-or-description> to start one.",
-      "Use fet continue to prepare planning artifacts, fet apply for implementation instructions, fet verify before archive."
+      "Use fet continue to prepare planning artifacts, fet tdd then fet apply for implementation, fet test then fet verify before archive."
     ],
     data: { activeChangeId: state.activeChangeId, openChangeIds: inspection.changes, archivedChangeIds: inspection.archived }
   });
@@ -3895,7 +4427,7 @@ async function artifactWorkflowCommand(ctx, command, args) {
       `Create or update openspec/changes/${changeId}/${resolveOutputPath(status, artifactId)}`,
       "Review the artifact with the user before generating the next planning file.",
       `Run fet passthrough status --change ${changeId}`,
-      status.isComplete ? `Run fet apply --change ${changeId}` : `Run fet continue --change ${changeId} when ready for the next artifact`
+      status.isComplete ? `Run fet tdd --change ${changeId}, then fet apply --change ${changeId}` : `Run fet continue --change ${changeId} when ready for the next artifact`
     ];
     if (uiContract) {
       planningNextSteps.unshift(
@@ -3937,7 +4469,7 @@ async function ensureProposedChange(ctx, args) {
     });
   }
   const input = args.join(" ").trim();
-  const changeId = isKebabId(input) ? input : toKebabId(input);
+  const changeId = isKebabId(input) ? input : toKebabId2(input);
   if (!changeId) {
     throw new FetError({
       code: "INVALID_ARGUMENTS" /* InvalidArguments */,
@@ -4087,7 +4619,7 @@ function resolveOutputPath(status, artifactId) {
 function isKebabId(value) {
   return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 }
-function toKebabId(value) {
+function toKebabId2(value) {
   return value.trim().toLowerCase().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function parseOpenSpecJson(stdout) {
@@ -4124,7 +4656,7 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join19(projectRoot, "CHANGELOG.md");
+  const changelogPath = join22(projectRoot, "CHANGELOG.md");
   const existing = await readOptional5(changelogPath);
   const legacyContentLabel = "\u66F4\u65B0\u5185\u5BB9";
   const block = `updateTime: ${entry.updateTime}
@@ -4137,12 +4669,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join19(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional5(join19(changeRoot, "proposal.md"));
+  const changeRoot = join22(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional5(join22(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional5(join19(changeRoot, "README.md"));
+  const readme = await readOptional5(join22(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -4154,7 +4686,7 @@ function summarizeMarkdown(content) {
 }
 async function readOptional5(path) {
   try {
-    return await readFile14(path, "utf8");
+    return await readFile17(path, "utf8");
   } catch {
     return null;
   }
@@ -4406,115 +4938,1168 @@ function runNpm(command, args, options) {
         stdout: stdout.length ? Buffer.concat(stdout).toString("utf8") : void 0,
         stderr: stderr.length ? Buffer.concat(stderr).toString("utf8") : void 0
       });
-    });
-  });
-}
-function compareVersions(left, right) {
-  const leftVersion = parseVersion(left);
-  const rightVersion = parseVersion(right);
-  for (let index = 0; index < 3; index += 1) {
-    const diff = leftVersion.main[index] - rightVersion.main[index];
-    if (diff !== 0) {
-      return Math.sign(diff);
+    });
+  });
+}
+function compareVersions(left, right) {
+  const leftVersion = parseVersion(left);
+  const rightVersion = parseVersion(right);
+  for (let index = 0; index < 3; index += 1) {
+    const diff = leftVersion.main[index] - rightVersion.main[index];
+    if (diff !== 0) {
+      return Math.sign(diff);
+    }
+  }
+  if (!leftVersion.prerelease.length && rightVersion.prerelease.length) {
+    return 1;
+  }
+  if (leftVersion.prerelease.length && !rightVersion.prerelease.length) {
+    return -1;
+  }
+  const length = Math.max(leftVersion.prerelease.length, rightVersion.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftVersion.prerelease[index];
+    const rightPart = rightVersion.prerelease[index];
+    if (leftPart === void 0) {
+      return -1;
+    }
+    if (rightPart === void 0) {
+      return 1;
+    }
+    const diff = comparePrereleasePart(leftPart, rightPart);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return 0;
+}
+function parseVersion(version) {
+  const [withoutBuild] = version.trim().replace(/^v/i, "").split("+");
+  const [mainValue = "", prereleaseValue = ""] = withoutBuild.split("-");
+  const mainParts = mainValue.split(".").map((part) => Number.parseInt(part, 10));
+  return {
+    main: [
+      Number.isFinite(mainParts[0]) ? mainParts[0] : 0,
+      Number.isFinite(mainParts[1]) ? mainParts[1] : 0,
+      Number.isFinite(mainParts[2]) ? mainParts[2] : 0
+    ],
+    prerelease: prereleaseValue ? prereleaseValue.split(".") : []
+  };
+}
+function comparePrereleasePart(left, right) {
+  const leftNumber = /^\d+$/.test(left) ? Number.parseInt(left, 10) : null;
+  const rightNumber = /^\d+$/.test(right) ? Number.parseInt(right, 10) : null;
+  if (leftNumber !== null && rightNumber !== null) {
+    return Math.sign(leftNumber - rightNumber);
+  }
+  if (leftNumber !== null) {
+    return -1;
+  }
+  if (rightNumber !== null) {
+    return 1;
+  }
+  return left.localeCompare(right);
+}
+
+// src/commands/update.ts
+async function updateCommand(ctx) {
+  const packageName = getFetPackageName();
+  const latestVersion = await resolveLatestFetVersion(packageName);
+  const currentVersion = ctx.fetVersion;
+  if (compareVersions(currentVersion, latestVersion) >= 0) {
+    ctx.output.result({
+      ok: true,
+      command: "update",
+      summary: ctx.language === "en" ? `FET is already up to date (${currentVersion}).` : `FET \u5DF2\u662F\u6700\u65B0\u7248 (${currentVersion})\u3002`,
+      data: {
+        packageName,
+        currentVersion,
+        latestVersion,
+        updated: false
+      }
+    });
+    return;
+  }
+  const install = await performFetUpdate(currentVersion, latestVersion, {
+    cwd: ctx.cwd,
+    json: ctx.json,
+    language: ctx.language,
+    info: (message) => ctx.output.info(message)
+  });
+  ctx.output.result({
+    ok: true,
+    command: "update",
+    summary: ctx.language === "en" ? `FET updated from ${currentVersion} to ${latestVersion}.` : `FET \u5DF2\u4ECE ${currentVersion} \u5347\u7EA7\u5230 ${latestVersion}\u3002`,
+    data: {
+      packageName,
+      currentVersion,
+      latestVersion,
+      updated: true,
+      installCommand: install.installCommand
+    }
+  });
+}
+
+// src/commands/tdd.ts
+import { mkdir as mkdir8 } from "fs/promises";
+import { join as join24 } from "path";
+
+// src/tdd/extract-cases.ts
+import { readFile as readFile18 } from "fs/promises";
+import { join as join23 } from "path";
+async function extractCasesFromChange(projectRoot, changeId, sources) {
+  const cases = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    const content = await readFile18(join23(projectRoot, source), "utf8");
+    if (source.endsWith("tasks.md")) {
+      for (const item of extractTaskCases(content, changeId)) {
+        if (!seen.has(item.id)) {
+          seen.add(item.id);
+          cases.push({ ...item, specRef: `${source} \u2014 ${item.specRef}` });
+        }
+      }
+    }
+    if (source.includes("/specs/") && source.endsWith(".md")) {
+      for (const item of extractScenarioCases(content, changeId, source)) {
+        if (!seen.has(item.id)) {
+          seen.add(item.id);
+          cases.push(item);
+        }
+      }
+    }
+  }
+  if (!cases.length) {
+    cases.push({
+      id: `${changeId}-smoke`,
+      title: "Change smoke test",
+      specRef: sources[0] ?? `openspec/changes/${changeId}/`,
+      testFile: `tests/changes/${changeId}.test.ts`,
+      testIds: [`${changeId}-smoke`],
+      required: true
+    });
+  }
+  return cases;
+}
+function extractTaskCases(content, changeId) {
+  const cases = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const numbered = line.match(/^\s*[-*]\s+\[[ xX]?\]\s+((?:\d+(?:\.\d+)*\.?)?)\s*(.+)$/);
+    if (numbered) {
+      const taskId = numbered[1] || String(cases.length + 1);
+      const title = numbered[2]?.trim() ?? taskId;
+      const id = toKebabId(`${changeId}-task-${taskId}`) || `${changeId}-task-${cases.length + 1}`;
+      cases.push({
+        id,
+        title,
+        specRef: title,
+        testFile: suggestTestFile(changeId, id),
+        testIds: [id],
+        required: true
+      });
+      continue;
+    }
+    const plain = line.match(/^\s*[-*]\s+\[[ xX]?\]\s+(.+)$/);
+    if (plain?.[1]) {
+      const title = plain[1].trim();
+      const id = toKebabId(`${changeId}-${title}`) || `${changeId}-task-${cases.length + 1}`;
+      cases.push({
+        id,
+        title,
+        specRef: title,
+        testFile: suggestTestFile(changeId, id),
+        testIds: [id],
+        required: true
+      });
+    }
+  }
+  return cases;
+}
+function extractScenarioCases(content, changeId, source) {
+  const cases = [];
+  const lines = content.split(/\r?\n/);
+  let currentRequirement = "";
+  for (const line of lines) {
+    const req = line.match(/^#{2,4}\s+Requirement:\s*(.+)$/i);
+    if (req?.[1]) {
+      currentRequirement = req[1].trim();
+    }
+    const scenario = line.match(/^#{2,4}\s+Scenario:\s*(.+)$/i);
+    if (scenario?.[1]) {
+      const title = scenario[1].trim();
+      const id = toKebabId(`${changeId}-${title}`) || `${changeId}-scenario-${cases.length + 1}`;
+      cases.push({
+        id,
+        title,
+        specRef: currentRequirement ? `Requirement: ${currentRequirement} \u2014 Scenario: ${title}` : `Scenario: ${title}`,
+        testFile: suggestTestFile(changeId, id),
+        testIds: [id],
+        required: true
+      });
+    }
+  }
+  if (!cases.length && content.trim()) {
+    const id = `${changeId}-spec-smoke`;
+    cases.push({
+      id,
+      title: `Spec coverage for ${source}`,
+      specRef: source,
+      testFile: suggestTestFile(changeId, id),
+      testIds: [id],
+      required: true
+    });
+  }
+  return cases;
+}
+function suggestTestFile(changeId, caseId) {
+  const segment = caseId.replace(new RegExp(`^${changeId}-?`), "") || "suite";
+  return `tests/changes/${changeId}/${segment}.test.ts`;
+}
+
+// src/commands/tdd.ts
+async function tddCommand(ctx) {
+  await withProjectLock(ctx.projectRoot, { command: "tdd", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    const changeId = await resolveChangeId(ctx);
+    await assertChangeExists(ctx, changeId);
+    const config = await loadTddConfig(ctx.projectRoot);
+    const sources = await collectPlanningSources(ctx.projectRoot, changeId);
+    if (!sources.length) {
+      throw new FetError({
+        code: "INVALID_ARGUMENTS" /* InvalidArguments */,
+        message: msg(ctx.language, "\u672A\u627E\u5230\u53EF\u7528\u4E8E\u751F\u6210 TDD \u7684\u89C4\u5212\u4EA7\u7269\u3002", "No planning artifacts found for TDD generation."),
+        details: { changeId },
+        suggestedCommand: `fet continue --change ${changeId}`,
+        recoverable: true
+      });
+    }
+    const planningFingerprint = await computePlanningFingerprint(ctx.projectRoot, changeId);
+    const cases = await extractCasesFromChange(ctx.projectRoot, changeId, sources);
+    const scan = await ctx.scanner.scan(ctx.projectRoot, {});
+    const testCommand2 = scan.commands.test?.command ?? scan.commands["test:unit"]?.command ?? null;
+    const manifest = createTddManifest({
+      changeId,
+      planningFingerprint,
+      sources,
+      cases,
+      testCommand: testCommand2
+    });
+    const manifestPath3 = await writeTddManifest(ctx.projectRoot, manifest);
+    const fetDir = join24(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+    await mkdir8(fetDir, { recursive: true });
+    const instructionsPath = tddInstructionsRelativePath(changeId);
+    const specPath = tddSpecRelativePath(changeId);
+    await atomicWrite(join24(ctx.projectRoot, instructionsPath), renderTddInstructions(changeId, manifest, ctx.language));
+    await atomicWrite(join24(ctx.projectRoot, specPath), renderTddSpec(changeId, manifest, ctx.language));
+    const changeState = await ctx.stateStore.getOrCreateChange(changeId, "implement");
+    changeState.tdd = {
+      status: "ready",
+      generatedAt: manifest.generatedAt,
+      planningFingerprint,
+      manifestPath: manifestPath3
+    };
+    invalidateTestRun(changeState);
+    changeState.currentPhase = "implement";
+    changeState.phases.implement = { status: "in_progress", updatedAt: manifest.generatedAt };
+    await ctx.stateStore.writeChange(changeState);
+    const global = await ctx.stateStore.getOrCreateGlobal();
+    global.activeChangeId = changeId;
+    await ctx.stateStore.writeGlobal(global);
+    ctx.output.result({
+      ok: true,
+      command: "tdd",
+      summary: msg(
+        ctx.language,
+        `\u5DF2\u4E3A change "${changeId}" \u751F\u6210 TDD \u4EA7\u7269\uFF08${cases.length} \u4E2A\u7528\u4F8B\uFF09\u3002`,
+        `Generated TDD artifacts for change "${changeId}" (${cases.length} case(s)).`
+      ),
+      warnings: !testCommand2 && config.whenNoTestScript !== "skip" ? [
+        msg(
+          ctx.language,
+          "\u9879\u76EE\u672A\u914D\u7F6E test \u811A\u672C\uFF1B\u5B9E\u73B0\u540E\u53EF\u80FD\u65E0\u6CD5\u8FD0\u884C fet test\u3002",
+          "No test script found in the project; fet test may fail after implementation."
+        )
+      ] : void 0,
+      nextSteps: [
+        msg(ctx.language, `\u9605\u8BFB ${instructionsPath}\uFF0C\u7531 IDE/AI \u521B\u5EFA/\u66F4\u65B0\u6E05\u5355\u4E2D\u7684\u6D4B\u8BD5\u6587\u4EF6\u3002`, `Read ${instructionsPath} and create/update test files listed in the manifest.`),
+        msg(ctx.language, `\u5B8C\u6210\u540E\u8FD0\u884C fet apply --change ${changeId}`, `Then run fet apply --change ${changeId}`),
+        msg(ctx.language, `\u5B9E\u73B0\u540E\u8FD0\u884C fet test --change ${changeId}`, `After implementation, run fet test --change ${changeId}`)
+      ],
+      data: {
+        changeId,
+        manifestPath: manifestPath3,
+        specPath,
+        instructionsPath,
+        caseCount: cases.length,
+        planningFingerprint,
+        testCommand: testCommand2
+      }
+    });
+  });
+}
+
+// src/commands/run-script.ts
+import { spawn as spawn2 } from "child_process";
+async function runShellCommand(commandLine, cwd, extraArgs = []) {
+  const parts = splitCommandLine(commandLine);
+  const executable = parts[0];
+  if (!executable) {
+    throw new Error("Empty command");
+  }
+  const args = [...parts.slice(1), ...extraArgs];
+  return runProcess(executable, args, cwd, commandLine);
+}
+async function runProcess(executable, args, cwd, label = executable) {
+  return new Promise((resolve2) => {
+    const stdout = [];
+    const stderr = [];
+    const child = spawn2(executable, args, {
+      cwd,
+      shell: process.platform === "win32",
+      env: process.env
+    });
+    child.stdout?.on("data", (chunk) => stdout.push(chunk));
+    child.stderr?.on("data", (chunk) => stderr.push(chunk));
+    child.on("close", (code, signal) => {
+      resolve2({
+        command: label,
+        args,
+        exitCode: code ?? 1,
+        signal,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8")
+      });
+    });
+    child.on("error", () => {
+      resolve2({
+        command: label,
+        args,
+        exitCode: 1,
+        signal: null,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8")
+      });
+    });
+  });
+}
+function splitCommandLine(commandLine) {
+  return commandLine.trim().split(/\s+/);
+}
+
+// src/commands/test.ts
+async function testCommand(ctx, options) {
+  await withProjectLock(ctx.projectRoot, { command: "test", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    const changeId = await resolveChangeId(ctx);
+    await assertChangeExists(ctx, changeId);
+    const config = await loadTddConfig(ctx.projectRoot);
+    const manifest = await readTddManifest(ctx.projectRoot, changeId);
+    if (!manifest) {
+      throw new FetError({
+        code: "STATE_CORRUPTED" /* StateCorrupted */,
+        message: msg(ctx.language, "\u7F3A\u5C11 TDD \u6E05\u5355\uFF0C\u65E0\u6CD5\u8FD0\u884C fet test\u3002", "TDD manifest is missing; cannot run fet test."),
+        details: { changeId },
+        suggestedCommand: `fet tdd --change ${changeId}`,
+        recoverable: true
+      });
+    }
+    const planningFingerprint = await computePlanningFingerprint(ctx.projectRoot, changeId);
+    if (manifest.planningFingerprint !== planningFingerprint) {
+      throw new FetError({
+        code: "STATE_CORRUPTED" /* StateCorrupted */,
+        message: msg(ctx.language, "TDD \u6E05\u5355\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u8FD0\u884C fet tdd\u3002", "TDD manifest is stale; rerun fet tdd."),
+        details: { changeId },
+        suggestedCommand: `fet tdd --change ${changeId}`,
+        recoverable: true
+      });
+    }
+    const scan = await ctx.scanner.scan(ctx.projectRoot, {});
+    const testCommand2 = manifest.run.fallbackCommand ?? scan.commands.test?.command ?? scan.commands["test:unit"]?.command ?? null;
+    if (!testCommand2) {
+      if (config.whenNoTestScript === "skip") {
+        await recordSkippedTestRun(ctx, changeId, planningFingerprint, manifestPath(changeId));
+        ctx.output.result({
+          ok: true,
+          command: "test",
+          summary: msg(ctx.language, "\u672A\u914D\u7F6E test \u811A\u672C\uFF0C\u5DF2\u8DF3\u8FC7 fet test\u3002", "No test script configured; fet test skipped."),
+          warnings: [msg(ctx.language, "\u8DF3\u8FC7\u540E\u53EF\u76F4\u63A5 fet verify\uFF08\u82E5\u9879\u76EE\u7B56\u7565\u5141\u8BB8\uFF09\u3002", "You may proceed to fet verify if your policy allows.")],
+          data: { changeId, skipped: true }
+        });
+        return;
+      }
+      throw new FetError({
+        code: "CONFIG_INVALID" /* ConfigInvalid */,
+        message: msg(ctx.language, "\u672A\u627E\u5230 test \u811A\u672C\uFF0C\u65E0\u6CD5\u6267\u884C fet test\u3002", "No test script found; cannot run fet test."),
+        suggestedCommand: "\u5728 package.json \u4E2D\u6DFB\u52A0 scripts.test \u6216\u914D\u7F6E openspec/config.yaml fet.tdd.whenNoTestScript: skip"
+      });
+    }
+    const extraArgs = buildTestArgs(manifest);
+    const planLabel = `${testCommand2}${extraArgs.length ? ` ${extraArgs.join(" ")}` : ""}`;
+    if (options.plan) {
+      ctx.output.result({
+        ok: true,
+        command: "test",
+        summary: msg(ctx.language, "\u5DF2\u751F\u6210 fet test \u6267\u884C\u8BA1\u5212\u3002", "Generated fet test execution plan."),
+        data: {
+          changeId,
+          command: planLabel,
+          cases: manifest.cases.map((item) => ({ id: item.id, testFile: item.testFile }))
+        },
+        nextSteps: [`fet test --change ${changeId}`]
+      });
+      return;
+    }
+    const result = await runShellCommand(testCommand2, ctx.projectRoot, extraArgs);
+    const caseResults = manifest.cases.map((item) => ({
+      id: item.id,
+      status: result.exitCode === 0 ? "passed" : "failed",
+      exitCode: result.exitCode,
+      message: result.exitCode === 0 ? void 0 : msg(ctx.language, "\u6D4B\u8BD5\u547D\u4EE4\u672A\u901A\u8FC7", "Test command failed")
+    }));
+    const resultsDoc = {
+      schemaVersion: 1,
+      changeId,
+      ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+      command: planLabel,
+      exitCode: result.exitCode,
+      planningFingerprint,
+      cases: caseResults
+    };
+    const resultsPath = await writeTddResults(ctx.projectRoot, resultsDoc);
+    const changeState = await ctx.stateStore.getOrCreateChange(changeId, "implement");
+    changeState.testRun = {
+      status: result.exitCode === 0 ? "passed" : "failed",
+      ranAt: resultsDoc.ranAt,
+      command: planLabel,
+      exitCode: result.exitCode,
+      planningFingerprint,
+      manifestPath: manifestPath(changeId),
+      resultsPath
+    };
+    await ctx.stateStore.writeChange(changeState);
+    if (result.exitCode !== 0) {
+      throw new FetError({
+        code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+        message: msg(ctx.language, "fet test \u672A\u901A\u8FC7\u3002", "fet test failed."),
+        details: {
+          changeId,
+          exitCode: result.exitCode,
+          command: planLabel,
+          resultsPath: tddResultsRelativePath(changeId),
+          stderr: truncate(result.stderr)
+        },
+        suggestedCommand: `fet test --change ${changeId}`,
+        recoverable: true
+      });
+    }
+    ctx.output.result({
+      ok: true,
+      command: "test",
+      summary: msg(ctx.language, `change "${changeId}" \u7684\u5355\u6D4B\u5DF2\u901A\u8FC7\u3002`, `Unit tests passed for change "${changeId}".`),
+      nextSteps: [`fet verify --change ${changeId}`],
+      data: {
+        changeId,
+        command: planLabel,
+        resultsPath: tddResultsRelativePath(changeId),
+        cases: caseResults
+      }
+    });
+  });
+}
+function manifestPath(changeId) {
+  return tddManifestRelativePath(changeId);
+}
+function buildTestArgs(manifest) {
+  if (!manifest || manifest.run.mode === "workspace") {
+    return [];
+  }
+  const files = [...new Set(manifest.cases.map((item) => item.testFile).filter(Boolean))];
+  return files.length ? ["--", ...files] : [];
+}
+async function recordSkippedTestRun(ctx, changeId, planningFingerprint, manifestPathValue) {
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "implement");
+  changeState.testRun = {
+    status: "skipped",
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    command: "(skipped)",
+    exitCode: 0,
+    planningFingerprint,
+    manifestPath: manifestPathValue,
+    resultsPath: null
+  };
+  await ctx.stateStore.writeChange(changeState);
+}
+function truncate(value, max = 2e3) {
+  return value.length > max ? `${value.slice(0, max)}\u2026` : value;
+}
+
+// src/commands/visual.ts
+import { mkdir as mkdir10 } from "fs/promises";
+import { join as join28 } from "path";
+
+// src/visual/config.ts
+import { readFile as readFile19 } from "fs/promises";
+import { join as join25 } from "path";
+import { parseDocument as parseDocument5 } from "yaml";
+var DEFAULT_CONFIG4 = {
+  enabled: true,
+  compareMode: "layout-only",
+  requireBeforeVerify: "when_figma",
+  whenNoCapture: "warn"
+};
+async function loadVisualConfig(projectRoot) {
+  try {
+    const raw = await readFile19(join25(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument5(raw);
+    const fetNode = doc.get("fet", true);
+    const node = fetNode?.get?.("visual");
+    if (!node || typeof node.get !== "function") {
+      return DEFAULT_CONFIG4;
+    }
+    const enabled = node.get("enabled");
+    const requireBeforeVerify = node.get("requireBeforeVerify");
+    const whenNoCapture = node.get("whenNoCapture");
+    return {
+      enabled: enabled === void 0 ? true : Boolean(enabled),
+      compareMode: "layout-only",
+      requireBeforeVerify: parseRequireBeforeVerify(requireBeforeVerify),
+      whenNoCapture: parseWhenNoCapture(whenNoCapture)
+    };
+  } catch {
+    return DEFAULT_CONFIG4;
+  }
+}
+function parseRequireBeforeVerify(value) {
+  if (value === "off" || value === "always" || value === "when_figma") {
+    return value;
+  }
+  return DEFAULT_CONFIG4.requireBeforeVerify;
+}
+function parseWhenNoCapture(value) {
+  if (value === "block" || value === "warn" || value === "skip") {
+    return value;
+  }
+  return DEFAULT_CONFIG4.whenNoCapture;
+}
+function isVisualRequiredForVerify(config, hasFigma) {
+  if (!config.enabled) {
+    return false;
+  }
+  if (config.requireBeforeVerify === "off") {
+    return false;
+  }
+  if (config.requireBeforeVerify === "always") {
+    return true;
+  }
+  return hasFigma;
+}
+
+// src/visual/playwright.ts
+import { createRequire } from "module";
+import { dirname as dirname9, join as join26 } from "path";
+import { pathToFileURL } from "url";
+async function resolvePlaywright(projectRoot) {
+  const require2 = createRequire(join26(projectRoot, "package.json"));
+  const candidates = ["playwright", "@playwright/test"];
+  for (const name of candidates) {
+    try {
+      const resolved = require2.resolve(name);
+      const mod = await import(pathToFileURL(resolved).href);
+      if (mod?.chromium) {
+        return mod;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+async function capturePagesWithPlaywright(projectRoot, manifest, baseUrl) {
+  const playwright = await resolvePlaywright(projectRoot);
+  if (!playwright) {
+    return [];
+  }
+  const browser = await playwright.chromium.launch({ headless: true });
+  const results = [];
+  try {
+    for (const page of manifest.pages) {
+      results.push(await captureSinglePage(projectRoot, browser, manifest.changeId, page, baseUrl));
+    }
+  } finally {
+    await browser.close();
+  }
+  return results;
+}
+async function captureSinglePage(projectRoot, browser, changeId, pageDef, baseUrl) {
+  const { mkdir: mkdir15 } = await import("fs/promises");
+  const { join: joinPath } = await import("path");
+  const screenshotRelative = visualPageScreenshotRelative(changeId, pageDef.id);
+  const screenshotAbsolute = joinPath(projectRoot, screenshotRelative);
+  await mkdir15(dirname9(screenshotAbsolute), { recursive: true });
+  const url = new URL(pageDef.route, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
+  const pwPage = await browser.newPage();
+  try {
+    await pwPage.setViewportSize(pageDef.viewport);
+    await pwPage.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
+    await pwPage.screenshot({ path: screenshotAbsolute, fullPage: true });
+    const regions = await extractRegions(pwPage, pageDef);
+    return {
+      pageId: pageDef.id,
+      route: pageDef.route,
+      screenshotPath: screenshotRelative,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      regions
+    };
+  } catch {
+    return {
+      pageId: pageDef.id,
+      route: pageDef.route,
+      screenshotPath: null,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      regions: []
+    };
+  } finally {
+    await pwPage.close();
+  }
+}
+var EXTRACT_REGIONS_SCRIPT = `
+(inputSelectors) => {
+  const layouts = [];
+  for (const selector of inputSelectors) {
+    const element = document.querySelector(selector);
+    if (!element) {
+      layouts.push({
+        selector,
+        exists: false,
+        visible: false,
+        width: 0,
+        height: 0,
+        display: "none",
+        position: "static"
+      });
+      continue;
+    }
+    const style = window.getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    layouts.push({
+      selector,
+      exists: true,
+      visible: style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0,
+      width: rect.width,
+      height: rect.height,
+      display: style.display,
+      position: style.position
+    });
+  }
+  return layouts;
+}
+`;
+async function extractRegions(page, pageDef) {
+  const selectors = pageDef.checkRegions.map((region) => region.selector);
+  return page.evaluate(EXTRACT_REGIONS_SCRIPT, selectors);
+}
+
+// src/visual/manifest.ts
+import { mkdir as mkdir9, readFile as readFile20, stat as stat11 } from "fs/promises";
+import { dirname as dirname10, join as join27 } from "path";
+import { parse as parse5, stringify as stringify4 } from "yaml";
+function visualManifestPath(projectRoot, changeId) {
+  return join27(projectRoot, visualManifestRelativePath(changeId));
+}
+async function readVisualManifest(projectRoot, changeId) {
+  const path = visualManifestPath(projectRoot, changeId);
+  try {
+    await stat11(path);
+  } catch {
+    return null;
+  }
+  const doc = parse5(await readFile20(path, "utf8"));
+  if (!doc || doc.schemaVersion !== 1 || doc.changeId !== changeId) {
+    return null;
+  }
+  return doc;
+}
+async function writeVisualManifest(projectRoot, manifest) {
+  const relative6 = visualManifestRelativePath(manifest.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, stringify4(manifest));
+  return relative6;
+}
+async function readVisualCapture(projectRoot, changeId) {
+  const path = join27(projectRoot, visualCaptureRelativePath(changeId));
+  try {
+    const doc = JSON.parse(await readFile20(path, "utf8"));
+    if (doc?.schemaVersion === 1 && doc.changeId === changeId) {
+      return doc;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function writeVisualCapture(projectRoot, capture) {
+  const relative6 = visualCaptureRelativePath(capture.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, `${JSON.stringify(capture, null, 2)}
+`);
+  return relative6;
+}
+async function writeVisualResults(projectRoot, results) {
+  const relative6 = visualResultsRelativePath(results.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, `${JSON.stringify(results, null, 2)}
+`);
+  return relative6;
+}
+function createVisualManifest(input) {
+  return {
+    schemaVersion: 1,
+    changeId: input.changeId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    fetVersion: FET_VERSION,
+    planningFingerprint: input.planningFingerprint,
+    compareMode: "layout-only",
+    figmaUrls: input.figmaUrls,
+    figmaSources: input.figmaSources,
+    run: { baseUrl: input.baseUrl },
+    pages: input.pages
+  };
+}
+
+// src/visual/capture.ts
+async function runVisualCapture(options) {
+  const warnings = [];
+  const baseUrl = options.baseUrl ?? options.manifest.run.baseUrl;
+  if (!baseUrl) {
+    return handleMissingBaseUrl(options.config, options.language, warnings);
+  }
+  const playwright = await resolvePlaywright(options.projectRoot);
+  if (!playwright) {
+    return handleMissingPlaywright(options.config, options.language, warnings);
+  }
+  const pages = await capturePagesWithPlaywright(options.projectRoot, options.manifest, baseUrl);
+  const failedPages = pages.filter((page) => !page.screenshotPath);
+  const capture = {
+    schemaVersion: 1,
+    changeId: options.changeId,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    baseUrl,
+    pages
+  };
+  await writeVisualCapture(options.projectRoot, capture);
+  if (failedPages.length) {
+    return {
+      status: "failed",
+      capture,
+      warnings,
+      message: options.language === "en" ? `Capture failed for ${failedPages.length} page(s). Check dev server and routes.` : `${failedPages.length} \u4E2A\u9875\u9762\u622A\u56FE\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5 dev \u670D\u52A1\u4E0E\u8DEF\u7531\u3002`
+    };
+  }
+  return { status: "passed", capture, warnings };
+}
+function handleMissingBaseUrl(config, language, warnings) {
+  const message = language === "en" ? "No base URL for capture. Pass --base-url or set manifest.run.baseUrl." : "\u672A\u914D\u7F6E base URL\uFF0C\u65E0\u6CD5\u622A\u56FE\u3002\u8BF7\u4F7F\u7528 --base-url \u6216\u5728 manifest \u4E2D\u8BBE\u7F6E run.baseUrl\u3002";
+  warnings.push(message);
+  if (config.whenNoCapture === "block") {
+    return { status: "failed", capture: null, warnings, message };
+  }
+  return { status: "skipped", capture: null, warnings, message };
+}
+function handleMissingPlaywright(config, language, warnings) {
+  const message = language === "en" ? "Playwright not found in project. Install playwright or use --check-layout-only after manual capture." : "\u9879\u76EE\u672A\u5B89\u88C5 Playwright\u3002\u8BF7\u5B89\u88C5 playwright\uFF0C\u6216\u5728\u624B\u52A8\u622A\u56FE\u540E\u4F7F\u7528 --check-layout-only\u3002";
+  warnings.push(message);
+  if (config.whenNoCapture === "block") {
+    return { status: "failed", capture: null, warnings, message };
+  }
+  return { status: "skipped", capture: null, warnings, message };
+}
+
+// src/visual/check-layout.ts
+function runLayoutCheck(manifest, capture, language, options) {
+  const regions = [];
+  if (!capture && options?.allowManifestOnly) {
+    return runManifestOnlyValidation(manifest, language);
+  }
+  if (capture?.pages.length) {
+    for (const page of manifest.pages) {
+      const captured = capture.pages.find((item) => item.pageId === page.id);
+      for (const region of page.checkRegions) {
+        const layout = captured?.regions.find((item) => item.selector === region.selector);
+        const result = evaluateRegion(page.id, region.selector, region.checks, layout, language);
+        regions.push(result);
+      }
+    }
+  } else {
+    for (const page of manifest.pages) {
+      if (!page.checkRegions.length) {
+        regions.push({
+          pageId: page.id,
+          selector: "(page)",
+          status: "failed",
+          message: language === "en" ? "No checkRegions defined" : "\u672A\u5B9A\u4E49 checkRegions"
+        });
+        continue;
+      }
+      for (const region of page.checkRegions) {
+        regions.push({
+          pageId: page.id,
+          selector: region.selector,
+          status: capture ? "failed" : "skipped",
+          message: language === "en" ? "No capture data; run capture with --base-url or install Playwright" : "\u65E0\u622A\u56FE\u6570\u636E\uFF1B\u8BF7\u5E26 --base-url \u8FD0\u884C capture \u6216\u5B89\u88C5 Playwright"
+        });
+      }
+    }
+  }
+  const failed = regions.filter((item) => item.status === "failed");
+  if (failed.length) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? `Layout check failed for ${failed.length} region(s).` : `${failed.length} \u4E2A\u533A\u57DF\u7684\u5E03\u5C40\u68C0\u67E5\u672A\u901A\u8FC7\u3002`
+    };
+  }
+  const skipped = regions.filter((item) => item.status === "skipped");
+  if (skipped.length && !capture) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? "Layout check requires capture data when regions are defined." : "\u5DF2\u5B9A\u4E49\u68C0\u67E5\u533A\u57DF\u65F6\u9700\u8981 capture \u6570\u636E\u624D\u80FD\u5B8C\u6210\u5E03\u5C40\u9A8C\u6536\u3002"
+    };
+  }
+  return { status: "passed", regions };
+}
+function runManifestOnlyValidation(manifest, language) {
+  const regions = [];
+  if (!manifest.pages.length) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? "Visual manifest has no pages." : "\u89C6\u89C9\u6E05\u5355\u4E2D\u6CA1\u6709\u4EFB\u4F55\u9875\u9762\u3002"
+    };
+  }
+  for (const page of manifest.pages) {
+    for (const region of page.checkRegions) {
+      regions.push({
+        pageId: page.id,
+        selector: region.selector,
+        status: "skipped",
+        message: language === "en" ? "Manifest-only mode (layout-only, no pixel/content compare)" : "\u4EC5 manifest \u6821\u9A8C\uFF08layout-only\uFF0C\u4E0D\u5BF9\u6BD4\u50CF\u7D20/\u52A8\u6001\u5185\u5BB9\uFF09"
+      });
     }
   }
-  if (!leftVersion.prerelease.length && rightVersion.prerelease.length) {
-    return 1;
-  }
-  if (leftVersion.prerelease.length && !rightVersion.prerelease.length) {
-    return -1;
+  return {
+    status: "passed",
+    regions,
+    message: language === "en" ? "Manifest validated; capture skipped \u2014 layout-only checklist recorded." : "\u6E05\u5355\u6821\u9A8C\u901A\u8FC7\uFF1B\u5DF2\u8DF3\u8FC7\u622A\u56FE \u2014 \u5DF2\u8BB0\u5F55 layout-only \u68C0\u67E5\u9879\u3002"
+  };
+}
+function evaluateRegion(pageId, selector, checks, layout, language) {
+  if (!layout) {
+    return {
+      pageId,
+      selector,
+      status: "failed",
+      message: language === "en" ? "Region not found in capture" : "capture \u4E2D\u672A\u627E\u5230\u8BE5\u533A\u57DF"
+    };
   }
-  const length = Math.max(leftVersion.prerelease.length, rightVersion.prerelease.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftPart = leftVersion.prerelease[index];
-    const rightPart = rightVersion.prerelease[index];
-    if (leftPart === void 0) {
-      return -1;
+  for (const check of checks) {
+    if (check === "exists" && !layout.exists) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Missing element" : "\u5143\u7D20\u4E0D\u5B58\u5728" };
     }
-    if (rightPart === void 0) {
-      return 1;
+    if (check === "visible" && !layout.visible) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Not visible" : "\u4E0D\u53EF\u89C1" };
     }
-    const diff = comparePrereleasePart(leftPart, rightPart);
-    if (diff !== 0) {
-      return diff;
+    if (check === "has-box" && (layout.width <= 0 || layout.height <= 0)) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Zero layout box" : "\u5E03\u5C40\u5C3A\u5BF8\u4E3A 0" };
     }
   }
-  return 0;
+  return { pageId, selector, status: "passed" };
 }
-function parseVersion(version) {
-  const [withoutBuild] = version.trim().replace(/^v/i, "").split("+");
-  const [mainValue = "", prereleaseValue = ""] = withoutBuild.split("-");
-  const mainParts = mainValue.split(".").map((part) => Number.parseInt(part, 10));
+function buildVisualResults(input) {
   return {
-    main: [
-      Number.isFinite(mainParts[0]) ? mainParts[0] : 0,
-      Number.isFinite(mainParts[1]) ? mainParts[1] : 0,
-      Number.isFinite(mainParts[2]) ? mainParts[2] : 0
-    ],
-    prerelease: prereleaseValue ? prereleaseValue.split(".") : []
+    schemaVersion: 1,
+    changeId: input.changeId,
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint: input.planningFingerprint,
+    steps: input.steps,
+    captureStatus: input.captureStatus,
+    layoutStatus: input.layoutStatus,
+    regions: input.regions
   };
 }
-function comparePrereleasePart(left, right) {
-  const leftNumber = /^\d+$/.test(left) ? Number.parseInt(left, 10) : null;
-  const rightNumber = /^\d+$/.test(right) ? Number.parseInt(right, 10) : null;
-  if (leftNumber !== null && rightNumber !== null) {
-    return Math.sign(leftNumber - rightNumber);
-  }
-  if (leftNumber !== null) {
-    return -1;
+
+// src/visual/generate.ts
+var DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+async function buildVisualManifestPages(projectRoot, changeId, figmaUrls) {
+  if (figmaUrls.length) {
+    return [
+      {
+        id: `${changeId}-main`,
+        title: "Main UI screen",
+        route: "/",
+        viewport: DEFAULT_VIEWPORT,
+        dataMode: "mock",
+        mockFixture: null,
+        ignoreSelectors: [".dynamic-list", "[data-dynamic]", "[data-testid='dynamic-content']"],
+        checkRegions: [
+          { selector: "header, [role='banner'], .app-header", checks: ["exists", "visible", "has-box"] },
+          { selector: "main, [role='main'], .app-main", checks: ["exists", "visible", "has-box"] },
+          { selector: "nav, [role='navigation'], .app-nav", checks: ["exists", "has-box"] }
+        ]
+      }
+    ];
   }
-  if (rightNumber !== null) {
-    return 1;
+  return [
+    {
+      id: `${changeId}-shell`,
+      title: "Application shell",
+      route: "/",
+      viewport: DEFAULT_VIEWPORT,
+      dataMode: "mock",
+      mockFixture: null,
+      ignoreSelectors: [".dynamic-list", "[data-dynamic]"],
+      checkRegions: [{ selector: "body", checks: ["exists", "visible", "has-box"] }]
+    }
+  ];
+}
+async function generateVisualManifestInput(projectRoot, changeId, baseUrl) {
+  const { urls, sources } = await collectFigmaUrlsFromChange(projectRoot, changeId);
+  const planningFingerprint = await computePlanningFingerprint(projectRoot, changeId);
+  const pages = await buildVisualManifestPages(projectRoot, changeId, urls);
+  return {
+    planningFingerprint,
+    figmaUrls: urls,
+    figmaSources: sources,
+    pages
+  };
+}
+function mergeBaseUrl(manifest, baseUrl) {
+  if (!baseUrl) {
+    return manifest;
   }
-  return left.localeCompare(right);
+  return {
+    ...manifest,
+    run: { baseUrl }
+  };
 }
 
-// src/commands/update.ts
-async function updateCommand(ctx) {
-  const packageName = getFetPackageName();
-  const latestVersion = await resolveLatestFetVersion(packageName);
-  const currentVersion = ctx.fetVersion;
-  if (compareVersions(currentVersion, latestVersion) >= 0) {
-    ctx.output.result({
-      ok: true,
-      command: "update",
-      summary: ctx.language === "en" ? `FET is already up to date (${currentVersion}).` : `FET \u5DF2\u662F\u6700\u65B0\u7248 (${currentVersion})\u3002`,
-      data: {
-        packageName,
-        currentVersion,
-        latestVersion,
-        updated: false
-      }
-    });
+// src/visual/gates.ts
+async function assertVisualPassed(ctx, changeId) {
+  const config = await loadVisualConfig(ctx.projectRoot);
+  const { urls } = await collectFigmaUrlsFromChange(ctx.projectRoot, changeId);
+  if (!isVisualRequiredForVerify(config, urls.length > 0)) {
     return;
   }
-  const install = await performFetUpdate(currentVersion, latestVersion, {
-    cwd: ctx.cwd,
-    json: ctx.json,
-    language: ctx.language,
-    info: (message) => ctx.output.info(message)
+  const change = await ctx.stateStore.readChange(changeId);
+  const visualRun = change?.visualRun;
+  if (visualRun?.status === "skipped") {
+    return;
+  }
+  if (visualRun?.status === "passed" && await fingerprintMatches2(ctx, changeId, visualRun)) {
+    return;
+  }
+  throw new FetError({
+    code: "STATE_CORRUPTED" /* StateCorrupted */,
+    message: msg(ctx.language, "\u672C change \u5C1A\u672A\u901A\u8FC7 fet visual\u3002", "This change has not passed fet visual yet."),
+    details: { changeId, visualRun: visualRun ?? null, figmaUrlCount: urls.length },
+    suggestedCommand: `fet visual --change ${changeId}`,
+    recoverable: true
   });
-  ctx.output.result({
-    ok: true,
-    command: "update",
-    summary: ctx.language === "en" ? `FET updated from ${currentVersion} to ${latestVersion}.` : `FET \u5DF2\u4ECE ${currentVersion} \u5347\u7EA7\u5230 ${latestVersion}\u3002`,
-    data: {
-      packageName,
-      currentVersion,
-      latestVersion,
-      updated: true,
-      installCommand: install.installCommand
+}
+async function fingerprintMatches2(ctx, changeId, visualRun) {
+  const current = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  return visualRun.planningFingerprint === current;
+}
+function invalidateVisualRun(state) {
+  state.visualRun = null;
+}
+function manifestPath2(changeId) {
+  return visualManifestRelativePath(changeId);
+}
+
+// src/commands/visual.ts
+async function visualCommand(ctx, options) {
+  await withProjectLock(ctx.projectRoot, { command: "visual", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    const changeId = await resolveChangeId(ctx);
+    await assertChangeExists(ctx, changeId);
+    const config = await loadVisualConfig(ctx.projectRoot);
+    const steps = [];
+    const warnings = [];
+    const manifest = await ensureManifest(ctx, changeId, options.baseUrl ?? null);
+    steps.push("manifest");
+    if (options.plan) {
+      ctx.output.result({
+        ok: true,
+        command: "visual",
+        summary: msg(ctx.language, "\u5DF2\u751F\u6210 fet visual \u6267\u884C\u8BA1\u5212\u3002", "Generated fet visual execution plan."),
+        data: {
+          changeId,
+          compareMode: manifest.compareMode,
+          steps: options.checkLayoutOnly ? ["manifest", "check-layout"] : options.captureOnly ? ["manifest", "capture"] : ["manifest", "capture", "check-layout"],
+          baseUrl: options.baseUrl ?? manifest.run.baseUrl,
+          pages: manifest.pages.map((page) => ({ id: page.id, route: page.route }))
+        },
+        nextSteps: [`fet visual --change ${changeId}${options.baseUrl ? ` --base-url ${options.baseUrl}` : ""}`]
+      });
+      return;
+    }
+    let captureStatus = "skipped";
+    let captureDoc = await readVisualCapture(ctx.projectRoot, changeId);
+    if (!options.checkLayoutOnly) {
+      const captureResult = await runVisualCapture({
+        projectRoot: ctx.projectRoot,
+        changeId,
+        manifest,
+        baseUrl: options.baseUrl ?? null,
+        config,
+        language: ctx.language
+      });
+      warnings.push(...captureResult.warnings);
+      captureStatus = captureResult.status;
+      captureDoc = captureResult.capture;
+      steps.push("capture");
+      if (captureResult.status === "failed") {
+        await recordVisualFailure(ctx, changeId, manifest.planningFingerprint, steps, captureStatus, "failed", [], captureResult.message);
+        throw new FetError({
+          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+          message: captureResult.message ?? msg(ctx.language, "fet visual \u622A\u56FE\u5931\u8D25\u3002", "fet visual capture failed."),
+          details: { changeId },
+          suggestedCommand: `fet visual --change ${changeId} --base-url http://localhost:3000`,
+          recoverable: true
+        });
+      }
+    } else {
+      steps.push("capture");
+      captureStatus = captureDoc ? "passed" : "skipped";
+    }
+    if (!options.captureOnly) {
+      const layout = runLayoutCheck(manifest, captureDoc, ctx.language, {
+        allowManifestOnly: captureStatus === "skipped" && config.whenNoCapture !== "block"
+      });
+      steps.push("check-layout");
+      const results = buildVisualResults({
+        changeId,
+        planningFingerprint: manifest.planningFingerprint,
+        steps,
+        captureStatus,
+        layoutStatus: layout.status,
+        regions: layout.regions
+      });
+      const resultsPath = await writeVisualResults(ctx.projectRoot, results);
+      if (layout.status === "failed") {
+        await recordVisualFailure(ctx, changeId, manifest.planningFingerprint, steps, captureStatus, layout.status, layout.regions, layout.message);
+        throw new FetError({
+          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+          message: layout.message ?? msg(ctx.language, "fet visual \u5E03\u5C40\u68C0\u67E5\u672A\u901A\u8FC7\u3002", "fet visual layout check failed."),
+          details: { changeId, resultsPath: visualResultsRelativePath(changeId) },
+          suggestedCommand: `fet visual --change ${changeId}`,
+          recoverable: true
+        });
+      }
+      await recordVisualSuccess(ctx, changeId, manifest.planningFingerprint, resultsPath, captureStatus);
+      ctx.output.result({
+        ok: true,
+        command: "visual",
+        summary: msg(
+          ctx.language,
+          `change "${changeId}" \u5DF2\u901A\u8FC7 layout-only \u89C6\u89C9\u9A8C\u6536\u3002`,
+          `Layout-only visual verification passed for change "${changeId}".`
+        ),
+        warnings: warnings.length ? warnings : void 0,
+        nextSteps: [`fet verify --change ${changeId}`],
+        data: { changeId, results, capturePath: captureDoc ? visualCaptureRelativePath(changeId) : null }
+      });
+      return;
     }
+    ctx.output.result({
+      ok: true,
+      command: "visual",
+      summary: msg(ctx.language, "fet visual \u622A\u56FE\u6B65\u9AA4\u5DF2\u5B8C\u6210\u3002", "fet visual capture step completed."),
+      warnings: warnings.length ? warnings : void 0,
+      data: { changeId, captureStatus, capturePath: captureDoc ? visualCaptureRelativePath(changeId) : null }
+    });
+  });
+}
+async function ensureManifest(ctx, changeId, baseUrl) {
+  const fingerprint2 = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  const existing = await readVisualManifest(ctx.projectRoot, changeId);
+  if (existing && existing.planningFingerprint === fingerprint2 && (!baseUrl || existing.run.baseUrl === baseUrl)) {
+    return existing;
+  }
+  const input = await generateVisualManifestInput(ctx.projectRoot, changeId, baseUrl);
+  const manifest = mergeBaseUrl(
+    createVisualManifest({
+      changeId,
+      planningFingerprint: input.planningFingerprint,
+      figmaUrls: input.figmaUrls,
+      figmaSources: input.figmaSources,
+      baseUrl,
+      pages: input.pages
+    }),
+    baseUrl
+  );
+  await writeVisualManifest(ctx.projectRoot, manifest);
+  const fetDir = join28(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  await mkdir10(fetDir, { recursive: true });
+  await atomicWrite(join28(ctx.projectRoot, visualInstructionsRelativePath(changeId)), renderVisualInstructions(changeId, manifest, ctx.language));
+  await atomicWrite(join28(ctx.projectRoot, visualSpecRelativePath(changeId)), renderVisualSpec(changeId, manifest, ctx.language));
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visual = {
+    status: "ready",
+    generatedAt: manifest.generatedAt,
+    planningFingerprint: fingerprint2,
+    manifestPath: manifestPath2(changeId)
+  };
+  invalidateVisualRun(changeState);
+  await ctx.stateStore.writeChange(changeState);
+  return manifest;
+}
+async function recordVisualSuccess(ctx, changeId, planningFingerprint, resultsPath, captureStatus) {
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visualRun = {
+    status: "passed",
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint,
+    manifestPath: manifestPath2(changeId),
+    resultsPath,
+    captureStatus
+  };
+  await ctx.stateStore.writeChange(changeState);
+}
+async function recordVisualFailure(ctx, changeId, planningFingerprint, steps, captureStatus, layoutStatus, regions, message) {
+  const results = buildVisualResults({
+    changeId,
+    planningFingerprint,
+    steps,
+    captureStatus,
+    layoutStatus,
+    regions
   });
+  await writeVisualResults(ctx.projectRoot, results);
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visualRun = {
+    status: "failed",
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint,
+    manifestPath: manifestPath2(changeId),
+    resultsPath: visualResultsRelativePath(changeId),
+    captureStatus
+  };
+  await ctx.stateStore.writeChange(changeState);
+  if (message) {
+    void message;
+  }
 }
 
 // src/commands/verify.ts
-import { createHash } from "crypto";
-import { mkdir as mkdir7, readFile as readFile15, stat as stat9 } from "fs/promises";
-import { join as join20 } from "path";
-function msg(language, zh, en) {
-  return language === "en" ? en : zh;
-}
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir11, readFile as readFile21, stat as stat12 } from "fs/promises";
+import { join as join29 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -4580,10 +6165,12 @@ async function verifyCommand(ctx, options) {
 }
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
+  await assertTestPassed(ctx, changeId);
+  await assertVisualPassed(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join20(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join20(dir, "verify-instructions.md");
-  await mkdir7(dir, { recursive: true });
+  const dir = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join29(dir, "verify-instructions.md");
+  await mkdir11(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -4598,8 +6185,10 @@ async function writeInstructions(ctx, changeId) {
 }
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
+  await assertTestPassed(ctx, changeId);
+  await assertVisualPassed(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join20(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(ctx, instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -4621,21 +6210,10 @@ async function markDone(ctx, changeId) {
     nextSteps: [`fet sync --change ${changeId}`, `fet archive --change ${changeId}`]
   });
 }
-async function assertChangeExists(ctx, changeId) {
-  const inspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
-  if (!inspection.exists) {
-    throw new FetError({
-      code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-      message: msg(ctx.language, "\u6307\u5B9A\u7684 change \u4E0D\u5B58\u5728", "The specified change does not exist"),
-      details: { changeId },
-      suggestedCommand: `fet verify --change ${changeId}`
-    });
-  }
-}
 async function readInstructions(ctx, path, changeId) {
   try {
-    await stat9(path);
-    const content = await readFile15(path, "utf8");
+    await stat12(path);
+    const content = await readFile21(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -4667,26 +6245,7 @@ function readFrontMatterValue(content, key) {
   return match?.[1]?.trim() ?? null;
 }
 function fingerprint(value) {
-  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
-}
-async function resolveChangeId(ctx) {
-  if (ctx.changeId) {
-    return ctx.changeId;
-  }
-  const global = await ctx.stateStore.getOrCreateGlobal();
-  if (global.activeChangeId) {
-    return global.activeChangeId;
-  }
-  const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
-  if (inspection.changes.length === 1 && inspection.changes[0]) {
-    return inspection.changes[0];
-  }
-  throw new FetError({
-    code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-    message: msg(ctx.language, "\u65E0\u6CD5\u786E\u5B9A\u8981\u9A8C\u8BC1\u7684 change", "Cannot determine which change to verify"),
-    details: { openChangeIds: inspection.changes },
-    suggestedCommand: "fet verify --change <change-id>"
-  });
+  return `sha256:${createHash2("sha256").update(JSON.stringify(value)).digest("hex")}`;
 }
 
 // src/model-policy.ts
@@ -4777,11 +6336,12 @@ function renderIdeModelPolicy(command, language = "zh-CN") {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir8, readFile as readFile16, stat as stat10 } from "fs/promises";
+import { mkdir as mkdir12, readFile as readFile22, stat as stat13 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname8, join as join21 } from "path";
+import { dirname as dirname11, join as join30 } from "path";
 
 // src/adapters/commands.ts
+var FET_STANDALONE_COMMANDS = ["tdd", "test", "visual"];
 var FET_WORKFLOW_COMMANDS = [
   "explore",
   "propose",
@@ -4796,7 +6356,7 @@ var FET_WORKFLOW_COMMANDS = [
   "onboard"
 ];
 var FET_GRAPH_COMMANDS = ["graph-status", "graph-setup", "graph-init", "graph-refresh", "graph-doctor", "graph-handoff"];
-var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, "update", "fill-context", "passthrough", ...FET_GRAPH_COMMANDS];
+var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, ...FET_STANDALONE_COMMANDS, "update", "fill-context", "passthrough", ...FET_GRAPH_COMMANDS];
 function renderFetAdapterUsage(command, args = "[...args]") {
   if (command.startsWith("graph-")) {
     const subcommand = command.slice("graph-".length);
@@ -5864,7 +7424,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists5(join21(projectRoot, ".codex")) || await exists5(join21(projectRoot, "AGENTS.md")),
+      detected: await exists6(join30(projectRoot, ".codex")) || await exists6(join30(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -5903,7 +7463,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir8(dirname8(target), { recursive: true });
+      await mkdir12(dirname11(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -5930,9 +7490,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join21(resolveCodexHome(), file.path);
+    return join30(resolveCodexHome(), file.path);
   }
-  return join21(projectRoot, file.path);
+  return join30(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -5941,18 +7501,18 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join21(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join30(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile16(path, "utf8");
+    return await readFile22(path, "utf8");
   } catch {
     return null;
   }
 }
-async function exists5(path) {
+async function exists6(path) {
   try {
-    await stat10(path);
+    await stat13(path);
     return true;
   } catch {
     return false;
@@ -5960,8 +7520,8 @@ async function exists5(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir9, readFile as readFile17, stat as stat11 } from "fs/promises";
-import { dirname as dirname9, join as join22 } from "path";
+import { mkdir as mkdir13, readFile as readFile23, stat as stat14 } from "fs/promises";
+import { dirname as dirname12, join as join31 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorFigmaStopRuleFile(language = DEFAULT_LANGUAGE) {
@@ -6093,6 +7653,12 @@ After installation, verify with \`gitnexus --version\`, then run \`fet graph ini
   if (command === "apply") {
     return renderApplySkill(usage, language);
   }
+  if (command === "tdd" || command === "test") {
+    return renderTddTestSkill(command, usage, language);
+  }
+  if (command === "visual") {
+    return renderVisualSkill(usage, language);
+  }
   if (command === "propose" || command === "continue" || command === "ff") {
     return renderPlanningSkill(command, usage, language);
   }
@@ -6210,6 +7776,67 @@ ${figmaBlock}
 ${uiContractBlock}
 
 \u6267\u884C\u524D\u8BF7\u9605\u8BFB AGENTS.md\u3001openspec/config.yaml \u4E0E\u5F53\u524D change \u4E0B\u7684 OpenSpec \u4EA7\u7269\u3002
+
+\u5B9E\u65BD\u524D\u987B\u5DF2\u8FD0\u884C \`fet tdd\`\uFF1B\u5B58\u5728 \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\` \u65F6\u6309\u6E05\u5355\u7F16\u5199\u6D4B\u8BD5\u4E0E\u5B9E\u73B0\uFF0C\u5E76\u5728 \`fet verify\` \u524D\u5148 \`fet test\`\u3002
+`;
+}
+function renderVisualSkill(usage, language) {
+  const body = language === "en" ? `Default \`fet visual\` runs manifest refresh, Playwright capture (needs \`--base-url\`), and **layout-only** checks (no pixel match on dynamic API content). Use \`--plan\`, \`--capture-only\`, or \`--check-layout-only\` only when debugging.` : `\u9ED8\u8BA4 \`fet visual\` \u4F1A\u66F4\u65B0\u6E05\u5355\u3001Playwright \u622A\u56FE\uFF08\u9700 \`--base-url\`\uFF09\u5E76\u505A **layout-only** \u68C0\u67E5\uFF08\u4E0D\u5BF9\u52A8\u6001\u63A5\u53E3\u5185\u5BB9\u505A\u50CF\u7D20\u5BF9\u6BD4\uFF09\u3002\u4EC5\u5728\u8C03\u8BD5\u65F6\u4F7F\u7528 \`--plan\`\u3001\`--capture-only\`\u3001\`--check-layout-only\`\u3002`;
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: cursor-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+---
+name: fet-visual
+description: ${language === "en" ? "Layout-only visual verification for a change" : "change \u7EA7 layout-only \u89C6\u89C9\u9A8C\u6536"}
+disable-model-invocation: true
+---
+
+${renderIdeModelPolicy("visual", language)}
+
+${languageInstruction(language)}
+
+\u8BF7\u5728\u7EC8\u7AEF\u4E2D\u6267\u884C\uFF1A
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+${body}
+`;
+}
+function renderTddTestSkill(command, usage, language) {
+  const description = command === "tdd" ? language === "en" ? "Generate per-change TDD manifest and test instructions" : "\u751F\u6210\u672C change \u7684 TDD \u6E05\u5355\u4E0E\u6D4B\u8BD5\u6307\u5F15" : language === "en" ? "Run unit tests scoped to the change TDD manifest" : "\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B";
+  const body = command === "tdd" ? language === "en" ? `After planning artifacts exist, run this before \`fet apply\`. It writes \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\`, \`tdd-spec.md\`, and \`tdd-instructions.md\`. Then create failing tests in the repo before implementation.` : `\u89C4\u5212\u4EA7\u7269\u5C31\u7EEA\u540E\u3001\`fet apply\` \u4E4B\u524D\u8FD0\u884C\u3002\u4F1A\u5199\u5165 \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\`\u3001\`tdd-spec.md\`\u3001\`tdd-instructions.md\`\uFF0C\u518D\u5728\u4ED3\u5E93\u4E2D\u7F16\u5199\u9884\u671F\u5931\u8D25\u7684\u6D4B\u8BD5\u3002` : language === "en" ? `Run after implementation. Requires a current \`tdd-manifest.yaml\`. Records pass/fail in FET state; \`fet verify\` is blocked until this passes (unless configured to skip).` : `\u5B9E\u73B0\u5B8C\u6210\u540E\u8FD0\u884C\u3002\u9700\u8981\u6709\u6548\u7684 \`tdd-manifest.yaml\`\u3002\u7ED3\u679C\u5199\u5165 FET \u72B6\u6001\uFF1B\u672A\u901A\u8FC7\u524D \`fet verify\` \u4F1A\u88AB\u62E6\u622A\uFF08\u9664\u975E\u914D\u7F6E\u4E3A skip\uFF09\u3002`;
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: cursor-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+---
+name: fet-${command}
+description: ${description}
+disable-model-invocation: true
+---
+
+${renderIdeModelPolicy(command, language)}
+
+${languageInstruction(language)}
+
+\u8BF7\u5728\u7EC8\u7AEF\u4E2D\u6267\u884C\uFF1A
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+${body}
 `;
 }
 
@@ -6219,7 +7846,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists6(join22(projectRoot, ".cursor")),
+      detected: await exists7(join31(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -6236,7 +7863,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join22(projectRoot, file.path);
+      const target = join31(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -6249,7 +7876,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir9(dirname9(target), { recursive: true });
+      await mkdir13(dirname12(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -6259,7 +7886,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join22(projectRoot, file.path);
+      const target = join31(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -6275,14 +7902,14 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile17(path, "utf8");
+    return await readFile23(path, "utf8");
   } catch {
     return null;
   }
 }
-async function exists6(path) {
+async function exists7(path) {
   try {
-    await stat11(path);
+    await stat14(path);
     return true;
   } catch {
     return false;
@@ -6294,45 +7921,45 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir as readdir5, stat as stat12 } from "fs/promises";
-import { join as join23 } from "path";
+import { readdir as readdir6, stat as stat15 } from "fs/promises";
+import { join as join32 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join23(projectRoot, "openspec");
-  const changesPath = join23(openspecPath, "changes");
-  const legacyArchivePath = join23(openspecPath, "archive");
-  const changesArchivePath = join23(changesPath, "archive");
+  const openspecPath = join32(projectRoot, "openspec");
+  const changesPath = join32(openspecPath, "changes");
+  const legacyArchivePath = join32(openspecPath, "archive");
+  const changesArchivePath = join32(changesPath, "archive");
   return {
-    exists: await exists7(openspecPath),
+    exists: await exists8(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
     archived: [.../* @__PURE__ */ new Set([...await listDirectories(legacyArchivePath), ...await listDirectories(changesArchivePath)])]
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join23(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join23(changePath, "tasks.md");
-  const specsPath = join23(changePath, "specs");
+  const changePath = join32(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join32(changePath, "tasks.md");
+  const specsPath = join32(changePath, "specs");
   return {
     changeId,
-    exists: await exists7(changePath),
-    hasProposal: await exists7(join23(changePath, "proposal.md")),
-    hasTasks: await exists7(tasksPath),
-    hasSpecs: await exists7(specsPath),
+    exists: await exists8(changePath),
+    hasProposal: await exists8(join32(changePath, "proposal.md")),
+    hasTasks: await exists8(tasksPath),
+    hasSpecs: await exists8(specsPath),
     tasksPath,
     changePath
   };
 }
 async function listDirectories(path, options = {}) {
   try {
-    const entries = await readdir5(path, { withFileTypes: true });
+    const entries = await readdir6(path, { withFileTypes: true });
     const excluded = new Set(options.exclude ?? []);
     return entries.filter((entry) => entry.isDirectory() && !excluded.has(entry.name)).map((entry) => entry.name);
   } catch {
     return [];
   }
 }
-async function exists7(path) {
+async function exists8(path) {
   try {
-    await stat12(path);
+    await stat15(path);
     return true;
   } catch {
     return false;
@@ -6399,14 +8026,14 @@ function exec(command, args) {
 }
 
 // src/openspec/runner.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 async function runOpenSpec(executablePath, command, args, options) {
   const spawnCommand = executablePath === "npx openspec" ? "npx" : executablePath;
   const spawnArgs = executablePath === "npx openspec" ? ["openspec", command, ...args] : [command, ...args];
   return new Promise((resolve2, reject) => {
     const stdout = [];
     const stderr = [];
-    const child = spawn2(spawnCommand, spawnArgs, {
+    const child = spawn3(spawnCommand, spawnArgs, {
       cwd: options.cwd,
       stdio: options.stdio ?? "inherit",
       shell: process.platform === "win32"
@@ -6515,14 +8142,14 @@ function escapeRegExp(value) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir6, stat as stat13 } from "fs/promises";
-import { join as join24, relative as relative4, sep } from "path";
+import { readdir as readdir7, stat as stat16 } from "fs/promises";
+import { join as join33, relative as relative5, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join24(projectRoot, candidate);
-    if (!await exists8(root)) {
+    const root = join33(projectRoot, candidate);
+    if (!await exists9(root)) {
       continue;
     }
     for (const file of await listFiles(root)) {
@@ -6530,8 +8157,8 @@ async function scanRoutes(projectRoot) {
         continue;
       }
       routes.push({
-        path: inferRoutePath(relative4(root, file)),
-        source: relative4(projectRoot, file).split(sep).join("/"),
+        path: inferRoutePath(relative5(root, file)),
+        source: relative5(projectRoot, file).split(sep).join("/"),
         inferred: true,
         confidence: "medium"
       });
@@ -6546,10 +8173,10 @@ function inferRoutePath(relativePath) {
   return `/${withoutIndex}`.replace(/\/+/g, "/");
 }
 async function listFiles(root) {
-  const entries = await readdir6(root, { withFileTypes: true });
+  const entries = await readdir7(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join24(root, entry.name);
+    const path = join33(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -6558,9 +8185,9 @@ async function listFiles(root) {
   }
   return files;
 }
-async function exists8(path) {
+async function exists9(path) {
   try {
-    await stat13(path);
+    await stat16(path);
     return true;
   } catch {
     return false;
@@ -6717,9 +8344,9 @@ async function createCommandContext(command, options) {
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/update/check.ts
-import { mkdir as mkdir10, readFile as readFile18, writeFile } from "fs/promises";
+import { mkdir as mkdir14, readFile as readFile24, writeFile } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname10, join as join25 } from "path";
+import { dirname as dirname13, join as join34 } from "path";
 var DEFAULT_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
 function getFetUpdateCheckMode(env = process.env) {
   const value = env.FET_UPDATE_CHECK?.trim().toLowerCase();
@@ -6792,11 +8419,11 @@ function formatFetUpdateWarning(availability, language) {
 }
 function cachePath() {
   const home = process.env.FET_UPDATE_CHECK_CACHE_HOME?.trim() || homedir2();
-  return join25(home, ".fet", "update-check-cache.json");
+  return join34(home, ".fet", "update-check-cache.json");
 }
 async function readUpdateCheckCache() {
   try {
-    const raw = await readFile18(cachePath(), "utf8");
+    const raw = await readFile24(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.latestVersion !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -6812,7 +8439,7 @@ async function readUpdateCheckCache() {
 }
 async function writeUpdateCheckCache(cache) {
   const path = cachePath();
-  await mkdir10(dirname10(path), { recursive: true });
+  await mkdir14(dirname13(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -6899,6 +8526,23 @@ for (const action of ["init", "refresh"]) {
 addGlobalOptions(program.command("doctor").description("\u8BCA\u65AD\u72B6\u6001\u3001\u914D\u7F6E\u4E0E\u4E00\u81F4\u6027").option("--fix-lock", "\u6E05\u7406 FET \u9501\u6587\u4EF6")).action(
   wrap("doctor", (ctx, options) => doctorCommand(ctx, { fixLock: Boolean(options.fixLock) }))
 );
+addGlobalOptions(program.command("tdd").description("\u6839\u636E\u89C4\u5212\u4EA7\u7269\u751F\u6210 change \u7EA7 TDD \u6E05\u5355\u4E0E\u6D4B\u8BD5\u6307\u5F15")).action(wrap("tdd", tddCommand));
+addGlobalOptions(program.command("test").description("\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B\u5E76\u8BB0\u5F55\u7EFF\u706F\u72B6\u6001").option("--plan", "\u4EC5\u8F93\u51FA\u5C06\u6267\u884C\u7684\u6D4B\u8BD5\u547D\u4EE4\uFF0C\u4E0D\u8FD0\u884C")).action(
+  wrap("test", (ctx, options) => testCommand(ctx, { plan: Boolean(options.plan) }))
+);
+addGlobalOptions(
+  program.command("visual").description("layout-only \u89C6\u89C9\u9A8C\u6536\uFF08\u9ED8\u8BA4\uFF1A\u66F4\u65B0\u6E05\u5355 + \u622A\u56FE + \u5E03\u5C40\u68C0\u67E5\uFF09").option("--plan", "\u4EC5\u8F93\u51FA\u6267\u884C\u8BA1\u5212").option("--capture-only", "\u4EC5\u6267\u884C\u622A\u56FE").option("--check-layout-only", "\u4EC5\u6267\u884C\u5E03\u5C40\u68C0\u67E5\uFF08\u4F9D\u8D56\u5DF2\u6709 capture\uFF09").option("--base-url <url>", "\u5E94\u7528 base URL\uFF0C\u7528\u4E8E Playwright \u622A\u56FE")
+).action(
+  wrap(
+    "visual",
+    (ctx, options) => visualCommand(ctx, {
+      plan: Boolean(options.plan),
+      captureOnly: Boolean(options.captureOnly),
+      checkLayoutOnly: Boolean(options.checkLayoutOnly),
+      baseUrl: options.baseUrl
+    })
+  )
+);
 addGlobalOptions(program.command("verify").description("\u6700\u7EC8\u8D28\u91CF\u9A8C\u8BC1").option("--done", "\u58F0\u660E\u624B\u52A8\u9A8C\u8BC1\u5DF2\u5B8C\u6210").option("--auto", "\u751F\u6210\u6216\u6267\u884C\u81EA\u52A8\u9A8C\u8BC1\u8BA1\u5212")).action(
   wrap("verify", verifyCommand)
 );