@cr1992/agentkit 1.0.0

package/docs/orchestrate/orchestration-runtime.md

@@ -0,0 +1,261 @@
+# 编排运行时 v1
+
+本运行时用于 `orchestration_mode: full`。`SKILL.md` 定义的 `≤3` 个独立只读 worker 轻量档使用仓库外
+JSON 快照，不初始化本 ledger。两种档位都先声明节点所需有效能力：requirements 非空时通过
+`worker-capability-preflight.mjs` 校验；为空时不调用脚本，只记录 `not_required` 与合同已提供全部输入等
+依据。任一轻量资格失效时，将节点、宿主派发回执和已有产物收养到本 ledger 后继续。
+
+`contract-tool.mjs` 是 Task Contract 的机械入口：
+
+```text
+normalize --input <json>
+validate --input <json>
+digest --input <json>
+review-view --input <json>
+diff --left <json> --right <json>
+project --input <json> --items <id,id> [--contract-id <id>]
+capabilities
+```
+
+`orchestration-ledger.mjs` 只记录控制面的已发生事实，不直接派发 Agent：
+
+```text
+init --contract <json> [--state-root <dir>] [--ledger-id <id>]
+add-node / add-edge / dispatch-record / update / attach
+batch-init / batch-record / batch-status / batch-fuse
+record-reflection / propose-improvement
+status / inspect / rebuild / doctor / capabilities
+```
+
+`init` 回显 `ledger_id / ledger_dir / ledger / state_root / revision`。后续所有命令的 `--ledger`
+传 `ledger` 字段的值，也就是 `<state-root>/ledgers/<ledger-id>`，**不是 `--state-root` 本身**；
+把 state root 当 `--ledger` 传时，ledger 直接给出应传的绝对路径（多个 ledger 时列出候选）。
+
+五个脚本（`contract-tool` / `orchestration-ledger` / `worker-capability-preflight` /
+`review-budget` / `orchestration-reflection`）在 `--help`、`-h`、`help` 或无参数时打印自己的命令与
+参数清单并退出 0；清单由脚本内的 `CLI_SPEC` 表机械渲染，不另写一份。未知命令与非法输入仍保持
+各脚本原有的错误形状与非零退出。
+
+`capabilities` 同时输出独立的 `protocol_version`、`runtime_version` 和 Skill tree `content_digest`。
+当前协议版本为 `1.1.0`，ledger runtime 为 `1.7.0`；三者分别表达兼容语义、脚本实现和精确安装内容，
+不能互相替代。
+
+## Reviewer 预算门禁
+
+Reviewer 不是 worker 的 1:1 配套。合同需要 reviewer 时，在 freeze 前写入
+`extensions.review_policy`，派发前执行：
+
+```text
+review-budget.mjs evaluate --policy <json> --history <json> --request <json>
+```
+
+默认每个 Artifact 最多一次 primary review；仅当 primary 为 `undecidable`、证据冲突或协议歧义时，
+允许一个不同 lens 的 escalation review。smoke 未通过、同 lens 重复、输入预算超限或已有 safety stop
+均拒绝派发。runtime 只做纯门禁，不直接创建 reviewer；详细 envelope 和建议默认值见
+[Reviewer 与 Token 预算](review-budget.md)。
+
+所有修改命令支持 `--expected-revision`。状态默认写在业务仓库外；宿主派发回执必须通过
+`dispatch-record` 绑定精确 worker identity、本地 tier、model、reasoning effort、attempt lineage、
+动态调整动作、选择理由、配置来源 / 确认状态、能力证据、派发 provenance、token budget 和
+`max_attempts`。完整档的
+`capability_fingerprint` 必须是当轮实时复核过的 `sha256:` 摘要；未知字段和缺字段均拒绝。示例：
+
+`resolve_model_policy.mjs` 输出的是 `model-policy-resolution` schema v1；其
+`dispatch_record_patch` 与下列 v2 dispatch 的同名字段可直接合并。Controller 仍须补齐
+`schema_version / worker_id / orchestration_mode / capability_source / capability_fingerprint /
+token_budget`。两种记录各自版本化，不能把 resolver 顶层 envelope 当作 dispatch 写入 ledger。
+
+```json
+{
+  "schema_version": 2,
+  "worker_id": "opaque-worker-id",
+  "orchestration_mode": "full",
+  "attempt_id": "opaque-attempt-id",
+  "attempt": 1,
+  "previous_attempt_id": null,
+  "tier": "primary",
+  "model": "provider-primary-current",
+  "reasoning_effort": "medium",
+  "adjustment_action": "initial",
+  "failure_kind": null,
+  "failure_ref": null,
+  "selection_reason": "规范明确且测试可低成本发现偏差",
+  "config_source": ["user-host:<path>/hosts/<host>.json"],
+  "configuration_state": "persisted-config",
+  "model_resolution_state": "discovered-and-validated",
+  "capability_source": "cache:<path>+live-validation",
+  "capability_fingerprint": "sha256:...",
+  "dispatch_provenance": "explicit",
+  "token_budget": "unsupported",
+  "max_attempts": 3
+}
+```
+
+示例模型名不是推荐值。`configuration_state` 只接受 `user-explicit / session-inferred /
+session-confirmed / persisted-config / host-default`；它说明偏好如何形成，不替代宿主调用参数或回执。
+`doctor` 会重新校验持久化 dispatch。
+
+`model_resolution_state` 只接受 `discovered-and-validated / user-explicit-unverifiable /
+host-default-unexposed`。第二种必须同时是 `configuration_state: user-explicit`；第三种必须使用
+`model: host-default`、`configuration_state: host-default` 和 `dispatch_provenance: host-default`。
+
+验收失败后的重派必须创建新节点；前序节点先附 `report` 或 `evidence` 并进入 `failed`。新 dispatch
+使用连续 `attempt`，通过 `previous_attempt_id` 指向前序 dispatch，并用 `failure_ref` 指向前序节点的
+稳定失败附件摘要。ledger 拒绝重复 attempt ID、不连续 lineage、未失败前序或错绑证据。环境、合同、
+安全和不可判定失败不属于可重路由类型，不能写进重派 dispatch。
+
+## Worker 有效能力预检
+
+`worker-capability-preflight.mjs` 不派发探针，只校验 controller 提供的 Requirements 与 Effective
+Capability：
+
+```text
+capabilities
+normalize --input <effective.json>
+check --requirements <requirements.json> [--effective <effective.json>]
+```
+
+Requirements 的 `required` 只接受 `worker.` 前缀的能力键（例如 `worker.read.cwd`、
+`worker.execute_commands`）；`host.*`、`shell.*` 等其他前缀一律拒绝，报错会同时给出前缀与示例键。
+同一约定写在 [Worker Capability Requirements v1](../../schemas/worker-capability-requirements-v1.schema.json)
+的 `required.description` 里。
+
+没有 required capability 时无需运行 `check`，允许缺省 effective 文件；controller 在快照或 ledger
+派发记录旁写明 `not_required` 与判据。有要求但缺记录时返回 `scoped_probe_or_replan`。binding / 指纹
+不匹配或过期返回 `refresh_effective_profile`；相同 requirements 与 binding 的当轮有效 `allowed` 结果
+可以复用。同机、本地进程或历史上总是通过都不能替代这些绑定；策略拒绝、审批通道故障和执行故障
+分别返回 `replan_or_controller`、`stop_same_class_and_escalate`、`stop_same_class_and_diagnose`。具体
+结构见对应两个 v1 schema。
+
+## 轻量 Reflection
+
+轻量档通过独立入口记录改进输入，不初始化 ledger：
+
+```text
+agentkit orchestrate reflection record --state-root <session-state> --input <reflection-input.json>
+agentkit orchestrate reflection propose --state-root <session-state> --reflection <relative-ref> --input <proposal-input.json>
+```
+
+`record` 的 `evidence_refs[].id` 必须是 state root 内相对路径，并逐项校验文件摘要；没有证据只能记录
+`confidence: low`。`propose` 重验 Reflection 与证据，只生成 `lifecycle: proposed`。完整档仍由 ledger
+登记同一 v1 Reflection / Proposal，二者不需要共享 journal。
+
+每个 `add-node` 输入必须显式包含：
+
+```json
+{
+  "verification": {
+    "requirement": "worker_self_check | controller_recheck | independent_evidence | not_applicable",
+    "provider": "none | verify-agent-output",
+    "artifact_scope": "node_output | integration_candidate | not_applicable"
+  }
+}
+```
+
+`not_applicable` 只给**没有实现交付物的只读评审节点**：`role` 必须是 `critic` 或 `scout`，且
+`provider: none`、`artifact_scope: not_applicable`；`worker` / `judge`（含缺省 role）传
+`not_applicable` 一律拒绝。这类节点不受“实现节点必须有稳定交付物”的门禁约束，也不需要
+`verification_ref`，但进入 `passed` 前必须先 `attach --type report` 附一份稳定 report 作为可复核输出。
+`not_applicable` 不影响其他三档的语义、既有 ledger 与计数，也不改变 `protocol_version`。
+
+`worker_self_check` 有任一稳定输出即可通过，只能报告该最低保证。`controller_recheck` 先附稳定输出，
+再附以下 report；它必须完整覆盖当时除其他 Controller Recheck Record 外的稳定输出摘要。机器结构见
+[Controller Recheck Record v1](../../schemas/controller-recheck-record-v1.schema.json)：
+
+```json
+{
+  "schema_version": 1,
+  "report_type": "controller_recheck",
+  "contract_digest": "sha256:...",
+  "stable_output_digests": ["sha256:..."],
+  "outcome": "pass",
+  "checked_at": "RFC3339"
+}
+```
+
+`independent_evidence` 要求公共合同预先冻结 `verify-agent-output` provider 与 Skill 摘要，只接受一个
+标准 Artifact Ref，以及结构、摘要、合同和 Artifact 绑定都有效的 Evidence Package。进入 `passed`
+时，后两档的 `update` 输入必须用 `verification_ref` 指向被采信的 report / Evidence attachment digest；
+Evidence 必须为 `terminal_outcome: pass` 且不再要求 human gate。节点终态后不再接受 attachment。
+`status.summary.verification_assurance` 分别计数四档（含 `not_applicable`）和 `none`，
+`doctor` 重新执行同一门禁。
+
+**Token 消耗与成本核算（v1.2）**：`update` 支持记录节点消耗的 `tokens`（非负安全整数，或字段完整的 `{ input_tokens, output_tokens, total_tokens }`，其中 `total_tokens = input_tokens + output_tokens`）及非负安全整数 `duration_ms`。`status` 命令在 `summary.token_accounting` 中自动汇总总 Token 与按角色分级的消耗分布，支持计算多 Agent 分发相比全量顶配模型的 Token 节省率；`doctor` 使用同一校验器复核持久化节点。
+
+**合同投影（v1.2）**：Evidence 的合同绑定有两条合法路径，缺省仍是全等——verify-agent-output
+那次验证直接使用本 ledger 的公共合同（同一份 JSON、同一个摘要）。多节点图下若多个节点各自
+独立验收，公共合同的 acceptance 条目往往覆盖全图，reviewer 会拿其他节点的条目审出假 fail；
+此时改用**投影合同**：从公共合同切出该节点产物专属的条目子集，作为该节点的验证合同。
+
+投影合同由 `contract-tool.mjs project` 生成，不得手写：
+
+```bash
+agentkit contract project --input <公共合同.json> --items <item-id1,item-id2> \
+  [--contract-id <显式 id>] > node-contract.json
+```
+
+投影只允许改动**四项**：`contract_id`、`acceptance`（收窄为父合同条目的子集）、
+`extensions.projection`（血缘）、`contract_digest`（重签）。其余顶层字段——`objective / scope /
+permissions / environment / skill_set / stop_conditions`，以及父合同自带的任何扩展顶层字段——
+逐字节原样继承；`extensions` 去掉 `projection` 键后也必须与父合同完全一致。选中的 acceptance
+条目**逐字节 verbatim** 拷贝，不得改写措辞。血缘写在：
+
+```json
+{
+  "extensions": {
+    "projection": {
+      "parent_contract_digest": "sha256:...",
+      "projected_item_ids": ["item-id1", "item-id2"]
+    }
+  }
+}
+```
+
+`contract_id` 缺省为 `<父 contract_id>--proj-<8 位随机>`，`contract_digest` 按 RFC 8785 重算。
+未知条目 id、空 `--items`、重复 id、父合同缺摘要或摘要不自洽一律报错。
+
+ledger 侧用 `attach --type contract` 登记：只有 `independent_evidence` 节点可附，每节点至多一份，
+终态节点不再接受，且必须在附 Evidence 之前登记。attach 时机械校验血缘与条目子集；随后
+`validateEvidencePackage` 接受 `evidence.contract_digest` 等于公共合同摘要**或**该节点这份投影合同
+的摘要。`update --state passed` 与 `doctor` 对 `passed` 节点复跑同一门禁，attachments 目录被改写
+会在 doctor 现形。没有 contract attachment 的节点行为与 v1.1 完全一致。
+
+**反张冠李戴保证如何保持**：换一个任务的合同来交差，被 `parent_contract_digest !== ledger 公共合同
+摘要` 拦下；把条目措辞改宽松，条目的 canonical JSON 摘要不再命中公共合同的条目摘要集合，被拦下；
+夹带公共合同里没有的自造条目，同样被条目子集校验拦下；`acceptance` 的 id 集合必须与
+`projected_item_ids` 完全一致，防止声明与实际条目不符；改写 `objective / scope / permissions /
+environment / skill_set / stop_conditions` 或其他 `extensions` 键，被逐字段全等校验拦下并指名是哪个
+字段——放宽 `permissions` 或掉包 `scope` 骗过 reviewer 这条路是堵死的。子集校验取的父条目集合来自
+ledger 目录里的 `contract.json`，使用前先要求 `envelopeDigest(contract.json) === snapshot.contract_digest`，
+否则换掉那份文件就能给私货投影背书。因此投影只能**收窄**验收面，不能改写或扩张它——仍然不要通过
+复制改写公共合同来伪造"等值"，那会破坏合同摘要的审计意义。
+
+`add-node` 必须显式给出 `verification`，没有缺省档。Ledger v1 schema 可以读取任何旧快照，但
+Skill content digest 已变化的旧 ledger 只允许审计，继续写入前必须 re-contract，不做原地补字段或
+静默升级。
+
+批级熔断属于此 ledger；每个 Loop 仍只维护自己的单个收敛对象。
+
+Reflection 与 Improvement Proposal 是追加式改进输入；轻量档也有 ledger-independent 的同 schema
+入口。Proposal 的生命周期固定为 `proposed`，
+当前执行面不读取它，也不会据此改写合同、节点状态或验收结论。
+
+## 台账信任边界
+
+state root 只由 controller/operator 与 runtime 写。journal digest chain 可发现损坏并恢复，但不是
+数字签名或外部不可变日志；拥有完整写权限的进程仍能重写历史，不得描述成抗恶意 writer 的保证。
+
+## 编排原语选择
+
+- 高风险 finding 用不同 lens 的证伪 critic；解空间宽才使用 judge 面板。
+- 未知规模使用 loop-until-dry，对累计已见集合去重，必要时末尾加 completeness critic。
+- 多 stage 默认逐条 pipeline；barrier 只在跨条去重、聚合、比较或早退时设置——它把并发压成同步点，
+  没有跨条依赖时只会拖慢整批。
+
+## 派发台账的三张表
+
+- **活跃 Agent**：任务、精确执行配置、仓库 / 隔离、写范围、三态 `运行中 / 阻塞 / 待验收`
+  与可观察检查点。
+- **本批已完成**：结果、稳定产物、证据、环境收尾。
+- **工作进展**（存在并行时）：必须包含 controller 自己的集成、提交、发布与回收工作，
+  否则汇报里只剩 worker 的活，controller 的关键路径不可见。

