@nick848/fet 1.1.10 → 1.1.12

package/dist/cli/index.js

@@ -2090,6 +2090,12 @@ function renderFetConfig(scan, language = "zh-CN") {
         mode: "require_before_apply",
         whenNoTestScript: "block"
       },
+      visual: {
+        enabled: true,
+        compareMode: "layout-only",
+        requireBeforeVerify: "when_figma",
+        whenNoCapture: "warn"
+      },
       specLanguage: {
         style: "layered_bilingual",
         canonical: "en",
@@ -2274,7 +2280,7 @@ function tddResultsRelativePath(changeId) {
 
 // src/templates/tdd.ts
 function renderTddInstructions(changeId, manifest, language) {
-  const manifestPath2 = tddManifestRelativePath(changeId);
+  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") {
@@ -2293,13 +2299,13 @@ Create or update unit tests **before** marking implementation tasks done in \`ta
 ## Sources
 ${manifest.sources.map((s) => `- ${s}`).join("\n")}
 
-## Cases (from ${manifestPath2})
+## 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 \`${manifestPath2}\` by hand unless fixing IDs; re-run \`fet tdd --change ${changeId}\` after planning changes.
+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}\`
@@ -2320,13 +2326,13 @@ generatedAt: ${manifest.generatedAt}
 ## \u6765\u6E90
 ${manifest.sources.map((s) => `- ${s}`).join("\n")}
 
-## \u7528\u4F8B\uFF08\u89C1 ${manifestPath2}\uFF09
+## \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 \`${manifestPath2}\`\uFF1B\u89C4\u5212\u53D8\u66F4\u540E\u8BF7\u91CD\u65B0\u6267\u884C \`fet tdd --change ${changeId}\`\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}\`
@@ -2371,19 +2377,151 @@ function escapeTable(value) {
   return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 function renderTddApplyNextSteps(changeId, language) {
-  const manifestPath2 = tddManifestRelativePath(changeId);
+  const manifestPath3 = tddManifestRelativePath(changeId);
   if (language === "en") {
     return [
-      `Read ${manifestPath2} and tdd-instructions.md; implement code until fet test passes for this change.`,
+      `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 ${manifestPath2} \u4E0E tdd-instructions.md\uFF1B\u5B9E\u73B0\u4EE3\u7801\u76F4\u81F3\u672C change \u7684 fet test \u901A\u8FC7\u3002`,
+    `\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) {
@@ -2862,6 +3000,390 @@ When the artifact is \`specs/<capability>/spec.md\` (or you edit spec files in t
 3. \u82F1\u6587\u89C4\u8303\u53E5\u6709\u4EFB\u4F55\u53D8\u52A8\u65F6\uFF0C**\u540C\u4E00\u6B21\u7F16\u8F91**\u5FC5\u987B\u540C\u6B65\u66F4\u65B0\u5BF9\u5E94\u4E2D\u6587\u6CE8\u91CA\u3002${uiBlock}`;
 }
 
+// src/templates/write-boundary.ts
+var WRITE_BOUNDARY_ALLOW_PREFIXES = ["src/", "openspec/"];
+var WRITE_BOUNDARY_ROOT_CONFIG_EXACT = [
+  ".gitignore",
+  ".gitattributes",
+  ".stylelintignore",
+  ".eslintignore",
+  ".prettierignore",
+  ".editorconfig",
+  ".npmrc",
+  ".nvmrc",
+  ".node-version",
+  ".checkrc.js",
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "npm-shrinkwrap.json"
+];
+var WRITE_BOUNDARY_ROOT_CONFIG_BASENAME_PREFIXES = [
+  ".eslintrc",
+  ".stylelintrc",
+  ".prettierrc",
+  ".stylelint",
+  "eslint.config",
+  "stylelint.config",
+  "prettier.config",
+  "tsconfig",
+  "vitest.config",
+  "vite.config",
+  "tsup.config",
+  "jest.config",
+  "rollup.config",
+  "webpack.config",
+  "babel.config",
+  "biome.json",
+  "deno.json",
+  "deno.jsonc"
+];
+function renderRootConfigPathList(language) {
+  const samples = language === "en" ? "`.gitignore`, `.stylelintignore`, `.stylelintrc*`, `.eslintrc*`, `eslint.config.*`, `.checkrc.js`, `package.json`, `package-lock.json`, `tsconfig*.json`, `.prettierrc*`, tool configs at repo root (`vitest.config.*`, `vite.config.*`, \u2026)" : "`.gitignore`\u3001`.stylelintignore`\u3001`.stylelintrc*`\u3001`.eslintrc*`\u3001`eslint.config.*`\u3001`.checkrc.js`\u3001`package.json`\u3001`package-lock.json`\u3001`tsconfig*.json`\u3001`.prettierrc*`\u3001\u4EE5\u53CA\u4ED3\u5E93\u6839\u76EE\u5F55\u4E0B\u7684 `vitest.config.*`\u3001`vite.config.*` \u7B49\u5DE5\u5177\u914D\u7F6E";
+  return samples;
+}
+function renderWriteBoundaryGuardrail(language) {
+  const rootList = renderRootConfigPathList(language);
+  if (language === "en") {
+    return `- Default write scope: \`src/**\`, \`openspec/**\`, and any \`**/.fet/**\`. All other paths need explicit user approval first.
+- **Repo-root config is high risk**: ${rootList} \u2014 list each file and why before editing; never change these silently.`;
+  }
+  return `- \u9ED8\u8BA4\u53EA\u5141\u8BB8\u4FEE\u6539 \`src/**\`\u3001\`openspec/**\` \u53CA\u4EFB\u610F \`**/.fet/**\`\uFF1B\u5176\u4F59\u8DEF\u5F84\u987B\u5148\u83B7\u7528\u6237\u660E\u786E\u540C\u610F\u3002
+- **\u4ED3\u5E93\u6839\u76EE\u5F55\u914D\u7F6E\u6587\u4EF6\u9AD8\u98CE\u9669**\uFF1A${rootList} \u2014 \u4FEE\u6539\u524D\u987B\u5217\u51FA\u6587\u4EF6\u4E0E\u539F\u56E0\uFF0C\u7981\u6B62\u64C5\u81EA\u6539\u52A8\u3002`;
+}
+function renderWriteBoundaryPolicyBody(language) {
+  if (language === "en") {
+    return `## Default allowed write scope
+
+- \`src/**\` \u2014 application/library source
+- \`openspec/**\` \u2014 OpenSpec specs and change artifacts
+- \`**/.fet/**\` \u2014 per-change FET handoff files (including \`openspec/changes/<id>/.fet/\`)
+
+## Ask the user first
+
+Before creating, editing, or deleting files **outside** the allowed scope:
+
+1. List every path you need to touch and why.
+2. Wait for explicit user approval (do not assume silence means yes).
+3. Prefer minimal diffs.
+
+Common paths that need approval: \`tests/**\`, \`.github/**\`, \`.workflow/**\`, \`.cursor/**\`, \`.codex/**\`, \`AGENTS.md\`, \`README*\`, \`.env*\`.
+
+## Repo-root config (always ask \u2014 never silent edit)
+
+These live at the **repository root** (no subdirectory). Treat every change as infrastructure impact:
+
+${renderRootConfigPathList(language)}
+
+Workflow:
+
+1. State **exact filenames** (e.g. \`package.json\`, \`.eslintrc.js\`, \`.gitignore\`).
+2. Explain **why** each file must change.
+3. Wait for **explicit user approval** before writing.
+4. Do not \u201Cfix lint/format\u201D by editing root configs unless the user requested that scope.
+
+## Forbidden without approval
+
+- Dependency or lockfile changes (\`package.json\`, \`package-lock.json\`, etc.) unless the user asked
+- Lint/format/tooling config at repo root (\`.eslintrc*\`, \`.stylelint*\`, \`.checkrc.js\`, \`.gitignore\`, \u2026) unless the user asked
+- Secrets or credential files
+- Using shell redirects or destructive git commands to bypass this policy
+
+## Cursor enforcement
+
+When \`.cursor/hooks/fet-guard-write-paths.mjs\` is installed, out-of-scope **write tools** trigger an approval prompt (\`permission: ask\`). Shell writes are gated by \`fet-guard-shell-writes.mjs\`. Rules alone are not sufficient\u2014keep hooks enabled after \`fet init\`.`;
+  }
+  return `## \u9ED8\u8BA4\u5141\u8BB8\u4FEE\u6539\u7684\u8303\u56F4
+
+- \`src/**\` \u2014 \u4E1A\u52A1/\u5E93\u6E90\u7801
+- \`openspec/**\` \u2014 OpenSpec \u89C4\u8303\u4E0E change \u4EA7\u7269
+- \`**/.fet/**\` \u2014 \u5404 change \u7684 FET \u4EA4\u63A5\u6587\u4EF6\uFF08\u542B \`openspec/changes/<id>/.fet/\`\uFF09
+
+## \u987B\u5148\u5F81\u5F97\u7528\u6237\u540C\u610F
+
+\u5728**\u5141\u8BB8\u8303\u56F4\u5916**\u521B\u5EFA\u3001\u4FEE\u6539\u6216\u5220\u9664\u6587\u4EF6\u4E4B\u524D\uFF1A
+
+1. \u5217\u51FA\u5C06\u8981\u4FEE\u6539\u7684\u8DEF\u5F84\u53CA\u539F\u56E0\u3002
+2. \u7B49\u5F85\u7528\u6237\u660E\u786E\u540C\u610F\uFF08\u4E0D\u8981\u9ED8\u8BA4\u6C89\u9ED8\u5373\u540C\u610F\uFF09\u3002
+3. \u4FDD\u6301\u6700\u5C0F\u6539\u52A8\u3002
+
+\u5E38\u89C1\u9700\u5BA1\u6279\u8DEF\u5F84\uFF1A\`tests/**\`\u3001\`.github/**\`\u3001\`.workflow/**\`\u3001\`.cursor/**\`\u3001\`.codex/**\`\u3001\`AGENTS.md\`\u3001\`README*\`\u3001\`.env*\`\u3002
+
+## \u4ED3\u5E93\u6839\u76EE\u5F55\u914D\u7F6E\uFF08\u59CB\u7EC8\u987B\u8BE2\u95EE\uFF0C\u7981\u6B62\u9759\u9ED8\u4FEE\u6539\uFF09
+
+\u4EE5\u4E0B\u6587\u4EF6\u4F4D\u4E8E**\u9879\u76EE\u6839\u76EE\u5F55**\uFF08\u8DEF\u5F84\u4E2D\u65E0\u5B50\u76EE\u5F55\uFF09\uFF0C\u4E00\u5F8B\u89C6\u4E3A\u57FA\u7840\u8BBE\u65BD\u7EA7\u6539\u52A8\uFF1A
+
+${renderRootConfigPathList(language)}
+
+\u6D41\u7A0B\uFF1A
+
+1. \u660E\u786E\u5217\u51FA**\u5B8C\u6574\u6587\u4EF6\u540D**\uFF08\u5982 \`package.json\`\u3001\`.eslintrc.js\`\u3001\`.gitignore\`\uFF09\u3002
+2. \u8BF4\u660E**\u6BCF\u9879\u4FEE\u6539\u7684\u539F\u56E0**\u3002
+3. \u83B7\u5F97\u7528\u6237**\u660E\u786E\u540C\u610F**\u540E\u518D\u5199\u5165\u3002
+4. \u4E0D\u8981\u4EE5\u300C\u987A\u4FBF\u4FEE lint/\u683C\u5F0F\u300D\u4E3A\u7531\u64C5\u81EA\u6539\u6839\u76EE\u5F55\u914D\u7F6E\u3002
+
+## \u672A\u7ECF\u540C\u610F\u7981\u6B62
+
+- \u64C5\u81EA\u6539\u4F9D\u8D56\u6216\u9501\u6587\u4EF6\uFF08\`package.json\`\u3001\`package-lock.json\` \u7B49\uFF09\uFF0C\u9664\u975E\u7528\u6237\u660E\u786E\u8981\u6C42
+- \u64C5\u81EA\u6539\u6839\u76EE\u5F55 lint/\u683C\u5F0F\u5316/\u5DE5\u5177\u94FE\u914D\u7F6E\uFF08\`.eslintrc*\`\u3001\`.stylelint*\`\u3001\`.checkrc.js\`\u3001\`.gitignore\` \u7B49\uFF09\uFF0C\u9664\u975E\u7528\u6237\u660E\u786E\u8981\u6C42
+- \u4FEE\u6539\u5BC6\u94A5\u6216\u51ED\u8BC1\u6587\u4EF6
+- \u7528 shell \u91CD\u5B9A\u5411\u6216\u7834\u574F\u6027 git \u547D\u4EE4\u7ED5\u8FC7\u672C\u7B56\u7565
+
+## Cursor \u786C\u95E8\u7981
+
+\u5B89\u88C5 \`.cursor/hooks/fet-guard-write-paths.mjs\` \u540E\uFF0C\u8D85\u51FA\u8303\u56F4\u7684**\u5199\u5DE5\u5177**\u4F1A\u5F39\u51FA\u5BA1\u6279\uFF08\`permission: ask\`\uFF09\uFF1B\`fet-guard-shell-writes.mjs\` \u7EA6\u675F\u53EF\u80FD\u5199\u6587\u4EF6\u7684 shell\u3002\u4EC5\u89C4\u5219\u4E0D\u591F\u2014\u2014\`fet init\` \u540E\u8BF7\u4FDD\u6301 hooks \u542F\u7528\u3002`;
+}
+function renderCursorWriteBoundaryRule(language) {
+  const description = language === "en" ? "FET write boundary: default edits only under src/, openspec/, and .fet/" : "FET \u5199\u8DEF\u5F84\u8FB9\u754C\uFF1A\u9ED8\u8BA4\u4EC5\u53EF\u6539 src/\u3001openspec/\u3001.fet/";
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: cursor-adapter
+adapterVersion: 1
+FET:END -->
+
+---
+description: ${description}
+alwaysApply: true
+---
+
+${renderWriteBoundaryPolicyBody(language)}
+
+${renderWriteBoundaryGuardrail(language)}
+`;
+}
+function renderCodexWriteBoundaryGuide(language) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+FET:END -->
+
+# ${language === "en" ? "Write path boundary (Codex)" : "\u5199\u8DEF\u5F84\u8FB9\u754C\uFF08Codex\uFF09"}
+
+${renderWriteBoundaryPolicyBody(language)}
+
+${renderWriteBoundaryGuardrail(language)}
+`;
+}
+function renderCursorWritePathsHookMjs() {
+  const allowPrefixes = [...WRITE_BOUNDARY_ALLOW_PREFIXES];
+  const rootExact = [...WRITE_BOUNDARY_ROOT_CONFIG_EXACT];
+  const rootPrefixes = [...WRITE_BOUNDARY_ROOT_CONFIG_BASENAME_PREFIXES];
+  return `#!/usr/bin/env node
+/**
+ * FET:MANAGED
+ * adapterVersion: 1
+ * write-path guard for Cursor preToolUse (Write/StrReplace/EditNotebook/Delete).
+ */
+import { readFileSync } from "node:fs";
+
+const ALLOW_PREFIXES = ${JSON.stringify(allowPrefixes)};
+const ROOT_CONFIG_EXACT = ${JSON.stringify(rootExact)};
+const ROOT_CONFIG_PREFIXES = ${JSON.stringify(rootPrefixes)};
+
+function normalizePath(path) {
+  return String(path ?? "")
+    .replaceAll("\\\\", "/")
+    .replace(/^\\.\\/+/, "")
+    .replace(/^\\/+/u, "");
+}
+
+function isRootConfigPath(path) {
+  const normalized = normalizePath(path);
+  if (!normalized || normalized.includes("/")) return false;
+  const base = normalized.toLowerCase();
+  if (ROOT_CONFIG_EXACT.includes(base)) return true;
+  return ROOT_CONFIG_PREFIXES.some((prefix) => base === prefix || base.startsWith(prefix));
+}
+
+function classifyPath(path) {
+  const normalized = normalizePath(path);
+  if (!normalized) return "ask";
+  for (const prefix of ALLOW_PREFIXES) {
+    const bare = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+    if (normalized === bare || normalized.startsWith(prefix)) return "allow";
+  }
+  if (normalized.startsWith(".fet/") || normalized.includes("/.fet/")) return "allow";
+  if (isRootConfigPath(normalized)) return "root_config";
+  return "ask";
+}
+
+function extractPaths(payload) {
+  const paths = [];
+  const tool = payload?.tool_name ?? payload?.toolName ?? "";
+  const input = payload?.tool_input ?? payload?.toolInput ?? payload?.input ?? {};
+  if (tool === "Write" || tool === "StrReplace" || tool === "Delete") {
+    if (input.path) paths.push(input.path);
+  }
+  if (tool === "EditNotebook" && input.target_notebook) {
+    paths.push(input.target_notebook);
+  }
+  return paths;
+}
+
+function respond(decision, paths) {
+  if (decision === "allow") {
+    process.stdout.write(JSON.stringify({ permission: "allow" }));
+    return;
+  }
+  const list = paths.map((p) => normalizePath(p)).filter(Boolean).join(", ") || "(unknown path)";
+  const hasRootConfig = paths.some((p) => classifyPath(p) === "root_config");
+  const msg = hasRootConfig
+    ? "FET: repo-root config file(s) require your explicit approval (.gitignore, package.json, .eslintrc*, .stylelint*, .checkrc.js, lockfiles, etc.). Approve only if you requested this tooling change."
+    : "FET write boundary: this edit is outside src/, openspec/, or **/.fet/. Approve only if you intend to modify protected paths.";
+  process.stdout.write(
+    JSON.stringify({
+      permission: "ask",
+      user_message: msg + " Paths: " + list,
+      agent_message: hasRootConfig
+        ? "Repo-root config edit blocked. Explain why each root config file must change and wait for user approval."
+        : "Out-of-scope write blocked pending user approval. List why each path is needed, then retry after approval."
+    })
+  );
+}
+
+const raw = readFileSync(0, "utf8");
+let payload = {};
+try {
+  payload = JSON.parse(raw || "{}");
+} catch {
+  process.stdout.write(JSON.stringify({ permission: "ask", user_message: "FET write guard: invalid hook payload." }));
+  process.exit(0);
+}
+
+const paths = extractPaths(payload);
+if (paths.length === 0) {
+  respond("allow", paths);
+  process.exit(0);
+}
+
+const decisions = paths.map((p) => classifyPath(p));
+if (decisions.every((d) => d === "allow")) {
+  respond("allow", paths);
+} else {
+  respond("ask", paths);
+}
+process.exit(0);
+`;
+}
+function renderCursorShellWriteHookMjs() {
+  return `#!/usr/bin/env node
+/**
+ * FET:MANAGED
+ * adapterVersion: 1
+ * shell guard for commands that may write outside the FET write boundary.
+ */
+import { readFileSync } from "node:fs";
+
+const REDIRECT = />\\s*[^\\s|&;]+/;
+const GIT_WRITE = /\\bgit\\s+(checkout|restore|reset|clean|apply)\\b/i;
+const PKG_WRITE = /\\b(npm|pnpm|yarn|bun)\\s+(install|ci|add|remove|update)\\b/i;
+const STREAM_EDIT = /\\b(sed|perl)\\s+[^\\n]*-i\\b/i;
+const TEE = /\\btee\\s+[^|;&\\n]+/i;
+
+function respondAsk(command, reason) {
+  process.stdout.write(
+    JSON.stringify({
+      permission: "ask",
+      user_message: "FET shell guard: " + reason,
+      agent_message: "Shell command may modify files outside src/openspec/.fet. Command: " + command
+    })
+  );
+}
+
+const raw = readFileSync(0, "utf8");
+let payload = {};
+try {
+  payload = JSON.parse(raw || "{}");
+} catch {
+  respondAsk("", "invalid hook payload");
+  process.exit(0);
+}
+
+const command = String(payload?.command ?? "");
+if (!command.trim()) {
+  process.stdout.write(JSON.stringify({ permission: "allow" }));
+  process.exit(0);
+}
+
+if (
+  REDIRECT.test(command) ||
+  GIT_WRITE.test(command) ||
+  PKG_WRITE.test(command) ||
+  STREAM_EDIT.test(command) ||
+  TEE.test(command)
+) {
+  respondAsk(command, "command may write or replace project files outside the default FET scope");
+  process.exit(0);
+}
+
+process.stdout.write(JSON.stringify({ permission: "allow" }));
+process.exit(0);
+`;
+}
+function renderCursorHooksJson() {
+  return JSON.stringify(
+    {
+      version: 1,
+      _fet: {
+        writeBoundary: true,
+        fetVersion: FET_VERSION
+      },
+      hooks: {
+        preToolUse: [
+          {
+            command: ".cursor/hooks/fet-guard-write-paths.mjs",
+            matcher: "Write|StrReplace|EditNotebook|Delete",
+            failClosed: true
+          }
+        ],
+        beforeShellExecution: [
+          {
+            command: ".cursor/hooks/fet-guard-shell-writes.mjs",
+            failClosed: true
+          }
+        ]
+      }
+    },
+    null,
+    2
+  );
+}
+function mergeCursorHooksJson(existingContent, fetContent) {
+  const fet = JSON.parse(fetContent);
+  if (!existingContent?.trim()) {
+    return fetContent;
+  }
+  let existing;
+  try {
+    existing = JSON.parse(existingContent);
+  } catch {
+    return fetContent;
+  }
+  const merged = {
+    version: existing.version ?? fet.version ?? 1,
+    _fet: { ...existing._fet, ...fet._fet, writeBoundary: true },
+    hooks: { ...existing.hooks }
+  };
+  for (const [event, fetEntries] of Object.entries(fet.hooks ?? {})) {
+    const current = [...merged.hooks?.[event] ?? []];
+    for (const entry of fetEntries) {
+      const duplicate = current.some((item) => item.command === entry.command);
+      if (!duplicate) {
+        current.push(entry);
+      }
+    }
+    merged.hooks = merged.hooks ?? {};
+    merged.hooks[event] = current;
+  }
+  return `${JSON.stringify(merged, null, 2)}
+`;
+}
+
 // src/commands/update-context.ts
 async function updateContextCommand(ctx) {
   let contextResult = { warnings: [] };
@@ -3818,6 +4340,8 @@ function createChangeState(fetVersion, changeId, phase) {
     manualVerify: null,
     tdd: null,
     testRun: null,
+    visual: null,
+    visualRun: null,
     lastOpenSpecCommand: null,
     warnings: []
   };
@@ -4104,6 +4628,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,
@@ -5043,7 +5568,7 @@ async function tddCommand(ctx) {
       cases,
       testCommand: testCommand2
     });
-    const manifestPath2 = await writeTddManifest(ctx.projectRoot, manifest);
+    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);
@@ -5055,7 +5580,7 @@ async function tddCommand(ctx) {
       status: "ready",
       generatedAt: manifest.generatedAt,
       planningFingerprint,
-      manifestPath: manifestPath2
+      manifestPath: manifestPath3
     };
     invalidateTestRun(changeState);
     changeState.currentPhase = "implement";
@@ -5086,7 +5611,7 @@ async function tddCommand(ctx) {
       ],
       data: {
         changeId,
-        manifestPath: manifestPath2,
+        manifestPath: manifestPath3,
         specPath,
         instructionsPath,
         caseCount: cases.length,
@@ -5291,81 +5816,746 @@ function truncate(value, max = 2e3) {
   return value.length > max ? `${value.slice(0, max)}\u2026` : value;
 }
 
-// src/commands/verify.ts
-import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir9, readFile as readFile19, stat as stat11 } from "fs/promises";
+// 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";
-async function verifyCommand(ctx, options) {
-  if (options.auto) {
-    const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-    const plan = {
-      schemaVersion: 1,
-      packageManager: scan.project.packageManager,
-      workspaces: [
-        {
-          name: "root",
-          cwd: ".",
-          commands: Object.entries(scan.commands).filter(([name]) => ["lint", "typecheck", "test"].includes(name)).map(([dimension, command]) => ({
-            dimension,
-            command: command.command,
-            source: command.source,
-            required: command.required,
-            statusIfMissing: command.required ? "fail" : "warn"
-          }))
-        }
-      ],
-      missing: ["lint", "typecheck", "test"].filter((name) => !scan.commands[name])
-    };
-    if (ctx.yes) {
-      const global = await ctx.stateStore.getOrCreateGlobal();
-      global.verifyAuthorization = {
-        schemaVersion: 1,
-        approvedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        commandFingerprint: fingerprint(plan),
-        packageManager: plan.packageManager,
-        plan: plan.workspaces.flatMap(
-          (workspace) => workspace.commands.map((command) => ({
-            cwd: workspace.cwd,
-            dimension: command.dimension,
-            command: command.command,
-            source: command.source,
-            required: command.required
-          }))
-        )
-      };
-      await ctx.stateStore.writeGlobal(global);
+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;
     }
-    ctx.output.result({
-      ok: true,
-      command: "verify",
-      summary: ctx.yes ? "\u5DF2\u786E\u8BA4 verify --auto \u6267\u884C\u8BA1\u5212\uFF1BMVP \u6682\u4E0D\u6267\u884C\u4ED3\u5E93\u811A\u672C\u3002" : "\u5DF2\u751F\u6210 verify --auto \u6267\u884C\u8BA1\u5212\uFF1BMVP \u6682\u4E0D\u6267\u884C\u4ED3\u5E93\u811A\u672C\u3002",
-      warnings: plan.missing.map((name) => `\u672A\u53D1\u73B0 ${name} \u811A\u672C\uFF0C\u5C06\u5728\u81EA\u52A8\u6267\u884C\u7248\u672C\u4E2D\u6309\u914D\u7F6E\u5904\u7406\u3002`),
-      data: plan,
-      nextSteps: ctx.yes ? ["\u5F53\u524D\u7248\u672C\u8BF7\u8FD0\u884C fet verify \u8FDB\u5165\u624B\u52A8\u9A8C\u8BC1\u6A21\u5F0F"] : ["\u5BA1\u6838\u6267\u884C\u8BA1\u5212", "\u786E\u8BA4\u8BA1\u5212\u540E\u53EF\u8FD0\u884C fet verify --auto --yes", "\u5F53\u524D\u7248\u672C\u8BF7\u8FD0\u884C fet verify \u8FDB\u5165\u624B\u52A8\u9A8C\u8BC1\u6A21\u5F0F"]
-    });
-    return;
+    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;
   }
-  await withProjectLock(
-    ctx.projectRoot,
-    { command: "verify", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
-    async () => {
-      const changeId = await resolveChangeId(ctx);
-      if (options.done) {
-        await markDone(ctx, changeId);
-      } else {
-        await writeInstructions(ctx, changeId);
-      }
-    }
-  );
 }
-async function writeInstructions(ctx, changeId) {
-  await assertChangeExists(ctx, changeId);
-  await assertTestPassed(ctx, changeId);
-  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join25(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join25(dir, "verify-instructions.md");
-  await mkdir9(dir, { recursive: true });
-  await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
+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"
+      });
+    }
+  }
+  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"
+    };
+  }
+  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 (check === "visible" && !layout.visible) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Not visible" : "\u4E0D\u53EF\u89C1" };
+    }
+    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 { pageId, selector, status: "passed" };
+}
+function buildVisualResults(input) {
+  return {
+    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
+  };
+}
+
+// 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"] }
+        ]
+      }
+    ];
+  }
+  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 {
+    ...manifest,
+    run: { baseUrl }
+  };
+}
+
+// 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 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
+  });
+}
+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 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, {});
+    const plan = {
+      schemaVersion: 1,
+      packageManager: scan.project.packageManager,
+      workspaces: [
+        {
+          name: "root",
+          cwd: ".",
+          commands: Object.entries(scan.commands).filter(([name]) => ["lint", "typecheck", "test"].includes(name)).map(([dimension, command]) => ({
+            dimension,
+            command: command.command,
+            source: command.source,
+            required: command.required,
+            statusIfMissing: command.required ? "fail" : "warn"
+          }))
+        }
+      ],
+      missing: ["lint", "typecheck", "test"].filter((name) => !scan.commands[name])
+    };
+    if (ctx.yes) {
+      const global = await ctx.stateStore.getOrCreateGlobal();
+      global.verifyAuthorization = {
+        schemaVersion: 1,
+        approvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        commandFingerprint: fingerprint(plan),
+        packageManager: plan.packageManager,
+        plan: plan.workspaces.flatMap(
+          (workspace) => workspace.commands.map((command) => ({
+            cwd: workspace.cwd,
+            dimension: command.dimension,
+            command: command.command,
+            source: command.source,
+            required: command.required
+          }))
+        )
+      };
+      await ctx.stateStore.writeGlobal(global);
+    }
+    ctx.output.result({
+      ok: true,
+      command: "verify",
+      summary: ctx.yes ? "\u5DF2\u786E\u8BA4 verify --auto \u6267\u884C\u8BA1\u5212\uFF1BMVP \u6682\u4E0D\u6267\u884C\u4ED3\u5E93\u811A\u672C\u3002" : "\u5DF2\u751F\u6210 verify --auto \u6267\u884C\u8BA1\u5212\uFF1BMVP \u6682\u4E0D\u6267\u884C\u4ED3\u5E93\u811A\u672C\u3002",
+      warnings: plan.missing.map((name) => `\u672A\u53D1\u73B0 ${name} \u811A\u672C\uFF0C\u5C06\u5728\u81EA\u52A8\u6267\u884C\u7248\u672C\u4E2D\u6309\u914D\u7F6E\u5904\u7406\u3002`),
+      data: plan,
+      nextSteps: ctx.yes ? ["\u5F53\u524D\u7248\u672C\u8BF7\u8FD0\u884C fet verify \u8FDB\u5165\u624B\u52A8\u9A8C\u8BC1\u6A21\u5F0F"] : ["\u5BA1\u6838\u6267\u884C\u8BA1\u5212", "\u786E\u8BA4\u8BA1\u5212\u540E\u53EF\u8FD0\u884C fet verify --auto --yes", "\u5F53\u524D\u7248\u672C\u8BF7\u8FD0\u884C fet verify \u8FDB\u5165\u624B\u52A8\u9A8C\u8BC1\u6A21\u5F0F"]
+    });
+    return;
+  }
+  await withProjectLock(
+    ctx.projectRoot,
+    { command: "verify", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
+    async () => {
+      const changeId = await resolveChangeId(ctx);
+      if (options.done) {
+        await markDone(ctx, changeId);
+      } else {
+        await writeInstructions(ctx, changeId);
+      }
+    }
+  );
+}
+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 = 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";
   state.phases.verify = { status: "in_progress", updatedAt: generatedAt };
