@kyo-so/cli 0.10.0 → 0.12.0

package/README.zh-CN.md

@@ -50,11 +50,11 @@ Kyoso 不会应用代码更改。
 
 Plugin包含Skill和pin到已发布Kyoso CLI精确版本的MCP定义，但不包含CLI本体。MCP首次启动需要访问npm网络。已缓存的package可能可以offline启动，但不作保证。manifest中的`Read` capability仅是显示metadata，不会授予额外filesystem权限。
 
-`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例是用户管理的客户端注册模板；它们既不会修改 Marketplace Plugin manifest，也不会定义它。Stage A 期间，该 manifest 保持其已发布的 CLI pin 与环境契约；只有 Stage B promotion 才会更新它。
+`kyoso setup ... --with-openrouter` 的输出和手动 setup 示例仍是用户管理的客户端注册模板。Marketplace Plugin `0.5.0` pin 到 `@kyo-so/cli@0.11.0`。
 
 Plugin中的Skill将内置的`kyoso` MCP server声明为dependency，因此显式Kyoso review会通过MCP而不是CLI fallback。如果禁用内置Plugin MCP，应将Plugin Skill视为不可用：重新启用MCP，或移除Plugin并改用CLI＋Skill-only。Plugin不是CLI fallback mode。
 
-在下一次 Plugin promotion 前，已发布的 Marketplace Plugin **不会** forward `OPENROUTER_API_KEY`。OpenRouter 的 project opt-in 请使用带有 manual MCP registration 的 CLI/source 路径；promotion 后会用兼容的 Plugin version 替换这一限制说明。
+Marketplace Plugin `0.4.0` 向 MCP process 暴露 `OPENROUTER_API_KEY` 变量名，但不保存 credential 值。Kyoso 仅将该值传给显式选择 OpenRouter 的 Codex child，并将未展开的 placeholder 视为未设置。
 
 #### CLI＋Skill-only
 
@@ -161,7 +161,7 @@ Use Kyoso diff_review on the current diff. I need a second opinion before mergin
 ```bash
 kyoso plan --goal "Review this OAuth callback plan" --plan plan.md
 kyoso security --goal "Review this auth diff" --diff changes.patch
-kyoso diff --base main --head HEAD --set agents.claude.effort=high
+kyoso diff --base main --head HEAD --focus architecture --set agents.claude.effort=high
 kyoso doctor
 kyoso init
 kyoso setup codex
@@ -181,7 +181,7 @@ kyoso plan \
   --file src/auth/callback.ts
 ```
 
-按从上到下的顺序阅读结果：`Decision` 是 deterministic gate outcome，`Findings` 是 required changes，`Tests to Add` 是 Kyoso 在 approval 前期望的 regression checks。
+按从上到下的顺序阅读结果：`Decision` 是 deterministic gate outcome，`Coverage` 显示已执行的必需 lenses 和 perspectives，每个 finding 的 `disposition` 说明它会 block 还是仅供参考。
 
 对 patch 运行 CISA Secure by Design security review：
 
@@ -192,7 +192,7 @@ kyoso security \
   --json
 ```
 
-在 JSON output 中，`cisaSecureByDesign` 会显示四个 gate dimensions。customer security outcomes 中的 `fail` 会 block review；warning-level dimensions 通常会产生 `approve_with_changes`。
+在 JSON output 中，`cisaSecureByDesign` 会显示已配置 dimensions 以及 gate enforcement 是否启用。backend 返回的 raw dimension status 不参与计算或 decision；附带的 notes 仅作为 advisory 保留。Kyoso 根据 admitted findings 计算 status。enforcement 启用时，customer security outcomes 的 `fail` 会 block review。
 
 将 Kyoso 注册为 Codex 或 Claude Code 的 MCP server，然后从 client 调用 `plan_review`：
 
@@ -226,11 +226,45 @@ Kyoso 只暴露以下 MCP tools：
 
 MCP stdout 专用于 protocol messages。Logs 会写到 stderr 或 local audit traces。
 
