@namewta/speculo 1.0.16 → 1.0.17

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

@@ -274,13 +274,13 @@ export function deploymentReadme(status, dep, runId, generatedAt, { ledger = nul
   out.push("## 同项目部署位置\n", replicas.sort((a, b) => a.deployment_id < b.deployment_id ? -1 : 1).map((d) => `- ${d.host_id} / ${d.deployment_id}：${code(d.root)}`).join("\n") + "\n");
   if (controller) out.push("\n本目录是部署机的配置、凭据、运行证据和远端文档记录；不声称自动复制了远端业务数据。数据备份需要独立的备份策略和回执。\n");
   if (includeCredentials) out.push(credentialsText(credentialRefs(status, dep), ledger));
-  else out.push("\n## 凭据记录\n\n本 README 默认不写密码。获授权管理员读取本项目 OPERATIONS.md（启用时）或部署机明文手册；密码未知时必须补齐，不能编造。\n");
+  else out.push("\n## 凭据记录\n\nsecret_ref: " + credentialRefs(status, dep).map(code).join(", ") + "\n\n本文件默认不写密码。凭据按 ID@版本定位受限 private/credentials.json；真实值仅在批准 plaintext_documentation 后导出。未知值不得编造。\n");
   return out.join("\n") + "\n";
 }
 
 export function hostReadme(status, hid, runId, at, { ledger = null, full = false, controller = false } = {}) {
   const host = status.hosts[hid];
-  const includeCredentials = Boolean(full && controller && ledger);
+  const includeCredentials = Boolean(full && controller && ledger && plaintextDocumentation(status));
   const rows = overviewRows(status, hid, { ledger, includeCredentials });
   const out = [
     `# 主机 ${host.display_name} / ${hid}\n`,
@@ -368,6 +368,11 @@ const KNOWLEDGE_INDEX = `# 共享知识索引
 只收录经用户确认、带来源和最后验证时间的知识，不存密码。
 `;
 
+// Legacy absent field retains existing deliberate behavior; init seeds false. Changing policy requires a new approved plan.
+export function plaintextDocumentation(status) {
+  return status.policies.plaintext_documentation ?? true;
+}
+
 export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
   const at = now();
   const rid = plan.run_id;
@@ -381,9 +386,9 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
   for (const did of [...new Set(verifiedIds)].sort()) {
     const d = status.deployments[did];
     const hid = d.host_id;
-    const readme = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: status.policies.server_readme_credentials });
+    const readme = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: Boolean(status.policies.server_readme_credentials && plaintextDocumentation(status)) });
     addRemote(hid, pathFor(status, d, "README.md"), readme);
-    const operations = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true });
+    const operations = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: plaintextDocumentation(status) });
     if (status.policies.server_operations) addRemote(hid, pathFor(status, d, "OPERATIONS.md"), operations);
     addRemote(hid, pathFor(status, d, "project.yaml"), JSON.stringify(d, null, 2) + "\n");
     addRemote(hid, pathFor(status, d, "run/release-state.json"), JSON.stringify({
@@ -397,7 +402,7 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
       addRemote(hid, targetJoin({ ...status.hosts[hid], root: projectroot }, "README.md"), text);
     }
     const prefix = `hosts/${hid}/deployments/${did}`;
-    local[prefix + "/README.md"] = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true, controller: true });
+    local[prefix + "/README.md"] = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: plaintextDocumentation(status), controller: true });
     local[prefix + "/OPERATIONS.md"] = operations;
     local[prefix + "/deployment.json"] = JSON.stringify(d, null, 2) + "\n";
     local[prefix + "/server/README.md"] = readme;
@@ -420,8 +425,8 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
     local[`hosts/${hid}/knowledge/host-services.json`] = hostServicesDocument(h);
     if (ingressJson) local[`hosts/${hid}/knowledge/public-ingress.json`] = ingressJson;
   }