@@ -5380,8 +6570,9 @@ 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 = join25(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");
@@ -5405,8 +6596,8 @@ async function markDone(ctx, changeId) {
 }
 async function readInstructions(ctx, path, changeId) {
   try {
-    await stat11(path);
-    const content = await readFile19(path, "utf8");
+    await stat12(path);
+    const content = await readFile21(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -5529,12 +6720,12 @@ function renderIdeModelPolicy(command, language = "zh-CN") {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir10, readFile as readFile20, stat as stat12 } from "fs/promises";
+import { mkdir as mkdir12, readFile as readFile22, stat as stat13 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname9, join as join26 } from "path";
+import { dirname as dirname11, join as join30 } from "path";
 
 // src/adapters/commands.ts
-var FET_STANDALONE_COMMANDS = ["tdd", "test"];
+var FET_STANDALONE_COMMANDS = ["tdd", "test", "visual"];
 var FET_WORKFLOW_COMMANDS = [
   "explore",
   "propose",
@@ -5578,6 +6769,7 @@ Before doing FET or OpenSpec work in Codex, read:
 - .codex/fet/spec-language.md when writing or updating OpenSpec specs
 - openspec/changes/<change-id>/.fet/figma-apply-instructions.md before UI work when FET apply reports Figma links
 - .codex/fet/ui-display-contract.md when UI binds API data; openspec/changes/<change-id>/.fet/ui-display-contract.yaml when present
+- .codex/fet/write-boundary.md for default edit scope (src/, openspec/, .fet/ only; ask before other paths)
 - the active change files under openspec/changes/<change-id>/, when a change is selected
 
 If GitNexus code graph context is available in the IDE or MCP tools, prefer it before broad repository scans. Use it to identify relevant modules, dependencies, and insertion points, then read only the concrete source files needed. If GitNexus is unavailable, continue with the normal FET/OpenSpec workflow.
@@ -5599,6 +6791,7 @@ ${languageInstruction(language)}
 - \u6309 Figma \u5B9E\u73B0 UI \u65F6\u9605\u8BFB .codex/fet/figma-stop.md\uFF1B\u6709 figma-apply-instructions.md \u65F6\u5FC5\u987B\u5728\u6539 UI \u524D\u5B8C\u6574\u6267\u884C
 - \u7F16\u5199\u6216\u66F4\u65B0 spec \u65F6\u9605\u8BFB .codex/fet/spec-language.md\uFF08\u82F1\u6587\u89C4\u8303 + \u540C\u6B21\u7F16\u8F91\u7EF4\u62A4\u4E2D\u6587\u6CE8\u91CA\uFF09
 - \u7ED1\u5B9A\u63A5\u53E3\u7684 UI \u9605\u8BFB .codex/fet/ui-display-contract.md\uFF1B\u5B58\u5728 ui-display-contract.yaml \u65F6\u5B9E\u65BD\u524D\u987B\u786E\u8BA4 displayFields
+- \u4FEE\u6539\u6587\u4EF6\u524D\u9605\u8BFB .codex/fet/write-boundary.md\uFF08\u9ED8\u8BA4\u4EC5 src/\u3001openspec/\u3001.fet/\uFF1B\u5176\u5B83\u8DEF\u5F84\u987B\u7528\u6237\u660E\u786E\u540C\u610F\uFF09
 - \u5982\u679C\u5DF2\u9009\u62E9 change\uFF0C\u9605\u8BFB openspec/changes/<change-id>/ \u4E0B\u7684\u5F53\u524D\u4EA7\u7269
 
 \u5982\u679C IDE \u6216 MCP \u5DE5\u5177\u4E2D\u53EF\u7528 GitNexus \u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\uFF0C\u5148\u7528\u5B83\u7F29\u5C0F\u4ED3\u5E93\u626B\u63CF\u8303\u56F4\uFF1B\u7528\u56FE\u8BC6\u522B\u76F8\u5173\u6A21\u5757\u3001\u4F9D\u8D56\u548C\u63D2\u5165\u70B9\uFF0C\u518D\u53EA\u8BFB\u53D6\u9700\u8981\u786E\u8BA4\u884C\u4E3A\u7684\u5177\u4F53\u6E90\u7801\u6587\u4EF6\u3002GitNexus \u4E0D\u53EF\u7528\u65F6\uFF0C\u6309\u666E\u901A FET/OpenSpec \u5DE5\u4F5C\u6D41\u7EE7\u7EED\u3002
@@ -5637,12 +6830,19 @@ function codexUiDisplayContractFile(language = DEFAULT_LANGUAGE) {
     content: renderCodexUiDisplayContractGuide(language)
   };
 }
+function codexWriteBoundaryFile(language = DEFAULT_LANGUAGE) {
+  return {
+    path: ".codex/fet/write-boundary.md",
+    content: renderCodexWriteBoundaryGuide(language)
+  };
+}
 function codexCommandFiles(language = DEFAULT_LANGUAGE) {
   return [
     codexKarpathyGuidelinesFile(language),
     codexFigmaStopFile(language),
     codexUiDisplayContractFile(language),
     codexSpecLanguageFile(language),
+    codexWriteBoundaryFile(language),
     ...FET_ADAPTER_COMMANDS.map((command) => ({
       path: `.codex/fet/commands/${command}.md`,
       content: renderCommand(command, language)
@@ -5684,6 +6884,9 @@ function renderCommand(command, language) {
   if (command.startsWith("graph-")) {
     return renderGraphCommand(command, language);
   }
+  if (command === "tdd" || command === "test" || command === "visual") {
+    return renderStandaloneWorkflowCommand(command, language);
+  }
   const usage = renderFetAdapterUsage(command, "");
   return `<!-- FET:MANAGED
 schemaVersion: 1
@@ -5714,11 +6917,16 @@ ${usage}
 If the command needs a change id, pass it with \`--change <change-id>\` or use the active OpenSpec change from the user's request.
 
 After the command completes, report the important next steps from the FET output and keep any generated OpenSpec artifacts in the normal project workflow.
+
+${renderWriteBoundaryGuardrail(language)}
 `;
 }
 function renderCommandZh(command) {
   const usage = renderFetAdapterUsage(command, command === "fill-context" ? "" : command === "passthrough" ? "<openspec-command> [...args]" : "");
   const title = commandTitleZh(command);
+  if (command === "tdd" || command === "test" || command === "visual") {
+    return renderStandaloneWorkflowCommand(command, "zh-CN");
+  }
   if (command === "graph-setup") {
     return `<!-- FET:MANAGED
 schemaVersion: 1
@@ -5776,6 +6984,8 @@ ${usage}
 \u5982\u679C\u547D\u4EE4\u9700\u8981 change id\uFF0C\u4F18\u5148\u4F7F\u7528\u7528\u6237\u8F93\u5165\u3001\`--change <change-id>\`\u3001FET active change \u6216\u552F\u4E00\u6253\u5F00\u7684 change\u3002\u5B58\u5728\u6B67\u4E49\u65F6\u5148\u8BE2\u95EE\u7528\u6237\u3002
 
 \u6267\u884C\u5B8C\u6210\u540E\uFF0C\u7528\u4E2D\u6587\u603B\u7ED3\u5173\u952E\u8F93\u51FA\u3001\u751F\u6210\u6216\u66F4\u65B0\u7684\u6587\u4EF6\uFF0C\u4EE5\u53CA\u4E0B\u4E00\u6B65\u5EFA\u8BAE\u3002
+
+${renderWriteBoundaryGuardrail("zh-CN")}
 `;
 }
 function renderPassthroughCommand(language) {
@@ -5892,6 +7102,9 @@ function renderSlashPrompt(command, language) {
   if (command === "apply") {
     return renderApplySlashPrompt(language);
   }
+  if (command === "tdd" || command === "test" || command === "visual") {
+    return renderStandaloneWorkflowSlashPrompt(command, language);
+  }
   if (command === "verify") {
     return renderVerifySlashPrompt(language);
   }
@@ -5953,6 +7166,9 @@ function renderSlashPromptZh(command) {
   if (command === "graph-setup") {
     return renderGraphSetupSlashPrompt("zh-CN");
   }
+  if (command === "tdd" || command === "test" || command === "visual") {
+    return renderStandaloneWorkflowSlashPrompt(command, "zh-CN");
+  }
   const usage = renderFetAdapterUsage(command, command === "fill-context" ? "" : command === "passthrough" ? "<openspec-command> [...args]" : "[...args]");
   const argumentHint = command === "passthrough" ? "openspec-command [...args]" : void 0;
   const argumentHintLine = argumentHint ? `argument-hint: ${argumentHint}
@@ -5993,9 +7209,10 @@ ${commandGoalZh(command)}
 - \u9ED8\u8BA4\u4F7F\u7528\u4E2D\u6587\u4EA7\u51FA\u3002
 - \u4E0D\u8981\u7ED5\u8FC7 FET \u76F4\u63A5\u8C03\u7528 openspec\uFF0C\u9664\u975E FET \u547D\u4EE4\u672C\u8EAB\u4E0D\u53EF\u7528\u3002
 - change \u4E0D\u660E\u786E\u65F6\u5148\u8BE2\u95EE\u7528\u6237\u3002
-${command === "fill-context" ? "- fet fill-context \u53EF\u80FD\u5DF2\u5199\u5165\u5C0F\u7A0B\u5E8F\u5305\u4F53\u79EF\u4E0E 2MB \u7EA6\u675F\uFF0C\u4E0D\u8981\u8986\u76D6\u8BE5\u8282\u4E2D\u7684\u626B\u63CF\u7ED3\u679C\uFF0C\u9664\u975E\u4ED3\u5E93\u7ED3\u6784\u5DF2\u53D8\u3002\n- \u66FF\u6362 AGENTS.md \u4E2D\u5176\u4F59 [NEEDS LLM INPUT] \u5360\u4F4D\u7B26\uFF0C\u4FDD\u7559 FET \u6258\u7BA1\u6807\u8BB0\uFF0C\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" ? "- \u4E00\u6B21\u53EA\u521B\u5EFA\u4E00\u4E2A ready artifact\uFF0C\u5E76\u5728\u5199\u5165\u524D\u9605\u8BFB\u4F9D\u8D56\u6587\u4EF6\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" ? "- \u4E0D\u8981\u5728\u7528\u6237\u5BA1\u9605\u5F53\u524D\u4EA7\u7269\u524D\u81EA\u52A8\u8FD0\u884C fet continue\u3001fet ff \u6216\u5FAA\u73AF\u751F\u6210\u540E\u7EED\u4EA7\u7269\uFF1B\u9700\u8981\u7528\u6237\u660E\u786E\u786E\u8BA4\u540E\u518D\u63A8\u8FDB\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" || command === "sync" ? `${renderSpecArtifactGuardrail("zh-CN")}
+${renderWriteBoundaryGuardrail("zh-CN")}
+${command === "fill-context" ? "- fet fill-context \u53EF\u80FD\u5DF2\u5199\u5165\u5C0F\u7A0B\u5E8F\u5305\u4F53\u79EF\u4E0E 2MB \u7EA6\u675F\uFF0C\u4E0D\u8981\u8986\u76D6\u8BE5\u8282\u4E2D\u7684\u626B\u63CF\u7ED3\u679C\uFF0C\u9664\u975E\u4ED3\u5E93\u7ED3\u6784\u5DF2\u53D8\u3002\n- \u66FF\u6362 AGENTS.md \u4E2D\u5176\u4F59 [NEEDS LLM INPUT] \u5360\u4F4D\u7B26\uFF0C\u4FDD\u7559 FET \u6258\u7BA1\u6807\u8BB0\uFF0C\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\uFF1B\u4FEE\u6539 AGENTS.md \u5C5E\u4E8E\u5141\u8BB8\u8303\u56F4\u5916\u8DEF\u5F84\uFF0C\u987B\u5728\u672C\u8F6E\u5DF2\u83B7\u5F97\u7528\u6237\u540C\u610F\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" ? "- \u4E00\u6B21\u53EA\u521B\u5EFA\u4E00\u4E2A ready artifact\uFF0C\u5E76\u5728\u5199\u5165\u524D\u9605\u8BFB\u4F9D\u8D56\u6587\u4EF6\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" ? "- \u4E0D\u8981\u5728\u7528\u6237\u5BA1\u9605\u5F53\u524D\u4EA7\u7269\u524D\u81EA\u52A8\u8FD0\u884C fet continue\u3001fet ff \u6216\u5FAA\u73AF\u751F\u6210\u540E\u7EED\u4EA7\u7269\uFF1B\u9700\u8981\u7528\u6237\u660E\u786E\u786E\u8BA4\u540E\u518D\u63A8\u8FDB\u3002\n" : ""}${command === "propose" || command === "continue" || command === "ff" || command === "sync" ? `${renderSpecArtifactGuardrail("zh-CN")}
 ` : ""}${command === "propose" || command === "continue" || command === "ff" ? `${renderUiDisplayContractGuardrail("zh-CN")}
-` : ""}${command === "apply" ? "- \u4E0D\u8981\u5728\u672A\u5B8C\u6210\u771F\u5B9E\u5B9E\u73B0\u524D\u52FE\u9009 tasks.md\uFF1B\u4E0D\u8981\u4ECE apply \u9636\u6BB5\u76F4\u63A5 sync \u6216 archive\u3002\n- \u82E5\u5B58\u5728 openspec/changes/<change-id>/.fet/figma-apply-instructions.md\uFF0C\u5FC5\u987B\u5148\u8BFB Figma\uFF08MCP/API\uFF09\u518D\u6539 UI\uFF1B\u5931\u8D25\u5219\u505C\u4E0B\u95EE\u7528\u6237\uFF0C\u7981\u6B62\u731C\u6837\u5F0F\u3002\n- \u82E5\u5B58\u5728 openspec/changes/<change-id>/.fet/ui-display-contract.yaml\uFF0C\u5B9E\u65BD\u7ED1\u5B9A\u63A5\u53E3\u7684 UI \u524D\u987B\u786E\u8BA4 displayFields\uFF0C\u7981\u6B62\u6309 OpenAPI \u5168\u91CF\u5C55\u793A\u3002\n" : ""}`;
+` : ""}${command === "apply" ? "- \u4E0D\u8981\u5728\u672A\u5B8C\u6210\u771F\u5B9E\u5B9E\u73B0\u524D\u52FE\u9009 tasks.md\uFF1B\u4E0D\u8981\u4ECE apply \u9636\u6BB5\u76F4\u63A5 sync \u6216 archive\u3002\n- \u5B9E\u65BD\u524D\u987B\u5DF2\u8FD0\u884C fet tdd\uFF1B\u5B58\u5728 tdd-manifest.yaml \u65F6\u6309\u6E05\u5355\u7F16\u5199\u6D4B\u8BD5\u4E0E\u5B9E\u73B0\uFF0Cfet verify \u524D\u5148 fet test\u3002\n- \u82E5\u5B58\u5728 openspec/changes/<change-id>/.fet/figma-apply-instructions.md\uFF0C\u5FC5\u987B\u5148\u8BFB Figma\uFF08MCP/API\uFF09\u518D\u6539 UI\uFF1B\u5931\u8D25\u5219\u505C\u4E0B\u95EE\u7528\u6237\uFF0C\u7981\u6B62\u731C\u6837\u5F0F\u3002\n- \u82E5\u5B58\u5728 openspec/changes/<change-id>/.fet/ui-display-contract.yaml\uFF0C\u5B9E\u65BD\u7ED1\u5B9A\u63A5\u53E3\u7684 UI \u524D\u987B\u786E\u8BA4 displayFields\uFF0C\u7981\u6B62\u6309 OpenAPI \u5168\u91CF\u5C55\u793A\u3002\n" : ""}`;
 }
 function commandTitleZh(command) {
   const titles = {
@@ -6069,7 +7286,9 @@ First run:
 fet fill-context
 \`\`\`
 
-Then read AGENTS.md and openspec/config.yaml, inspect the project, and replace every [NEEDS LLM INPUT] or [NEED LLM INPUT] placeholder in AGENTS.md with concrete project-specific content. Preserve FET managed markers and do not modify business code.
+Then read AGENTS.md and openspec/config.yaml, inspect the project, and replace every [NEEDS LLM INPUT] or [NEED LLM INPUT] placeholder in AGENTS.md with concrete project-specific content. Preserve FET managed markers and do not modify business code. Editing AGENTS.md is outside the default write scope\u2014confirm user approval first.
+
+${renderWriteBoundaryGuardrail(language)}
 `;
 }
 function renderFillContextSlashPrompt(language) {
@@ -6105,7 +7324,9 @@ Steps:
 Guardrails:
 - Do not invent facts that cannot be inferred from the repo.
 - Use [UNKNOWN] only when the repository does not contain enough evidence.
-- Keep generated context stable and useful for future AI coding sessions.`,
+- Keep generated context stable and useful for future AI coding sessions.
+- Editing AGENTS.md is outside the default write scope; confirm user approval first (see .codex/fet/write-boundary.md).
+${renderWriteBoundaryGuardrail(language)}`,
     void 0,
     language
   );
@@ -6174,14 +7395,16 @@ Steps:
    - Follow proposal, specs, design, and tasks.
    - Mark each completed task checkbox in tasks.md from \`- [ ]\` to \`- [x]\`.
    - Pause and ask if a task is ambiguous or reveals a design conflict.
-8. After completing or pausing, summarize completed tasks, remaining tasks, and blockers.
+8. Run \`fet tdd --change <change-id>\` before implementation when no \`tdd-manifest.yaml\` exists yet; after coding run \`fet test --change <change-id>\` before \`fet verify\`.
+9. After completing or pausing, summarize completed tasks, remaining tasks, and blockers.
 
 Guardrails:
 - Never skip reading OpenSpec artifacts before implementation.
 - When Figma links exist for this change, never implement or restyle UI without reading Figma first.
 - When ui-display-contract.yaml exists, API schemas are not UI checklists\u2014only displayFields may render.
 - Do not mark a task complete until the code change is actually done.
-- Do not run sync or archive from apply.`,
+- Do not run sync or archive from apply.
+${renderWriteBoundaryGuardrail(language)}`,
     void 0,
     language
   );
@@ -6608,8 +7831,97 @@ ${languageInstruction(language)}
 ${graphContextInstruction}
 
 ${body}
+
+${renderWriteBoundaryGuardrail(language)}
 `;
 }
+function renderStandaloneWorkflowCommand(command, language) {
+  const usage = renderFetAdapterUsage(command, "");
+  const { title, body } = standaloneWorkflowCopy(command, language);
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+# ${usage}
+
+${renderIdeModelPolicy(command, language)}
+
+${languageInstruction(language)}
+
+## ${language === "en" ? "Purpose" : "\u7528\u9014"}
+
+${title}
+
+## ${language === "en" ? "Workflow" : "\u5DE5\u4F5C\u6D41"}
+
+${body}
+
+${renderWriteBoundaryGuardrail(language)}
+`;
+}
+function renderStandaloneWorkflowSlashPrompt(command, language) {
+  const usage = renderFetAdapterUsage(command, "[...args]");
+  const { title, body, description } = standaloneWorkflowCopy(command, language);
+  return renderManagedSlashPrompt(
+    usage,
+    description,
+    `${title}
+
+Steps:
+
+1. Read AGENTS.md, openspec/config.yaml, .codex/fet/karpathy-guidelines.md, and .codex/fet/write-boundary.md.
+2. Resolve the change id when needed (\`--change <change-id>\` or active change).
+3. Run:
+   \`\`\`sh
+   ${renderFetAdapterUsage(command, "")}
+   \`\`\`
+4. ${body}
+5. Summarize outputs, paths written under openspec/changes/<change-id>/.fet/, and next steps.
+
+Guardrails:
+- ${body.split("\n")[0]}
+${renderWriteBoundaryGuardrail(language)}`,
+    void 0,
+    language
+  );
+}
+function standaloneWorkflowCopy(command, language) {
+  if (command === "tdd") {
+    return language === "en" ? {
+      description: "Generate per-change TDD manifest and test instructions",
+      title: "Generate the TDD manifest before implementation.",
+      body: "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 add failing tests in the repo before implementation (tests/ edits need user approval per write-boundary)."
+    } : {
+      description: "\u751F\u6210\u672C change \u7684 TDD \u6E05\u5355\u4E0E\u6D4B\u8BD5\u6307\u5F15",
+      title: "\u5728\u5B9E\u65BD\u524D\u751F\u6210 TDD \u6E05\u5355\u3002",
+      body: "\u89C4\u5212\u4EA7\u7269\u5C31\u7EEA\u540E\u3001\u6267\u884C `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\uFF08\u4FEE\u6539 tests/ \u987B\u7B26\u5408 write-boundary\uFF0C\u5148\u83B7\u7528\u6237\u540C\u610F\uFF09\u3002"
+    };
+  }
+  if (command === "test") {
+    return language === "en" ? {
+      description: "Run unit tests scoped to the change TDD manifest",
+      title: "Run change-scoped tests after implementation.",
+      body: "Requires `tdd-manifest.yaml`. Records pass/fail in FET state; `fet verify` is blocked until this passes (unless configured to skip)."
+    } : {
+      description: "\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B",
+      title: "\u5B9E\u73B0\u5B8C\u6210\u540E\u6309 change \u8FD0\u884C\u6D4B\u8BD5\u3002",
+      body: "\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 language === "en" ? {
+    description: "Layout-only visual verification for a change",
+    title: "Run layout-only visual checks for the change.",
+    body: "Default `fet visual` refreshes the manifest, captures with Playwright (`--base-url` required), and runs layout-only checks (no pixel match on dynamic API content). Use `--plan`, `--capture-only`, or `--check-layout-only` only when debugging."
+  } : {
+    description: "change \u7EA7 layout-only \u89C6\u89C9\u9A8C\u6536",
+    title: "\u5BF9 change \u505A layout-only \u89C6\u89C9\u9A8C\u6536\u3002",
+    body: "\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"
+  };
+}
 
 // src/adapters/codex/index.ts
 var CodexAdapter = class {
@@ -6617,7 +7929,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists6(join26(projectRoot, ".codex")) || await exists6(join26(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"
     };
   }
@@ -6656,7 +7968,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir10(dirname9(target), { recursive: true });
+      await mkdir12(dirname11(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -6683,9 +7995,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join26(resolveCodexHome(), file.path);
+    return join30(resolveCodexHome(), file.path);
   }
-  return join26(projectRoot, file.path);
+  return join30(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -6694,18 +8006,18 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join26(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join30(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile20(path, "utf8");
+    return await readFile22(path, "utf8");
   } catch {
     return null;
   }
 }
 async function exists6(path) {
   try {
-    await stat12(path);
+    await stat13(path);
     return true;
   } catch {
     return false;
@@ -6713,8 +8025,8 @@ async function exists6(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir11, readFile as readFile21, stat as stat13 } from "fs/promises";
-import { dirname as dirname10, join as join27 } 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) {
@@ -6729,6 +8041,28 @@ function cursorSpecLanguageRuleFile(language = DEFAULT_LANGUAGE) {
     content: renderCursorSpecLanguageRule(language)
   };
 }
+function cursorWriteBoundaryRuleFile(language = DEFAULT_LANGUAGE) {
+  return {
+    path: ".cursor/rules/fet-write-boundary.mdc",
+    content: renderCursorWriteBoundaryRule(language)
+  };
+}
+function cursorHookFiles() {
+  return [
+    {
+      path: ".cursor/hooks/fet-guard-write-paths.mjs",
+      content: renderCursorWritePathsHookMjs()
+    },
+    {
+      path: ".cursor/hooks/fet-guard-shell-writes.mjs",
+      content: renderCursorShellWriteHookMjs()
+    },
+    {
+      path: ".cursor/hooks.json",
+      content: renderCursorHooksJson()
+    }
+  ];
+}
 function cursorUiDisplayContractRuleFile(language = DEFAULT_LANGUAGE) {
   return {
     path: ".cursor/rules/fet-ui-display-contract.mdc",
@@ -6738,6 +8072,7 @@ function cursorUiDisplayContractRuleFile(language = DEFAULT_LANGUAGE) {
 function cursorRuleFiles(language = DEFAULT_LANGUAGE) {
   return [
     cursorRuleFile(language),
+    cursorWriteBoundaryRuleFile(language),
     cursorFigmaStopRuleFile(language),
     cursorUiDisplayContractRuleFile(language),
     cursorSpecLanguageRuleFile(language)
@@ -6775,6 +8110,7 @@ ${languageInstruction(language)}
 - \u6309 Figma \u5B9E\u73B0 UI \u65F6\u9075\u5B88 \`.cursor/rules/fet-figma-stop.mdc\`\uFF1B\u82E5\u5B58\u5728 \`openspec/changes/<change-id>/.fet/figma-apply-instructions.md\` \u5FC5\u987B\u5728\u6539 UI \u524D\u5B8C\u6574\u6267\u884C\uFF1B\u540C\u76EE\u5F55 \`figma-stop.md\` \u542B\u94FE\u63A5\u4E0E\u505C\u6B62\u89C4\u5219\u3002
 - \u7F16\u5199\u6216\u4FEE\u6539 OpenSpec \`specs/**/spec.md\` \u65F6\u9075\u5B88 \`.cursor/rules/fet-spec-language.mdc\`\uFF08\u82F1\u6587\u89C4\u8303 + \`<!-- \u4E2D\u6587\uFF1A... -->\`\uFF0C\u540C\u6B21\u7F16\u8F91\u540C\u6B65\u66F4\u65B0\u4E2D\u6587\u8BF4\u660E\uFF09\u3002
 - \u7ED1\u5B9A\u63A5\u53E3\u7684 UI \u9075\u5B88 \`.cursor/rules/fet-ui-display-contract.mdc\`\uFF1B\u5B58\u5728 \`openspec/changes/<change-id>/.fet/ui-display-contract.yaml\` \u65F6\u5B9E\u65BD\u524D\u987B\u786E\u8BA4 displayFields\u3002
+- \u4FEE\u6539\u6587\u4EF6\u65F6\u9075\u5B88 \`.cursor/rules/fet-write-boundary.mdc\`\uFF08\u9ED8\u8BA4\u4EC5 \`src/**\`\u3001\`openspec/**\`\u3001\`**/.fet/**\`\uFF1B\u5176\u5B83\u8DEF\u5F84\u987B\u7528\u6237\u660E\u786E\u540C\u610F\uFF09\u3002Cursor hooks \u4F1A\u5BF9\u8D8A\u754C\u5199\u5165\u5F39\u51FA\u5BA1\u6279\u3002
 
 \u5982\u679C\u7528\u6237\u8F93\u5165\u7C7B\u4F3C \`/fet apply\` \u7684\u8BF7\u6C42\uFF0C\u8BF7\u628A\u5B83\u89C6\u4E3A\u5DE5\u4F5C\u6D41\u610F\u56FE\uFF0C\u5E76\u63D0\u793A\u6216\u6267\u884C\u5BF9\u5E94\u7684\u7EC8\u7AEF\u547D\u4EE4 \`fet <cmd>\`\u3002
 `
@@ -6810,7 +8146,9 @@ ${languageInstruction(language)}
 
 \`fet fill-context\` \u53EF\u80FD\u5DF2\u5199\u5165\u5C0F\u7A0B\u5E8F\u5305\u4F53\u79EF\u8868\u4E0E 2MB \u5F00\u53D1\u7EA6\u675F\uFF0C\u4E0D\u8981\u8986\u76D6 AGENTS.md\u300C\u5C0F\u7A0B\u5E8F\u300D\u8282\u4E2D\u7684\u626B\u63CF\u7ED3\u679C\uFF0C\u9664\u975E\u4ED3\u5E93\u7ED3\u6784\u5DF2\u53D8\u3002
 
-\u68C0\u67E5 README\u3001package scripts\u3001\u8DEF\u7531\u3001\u6D4B\u8BD5\u3001\u6E90\u7801\u7ED3\u6784\u548C\u73B0\u6709\u7EA6\u5B9A\u540E\uFF0C\u628A AGENTS.md \u4E2D**\u5176\u4F59** \`[NEEDS LLM INPUT]\` \u6216 \`[NEED LLM INPUT]\` \u5360\u4F4D\u7B26\u66FF\u6362\u4E3A\u5177\u4F53\u3001\u7B80\u6D01\u3001\u9879\u76EE\u76F8\u5173\u7684\u5185\u5BB9\u3002\u4FDD\u7559 FET \u6258\u7BA1\u6807\u8BB0\uFF0C\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002
+\u68C0\u67E5 README\u3001package scripts\u3001\u8DEF\u7531\u3001\u6D4B\u8BD5\u3001\u6E90\u7801\u7ED3\u6784\u548C\u73B0\u6709\u7EA6\u5B9A\u540E\uFF0C\u628A AGENTS.md \u4E2D**\u5176\u4F59** \`[NEEDS LLM INPUT]\` \u6216 \`[NEED LLM INPUT]\` \u5360\u4F4D\u7B26\u66FF\u6362\u4E3A\u5177\u4F53\u3001\u7B80\u6D01\u3001\u9879\u76EE\u76F8\u5173\u7684\u5185\u5BB9\u3002\u4FDD\u7559 FET \u6258\u7BA1\u6807\u8BB0\uFF0C\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002\u4FEE\u6539 \`AGENTS.md\` \u4E0D\u5728\u9ED8\u8BA4\u5199\u8DEF\u5F84\u5185\uFF0C\u987B\u786E\u8BA4\u7528\u6237\u5DF2\u540C\u610F\uFF08\u6216\u7531 hooks \u5BA1\u6279\uFF09\u3002
+
+${renderWriteBoundaryGuardrail(language)}
 `;
   }
   if (command === "graph-setup") {
@@ -6849,6 +8187,9 @@ After installation, verify with \`gitnexus --version\`, then run \`fet graph ini
   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);
   }
@@ -6913,6 +8254,8 @@ ${renderSpecArtifactGuardrail(language)}
 
 ${renderUiDisplayContractGuardrail(language)}
 
+${renderWriteBoundaryGuardrail(language)}
+
 \u6267\u884C\u524D\u8BF7\u9605\u8BFB AGENTS.md\u3001openspec/config.yaml\uFF08\u542B \`fet.specLanguage\`\uFF09\u4E0E\u5F53\u524D change \u5DF2\u6709\u4EA7\u7269\u3002
 `;
 }
@@ -6968,6 +8311,37 @@ ${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
+
+${renderWriteBoundaryGuardrail(language)}
+`;
+}
+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) {
@@ -7007,14 +8381,14 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists7(join27(projectRoot, ".cursor")),
+      detected: await exists7(join31(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
   async planInstall(_projectRoot, language) {
     return {
       tool: this.tool,
-      files: [...cursorSkillFiles(language), ...cursorRuleFiles(language)].map((file) => ({
+      files: [...cursorSkillFiles(language), ...cursorRuleFiles(language), ...cursorHookFiles()].map((file) => ({
         ...file,
         managed: true
       }))
@@ -7024,8 +8398,14 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join27(projectRoot, file.path);
+      const target = join31(projectRoot, file.path);
       const existing = await readExisting2(target);
+      if (file.path === ".cursor/hooks.json") {
+        await mkdir13(dirname12(target), { recursive: true });
+        await atomicWrite(target, mergeCursorHooksJson(existing, file.content));
+        written.push(file.path);
+        continue;
+      }
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
           code: "TOOL_ADAPTER_CONFLICT" /* ToolAdapterConflict */,
@@ -7037,7 +8417,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir11(dirname10(target), { recursive: true });
+      await mkdir13(dirname12(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -7047,14 +8427,16 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join27(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}`));
+      const hooksManaged = file.path === ".cursor/hooks.json" && Boolean(content?.includes('"writeBoundary"'));
+      const hookScript = file.path.startsWith(".cursor/hooks/fet-guard-") && file.path.endsWith(".mjs");
+      const managed = hooksManaged || hookScript || Boolean(content?.includes("FET:MANAGED"));
+      const versionMatches = file.path === ".cursor/hooks.json" ? Boolean(content?.includes('"writeBoundary"')) : hookScript ? Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`)) : Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
       checks.push({
         id: `cursor:${file.path}`,
         status: !content ? "warn" : managed && versionMatches ? "pass" : "warn",
-        message: !content ? `${file.path} \u7F3A\u5931` : !managed ? `${file.path} \u5DF2\u5B58\u5728\uFF0C\u4F46\u4E0D\u7531 FET \u7BA1\u7406` : !versionMatches ? `${file.path} adapterVersion \u5DF2\u8FC7\u671F` : `${file.path} \u5DF2\u5B58\u5728\u4E14\u7248\u672C\u5339\u914D`,
+        message: !content ? `${file.path} \u7F3A\u5931` : !managed ? `${file.path} \u5DF2\u5B58\u5728\uFF0C\u4F46\u4E0D\u7531 FET \u7BA1\u7406` : !versionMatches ? `${file.path} \u7248\u672C\u5DF2\u8FC7\u671F\uFF08\u8BF7\u8FD0\u884C fet init \u66F4\u65B0\uFF09` : `${file.path} \u5DF2\u5B58\u5728\u4E14\u7248\u672C\u5339\u914D`,
         suggestedCommand: !content || !managed || !versionMatches ? "fet init" : void 0
       });
     }
@@ -7063,14 +8445,14 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile21(path, "utf8");
+    return await readFile23(path, "utf8");
   } catch {
     return null;
   }
 }
 async function exists7(path) {
   try {
-    await stat13(path);
+    await stat14(path);
     return true;
   } catch {
     return false;
@@ -7082,13 +8464,13 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir as readdir6, stat as stat14 } from "fs/promises";
-import { join as join28 } from "path";
+import { readdir as readdir6, stat as stat15 } from "fs/promises";
+import { join as join32 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join28(projectRoot, "openspec");
-  const changesPath = join28(openspecPath, "changes");
-  const legacyArchivePath = join28(openspecPath, "archive");
-  const changesArchivePath = join28(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 exists8(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -7096,13 +8478,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join28(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join28(changePath, "tasks.md");
-  const specsPath = join28(changePath, "specs");
+  const changePath = join32(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join32(changePath, "tasks.md");
+  const specsPath = join32(changePath, "specs");
   return {
     changeId,
     exists: await exists8(changePath),
-    hasProposal: await exists8(join28(changePath, "proposal.md")),
+    hasProposal: await exists8(join32(changePath, "proposal.md")),
     hasTasks: await exists8(tasksPath),
     hasSpecs: await exists8(specsPath),
     tasksPath,
@@ -7120,7 +8502,7 @@ async function listDirectories(path, options = {}) {
 }
 async function exists8(path) {
   try {
-    await stat14(path);
+    await stat15(path);
     return true;
   } catch {
     return false;
@@ -7303,13 +8685,13 @@ function escapeRegExp(value) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir7, stat as stat15 } from "fs/promises";
-import { join as join29, relative as relative5, 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 = join29(projectRoot, candidate);
+    const root = join33(projectRoot, candidate);
     if (!await exists9(root)) {
       continue;
     }
@@ -7337,7 +8719,7 @@ async function listFiles(root) {
   const entries = await readdir7(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join29(root, entry.name);
+    const path = join33(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -7348,7 +8730,7 @@ async function listFiles(root) {
 }
 async function exists9(path) {
   try {
-    await stat15(path);
+    await stat16(path);
     return true;
   } catch {
     return false;
@@ -7505,9 +8887,9 @@ async function createCommandContext(command, options) {
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/update/check.ts
-import { mkdir as mkdir12, readFile as readFile22, writeFile } from "fs/promises";
+import { mkdir as mkdir14, readFile as readFile24, writeFile } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname11, join as join30 } 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();
@@ -7580,11 +8962,11 @@ function formatFetUpdateWarning(availability, language) {
 }
 function cachePath() {
   const home = process.env.FET_UPDATE_CHECK_CACHE_HOME?.trim() || homedir2();
-  return join30(home, ".fet", "update-check-cache.json");
+  return join34(home, ".fet", "update-check-cache.json");
 }
 async function readUpdateCheckCache() {
   try {
-    const raw = await readFile22(cachePath(), "utf8");
+    const raw = await readFile24(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.latestVersion !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -7600,7 +8982,7 @@ async function readUpdateCheckCache() {
 }
 async function writeUpdateCheckCache(cache) {
   const path = cachePath();
-  await mkdir12(dirname11(path), { recursive: true });
+  await mkdir14(dirname13(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -7691,6 +9073,19 @@ addGlobalOptions(program.command("tdd").description("\u6839\u636E\u89C4\u5212\u4
 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)
 );