@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-t-triage/references/release-preflight.md

@@ -0,0 +1,17 @@
+# 发布预检
+
+读取 <Path>{roots.workflows}/specdev/specdev-t-triage/assets/triage-run-template.md</Path>，创建或恢复 T 拥有的独立操作记录。预检只读远程与项目事实，不自动修复环境。记录：
+
+1. repo、发布分支/渠道、工作区状态、明确的目标 commit SHA、版本、tag；以项目声明为准，无法确定时停止。
+2. package.json、workspace/lockfile、engines 完整版本范围、packageManager、包集合、registry、access、dist-tag；不能把所有版本限制解释为大于等于。
+3. 实际 workflow 路径、trigger、复用 workflow 和调用脚本。npm_target 必须为 required/not-required/unknown；grep 仅作定位，包装脚本或表达式不明时为 unknown 并阻塞 release。
+4. 每个包的目标版本与 registry 是否已有版本，tag 是否存在且指向预期 SHA。冲突先恢复/更换版本，不建议删除远程 tag。
+5. gh 身份和所需的具体权限，发布认证按 <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-authentication.md</Path>；不要求无关管理员权限，不保存凭据。
+6. 项目声明的 test/typecheck/lint/build/bin/pack 等闸门与证据、CHANGELOG 版本内容、预期 Release 正文。缺失基础设施交 I；按需参考 <Path>{roots.workflows}/specdev/specdev-t-triage/references/workflow-yaml-reference.md</Path>，不在预检中安装。
+7. 需要文档同步时，由 <Path>{roots.commands}/docs-sync/COMMAND.md</Path> 处理其 state、bootstrap 和范围；T 不改 sidecar。
+
+完成条件：记录中的 targets 数组及 Targets 正文列出每个包、registry、版本、dist-tag 与发布判定，Evidence 引用固定 SHA 的检查；unknown/冲突保留 blocked。预检通过并不授权 commit/push/tag/发布。
+
+## 兼容与用户迁移
+
+核对实际已发布基线、待发布构件与适用升级说明。说明受影响者、旧新行为、迁移步骤和确认结果；回退须有真实保证。预发布数据也有兼容义务，不能当作可随意丢弃的开发数据。

package/template/workflows/specdev/specdev-t-triage/references/release-protocol.md

@@ -0,0 +1,16 @@
+# npm / GitHub Release 发布
+
+先执行 <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-preflight.md</Path>；读取已有 TRI 记录，模式变为 release 并保留预检证据。每阶段原子写入回执并重读。T 不写 docs-sync state，不更改 change 的完成事实。
+
+1. 明确发布范围，展示普通提交、docs-sync、版本修改、release commit、分支/tag push、workflow 和发布目标的准确计划。只执行已获授权动作，沿用仍有效授权。
+2. 如有待提交改动，按项目规则显式选路径，不用 stash 隐藏内容。质量闸通过后才能提交。调用 docs-sync 时遵守其范围和提交协议。
+3. 保留 Unreleased，按项目格式迁移本版本 CHANGELOG；同步 package/workspace/lockfile 的必要版本。将版本与发布说明固定于同一 release commit，直接记录 SHA，不从模糊 commit message 推断。
+4. 按批准的仓库策略推送分支并创建/推送精确指向该 SHA 的 tag。不自动 merge、不移动已有 tag。触发的 workflow 必须按准确 SHA、event、workflow 路径和 run ID 定位，不能只看最新一条 run。
+5. 监控该 run；失败进入 <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-recovery.md</Path>。成功后校验 workflow 与 SHA、GitHub Release tag/正文/发布状态，以及每个 required npm 包的明确 package@version 和目标 dist-tag。prerelease/非 latest 按原计划验证。
+6. Release 正文来自已确认版本说明，按需读取 <Path>{roots.workflows}/specdev/specdev-t-triage/references/release-notes-injection.md</Path>。需要补记 docs-sync 输入节点时再次调用 docs-sync，由它维护游标；tag 保持不变。
+
+记录最终 SHA/tag/run ID、每个目标读回结果、docs-sync 结果或不适用原因。任一 required 目标未知或失败不得标 completed，保留已发布事实和后续恢复条件。全部通过才将 TRI 标 completed，运行 --triage-run 校验并返回报告。
+
+## 逐目标成功与未知结果
+
+npm、GitHub Release、tag 和其他获批目标各有回执，部分成功只恢复未完成部分。超时先核实原目标，不重复执行已确认效果；缺必需验证仍阻塞，不改本地开发完成状态。

