@namewta/speculo 1.0.19 → 1.0.21

package/template/workflows/specdev/T-triage/scripts/github-transport.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const exec = promisify(execFile);
+export const sha256 = value => createHash("sha256").update(value).digest("hex");
+const must = (value, message) => { if (!value) throw new Error(message); };
+const commentFields = value => ({ ...value, author: value.user ?? value.author, createdAt: value.created_at ?? value.createdAt, updatedAt: value.updated_at ?? value.updatedAt, url: value.html_url ?? value.url });
+function required(o, keys) { for (const k of keys) must(typeof o[k] === "string" && o[k].trim(), "missing --" + k.replaceAll("_", "-")); }
+function validateTarget(o) {
+  must(/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(o.repo ?? ""), "invalid repo");
+  if (o.number !== undefined) must(/^[1-9]\d*$/.test(String(o.number)), "invalid number");
+  if (o.marker !== undefined) must(/^[a-zA-Z0-9:_./-]+$/.test(o.marker), "invalid marker");
+}
+export function createTransport(run = async args => {
+  try { return (await exec("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })).stdout.trim(); }
+  catch { throw new Error("GitHub operation failed; remote outcome may be unknown. Re-read before retrying (raw credential-bearing stderr omitted)."); }
+}, readText = path => readFile(path, "utf8")) {
+  const json = async args => JSON.parse(await run(args));
+  const api = path => json(["api", path]);
+  const pages = async path => {
+    const value = await json(["api", path + (path.includes("?") ? "&" : "?") + "per_page=100", "--paginate", "--slurp"]);
+    must(Array.isArray(value) && value.every(Array.isArray), "incomplete or invalid pagination");
+    return value.flat();
+  };
+  async function readIssue(repo, number) {
+    const item = await api("repos/" + repo + "/issues/" + number);
+    must(!item.pull_request, "target is a pull request; use pr-read");
+    const comments = await pages("repos/" + repo + "/issues/" + number + "/comments");
+    must(comments.length === item.comments, "issue comments changed or pagination incomplete");
+    const after = await api("repos/" + repo + "/issues/" + number);
+    must(after.updated_at === item.updated_at && after.body === item.body && after.comments === item.comments && after.state === item.state, "issue drift during read");
+    return { ...item, author: item.user, state: item.state.toUpperCase(), url: item.html_url, comments: comments.map(commentFields),
+      createdAt: item.created_at, updatedAt: item.updated_at,
+      pagination_complete: true, fetched_at: new Date().toISOString() };
+  }
+  async function readPull(repo, number) {
+    const root = "repos/" + repo + "/pulls/" + number;
+    const before = await api(root);
+    const [comments, reviews, review_comments, files, diff] = await Promise.all([
+      pages("repos/" + repo + "/issues/" + number + "/comments"), pages(root + "/reviews"),
+      pages(root + "/comments"), pages(root + "/files"),
+      run(["api", root, "-H", "Accept: application/vnd.github.diff"]),
+    ]);
+    const after = await api(root);
+    must(before.base.sha === after.base.sha && before.head.sha === after.head.sha && before.updated_at === after.updated_at &&
+      before.body === after.body && before.comments === after.comments && before.review_comments === after.review_comments, "PR drift during read");
+    must(files.length === after.changed_files && comments.length === after.comments && review_comments.length === after.review_comments,
+      "PR pagination incomplete");
+    must(typeof diff === "string" && (after.changed_files === 0 || diff.includes("diff --git")), "missing PR diff");
+    return { number: after.number, title: after.title, body: after.body ?? "", state: after.merged_at ? "MERGED" : after.state.toUpperCase(),
+      url: after.html_url, author: after.user, labels: after.labels, createdAt: after.created_at, updatedAt: after.updated_at,
+      baseRefName: after.base.ref, headRefName: after.head.ref, baseRefOid: after.base.sha, headRefOid: after.head.sha,
+      isDraft: after.draft, comments: comments.map(commentFields), reviews: reviews.map(commentFields), review_comments: review_comments.map(commentFields),
+      files: files.map(file => ({ ...file, path: file.filename ?? file.path })), diff, pagination_complete: true,
+      body_sha256: sha256(after.body ?? ""), fetched_at: new Date().toISOString() };
+  }
+  function fixed(o, p) {
+    for (const k of ["base_sha", "head_sha"]) must(/^[a-f0-9]{40,64}$/.test(o[k] ?? ""), "invalid " + k);
+    must(p.baseRefOid === o.base_sha && p.headRefOid === o.head_sha, "PR SHA drift");
+    if (o.expected_body_sha256 !== undefined) must(p.body_sha256 === o.expected_body_sha256, "PR body drift");
+  }
+  async function candidate(o) {
+    const qualifiedHead = o.head.includes(":") ? o.head : o.repo.split("/")[0] + ":" + o.head;
+    const found = await pages("repos/" + o.repo + "/pulls?state=all&head=" + encodeURIComponent(qualifiedHead) + "&base=" + encodeURIComponent(o.base));
+    const matches = found.filter(p => String(p.body ?? "").includes("<!-- " + o.marker + " -->"));
+    must(matches.length < 2, "multiple PRs with marker");
+    if (matches.length) return readPull(o.repo, String(matches[0].number));
+    must(found.every(p => p.state !== "open"), "existing open PR for branches needs explicit update");
+    return null;
+  }
+  async function createPr(o, plan) {
+    required(o, ["base", "head", "base_sha", "head_sha", "title", "body_file", "marker"]);
+    const raw = await readText(o.body_file);
+    const marker = "<!-- " + o.marker + " -->";
+    const body = raw.includes(marker) ? raw : raw.trimEnd() + "\n\n" + marker;
+    const existing = await candidate(o);
+    if (existing) {
+      fixed(o, existing);
+      must(existing.body === body && existing.title === o.title, "existing PR content differs; use explicit update");
+      return { ...plan, status: "already-present", ...existing };
+    }
+    const base = await api("repos/" + o.repo + "/commits/" + encodeURIComponent(o.base));
+    const colon = o.head.indexOf(":");
+    if (colon >= 0) required(o, ["head_repo"]);
+    const headRepo = colon >= 0 ? o.head_repo : o.repo;
+    must(/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(headRepo), "invalid head-repo");
+    if (colon >= 0) must(headRepo.split("/")[0] === o.head.slice(0, colon), "head owner disagrees with head-repo");
+    const head = await api("repos/" + headRepo + "/commits/" + encodeURIComponent(colon >= 0 ? o.head.slice(colon + 1) : o.head));
+    fixed({ ...o, expected_body_sha256: undefined }, { baseRefOid: base.sha, headRefOid: head.sha });
+    if (!o.apply) return { ...plan, body_sha256: sha256(body), draft: true };
+    let failure;
+    try { await run(["pr", "create", "--repo", o.repo, "--base", o.base, "--head", o.head, "--title", o.title, "--body", body, "--draft"]); }
+    catch (e) { failure = e; }
+    const after = await candidate(o);
+    if (!after) throw failure ?? new Error("PR create result unknown; query marker before retry");
+    fixed(o, after);
+    must(after.body === body && after.title === o.title && after.isDraft, "PR creation readback mismatch");
+    return { ...plan, status: "created", ...after };
+  }
+  return async function transport(operation, options) {
+    const o = { labels: [], ...options }; validateTarget(o);
+    const plan = { operation, provider: "github", repo: o.repo, mode: o.apply ? "apply" : "dry-run" };
+    if (operation === "issue-read") { required(o, ["number"]); return { ...plan, kind: "issue", ...await readIssue(o.repo, o.number) }; }
+    if (operation === "pr-read") { required(o, ["number"]); return { ...plan, kind: "pull-request", ...await readPull(o.repo, o.number) }; }
+    if (operation === "issue-search") {
+      required(o, ["query"]);
+      const issues = await json(["issue", "list", "--repo", o.repo, "--search", o.query, "--state", o.state || "all", "--limit", o.limit || "20", "--json", "number,title,state,url,labels,updatedAt"]);
+      return { ...plan, issues, exhaustive: false };
+    }
+    if (operation === "issue-create") {
+      required(o, ["title", "body_file"]);
+      Object.assign(plan, { title: o.title, body_file: o.body_file, labels: o.labels });
+      if (!o.apply) return plan;
+      const body = await readText(o.body_file);
+      const args = ["issue", "create", "--repo", o.repo, "--title", o.title, "--body-file", o.body_file];
+      for (const label of o.labels) args.push("--label", label);
+      // Optional marker enables exact retry recovery for callers with durable ledgers.
+      const find = async () => {
+        if (!o.marker) return null;
+        must(body.includes("<!-- " + o.marker + " -->"), "body must include marker");
+        const list = await pages("repos/" + o.repo + "/issues?state=all");
+        const found = list.filter(i => !i.pull_request && String(i.body ?? "").includes("<!-- " + o.marker + " -->"));
+        must(found.length < 2, "multiple issues with marker");
+        return found.length ? readIssue(o.repo, String(found[0].number)) : null;
+      };
+      const previous = await find();
+      if (previous) { must(previous.body === body && previous.title === o.title, "existing issue content drift"); return { ...plan, status: "already-present", url: previous.url }; }
+      let url;
+      try { url = await run(args); } catch (error) { const recovered = await find(); if (!recovered) throw error; url = recovered.url; }
+      const number = /\/issues\/(\d+)$/.exec(url)?.[1]; must(number, "unknown issue create result");
+      const after = await readIssue(o.repo, number);
+      must(after.body === body && after.title === o.title, "issue readback mismatch");
+      return { ...plan, url: after.url, status: "created" };
+    }
+    if (operation === "issue-comment-close") {
+      required(o, ["number", "comment_file", "marker"]);
+      const comment = (await readText(o.comment_file)).trim(), marker = "<!-- " + o.marker + " -->";
+      const before = await readIssue(o.repo, o.number);
+      const exists = before.comments.some(c => String(c.body).includes(marker));
+      const result = { ...plan, number: Number(o.number), url: before.url, state_before: before.state, marker: o.marker,
+        comment_required: !exists, close_required: before.state !== "CLOSED", steps: [] };
+      if (!o.apply) return result;
+      if (!exists) { await run(["issue", "comment", o.number, "--repo", o.repo, "--body", comment + "\n\n" + marker]); result.steps.push("commented"); }
+      else result.steps.push("comment-already-present");
+      if (before.state !== "CLOSED") { await run(["issue", "close", o.number, "--repo", o.repo, "--reason", o.reason || "completed"]); result.steps.push("closed"); }
+      const after = await readIssue(o.repo, o.number);
+      must(after.state === "CLOSED" && after.comments.some(c => String(c.body).includes(marker)), "issue close readback mismatch");
+      return { ...result, state_after: after.state, status: "closed" };
+    }
+    if (operation === "pr-create") return createPr(o, plan);
+    if (["pr-update", "pr-ready"].includes(operation)) {
+      required(o, ["number", "base_sha", "head_sha", "expected_body_sha256"]);
+      must(/^[a-f0-9]{64}$/.test(o.expected_body_sha256), "invalid expected-body-sha256");
+      const before = await readPull(o.repo, o.number); fixed(o, before);
+      must(before.state === "OPEN", "PR is not open");
+      if (operation === "pr-ready") {
+        if (!o.apply) return { ...plan, number: before.number, ready_required: before.isDraft };
+        if (before.isDraft) await run(["pr", "ready", o.number, "--repo", o.repo]);
+        const after = await readPull(o.repo, o.number); fixed(o, after);
+        must(!after.isDraft, "PR remained draft");
+        return { ...plan, status: "ready", ...after };
+      }
+      required(o, ["title", "body_file", "marker"]);
+      const body = await readText(o.body_file), marker = "<!-- " + o.marker + " -->";
+      must(before.body.includes(marker) && body.includes(marker), "PR marker mismatch");
+      if (!o.apply) return { ...plan, number: before.number, body_sha256: sha256(body) };
+      await run(["pr", "edit", o.number, "--repo", o.repo, "--title", o.title, "--body", body]);
+      const after = await readPull(o.repo, o.number);
+      fixed({ ...o, expected_body_sha256: sha256(body) }, after);
+      must(after.title === o.title, "PR title readback mismatch");
+      return { ...plan, status: "updated", ...after };
+    }
+    throw new Error("unknown operation: " + operation);
+  };
+}
+export function parseArgs(argv) {
+  const [operation, ...rest] = argv, options = { labels: [] };
+  const allowed = new Set(["repo", "number", "query", "state", "limit", "title", "body_file", "comment_file", "marker", "reason", "base", "head", "head_repo", "base_sha", "head_sha", "expected_body_sha256", "label"]);
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--apply") { options.apply = true; continue; }
+    must(rest[i].startsWith("--"), "unexpected argument");
+    const k = rest[i].slice(2).replaceAll("-", "_"), value = rest[++i];
+    must(allowed.has(k) && value !== undefined && !value.startsWith("--"), "invalid option or missing value");
+    if (k === "label") options.labels.push(value); else { must(!(k in options), "duplicate option"); options[k] = value; }
+  }
+  return { operation, options };
+}
+export const usage = `github-transport.mjs <operation> --repo OWNER/REPO [options]
+issue-read | pr-read --number N
+issue-search --query TEXT [--state all] [--limit 20]
+issue-create --title TEXT --body-file PATH [--label LABEL] [--marker ID] [--apply]
+issue-comment-close --number N --comment-file PATH --marker ID [--reason completed] [--apply]
+pr-create --base BRANCH --head BRANCH|OWNER:BRANCH [--head-repo OWNER/REPO] --base-sha SHA --head-sha SHA --title TEXT --body-file PATH --marker ID [--apply]
+pr-update --number N --base-sha SHA --head-sha SHA --expected-body-sha256 HASH --title TEXT --body-file PATH --marker ID [--apply]
+pr-ready --number N --base-sha SHA --head-sha SHA --expected-body-sha256 HASH [--apply]
+Defaults to dry-run; caller owns authorization and state. --apply never implies push, merge or release.`;
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const { operation, options } = parseArgs(process.argv.slice(2));
+    if (!operation || ["--help", "-h", "help"].includes(operation)) console.log(usage);
+    else console.log(JSON.stringify(await createTransport()(operation, options), null, 2));
+  } catch (error) { console.error("ERROR: " + error.message); process.exitCode = 1; }
+}

