@namewta/speculo 1.0.19 → 1.0.20

package/template/skills/source-code-zip/SKILL.md

@@ -3,16 +3,52 @@ name: source-code-zip
 description: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
 ---
 
-# source-code-zip
+# Source Code ZIP
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+先确认 node 可用，只有 node 不存在时才回退 nodejs。使用 scripts/zip_source_code.js；无第三方依赖，不安装 npm/Python/zip 工具。
 
-## Scope
+## 标准工作流
 
-- Trigger: Create a requested source ZIP using the bundled Node script and its ignore rules; do not install dependencies.
-- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
-- Do not infer missing scope, credentials, target, or authorization.
+1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
+2. 先确认 `node --version` 能正常执行。
+3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
+4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
+5. 正式创建 ZIP。
+6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
+7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
 
-## Stop
+推荐预览：
 
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.
+```bash
+node scripts/zip_source_code.js "/path/to/project" --dry-run
+```
+
+查看每个项目被排除的原因：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project" \
+  --dry-run \
+  --verbose
+```
+
+正式创建：
+
+```bash
+node scripts/zip_source_code.js "/path/to/project"
+```
+
+默认输出在源目录旁边：
+
+```text
+<目录名>.code.zip
+```
+
+例如：
+
+```text
+源目录：/work/my-app
+输出：  /work/my-app.code.zip
+```
+
+
+需要自定义过滤、额外文件、输出位置、覆盖、压缩或排障时读取 [参数与行为参考](references/cli-reference.md)。执行前核对目标目录和忽略策略，交付 ZIP 路径、清单/统计及未打包项。

package/template/skills/source-code-zip/references/{entry-procedure.md → cli-reference.md}

@@ -74,49 +74,6 @@ chmod +x scripts/zip_source_code.js
 ./scripts/zip_source_code.js "/path/to/project"
 ```
 
-## 标准工作流
-
-1. 确认用户提供的是目录路径，不是单个文件；路径含空格时必须加引号。
-2. 先确认 `node --version` 能正常执行。
-3. 默认先运行一次 `--dry-run`；目录较大、规则刚修改或可能包含敏感信息时，同时添加 `--verbose`。
-4. 检查预览结果，确认 `.env`、YAML、依赖目录、构建产物、归档文件和密钥没有被纳入。
-5. 正式创建 ZIP。
-6. 报告 ZIP 的绝对路径、纳入文件数、输入总大小和生成结果。
-7. 除非用户明确理解风险并提出要求，不得使用 `--no-default-ignore`。
-
-推荐预览：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" --dry-run
-```
-
-查看每个项目被排除的原因：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project" \
-  --dry-run \
-  --verbose
-```
-
-正式创建：
-
-```bash
-node scripts/zip_source_code.js "/path/to/project"
-```
-
-默认输出在源目录旁边：
-
-```text
-<目录名>.code.zip
-```
-
-例如：
-
-```text
-源目录：/work/my-app
-输出：  /work/my-app.code.zip
-```
-
 ## 默认过滤行为
 
 脚本采用两层过滤：

package/template/skills/upstream-fork-sync/SKILL.md

@@ -4,16 +4,79 @@ description: Assess a requested fork/upstream checkpoint and produce reproducibl
 metadata: {"speculo-id": "upstream-fork-sync", "speculo-kind": "skill"}
 ---
 
-# upstream-fork-sync
+# Upstream Fork Sync
 
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
+以**检查点**为主导词。每个仓库始终分开记录：本次观测到的 upstream tip、可选本地 mirror tip，以及已经由产品分支历史证明完成集成的 upstream checkpoint。Fetch 或 mirror 变化不能推进集成 checkpoint。
 
-## Scope
+## 1. 解析上下文
 
