@namewta/speculo 0.4.0 → 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/workflows/specdev/I-implement/codebase-design-glossary.md

@@ -1,12 +0,0 @@
-# 代码库设计术语
-
-- **模块**：隐藏复杂度并提供稳定接口的单元，不等于目录或类。
-- **深度**：接口简单度相对于模块内部承载复杂度的杠杆。
-- **接口**：调用者必须知道的全部，包括类型、不变量、顺序、错误和性能语义。
-- **接缝**：可以替换、观察或验证行为的位置。
-- **适配器**：把外部变化隔离在稳定接缝外的实现。
-- **信息隐藏**：设计决定只存在于一个权威位置。
-- **局部性**：完成一个行为所需理解和修改的范围尽可能集中。
-- **时间耦合**：调用必须按隐含顺序发生；应显式化或封装。
-
-检查目标：减少调用者认知，而不是单纯减少行数或文件数。

package/template/workflows/specdev/I-implement/deepening.md

@@ -1,17 +0,0 @@
-# 深化与依赖策略
-
-## 依赖分类
-
-1. 进程内稳定依赖：直接调用通常足够。
-2. 本地可替换依赖：在真实替换/测试需要处建立接缝。
-3. 远程但自有：封装协议、超时、重试、幂等和可观测性。
-4. 真正外部：适配器隔离版本、失败、限流和不可控变化。
-
-不要为了“可测试”给每个类加接口。接缝应服务真实变化轴或高价值验证。
-
-## 深化问题
-
-- 能否让调用者少知道一个状态、顺序或错误分支？
-- 能否把重复策略收进单一模块？
-- 是否把外部 SDK 类型泄漏到领域层？
-- 是否有至少两个真实消费者/适配器证明抽象成立？