package/template/workflows/specdev/T-triage/source-template.md

@@ -20,6 +20,9 @@ close_capability: not-applicable
 - **Labels or classification supplied by source:** none / ...
 - **Attachments:** none / URL references only
 - **Redactions:** none / description of omitted sensitive material
+- **Pagination / fetched at:** GitHub 来源填完整性、每类条数及读取时间；其他来源不适用
+- **Base / head SHA:** PR 填固定值，其他来源不适用
+- **Supersedes:** 新快照在 frontmatter 填 supersedes_source 指向前一不可变快照；初次来源不适用
 
 ## Original Content
 
@@ -28,3 +31,7 @@ close_capability: not-applicable
 ## Source Comments
 
 <按来源顺序保存评论；没有评论时写“无”。>
+
+## PR Evidence
+
+PR 来源保存 reviews、review comments、文件清单和完整 diff；分页缺失或 SHA 漂移阻塞分诊。非 PR 来源写不适用。

package/template/workflows/specdev/T-triage/triage-run-template.md

@@ -0,0 +1,34 @@
+---
+schema_version: 1
+artifact: triage-run
+id: TRI-001
+mode: release-preflight
+status: planned
+repo: owner/repo
+change: null
+commit_sha: null
+npm_target: unknown
+targets: []
+updated_at: <ISO-8601>
+---
+
+# 独立操作记录
+
+## Targets
+明确 repo、run/alert、workflow、SHA、tag；发布时逐包列 package、registry、version、dist-tag、required/not-required。
+同步填写 frontmatter targets 数组，每项为 {"kind":"npm|github-release|ci|security","identity":"准确包名/tag/run/alert","required":true,"version":null,"registry":null,"dist_tag":null,"observed":"pending|verified|failed|unknown","receipt":null}。npm required 项必须填 version、registry、dist_tag；回读后填写 receipt 证据引用。预检通过允许 pending；release completed 要求每个 required 项 verified 且有 receipt。
+
+## Plan
+操作步骤与完成标准。恢复沿用本记录，保留先前尝试。
+
+## Evidence
+源证据、命令/退出码、脱敏日志、预检与目标判定理由；无法读取为 unknown。
+
+## Authorization
+每个副作用的用户授权出处、目标和内容；尚无授权时只准备计划。
+
+## Receipts
+逐步回执与执行后读回；completed 必须列出每个所需目标的确认结果。
+
+## Recovery
+失败点、已完成动作、状态未知项、漂移与恢复条件。