package/docs/orchestrate/review-budget.md

@@ -0,0 +1,90 @@
+# Reviewer 数量与 Token 预算
+
+只在 controller 考虑派独立 reviewer、critic 或 judge 时读取。本规则限制昂贵 L1 取证，不降低
+`verify-agent-output` 对单次冻结 Artifact 的完整性要求。
+
+## 默认策略
+
+普通 worker self-check 与 controller recheck 不计入独立 reviewer 配额。对同一 Artifact：
+
+- smoke/preflight 未通过时不派 reviewer；
+- 默认最多 1 次 primary independent review；
+- 默认最多 1 次 escalation review，且必须使用不同 lens；
+- escalation 只能由 `undecidable`、可复现证据冲突或协议歧义触发；
+- `blocked_safety` 直接停止并升级给人，不用更多 reviewer 抵消；
+- 每次请求必须说明会改变哪个决策，并估算 reviewer 输入 tokens；超预算先投影合同或缩小 scope；
+- 同 Artifact、同 lens 的重复 review 复用已有 Evidence，不重新派发。
+
+高风险不等于 reviewer 越多越好。第二 reviewer 只有在独立证据可能改变处置时才有价值；多个普通
+worker 也不做 1:1 reviewer 配对，优先验证最终集成候选。
+
+## 冻结策略
+
+公共 Task Contract 可在 `extensions.review_policy` 冻结：
+
+```json
+{
+  "schema_version": 1,
+  "max_primary_reviews_per_artifact": 1,
+  "max_escalation_reviews_per_artifact": 1,
+  "require_distinct_lens": true,
+  "review_only_after_smoke_pass": true,
+  "max_review_input_tokens": 12000
+}
+```
+
+这些上限是当前任务的成本与停止条件。提高数量或 token 上限属于 re-contract，需要 controller 明确
+说明新增 reviewer 会改变的决策；reviewer/worker 不能自行提高。
+
+## 派发前机械门禁
+
+`--history` 是一个 JSON **数组**，不是带 `reviews` 字段的对象。还没有任何 review 时传空数组：
+
+```json
+[]
+```
+
+已有一次完成的 review 时，每项只需要门禁用到的五个字段：
+
+```json
+[
+  {
+    "review_id": "review-1",
+    "artifact_digest": "sha256:...",
+    "lens": "protocol_semantics",
+    "kind": "primary",
+    "outcome": "undecidable"
+  }
+]
+```
+
+`kind` 取 `primary | escalation`，`outcome` 取 `pass | fail | undecidable | blocked_safety`；
+`review_id` 在同一份历史内唯一。把这份历史与新请求写成 JSON，然后执行：
+
+```text
+agentkit orchestrate review-budget evaluate \
+  --policy <review-policy.json> \
+  --history <review-history.json> \
+  --request <review-request.json>
+```
+
+请求字段：
+
+```json
+{
+  "schema_version": 1,
+  "artifact_digest": "sha256:...",
+  "lens": "protocol_semantics",
+  "kind": "primary",
+  "decision_impact": "该 finding 会决定是否接受 direct response lifecycle",
+  "smoke_passed": true,
+  "estimated_input_tokens": 6000,
+  "escalation_trigger": null
+}
+```
+
+`allowed: false` 时按 `next_action` 缩小输入、复用现有 review、先跑 smoke，或停止并升级；不得绕过
+门禁直接派发。runtime 只做纯函数判断，不派 Agent、不读取源码、不修改 ledger。
+
+`estimated_input_tokens` 使用宿主实际计数；宿主不暴露时以即将投递的 UTF-8 字符数作为保守代理并在
+台账注明 `estimated`。运行后把实际 token 使用写回节点 `tokens`，用于 `status.summary.token_accounting`。