package/template/workflows/specdev/specdev-t-triage/references/release-recovery.md

@@ -0,0 +1,22 @@
+# 恢复原操作
+
+输入必须是已有 TRI/PR/capture/publish/来源回写记录的准确路径与原目标。恢复原记录，不另建成功记录替代失败；检查 owner、锁、漂移和仍有效的授权。普通远程动作按 <Path>{roots.workflows}/specdev/specdev-t-triage/references/remote-operations.md</Path> 恢复。
+
+发布先重新读取准确 tag/SHA、workflow run、Release、registry 中的 package@version、dist-tag。npm 状态为未知时先解决读取/权限问题，不以未查到日志证明未上传。
+
+| 实际状态 | 恢复 |
+|---|---|
+| 尚未发布，原 SHA 未变，失败原因为暂态且已排除 | 展示并执行已授权的指定 run/job 重跑；重跑后完整验证 |
+| 尚未发布，但需要代码/配置变更 | 交 I 修复，形成新的 commit/发布计划；不默认覆盖远程 tag |
+| npm 已发布，GitHub Release/正文失败 | 只补缺失的 GitHub 动作，不重新发布 npm；记录读回 |
+| npm 已发布，包内容错误 | 新版本修复，保留旧版本与 tag 的事实；不尝试 unpublish 后覆盖 |
+| Release 已有人工修改或 SHA 漂移 | 停止受影响更新，比较差异并重新确定计划 |
+| 多包部分成功 | 逐包记账，仅继续确认未发布且仍匹配原计划的目标 |
+
+相同根因重试必须记录新证据或与上次的差异；没有差异先停止。不得要求提供 Token 片段作为证明。
+
+错误定位：认证失败核对权限/有效期/OIDC 配置；provenance 核对 runner、repository 和 id-token；E422 核对 tag/Release 已存在与正文；EUSAGE 核对实际 CLI 版本和参数。不要通过默认删 tag、force-push 或删除远程对象处理这些错误。恢复后的 completed 仍需原发布协议的所有目标校验。
+
+## 证据失效与原 owner
+
+恢复原 TRI 和逐目标回执，核对 tag/版本/构件 digest/授权和外部状态。目标或正文漂移先重新确认范围；不凭旧记录重发，不清除他人锁，不把未知结果标失败后无条件重试。

package/template/workflows/specdev/specdev-t-triage/references/remote-operations.md