-- Trigger: Assess a requested fork/upstream checkpoint and produce reproducible diff, conflict, and customization-risk evidence.
-- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
-- Do not infer missing scope, credentials, target, or authorization.
+1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base` 和所有 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
+2. 读取项目 `AGENTS.md` 及其作用域内规则。项目存在工程规范时读取适用入口。
+3. 将本 Skill 的唯一持久化根解析为 `<Path>{roots.state}/skills/upstream-fork-sync/</Path>`。独立运行只写该根；不得创建 workflow change 或 command 报告。
+4. 读取 [Repository contract](references/repository-contract.md)，确定仓库、refs、网络刷新和副作用边界。
 
-## Stop
+完成标准：项目根、Skill state 根、目标仓库集合和本次是否允许 fetch 都只有一个解释。
 
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.
+## 2. 建立稳定配置
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path>`。不存在时，只读发现 Git 仓库、remotes、默认产品分支和 upstream tracking refs，按 [Repository contract](references/repository-contract.md) 创建 schema v1 配置；无法从 Git 事实唯一判断的字段一次性询问用户。配置已存在时验证，不静默改写。
+
+读取 `<Path>{roots.state}/skills/upstream-fork-sync/customization-map.md</Path>`。不存在时创建最小稳定清单，记录 fork 必须长期保留的产品不变量和审查热点；无法从项目文档或代码证明的业务约束标记为待确认。该文件不接收运行 SHA、dirty paths、冲突或本次结论。
+
+完成标准：每个 repository id 唯一，所有项目路径和 refs 可解析，稳定配置与动态运行事实分离。
+
+## 3. 创建评估 change
+
+读取 [State schema](references/state-schema.md) 和 [Report contract](references/report-contract.md)，从用户主题生成小写 ASCII kebab-case topic，然后运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> assess \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --topic <topic>
+```
+
+- 默认离线使用本地 refs；只有用户明确要求刷新网络 refs 时添加 `--fetch`。
+- 只需预览完整冻结快照时添加 `--dry-run`，此分支不写 state 或 change。
+- 正常运行创建 `<Path>{roots.state}/skills/upstream-fork-sync/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。
+
+完成标准：脚本退出 0，change 的 state 与两份报告完整发布，根 `state.json` 只在 change 发布成功后更新。
+
+## 4. 深化风险结论
+
+逐仓库检查报告中的 Git 确认冲突、自动合并重叠和定制风险路径。对每条高风险路径使用报告冻结的 SHA 执行精确 `git diff <base>..<target> -- <path>`，再与 `customization-map.md` 的稳定不变量映射。
+
+只把路径级证据支持的语义结论补入本 change 的报告。保持 Git 冲突、自动合并重叠、定制合同风险和 dirty-worktree 重叠为四个类别；零文本冲突不得表述为集成安全。
+
+完成标准：所有冲突和定制热点都有结论或明确未验证项，报告中的命令可以从冻结 SHA 复现。
+
+## 5. 返回后续选择
+
+返回 change 路径、仓库 checkpoint、观测 upstream SHA、风险摘要和未验证项。列出适合继续处理的已安装 Work，但不自动创建 workflow change、不调用 Work、不 merge、不 commit、不 push；后续路线由用户选择。
+
+完成标准：本次 Skill 在评估 change 完整后停止，用户能用冻结产物自行选择下一 Work。
+
+## 6. 记录外部集成
+
+只有其他 Work 已完成集成且用户要求更新 checkpoint 时进入此分支。读取目标 change state，并运行：
+
+```bash
+node <Path>{roots.skills}/upstream-fork-sync/scripts/upstream-sync.mjs</Path> record-integration \
+  --root . \
+  --state-root <Path>{roots.state}/skills/upstream-fork-sync</Path> \
+  --repository-map <Path>{roots.state}/skills/upstream-fork-sync/repository-map.json</Path> \
+  --change <change> \
+  --repository <repository-id> \
+  --merge-commit <full-sha> \
+  --upstream-sha <full-sha> \
+  --verification '<command>: exit 0'
+```
+
+该入口只在 merge commit 可从产品 ref 到达、目标 upstream SHA 是其精确非第一父节点且匹配 change 冻结目标时更新状态；它不执行集成。
+
+完成标准：change state 和根 checkpoint 都已原子重读，实际 Git 历史与记录一致。
+
+## 停止条件
+
+目标 ref 缺失、保存的 checkpoint 不在产品历史、checkpoint 不在当前 upstream 历史、存在多个 merge-base、配置越界或状态 schema 非法时，停止且不移动 refs、不发布部分 change、不推进 checkpoint。返回准确 repository id、路径、refs 与 SHAs。

package/template/skills/{writing-great-skills → writing-for-agents}/GLOSSARY.md

@@ -1,6 +1,6 @@
 # 术语表 — 构建优秀技能
 
