@namewta/speculo 1.0.16 → 1.0.17

package/dist/src/transaction.js

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { lstat, mkdir, rename, rm } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { fingerprintTree } from "./manifest.js";
+import { EXTERNAL_NAMES, assertImage, imageDigest, readImage, replaceImage, syncDirectory, writeDurableJson } from "./external-files.js";
+export const LOCK_NAME = ".speculo-init.lock";
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function directory(path) {
+    if (!(await exists(path)))
+        return;
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`unsafe-transaction-directory: ${path}`);
+}
+export async function assertInstallDirectory(target) {
+    await directory(join(target, "speculo"));
+}
+function journalPath(target) { return join(target, LOCK_NAME, "transaction.json"); }
+export async function readTransaction(target) {
+    await directory(join(target, LOCK_NAME));
+    const raw = await readImage(journalPath(target));
+    if (!raw)
+        throw new Error("unidentified-lock: no durable transaction; inspect owner.json and preserve all residues");
+    const j = JSON.parse(Buffer.from(raw.content, "base64").toString("utf8"));
+    if (j.schema_version !== 1 || j.target !== resolve(target) || !/^[a-f0-9-]{36}$/.test(j.id) ||
+        typeof j.host !== "string" || !Number.isSafeInteger(j.pid) || j.pid < 1 ||
+        !/^\.speculo-init-stage-[A-Za-z0-9]+$/.test(j.stage) || j.backup !== j.stage + "-backup" ||
+        !/^(absent|[a-f0-9]{64})$/.test(j.before) || !/^[a-f0-9]{64}$/.test(j.after) ||
+        !["prepared", "old-renamed", "installed", "external-finalized", "committed", "rolled-back"].includes(j.phase) ||
+        !Array.isArray(j.external) || j.external.length !== EXTERNAL_NAMES.length ||
+        new Set(j.external.map((e) => e.name)).size !== EXTERNAL_NAMES.length)
+        throw new Error("invalid-transaction-journal");
+    for (const e of j.external) {
+        if (!EXTERNAL_NAMES.includes(e.name))
+            throw new Error("invalid-transaction-external-path");
+        for (const value of [e.before, e.after]) {
+            if (value !== null && (!value || typeof value.content !== "string" || !Number.isInteger(value.mode) || value.mode < 0 || value.mode > 0o777 ||
+                Buffer.from(value.content, "base64").toString("base64") !== value.content))
+                throw new Error("invalid-transaction-file-image");
+        }
+    }
+    return j;
+}
+async function save(j, phase) {
+    await writeDurableJson(journalPath(j.target), { ...j, phase });
+    j.phase = phase;
+}
+/** Validate every source before moving any directory or restoring any external file. */
+async function rollback(j) {
+    const root = join(j.target, "speculo"), stage = join(j.target, j.stage), backup = join(j.target, j.backup);
+    for (const path of [root, stage, backup])
+        await directory(path);
+    const r = await fingerprintTree(root), s = await fingerprintTree(stage), b = await fingerprintTree(backup);
+    const untouched = r === j.before && b === "absent" && (s === j.after || s === "absent");
+    const renamed = j.before !== "absent" && b === j.before &&
+        ((r === "absent" && s === j.after) || (r === j.after && s === "absent"));
+    const newInstall = j.before === "absent" && b === "absent" && r === j.after && s === "absent";
+    if (!untouched && !renamed && !newInstall)
+        throw new Error("recovery-drift: installation layout differs from before/after evidence; preserve all directories");
+    for (const e of j.external) {
+        const digest = imageDigest(await readImage(join(j.target, e.name)));
+        if (![imageDigest(e.before), imageDigest(e.after)].includes(digest))
+            throw new Error(`recovery-drift: ${e.name}; concurrent content preserved`);
+    }
+    for (const e of [...j.external].reverse()) {
+        const current = await readImage(join(j.target, e.name));
+        await replaceImage(join(j.target, e.name), current, e.before);
+    }
+    if (!untouched) {
+        if (r === j.after)
+            await rename(root, stage);
+        if (j.before !== "absent")
+            await rename(backup, root);
+        await syncDirectory(j.target);
+    }
+    await save(j, "rolled-back");
+    if (await fingerprintTree(stage) !== "absent" && await fingerprintTree(stage) !== j.after)
+        throw new Error("recovery-drift: staged directory changed");
+    await rm(stage, { recursive: true, force: true });
+}
+async function finish(j) {
+    const root = join(j.target, "speculo"), backup = join(j.target, j.backup);
+    await directory(root);
+    await directory(backup);
+    if (await fingerprintTree(root) !== j.after)
+        throw new Error("recovery-drift: committed installation changed");
+    for (const e of j.external)
+        await assertImage(join(j.target, e.name), e.after);
+    const fingerprint = await fingerprintTree(backup);
+    if (fingerprint !== "absent" && fingerprint !== j.before)
+        throw new Error("recovery-drift: backup changed; preserve it");
+    await rm(backup, { recursive: true, force: true });
+    await syncDirectory(j.target);
+}
+export async function commitInstall(target, stagedRoot, before, external, hook) {
+    const j = { schema_version: 1, id: randomUUID(), host: hostname(), pid: process.pid, target,
+        stage: basename(stagedRoot), backup: basename(stagedRoot) + "-backup", before,
+        after: await fingerprintTree(stagedRoot), phase: "prepared", external };
+    const root = join(target, "speculo");
+    if (await fingerprintTree(root) !== before)
+        throw new Error("concurrent-drift: installation changed before commit");
+    for (const e of external)
+        await assertImage(join(target, e.name), e.before);
+    await save(j, "prepared");
+    try {
+        await hook?.("prepared");
+        if (before !== "absent")
+            await rename(root, join(target, j.backup));
+        await syncDirectory(target);
+        await save(j, "old-renamed");
+        await hook?.("old-renamed");
+        await rename(stagedRoot, root);
+        await syncDirectory(target);
+        await save(j, "installed");
+        await hook?.("installed");
+        if (await fingerprintTree(root) !== j.after)
+            throw new Error("post-install validation failed");
+        for (const e of external)
+            await replaceImage(join(target, e.name), e.before, e.after);
+        await save(j, "external-finalized");
+        await hook?.("external-finalized");
+        await save(j, "committed");
+        await hook?.("committed");
+        await finish(j);
+    }
+    catch (error) {
+        if (j.phase === "committed")
+            throw new Error(`committed-cleanup-pending: run doctor then recover with transaction ${j.id}; ${String(error)}`);
+        try {
+            await rollback(j);
+        }
+        catch (recoveryError) {
+            throw new Error(`recovery-required: transaction ${j.id}; ${String(error)}; ${String(recoveryError)}`);
+        }
+        await rm(journalPath(target));
+        throw error;
+    }
+    await rm(journalPath(target));
+}
+/** Explicit local recovery only. Never steals a live, remote-host, or unidentified lock. */
+export async function recoverInstall(targetArg, id) {
+    const target = resolve(targetArg);
+    const j = await readTransaction(target);
+    if (j.id !== id)
+        throw new Error("recovery-transaction-mismatch");
+    if (j.host !== hostname())
+        throw new Error("recovery-host-mismatch: inspect the original host before recovery");
+    try {
+        process.kill(j.pid, 0);
+        throw new Error("recovery-owner-live: stop the owning process first");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    const guard = join(target, LOCK_NAME, "recovery.lock");
+    await mkdir(guard, { mode: 0o700 });
+    let success = false;
+    try {
+        if (j.phase === "committed")
+            await finish(j);
+        else
+            await rollback(j);
+        success = true;
+        return { id, outcome: j.phase === "committed" ? "completed-cleanup" : "rolled-back" };
+    }
+    finally {
+        await rm(guard, { recursive: true, force: true });
+        if (success) {
+            await rm(join(target, LOCK_NAME), { recursive: true });
+            await syncDirectory(target);
+        }
+    }
+}
+export async function hasTransaction(target) { return exists(journalPath(target)); }
+//# sourceMappingURL=transaction.js.map

package/dist/src/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/transaction.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.js

@@ -4,8 +4,10 @@ export async function pathExists(path) {
         await access(path);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
     }
 }
 //# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IACxC,OAAO,KAAK,EAAE,CAAC;QACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACrE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/workflows.js

