@cr1992/agentkit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,130 @@
 
 ## Unreleased
 
+## 1.2.0 - 2026-09-20
+
+- 升级影响：本批改动多数触及 `core/`、`schemas/`、各域 `domains/<域>/` 或 `docs/<域>/`，升级后
+  所有升级前 init 的在途 ledger、loop、verify run 都会判定为 `skill_drift`，需要先收尾在途任务
+  再升级。升级后 drift 的 ledger 可用 `agentkit orchestrate ledger close --abandon --reason <text>`
+  记为放弃；drift 但未放弃、未进入终态的 ledger 指针会一直保留，等待 `close --abandon` 或
+  re-contract。升级前 init 的 ledger 没有仓级指针，`agentkit status` 找不到它们，仍需手传
+  `--ledger <ledger 目录>`。
+- 新增 `agentkit contract interview-ask / interview-answer / interview-freeze`：一台由实质性判据的
+  拒绝清单驱动提问、由自己的三条完成判据决定何时冻结的状态机。命令本身不调用任何模型，只出题、
+  校验回填、冻结；选项由调用它的模型填，选哪个由用户定。提问顺序固定为
+  `permissions → objective → acceptance → scope.include → scope.exclude → stop_conditions`，
+  `permissions` 必问且最先问——`scope.exclude` / `stop_conditions` 的判据只在 write 模式下生效，
+  而 scaffold 默认 `read_only`，不先问权限，写任务会一路走完却从没被问到边界和刹车。
+  轮次与作答记录写在契约草稿自己的 `extensions.interview` 里，并进入 `contract_digest`；上限 3 轮。
+  `permissions` / `objective` / `acceptance` 必须有 `source: "user"` 的作答记录，不接受 assumption——
+  否则模型可以先把 `objective` 写进草稿，再记一条"用户说都行"，在没有任何用户选择的情况下把契约冻掉。
+  只有 `scope.include` / `scope.exclude` / `stop_conditions` 可以 `deferred`，`assumed` 会原样写进对应字段
+  （执行方读的是契约字段而不是 `extensions`），`assumed` 允许是空数组表示"没有"。
+  用法见 `agentkit docs orchestrate contract-interview`。
+- 新增 `agentkit contract scaffold` 别名。契约骨架下沉到 `core/contract-scaffold.mjs`，
+  与 `agentkit verify scaffold --kind contract` 同源，两边只在 `skill_set` 上分叉
+  （各自冻结自己域的 content digest）。
+- 契约、profile 的创建入口（`contract validate`、`ledger init`、`verify preflight / init / prepare-run`、
+  `loop init`）新增实质性检查，原样照抄 `verify scaffold` 生成的占位契约或 profile 一律拒绝，
+  报错给出字段路径与当前值但不给可以照抄的合规值；`prepare-run` 遇到该拒绝时紧凑输出也会带上
+  `errors`。续跑与恢复入口（`ledger add-node`、`verify record-review` / `validate`、
+  `loop adopt-root` / `record-embedded-review` / `validate`）不重判实质性，行为不变。
+  同一批判据里，每条 `acceptance[].contract_item_id` 必须至少被一条 `l1_review` 引用，不分权限
+  模式，只在同时拿到契约与 profile 的创建入口执行；`permissions.mode` 为 `write` 且
+  `scope.exclude` / `stop_conditions` 为空只降级为 warning，不拒绝、退出码不变。`warnings` 键仅
+  非空时出现：见 `contract validate`、`ledger init`、`verify init`、`loop init` 的返回值，以及
+  `preflight` 报告（该键恒在，可能是空数组）；`prepare-run` 把它放进完整报告的
+  `preflight.warnings`，默认紧凑输出不带，取证需加 `--verbose`。`ledger / verify / loop doctor`
+  新增 `substance_warnings`：恒在，把手上能执行的判据整体降级为 warning，不进 `findings`，
+  不改变 `healthy`。
+- 声明 `extensions.verification.provider === 'verify-agent-output'` 时，`completion_ready` 要求每个
+  required 的实现节点（`verification.requirement !== 'not_applicable'`）要么自身是已通过的
+  `independent_evidence` 节点，要么沿 `dependency` / `barrier` 边可达一个已通过、
+  `artifact_scope: integration_candidate` 的 `independent_evidence` 节点；不满足则拒绝视为完成。
+  没有任何 required 节点的空 ledger，`completion_ready` 恒为 false。`status` / `inspect` 的
+  `summary` 新增三份名单：`uncovered_implementation_nodes`（声明 provider 但未被覆盖的实现节点）、
+  `non_required_implementation_nodes`、`nodes_without_independent_evidence`（未声明 provider 时，
+  列出尚未经独立验证的实现节点）。
+- `orchestrate ledger close` 要求 `status` 判定的 `completion_ready` 为 true，不满足时非零退出，
+  逐条列出未满足的条件（同一份文本同时出现在 `status.summary.unmet_completion_conditions`）；
+  `close --abandon --reason <text>` 记为放弃，`reason` 必填且非空，不带 `--abandon` 的 `--reason`
+  会被拒绝。事件链新增终态事件 `closed` / `abandoned`，快照新增可选字段 `lifecycle`
+  （终态种类、时间、reason、写入时的 runtime 摘要与 drift 状态），旧快照不含该字段仍然合法。
+  `close` 返回体新增 `pointer` 字段（仓级指针的写入/删除结果）。ledger 进入终态后任务图冻结，
+  `add-node / add-edge / dispatch-record / update / attach / batch-init / batch-record / close`
+  等修改命令一律拒绝，只读命令与 `record-reflection / propose-improvement / rebuild` 仍可用；
+  `status` / `inspect` 新增输出键 `skill_drift`，drift 下 `close --abandon` 是唯一仍能写入的路径，
+  其余修改命令照常拒绝。
+- ledger 状态发现。`orchestrate ledger init` 在 `contract.environment.repository` 所属仓库的
+  git common dir 下写仓级指针 `<git-common-dir>/agentkit/ledgers/<ledger_id>.json`（第 18 份
+  canonical schema `ledger-pointer-v1`），`close`（含 `--abandon`）成功后删除它。**指针不是真源**：
+  只回答"ledger 在哪"，一切判定仍回读 state root 的事件链；指针只写在 `.git/` 下，不进版本控制。
+  写/删失败一律降级为 warning，不让 `init` 失败后留下半个 ledger。
+- 新增顶层 `agentkit status [--json]`：从 cwd 找 git common dir，读全部指针、回读各 state root，
+  筛出未终态的 ledger，单屏给出当前阶段、活跃 worktree、阻塞项、未覆盖节点与下一步命令。多个时
+  全部列出不猜测；受管 worktree 里用 record 的 `ledger` 字段收窄；`skill_drift` 的单独成组，
+  下一步只给 `close --abandon` 与 re-contract。
+- `orchestrate ledger doctor` 新增 `--repository <path>` 档位（返回体新增 `mode: "repository"`，
+  单 ledger 档位为 `mode: "ledger"`），扫描并分类该仓的全部指针；回收是显式的
+  `orchestrate ledger reclaim-pointers --repository <path>`，不藏在只读的 `doctor` 里。
+  **drift 但未进入终态的 ledger 指针一律保留**：它还需要有人来 `close --abandon` 或 re-contract。
+- `worktree spawn` 新增可选 `--ledger <id>`，写进 record 的 `ledger` 字段供 `agentkit status` 收窄；
+  worktree 域只校验 id 格式，格式规则下沉到 `core/ledger-pointer.mjs`，两个域之间不互相 import。
+- 编排拦截点（缺 `verification_ref`、`verification_ref` 类型不符、`completion_ready` 为 false 时
+  `close`、drift 下执行修改命令）的报错文案改写为"违规原因 + 合规做法"：点出字段路径或节点 id、
+  当前值、要求的性质与可执行的命令/flag 名，取值一律用占位符，不给可以照抄的合规值；不新增拦截点，
+  不改变任何命令的放行/拒绝行为、`error` 码或退出码。
+- `verify-agent-output` 的证伪任务提示词新增一条：已成立的 finding 涉及结构调整时，`expected`
+  必须写出具名重构手法且只针对该 finding 的 `contract_item_id`，给不出具名手法的结构评价不写入
+  findings；不扩大取证范围，不新增 schema 字段。
+- 架构文档 `docs/architecture/skill-system-architecture.md` 只保留与真源不重复的内容，其余段落
+  改写为指向 `domains/<域>/`、`docs/<域>/`、四份 `SKILL.md`、`schemas/`、`core/digest.mjs` 等真源的
+  指针（累计从 114,315 字节精简到 49,877 字节）；`tests/architecture-consistency.test.mjs` 的判据
+  从"固定字符串存在"改为"指针能实际解析且覆盖当前 `domains/*` 与 `docs/<域>/` 目录"。四份
+  `SKILL.md` 补齐指向 `agentkit status`、`orchestrate ledger close`、`contract interview-*`、
+  `worktree spawn --ledger` 的指针；`tests/documentation.test.mjs` 新增孤儿文档检查，
+  `docs/<域>/` 下每个主题必须被至少一个 `SKILL.md` 以 `agentkit docs <域> <主题>` 的形式指到。
+- 四个 Skill 的正文字符预算按当前实测值重新标定并去掉总量卡口里不再起约束作用的重复上限；
+  `description` 合计上限改为按 Skill 数量推导。删除 `approximate_tokens`
+  （原按英文字符数估算 token，在中英混排文本上系统性偏差较大）。`tests/skill-budgets.mjs`
+  作为预算数字的共享真源，供架构文档反查比对。
+- 新增手动触发的发版流水线（`.github/workflows/release.yml`）：`verify`（限定从 `main` 发布、
+  版本号须与 `package.json` 一致、该版本不得已在 registry 上、`npm test` 与 tarball 干净安装验证，
+  Node 22/24 双版本矩阵）→ `publish`（`npm publish --provenance`）→ `attest`（从 registry 反装并跑
+  `agentkit doctor` 确认版本一致，同样跑 Node 22/24 双版本矩阵）→ `tag-and-release`（同一 commit
+  对同一 semver 打 tag、建 GitHub Release，正文从本文件对应小节程序化提取，缺小节即失败）。
+  `verify` 与 `attest` 两段的发布证据（`npm pack --dry-run` 文件清单、`agentkit doctor` 输出，
+  均带上 commit SHA 与版本号）按矩阵各存为一份 GitHub Actions 产物。需要仓库 secret `NPM_TOKEN`。
+- 新增 `evals/protocol-routing/`：协议路由评测 harness 与 11 条用例，用于衡量 agent 在给定提示下
+  是否按预期路由到只读、`agentkit <域> <动词>` 或写操作。支持预录 JSONL 回放（接入 `npm test`）与
+  两种真实评测运行方式——GitHub Actions + `ANTHROPIC_API_KEY`，或本机一次性容器
+  （`evals/protocol-routing/container/`）+ `claude setup-token` 生成的订阅 token；容器以只读挂载
+  仓库、非 root 用户、`--cap-drop ALL` 等收紧运行。均不进发布包，不在任何 Skill 内容摘要范围内。
+- 本批各域新增用户可见能力，同步各升一个 minor：`orchestrate-subagents` 的
+  `ORCHESTRATION_RUNTIME_VERSION` 1.7.0 → 1.8.0（`ledger close`、`reclaim-pointers`、`status` 新键）；
+  `contract-tool` 的 `capabilities().runtime_version` 1.1.0 → 1.2.0（`scaffold`、`interview-*`）；
+  `verify-agent-output` 的 `RUNTIME_VERSION` 1.3.0 → 1.4.0（实质性检查、`warnings` /
+  `substance_warnings`）；`run-agent-verify-loop` 的 `RUNTIME_VERSION` 1.0.0 → 1.1.0（同上）；
+  `manage-worktrees` 的 `runtime_version` 1.4.0 → 1.5.0（`spawn --ledger`）。
+  `orchestration-reflection`、`worker-capability-preflight`、`review-budget` 本批未改行为，
+  runtime version 不动。
+
+## 1.1.1 - 2026-09-08
+
+- 修复 `doctor` 对已回收 record 仍生成需要活树才能收敛的 metadata finding。`stack_parent`、
+  `history_operation` 和 `review_refresh` 三个分支缺少 `worktree_state` 过滤，对已删除目录报
+  `STACK_PARENT_ADVANCED` 等提示，其补救动作（managed rebase/retarget、`rebase --continue`、
+  `refresh-review`）在回收后都无法执行，噪声永远清不掉；其中 error 级的还会按「任何 error 都暂停
+  `spawn/adopt`」把后续派工钉死。生命周期与 watcher 两个收集器早已是这个口径，本次补齐 metadata。
+- `manage-worktrees` 补齐 `--no-watch` 的使用判据：只用于确定不会合入，或武装失败原因为永久性
+  （否则 pending 会积一条清不掉的 `AUTO_RECLAIM_NOT_ARMED`）。明确禁止因 watcher 活不过会话或
+  为压后台进程数而关闭——前者是 `watch-service` 的职责，后者不成立（`disabled` 持久且不重试）。
+- `watch-service status` 进入强制流程表的「恢复/盘点」行，不再只以表外散文形式存在。
+- 四个 SKILL.md 对 `docs/<域>/` 的引用从相对链接改为 `agentkit docs <域> <主题>` 命令。宿主把 Skill
+  基目录报成安装路径（常为软链），Read 工具按词法折叠 `..`，原 `../docs/...` 链接在安装态全部不可达，
+  agent 只剩摘要表。`validate-skills` 新增安装态检查：SKILL.md 相对链接越出 Skill 目录即报错，
+  `agentkit docs` 引用的主题必须真实存在。
+
 ## 1.1.0 - 2026-09-07
 
 - 修复从待回收 worktree 自身执行 `reclaim` 时，目录删除后误判本地分支已不存在的问题；未完成的