package/template/workflows/specdev/T-triage/triage-template.md

@@ -1,8 +1,11 @@
 ---
-schema_version: 1
+schema_version: 2
 artifact: triage
 change: <YYYY-MM-DD-topic>
 mode: intake
+disposition: needs-triage
+verification: pending
+remote_actions: []
 source: <Path>{roots.state}/specdev/changes/{change}/source.md</Path>
 classification: investigation
 risk: medium

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -88,3 +88,10 @@ W 的 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只
 新 Ticket/普通 Map 保持原 schema_version，并使用 plan_contract_version: 1 扩展。Ticket 拥有经过核实的 Skill 调用绑定、语义资源和执行计划；Map 路由是其投影。规则为 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。计划、产物数量与完成证据漂移必须由对应 owner 修订；不能仅改 map 状态。
 
 父 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 是 goal-tickets-map 无状态入口，只引用现有 Implementation Map/Plan；它不能拥有第二份 status、owner 或任务清单。统一 P 拥有生命周期，旧 O 仅保留入口与恢复键。
+
+## 新增工件 owner
+
+- T：<Path>{roots.state}/specdev/changes/{change}/pull-requests/PR-###.md</Path> 拥有 PR 交付回执；<Path>{roots.state}/specdev/triage-runs/TRI-###.md</Path> 拥有独立远程操作，绝不复用 external_action/publish_action/capture。
+- R-retro：<Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path> 拥有活动复盘建议和来源；不成为永久知识。
+- P：<Path>{roots.state}/specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md</Path> 记录逻辑模型与浏览器证据；index.html 是可运行原型，ready 时 hash 与记录一致。
+- 来源更新：<Path>{roots.state}/specdev/changes/{change}/source.md</Path> 冻结后保持不变。T 将后续读取写入 <Path>{roots.state}/specdev/changes/{change}/sources/SRC-###.md</Path>，记录 replaces、固定 SHA/hash、完整性和原 locator，triage 正文选择有效快照；不得把新远程事实自动升级为已接受 Spec。

