@namewta/speculo 0.6.0 → 0.7.0

package/template/skills/github-npm-ops/scripts/issue-transport.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function parseArgs(argv) {
+  const [operation, ...rest] = argv;
+  const options = { labels: [] };
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (token === "--apply") {
+      options.apply = true;
+      continue;
+    }
+    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
+    const key = token.slice(2).replaceAll("-", "_");
+    const value = rest[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`${token} requires a value`);
+    }
+    index += 1;
+    if (key === "label") options.labels.push(value);
+    else options[key] = value;
+  }
+  return { operation, options };
+}
+
+function requireOptions(options, keys) {
+  const missing = keys.filter((key) => !String(options[key] ?? "").trim());
+  if (missing.length) throw new Error(`missing options: ${missing.map((key) => `--${key.replaceAll("_", "-")}`).join(", ")}`);
+}
+
+async function gh(args) {
+  try {
+    const { stdout } = await execFileAsync("gh", args, {
+      maxBuffer: 16 * 1024 * 1024,
+      encoding: "utf8",
+    });
+    return stdout.trim();
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    throw new Error(`gh ${args[0]} failed: ${detail}`);
+  }
+}
+
+async function readIssue(repo, number) {
+  return JSON.parse(
+    await gh([
+      "issue",
+      "view",
+      number,
+      "--repo",
+      repo,
+      "--json",
+      "number,title,body,state,url,author,labels,createdAt,updatedAt,comments",
+    ]),
+  );
+}
+
+async function issueRead(options) {
+  requireOptions(options, ["repo", "number"]);
+  const issue = await readIssue(options.repo, options.number);
+  return {
+    operation: "issue-read",
+    provider: "github",
+    repo: options.repo,
+    kind: "issue",
+    ...issue,
+  };
+}
+
+async function prRead(options) {
+  requireOptions(options, ["repo", "number"]);
+  const pull = JSON.parse(
+    await gh([
+      "pr",
+      "view",
+      options.number,
+      "--repo",
+      options.repo,
+      "--json",
+      "number,title,body,state,url,author,labels,createdAt,updatedAt,comments,baseRefName,baseRefOid,headRefName,headRefOid,files",
+    ]),
+  );
+  return {
+    operation: "pr-read",
+    provider: "github",
+    repo: options.repo,
+    kind: "pull-request",
+    ...pull,
+  };
+}
+
+async function issueSearch(options) {
+  requireOptions(options, ["repo", "query"]);
+  const issues = JSON.parse(
+    await gh([
+      "issue",
+      "list",
+      "--repo",
+      options.repo,
+      "--search",
+      options.query,
+      "--state",
+      options.state || "all",
+      "--limit",
+      options.limit || "20",
+      "--json",
+      "number,title,state,url,labels,updatedAt",
+    ]),
+  );
+  return { operation: "issue-search", provider: "github", repo: options.repo, issues };
+}
+
+async function issueCreate(options) {
+  requireOptions(options, ["repo", "title", "body_file"]);
+  const plan = {
+    operation: "issue-create",
+    provider: "github",
+    repo: options.repo,
+    title: options.title,
+    body_file: options.body_file,
+    labels: options.labels,
+    mode: options.apply ? "apply" : "dry-run",
+  };
+  if (!options.apply) return plan;
+
+  await readFile(options.body_file, "utf8");
+  const args = [
+    "issue",
+    "create",
+    "--repo",
+    options.repo,
+    "--title",
+    options.title,
+    "--body-file",
+    options.body_file,
+  ];
+  for (const label of options.labels) args.push("--label", label);
+  return { ...plan, url: await gh(args), status: "created" };
+}
+
+async function issueCommentClose(options) {
+  requireOptions(options, ["repo", "number", "comment_file", "marker"]);
+  const marker = `<!-- ${options.marker} -->`;
+  const comment = (await readFile(options.comment_file, "utf8")).trim();
+  const before = await readIssue(options.repo, options.number);
+  const markerExists = (before.comments ?? []).some((item) =>
+    String(item?.body ?? "").includes(marker),
+  );
+  const plan = {
+    operation: "issue-comment-close",
+    provider: "github",
+    repo: options.repo,
+    number: Number(options.number),
+    url: before.url,
+    mode: options.apply ? "apply" : "dry-run",
+    state_before: before.state,
+    comment_required: !markerExists,
+    close_required: String(before.state).toUpperCase() !== "CLOSED",
+    marker: options.marker,
+    steps: [],
+  };
+  if (!options.apply) return plan;
+
+  if (!markerExists) {
+    await gh([
+      "issue",
+      "comment",
+      options.number,
+      "--repo",
+      options.repo,
+      "--body",
+      `${comment}\n\n${marker}`,
+    ]);
+    plan.steps.push("commented");
+  } else {
+    plan.steps.push("comment-already-present");
+  }
+  if (String(before.state).toUpperCase() !== "CLOSED") {
+    await gh([
+      "issue",
+      "close",
+      options.number,
+      "--repo",
+      options.repo,
+      "--reason",
+      options.reason || "completed",
+    ]);
+    plan.steps.push("closed");
+  } else {
+    plan.steps.push("already-closed");
+  }
+
+  const after = await readIssue(options.repo, options.number);
+  if (String(after.state).toUpperCase() !== "CLOSED") {
+    throw new Error(`issue remained ${after.state} after close operation`);
+  }
+  return { ...plan, state_after: after.state, status: "closed" };
+}
+
+function usage() {
+  return `Usage:
+  issue-transport.mjs issue-read --repo OWNER/REPO --number N
+  issue-transport.mjs pr-read --repo OWNER/REPO --number N
+  issue-transport.mjs issue-search --repo OWNER/REPO --query TEXT [--state all] [--limit 20]
+  issue-transport.mjs issue-create --repo OWNER/REPO --title TEXT --body-file PATH [--label LABEL] [--apply]
+  issue-transport.mjs issue-comment-close --repo OWNER/REPO --number N --comment-file PATH --marker ID [--reason completed] [--apply]`;
+}
+
+try {
+  const { operation, options } = parseArgs(process.argv.slice(2));
+  if (!operation || ["help", "--help", "-h"].includes(operation)) {
+    console.log(usage());
+  } else {
+    const handlers = { issueRead, prRead, issueSearch, issueCreate, issueCommentClose };
+    const handler = handlers[operation.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())];
+    if (!handler) throw new Error(`unknown operation: ${operation}\n${usage()}`);
+    console.log(JSON.stringify(await handler(options), null, 2));
+  }
+} catch (error) {
+  console.error(`ERROR: ${error.message}`);
+  process.exitCode = 1;
+}