@@ -0,0 +1,25 @@
+# GitHub 远程操作合同
+
+本协议及 <Path>{roots.workflows}/specdev/specdev-t-triage/scripts/github-transport.mjs</Path> 由 T 唯一维护。C、command 或其他调用方可直接复用：不激活 T、不创建 change、不创建工作调用镜像；原调用方拥有报告、授权与回执。
+
+## 输入与操作
+
+显式传入 repo、目标编号或分支、正文文件和操作。读取失败、分页不完整、对象类型不符、SHA/正文漂移时停止受影响操作。
+
+- issue-read / pr-read：完整可见内容；PR 包含评论、reviews、review comments、文件与 diff、不可变 base/head SHA、读取时间和完整性证据。
+- issue-search：候选检索；limit 是检索范围，不代表已穷尽仓库。
+- issue-create：title、body-file、labels，可选 marker；调用方先去重。
+- issue-comment-close：comment-file、marker、reason；按 marker 幂等评论，执行后确认关闭。
+- pr-create：base、head（同仓分支或 owner:branch）、base-sha、head-sha、title、body-file、marker；默认创建 draft。
+- pr-update：number、base-sha、head-sha、expected-body-sha256、title、body-file、marker。
+- pr-ready：number、base-sha、head-sha、expected-body-sha256；另需本次可审查授权。
+
+运行脚本 --help 查看完整参数。所有参数使用 argv，不拼 shell。操作返回 JSON，失败退出非零；脚本不写任何 workflow 或 command 状态。
+
+## 写入与恢复
+
+默认 dry-run，外部写入为零。调用方在写前展示准确目标、内容与动作并取得明确授权后才传 --apply。已授权同一动作不重复索取授权；目标/内容发生实质变化则重新确认范围。PR、push、merge、release 各自独立。
+
+对外正文标明 AI 协助。持久工件不保存凭据、Cookie、认证输出、机器绝对路径或未脱敏日志。临时正文文件由调用方管理。
+
+执行前重读目标和预期 SHA/正文摘要；执行后重读验证。超时不表示未写入，先查询稳定 marker/目标再恢复，不能盲目重建。重复 marker、多候选、并发漂移或读回不符时返回失败，由调用方保存已完成步骤和恢复条件。本地开发事实不因远程失败回滚。

package/template/workflows/specdev/specdev-t-triage/scripts/capture-status.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Aggregate inbox counts from the workspace-owned capture.md ledger.
+ * Local file is authoritative; this tool does not query GitHub.
+ * Missing capture.md is legal and counts as an empty inbox.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { safeWorkPathSync } from "../../../../lib/speculo-runtime.mjs";
+
+const OPEN = "open";
+const INTAKEN = "intaken";
+const WAIVED = "waived";
+const SKIPPED = new Set(["skipped:duplicate"]);
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return meta;
+}
+
+function parseLedgerStates(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((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 9) continue;
+    rows.push({
+      id: cells[0],
+      kind: cells[1],
+      state: cells[8],
+    });
+  }
+  return rows;
+}
+
+function summarize(stateRoot) {
+  const file = safeWorkPathSync(stateRoot, "capture.md", { type: "file" });
+  if (!existsSync(file)) {
+    return {
+      inbox_open: 0,
+      inbox_intaken: 0,
+      inbox_waived: 0,
+      inbox_skipped: 0,
+      inbox_failed: 0,
+      records: 0,
+      missing: true,
+      ledger: null,
+    };
+  }
+
+  const text = readFileSync(file, "utf8");
+  const meta = parseFrontmatter(text);
+  const body = text.replace(/^---[\s\S]*?---/, "");
+  const rows = parseLedgerStates(body);
+  let inbox_open = 0;
+  let inbox_intaken = 0;
+  let inbox_waived = 0;
+  let inbox_skipped = 0;
+  let inbox_failed = 0;
+  for (const row of rows) {
+    if (row.state === OPEN) inbox_open += 1;
+    else if (row.state === INTAKEN) inbox_intaken += 1;
+    else if (row.state === WAIVED) inbox_waived += 1;
+    else if (SKIPPED.has(row.state)) inbox_skipped += 1;
+    else if (row.state === "failed") inbox_failed += 1;
+  }
+
+  return {
+    inbox_open,
+    inbox_intaken,
+    inbox_waived,
+    inbox_skipped,
+    inbox_failed,
+    records: rows.length,
+    missing: false,
+    ledger: file,
+    repo: meta.repo || null,
+  };
+}
+
+function usage() {
+  console.error("Usage: node capture-status.mjs --state-root <specdev-state-root> [--json]");
+  process.exit(2);
+}
+
+function main(argv) {
+  let stateRoot = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--state-root") {
+      stateRoot = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--json") {
+      json = true;
+    } else {
+      usage();
+    }
+  }
+  if (!stateRoot) usage();
+  const summary = summarize(stateRoot);
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return 0;
+  }
+  const missing = summary.missing ? " (missing ledger, empty inbox)" : "";
+  console.log(`inbox_open:    ${summary.inbox_open}${missing}`);
+  console.log(`inbox_intaken: ${summary.inbox_intaken}`);
+  console.log(`inbox_waived:  ${summary.inbox_waived}`);
+  console.log(`inbox_skipped: ${summary.inbox_skipped}`);
+  console.log(`inbox_failed:  ${summary.inbox_failed}`);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { summarize };

