@namewta/speculo 1.0.14 → 1.0.16

package/template/workflows/specdev/common/rules/workflow-routing.md

@@ -4,6 +4,7 @@
 | 场景 | 入口 | 正常出口 |
 |---|---|---|
 | 需要冻结外部来源或审计摄入 | T-triage intake | D / G / W / P / S / C / T |
+| 尚未成 Change，只要先在 GitHub 留一条仍 open 的记事项 | T-triage capture | 停止 / 以后 intake / W |
 | 本地 change 完成且来源可关闭 | T-triage reconcile | A |
 | 本地 change 完成且要把 Ticket 记到 GitHub | T-triage publish | reconcile / A / 停止 |
 | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
@@ -13,7 +14,7 @@
 | 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
 | 外部行为已清楚 | S-spec | T-tickets |
 | Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
-| 单个或多个 Ready change 的 Goal 规划、持续实现与恢复 | P-goal-plan | I / verify / completed / blocked |
+| 单个已拆票 change 或多个 Ready change 的 Goal 规划、持续实现与恢复 | P-goal-plan | I / verify / completed / blocked |
 | 旧 O 调用或恢复键 | P-goal-plan | 统一 P 多 change 模式 |
 | Ready 执行 | I-implement | Triage / A / blocked / deviation |
 | 开发完成后需要理解当前 change 或追问实现 | L-learn-change | 返回用户 / 继续提问 / Triage / A |
@@ -22,4 +23,4 @@
 同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
 
 
-本地已清晰请求不强制绕行 Triage。完成后要记账才选 publish；publish 与 reconcile 写不同远程对象，可先后执行。G 是单 change Grill，P-prototype 是 UI 设计，不与统一 P-goal-plan 混淆。W 发现候选后逐个交 G/S/T；只有清晰且 Ready 的 child 才交 P。原缺陷诊断 D、风险分诊、远程 reconcile 和完成后发布投影职责不删除。
+本地已清晰请求不强制绕行 Triage。完成后要记账才选 publish；尚未成 Change、只想先留 inbox 记录才选 capture。publish、reconcile 与 capture 写不同远程对象，可先后执行。G 是单 change Grill，P-prototype 是 UI 设计，不与统一 P-goal-plan 混淆。W 发现候选后逐个交 G/S/T；单 change 拆票后可交 P 规划，多个 child 创建父 Goal 前仍须全部 Ready。原缺陷诊断 D、风险分诊、远程 reconcile、完成后发布投影和记事项捕获职责不删除。

package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md

@@ -9,6 +9,7 @@
 - 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
 - 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
 - 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
+- 捕获账本（可选，缺失合法）：`<Path>{roots.state}/specdev/capture.md</Path>`
 
 刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据：配置使用 baseline 三方合并，登记的状态 schema 使用显式 migrator，其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup；冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
 

package/template/workflows/specdev/common/schemas/capture.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:capture:v1",
+  "title": "SpecDev Capture Index Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "mode", "repo", "updated_at"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "artifact": {"const": "capture-index"},
+    "mode": {"const": "capture"},
+    "repo": {"type": "string", "pattern": "^.+/.+$"},
+    "updated_at": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": true
+}

package/template/workflows/specdev/common/tools/README.md