package/docs/orchestrate/task-playbooks.md

@@ -0,0 +1,85 @@
+# 任务类型剧本与模型分级（Task-Type Playbooks & Tier Dispatch）
+
+本剧本沉淀了典型多 Agent 协同任务的阶段化模型分级（Tier Dispatch）、角色分配与验收策略。在规划复杂任务图时，Controller 可直接参考本剧本进行节点拆解与模型配置。
+
+---
+
+## 1. 四维难度评估准则（Four-axis Difficulty Rubric）
+
+在为任务图中的各个节点选择本地 tier 时，依据以下四个维度综合评估。`low / mid / top` 只表示
+相对决策杠杆，不是配置中必须出现的名称：
+
+| 维度 | 较低 tier 判定依据 | 较高 tier 判定依据 |
+|---|---|---|
+| **推理深度（Reasoning depth）** | 机械式检索、格式转换、明确规则的脚本执行、模板搬运 | 架构权衡、多步因果推导、隐蔽缺陷发现、系统级设计 |
+| **需求模糊度（Spec ambiguity）** | 接口/规范/格式完全固定，输入与输出契约无二义性 | 探索性需求、开放式目标、边界未明、需要主观判断 |
+| **爆炸半径（Blast radius）** | 局部叶子节点、单文件只读分析、隔离的单元测试 | 核心公共 API、共享协议、安全边界、不可逆的写操作 |
+| **上下文集成度（Context integration）** | 只需关注当前文件或单一输入，无跨模块依赖 | 需要同时综合跨模块历史、系统全局状态与外部规范 |
+
+### 核心分发自问（The Tie-Breaker Question）
+> **“如果这个节点产物返回了错误结果，Controller 能否以极低成本（如跑一次已有测试、格式校验或简单 Diff）迅速察觉？”**
+> - **能轻易察觉** $\rightarrow$ 选择本地较低 tier，并使用 `worker_self_check`。
+> - **难以察觉且后果严重**（如看似合理实则隐蔽的逻辑 bug、失真的 API 契约） $\rightarrow$ 选择本地较高 tier，并使用 `controller_recheck` 或 `independent_evidence`。
+
+---
+
+## 2. 本地 tier 与 effort
+
+模型、effort 默认值和允许范围由用户级 host 配置决定。Controller 可以让较便宜模型运行较高 effort，
+也可以让 frontier 模型在边界清楚时使用中等 effort；不要用全局预算模式覆盖所有节点。需要降低成本时，
+直接选择仍可可靠完成该节点的较低本地 tier，并收紧节点自己的尝试数或 scope。
+
+---
+
+## 3. 四大核心场景剧本
+
+### 剧本 1：代码批量重构与迁移（Bulk Migration / Refactoring）
+**适用场景**：将大批端点/组件从老架构迁移到新规范（如从回调转 async/await、从旧 ORM 迁移到新 client）。
+
+```mermaid
+graph LR
+    S1[S1: 规范定义<br/>Top / Controller] --> S2[S2: 批量并发重构<br/>Mid or Low / Worker]
+    S2 --> S3[S3: 单元测试回归<br/>Low / Worker]
+    S3 --> S4[S4: 对抗性 Diff 审查<br/>Top / Critic]
+```
+
+- **S1（规范契约定义）**：`role: judge / controller`, `tier: top`。先撰写 1 页纸的标准迁移范式与防踩坑指南，冻结为任务公共契约（Gating Everything）。
+- **S2（批量并发实现）**：`role: worker`, `tier: mid`（若为纯语法规则替换且有测试守护则 `tier: low`）。分批次并行下发，受 Worktree 隔离守护。
+- **S3（自动化测试验证）**：`role: worker`, `tier: low`。执行 `npm test` 或测试套件，回传测试证据。
+- **S4（对抗性 Diff 审查）**：`role: critic`, `tier: top`。重点审查是否有遗漏的异常分支处理、未清理的资源或微妙的时序问题。
+- **成本收益典型特征**：~80% 的 Agent 执行时间消耗在 low/mid 档位。
+
+---
+
+### 剧本 2：安全与代码审计（Repository Bug / Security Audit）
+**适用场景**：全仓缺陷排查、依赖漏洞检测或代码质量审计。
+
+- **S1（模块化并行扫描）**：`role: scout`, `tier: low`。按目录/模块拆分并发扫描，要求给出精确的文件行号、可疑片段与触发条件。
+- **S2（逐项处方与事实核验）**：`role: critic`, `tier: mid/top`。针对 S1 报告的疑点，对照源码与历史提交进行真实性核验，剔除误报（False Positives）。
+- **S3（系统性综合报告）**：`role: controller`, `tier: top`。Controller 亲自综合全景影响，输出带可复核证据链的最终修复清单。
+
+---
+
+### 3. 剧本 3：多源技术与竞品调研（Multi-Source Research）
+**适用场景**：对比评估多个技术方案、开源库或竞品特性。
+
+- **S1（单源结构化提取）**：`role: scout`, `tier: low`。每个调研对象指派一个独立 worker，使用统一的 JSON/Markdown 模板结构化提取事实。
+- **S2（冲突裁决与对齐）**：`role: critic / worker`, `tier: mid`。对各源之间相互矛盾的性能参数、授权许可或兼容性声明进行交叉核验。
+- **S3（综合结论与选型决策）**：`role: judge / controller`, `tier: top`。在 Controller 主会话中整合对比矩阵并给出最终选型建议。
+
+---
+
+### 4. 剧本 4：API 文档与契约编写（Documentation & API Specs）
+**适用场景**：为大型模块、SDK 或通用协议补充架构设计与 API 文档。
+
+- **S1（文档结构与规范对齐）**：`role: controller`, `tier: top`。先确定文档目录结构、章节脉络、受众与语调。
+- **S2（各章节并发初稿）**：`role: worker`, `tier: mid`。按照代码与现有注释并行起草各章节内容。
+- **S3（术语与死链扫描）**：`role: scout`, `tier: low`。执行脚本或简单模型通读，检查代码块格式、死链接与术语统一性。
+- **S4（代码一致性核验）**：`role: critic`, `tier: top`。核对文档中的 API 示例代码与实际实现是否 100% 一致（防止“看似流畅但参数过时”的假文档）。
+
+## 规模推导细则
+
+- 扫描数等于真正独立、单个上下文装不下的工作块数；两个 scope 重叠过半就合并。
+- 核验数从风险推导，只核「错误会改变最终决策」的条目，不与扫描任务 1:1 配对。核验大多只是确认
+  并补细节、很少推翻，说明核多了。
+- 快速看一眼用 2-3 个；常规盘点 / 审计一轮扫描任务合并后通常 `4-6` 个；几十个只用于大规模同构 pipeline。

