@namewta/speculo 0.8.13 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.8.13",
+  "version": "1.0.2",
   "description": "Workflow-packaged AI collaboration assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {
@@ -13,9 +13,10 @@
     "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",
+    "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",
     "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"
   },
@@ -49,7 +50,7 @@
   },
   "packageManager": "pnpm@11.1.3",
   "engines": {
-    "node": "22.22.3"
+    "node": ">=22.22.3 <25"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",

package/template/.speculo/README.md

@@ -10,7 +10,7 @@
 
 配置使用 `.speculo/baselines/` 中的上次模板默认值执行 base/local/incoming 三方合并：模板新增项自动增加，模板删除项直接删除，未被用户修改的旧默认值跟随模板更新，用户覆盖值在满足目标合同的前提下保留。只有字段删除、显式 schema 迁移或结构化文件变换时，CLI 才把原文件写入 `back/` 并生成 targeted manifest；opaque 内容不会被整包复制到备份。
 
-`install.json` 使用 schema v2，记录包版本、已安装 workflows、managed manifest 路径和 baseline schema。初始化以项目锁、完整 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 复验、原子 rename 与失败 rollback 组成一个事务；冲突不会发布部分结果，也不会创建新的 pending marker。
 
 ## 读取顺序
 

package/template/.speculo/capabilities.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": 1,
+  "model": {
+    "id": "unknown",
+    "provider": "unknown",
+    "modalities": ["text"],
+    "context_window": 0,
+    "max_output": 0,
+    "reasoning_levels": []
+  },
+  "tools": {"classes": ["read-only"], "parallel": false, "programmatic": false},
+  "execution": {"sandbox": false, "network": false, "filesystem_roots": [], "data_retention": "session"},
+  "memory": {"compaction": false, "persistent": true, "cache": false}
+}

package/template/.speculo/kernel/README.md

@@ -0,0 +1,10 @@
+# Speculo Runtime Kernel
+
+The kernel is the provider-neutral persistence contract shared by every workflow.
+
+- `events.jsonl` is append-only and records transitions, tools, approvals and evidence.
+- `context/checkpoint.json` is the minimum recovery input after compaction or session loss.
+- `capabilities.json` is a model/tool/sandbox capability snapshot captured at run start.
+- `trace/` stores immutable run traces used by offline scenario evaluation.
+
+Workflow packages declare stages and domain artifacts; they do not redefine lifecycle, risk, approval, or recovery semantics.

package/template/.speculo/kernel/capability-profile.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:kernel:capability-profile:v1",
+  "type": "object",
+  "required": ["schema_version", "model", "tools", "execution", "memory"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "model": {"type": "object", "required": ["id", "modalities", "context_window", "max_output", "reasoning_levels"]},
+    "tools": {"type": "object", "required": ["classes", "parallel", "programmatic"]},
+    "execution": {"type": "object", "required": ["sandbox", "network", "filesystem_roots", "data_retention"]},
+    "memory": {"type": "object", "required": ["compaction", "persistent", "cache"]}
+  },
+  "additionalProperties": false
+}

package/template/.speculo/kernel/checkpoint.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:kernel:checkpoint:v1",
+  "type": "object",
+  "required": ["schema_version", "change_id", "stage", "locked_decisions", "open_questions", "next_action", "evidence", "state_digest", "created_at"],
+  "properties": {"schema_version": {"const": 1}, "change_id": {"type": "string"}, "stage": {"type": "string"}, "locked_decisions": {"type": "array", "items": {"type": "string"}}, "open_questions": {"type": "array", "items": {"type": "string"}}, "next_action": {"type": "string"}, "evidence": {"type": "array", "items": {"type": "string"}}, "state_digest": {"type": "string"}, "created_at": {"type": "string", "format": "date-time"}}
+}

package/template/.speculo/kernel/trace-event.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:kernel:trace-event:v1",
+  "type": "object",
+  "required": ["schema_version", "sequence", "at", "kind", "payload"],
+  "properties": {"schema_version": {"const": 1}, "sequence": {"type": "integer", "minimum": 1}, "at": {"type": "string", "format": "date-time"}, "kind": {"enum": ["capability", "context", "tool", "transition", "approval", "evidence"]}, "payload": {"type": "object"}},
+  "additionalProperties": false
+}

