@namewta/speculo 0.8.5 → 0.8.7

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

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CHANGE_NAME = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DOMAIN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const WORK_ID = /^learning\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CHANGE_STATUS = new Set(["active", "blocked", "awaiting_retention", "completed", "archived"]);
+const PHASE = new Set(["intake", "assessment", "teaching", "practice", "immediate_quiz", "retention", "ready_to_archive", "archived"]);
+const DOMAIN_TYPE = new Set(["project", "product", "subject", "language", "skill"]);
+const RESULT = new Set(["not_attempted", "failed", "passed", "needs_review"]);
+const KNOWLEDGE_STATUS = new Set(["mastered", "review_due", "needs_refresh", "superseded"]);
+const EXPECTED_WORKS = new Set([
+  "A-archive-and-consolidate",
+  "A-assess-and-plan",
+  "E-eli5",
+  "I-init-setup",
+  "P-practice",
+  "Q-quiz",
+  "R-review",
+]);
+
+function parseArgs(argv) {
+  const result = { workflowRoot: null, stateRoot: null, stage: null, change: null, selfCheck: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--workflow-root") result.workflowRoot = resolve(argv[++index] ?? "");
+    else if (arg === "--state-root") result.stateRoot = resolve(argv[++index] ?? "");
+    else if (arg === "--stage") result.stage = argv[++index] ?? null;
+    else if (arg === "--change") result.change = argv[++index] ?? null;
+    else if (arg === "--self-check") result.selfCheck = true;
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  if (!result.workflowRoot && !result.stateRoot && !result.selfCheck) {
+    throw new Error("use --workflow-root <path>, --state-root <path>, or --self-check");
+  }
+  if (result.stage && !new Set(["pre-archive", "complete"]).has(result.stage)) {
+    throw new Error("--stage must be pre-archive or complete");
+  }
+  if (result.stage && !result.change) throw new Error("--stage requires --change");
+  if (result.change && !CHANGE_NAME.test(result.change)) throw new Error("--change has an invalid name");
+  return result;
+}
+
+function isFile(path) {
+  return existsSync(path) && statSync(path).isFile();
+}
+
+function isDirectory(path) {
+  return existsSync(path) && statSync(path).isDirectory();
+}
+
+function readJson(path, label, errors) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    errors.push(`${label}: invalid JSON (${error.message})`);
+    return null;
+  }
+}
+
+function walk(root) {
+  if (!isDirectory(root)) return [];
+  const files = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...walk(path));
+    else if (entry.isFile()) files.push(path);
+  }
+  return files;
+}
+
+function sameMembers(actual, expected) {
+  return actual.size === expected.size && [...actual].every((item) => expected.has(item));
+}
+
+function duplicates(values) {
+  const seen = new Set();
+  return values.filter((value) => seen.has(value) || !seen.add(value));
+}
+
+function validDateTime(value) {
+  return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+
+function validateWorkflowRoot(root, errors) {
+  const indexPath = join(root, "INDEX.md");
+  const readmePath = join(root, "README.md");
+  const seedPath = join(root, "_state", "status.json");
+  const runtimePath = join(root, "runtime-contract.json");
+  for (const path of [indexPath, readmePath, seedPath, runtimePath]) {
+    if (!isFile(path)) errors.push(`${path}: required workflow file is missing`);
+  }
+  if (errors.length) return;
+
+  const index = readFileSync(indexPath, "utf8");
+  const readme = readFileSync(readmePath, "utf8");
+  if (!/^id: learning$/m.test(index) || !/^type: workflow$/m.test(index) || !/^workflow: learning$/m.test(index)) {
+    errors.push("INDEX.md: identity must be learning/type workflow");
+  }
+  for (const heading of ["## 永久知识", "## Work 激活"]) {
+    if (!index.includes(heading)) errors.push(`INDEX.md: missing ${heading}`);
+  }
+  if (!index.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push("INDEX.md: missing activation pointer");
+  if ((readme.match(/AUTO-INDEX-START/g) ?? []).length !== 1 || (readme.match(/AUTO-INDEX-END/g) ?? []).length !== 1) {
+    errors.push("README.md: requires one AUTO-INDEX marker pair");
+  }
+
+  const works = new Set(readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && /^[A-Z]-/.test(entry.name))
+    .map((entry) => entry.name));
+  if (!sameMembers(works, EXPECTED_WORKS)) {
+    errors.push(`workflow works mismatch: expected ${[...EXPECTED_WORKS].sort().join(", ")}; found ${[...works].sort().join(", ")}`);
+  }
+  for (const work of works) {
+    const path = join(root, work, `${work}.md`);
+    if (!isFile(path)) {
+      errors.push(`${work}: missing same-named entry`);
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    if (!text.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push(`${work}: missing activation contract reference`);
+    if (!/^workflow: learning$/m.test(text) || !/^type: workflow-entry$/m.test(text)) errors.push(`${work}: invalid frontmatter identity`);
+  }
+
+  const seed = readJson(seedPath, "_state/status.json", errors);
+  if (seed && (seed.schema_version !== 1 || seed.workflow !== "learning" || !Array.isArray(seed.active) || !Array.isArray(seed.archived))) {
+    errors.push("_state/status.json: expected empty learning schema v1 status");
+  }
+  const runtime = readJson(runtimePath, "runtime-contract.json", errors);
+  if (runtime && (runtime.schema_version !== 1 || runtime.workflow !== "learning" || runtime.config !== null || runtime.opaque_default !== "preserve-byte-for-byte")) {
+    errors.push("runtime-contract.json: invalid learning contract");
+  }
+  for (const schema of ["status.schema.json", "change-status.schema.json"]) {
+    readJson(join(root, "common", "schemas", schema), `common/schemas/${schema}`, errors);
+  }
+
+  for (const path of walk(root).filter((candidate) => candidate.toLowerCase().endsWith(".md"))) {
+    if (/```mermaid\b/i.test(readFileSync(path, "utf8"))) {
+      errors.push(`${relative(root, path)}: Learning diagrams must use fenced ASCII text, not Mermaid`);
+    }
+  }
+
+  const teachingContracts = [
+    [join(root, "E-eli5", "E-eli5.md"), ["5 岁的小孩", "大一新生", "ASCII", "不得生成 Mermaid"]],
+    [join(root, "E-eli5", "lesson-template.md"), ["## 教学表达基线", "5 岁的小孩", "大一新生", "```text"]],
+    [join(root, "common", "rules", "teaching-policy.md"), ["5 岁的小孩", "大一新生", "默认使用", "纯文本 ASCII"]],
+    [join(root, "I-init-setup", "learner-profile-template.md"), ["教学表达基线", "5 岁的小孩", "仅纯文本 ASCII"]],
+  ];
+  for (const [path, requiredMarkers] of teachingContracts) {
+    if (!isFile(path)) {
+      errors.push(`${relative(root, path)}: required teaching contract is missing`);
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    for (const marker of requiredMarkers) {
+      if (!text.includes(marker)) errors.push(`${relative(root, path)}: missing '${marker}'`);
+    }
+  }
+}
+
+function validateGlobalStatus(status, errors) {
+  if (!status) return;
+  if (status.schema_version !== 1 || status.workflow !== "learning" || !Array.isArray(status.active) || !Array.isArray(status.archived)) {
+    errors.push("status.json: expected learning schema v1 with active and archived arrays");
+    return;
+  }
+  const activeNames = [];
+  for (const [index, entry] of status.active.entries()) {
+    const label = `status.json active[${index}]`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      errors.push(`${label}: must be an object`);
+      continue;
+    }
+    if (!CHANGE_NAME.test(entry.change ?? "")) errors.push(`${label}: invalid change`);
+    if (!DOMAIN.test(entry.domain ?? "")) errors.push(`${label}: invalid domain`);
+    if (typeof entry.topic !== "string" || !entry.topic.trim()) errors.push(`${label}: topic is required`);
+    if (!(entry.current_work === null || WORK_ID.test(entry.current_work ?? ""))) errors.push(`${label}: invalid current_work`);
+    if (!Array.isArray(entry.works_run) || entry.works_run.some((item) => !WORK_ID.test(item)) || duplicates(entry.works_run ?? []).length) {
+      errors.push(`${label}: works_run must contain unique learning work ids`);
+    }
+    activeNames.push(entry.change);
+  }
+  if (duplicates(activeNames).length || duplicates(status.archived).length) errors.push("status.json: duplicate change names");
+  for (const name of status.archived) {
+    if (!CHANGE_NAME.test(name)) errors.push(`status.json: invalid archived change ${name}`);
+    if (activeNames.includes(name)) errors.push(`status.json: ${name} is both active and archived`);
+  }
+}
+
+function validateMasteryGate(changeStatus, label, errors) {
+  const mastery = changeStatus.mastery;
+  if (!mastery || typeof mastery !== "object" || Array.isArray(mastery)) {
+    errors.push(`${label}: mastery is required`);
+    return;
+  }
+  if (!RESULT.has(mastery.immediate) || !RESULT.has(mastery.retention)) errors.push(`${label}: invalid mastery result`);
+  if (mastery.score !== null && (typeof mastery.score !== "number" || mastery.score < 0 || mastery.score > 100)) errors.push(`${label}: invalid mastery score`);
+  if (typeof mastery.critical_objectives_passed !== "boolean" || typeof mastery.transfer_passed !== "boolean") errors.push(`${label}: mastery booleans are required`);
+  if (!Array.isArray(mastery.blocking_misconceptions) || !Array.isArray(mastery.evidence)) errors.push(`${label}: mastery arrays are required`);
+  if (!(mastery.next_review_at === null || validDateTime(mastery.next_review_at))) errors.push(`${label}: invalid next_review_at`);
+
+  if (changeStatus.change_status === "awaiting_retention" && mastery.immediate !== "passed") {
+    errors.push(`${label}: awaiting_retention requires immediate passed`);
+  }
+  if (["completed", "archived"].includes(changeStatus.change_status)) {
+    if (mastery.immediate !== "passed" || mastery.retention !== "passed") errors.push(`${label}: completed knowledge requires both mastery gates passed`);
+    if (typeof mastery.score !== "number" || mastery.score < 80) errors.push(`${label}: completed knowledge requires score >= 80`);
+    if (!mastery.critical_objectives_passed) errors.push(`${label}: completed knowledge requires all critical objectives`);
+    if (!mastery.transfer_passed) errors.push(`${label}: completed knowledge requires transfer evidence`);
+    if (mastery.blocking_misconceptions.length) errors.push(`${label}: completed knowledge has blocking misconceptions`);
+    if (mastery.evidence.length < 2 || !mastery.evidence.some((item) => /\/quiz\/immediate-/.test(item)) || !mastery.evidence.some((item) => /\/quiz\/retention-/.test(item))) {
+      errors.push(`${label}: completed knowledge requires immediate and retention result evidence`);
+    }
+  }
+}
+
+function validateChangeStatus(value, expectedName, expectedArchived, errors) {
+  const label = `${expectedName}/.status.json`;
+  if (!value) return;
+  if (value.schema_version !== 1 || value.artifact !== "learning-change-status") errors.push(`${label}: invalid identity/schema`);
+  if (value.change !== expectedName) errors.push(`${label}: change must match directory`);
+  if (!DOMAIN.test(value.domain ?? "") || !DOMAIN_TYPE.has(value.domain_type)) errors.push(`${label}: invalid domain or domain_type`);
+  if (typeof value.topic !== "string" || !value.topic.trim()) errors.push(`${label}: topic is required`);
+  if (!CHANGE_STATUS.has(value.change_status) || !PHASE.has(value.phase)) errors.push(`${label}: invalid status or phase`);
+  if (!(value.current_work === null || WORK_ID.test(value.current_work ?? ""))) errors.push(`${label}: invalid current_work`);
+  if (!Array.isArray(value.works_run) || value.works_run.some((item) => !WORK_ID.test(item)) || duplicates(value.works_run ?? []).length) errors.push(`${label}: invalid works_run`);
+  if (!validDateTime(value.created_at) || !validDateTime(value.updated_at)) errors.push(`${label}: created_at and updated_at must be date-times`);
+  if (!Array.isArray(value.blockers)) errors.push(`${label}: blockers must be an array`);
+  if (expectedArchived && (value.change_status !== "archived" || value.phase !== "archived" || !validDateTime(value.archived_at) || typeof value.archive_path !== "string")) {
+    errors.push(`${label}: archived index requires archived status, phase, time, and path`);
+  }
+  if (expectedArchived && value.archive_path !== `<Path>{roots.state}/learning/archive/${expectedName.slice(0, 7)}/${expectedName}</Path>`) {
+    errors.push(`${label}: archive_path does not match the indexed archive location`);
+  }
+  if (!expectedArchived && value.change_status === "archived") errors.push(`${label}: active index cannot point to archived change`);
+  if (value.change_status === "completed" && (!validDateTime(value.completed_at) || value.phase !== "ready_to_archive")) errors.push(`${label}: completed requires completed_at and ready_to_archive phase`);
+  validateMasteryGate(value, label, errors);
+}
+
+function statePathFromTag(stateRoot, taggedPath) {
+  const match = /^<Path>\{roots\.state\}\/learning\/(.+)<\/Path>$/.exec(taggedPath);
+  return match ? join(stateRoot, ...match[1].split("/")) : null;
+}
+
+function validateContext(stateRoot, errors) {
+  const contextRoot = join(stateRoot, "context");
+  if (!isDirectory(contextRoot)) return;
+  for (const required of ["INDEX.md", "REVIEW.md"]) {
+    if (!isFile(join(contextRoot, required))) errors.push(`context/${required}: missing`);
+  }
+  const ids = new Map();
+  for (const file of walk(contextRoot).filter((path) => path.endsWith(".md"))) {
+    const text = readFileSync(file, "utf8");
+    const fileLabel = relative(stateRoot, file).split(sep).join("/");
+    for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+      const target = match[1].split("#")[0].trim();
+      if (!target || /^(?:https?:|mailto:|#)/.test(target) || target.includes("<")) continue;
+      const resolved = resolve(dirname(file), decodeURIComponent(target));
+      if (!resolved.startsWith(resolve(contextRoot) + sep) || !existsSync(resolved)) errors.push(`${fileLabel}: broken or escaping Markdown link ${target}`);
+    }
+    const id = /^\|\s*Knowledge ID\s*\|\s*([^|]+?)\s*\|\s*$/m.exec(text)?.[1];
+    if (!id) continue;
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) errors.push(`${fileLabel}: invalid Knowledge ID ${id}`);
+    if (ids.has(id)) errors.push(`${fileLabel}: duplicate Knowledge ID ${id} also in ${ids.get(id)}`);
+    else ids.set(id, fileLabel);
+    const state = /^\|\s*状态\s*\|\s*([^|]+?)\s*\|\s*$/m.exec(text)?.[1];
+    if (!KNOWLEDGE_STATUS.has(state)) errors.push(`${fileLabel}: invalid or missing knowledge 状态`);
+    for (const heading of ["## 当前理解", "## 心智模型", "## 示例与应用", "## 常见误区", "## 来源与证据"]) {
+      if (!text.includes(heading)) errors.push(`${fileLabel}: missing ${heading}`);
+    }
+  }
+}
+
+function validateStateRoot(root, options, errors) {
+  const statusPath = join(root, "status.json");
+  if (!isFile(statusPath)) {
+    errors.push("status.json: missing");
+    return;
+  }
+  const status = readJson(statusPath, "status.json", errors);
+  validateGlobalStatus(status, errors);
+  if (!status || !Array.isArray(status.active) || !Array.isArray(status.archived)) return;
+
+  for (const entry of status.active) {
+    if (!entry || typeof entry.change !== "string") continue;
+    const path = join(root, "changes", entry.change, ".status.json");
+    if (!isFile(path)) {
+      errors.push(`${entry.change}: indexed active change is missing .status.json`);
+      continue;
+    }
+    const changeStatus = readJson(path, `${entry.change}/.status.json`, errors);
+    validateChangeStatus(changeStatus, entry.change, false, errors);
+    if (changeStatus && (changeStatus.domain !== entry.domain || changeStatus.topic !== entry.topic || changeStatus.current_work !== entry.current_work || JSON.stringify(changeStatus.works_run) !== JSON.stringify(entry.works_run))) {
+      errors.push(`${entry.change}: global and change status projections differ`);
+    }
+    if (options.stage === "pre-archive" && (!options.change || options.change === entry.change) && changeStatus?.change_status !== "completed") {
+      errors.push(`${entry.change}: pre-archive requires completed status`);
+    }
+    if (options.stage === "complete" && (!options.change || options.change === entry.change)) {
+      errors.push(`${entry.change}: complete stage cannot leave the change active`);
+    }
+    for (const evidence of changeStatus?.mastery?.evidence ?? []) {
+      const resolved = statePathFromTag(root, evidence);
+      if (!resolved || !isFile(resolved)) errors.push(`${entry.change}: mastery evidence does not exist ${evidence}`);
+    }
+  }
+
+  for (const name of status.archived) {
+    const archiveRoot = join(root, "archive", name.slice(0, 7), name);
+    const path = join(archiveRoot, ".status.json");
+    if (!isFile(path)) {
+      errors.push(`${name}: indexed archive is missing .status.json`);
+      continue;
+    }
+    validateChangeStatus(readJson(path, `${name}/.status.json`, errors), name, true, errors);
+    if (isDirectory(join(root, "changes", name))) errors.push(`${name}: archived change still exists under changes`);
+    if (options.stage === "complete" && (!options.change || options.change === name) && !isFile(join(archiveRoot, "promotion-plan.md"))) {
+      errors.push(`${name}: complete stage requires archived promotion-plan.md`);
+    }
+  }
+  if (options.change && !status.active.some((entry) => entry.change === options.change) && !status.archived.includes(options.change)) errors.push(`${options.change}: change is not indexed`);
+  validateContext(root, errors);
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const errors = [];
+  if (options.selfCheck) {
+    const ownRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    validateWorkflowRoot(ownRoot, errors);
+  }
+  if (options.workflowRoot) validateWorkflowRoot(options.workflowRoot, errors);
+  if (options.stateRoot) validateStateRoot(options.stateRoot, options, errors);
+  if (errors.length) {
+    console.error(`Learning validation failed (${errors.length})`);
+    for (const error of errors) console.error(`  - ${error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log("Learning validation: OK");
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Learning validation failed: ${error.message}`);
+  process.exitCode = 1;
+}

package/template/workflows/learning/runtime-contract.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "workflow": "learning",
+  "config": null,
+  "structured_state": [
+    ".speculo/learning/status.json",
+    ".speculo/learning/changes/*/.status.json",
+    ".speculo/learning/archive/*/*/.status.json"
+  ],
+  "opaque_default": "preserve-byte-for-byte"
+}

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -55,7 +55,7 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 仅在上下文未提供时询问：
 
 - 交互语言与持久化工件语言；
-- implementation subagent、集成尝试次数和原型变体上限（初始化时写入 config，Lead 不计入）；
+- implementation subagent、集成尝试次数和 UI 设计候选上限（初始化时写入 config，Lead 不计入）；
 - Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
 
 不询问可由仓库事实回答的文件位置、脚本名或默认分支。

package/template/workflows/specdev/I-init-setup/config-template.json

@@ -21,7 +21,7 @@
     "default_depth": "standard",
     "require_ready_gate": true,
     "require_evidence": true,
-    "ui_prototype_default_variants": 3,
-    "ui_prototype_max_variants": 5
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
   }
 }

package/template/workflows/specdev/INDEX.md

@@ -3,8 +3,8 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、零基础新生图解、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
-keywords: [specdev, local-first, 规格驱动开发, decision-complete, eli5, prototype, code-review, TDD, 证据]
+description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
+keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
 ---
 
 # SpecDev Index

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -10,7 +10,7 @@
 - Tickets Map 与全部 Ticket 存在、Ready、DAG 无环；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；原型变体范围读取 planning 配置；
+- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 已获授权；
 - Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突；

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -2,47 +2,51 @@
 id: specdev/prototype
 type: workflow-entry
 workflow: specdev
-name: 原型
-description: 在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
-keywords: [prototype, 原型, logic, UI, variant, 一次性代码, 设计问题]
+name: UI 设计原型
+description: 检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
+keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互, design tokens]
 ---
 
-# 原型
+# UI 设计原型
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
-原型是**回答一个问题的一次性代码**。P 不交付生产实现，也不把原型代码提升到 main；它把答案和一手资料 locator 交给后续 G/S/Tickets/I。
+本 Work 的主导词是**设计定向**：先从项目事实识别现状，再让用户看到基于功能而非流行色推荐的候选，最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI；后续 S、Tickets 和 I 以设计包为视觉与交互权威。
 
 ## 输入与所有权
 
-- 一个可精确陈述的问题，来自用户、G、Spec 或 `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>`；
-- 相关代码、组件系统、领域上下文和 ADR；
-- 获授权的项目可写范围及临时 branch/worktree。
+- 必需输入：目标项目或新产品设想、核心用户任务，以及当前 SpecDev change。
+- 可选输入：现有代码、页面、截图、设计 token、品牌约束、ADR、Spec、调查和用户明确给出的参考产品。
+- 项目事实权威：依赖清单、样式源码、组件实现、路由、真实页面、测试和可复现截图；仅凭依赖名称不得断言实际风格。
+- 用户决定权威：产品方向、候选风格、密度、色调、字体气质、圆角、交互反馈和跨端优先级。
 
-P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`。代码写在临时 workspace 的项目路径附近；state 只保存项目相对 Path、branch、commit 和可迁移 `workspace_ref`。
+P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</Path>`。其中 `design-id` 使用当前 change 内最小未占用的 `UI-NNN`；目录中的设计系统主文档是唯一设计权威，comparison 和 final 文件均由它或其中已记录的候选决定派生。P 不写永久 research namespace，不创建 branch/worktree，不提交生产代码。
 
 ## 流程
 
-1. **锁定问题**：一个 record 只回答一个问题。业务逻辑、状态转换或数据形态使用 Logic；页面外观、信息层级或交互布局使用 UI。问题含糊且用户不在线时按周围代码选择，并在 record 写明假设。
-2. **建立临时工作区**：按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 创建/恢复工作区。创建 branch、commit 或删除 worktree 分别遵守现有授权边界；路径名明确包含 prototype。
-3. **执行分支**：Logic 加载 `<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`；UI 加载 `<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`。两个分支都把完整状态呈现给评审者，不依赖生产数据写入。
-4. **捕获答案**：使用 `<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>` 记录问题、运行方法、资产、验证反馈、赢家/拒绝项、结论、promotion target 和清理状态，原子重读。
-5. **关闭或阻塞**：答案已确认时 `status: answered`；用户选择不继续时 `discarded`；原型无法回答问题时 `blocked` 并说明缺失输入。Wayfinder 调用时，把 record/branch/URL 写入当前 Ticket 的 solution comment，并只关闭该 Ticket。
-6. **验证与路由**：使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage prototype` 校验当前 change。需要产品决定返回 G，需要外部行为合同返回 S，需要执行计划返回 Tickets；生产实现只进入 I。
+1. **创建或恢复设计包**：读取 change 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`。不存在时从 `<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>` 创建，写入 `status: detecting` 并原子重读；存在时只询问尚未确认的高影响选择。
+2. **检测现有风格**：加载 `<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，穷尽技术栈、布局、视觉 token、组件状态、响应式与可访问性证据。新项目明确记录 `project_kind: new`，不伪造检测结果。
+3. **建立功能候选**：读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，依据产品任务、平台和信息密度从八种风格及六种布局中推荐 2-4 个候选。每个候选写明适合原因、需要保留/调整/替换的现有事实、参考项目和迁移成本。
+4. **逐项选择并持久化**：加载 `<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`。每轮只处理一个决策层；每个答案立即写回设计系统主文档并重读。高影响偏好未确认时保持 `status: selecting`，不得自行标记 Ready。
+5. **生成可视对照与最终原型**：加载 `<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`。为每个候选生成独立 comparison variant，再生成 comparison 索引。用户确认或明确组合后，把最终 HTML/CSS/JS 作为具名代码块写入设计系统主文档，再物化到 final 目录。
+6. **验证并封板**：运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`；随后运行 SpecDev `--stage prototype`。全部通过且选择闭合后设置 `status: ready`，更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
+7. **返回路由**：返回设计包、comparison 和 final 的完整路径、验证命令与结果、未决问题和下一 Work。需要补足产品决定时返回 G；需要写外部行为合同返回 S；需要拆实施工作返回 Tickets；已有 Ready Ticket 才返回 I。Wayfinder 调用时只把设计包与 comparison locator 写入对应 solution comment。
 
 ## 完成标准
 
-- 只有一个问题和一个正确分支；
-- 原型极易运行，完整状态可见；
-- 临时 branch/worktree 与项目路径可恢复且不含机器绝对路径；
-- 原型没有测试、生产数据库依赖或伪装成生产代码；
-- 答案、资产、赢家、拒绝项、promotion target 和清理状态完整；
-- main 不保留落选变体、switcher 或原型外壳；
-- Wayfinder Ticket、solution comment 与 prototype record 可互相定位。
+- 现有项目的检测结论逐项有项目相对证据；新项目明确没有既有风格。
+- 候选由功能、平台和密度推导，不只更换颜色；用户已看到每个候选的独立 HTML。
+- 设计系统主文档完整包含 UI 结构、CSS token、交互 JS 和最终 HTML 源码，并记录研究出处与拒绝理由。
+- comparison 索引可导航到 2-4 个候选，final HTML 可离线运行；桌面与移动宽度不存在空白、遮挡或无意横向溢出。
+- 字体、间距、圆角、色彩、层级、控件状态、异步反馈、响应式、键盘、focus 和 reduced motion 均有明确合同。
+- Markdown 代码块与 `final/` 文件逐字一致，schema、局部校验和 SpecDev stage 校验全部通过。
+- 设计包不包含机器绝对路径、敏感值、生产数据写入、发布动作或未授权的生产实现。
 
 ## 子文件引用
 
-- Logic：`<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`
-- UI：`<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`
-- Record：`<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>`
-- Schema：`<Path>{roots.workflows}/specdev/common/schemas/prototype-record.schema.json</Path>`
+- 检测：`<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，仅在步骤 2 加载。
+- 选择：`<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`，仅在步骤 4 加载。
+- 生成：`<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`，仅在步骤 5 加载。
+- 模板：`<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>`，创建设计包时加载。
+- 设计库：`<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，建立候选或查具体规则时渐进读取。
+- Schema：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`。

package/template/workflows/specdev/P-prototype/design-library/INDEX.md

@@ -0,0 +1,43 @@
+# P-prototype 设计库
+
+本目录是 P-prototype 的静态设计参考层。它帮助 UI 原型先按任务、对象、密度和平台选择结构，再选择视觉表达；它不拥有运行时状态，不替代项目现有设计系统，也不授权修改生产代码。
+
+研究快照固定在 commit `49b565913c52f4867456e609696625157f19b930`。快照是证据与可运行样板，不在原型过程中原地修改；需要复用时，把所需 HTML/CSS/JS/图片和 attribution 复制到当前 change 的设计包。
+
+## 渐进披露入口
+
+| 当前问题 | 读取 | 读完应得到 |
+|---|---|---|
+| 先决定信息架构、密度和组件边界 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/foundations.md</Path>` | 一个主布局范式、密度档和设计系统边界 |
+| 在八种可运行风格中选择起点 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/style-index.md</Path>` | 一个主风格、必要时一个受控对照风格 |
+| 寻找相似产品及其真实模式 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/product-pattern-index.md</Path>` | 对应项目、可借鉴模式和一手研究路径 |
+| 定义浅色/深色、语义 token、字号与层级 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/color-and-theme.md</Path>` | 可实现的主题与密度假设 |
+| 设计导航、表格、表单、反馈或危险操作 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/interaction-patterns.md</Path>` | 完整状态和验证动作 |
+| 需要窄屏、触屏、桌面/Web/移动重排 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/responsive-and-platforms.md</Path>` | 每个平台的任务职责和断点行为 |
+| 需要引用、复制资产或判断证据强度/许可 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-provenance.md</Path>` | 可追溯来源、复用边界和 attribution |
+
+## 使用顺序
+
+1. 检测现有项目或明确新产品设想，并列出核心对象、最常见的 3-5 个任务、目标输入设备和最坏数据状态。
+2. 读取 foundations，选择一个主布局范式。不要先按品牌色、圆角或流行风格选择页面。
+3. 读取 style-index，按功能推荐 2-4 个结构不同的候选，并为每个候选生成独立 comparison HTML。
+4. 读取 product-pattern-index，只深入与当前对象、任务或平台相似的项目研究；星标不构成设计质量或许可结论。
+5. 只加载当前问题涉及的 theme、interaction 或 responsive 文件。精确值必须能回到 snapshot 中的 token、CSS 或研究证据。
+6. 复制样板时保留相对目录关系和所需 attribution；把 demo 名称、权限、Git、同步与审批状态替换为原型自己的假数据，不把演示逻辑当作真实业务逻辑。
+7. 用真实极端数据、键盘、目标宽度和浅/深主题验证。选择、拒绝理由和最终源码进入设计系统主文档，设计库本身保持不变。
+
+## 快照入口
+
+- 总报告：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/report/OPEN_SOURCE_UI_RESEARCH_2026.md</Path>`
+- 八种风格总览：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/index.html</Path>`
+- 样板使用说明：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/README.md</Path>`
+- 结构化项目数据：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/projects.json</Path>` 与 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/extended-projects.json</Path>`
+- 综合 token：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>`
+
+## 完成门
+
+- 选择理由落在任务模型、信息密度、输入设备和状态复杂度，而不是“看起来像”；
+- 一个布局范式和一个主风格已明确，所有新增 token 都有语义角色；
+- loading、empty、no-results、error、offline、read-only、permission 与长文本按适用性逐项处理；
+- 窄屏改变任务流而非压缩桌面多栏；
+- 引用与复制均可回到固定 commit、研究文件和 attribution。

package/template/workflows/specdev/P-prototype/design-library/color-and-theme.md

@@ -0,0 +1,65 @@
+# 色彩、主题与视觉层级
+
+视觉系统先定义角色，再选择色值。固定快照中的 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>` 是跨项目综合起点，不是任何单一产品的 token 复制品。
+
+## 最小语义集合
+
+```text
+canvas
+surface-1 / surface-2 / surface-3 / overlay
+text-primary / text-secondary / text-tertiary / text-disabled
+border-subtle / border-default / border-strong
+accent / accent-hover / accent-subtle / accent-contrast
+success / warning / danger / info (+ subtle variants)
+hover / selected / pressed / focus-ring / scrim
+```
+
+业务组件消费语义角色，不直接写 `#fff`、`black` 或任意透明度。品牌 accent 只服务主要动作、选中和链接；状态色必须同时配图标、文本或形状。数据可视化色板、Git diff、syntax highlight 和业务状态分别建组，不复用 UI accent 充当所有含义。
+
+## 浅色与深色
+
+- 两种主题一起设计，不把深色简单反相。深色 overlay 往往比基础表面更亮，边框和语义色需要重新分配明度与对比。
+- 分别检查正文、次要文字、图标、边框、focus ring 和状态，而不只检查按钮。
+- 中性色保持低 chroma，避免所有表面都带强品牌倾向。
+- 用户切换主题时保持布局、选择、输入和面板尺寸；主题改变不应触发内容重排。
+- 高对比需求不能只靠增加饱和度，应重新检查边界、文字与焦点。
+
+## 字体和密度
+
+| 角色 | 字号/行高起点 |
+|---|---|
+| 坐标、元数据、辅助标签 | 11-12px / 16px；不承载长文本、错误原因或主要操作 |
+| 表格、侧栏、紧凑控件 | 13px / 18-20px |
+| 默认 UI 正文与表单 | 14px / 20px |
+| 内容正文 | 15-16px / 24-26px |
+| 小节/弹窗标题 | 16-18px / 22-26px |
+| 页面标题 | 20-24px / 28-32px |
+
+工具界面不使用营销页级大标题。数字表格可启用 tabular numerals，代码/SQL/ID 使用 mono；中英文混排单独验证 CJK 回退和行高。不使用负字距挤压 UI，长名称通过布局、换行或中间截断处理。
+
+| 密度 | 控件高度 | 表格行高 | 典型任务 |
+|---|---:|---:|---|
+| Compact | 28px | 32px | SQL、日志、开发工具 |
+| Default | 32-36px | 36-40px | CRM、项目管理、后台 |
+| Comfortable | 40px | 44-48px | 文档、协作、低频表单 |
+| Touch | 44-48px | 48-52px | 移动与触屏 |
+
+## 圆角、边框与阴影
+
+- 2-4px：代码块、表格小元素、密集工具按钮。
+- 4-6px：输入、按钮、菜单项、紧凑面板。
+- 6-8px：普通卡片、popover、较大控件。
+- 8-12px：dialog、sheet、移动大容器；移动样板可因触屏语言使用更大值。
+- pill：状态徽标、分段选择滑块或真正胶囊语义，不用于所有按钮。
+
+同一视觉层只保留 2-3 个主圆角。常驻页面分区、侧栏、表格和检查器用 1px 边框或背景差建立层级，不用浮卡阴影；popover/menu 使用清晰边框和中等阴影；dialog 使用 scrim 与较大阴影；focus ring 独立于层级阴影。hover、selected、pressed 必须是不同 token。
+
+## 原型验证
+
+- 浅色、深色、200% 缩放和常见色觉差异下，文本与状态仍可区分；
+- 页面没有绕过 token 的随机颜色、圆角和阴影；
+- 状态不只依赖颜色；
+- 最长名称、中文、数字和错误文案不会撑坏控件；
+- reduced motion 时 token 中的 UI duration 降为零或对应交互停止非必要动画。
+
+八种具体 `.theme-*` 实现在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/styles/pages.css</Path>`，综合 token 的使用约束在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/USAGE.md</Path>`。