package/docs/orchestrate/user-facing-reporting.md

@@ -0,0 +1,14 @@
+# 面向用户的汇报词表
+
+台账术语只留在仓库外状态文件里。对外汇报换成下面的说法，术语首次出现就当场解释。
+
+| 台账术语 | 对外说法 |
+| --- | --- |
+| critic | 独立挑错评审 |
+| scout | 前期摸底 |
+| worker | 实现者 |
+| controller recheck | 我方复核 |
+| independent evidence | 独立验收证据 |
+| 产物冻结 | 固定到某个提交 SHA |
+| awaiting_verification | 待验收 |
+| partial | 做了一半 |

package/docs/verify/evidence-schema.md

@@ -0,0 +1,167 @@
+# Verification v1 envelope 与证据约束
+
+## 目录
+
+1. 公共摘要规则
+2. Task Contract
+3. Verification Profile
+4. Artifact Ref
+5. Reviewer Input / Review Result
+6. Evidence Package
+7. Git 与路径约束
+8. 派发与前置检查（prepare / readiness / review-bundle）
+
+## 1. 公共摘要规则
+
+所有机器输入必须是 JSON。解析时拒绝重复 key、非法 Unicode surrogate 与非有限 number；摘要使用
+RFC 8785 canonical JSON 的 UTF-8 字节并以 `sha256:<hex>` 表示。每个 envelope 的 digest 对移除
+自身 digest 字段后的完整对象计算。
+
+## 2. Task Contract
+
+必需字段：`schema_version: 1`、`contract_id`、非空 `objective`、`scope.include/exclude`、非空
+`acceptance`、`permissions`、`environment`、`skill_set`、`stop_conditions`、`extensions` 和
+`contract_digest`。每个 acceptance item 包含唯一非空 `contract_item_id` 与 `requirement`。
+
+`skill_set` 必须记录实际参与本轮决策的 Skill 名称、版本、`content_digest` 和 provider mode。
+`provider_mode` 只接受 `primary | optional`，由 `preflight/init` 按 schema 严格校验，其他值一律拒绝。
+
+## 3. Verification Profile
+
+必需字段：`schema_version: 1`、`profile_id`、`l0_checks`、`l1_review`、protected/allowed path、
+`runtime`、`human_gate` 与 `verification_profile_digest`。
+
+每个 L0 check：
+
+```json
+{
+  "check_id": "unit",
+  "argv": ["node", "--test"],
+  "cwd_rel": ".",
+  "stage": "smoke | final | both",
+  "timeout_ms": 120000,
+  "expected_exit_codes": [0]
+}
+```
+
+`argv[0]` 必须在 `runtime.executable_paths` 映射到绝对可执行文件；runtime 不调用 shell。
+`runtime.env_allowlist` 只列变量名；`network_policy` 是 `denied` 或 `contract_authorized`；
+`cache_policy` 是 `disabled | isolated | trusted_identity`；`max_log_bytes` 必须为正整数。
+
+`l1_review` 是非空数组，每项形状为：
+
+```json
+{
+  "contract_item_id": "acceptance-item-id",
+  "lenses": ["functional", "scope", "verification_definition", "safety"]
+}
+```
+
+`contract_item_id` 必须引用 Task Contract；`lenses` 只能使用上述四值。`human_gate` 只能是
+`none | release | destructive | external_side_effect`。`network_policy: denied` 时，`preflight/init`
+还要求宿主显式传入 `--network-isolated`，该旗标是宿主 assurance，不由 runtime 自行推断。
+
+## 4. Artifact Ref
+
+必需字段：`schema_version: 1`、`provider`、`repository_id`、`object_format`、完整 `base_sha` 和
+`artifact_sha`。branch 只可作为 `branch_hint`，不得用于身份绑定。
+
+v1 runtime 通过 Artifact 可达的 root commit 集合计算 repository identity：
+
+```text
+git:<object_format>:sha256(<排序后的 root commit JSON>)
+```
+
+调用方使用其他稳定 identity 时可保留自己的 opaque 值，但 runtime 会同时冻结并校验
+`runtime_repository_identity`，避免当前 run 内换仓。
+
+## 5. Reviewer Input / Review Result
+
+`review-input` 顶层提供 `contract_digest`、`verification_profile_digest`、`artifact_ref` 和
+`challenge_nonce`。Review Result v1 必须原样复制这四个绑定；controller 不得在 reviewer 输出后补写
+或修改元数据。完整 Review Result 形状见 [schemas/review-result-v1.schema.json](../../schemas/review-result-v1.schema.json)。
+
+## 6. Evidence Package
+
+Evidence 包含 `run_id`、protocol/runtime version、Contract/Profile 摘要、Artifact、三阶段结果、
+`terminal_outcome`、`completion_scope: verification_only`、human gate 标记、provider 与 reviewer
+provenance、runtime 生成的 RFC3339 时间和 `evidence_digest`。
+
+`init` 必须在 reviewer 执行前冻结计划使用的 `host_reported | user_relayed` isolation assurance；
+若 smoke 失败导致 L1 未运行，Evidence 保留该计划 assurance，并在 limitations 标记 `l1_not_run`。
+
+terminal outcome 仅为：`pass | fail | undecidable | blocked_safety`。operational abort 不生成
+Evidence。日志先脱敏，再按内容摘要持久化；Evidence 只引用日志摘要和相对 ref。
+
+版本化 JSON Schema 位于 [schemas/](../../schemas/)；runtime 仍执行跨字段、Git 和 digest 机械校验，不能只靠
+结构 schema 宣称验证成立。
+
+## 7. Git 与路径约束
+
+- base/artifact 必须是完整 commit object，base 是 artifact ancestor；
+- 每个 gate 前后要求 clean workdir 且 `HEAD == artifact_sha`；
+- protected path 只接受精确相对路径或以 `/` 结尾的目录前缀；
+- 拒绝 wildcard、path magic、绝对路径、反斜杠、空段与 parent traversal；
+- 未被 `allowed_validation_changes` 覆盖的 protected path 变化在 L1 前失败。
+
+## 8. 派发与前置检查
+
+这三个命令只服务于「把输入准备好、把验收派出去」，都不产生 verdict，也不写 Evidence。
+
+### 8.1 `prepare --workdir <dir> [--out-dir <dir>]`
+
+薄串联：`scaffold --kind contract` + `scaffold --kind profile` + TODO 清单 + 后续命令清单。
+带 `--out-dir` 时写出 `contract.json` 与 `profile.json`（已存在即拒绝覆盖），否则把两个骨架内联
+返回。**它不猜测任何测试命令，也不内置任何项目专属 preset**；输出的 `notice` 固定声明
+「Verification Profile 的 `l0_checks` 需 controller 按项目实际填写并确认」。`prepare` 不代跑
+`readiness` 与 `preflight`，只在 `next_steps` 给出命令行。
+
+### 8.2 `readiness --contract <json> --profile <json> --workdir <dir> [--state-root <dir>]`
+
+只机械检查环境前提。`contract_readable` / `profile_readable` 是**门槛项**：输入不可读或解析失败时
+只以 blocker 形式出现（`blockers[]`），不进入 `checks[]`。其余检查项在其所需输入可用时照常执行并
+逐项产出 `{check_id, ok, detail}` 进入 `checks[]`（`workdir_git_root` / `state_root_writable` 无输入
+依赖；`executable:*` / `l0_cwd:*` / `argv_file:*` 三类仅依赖 Profile，与合同无关）：
+
+| check_id | 判据 |
+| --- | --- |
+| `contract_readable` / `profile_readable` | 门槛项：输入可读且能严格解析；失败只出现在 `blockers[]` |
+| `workdir_git_root` | workdir 存在、是目录，且是 Git worktree 根目录 |
+| `state_root_writable` | state root（或其最近的已存在祖先）是目录且可写 |
+| `executable:<name>` | `runtime.executable_paths` 的每个绝对路径存在、是文件、可执行 |
+| `l0_cwd:<check_id>` | `resolve(workdir, cwd_rel)` 存在、是目录、不越出 workdir |
+| `argv_file:<check_id>:<index>` | argv 中**在 workdir 下 resolve 后确实存在**的文件参数可读 |
+
+argv 参数沿用 L0 冻结逻辑的同一口径：不猜测哪些参数是文件，只对已经存在的路径做可读性检查。
+`runtime.env_allowlist` 中的变量是否为 L0 必需无法机械判定，因此只写进 `notes`，既不猜也不拦。
+
+输出为 `{ready: true, ...}` 或 `{ready: false, blockers: [{kind: 'precondition', check_id, detail}], ...}`，
+并固定带 `blocker_semantics: 'blocked_precondition_not_artifact_defect'`。CLI 在 not ready 时以退出码
+2 表达，与 `preflight` 同口径。
+
+**readiness 失败 ≠ 产物缺陷。** 它只表示环境前提未就绪，归类为 blocked/precondition，不构成
+Artifact `fail`，也不进入任何 terminal outcome。
+
+`run-smoke` 会先内联跑一次同样的检查，未通过时拒绝执行 L0 并记录 `stale_precondition` operational
+abort——这正是本命令存在的理由：环境问题不该以「L0 跑挂」的形式与产物缺陷混在一起。内联版本
+排除 `executable:*` 与 `argv_file:*`，这两类在 run 内已被冻结身份门禁接管，漂移仍判
+`check_runtime_failure`，避免同一现象出现两种 abort 语义。
+
+### 8.3 `review-bundle --run <run-dir> [--out <path>]`
+
+要求 run 已 `smoke_passed`。输出一份自包含 JSON（stdout 或 `--out` 落盘），字段：
+
+| 字段 | 内容 |
+| --- | --- |
+| `reviewer_prompt` | 标准 reviewer 提示词：证伪任务原文（取自 `verification-protocol.md` 的「证伪任务」段）+ 三态 verdict、finding 五字段、forensics、safety 不可抵消、绑定原样复制等输出契约 |
+| `review_input` | `review-input` 全量，含两个 digest、`challenge_nonce` 与 `reviewer_view` |
+| `review_result_schema` | 内联的 `schemas/review-result-v1.schema.json` |
+| `artifact_ref` / `workdir` | 冻结 Artifact 与 workdir 绝对路径 |
+| `permissions` | `read_only`，显式列出禁止的 commit / checkout 等操作 |
+| `stop_conditions` | 三态 verdict 产出后立即停止 |
+| `digest_backfill` | `digest --kind review` 命令行与「不要手写 digest」说明 |
+| `contract_kind` | `public \| projected` |
+
+`contract_kind` 的判据是 `contract.extensions.projection` 是否存在。投影场景下 bundle 的合同部分
+就是投影合同本身（`review-input` 本就如此），runtime 不做二次裁剪；该字段只是给 reviewer 的提示：
+只对被投影的 acceptance 取证，不越界评判未投影条目。

