carlos-flow 2.9.0 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,44 @@
5
5
 
6
6
  ---
7
7
 
8
+ ## [2.10.0] - 2026-11-12 — 合并 _carlos-flow-remote 分支:verdict_role 落盘 + 协议字段漂移修复
9
+
10
+ > 本版把 `_carlos-flow-remote` 分支上**发布线缺失**的独有内容合并进来(该分支后被
11
+ > v2.8.0/v2.9.0 取代,其角色门禁实现已被更强的 claimed_role 口径覆盖,故不整支合入)。
12
+
13
+ ### ✨ 新增 | Added
14
+
15
+ - **`verdict_role` 字段** —— 持久记录「本条裁定是谁落的」。
16
+ - 与 `claimed_role` 的区别:后者是「会话最近 claim 的角色」(可能已过期),
17
+ 前者是「实际写下这条裁定时传进来的 role」,直接回答「这条 PASS 是谁落的」。
18
+ - `flow_verdict` 返回值、`flow_status` 均可读;未显式声明 role 时落 `null`(不谎报)。
19
+ - **`test/protocol-consistency.mjs`** —— 协议一致性守护(5 条断言):
20
+ 字段集合、字段默认值、ERROR_LAYERS 含「门禁拒绝」层、实现方式未回退为手写常量。
21
+
22
+ ### 🐛 修复 | Fixed
23
+
24
+ - **`protocol.js` 的 `STATE_FIELDS` 与状态结构漂移**:原先是**手写常量**,已漏掉
25
+ **9 个字段**(`claimed` / `claimed_role` / `activation_pending` / `activation_activated` /
26
+ `dispatch_baseline` / `last_falsify` / `audit_axes` / `audit_axes_ts` / `schemaVersion`)。
27
+ Agent 通过 `flow_protocol` 读到过期的字段表,会按错误的字段名做决策。
28
+ 改为从 `defaultState()` 生成,并加测试钉死。
29
+
30
+ ### 🔒 变更 | Changed
31
+
32
+ - **`ERROR_LAYERS` 新增「门禁拒绝(非错误)」层**:明确告知 Agent 闸门拦不是工具坏了,
33
+ 应按错误信息里的下一步修正后重试,**不要重试同一调用**。
34
+ - **状态结构版本 v3 → v4**:`migrate()` 新增 v3→v4 迁移,补全旧状态的 `verdict_role`。
35
+
36
+ ### 🔬 验证 | Verification
37
+
38
+ - e2e **79/0**(新增 28a–28c 三条 `verdict_role` 用例);p0 22/0;scope 10/0;
39
+ package-e2e 19/0;audit 23/0;bridge 6/0;trigger 29/0;concurrency 3/0;
40
+ acceptance 13/0;lang 12/0;smoke 通过。
41
+ - `check:full` / `check:parity` / `check:lang` / `check:anchors` 17/17 / `check:readme` /
42
+ `check:params` / `check:claims` / `check:no-dead-handler` 全部通过。
43
+
44
+ ---
45
+
8
46
  ## [2.9.0] - 2026-11-12 — 双轴审查门禁:PASS 裁定前必须收齐 Standards / Spec 两轴证据
9
47
 
10
48
  ### ✨ 新增 | Added
package/README.en.md CHANGED
@@ -293,8 +293,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
293
293
  | `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr + `output_hash` |
294
294
  | `flow_falsify` | **Negative control**: run `verify.cmd` pre-change (must fail) and post-change (must pass) | Vacuous tests (`|| true`) rejected; required before PASS |
295
295
  | `flow_check_scope` | Check whether files are in scope | Empty scope → fail-closed, everything out of scope |
296
- | `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch / passing verification / passing negative control / **both audit axes**; any axis FAIL blocks PASS |
297
- | `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
296
+ | `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch / passing verification / passing negative control / **both audit axes**; any axis FAIL blocks PASS; returns `verdict_role` |
297
+ | `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
298
298
  | `flow_audit` | Read the audit stream | Includes 6 activation-related event kinds |
299
299
  | `flow_diff_hunks` | Parse `git diff -U0` hunk ranges | — |
300
300
  | `flow_bypass` | Toggle bypass mode | Requires `confirmed=true`; auto-cleared on dispatch |
package/README.md CHANGED
@@ -299,8 +299,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
299
299
  | `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