@@ -9,7 +9,18 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 
-`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。`goal-plan` 还会读取父 change 的 sibling 成员，要求每个成员已有 Ready Spec/Tickets，校验组合 Ticket DAG、唯一父归属、serialization、跨 Ticket 写路径、全局 workspace/实现配额和完成门。省略 stage 时验证当前存在的工件，不会因未来 Work 尚未运行而报错。`--repo` 可选；提供后会把状态中的 SHA、祖先关系、当前分支和完成时 clean 状态与真实 Git 仓库交叉验证。
+`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。单 change 的 `goal-plan` 要求自己的 Goal Plan，允许合法的 `draft / ready_for_execution: false`；Tickets 阶段可尚无 Goal。Goal 的就绪字段必须是布尔值并与状态对应。
+
+存在 Implementation Map、Implementation Plan 或 goal-tickets-map 入口中的任一项即走父编排校验；缺少另一父工件会报错，不回退单 change，也不额外要求单 change Goal。父编排读取 sibling 成员，创建时要求每个成员已有 Ready Spec/Tickets，继续校验组合 Ticket DAG、唯一父归属、serialization、跨 Ticket 写路径、全局 workspace/实现配额和完成门。已有父 Map/Plan 尚未补建无状态入口时仍可验证。
+
+省略 stage 时验证当前存在的工件，不会因未来 Work 尚未运行而报错。`--repo` 可选；提供后会把状态中的 SHA、祖先关系、当前分支和完成时 clean 状态与真实 Git 仓库交叉验证。
+
+校验 workspace 捕获账本（文件必须已存在；缺失时不要为了校验去创建）：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --capture <Path>{roots.state}/specdev/capture.md</Path>
+```
 
 ## 校验 SpecDev 工作流包
 
@@ -27,6 +38,8 @@ node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --ma
 
 接受普通 tickets-map、父 goal-tickets-map 入口或旧 Implementation Map。可选 --previous 读取上轮 JSON 输出作漂移检查；该输出应保存到调用方已有 Evidence，不建立第二套权威状态。输出 frontier、blocked、deferred、in_flight、invalidated 与逐票契约摘要。
 
+单 change 的 Goal Ready 不要求所有未来票同时 Ready。合法 draft 票保留缺口与重审条件，只阻塞自身及依赖闭包；`ready/in_progress/review` 却没有 `ready=true` 是逐票错误。frontier 只包含自身 Ready、依赖成功完成、owner/资源/并发条件满足的票；上游 done 不自动修改消费者状态。全局执行门未满足时无可派单票，空 frontier 的 blocked/deferred 说明恢复条件。多 change 父创建的全员 Ready 输入门保持不变。
+
 只读工具不调用 Skill、不执行实现、不检查真实授权/正式记忆网关，不获取锁或自动解锁；Lead 必须在 dispatch 前完成这些检查。结构错误返回非零；局部错误仍可能带独立 frontier，调用方必须检查节点和全局 diagnostics。结构检查成功的退出码 0 不代表任务完成，且业务门禁可能仍阻塞全部票。eligible_for_final_verification 只表示可进入最终验收，不是 Goal completed。
 
 `<Path>{roots.workflows}/specdev/common/tools/plan-contract.mjs</Path>` 是两个工具共用的只读校验库：新 Ticket 的真实 Skill 名称/摘要、必需调用证据、Map 数量合同、父入口与 W 候选图。普通 --repo 仍支持原 Git 事实验证；存在未完成票的真实项目 Skill 绑定时必须提供项目根。旧票可读，开始新实现前必须显式补齐 Plan 合同；已完成历史证据不要求当前 Skill 包仍与历史版本相同。

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

@@ -103,6 +103,20 @@ const FORBIDDEN_PUBLISH_LABELS = new Set([
   "stale",
 ]);
 const COUNTED_PUBLISH_STATES = new Set(["closed", "created", "commented"]);
+const VALID_CAPTURE_ROW_STATE = new Set([
+  "planned",
+  "open",
+  "skipped:duplicate",
+  "intaken",
+  "waived",
+  "failed",
+]);
+const FORBIDDEN_CAPTURE_LABELS = new Set([
+  ...FORBIDDEN_PUBLISH_LABELS,
+  "specdev:published",
+  "specdev:change",
+]);
+const COUNTED_CAPTURE_REMOTE_STATES = new Set(["open", "intaken"]);
 const VALID_DEPTH = new Set(["lite", "standard", "deep"]);
 const VALID_RISK = new Set(["low", "medium", "high", "critical"]);
 const VALID_PLAN_MODES = new Set([
@@ -213,6 +227,7 @@ const STATE_ARTIFACT_BASENAMES = new Set([
   ".status.json",
   "triage.md",
   "publish.md",
+  "capture.md",
   "diagnosis.md",
   "source.md",
   "architecture-review.md",
@@ -1011,7 +1026,7 @@ function capabilityChecks(root) {
       "triage",
       [
         join(root, "T-triage", "T-triage.md"),
-        ["source.md", "intake", "reconcile", "publish", "publish.md", "specdev:published", "唯一权威", "远程写入为零"],
+        ["source.md", "intake", "reconcile", "publish", "publish.md", "specdev:published", "capture", "capture.md", "specdev:captured", "唯一权威", "远程写入为零"],
       ],
     ],
     [
@@ -1140,6 +1155,11 @@ function capabilityChecks(root) {
     "common/rules/parent-implementation-orchestration.md",
     "common/schemas/implementation-map.schema.json",
     "common/schemas/implementation-plan.schema.json",
+    "common/schemas/capture.schema.json",
+    "T-triage/capture-protocol.md",
+    "T-triage/capture-template.md",
+    "T-triage/issue-record-template.md",
+    "T-triage/tools/capture-status.mjs",
   ]) {
     if (!isFile(join(root, required))) errors.push(`missing architecture/wayfinding contract ${required}`);
   }
@@ -1500,6 +1520,99 @@ function validatePublish(path, expectedChange, triage, errors) {
   return { path, meta, body, rows };
 }
 
+function parseCaptureLedger(body) {
+  const rows = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\|/.test(line) || /^\|\s*-+/.test(line) || /^\|\s*id\s*\|/i.test(line)) continue;
+    const cells = line.split("|").map((cell) => cell.trim());
+    const inner = cells.slice(1, cells.length - 1);
+    if (inner.length < 9) continue;
+    rows.push({
+      id: inner[0],
+      kind: inner[1],
+      title: inner[2],
+      labels: inner[3],
+      number: inner[4],
+      url: inner[5],
+      marker: inner[6],
+      sha256: inner[7],
+      state: inner[8],
+    });
+  }
+  return rows;
+}
+
+function validateCapture(path, errors) {
+  if (!isFile(path)) {
+    errors.push("missing capture.md ledger");
+    return null;
+  }
+  const { meta, body } = parseFrontmatter(path);
+  const required = [
+    "schema_version",
+    "artifact",
+    "mode",
+    "repo",
+    "updated_at",
+  ];
+  const missing = required.filter((key) => !(key in meta));
+  if (missing.length) errors.push(`capture.md: missing keys ${JSON.stringify(missing)}`);
+  if (meta.schema_version !== 1 || meta.artifact !== "capture-index") {
+    errors.push("capture.md: artifact/schema_version must be capture-index/1");
+  }
+  if (meta.mode !== "capture") errors.push(`capture.md: invalid mode ${meta.mode}`);
+  if (typeof meta.repo !== "string" || !/.+\/.+/.test(meta.repo)) {
+    errors.push("capture.md: repo must be owner/repo");
+  }
+  for (const heading of ["## 捕获计划", "## 账本", "## 计数", "## 重试"]) {
+    if (!body.includes(heading)) errors.push(`capture.md: missing '${heading}'`);
+  }
+  const rows = parseCaptureLedger(body);
+  for (const row of rows) {
+    if (!CHANGE_NAME.test(row.id)) {
+      errors.push(`capture.md: invalid id ${row.id}`);
+    }
+    if (!VALID_CAPTURE_ROW_STATE.has(row.state)) {
+      errors.push(`capture.md: ${row.id}: invalid state ${row.state}`);
+    }
+    const labels = row.labels.split(",").map((item) => item.trim()).filter(Boolean);
+    for (const label of labels) {
+      if (FORBIDDEN_CAPTURE_LABELS.has(label)) {
+        errors.push(`capture.md: ${row.id}: forbidden label ${label}`);
+      }
+    }
+    const skipped = row.state.startsWith("skipped:") || row.state === "waived" || row.state === "planned" || row.state === "failed";
+    if (!skipped && !VALID_TICKET_KIND.has(row.kind)) {
+      errors.push(`capture.md: ${row.id}: invalid kind ${row.kind}`);
+    }
+    if (COUNTED_CAPTURE_REMOTE_STATES.has(row.state)) {
+      if (!VALID_TICKET_KIND.has(row.kind)) {
+        errors.push(`capture.md: ${row.id}: invalid kind ${row.kind}`);
+      }
+      if (!/^\d+$/.test(row.number)) {
+        errors.push(`capture.md: ${row.id}: ${row.state} row requires issue number`);
+      }
+      if (!String(row.url).startsWith("https://github.com/")) {
+        errors.push(`capture.md: ${row.id}: ${row.state} row requires GitHub url`);
+      }
+      const expectedMarker = `specdev:capture:${row.id}`;
+      if (row.marker !== expectedMarker) {
+        errors.push(`capture.md: ${row.id}: marker must be ${expectedMarker}`);
+      }
+      if (!labels.includes("specdev:captured")) {
+        errors.push(`capture.md: ${row.id}: missing specdev:captured`);
+      }
+      if (!labels.includes("origin:local")) {
+        errors.push(`capture.md: ${row.id}: missing origin:local`);
+      }
+      if (labels.includes("origin:intake")) {
+        errors.push(`capture.md: ${row.id}: capture origin must be local`);
+      }
+    }
+  }
+  return { path, meta, body, rows };
+}
+
 function validateDiagnosis(path, expectedChange, errors) {
   if (!isFile(path)) {
     errors.push("missing diagnosis artifact");
@@ -1910,7 +2023,10 @@ function validateMap(path, errors, repoRoot = null) {
 }
 
 function validateGoalPlan(path, errors) {
-  if (!isFile(path)) return null;
+  if (!isFile(path)) {
+    errors.push(`missing Goal Plan: ${basename(path)}`);
+    return null;
+  }
   const { meta, body } = parseFrontmatter(path);
   const required = [
     "schema_version",
@@ -1971,6 +2087,7 @@ function validateGoalPlan(path, errors) {
   const validReadyStates = new Set(["ready", "in_progress"]);
   const validNotReadyStates = new Set(["draft", "blocked", "completed"]);
   if (
+    typeof meta.ready_for_execution !== "boolean" ||
     (meta.ready_for_execution === true && !validReadyStates.has(meta.status)) ||
     (meta.ready_for_execution === false && !validNotReadyStates.has(meta.status))
   ) {
@@ -2201,6 +2318,10 @@ function validateTicket(path, errors) {
   const ticketId = String(meta.id);
   if (!/^T-\d{2,}$/.test(ticketId)) errors.push(`${basename(path)}: invalid Ticket id ${ticketId}`);
   if (!VALID_TICKET_STATUS.has(meta.status)) errors.push(`${basename(path)}: invalid status ${meta.status}`);
+  if (typeof meta.ready !== "boolean") errors.push(`${basename(path)}: ready must be a boolean`);
+  if (new Set(["ready", "in_progress", "review"]).has(meta.status) && meta.ready !== true) {
+    errors.push(`${basename(path)}: executable Ticket must keep ready=true`);
+  }
   if (meta.kind != null && meta.kind !== "" && !VALID_TICKET_KIND.has(meta.kind)) {
     errors.push(`${basename(path)}: invalid kind ${meta.kind}`);
   }
@@ -2697,12 +2818,10 @@ function validateGitEvidence(repoRoot, changeStatus, errors) {
 }
 
 function validateParentImplementation(change, parentStatus, stage, errors, warnings, repoRoot = null) {
-  const required = stage === "goal-plan";
   const mapPath = join(change, "implementation-map.md");
   const planPath = join(change, "implementation-plan.md");
-  if (!required && !isFile(mapPath) && !isFile(planPath)) return null;
-  if (!isFile(mapPath)) errors.push("goal-plan stage requires implementation-map.md");
-  if (!isFile(planPath)) errors.push("goal-plan stage requires implementation-plan.md");
+  if (!isFile(mapPath)) errors.push("parent implementation requires implementation-map.md");
+  if (!isFile(planPath)) errors.push("parent implementation requires implementation-plan.md");
   if (!isFile(mapPath) || !isFile(planPath)) return null;
 
   const parentName = basename(change);
@@ -3080,7 +3199,7 @@ function validateParentImplementation(change, parentStatus, stage, errors, warni
     if (count > 1) errors.push(`repository/ref integration must be serialized for ${ref}; found ${count}`);
   }
 
-  if (required && parentStatus && new Set(["active", "blocked"]).has(parentStatus.change_status) && !new Set(["specdev/goal-plan"]).has(parentStatus.current_work)) {
+  if (stage === "goal-plan" && parentStatus && new Set(["active", "blocked"]).has(parentStatus.change_status) && !new Set(["specdev/goal-plan"]).has(parentStatus.current_work)) {
     errors.push("parent active/blocked status must keep current_work=specdev/goal-plan");
   }
   if (parentStatus?.change_status === "completed") {
@@ -3151,12 +3270,20 @@ function validateChange(change, stage = null, repoRoot = null) {
   const workspace = resolveWorkspaceContract(repoRoot, change);
   errors.push(...workspace.errors);
 
+  // A partial parent must never fall back to the single-change artifact contract.
+  const mapPath = join(change, "tickets-map.md");
+  const isParentImplementation = isFile(join(change, "implementation-map.md")) ||
+    isFile(join(change, "implementation-plan.md")) ||
+    (isFile(mapPath) && parseFrontmatter(mapPath).meta.artifact === "goal-tickets-map");
   const changeStatus = validateChangeStatus(join(change, ".status.json"), basename(change), errors);
-  validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot);
+  if (isParentImplementation) validateParentImplementation(change, changeStatus, stage, errors, warnings, repoRoot);
   errors.push(...validateInitiative(change));
   if (isFile(join(change, "source-issue.md"))) {
     errors.push("obsolete source-issue.md is forbidden; use source.md without compatibility fallback");
   }
+  if (isFile(join(change, "capture.md"))) {
+    errors.push("capture.md is workspace-owned at specdev/capture.md; change-level copies are forbidden");
+  }
   const sourceRequired = stage === "triage";
   const sourcePath = join(change, "source.md");
   const source = isFile(sourcePath) || sourceRequired
@@ -3181,7 +3308,6 @@ function validateChange(change, stage = null, repoRoot = null) {
   validatePrototypes(change, stage === "prototype", errors);
   validateChangeLearning(change, stage === "learn-change", errors);
 
-  const isParentImplementation = isFile(join(change, "implementation-map.md"));
   const specRequired = new Set(["spec", "tickets", "goal-plan", "implement", "complete"]).has(stage) && !isParentImplementation;
   const specPath = join(change, "spec.md");
   const spec = isFile(specPath) || specRequired
@@ -3189,10 +3315,9 @@ function validateChange(change, stage = null, repoRoot = null) {
     : null;
   const ticketMode = isDirectory(join(change, "ticket"));
   const mapRequired = !isParentImplementation && (new Set(["tickets", "goal-plan"]).has(stage) || (stage === "implement" && ticketMode));
-  const mapPath = join(change, "tickets-map.md");
   const ticketsMap = isFile(mapPath) || mapRequired ? validateMap(mapPath, errors, repoRoot) : null;
   const goalPlanPath = join(change, "goal-plan.md");
-  const goalPlan = isFile(goalPlanPath) || stage === "goal-plan"
+  const goalPlan = isFile(goalPlanPath) || (stage === "goal-plan" && !isParentImplementation)
     ? validateGoalPlan(goalPlanPath, errors)
     : null;
   validateDesignTree(join(change, "design-tree.json"), change, errors);
@@ -3411,14 +3536,6 @@ function validateChange(change, stage = null, repoRoot = null) {
   }
 
   if (goalPlan?.meta.ready_for_execution === true) {
-    const notReady = [...tickets]
-      .filter(
-        ([, artifact]) =>
-          !new Set(["done", "cancelled"]).has(artifact.meta.status) &&
-          artifact.meta.ready !== true,
-      )
-      .map(([ticketId]) => ticketId);
-    if (notReady.length) errors.push(`Goal Plan is Ready but Tickets are not Ready: ${JSON.stringify(notReady)}`);
     if (spec && spec.meta.ready_for_tickets !== true) {
       errors.push("Goal Plan is Ready but Spec is not ready_for_tickets");
     }
@@ -3495,7 +3612,7 @@ function printResults(errors, warnings) {
 }
 
 function usage() {
-  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--repo <project-root>] <change-directory> | --self-check");
+  console.error("Usage: node validate-specdev.mjs [--stage <stage>] [--repo <project-root>] <change-directory> | --self-check | --capture <capture.md>");
   return 2;
 }
 
@@ -3503,6 +3620,7 @@ function main(argv) {
   let selfCheckRequested = false;
   let stage = null;
   let repoRoot = null;
+  let capturePath = null;
   const positional = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -3518,6 +3636,11 @@ function main(argv) {
       index += 1;
     } else if (arg.startsWith("--repo=")) {
       repoRoot = arg.slice("--repo=".length);
+    } else if (arg === "--capture") {
+      capturePath = argv[index + 1] ?? null;
+      index += 1;
+    } else if (arg.startsWith("--capture=")) {
+      capturePath = arg.slice("--capture=".length);
     } else if (arg.startsWith("--")) {
       return usage();
     } else {
@@ -3526,12 +3649,18 @@ function main(argv) {
   }
   if (stage !== null && !VALID_STAGES.has(stage)) return usage();
   if (selfCheckRequested) {
-    if (positional.length || stage !== null) return usage();
+    if (positional.length || stage !== null || capturePath) return usage();
     const scriptDirectory = dirname(fileURLToPath(import.meta.url));
     const root = resolve(scriptDirectory, "..", "..");
     const result = selfCheck(root);
     return printResults(result.errors, result.warnings);
   }
+  if (capturePath) {
+    if (positional.length || stage !== null || repoRoot) return usage();
+    const errors = [];
+    validateCapture(resolve(capturePath), errors);
+    return printResults(errors, []);
+  }
   if (positional.length === 1) {
     const result = validateChange(resolve(positional[0]), stage, repoRoot);
     return printResults(result.errors, result.warnings);
@@ -3539,7 +3668,7 @@ function main(argv) {
   return usage();
 }
 
-export { parseFrontmatter, validateChange, validateTicket, validateMap, pathsOverlap, findCycle };
+export { parseFrontmatter, validateChange, validateTicket, validateMap, pathsOverlap, findCycle, validateCapture };
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try { process.exitCode = main(process.argv.slice(2)); }