package/template/workflows/specdev/specdev-t-triage/scripts/publish-status.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Aggregate published-issue counts from active + archive publish.md ledgers.
+ * Local files are authoritative; this tool does not query GitHub.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverChangesSync, readChangeFactsSync, readLegacyChangeEvidenceSync, safeWorkPathSync } from "../../../../lib/speculo-runtime.mjs";
+
+const COUNTED = new Set(["closed", "created", "commented"]);
+const SKIPPED = new Set(["skipped:cancelled", "skipped:excluded"]);
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return meta;
+}
+
+function parseLedgerStates(body) {
+  const states = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (!/^\|/.test(line) || /^\|\s*-+/.test(line) || /^\|\s*ticket\s*\|/i.test(line)) continue;
+    const cells = line.split("|").map((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 8) continue;
+    states.push(cells[7]);
+  }
+  return { states };
+}
+
+function collectLedgers(stateRoot) {
+  const files = [];
+  for (const location of discoverChangesSync(stateRoot, { includeArchived: true, includeLegacy: true })) {
+    if (location.kind === 'legacy-archive') readLegacyChangeEvidenceSync(stateRoot, location);
+    else readChangeFactsSync(stateRoot, location);
+    const file = safeWorkPathSync(location.root, 'publish.md', { type: 'file' });
+    if (existsSync(file)) files.push({ file, change: location.name });
+  }
+  return files;
+}
+
+function summarize(stateRoot) {
+  const files = collectLedgers(stateRoot);
+  let published = 0;
+  let skipped = 0;
+  let failed = 0;
+  let originLocal = 0;
+  let originIntake = 0;
+  const byChange = [];
+
+  for (const {file, change} of files) {
+    const text = readFileSync(file, "utf8");
+    const meta = parseFrontmatter(text);
+    if (meta.change !== change) throw new Error(`identity-conflict: ${file}: ledger change differs from its owning directory`);
+    const body = text.replace(/^---[\s\S]*?---/, "");
+    const { states } = parseLedgerStates(body);
+    const origin = meta.origin === "intake" ? "intake" : "local";
+    let changePublished = 0;
+    let changeSkipped = 0;
+    let changeFailed = 0;
+    for (const state of states) {
+      if (COUNTED.has(state)) {
+        changePublished += 1;
+        if (origin === "intake") originIntake += 1;
+        else originLocal += 1;
+      } else if (SKIPPED.has(state)) {
+        changeSkipped += 1;
+      } else if (state === "failed") {
+        changeFailed += 1;
+      }
+    }
+    published += changePublished;
+    skipped += changeSkipped;
+    failed += changeFailed;
+    byChange.push({
+      change,
+      origin,
+      publish_action: meta.publish_action || "unknown",
+      published: changePublished,
+      skipped: changeSkipped,
+      failed: changeFailed,
+    });
+  }
+
+  return {
+    published_issues: published,
+    origin: { local: originLocal, intake: originIntake },
+    publish_skipped: skipped,
+    publish_failed: failed,
+    ledgers: files.length,
+    changes: byChange,
+  };
+}
+
+function usage() {
+  console.error("Usage: node publish-status.mjs --state-root <specdev-state-root> [--json]");
+  process.exit(2);
+}
+
+function main(argv) {
+  let stateRoot = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--state-root") {
+      stateRoot = argv[i + 1];
+      i += 1;
+    } else if (argv[i] === "--json") {
+      json = true;
+    } else {
+      usage();
+    }
+  }
+  if (!stateRoot) usage();
+  const summary = summarize(stateRoot);
+  if (json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return 0;
+  }
+  console.log(
+    `published_issues: ${summary.published_issues}   (origin:local ${summary.origin.local}, origin:intake ${summary.origin.intake})`,
+  );
+  console.log(`publish_skipped:  ${summary.publish_skipped}`);
+  console.log(`publish_failed:   ${summary.publish_failed}`);
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+export { summarize };