package/template/workflows/specdev/common/rules/change-completion.md

@@ -32,3 +32,9 @@ Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</P
 远程动作不参与本地完成判定。Triage `external_action` 为 `pending-close`/`close-failed` 时先 reconcile；`closed`、`waived` 或 `not-applicable` 才允许 Archive。Triage `publish_action` 为 `pending`/`publish-failed` 时先恢复或结束 publish；`not-requested`、`published` 或 `waived` 才允许 Archive。`not-requested` 是默认，未点过 publish 的 change 不被新模式绑架。归档后工件只读。
 
 **完成标准**：完成声明可由本地工件、Git 与验证重建；只有一个 owner 命中；失败 candidate 不污染父分支。
+
+## 非实现复盘终点与 PR 归档门
+
+仅有 R-retro（可先经 T intake）的 review-only change，以 completed 的 RETRO 报告作为等价验收；不能同时存在 Spec、Ticket、Map、Goal Plan、implementation 工件、Evidence 或 worktree。报告 sources 非空、结果诚实、全部验收完成，owner 按原完成转换规则更新状态；存在实现工件时仍走原实现完成门。insufficient-evidence 仅表示报告完整，不表示问题已解决。
+
+PR requested=true 且 status=planned/failed 时阻塞归档；delivery_target=ready 时 draft 也保持未闭合。draft 目标可由 draft/ready 满足，ready 目标只由 ready 满足；waived 须记录放弃交付的授权与原因。创建成功不等于已授权 merge。独立 TRI 不因关联 change 就参与完成/归档门。

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

