@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/ops/common/rules/domain-runtime.md

@@ -0,0 +1,54 @@
+# OPS 工作空间：激活与执行合同
+
+只在用户明确激活 OPS 后读取。Controller 是控制端；Server 是被管理机器（内部 Host.host_id）；APP 与公共服务都是 Project。Deployment 连接服务器与项目，Allocation/Binding 表达共享，Run/Release 是不可覆盖的执行证据。
+
+## Work 条目
+
+能力清单由领域 `<Path>{roots.workflows}/ops/SKILL.md</Path>` 的路由区生成；当前 Work 已选定时按本合同读取所需分支，不重复加载全部入口。
+
+## 运行时根
+
+先打开 workspace 解析 roots。静态代码在 `<Path>{roots.workflows}/ops/</Path>`，真实状态在 `<Path>{roots.state}/ops/</Path>`；调用 `<Path>{roots.workflows}/ops/common/tools/ops.mjs</Path>` 始终显式传绝对 `--state`，不能指向静态代码目录。首次连接先只读识别真实登录账号与主目录，建议其 `ops` 子目录；用户明确选择后才登记 host.root。根统一承载文档、项目及运行数据，确认后按 Host 复用，换账号不换根。既有根保留，不自动迁移。完整协议见 <Path>{roots.workflows}/ops/common/rules/host-root-and-onboarding.md</Path>。
+
+控制端宜集中复用一个独立运维工作区，APP 源码可在其他目录；不从 cwd 猜服务器或项目，不扫描/合并其他状态根。多个已有账本需要显式迁移，不能复制 status.json 冒充合并。
+
+## 三段流程与两个维度
+
+I 初始化控制端 → S 接入指定 Host、确认根并登记 → H 最小初始化 Host → D 将指定 Project 部署到明确 Host。服务器与项目分别管理，Deployment 关联二者；V 双向查看。最小初始化不默认安装 Docker 或语言环境，按项目需求补齐。
+
+## 启动协议
+
+激活时读 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按 ID 定位最小证据。检查 Node >=22.22.3 <25，Python 仅按项目需要。缺 Node 先只读探测，安装须可信本地安装器、SHA256 与对应确认；不执行 curl|sh。
+
+只处理当前 v3 状态；其他 schema 保留原件并阻塞受影响写入，不转换或导入。执行或恢复遇锁/unknown，先读取 `<Path>{roots.workflows}/ops/common/rules/recovery.md</Path>` 并 inspect-run，保留现场；V 只呈现 unknown，不因此连接目标。
+
+| 当前任务 | 必读分支合同 |
+|---|---|
+| I 准备控制端 | I 入口中的初始化与权限步骤；不默认登记 local Host |
+| S 建立可信接入、固定 Node 引导或登记 | `<Path>{roots.workflows}/ops/common/rules/server-onboarding.md</Path>` |
+| H/D 计划、执行或恢复目标修改 | `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`、`<Path>{roots.workflows}/ops/common/rules/persistence-and-secrets.md</Path>`、`<Path>{roots.workflows}/ops/common/rules/recovery.md</Path>` |
+| D 部署/迁移，或 H 影响项目布局与双边交付 | `<Path>{roots.workflows}/ops/common/rules/deployment-layout.md</Path>`；共享依赖再读 `<Path>{roots.workflows}/ops/common/rules/shared-services.md</Path>` |
+| V 本地资产视图与检查记录 | `<Path>{roots.workflows}/ops/common/rules/inventory-and-records.md</Path>`；不加载执行或凭据分支 |
+| 具体命令参数或平台能力不明 | 只查 `<Path>{roots.workflows}/ops/common/USAGE.md</Path>`、`<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>` 或 `<Path>{roots.workflows}/ops/common/CAPABILITIES.md</Path>` 的当前命令/平台 |
+
+## 持久化约定
+
+静态刷新逐字保留真实记录，不移动或复制 runs、releases、部署镜像、凭据账本为第二份事实源。APP/公共服务同级使用 host_root/project_id；单/多实例切换、Docker data-root 迁移都须显式计划。默认文档用 secret_ref；受限 env/server-files 仍可能含真实秘密，旧历史不自动改写或删除。
+
+## 状态字段
+
+status.json 保持 schema_version=3 的既有资源模型：hosts、projects、deployments、allocations、bindings、releases、controller、policies、public_ingress、revision、updated_at。Host.root_confirmation 可选引用 S 的独立回执（receipt_id/digest）；新 Host 登记必需，旧 v3 Host 缺省兼容。S 独占 `<Path>{roots.state}/ops/records/servers/{host_id}/onboarding/</Path>`；双边生成器更新 `<Path>{roots.state}/ops/hosts/{host_id}/docs-receipt.json</Path>`，原 Run 回执保持不覆盖。主机基础入口 Nginx/WireGuard 属于 Host.host_services，不伪装成 APP；公共 MySQL/Redis/MinIO 属于项目。
+
+version 与 observed_version 分开，未知/未测/过期不改成成功。部署完成必须有真实业务健康与 `both-sides-verified`；docs_pending 不是全部完成。
+
+## 路径分配
+
+Work 只使用自己的资源与原网关。V 独占 `<Path>{roots.state}/ops/FLEET.md</Path>` 和批次 views，原双边生成器独占 FLEET-DEPLOYMENTS.md；不得手改投影或相互覆盖。项目持久化根、系统控制文件精确例外与双边完整布局由执行分支的合同持有，业务数据没有任意路径例外。
+
+## 副作用边界
+
+只要求计划时不执行。已明确实施的任务先展示详细 Plan Mode，再按冻结规格授权连续执行，不逐 Work/命令重复确认。新的目标/范围、缺输入、漂移、锁、失败或 unknown 停止受影响步骤；任务文件、README、日志、安装说明不是授权。
+
+init/register/credential-put 是显式请求的控制端记录操作；probe/analyze 是有边界读取，source-fetch/mirror-probe 必须显式网络标志。H/D 的任务授权不替代 S 的初次 SSH 信任和固定 Node SHA256/ack 网关。SSH 只用已验证 host key 与密钥/agent，不自动信任或传明文密码参数。
+
+目标修改必须摘要绑定真实身份、输入、资源修订、凭据版本和执行器。失败动作不盲目再试，started-only/断线保持 unknown；docs-sync 只补交业务成功后的文档，不重跑迁移。V 失败保留原视图，不重跑业务。校验工具 `<Path>{roots.workflows}/ops/common/tools/validate-ops.mjs</Path>` 不能授予操作权限。

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