package/template/workflows/specdev/specdev-w-wayfinder/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: specdev-w-wayfinder
+description: "大需求的 change 边界或实施路线尚不可见时建立探索地图，并分别澄清各 change；已有清晰 Spec 时不触发。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/wayfinder
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 探索大需求与 Change 边界
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。
+
+W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill → Spec → Tickets → 一个或多个 change 的 Goal。探索载体继续使用普通 change 目录，不增加另一套全局状态根；它不等于最终产品 change。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；先从共享地图定位当前调查 ID，再读当前问题、直接依赖及其 solution comment 原文；共享答案只引用 provenance。低分辨率地图不缓存所有开放票正文。
+
+## 按当前调查选择参考
+
+| 当前需要 | 按需读取 |
+|---|---|
+| 初次绘制问题空间，或划分多个 change | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>` |
+| 领取并解决一个调查问题，或恢复既有地图 | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/map-traversal.md</Path>` 和 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>` |
+| 生成地图、问题与答案 | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`、`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`、`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>` |
+| 选定清晰 change 交给 Goal | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>` 的交接门禁 |
+
+## 调查的决策价值
+
+每张调查说明它影响的决定、已知事实、缺失证据、最小调查、结束条件和下一 owner。只对目的地相关的兼容、迁移、权限、故障、成本和部署约束展开，不把“全面研究”变成无限搜索。答案需有可回读来源；没有依据的候选继续未知，不能以调查完成代替产品完成。
+
+## 必留纪律
+
+- 目的地约束所有调查；能精确陈述的问题成为调查票，尚不能陈述的留在战争迷雾，目标外内容不自动升级。
+- 默认每个会话最多解决一个调查 Ticket；绘图会话不关闭调查票。这个限制约束 W，不限制 P 的长期 Goal 调度；不静默减少用户明确要求的交付数量。
+- 四类保持 `wayfinder:research`、`wayfinder:prototype`、`wayfinder:grilling`、`wayfinder:task`。HITL 必须真人参与，Agent 不代答；Task 仅解除调查阻塞，不偷做目的地实现。
+- 调查认领保存在各 investigation Ticket 的实际 Assignment；不建中央镜像。先领取后执行；他人已领取的问题跳过，不接管；只暂停有归属冲突的部分。
+- 每个 materialized change 拥有自己的 design-tree、LOG、CONTEXT、ADR、Spec 与 tickets-map；涉及 UI 时也拥有经批准的 DESIGN。共享探索答案通过 solution comment 引用，不复制成多个可写事实源。
+- 缺失关键决定或必需证据时保持该 change 未就绪；其他独立清晰 change 可以交接，不要求整个大需求一次揭完迷雾。
+
+UI 调查调用 P 时按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 继承永久基线并在 HTML 后集中确认。solution comment 只保存设计合同/版本、指定原型与实际证据；探索包复用到 child change 必须核对新范围，不复制出多个永久写入 owner，也不把父探索批准自动视作 child 批准。
+
+## 校验与交接
+
+存在多个候选 change 时，由 W 写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；使用 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-template.json</Path>` 和 `<Path>{roots.workflows}/specdev/common/schemas/initiative.schema.json</Path>`。目标 change 只在用户接受边界后创建，不能挪用已属于其他任务的状态。
+
+运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder` 校验地图、claim、评论和 initiative；选定成员必须分别满足 Grill 共识、Ready Spec 和 Ready Tickets，再转交 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`。W 不把“地图完成”宣称为产品已经交付。

package/template/workflows/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md

