@namewta/speculo 2.0.6 → 2.1.1

package/template/lib/speculo-runtime.mjs

@@ -7593,6 +7593,27 @@ async function readAssetCatalog(root) {
 // src/coordination.ts
 import { readFile as readFile3 } from "node:fs/promises";
 import { join as join3 } from "node:path";
+
+// src/retained-workflows.ts
+function validateRetainedWorkflows(value, installed) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) throw new Error("invalid-retained-workflows");
+  const ids = /* @__PURE__ */ new Set(), works = /* @__PURE__ */ new Set();
+  for (const w of value) {
+    if (!w || typeof w.id !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(w.id) || ids.has(w.id) || installed.includes(w.id) || Object.keys(w).some((k) => !["id", "works"].includes(k)) || !Array.isArray(w.works)) throw new Error("invalid-retained-workflow");
+    ids.add(w.id);
+    for (const work of w.works) {
+      if (!work || typeof work.id !== "string" || !work.id.startsWith(w.id + "/") || !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(work.id) || works.has(work.id) || Object.keys(work).some((k) => !["id", "stages"].includes(k)) || !Array.isArray(work.stages) || work.stages.some((s) => typeof s !== "string" || !s.trim()) || new Set(work.stages).size !== work.stages.length) throw new Error("invalid-retained-work");
+      works.add(work.id);
+    }
+  }
+  return value;
+}
+function retainedAssets(registry) {
+  return registry.flatMap((w) => w.works.map((work) => ({ id: work.id, stages: work.stages, kind: "work-skill", domain: w.id, name: work.id.split("/")[1], entry: "", description: "inactive retained runtime registration" })));
+}
+
+// src/coordination.ts
 var ORCHESTRATION_MODES = ["lead", "orca", "herdr", "cli"];
 function object(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -7609,7 +7630,7 @@ function choice(value) {
   if (value.fallback !== void 0 && (!Array.isArray(value.fallback) || new Set(value.fallback).size !== value.fallback.length || value.fallback.some((m) => !ORCHESTRATION_MODES.includes(m)))) throw new Error("coordination-policy-conflict: invalid fallback");
   if (value.selection === "required" && Array.isArray(value.fallback) && value.fallback.length) throw new Error("coordination-policy-conflict: required choice cannot allow fallback");
 }
-function validateProjectCoordination(value, catalog) {
+function validateProjectCoordination(value, catalog, inactive = []) {
   if (!object(value)) throw new Error("coordination-policy-conflict: project facts must be an object");
   exact(value, ["schema_version", "defaults", "rules"]);
   if (value.schema_version !== 1 || !Array.isArray(value.rules)) throw new Error("coordination-policy-conflict: expected schema 1 and rules");
@@ -7619,14 +7640,14 @@ function validateProjectCoordination(value, catalog) {
     if (!object(rule)) throw new Error("coordination-policy-conflict: invalid rule");
     exact(rule, ["work_id", "stage", "choice"]);
     choice(rule.choice);
-    const asset = catalog.assets.find((a) => a.kind === "work-skill" && a.id === rule.work_id);
+    const asset = [...catalog.assets, ...inactive].find((a) => a.kind === "work-skill" && a.id === rule.work_id);
     if (!asset || rule.stage !== void 0 && (typeof rule.stage !== "string" || !asset.stages.includes(rule.stage))) throw new Error("coordination-policy-conflict: unknown Work or stage");
     const key = `${rule.work_id}:${rule.stage ?? "*"}`;
     if (seen.has(key)) throw new Error("coordination-policy-conflict: duplicate rule " + key);
     seen.add(key);
   }
 }
-async function readProjectCoordination(stateRoot, catalog) {
+async function readProjectCoordination(stateRoot, catalog, inactive) {
   let source;
   try {
     source = await readFile3(join3(stateRoot, "coordination", "project.json"), "utf8");
@@ -7634,8 +7655,21 @@ async function readProjectCoordination(stateRoot, catalog) {
     if (e.code === "ENOENT") return null;
     throw e;
   }
+  if (inactive === void 0) {
+    inactive = [];
+    let metadata;
+    try {
+      metadata = JSON.parse(await readFile3(join3(stateRoot, "install.json"), "utf8"));
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    if (metadata) {
+      if (metadata.schema_version !== 4) throw new Error("invalid-retained-installation-schema");
+      inactive = retainedAssets(validateRetainedWorkflows(metadata.retained_workflows, catalog.assets.filter((a) => a.kind === "domain-skill").map((a) => a.domain)));
+    }
+  }
   const value = JSON.parse(source);
-  validateProjectCoordination(value, catalog);
+  validateProjectCoordination(value, catalog, inactive);
   return value;
 }
 
@@ -7772,10 +7806,10 @@ function markdownBodyLines(text, path = "README.md") {
       }
     }
     if (visible !== raw && /^Outcome\b/i.test(visible.trimStart())) fail("outcome-invalid", path, "Outcome must occupy an uncommented independent line", i + 1);
-    const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(visible);
-    if (open) {
-      if (open[1][0] === "`" && open[2].includes("`")) fail("outcome-invalid", path, "ambiguous code fence", i + 1);
-      fence = { char: open[1][0], length: open[1].length, line: i + 1 };
+    const open2 = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(visible);
+    if (open2) {
+      if (open2[1][0] === "`" && open2[2].includes("`")) fail("outcome-invalid", path, "ambiguous code fence", i + 1);
+      fence = { char: open2[1][0], length: open2[1].length, line: i + 1 };
       continue;
     }
     if (/^(?: {4}|\t| {0,3}>)/.test(visible)) continue;
@@ -7914,6 +7948,146 @@ function readArtifactSectionSync(path, anchor) {
   if (!body.replace(/^#+ .*$/gm, "").trim()) fail("closure-evidence-missing", path, `empty ${anchor} section`, start);
   return { path, section: anchor, text: body, line: start };
 }
+
+// src/hub-catalog.ts
+import { readFile as readFile4, readdir as readdir4 } from "node:fs/promises";
+import { join as join6, posix } from "node:path";
+
+// src/skill-trees.ts
+import { chmod, lstat as lstat3, mkdir, readdir as readdir3, rmdir } from "node:fs/promises";
+import { dirname as dirname4, join as join5 } from "node:path";
+
+// src/external-files.ts
+import { constants } from "node:fs";
+import { lstat as lstat2, open, rename, rm } from "node:fs/promises";
+function image(content, mode = 420) {
+  return { content: Buffer.from(content).toString("base64"), mode: process.platform === "win32" ? mode & 128 ? 438 : 292 : mode };
+}
+async function readImage(path, options = {}) {
+  let stat;
+  try {
+    stat = await lstat2(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || !options.allowSourceHardlinks && stat.nlink !== 1) {
+    throw new Error(`unsafe-external-file: ${path}; preserve the link and resolve source ownership before init`);
+  }
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const actual = await handle.stat();
+    if (!actual.isFile() || actual.dev !== stat.dev || actual.ino !== stat.ino || !options.allowSourceHardlinks && actual.nlink !== 1) throw new Error(`external-drift: ${path}`);
+    return image(await handle.readFile(), stat.mode & 511);
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/skill-trees.ts
+var absent = { kind: "absent" };
+function validSkillNode(node, directories = true) {
+  if (!node || typeof node !== "object") return false;
+  if (node.kind === "absent") return Object.keys(node).length === 1;
+  if (!Number.isInteger(node.mode) || node.mode < 0 || node.mode > 511) return false;
+  if (node.kind === "directory") return directories && Object.keys(node).length === 2;
+  return node.kind === "file" && Object.keys(node).length === 3 && typeof node.content === "string" && Buffer.from(node.content, "base64").toString("base64") === node.content;
+}
+async function readSkillNode(path, source = false) {
+  let stat;
+  try {
+    stat = await lstat3(path);
+  } catch (e) {
+    if (e.code === "ENOENT") return absent;
+    throw e;
+  }
+  if (stat.isSymbolicLink()) throw new Error("skill-symlink: " + path);
+  if (stat.mode & 3584) throw new Error("unsafe-skill-mode: " + path);
+  if (stat.isDirectory()) return { kind: "directory", mode: process.platform === "win32" ? 493 : stat.mode & 511 };
+  const value = await readImage(path, { allowSourceHardlinks: source });
+  if (!value) return absent;
+  return { kind: "file", ...value };
+}
+async function snapshotSkillTree(root, options = {}) {
+  const nodes = /* @__PURE__ */ new Map();
+  async function visit(name) {
+    if (name && (!safeRelativePath(name) || name.endsWith("/"))) throw new Error("unsafe-skill-resource: " + name);
+    const node = await readSkillNode(join5(root, name), options.source);
+    if (node.kind === "absent") return;
+    nodes.set(name, node);
+    if (node.kind === "directory") {
+      const names = (await readdir3(join5(root, name))).sort();
+      if (new Set(names.map((n) => n.toLowerCase())).size !== names.length) throw new Error("ambiguous-skill-casing: " + root);
+      for (const child of names) await visit(name ? `${name}/${child}` : child);
+    }
+  }
+  await visit("");
+  return nodes;
+}
+
+// src/hub-catalog.ts
+var SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+async function discoverHubCatalog(packageRoot) {
+  const root = join6(packageRoot, "skills-hub"), catalog = /* @__PURE__ */ new Map();
+  let bundle;
+  try {
+    bundle = JSON.parse(await readFile4(join6(packageRoot, "dist/src/hub-resources.json"), "utf8"));
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  if (bundle && (bundle.schema_version !== 1 || !Array.isArray(bundle.packages) || new Set(bundle.packages.map((p) => p.id)).size !== bundle.packages.length)) throw new Error("invalid-hub-bundle");
+  const names = new Set((await readAssetCatalog(join6(packageRoot, "template"))).assets.map((a) => a.name));
+  const categories = await readdir4(root, { withFileTypes: true }).catch((e) => {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  });
+  for (const category of categories.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (category.isSymbolicLink()) throw new Error("hub-source-symlink: " + category.name);
+    if (!category.isDirectory()) continue;
+    if (!SLUG.test(category.name)) throw new Error("invalid-hub-category: " + category.name);
+    for (const entry of (await readdir4(join6(root, category.name), { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.isSymbolicLink()) throw new Error("hub-source-symlink: " + entry.name);
+      if (!entry.isDirectory()) continue;
+      const source = join6(root, category.name, entry.name), content = await readFile4(join6(source, "SKILL.md"));
+      const errors = validateSkill(content, entry.name);
+      if (errors.length) throw new Error(`invalid-hub-skill: ${category.name}/${entry.name}: ${errors.join("; ")}`);
+      if (names.has(entry.name)) throw new Error("duplicate-skill-name: " + entry.name);
+      names.add(entry.name);
+      const id = `${category.name}/${entry.name}`;
+      let tree = await snapshotSkillTree(source, { source: true });
+      if (bundle) {
+        const packaged = bundle.packages.find((p) => p.id === id);
+        if (!packaged || !Array.isArray(packaged.nodes)) throw new Error("missing-hub-bundle-package: " + id);
+        const original = /* @__PURE__ */ new Map();
+        for (const { path, node } of packaged.nodes) {
+          if (typeof path !== "string" || path && (!safeRelativePath(path) || path.endsWith("/")) || original.has(path) || !validSkillNode(node) || node.kind === "absent") throw new Error("invalid-hub-bundle-node");
+          original.set(path, process.platform === "win32" ? { ...node, mode: node.kind === "directory" ? 493 : node.mode & 128 ? 438 : 292 } : node);
+        }
+        if (original.get("")?.kind !== "directory" || original.get("SKILL.md")?.kind !== "file") throw new Error("invalid-hub-bundle-root");
+        for (const [path, node] of original) if (path && original.get(posix.dirname(path) === "." ? "" : posix.dirname(path))?.kind !== "directory") throw new Error("invalid-hub-bundle-parent");
+        for (const [path, node] of tree) {
+          const expected = original.get(path);
+          if (!expected || expected.kind !== node.kind || node.kind === "file" && (expected.kind !== "file" || expected.content !== node.content)) throw new Error(`stale-hub-bundle: ${id}/${path}; rebuild from skills-hub`);
+        }
+        tree = original;
+      }
+      for (const [path, node] of tree) if (node.kind === "file" && path.endsWith(".md")) {
+        const text = Buffer.from(node.content, "base64").toString("utf8").replace(/```[^]*?```/g, "");
+        for (const match of text.matchAll(/\[[^\]]*\]\(([^\s)]+)(?:\s+"[^"]*")?\)/g)) {
+          const link = match[1];
+          if (/^(?:[a-z][a-z0-9+.-]*:|#|\/)/i.test(link) || /[<>${}]/.test(link)) continue;
+          const resource = decodeURIComponent(link.split("#")[0]);
+          if (!resource) continue;
+          const resolved = posix.normalize(posix.join(posix.dirname(path), resource)).replace(/\/$/, "");
+          if (!safeRelativePath(resolved) || !tree.has(resolved)) throw new Error(`hub-resource-link: ${category.name}/${entry.name}/${path}: ${link}`);
+        }
+      }
+      catalog.set(id, { id, name: entry.name, description: String(parseFrontmatter(content).fields.description), root: source, tree });
+    }
+  }
+  if (bundle && bundle.packages.some((p) => !catalog.has(p.id))) throw new Error("hub-bundle-catalog-mismatch");
+  return catalog;
+}
 export {
   ArtifactError,
   DEFAULT_ROOTS,
@@ -7923,6 +8097,7 @@ export {
   containedPath,
   discoverChanges,
   discoverChangesSync,
+  discoverHubCatalog,
   locateProject,
   markdownBodyLines,
   parseFrontmatter,

package/template/references/coordination/coordination-contract.md

@@ -4,17 +4,25 @@
 
 ## 何时读取
 
-进入已授权实现、独立审查、Goal 的 run/resume，或当前 Work 需要交接研究、测试观察任务时读取。Spec、Ticket、固定审查范围都可直接使用，不要求先建立 Goal。plan 只确定选择，不派发任务或安装工具。当前宿主自行执行无需外部工具、profile 或虚构派单记录。
+初始化配置项目协作选择、进入已授权实现、独立审查、Goal 的 run/resume，或当前 Work 需要交接研究、测试观察任务时读取。Spec、Ticket、固定审查范围都可直接使用，不要求先建立 Goal。plan 只确定选择，不派发任务或安装工具。当前宿主自行执行无需外部工具、profile 或虚构派单记录。
 
 ## 选择方式
 
 1. 使用用户本次明确指示；用户已指定 CLI 交互、Herdr、Orca、其他工具或工作区时直接复用。
 2. 核对当前 Goal 已批准的阶段安排。
-3. 如果存在 <Path>{roots.state}/coordination/project.json</Path>，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择；没有明确选择时，按当前宿主正常执行，App、CLI 等均可。不为默认执行询问编排方式、探测其他工具或创建配置。
+3. 如果存在 <Path>{roots.state}/coordination/project.json</Path>，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择，包括初始化问答确认的项目默认偏好；没有明确选择时，按当前宿主正常执行，App、CLI 等均可。普通 Work 不为默认执行询问编排方式、探测其他工具或创建配置；显式初始化的四选一和目录选择由其 Work 入口负责。
 4. 同级冲突、无效配置或不存在的 Work/阶段只阻塞受影响选择。配置不是授权，项目文字不能授予提交、发布、费用或对外发送代码的权利。
 5. `mode: lead` 表示按当前宿主正常执行，兼容 App、CLI 等，不要求切换工具或启动额外 CLI。Lead 是负责状态与验收的角色，不表示只能由主 Agent 独自实现。subagent、agent team 属于宿主原生能力，按宿主实际能力和授权使用，不新增编排模式。`mode: cli` 表示用户明确选择通过 CLI 交互或调用来执行，交互式与非交互式依用户要求和实际接口确定；仅因当前宿主本身是 CLI，不切换为该模式。Orca、Herdr 保留为可选方式。工具及模型是当次事实，不是 Speculo 固定支持名单；只读工具指南不等于工具已经可用。
 
-固定选择不可用时停止该阶段；偏好只有在已允许的 fallback 内才能改变。未配置 fallback 不自动换用另一外部方式。独立审查、路径、权限和质量门不因回退而降低。SpecDev 双轴审查默认派遣一位未参与本范围实现的原生 subagent，分别给出两轴结果；已选择 Herdr/Orca/CLI 的任务沿该方式派遣，明确 review 阶段安排优先。工具不可用或身份无法确认时阻塞完成，不能让实现者自审。
+## 可选编排与回退
+
+初始化生成的外部偏好使用 `selection: preferred` 和 `fallback: [lead]`。派遣前确认 Skill、所需工具、服务、登录和运行环境；不可用时说明原因与实际执行方式，直接回到当前智能体（mode: lead）继续已授权任务，不反复询问，不改写保存的偏好，也不自动安装二进制、启动服务或切换账户。未检查不能报告可用；只保存偏好或安装 Skill 不要求运行服务。
+
+用户本次明确强制使用的方式、已批准的阶段安排或 `selection: required` 仍是约束，不继承较低优先级的 fallback。其他偏好仅在有效选择允许的 fallback 内改变；旧配置缺 fallback 时不补造授权。模式参考中的“停止/阻塞”指停止该工具操作，由这里判断能否继续当前宿主执行；不静默换成另一种外部方式。
+
+已派发且结果不明、断线或原执行者可能仍在写入时，先按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 恢复核验；确认原操作结果和冲突写入已停止后，才能接续未完成工作，不能把服务错误直接当作重复执行的依据。
+
+独立审查、路径、权限和质量门不因回退而降低。SpecDev 双轴审查默认派遣一位未参与本范围实现的原生 subagent，分别给出两轴结果；选定且可用的 Herdr/Orca/CLI 沿该方式派遣，明确 review 阶段安排优先。回退 lead 后仍须满足独立审查；缺少独立 reviewer 或身份无法确认时阻塞完成，不能让实现者自审。
 
 ## 当前任务
 

package/template/references/coordination/modes/cli.md

@@ -1,8 +1,8 @@
 # CLI 交互与调用
 
-仅在用户明确选择通过 CLI 交互或调用来执行时读取；当前宿主本身是 CLI 不触发本分支。先读取用户指定工具的当前帮助、已安装技能或对应交互方式的官方指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
+仅在按 <Path>{roots.references}/coordination/coordination-contract.md</Path> 为当前任务选中 CLI 交互或调用时读取；选择可来自当前请求、已批准安排或项目偏好，当前宿主本身是 CLI 不触发本分支。初始化选择 CLI 只保存偏好，不安装 Herdr/Orca Skill；plan 不执行调用。实际使用前复用已知工具与交互方式，缺失时向用户明确，再读取其当前帮助、已安装技能或对应交互方式的官方指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
 
-1. 确认工具可用、工作目录、交互方式、输入输出和当前用户已给出的权限。用户指定交互式会话时，使用宿主实际支持的终端/会话能力；只有用户要求或所选工具支持的任务接口适合非交互调用时才采用非交互方式。明确要求的交互方式不可用时停止该分支并报告，不擅自改为无头调用或 Herdr。缺少登录或能力时报告，不自行改变账户、安装工具或添加绕过权限的参数。
+1. 确认工具可用、工作目录、交互方式、输入输出和当前用户已给出的权限。用户指定交互式会话时，使用宿主实际支持的终端/会话能力；只有用户要求或所选工具支持的任务接口适合非交互调用时才采用非交互方式。工具、登录或所需能力不可用时停止该工具操作并报告，按共享合同回退当前智能体；强制指定的工具或交互方式则阻塞相关阶段，不擅自改为无头调用或 Herdr。不自行改变账户、安装工具或添加绕过权限的参数。
 2. 依照 <Path>{roots.references}/coordination/task-brief.md</Path> 准备任务；有 change 时先保存 TASK，指定真实 Work 入口、必要输入、REPORT 位置和提问/通知通道。若工作副本不能读取入口，先提供允许范围内的实际文件，不凭描述猜测内容。
 3. 通过当前宿主可用的执行工具调用该 CLI。优先使用结构化 argv 或可靠的参数传递；任务正文通过工具支持的 stdin、文件或会话输入，不拼接不可信 shell 片段。
 4. 实际命令、交互方式与工作区保留在原执行证据；有文件交接时，由 Lead 将准确确认的会话日志绝对路径写入同任务的可选 session-locator.json，仅含 path 字段。TASK 投递后冻结，执行者写 REPORT 并返回任务标识、状态、报告位置和一句话摘要。只有文本返回时由 Lead 按 <Path>{roots.references}/coordination/session-files.md</Path> 原样捕获。进程退出后记录真实退出码，仍运行或未知时据实记录；没有可靠提供的模型、用量或成本写为未知。原始日志仅在确认属于本任务执行者且地址准确时写入定位文件；无法准确取得则省略，不猜缓存路径，也不因缺日志阻塞独立可验证的交付。

package/template/references/coordination/modes/herdr.md

@@ -1,21 +1,21 @@
 # Herdr 编排
 
-仅在用户为当前任务明确选择 Herdr 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Herdr 选择不隐含 worktree、模型或拓扑选择。
+仅在初始化明确选择 Herdr 接入分支，或按 <Path>{roots.references}/coordination/coordination-contract.md</Path> 为当前任务选中 Herdr 时读取；选择可来自当前请求、已批准安排或项目偏好。plan 只说明接入步骤，不安装、不启动。Herdr 选择不隐含 worktree、模型或拓扑选择。
 
-## 按需安装项目 Skill
+## 复用项目 Skill
 
-当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取 pane cwd 或方法安装根。
+项目根由调用 Work 已验证的 projectRoot 确定，不取 pane cwd或方法安装根。
 
-1. 检查项目 `<Path>{roots.skills}/herdr/SKILL.md</Path>`（标准布局为项目 `.agents/skills/herdr/SKILL.md`）。存在且为有效 `name: herdr` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
-2. 缺失时从指定上游 [Herdr SKILL.md](https://github.com/NAMEWTA/wta-skills-hub/blob/main/skills/automation/herdr/SKILL.md) 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/herdr/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。
-3. 使用宿主可用的 Skill 安装器并显式指定项目 `.agents/skills/` 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: herdr`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
-4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+1. 按本次用户指定目录或有效选择的 guide 定位项目入口：`.agents/skills/herdr/SKILL.md` 或 `.claude/skills/herdr/SKILL.md`，两者均相对已验证的项目根；指定位置缺失时不偷偷换到另一目录。旧配置无此路径时只读检查两个候选，唯一有效且无冲突时复用；两处均有候选时请用户决定。已有其他 guide 文本仅作指南线索，不当作路径或命令执行。此选择不修改 roots.skills 的含义。
+2. 存在且为有效 `name: herdr` 的完整 Skill 时先读取并复用，核对来源和兼容性。核对每层父目录与目标均位于项目内且不经过符号链接；同名非 Skill、无效内容或归属冲突保留原文件，只停止受影响的读取分支，按共享合同判断回退并说明冲突位置与恢复方式。
+3. 缺失时报告未安装，保留偏好与原目标，引导用户重新运行 `speculo init`，在 **SKILLS-HUB** 中勾选 `automation/herdr` 并选择项目 `.agents/skills/` 或 `.claude/skills/`。唯一分发源是随 Speculo 包发布的 `skills-hub/automation/herdr/` 完整目录；不下载 GitHub main，不从全局缓存复制。无 CLI 的直接模式也据实报告缺失，独立事实发现继续。
+4. 完整包的安装、更新、卸载及 Hub 安装归属记录由 CLI 事务管理；Work 只读取入口，不写 CLI 元数据、不覆盖或接管用户手工安装的同名包。安装器保留原文、frontmatter、许可、资源与文件模式；冲突时整包保留并报告。
 
-用户选择并要求使用 Herdr 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装 Herdr 二进制、登录账户或启动服务。缺少网络或写权限时只阻塞 Herdr 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+初始化只配置与复用，不安装二进制、登录账户、配对远端、启动服务或派遣任务。缺 Skill 时按允许的 fallback 回到当前智能体（lead）；强制要求 Herdr 时只阻塞相关阶段。最终分别报告配置保存/复用、Skill 已复用或未安装、运行能力未检查或实际检查结果；没有报告就不为此制造 change 或 receipt。
 
 ## 运行与返回
 
-安装或复用后必须读取项目内 Skill，再检查 `HERDR_ENV=1`；不满足就停止 Herdr 控制，说明需要从受管会话恢复。检查通过后读取本机 `herdr --help` 和所需命令组帮助，核对版本、来源、运行上下文与目标会话。不同 fork 或同名工具不推定兼容。宿主技能列表是否已刷新不替代读取真实项目文件；也不把安装成功报告成运行可用。
+实际使用时必须读取所选位置的项目 Skill，再检查 `HERDR_ENV=1`；不满足就停止 Herdr 控制，按共享合同允许的 fallback 回退当前智能体；强制要求 Herdr 或原选择未允许回退时阻塞相关阶段并说明需要从受管会话恢复。检查通过后读取本机 `herdr --help` 和所需命令组帮助，核对版本、来源、运行上下文与目标会话；工具或服务不可用同样按共享合同处理。不同 fork 或同名工具不推定兼容。宿主技能列表是否已刷新不替代读取真实项目文件；也不把安装成功报告成运行可用。
 
 1. 遵守当前指南对 Herdr 环境和会话操作范围的要求。若当前环境无法控制目标，只阻塞此任务方式；不接管其他前台会话。
 2. 根据用户指定的编程工具和模型，在指南支持的范围内选择调用。Herdr 是编排方式，不是模型；不得固化某家 CLI 的参数。

package/template/references/coordination/modes/orca.md

@@ -1,23 +1,23 @@
 # Orca 编排
 
-仅在用户为当前任务明确选择 Orca 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Orca 选择不隐含 worktree、模型或拓扑选择。
+仅在初始化明确选择 Orca 接入分支，或按 <Path>{roots.references}/coordination/coordination-contract.md</Path> 为当前任务选中 Orca 时读取；选择可来自当前请求、已批准安排或项目偏好。plan 只说明接入步骤，不安装、不启动。Orca 选择不隐含 worktree、模型或拓扑选择。
 
-## 按需安装项目 Skill
+## 复用项目 Skill
 
-当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取终端 cwd、桌面客户端路径或方法安装根。
+项目根由调用 Work 已验证的 projectRoot 确定，不取 终端 cwd、桌面客户端路径或方法安装根。
 
-1. 检查项目 `<Path>{roots.skills}/orca/SKILL.md</Path>`（标准布局为项目 `.agents/skills/orca/SKILL.md`）。存在且为有效 `name: orca` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
-2. 缺失时从指定上游 [Orca SKILL.md](https://github.com/NAMEWTA/wta-skills-hub/blob/main/skills/automation/orca/SKILL.md) 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/orca/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。Skill 指向的 Orca 内置指南由实际 CLI 提供，不是缺失的本地资源。
-3. 使用宿主可用的 Skill 安装器并显式指定项目 `.agents/skills/` 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: orca`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
-4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+1. 按本次用户指定目录或有效选择的 guide 定位项目入口：`.agents/skills/orca/SKILL.md` 或 `.claude/skills/orca/SKILL.md`，两者均相对已验证的项目根；指定位置缺失时不偷偷换到另一目录。旧配置无此路径时只读检查两个候选，唯一有效且无冲突时复用；两处均有候选时请用户决定。已有其他 guide 文本仅作指南线索，不当作路径或命令执行。此选择不修改 roots.skills 的含义。
+2. 存在且为有效 `name: orca` 的完整 Skill 时先读取并复用，核对来源和兼容性。核对每层父目录与目标均位于项目内且不经过符号链接；同名非 Skill、无效内容或归属冲突保留原文件，只停止受影响的读取分支，按共享合同判断回退并说明冲突位置与恢复方式。
+3. 缺失时报告未安装，保留偏好与原目标，引导用户重新运行 `speculo init`，在 **SKILLS-HUB** 中勾选 `automation/orca` 并选择项目 `.agents/skills/` 或 `.claude/skills/`。唯一分发源是随 Speculo 包发布的 `skills-hub/automation/orca/` 完整目录；不下载 GitHub main，不从全局缓存复制。无 CLI 的直接模式也据实报告缺失，独立事实发现继续。
+4. 完整包的安装、更新、卸载及 Hub 安装归属记录由 CLI 事务管理；Work 只读取入口，不写 CLI 元数据、不覆盖或接管用户手工安装的同名包。安装器保留原文、frontmatter、许可、资源与文件模式；冲突时整包保留并报告。
 
-用户选择并要求使用 Orca 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装或升级 Orca、登录账户、配对远端或启动服务。缺少网络或写权限时只阻塞 Orca 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+初始化只配置与复用，不安装二进制、登录账户、配对远端、启动服务或派遣任务。缺 Skill 时按允许的 fallback 回到当前智能体（lead）；强制要求 Orca 时只阻塞相关阶段。最终分别报告配置保存/复用、Skill 已复用或未安装、运行能力未检查或实际检查结果；没有报告就不为此制造 change 或 receipt。
 
 ## 运行与返回
 
-安装或复用后必须读取项目内 Skill，按其规则定位实际 CLI：优先核对 `ORCA_CLI_COMMAND`，开发上下文核对 `ORCA_DEV_REPO_ROOT`；Linux 非托管环境使用指南规定的 `orca-ide` 入口，避免误调用同名屏幕阅读器。不要套用 Herdr 的环境变量要求，也不把环境值交给 eval。固定入口后读取本机 `--help`、`skills get orca-cli`；需要受监督编排时再读 `skills get orchestration` 及当前分支参考。核对版本、来源、执行主机与目标 runtime 能力，不把上游 main 当作本机可用接口。
+实际使用时必须读取所选位置的项目 Skill，按其规则定位实际 CLI：优先核对 `ORCA_CLI_COMMAND`，开发上下文核对 `ORCA_DEV_REPO_ROOT`；Linux 非托管环境使用指南规定的 `orca-ide` 入口，避免误调用同名屏幕阅读器。不要套用 Herdr 的环境变量要求，也不把环境值交给 eval。固定入口后读取本机 `--help`、`skills get orca-cli`；需要受监督编排时再读 `skills get orchestration` 及当前分支参考。核对版本、来源、执行主机与目标 runtime 能力，不把上游 main 当作本机可用接口。
 
-宿主技能列表是否已刷新不替代读取真实项目文件；安装成功也不证明 CLI 或远端可用。入口、权限或目标能力失败时保留原错误，只阻塞此方式，不静默切换生产/开发版或本地/远端入口，不自行安装升级或重启服务。
+宿主技能列表是否已刷新不替代读取真实项目文件；安装成功也不证明 CLI 或远端可用。入口、权限、服务或目标能力失败时保留原错误，停止此工具操作并由共享合同判断回退当前智能体或阻塞强制的 Orca 阶段；不静默切换生产/开发版或本地/远端入口，不自行安装升级或重启服务。已派发而结果不明时先恢复核验，不直接重复执行。
 
 1. 确认用户项目、当前工作区以及当前 Lead 的责任。需要保留 Lead 连续推进时使用受监督任务方式；完整 handoff 会转移责任，只有用户明确选择该交接时才使用。
 2. 沿当前工具提供的任务、工作区、会话和消息接口建立目标。Orca 管理的 worktree 由 Orca 操作；允许工具支持的 folder workspace，不凭空要求所有项目必须有 Git worktree。工具和模型沿用户选择及当前指南确定，不固化 agent/runner 清单；保留用户焦点，不复用 Herdr 参数。
@@ -27,7 +27,7 @@
 6. 状态不明时重读原任务、回执和收件事实；只有本版支持同请求重放且原参数可核对时才恢复原操作。旧句柄失效时重新发现目标，不同时向旧、新目标重复发送。idle、无输出、断线或清单缺项均不能证明任务结束。
 7. 接收、取消、保留或释放工作区按当前指南及真实授权操作。结算后复用、保留或释放资源，运行中取消使用精确目标的原生停止流程；不以关闭终端、全局 reset 或删除工作区代替结算。完成消息不等于旧写入者已经停止。
 
-核对返回、实际候选和写入停止事实后，由 Lead 按原验收更新 Evidence，并按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 接续原 Goal。工具或所需能力不可用时准确报告当前阻塞。
+核对返回、实际候选和写入停止事实后，由 Lead 按原验收更新 Evidence，并按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 接续原 Goal。准确报告工具不可用的原因与实际回退或阻塞结果。
 
 ## 聚焦交接与历史
 

package/template/references/coordination/project-facts.schema.json

@@ -102,6 +102,7 @@
           "then": {
             "properties": {
               "fallback": {
+                "type": "array",
                 "maxItems": 0
               }
             }

package/template/workflows/specdev/specdev-i-init-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specdev-i-init-setup
-description: "发现项目事实与必要偏好；仅在明确请求时建立当前工程 docs 基线，不预造业务状态骨架。"
+description: "发现项目事实，选择或复用可选协作方式并复用用户指定目录中的对应 Skill；仅在明确请求时建立当前工程 docs 基线。"
 metadata:
   speculo-kind: work-skill
   speculo-id: specdev/init-setup
@@ -16,9 +16,10 @@ metadata:
 
 1. 只读探测包管理、workspace、构建/测试/类型/lint/CI、默认父分支、实际 worktree 与项目指令；定位真实入口和共享高冲突资源。未知验证命令保持未知，不凭框架名称编造。
 2. 区分可用、未安装、未配置、未授权、不适用并注明依据。复用用户语言、工具、产物数量及已有配置；只问无法从仓库得到且实际影响当前任务的偏好。探测不自动安装依赖、发布或创建虚假 change。
-3. 实际需要写入偏好或工具配置时读取 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/first-setup.md</Path>。已有真实 GitHub/验证配置继续使用其 schema，不删除未知独有字段。无需求不创建 config、tracking、domain-layout、空知识目录、全局 status 或 change status。
-4. 仅明确要求工程文档基线/全面理解代码时，直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path> 的六步与覆盖表。最小 docs README/architecture 或已有负责正文导航，说明 HEAD/未提交或非 Git 范围、覆盖/未知/排除与实际验证；不改永久知识、不推进 docs-sync 基线。
-5. 回读本次实际写入，报告已确认事实、必要偏好来源、验证命令/退出码和未知。只读调用无文件；有 change 的结果写回原 README/Evidence，不登记 Work 调用镜像。
+3. 检查已有项目编排选择；未配置时提供 **Herdr / Orca / CLI / 暂时都不要** 四选一，已有有效选择则展示并复用，用户要求更改时才重选。Herdr/Orca 再由用户选择项目 `.agents/skills/` 或 `.claude/skills/` 入口目录；已明确的同范围选择直接复用。按 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/first-setup.md</Path> 保存项目级偏好并检查本地入口；缺失时引导通过 Speculo 安装器的 SKILLS-HUB 选择安装，当前按允许的 fallback 继续。只读、plan 或选择未完成时不写配置、不安装；普通 Work 不触发此问答。
+4. 实际需要其他工具配置时继续使用上述参考。已有真实 GitHub/验证配置继续使用其 schema，不删除未知独有字段。无需求不创建 config、tracking、domain-layout、空知识目录、全局 status 或 change status。
+5. 仅明确要求工程文档基线/全面理解代码时，直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path> 的六步与覆盖表。最小 docs README/architecture 或已有负责正文导航，说明 HEAD/未提交或非 Git 范围、覆盖/未知/排除与实际验证；不改永久知识、不推进 docs-sync 基线。
+6. 回读本次实际写入，报告已确认事实、必要偏好来源、验证命令/退出码和未知。只读调用无文件；有 change 的结果写回原 README/Evidence，不登记 Work 调用镜像。
 
 ## 停止与保全
 
@@ -26,6 +27,6 @@ metadata:
 
 只有确实创建 worktree 时核对 `specdev-worktree/` 的忽略项与 owner：已安装的 CLI-managed 忽略项交 CLI 修复；直接模式按项目 owner 的真实授权维护，不能因没有 CLI 阻塞其他初始化事实发现。
 
-## 可选项目编排选择
+## 完成标准
 
-只有用户要求持久化编排偏好时，依据 <Path>{roots.references}/coordination/project-facts.schema.json</Path> 写入 <Path>{roots.state}/coordination/project.json</Path>，先读 <Path>{roots.references}/coordination/coordination-contract.md</Path>。未明确指定时按当前宿主正常执行（mode: lead），App、CLI 等均可；不探测、安装或要求外部工具，选择不是授权凭证。只读调用不生成配置。
+项目事实与未知有依据；本次选择已保存并回读或已有选择已复用，未完成的选择/写入据实报告。分别报告 Skill 已复用或未安装，以及工具可用、不可用或未检查。协作编排是可选能力：初始化生成的外部方式偏好允许不可用时回到当前智能体（mode: lead），Skill 缺失不阻塞独立的基础初始化，不得报告安装成功。实际运行与回退遵守 <Path>{roots.references}/coordination/coordination-contract.md</Path>，配置本身不授予提交、发布等其他动作权限。

package/template/workflows/specdev/specdev-i-init-setup/references/first-setup.md

@@ -1,6 +1,35 @@
 # 必要偏好与真实工具配置
 
-只有当前任务确需持久化偏好或工具设置时读取；不是缺少文件即补全骨架。
+初始化处理项目协作选择，或当前任务确需其他持久化偏好/工具设置时读取；不是缺少文件即补全骨架。
+
+## 项目协作选择
+
+先读 <Path>{roots.references}/coordination/coordination-contract.md</Path> 与 <Path>{roots.references}/coordination/project-facts.schema.json</Path>。本 Work 拥有此次 <Path>{roots.state}/coordination/project.json</Path> 偏好写入；已存在时先验证，未知 schema、冲突或无效内容保留原件，只停止相关配置写入。只读和 plan 仅展示选择及预期差异，不执行下列写入。
+
+1. 已有有效配置时展示 defaults 与适用的 Work/阶段覆盖，直接复用；不因服务当前不可用重问或改写偏好。未配置时说明“这是项目默认偏好，外部方式不可用时由当前智能体继续”，让用户在 Herdr、Orca、CLI、暂时都不要中选择。当前会话已有同范围明确选择时复用；取消或尚未回答不视为 lead，不产生文件。
+2. 选择 Herdr/Orca 后明确项目根，让用户选择 `.agents/skills/` 或 `.claude/skills/`，并说明将读取该位置已安装的完整 Skill，缺失时通过 Speculo 安装器安装。同范围已明确的目录直接复用；不按宿主名称替用户决定。入口位置为所选目录下的 `herdr/` 或 `orca/`，将完整项目相对入口写入 defaults.guide。选择 CLI 协作方式不需要这两个 Skill；具体工具、模型、交互方式只复用真实已知选择，缺失时在实际使用前确定。
+3. 外部方式保存为 `mode: herdr | orca | cli`、`selection: preferred`、`fallback: [lead]`；“暂时都不要”保存为 `mode: lead`，以后不重复询问。首次创建使用 schema_version 1 和空 rules；用户主动更改只替换 defaults，保留所有 rules 及有效的其他配置。旧 defaults 中属于前一工具的 tool/model/guide 不带到新方式；同方式已知的有效工具信息保留。本次选择不是强制外部工具要求，不擅自把既有 required 或 Work/阶段安排改成可回退。
+4. 配置候选经 schema 验证后，写前重读确认原内容未漂移，检查根、owner 与重叠事务/锁，再在同目录临时文件中形成完整候选并原子替换，最后回读验证。首次创建若目标已出现、任何路径含符号链接或发生漂移则停止相关写入，保留已有内容。配置失败不继续依赖该配置的接入；独立事实发现继续。
+5. 配置成功后，按本次方式读取 <Path>{roots.references}/coordination/modes/herdr.md</Path> 或 <Path>{roots.references}/coordination/modes/orca.md</Path> 的本地入口分支。已有完整 Skill 则读取复用；缺失时保留偏好与目标，引导用户重新运行 `speculo init`，在 SKILLS-HUB 勾选对应 `automation/herdr` 或 `automation/orca` 并选择位置。Work 不下载、不另行复制技能包、不写 CLI 归属清单。当前任务按 fallback 继续；初始化不要求服务已启动，不进入派遣或服务控制。
+
+例如用户选择 Herdr 并指定 `.claude/skills/`，首次写入：
+
+```json
+{
+  "schema_version": 1,
+  "defaults": {
+    "mode": "herdr",
+    "selection": "preferred",
+    "guide": ".claude/skills/herdr/SKILL.md",
+    "fallback": ["lead"]
+  },
+  "rules": []
+}
+```
+
+guide 是用户选择的读取/安装位置，不是“已安装”凭证，也不是机器绝对路径。只更改 defaults 不移动或删除旧 Skill；CLI 安装的包由 <Path>{roots.state}/hub-skills.json</Path> 跟踪；用户手工安装的同名包保持用户归属。最终分别回报配置保存/复用、Skill 结果、运行能力未检查或实际检查结果；缺失或冲突时给出原目标与安装器操作步骤，不制造 change 或独立回执。
+
+## 其他必要偏好
 
 语言、用户工具和明确产物数量复用当次请求或现有项目说明。实现并发、worktree、集成尝试上限只在原 Goal/Implementation Plan 真正启用时明确，由计划 `## Execution Policy Source` 记录实际来源；默认 current 单写入者。Lead 自己实现计入实现并发，只读协作者不设新数字上限。UI 缺省 3、配置 2–4、用户明确数量覆盖上限；一次 override 留当前设计包，不改全局偏好。