300
300
  | `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
301
301
  | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
302
- | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS |
303
- | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
302
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` |
303
+ | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
304
304
  | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
305
305
  | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
306
306
  | `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
package/README.zh.md CHANGED
@@ -299,8 +299,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
299
299
  | `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
300
300
  | `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
301
301
  | `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
302
- | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS |
303
- | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
302
+ | `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` |
303
+ | `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
304
304
  | `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
305
305
  | `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
306
306
  | `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
package/TRIGGER_GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Carlos Flow 智能触发引擎使用指南
2
2
 
3
- > **版本**: v2.9.0
3
+ > **版本**: v2.10.0
4
4
  > **适用**:`carlos-flow` 单包架构(2.6.0+)
5
5
  > **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
6
6
 
@@ -779,5 +779,5 @@ MIT License
779
779
 
780
780
  ---
781
781
 
782
- **版本**: v2.9.0
782
+ **版本**: v2.10.0
783
783
  **更新日期**: 2026-11-12
package/ghost.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "name": "Carlos 工作流",
6
6
  "description": "机械门禁 MCP:留痕/派发/裁定/审计/快照/免检/还原。自动管理 Bridge 后台常驻,首次调用 ~3-5s,后续 ~1s。",
7
7
  "whenToUse": "需要走 Carlos 工作流门禁时使用:留痕/派发/裁定/审计/快照/免检/还原",
8
- "version": "2.9.0",
8
+ "version": "2.10.0",
9
9
  "kind": "mcp",
10
10
  "entry": "client/carlos.js",
11
11
  "command": "门禁",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "carlos-flow",
3
- "version": "2.9.0",
3
+ "version": "2.10.0",
4
4
  "description": "Carlos 工作流 — AI 编码 Agent 的机械门禁。留痕/派发/验证/裁定/审计/还原,约束写在代码里而非提示词里。单一包支持 Cindy/OpenCode/Cursor/Cline/VS Code/Claude Desktop。",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