@@ -0,0 +1,33 @@
+---
+artifact: wayfinder-map
+change: <YYYY-MM-DD-topic>
+status: active
+---
+
+# Wayfinder Map: <地图名称>
+
+## 目的地
+
+<到达此地图终点时的样子——此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 Ticket 之前以其为定位。>
+
+## 说明
+
+<领域；每个会话应咨询的 skills；此工作的常设偏好；是否明确把执行带入地图。>
+
+## 已做出的决策
+
+<!-- 索引——每个已关闭 Ticket 一行：足以判断相关性，然后放大链接查看 solution comment 持有的详细信息。开放 Tickets 通过本地 tracker 查询，不列在这里。 -->
+
+- **<已关闭 Ticket 标题>：** `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/INV-01/01-solution.md</Path>` —— <答案的一句话概括>
+
+## 尚未明确
+
+<!-- 范围内但尚无法精确表述为 Ticket 的战争迷雾；随着前沿推进而升级。 -->
+
+## 超出范围
+
+<!-- 被裁定在目的地之外的工作；已关闭，永不升级。 -->
+
+## Change 边界入口
+
+存在多个候选 change 时，W 创建并按需读取 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；地图不复制其中的候选或子状态。每个目标 change 的 Grill/Spec/Ticket 独立拥有，交接规则见 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>`。

package/template/workflows/specdev/specdev-w-wayfinder/references/initiative-discovery.md

@@ -0,0 +1,29 @@
+# Initiative：从大需求到独立 Change
+
+## 结构与所有权
+
+探索载体是现有 change 目录；W 在其中拥有 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 与 wayfinder 地图/调查票。`<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只记录候选边界、关系和 materialized target，不缓存子 change 的状态、Spec、设计树或票正文。
+
+候选 `id` 是稳定 kebab 标识，`target` 为 null 或实际 sibling change 名；同一个 target 不能重复，也不能指向探索载体本身或父 implementation change。其他任务的现存 change 只能在核验归属并获得明确关联授权后引用，不接管其工作。
+
+## 探索顺序
+
+1. 命名大目标、用户指定数量和排除项；按行为、领域边界、风险、接口与发布独立性广度扫描。
+2. 能描述边界的部分成为候选 change；不能描述的留在迷雾。候选至少写背景、目标、非目标和未知项，不预造实施步骤。
+3. 在探索地图建立共享调查问题；每个问题仍遵循 research/prototype/grilling/task、HITL/AFK 和每会话一个调查票的原纪律。
+4. 用户接受候选边界后，创建或明确关联 target change。共享答案以 solution comment/source 引用导入，不复制成新的永久知识。
+5. 对每个 target 调用 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；该 target 独立拥有 design-tree、LOG、CONTEXT、ADR。已确认共享决定可引用复用，不能要求用户机械回答同一问题。
+6. 单个 target 的关键决定清晰后分别进入 S/T；无关 target 继续探索。一个 target 的 blocker 不应阻塞其独立 sibling。
+
+## 校验与交接门禁
+
+- 候选 DAG 无环，依赖 ID 存在；目标与来源有证据，未创建 target 的候选不宣称 Ready。
+- `--stage wayfinder` 验证 initiative 结构、目标存在性与禁止自引用；它不等于子 change 已就绪。
+- 交接时对**选定** target 分别执行 `--stage grill` 与 `--stage tickets --repo <project-root>`，检查设计树 consensus、Spec `ready_for_tickets`、所有待执行票 Ready。
+- 选定范围的跨 change 依赖须同时选择或有已完成基线证据，不用未完成/已取消票虚假满足依赖。
+- 一个 target 交给 P 的单 change 分支；两个或以上 Ready target 交给 P 的多 change 分支。P 不接手剩余迷雾，也不为这些未知部分伪造计划。
+- 用户明确要求全部 change 时，报告全部候选与各自阻塞；交接已清晰部分不等于少交付其他部分或宣布整个大需求完成。
+
+## 版本与恢复
+
+变更候选边界或依赖时递增 `revision`，在探索 LOG 记录来源和替代关系。原 claim、评论编号和低分辨率地图仍是原协议；不改写其他任务，不把探索载体迁成父实现 change。两者可以关联，但职责和 owner 分开。