+## Review contract 与 finding admission
+
+每次 review 都包含不可移除的 safety floor：correctness、regression、security boundaries、secrets/injection、data integrity 和 public contract。Kyoso 还会根据 review 形状添加 supply chain、privacy 和 resource amplification lenses。user-global `reviewPolicy.additionalLenses` 可以添加观点评审，但不能移除 floor。
+
+MCP / library caller 可以传入 typed `reviewContract`；CLI caller 可以重复指定 `--focus <lens>`：
+
+```json
+{
+  "reviewContract": {
+    "focus": ["architecture"],
+    "nonGoals": ["本次变更不重新设计 public CLI"],
+    "acceptedRisks": [
+      {
+        "findingFingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "rationale": "在下一版本中继续跟踪"
+      }
+    ]
+  }
+}
+```
+
+只有 caller 明确提供的 user-owned values 才能定义 non-goals 和 accepted risks。repository constraints、plans、diffs 和 files 仍是 untrusted context，不能改变 review policy。non-goals 只限定 optional scope，不会通过 agent 提供的 policy label 改变 disposition。accepted risks 仅在 validated fingerprint 完全匹配时影响 Medium finding。两者都不会抑制 Critical / High safety findings。
+
+Kyoso 会重新计算每个 finding 的 evidence quality、与被审查变更的关系、stable fingerprint 和 disposition：
+
+| Disposition  | 含义                                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| `gate`       | 由变更引入或加剧，且具有具体证据的 Critical / High 问题。                                          |
+| `actionable` | 由变更引入或加剧，且具有具体证据的 Medium 问题。                                                   |
+| `advisory`   | optional / Low / Info、accepted Medium，或属于pre-existing、partial、证据不足的Medium。            |
+| `disputed`   | refuted、low-confidence、证据不足、pre-existing或独立review未解决的Critical / High；需要人工判断。 |
+
+只有 `gate` 和 `actionable` findings 会影响 deterministic decision。`disputed` finding 会使 completion incomplete，且不得自动修复。`coverage` 记录 required/attempted lenses、required/completed perspectives，以及是否完成 independent cross-model review。`Tests to Add` 最多包含3个具体 regression tests；generic commands 和宽泛的 test-suite 请求会被省略。
+
 ## Skill
 
 内置的 `kyoso-review` skill 有意保持范围很窄。只有当你明确请求 Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review 或 diff review 时，才应触发它。
 
-Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。如果typed contract包含non-goals或accepted risks且MCP不可用，CLI fallback只能保留`focus`，因此Skill会停止。
 
 `kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
@@ -253,7 +287,9 @@ Kyoso 按以下顺序 load config：
 
 未知 key 会被拒绝。Boolean / numeric config keys 会转换为 schema 类型，string keys 保持字符串，然后重新验证完整 config。
 
-Project `kyoso.toml` 是 declarative config，不需要 trust approval。它可以设置 tools toggles、agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、经过 user global authorization 的 Codex `provider` 或继承 OpenRouter 时的 model 覆盖、workspace byte limits 和 additive `workspace.deny`、verification settings、advisory judge settings，以及 tightening-only security/network settings。
+Project `kyoso.toml` 是 declarative config，不需要 trust approval。它可以设置 agent `enabled` / `model` / `effort` / `role` / `timeoutMs`、经过 user global authorization 的 Codex `provider` 或继承 OpenRouter 时的 model 覆盖、workspace byte limits 和 additive `workspace.deny`、verification settings、advisory judge settings，以及 tightening-only security/network/CISA settings。
+
+`entrypoints.*`、`tools.*` 和 `reviewPolicy.*` 是 user-global policy。entrypoint 或 tool 被禁用时，Kyoso 会在启动 agents 前返回 structured policy block。`firstClassClient = "codex"`、`workspace.readOnly = true`、`network.mediatedWeb.enabled = false` 和 `audit.includeFileContents = false` 是 fixed / reserved values；不支持的值会被拒绝，而不是成为 no-op。
 
 Global TOML 用于 user-owned settings，包括 command 启动和 env forwarding。
 
@@ -373,8 +409,8 @@ Subscription-only setup:
 
 - Codex: 使用 local `codex` login
 - Claude: 运行 `claude setup-token`，然后设置 `CLAUDE_CODE_OAUTH_TOKEN`
-- Judge: 不设置 API keys，因此 Kyoso 使用 `deterministic_fallback`（参见 [Judge](#judge)）
-- 当存在 `OPENAI_API_KEY` 时，如需避免 OpenAI judge calls，请设置 `judge.provider = "none"`
+- Judge: 默认的 `deterministic_only` mode 不需要 API key（参见 [Judge](#judge)）
+- 如需禁用显式 LLM judge opt-in，请设置 `judge.mode = "deterministic_only"` 或 `judge.provider = "none"`
 
 Team admins 还应检查 organization Usage credits。如果启用了 credits，超出 subscription limits 的 billing behavior 由 Kyoso 外部控制。
 
@@ -382,10 +418,27 @@ Team admins 还应检查 organization Usage credits。如果启用了 credits，
 
 Kyoso 可以在只有 Claude 或只有 Codex 可用时运行。请在 `kyoso.toml` 中禁用缺失的 backend；示例见 `examples/claude-only.toml` 和 `examples/codex-only.toml`。
 
-在 single-agent mode 中，剩余 backend 会以 `combined_reviewer` 运行一次，同时覆盖 implementation 和 architecture/security 两类关注点。JSON output 会包含 `reviewMode: "single_agent"` 和 `agentsUsed`；Markdown output 会说明未执行 cross-model verification，并将 disagreements 标记为 N/A。
+在 single-agent mode 中，剩余 backend 会以 `combined_reviewer` 运行一次，同时覆盖 implementation 和 architecture/security 两个 perspectives。JSON output 包含 `reviewMode: "single_agent"`、`agentsUsed` 和 `coverage.independentReview: false`；Markdown output 会说明未执行 cross-model verification。设置 user-global `reviewPolicy.multiAgentRequired = true` 后，这种 degraded coverage 会变为 incomplete 并 block。
 
 该 mode 不提供独立的 cross-model validation，仍可能有 self-review bias。它仍保留独立只读 review process、temporary snapshots、adversarial review prompts、secret scanning 和 deterministic gates。
 
+### Execution budget and review stopping
+
+每次 review 都有 user-global hard ceiling，用于限制 model call 数、总 wall time、streaming agent text（message 和 thought chunk）以及每个 agent 的 finding 数量。
+
+```toml
+[reviewBudget]
+maxModelCalls = 4
+maxTotalWallTimeMs = 480000
+maxAgentOutputBytes = 65536
+maxFindingsPerAgent = 10
+skipOptionalPhasesWhenTokenUsageUnknown = true
+```
+
+`reviewBudget` 只能在 user-global 配置中设置；project `kyoso.toml` 和 `--set` 都不能修改它。MCP / library request 只能通过 `options.reviewBudget` 降低 ceiling，不能提高。Kyoso 会先同时预留两个 primary reviewer，再将剩余 call 用于 verification，并把 LLM Judge 作为 advisory。默认 Judge mode 是 `deterministic_only`。
+
+结果包含 `completion`、`executionBudget` 和 `requestFingerprint`。Markdown 与 Audit 会显示 call 数、wall time、output bytes，以及 reported 或 unknown token usage。若 `completion.status` 为 `incomplete`，Kyoso 返回普通的 `block` 结果且 `retryable: false`：该 block 表示 review coverage 未完成，而不是已经确认 code defect。不要自动重试相同 fingerprint。对于一个 review checkpoint，bundled Skill 只允许首次评审与 material fix 后的确认评审各1次；第三次需要用户明确批准。
+
 ### Verification
 
 Verification keys: `verification.<enabled|maxFindings|timeoutMs>`。Optional finding verification 默认 disabled:
@@ -399,11 +452,11 @@ timeoutMs = 90000
 allowDemotion = false
 ```
 
