@namewta/speculo 0.8.6 → 0.8.7

package/template/workflows/specdev/P-prototype/tools/materialize-prototype.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const REQUIRED_TARGETS = new Set([
+  "final/index.html",
+  "final/styles.css",
+  "final/app.js",
+]);
+
+const TARGET_LANGUAGE = new Map([
+  ["final/index.html", new Set(["html"])],
+  ["final/styles.css", new Set(["css"])],
+  ["final/app.js", new Set(["javascript", "js"])],
+]);
+
+export function extractPrototypeSources(markdown) {
+  const pattern = /<!-- PROTOTYPE-FILE: ([^\r\n]+) -->\r?\n```(html|css|javascript|js)\r?\n([\s\S]*?)\r?\n```\r?\n<!-- \/PROTOTYPE-FILE -->/g;
+  const sources = new Map();
+
+  for (const match of markdown.matchAll(pattern)) {
+    const target = match[1].trim().replaceAll("\\", "/");
+    if (isAbsolute(target) || !TARGET_LANGUAGE.has(target)) {
+      throw new Error(`unsupported prototype target: ${target}`);
+    }
+    if (!TARGET_LANGUAGE.get(target).has(match[2])) throw new Error(`invalid code fence language for ${target}: ${match[2]}`);
+    if (sources.has(target)) throw new Error(`duplicate prototype target: ${target}`);
+    sources.set(target, `${match[3].replaceAll("\r\n", "\n")}\n`);
+  }
+
+  const openingCount = markdown.match(/<!-- PROTOTYPE-FILE:/g)?.length ?? 0;
+  const closingCount = markdown.match(/<!-- \/PROTOTYPE-FILE -->/g)?.length ?? 0;
+  if (openingCount !== 3 || closingCount !== 3 || sources.size !== 3) {
+    throw new Error(`expected exactly three paired PROTOTYPE-FILE blocks; found ${openingCount} openings, ${closingCount} closings, ${sources.size} valid blocks`);
+  }
+
+  for (const target of REQUIRED_TARGETS) {
+    if (!sources.has(target)) throw new Error(`missing prototype source block: ${target}`);
+  }
+
+  return sources;
+}
+
+function resolveInside(root, target) {
+  const destination = resolve(root, ...target.split("/"));
+  const local = relative(root, destination);
+  if (!local || local.startsWith(`..${sep}`) || local === ".." || isAbsolute(local)) {
+    throw new Error(`prototype target escapes design package: ${target}`);
+  }
+  return destination;
+}
+
+async function assertNoSymlink(root, target) {
+  let current = root;
+  const local = relative(root, target);
+  for (const segment of ["", ...local.split(sep).filter(Boolean)]) {
+    if (segment) current = join(current, segment);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) throw new Error(`prototype path must not contain symlinks: ${current}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+
+async function atomicWrite(destination, content) {
+  await mkdir(dirname(destination), { recursive: true });
+  const temporary = `${destination}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(temporary, content, "utf8");
+  try {
+    await rename(temporary, destination);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function materialize(markdownPath, { check = false } = {}) {
+  const absoluteMarkdown = resolve(markdownPath);
+  const root = dirname(absoluteMarkdown);
+  const markdown = await readFile(absoluteMarkdown, "utf8");
+  const sources = extractPrototypeSources(markdown);
+  const mismatches = [];
+
+  for (const [target, expected] of sources) {
+    const destination = resolveInside(root, target);
+    await assertNoSymlink(root, destination);
+    if (check) {
+      let actual;
+      try {
+        actual = await readFile(destination, "utf8");
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          mismatches.push(`${target}: missing`);
+          continue;
+        }
+        throw error;
+      }
+      if (actual !== expected) mismatches.push(`${target}: differs from design-system.md`);
+    } else {
+      await atomicWrite(destination, expected);
+    }
+  }
+
+  if (mismatches.length > 0) throw new Error(mismatches.join("\n"));
+  return [...sources.keys()];
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const check = args.includes("--check");
+  const paths = args.filter((arg) => arg !== "--check");
+  if (paths.length !== 1) throw new Error("usage: materialize-prototype.mjs [--check] <design-system.md>");
+  const targets = await materialize(paths[0], { check });
+  console.log(`${check ? "verified" : "materialized"} ${targets.length} prototype files`);
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/template/workflows/specdev/P-prototype/tools/validate-design-package.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { extractPrototypeSources, materialize } from "./materialize-prototype.mjs";
+
+const REQUIRED_HEADINGS = [
+  "## Project Evidence",
+  "## Style Decision",
+  "## Foundation Tokens",
+  "## Component and State Contract",
+  "## Interaction Contract",
+  "## Responsive Contract",
+  "## Prototype Sources",
+  "## Validation and Handoff",
+];
+
+function frontmatterValue(header, key) {
+  const match = header.match(new RegExp(`^${key}:\\s*(.*?)\\s*$`, "m"));
+  if (!match) return undefined;
+  const value = match[1].trim();
+  if (value === "null") return null;
+  if (/^\d+$/.test(value)) return Number(value);
+  return value.replace(/^['"]|['"]$/g, "");
+}
+
+function frontmatterArray(header, key) {
+  const value = frontmatterValue(header, key);
+  if (typeof value !== "string" || !value.startsWith("[") || !value.endsWith("]")) return [];
+  return value.slice(1, -1).split(",").map((item) => item.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+}
+
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function isSymlink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function validate(path, { allowDraft = false } = {}) {
+  const designPath = resolve(path);
+  if (await isSymlink(designPath)) throw new Error("design-system.md must not be a symlink");
+  const markdown = await readFile(designPath, "utf8");
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  const errors = [];
+  if (!match) throw new Error("design-system.md requires YAML frontmatter");
+  const [, header, body] = match;
+  const meta = {
+    schemaVersion: frontmatterValue(header, "schema_version"),
+    artifact: frontmatterValue(header, "artifact"),
+    change: frontmatterValue(header, "change"),
+    designId: frontmatterValue(header, "design_id"),
+    status: frontmatterValue(header, "status"),
+    projectKind: frontmatterValue(header, "project_kind"),
+    platforms: frontmatterArray(header, "platforms"),
+    candidates: frontmatterArray(header, "style_candidates"),
+    selectedStyle: frontmatterValue(header, "selected_style"),
+    density: frontmatterValue(header, "density"),
+    colorMode: frontmatterValue(header, "color_mode"),
+    researchSnapshot: frontmatterValue(header, "research_snapshot"),
+    prototypeFiles: frontmatterArray(header, "prototype_files"),
+    updatedAt: frontmatterValue(header, "updated_at"),
+  };
+
+  const designRoot = dirname(designPath);
+  const expectedDesignId = basename(designRoot);
+  const expectedChange = basename(dirname(dirname(designRoot)));
+  if (meta.schemaVersion !== 2 || meta.artifact !== "ui-design-system") errors.push("artifact/schema_version must be ui-design-system/2");
+  if (!/^UI-\d{3,}$/.test(String(meta.designId ?? "")) || meta.designId !== expectedDesignId) errors.push("design_id must match the UI-NNN directory");
+  if (meta.change !== expectedChange) errors.push("change must match the owning change directory");
+  if (!new Set(["detecting", "selecting", "ready", "blocked"]).has(meta.status)) errors.push("invalid design status");
+  if (!new Set(["existing", "new"]).has(meta.projectKind)) errors.push("project_kind must be existing or new");
+  if (!meta.platforms.length || meta.platforms.some((value) => !new Set(["desktop", "web", "mobile"]).has(value))) errors.push("platforms must contain desktop, web, or mobile");
+  if (meta.candidates.length < 2 || meta.candidates.length > 4 || new Set(meta.candidates).size !== meta.candidates.length) errors.push("style_candidates must contain 2-4 unique values");
+  if (meta.researchSnapshot !== "49b5659") errors.push("research_snapshot must equal 49b5659");
+  for (const required of ["final/index.html", "final/styles.css", "final/app.js"]) {
+    if (!meta.prototypeFiles.includes(required)) errors.push(`prototype_files must include ${required}`);
+  }
+  if (typeof meta.updatedAt !== "string" || Number.isNaN(Date.parse(meta.updatedAt))) errors.push("updated_at must be ISO-8601");
+  for (const heading of REQUIRED_HEADINGS) if (!body.includes(heading)) errors.push(`missing '${heading}'`);
+  if (/(?:[A-Za-z]:[\\/]|\/(?:Users|home|tmp)\/)/.test(markdown)) errors.push("design package contains a machine-specific absolute path");
+
+  let sources;
+  try {
+    sources = extractPrototypeSources(markdown);
+  } catch (error) {
+    errors.push(error.message);
+  }
+
+  if (meta.status === "ready" && !allowDraft) {
+    if (!meta.selectedStyle || !meta.candidates.includes(meta.selectedStyle)) errors.push("ready design requires selected_style from style_candidates");
+    if (!new Set(["compact", "default", "comfortable", "touch"]).has(meta.density)) errors.push("ready design requires a density");
+    if (!new Set(["light", "dark", "system", "both"]).has(meta.colorMode)) errors.push("ready design requires a color_mode");
+    const comparisonIndex = join(designRoot, "comparison", "index.html");
+    const variantsRoot = join(designRoot, "comparison", "variants");
+    if (!(await isFile(comparisonIndex))) errors.push("ready design requires comparison/index.html");
+    if (await isSymlink(comparisonIndex)) errors.push("comparison/index.html must not be a symlink");
+    if (await isSymlink(join(designRoot, "comparison")) || await isSymlink(variantsRoot)) errors.push("comparison directories must not be symlinks");
+    let variants = [];
+    try {
+      variants = (await readdir(variantsRoot)).filter((entry) => entry.endsWith(".html"));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (variants.length < 2 || variants.length > 4) errors.push("ready design requires 2-4 comparison variant HTML files");
+    for (const variant of variants) {
+      if (await isSymlink(join(variantsRoot, variant))) errors.push(`comparison variant must not be a symlink: ${variant}`);
+    }
+    if (await isSymlink(join(designRoot, "final"))) errors.push("final directory must not be a symlink");
+    if (sources) {
+      try {
+        await materialize(designPath, { check: true });
+      } catch (error) {
+        errors.push(error.message);
+      }
+      const html = sources.get("final/index.html") ?? "";
+      const css = sources.get("final/styles.css") ?? "";
+      const js = sources.get("final/app.js") ?? "";
+      if (!/href=["']styles\.css["']/.test(html) || !/src=["']app\.js["']/.test(html)) errors.push("final HTML must reference relative styles.css and app.js");
+      if (/<(?:script|link)[^>]+(?:src|href)=["']https?:/i.test(html)) errors.push("final HTML must not load remote scripts or styles");
+      if (!css.includes(":focus-visible")) errors.push("final CSS must define :focus-visible");
+      if (!css.includes("prefers-reduced-motion")) errors.push("final CSS must handle prefers-reduced-motion");
+      if (!js.includes("addEventListener")) errors.push("final JS must implement an explicit interaction");
+    }
+  }
+
+  if (errors.length) throw new Error(errors.join("\n"));
+  return meta;
+}
+
+const args = process.argv.slice(2);
+const allowDraft = args.includes("--allow-draft");
+const paths = args.filter((arg) => arg !== "--allow-draft");
+if (paths.length !== 1) {
+  console.error("usage: validate-design-package.mjs [--allow-draft] <design-system.md>");
+  process.exitCode = 1;
+} else {
+  validate(paths[0], { allowDraft })
+    .then((meta) => console.log(`valid ${meta.designId} (${meta.status})`))
+    .catch((error) => {
+      console.error(error.message);
+      process.exitCode = 1;
+    });
+}

package/template/workflows/specdev/README.md

@@ -50,9 +50,13 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
 
+`{design-id}` 由 P-prototype 在当前 change 内分配为最小未占用的 `UI-NNN`；设计系统文档是设计权威，comparison 与 final 是其可运行投影。
+
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
 ## 持久化约定
@@ -98,7 +102,9 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
 
 ## 全局治理原则
@@ -156,7 +162,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 
 `active[].change` 必须唯一，且不得同时出现在 `archived`。开始 Work 时设置 `current_work`；暂停或可恢复阻塞时保留；成功完成时加入 `works_run` 并清空；取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载，不写入全局索引。
 
-`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning 原型变体字段均为可配置正整数，初始化时写入默认值；仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
+`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning UI 设计候选字段均为可配置正整数；候选默认值与上限必须落在 2-4 且默认值不大于上限。仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
 
 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent；required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录；父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态，必须保留全部集成与 E2E 证据。
 
@@ -189,7 +195,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
 | 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
 | 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
-| 需要用代码回答逻辑/UI 问题 | P-prototype | G / S / T / I |
+| 需要检测项目 UI、选择设计方向并生成可运行设计包 | P-prototype | G / S / T / I |
 | 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
 | 外部行为已清楚 | S-spec | T-tickets |
 | Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
@@ -210,7 +216,7 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 - **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
 - **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
 - **P-goal-plan** — 目标规划：在跨 Ticket 协调复杂度需要时，以固定 Lead、动态派单、DAG/Gate 和候选合并门禁生成决策完备且可恢复的执行计划。
-- **P-prototype** — 原型：在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
+- **P-prototype** — UI 设计原型：检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
 - **R-review-architecture** — 架构审查：从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
 - **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
 - **T-tickets** — 拆分 Tickets：将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。

package/template/workflows/specdev/T-triage/T-triage.md

@@ -38,7 +38,7 @@ Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间，`<Path>
    - 根因未知的 bug → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
    - 产品或架构决定未锁定 → `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
    - 路径超出单次上下文 → `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
-   - 需要可运行原型回答设计问题 → `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>`；
+   - 需要检测项目 UI、比较风格候选并固化可运行设计包 → `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>`；
    - 外部行为明确 → `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
    - 固定点 diff 或 PR 审查 → `<Path>{roots.workflows}/specdev/C-code-review/C-code-review.md</Path>`；
    - 小型明确变更 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 或获批 Direct Spec。

package/template/workflows/specdev/W-wayfinder/W-wayfinder.md

@@ -47,7 +47,7 @@ Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图
 每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
 - **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
-- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` 回答一个 UI/逻辑问题，并把 record、临时 branch/worktree 和运行 URL 链接为 solution comment 资产；P 不实现目的地。
+- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` 检测项目 UI、比较功能风格候选并逐步确认设计方向，把 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>` 与 comparison locator 链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
 - **Grilling（HITL）**：对话。调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
 - **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
 

package/template/workflows/specdev/common/README.md

@@ -37,14 +37,14 @@
 - 分诊：`<Path>{roots.workflows}/specdev/common/schemas/triage.schema.json</Path>`
 - 诊断：`<Path>{roots.workflows}/specdev/common/schemas/diagnosis.schema.json</Path>`
 - 代码审查：`<Path>{roots.workflows}/specdev/common/schemas/code-review.schema.json</Path>`
-- 原型记录：`<Path>{roots.workflows}/specdev/common/schemas/prototype-record.schema.json</Path>`
+- UI 设计包：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`
 
 ## 工具与 Skill
 
 - 包与 change 校验器：`<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
 - 校验器说明：`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
 - 外部技术研究 Skill：`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
-- Ticket/原型 worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；仅 required Ticket 使用 source → parent-candidate → parent 状态机，current Ticket 使用 current workspace/direct-parent，原型保持临时生命周期
+- Ticket worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；仅 required Ticket 使用 source → parent-candidate → parent 状态机，current Ticket 使用 current workspace/direct-parent
 - 动态 Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；P-goal-plan 建立 Lead 合同，I-implement 在执行期派单与验收
 - 双轴代码审查 Skill：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
 

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -19,13 +19,15 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| 原型记录 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
+| UI 设计包 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+
 Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `<Path>{roots.state}/specdev/context/</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
 
 ## 2. 权威顺序

package/template/workflows/specdev/common/schemas/config.schema.json

@@ -40,19 +40,19 @@
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
         "require_evidence": {"type": "boolean"},
-        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
-        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
+        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
+        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
       },
       "additionalProperties": true
     }
   },
   "allOf": [{
-    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
   }],
   "additionalProperties": false
 }

package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: dev-worktree
-description: 管理 SpecDev required Ticket 或原型的 Git worktree；为 required Ticket 创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
+description: 管理 SpecDev required Ticket 的 Git worktree；创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
 ---
 
 # Dev Worktree
 
-本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。`purpose=prototype` 只使用调用方批准的临时生命周期。
+本 Skill 由 T-tickets、P-goal-plan 和 I-implement 复用。仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。
 
 ## 输入
 
 - `operation=create | restore | finalize | remove`；
-- `purpose=ticket | prototype`；
+- `purpose=ticket`；
 - repository、父分支、`base_sha`、branch、portable workspace locator；
 - workspace、implementation 和 integration owner；
 - 允许动作、路径合同、验证合同、调用方状态记录位置。
@@ -39,7 +39,7 @@ implementation owner 只在来源 worktree 修改授权项目路径，运行 Tic
 
 ## 4. 移除
 
-`operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
+`operation=remove` 先验证 Ticket 已 `integrated`、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
 
 **完成标准**：只删除精确授权目标；失败保留现场与恢复命令。
 

package/template/workflows/specdev/common/skills/dev-worktree/references/create.md

@@ -8,14 +8,12 @@
 - `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`；
 - 目标 branch/worktree 不覆盖现有用户 workspace，路径合同无冲突。
 
-Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问题、owner、locator 和清理策略；它不写 Ticket worktree 状态。
-
 ## 创建 Ticket 来源 worktree
 
 1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs；父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞；
 2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`；
 3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前 Ticket；
-4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket/原型目录；
+4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket 目录；
 5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同；
 6. 安装实际需要的依赖，运行最小非 E2E 基线；
 7. Lead 写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`，状态为 `active`。

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -465,10 +465,21 @@ function validateDocumentReferences(root) {
   const errors = [];
   const warnings = [];
   const entries = walk(root);
-  const knownFiles = new Set(entries.filter(isFile).map((path) => basename(path)));
-  const knownDirectories = new Set(entries.filter(isDirectory).map((path) => basename(path)));
+  const frozenResearchRoot = join(
+    root,
+    "P-prototype",
+    "design-library",
+    "research-snapshot",
+  );
+  const governedEntries = entries.filter(
+    (path) => path !== frozenResearchRoot && !path.startsWith(`${frozenResearchRoot}${sep}`),
+  );
+  const knownFiles = new Set(governedEntries.filter(isFile).map((path) => basename(path)));
+  const knownDirectories = new Set(governedEntries.filter(isDirectory).map((path) => basename(path)));
 
-  for (const path of entries.filter(
+  // The pinned research snapshot preserves its upstream relative links and HTML
+  // asset paths byte-for-byte. Global template link checks still validate it.
+  for (const path of governedEntries.filter(
     (item) => isFile(item) && [".md", ".html"].includes(extname(item).toLowerCase()),
   )) {
     const label = toPosix(relative(root, path));
@@ -682,12 +693,13 @@ function validateExecutionContractAssets(root) {
     configTemplate.execution.max_implementation_agents < 1 ||
     !Number.isInteger(configTemplate.execution?.max_integration_attempts) ||
     configTemplate.execution.max_integration_attempts < 1 ||
-    !Number.isInteger(configTemplate.planning?.ui_prototype_default_variants) ||
-    !Number.isInteger(configTemplate.planning?.ui_prototype_max_variants) ||
-    configTemplate.planning.ui_prototype_default_variants < 1 ||
-    configTemplate.planning.ui_prototype_max_variants < configTemplate.planning.ui_prototype_default_variants
+    !Number.isInteger(configTemplate.planning?.ui_design_default_candidates) ||
+    !Number.isInteger(configTemplate.planning?.ui_design_max_candidates) ||
+    configTemplate.planning.ui_design_default_candidates < 2 ||
+    configTemplate.planning.ui_design_max_candidates > 4 ||
+    configTemplate.planning.ui_design_max_candidates < configTemplate.planning.ui_design_default_candidates
   ) {
-    errors.push("config-template.json must define SpecDev config v5 with positive execution limits and valid prototype variant bounds");
+    errors.push("config-template.json must define SpecDev config v5 with positive execution limits and valid UI design candidate bounds");
   }
   for (const obsolete of ["auto_commit", "worktree_for_parallel", "max_parallel"]) {
     if (JSON.stringify(configTemplate).includes(`\"${obsolete}\"`)) {
@@ -816,7 +828,7 @@ function capabilityChecks(root) {
       "prototype",
       [
         join(root, "P-prototype", "P-prototype.md"),
-        ["一个问题", "Logic", "UI", "临时 branch/worktree", "promotion target", "main"],
+        ["设计定向", "风格", "design-system.md", "comparison", "HTML/CSS/JS", "design-library/INDEX.md"],
       ],
     ],
     [
@@ -1196,31 +1208,78 @@ function validateReviews(change, required, errors) {
 
 function validatePrototypes(change, required, errors) {
   const root = join(change, "prototypes");
-  const paths = isDirectory(root)
-    ? walk(root).filter((path) => isFile(path) && basename(path) === "record.md").sort()
-    : [];
-  if (required && !paths.length) errors.push("prototype stage requires a prototypes/<id>/record.md artifact");
-  for (const path of paths) {
-    const { meta, body } = parseFrontmatter(path);
-    const label = toPosix(relative(change, path));
-    if (meta.schema_version !== 1 || meta.artifact !== "prototype-record") {
-      errors.push(`${label}: artifact/schema_version must be prototype-record/1`);
+  if (!isDirectory(root)) {
+    if (required) errors.push("prototype stage requires a prototypes/UI-NNN/design-system.md artifact");
+    return [];
+  }
+
+  const validator = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "P-prototype",
+    "tools",
+    "validate-design-package.mjs",
+  );
+  const paths = [];
+  let readyCount = 0;
+
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const entryPath = join(root, entry.name);
+    const label = toPosix(relative(change, entryPath));
+    if (entry.isSymbolicLink()) {
+      errors.push(`${label}: prototype design directories and files must not be symlinks`);
+      continue;
     }
-    if (meta.change !== basename(change)) errors.push(`${label}: change must equal directory name`);
-    if (!/^PROTO-\d{3,}$/.test(String(meta.prototype_id ?? ""))) errors.push(`${label}: invalid prototype_id`);
-    if (!new Set(["logic", "ui"]).has(meta.branch)) errors.push(`${label}: invalid prototype branch`);
-    if (!new Set(["active", "answered", "blocked", "discarded"]).has(meta.status)) errors.push(`${label}: invalid prototype status`);
-    if (typeof meta.workspace_ref !== "string" || ABSOLUTE_MACHINE_PATH_RE.test(meta.workspace_ref)) {
-      errors.push(`${label}: workspace_ref must be a portable locator`);
+    if (!entry.isDirectory()) {
+      errors.push(`${label}: prototypes may only contain UI-NNN design directories`);
+      continue;
+    }
+    if (!/^UI-\d{3,}$/.test(entry.name)) {
+      errors.push(`${label}: prototype design directory must use UI-NNN`);
+      continue;
     }
-    if (meta.status === "answered" && (!String(meta.winner ?? "").trim() || !String(meta.promotion_target ?? "").trim())) {
-      errors.push(`${label}: answered prototype requires winner and promotion_target`);
+
+    const designPath = join(entryPath, "design-system.md");
+    if (!isFile(designPath)) {
+      errors.push(`${label}: missing design-system.md`);
+      continue;
+    }
+    paths.push(designPath);
+    const { meta } = parseFrontmatter(designPath);
+    if (meta.status === "ready") readyCount += 1;
+    try {
+      execFileSync(process.execPath, [validator, designPath], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      const details = String(error.stderr || error.stdout || error.message)
+        .trim()
+        .split(/\r?\n/)
+        .filter(Boolean);
+      if (!details.length) errors.push(`${label}: design package validation failed`);
+      for (const detail of details) errors.push(`${label}: ${detail}`);
     }
-    if (!new Set(["pending", "clean", "registered"]).has(meta.cleanup_status)) errors.push(`${label}: invalid cleanup_status`);
-    for (const heading of ["## Question and Assumption", "## Run and Assets", "## Evaluation", "## Promotion and Cleanup"]) {
-      if (!body.includes(heading)) errors.push(`${label}: missing '${heading}'`);
+  }
+
+  const obsoleteRecords = walk(root).filter(
+    (path) => isFile(path) && basename(path) === "record.md",
+  );
+  for (const path of obsoleteRecords) {
+    errors.push(`${toPosix(relative(change, path))}: obsolete prototype record is forbidden; use UI-NNN/design-system.md`);
+  }
+  const discoveredDesigns = walk(root).filter(
+    (path) => isFile(path) && basename(path) === "design-system.md",
+  );
+  for (const path of discoveredDesigns) {
+    if (!paths.includes(path)) {
+      errors.push(`${toPosix(relative(change, path))}: design-system.md must be directly under prototypes/UI-NNN`);
     }
   }
+  if (required && readyCount === 0) {
+    errors.push("prototype stage requires at least one ready UI design package");
+  }
   return paths;
 }