@namewta/speculo 0.3.4 → 0.5.0

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

@@ -56,6 +56,22 @@ const VALID_PLAN_MODES = new Set([
   "reference-conformance",
   "release-coordination",
 ]);
+const VALID_DESIGN_TREE_STATUS = new Set(["active", "consensus", "blocked"]);
+const VALID_DESIGN_NODE_STATUS = new Set(["open", "answered", "deferred", "rejected"]);
+const VALID_WAYFINDER_LABEL = new Set([
+  "wayfinder:research",
+  "wayfinder:prototype",
+  "wayfinder:grilling",
+  "wayfinder:task",
+]);
+const VALID_WAYFINDER_STATUS = new Set(["open", "closed"]);
+const VALID_WAYFINDER_RESOLUTION = new Set([
+  null,
+  "answered",
+  "out-of-scope",
+  "superseded",
+  "cancelled",
+]);
 const REQUIRED_TICKET_KEYS = new Set([
   "schema_version",
   "artifact",
@@ -108,6 +124,7 @@ const STATE_ARTIFACT_BASENAMES = new Set([
   "architecture-review.md",
   "architecture-review.html",
   "wayfinder-map.md",
+  "design-tree.json",
 ]);
 const FORBIDDEN_OBSOLETE_BASENAMES = new Set([
   "input-validation.md",
@@ -522,28 +539,38 @@ function capabilityChecks(root) {
       "goal-plan",
       [
         join(root, "P-goal-plan", "P-goal-plan.md"),
-        ["Outcome", "Authority", "DAG", "Gate", "Wave", "Lead", "Definition of Done"],
+        [
+          "Outcome",
+          "Authority",
+          "DAG",
+          "Gate",
+          "Wave",
+          "Lead",
+          "Dispatch Packet",
+          "subagent-delivery",
+          "Definition of Done",
+        ],
       ],
     ],
     [
       "implement",
       [
         join(root, "I-implement", "I-implement.md"),
-        ["design-it-twice", "TDD", "双轴审查", "Evidence", "提交"],
+        ["codebase-design", "design-it-twice", "TDD", "双轴审查", "Evidence", "delegated execution", "subagent-delivery", "提交"],
       ],
     ],
     [
       "wayfinder",
       [
         join(root, "W-wayfinder", "W-wayfinder.md"),
-        ["共享地图", "claimed_investigations", "research", "decision", "并行"],
+        ["共享地图", "claimed_investigations", "wayfinder:prototype", "wayfinder:grilling", "solution comment", "每个会话"],
       ],
     ],
     [
       "architecture-review",
       [
         join(root, "R-review-architecture", "R-review-architecture.md"),
-        ["浅模块", "接缝泄漏", "局部性", "architecture-review.html", "逐项"],
+        ["shallow", "interface", "locality", "Tailwind CDN", "Mermaid CDN", "最佳推荐"],
       ],
     ],
     [
@@ -557,7 +584,7 @@ function capabilityChecks(root) {
       "grill",
       [
         join(root, "G-grill-with-docs", "G-grill-with-docs.md"),
-        ["一次一问", "LOG.md", "CONTEXT.md", "ADR.md", "推荐默认值"],
+        ["完整 frontier", "design-tree.json", "LOG.md", "CONTEXT.md", "ADR.md", "推荐答案"],
       ],
     ],
     [
@@ -583,6 +610,28 @@ function capabilityChecks(root) {
   }
   if (!isFile(join(root, "R-review-architecture", "architecture-review-report-template.html"))) {
     errors.push("architecture review lost its visual HTML report template");
+  } else {
+    const html = readText(join(root, "R-review-architecture", "architecture-review-report-template.html"));
+    for (const marker of ["cdn.tailwindcss.com", "mermaid", "Before", "After", "top-recommendation"]) {
+      if (!html.includes(marker)) errors.push(`architecture HTML template lost marker ${marker}`);
+    }
+  }
+
+  for (const required of [
+    "common/rules/codebase-design.md",
+    "common/schemas/design-tree.schema.json",
+    "common/schemas/wayfinder-ticket.schema.json",
+    "G-grill-with-docs/design-tree-template.json",
+    "W-wayfinder/local-tracker-contract.md",
+    "W-wayfinder/solution-comment-template.md",
+    "R-review-architecture/architecture-report-contract.md",
+  ]) {
+    if (!isFile(join(root, required))) errors.push(`missing architecture/wayfinding contract ${required}`);
+  }
+
+  const mapTemplate = join(root, "W-wayfinder", "wayfinder-map-template.md");
+  if (isFile(mapTemplate) && /^## (?:开放 Tickets|调查清单)/m.test(readText(mapTemplate))) {
+    errors.push("Wayfinder map template must query open Tickets instead of caching them");
   }
   return errors;
 }
@@ -777,6 +826,176 @@ function validateGoalPlan(path, errors) {
   return { path, meta, body };
 }
 
+function validateDesignTree(path, change, errors) {
+  if (!isFile(path)) return null;
+  let data;
+  try {
+    data = JSON.parse(readText(path));
+  } catch (error) {
+    errors.push(`${basename(path)}: invalid JSON: ${error.message}`);
+    return null;
+  }
+
+  if (data.schema_version !== 1 || data.artifact !== "design-tree") {
+    errors.push(`${basename(path)}: artifact/schema_version must be design-tree/1`);
+  }
+  if (data.change !== basename(change)) {
+    errors.push(`${basename(path)}: change must equal directory name ${basename(change)}`);
+  }
+  if (!VALID_DESIGN_TREE_STATUS.has(data.status)) {
+    errors.push(`${basename(path)}: invalid status ${data.status}`);
+  }
+  if (!Number.isInteger(data.round) || data.round < 0) {
+    errors.push(`${basename(path)}: round must be a non-negative integer`);
+  }
+  if (!Array.isArray(data.nodes)) {
+    errors.push(`${basename(path)}: nodes must be a list`);
+    return data;
+  }
+
+  const nodes = new Map();
+  const graph = new Map();
+  for (const node of data.nodes) {
+    const id = String(node?.id ?? "");
+    if (!/^D-\d{3,}$/.test(id)) errors.push(`${basename(path)}: invalid design node id ${id}`);
+    if (nodes.has(id)) errors.push(`${basename(path)}: duplicate design node id ${id}`);
+    nodes.set(id, node);
+    const dependencies = Array.isArray(node?.depends_on) ? node.depends_on.map(String) : [];
+    graph.set(id, dependencies);
+    if (!Array.isArray(node?.depends_on)) {
+      errors.push(`${basename(path)}: ${id} depends_on must be a list`);
+    }
+    for (const key of ["title", "question", "recommendation"]) {
+      if (!String(node?.[key] ?? "").trim()) errors.push(`${basename(path)}: ${id} ${key} is required`);
+    }
+    if (!VALID_DESIGN_NODE_STATUS.has(node?.status)) {
+      errors.push(`${basename(path)}: ${id} has invalid status ${node?.status}`);
+    }
+    if (node?.round !== null && (!Number.isInteger(node?.round) || node.round < 1)) {
+      errors.push(`${basename(path)}: ${id} round must be null or a positive integer`);
+    }
+    if (node?.status !== "open") {
+      if (!String(node?.answer ?? "").trim()) errors.push(`${basename(path)}: ${id} closed node needs an answer`);
+      if (!/^LOG-\d{3,}$/.test(String(node?.log_ref ?? ""))) {
+        errors.push(`${basename(path)}: ${id} closed node needs a LOG-### reference`);
+      }
+    }
+  }
+
+  for (const [id, dependencies] of graph) {
+    for (const dependency of dependencies) {
+      if (!nodes.has(dependency)) errors.push(`${basename(path)}: ${id} depends on missing ${dependency}`);
+      if (dependency === id) errors.push(`${basename(path)}: ${id} cannot depend on itself`);
+    }
+  }
+  const cycle = findCycle(graph);
+  if (cycle) errors.push(`Design tree dependency cycle: ${cycle.join(" -> ")}`);
+  if (
+    data.status === "consensus" &&
+    data.nodes.some((node) => new Set(["open", "deferred"]).has(node?.status))
+  ) {
+    errors.push(`${basename(path)}: consensus design tree cannot contain open or deferred nodes`);
+  }
+
+  const logPath = join(change, "LOG.md");
+  const logText = isFile(logPath) ? readText(logPath) : "";
+  for (const node of data.nodes) {
+    if (node?.log_ref && !logText.includes(String(node.log_ref))) {
+      errors.push(`${basename(path)}: ${node.id} points to missing ${node.log_ref} in LOG`);
+    }
+  }
+  return data;
+}
+
+function validateWayfinder(change, errors) {
+  const mapPath = join(change, "wayfinder-map.md");
+  const investigationDir = join(change, "investigation");
+  if (!isFile(mapPath) && !isDirectory(investigationDir)) return null;
+  if (!isFile(mapPath)) errors.push("Wayfinder investigations exist but the map is missing");
+  if (!isDirectory(investigationDir)) {
+    errors.push("Wayfinder map exists but the investigation directory is missing");
+    return null;
+  }
+
+  if (isFile(mapPath)) {
+    const { meta } = parseFrontmatter(mapPath);
+    if (meta.artifact !== "wayfinder-map") errors.push("wayfinder-map.md: artifact must be wayfinder-map");
+    if (meta.change !== basename(change)) {
+      errors.push(`wayfinder-map.md: change must equal directory name ${basename(change)}`);
+    }
+  }
+
+  const ticketPaths = readdirSync(investigationDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => join(investigationDir, entry.name))
+    .sort();
+  const tickets = new Map();
+  const graph = new Map();
+  for (const path of ticketPaths) {
+    const { meta } = parseFrontmatter(path);
+    const id = String(meta.id ?? "");
+    if (meta.artifact !== "wayfinder-ticket") {
+      errors.push(`${basename(path)}: artifact must be wayfinder-ticket`);
+    }
+    if (!/^INV-\d{2,}$/.test(id)) errors.push(`${basename(path)}: invalid Wayfinder Ticket id ${id}`);
+    if (tickets.has(id)) errors.push(`duplicate Wayfinder Ticket id ${id}`);
+    tickets.set(id, { path, meta });
+    if (!basename(path).startsWith(id)) errors.push(`${basename(path)}: filename must start with ${id}`);
+    if (!String(meta.name ?? "").trim()) errors.push(`${basename(path)}: name is required`);
+    const parentMap = typeof meta.parent_map === "string" ? stripPathTag(meta.parent_map) : null;
+    if (parentMap === null || !parentMap.endsWith("/wayfinder-map.md")) {
+      errors.push(`${basename(path)}: parent_map must be a rooted Wayfinder map Path`);
+    }
+    if (!VALID_WAYFINDER_LABEL.has(meta.label)) {
+      errors.push(`${basename(path)}: invalid Wayfinder label ${meta.label}`);
+    }
+    if (!VALID_WAYFINDER_STATUS.has(meta.status)) {
+      errors.push(`${basename(path)}: invalid Wayfinder status ${meta.status}`);
+    }
+    const dependencies = Array.isArray(meta.blocked_by) ? meta.blocked_by.map(String) : [];
+    if (!Array.isArray(meta.blocked_by)) errors.push(`${basename(path)}: blocked_by must be a list`);
+    graph.set(id, dependencies);
+    if (!VALID_WAYFINDER_RESOLUTION.has(meta.resolution)) {
+      errors.push(`${basename(path)}: invalid Wayfinder resolution ${meta.resolution}`);
+    }
+    if (meta.status === "open" && meta.resolution !== null) {
+      errors.push(`${basename(path)}: open Wayfinder Ticket must have resolution: null`);
+    }
+    if (meta.status === "closed" && meta.resolution === null) {
+      errors.push(`${basename(path)}: closed Wayfinder Ticket needs a resolution`);
+    }
+  }
+
+  for (const [id, dependencies] of graph) {
+    for (const dependency of dependencies) {
+      if (!tickets.has(dependency)) errors.push(`${id}: blocked_by references missing ${dependency}`);
+      if (dependency === id) errors.push(`${id}: Wayfinder Ticket cannot block itself`);
+    }
+  }
+  const cycle = findCycle(graph);
+  if (cycle) errors.push(`Wayfinder dependency cycle: ${cycle.join(" -> ")}`);
+
+  const commentsRoot = join(investigationDir, "comments");
+  for (const [id, ticket] of tickets) {
+    if (ticket.meta.status !== "closed") continue;
+    const commentDir = join(commentsRoot, id);
+    const comments = isDirectory(commentDir)
+      ? readdirSync(commentDir).filter((name) => /^\d{2,}-solution\.md$/.test(name)).sort()
+      : [];
+    if (!comments.length) {
+      errors.push(`${id}: closed Wayfinder Ticket has no solution comment`);
+      continue;
+    }
+    for (const name of comments) {
+      const { meta } = parseFrontmatter(join(commentDir, name));
+      if (meta.artifact !== "wayfinder-solution-comment" || meta.ticket !== id) {
+        errors.push(`${toPosix(relative(change, join(commentDir, name)))}: invalid solution comment identity`);
+      }
+    }
+  }
+  return tickets;
+}
+
 function validateTicket(path, errors) {
   const { meta, body } = parseFrontmatter(path);
   const missing = [...REQUIRED_TICKET_KEYS].filter((key) => !(key in meta));
@@ -930,6 +1149,8 @@ function validateChange(change) {
   const spec = validateSpec(join(change, "spec.md"), errors, warnings);
   const ticketsMap = validateMap(join(change, "tickets-map.md"), errors);
   const goalPlan = validateGoalPlan(join(change, "goal-plan.md"), errors);
+  validateDesignTree(join(change, "design-tree.json"), change, errors);
+  validateWayfinder(change, errors);
   for (const artifact of [spec, ticketsMap, goalPlan]) {
     if (artifact && artifact.meta.change !== basename(change)) {
       errors.push(`${basename(artifact.path)}: change must equal directory name ${basename(change)}`);

package/template/skills/agents-md-builder/SKILL.md

@@ -1,30 +0,0 @@
----
-id: agents-md-builder
-type: skill
-name: AGENTS.md Builder
-description: 扫描 manifest 目录并生成有证据、极简且形成父子导航树的 AGENTS.md 与 CLAUDE.md。
----
-
-# AGENTS.md Builder
-
-每份 AGENTS.md 是模块导读。逐行执行删除测试：删除后不会使代理犯错的内容不进入产物。
-
-## 输入
-
-- 项目根（默认 runtime context 的 project root）与可选目标子树。
-- 可选 manifest 类型过滤和输出语言（默认中文）。
-
-## 流程
-
-1. 读取 `references/manifest-discovery.md`，发现 manifest 目录、忽略目录和父子树；同时列出无 manifest 却存在代理手册的目录。完成标准：扫描范围内每个 manifest 恰好出现一次，所有孤立手册已列为候选而未直接删除。
-2. 读取 `references/role-classification.md`，按优先级为每个目录判定唯一角色。完成标准：所有目录都有角色及支持证据，没有多重分类。
-3. 读取 `references/evidence-collection.md`，收集 manifest、入口、依赖、消费方和测试。完成标准：每个将写入的结论都能指向真实文件。
-4. 读取 `references/content-contract.md`、`references/writing-style.md` 和对应 `references/templates/*`，自底向上生成或更新 AGENTS.md。完成标准：父子 routing 完整、内容不跨模块重复且逐行通过删除测试。
-5. 读取 `references/claude-redirect.md` 生成同层 CLAUDE.md；展示创建、更新和删除候选，确认后再写入。完成标准：每个合法 AGENTS.md 有唯一重定向，非法候选的处置有记录。
-
-## 输出
-
-- 生成/更新的 AGENTS.md 与 CLAUDE.md 清单。
-- 按角色统计、证据缺口和经确认清理的孤立文件清单。
-
-本 skill 不自行选择 Speculo 报告路径；需要持久化时由调用方提供。

package/template/skills/typescript-engineering-standards/README.md

@@ -1,36 +0,0 @@
-# TypeScript Engineering Standards Skill
-
-这是一个采用渐进式披露结构的通用 TypeScript 工程规范 Skill。
-
-## 使用方式
-
-将整个 `typescript-engineering-standards/` 目录放入支持 Skill 的目录中，并以 `SKILL.md` 作为入口。不同平台的 Skill 安装位置可能不同；保持目录内部相对路径不变即可。
-
-## 目录说明
-
-```text
-typescript-engineering-standards/
-├── SKILL.md              # 主入口：触发条件、工作流、参考路由
-├── references/           # 详细规范，按任务最小化读取
-├── templates/            # AGENTS、tsconfig、格式化、PR 与评审模板
-├── examples/             # 目录、命名、类型、注释和审查示例
-└── manifest.txt          # 包内文件清单
-```
-
-## 设计原则
-
-- `SKILL.md` 保持相对精简，不承载所有细节。
-- 详细规则按主题拆分到 `references/`。
-- 执行具体任务时只读取必要参考。
-- 模板是起点，不直接覆盖现有仓库配置。
-- 用户要求、平台约束和仓库事实优先于通用默认规则。
-
-## 推荐入口
-
-- 创建或审查项目目录：`references/01-project-architecture-and-directory-layout.md`
-- 文件和标识符命名：`references/02-file-directory-and-symbol-naming.md`
-- TypeScript 类型安全：`references/04-typescript-type-system.md`
-- 注释和 JSDoc：`references/06-comments-jsdoc-and-documentation.md`
-- 测试：`references/07-testing-strategy.md`
-- 格式化、Lint、复杂度：`references/10-formatting-lint-and-complexity.md`
-- CI 和质量门禁：`references/11-configuration-dependencies-and-ci.md`

package/template/skills/typescript-engineering-standards/SKILL.md

@@ -1,158 +0,0 @@
----
-name: typescript-engineering-standards
-description: 为 TypeScript、JavaScript、React、Node.js、Electron、CLI、npm 库与 Monorepo 项目提供可渐进加载的工程规范。用于新建项目、生成代码、目录设计、命名、类型建模、代码审查、重构、测试、Lint、CI、安全与质量门禁；详细规则按任务从 references/ 中最小化读取。
----
-
-# TypeScript Engineering Standards Skill
-
-本 Skill 将 TypeScript 工程规范拆成一个轻量主入口和多个主题参考文档。执行任务时采用**渐进式披露**：先判断任务类型，再只读取必要参考，避免把全部规范一次性加入上下文。
-
-## 适用任务
-
-在以下任务中使用本 Skill：
-
-- 设计或调整 TypeScript 项目目录。
-- 创建、重命名、移动 `.ts`、`.tsx`、测试或声明文件。
-- 编写、补全、重构或审查 TypeScript/React/Node.js 代码。
-- 制定团队编码规范、`AGENTS.md`、`CONTRIBUTING.md` 或 PR 检查清单。
-- 配置 TypeScript、格式化、Lint、测试、构建与 CI。
-- 处理类型安全、异步、错误、资源清理、安全、性能或跨平台问题。
-- 对现有仓库做工程质量审计。
-
-不在以下场景机械套用：
-
-- 用户明确指定了不同规范。
-- 框架、生成器或公开 API 有不可违背的约定。
-- 任务仅是解释一段代码且不涉及代码修改或规范判断。
-
-## 规则优先级
-
-发生冲突时依次遵循：
-
-1. 用户的明确要求。
-2. 当前仓库已生效的配置、公共 API 与框架约定。
-3. 当前模块已经形成且一致的局部惯例。
-4. 本 Skill 的通用默认规则。
-
-不要为了符合本 Skill 而进行与任务无关的大规模重命名、格式化或架构迁移。发现历史问题时，区分“本次必须修复”和“建议后续治理”。
-
-## 核心执行流程
-
-### 1. 识别任务和边界
-
-先判断：
-
-- 项目类型：Web、React、Node.js、Electron、CLI、库或 Monorepo。
-- 任务类型：新建、增量开发、重构、审查、修复、规范制定或配置。
-- 运行边界：浏览器、服务端、主进程、预加载、Worker、测试环境。
-- 变更范围：单文件、单领域、跨模块或全仓库。
-
-### 2. 检查仓库事实
-
-修改现有项目时，优先检查：
-
-- `package.json` 与锁文件。
-- `tsconfig*.json`。
-- ESLint、Oxlint、Prettier、Oxfmt、Biome 等配置。
-- 测试配置与现有测试命名。
-- `src/` 目录结构、路径别名和导出方式。
-- `AGENTS.md`、`CONTRIBUTING.md`、README 与 CI 工作流。
-
-不要假设项目使用 React、ESLint、Prettier、Vitest、Zod 或某种模块系统。
-
-### 3. 最小化读取参考文档
-
-仅加载与任务直接相关的参考文档。只有进行全仓库规范设计或综合审计时，才读取多个主题。
-
-| 任务 | 首选参考 |
-|---|---|
-| 判断规则强度、处理冲突 | `references/00-standard-levels-and-precedence.md` |
-| 设计目录、拆模块、平铺策略 | `references/01-project-architecture-and-directory-layout.md` |
-| 文件、目录、变量、类型命名 | `references/02-file-directory-and-symbol-naming.md` |
-| 导入、导出、Barrel、依赖方向 | `references/03-modules-imports-exports-and-dependencies.md` |
-| 类型、`unknown`、联合、声明文件 | `references/04-typescript-type-system.md` |
-| 函数、异步、错误、资源生命周期 | `references/05-functions-async-errors-and-resources.md` |
-| 注释、JSDoc、TODO、文档 | `references/06-comments-jsdoc-and-documentation.md` |
-| 单元、集成、契约、E2E 测试 | `references/07-testing-strategy.md` |
-| React、Hook、状态、可访问性 | `references/08-react-and-frontend.md` |
-| Node.js、CLI、路径、环境变量 | `references/09-node-cli-and-cross-platform.md` |
-| 格式、Lint、文件大小、复杂度 | `references/10-formatting-lint-and-complexity.md` |
-| 配置、依赖、脚本、CI | `references/11-configuration-dependencies-and-ci.md` |
-| 安全、性能、国际化 | `references/12-security-performance-and-i18n.md` |
-| Git、PR、评审和交付 | `references/13-git-review-and-delivery.md` |
-| 老项目迁移、例外和渐进治理 | `references/14-adoption-exceptions-and-migration.md` |
-| 了解 Orca 中提炼出的工程习惯 | `references/15-orca-derived-observations.md` |
-
-完整索引见 `references/README.md`。
-
-### 4. 应用核心默认规则
-
-除非仓库事实或用户要求另有规定，默认遵守：
-
-- 先按运行环境和业务领域划分边界，领域内部局部平铺。
-- 文件名表达“领域 + 职责”，避免 `utils`、`helpers`、`common`、`misc` 等模糊名称。
-- 一个文件只有一个主要职责；不要为单个文件机械创建目录。
-- 默认使用命名导出，控制公共 API，禁止无意义全局 Barrel。
-- TypeScript 开启严格模式；外部输入先作为 `unknown` 并在边界验证。
-- 优先使用可辨识联合表达状态，使无效状态难以构造。
-- 所有 Promise、监听器、Timer、连接和进程都有明确处理与清理路径。
-- 注释解释原因、约束与权衡，不逐行翻译代码。
-- 单元测试靠近源码；跨模块集成与 E2E 测试放在独立测试目录。
-- 通过格式化、Lint、类型检查、测试和构建形成自动化门禁。
-
-### 5. 生成或修改代码
-
-生成代码时：
-
-- 遵循仓库现有模块系统和格式风格。
-- 新公开函数写明确返回类型。
-- 不引入未经请求的新框架或依赖。
-- 不用 `any`、双重断言、规则禁用或删除测试掩盖问题。
-- 需要外部验证时，在边界层完成，不把不可信类型传播到内部。
-- 修复缺陷时优先补回归测试。
-- 只修改任务相关文件，避免格式噪声。
-
-### 6. 审查和输出
-
-代码审查时按以下优先级报告：
-
-1. 正确性、安全和数据损坏风险。
-2. 类型系统未覆盖的运行时风险。
-3. 资源泄漏、竞态、取消与错误处理。
-4. 架构边界、循环依赖和公共 API。
-5. 测试缺口。
-6. 命名、文件大小和可维护性。
-7. 纯风格建议。
-
-每条问题尽量包含：位置、风险、触发条件、修复方向。不要把个人偏好描述成缺陷。
-
-## 常用模板
-
-- 精简团队规则：`templates/AGENTS.typescript.md`
-- 严格 TypeScript 基线：`templates/tsconfig.base.json`
-- 多环境项目引用：`templates/tsconfig.project-references.json`
-- 格式化基线：`templates/prettier.json`
-- 编辑器基线：`templates/.editorconfig`
-- npm 脚本示例：`templates/package-scripts.json`
-- PR 模板：`templates/pull-request-template.md`
-- 代码评审清单：`templates/code-review-checklist.md`
-
-模板是起点，不得在未检查项目工具链时直接覆盖现有配置。
-
-## 示例
-
-- 项目目录示例：`examples/project-layouts.md`
-- 命名模式示例：`examples/naming-patterns.md`
-- 类型建模示例：`examples/type-modeling-patterns.md`
-- 注释示例：`examples/comment-patterns.md`
-- 审查输出示例：`examples/review-output-example.md`
-
-## 交付要求
-
-完成任务前确认：
-
-- 变更符合当前仓库事实，而非仅符合抽象规范。
-- 必要测试和质量检查已执行，或明确说明未能执行的项目。
-- 没有增加无意义目录、模糊文件名或隐藏依赖。
-- 没有通过削弱类型、关闭规则或跳过测试来获得表面通过。
-- 输出聚焦本次任务；更广泛的治理建议单独列出，不混入必要修复。

package/template/skills/typescript-engineering-standards/examples/comment-patterns.md

@@ -1,47 +0,0 @@
-# 注释模式示例
-
-## 兼容性
-
-```ts
-// Why: Windows reports the executable path with inconsistent drive-letter casing.
-const normalizedPath = normalizeWindowsDriveLetter(executablePath)
-```
-
-## 第三方缺陷
-
-```ts
-// Why: SDK 4.2 can invoke this callback twice after cancellation.
-if (requestState.isSettled) {
-  return
-}
-```
-
-## 安全顺序
-
-```ts
-// Validate before resolving the path so traversal segments cannot escape the root.
-const safeRelativePath = parseRelativePath(input)
-```
-
-## 性能
-
-```ts
-// Keep the compiled expression outside the hot loop; this runs for every log line.
-const ansiPattern = createAnsiPattern()
-```
-
-## 不推荐
-
-```ts
-// Loop through items.
-for (const item of items) {
-  // Add the item.
-  results.push(item)
-}
-```
-
-## TODO
-
-```ts
-// TODO(PROJ-1423): Remove the v2 fallback after desktop 3.8 reaches 95% adoption.
-```

package/template/skills/typescript-engineering-standards/examples/naming-patterns.md

@@ -1,42 +0,0 @@
-# 命名示例
-
-## 从模糊名称改为具体名称
-
-| 模糊 | 推荐 |
-|---|---|
-| `utils.ts` | `shell-command-quote.ts` |
-| `helpers.ts` | `workspace-path-normalize.ts` |
-| `manager.ts` | `terminal-process-registry.ts` |
-| `handler.ts` | `payment-webhook-handler.ts` |
-| `service.ts` | `user-session-service.ts` |
-| `data.ts` | `workspace-summary.ts` |
-| `types.ts` | `payment-contract.ts` |
-| `constants.ts` | `terminal-limits.ts` |
-
-## 函数
-
-| 含义弱 | 推荐 |
-|---|---|
-| `handle()` | `handleWorkspaceClosed()` |
-| `process()` | `parseTerminalOutput()` |
-| `check()` | `validateWorkspacePath()` |
-| `getData()` | `loadUserProfile()` |
-| `doRetry()` | `retryPaymentCapture()` |
-
-## 布尔值
-
-| 含义弱 | 推荐 |
-|---|---|
-| `flag` | `shouldPersist` |
-| `enabled` | `isTelemetryEnabled` |
-| `valid` | `isWorkspacePathValid` |
-| `notReady` | `isInitializing` 或 `isReady` |
-
-## 单位
-
-| 含义弱 | 推荐 |
-|---|---|
-| `timeout` | `timeoutMs` |
-| `size` | `payloadSizeBytes` |
-| `delay` | `retryDelayMs` |
-| `limit` | `pageSizeLimit` |

package/template/skills/typescript-engineering-standards/examples/project-layouts.md

@@ -1,75 +0,0 @@
-# 项目目录示例
-
-## 小型 Node 服务
-
-```text
-src/
-├── app/
-│   ├── create-server.ts
-│   └── load-environment.ts
-├── features/
-│   └── user-auth/
-│       ├── authenticate-user.ts
-│       ├── authenticate-user.test.ts
-│       └── user-token.ts
-├── infrastructure/
-│   ├── database/
-│   └── http/
-└── shared/
-    └── result.ts
-```
-
-## React 应用
-
-```text
-src/
-├── app/
-│   ├── App.tsx
-│   └── routes.tsx
-├── features/
-│   ├── workspace-search/
-│   │   ├── WorkspaceSearchPanel.tsx
-│   │   ├── workspace-search-query.ts
-│   │   └── use-workspace-search.ts
-│   └── user-settings/
-├── shared/
-│   ├── components/
-│   └── hooks/
-└── infrastructure/
-    └── api/
-```
-
-`shared/components` 只放真正无业务归属且有多个真实调用方的组件。
-
-## Electron
-
-```text
-src/
-├── main/
-│   ├── app-lifecycle.ts
-│   └── windows/
-├── preload/
-│   └── workspace-api.ts
-├── renderer/
-│   ├── app/
-│   └── features/
-├── shared/
-│   └── workspace-contract.ts
-└── types/
-    └── electron-api.d.ts
-```
-
-## Monorepo
-
-```text
-apps/
-├── web/
-└── api/
-packages/
-├── domain/
-├── contracts/
-├── ui/
-└── test-support/
-```
-
-包边界应与独立发布、运行环境或稳定依赖方向对应，不要仅为缩短相对路径拆包。