package/README.en.md

@@ -12,7 +12,7 @@ the `orchestrate-subagents` control plane, which then chooses lightweight or ful
 rerouting from effective capabilities, task scale, and local model policy. Providers remain independently usable and
 compose through frozen Artifact, Binding, and Evidence envelopes.
 
-[Detailed collaboration contracts and safety boundaries (Chinese, v1.1.0)](./docs/architecture/skill-system-architecture.md)
+[Detailed collaboration contracts and safety boundaries (Chinese, v1.2.0)](./docs/architecture/skill-system-architecture.md)
 
 ## Included skills
 
@@ -75,6 +75,7 @@ script entry points remain as compatibility forwarders; new integrations should
 
 ```bash
 agentkit capabilities --json
+agentkit status --json
 agentkit doctor --json
 agentkit worktree --help
 agentkit contract --help

package/README.md

@@ -11,7 +11,7 @@
 其内部再按有效能力、任务规模、本地模型配置和验收证据选择轻量或完整运行方式及后续重路由。
 各 provider 仍可独立使用，并通过冻结的 Artifact、Binding 和 Evidence envelope 按需组合。
 
-[Agent Skills 协作契约与安全边界（v1.1.0）](./docs/architecture/skill-system-architecture.md)
+[Agent Skills 协作契约与安全边界（v1.2.0）](./docs/architecture/skill-system-architecture.md)
 
 ## 包含的 Skill
 
@@ -72,6 +72,7 @@ npx skills add https://github.com/cr1992/agentkit.git -g --agent '*' --skill man
 
 ```bash
 agentkit capabilities --json