package/template/workflows/specdev/specdev-w-wayfinder/references/local-tracker-contract.md

@@ -0,0 +1,33 @@
+# Wayfinder 本地 Tracker 适配
+
+最新版 Wayfinder 以 issue tracker 为物理载体。SpecDev 的默认 tracker 是 change state 内的本地 Markdown/JSON；本文件只映射物理原语，不改写 Wayfinder 的地图、Ticket、战争迷雾或遍历语义。
+
+| Tracker 原语 | 本地实现 |
+|---|---|
+| 地图 issue | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` |
+| 子 issue | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` |
+| label | Ticket frontmatter 的 `wayfinder:research|prototype|grilling|task` |
+| 阻塞关系 | Ticket frontmatter 的 `blocked_by` |
+| assignment | 原 investigation Ticket 的 `## Assignment` 实际领取记录 |
+| solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` |
+| 关闭 issue | Ticket frontmatter 的 `status: closed` 与 `resolution` |
+
+## 查询前沿
+
+扫描当前地图的全部子 Ticket。一个 Ticket 同时满足以下条件时属于**前沿**：
+
+1. `status: open`；
+2. `blocked_by` 中的每个 Ticket 都是 `status: closed`；
+3. 该 Ticket 没有仍有效的实际 Assignment。
+
+按文件名中的数字 ID 升序返回。地图正文不缓存开放 Ticket 列表；每次选择前沿都从 Ticket 与 claim 事实重新查询。
+
+## 原子领取
+
+实际领取时在该 Ticket 的 `## Assignment` 写 Owner、Session、Claimed-At 与依据，缺省单 writer；并发必须由真实单写入者协调或有可证明隔离，普通文件 rename 不证明互斥。重读确认未被他人领取，冲突选下一前沿。完成/释放时记录真实处置，不因超时删除他人领取。未领取不建空槽，地图只导航，不建中央 claim registry。
+
+## 解决方案评论
+
+Ticket 正文只保存问题。答案写入下一个未占用的 solution comment 文件，资产从评论链接，不粘贴进 Ticket。关闭 Ticket 后，地图的“已做出的决策”只追加名称链接和一句概括；`out-of-scope` 不进入决策索引。
+
+**完成标准**：地图、Ticket、claim、阻塞和 solution comment 可以重建相同前沿；同一事实没有第二份可写副本。

package/template/workflows/specdev/specdev-w-wayfinder/references/map-traversal.md