package/template/.speculo/kernel/workflow-manifest.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:kernel:workflow-manifest:v1",
+  "type": "object",
+  "required": ["schema_version", "id", "version", "stages"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "id": {"type": "string"},
+    "version": {"type": "string"},
+    "stages": {"type": "array", "items": {"type": "object", "required": ["id", "after", "inputs", "outputs", "risk", "context_budget"]}}
+  },
+  "additionalProperties": false
+}

package/template/.speculo/kernel.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "runtime": "speculo-kernel",
+  "change_lifecycle": ["draft", "active", "blocked", "awaiting_user", "completed", "archived", "cancelled"],
+  "risk_classes": ["read-only", "local-reversible", "local-destructive", "external-mutation", "production-critical"],
+  "event_log": ".speculo/events.jsonl",
+  "checkpoint": ".speculo/context/checkpoint.json",
+  "capability_profile": ".speculo/capabilities.json",
+  "trace": ".speculo/trace/"
+}

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

@@ -9,12 +9,15 @@
   "managed_metadata": [
     ".speculo/README.md",
     ".speculo/workspace.json",
-    ".speculo/refresh-contract.json"
+    ".speculo/refresh-contract.json",
+    ".speculo/kernel.json"
   ],
   "reserved_runtime": [
     "README.md",
     "workspace.json",
     "refresh-contract.json",
+    "kernel.json",
+    "kernel",
     "install.json",
     "managed.json",
     "migration.json",

package/template/AGENTS.md

@@ -1,4 +1,12 @@
-# AGENTS.md
+# Speculo runtime guide
 
-<SPECULO>
-</SPECULO>
+先按当前任务定位相关 workflow、command、skill 或 change，再读取对应入口和分支 reference；不默认整读 `speculo/` 或永久知识索引。
+
+- 被动发现：读取 `speculo/workflows/<workflow>/INDEX.md`，只定位与当前请求相关的永久知识条目。
+- 激活 workflow：再读取对应 `README.md`、状态投影和当前 Work；只加载当前分支需要的规则、schema、模板与工具。
+- 记忆检索：先定位索引 entry，再回读少量原文和 provenance；没有匹配证据时停止猜测。
+- 记忆写入：先解析 owner/gateway，检查 pending transaction、lock 和 recovery evidence；网关未知时阻塞该写入并继续独立工作。
+- 只读探索、静态编辑和本地测试可直接进行；提交、推送、发布、部署、远程写入、归档移动、永久知识改写和不可逆操作必须由拥有该动作的入口取得明确授权。
+- 失败、漂移、schema 冲突、越界路径或 owner 不明时停止受影响分支，保留证据并报告恢复路径。
+
+详细状态、所有权和副作用合同由各 workflow 的 `INDEX.md`、`README.md`、`common/rules/` 和 schema 定义。

package/template/canonical/canonical-specdev-goal-plan.md

@@ -19,6 +19,13 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情：整体 Outcome、
 
 产物写入 `specdev/changes/{change}/goal-plan.md`。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 何时运行
 
 满足任一条件时运行：
@@ -38,7 +45,7 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情：整体 Outcome、
 
 - `specdev/changes/{change}/spec.md`
 - `specdev/changes/{change}/tickets-map.md`
-- `specdev/changes/{change}/ticket/`
+- `specdev/changes/{change}/ticket/`：先枚举 Ticket 入口的 frontmatter、依赖和状态，按 DAG、路径和风险定位需要完整读取的 Ticket。
 - `specdev/config.json`
 
 按存在情况读取：
@@ -51,6 +58,8 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情：整体 Outcome、
 - 永久领域上下文：`specdev/context/`
 - 用户提供的合同、标准、参考实现、环境限制、发布窗口和批准策略。
 
+非当前分支的 ADR、CONTEXT、LOG、Diagnosis、Evidence、研究资料和永久目录先通过索引、状态和关键词定位；只有被当前 Gate、依赖、冲突或恢复条件命中的条目才回读原文。Tickets Map、当前计划和决定 DAG 的 Ticket frontmatter 是权威编排输入，仍需完整读取。
+
 永久目录可以为空，静默继续。缺少 Spec 或 Tickets Map 时返回 “编写 Spec 阶段” 或 “拆分 Tickets 阶段”；当前 ADR/CONTEXT 缺失且规划依赖对应决定时返回 “设计访谈能力”，不在 Goal Plan 中补造上游权威。
 
 ## 流程

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -19,6 +19,13 @@
 
 本 work 只把访谈写成当前 change 的可恢复工件：设计树保存进度，LOG 保存讨论轨迹，CONTEXT 保存本 change 已确认的规范语言，ADR 保存已成为本 change 下游合同的架构决定。这些工件不等于项目永久知识，也不构成实现授权；永久 namespace 对 G 只读，只有 “归档与沉淀阶段” 能在实现证据、毕业评估和用户确认通过后执行提升。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 输入与产物
 
 按存在情况读取：

package/template/canonical/canonical-specdev-orchestrate-implementation.md

@@ -19,6 +19,13 @@
 
 父 change 的主产物是 `specdev/changes/{change}/implementation-map.md` 与 `specdev/changes/{change}/implementation-plan.md`；整体验证写入 `specdev/changes/{change}/evidence/implementation-orchestration.md`。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 激活输入
 
 创建模式必须获得至少两个用户明确指定的 change。恢复模式由用户指定父 change，或从 active change 中唯一满足 `current_work=specdev/orchestrate-implementation` 且存在父实现产物者确定。
@@ -29,10 +36,12 @@
 - 每个成员的 `specdev/changes/{member-change}/.status.json`；
 - 每个成员的 `specdev/changes/{member-change}/spec.md`；
 - 每个成员的 `specdev/changes/{member-change}/tickets-map.md`；
-- 每个成员的 `specdev/changes/{member-change}/ticket/`；
+- 每个成员的 `specdev/changes/{member-change}/ticket/`：先枚举所有 Ticket frontmatter、依赖、状态和可写路径，再按 super-DAG、冲突和当前 frontier 回读相关正文；
 - 存在时读取子 Goal Plan、ADR、CONTEXT、LOG、Diagnosis 与 Evidence；
 - 当前 repository、branch、HEAD、dirty 状态、项目 Agent 指令与可用验证命令。
 
+成员的 Spec、Tickets Map、Ticket frontmatter、状态和父级编排证据是 super-DAG 的权威输入，必须完整读取；成员的 ADR、CONTEXT、LOG、Diagnosis、Evidence、研究资料和项目 Skills 先按索引、状态和关键词定位，只读取命中的条目。恢复、冲突、漂移和集成失败时按本 Work 的证据合同扩展为全量读取。
+
 加载 下方 `<input-readiness>` 标签 和 下方 `<parent-implementation-orchestration>` 标签。任何成员未实现就绪、已归档、等于父 change、属于另一个未完成父实现 change，或本身是父实现 change 时，不创建父 change。
 
 ## 流程
@@ -438,6 +447,13 @@ ready_for_execution: true
 
 若当前 change 是未完成父 Implementation Map 的成员，必须读取 下方 `<parent-implementation-orchestration>` 标签、父 Map 与父 Plan。父 Plan 提供跨 change dependency/serialization、全局 workspace 策略、组合派单标识、implementation agent cap 和 integration queue；子 Goal Plan 只能增加子内 Gate，不能放宽或冲突。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 执行模式
 
 ### Ticket 模式（默认）
@@ -629,7 +645,7 @@ Ticket 模式返回 Ticket/change 状态、Evidence 完整路径、workspace loc
 
 - [ ] Ticket frontmatter 可解析，`ready: true`，`status: ready`。
 - [ ] Tickets Map 已完整读取，包含总体实施背景和项目 Skill 读取矩阵；当前 Ticket 被 `ALL` 或自身 ID 覆盖。
-- [ ] 当前 Ticket 映射的项目 Skill 路径均为真实存在的项目根相对入口文件，Lead 已完整读取；implementation subagent Packet 包含 Map 与同一最低必读集合。
+- [ ] 当前 Ticket 映射的项目 Skill 路径均为真实存在的项目根相对入口文件，Lead 已读取入口并完整展开命中的 Skill；implementation subagent Packet 包含 Map 与同一最低必读集合。
 - [ ] 项目 Agent 指令或当前实现范围没有触发矩阵外的未读项目 Skill；发现新匹配项时由 Lead 更新 Map、重新运行 tickets 校验后再恢复项目写入。
 - [ ] 所有 `blocked_by` Ticket 为 done 且 Evidence 存在。
 - [ ] Spec、ADR、Ticket 与 Goal Plan 无冲突；旧 Goal Plan schema 必须重跑 P-goal-plan。

package/template/canonical/canonical-specdev-spec.md

@@ -17,6 +17,13 @@
 
 Spec 决定“为什么、为谁、系统应表现为何”。它可以锁定影响公共接口、数据、兼容、安全或验收的实现约束，但不写逐文件施工计划。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 输入
 
 按存在情况读取：

package/template/canonical/canonical-specdev-tickets.md

@@ -17,6 +17,13 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 
 本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 输入
 
 优先读取：
@@ -37,7 +44,7 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 
 ### 1. 输入预检
 
-1. 读取所有存在的上游工件；
+1. 先读取上游工件索引，按当前 Ticket 的依赖、缺口和冲突关键词定位，再回读相关工件；
 2. 检查 `specdev/changes/{change}/spec.md` 的 `ready_for_tickets`；
 3. 按 下方 `<artifact-contract>` 标签 处理 Spec、ADR、用户决定与代码事实的冲突；
 4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节；
@@ -61,8 +68,8 @@ Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、
 #### 项目 Skill 路由
 
 1. 读取项目 Agent 指令，确定项目声明的 Skill 根；至少枚举 `.agents/skills/**/SKILL.md`，存在其他项目级 Skill 根时一并枚举；
-2. 先读取候选 Skill 的 frontmatter 与入口路由；存在 `.agents/skills/engineering-standards/SKILL.md` 时完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
-3. 根据整个 change 和每个 Ticket 的路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
+2. 先读取候选 Skill 的 frontmatter 与入口路由；只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
+3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
 4. 使用项目根相对 Path 记录每个 Skill 的入口文件，同时记录触发 scope、读取时机和用途；不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill；
 5. 未发现适用项目 Skill 时，记录已扫描的 Skill 根和“无适用项”，不生成虚假路径；项目 Skill 清单是最低集合而非 allowlist。
 
@@ -397,7 +404,7 @@ shared_path_owners: []
 - **上游 Spec：** `specdev/changes/{change}/spec.md`
 - **完成 Evidence：** `specdev/changes/{change}/evidence/T-01.md`
 
-实现本 Ticket 时，Lead 与 implementation subagent 必须按顺序完整读取总体 Map、其中适用于 `ALL`/`T-01` 的项目 Skill，再读取本 Ticket 与其他上游工件。Map 中的 Skill 是最低必读集合；新的匹配项先由 Lead 同步到 Map 并重新校验。
+实现本 Ticket 时，Lead 与 implementation subagent 必须按顺序完整读取总体 Map，读取项目 Skill 的 frontmatter 与入口并只展开适用于 `ALL`/`T-01` 的匹配项，再读取本 Ticket 与相关上游工件。Map 中的 Skill 是最低必读集合；新的匹配项先由 Lead 同步到 Map 并重新校验。
 
 ## 1. 战略与来源
 
@@ -496,7 +503,7 @@ E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不
 ## 10. 验收标准
 
 - [ ] `AC-001`：<可判定结果>。
-- [ ] 实现开始前已完整读取 Tickets Map 及其中适用于 `ALL`/`T-01` 的项目 Skill；新发现的匹配 Skill 已由 Lead 同步回 Map。
+- [ ] 实现开始前已完整读取 Tickets Map，已读取项目 Skill 入口并完整展开其中适用于 `ALL`/`T-01` 的匹配项；新发现的匹配 Skill 已由 Lead 同步回 Map。
 - [ ] 验证矩阵全部执行并记录到 `specdev/changes/{change}/evidence/T-01.md`。
 - [ ] 实际项目修改未超出 `writable_paths`，shared path 由指定 owner 修改。
 - [ ] Ticket 已按 Goal Plan 策略形成非空 implementation/source commit，direct-parent 或 candidate 验证通过且父分支 result 已记录。
@@ -537,7 +544,7 @@ status: draft
 
 ### 项目 Skill 读取矩阵
 
-每个 Ticket 的 Lead 或 implementation subagent 都必须先完整读取本 Map，再读取下表中适用于 `ALL` 或当前 Ticket ID 的项目 Skill，最后进入当前 Ticket。下表是发布时已确认的**最低必读集合，不是 Skill allowlist**；项目 Agent 指令或实现范围触发其他项目 Skill 时，先读取该 Skill，并由 Lead 更新本 Map、重新校验后继续。
+每个 Ticket 的 Lead 或 implementation subagent 都必须先完整读取本 Map，再读取候选项目 Skill 的 frontmatter 与入口；只有适用于 `ALL` 或当前 Ticket ID、且 scope/路径/技术域/验证条件命中的 Skill 才完整读取，最后进入当前 Ticket。下表是发布时已确认的**最低必读集合，不是 Skill allowlist**；项目 Agent 指令或实现范围触发其他项目 Skill 时，先定位并读取其入口，由 Lead 更新本 Map、重新校验后继续。
 
 项目 Skill 使用项目根相对 Path，例如 `.agents/skills/{skill-name}/SKILL.md`；不得写机器绝对路径。若没有适用项目 Skill，保留一行 `无（已扫描项目 Skill 入口，未发现适用项）`，并在 Trigger / Scope 中记录实际扫描范围。
 

package/template/canonical/canonical-specdev-wayfinder.md

@@ -17,6 +17,13 @@
 
 目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
 
+## 读取范围
+
+1. 先读取 SpecDev 的激活合同 与当前 Work 的状态入口。
+2. 再读取 SpecDev 的按需读取与记忆写入协议，按当前分支、状态和关键词定位最小相关工件。
+3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
+
+
 ## 核心纪律
 
 ### 规划，而非执行

package/template/commands/archive-and-consolidate.md

@@ -2,59 +2,31 @@
 id: archive-and-consolidate
 type: command
 name: Archive and Consolidate
-description: >
-  归档已完成 change，从归档中提取知识合并到 workflow 声明的知识 store（如 adr/、context/），
-  并清理过时/重复知识。默认 dry-run，需用户确认后执行。
-keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并, 清理, 收尾]
+description: Archive or consolidate a user-selected completed change and its knowledge under the owning workflow contract.
+keywords: [archive, consolidate, learning, topic, cold-archive, 归档, 综合]
 ---
 
 # Archive and Consolidate 命令
 
 ## 报告
 