-启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。Phase 1 是 annotate-only：verification 可以更新 finding confidence 和 notes，但不会改变 severity 或 final decision。`allowDemotion` 为未来的 opt-in phase 保留，目前是 no-op。
+启用后，Kyoso 会让没有报告该 finding 的 agent 对 high/critical 且 single-source 的 finding 尝试反驳。verification 是 annotate-only：可以更新 confidence 和 notes，但永远不会改变 severity。被反驳或仍未解决的 material finding 会成为 `disputed`；若 verification 被 skip、失败、预算耗尽或 overflow，finding 会保留为 `not_verified`，并返回 incomplete coverage。这样可防止第二个 model 静默降低原始 risk signal。`allowDemotion` 为 compatibility 保留并被接受，但任一值都没有 demotion effect。
 
 ### Judge
 
-Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs 是 optional。设置 `OPENAI_API_KEY` 或 `CODEX_API_KEY` 可使用 OpenAI judge，设置 `ANTHROPIC_API_KEY` 可使用 Anthropic judge。Optional overrides:
+Judge keys: `judge.<mode|provider|timeoutMs>`。Judge LLMs 是 optional，默认 `mode = "deterministic_only"`；仅设置 credential 不会启动 judge call。OpenAI judge 需要 `mode = "deterministic_plus_llm"` 与 `OPENAI_API_KEY` 或 `CODEX_API_KEY`；Anthropic judge 需要同一 mode 与 `ANTHROPIC_API_KEY`。Optional overrides:
 
 - `OPENAI_BASE_URL`: OpenAI-compatible API base URL
 - `KYOSO_OPENAI_JUDGE_MODEL`: OpenAI judge model, default `gpt-5.4-mini`
@@ -413,7 +466,7 @@ Judge defaults 有意使用 lightweight models。若需要更强的 judge，请
 
 ### Timeouts
 
-Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round 默认 90 秒。MCP clients 应允许 tool calls 至少运行 360 秒。如果 `verification.enabled` 为 true，Kyoso 可能会运行额外的 cross-agent verification round，因此请至少允许 480 秒。
+Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round 默认 90 秒。review-wide deadline 默认480秒，各 phase 使用剩余 deadline 而不会延长它。MCP clients 应允许 tool calls 至少运行480秒。
 
 ### Audit
 
