@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-p-prototype/scripts/validate-design-package.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { materialize } from './materialize-prototype.mjs';
+import { assertSchema, readDesign, safePath, prototypeDigest, validateChangeDesign, DESIGN_LIBRARY } from '../../common/tools/design-artifacts.mjs';
+
+async function localResources(root, locator, seen = new Set()) {
+  if (seen.has(locator)) return;
+  seen.add(locator);
+  if (!/^(?:final|comparison)\//.test(locator)) throw new Error(`prototype runtime resource is outside digest coverage: ${locator}`);
+  const file = await safePath(root, locator);
+  if (!/\.(?:html|css|js)$/.test(locator)) return;
+  const text = await readFile(file, 'utf8');
+  // Prototype state is an in-memory mock. Disallow network APIs even when their
+  // URL is assembled dynamically; user navigation links remain permitted.
+  if (/\b(?:fetch|XMLHttpRequest|WebSocket|EventSource|sendBeacon|importScripts)\s*\(/.test(text)) throw new Error(`prototype must use local mock state, not network APIs: ${locator}`);
+  if (/(?:src|poster|srcset)\s*=\s*["'][^"']*(?:https?:)?\/\/|<link\b[^>]*href\s*=\s*["'](?:https?:)?\/\/|(?:@import|url\s*\()[^;\n]*(?:https?:)?\/\//i.test(text)) throw new Error(`remote prototype resource: ${locator}`);
+  const refs = [...text.matchAll(/(?:src|href|poster)\s*=\s*["']([^"']+)["']|url\(\s*["']?([^)'"\s]+)["']?\s*\)/gi)].map(match => match[1] || match[2]);
+  const dependencies = [
+    ...text.matchAll(/@import\s*["']([^"']+)["']/gi),
+    ...text.matchAll(/\b(?:import|export)\s+(?:[^;\n]*?\s+from\s*)?["']([^"']+)["']/g),
+    ...text.matchAll(/\b(?:import|Worker|SharedWorker)\s*\(\s*["']([^"']+)["']/g),
+  ].map(match => match[1]);
+  for (const ref of dependencies) {
+    if (/^(?:[a-z]+:|\/\/)/i.test(ref)) throw new Error(`remote or unsupported module resource: ${ref}`);
+    refs.push(ref);
+  }
+  if (/\b(?:import|Worker|SharedWorker)\s*\(\s*[^\s"']/.test(text)) throw new Error(`dynamic module path cannot establish offline closure: ${locator}`);
+  for (const match of text.matchAll(/srcset\s*=\s*["']([^"']+)["']/gi)) for (const item of match[1].split(',')) refs.push(item.trim().split(/\s+/)[0]);
+  for (const value of refs) {
+    const ref = value.split(/[?#]/)[0];
+    if (!ref || /^(?:data:|https?:|mailto:|tel:)/i.test(ref)) continue;
+    const target = relative(root, resolve(dirname(file), ref)).replaceAll('\\', '/');
+    await localResources(root, target, seen);
+  }
+}
+
+function substantiveHTML(html, label) {
+  if (!/<main\b/i.test(html) || !/<(?:h1|h2)\b/i.test(html) || !/<(?:button|input|select|textarea|a)\b/i.test(html)) throw new Error(`${label}: candidate requires a task surface, heading and operable controls; title-only HTML is insufficient`);
+  if (html.replace(/<[^>]*>/g, '').trim().length < 80) throw new Error(`${label}: candidate requires representative task content`);
+}
+
+// Reject recoloring the same page as distinct candidates. Human critique still
+// decides whether different markup represents a meaningful task alternative.
+function structure(html) {
+  return (html.replace(/<(?:script|style)\b[^>]*>[\s\S]*?<\/(?:script|style)>/gi, '').match(/<\/?(?:main|nav|aside|section|article|header|footer|form|table|thead|tbody|tr|td|ul|ol|li|button|input|select|textarea|a|h[1-6])\b[^>]*>/gi) ?? [])
+    .map(tag => tag.replace(/\s[^>]*?(?=\/?>)/, '').toLowerCase()).join('');
+}
+
+async function browserEvidence(root, locator, digest, candidates) {
+  const evidence = JSON.parse(await readFile(await safePath(root, locator), 'utf8'));
+  assertSchema('browserEvidence', evidence);
+  if (evidence.prototype_digest !== digest) throw new Error('browser evidence digest is stale');
+  for (const required of ['final/index.html', ...candidates.map(c => c.entry)]) if (!evidence.inspected_files.includes(required)) throw new Error(`browser evidence did not inspect ${required}`);
+  for (const file of evidence.inspected_files) await safePath(root, file);
+  for (const entry of ['final/index.html', ...candidates.map(c => c.entry)]) for (const width of [390, 1440]) if (!evidence.cases.some(c => c.entry === entry && c.width === width)) throw new Error(`browser evidence requires ${entry} at ${width}px viewport`);
+  for (const item of evidence.cases) {
+    if (!evidence.inspected_files.includes(item.entry)) throw new Error(`browser case refers to uninspected entry: ${item.entry}`);
+    const screenshot = await readFile(await safePath(root, item.screenshot));
+    if (screenshot.length < 100 || screenshot.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a') throw new Error(`browser screenshot must be an actual PNG: ${item.screenshot}`);
+    if (screenshot.readUInt32BE(16) < item.width || screenshot.readUInt32BE(20) < item.height) throw new Error(`browser screenshot dimensions do not cover recorded viewport: ${item.id}`);
+  }
+  for (const review of [evidence.design_review, evidence.technical_review]) if ((await readFile(await safePath(root, review), 'utf8')).trim().length < 80) throw new Error('browser/design review must describe actual findings and recheck');
+  return evidence;
+}
+
+export async function validate(path, options = {}) {
+  const { allowDraft = false, checkReady = false, checkPreview = false } = options;
+  const designPath = resolve(path), root = dirname(designPath);
+  await safePath(dirname(root), `${basename(root)}/${basename(designPath)}`);
+  const { meta } = await readDesign(designPath);
+  if (meta.schema_version !== 3) throw new Error('legacy design package is read-only; create a new v3 UI package and obtain fresh confirmation');
+  assertSchema('designPackage', meta);
+  if (meta.design_id !== basename(root) || meta.change !== basename(dirname(dirname(root)))) throw new Error('prototype identity does not match owning change/UI directory');
+  const count = meta.candidates.length;
+  if (meta.candidate_count_override ? count !== meta.candidate_count_override.count : count < 2 || count > 4) throw new Error('candidate count requires 2-4 candidates or the exact explicit user override');
+  const ids = meta.candidates.map(c => c.id);
+  if (new Set(ids).size !== count) throw new Error('duplicate candidate id');
+  if (new Set(meta.candidates.map(c => c.task_id)).size !== 1) throw new Error('candidates must use the same user task');
+  if (new Set(meta.candidates.map(c => c.structural_difference)).size !== count) throw new Error('candidates need distinct structural decisions');
+  const catalog = JSON.parse(await readFile(join(DESIGN_LIBRARY, 'catalog.json'), 'utf8'));
+  assertSchema('designCatalog', catalog);
+  const templates = new Set(catalog.templates.map(t => t.id));
+  const references = new Set([...catalog.references.map(r => r.id), ...meta.sources.map(s => s.id)]);
+  for (const candidate of meta.candidates) {
+    if (!templates.has(candidate.template_id) && !meta.sources.some(s => s.id === candidate.template_id)) throw new Error(`unknown template ${candidate.template_id}`);
+    if (!references.has(candidate.primary_reference)) throw new Error(`unknown visual reference ${candidate.primary_reference}`);
+    if (candidate.auxiliaries.length > 2 || candidate.auxiliaries.some(a => !references.has(a.reference_id))) throw new Error('composition needs at most two known auxiliary references with explicit dimensions');
+    if (new Set([candidate.primary_reference, ...candidate.auxiliaries.map(a => a.reference_id)]).size !== candidate.auxiliaries.length + 1) throw new Error('composition references must have distinct roles, without repeated primary/auxiliary references');
+  }
+  if (!checkReady && !checkPreview && (meta.status !== 'ready' || allowDraft)) return meta;
+  if (!ids.includes(meta.selected_candidate)) throw new Error('ready prototype requires selected_candidate');
+  await materialize(designPath, { check: true });
+  const index = await readFile(await safePath(root, 'comparison/index.html'), 'utf8');
+  await localResources(root, 'comparison/index.html');
+  const structures = new Set();
+  for (const candidate of meta.candidates) {
+    if (!candidate.entry.startsWith('comparison/variants/')) throw new Error('candidate entry must belong to comparison/variants');
+    const file = await safePath(root, candidate.entry);
+    if (!index.includes(candidate.entry.slice('comparison/'.length))) throw new Error(`comparison does not link candidate ${candidate.id}`);
+    const html = await readFile(file, 'utf8');
+    substantiveHTML(html, candidate.id);
+    const outline = structure(html);
+    if (structures.has(outline)) throw new Error('candidates repeat the same task structure; recoloring alone is insufficient');
+    structures.add(outline);
+    await localResources(root, candidate.entry);
+  }
+  substantiveHTML(await readFile(await safePath(root, 'final/index.html'), 'utf8'), 'final');
+  await localResources(root, 'final/index.html');
+  for (const file of meta.prototype_files) await safePath(root, file);
+  const digest = await prototypeDigest(designPath);
+  const change = await validateChangeDesign(join(dirname(dirname(root)), 'DESIGN.md'), { ...options, requireApproved: !checkPreview });
+  if (change.meta.prototype_ref.id !== meta.design_id || change.meta.prototype_ref.digest !== digest || change.meta.selection.candidate_id !== meta.selected_candidate) throw new Error('change DESIGN does not approve this prototype/selection digest');
+  if (!meta.browser_evidence) throw new Error('ready prototype requires browser evidence');
+  const evidence = await browserEvidence(root, meta.browser_evidence, digest, meta.candidates);
+  for (const page of change.meta.pages) for (const state of page.states) if (!evidence.cases.some(c => c.entry.startsWith('final/') && c.states.includes(`${page.id}:${state}`))) throw new Error(`browser evidence missing final page state ${page.id}:${state}`);
+  return meta;
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  const args = process.argv.slice(2), paths = [], options = {};
+  for (let i=0;i<args.length;i++) {
+    const arg=args[i], field={'--repo':'repoRoot','--method-root':'methodRoot','--state-root':'stateRoot','--snapshot-specdev':'snapshotSpecdev'}[arg];
+    if (field) { if (!args[i+1] || args[i+1].startsWith('--') || field in options) throw new Error('invalid design context'); options[field]=args[++i]; }
+    else if (arg === '--allow-draft') options.allowDraft=true;
+    else if (arg === '--check-ready') options.checkReady=true;
+    else if (arg === '--check-preview') options.checkPreview=true;
+    else paths.push(arg);
+  }
+  if (paths.length !== 1) { console.error('usage: validate-design-package.mjs [--allow-draft|--check-ready|--check-preview] [--repo project --method-root method --state-root specdev] <design-system.md>'); process.exitCode = 2; }
+  else validate(paths[0], options).then(() => console.log('design package: valid (browser evidence is recorded, not a host certification)')).catch(error => { console.error(error.message); process.exitCode = 1; });
+}

package/template/workflows/specdev/specdev-r-retro/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: specdev-r-retro
+description: "对指定开发活动、环境或协作流程的已观察摩擦做证据化复盘，形成根因、改进 owner 与可检验提案；代码讲解使用 L-learn-change，Speculo 产品反馈使用 retro 命令。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/retro
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 开发复盘
+
+先读 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>。本 Work 不自动修代码、提 Issue 或改永久知识。
+
+## 流程
+
+1. 固定本次会话/活动范围，按来源 ID 定位 change、测试、CI、交接和失败证据，不全读历史。缺失资料列 unknown；范围清楚且证据可定位才开始分析。
+2. 未归档且尚未 completed 的当前 change 使用其 retro 目录。completed 或 archived 来源以及独立复盘建立非实现 review change，引用原 locator；不重开来源状态或改写归档。按 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path> 初始化/恢复；存在重叠实际 writer 时先由原 owner 停止或真实交接。
+3. 调用 <Path>{roots.references}/retrospective/retrospective-contract.md</Path>，检查约束是否缺失、已有检查是否失效或未接入；区分环境事实、机械检查和判断规则。每个发现有因果证据或明确假设，建议有 owner、正反验收与路由。
+4. 按 <Path>{roots.workflows}/specdev/specdev-r-retro/assets/retro-template.md</Path> 创建 <Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path>，选择最小未占用 ID。原子保存并重读，运行 SpecDev --stage retro；修订保留来源与被替代结论。
+5. 验证通过后回读原 RETRO 并在 README 导航接续；证据不足可完成一份 outcome=insufficient-evidence 的诚实报告，不冒充解决问题。只读复盘不创建 Spec/Ticket 或 implementation Evidence。review-only change 按专用完成门关闭。
+
+## 改进必须能被证伪
+
+逐项判断是规则缺失、规则未接入、规则判断错、测试不能失败或环境事实变化。建议说明真正修改位置、owner、正反验收、恢复影响和新增维护成本；不要对每个问题都增加一条提示词。记录已观察因果、尚未验证解释和不采纳理由，复盘报告不等于修复完成。
+
+## 结果与路由
+
+合法 outcome：findings、no-findings、insufficient-evidence。发现的 disposition 为 file-issue / lesson-only / discard / duplicate；每项记录理由，允许没有发现。
+
+代码问题交 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>，计划改进交 <Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>，远程反馈交 <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path>；永久知识交 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path>。返回完整报告、已验证与未验证项、下一入口；不自动推进这些后续副作用。

package/template/workflows/specdev/specdev-r-review-architecture/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: specdev-r-review-architecture
+description: "审查指定代码范围的结构与维护成本，或测量真实用户操作的性能并形成候选；只报告或深入用户选定的设计，不直接实施优化。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/review-architecture
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 架构审查
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`，再执行本入口。
+
+本 work 根据可定位的代码压力审查当前范围：先找会让 module 变浅的结构性坏味道，再找能删掉复杂性的 `code-judo` 机会，再找真正值得深化的 seam。行为正确不构成通过；如果存在更简单的路径，就优先把复杂性删掉，而不是搬家。
+
+本 work 只审查、呈现和访谈，不直接修改产品代码。报告阶段只产出 Markdown 决策记录，不生成 HTML。
+
+本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/review-rubric.md</Path>`。沿用 CONTEXT 与共享设计词汇（module、interface、depth、seam、adapter、leverage、locality）准确表达含义，不为机械出现英文而牺牲理解。
+
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
+
+## 输入与产物
+
+按存在情况读取：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- 当前代码、测试、依赖和 Git 历史。
+
+无 change 的明确范围 report 默认在会话返回 Markdown，零文件写入；用户明确要求保存时使用获批项目报告路径，不造 change。已有 change 的产物：
+
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+
+结构 report 的每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
+
+## 选择交付分支
+
+- `report`（默认）：用户只请求 review/扫描时完成下方探索与报告，候选保持 `unselected`；没有候选是有效结果，不要求用户先选方案才完成报告。
+- `selected-design`：只有用户已经选择一个候选并请求深入设计，才加载 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/selected-design.md</Path>`。输入是可回读报告和所选候选；来源漂移先核对影响，不用旧结论代替当前代码。
+
+结构报告、已选设计和性能分支均不修改生产代码，报告不授权访谈、建票或实施。
+
+## Performance 分支
+
+选择 performance 时直接执行此参考，不强制运行下方结构 Report 流程；只读性能报告是有效终点，不要求先选择优化方案。
+
+用户要求定位性能成本或评估优化时读取 <Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/performance-review.md</Path>，以真实用户操作、工作量、冷暖状态、时钟、原始样本和端到端结果形成测量与候选。performance 使用原 architecture-review 报告，不新建状态；代码实施仍交 S/T/P/I。无瓶颈、无收益、拒绝优化与证据不足均可诚实返回。需要确认已有性能故障根因时进入 D。
+
+结构/简化候选同时核对 API、状态、配置、重复表示、缓存失效、兼容与测试的实际维护成本、动态加载和真实消费者。单一 provider 不自动等于多余抽象；不要为删行数删除义务。
+
+## Report 流程
+
+### 1. 探索
+
+**先找结构压力，再找方案。** YAGNI 仍然成立，但只有真正的代码压力才值得写入报告。
+
+- 用户指明 module、子系统或痛点时直接采用，跳过热点推断；
+- 否则翻阅足够长的 `git log --oneline`，找出反复出现的 files、call sites 和 test surfaces；
+- 变更散落、没有明确热点时才扩大搜索范围；
+- 只接受能通过删除测试的候选：删掉该 module 后，复杂性应集中或消失，而不是换一个地方继续蔓延；
+- 逐项应用 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/review-rubric.md</Path>` 的结构压力、删除测试与排序规则；
+- 先读取项目领域词汇及当前区域 ADR；探索真实调用和测试表面，过滤仅 rearrange complexity 的提案。
+
+对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。若没有任何候选通过这条线，明确写出“没有高置信候选”，不要为了填表而硬造一个。
+
+**完成标准**：审查范围、排除范围、领域/ADR 输入和每个候选的 code pressure 均可追踪；没有把行为正确但结构平庸的地方当成通过。
+
+### 2. 生成 Markdown 报告
+
+按 <Path>{roots.workflows}/specdev/specdev-r-review-architecture/assets/architecture-review-template.md</Path> 的适用内容形成 Markdown 决策记录；有 change/获批报告路径才落盘，无 change 的只读请求直接会话返回。
+
+每个候选以高置信 finding 的顺序展示，而不是按文件顺序排列。每个候选包含：
+
+- **文件**——涉及的 files 和 modules；
+- **问题**——当前架构造成的摩擦；
+- **代码 judo**——保留行为但删掉什么复杂性；
+- **收益**——用 locality、leverage、depth 和测试改善解释；
+- **删除测试**——删掉这个 module 后复杂性是否真的消失；
+- **前后对比**——用文本图示或 Mermaid 记录 shallow 与 deep；
+- **建议强度**——`Strong | Worth exploring | Speculative`；
+- **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`；
+- **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
+
+报告以“最佳推荐”结束；若没有高置信候选，就明确写 `无高置信候选`。报告阶段**不提出 interface**；返回候选和证据即可，不强制追加选择问题。
+
+**完成标准**：每个候选字段完整、最佳推荐唯一或明确为空，会话报告可回读；获批文件报告已原子写入并重读。
+
+## 分支完成、状态与返回
+
+`performance` 完成条件：测量卡、原始样本或明确缺口、可比较性和候选依据完整，工程证据检查已运行；baseline/inconclusive 是调查结果，不代表优化已经交付。报告已回读，后续实施必须另有授权。
+
+`report` 完成条件：范围有依据；高置信候选满足删除测试且每项有当前文件/调用/测试证据、前后对比、收益、强度和 ADR 冲突处理；最佳推荐唯一或明确为“无高置信候选”；Markdown 已原子写入并回读。未选择或拒绝的候选不变成 Ticket。
+
+`selected-design` 完成条件：用户选定的一个候选完成参考中的完整 frontier 访谈，或明确 blocked/rejected；只有接受且达成共识的方案才按原 Ticket 治理交接。其他候选保持未选择，不批量要求决定。
+
+按本分支真实结果更新原报告，blocked 保留具体原因、owner 与下一核验步骤；无 change 的指定范围审查不创建状态。报告完成不是产品交付；只有请求本来以非实现审查为终点且满足 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，该终点 owner 才可关闭 change。
+
+返回分支、报告完整路径、审查范围/排除范围、代码证据、候选结论、实际验证与未验证项；有选择时再返回相应设计树/下一 Work。结构检查不证明设计判断正确，不能把弱候选包装成最佳推荐。

package/template/workflows/specdev/specdev-r-review-architecture/assets/architecture-review-template.md

@@ -0,0 +1,73 @@
+---
+artifact: architecture-review
+change: <YYYY-MM-DD-topic>
+status: draft
+---
+
+# 架构审查：<范围>
+
+- **决策记录：** `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- **审查准则：** `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/review-rubric.md</Path>`
+
+## 1. 审查压力与范围
+
+- 触发目标：
+- 审查入口：
+- 相关行为或 Ticket：
+- 不审查范围：
+- 成功标准：
+- 热点依据：用户指定 / Git 历史
+- 结构性压力：file-size、spaghetti growth、boundary drift、wrong-layer logic、thin wrapper、sequential orchestration
+
+## 2. 当前结构地图
+
+### 模块与接口
+
+### 数据、控制与错误流及 seam
+
+### 变化热点、locality 与测试表面
+
+### 拆分压力
+
+- 接近或超过 1k lines 的文件：
+- 需要先删除还是先拆分的复杂性：
+
+## 3. 候选提案
+
+### AR-001: <标题>
+
+- **文件：** `<Path>project/relative/path</Path>`
+- **结构类别：** structural blocker / missed simplification / spaghetti growth / boundary drift / file-size pressure / wrong-layer logic
+- **问题：** 当前架构如何造成摩擦
+- **代码 judo：** 保留行为但删掉什么复杂性
+- **删除复杂性：** 会消失的 branch、helper、wrapper、mode、special case
+- **删除测试：** 删除当前 shallow module 会集中复杂性 / 只移动复杂性
+- **收益：** locality、leverage、depth 与测试改善
+- **建议强度：** Strong / Worth exploring / Speculative
+- **依赖类别：** in-process / local-substitutable / ports & adapters / mock
+- **ADR 冲突：** 无 / ADR-###，值得重审因为 ...
+
+#### 前后对比
+
+- Before：shallow interface、leaking seam 与分散 locality。
+- After：deep module、稳定 interface 与集中测试表面。
+
+- **证据：** `CODE:<Path>project/relative/path</Path>`、git log、测试输出
+- **推荐：**
+- **访谈状态：** unselected / selected / consensus / blocked / rejected
+- **用户结论：**
+- **ADR 影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 中的 ADR-###
+
+## 4. 最佳推荐
+
+首先探索：AR-###。原因：<一句话>。若没有高置信候选，明确写 `无高置信候选`。
+
+## 5. 下一步
+
+- 当前请求：report / selected-design。report 到此完成，访谈状态可为 unselected；无高置信候选也可交付。
+- 用户选择原文与候选 ID：仅 selected-design 填写；未选择时不虚构结论、不自动转票。
+- 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>`。
+
+## 性能测量（仅 performance 分支）
+
+按 <Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/performance-review.md</Path> 填写用户操作、工作量/入口/时钟/环境/冷暖/排除成本、原始样本、内存与端到端边界、最强保留理由、候选及停止条件；无样本明确 inconclusive。使用 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path> 的标记记录，不把提案收益当已实施结果。普通结构报告不制造测量数据。

package/template/workflows/specdev/specdev-r-review-architecture/references/proposal-to-ticket.md

@@ -0,0 +1,13 @@
+# 架构提案转 Ticket
+
+本规则由 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/SKILL.md</Path>` 在候选被用户接受后加载。
+
+- 只有有代码证据、具体收益和用户接受的提案才生成 Ticket。
+- 先确认提案真正在删除复杂性，而不是把复杂性搬家；纯重排、纯改名或 thin wrapper 不进入 Ticket。
+- 前置 Ticket 必须指出解除的后续阻碍、受益 Ticket 或行为，以及独立验证。
+- 修改公共接口、schema、数据或大范围调用方时使用 Deep，并采用 expand → migrate → observe → contract。
+- 架构报告中的项目路径只是审查证据；生成 Ticket 时重新确认当前项目路径和所有权。
+- 不把“清理整个模块”写成单一 Ticket；按可验证安全落点拆分。
+- 如果候选会让文件越过 1k lines、引入更多 special cases，或者只是在已经忙乱的流程里再加一层分支，先继续分解，再考虑 Ticket。
+- 任何会改变外部行为或验收合同的提案先修订 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
+- 任何会改变已接受架构决策的提案先更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。

package/template/workflows/specdev/specdev-r-review-architecture/references/review-rubric.md

@@ -0,0 +1,56 @@
+# 架构审查准则
+
+本准则只在 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/SKILL.md</Path>` 激活时生效。它把实际维护压力转成候选筛选和排序规则；每个结论都要有路径、调用或测试证据。
+
+使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语：module、interface、depth、seam、adapter、leverage、locality。优先保持项目共享含义；中文解释可与专业词并列，不要求机械复述每个词。
+
+## 重点观察
+
+优先寻找有真实代码压力的候选：
+
+- 结构性回退：module 变浅，interface 正在向 implementation 膨胀；
+- 代码 judo 机会：删掉一个 branch、helper、wrapper、mode 或 special case；
+- spaghetti growth：ad-hoc conditionals、散落例外或一次性 flags；
+- boundary drift：cast、`any`、`unknown` 或 optionality 掩盖真实不变量；
+- 文件大小或拆分压力，尤其是把文件推到 1k lines 以上；
+- wrong-layer logic 泄漏进共享路径或 canonical helper；
+- 重复的 canonical helper、identity abstraction 或 pass-through wrapper；
+- 原本可以更原子化的顺序编排或部分更新；
+- seam 正在把测试、错误或状态处理复杂性泄漏给调用方。
+
+## 删除测试
+
+只有删除当前 module、helper 或 branch 后，复杂性真的消失，或者至少集中到更容易推理的位置，候选才算成立。
+
+拒绝以下候选：
+
+- 只是重新摆放复杂性；
+- 只是改名；
+- 只是把一个 shallow module 换成另一个 shallow module；
+- 只是加一个 thin wrapper、adapter 或 identity abstraction，却没有换来 leverage；
+- 依赖 speculative generality，而不是当前真实压力；
+- 没有文件、调用点或测试证据。
+
+## 排序规则
+
+按严重度和代码压力排序：
+
+1. 结构性阻塞；
+2. 明显的代码 judo；
+3. 重复 special case 和 spaghetti growth；
+4. boundary 与 type contract 漂移；
+5. 文件大小和拆分压力；
+6. wrong-layer logic 和 canonical helper 重复；
+7. 低信号的可读性问题。
+
+## 文件大小规则
+
+不要让一个候选轻易把文件从 1k lines 以下推到 1k lines 以上。默认把它当成拆分压力，而不是通过项。
+
+## 报告门槛
+
+不要把报告写成杂音集合。只保留高置信 finding。若没有候选通过门槛，就直接写 `无高置信候选`，不要硬造一个来填模板。
+
+## 维护义务与最强反对理由
+
+候选记录真实生产消费者、动态配置/加载、第三方接口、数据与兼容义务。明确移除了哪些状态、配置、表示、失效路径和测试负担，剩余 glue 的代价是什么，以及最强保留理由。单 provider 或静态零调用不自动证明可删；代码行数只用于发现，不作收益指标。性能提案必须先使用 <Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/performance-review.md</Path> 测量。

package/template/workflows/specdev/specdev-r-review-architecture/references/selected-design.md

@@ -0,0 +1,27 @@
+# 已选架构候选的设计与转票
+
+用户选定一个候选后读取；保持审查报告和 change 内决策同步，不修改生产代码。
+
+### 3. 访谈用户选择的一个候选
+
+用户选择候选后，调用 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
+
+决策结晶时保持领域模型同步：
+
+- 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
+- 模糊术语当场精炼；
+- 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时，询问是否记录 ADR；任一条件不满足就留在 LOG/Ticket，不制造 ADR；
+- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`；
+- 如果候选最终只是把复杂性搬家，而不是删掉它，在访谈中直接回退，不把它升级成 Ticket。
+
+将选择、访谈状态与结论同步到 Markdown；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
+
+**完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
+
+### 4. 转化为执行工作
+
+只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>`。加载 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/references/proposal-to-ticket.md</Path>`，按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理；只有能删除复杂性的提案才继续，纯重排和 thin wrapper 不进入 Ticket。
+
+## 从候选到验收
+
+接受的简化必须保持现存消费者、安全、兼容和持久数据义务；若主动放弃能力，交上游明确批准。原测试删除逐项给出承接证据；性能候选把可比较测量和行为保持一并交票，不将估计收益改写为已验证。

package/template/workflows/specdev/specdev-s-spec/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: specdev-s-spec
+description: "综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/spec
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 编写 Spec
+
+激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。本 Work 综合已有事实，定义为什么、为谁、系统应表现为何，不另开宽泛访谈，也不写逐文件施工计划。
+
+## 形成行为合同
+
+1. **Grounding**：定位用户目标与当前代码、测试、接口、schema、配置和运行事实。按存在情况定位 change 的来源、分诊、诊断、LOG、CONTEXT、ADR 及相关永久领域词汇/决策；只回读命中原文，可选工件缺失静默跳过，不当作已确认事实。按 `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>` 区分可发现事实、高影响偏好和可逆实现细节；冲突按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 返回权威 owner。
+2. **关闭必要决定**：只确认会改变外部行为、接口、数据、兼容、安全、迁移、发布或验收的高价值问题。广泛取舍未定时返回 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；陌生外部依赖或版本行为通过 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>` 查证。不虚构错误码、性能阈值、法规或迁移政策。
+3. **写入合同**：先按下述轻量/完整边界选择唯一负责位置；轻量写 README 等价章节，完整模式以 `<Path>{roots.workflows}/specdev/specdev-s-spec/assets/spec-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。模板拥有问题/用户/成功、正常/边界/失败/角色/状态行为、IN/REUSE/OUT、保持项、接口数据与 NFR 的完整结构及 `US-### / AC-### / NFR-### / DEC-### / OOS-###` 稳定编号。实现约束仅锁定会影响公共合同、兼容、安全或验收的决定。
+4. **绑定验证接缝**：优先复用稳定接缝，通常从用户端到端行为、公共 API/CLI、事件/集成、稳定单元接缝选择；按实际风险与项目先例决定，不机械追求最高测试层级。每个接缝注明入口类型/位置、触发方式、可观察结果、覆盖 AC 和实际测试先例/命令。选择显著改变可测试性、事故半径或范围时聚焦确认；可由已有代码推导时记录依据即可。证据遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+5. **Readiness**：对照 <Path>{roots.workflows}/specdev/specdev-s-spec/references/spec-readiness.md</Path>；完整 Spec 再校验 <Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>。高影响未决问题使 `ready_for_tickets: false`；低影响、可逆默认值可作为带验证方式的显式假设。每个 AC 必须可观察、可判定、绑定接缝；不适用影响写明理由。
+
+简单单 change 可使用 README 的 scope/acceptance/verification 等价章节承载规格，仍须通过同一行为/AC/Ready 语义；独立 <Path>{roots.state}/specdev/changes/{change}/spec.md</Path> 存在时默认使用它，双权威先裁决。用户明确要求 Spec 或存在复杂设计/Deep/并行/跨 change 时交付完整 Spec。迁出 README 规格改为导航。
+
+## 失败与兼容合同
+
+适用时读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>，把未开始/部分发生/已提交/未知结果、重复/乱序/取消、可重试前提、状态有效性和可见诊断写入原 AC/NFR。公共接口与旧数据变更须给出兼容、迁移和恢复限制。每项绑定真实可观察接缝或待建设接缝，不虚构错误码、性能阈值或安全保证。已知低风险变更不为了填表增加无关条款。
+
+## 验证、状态与交接
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage spec --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+回读真实规格与 Ready 结论，返回负责工件完整路径、行为/验收合同、范围、验证接缝、风险、高影响缺口与验证结果；接续写原 README/规格，不维护调用或全局状态镜像。
+
+只有用户请求或工作流已显式串联时才进入 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>`；产出 Ready Spec 本身不授权实施。
+
+## UI 设计与逻辑原型
+
+涉及 UI 外部行为时读取 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>，硬引用已批准 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 的 revision/digest、项目基线和指定 UI 原型；把页面/状态/交互映射到 Spec AC。未确认、摘要漂移或与行为合同冲突时 UI 部分不可 Ready，返回 P 或相应 owner；不在 S 重新选风格。纯后端不强制设计文档。
+
+LOGIC 原型仍可作为已验证行为和边界证据，记录具体 locator/hash；它不自动成为生产实现，也不要求 UI DESIGN。未闭合高影响产品决定返回 G。

package/template/workflows/specdev/specdev-s-spec/references/spec-readiness.md

@@ -0,0 +1,17 @@
+# Spec Readiness
+
+本检查适用于独立 Spec 或合同允许的 README 等价范围/AC/验证；轻量不机械要求 Spec YAML，但行为、可观察 AC、风险与 Ready 判断不变。独立 Spec 存在则读取它，不能双权威。
+
+- [ ] 问题、目标用户和成功标准从用户或调用者视角可理解。
+- [ ] 主要、边界、错误、角色和状态场景足以生成垂直切片。
+- [ ] 每个用户故事至少被一个验收合同覆盖。
+- [ ] 每个验收合同可观察、可判定且有验证接缝。
+- [ ] IN、REUSE、OUT 无冲突。
+- [ ] 公共接口、数据、兼容、安全、迁移和发布影响已决定或明确不适用。
+- [ ] 已锁定实现约束有来源，没有把偏好伪装成事实。
+- [ ] UI 范围已实际读取并引用批准有效的 change DESIGN、基线 revision/digest 与 UI 原型，页面/状态对应 AC；没有 UI 影响时明确不适用。
+- [ ] 高影响未决问题为零。
+- [ ] 低影响假设可逆且有验证方式。
+- [ ] 项目路径引用使用项目相对 Path 标签，内部工件使用完整根变量 Path 标签。
+- [ ] Spec 不包含逐文件施工清单或容易过时的行号承诺。
+- [ ] 独立 Spec 的 `ready_for_tickets: true` 与实际内容一致；轻量在原 README 明确同等就绪/缺口，不为免拆票创造 Map。

package/template/workflows/specdev/specdev-t-tickets/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: specdev-t-tickets
+description: "将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket，并绑定真实项目 Skill；不用于探索未知需求或执行代码。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/tickets
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 编写计划型 Tickets
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。
+
+每张票都是供新上下文执行的 Plan：说明背景、来源、目标、非目标、真实项目 SKILL 调用、修改顺序、验证和失败停止点。Tickets Map 是统一启动与恢复入口，不是静态清单；它不复制 Ticket 的状态权威。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令，再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由，不默认展开全部技能。
+
+先判断是否确需拆票；单 change、明确范围/AC 且无需 DAG/独立票的任务保留 README 或无票 Goal 清单，不为工具制造 Map。用户明确要求 Ticket 则交付；复杂并行、Deep 或跨 change 使用完整合同。
+
+## 从合同到可执行票
+
+1. **输入与范围**：确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G；无 Ready Spec 时，只有用户材料已等价覆盖全部合同才可规划。
+2. **地形与绑定**：定位真实可维护源、调用方、测试接缝和 Skill 根。按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作；没有适用项目 Skill 时记录扫描证据，不造名称。
+3. **垂直切片**：需要具体拆分时读取 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/planning-procedure.md</Path>` 与 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG，不按技术层制造空价值任务。
+4. **写 Plan**：使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>`。Lite 仅减少不适用说明，不删用户数量、权限、验收或停止条件。所有票必须使用 `plan_contract_version: 1`；旧格式不进入执行。
+5. **写总控**：使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>`，记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口；进度、Ready 与执行 owner 每次从 Ticket/Evidence 回读，不写入 Map。按 AC 反查至少一个负责验证的 Ticket，暴露未覆盖和重复所有权；依赖环、路径重叠与语义共享资源分别检查，不能用“可并行”文字替代实际 DAG/写集。
+6. **Definition of Ready**：读取 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>`，并调用 `<Path>{roots.workflows}/specdev/common/skills/plan-quality-review/SKILL.md</Path>`。缺失引用、必需 Skill、可运行验收或权限边界，当前票不可 ready。
+7. **与用户核对**：展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量；已授权自主规划且无关键未知时不重复请求形式确认。
+8. **验证、回读和交付**：按下述命令检查，再回读真实 Ticket/Map，报告修改、验证结果和未完成项。规划完成不自动进入实现。
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage tickets --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
+node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --map <Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path> --repo <project-root>
+```
+
+需要正式 Goal、多 change、迁移或跨票 Gate 时交给 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`；少量线性票可从 map 按已授权范围调用 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`。不得以“精简”为理由静默更换默认工具或少交付。
+
+## 工程义务与证据失效
+
+每票按实际影响列明真实生产消费者、接口两端、文档/升级说明、回归与模型可见输出的责任；删除测试要给出原风险在新测试中的承接。风险及证据选择使用 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>，失败状态使用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。工具定义或上下文变更才加载 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。
+
+将有关检查合并进负责该行为的 Ticket，不为每个检查项创建一票。documentation 仍用现有 kind，性能实施引用 R 的测量基线，不增加分类 schema。每票说明 base/head、配置、输入或 Skill 改变后哪些证据需重新验证。
+
+## UI 设计绑定与逻辑证据
+
+UI 拆票必读 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 与已批准 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>。UI Ticket 使用 `ui_change: true` 和 `design_ref: {revision, digest, pages, acceptance}` 固定本 change 设计版本、designDigest、页面 ID 与验收 ID；Map 给出共同基线与读取位置。expected_changes 明确命中 UI 文件时同样需要绑定，不能以缺字段绕过。纯非 UI 票可省略或设 ui_change=false、design_ref=null，不制造 UI 门禁。
+
+将组件复用、页面/状态、响应式与真实浏览器验收放入相应垂直切片；缺确认或摘要漂移返回 P，不让执行者重新选择。LOGIC 证据保留 locator/hash，模拟原型不能自动成为生产实现。