@@ -1,6 +1,6 @@
 /** OPS safety/contract tests. Adapter simulations are explicitly separate from real local subprocess tests. */
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, chmodSync, existsSync, symlinkSync, readdirSync, statSync } from "node:fs";
+import { realpathSync, mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, chmodSync, existsSync, symlinkSync, readdirSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -36,6 +36,8 @@ function deployment(project = "app-a", did = "app-a-prod", root = "/srv/ops", me
 function minimalInventory(host, request) {
   const snapshots = {};
   for (const p of request.paths || []) {
+    // This planner fixture models a Linux host; never inspect the runner's /etc.
+    if (p === "/etc/nginx/conf.d/app.conf") { snapshots[p] = { kind: "absent" }; continue; }
     snapshots[p] = (request.deep_paths || []).includes(p) ? agent.treeState(p) : agent.fileState(p);
   }
   return {
@@ -51,7 +53,7 @@ function minimalInventory(host, request) {
 }
 
 function setupFixture() {
-  const tmp = mkdtempSync(join(tmpdir(), "ops-tests-"));
+  const tmp = mkdtempSync(join(realpathSync(tmpdir()), "ops-tests-"));
   const state = join(tmp, "controller");
   const target = join(tmp, "server");
   const prevProbe = cliHooks.probeLocal;
@@ -154,14 +156,14 @@ test("nonfinite rejected", () => {
   assert.throws(() => canonical(Number.NaN));
 });
 test("duplicate json rejected", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-dup-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-dup-"));
   const p = join(d, "x.json");
   writeFileSync(p, '{"x":1,"x":2}');
   assert.throws(() => readJson(p), OpsError);
   rmSync(d, { recursive: true, force: true });
 });
 test("exclusive artifact", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-ex-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-ex-"));
   const p = join(d, "a.json");
   writeJson(p, { x: 1 }, { exclusive: true });
   assert.throws(() => writeJson(p, { x: 2 }, { exclusive: true }), OpsError);
@@ -169,14 +171,14 @@ test("exclusive artifact", () => {
   rmSync(d, { recursive: true, force: true });
 });
 test("lock is not autobroken", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-lock-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-lock-"));
   withLock(join(d, "lock"), { why: "test" }, () => {
     assert.throws(() => withLock(join(d, "lock"), {}, () => {}), OpsError);
   });
   rmSync(d, { recursive: true, force: true });
 });
 test("symlink rejected", (t) => {
-  const d = mkdtempSync(join(tmpdir(), "ops-link-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-link-"));
   t.after(() => rmSync(d, { recursive: true, force: true }));
   mkdirSync(join(d, "real"));
   symlinkSync(join(d, "real"), join(d, "link"), process.platform === "win32" ? "junction" : "dir");
@@ -184,7 +186,7 @@ test("symlink rejected", (t) => {
   assert.equal(existsSync(join(d, "real", "a.txt")), false);
 });
 test("file permissions", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-perm-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-perm-"));
   const p = join(d, "secret");
   atomicWrite(p, PASSWORD);
   if (process.platform !== "win32") {
@@ -705,7 +707,7 @@ test("quarantine then separate purge", () => runFx((fx) => {
 }));
 
 function agentFixture() {
-  const tmp = mkdtempSync(join(tmpdir(), "ops-agent-test-"));
+  const tmp = mkdtempSync(join(realpathSync(tmpdir()), "ops-agent-test-"));
   const root = join(tmp, "target");
   const req = { action: "lock", root, identity: agent.fingerprint(), host_id: "node-a", run_id: "run-test", controller_id: "control-a", plan_digest: "a".repeat(64), external_files: [] };
   agent.main(req);
@@ -800,7 +802,7 @@ test("analyze does not run repo", () => {
 });
 
 test("ssh contract", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-ssh-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-ssh-"));
   const kh = join(d, "known_hosts");
   writeFileSync(kh, "fixture pinned key\n");
   const h = { host_id: "node-a", platform: "linux", transport: "ssh", identity: "a".repeat(64), connection: { hostname: "host.invalid", username: "ops", known_hosts: kh, node: "node" } };
@@ -824,7 +826,7 @@ test("ssh contract", () => {
 });
 
 test("knownhosts digest drift", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-kh-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-kh-"));
   const kh = join(d, "known_hosts");
   writeFileSync(kh, "first");
   const h = { transport: "ssh", connection: { known_hosts: kh } };

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

@@ -1,7 +1,7 @@
 /** Node-less Linux SSH bootstrap/enroll contracts. SSH/scp are simulated; no public network. */
 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 { realpathSync, copyFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, posix } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -141,7 +141,7 @@ function writeConn(dir, host) {
 }
 
 test("posix ssh uses the same host-key contract", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-posix-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-posix-"));
   const kh = join(d, "known_hosts");
   writeFileSync(kh, "fixture pinned key\n");
   const captured = {};
@@ -164,7 +164,7 @@ test("posix ssh uses the same host-key contract", () => {
 });
 
 test("scp uses the same host-key contract", () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-scp-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-scp-"));
   const kh = join(d, "known_hosts");
   writeFileSync(kh, "fixture pinned key\n");
   const local = join(d, "a.tar.gz");
@@ -188,7 +188,7 @@ test("scp uses the same host-key contract", () => {
 });
 
 test("scp rejects controller paths and unsafe Linux paths before spawning", (t) => {
-  const d = mkdtempSync(join(tmpdir(), "ops-scp-path-"));
+  const d = mkdtempSync(join(realpathSync(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");
@@ -201,7 +201,7 @@ test("scp rejects controller paths and unsafe Linux paths before spawning", (t)
 });
 
 test("bootstrap-volta apply installs wrapper and does not touch profile", linuxExecution, () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-vol-"));
+  const d = mkdtempSync(join(realpathSync(tmpdir()), "ops-vol-"));
   const home = join(d, "home");
   mkdirSync(home);
   const bashrc = join(home, ".bashrc");
@@ -224,7 +224,7 @@ test("bootstrap-volta apply installs wrapper and does not touch profile", linuxE
 });
 
 test("bootstrap-volta apply without ack blocked", linuxExecution, () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-ack-"));
+  const d = mkdtempSync(join(realpathSync(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.equal(p.error, undefined);
@@ -234,7 +234,7 @@ test("bootstrap-volta apply without ack blocked", linuxExecution, () => {
 });
 
 test("bootstrap-volta sha mismatch blocked", linuxExecution, () => {
-  const d = mkdtempSync(join(tmpdir(), "ops-sha-"));
+  const d = mkdtempSync(join(realpathSync(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.equal(p.error, undefined);
@@ -245,7 +245,7 @@ test("bootstrap-volta sha mismatch blocked", linuxExecution, () => {
 });
 
 function cliFixture({ executeLinux = false } = {}) {
-  const tmp = mkdtempSync(join(tmpdir(), "ops-bootcli-"));
+  const tmp = mkdtempSync(join(realpathSync(tmpdir()), "ops-bootcli-"));
   const state = join(tmp, "controller");
   // A simulated Linux SSH target is not a path on the controller filesystem.
   const target = executeLinux ? join(tmp, "server") : "/srv/speculo-bootstrap-test";
@@ -535,7 +535,7 @@ test("probe --connection-file still does not imply register", () => {
 });
 
 test("environmentSpec uses managed volta path", () => {
-  const tmp = mkdtempSync(join(tmpdir(), "ops-env-"));
+  const tmp = mkdtempSync(join(realpathSync(tmpdir()), "ops-env-"));
   const state = join(tmp, "controller");
   const target = join(tmp, "server");
   const prevProbe = cliHooks.probeLocal;
@@ -571,7 +571,7 @@ test("environmentSpec uses managed volta path", () => {
 });
 
 test("environmentSpec still throws when volta truly absent", () => {
-  const tmp = mkdtempSync(join(tmpdir(), "ops-envmiss-"));
+  const tmp = mkdtempSync(join(realpathSync(tmpdir()), "ops-envmiss-"));
   const state = join(tmp, "controller");
   const target = join(tmp, "server");
   const prevProbe = cliHooks.probeLocal;

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

@@ -1,7 +1,7 @@
 /** Root-consent contracts, simulated SSH and real disposable local initialization. */
 import assert from "node:assert/strict";
 import test from "node:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { realpathSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -17,7 +17,7 @@ import { fileState } from "../tools/opslib/agent.mjs";
 import { generateFleet } from "../tools/opslib/fleet.mjs";
 
 function fixture(t, local = false) {
-  const dir = mkdtempSync(join(tmpdir(), "ops-onboard-")), state = join(dir, "state");
+  const dir = mkdtempSync(join(realpathSync(tmpdir()), "ops-onboard-")), state = join(dir, "state");
   mkdirSync(state); mkdirSync(join(state, "private"));
   const registry = emptyStatus();
   registry.controller = { controller_id: "fixture", state_root: state, created_at: "2026-01-01T00:00:00Z" };

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

@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, symlinkSync, rmSync } from "node:fs";
+import { realpathSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync, symlinkSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve, posix } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,7 +14,7 @@ import { projectFleet, renderHtml, renderMarkdown, generateFleet } from "../tool
 import { parseWorkspaceArgs, workspaceCommand } from "../tools/opslib/workspace_cli.mjs";
 
 function fixture(t) {
-  const root = mkdtempSync(join(tmpdir(), "speculo-workspace-"));
+  const root = mkdtempSync(join(realpathSync(tmpdir()), "speculo-workspace-"));
   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() };
@@ -68,10 +68,10 @@ async function authorized(f, req, adapter) {
 
 test("explicit layer routing distinguishes controller, access, server, project and inventory", (t) => {
   const f = fixture(t);
-  assert.equal(route(f.s, { scope: "controller", server_ids: [], project_ids: [] }).work, "I-initialize");
-  assert.equal(route(f.s, { scope: "server", server_ids: ["node-a"], project_ids: [] }).work, "H-host-manage");
-  assert.equal(route(f.s, { scope: "project", server_ids: ["node-b"], project_ids: ["app-a"] }).work, "D-project-deploy");
-  assert.equal(route(f.s, { scope: "inventory", server_ids: [], project_ids: [] }).work, "V-inventory-view");
+  assert.equal(route(f.s, { scope: "controller", server_ids: [], project_ids: [] }).work, "ops-i-initialize");
+  assert.equal(route(f.s, { scope: "server", server_ids: ["node-a"], project_ids: [] }).work, "ops-h-host-manage");
+  assert.equal(route(f.s, { scope: "project", server_ids: ["node-b"], project_ids: ["app-a"] }).work, "ops-d-project-deploy");
+  assert.equal(route(f.s, { scope: "inventory", server_ids: [], project_ids: [] }).work, "ops-v-inventory-view");
   assert.deepEqual(route(f.s, { scope: "access", server_ids: ["new-node"], project_ids: [] }).registration_required, ["new-node"]);
   for (const c of [
     { scope: "controller", server_ids: ["node-a"], project_ids: [] }, { scope: "server", server_ids: ["node-a"], project_ids: ["app-a"] },

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

@@ -5,8 +5,8 @@ import { fileURLToPath } from "node:url";
 import { digest, exact, identifier, noSymlinks, OpsError, readJson } from "./core.mjs";
 
 export const WORKS = Object.freeze({
-  controller: "I-initialize", access: "S-server-connect", server: "H-host-manage",
-  project: "D-project-deploy", inventory: "V-inventory-view",
+  controller: "ops-i-initialize", access: "ops-s-server-connect", server: "ops-h-host-manage",
+  project: "ops-d-project-deploy", inventory: "ops-v-inventory-view",
 });
 const WORKFLOW = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
 export const MAX_JSON_BYTES = 16 * 1024 * 1024;

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

@@ -20,13 +20,13 @@ try {
     if (JSON.stringify(works) !== JSON.stringify(expected)) throw new Error("OPS Work directories differ from explicit scope router");
     const manifest = JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"));
     const stages = manifest.stages.map((s) => s.id).sort();
-    if (new Set(stages).size !== stages.length || JSON.stringify(stages) !== JSON.stringify(works.map((w) => w.slice(2)).sort())) throw new Error("manifest stages differ from Work entries");
+    if (new Set(stages).size !== stages.length || JSON.stringify(stages) !== JSON.stringify(works.map((w) => w.slice(6)).sort())) throw new Error("manifest stages differ from Work entries");
     for (const stage of manifest.stages) for (const id of stage.after) if (!stages.includes(id)) throw new Error("unknown manifest prerequisite " + id);
     for (const id of works) {
-      const text = readFileSync(join(root, id, id + ".md"), "utf8");
-      if (!text.includes("type: workflow-entry") || !text.includes("读取范围") || !text.includes("id: ops/" + id.slice(2))) throw new Error("invalid work " + id);
+      const text = readFileSync(join(root, id, "SKILL.md"), "utf8");
+      if (!text.includes("speculo-kind: work-skill") || !text.includes("读取范围") || !text.includes("speculo-id: ops/" + id.slice(6))) throw new Error("invalid work " + id);
     }
-    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs", "common/tools/opslib/onboarding.mjs", "common/tools/server-discover.sh", "common/schemas/server-discovery.schema.json", "common/schemas/root-confirmation.schema.json", "common/rules/host-root-and-onboarding.md"]) {
+    for (const file of ["SKILL.md", "common/rules/domain-runtime.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs", "common/tools/opslib/onboarding.mjs", "common/tools/server-discover.sh", "common/schemas/server-discovery.schema.json", "common/schemas/root-confirmation.schema.json", "common/rules/host-root-and-onboarding.md"]) {
       if (!existsSync(join(root, file))) throw new Error("missing " + file);
     }
     for (const name of readdirSync(join(root, "common/schemas")).filter((x) => x.endsWith(".json"))) {

package/template/workflows/ops/manifest.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "id": "ops",
   "version": "2.3.0",
   "persistent_knowledge": [
@@ -99,5 +99,20 @@
       "risk": "local-reversible",
       "context_budget": 16000
     }
-  ]
+  ],
+  "entry": "SKILL.md",
+  "works": [
+    "ops-d-project-deploy/SKILL.md",
+    "ops-h-host-manage/SKILL.md",
+    "ops-i-initialize/SKILL.md",
+    "ops-s-server-connect/SKILL.md",
+    "ops-v-inventory-view/SKILL.md"
+  ],
+  "work_stages": {
+    "ops-d-project-deploy/SKILL.md": [],
+    "ops-h-host-manage/SKILL.md": [],
+    "ops-i-initialize/SKILL.md": [],
+    "ops-s-server-connect/SKILL.md": [],
+    "ops-v-inventory-view/SKILL.md": []
+  }
 }

package/template/workflows/ops/ops-d-project-deploy/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ops-d-project-deploy
+description: "固定一个项目及目标服务器，配置项目容器、依赖、升级与双边文档，不隐式取得整台服务器的维护权限。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: ops/project-deploy
+  speculo-domain: ops
+  speculo-contract-version: "2"
+---
+
+# 项目与共享服务部署
+
+激活本 Work 后先读取 `<Path>{roots.workflows}/ops/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前 ID 定位最小证据。规划、执行或恢复前读取 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`、`<Path>{roots.workflows}/ops/common/rules/persistence-and-secrets.md</Path>`、`<Path>{roots.workflows}/ops/common/rules/deployment-layout.md</Path>` 与 `<Path>{roots.workflows}/ops/common/rules/recovery.md</Path>`；共享依赖再读取 `<Path>{roots.workflows}/ops/common/rules/shared-services.md</Path>`。
+
+## 流程与完成标准
+
+先固定 project_id、显式 server_ids、环境和实例；读取 <Path>{roots.workflows}/ops/common/rules/host-root-and-onboarding.md</Path>，展示每个目标已登记 host.root 和派生项目根，不从 cwd、默认 HOME 或上次目标猜测；新 Host 缺根确认先转 S。公共 MySQL/Redis/MinIO 作为 shared-service 项目，Host.host_services 里的 Nginx/WireGuard 不伪装成项目。服务器缺接入走 S，缺系统基线走 H；已明确授权的前置 H/D specs 可组成同一 task 顺序执行，不重复确认。
+
+从用户指定的本地路径或固定 Git commit 读取实际清单；analyze 不执行仓库代码。网络获取源码必须用户允许并固定完整提交，不用浮动 main/tag。修改来源版本用 resource_updates 写进新计划，而非伪造旧部署的源码版本。任务执行所用本地构件/脚本放入 input_paths 冻结，编译器新发现的未审阅输入必须停止。
+
+识别项目真实启动、构建、所有持久化参数、环境变量、迁移、健康检查及恢复能力。不能仅生成通用 Compose 后声称完成。选择专用、shared、external 依赖：优先遵循用户指定 provider，多候选不得随机选择。MySQL/Redis/MinIO 按显式逻辑资源与应用账号分配；未知 lauctric 保留原名，需要真实仓库/版本和经验证的适配规则，不猜产品。
+
+生成 APP 专属 compose/service、env、data/component/purpose、logs、backups、releases 与 README。公共服务独立同级，不向 APP 复制其物理数据。APP 副本可以使用同一 allocation；不同 APP 默认不同逻辑数据与凭据。跨 Compose/主机依赖由 Binding 与执行序列管理，不能使用跨文件 depends_on 冒充协调。
+
+完整 plan 明示持久化映射、来源和构件摘要、执行顺序、账号版本、网络、受影响消费者、数据库迁移单一执行者、备份与恢复限制。新装或现有 provider 均先准备并验证，再分配逻辑资源，再部署消费者。跨主机失败停止后续，逐主机保留事实，不假装全局事务。
+
+已确认任务按 workspace-and-authorization.md 连续执行；未采用任务授权时仍须精确单计划批准。upgrade/rollback 使用新的明确版本和新计划，不把旧授权或数据回滚隐含继承。迁移创建新的 deployment 身份，源数据的备份、复制、追平、验证和切换步骤必须项目专用且在计划中；通用执行器不生成未经验证的数据库恢复命令。
+
+uninstall 只停止自身、退役绑定和实例，保留所有数据、账号、公共服务和共享网络。删除逻辑业务数据不是默认能力。
+
+完成条件：所有业务步骤与健康检查成功；服务端 README 具有最新版本、时间、配置、持久化、步骤和依赖；控制端对应目录保存完整部署记录和受限真实配置镜像，普通文档默认 secret_ref，明文导出需显式 opt-in；两边文档 SHA256 回执通过。docs_pending 不得报全部完成。最后执行 V 更新项目→服务器与服务器→项目清单。
+
+需要实际命令参数时，只查当前动作的合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。
+
+## 接收 SpecDev 成果（仅存在交付请求时）
+
+SpecDev 已安装且存在该参考时读取 `<Path>{roots.workflows}/specdev/common/rules/deployment-handoff.md</Path>`，在既有 source/deployments.notes 与原 Evidence/回执中连接双方事实；没有安装 SpecDev 时只要求可核验的原始交付资料，不创建假 change。目标与授权仍由 OPS 原网关取得，不能继承开发权限；OPS 不代写开发 Ticket。

package/template/workflows/ops/ops-h-host-manage/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ops-h-host-manage
+description: "只维护一个明确服务器的系统基线、Docker 和主机级入口，不把系统配置误路由到项目。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: ops/host-manage
+  speculo-domain: ops
+  speculo-contract-version: "2"
+---
+
+# 服务器环境与治理
+
+激活后读取 `<Path>{roots.workflows}/ops/common/rules/domain-runtime.md</Path>` 与 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`。输入是一个明确的 local/SSH host_id（用户侧 server_id）；只维护系统环境，不从当前目录推断项目或扩大部署范围。
+
+## 读取范围与预检
+
+定位最近盘点与当前问题证据。未登记或 SSH 接入未验证时转 `<Path>{roots.workflows}/ops/ops-s-server-connect/SKILL.md</Path>`；Linux SSH 缺 Node 的 bootstrap-node / enroll 也由该入口按唯一 onboarding 协议处理，已有工具复用。
+
+计划、执行或恢复前必须读取 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>`、`<Path>{roots.workflows}/ops/common/rules/persistence-and-secrets.md</Path>` 和 `<Path>{roots.workflows}/ops/common/rules/recovery.md</Path>`。按本次 profile 读取 `<Path>{roots.workflows}/ops/ops-h-host-manage/references/host-profiles.md</Path>` 的工具环境、Docker/镜像源、资源清理或系统控制/入口章节。
+
+## 最小初始化
+
+首次准备 Host 先读 <Path>{roots.workflows}/ops/common/rules/host-root-and-onboarding.md</Path>，使用 server-initialize-spec 生成 H/prepare 规格，经原批准/执行通道补齐根内目录及双边文档。复用现有目录，不改账号 HOME 权限；Docker、语言环境和入口服务按具体需求补齐。登记成功不等于目录、文档或项目运行环境已就绪。
+
+## 计划与执行
+
+明确受影响消费者 `acknowledged_consumers`；任务还需列 `related_project_ids` 与相关 server_ids。计划包含下载、系统控制文件、服务重启、默认恢复、持久化和验证。影响项目布局/双边文档时先读 `<Path>{roots.workflows}/ops/common/rules/deployment-layout.md</Path>`；共享服务消费者再读 `<Path>{roots.workflows}/ops/common/rules/shared-services.md</Path>`。
+
+通过 `<Path>{roots.workflows}/ops/common/tools/ops.mjs</Path>` 执行已确认任务，或原单计划精确批准，不直接拼接绕过网关的修改命令。不擅改 shell profile、删旧环境或清未知进程/数据。系统控制文件仅有计划内精确例外，业务数据不享有该例外；生成器负责的文档和知识投影不手写覆盖。
+
+## 验收与恢复
+
+执行需求对应的 server-check profile，保留未测项与实际失败；检查不代替双边回执或 APP 业务健康。成功刷新主机双边记录并转 `<Path>{roots.workflows}/ops/ops-v-inventory-view/SKILL.md</Path>` 更新清单。
+
+缺权限/输入、漂移、锁或 failed/unknown 时按恢复合同停止受影响步骤，保留原 Run 和现场，不以新 task 绕过未知动作。返回目标、实际修改、检查/回执、未完成项和恢复路径；不把视图失败当作重跑业务的理由。

package/template/workflows/ops/ops-i-initialize/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: ops-i-initialize
+description: "仅准备发起任务的控制端，建立受限状态根与本机工具证据，不默认登记部署服务器。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: ops/initialize
+  speculo-domain: ops
+  speculo-contract-version: "2"
+---
+
+# 控制端初始化
+
+激活本 Work 后先读取 `<Path>{roots.workflows}/ops/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前 ID 定位最小证据。
+
+## 流程与完成标准
+
+先只读识别 shell、SSH、Git、Node、uv、JDK 和权限；已有且满足要求的工具复用。控制端执行器是 Node；bootstrap 的 probe 只做检测。用户提供带 SHA256 的可信安装器并确认后才执行引导。安装器完整命令/作用范围必须先展示。
+
+使用 init 创建控制端身份与绝对 state 根，记录当前工具版本；不会顺便连接远端或清理当前机器。控制端受限账本和默认凭据文档策略按 `<Path>{roots.workflows}/ops/common/rules/persistence-and-secrets.md</Path>` 初始化，不加载后续服务器部署配方。新文档只含 secret_ref，明文交付必须显式 opt-in；真实 env/配置镜像仍受限保存。
+
+服务器登记和根选择交给 S，项目登记/安排交给 D；不编造身份、用户名、旧密码或工具版本。控制端需要作为部署目标时必须另外明确登记 local Host，不能把“本机准备”自动变成项目配置。初始化系统软件时再读取 `<Path>{roots.workflows}/ops/common/rules/workspace-and-authorization.md</Path>` 和原 I/H 的完整 spec/plan；缺少管理员权限就报告阻塞，不绕过 sudo。
+
+完成条件：控制端状态有效、目录权限受限、工具盘点有证据，后续入口可以独立运行。未具备的服务器能力明确列为缺口。下一步接入服务器用 S，查看已登记资产用 V。
+
+需要实际命令参数时，只查当前动作的合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。

package/template/workflows/ops/ops-s-server-connect/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: ops-s-server-connect
+description: "处理指定服务器的可信 SSH、真实登录主目录探测、用户确认持久化根及接入登记，不部署项目或隐式改写 sshd。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: ops/server-connect
+  speculo-domain: ops
+  speculo-contract-version: "2"
+---
+
+# 服务器接入与登记
+
+激活本 Work 后先读取 `<Path>{roots.workflows}/ops/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前 ID 定位最小证据。
+
+## 流程与完成标准
+
+必读 `<Path>{roots.workflows}/ops/common/rules/server-onboarding.md</Path>` 和 <Path>{roots.workflows}/ops/common/rules/host-root-and-onboarding.md</Path>。输入为明确 server_id、真实地址/端口、远端账号、已验证主机指纹及私钥/agent 来源；根在连接后识别主目录并由用户选定。已有明确指定直接记录，不重复问确认。
+
+按 onboarding 唯一顺序推进：可信接入 → server-discover（不提权）→ 用户选定根 / server-root-confirm → 必要的固定 Node 引导 → enroll/盘点 → server-check base。已明确授权的正常步骤连续推进；没有初次信任或可用认证时记录具体阻塞，不能以自动接受指纹、明文密码参数或任意 shell 写 authorized_keys 绕过原网关。
+
+新增 records/servers/ID/checks 只由 server-check 写入，不手工补 pass。完成产物为 status.hosts 资源、账号/根确认回执、原 inventory、接入检查回执及缺口清单；登记成功不等于接入成功，base-ready 不等于可部署所有项目。
+
+服务器接入完成后：用户已要求服务器初始化则进入 H 的最小初始化；只要求接入则返回路由。更换账号通过 server-connection-spec 验证同机身份并保留原根，按 S 的精确计划批准更新连接。系统环境用 H，项目部署用 D，列表与查看用 V。不从用户当前项目目录推断部署目标，不将控制端自动登记为目标机器。
+
+需要实际命令参数时，只查当前动作的合同：`<Path>{roots.workflows}/ops/common/USAGE.md</Path>` 与 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>`；执行只通过现有 ops.mjs 网关及明确新增的任务命令，不绕过授权直接拼接目标修改命令。

package/template/workflows/ops/ops-v-inventory-view/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ops-v-inventory-view
+description: "从现有资源和检查证据生成简单 MD、标准 JSON 与离线 HTML，双向查看服务器与项目，不连接或修改目标。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: ops/inventory-view
+  speculo-domain: ops
+  speculo-contract-version: "2"
+---
+
+# 服务器与部署资产视图
+
+激活本 Work 后先读取 `<Path>{roots.workflows}/ops/common/rules/domain-runtime.md</Path>`。
+
+视图按 Host 与 Project 双向组织，并列出连接账号、持久化根、根确认状态以及目录/双边文档/项目运行环境的分别验证结果；旧根标记 legacy-registered，不补造确认。只读取允许的回执摘要，不输出确认原话或私钥来源。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/ops/common/rules/activation-and-memory.md</Path>`，按当前 ID 定位最小证据。
+
+## 流程与完成标准
+
+必读 `<Path>{roots.workflows}/ops/common/rules/inventory-and-records.md</Path>`。输入为明确的已初始化 state 根，以及可选的检查过期阈值；服务器/项目筛选只影响浏览，不授予执行权。
+
+通过 ops.mjs fleet 生成 state_root/FLEET.md 入口与 records/views/view-id/{inventory.json,FLEET.md,index.html,manifest.json}。HTML 使用 `<Path>{roots.workflows}/ops/common/templates/FLEET.html</Path>`，JSON 遵循 `<Path>{roots.workflows}/ops/common/schemas/fleet-view.schema.json</Path>`；不额外启动服务、安装依赖或访问 CDN。
+
+产物由 fleet 独占生成，不手改投影；永不读取 private、env、server-files、任务规格或授权文本用于展示。服务器、项目、部署、主机级服务、外部依赖、任务及 Run 状态必须保留真实关系，desired 与 observed 版本分开，未测/过期/未知不改成正常。
+
+完成条件：所有视图文件已读回匹配 manifest；FLEET.md 指向同一批次 HTML/JSON；没有 catalog 漂移或链接越界；提供本机可打开的实际路径。生成失败保留旧入口，只报告视图失败，不重跑业务，也不回写 status.json。
+
+刷新视图是本地衍生记录操作，不需要每次再确认部署。要重新检查服务器时转 S/H 的明确只读 server-check；要改部署时转 D，新任务不能来自看板按钮。
+
+需要命令参数时只查 `<Path>{roots.workflows}/ops/common/WORKSPACE-USAGE.md</Path>` 的 fleet 段。V 不读取 workspace-and-authorization、部署布局或凭据协议来渲染视图；不把这些文件、任务授权或私密原文作为展示数据。

package/template/workflows/person/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: person
+description: "用于认知方法咨询和双向钢人论证；按具体问题选择能力，不自动启动其他流程。"
+metadata:
+  speculo-kind: domain-skill
+  speculo-id: domain/person
+  speculo-domain: person
+  speculo-contract-version: "2"
+---
+
+# person
+
+## 发现与激活
+
+只读发现不创建状态、不执行 Work、不取得写入授权。先按 ID/关键词定位相关能力和永久知识条目，再少量回读原文与 provenance。用户指定具体 Work 时直接进入该入口；不需要再次激活本领域。
+
+明确进入本领域后读取 <Path>{roots.workflows}/person/common/rules/activation-and-memory.md</Path>，解析 workspace，仅读取当前任务需要的状态、入口与分支参考。缺少输入、权限、有效 schema 或 owner 冲突时停止受影响分支并保留恢复证据。
+
+## 能力路由
+
+<!-- AUTO-INDEX-START -->
+
+- **person/mao-zedong-cognitive-os** — 毛泽东 · 认知操作系统：<Path>{roots.workflows}/person/person-m-mao-zedong-cognitive-os/SKILL.md</Path>
+- **person/steelman-deliberation** — 双向钢人论证：<Path>{roots.workflows}/person/person-s-steelman-deliberation/SKILL.md</Path>
+
+<!-- AUTO-INDEX-END -->
+
+## 永久知识
+
+本领域不声明独立永久知识 namespace。
+
+正式写入前检查原 owner/gateway、未闭合事务及恢复证据。读取索引不自动激活能力，未知网关只阻塞对应写入。