-统一写入：`<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
+统一写入：`<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`。报告记录 workflow、source/root IDs、dry-run 清单、用户确认、relocation manifest、synthesis revision 或 archive locator 和验证结果。
 
-报告必须记录：`mode`（dry-run 或 executed）、选中的 workflow、归档计划、合并计划、清理候选、用户确认状态和最终结果。
+## Learning 路由
 
-## Ops 路由
+目标 workflow 为 Learning 时，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，由用户明确选择一个 Work：
 
-目标 workflow 为 Ops 时，不调用通用 archive skill；该 skill 的机械路径合同只支持 workflow 根级 `changes/` 与 `archive/`，不能处理 Ops 的 project scope。
+- `C-consolidate`：生成 source manifest 和 dry-run；确认后调用 `<Path>{roots.workflows}/learning/common/tools/relocate-learning.mjs</Path>` 物理移动 active/closed Change 到父 Change 的 `children/`，再生成带 provenance 的 synthesis。未确认时不得移动或更新 context。
+- `A-archive`：只处理用户 close/confirm 的 root Change 树，以最新源更新时间决定 `archive/YYYY-MM/`，不要求 Homework、R 或 mastery，也不写 context。
 
-- `archive-single`：读取 `<Path>{roots.workflows}/ops/README.md</Path>` 和 `<Path>{roots.workflows}/ops/A-archive-and-learn/A-archive-and-learn.md</Path>`，把用户选择的完整 `{scope, project_id, change}` 交给 A 执行复盘、promotion dry-run、批量确认和 scope-aware 事务关闭。Command 报告只记录选择、A 返回的 manifest/approval/archive locator 和验证结果，不成为知识 writer。
-- `archive-batch`：只读列出全部 completed Ops tuples 和各自复盘/提升状态，生成 command 报告后停止。知识合并与归档必须逐 change 进入 A 并分别批准，不能用一次跨项目确认替代多个精确 promotion manifest。
+不得把 Learning 交给共享的根级机械归档 skill；该 skill 不能理解递归 locator、parent lock 或单文件 Homework 证据。已冷归档树保持只读，需先由用户显式恢复才能作为 C 的可移动 source。
 
-以下通用模式只适用于仍采用 workflow 根级 changes/archive 合同的其他 workflows。
+## 其他 workflow
 
-## 模式
-
-### archive-single
-
-归档并合并单个已完成 change 的知识。
-
-1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析（Step 0），解析 `<Path>{roots.config}</Path>`（不存在时静默降级）。
-2. 选择一个 `change_status: completed` 的 change。
-3. 目标为 SpecDev 时先读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 与当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`：完成门必须通过，`external_action` 必须为 `closed | waived | not-applicable`；pending/failed 返回 Triage，不生成可执行归档计划。
-4. 执行 Step 1-5：扫描 stores、扫描 change、生成归档计划、生成合并计划、生成清理候选。
-5. 默认 dry-run：将完整计划写入报告文件，展示摘要并等待用户显式确认。
-6. 确认后以 mode=`confirmed` 执行 Step 7-8：归档移动、合并写入、清理、重读验证。
-7. 执行结果作为补遗追加到原报告。
-
-### archive-batch
-
-批量归档并合并所有已完成 change 的知识。
-
-1. 读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`，执行路径解析。
-2. 扫描目标 workflow 下所有 `change_status: completed` 的 change。不接受 active 或 broken 状态。
-3. SpecDev 候选逐个通过 change completion 与 external reconcile 门；任一 pending/failed 阻塞整批。
-4. 执行 Step 1-5：扫描 stores、逐 change 扫描、批量预检、合并计划、清理候选。
-5. 批量原子性：任一预检失败阻塞整批。
-6. 默认 dry-run：将完整计划写入报告文件，展示摘要并等待用户显式确认。
-7. 确认后逐项执行：归档移动 → 合并写入 → 清理 → 重读验证。失败时报告已完成/未完成清单。
+非 Learning 目标继续读取自身 README 和归档 Work，Command 报告只记录选择和 owning Work 返回的 manifest，不成为知识 writer。
 
 ## 完成标准
 
-- 报告文件位于 command 专属目录，scope 可从文件名判断。
-- 所有状态、目录和索引变更均已重读验证。
-- 未确认或 mode=`dry-run` 时无任何文件修改。
-- 合并写入的每条知识有来源 change 标注。
-- 每个清理候选有分类和理由。
+- dry-run、确认、移动、回滚和最终验证均有报告；
+- 原始 Markdown 内容不被覆盖，跨路径引用通过 stable ID/locations 解析；
+- 未确认或失败事务不留下部分移动或 context 写入。

package/template/commands/docs-sync.md

@@ -2,7 +2,7 @@
 id: docs-sync
 type: command
 name: Docs Sync
-description: 清洁并提交工作区，以可复现 Git 区间和确认范围同步项目文档、Agent 手册与 workflow 知识
+description: Synchronize project documentation and agent handbooks for a confirmed reproducible Git range.
 keywords: [docs-sync, readme, changelog, agents, documentation]
 ---
 

package/template/commands/git-repository-audit.md

@@ -2,7 +2,7 @@
 id: git-repository-audit
 type: command
 name: Git Repository Audit
-description: 只读盘点项目根目录下一个或多个 Git 仓库，生成可复核的代码迭代、团队协作与个人贡献报告
+description: Produce a read-only reproducible audit for explicitly selected local Git repositories.
 keywords: [git-audit, git-inventory, repository, commit, merge, contribution, 仓库盘点, 代码审计, 团队评估]
 ---
 

package/template/commands/handoff.md

@@ -2,7 +2,7 @@
 id: handoff
 type: command
 name: handoff
-description: 将当前对话压缩为一份交接文档，供另一个 agent 接手继续工作。
+description: Persist a compact handoff when the user asks another agent or session to continue the current work.
 keywords: [handoff, 交接, 移交, 上下文压缩]
 argument-hint: "下一个会话将用于什么？"
 disable-model-invocation: true

package/template/commands/retro.md

@@ -2,7 +2,7 @@
 id: retro
 type: command
 name: Speculo Retro
-description: 复盘 Speculo commands/workflows 使用痛点，深度分析后经确认用 gh 提交改进 issue
+description: Analyze confirmed Speculo usage friction and propose or create GitHub issues through the npm/GitHub operation skill.
 keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 ---
 

package/template/commands/status.md

@@ -2,7 +2,7 @@
 id: status
 type: command
 name: Status
-description: 汇总已安装 workflow、active changes、异常状态与下一步
+description: Summarize installed workflows, active changes, anomalies, and next routes without activating a workflow.
 keywords: [status, 状态, active, blocked]
 ---
 
@@ -10,8 +10,8 @@ keywords: [status, 状态, active, blocked]
 
 1. 读取 `<Path>{roots.state}/workspace.json</Path>`，解析 `<Path>{roots.config}</Path>`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
 2. 扫描 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>`，得到已安装 workflow ids。