@@ -39,10 +39,9 @@ export async function discoverWorkflowCatalog(packageRoot) {
             });
         }
         catch (error) {
-            if (error instanceof Error && error.message.includes("ids must match")) {
+            if (error.code !== "ENOENT")
                 throw error;
-            }
-            // A directory without INDEX.md is not an installable workflow package.
+            // Only a missing INDEX.md means this is not an installable workflow package.
         }
     }
     return catalog;
@@ -74,7 +73,7 @@ export function isInteractive() {
 }
 export async function promptWorkflowSelection(catalog, options) {
     if (!isInteractive())
-        return selectAllFromCatalog(catalog);
+        return { workflowIds: [...(options?.preSelectedWorkflowIds ?? [])].filter((id) => catalog.has(id)).sort() };
     const choices = [...catalog.values()]
         .sort((left, right) => left.id.localeCompare(right.id))
         .map((workflow) => ({

package/dist/src/workflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/workflows.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/workflows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {
@@ -13,12 +13,14 @@
     "pretest": "pnpm build",
     "generate-canonical": "node scripts/generate-specdev-canonical.mjs",
     "validate-source-parity": "node scripts/check-specdev-source-parity.mjs",
-    "validate-assets": "node scripts/check-specdev-source-parity.mjs && node scripts/generate-specdev-canonical.mjs --check && node scripts/validate-refresh-contracts.mjs && node scripts/validate-framework-assets.mjs && node scripts/check-template-links.mjs && node scripts/validate-workflow-disclosure.mjs && node template/workflows/specdev/common/tools/validate-specdev.mjs --self-check && node template/workflows/learning/common/tools/validate-learning.mjs --workflow-root template/workflows/learning",
+    "validate-assets": "node scripts/validate-skills.mjs && node scripts/check-specdev-source-parity.mjs && node scripts/generate-specdev-canonical.mjs --check && node scripts/validate-refresh-contracts.mjs && node scripts/validate-framework-assets.mjs && node scripts/check-template-links.mjs && node scripts/validate-workflow-disclosure.mjs && node template/workflows/specdev/common/tools/validate-specdev.mjs --self-check && node template/workflows/learning/common/tools/validate-learning.mjs --workflow-root template/workflows/learning",
     "check": "pnpm test && pnpm validate-assets",
     "verify-bin": "node scripts/verify-bin.mjs",
     "eval:scenarios": "node scripts/evaluate-scenarios.mjs",
     "prepack": "pnpm build",
-    "prepublishOnly": "pnpm test && pnpm validate-assets"
+    "prepublishOnly": "pnpm test && pnpm validate-assets",
+    "validate-skills": "node scripts/validate-skills.mjs",
+    "validate-source-inventory": "node scripts/check-specdev-source-parity.mjs"
   },
   "files": [
     "dist/src",
@@ -53,7 +55,7 @@
     "node": ">=22.22.3 <25"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
+    "@types/node": "^22.0.0",
     "fast-xml-parser": "^5.9.3",
     "typescript": "^5.8.3"
   },

package/template/.speculo/README.md

@@ -10,12 +10,12 @@
 
 配置使用 `.speculo/baselines/` 中的上次模板默认值执行 base/local/incoming 三方合并：模板新增项自动增加，模板删除项直接删除，未被用户修改的旧默认值跟随模板更新，用户覆盖值在满足目标合同的前提下保留。只有字段删除、显式 schema 迁移或结构化文件变换时，CLI 才把原文件写入 `back/` 并生成 targeted manifest；opaque 内容不会被整包复制到备份。
 
-`install.json` 使用 schema v3，记录包版本、已安装 workflows、managed manifest 路径和 baseline schema。`kernel.json` 定义共享 change、风险、checkpoint、能力和 trace 位置。Speculo 1.0 不读取或迁移任何 0.x 安装；检测到旧 manifest 时必须先由用户移除或改名旧 `speculo/` 目录。初始化以项目锁、完整 staging、active fingerprint 复验、原子 rename 与失败 rollback 组成一个事务；冲突不会发布部分结果，也不会创建新的 pending marker。
+`install.json` 使用 schema v3，记录包版本、已安装 workflows、managed manifest 路径和 baseline schema。`kernel.json` 定义共享 change、风险、checkpoint、能力和 trace 位置。Speculo 1.0 不读取或迁移任何 0.x 安装；检测到旧 manifest 时必须先由用户移除或改名旧 `speculo/` 目录。初始化使用项目锁、完整 staging、active fingerprint、配套手册 before/after images 与持久事务阶段记录。正常异常回滚；进程中断后保留现场，通过只读 doctor 检查，再由用户显式 recover 处理。多文件交换不是对所有读者全时刻原子的，保证范围是受测试的进程中断恢复，不宣称跨平台掉电原子性。
 
 ## 读取顺序
 
-1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。嵌套安装时，项目根 `.speculo/` 不是本目录；只有该文件声明的状态根是运行时状态的唯一持久化根，项目根 `.speculo/specdev` 非法。
-2. 从 `../workflows/<workflow>/INDEX.md` 发现 workflow并按需读取其中声明的永久知识；这一步不读取 Work 条目或运行状态。
+1. 从项目根打开字面 `speculo/.speculo/workspace.json`（已在本目录时为 `workspace.json`），以当前打开项目为 `project_root` 解析公共 roots。嵌套安装时，项目根 `.speculo/` 不是本目录；只有该文件声明的状态根是运行时状态的唯一持久化根，项目根 `.speculo/specdev` 非法。
+2. 从本目录生成的 `catalog.md` 定位已安装能力，再按需读取 `../workflows/<workflow>/INDEX.md` 声明的永久知识；这一步不读取 Work 条目或运行状态。
 3. 用户明确激活 workflow 或 work 后，读取 INDEX 指向的 workflow 根 `README.md`，从其中的 Work 条目选择目标并读取具体入口文件。
 4. 按激活合同读取 `<Path>{roots.state}/{workflow}/status.json</Path>`。SpecDev/Learning 再读取当前 change `.status.json` 与 work 产物。Ops schema v3 读取 hosts/projects/deployments/allocations/bindings/releases 及对应运行记录，不创建 `changes/`。
 5. 历史 change（SpecDev/Learning）只从 `<Path>{roots.state}/{workflow}/archive/{YYYY-MM}/{change}/</Path>` 读取。Ops 运行证据在 `hosts/{host_id}/runs/{run_id}` 或 `releases/{run_id}`。
@@ -32,3 +32,9 @@
 - 独立 Skill 只写 `<Path>{roots.state}/skills/{skill}/</Path>`；一次运行目录命名为 `<YYYY-MM-DD>-<kebab-topic>[-NN]`，禁止覆盖。由 command/work 调用时改用调用方提供的 owner 路径。
 - `back/` 由 `speculo init` 单一写入；workflow 和 commands 不得修改。
 - `install.json`、`managed.json`、`baselines/` 与 refresh contract 由 CLI 拥有，workflow 不得创建、修改或删除。
+
+## 显式中断恢复
+
+`speculo doctor [target] --json` 是只读 installation-integrity 检查，验证配置、roots、manifest 与文件摘要，报告尚未检查的领域状态、宿主行为和服务健康。发现 `.speculo-init.lock/transaction.json` 时输出事务 ID 和阶段。确认原执行进程已停止后，执行 `speculo recover [target] --transaction <id>`。事务 ID、宿主、owner PID、安装 before/after hash、配套文件和目录布局必须匹配；未知锁、仍在运行的 owner、内容漂移或越界链接均保留并阻塞。
+
+committed 阶段只完成清理，其他已记录阶段恢复旧安装与旧手册。未进入持久事务的 stage/owner 锁、恢复自身被强制终止留下的 recovery.lock 或清理窗口中的不完整记录须人工核对，不能仅凭锁龄删除。严禁 rm 未识别备份来“解除阻塞”。项目目录必须可信；这不是阻止同账户恶意进程竞态的沙箱。POSIX 使用文件与目录 fsync，Windows 没有通用目录 fsync，掉电恢复需要宿主备份策略。

package/template/.speculo/refresh-contract.json

@@ -10,7 +10,9 @@
     ".speculo/README.md",
     ".speculo/workspace.json",
     ".speculo/refresh-contract.json",
-    ".speculo/kernel.json"
+    ".speculo/kernel.json",
+    ".speculo/AGENTS.md",
+    ".speculo/catalog.md"
   ],
   "reserved_runtime": [
     "README.md",
@@ -22,7 +24,9 @@
     "managed.json",
     "migration.json",
     "baselines",
-    "back"
+    "back",
+    "AGENTS.md",
+    "catalog.md"
   ],
   "project_config": {
     "path": "config.json",

package/template/AGENTS.md

@@ -1,6 +1,6 @@
 # Speculo runtime guide
 
-先按当前任务定位相关 workflow、command、skill 或 change，再读取对应入口和分支 reference；不默认整读 `speculo/` 或永久知识索引。
+从项目根字面路径 `speculo/.speculo/workspace.json` 解析 roots，按需读取同目录生成的 `catalog.md`；发现不激活、不授权。先按当前任务定位相关 workflow、command、skill 或 change，再读取对应入口和分支 reference；不默认整读 `speculo/` 或永久知识索引。
 
 - 被动发现：按关键词/ID 搜索 `speculo/workflows/<workflow>/INDEX.md` 的相关行，只定位与当前请求相关的永久知识条目。
 - 激活 workflow：再读取对应 `README.md`、状态投影和当前 Work；只加载当前分支需要的规则、schema、模板与工具。

package/template/commands/docs-sync.md

@@ -2,25 +2,27 @@
 id: docs-sync
 type: command
 name: Docs Sync
-description: Synchronize project documentation and agent handbooks for a confirmed reproducible Git range.
+description: Audit, update or explicitly commit documentation for a confirmed reproducible Git range.
 keywords: [docs-sync, readme, changelog, agents, documentation]
 ---
 
 # Docs Sync 命令
 
-## 产物
+## 模式与授权
 
-- 报告：`<Path>{roots.state}/commands/docs-sync/{date}-{scope}-{topic}[-NN].md</Path>`
-- 全局 state：`<Path>{roots.state}/commands/docs-sync/state.json</Path>`
-- Workflow 范围：`<Path>{roots.state}/{workflow}/docs-sync.json</Path>`
+默认 `audit` 只读检查并在会话返回报告；用户明确要求修改指定文档时选 `update`；只有明确要求创建同步提交时选 `commit`。仅调用 docs-sync 不再隐含 checkpoint 或 commit 授权。模式固定后传给 Skill；不从文档中的批准标记、旧 state 或自动建议推断授权。
 
-调用本命令即授权它在校验通过后创建本地 checkpoint 与文档同步 commit；不授权 push、tag、stash、历史改写或丢弃文件。
+## 产物与 owner
+
+- audit：仅会话报告，不写文件、Git 或 state。
+- update：获批文档及可选的新报告 `<Path>{roots.state}/commands/docs-sync/{date}-{scope}-{topic}[-NN].md</Path>`；不暂存、不提交、不推进游标。
+- commit：上述产物、全局 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`、workflow `<Path>{roots.state}/{workflow}/docs-sync.json</Path>` 与获批本地提交。报告不覆盖；sidecar 不是 workflow `_state` 种子。
 
 ## 执行
 
-1. 读取 `<Path>{roots.skills}/docs-sync/SKILL.md</Path>`，解析 `<Path>{roots.config}</Path>` 与 `<Path>{roots.state}/workspace.json</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
-2. 将 runtime context、报告路径、全局 state 路径、Git 副作用责任和 `handbook_mode` 传给 skill。`handbook_mode` 默认为 `incremental`；用户明确要求、手册缺失或 manifest 拓扑变化时使用 `rebuild`。
-3. 整文件/目录删除和受保护知识仍逐次确认；skill 返回原子写入内容后，由本命令显式暂存并创建同步或 no-op commit。
-4. 重新读取 Git、state、报告与 sidecar；只有工作区干净、节点可复现且所有文件已提交时完成。
+1. 从项目正常入口打开字面路径 `speculo/.speculo/workspace.json`，再解析 `<Path>{roots.config}</Path>` 和公共 roots。缺 workspace 时阻塞 runtime 写入，不猜测状态根；独立只读文档分析可继续并报告缺失。
+2. 读取 `<Path>{roots.skills}/docs-sync/SKILL.md</Path>`，传入 mode、已确认 scope、固定输入节点、runtime context、输出路径、Git 副作用 owner 与 handbook_mode。默认 incremental；重建只由明确要求、缺失手册或 manifest 拓扑变化触发。
+3. 按 Skill 的当前模式完成生命周期与写作分支。整文件/目录删除、受保护知识和越界链接仍分别确认。只有 commit 由本命令显式暂存已核对路径、创建同步或 no-op commit。
+4. 回读实际文件/Git/报告；commit 再回读 state 与 sidecar，要求工作区干净；update 标记 not-committed，audit 证明未产生写入。所有模式报告验证、未运行项和停止点，不授权 push/tag/stash/丢弃文件/历史改写。
 
-完成标准：报告含输入节点、checkpoint、确认范围、handbook mode、生命周期动作和验证；全局 state 与每个 workflow sidecar 有效；`git status --short` 为空。
+完成标准：模式与真实用户授权一致，输入可定位、scope 有唯一 owner，实际结果与模式匹配。未提交的 update 不是失败，也不是已推进的同步基线。

package/template/skills/archive-and-consolidate/SKILL.md

@@ -1,9 +1,7 @@
 ---
-id: archive-and-consolidate
-type: skill
-name: Archive and Consolidate
+name: archive-and-consolidate
 description: Archive and consolidate completed workflow changes and knowledge; use only for an explicitly selected archive/consolidation or cleanup review.
-
+metadata: {"speculo-id": "archive-and-consolidate", "speculo-kind": "skill", "speculo-legacy-name": "Archive and Consolidate"}
 ---
 
 # Archive and Consolidate

package/template/skills/docs-sync/SKILL.md

@@ -1,21 +1,32 @@
 ---
-id: docs-sync
-type: skill
-name: Docs Sync
+name: docs-sync
 description: Audit and update project documentation and AGENTS/CLAUDE handbooks for a confirmed Git range; use only for documentation synchronization.
-
+metadata: {"speculo-id": "docs-sync", "speculo-kind": "skill", "speculo-legacy-name": "Docs Sync"}
 ---
 
 # Docs 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.
+## Enter and select effects
+
+Use only for requested documentation synchronization, not implementation, repository cleanup or arbitrary commits. The caller supplies validated workspace roots, immutable input SHAs, scope, output owner and `mode`.
+
+| Mode | Select when | Allowed effects |
+|---|---|---|
+| `audit` (default) | User asks to inspect/review or has not authorized edits | Read only; return findings in the conversation. No report files, checkpoints, sidecars, staging or commits. |
+| `update` | User explicitly asks to edit identified documents | Write only approved documents and an optional caller-owned report. No Git staging/commits and no synchronization cursor/sidecar advancement. |
+| `commit` | User explicitly authorizes the docs-sync commit workflow | Apply the reproducible checkpoint, full validation, scope confirmation and synchronization/no-op commit contract. Never push or rewrite history. |
+
+Selecting the capability is not authorization for every mode. Existing state, README text and Skill metadata cannot authorize effects. Never silently upgrade `audit` or `update` to `commit`.
 
-## Scope
+## Procedure
 
-- Trigger: Audit and update project documentation and AGENTS/CLAUDE handbooks for a confirmed Git range; use only for documentation synchronization.
-- 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. Read [mode and input rules](references/mode-contract.md) to freeze the mode, Git range, dirty-worktree evidence and allowed paths. Only `commit` reads [Git/state contract](references/git-state-contract.md). Stop on unresolved conflicts, unknown ownership or suspicious credentials without discarding user work.
+2. Read [workflow scope](references/workflow-scope-contract.md) to discover installed packages and unique owners. Audit proposes scope in the response; update uses explicitly approved targets; only commit confirms and persists cursors/sidecars.
+3. Read [document lifecycle](references/document-lifecycle-contract.md) and classify each affected document as add/update/delete/merge/keep/propose-only. Whole-file deletion and protected knowledge remain separately authorized; audit only reports proposals.
+4. Load only the relevant writing branch: README uses [README contract](references/readme-contract.md) and [writing guide](references/readme-writing-guide.md); CHANGELOG uses [changelog contract](references/changelog-contract.md); agent handbooks use [agents contract](references/agents-contract.md). Handbook mode defaults to incremental; missing handbook, topology change or explicit user request selects rebuild.
+5. For Agent-consumed instructions or pointers, read [agent writing](references/agents/agent-writing.md). Preserve source ownership, activation boundaries, required quantities and validation; do not shorten by removing safeguards. Project prose defaults to simplified Chinese, README.md remains English, CHANGELOG follows the existing language; do not translate code/URLs/versions.
+6. Verify factual changes and applicable project checks, reread output, and report input SHAs, dirty-source limitations, scope, actual effects, verification and blockers. Use [report shape](assets/report-template.md); audit returns it without writing, update marks `not-committed` and does not advance state, commit additionally returns [state](assets/state-template.json) and [workflow scope](assets/workflow-scope-template.json) for the owning command to commit and reread.
 
-## Stop
+## Stop and return
 
-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.
+Missing scope, source ownership, required reference, permission, validation or recovery evidence stops the affected write set. Do not fabricate completion or clean unrelated work. A report and a green structure check are not proof that the underlying documentation is correct. Return results to the declared caller; do not create an independent Skill state tree.

package/template/skills/docs-sync/references/agents-contract.md

@@ -2,6 +2,8 @@
 
 本契约用于差量维护或重建已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。调用方传入 `handbook_mode=incremental|rebuild`；默认使用 `incremental`，仅在用户显式要求、手册缺失或 manifest 拓扑变化时进入 `rebuild`。
 
+调用方的 `mode=audit|update|commit` 控制实际效果；以下“生成/修改/修复”在 audit 中只表示候选报告，不产生写入。在 update 中不写游标、不提交。handbook_mode 仅控制分析/构建方式，不升级动作授权。
+
 ## 分支路由
 
 ### Incremental
@@ -22,7 +24,7 @@
 
 展示创建、更新和删除候选；整文件删除或把多行 CLAUDE.md 改成重定向前取得明确确认。
 
-**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，每个 AGENTS.md 有唯一 CLAUDE.md 重定向，父子 routing 完整，所有处置均有证据和确认状态。
+**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，需该适配的目录有唯一 CLAUDE.md 重定向（不强迫所有宿主增加无用手册），父子 routing 完整，所有处置均有证据和确认状态。
 
 ## 内容优先级
 
@@ -37,7 +39,7 @@
 - 命令、版本、目录、入口、测试、发布或持久化事实变化时，修改或删除对应陈述。
 - 陷阱已被代码或工具消除时删除；同一错误尚未真实发生时不预先堆规则。
 - 每行执行删除测试：“删除后是否会使代理更可能犯错？”答案为否就删除或改为权威链接。
-- 根手册以约 200 行为目标；超过 300 行必须拆到就近手册或权威文档，而不是继续追加。
+- 根手册以紧凑项目事实为目标，行数仅作诊断信号，不是强制删改门。每次必读的简短规则保留，分支细则按明确条件下沉；用实际读取与行为验证决定拆分，不以行数牺牲安全或必要上下文。
 - 使用明确条件和祈使句；安全边界可使用“禁止/不得”，不要把所有偏好写成铁律。
 
 ## AGENTS 与 CLAUDE
@@ -51,8 +53,8 @@
   ```
 
 - 所有代理指令、事实和规则写入 `AGENTS.md`，不把 `CLAUDE.md` 当作权威内容载体。
-- 现有多行 `CLAUDE.md` 经用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`。
-- `AGENTS.md` 不得被缩减为指向 `CLAUDE.md` 的重定向——发现即修复。
+- 现有多行 `CLAUDE.md` 只在用户确认迁移后改写为重定向，原内容全量迁移到 `AGENTS.md`；普通同步默认保留。宿主专属语法由适配层承担，不宣称普通 Markdown 链接自动导入适用于全部宿主。
+- `AGENTS.md` 不应被缩减为指向 `CLAUDE.md` 的重定向；audit 报告问题，只有获准 update/commit 才修复。
 - Monorepo 使用就近手册覆盖；父级只导航，不复制子模块细节。
 
 ## 验证

package/template/skills/docs-sync/references/document-lifecycle-contract.md

@@ -1,5 +1,7 @@
 # 文档生命周期契约
 
+audit 中的所有生命周期动作仅作为候选报告；update 仅写获批目标且不推进 state；commit 才执行完整同步提交。本文不改变调用方 mode 或 workflow 原有知识权限。
+
 Diff 只负责发现变化；文档结论必须来自当前源码、配置、测试、CI、发布元数据、workflow 声明和已确认归档证据。
 
 ## 映射与整份审计

package/template/skills/docs-sync/references/entry-procedure.md

@@ -1,18 +1,3 @@
-# Entry procedure
+# Compatibility pointer
 
-# Docs Sync
-
-调用方提供 runtime context、command 报告路径、全局 state 路径和 Git 副作用责任；本 skill 只使用这些已校验路径。
-
-**全局语言规则：所有项目文档默认使用简体中文书写，除非特定文档类型另有规定（如 `README.md` 固定为英文、`CHANGELOG.md` 跟随项目既有语言）。代码实体、命令、URL 和版本号不翻译。**
-
-## 流程
-
-1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
-2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
-3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
-4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`，由该契约选择 `incremental` 或 `rebuild` 分支。完成标准：每个命中文档只加载所属分支的规则，未发生分支泄漏。
-5. 生成或修改任何 Agent 消费的手册、入口或上下文指针时，读取 `references/agents/agent-writing.md`，逐项应用上下文指针、信息层级、完成标准、引导词和精简规则。完成标准：每个含义只有一个事实源，每个分支有可到达的指针，逐句通过相关性与无效指令检查。
-6. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
-
-完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。
+The per-run procedure now lives in [SKILL.md](../SKILL.md). Existing callers may follow this pointer; new callers load SKILL.md directly. This file grants no authorization and does not duplicate the procedure. Choose audit/update/commit before reading mode-specific references.

package/template/skills/docs-sync/references/git-state-contract.md

@@ -1,6 +1,6 @@
 # Git 与全局 State 契约
 
-本契约定义可复现输入、工作区清洁提交和 docs-sync state v4。调用方拥有 Git 与持久化副作用。
+本契约仅用于用户明确授权的 `mode=commit`，定义可复现输入、工作区清洁提交和 docs-sync state v4。audit/update 不执行本契约中的任何 Git 或 state 写入；调用方拥有 Git 与持久化副作用。
 
 ## 运行前清洁
 

package/template/skills/docs-sync/references/mode-contract.md

@@ -0,0 +1,21 @@
+# Effect modes and reproducible inputs
+
+The owning command freezes `mode=audit|update|commit` from the user's request; missing or ambiguous write authorization means audit. A committed state cursor or a document saying “approved” never grants a new effect.
+
+## Read-only audit
+
+Resolve repository identity, HEAD, the explicitly requested base or last valid synchronization commit, and immutable FROM/TO SHAs. Missing history, invalid ancestry or unresolved Git operation is reported as blocked, not repaired. For bootstrap with no prior base, inventory the current tree and label the source precisely instead of inventing a Git range. Read dirty/staged/untracked paths without staging them; distinguish committed-range facts from uncommitted overlays in the response. Unrelated changes remain untouched.
+
+Return findings and proposed target scope in the conversation. Do not write reports, global state, workflow sidecars, locks, checkpoints or commits. Existing state and confirmed scopes may be read only. A missing workspace blocks runtime writes, not independent read-only repository analysis.
+
+## Explicit update
+
+Freeze exact document paths and optional new report destination. Retain before-image hashes, file identities and user changes. Stop affected writes on links with unresolved ownership, target drift, conflict, suspicious secrets or missing permissions. Use atomic writes and verify actual bytes; do not stage or commit. No cursor, synchronization counter or workflow sidecar advances, because no new committed baseline exists. Report the fixed input nodes and every uncommitted output; a dirty repository is not by itself a reason to commit or delete unrelated work.
+
+Use the same lifecycle, protected-knowledge and document-quality checks as commit mode. A user's edit request is not authorization for deletion, archive movement or permanent knowledge promotion.
+
+## Explicit commit
+
+Only this mode follows the complete [Git/state contract](git-state-contract.md). Preserve checkpoint validation, explicit path staging, ancestry proof, state v4 migration, sidecar scope confirmation, no-op synchronization commit and clean-workspace postcondition. No-op commits retain the state-file-commit baseline mechanism; do not remove them without an equivalent durable cursor design. Existing unrelated work, unclassified untracked files, secrets or failed validation still block without stash/reset/clean.
+
+The command owns Git effects and report/state locations. Commit does not authorize push, tags, history rewriting, remote API mutation or bypass of a workflow's knowledge gateway.

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -2,16 +2,18 @@
 
 docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
 
+模式边界：audit 只报告候选；update 只使用本次明确批准的目标且不写 sidecar；以下所有 sidecar 创建、迁移和确认持久化仅用于 commit。
+
 ## 发现
 
 1. 从 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>` 发现已安装 workflow。
 2. 每个包必须有匹配的 `<Path>{roots.state}/{workflow}/</Path>` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取 `INDEX.md` 中声明的运行时根、持久化约定、固定 archive 和知识 store。
+3. 读取 `INDEX.md` 的发现声明；仅需解析合同或写入 owner 时，再按该入口显式指向的 README/contract 读取对应部分，不假设每个 INDEX 都包含运行合同。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
 ## Sidecar v1
 
-每个已安装 workflow 首次 docs-sync 都创建：
+每个已安装 workflow 首次获准的 commit 同步才创建：
 
 ```json
 {
@@ -47,4 +49,4 @@ docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 comm
 - `existing-only` store 永远只读。RULES/policy、ADR、CONTEXT、语义冲突和任何知识文件删除均进入 `propose-only`，按目标 workflow 规则取得逐次确认。
 - 不跨 workflow 搬运知识；共享结论必须先确认唯一归属。
 
-完成标准：所有已安装 workflow 都有有效 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。
+完成标准：commit 模式所有已安装 workflow 都有有效 sidecar；audit/update 不产生 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。