package/docs/verify/input-preparation.md

@@ -0,0 +1,44 @@
+# 输入准备与诊断命令
+
+仅在尚未准备 Contract/Profile/Artifact、`prepare-run` 失败，或需要调试完整 snapshot 时读取。三个输入
+已经冻结且 happy path 正常时不加载。
+
+## 骨架与摘要
+
+`prepare` 生成 Contract/Profile 骨架、逐项 TODO 和后续命令，不猜测试命令、不内置项目 preset。
+`l0_checks` 必须由 controller 按项目实际填写。`scaffold` 支持 `contract | profile | artifact | review |
+bundle`；骨架结构和摘要合法，但 TODO acceptance 与示例 L0 必须替换。
+
+`artifact/bundle` 要求 `--workdir` 与 `--base-sha`，默认冻结当前 HEAD。`review` 从 `review-input` 原样
+取得 Contract/Profile digest、Artifact 与 challenge nonce。`digest` 支持 `contract | profile | review`，
+输出重算摘要的新 JSON，不覆盖源文件。
+
+```text
+agentkit verify prepare \
+  --workdir <clean-pinned-workdir> --out-dir <inputs-dir>
+agentkit verify scaffold \
+  --kind bundle --workdir <clean-pinned-workdir> --base-sha <full-base-sha>
+```
+
+## Readiness 与 Preflight
+
+`readiness` 只检查环境前提：Git worktree 根、可执行文件、已存在的 argv 文件、L0 `cwd_rel` 和可写
+state root。失败返回 precondition blockers，不是 Artifact defect，不进入 verdict。runtime 无法判断
+`env_allowlist` 中变量是否为 L0 必需，只记 note。
+
+`run-smoke` 内联同一检查，排除已由冻结身份门禁接管的 executable 与 argv 文件；漂移时报
+`stale_precondition`。`preflight/init` 一次汇总 envelope、枚举、摘要、Skill binding 与隔离 assurance
+问题；init 通过后再执行 Git、路径和运行环境门禁。
+
+`prepare-run` 在临时副本重算 Contract/Profile digest，依次执行 readiness、preflight 和 init，不覆盖
+源输入；失败不留下半初始化 run。逐层诊断可分别运行 `digest/readiness/preflight/init --help`。
+
+## Reviewer bundle 与输出
+
+`review-bundle` 生成一次派发的自包含 JSON：标准证伪提示、review-input、Review Result v1 schema、
+Artifact、workdir、只读权限、停止条件和摘要回填指引。投影合同标记为 `projected`，reviewer 只核被
+投影 acceptance。controller 直接转交该 JSON，不重写提示。
+
+`init/prepare-run` 返回稳定 `run_dir/run_id`。写状态命令支持 `--expected-revision`。CLI 的
+`run-smoke/record-review/run-final` 默认 compact；取证加 `--verbose`，`inspect` 始终返回完整 snapshot。
+程序化 `main()` 始终返回完整对象。