-3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的 schema 解释，不把 SpecDev 字段套到其他 workflow。SpecDev schema v5 和 Learning schema v1 按根级 `changes/<change>` 与 `archive/YYYY-MM/<change>` 定位。Ops schema v2 将 active/archived entry 解析为 `{scope, project_id, change}`：global 仍使用根级路径，project 必须使用 `<Path>{roots.state}/ops/projects/{project_id}/changes/{change}/.status.json</Path>` 或对应 `archive/YYYY-MM/{change}/.status.json`；不得按 change 名跨项目合并。
-4. 报告 active 数量、各 change 的 `current_work`、去重后的 `works_run`、业务状态、最近更新时间和停滞 change（`.status.json` 超过 14 天未更新）。SpecDev 额外报告调查 claims 与 triage `external_action`；Learning 额外报告 domain/topic、测验与复习状态；Ops 额外报告 scope/project、phase、outcome、current plan/approval、latest attempt 和 blockers，并把同名不同项目 Change 分行展示。
-5. 报告 archived 数量和完整 scope/project/change locator；Learning 同时读取 `context/REVIEW.md` 汇总已到期、即将到期和 `needs_refresh` 知识。预期归档目录或 `.status.json` 缺失、active/archived tuple 重叠、同 scope 重复、Ops project.json 缺失、未知 schema、断开链接和 malformed 目录均列为异常，不自动修复。
+3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`，按该 workflow 自己的 schema 解释，不把 SpecDev 字段套到其他 workflow。Learning schema v2 的 active/archived entry 携带 stable `change_id`、kind、parent/root、current locator、current_work、Homework 和 retention projection；递归 Change 位于 `changes/**` 或 `archive/**`，位置历史读取 `<Path>{roots.state}/learning/locations.json</Path>`。SpecDev 继续使用 schema v5 根级 `changes/<change>`/`archive/YYYY-MM/<change>`；Ops schema v2 仍使用 `<Path>{roots.state}/ops/projects/{project_id}/changes/{change}/.status.json</Path>` 或对应 `archive/YYYY-MM/{change}/.status.json`。不得按 change 名跨 workflow 合并。
+4. 报告 active 数量、各 Change 的 `current_work`、去重后的 `works_run`、生命周期、parent/root、最近更新时间和停滞 Change（`.status.json` 超过 14 天未更新）。SpecDev 额外报告调查 claims 与 triage `external_action`；Learning 额外报告 domain/topic、Lesson/Homework、immediate/retention 和 synthesis 状态；Ops 额外报告 scope/project、phase、outcome、current plan/approval、latest attempt 和 blockers，并把同名不同项目 Change 分行展示。
+5. 报告 archived 数量和完整 scope/project/change locator；Learning 同时读取 `context/REVIEW.md` 汇总到期 Review、topic evidence status 和需要刷新内容。预期归档目录或 `.status.json` 缺失、active/archived 重叠、parent cycle、位置登记不一致、未知 schema、断开链接和 malformed 目录均列为异常，不自动修复。
 6. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
 7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`，并在报告中列出本次扫描的 workflow 选择。