@namewta/speculo 0.8.5 → 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

@@ -18,7 +18,7 @@ SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责
         ↓
 Triage 冻结为本地 Source
         ↓
-Diagnose / Grill / ELI5 / Wayfinder / Prototype / Code Review / Architecture Review
+Diagnose / Grill / Wayfinder / Prototype / Code Review / Architecture Review
         ↓
 Spec             外部行为、范围、验收合同与关键约束
         ↓
@@ -50,9 +50,12 @@ 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>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
+
+`{design-id}` 由 P-prototype 在当前 change 内分配为最小未占用的 `UI-NNN`；设计系统文档是设计权威，comparison 与 final 是其可运行投影。
 
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
@@ -99,9 +102,10 @@ 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>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
 
 ## 全局治理原则
 
@@ -158,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 证据。
 
@@ -190,9 +194,8 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 | 本地 change 完成且来源可关闭 | T-triage reconcile | A |
 | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
 | 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
-| 需要向刚上大一、没有专业背景的读者做 Markdown 与 ASCII 图解 | E-eli5 | 返回用户 / 继续当前 change |
 | 路径超出单次上下文 | 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 |
@@ -209,13 +212,11 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 - **A-archive-and-consolidate** — 归档与沉淀：校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
 - **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
 - **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
-- **E-eli5** — 零基础新生解释：面向刚上大一、没有专业背景的读者解释一个主题；用 Markdown 和 ASCII 图解说明概念、数据与调用如何流动。
-- **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
 - **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
 - **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,14 +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 和清理 | 生产实现或多个问题的计划 |
-| 零基础新生图解 | `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
+| 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`。