@@ -0,0 +1,120 @@
+# 寻路
+
+
+一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
+
+目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
+
+
+## 核心纪律
+
+### 规划，而非执行
+
+Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
+
+### 用名称引用
+
+每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
+
+### 每会话一个 Ticket
+
+无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 Ticket。
+
+## 产物与适配
+
+- 地图：`<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- 子 Tickets：`<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- solution comments：`<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
+- assignment：原 investigation Ticket 的实际领取/交接依据，不建全局镜像
+
+每次绘制或遍历前加载 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>`。Ticket 和地图模板：
+
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>`
+
+## Ticket 类型
+
+每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
+
+- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
+- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/specdev-p-prototype/SKILL.md</Path>` 继承项目基线、组合模板并先生成 HTML，再集中确认设计。把 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>、其 revision/digest、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、comparison/final 和浏览器证据链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
+- **Grilling（HITL）**：对话。调用 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>` 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
+- **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
+
+Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:grilling | wayfinder:task`。
+
+## 战争迷雾与范围
+
+地图刻意不完整：不要绘制还看不到的内容。活跃 Tickets 之外是**战争迷雾**——能感觉即将到来、但依赖尚未解决问题而无法精确陈述的决策和调查。
+
+**迷雾还是 Ticket？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
+
+- 问题已经清晰时做成 Ticket，即使仍被阻塞；
+- 还无法精确表述时留在“尚未明确”，不预先切成 Ticket 大小碎片。
+
+目的地固定范围。目标之外的工作进入**超出范围**，不是战争迷雾。范围之外永不升级；只有重新命名目的地并创建新 change 时才重新考虑。越界 Ticket 关闭为 `out-of-scope`，链接进“超出范围”，不进入“已做出的决策”。
+
+## 调用模式
+
+### 绘制地图
+
+用户带着模糊想法调用：
+
+1. **命名目的地。** 运行一轮 G 的 grilling/domain-modeling，确定正在寻路的 Spec、决策或变更。
+2. **绘制前沿。** 再次质询，这次广度优先，在整个空间展开而非深入一条线索。如果没有浮现任何迷雾，停下并询问用户如何继续，不创建地图。
+3. **创建地图。** 使用模板填写目的地和说明；“已做出的决策”为空，迷雾写入“尚未明确”。
+4. **创建现在可明确的 Tickets。** 先创建全部 Ticket，再第二遍连接 `blocked_by`，因为 ID 必须先存在。
+5. **派出 research Agent。** 每个 research Ticket 使用独立上下文和 claim，各自只解决一个 Ticket；需要 Git 分支时先取得对应授权。
+6. 停止。绘制地图是一个会话的工作，它不亲手解决任何 Ticket。
+
+**完成标准**：目的地、地图、当前可表述 Tickets、阻塞边和战争迷雾已持久化；绘图会话没有关闭 Ticket。
+
+### 遍历地图
+
+用户带来地图，可选指定 Ticket：
+
+1. 加载地图的低分辨率视图，不加载每个 Ticket 正文。
+2. 用户指定 Ticket 时使用它；否则按本地 tracker contract 查询并选择第一个 frontier Ticket。
+3. 在任何工作前领取 Ticket。已领取时跳过并选择其他 frontier。
+4. 按需缩放：只读取当前 Ticket、相关或已关闭 Ticket 的详情，以及“说明”指定的能力。
+5. 解决当前唯一 Ticket，使用下一个未占用编号写 solution comment，原子关闭 Ticket 并释放 claim。
+6. 在地图“已做出的决策”追加名称链接和一句概括；越界则写入“超出范围”。
+7. 创建新浮现的 Tickets，第二遍连接阻塞；从“尚未明确”删除每个已升级补丁；更新或关闭被答案判定无效的 Tickets。
+
+写回前重读地图、Ticket 与 claims，预期其他会话并发编辑。
+
+**完成标准**：本会话只关闭一个 Ticket；Ticket、solution comment、claim、地图和新 frontier 一致。
+
+## 收敛与路由
+
+当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
+
+路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder`；Ticket、claim、comment 或地图不一致时保持 blocked。
+
+- 需要产品或架构取舍：`<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；
+- 外部行为已清楚：`<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`；
+- Spec Ready、只需拆分：`<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>`；
+- Bug 根因路线收敛：`<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>`；
+- 仍有高影响未知项：保持 active/blocked 并返回下一 frontier Ticket 名称。
+
+## 完成标准
+
+- 目的地塑造每个 Ticket 并固定范围；
+- 地图是低分辨率索引，不列开放 Tickets，不复制答案详情；
+- 四类 Ticket 与 HITL/AFK 语义正确；
+- frontier 由 open、unblocked、unclaimed 事实查询；
+- 名称用于人类叙述，裸 ID 只作内部标识；
+- 战争迷雾、Ticket 与超出范围按可精确表述性和范围区分；
+- 每会话最多解决一个 Ticket，HITL 用户没有被 Agent 代答；
+- 每个关闭 Ticket 有 solution comment，资产通过链接引用；
+- claim、阻塞、地图与 Ticket 状态一致；
+- 路径清晰时返回下一 work，不把产品实现藏进寻路。
+
+## 子文件引用
+
+- 本地 Tracker：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`
+- Solution comment：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>`
+- 地图模板：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`
+- Ticket schema：`<Path>{roots.workflows}/specdev/common/schemas/wayfinder-ticket.schema.json</Path>`