@abelxiaoxing/cadence 1.0.14 → 1.1.0

package/README.md

@@ -3,23 +3,33 @@
 [![npm](https://img.shields.io/npm/v/@abelxiaoxing/cadence)](https://www.npmjs.com/package/@abelxiaoxing/cadence)
 [![GitHub](https://img.shields.io/github/license/abelxiaoxing/cadence)](https://github.com/abelxiaoxing/cadence)
 
-**Cadence** 是一个面向 pi 的规范驱动四阶段工作流扩展包，内置私有代理编排：
+**Cadence** 是一个面向 Pi 的规范驱动四阶段工作流扩展包，内置可恢复的私有代理编排：
 
-- `/abel-init [project-path]` — 初始化 OpenSpec 并修复 AGENTS 索引。
-- `/abel-design <requirement> | --change <change_name>` — 并行只读探索，设计依赖/冲突感知的任务 DAG，经由 Gate A（行为契约）与 Gate B（技术契约）双重批准。
-- `/abel-implement <change_name>` — 在已批准的 DAG 上编排任务级专业代理，委派 Red-Green-Refactor，由父代理执行验证。
-- `/abel-diagnose <problem-description>` — 先验证根因，再做最小修复。
+- `/abel-init [project-path]` — 本地、固定顺序且幂等地初始化或安全修复 OpenSpec 与 AGENTS 托管索引，不派发子代理。
+- `/abel-design <requirement> | --change <change_name>` — 使用有界只读证据包解决行为与技术决策，生成经 Gate A（WHAT）和 Gate B（HOW）批准的 canonical delivery；不启动实现 Worker，不运行产品测试，也不修改产品代码。
+- `/abel-implement <change_name>` — 在私有不可变 revision 中执行已批准的 Red-Green-Refactor DAG，累计验证全部任务后才通过一次可恢复事务写入主工作区。
+- `/abel-diagnose <problem-description>` — 独立执行“复现 → 证伪 → 失败回归 → 最小修复”，不充当 Implement 的失败路由。
 
 包是独立的：单一仓库、单一清单、单一 lockfile，无 workspace、无参考仓库检出、不依赖任何外部 Subagent 包。
-加载本包会注册一个私有扩展与四个包内专业 Agent；`abel_dispatch` 工具注册但保持未激活，只有经过验证的 Design、Implement 或 Diagnose 阶段才会激活它。
+加载本包会注册一个私有扩展与四个包内专业 Agent；`abel_dispatch` 工具注册但保持未激活，只有用户显式调用且包来源验证通过的 Design、Implement 或 Diagnose prompt 才会激活它。
+仓库中存在 Abel 文件、OpenSpec change、AGENTS 索引或普通文本都不会启动工作流；Init 也不会激活派发工具。
 
-共享工作流规则统一收录于包内 `abel-workflow` skill。
+共享工作流规则统一收录于包内 `abel-workflow` Skill；其发现信息同样明确要求先有显式 `/abel-*` 调用。
 
-交互式 TUI 中，经过验证的 `abel_dispatch` run 会显示紧凑的 Subagent 角色、请求、阶段、目标、耗时和状态，并在编辑器上方临时汇总仍在排队或运行的 Agents。
+Implement 只暴露 `start`、`status`、`resume`、`rebind`、`cancel` 和 `discard` 控制命令。
+`status` 完全本地可用；相同 operation id 幂等重放，进程、会话或 Worker 更换后仍从 durable checkpoint 继续。
 
-该显示只保留有限的终态摘要；不会显示子会话、工具活动、路径、模型身份、隐藏推理、完整引用或完整 diff。
+普通 artifact、错误 Red、transport、environment、stale、conflict、baseline 与验证失败都留在同一 Implement run 中恢复。
+累计验证发现 introduced failure 时会自动重开责任任务做有界修复；自动预算耗尽后 `resume` 复用已有 baseline 和 phase facts。
+只有继续工作确实需要新增行为、架构/策略、依赖、路径、资源、验证或 AGENTS 权限时才进入 `approval-needed`；结果不会携带返回 `/abel-design` 的阶段路由。
 
-print、JSON 和 RPC 模式保持原有结果与事件行为不变。
+交互式 TUI、print、JSON 和 RPC 都以 durable semantic state 为准。
+queued、connecting、waiting-first-response、running、validating、retrying、verifying、paused、approval-needed、applying 和 recovering 都不是完成；operation-cancelled 表示本次操作取消但 run 仍可恢复，discarded 与 rejected 是非成功终态。
+只有最终 apply 与 post-apply verification 提交后的 `completed` 才显示成功。
+
+私有 journal、artifact 与 change workspace 位于 consumer repository 之外的 owner-private state root。
+暂停会保留最小结构化恢复事实；完成或显式 discard 后安全清理。
+不会持久化凭据、环境值、原始 prompt、隐藏推理、完整子会话或原始模型输出。
 
 ## 安装（Install）
 
@@ -43,7 +53,13 @@ npm install -g @abelxiaoxing/cadence
 - **本地包目录（local package directory）** — 将 Pi 指向本仓库的绝对路径或相对路径（absolute or relative path，例如 `./cadence`），Pi 发现同样的资源。
 - **已安装 tarball 目录（installed tarball directory）** — 运行 `bun pm pack --destination <tmp>` 生成真实 tarball（.tgz），安装或解压到隔离目录后指向该目录；tarball 文件本身永远不会被当作本地包传给 Pi。
 
-本包从不检查或分类 Pi 主机版本，不声明任何版本范围，也不从参考仓库源安装。
+本包要求 Node.js `>=22.13.0`，以使用稳定可用的内置 `node:sqlite`；不从参考仓库源安装，也不维护 Pi 主机版本兼容矩阵。
+
+## Worker 路由（Worker routes）
+
+复制 [`config/routes.example.json`](config/routes.example.json) 到项目级 `.pi/cadence/routes.json` 或用户级 `~/.pi/agent/cadence/routes.json`。
+项目文件按整文件优先；route 必须显式列入对应角色，custom route 只引用 `apiKeyEnv` 的变量名，不能把凭据值写进 JSON。
+`rebind` 只能选择已获 policy 授权且能力匹配的 route，不会扩大任务边界。
 
 ## 跨项目验证合同（Cross-project verification）
 
@@ -108,8 +124,8 @@ bun run check:agents          # AGENTS 索引校验
 
 ```sh
 bun run verify      # check && lint && test && pack:check（发布前全套校验）
-bun run pack:check  # 真实 tarball 44 成员清单校验
-bun run traceability:check   # 81 条 Requirement/Scenario 引用精确解析
+bun run pack:check  # 真实 tarball 53 成员清单校验
+bun run traceability:check   # 162 条 active Requirement/Scenario 引用精确解析且唯一归属
 ```
 
 ## 许可（License）

package/agents/contract-reviewer.md

@@ -2,10 +2,10 @@
 
 You are a package-owned read-only professional Agent for terminal and checkpoint review of approved design delivery.
 
-You inspect the approved contracts, receipts, hashes, traceability, and task DAG ONLY through the scoped `read`, `grep`, `find`, and `ls` tools.
+You inspect the approved contracts, canonical `ImplementPlan`, receipts, raw and canonical hashes, verification closure, traceability, and task DAG ONLY through the scoped `read`, `grep`, `find`, and `ls` tools.
 You never write, mutate, or run validation.
 
 Your output is a compact structured evidence object returned through `abel_submit_result`, containing the review identity, the exact artifact hashes you verified, suite-evidence status, and typed `delivery-invalid` or `approval-boundary` facts (empty when the delivery is sound).
 
 You never patch product code, AGENTS files, or task state.
-Review evidence is read-only; the parent resolves it without a stage selection or recovery recommendation from you.
+Review evidence is read-only; the parent resolves it without a stage selection, Gate decision, or recovery recommendation from you.

package/agents/design-explorer.md

@@ -6,7 +6,7 @@ You explore the repository ONLY through the scoped `read`, `grep`, `find`, and `
 You have no shell, edit, Git, network, or validation capability, and you never create or modify files.
 
 Call `abel_submit_result` exactly once with one structured object.
-Do not emit a second submit, prose, or the legacy `conclusions`/`citations` shape.
+Do not emit a second submit, prose, or fields outside the declared Design evidence schema.
 The object contains the matching `id`, `role: "design-explorer"`, `kind: "evidence"`, and:
 
 - `packet_id` (exactly equal to the request id), `module_name`, `scope`, and

package/agents/diagnosis-worker.md

@@ -6,8 +6,11 @@ You collect evidence and falsify candidate root causes ONLY through the scoped `
 You never write, execute commands, or run validation.
 The fixed algorithm order is reproduce, falsify, failing-regression, then minimum-repair.
 
-Phase 1 output: a compact structured evidence object through `abel_submit_result` with reproduced symptoms, candidate causes, confirming or refuting citations, and a verified root-cause conclusion or an explicit blocked report.
+An evidence packet submits exactly one compact structured evidence object through `abel_submit_result` with the reported symptoms, candidate causes, confirming or refuting citations, and a supported root-cause conclusion or an explicit evidence gap.
+Only the parent may claim that command-based reproduction succeeded.
 
-Phase 2 output: first a complete failing-regression unified diff, then a minimum-repair unified diff, each returned through `abel_submit_result` with task identity, the complete untruncated diff, expected verification, risks, and typed blockers.
+A candidate packet submits exactly one complete unified diff: either the failing regression or, after the parent has verified that regression, the minimum repair.
+It includes task identity, expected parent-owned verification, risks, and typed blockers, and never claims that it ran the verification.
 
-You never invent a fix for an unverified root cause, and you never change behavior contracts; scope-expanding repairs are reported as blocked facts for the parent.
+You never invent a fix for an unverified root cause, change behavior contracts, select another workflow stage, or prescribe parent recovery.
+Scope-expanding repairs are reported as evidence for a user decision.

package/agents/implementation-worker.md

@@ -5,15 +5,20 @@ You are a package-owned read-only professional Agent for `abel-implement` task p
 You explore the workspace ONLY through the scoped `read`, `grep`, `find`, and `ls` tools.
 You never write the workspace, run validation, or execute commands.
 
-Your output is a complete unified diff returned through `abel_submit_result` with:
+Your output is a complete unified diff delivered through `abel_submit_result`:
 
-- the task id, phase, and your role name;
-- a concise summary and contract-compliance statement;
-- the complete, untruncated unified diff covering exactly the declared write
-  set (never reconstructed from a summary);
-- the expected verification command and result;
-- risks or typed blockers.
+- copy the attempt-bound `candidateId` from the phase contract;
+- submit the complete diff as one or more ordered `candidate-segment` calls
+  containing `candidateId`, a zero-based `sequence`, and raw `text`;
+- after every byte of the diff has been submitted, make exactly one
+  `candidate-seal` call containing `candidateId`;
+- never calculate or invent Base64 encodings, byte counts, or hashes; the
+  trusted submit tool computes them;
+- the diff covers exactly the declared write set;
+- preserve the expected parent-owned verification contract without claiming a result;
+- use a typed `context-request` for bounded context, task splitting, or an
+  approval-boundary blocker instead of submitting a partial diff.
 
-A result that cannot fit the configured complete-result limit is reported as terminal typed `result-limit` with `limitBytes`, never as a partial or truncated diff.
+If the configured candidate limit is exceeded, the submit tool returns terminal typed `result-limit` with `limitBytes`; never continue with a partial or truncated diff.
 The parent alone reviews, applies, and validates your diff.
-You report candidate facts only and never select parent recovery, workflow routing, or task-DAG control.
+You report candidate facts only and never claim execution success, select parent recovery, choose a workflow stage, or control the task DAG.

package/config/.env.example

@@ -1,20 +1,8 @@
-# Copy to <project>/.pi/cadence/.env or ~/.pi/agent/cadence/.env.
-# The project file wins as a whole file; values are not merged or interpolated.
-
-# Optional custom Subagent endpoint. To enable it, set all required values.
-# Any non-empty key commits the whole layer; partial/invalid layers fail closed.
-SUBAGENT_API_URL=
-SUBAGENT_API_KEY=
-SUBAGENT_MODEL=
-# Optional dialect: openai-completions (default), openai-responses, or anthropic-messages.
-# SUBAGENT_API=openai-completions
-# Optional bounds; internal defaults are 256000 and 128000 respectively.
-# SUBAGENT_CONTEXT_WINDOW=256000
-# SUBAGENT_MAX_TOKENS=128000
-
-# Per-role layers use the same six suffixes and override the global layer whole:
-# SUBAGENT_<ROLE>_<SUFFIX>, where ROLE is DESIGN_EXPLORER, CONTRACT_REVIEWER,
-# IMPLEMENTATION_WORKER, or DIAGNOSIS_WORKER. Partial/invalid layers fail closed.
+# Worker routing is configured as one whole JSON policy at
+# <project>/.pi/cadence/routes.json or ~/.pi/agent/cadence/routes.json.
+# Copy routes.example.json and reference custom credentials by environment
+# variable name; never place credential values in routes.json.
+CADENCE_CUSTOM_WORKER_API_KEY=
 
 # Context7 works anonymously with its default URL. Uncomment the API key for
 # authenticated access, or the URL only when overriding the default endpoint.

package/config/routes.example.json

@@ -0,0 +1,42 @@
+{
+  "version": 2,
+  "routes": {
+    "parent": {
+      "kind": "inherited",
+      "capabilities": {
+        "roles": [
+          "design-explorer",
+          "contract-reviewer",
+          "implementation-worker",
+          "diagnosis-worker"
+        ],
+        "dialects": [
+          "openai-completions",
+          "openai-responses",
+          "anthropic-messages"
+        ],
+        "contextWindow": 256000,
+        "maxTokens": 128000
+      }
+    },
+    "custom-worker": {
+      "kind": "custom",
+      "url": "https://example.invalid/v1",
+      "model": "example-model",
+      "dialect": "openai-responses",
+      "apiKeyEnv": "CADENCE_CUSTOM_WORKER_API_KEY",
+      "capabilities": {
+        "roles": ["implementation-worker"],
+        "dialects": ["openai-responses"],
+        "contextWindow": 256000,
+        "maxTokens": 128000
+      }
+    }
+  },
+  "roles": {
+    "design-explorer": ["parent"],
+    "contract-reviewer": ["parent"],
+    "implementation-worker": ["custom-worker", "parent"],
+    "diagnosis-worker": ["parent"]
+  }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.0.14",
-  "description": "Prompts, skills, and a private orchestration extension exposing the Abel four-stage workflow (/abel-init, /abel-design, /abel-implement, /abel-diagnose) with package-owned professional Agents.",
+  "version": "1.1.0",
+  "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "keywords": [
     "pi-package",