-关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-great-skills`](SKILL.md) 的公开参考。
+关于什么造就优秀技能的领域模型。技能的存在是为了从随机系统中驯服确定性；根本美德是 **Predictability**（可预测性），以下每个术语都是调节它的一根杠杆。这是 [`writing-for-agents`](SKILL.md) 的公开参考。
 
 术语按轴分组：**Invocation**（调用，技能如何被触达）、**Information Hierarchy**（信息层级，其内容如何排列）、**Steering**（引导，Agent 的运行时行为如何被塑造）和 **Pruning**（修剪，如何保持精炼）。每个**失败模式**都紧邻治愈它的杠杆，标记为 _失败模式_。
 

package/template/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: writing-for-agents
+description: Review or author agent instructions, Skills, AGENTS, commands and workflow contracts when explicitly requested.
+disable-model-invocation: true
+metadata: {"speculo-id": "writing-for-agents", "speculo-kind": "skill", "speculo-invocation": "user-only"}
+---
+
+# Writing for Agents
+
+对明确要求的文档编写/重构使用本能力；不因仓库存在指令文件而自动审计。先读 [保真合同](references/document-contract.md)，确定真实源、调用方、owner、输出与恢复边界。
+
+1. 从当前任务入口追踪相关调用和生成器，列出现存能力、数量、工具、权限、验证及失败语义。不要默认整读仓库。
+2. 明确触发分支和近邻职责；入口保留每次必读步骤，只有分支规则、示例、flags 与模板下沉。需要审查结构与冗余时读 [编写原则](references/authoring-principles.md)，术语按需查 [GLOSSARY](GLOSSARY.md)。
+3. 按单一规则 owner 合并重复；删除无效/过期内容，保留不可丢失的证据、研究、许可与必要元数据。新增或改变的行为单列。
+4. 修订调用方与生成器，测试正常、近邻不触发、缺失输入、失败与恢复；语法通过不代表实际宿主行为。
+5. 交付实际差异、全源字符统计、验证和未验证项。没有实际用量证据不声称 token 或额度节省。
+
+## 宿主适配
+
+Claude 的显式调用使用 disable-model-invocation；Codex 使用 agents/openai.yaml 中 policy.allow_implicit_invocation=false。metadata 仅描述策略，不授予权限。Speculo 的分发路径不等于宿主原生发现目录，安装/启用需由对应宿主方式完成；不要复制到系统或插件缓存。
+
+AGENTS 放项目独有事实与作用域约束，工具可检验的规则交机械检查；CLAUDE 需要加载同层手册时使用 @AGENTS.md，保护用户现有内容。

package/template/skills/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/skills/{writing-great-skills/references/entry-procedure.md → writing-for-agents/references/authoring-principles.md}

@@ -1,4 +1,4 @@
-# Entry procedure
+# 编写原则
 
 一个 skill 的存在是为了从随机系统中提取确定性。**可预测性** —— 即 agent 每次运行时采取相同的*流程*，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。
 
@@ -6,14 +6,7 @@
 
 ## 调用方式
 
-两种选择，付出不同的代价：
-
-- **模型调用** skill 保留 **description**，因此 agent 可以自主触发它，*并且*其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生**上下文负载** —— description 每轮都留在窗口里。实现机制：省略 `disable-model-invocation`，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
-- **用户调用** skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗**认知负载**：*你*是必须记住它存在的索引。实现机制：设置 `disable-model-invocation: true`；`description` 变为面向人类的 —— 一句摘要，去掉触发列表。
-
-只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。
-
-当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个**路由 skill** 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。
+触发策略按宿主适配。模型调用时描述覆盖实际分支，显式调用时给出用途；宿主规则与元数据不能混淆。入口中的适配合同是唯一规则源，不宣称零上下文负载。
 
 ## 编写 description
 

package/template/workflows/ops/common/tests/test_ops.mjs

@@ -175,16 +175,13 @@ test("lock is not autobroken", () => {
   });
   rmSync(d, { recursive: true, force: true });
 });
-test("symlink rejected", () => {
+test("symlink rejected", (t) => {
   const d = mkdtempSync(join(tmpdir(), "ops-link-"));
+  t.after(() => rmSync(d, { recursive: true, force: true }));
   mkdirSync(join(d, "real"));
-  try { symlinkSync(join(d, "real"), join(d, "link"), "dir"); }
-  catch (e) {
-    if (process.platform === "win32") { rmSync(d, { recursive: true, force: true }); return; }
-    throw e;
-  }
+  symlinkSync(join(d, "real"), join(d, "link"), process.platform === "win32" ? "junction" : "dir");
   assert.throws(() => atomicWrite(join(d, "link", "a.txt"), "x"), OpsError);
-  rmSync(d, { recursive: true, force: true });
+  assert.equal(existsSync(join(d, "real", "a.txt")), false);
 });
 test("file permissions", () => {
   const d = mkdtempSync(join(tmpdir(), "ops-perm-"));
@@ -994,7 +991,7 @@ test("new controllers keep secrets out of default documentation", () => runFx((f
   }
   assert.match(readFileSync(join(local,"OPERATIONS.md"),"utf8"), /secret_ref:.*app-auth@1/);
   assert.ok(readFileSync(join(remote,"env","app.env"),"utf8").includes(PASSWORD));
-  assert.equal(plan.operations.find((o) => o.path?.endsWith("env/app.env")).mode, 0o600);
+  assert.equal(plan.operations.find((o) => o.path === join(remote, "env", "app.env")).mode, 0o600);
   if (process.platform !== "win32") assert.equal(statSync(join(remote,"env","app.env")).mode & 0o777, 0o600);
   assert.equal(readJson(join(local,"docs-receipt.json")).status, "both-sides-verified");
 }));

package/template/workflows/ops/common/tests/test_ops_bootstrap.mjs

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import test from "node:test";
 import { createHash } from "node:crypto";
@@ -18,6 +18,7 @@ import * as model from "../tools/opslib/model.mjs";
 const toolsDir = join(dirname(fileURLToPath(import.meta.url)), "../tools");
 const scriptPath = join(toolsDir, "bootstrap-volta.sh");
 const ACK = "I-APPROVE-THIS-BOOTSTRAP";
+const linuxExecution = { skip: process.platform !== "linux" && "Requires Linux /bin/sh and a Linux Node executable; SSH protocol contracts run on every platform" };
 
 function sha256(p) {
   return createHash("sha256").update(readFileSync(p)).digest("hex");
@@ -58,13 +59,14 @@ function pinFor(archives, arch = "linux-x64") {
   return { ...base, archives: { ...base.archives, [arch]: slot } };
 }
 
-function mockTransport({ probeJson = null } = {}) {
+function mockTransport({ probeJson = null, agentJson = null, applyJson = null } = {}) {
   const prev = transport.transportHooks.spawnSync;
   const log = [];
   transport.transportHooks.spawnSync = (cmd, args, kw) => {
     log.push({ cmd, args: [...args], encoding: kw.encoding, inputIsBuffer: Buffer.isBuffer(kw.input) });
     const last = args[args.length - 1];
     if (cmd === "scp") {
+      if (applyJson) return { status: 0, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
       const local = args[args.length - 2];
       const spec = args[args.length - 1];
       const remotePath = spec.slice(spec.indexOf(":") + 1);
@@ -80,11 +82,13 @@ function mockTransport({ probeJson = null } = {}) {
         return { status: 0, stdout: Buffer.from(JSON.stringify(probeJson) + "\n"), stderr: Buffer.alloc(0) };
       }
       if (String(last).includes("--input-type=module")) {
+        if (agentJson) return { status: 0, stdout: Buffer.from(JSON.stringify({ ok: true, result: agentJson }) + "\n"), stderr: Buffer.alloc(0) };
         const parts = splitRemote(last);
         return spawnSync(parts[0], parts.slice(1), {
           input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
         });
       }
+      if (applyJson) return { status: 0, stdout: Buffer.from(String(last).includes("--apply") ? JSON.stringify(applyJson) + "\n" : ""), stderr: Buffer.alloc(0) };
       const parts = splitRemote(last);
       return spawnSync(parts[0], parts.slice(1), {
         input: kw.input, encoding: "buffer", timeout: kw.timeout, maxBuffer: kw.maxBuffer,
@@ -182,7 +186,20 @@ test("scp uses the same host-key contract", () => {
   } finally { transport.transportHooks.spawnSync = prev; rmSync(d, { recursive: true, force: true }); }
 });
 
-test("bootstrap-volta apply installs wrapper and does not touch profile", () => {
+test("scp rejects controller paths and unsafe Linux paths before spawning", (t) => {
+  const d = mkdtempSync(join(tmpdir(), "ops-scp-path-"));
+  t.after(() => rmSync(d, { recursive: true, force: true }));
+  const kh = join(d, "known_hosts"), local = join(d, "archive.tar.gz");
+  writeFileSync(kh, "fixture pinned key\n"); writeFileSync(local, "reviewed archive");
+  const prev = transport.transportHooks.spawnSync;
+  t.after(() => { transport.transportHooks.spawnSync = prev; });
+  transport.transportHooks.spawnSync = () => { assert.fail("invalid paths must not reach scp"); };
+  for (const path of ["C:\\server\\archive.tar.gz", "C:/server/archive.tar.gz", "\\\\server\\share\\archive.tar.gz", "/srv/ops\\archive.tar.gz", "relative.tar.gz", "/srv/../archive.tar.gz", "/srv/space name.tar.gz", "/srv/nul\0.tar.gz"]) {
+    assert.throws(() => transport.posixSend({ hostname: "host.invalid", username: "ops", known_hosts: kh }, local, path), /remote scp path/);
+  }
+});
+
+test("bootstrap-volta apply installs wrapper and does not touch profile", linuxExecution, () => {
   const d = mkdtempSync(join(tmpdir(), "ops-vol-"));
   const home = join(d, "home");
   mkdirSync(home);
@@ -205,28 +222,33 @@ test("bootstrap-volta apply installs wrapper and does not touch profile", () =>
   } finally { rmSync(d, { recursive: true, force: true }); }
 });
 
-test("bootstrap-volta apply without ack blocked", () => {
+test("bootstrap-volta apply without ack blocked", linuxExecution, () => {
   const d = mkdtempSync(join(tmpdir(), "ops-ack-"));
   const archives = makeArchives(d);
   const p = spawnSync("/bin/sh", [scriptPath, "--apply", archives.voltaTar, archives.voltaSha, archives.nodeTar, archives.nodeSha, join(d, "volta"), "24.21.0", "nope"], { encoding: "utf8" });
-  assert.notEqual(p.status, 0);
+  assert.equal(p.error, undefined);
+  assert.equal(p.status, 2);
+  assert.match(p.stderr, /acknowledgement/);
   rmSync(d, { recursive: true, force: true });
 });
 
-test("bootstrap-volta sha mismatch blocked", () => {
+test("bootstrap-volta sha mismatch blocked", linuxExecution, () => {
   const d = mkdtempSync(join(tmpdir(), "ops-sha-"));
   const archives = makeArchives(d);
   const p = spawnSync("/bin/sh", [scriptPath, "--apply", archives.voltaTar, "0".repeat(64), archives.nodeTar, archives.nodeSha, join(d, "volta"), "24.21.0", ACK], { encoding: "utf8" });
-  assert.notEqual(p.status, 0);
+  assert.equal(p.error, undefined);
+  assert.equal(p.status, 2);
+  assert.match(p.stderr, /installer changed after review/);
   assert.ok(!existsSync(join(d, "volta", "bin", "ops-node")));
   rmSync(d, { recursive: true, force: true });
 });
 
-function cliFixture() {
+function cliFixture({ executeLinux = false } = {}) {
   const tmp = mkdtempSync(join(tmpdir(), "ops-bootcli-"));
   const state = join(tmp, "controller");
-  const target = join(tmp, "server");
-  mkdirSync(target, { recursive: true });
+  // A simulated Linux SSH target is not a path on the controller filesystem.
+  const target = executeLinux ? join(tmp, "server") : "/srv/speculo-bootstrap-test";
+  if (executeLinux) mkdirSync(target, { recursive: true });
   const kh = join(tmp, "known_hosts");
   writeFileSync(kh, "fixture pinned key\n");
   const prevProbe = cliHooks.probeLocal;
@@ -251,6 +273,39 @@ const missingProbe = {
   node_path: null, node_version: null, node_usable: false, profile_has_volta: false,
 };
 
+test("Linux SSH bootstrap and enrollment preserve remote paths on every controller platform", () => {
+  const fx = cliFixture();
+  const connectionNode = posix.join(fx.target, "_host/toolchains/ops/volta/bin/ops-node");
+  const mock = mockTransport({ probeJson: missingProbe, applyJson: { status: "installed", connection_node: connectionNode, profile_unchanged: true } });
+  try {
+    const host = sshHost({ root: fx.target, kh: fx.kh, node: "node" });
+    const conn = writeConn(fx.tmp, host);
+    const r = captureMain(["bootstrap-node", "--state", fx.state, "--host-id", host.host_id, "--connection-file", conn, "--apply", "--account", "ops", "--host-root", fx.target, "--ack", ACK,
+      "--volta-archive", fx.archives.voltaTar, "--volta-sha256", fx.archives.voltaSha, "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha]);
+    assert.equal(r.code, 0, r.stderr);
+    const boot = JSON.parse(r.stdout), pins = pinFor(fx.archives).archives["linux-x64"];
+    const paths = [pins.volta.filename, pins.node.filename].map(name => posix.join(fx.target, "_host/installers", name));
+    assert.deepEqual(mock.log.filter(e => e.cmd === "scp").map(e => e.args.at(-1)), paths.map(p => "ops@host.invalid:" + p));
+    const applyArgs = splitRemote(mock.log.find(e => e.cmd === "ssh" && e.args.at(-1).includes("--apply")).args.at(-1));
+    assert.deepEqual(applyArgs.slice(applyArgs.indexOf("--apply") + 1), [paths[0], fx.archives.voltaSha, paths[1], fx.archives.nodeSha, posix.dirname(posix.dirname(connectionNode)), fx.archives.nodeVersion, ACK]);
+    assert.equal(JSON.parse(readFileSync(boot.receipt, "utf8")).connection_node, connectionNode);
+    assert.deepEqual(Object.keys(model.load(fx.state).hosts), []);
+    mock.restore();
+    host.connection.node = connectionNode;
+    const enrollFile = join(fx.tmp, "register.json"); writeFileSync(enrollFile, JSON.stringify({ hosts: [host], projects: [] }));
+    const inventory = { identity: "a".repeat(64), platform: "linux", tools: { node: { path: connectionNode, version: "v24.21.0" } } };
+    const enrolledMock = mockTransport({ probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: connectionNode }, node_path: connectionNode, node_usable: true }, agentJson: inventory });
+    try {
+      const enrolled = captureMain(["--state", fx.state, "enroll", "--file", enrollFile]);
+      assert.equal(enrolled.code, 0, enrolled.stderr);
+      assert.equal(model.load(fx.state).hosts[host.host_id].connection.node, connectionNode);
+      const snapshot = JSON.parse(enrolled.stdout).hosts[0].snapshot;
+      assert.deepEqual(JSON.parse(readFileSync(snapshot, "utf8")), inventory);
+      assert.equal(enrolledMock.log.filter(e => e.args.at(-1).includes("--input-type=module")).length, 2);
+    } finally { enrolledMock.restore(); }
+  } finally { mock.restore(); fx.cleanup(); }
+});
+
 test("discover probe without node returns node-missing", () => {
   const fx = cliFixture();
   const mock = mockTransport({ probeJson: missingProbe });
@@ -313,6 +368,7 @@ test("bootstrap-node sha mismatch blocked", () => {
       "--node-archive", fx.archives.nodeTar, "--node-sha256", fx.archives.nodeSha,
     ]);
     assert.equal(r.code, 2);
+    assert.match(r.stderr, /sha256 does not match the reviewed pin/i);
     assert.ok(!mock.log.some((e) => String(e.args.at(-1) || "").includes("--apply")));
   } finally { mock.restore(); fx.cleanup(); }
 });
@@ -362,8 +418,8 @@ test("bootstrap-node skips when node exists", () => {
   } finally { mock.restore(); fx.cleanup(); }
 });
 
-test("bootstrap-node apply then enroll writes inventory and status", () => {
-  const fx = cliFixture();
+test("bootstrap-node apply then enroll writes inventory and status", linuxExecution, () => {
+  const fx = cliFixture({ executeLinux: true });
   const home = join(fx.tmp, "home");
   mkdirSync(home);
   writeFileSync(join(home, ".bashrc"), "keep-me\n");
@@ -435,10 +491,11 @@ test("enroll without node blocked", () => {
 test("probe --connection-file still does not imply register", () => {
   const fx = cliFixture();
   const mock = mockTransport({
-    probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: process.execPath }, node_path: process.execPath, node_usable: true },
+    probeJson: { ...missingProbe, tools: { ...missingProbe.tools, node: "/usr/bin/node" }, node_path: "/usr/bin/node", node_usable: true },
+    agentJson: { identity: "a".repeat(64), platform: "linux" },
   });
   try {
-    const host = sshHost({ root: fx.target, kh: fx.kh, node: process.execPath, identity: "discover" });
+    const host = sshHost({ root: fx.target, kh: fx.kh, identity: "discover" });
     const conn = writeConn(fx.tmp, host);
     const r = captureMain(["probe", "--connection-file", conn]);
     assert.equal(r.code, 0, r.stderr);

package/template/workflows/ops/common/tests/test_ops_workspace.mjs

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
 import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, symlinkSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, posix } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { digest, emptyStatus, now, writeJson } from "../tools/opslib/core.mjs";
@@ -18,7 +18,7 @@ function fixture(t) {
   t.after(() => rmSync(root, { recursive: true, force: true }));
   const state = join(root, "state"); mkdirSync(state);
   const s = emptyStatus(); s.controller = { controller_id: "controller-a", state_root: state, created_at: now() };
-  for (const id of ["node-a", "node-b"]) s.hosts[id] = { host_id: id, display_name: id, platform: "linux", transport: "local", root: join(root, id), identity: "a".repeat(64), connection: {} };
+  for (const id of ["node-a", "node-b"]) s.hosts[id] = { host_id: id, display_name: id, platform: process.platform === "win32" ? "windows" : "linux", transport: "local", root: join(root, id), identity: "a".repeat(64), connection: {} };
   for (const id of ["app-a", "app-b"]) s.projects[id] = { project_id: id, display_name: id, kind: "app", service_type: null, source: { type: "local", location: join(root, "source"), revision: "v1" } };
   writeJson(join(state, "status.json"), s);
   const save = () => writeJson(join(state, "status.json"), s);
@@ -32,7 +32,13 @@ function request(id = "task-one") {
 function inventory(h) {
   return { identity: h.identity, platform: "linux", tools: { node: { version: "v22.22.3" } },
     snapshots: { [h.root]: { kind: "directory" } }, diagnostics: { disks: { [h.root]: { free: 4 * 1024 ** 3 } }, memory: { MemAvailable: 1024 ** 3 } },
-    docker_control: { status: "observed", endpoint: "unix:///var/run/docker.sock", data_root: join(h.root, "_runtime/docker"), compose_version: "2.30.0" } };
+    docker_control: { status: "observed", endpoint: "unix:///var/run/docker.sock", data_root: posix.join(h.root, "_runtime/docker"), compose_version: "2.30.0" } };
+}
+function linuxServer(f) {
+  return Object.assign(f.s.hosts["node-a"], { platform: "linux", root: "/srv/speculo-test/node-a" });
+}
+function directoryLink(target, path) {
+  symlinkSync(target, path, process.platform === "win32" ? "junction" : "dir");
 }
 function adapterFor(f, options = {}) {
   const calls = { compile: 0, approve: 0, apply: 0 };
@@ -76,7 +82,7 @@ test("explicit layer routing distinguishes controller, access, server, project a
 test("workspace rejects guessed roots, traversal, symlinks, duplicate JSON keys and orphan deployments", (t) => {
   const f = fixture(t);
   for (const path of [".", "/", f.state + "/../state"]) assert.throws(() => statePath(path));
-  const link = join(f.root, "linked"); symlinkSync(f.state, link, "dir"); assert.throws(() => statePath(link), /symlink/);
+  const link = join(f.root, "linked"); directoryLink(f.state, link); assert.throws(() => statePath(link), /symlink/);
   writeFileSync(join(f.state, "status.json"), '{"schema_version":3,"schema_version":3}'); assert.throws(() => readRegistry(f.state), /duplicate JSON/);
   f.s.deployments.dangling = { deployment_id: "dangling", host_id: "missing", project_id: "app-a" }; f.save(); assert.throws(() => readRegistry(f.state), /orphan/);
 });
@@ -90,7 +96,7 @@ test("CLI help works without network, server dependencies or state", () => {
   const r = spawnSync(process.execPath, [path, "workspace-help"], { encoding: "utf8" }); assert.equal(r.status, 0, r.stderr); assert.match(r.stdout, /server-check/);
 });
 test("Linux checklist distinguishes missing, failed, profile-ready and stale evidence", (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], inv = inventory(h), at = new Date("2026-01-01T00:00:00Z");
+  const f = fixture(t), h = linuxServer(f), inv = inventory(h), at = new Date("2026-01-01T00:00:00Z");
   assert.equal(readiness(assessServer(h), at.toISOString(), { at }), "unknown");
   assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at }), "ready");
   assert.equal(readiness(assessServer(h, { profile: "compose", inventory: inv }), at.toISOString(), { at: new Date("2026-01-03T00:00:00Z") }), "stale");
@@ -100,7 +106,7 @@ test("Linux checklist distinguishes missing, failed, profile-ready and stale evi
   }
 });
 test("server check uses pinned public-key-only SSH and records restricted evidence", async (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture verified key");
+  const f = fixture(t), h = linuxServer(f), kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture verified key");
   Object.assign(h, { transport: "ssh", connection: { hostname: "example.invalid", username: "deploy", known_hosts: kh } }); f.save();
   let spawned = 0, called = 0;
   const a = { sshArgv: () => ["ssh", "-o", "StrictHostKeyChecking=yes"], spawn: (_cmd, args) => { spawned++; assert.ok(args.includes("PasswordAuthentication=no")); assert.ok(args.includes("KbdInteractiveAuthentication=no")); return { status: 0 }; }, call: () => { called++; return inventory(h); } };
@@ -111,7 +117,7 @@ test("server check uses pinned public-key-only SSH and records restricted eviden
   writeFileSync(kh, "different key"); assert.notEqual(check.host_digest, targetDigest(h));
 });
 test("failed SSH login never triggers Node probe and is not reported ready", async (t) => {
-  const f = fixture(t), h = f.s.hosts["node-a"], kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture"); Object.assign(h, { transport: "ssh", connection: { hostname: "invalid", username: "deploy", known_hosts: kh } }); f.save();
+  const f = fixture(t), h = linuxServer(f), kh = join(f.root, "known_hosts"); writeFileSync(kh, "fixture"); Object.assign(h, { transport: "ssh", connection: { hostname: "invalid", username: "deploy", known_hosts: kh } }); f.save();
   const r = await checkServer(f.state, "node-a", {}, { sshArgv: () => ["ssh"], spawn: () => ({ status: 255 }), call: () => { throw new Error("must not probe"); } });
   assert.equal(r.status, "blocked"); assert.equal(r.checks.find(c => c.id === "machine-identity").status, "unknown");
 });
@@ -210,7 +216,10 @@ test("fleet writes immutable generations, verifies readback and retains one cons
   const before = readFileSync(first.markdown, "utf8"); writeFileSync(first.html, "tampered"); assert.throws(() => generateFleet(f.state, { at }), /readback mismatch/); assert.equal(readFileSync(first.markdown, "utf8"), before);
 });
 test("fleet refuses symlink outputs and catalog locks without overwriting old entry", (t) => {
-  const f = fixture(t), outside = join(f.root, "outside.txt"); writeFileSync(outside, "untouched"); symlinkSync(outside, join(f.state, "FLEET.md"));
+  const f = fixture(t), outsideDir = join(f.root, "outside"), outside = join(outsideDir, "sentinel.txt");
+  mkdirSync(outsideDir); writeFileSync(outside, "untouched");
+  if (process.platform === "win32") directoryLink(outsideDir, join(f.state, "FLEET.md"));
+  else symlinkSync(outside, join(f.state, "FLEET.md"));
   assert.throws(() => generateFleet(f.state), /symlink/); assert.equal(readFileSync(outside, "utf8"), "untouched");
   rmSync(join(f.state, "FLEET.md")); mkdirSync(join(f.state, ".locks/catalog"), { recursive: true }); assert.throws(() => generateFleet(f.state), /catalog lock/);
 });

package/template/workflows/ops/common/tools/opslib/bootstrap.mjs

@@ -1,7 +1,7 @@
 /** Node-less Linux SSH bootstrap: pinned Volta/Node via POSIX + scp, then enroll. */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, basename, isAbsolute, join } from "node:path";
+import { dirname, basename, join, posix as posixPath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { digest, exact, identifier, newId, noSymlinks, NodeMissing, now, OpsError, privateDir, rootPath, targetJoin, writeJson } from "./core.mjs";
 import { register, validateHost } from "./model.mjs";
@@ -142,8 +142,8 @@ export function bootstrapNode(args) {
   const installers = installerDir(hostRoot);
   const voltaHome = managedVoltaHome(hostRoot, args.account);
   posixCall(endpoint, "#!/bin/sh\nset -eu\nmkdir -p -- \"$1\" \"$2\"\n", { args: [installers, voltaHome] });
-  const remoteVolta = join(installers, volta.filename);
-  const remoteNode = join(installers, node.filename);
+  const remoteVolta = posixPath.join(installers, volta.filename);
+  const remoteNode = posixPath.join(installers, node.filename);
   posixSend(endpoint, volta.file, remoteVolta);
   posixSend(endpoint, node.file, remoteNode);
   const applied = posixCall(endpoint, SCRIPT, {
@@ -181,7 +181,7 @@ export function enroll(state, request) {
     if (posix.tools?.node === "missing" || posix.node_usable === false) throw new NodeMissing(posix);
     const discovery = host.identity === "discover" || host.identity == null;
     if (discovery) host.identity = "0".repeat(64);
-    if (!isAbsolute(host.connection.node)) {
+    if (!posixPath.isAbsolute(host.connection.node) || host.connection.node.includes("\\")) {
       throw new OpsError("connection.node must be the absolute path returned by bootstrap-node");
     }
     validateHost(host);

package/template/workflows/ops/common/tools/opslib/transport.mjs

@@ -1,7 +1,7 @@
 /** Strict host-key SSH and subprocess local transport. No passwords in argv. */
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, posix, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { canonical, digest, noSymlinks, OpsError, redact, UnknownResult } from "./core.mjs";
 import { fingerprint } from "./agent.mjs";
@@ -107,8 +107,8 @@ export function posixSend(endpoint, localFile, remotePath, { timeout = 180 } = {
     throw new OpsError("POSIX bootstrap is Linux-only; PowerShell targets still require an existing Node");
   }
   noSymlinks(localFile, { allowMissing: false });
-  if (typeof remotePath !== "string" || !isAbsolute(remotePath) || remotePath.split("/").includes("..") || /[\s\n\r]/.test(remotePath)) {
-    throw new OpsError("remote scp path must be absolute without spaces or ..");
+  if (typeof remotePath !== "string" || !posix.isAbsolute(remotePath) || remotePath.split("/").includes("..") || /[\s\\\0]/.test(remotePath)) {
+    throw new OpsError("remote scp path must be POSIX absolute without whitespace, backslashes, NUL or ..");
   }
   const argv = sshArgv(endpoint, { scp: true });
   argv.push("--", localFile, `${endpoint.username}@${endpoint.hostname}:${remotePath}`);

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

@@ -38,9 +38,9 @@
 change 内三份文档复用 grill 的既有格式，避免重复发明：
 
 - 设计日志：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`；
-- 领域上下文：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`；
-- 架构决策：`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`；
-- 领域建模规则：`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。
+- 领域上下文：`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`；
+- 架构决策：`<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`；
+- 领域建模规则：`<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`。
 
 同步顺序固定：先 LOG，再 CONTEXT，最后 ADR。CONTEXT 只描述当前真相，历史轨迹留在 LOG；未确认的解读不得写成已接受 ADR；与现有永久 ADR 冲突时建立 supersedes 链，不重写历史。高影响条目带来源标识（`USER-DECISION`、`CODE:`、`RESEARCH:`、`ADR-###`）。