package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md

@@ -3,168 +3,54 @@ id: specdev/archive-and-consolidate
 type: workflow-entry
 workflow: specdev
 name: 归档与沉淀
-description: 双模式沉淀 Work——归档已验证完成的 change 并提升其知识，或在没有可归档 change 时以当前代码为基本事实深度访谈用户，把经验证的架构决策与领域术语提升为永久知识。
+description: 校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
 keywords: [归档, consolidation, ADR, context, research, knowledge, 代码库访谈]
 ---
 
 # 归档与沉淀
 
-本 Work 的唯一目的：让**永久知识**只保存“当前仍真实、超出单个 change 仍有用、已有实现证据”的结论，同时保留历史与 supersedes 关系。
+A 是 SpecDev 的归档 wrapper：它拥有模式选择、SpecDev 完成门和代码访谈；机械扫描、dry-run、知识毕业、合并、清理、移动与重读由 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 单一维护。
 
-它有两个入口模式，最终收束到同一条“评估 → 提升 → 归档”尾部：
+## 模式
 
-- **archive 模式**：存在已验证完成、用户授权归档的 change 时，归档该 change 并提升其内部产物中的知识。
-- **consolidate-from-code 模式**：没有可归档 change，或用户明确要求“基于当前代码沉淀知识”时，以当前代码库为基本事实，一次一问深度访谈用户，把结论沉淀为永久领域上下文与架构决策。**这次访谈运行本身也是一个 change**：所有访谈轨迹、LOG、CONTEXT、ADR 先落在该 change 内，经代码验证后再提升到永久 store，最后归档该 change。
+- **archive**：处理用户指定或唯一的 completed change。
+- **consolidate-from-code**：用户明确要求从当前代码沉淀知识，或没有可归档 change；本次访谈本身创建一个 change，形成、验证、完成后再归档。
 
-归档不是把整个 change 无差别复制到永久知识库；访谈也不是把用户随口结论直接写成永久 ADR。两条路径都必须先有代码或实现证据，再提升。
+多个候选或模式冲突时请求消歧，不猜测。
 
-## 输入
+## Archive 模式
 
-### 共同输入
+1. 读取全局/change 状态、Ticket、Map、Goal Plan、Evidence、ADR、CONTEXT、LOG、triage 和项目验证事实。
+2. 加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，确认 `change_status: completed`、完成 owner 已写入时间和证据、无 blocker/deviation。
+3. 检查 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action`：`pending-close` 或 `close-failed` 返回 `<Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>`；只有 `closed | waived | not-applicable` 继续。
+4. 调用 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 的 `archive-single + dry-run`，传入已解析 workflow/state/changes/archive/knowledge roots。展示完整移动、提升和清理计划。
+5. 只有用户明确批准该计划后调用 `confirmed`。移动、知识写入和清理均使用计划内路径；计划后出现 drift 时停止。
+6. 重读源、归档目标、全局索引、归档 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>` 和永久知识；运行 `--stage complete` 及包级校验，报告每个提升/跳过结论。
 
-- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
-- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
-- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
-- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
-- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
-- 工件职责规则：`<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
+## Consolidate-from-code 模式
 
-### archive 模式输入
+1. 创建 `<Path>{roots.state}/specdev/changes/{change}/</Path>`、change 状态、LOG、CONTEXT 和 ADR，并登记 `current_work`。
+2. 加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`，每轮先探索代码/配置/测试并陈述证据，再一次只问一个真正影响长期理解的问题。
+3. 按 LOG → CONTEXT → ADR 顺序写入：CONTEXT 只保存项目规范术语；ADR 只有同时满足难逆转、令人意外和真实权衡时才创建。
+4. 用户结论必须由当前代码或实际行为验证；未验证内容留在 LOG，不提升。
+5. 按 change completion 规则由本 Work 关闭该非实现型 change，再进入 Archive 模式的 dry-run/确认流程。
 
-- change 根：`<Path>{roots.state}/specdev/changes/{change}/</Path>`
-- change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
-- 该 change 内的实现产物（存在即读，不存在静默跳过）：
-  - `<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}/spec.md</Path>`
-  - `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-  - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
-  - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+## 副作用
 
-### consolidate-from-code 模式输入
-
-- 项目代码、配置、接口、schema、测试与经验证文档——这是本模式的**基本事实源**。
-- 可选参考：与访谈主题相关的历史 change（`<Path>{roots.state}/specdev/changes/</Path>` 或 `<Path>{roots.state}/specdev/archive/</Path>`）。存在则读取以避免重复结论；不存在时直接以代码为事实访谈，不把“无相关 change”当作缺陷。
-
-不存在的可选输入静默跳过，不把缺失文件伪装成已确认事实。
-
-## 流程
-
-### 0. 判定模式
-
-读取 `<Path>{roots.state}/specdev/status.json</Path>` 并判定：
-
-- 用户或调用方**显式指定模式**时以其为准。
-- 存在唯一 `change_status: completed` 且已获授权归档的 change → **archive 模式**，`{change}` 即该 change。
-- 没有可归档 change → **consolidate-from-code 模式**。
-- 同时存在多个可归档候选，或既有可归档 change 又收到“基于代码沉淀”请求 → 停止并请用户消歧，不猜测。
-
-判定结果记入本次运行的状态摘要。archive 模式进入 §1a；consolidate-from-code 模式进入 §1b。
-
----
-
-### 1a. archive 模式 · 完成检查
-
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>`，检查 Ticket、Evidence、Spec 合同、Goal Gate、偏差、迁移、状态和用户授权。
-
-未完成、验证失败、存在未批准 deviation 或用户未授权时停止，不得标 completed 或 archived。
-
-### 2a. archive 模式 · 冻结归档快照
-
-记录：
-
-- 归档时间；
-- 最终基线、提交或 PR；
-- 全局验证摘要；
-- 已知残余风险；
-- 被批准的 cancelled/deferred 条目；
-- 归档目标 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
-
-归档前不得删除设计日志、Evidence 或被替代 ADR。完成后进入 §3（共同的知识评估）。
-
----
-
-### 1b. consolidate-from-code 模式 · 建立访谈 change
-
-创建承载本次沉淀运行的 change：`<Path>{roots.state}/specdev/changes/{change}/</Path>`，`{change}` 使用 `<YYYY-MM-DD>-<topic>`（topic 为访谈主题，如 `consolidate-auth-domain`）。
-
-首次创建：
-
-- 生命周期状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`，使用 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`；
-- 设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`；
-- 领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`；
-- 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
-
-在 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 中登记该 change，`current_work` 设为 `specdev/archive-and-consolidate`，并在 `work_history` 追加一条未完成记录。恢复已有访谈 change 时先读取三份文档与最后一条 LOG，不重复询问已确认结论。
-
-### 2b. consolidate-from-code 模式 · 代码为事实的深度访谈
-
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`，以当前代码库为基本事实一次一问访谈。每轮：先只读探索相关代码/配置/测试并陈述证据 → 提出唯一关键问题 → 给出选项、权衡与推荐 → 等待用户 confirmed/deferred/rejected → 立即把结果追加到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
-
-按固定顺序同步 change 内文档：先写 LOG，再把当前仍真实的术语/不变量/代码映射写入 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`，最后把满足条件的长期架构决策写入 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。历史轨迹不进 CONTEXT，未确认选项不写成已接受 ADR。
-
-访谈收束后进入 §3（共同的知识评估）。此时该 change 视为“已完成访谈、可提升与归档”。
-
----
-
-### 3. 评估长期知识（共同）
-
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md</Path>`，逐条评估 change 内（archive 模式来自实现产物，consolidate-from-code 模式来自访谈结论）的架构决策、领域术语和研究结论。
-
-每条结论执行：`create | update | merge | supersede | deprecate | skip`。无法判断当前真相时不提升，创建治理问题或新 change。consolidate-from-code 模式下，未获代码或实际行为验证的结论一律 `skip`，只留在 change 内。
-
-### 4. 提升与冲突处理（共同）
-
-- 架构决策提升到 `<Path>{roots.state}/specdev/adr/</Path>`；
-- 领域术语提升到 `<Path>{roots.state}/specdev/context/</Path>`；
-- 经实现验证、长期有效的研究提升到 `<Path>{roots.state}/specdev/research/</Path>`；
-- 冲突 ADR 建立 supersedes 双向引用，不静默覆盖；
-- 历史结论保留状态和来源，不通过删除历史制造一致性。
-
-### 5. 移动归档并更新状态（共同）
-
-将 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 移动到 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
-
-更新 `<Path>{roots.state}/specdev/status.json</Path>`：从 active 移除，追加 completed/archived 记录，并把当前 `work_history` 记录标记完成；归档内 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>` 写入完成时间、归档路径和 promotion 摘要。
-
-任何删除、移动或 Git 副作用均需用户授权。
-
-### 6. 校验与汇报（共同）
-
-运行包级和归档链接检查，确认：
-
-- 归档路径存在；
-- 全局状态与归档状态一致；
-- 永久知识引用有效；
-- supersedes 链无断裂；
-- 无敏感信息进入永久知识。
-
-输出 promotion report：本次模式、每条候选知识、执行动作、目标路径、证据和未提升原因。
-
-## 禁止
-
-- 未完成或验证失败的 change 标 completed；
-- 把临时实现细节、一次性命令或未经验证假设提升为永久知识；
-- consolidate-from-code 模式下把用户未经代码验证的结论直接写成永久 ADR/context；
-- 静默覆盖冲突 ADR；
-- 删除历史以制造一致性；
-- 在归档或永久知识中写入秘密、令牌、敏感日志或个人隐私；
-- 未经用户授权移动、删除、提交或推送。
+Dry-run 不修改文件。归档移动、知识 merge/rewrite/delete、Git 动作均在计划展示后单独确认。归档目录完成后只读；后续纠正通过新 change 和 supersedes 链完成。
 
 ## 完成标准
 