@@ -24,3 +24,9 @@
 
 
 本地已清晰请求不强制绕行 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、完成后发布投影和记事项捕获职责不删除。
+
+## 复盘与交付路由
+
+开发环境/流程复盘 → <Path>{roots.workflows}/specdev/R-retro/R-retro.md</Path>。代码讲解仍为 L；Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path> 的对应模式；确定性修复回到 D/I，不由 T 接管代码。
+
+长任务在阶段边界按产物与待决问题选择继续、压缩上下文或 handoff；交接只携带准确 owner、SHA、输入和未闭合动作，不硬编码特定模型的上下文阈值，不自动启动其他会话。

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

@@ -57,7 +57,7 @@
 
 ## 状态字段
 
-`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 保留各自 schema v3；新 Ticket/Map 使用附加 plan_contract_version: 1，config 使用 schema v5，Goal Plan 使用 schema v6，Implementation Map/Plan 使用 schema v1，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
+`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 保留各自 schema v3；新 Ticket/Map 使用附加 plan_contract_version: 1，config 使用 schema v6，Goal Plan 使用 schema v6，Implementation Map/Plan 使用 schema v1，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
 
 - `schema_version`（数字）：全局状态 schema 版本，固定为 `5`。
 - `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。

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

@@ -1,58 +1,169 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:config:v5",
+  "$id": "urn:speculo:specdev:config:v6",
   "title": "SpecDev Configuration",
   "type": "object",
-  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
+  "required": [
+    "schema_version",
+    "interaction_language",
+    "artifact_language",
+    "git",
+    "execution",
+    "verification",
+    "planning",
+    "github"
+  ],
   "properties": {
-    "schema_version": {"const": 5},
-    "interaction_language": {"type": "string", "minLength": 1},
-    "artifact_language": {"type": "string", "minLength": 1},
+    "schema_version": {
+      "const": 6
+    },
+    "interaction_language": {
+      "type": "string",
+      "minLength": 1
+    },
+    "artifact_language": {
+      "type": "string",
+      "minLength": 1
+    },
     "git": {
       "type": "object",
-      "required": ["default_branch"],
+      "required": [
+        "default_branch"
+      ],
       "properties": {
-        "default_branch": {"type": ["string", "null"]}
+        "default_branch": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": false
     },
     "execution": {
       "type": "object",
-      "required": ["max_implementation_agents", "max_integration_attempts", "deep_ticket_human_approval", "shared_path_owner"],
+      "required": [
+        "max_implementation_agents",
+        "max_integration_attempts",
+        "deep_ticket_human_approval",
+        "shared_path_owner"
+      ],
       "properties": {
-        "max_implementation_agents": {"type": "integer", "minimum": 1},
-        "max_integration_attempts": {"type": "integer", "minimum": 1},
-        "deep_ticket_human_approval": {"type": "boolean"},
-        "shared_path_owner": {"type": "string", "minLength": 1}
+        "max_implementation_agents": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_integration_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "deep_ticket_human_approval": {
+          "type": "boolean"
+        },
+        "shared_path_owner": {
+          "type": "string",
+          "minLength": 1
+        }
       },
       "additionalProperties": false
     },
     "verification": {
       "type": "object",
-      "required": ["test", "typecheck", "lint", "build"],
+      "required": [
+        "test",
+        "typecheck",
+        "lint",
+        "build"
+      ],
       "properties": {
-        "test": {"type": ["string", "null"]},
-        "typecheck": {"type": ["string", "null"]},
-        "lint": {"type": ["string", "null"]},
-        "build": {"type": ["string", "null"]}
+        "test": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "typecheck": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "build": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": true
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_design_default_candidates", "ui_design_max_candidates"],
+      "required": [
+        "default_depth",
+        "require_ready_gate",
+        "require_evidence",
+        "ui_design_default_candidates",
+        "ui_design_max_candidates"
+      ],
       "properties": {
-        "default_depth": {"enum": ["lite", "standard", "deep"]},
-        "require_ready_gate": {"type": "boolean"},
-        "require_evidence": {"type": "boolean"},
-        "ui_design_default_candidates": {"type": "integer", "minimum": 2, "maximum": 4},
-        "ui_design_max_candidates": {"type": "integer", "minimum": 2, "maximum": 4}
+        "default_depth": {
+          "enum": [
+            "lite",
+            "standard",
+            "deep"
+          ]
+        },
+        "require_ready_gate": {
+          "type": "boolean"
+        },
+        "require_evidence": {
+          "type": "boolean"
+        },
+        "ui_design_default_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        },
+        "ui_design_max_candidates": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 4
+        }
       },
       "additionalProperties": true
+    },
+    "github": {
+      "type": "object",
+      "required": [
+        "include_external_prs",
+        "labels"
+      ],
+      "properties": {
+        "include_external_prs": {
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
-  "allOf": [{
-    "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
-  }],
+  "allOf": [
+    {
+      "$comment": "ui_design_default_candidates <= ui_design_max_candidates is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+    }
+  ],
   "additionalProperties": false
 }

package/template/workflows/specdev/common/schemas/logic-prototype.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:logic-prototype:v1",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "id",
+    "status",
+    "verification",
+    "html_sha256",
+    "updated_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "logic-prototype"
+    },
+    "change": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^LOGIC-[0-9]{3,}$"
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "blocked",
+        "ready"
+      ]
+    },
+    "verification": {
+      "enum": [
+        "pending",
+        "passed",
+        "failed",
+        "unknown"
+      ]
+    },
+    "html_sha256": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      ]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "additionalProperties": false
+}