+agentkit status --json
 agentkit doctor --json
 agentkit worktree --help
 agentkit contract --help

package/bin/cli.mjs

@@ -4,7 +4,7 @@
 // CLI 自身的输出（help、version、capabilities 聚合、docs、doctor 汇总）不受该约束，
 // 但任何迁移提示只写 stderr，避免污染可被管道消费的 stdout。
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -109,7 +109,7 @@ function helpText() {
     '',
     '域：',
     '  worktree <命令>              Git worktree 隔离与生命周期（含 worktree scan）',
-    '  contract <命令>              任务契约规范化、校验、摘要与投影',
+    '  contract <命令>              任务契约 scaffold、访谈、规范化、校验、摘要与投影',
     '  orchestrate <工具> <命令>    ledger | preflight | review-budget | reflection',
     '  host <工具> <命令>           cache | model-policy',
     '  verify <命令>                冻结 Artifact 的一次性独立验收',
@@ -117,6 +117,7 @@ function helpText() {
     '',
     '跨域命令：',
     '  capabilities [--json]        汇总四个 Skill 的能力发现结果',
+    '  status [--json]              从当前仓库的 ledger 指针发现未终态 ledger 并给出下一步',
     '  doctor [--json]              检查 Node、Git、安装完整性与各域能力发现',
     '  docs [<域>] [<主题>]         输出参考文档原文；缺主题时只列索引',
     '  --version                    打印版本',
@@ -203,6 +204,231 @@ function runDoctor(args) {
   return healthy ? 0 : 1;
 }
 
+// ── agentkit status ───────────────────────────────────────────────────────────
+// 顶层状态发现：从 cwd 找 git common dir，读仓级指针，回读各 state root，筛出未终态的 ledger。
+// 这是 bin 层同时读 orchestrate（ledger 状态）与 worktree（record 里的 ledger 绑定）两个域的地方——
+// 域与域之间不互相 import，跨域聚合只发生在这一层。
+const LEDGER_TARGET = GROUPS.orchestrate.ledger;
+const PHASE_LABELS = {
+  empty: '空 ledger（还没有任何节点）',
+  not_started: '未开始',
+  in_progress: '进行中',
+  blocked: '阻塞',
+  ready_to_close: '待收口',
+};
+
+function ledgerPhase(status) {
+  const nodes = Object.values(status.nodes ?? {});
+  if (!nodes.length) return 'empty';
+  if (status.summary?.completion_ready) return 'ready_to_close';
+  if (nodes.some((node) => node.state === 'blocked')) return 'blocked';
+  if (nodes.some((node) => ['running', 'awaiting_verification'].includes(node.state))) return 'in_progress';
+  if (nodes.every((node) => node.state === 'pending')) return 'not_started';
+  return 'in_progress';
+}
+
+// drift 的 ledger 不给续跑命令：冻结的协议已经不成立，只剩记为放弃或换当前 runtime 重签。
+function nextCommands(entry) {
+  if (entry.skill_drift) {
+    return [
+      `agentkit orchestrate ledger close --ledger ${entry.ledger_dir} --abandon --reason <text>`,
+      're-contract：用当前 runtime 重签 Task Contract，再 agentkit orchestrate ledger init --contract <contract.json> --state-root <仓外路径>',
+    ];
+  }
+  if (entry.phase === 'ready_to_close') return [`agentkit orchestrate ledger close --ledger ${entry.ledger_dir}`];
+  if (entry.phase === 'empty') return [`agentkit orchestrate ledger add-node --ledger ${entry.ledger_dir} --input <node.json>`];
+  if (entry.phase === 'blocked') {
+    return [
+      `agentkit orchestrate ledger status --ledger ${entry.ledger_dir}`,
+      `agentkit orchestrate ledger update --ledger ${entry.ledger_dir} --node <node> --input <state.json>`,
+    ];
+  }
+  return [`agentkit orchestrate ledger status --ledger ${entry.ledger_dir}`];
+}
+
+async function worktreeRecords(commonDir) {
+  try {
+    const { listRecordCacheEntries } = await import('../domains/worktree/worktree-trace.mjs');
+    return listRecordCacheEntries(commonDir)
+      .map((entry) => entry.record)
+      .filter((record) => record && record.worktree_state !== 'reclaimed' && record.worktree_state !== 'archived');
+  } catch {
+    // worktree 域没装或 trace store 不可读时，status 仍然要能靠仓级指针工作。
+    return [];
+  }
+}
+
+function currentWorktreePath() {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  const top = result.stdout.trim();
+  if (!top) return null;
+  try { return realpathSync(top); } catch { return top; }
+}
+
+function worktreeSummary(record) {
+  return {
+    worktree_id: record.worktree_id,
+    task: record.task,
+    branch: record.branch ?? null,
+    path: record.path,
+    agent: record.agent ? `${record.agent.host}/${record.agent.id}` : null,
+    task_status: record.task_status ?? null,
+    worktree_state: record.worktree_state ?? null,
+  };
+}
+
+// ledger 目录不在这里重新推导：它由 core 的 ledgerDirectory 算出后传进来，避免第二份推导规则。
+function describeLedger(pointer, ledgerDir, status, records) {
+  const nodes = Object.values(status.nodes ?? {});
+  const entry = {
+    ledger_id: status.ledger_id,
+    ledger_dir: ledgerDir,
+    state_root: pointer.state_root,
+    revision: status.revision,
+    contract_digest: status.contract_digest,
+    // 指针里的摘要只用于交叉核对与展示：不一致说明指针陈旧，状态仍以 state root 为准。
+    pointer_contract_digest_matches: status.contract_digest === pointer.contract_digest,
+    skill_drift: Boolean(status.skill_drift),
+    skill_drift_remediation: status.skill_drift_remediation ?? null,
+    recovery_needed: Boolean(status.recovery_needed),
+    summary: {
+      pending: status.summary?.pending ?? 0,
+      active: status.summary?.active ?? 0,
+      terminal: status.summary?.terminal ?? 0,
+      completion_ready: Boolean(status.summary?.completion_ready),
+    },
+    blockers: [
+      ...nodes.filter((node) => node.state === 'blocked').map((node) => `${node.node_id} blocked：${node.reason ?? '未记录原因'}`),
+      ...nodes.filter((node) => node.state === 'failed' && node.required !== false).map((node) => `${node.node_id} failed：${node.reason ?? '未记录原因'}`),
+    ],
+    uncovered_implementation_nodes: status.summary?.uncovered_implementation_nodes ?? [],
+    unmet_completion_conditions: status.summary?.unmet_completion_conditions ?? [],
+    worktrees: records.filter((record) => record.ledger === status.ledger_id).map(worktreeSummary),
+  };
+  entry.phase = ledgerPhase(status);
+  entry.next_commands = nextCommands(entry);
+  return entry;
+}
+
+function collectLedgers(pointers, pointerApi, records) {
+  const active = [];
+  const drifted = [];
+  const terminal = [];
+  const dangling = [];
+  for (const item of pointers) {
+    if (item.error) {
+      dangling.push({ pointer_path: item.path, ledger_id: item.ledger_id, state: 'malformed', detail: item.error });
+      continue;
+    }
+    const pointer = item.pointer;
+    const dir = pointerApi.ledgerDirectory(pointer);
+    if (!existsSync(join(dir, 'events.ndjson'))) {
+      dangling.push({ pointer_path: item.path, ledger_id: pointer.ledger_id, state: 'dangling_state_root', detail: `state_root ${pointer.state_root} 下找不到 ledger 事件链 ${join(dir, 'events.ndjson')}` });
+      continue;
+    }
+    const status = capture(LEDGER_TARGET, ['status', '--ledger', dir]);
+    if (!status) {
+      dangling.push({ pointer_path: item.path, ledger_id: pointer.ledger_id, state: 'unreadable', detail: `ledger 目录 ${dir} 无法读取状态；用 agentkit orchestrate ledger doctor --ledger ${dir} 查看` });
+      continue;
+    }
+    if (status.lifecycle) {
+      terminal.push({ pointer_path: item.path, ledger_id: pointer.ledger_id, ledger_dir: dir, lifecycle_state: status.lifecycle.state, closed_at: status.lifecycle.closed_at });
+      continue;
+    }
+    const entry = { ...describeLedger(pointer, dir, status, records), pointer_path: item.path };
+    (entry.skill_drift ? drifted : active).push(entry);
+  }
+  return { active, drifted, terminal, dangling };
+}
+
+function renderStatusText(report) {
+  const lines = [`agentkit ${report.cli_version} status`];
+  lines.push(`当前工作树: ${report.worktree_root ?? '(未知)'}  git common dir: ${report.git_common_dir}`);
+  lines.push(`指针目录: ${report.pointer_dir}`);
+  if (report.scope === 'worktree') {
+    lines.push(`当前 worktree 绑定 ledger=${report.worktree_binding.ledger_id}（record ${report.worktree_binding.worktree_id.slice(0, 8)}），已收窄到该 ledger。`);
+  } else if (report.worktree_binding) {
+    lines.push(`当前 worktree 的 record 绑定 ledger=${report.worktree_binding.ledger_id}，但该 ledger 没有可用指针；下面列出全部未终态 ledger。`);
+  }
+
+  const groups = [['未终态 ledger', report.ledgers], ['skill_drift ledger（不能续跑）', report.drifted_ledgers]];
+  if (!report.ledgers.length && !report.drifted_ledgers.length) {
+    lines.push('');
+    lines.push('未发现 ledger。');
+    lines.push(`  在本仓 init 过的 ledger 会在 ${report.pointer_dir} 留下指针；升级前 init 的 ledger 没有指针，需要手传 --ledger <ledger 目录>。`);
+    lines.push('  新建：agentkit orchestrate ledger init --contract <contract.json> --state-root <仓外路径>');
+  }
+  for (const [title, entries] of groups) {
+    if (!entries.length) continue;
+    lines.push('');
+    lines.push(`${title}：${entries.length} 个`);
+    for (const entry of entries) {
+      lines.push(`  [${entry.ledger_id}] 阶段=${PHASE_LABELS[entry.phase] ?? entry.phase} revision=${entry.revision} 节点 pending/active/terminal=${entry.summary.pending}/${entry.summary.active}/${entry.summary.terminal}`);
+      lines.push(`    ledger: ${entry.ledger_dir}`);
+      lines.push(`    活跃 worktree: ${entry.worktrees.length ? entry.worktrees.map((item) => `${item.task}@${item.path}`).join('、') : '无'}`);
+      lines.push(`    阻塞项: ${entry.blockers.length ? entry.blockers.join('；') : '无'}`);
+      lines.push(`    未覆盖节点: ${entry.uncovered_implementation_nodes.length ? entry.uncovered_implementation_nodes.join('、') : '无'}`);
+      if (entry.skill_drift) lines.push(`    skill_drift: ${entry.skill_drift_remediation ?? '冻结的 runtime 与当前不一致'}`);
+      lines.push('    下一步:');
+      for (const command of entry.next_commands) lines.push(`      ${command}`);
+    }
+  }
+  if (report.dangling_pointers.length) {
+    lines.push('');
+    lines.push(`悬空指针：${report.dangling_pointers.length} 个（state root 已不存在或指针损坏）`);
+    for (const item of report.dangling_pointers) lines.push(`  [${item.ledger_id}] ${item.state}：${item.detail}`);
+    lines.push(`  回收：agentkit orchestrate ledger reclaim-pointers --repository ${report.worktree_root ?? report.git_common_dir}`);
+  }
+  if (report.terminal_pointers.length) {
+    lines.push('');
+    lines.push(`已终态但指针仍在：${report.terminal_pointers.length} 个`);
+    for (const item of report.terminal_pointers) lines.push(`  [${item.ledger_id}] ${item.lifecycle_state} @ ${item.closed_at}`);
+    lines.push(`  回收：agentkit orchestrate ledger reclaim-pointers --repository ${report.worktree_root ?? report.git_common_dir}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function runStatus(args) {
+  const unknown = args.filter((arg) => arg !== '--json');
+  if (unknown.length) {
+    process.stderr.write(`agentkit status: 未知选项「${unknown[0]}」；本命令只接受 --json，作用域由当前工作目录所属的 git 仓库决定\n`);
+    return 2;
+  }
+  const pointerApi = await import('../core/ledger-pointer.mjs');
+  const found = pointerApi.resolveGitCommonDir(process.cwd());
+  if (!found.common_dir) {
+    process.stderr.write(`agentkit status: ${found.reason}；status 从当前工作目录所属的 git 仓库读取仓级 ledger 指针，请在仓库内运行\n`);
+    return 2;
+  }
+  const commonDir = found.common_dir;
+  const records = await worktreeRecords(commonDir);
+  const here = currentWorktreePath();
+  const bound = here ? records.find((record) => record.path === here && record.ledger) ?? null : null;
+  const collected = collectLedgers(pointerApi.listLedgerPointers(commonDir), pointerApi, records);
+
+  // 受管 worktree 里优先用 record 的 ledger 字段收窄；收窄不到就退回全量，并说明原因，不做猜测。
+  const narrowed = bound ? [...collected.active, ...collected.drifted].filter((entry) => entry.ledger_id === bound.ledger) : [];
+  const scope = narrowed.length ? 'worktree' : 'repository';
+  const report = {
+    cli: 'agentkit',
+    cli_version: packageVersion(),
+    // 当前工作树（可能是 linked worktree）；reclaim-pointers 的 --repository 接受该仓的任意工作树。
+    worktree_root: here,
+    git_common_dir: commonDir,
+    pointer_dir: pointerApi.pointerDirectory(commonDir),
+    scope,
+    worktree_binding: bound ? { ledger_id: bound.ledger, worktree_id: bound.worktree_id, task: bound.task, path: bound.path } : null,
+    ledgers: scope === 'worktree' ? narrowed.filter((entry) => !entry.skill_drift) : collected.active,
+    drifted_ledgers: scope === 'worktree' ? narrowed.filter((entry) => entry.skill_drift) : collected.drifted,
+    dangling_pointers: collected.dangling,
+    terminal_pointers: collected.terminal,
+  };
+  if (args.includes('--json')) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else process.stdout.write(renderStatusText(report));
+  return 0;
+}
+
 function docsIndex(domain) {
   const dir = join(PACKAGE_ROOT, 'docs', DOC_DOMAINS[domain]);
   if (!existsSync(dir)) return [];
@@ -247,6 +473,7 @@ export async function main(argv) {
     return 0;
   }
   if (head === 'capabilities') return runCapabilities(rest);
+  if (head === 'status') return runStatus(rest);
   if (head === 'doctor') return runDoctor(rest);
   if (head === 'docs') return runDocs(rest);
 

package/core/contract-scaffold.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+// Task Contract 骨架的唯一构造出处。
+//
+// 骨架此前只长在 verify 域的 scaffold 里。orchestrate 域要提供 `contract scaffold` 别名，
+// 而 domains/ 之间禁止互相 import，照抄一份骨架就会出现两个各自漂移的真源：
+// 一边补了字段、另一边没补，interview 出的题和 verify 的占位判据就会对不上。
+// 因此把骨架本身下沉到 core，两个域各自注入自己的 skill 绑定与签名口径。
+//
+// 这里只负责"形状"，不负责"内容"：占位字面量仍以 core/contract-substance.mjs 为唯一出处，
+// 本模块只引用，不重新声明——否则 #12 的占位判据会静默失效。
+// 摘要也不在这里算：verify 与 orchestrate 的 canonicalJson 严格度不同（见 core/digest.mjs），
+// 由调用方用自己的 kit 签名，本模块返回未签名的对象。
+import { resolve } from 'node:path';
+
+import { SCAFFOLD_OBJECTIVE, SCAFFOLD_REQUIREMENT, SCAFFOLD_SCOPE_ITEM } from './contract-substance.mjs';
+
+/** scaffold 默认 acceptance 条目的 ID。interview 回填第一条要求时复用它，不另起编号。 */
+export const SCAFFOLD_ACCEPTANCE_ID = 'acceptance-1';
+
+/**
+ * @param {{ workdir: string, contractId: string, skillSet: { name: string, version: string, content_digest: string, provider_mode: string }[] }} options
+ * @returns {Record<string, any>} 未签名的契约骨架；字段顺序即两个域 scaffold 输出的字段顺序。
+ */
+export function buildScaffoldContract({ workdir, contractId, skillSet }) {
+  return {
+    schema_version: 1,
+    contract_id: contractId,
+    objective: SCAFFOLD_OBJECTIVE,
+    scope: { include: [SCAFFOLD_SCOPE_ITEM], exclude: [] },
+    acceptance: [{ contract_item_id: SCAFFOLD_ACCEPTANCE_ID, requirement: SCAFFOLD_REQUIREMENT }],
+    permissions: { mode: 'read_only', writable_paths: [] },
+    environment: { repository: resolve(workdir), isolation: 'caller_supplied' },
+    skill_set: skillSet.map((skill) => ({ ...skill })),
+    stop_conditions: [],
+    extensions: {},
+  };
+}

package/core/contract-substance.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+// Task Contract 与 Verification Profile 的实质性检查。
+//
+// 形状校验只能说明结构合法。scaffold 原样生成的契约和 profile 结构完全合法，却什么也没断言，
+// 这样的输入一路走到 Evidence 签发，整条 fail-closed 链就退化成了 fail-open。本模块负责在冻结的
+// 那一刻把这类输入拦下来。
+//
+// 调用约定：
+// - 只在创建入口调用：contract validate、ledger init、verify preflight/init/prepare-run、loop init；
+// - 续跑与恢复入口只做形状校验，不重判实质性，理由有两条：
+//   (a) 契约冻结后不可变，实质性只在冻结那一刻判定一次，再判一次不会得到新信息；
+//   (b) verify validate、loop validate、adopt-root、各域 doctor 这些只读回看路径不经过 mutate，
+//       会读到本判据出现之前冻结的状态；在这些路径上拒绝，等于让历史 Evidence 的审计结论随
+//       runtime 版本变化；
+// - mutate 路径不需要这层保护：三个域的 mutate 都先比对 skill_provenance.content_digest，
+//   摘要范围含 core/ 与 schemas/。跨版本的在途状态在到达校验器之前就已经以 skill_drift 终止，
+//   同版本内的在途状态则已经过了创建入口；
+// - 三个域的 doctor 用 substanceWarnings 把同一批判据整体降级成 warning，不改变 healthy；
+// - 各入口直接使用这里给出的原因字符串，只套各自的错误类型，不改写措辞。
+//
+// error 与 warning 的分界：只做存在性检查的判据一律只给 warning。"write 模式没写 exclude" 说明
+// 边界没划出来，但划不划得对本模块判断不了，拿它拒绝创建就是把没有信息量的检查当门禁。
+//
+// scaffold 的占位字面量以这里为唯一出处，verify scaffold 直接引用。两边一旦各自漂移，判据就会静默失效。
+
+export const SCAFFOLD_OBJECTIVE = 'TODO: describe the frozen artifact objective';
+export const SCAFFOLD_REQUIREMENT = 'TODO: replace with an observable requirement';
+export const SCAFFOLD_SCOPE_ITEM = 'TODO';
+export const SCAFFOLD_CHECK_ID = 'replace-with-real-check';
+export const SCAFFOLD_ARGV = Object.freeze(['node', '--version']);
+
+/** @typedef {{ errors: string[], warnings: string[] }} SubstanceReport */
+
+const quote = (/** @type {unknown} */ value) => JSON.stringify(value);
+
+/** @param {unknown} argv */
+function isScaffoldArgv(argv) {
+  return Array.isArray(argv) && argv.length === SCAFFOLD_ARGV.length && argv.every((item, index) => item === SCAFFOLD_ARGV[index]);
+}
+
+/**
+ * 契约层判据。只依赖契约本身，任何创建入口都能执行。
+ * 输入可能尚未通过形状校验，所以每个字段都按不可信数据读取。
+ * @param {any} contract
+ * @returns {SubstanceReport}
+ */
+export function contractSubstance(contract) {
+  const errors = [];
+  if (contract?.objective === SCAFFOLD_OBJECTIVE) {
+    errors.push(`objective = ${quote(SCAFFOLD_OBJECTIVE)}：仍是 scaffold 占位文本，需写明本次任务的真实目标`);
+  }
+  const acceptance = Array.isArray(contract?.acceptance) ? contract.acceptance : [];
+  acceptance.forEach((item, index) => {
+    if (item?.requirement === SCAFFOLD_REQUIREMENT) {
+      errors.push(`acceptance[${index}].requirement = ${quote(SCAFFOLD_REQUIREMENT)}：仍是 scaffold 占位文本，需写明可观察的验收要求`);
+    }
+  });
+  const include = Array.isArray(contract?.scope?.include) ? contract.scope.include : [];
+  include.forEach((item, index) => {
+    if (item === SCAFFOLD_SCOPE_ITEM) errors.push(`scope.include[${index}] = ${quote(SCAFFOLD_SCOPE_ITEM)}：仍是 scaffold 占位，需列出本次任务的真实范围`);
+  });
+  const warnings = [];
+  // 只读合同越界由 permissions 本身兜住；写入合同则全靠 scope.exclude 与 stop_conditions 划边界，
+  // 两处都空等于把"改哪里、什么时候停"完全交给执行方判断。
+  if (contract?.permissions?.mode === 'write') {
+    if (!(Array.isArray(contract?.scope?.exclude) ? contract.scope.exclude : []).length) {
+      warnings.push('permissions.mode = "write" 且 scope.exclude 为空：写入型合同没有划出任何不可触碰的面，改动跑偏时没有范围边界可对照');
+    }
+    if (!(Array.isArray(contract?.stop_conditions) ? contract.stop_conditions : []).length) {
+      warnings.push('permissions.mode = "write" 且 stop_conditions 为空：写入型合同没有声明任何终止条件，执行失控时没有机械停机点');
+    }
+  }
+  return { errors, warnings };
+}
+
+/**
+ * profile 层判据。只有同时拿到 profile 的入口才能执行。
+ * 两个分支各自独立触发：只改 check_id、或只换 argv，都绕不过去。
+ * @param {any} profile
+ * @returns {SubstanceReport}
+ */
+export function profileSubstance(profile) {
+  const errors = [];
+  const checks = Array.isArray(profile?.l0_checks) ? profile.l0_checks : [];
+  checks.forEach((check, index) => {
+    if (check?.check_id === SCAFFOLD_CHECK_ID) errors.push(`l0_checks[${index}].check_id = ${quote(SCAFFOLD_CHECK_ID)}：这是 scaffold 占位检查的标识，需替换为真实检查`);
+  });
+  if (checks.length > 0 && checks.every((check) => isScaffoldArgv(check?.argv))) {
+    errors.push(`l0_checks[*].argv 全部为 ${quote(SCAFFOLD_ARGV)}：只证明运行环境存在，没有检查本次 Artifact`);
+  }
+  return { errors, warnings: [] };
+}
+
+/**
+ * 契约 × profile 的覆盖判据。只有同时拿到两份文件的入口才能执行。
+ * 现有 profile 校验只做单向绑定（拒绝 L1 引用不存在的 acceptance），反向不成立：
+ * 一条 acceptance 可以一次都不被审，签出来的 Evidence 照样是"全部通过"。
+ *
+ * 这里只保证每条 acceptance 都被 L1 审过，不保证被 L0 测到：l0_checks 条目没有
+ * contract_item_id 字段，schema 又是 additionalProperties: false，无从建立对应关系。
+ * @param {any} contract @param {any} profile
+ * @returns {SubstanceReport}
+ */
+export function coverageSubstance(contract, profile) {
+  const errors = [];
+  const reviewed = new Set((Array.isArray(profile?.l1_review) ? profile.l1_review : []).map((item) => item?.contract_item_id).filter((id) => typeof id === 'string' && id));
+  const acceptance = Array.isArray(contract?.acceptance) ? contract.acceptance : [];
+  acceptance.forEach((item, index) => {
+    const id = item?.contract_item_id;
+    // ID 缺失或非字符串是形状问题，交给形状校验报，这里不重复报一遍。
+    if (typeof id !== 'string' || !id || reviewed.has(id)) return;
+    errors.push(`acceptance[${index}].contract_item_id = ${quote(id)}：未被任何 l1_review 条目引用`);
+  });
+  return { errors, warnings: [] };
+}
+
+/**
+ * doctor 口径：把手上能执行的全部判据整体降级成 warning。
+ * doctor 是只读回看路径，会读到本判据出现之前冻结的状态；在这里判 unhealthy，
+ * 等于让同一份 Evidence 的审计结论随 runtime 版本变化。profile 传 null 时只出契约层判据。
+ * @param {any} contract @param {any} [profile]
+ * @returns {string[]}
+ */
+export function substanceWarnings(contract, profile = null) {
+  const report = contractSubstance(contract);
+  const findings = [...report.errors];
+  if (profile) findings.push(...profileSubstance(profile).errors, ...coverageSubstance(contract, profile).errors);
+  return [...findings, ...report.warnings];
+}
+
+/** @param {string[]} errors */
+export function formatSubstanceErrors(errors) {
+  return `实质性检查失败（${errors.length} 项）:\n- ${errors.join('\n- ')}`;
+}