@cr1992/agentkit 1.1.0 → 1.2.0

package/domains/worktree/worktree-mgr.mjs

@@ -8,6 +8,9 @@ import { homedir, tmpdir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+// ledger id 的格式规则下沉在 core/：worktree 域只做格式校验，不 import orchestrate 域。
+import { LEDGER_ID_PATTERN, isLedgerId } from '../../core/ledger-pointer.mjs';
+
 import * as core from './worktree-core.mjs';
 import * as mergePreview from './worktree-merge-preview.mjs';
 import * as profile from './worktree-profile.mjs';
@@ -82,6 +85,8 @@ const dependencies = {
   processPlatform: process.platform,
   processExecPath: process.execPath,
   processGetuid: () => typeof process.getuid === 'function' ? process.getuid() : 0,
+  LEDGER_ID_PATTERN,
+  isLedgerId,
   ...mergePreview,
   ...profile,
   ...provider,
@@ -133,14 +138,15 @@ export const verifyArtifactEnvelope = artifactCommands.verifyArtifactEnvelope;
 
 function cmdCapabilities(args) {
   rejectUnknownFlags(args.flags, ['json']);
-  console.log(JSON.stringify({ skill: 'manage-worktrees', runtime_version: '1.4.0', contracts: { worktree_binding: [1], artifact_ref: [1], reflection_record: [1], improvement_proposal: [1], batch_result: [1] }, features: ['git-common-dir-ledger', 'ownership-epochs', 'artifact-verification', 'incident-reflection', 'proposed-only-improvement', 'batch-integrate', 'batch-conflict-scan', 'declared-post-integrate-steps', 'batch-result', 'evidence-archive-reclaim', 'durable-pushed-ref-proof', 'auto-armed-review-watch', 'persistent-review-watch-intent', 'launchd-watch-service', 'review-target-advance-prediction', 'explicit-review-refresh', 'managed-history-rewrite', 'stack-parent-attribution', 'structured-change-registration'], content_digest: worktreeSkillDigest() }, null, 2));
+  console.log(JSON.stringify({ skill: 'manage-worktrees', runtime_version: '1.5.0', contracts: { worktree_binding: [1], artifact_ref: [1], reflection_record: [1], improvement_proposal: [1], batch_result: [1] }, features: ['git-common-dir-ledger', 'ownership-epochs', 'artifact-verification', 'incident-reflection', 'proposed-only-improvement', 'batch-integrate', 'batch-conflict-scan', 'declared-post-integrate-steps', 'batch-result', 'evidence-archive-reclaim', 'durable-pushed-ref-proof', 'auto-armed-review-watch', 'persistent-review-watch-intent', 'launchd-watch-service', 'review-target-advance-prediction', 'explicit-review-refresh', 'managed-history-rewrite', 'stack-parent-attribution', 'structured-change-registration'], content_digest: worktreeSkillDigest() }, null, 2));
 }
 
 function usage() {
   console.log(`${PREFIX} portable multi-Agent worktree manager
 
-spawn <task> --agent <host> --agent-id <id> --purpose <text> [--owner <name>] [--base <ref> --base-reason <text>] [--root <path>] [--codegraph auto|on|off]
+spawn <task> --agent <host> --agent-id <id> --purpose <text> [--owner <name>] [--base <ref> --base-reason <text>] [--root <path>] [--codegraph auto|on|off] [--ledger <id>]
   同会话已有未回收树时默认拒绝；独立并行加 --parallel-reason <text>；替代加 --supersedes <selector> --replacement-reason <text>
+  --ledger <id>：把这棵树绑到某个 orchestration ledger，写进 record，供 agentkit status 收窄范围；只校验 id 格式
 adopt <path> --agent <host> --agent-id <id> --purpose <text> [--task <slug>] [--base <ref> --base-reason <text>]
 list [--json] [--all] [--present] [--archived]
   --present：只列目录仍然存在的 record（TRACKED/UNTRACKED/MAIN 分类不变），隐藏全部历史记录

package/manage-worktrees/SKILL.md

@@ -23,7 +23,7 @@ metadata:
 下文多行示例采用 POSIX 续行语法；PowerShell/cmd 保留相同 argv 即可。不要把 `python3`、`bash`、
 `~` 展开或 `/tmp` 视为跨平台常量。
 
-不要假设目标仓库有同名脚本。仓库可以通过根目录 `.worktree-trace.json` 提供 Profile，但 portable core 不执行 Profile 中的任意 shell command。配置 schema 和项目适配边界见 [Profile 配置](../docs/worktree/profile.md)。
+不要假设目标仓库有同名脚本。仓库可以通过根目录 `.worktree-trace.json` 提供 Profile，但 portable core 不执行 Profile 中的任意 shell command。配置 schema 和项目适配边界见 Profile 配置（`agentkit docs worktree profile`）。
 
 所有命令都必须从**目标 Git 仓库的任意 worktree 内**执行：manager 以当前工作目录解析 repository
 identity、primary worktree 和 Profile。
@@ -58,18 +58,18 @@ manager 的 trace/common-dir 状态只应由受信 operator/controller 与 runti
 
 | 阶段 | 最小命令面 | 硬门禁与按需文档 |
 |---|---|---|
-| 恢复/盘点 | `resume-all` → `list` → `doctor` | `list/doctor` 只读；`UNTRACKED` 不等于无人使用；`EPHEMERAL` 优先 commit+push；任何 error 都暂停 `spawn/adopt` |
+| 恢复/盘点 | `watch-service status` → `resume-all` → `list` → `doctor` | 常驻服务未安装时只报告并建议 `watch-service install`，不得用 `--no-watch` 顶替；`list/doctor` 只读；`UNTRACKED` 不等于无人使用；`EPHEMERAL` 优先 commit+push；任何 error 都暂停 `spawn/adopt` |
 | 碰撞扫描 | `scan --target <paths>` | `COLLIDE`、范围不确定或重做昂贵时隔离；`CLEAR` 仅在 owner 明确且改动小时共享；低置信后缀匹配先人工核对路径基准 |
-| 交付身份 | 选择复用/并存/替代 | branch、MR 或目录名不同不能单独证明独立交付；同一 agent 有存量树或需要替代时读[交付身份](../docs/worktree/delivery-identity.md) |
-| 创建/接管 | `spawn <semantic-slug>` / `adopt <path>` | 使用真实 agent-id，不猜身份；task 至少两个 lowercase 语义分词；base、root、堆叠、rebase/retarget 读[创建与堆叠](../docs/worktree/spawn-and-stack.md) |
-| 更新/交接 | `touch` / `handoff` / `refresh-review` | `ready_for_review` 默认武装冻结 HEAD；handoff 只接受 clean、已 push 边界，禁止 stash 搬运；读[评审生命周期](../docs/worktree/review-lifecycle.md) |
+| 交付身份 | 选择复用/并存/替代 | branch、MR 或目录名不同不能单独证明独立交付；同一 agent 有存量树或需要替代时读交付身份（`agentkit docs worktree delivery-identity`） |
+| 创建/接管 | `spawn <semantic-slug>` / `adopt <path>` | 使用真实 agent-id，不猜身份；task 至少两个 lowercase 语义分词；属于某次编排时带 `--ledger <id>`，好让 `agentkit status` 收窄到那一个；base、root、堆叠、rebase/retarget 读创建与堆叠（`agentkit docs worktree spawn-and-stack`） |
+| 更新/交接 | `touch` / `handoff` / `refresh-review` | `ready_for_review` 默认武装冻结 HEAD；handoff 只接受 clean、已 push 边界，禁止 stash 搬运；读评审生命周期（`agentkit docs worktree review-lifecycle`） |
 | 审计/提交 | `audit` / `submit` | portable core 不决定 MR/PR 或直推策略；先服从目标仓规则，再原子登记 change request 与 watcher target |
-| 批量集成 | `plan-batch` → `batch-integrate` → `batch-step` → `batch-result` | 同仓同 target：≥3 默认聚合，2 个仅在碰撞时；只合成冻结 SHA，不代跑门禁；合同/顺序/target 变化即重规划；读[批量集成](../docs/worktree/batch-integration.md) |
-| 回收 | `reclaim` / `archive` | 必须有远端/其他 ref 可达证明或明确 archive evidence；dirty、stash、submodule、权限或 branch-tip 异常一律 `KEEP`；替代树默认先归档，`--discard` 需人工明确授权；读[回收与看护](../docs/worktree/reclaim-and-watch.md) |
+| 批量集成 | `plan-batch` → `batch-integrate` → `batch-step` → `batch-result` | 同仓同 target：≥3 默认聚合，2 个仅在碰撞时；只合成冻结 SHA，不代跑门禁；合同/顺序/target 变化即重规划；读批量集成（`agentkit docs worktree batch-integration`） |
+| 回收 | `reclaim` / `archive` | 必须有远端/其他 ref 可达证明或明确 archive evidence；dirty、stash、submodule、权限或 branch-tip 异常一律 `KEEP`；替代树默认先归档，`--discard` 需人工明确授权；读回收与看护（`agentkit docs worktree reclaim-and-watch`） |
 
-`resume-all` 只提供当次恢复。需要跨 Agent 会话、注销或重启后仍自动恢复 watcher 时，先检查
-`agentkit worktree watch-service status`；macOS 可由用户一次性显式执行 `watch-service install`。
-未安装常驻维护器时不得把进程级 watcher 描述成跨会话保证。
+`resume-all` 只提供当次恢复。跨 Agent 会话、注销或重启后仍要自动恢复 watcher，靠的是常驻维护器：
+macOS 由用户一次性显式执行 `watch-service install`。未安装时不得把进程级 watcher 描述成跨会话保证，
+也不得因此改用 `--no-watch`（判据见评审生命周期）——那只会把待回收的树变成无人看护。
 
 不得按目录年龄、名称或“看起来干净”删除。禁止 `rm -rf`、`git worktree remove --force`、`branch -D`
 和 feature owner 手工 rebase。watcher 的 `merge-tree` 结果只是目标前进后的只读成本预判，不保证逐

package/orchestrate-subagents/SKILL.md

@@ -10,6 +10,7 @@ metadata:
 
 提供宿主无关的拆解、派发、控制和验收协议。最强适配模型持续担任 controller，掌握
 `Plan → Delegate → Observe → Re-plan → Verify → Finish`；不得派生另一个 agent 接管控制面或最终判断。
+新会话冷启动或接手已有任务时先跑 `agentkit status`，找回本仓未终态的 ledger。
 
 ## 组合协议
 
@@ -38,9 +39,10 @@ controller 始终拥有闭环对象、完成标准、任务图、依赖/barrier
 
 派生后维护“活跃 Agent”“本批已完成”，存在并行时再维护“工作进展”；在派发、批次收口、用户询问
 和最终答复时更新，无活跃 worker 明示为 0，不虚构百分比。字段与状态变换见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「派发台账的三张表」。台账也是回收清单：收口前
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「派发台账的三张表」。台账也是回收清单：收口前
 确认没有孤儿 worker/worktree/运行时资源。任务图与台账只写仓库外会话状态；完整档用 mechanical
-ledger，轻量档用单一 JSON 快照，闭环后清理。
+ledger，闭环后 `agentkit orchestrate ledger close` 收口，放弃或升级后 drift 的用
+`close --abandon --reason <text>`；轻量档用单一 JSON 快照，闭环后清理。
 
 ### 档位无关的有效能力预检
 
@@ -48,7 +50,7 @@ ledger，轻量档用单一 JSON 快照，闭环后清理。
 只有 `allowed` 可用。输入已随合同完整提供、节点不依赖额外宿主能力时 requirements 可为空，
 此时记 `not_required` 及依据即可。同机、本地或过去恒过都不构成豁免。探针只在比 controller 自做或
 缩小节点更便宜时派发，并计入 worker 与 Token 预算。能力键前缀、binding 与复用规则、反应矩阵见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「Worker 有效能力预检」。
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「Worker 有效能力预检」。
 
 ### 显式轻量档
 
@@ -59,16 +61,18 @@ ledger，轻量档用单一 JSON 快照，闭环后清理。
 轻量档仍冻结每个节点的目标、范围、事实/假设、输出合同、验收、证据和停止条件，并在仓库外维护
 单一 JSON 快照；它只记录事实，不伪造 journal。资格失效时停止新派发，把现状和产物收养进完整 ledger。
 Reflection 使用 `agentkit orchestrate reflection record/propose`，通用 Skill 缺口不得写入宿主能力缓存。
-快照 schema、收养步骤和 Reflection 约束见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)。
+快照 schema、收养步骤和 Reflection 约束见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）。
 
 ### 完整档机械台账工具
 
 不满足轻量档时使用 `orchestration_mode: full`。先用 `agentkit contract normalize / validate / digest /
-review-view / diff` 固定公共 Task Contract，再以仓库外 state root 初始化 `agentkit orchestrate ledger`。
+review-view / diff` 固定公共 Task Contract——需求还没逼问成可冻结的契约时，先用
+`agentkit contract interview-*` 访谈（`agentkit docs orchestrate contract-interview`）——再以仓库外
+state root 初始化 `agentkit orchestrate ledger`。
 脚本不直接派发 Agent，controller 把宿主回执写入 `dispatch-record`。节点必须选择
 `worker_self_check`、`controller_recheck`、`independent_evidence`，只读 critic/scout 用
 `not_applicable`；依赖/barrier 未通过不派下游。命令、schema、`--expected-revision`、state root 信任
-边界和批级熔断见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)。
+边界和批级熔断见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）。
 Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`，不能改变当前运行。
 
 ## 1. 先过闸门
@@ -81,7 +85,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 
 规模来自真正独立且单个上下文装不下的工作块，不来自话题数；删掉不影响答案的节点。常规盘点/审计
 一轮总 Agent 数 `≤10`。扫描与核验配比、
-合并判据与各档规模见 [任务类型剧本](../docs/orchestrate/task-playbooks.md)。
+合并判据与各档规模见 任务类型剧本（`agentkit docs orchestrate task-playbooks`）。
 
 ## 3. 派发前决定环境
 
@@ -98,7 +102,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 
 仓库 dirty、任务大或包含新文件本身都不足以要求隔离；先确认第二写入者、归属冲突或路径相交。
 裁决隔离后使用 `manage-worktrees`，它不改变任务图、权限或验收。不可用时必须先读
-[无 manage-worktrees 时的隔离下限](../docs/orchestrate/isolation-fallback.md)。
+无 manage-worktrees 时的隔离下限（`agentkit docs orchestrate isolation-fallback`）。
 
 共享树中 worker 不得切换分支，只按路径 stage / commit；禁止 `git add -A`、`git commit -am`、裸 `stash`、`reset --hard`、`checkout -- .` 和并发 merge，controller 是唯一 integrator。
 
@@ -107,7 +111,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 2-3 个独立任务用宿主轻量并行；循环、条件、逐项管线或预算驱动才使用结构化编排。多 stage 默认逐条
 pipeline，只有跨条去重、聚合、比较或早退才设 barrier。截断、采样或不重试必须披露覆盖缺口。
 barrier、critic 面板与 loop-until-dry 的具体用法见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「编排原语选择」。具体 API 服从宿主编排工具说明。
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「编排原语选择」。具体 API 服从宿主编排工具说明。
 
 ## 5. 派发可验收的任务契约
 
@@ -118,17 +122,17 @@ stop_conditions`；写任务再冻结权限、精确仓库/workdir/branch 和 wr
 controller 圆场。
 
 派发写 worker、完整档、独立 Evidence 或失败后重派前，必须读取
-[节点派发合同](../docs/orchestrate/dispatch-contract.md) 并使用完整 envelope。轻量只读节点可只使用上述最小合同。
+节点派发合同（`agentkit docs orchestrate dispatch-contract`） 并使用完整 envelope。轻量只读节点可只使用上述最小合同。
 
 ## 6. 控制运行态与升级
 
 用户可见台账只用 `运行中 / 阻塞 / 待验收`；`partial` 由 controller 决定继续、转阻塞或停止后判
 未通过。只有 controller 能给出 `通过 / 未通过 / 取消`。台账术语不进用户汇报，对外说法见
-[面向用户的汇报词表](../docs/orchestrate/user-facing-reporting.md)。
+面向用户的汇报词表（`agentkit docs orchestrate user-facing-reporting`）。
 
 只在结论交付、需要输入、scope/写入冲突、预算将尽、新依赖、失败或置信不足时介入；“等待中”不是
 状态包。能力故障、业务失败、中断与 contract gap 分开处理，不按失败次数机械升档。失败、重派、中断
-或 controller 接手时读取[失败路由与恢复](../docs/orchestrate/failure-routing-and-recovery.md)。合同失真、
+或 controller 接手时读取失败路由与恢复（`agentkit docs orchestrate failure-routing-and-recovery`）。合同失真、
 新授权、不可逆动作、资源/结论冲突或重试耗尽必须升级，不得自行扩 scope。
 
 ## 7. 验证、收敛与停止
@@ -139,7 +143,7 @@ controller 圆场。
 复核记录；`independent_evidence` 绑定唯一 Artifact 与标准 Evidence；只读 critic/scout 用
 `not_applicable`，附一份 report 即收口。失败、不可判定、安全阻塞、
 human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能用 `agentkit contract project` 从公共
-合同切出 acceptance 子集；完整门禁见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)「合同投影」。
+合同切出 acceptance 子集；完整门禁见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）「合同投影」。
 
 快速演进分支的迭代期只读 review 最多算 `controller_recheck`；到 RC/合入候选才冻结唯一 Artifact，
 运行 `verify-agent-output` 生成 `independent_evidence`。
@@ -153,7 +157,7 @@ human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能
 独立 reviewer 是高成本资源，不与 worker 1:1 配对。对同一 Artifact 默认只允许一次 primary review；
 第二次必须由 `undecidable`、证据冲突或协议歧义触发，使用不同 lens 且可能改变处置。smoke 未通过、
 同 lens 重复、输入超出预算或已有 `blocked_safety` 时不派。考虑任何 critic/reviewer 时必须读取
-[Reviewer 数量与 Token 预算](../docs/orchestrate/review-budget.md)，冻结 `extensions.review_policy`，并在派发前运行
+Reviewer 数量与 Token 预算（`agentkit docs orchestrate review-budget`），冻结 `extensions.review_policy`，并在派发前运行
 `agentkit orchestrate review-budget evaluate`。提高 reviewer 数量或输入上限属于 re-contract。
 
 最终答复前用 `闭环项 / 标准 / 证据 / 结果` 审计：闭环对象与外部状态已重查；必要节点已验收且活跃
@@ -163,11 +167,11 @@ human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能
 ## 8. 模型路由与宿主自适配
 
 controller 持续掌握目标、任务图、re-plan、失败分类和最终验收；worker 不自选模型或下一次配置。
-派发、首次建 tier、失败后调档或切模型时读[模型路由](../docs/orchestrate/model-routing-config.md)，按任务类型
-选档再读[任务剧本](../docs/orchestrate/task-playbooks.md)：使用本地配置中最低可靠 tier，model/effort 只取
+派发、首次建 tier、失败后调档或切模型时读模型路由（`agentkit docs orchestrate model-routing-config`），按任务类型
+选档再读任务剧本（`agentkit docs orchestrate task-playbooks`）：使用本地配置中最低可靠 tier，model/effort 只取
 用户配置与实时 schema，每次保存精确配置、attempt lineage、理由和预算；扩大授权或显著增费先确认。
 
 `agents/openai.yaml` 和缓存都不是能力证明。runtime/path/tool 要求先做有效能力预检；能力快照的创建、
-刷新和复用读[宿主能力缓存](../docs/orchestrate/host-capability-cache.md)。实时 schema 优先，unknown 不能被
+刷新和复用读宿主能力缓存（`agentkit docs orchestrate host-capability-cache`）。实时 schema 优先，unknown 不能被
 缓存补成 allowed，缓存不能扩大授权。`protocol_version`、`runtime_version`、`content_digest` 分别表示
 协议兼容性、实现版本和精确安装内容，不得互相替代。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1992/agentkit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Agent engineering toolkit: orchestration, git worktree isolation, independent verification and bounded verify loops.",
   "license": "MIT",
   "repository": {
@@ -17,14 +17,14 @@
   },
   "type": "module",
   "bin": {
-    "agentkit": "./bin/agentkit.mjs"
+    "agentkit": "bin/agentkit.mjs"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
     "validate": "node tools/validate-skills.mjs",
-    "test": "node tools/validate-skills.mjs && node --test tests/*.test.mjs domains/*/*.test.mjs scripts/*.test.mjs",
+    "test": "node tools/validate-skills.mjs && node --test tests/*.test.mjs domains/*/*.test.mjs scripts/*.test.mjs evals/*/tests/*.test.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "files": [

package/run-agent-verify-loop/SKILL.md

@@ -51,8 +51,8 @@ verification run，消费其标准 Evidence Package。Loop 不执行或复制完
 - runtime 只生成 `embedded_verification_record`，不能导出、转换或冒充 Evidence Package；
 - 无独立 reviewer 时停止，不用实现者自审产生 pass。
 
-进入 embedded L1 前读取 [内嵌 review 适配器](../docs/loop/embedded-review-adapter.md)。
-verifier 行为语义以 [验收协议](../docs/verify/verification-protocol.md) 为唯一真源；独立安装本 Skill
+进入 embedded L1 前读取 内嵌 review 适配器（`agentkit docs loop embedded-review-adapter`）。
+verifier 行为语义以 验收协议（`agentkit docs verify verification-protocol`） 为唯一真源；独立安装本 Skill
 时，adapter 只携带绑定和最低输入要求，不重定义 verdict。
 
 ## Runtime 流程
@@ -79,8 +79,8 @@ run-embedded-l0 → 新上下文 reviewer → record-embedded-review
 ```
 
 所有状态写命令可带 `--expected-revision <n>`；revision 不匹配时拒绝写入。详细状态迁移见
-[Loop 状态机](../docs/loop/loop-state-machine.md)，恢复和熔断见
-[恢复与熔断](../docs/loop/recovery-and-fuses.md)。只有发生复制/移动、journal 恢复、
+Loop 状态机（`agentkit docs loop loop-state-machine`），恢复和熔断见
+恢复与熔断（`agentkit docs loop recovery-and-fuses`）。只有发生复制/移动、journal 恢复、
 reflection 或提案时才使用 `adopt-root / record-reflection / convergence-report / propose-improvement --help`。
 
 ## 决策规则

package/schemas/ledger-pointer-v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-skills.local/schemas/ledger-pointer-v1.schema.json",
+  "title": "Ledger Pointer v1",
+  "description": "仓级 ledger 指针，落盘于 <git-common-dir>/agentkit/ledgers/<ledger_id>.json。只回答 ledger 在哪，不是任何状态的真源：state_root 之外的字段仅用于展示与交叉核对，判定一律回读 state root 的事件链。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "ledger_id", "state_root", "contract_digest", "created_at"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "ledger_id": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$" },
+    "state_root": { "type": "string", "minLength": 1, "description": "ledger state root 的绝对路径；ledger 目录为 <state_root>/ledgers/<ledger_id>。" },
+    "contract_digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "init 时冻结的 Task Contract 摘要，只用于展示与交叉核对。" },
+    "created_at": { "type": "string", "minLength": 1 }
+  }
+}

package/schemas/orchestration-ledger-v1.schema.json

@@ -1,6 +1,23 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://agent-skills.local/schemas/orchestration-ledger-v1.schema.json", "title": "Orchestration Ledger v1", "type": "object", "required": ["schema_version", "runtime_version", "ledger_id", "revision", "contract_digest", "nodes", "edges", "attachments", "batches", "reflection_refs", "improvement_proposal_refs", "skill_provenance", "created_at", "updated_at"], "properties": { "schema_version": { "const": 1 }, "runtime_version": { "type": "string" }, "ledger_id": { "type": "string" }, "revision": { "type": "integer" }, "contract_digest": { "type": "string" }, "nodes": { "type": "object", "additionalProperties": { "$ref": "#/$defs/node" } }, "edges": { "type": "array" }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/attachment" } }, "batches": { "type": "object" }, "reflection_refs": { "type": "array" }, "improvement_proposal_refs": { "type": "array" }, "skill_provenance": { "type": "object" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false,
+  "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://agent-skills.local/schemas/orchestration-ledger-v1.schema.json", "title": "Orchestration Ledger v1", "type": "object", "required": ["schema_version", "runtime_version", "ledger_id", "revision", "contract_digest", "nodes", "edges", "attachments", "batches", "reflection_refs", "improvement_proposal_refs", "skill_provenance", "created_at", "updated_at"], "properties": { "schema_version": { "const": 1 }, "runtime_version": { "type": "string" }, "ledger_id": { "type": "string" }, "revision": { "type": "integer" }, "contract_digest": { "type": "string" }, "nodes": { "type": "object", "additionalProperties": { "$ref": "#/$defs/node" } }, "edges": { "type": "array" }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/attachment" } }, "batches": { "type": "object" }, "reflection_refs": { "type": "array" }, "improvement_proposal_refs": { "type": "array" }, "skill_provenance": { "type": "object" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "lifecycle": { "$ref": "#/$defs/lifecycle" } }, "additionalProperties": false,
   "$defs": {
+    "lifecycle": {
+      "description": "v1.2 新增的可选终态。缺省表示 ledger 仍然活跃；v1.1 及更早的快照没有这个字段，仍然合法。终态之后任务图冻结，只剩 record-reflection / propose-improvement / rebuild / doctor / status / inspect / batch-status。",
+      "type": "object",
+      "required": ["state", "closed_at", "reason", "closed_by_content_digest", "skill_drift_at_close"],
+      "properties": {
+        "state": { "enum": ["closed", "abandoned"] },
+        "closed_at": { "type": "string" },
+        "reason": { "description": "abandoned 必填非空；closed 固定为 null。", "type": ["string", "null"] },
+        "closed_by_content_digest": { "description": "写入终态事件时的 runtime 内容摘要；skill_drift_at_close 为 true 时它与 skill_provenance.content_digest 不同，标明这条终态由 drift 的 runtime 写入。", "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "skill_drift_at_close": { "type": "boolean" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        { "if": { "properties": { "state": { "const": "abandoned" } }, "required": ["state"] }, "then": { "properties": { "reason": { "type": "string", "minLength": 1 } } } },
+        { "if": { "properties": { "state": { "const": "closed" } }, "required": ["state"] }, "then": { "properties": { "reason": { "type": "null" } } } }
+      ]
+    },
     "attachment": {
       "type": "object",
       "required": ["attachment_id", "node_id", "type", "digest", "ref"],

package/shell-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "package_name": "@cr1992/agentkit",
-  "package_version": "1.1.0",
+  "package_version": "1.2.0",
   "cli": {
     "command": "agentkit",
     "entry": "bin/agentkit.mjs"

package/verify-agent-output/SKILL.md

@@ -31,8 +31,8 @@ controller 必须先提供：
 4. clean workdir，`HEAD == artifact_sha`；
 5. 新上下文 reviewer，或由用户中继的第二会话。只有当前实现者上下文时停止，不得伪造独立验收。
 
-详细 envelope 与字段规则见 [Evidence schema](../docs/verify/evidence-schema.md)。进入 L1 前必须完整读取
-[验收协议](../docs/verify/verification-protocol.md)。
+详细 envelope 与字段规则见 Evidence schema（`agentkit docs verify evidence-schema`）。进入 L1 前必须完整读取
+验收协议（`agentkit docs verify verification-protocol`）。
 
 ## 标准流程
 
@@ -56,7 +56,7 @@ agentkit verify validate --run <run-dir>
 ```
 
 所有子命令支持 `--help`；写命令支持 `--expected-revision`。尚未准备输入、happy path 失败或需要完整
-诊断时，先读 [输入准备与诊断命令](../docs/verify/input-preparation.md)。readiness/preflight 失败属于环境
+诊断时，先读 输入准备与诊断命令（`agentkit docs verify input-preparation`）。readiness/preflight 失败属于环境
 前提，不得记录为 Artifact verdict。
 
 ## 状态与裁决