-- 模式已明确判定；
-- archive 模式：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>` 全部适用项通过；
-- consolidate-from-code 模式：访谈决策树关键分支已覆盖，LOG/CONTEXT/ADR 与代码事实一致；
-- change 已移动到 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`；
-- 全局和归档状态一致；
-- 长期知识已按证据处理，未验证结论未被提升；
-- promotion report 已向用户汇报；
-- 无未批准副作用。
+- 模式与唯一 change 已确定；
+- 本地完成和 external reconcile 门通过；
+- 机械归档与知识规则只有全局 skill 一个事实源；
+- dry-run 与 confirmed 执行严格分离；
+- 源不存在、目标完整、active/archived 无重叠、归档状态正确；
+- 永久知识只包含当前、跨 change 有用且有实现证据的结论；
+- 无未批准移动、删除、改写或 Git 副作用。
 
 ## 子文件引用
 
-- 归档检查：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>`
-- 知识提升规则：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md</Path>`
-- 代码库沉淀访谈协议：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`
+- 全局归档 Skill：`<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`
+- Change 完成：`<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
+- 代码访谈：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`

package/template/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md

@@ -17,11 +17,9 @@
 
 1. 领域边界与限界上下文：系统由哪些领域构成，各自职责与边界；
 2. 规范术语与语义：代码中的类型/模块名对应什么业务概念，别名与禁用词；
-3. 核心不变量与约束：始终成立、可被验证、跨 change 有效的规则；
-4. 概念关系：聚合、生命周期、依赖、拥有关系与状态转换；
-5. 已固化的架构决策：现有代码体现了哪些长期决策、其驱动因素与替代方案；
-6. 实现映射与差距：领域概念到模块/接口/存储/事件的映射，以及已知偏离；
-7. 历史缘由：为什么当前这样，哪些是有意决策、哪些是历史负担。
+3. Context Map：多个 bounded context 之间需要明确的关系；
+4. 已固化的架构决策：现有代码体现了哪些难逆转、令人意外且来自真实权衡的决定；
+5. 历史缘由：为什么当前这样，哪些是有意决策、哪些只是可从代码即时发现的实现事实。
 
 ## 3. 每轮只关闭一个关键结论
 
@@ -48,7 +46,7 @@ change 内三份文档复用 grill 的既有格式，避免重复发明：
 
 ## 5. 停止条件
 
-- 目标主题的领域术语、不变量、关系与架构决策已覆盖，足以提升为永久知识；或
+- 目标主题的规范术语、Context Map 与符合准入条件的架构决策已覆盖，足以提升为永久知识；或
 - 用户明确延后，且该延后不伪装成已确认真相；或
 - 缺少必要外部信息或权限，change 标 blocked；或
 - 继续提问只会产生低影响或纯实现细节，交给对应实现阶段决定。

package/template/workflows/specdev/C-code-review/C-code-review.md

@@ -0,0 +1,42 @@
+---
+id: specdev/code-review
+type: workflow-entry
+workflow: specdev
+name: 代码审查
+description: 将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
+keywords: [code-review, review, diff, fixed-point, PR, 标准, 规范]
+---
+
+# 代码审查
+
+C 是独立 review 入口，不实施修复。它拥有 `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`；I 的最终审查由 I 写入 Evidence，不写本目录。
+
+## 输入
+
+- 用户提供的 commit、branch、tag、merge-base 或 PR locator；缺失时只询问固定点。
+- 可选 source、Spec、Ticket、ADR 和 Goal Plan。
+- 当前仓库代码、commit log 和编码标准。
+
+## 流程
+
+1. **解析固定点**：使用 `git rev-parse` 把固定点和 HEAD 固定为 SHA；PR 先通过 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 的 `pr-read` 获得 base/head SHA，并确保对应对象可在本地解析。
+2. **冻结输入**：记录 `git diff <fixed>...<head>` 和 `git log <fixed>..<head> --oneline`。引用无效或 diff 为空时失败，不创建报告。
+3. **发现来源**：调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`；规范来源缺失时经确认跳过规范轴，标准轴继续。
+4. **隔离审查**：平台支持时并行 reviewer，否则用两个独立完整输入包顺序执行。两轴不得读取对方 finding。
+5. **持久化**：选择下一个未占用 `CR-###`，使用模板写入 `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>`，原子重读。
+6. **验证与路由**：使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage review` 校验当前 change。无阻塞 finding 时返回完成或 I；局部修复生成/修订 Ticket；规范冲突返回 S/G；无法确定的 blocker 保持 C 可恢复状态。
+
+## 完成标准
+
+- fixed point/head 是本地不可变 SHA，三点 diff 非空；
+- 规范和标准来源发现顺序有记录；
+- 两轴隔离、固定顺序、未合并排名；
+- 每个 finding 有路径、风险、依据和满足条件；
+- 报告、状态、验证结果和下一 Work 路径一致；
+- C 未修改项目代码或远程状态。
+
+## 子文件引用
+
+- 公共审查 Skill：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
+- 报告模板：`<Path>{roots.workflows}/specdev/C-code-review/code-review-template.md</Path>`
+- 报告 Schema：`<Path>{roots.workflows}/specdev/common/schemas/code-review.schema.json</Path>`

package/template/workflows/specdev/C-code-review/code-review-template.md

@@ -0,0 +1,42 @@
+---
+schema_version: 1
+artifact: code-review
+change: <YYYY-MM-DD-topic>
+review_id: CR-001
+fixed_point: <sha>
+head: <sha>
+status: request-changes
+standards_result: request-changes
+specification_result: skipped
+spec_sources: []
+standards_sources: []
+created_at: <ISO-8601>
+---
+
+# Code Review CR-001
+
+## Fixed Input
+
+- **Diff:** `git diff <fixed_point>...<head>`
+- **Commits:** `git log <fixed_point>..<head> --oneline`
+- **Scope:**
+
+## 标准
+
+| Severity | Path / block | Finding | Authority | Satisfied when |
+|---|---|---|---|---|
+
+## 规范
+
+| Severity | Requirement | Finding | Source | Satisfied when |
+|---|---|---|---|---|
+
+规范不存在时写 `skipped:no-spec`，不伪造通过。
+
+## Summary
+
+- **Standards findings:**
+- **Specification findings:**
+- **Most severe standards finding:** none / ...
+- **Most severe specification finding:** none / ...
+- **Next Work:** completed / `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` / `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`