-  local["FLEET-DEPLOYMENTS.md"] = fleetDocument(status, Object.keys(status.hosts), rid, at, { ledger, includeCredentials: true });
-  local["README.md"] = "# OPS 控制端\n\n主机记录位于 hosts/<host_id>/；项目关联位于 status.json；项目部署记录位于 hosts/<host_id>/deployments/<deployment_id>/；完整明文总册位于 FLEET-DEPLOYMENTS.md；凭据账本位于 private/credentials.json；执行证据按 host runs / release 保存。主机级入口见 hosts/<id>/knowledge/host-services.json，跨主机公网入口见 knowledge/public-ingress.json。\n\n不得清理此运行态目录来替换静态 workflow。双边文档完成由每次运行 docs-receipt.json 证明。\n";
+  local["FLEET-DEPLOYMENTS.md"] = fleetDocument(status, Object.keys(status.hosts), rid, at, { ledger, includeCredentials: plaintextDocumentation(status) });
+  local["README.md"] = "# OPS 控制端\n\n主机记录位于 hosts/<host_id>/；项目关联位于 status.json；项目部署记录位于 hosts/<host_id>/deployments/<deployment_id>/；总册位于 FLEET-DEPLOYMENTS.md（新安装默认仅引用凭据版本）；凭据账本位于 private/credentials.json；执行证据按 host runs / release 保存。主机级入口见 hosts/<id>/knowledge/host-services.json，跨主机公网入口见 knowledge/public-ingress.json。\n\n不得清理此运行态目录来替换静态 workflow。双边文档完成由每次运行 docs-receipt.json 证明。\n";
   local["docs/standards/DEPLOYMENT-STANDARD.md"] = STANDARD;
   if (!existsSync(join(state, "knowledge", "INDEX.md"))) {
     local["knowledge/INDEX.md"] = "# 共享知识索引\n\n只收录经用户批准、带来源与最后验证日期的通用知识。运行时环境和密码不自动提升为共享知识。跨主机入口规范见各主机 knowledge/public-ingress.json。\n";

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

@@ -237,6 +237,7 @@ export function compilePlan(state, specPath) {
     const current = load(state);
     if (current.controller == null) throw new OpsError("initialize the controller first");
     const after = structuredClone(current);
+    if (spec.plaintext_documentation !== undefined) after.policies.plaintext_documentation = spec.plaintext_documentation;
     const ledger = ledgerLoad(state);
     const revisions = spec.resource_updates || {};
     for (const [group, idkey, fixed] of [["hosts", "host_id", ["host_id", "root", "identity", "platform"]], ["projects", "project_id", ["project_id", "kind", "service_type"]]]) {
@@ -277,7 +278,12 @@ export function compilePlan(state, specPath) {
       return op;
     };
     const fileOp = (hostId, did, path, { content = undefined, binary = undefined, mode = undefined } = {}) => {
-      const data = { path, mode: mode ?? defaultFileMode(path) };
+      const secretBearing = credentialsIn(content ?? "").size > 0;
+      const selectedMode = mode ?? (secretBearing ? 0o600 : defaultFileMode(path));
+      if ((secretBearing || /(?:^|[\\/])env[\\/]/.test(path)) && (selectedMode & 0o077)) {
+        throw new OpsError("secret-bearing config/env mode must be 0600 or stricter; use explicit service ownership, not world-readable secrets");
+      }
+      const data = { path, mode: selectedMode };
       if (content !== undefined) data.content = content;
       else data.content_b64 = Buffer.from(binary).toString("base64");
       return add(hostId, did, "write", data);

package/template/workflows/specdev/common/rules/path-reference-contract.md

@@ -116,3 +116,9 @@ SpecDev 不假定运行时一定提供项目根变量。Ticket、Evidence、诊
 - 目录引用是否以 `/` 结束且文件引用是否不以 `/` 结束。
 
 路径检查通过仅表示引用结构正确，不代表工件语义、需求、设计或实现正确。
+
+## 9. 与标准 Skill 的分发边界
+
+本文件是 SpecDev 内部动态工件协议，不是通用 Agent Skills 的文件格式规范。独立标准 Skill 的静态 references/assets 使用相对路径；workflow 私有 Skill 声明 compatibility 后继续使用本 Path 合同。已有持久化引用不批量迁移。
+
+实际执行前可以使用只读 `speculo resolve <project-root> --path '<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>'` 展开单个指针。解析器先打开字面 workspace 路径，拒绝未知 alias、未替换变量、通配符、越界路径与链接跳转；不执行 shell、不授予文件写入权限。完整命令由已获授权调用方使用参数数组构造，不把 Path 标记或用户文本直接交给 shell。

package/template/workflows/specdev/common/skills/code-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
-name: specdev-code-review
+name: code-review
 description: 从不可变固定点对本地 diff 执行隔离的标准轴与规范轴审查，供独立 C Work 和 I Work 最终审查共同调用。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
+metadata: {"speculo-legacy-name": "specdev-code-review"}
 ---
 
 # SpecDev Code Review

package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dev-worktree
 description: 管理 SpecDev required Ticket 的 Git worktree；创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
 ---
 
 # Dev Worktree

package/template/workflows/specdev/common/skills/plan-quality-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
-name: specdev-plan-quality-review
+name: plan-quality-review
 description: T 发布计划型 Ticket 或 P 发布/重规划 Goal 前检查决策完备、Skill 调用和执行门禁；不执行代码审查或代替用户批准。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
+metadata: {"speculo-legacy-name": "specdev-plan-quality-review"}
 ---
 
 # Plan Quality Review

package/template/workflows/specdev/common/skills/research/SKILL.md

@@ -1,6 +1,8 @@
 ---
-name: specdev-research
+name: research
 description: 为调用 Work 的具体决定研究外部技术、依赖、标准或未知行为，逐声明返回一手来源、限制与不确定性，由调用方写入其拥有的工件。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
+metadata: {"speculo-legacy-name": "specdev-research"}
 ---
 
 # SpecDev Research

package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: subagent-delivery
 description: 仅在 Lead 规划派单合同、发出受限任务或验收其返回时调用；不是通用实现入口，外部网页交付仍为 ZIP-only。
+compatibility: Requires the owning Speculo workflow and its workspace path resolver.
 ---
 
 # Subagent Delivery