package/src/index.js CHANGED
@@ -782,11 +782,19 @@ const TOOLS = [
782
782
  state.verdict = verdict;
783
783
  state.completed_ok = verdict === "PASS";
784
784
  state.verdict_ts = Date.now();
785
+ // 落盘裁定者角色:审计链据此回溯「这条 PASS 是谁落的」。
786
+ state.verdict_role = a.role === undefined ? null : a.role;
785
787
  saveState(sessionId, state);
786
788
 
787
789
  audit("resolution", sessionId, { kind: "verdict", verdict, notes: a.notes, role: a.role });
788
790
 
789
- const result = { ok: true, verdict, completed_ok: state.completed_ok, notes: a.notes };
791
+ const result = {
792
+ ok: true,
793
+ verdict,
794
+ completed_ok: state.completed_ok,
795
+ notes: a.notes,
796
+ verdict_role: state.verdict_role,
797
+ };
790
798
  if (findings.length) result.findings = findings;
791
799
  return ok(result);
792
800
  } catch (e) {
@@ -820,6 +828,10 @@ const TOOLS = [
820
828
  dispatch_count: state.dispatch_count,
821
829
  max_dispatch: MAX_DISPATCH,
822
830
  verdict: state.verdict,
831
+ // 本条裁定是谁落的("auditor" | "executor" | null)。
832
+ // 与 claimed_role 不同:后者是「会话最近 claim 的角色」,可能已过期;
833
+ // 这个字段直接回答「这条 PASS 是谁落的」。
834
+ verdict_role: state.verdict_role === undefined ? null : state.verdict_role,
823
835
  verified: !!state.verdict,
824
836
  // verify_passed:真实验证是否通过(last_verify.ok===true 且命令与当前卡片一致)。
825
837
  // 注意 verified 只表示「是否已有裁定」,不代表验证通过——两者语义不同,不可混用。
package/src/protocol.js CHANGED
@@ -1,6 +1,12 @@
1
1
  // Carlos Flow 协议 — 路由档位 / 四段合同 / 报告规格 / 错误分层 / 状态字段的唯一真源。
2
2
  // 被协调器(coordinator)与各角色 Agent 共同引用。
3
3
 
4
+ // 状态字段从 defaultState() 生成,而不是手写常量 ——
5
+ // 手写副本会漂移(历史上就漏过 claimed / claimed_role / activation_* 等 9 个字段),
6
+ // 而协议是 Agent 运行时读取的权威依据,漂移会让 Agent 按错误的字段名做决策。
7
+ // 代价:protocol.js 依赖 state.js(纯数据模块,无副作用,无循环依赖)。
8
+ import { defaultState } from "./state.js";
9
+
4
10
  export const PROTOCOL = {
5
11
  ROUTE_TABLE: `| 档 | 场景 | 动作 |
6
12
  |---|---|---|
@@ -23,9 +29,12 @@ auditor 报告 ≤200 字,五段式:裁定 / 失败类型 / scope 标注 /
23
29
  |---|---|---|
24
30
  | 基础设施故障 | 网络抖动、模型不可用、配额耗尽 | 静默降级或改用 Explore / 自读只读验证,不把原始错误喂回 |
25
31
  | Agent 故障 | 工具名错、参数错 | 把错误喂回并附恢复指引 |
26
- | 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件 |`,
32
+ | 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件 |
33
+ | 门禁拒绝(非错误) | 闸门拦下当前动作(如 PASS 裁定角色不对、验证未跑通、验证已过期、scope 越界、双轴未齐) | **这不是工具坏了**,是门禁在正常工作。按错误信息里的下一步修正后重试:补齐缺失动作(如先 flow_claim role=auditor)再重试。**不要重试同一调用** |`,
27
34
 
28
- STATE_FIELDS: `{"card":null,"card_ts":0,"tier":"read_only","task_id":null,"dispatch_count":0,"write_files":0,"last_user_ts":0,"bypass":false,"bypass_ts":0,"verdict":null,"completed_ok":false,"stale":false}`,
35
+ // 从 defaultState() 生成,保证与状态结构永远一致(漂移防护)。
36
+ // 测试 test/protocol-consistency.mjs 会逐字段比对,手工改回常量会红。
37
+ STATE_FIELDS: JSON.stringify(defaultState()),
29
38
 
30
39
  AUDIT_EVENTS: `["run","finding","decision","resolution"]`,
31
40
 
package/src/state.js CHANGED
@@ -93,7 +93,7 @@ export function sanitizeId(s) {
93
93
 
94
94
  // 当前状态文件结构版本号。
95
95
  // 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
96
- export const CURRENT_SCHEMA_VERSION = 3;
96
+ export const CURRENT_SCHEMA_VERSION = 4;
97
97
 
98
98
  /**
99
99
  * 迁移旧版本的状态文件。
@@ -111,6 +111,9 @@ export const CURRENT_SCHEMA_VERSION = 3;
111
111
  * v2 → v3:新增 audit_axes / audit_axes_ts(双轴审查证据)。
112
112
  * · 旧状态没有这两个字段 → 补默认结构(两轴均为 null = 尚未审查,裁定会拒绝 PASS)
113
113
  * · audit_axes 存在但结构不全时也在此补齐,避免读到半初始化对象
114
+ *
115
+ * v3 → v4:新增 verdict_role(本条 PASS 是谁落的)。
116
+ * · 旧状态没有这个字段 → 补 null(仅影响可观测性,不影响门禁判定)
114
117
  */
115
118
  export function migrate(parsed) {
116
119
  if (!parsed || typeof parsed !== "object") return parsed;
@@ -146,6 +149,12 @@ export function migrate(parsed) {
146
149
  v = 3;
147
150
  }
148
151
 
152
+ if (v < 4) {
153
+ // v3 → v4
154
+ if (out.verdict_role === undefined) out.verdict_role = null;
155
+ v = 4;
156
+ }
157
+
149
158
  out.schemaVersion = CURRENT_SCHEMA_VERSION;
150
159
  return out;
151
160
  }
@@ -201,6 +210,11 @@ export function defaultState() {
201
210
  audit_axes: { standards: null, spec: null },
202
211
  // 两轴最后提交时间(审计链留痕用;不参与冒充校验,校验看 card_ts)。
203
212
  audit_axes_ts: 0,
213
+ // 本条裁定是谁落的("auditor" | "executor" | null)。
214
+ // 与 claimed_role 的区别:claimed_role 是「会话最近 claim 的角色」(可能已过期),
215
+ // verdict_role 是「实际写下这条裁定时传进来的 role」,直接回答「这条 PASS 是谁落的」。
216
+ // 审计流水里也有 role,但那是日志;这是状态层的持久记录,可用 flow_status 直接查。
217
+ verdict_role: null,
204
218
  };
205
219
  }
206
220