@@ -425,7 +478,7 @@ Default agent timeouts 是 Codex 120 秒、Claude 300 秒；verification round
 
 `audit.directory`是 logical relative directory（默认：`.kyoso/traces`），不是 workspace 内的 directory。现有 workspace `.kyoso/traces`不会被自动迁移或删除。
 
-Raw agent output 和 raw file contents 默认禁用。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning（参见 [Safety Model](#safety-model)）。
+Raw agent output 默认禁用。`audit.includeFileContents` 是 reserved value，固定为 `false`；不会通过该设置保存 file contents。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning（参见 [Safety Model](#safety-model)）。
 
 ## Safety Model
 
@@ -445,6 +498,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 
 ## 迁移
 
+- 将 project `kyoso.toml` 中的 `tools.*` 移到 user-global config。project-owned tool availability 现在会被拒绝，避免 repository content 禁用 review。
 - 从手动MCP迁移到CLI＋Skill：先安装CLI和Skill，再运行`codex mcp remove kyoso`或`claude mcp remove kyoso --scope local|project|user`。
 - 从CLI＋Skill迁移到Plugin：添加Plugin并确认enabled后，再删除手动MCP注册。手动复制的Skill不会自动删除。
 - 从Plugin迁移到CLI＋Skill：先安装CLI和Skill，再运行`codex plugin remove kyoso@kyoso`。
@@ -455,7 +509,7 @@ Windows，以及无法证明所需 filesystem capability 的环境，会 fail-cl
 - MCP timeout: 将 client tool timeouts 设置为至少 360 秒；当 `verification.enabled` 为 true 时，设置为至少 480 秒。Kyoso defaults 请参阅 [Timeouts](#timeouts)。
 - Fresh npm release: safe-chain 等 minimum-package-age protection 可能会在 publish 后短时间内 block `npx @kyo-so/cli` resolution。
 - Deprecated TypeScript config: 除非传入 `--trust-config`，否则 untrusted `kyoso.config.ts` 会被 skip；新配置请使用 `kyoso.toml`。
-- OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。已发布 Marketplace Plugin 在下一次 promotion 前不会 forward 此 key，setup 也不会重写已有 MCP registration。
+- OpenRouter key missing: 确认 Codex `model` 非空、`OPENROUTER_API_KEY` 已 forward 给 Kyoso process，并已重启 client；再运行 `kyoso doctor`。Marketplace Plugin `0.4.0` 及更高版本会将此变量名 forward 给 Kyoso process，旧版本不会。setup 也不会重写已有 MCP registration。
 
 ### Codex approval prompts
 

package/dist/acp/FakeAgentManager.d.ts

@@ -1,6 +1,6 @@
 import type { AgentRunInput, AgentRunResult } from "../core/types.js";
 import { BaseAcpAgentManager } from "./AcpAgentManager.js";
-export type FakeAgentScenario = "success" | "markdown_json" | "timeout" | "malformed" | "preflight_failure" | "openrouter_key_missing" | "auth_failure" | "permission_request" | "write_attempt";
+export type FakeAgentScenario = "success" | "markdown_json" | "timeout" | "malformed" | "preflight_failure" | "openrouter_key_missing" | "auth_failure" | "permission_request" | "write_attempt" | "unknown_usage";
 export type FakeVerifierVerdict = {
     findingId: string;
     verdict: "confirmed" | "refuted" | "uncertain";

package/dist/acp/prompts.d.ts

@@ -1,3 +1,8 @@
-import type { AgentName, AgentRole, KyosoFinding, KyosoReviewRequest, ReviewTool } from "../core/types.js";
-export declare function buildAgentPrompt(tool: ReviewTool, request: KyosoReviewRequest, agent: AgentName, role: AgentRole): string;
-export declare function buildFindingVerifierPrompt(tool: ReviewTool, request: KyosoReviewRequest, verifier: AgentName, findings: KyosoFinding[]): string;
+import type { AgentName, AgentRole, KyosoFinding, KyosoReviewRequest, ReviewLens, ReviewTool } from "../core/types.js";
+export declare function buildAgentPrompt(tool: ReviewTool, request: KyosoReviewRequest, agent: AgentName, role: AgentRole, policy?: {
+    requiredLenses?: ReviewLens[];
+    cisaEnabled?: boolean;
+}): string;
+export declare function buildFindingVerifierPrompt(tool: ReviewTool, request: KyosoReviewRequest, verifier: AgentName, findings: KyosoFinding[], policy?: {
+    requiredLenses?: ReviewLens[];
+}): string;

package/dist/aggregate/aggregateFindings.d.ts

@@ -3,6 +3,7 @@ export type AggregatedReview = {
     findings: KyosoFinding[];
     testsToAdd: string[];
     residualRisks: string[];
+    openQuestions: string[];
     disagreements: Array<{
         topic: string;
         positions: Array<{