carlos-flow 0.0.0-stage → 2.5.9
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/.mcprc.template +28 -0
- package/CHANGELOG.md +97 -0
- package/LICENSE +21 -0
- package/README.en.md +488 -0
- package/README.md +217 -2
- package/README.zh.md +218 -0
- package/TRIGGER_GUIDE.md +592 -0
- package/bridge/mcp-bridge.js +168 -0
- package/client/carlos.js +484 -0
- package/ghost.json +405 -0
- package/opencode.json +32 -0
- package/opencode.json.template +32 -0
- package/package.json +85 -3
- package/plugins/carlos-flow-trigger.js +204 -0
- package/scripts/check-mutant-anchors.mjs +53 -0
- package/scripts/check-repo-parity.mjs +293 -0
- package/scripts/clean-readme-noise.mjs +53 -0
- package/scripts/mutation-check.mjs +440 -0
- package/scripts/release.mjs +204 -0
- package/scripts/sync-readme.mjs +99 -0
- package/scripts/verify-activation-e2e.sh +55 -0
- package/scripts/verify-install-e2e.sh +104 -0
- package/src/card.js +288 -0
- package/src/dispatch.js +252 -0
- package/src/index.js +1230 -0
- package/src/protocol.js +77 -0
- package/src/state.js +479 -0
- package/src/trigger.js +909 -0
- package/templates/claude/claude_desktop_config.json +11 -0
- package/templates/cline/mcp.json +11 -0
- package/templates/cursor/mcp.json +11 -0
- package/templates/vscode/mcp.json +12 -0
- package/trigger-config.example.json +35 -0
- package/trigger-config.usable.json +16 -0
package/.mcprc.template
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Carlos 工作流 - OpenCode MCP 配置模板
|
|
2
|
+
# 复制为 ~/.config/opencode/.mcprc 并修改路径
|
|
3
|
+
|
|
4
|
+
mcpServers:
|
|
5
|
+
carlos-flow:
|
|
6
|
+
command: "node"
|
|
7
|
+
args: ["__ROOT__/src/index.js"]
|
|
8
|
+
env:
|
|
9
|
+
CARLOS_FLOW_HOME: "<CARLOS_FLOW_HOME>"
|
|
10
|
+
# 可选:如需使用 rea 工具
|
|
11
|
+
# REA_MCP_ROOT: "<REA_MCP_ROOT>"
|
|
12
|
+
# GHIDRA_INSTALL_DIR: "<GHIDRA_HOME>"
|
|
13
|
+
# JAVA_HOME: "<JAVA_HOME>"
|
|
14
|
+
# NODE_PATH: "node"
|
|
15
|
+
|
|
16
|
+
# 可选:rea 逆向分析工具(需单独安装 Ghidra + JDK 21)
|
|
17
|
+
# rea:
|
|
18
|
+
# command: "node"
|
|
19
|
+
# args: ["<REA_MCP_ROOT>/node_modules/rea-agents/scripts/rea.mjs", "mcp"]
|
|
20
|
+
# env:
|
|
21
|
+
# GHIDRA_INSTALL_DIR: "<GHIDRA_HOME>"
|
|
22
|
+
# JAVA_HOME: "<JAVA_HOME>"
|
|
23
|
+
|
|
24
|
+
# 说明:
|
|
25
|
+
# - __ROOT__ 替换为本仓库根目录绝对路径(含 src/)
|
|
26
|
+
# - <CARLOS_FLOW_HOME> 替换为状态/审计目录,如 ~/carlos-flow 或 ~/opencode-backups
|
|
27
|
+
# - Windows 路径用正斜杠 / 或双反斜杠 \
|
|
28
|
+
# - OpenCode 2.2.2+ 读取此文件或 opencode.json(二选一生效)
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# 变更日志 | Changelog
|
|
2
|
+
|
|
3
|
+
> 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)
|
|
4
|
+
> Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), versioning follows [SemVer](https://semver.org/)
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## [2.5.9] - 2026-11-06 — 清除全部个人私有路径(安装/分发可用性修复)
|
|
9
|
+
|
|
10
|
+
### 🐛 修复 | Fixed
|
|
11
|
+
|
|
12
|
+
> 这一版修的全是**会跟着包分发给所有人**的问题 —— 开发机路径被写进了产物里。
|
|
13
|
+
> 用户按文档照抄必然失败,且无法自行察觉。
|
|
14
|
+
|
|
15
|
+
| # | 问题 | 影响 | 修复 |
|
|
16
|
+
|---|------|------|------|
|
|
17
|
+
| T-52 | Cindy 插件设置页默认值写死 `D:/cindy/carlos-flow-mcp` | Cindy 用户**开箱即见**一个开发者本机的无效路径(目录名根本不存在) | 默认值改为空(留空即用插件自带 `src/`),placeholder 改为通用说明 |
|
|
18
|
+
| T-53 | `scripts/verify-activation-e2e.sh` 写死 `D:/cindy/publish-output/carlos-flow-cindy` | 该脚本**随包分发**:用户跑会 `cd` 到不存在的路径;且在 **opencode 包里还指向 cindy 仓**(跨仓串味) | 根目录改为从**脚本自身位置**推导(`scripts/` → 仓库根),两仓一致 |
|
|
19
|
+
| T-54 | README 安装示例写死 `D:/dev-env/node-v22.23.4-win-x64/...`、`C:/Users/EDY/.carlos-flow` | **用户照抄必失败**(路径不存在 / 指向别人的用户名目录) | 改为 `<npm 全局目录>` 占位符 + `npm root -g` 推导说明;`CARLOS_FLOW_HOME` 改用 `~/.carlos-flow` 平台无关写法 |
|
|
20
|
+
| T-55 | README 环境变量表 / 路径说明 / QA 报告残留 `D:/dev-env/rea`、`D:/dev-env/ghidra/...`、`D:/dev-env/jdk-...`、`D:/cindy/.qa-logs/...` | 继续散落开发者本机路径 | 全部替换为通用示例(`/opt/rea`、`/opt/ghidra_*`、`/usr/lib/jvm/*`);QA 报告改为指向 CI 输出 |
|
|
21
|
+
| T-56 | README 声称 Windows 配置目录是 `%APPDATA%opencode` | **实证是错的**:OpenCode 走 XDG 风格,Windows 上真正被读的是 `~/.config/opencode/`(`$env:USERPROFILE.configopencode`)。照 README 放到 `%APPDATA%` 的用户 → 配置读不到 → **MCP server 根本不启动** | README 统一改为「所有平台都是 `~/.config/opencode/`」,并给出 Windows 的 `$env:USERPROFILE.configopencode` 写法 + 明确警示「不是 %APPDATA%」(中文/英文 FAQ 同步) |
|
|
22
|
+
| T-57 | `CARLOS_FLOW_HOME=~/.carlos-flow` **不会被展开** | `path.normalize` 只换分隔符不展开 `~` → 状态/审计链写到**当前工作目录下字面名为 `~` 的目录**(实测 `FLOW_HOME = ~.carlos-flow`),位置诡异极易丢失 | `state.js` / `trigger.js` 新增 `expandHome()`,统一展开 `~`、`~/...`(Windows 同时支持 `~`);新增回归用例(trigger 29 项) |
|
|
23
|
+
| T-58 | `scripts/verify-install-e2e.sh` 里路径内插进 `node -e` 字符串 | Windows 路径含**反斜杠与空格** → 被拆坏,测试在 Windows 上假失败(实测 tools/list 返回 0 个工具) | 路径一律经**环境变量**传给 node 进程;包目录布局多平台探测(lib/node_modules、node_modules、Lib/…) |
|
|
24
|
+
|
|
25
|
+
> 补充:另修正 `verify-activation-e2e.sh` 的跨仓串味(opencode 包里原本指向 cindy 仓),
|
|
26
|
+
> 以及 README 里 `D:/dev-env/rea`、`ghidra`、`jdk` 等开发机路径(全部换成通用示例)。
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### 🧪 新增 | Added
|
|
31
|
+
|
|
32
|
+
- **`scripts/verify-install-e2e.sh`** —— 「从没见过本项目的用户」视角的安装验收:
|
|
33
|
+
从真实 npm registry 装包(独立 prefix,模拟干净环境)→ 检查包内容完整性 →
|
|
34
|
+
验证触发器模板是合法 JSON 且可被引擎读取 → 拉起 MCP server 走真实 JSON-RPC
|
|
35
|
+
(`tools/list` / `flow_status` / `flow_trigger_check`)→ 审计包内无个人私有路径。
|
|
36
|
+
跨平台(Windows / Linux 均实测通过);路径一律经环境变量传给 node,**不内插进 `node -e` 字符串**
|
|
37
|
+
(Windows 路径含反斜杠与空格,内插会被拆坏)。
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## [2.5.8] - 2026-11-06 — 修包内容与文档不一致 + 变异体锚点加固
|
|
41
|
+
|
|
42
|
+
### 🐛 修复 | Fixed
|
|
43
|
+
|
|
44
|
+
| # | 问题 | 影响 | 修复 |
|
|
45
|
+
|---|------|------|------|
|
|
46
|
+
| T-47 | `trigger-config.usable.json` 整份含 `//` 注释 ⇒ **不是合法 JSON** | 复制成 trigger-config.json 后 `JSON.parse` 抛错 → 配置被整体丢弃、静默回退默认词表 ⇒ 用户以为「复制即可生效」,实际自定义词**一条都不生效** | 改为纯 JSON;`trigger-config.example.json` 补上真实可配置键(原先真键都带 `_` 前缀,直接复制同样无效) |
|
|
47
|
+
| T-48 | README 安装命令钉死 `@2.5.5` | 用户照文档装不到含 bin 修复的版本,老 EEXIST 照原样复现 | 改为不钉版本(`npm install -g carlos-flow-opencode`),避免文档随发版过时;版本行同步;`docs/` 报告链接改 GitHub 绝对链接(`docs/` 不在 npm files 白名单,相对链接在 npm 页面 404) |
|
|
48
|
+
| T-49 | `.mutation-report.md` 未被 `.gitignore` 覆盖 | 跑一次变异测试就脏工作区 ⇒ `release.mjs` 的「工作区干净」硬拦、**发不了** | 加 `.gitignore` + 把历史上误提交的该文件取消跟踪并删除;同时清理根目录 13 个死进程残留的 `bridge-*.pid` |
|
|
49
|
+
| T-50 | M6/M9 **共用同一段 from 锚点**、M10 的 from 仅 2 行 | 该段一改缩进/注释 → 多个变异体同时 SKIP:**静默失去守护作用**,而历史报告仍显示「13/13 全部被抓住」 | 三个锚点各自唯一且更长;新增 `scripts/check-mutant-anchors.mjs`(`npm run check:anchors`)+ 接入 CI,锚点失效立刻报错 |
|
|
50
|
+
| T-51 | `release.mjs` 的跳过逻辑按**标签**、目标路径按**身份**解析 —— 两者不同源 | 在 opencode 仓**不带** `--include-peer` 时:「opencode」分支被跳过(跳掉**自己**),「cindy」分支照跑却推了**对方** ⇒ **opencode 包永不发布,反而去发 cindy**,而日志还写「跳过 opencode」 | 推送循环重构为「跳过与路径同源于身份」:本仓**始终**发布,对方仓受 `--include-peer` 约束;两个标签分支合并为一段,日志带仓名与身份标记。四种组合的决策推演已全部验证正确 |
|
|
51
|
+
|
|
52
|
+
> 实测:两个触发器模板复制后,自定义词「评审」生效、默认中文词「门禁」保留、只读词「讲一下」已追加。
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
## [2.5.7] - 2026-11-06 — 修 bin 名冲突:两个包可同时全局安装
|
|
56
|
+
|
|
57
|
+
### 🐛 修复 | Fixed
|
|
58
|
+
|
|
59
|
+
| # | 问题 | 影响 | 修复 |
|
|
60
|
+
|---|------|------|------|
|
|
61
|
+
| T-46 | `carlos-flow-cindy` 与 `carlos-flow-opencode` 声明了**同名 bin** `carlos-flow` | `npm install -g` 两个包时后者与前者互斥 → **EEXIST 报错,两个包无法共存** | npm 的规则是同名 bin 不能共存,必须有一个让位:`carlos-flow-cindy` 保留 `carlos-flow`(通用名)并新增别名 `carlos-flow-cindy`;`carlos-flow-opencode` 只用 `carlos-flow-opencode`。opencode 用户升级后请改用新命令名(README 用法本就是 `node client/carlos.js ...`,不依赖 bin 名) |
|
|
62
|
+
|
|
63
|
+
> 实测:修复前 `npm install -g carlos-flow-cindy@2.5.6 carlos-flow-opencode@2.5.6` 报 EEXIST,修复后两包可同时安装。
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
## [2.5.6] - 2026-11-06 — 门禁伪填充绕过修复 + 触发器接入 MCP 路径
|
|
67
|
+
|
|
68
|
+
### 🐛 修复 | Fixed
|
|
69
|
+
|
|
70
|
+
| # | 问题 | 影响 | 修复 |
|
|
71
|
+
|---|------|------|------|
|
|
72
|
+
| T-34 | `acceptance` 必填校验只看数组长度 | `[""]` / `[null]` / `[0]` / `[{}]` 等伪填充被当作「已填」——空验收标准的卡片能过校验,激活闸门也会误判为「已补齐」而解开 | 必填校验与闸门推导统一改为**内容判定**(严格口径:每个元素都必须是有效非空字符串) |
|
|
73
|
+
| T-35 | 卡片文本字段用 `String(x)` 归一化 | `[null]`→`["null"]`、`[{}]`→`["[object Object]"]`,垃圾串被当成合法验收标准 | 取消过滤式归一化,两条入口(结构化 / cardText)均保留原始类型,由校验器统一判定 |
|
|
74
|
+
| T-36 | `trigger-config.json` 浅合并 | 用户写一个自定义词就把默认词表(含内置中文流程词)整个丢掉,中文场景重新变回 0 分 | 改**深合并**:keywordWeights 合并、词表数组追加去重 |
|
|
75
|
+
| T-37 | README FAQ / TRIGGER_GUIDE 仍写「默认词表为英文」 | 文档与实现不符,用户据此以为中文不触发 | 全部更正,并说明自定义是**追加**不是替换 |
|
|
76
|
+
| T-38 | 验收标准判定用 some(至少一个有效) | `[null,"x"]` 混入的 null 会原样落盘并进入 executor 合同文本 | 收紧为 every(每个元素都必须有效) |
|
|
77
|
+
| T-39 | scope 非字符串元素被静默丢弃 | `scope=[123]` → 静默降档成 read_only 空卡且无提示 | 入口即明确拒绝 |
|
|
78
|
+
| T-40 | 参数校验不查数组元素类型 | `paths:["README.md",123]` 抛不可读的 Node 底层错误 | 补元素级校验,入口即给明确提示 |
|
|
79
|
+
|
|
80
|
+
### ✨ 新增 | Added
|
|
81
|
+
|
|
82
|
+
- **`flow_trigger_check` MCP 工具** —— 触发引擎不再只接在命令行客户端上,宿主可在消息事件里调用它,
|
|
83
|
+
获得与 CLI 完全一致的自动触发行为(MCP 协议是被动的,服务端不能主动推送)
|
|
84
|
+
- **OpenCode 插件 `plugins/carlos-flow-trigger.js`** —— 监听 `chat.message` 钩子,实现消息级自动触发;
|
|
85
|
+
异常只记日志、绝不阻断用户消息
|
|
86
|
+
- **内置中文流程词** —— 工作流 / 门禁 / 任务卡 / 派发 / 子代理 / 流程 / 触发 / 执行 / 调度 / 审计 / 复核 / 留痕 / 裁定;
|
|
87
|
+
只收流程性词汇,不收「实现 / 新增 / 接口」这类普通开发动词
|
|
88
|
+
- **`trigger-config.usable.json` / `trigger-config.example.json`** —— 可直接用的中文触发配置模板
|
|
89
|
+
- **`test/e2e-acceptance.mjs`(`npm run test:acceptance`)** —— 端到端验收:MCP 触发 / 中文词表 /
|
|
90
|
+
伪填充拒绝 / 配置合并 / 插件真实开卡
|
|
91
|
+
|
|
92
|
+
### 🌐 跨平台 | Cross-platform
|
|
93
|
+
|
|
94
|
+
- `runVerifyCommand` 不再硬编码 `cmd.exe`(Linux/macOS 上命令根本没跑,exitCode=127,门禁失守)
|
|
95
|
+
- OpenCode DB 路径多路探测(XDG / macOS 原生 / Windows APPDATA),修复 macOS/Windows 读不到用户原话
|
|
96
|
+
- npm 包补入 `scripts/` 目录 —— 装包后 `npm run test:e2e` 不再因缺文件失败
|
|
97
|
+
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Carlos Flow Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,488 @@
|
|
|
1
|
+
# Carlos Flow — Cindy Edition
|
|
2
|
+
|
|
3
|
+
> **Mechanical gatekeeping for AI coding agents**: Record → Dispatch → Verify → Verdict → Audit → Restore
|
|
4
|
+
> Turns "trust the agent" into "verify the agent" — with machine-enforced scope limits, real command execution, and a tamper-proof audit chain.
|
|
5
|
+
**语言 / Languages:** [中文](README.zh.md) | [English](README.en.md)
|
|
6
|
+
**版本 / Version:** 2.5.9 | **License:** MIT | **CI:** passing | **Node.js:** 22+ | **MCP:** 1.29+
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
## 🆕 What's new in v2.5.5
|
|
10
|
+
> In one line: **the workflow now recognises when it is its turn to step in.**
|
|
11
|
+
|
|
12
|
+
### ✨ Smart trigger engine (brand new)
|
|
13
|
+
No more manually saying "run the gate" every time. The engine reads your input, decides whether the Carlos workflow should start, and — crucially — **tells you why**.
|
|
14
|
+
|
|
15
|
+
| Layer | Component | What it does | Why it matters |
|
|
16
|
+
|-------|-----------|--------------|---------------|
|
|
17
|
+
| **L1** | `DynamicTriggerManager` | Dynamically computes "how many triggers are left in this session" | A fixed cap is either noisy or too strict; longer sessions and complex tasks automatically raise the ceiling |
|
|
18
|
+
| **L2** | `TriggerScorer` | Scores every message: keywords 50 + context 30 + intent 20, weighted to a **38**-point maximum | Whether to trigger must be **explainable** — you always see which words matched and how many points were scored |
|
|
19
|
+
| **L3** | `TriggerDecisionEngine` | Four-way decision: `trigger` / `review` / `ignore` / `throttled` | Turns "should we trigger?" from a hunch into an explicit rule |
|
|
20
|
+
|
|
21
|
+
**Key properties**
|
|
22
|
+
- 🎚️ **Dynamic cap**: `5 + sessionHours×0.5 + complexity×2 − triggersInWindow×0.3`, capped at 15
|
|
23
|
+
- 🛡️ **Non-intrusive**: 5-minute minimum interval per session; the more you trigger, the **lower** the cap (a penalty, not a bonus)
|
|
24
|
+
- 📊 **Transparent scoring**: returns the full `breakdown` (matched keywords / context words / intent type)
|
|
25
|
+
- ⚖️ **Honest under throttling**: even when throttled it returns the real score and confidence — it never pretends "0 points"
|
|
26
|
+
- 🧠 **Learns from feedback**: accepted / rejected triggers are persisted; when negative feedback dominates, the **trigger threshold is raised automatically** (more conservative)
|
|
27
|
+
- 📦 **Zero external dependencies**: plain JavaScript, no new npm packages
|
|
28
|
+
|
|
29
|
+
#### 🔁 Decision → Judgment → Activation (the piece that matters most here)
|
|
30
|
+
The earlier implementation only printed a log line when it hit — it never actually started the workflow. That gap is now closed:
|
|
31
|
+
|
|
32
|
+
| Stage | Action | Real effect |
|
|
33
|
+
|-------|--------|-------------|
|
|
34
|
+
| **Judgment** | L1 cap → L2 scoring → L3 four-way decision | Yields `decision` + `score` + `confidence` + `breakdown` |
|
|
35
|
+
| **Translation** | `buildActivationPlan()` | Turns the verdict into an **executable MCP action sequence** (each step tagged `auto`) |
|
|
36
|
+
| **Activation ①** | `flow_add_user_msg` | The user's own words are recorded and become the anchor source for the card's `quote` |
|
|
37
|
+
| **Activation ②** | `flow_submit_requirement` (`activation: true`) | Submits a `read_only` placeholder card — the session **enters the gated state** |
|
|
38
|
+
| **Gate** | `activation_pending` | Until `scope` / `acceptance` / `verify.cmd` are filled in, `flow_claim`, `flow_dispatch` and `flow_verdict` all **refuse** (no "PASS without ever running it") |
|
|
39
|
+
| **Release** | Resubmit the complete card | `activation_pending` clears → normal dispatch proceeds |
|
|
40
|
+
|
|
41
|
+
> Safety constraint: when the session **already has a card**, auto-activation skips card creation (it never overwrites an existing task). Auto-activation only handles "record + enter the gate" — it **never decides which files may change** on the agent's behalf.
|
|
42
|
+
|
|
43
|
+
##### 🔐 Four gate defenses (hardened after independent QA audit)
|
|
44
|
+
| Defense | What it blocks | Outcome |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| **Field-by-field verification** | Submitting with only `scope` filled while `acceptance` / `verify.cmd` are still empty | The gate **keeps holding** (`activation_pending` lists exactly what is still missing) |
|
|
47
|
+
| **No PASS without dispatch** | `verdict=PASS` on a card that was just submitted and never dispatched | Rejected; `completed_ok` stays `false` (`DIRECTION` / `LOCAL` are unaffected — rework notes are not blocked) |
|
|
48
|
+
| **Empty scope fails closed** | Modifying any file while the card's `scope` is empty | `flow_check_scope` reports **every** path as out-of-scope (the early implementation failed *open*, i.e. "empty whitelist → change anything") |
|
|
49
|
+
| **Dedicated audit events** | Asking afterwards "was this a placeholder card? was it ever released?" | `activation` / `activation_gate_activated` / `activation_gate_held` / `activation_gate_unlocked` / `activation_released` / `verdict_denied` are all queryable |
|
|
50
|
+
|
|
51
|
+
> Every one of these defenses has a matching **mutation test** (inject the regression → confirm the suite fails). 13 injected mutations, **all 13 caught**.
|
|
52
|
+
|
|
53
|
+
>
|
|
54
|
+
> Also fixed: trigger state was previously kept in **one shared file for all sessions**, so one session could throttle another — it is now stored per session.
|
|
55
|
+
|
|
56
|
+
### 🐛 7 real defects fixed
|
|
57
|
+
> These are all reproducible bugs, not "theoretical risks".
|
|
58
|
+
|
|
59
|
+
| # | Defect | Impact | Fix |
|
|
60
|
+
|---|--------|--------|-----|
|
|
61
|
+
| 1 | `client/carlos.js` is ESM but loaded the trigger engine with `require()`; the error was swallowed by `catch` | **Integration silently dead** — the engine never ran | Switched to dynamic `import()` |
|
|
62
|
+
| 2 | `canTrigger()` compared a 0–1 weighted average against a 5–15 cap | The cap check **could never fire** | Added `countTriggersInWindow()` returning the raw count |
|
|
63
|
+
| 3 | The history factor in the dynamic-cap formula was an **additive** term | More triggers meant a *higher* cap — the cap cancelled itself out | Changed to a **penalty** term (subtraction) |
|
|
64
|
+
| 4 | `processUserMessage()` hard-coded `sessionId='default'` | Ignored `context.sessionId`; sessions bled into each other | Session id now passed through from context |
|
|
65
|
+
| 5 | `src/trigger.js` detected its CLI entry via `import.meta.url.endsWith(process.argv[1])` | The `file:///` prefix meant it **never matched** — the CLI was decorative | Switched to `fileURLToPath()` + `resolve()` |
|
|
66
|
+
| 6 | `shouldTrigger()` returned early in the throttling branch | Score collapsed to `0` and confidence was lost | Score is now computed before throttling is judged |
|
|
67
|
+
| 7 | `test:trigger` wrote its result file into the publish directory | Polluted the published npm package | Now written to the system temp directory |
|
|
68
|
+
|
|
69
|
+
### 🔒 Security & hygiene
|
|
70
|
+
- 🚨 **`.gitignore` rule collision**: the trailing `*.tar.gz.npmrc.local` line meant `.npmrc.local` (which contains an **npm token**) was never actually ignored → split into separate rules
|
|
71
|
+
- 🏠 **State files no longer wander**: trigger state lands in `CARLOS_FLOW_HOME`, not the current working directory
|
|
72
|
+
- 🌐 **No hard-coded machine paths**: `D:\opencode-backups` → `~/.carlos-flow` (cross-platform default)
|
|
73
|
+
- 🧹 **42 one-off fix scripts and scratch files removed** (net −5325 lines)
|
|
74
|
+
|
|
75
|
+
### 🚀 Release engineering
|
|
76
|
+
- 🔑 **GitHub Actions OIDC publishing**: no npm token stored in the repository any more
|
|
77
|
+
- 🧩 **`scripts/release.mjs`**: version checks / bilingual consistency / tests / build / publish in one command
|
|
78
|
+
- 🛡️ **`npm run check:readme`**: prepublish hook keeps the three README files from drifting apart
|
|
79
|
+
- 📋 **Independent QA report**: [`docs/QA_REPORT_v2.5.5.md`](https://github.com/skyer-now/carlos-flow-cindy/blob/main/docs/QA_REPORT_v2.5.5.md) — third-party read-only acceptance before release
|
|
80
|
+
- 🧬 **Mutation report**: [`docs/MUTATION_REPORT_v2.5.5.md`](https://github.com/skyer-now/carlos-flow-cindy/blob/main/docs/MUTATION_REPORT_v2.5.5.md) — 13 injected mutations, **all 13 caught**
|
|
81
|
+
|
|
82
|
+
### 📚 Documentation readability
|
|
83
|
+
- Removed the repeated **language bar / version line noise** that was injected throughout the READMEs (24–26 occurrences per file → consolidated to 1 at the top); tables are no longer truncated
|
|
84
|
+
- Added [`TRIGGER_GUIDE.md`](TRIGGER_GUIDE.md): the complete smart-trigger guide
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
## 🎯 Why Carlos Flow?
|
|
88
|
+
Most AI coding workflows are **advisory**. The prompt says "only touch these files" — and the agent politely agrees, then rewrites half the repository. The prompt says "run the tests" — and the agent reports "tests pass" without ever running them.
|
|
89
|
+
Carlos Flow is **mechanical**. The constraints live in code, not in prose.
|
|
90
|
+
### Pain points it removes
|
|
91
|
+
| Pain | Typical state today | Carlos Flow's answer |
|
|
92
|
+
|------|--------------------|---------------------|
|
|
93
|
+
| **Scope creep** | "Only edit `src/auth.py`" — a suggestion, not a rule | `enforceScope()` compares real `git diff` output against the card's whitelist; out-of-scope files **block the dispatch** |
|
|
94
|
+
| **Verification theatre** | Agent claims "tests pass"; nobody can prove it | `runVerifyCommand()` actually spawns `verify.cmd`, captures `stdout` / `stderr` / `exitCode`; a `PASS` verdict additionally **requires** a passing verification |
|
|
95
|
+
| **Laundered audit logs** | Logs in a plain file — deletable, editable | SHA-256 **chained** audit log (`prevHash` → `hash`); altering one record breaks the chain |
|
|
96
|
+
| **Runaway bypass mode** | One sentence ("skip the gate, it's urgent") disables everything | Bypass requires an explicit `confirmed=true` on the card and **auto-resets on every dispatch** |
|
|
97
|
+
| **Infinite dispatch budget** | Claiming a slot resets the counter — unlimited retries | `dispatch_count` increments **only on dispatch**; quota exhaustion blocks both claim and dispatch |
|
|
98
|
+
| **Forgotten daemons** | "Did you start the server?" / port already in use | Bridge is auto-launched on first call, health-checked, token-authenticated, rate-limited |
|
|
99
|
+
| **Self-attested reviews** | Same agent implements *and* approves | Built-in `auditor` role with a separate contract; verdict is one of `PASS` / `DIRECTION` / `LOCAL` |
|
|
100
|
+
| **No way back from a bad change** | Manual `git revert` only | Automatic snapshot before dispatch → `flow_revert_plan` produces an atomic restore plan |
|
|
101
|
+
| **Manual kick-off every time** | "run the gate" — if you forget, you work unprotected | The **smart trigger engine** scores your input and only fires when the intent is clear |
|
|
102
|
+
### How it differs
|
|
103
|
+
| Capability | **Carlos Flow** | Raw MCP server | Prompt-only / scripts |
|
|
104
|
+
|------------|-----------------|-----------------|----------------------|
|
|
105
|
+
| **Scope enforcement** | ✅ runtime `git diff` level | ❌ none | ❌ relies on goodwill |
|
|
106
|
+
| **Real verification** | ✅ spawns the command, captures output; `PASS` requires it to pass | ❌ none | ❌ agent self-reports |
|
|
107
|
+
| **Tamper-proof audit** | ✅ SHA-256 chained | ❌ none | ❌ none |
|
|
108
|
+
| **Controlled bypass** | ✅ explicit + auto-reset | ❌ none | ❌ one-liner disables all |
|
|
109
|
+
| **Honest dispatch quota** | ✅ counts dispatch only | ❌ none | ❌ none |
|
|
110
|
+
| **Independent review** | ✅ built-in `auditor` role | ❌ none | ❌ optional |
|
|
111
|
+
| **Snapshot + restore** | ✅ automatic, atomic plan | ❌ none | ❌ manual `git revert` |
|
|
112
|
+
| **Daemon lifecycle** | ✅ automatic (Cindy edition) | ❌ manual | ❌ manual |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
## 🚀 Quick start (30 seconds)
|
|
116
|
+
|
|
117
|
+
### 1. Install
|
|
118
|
+
```bash
|
|
119
|
+
npm install -g carlos-flow-cindy
|
|
120
|
+
```
|
|
121
|
+
> ⚠️ **If you get `ETARGET: No matching version found`** — that is npm's **registry metadata cache** being stale,
|
|
122
|
+
> not a missing version. Clear the cache and retry:
|
|
123
|
+
> ```bash
|
|
124
|
+
> npm cache clean --force
|
|
125
|
+
> ```
|
|
126
|
+
> To confirm the version really exists: `npm view carlos-flow-cindy versions`
|
|
127
|
+
|
|
128
|
+
### 2. Configure
|
|
129
|
+
|
|
130
|
+
The Cindy edition installs from the **plugin marketplace**: Cindy → Settings → Plugins → Browse marketplace →
|
|
131
|
+
search `carlos-flow` → Install, then fill in the environment variables on the plugin settings page
|
|
132
|
+
(equivalent to the repo's `.env.example`).
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
# or from source
|
|
136
|
+
cp .env.example .env # edit: CARLOS_FLOW_MCP_ROOT, CARLOS_FLOW_HOME
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### 3. Set the environment variables
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# 把下面两行换成你自己的实际路径
|
|
143
|
+
CARLOS_FLOW_MCP_ROOT=/opt/carlos-flow-cindy # Windows 例:D:/apps/carlos-flow-cindy
|
|
144
|
+
CARLOS_FLOW_HOME=~/.carlos-flow # Windows 例:C:/Users/<你的用户名>/.carlos-flow
|
|
145
|
+
BRIDGE_PORT=19099
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### 4. Restart and verify
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
# ask Cindy “走门禁”, or verify via the CLI
|
|
152
|
+
node client/carlos.js flow_status '{"sessionId":"probe"}'
|
|
153
|
+
```
|
|
154
|
+
> Expected output contains `has_card: false`, which means the service is alive.
|
|
155
|
+
|
|
156
|
+
> 📁 On first run a state directory is created under `CARLOS_FLOW_HOME` (default `~/.carlos-flow`),
|
|
157
|
+
> holding the **audit log** and **file snapshots**. **Do not delete it manually** — that would break the audit chain.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
## 🌟 Core capabilities
|
|
161
|
+
#### 🆕 Smart trigger engine — `src/trigger.js`
|
|
162
|
+
> **Decision → judgment → activation**, end to end: decides *before* the workflow starts whether this is the moment to run the gate, then turns that verdict into **real gate actions**.
|
|
163
|
+
|
|
164
|
+
##### 🔁 Decision & activation flow
|
|
165
|
+
```mermaid
|
|
166
|
+
flowchart LR
|
|
167
|
+
U[User input] --> L1{"L1 dynamic cap<br/>still allowed?"}
|
|
168
|
+
L1 -->|"throttled"| T["throttled<br/>reports the real score<br/>takes no action"]
|
|
169
|
+
L1 -->|"allowed"| L2{"L2 three-axis score<br/>keyword + context + intent"}
|
|
170
|
+
L2 -->|"< 10"| I["ignore"]
|
|
171
|
+
L2 -->|"10 ~ 15"| R["review<br/>suggest manual start"]
|
|
172
|
+
L2 -->|"≥ 15"| L3{"≥ 25 and<br/>confidence ≥ 0.8?"}
|
|
173
|
+
L3 -->|"no"| M["manual<br/>advice only<br/>no auto execution"]
|
|
174
|
+
L3 -->|"yes"| A["✅ activated"]
|
|
175
|
+
A --> A1["flow_add_user_msg<br/>record the user text"]
|
|
176
|
+
A1 --> A2["flow_submit_requirement<br/>submit a read_only placeholder card"]
|
|
177
|
+
A2 --> G{"Gate<br/>scope / acceptance / verify.cmd<br/>filled in?"}
|
|
178
|
+
G -->|"not yet"| B["flow_claim / flow_dispatch<br/>refuse to dispatch"]
|
|
179
|
+
G -->|"yes"| C["normal dispatch<br/>executor → auditor"]
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
##### What activation actually does (it is not just a log line)
|
|
183
|
+
| Stage | Action | Effect |
|
|
184
|
+
|-------|--------|--------|
|
|
185
|
+
| **Judgment** | L1 cap → L2 scoring → L3 four-way decision | Produces `decision` + `score` + `confidence` + `breakdown` |
|
|
186
|
+
| **Translation** | `buildActivationPlan()` | Turns the verdict into an **executable MCP action sequence** |
|
|
187
|
+
| **Activation ①** | `flow_add_user_msg` | The user's own words become the anchor source for the card's `quote` |
|
|
188
|
+
| **Activation ②** | `flow_submit_requirement` (`activation: true`) | Submits a `read_only` placeholder card — the session **enters the gated state** |
|
|
189
|
+
| **Gate** | `activation_pending` | Until `scope` / `acceptance` / `verify.cmd` are filled in, `flow_claim`, `flow_dispatch` and `flow_verdict` all **refuse** (no "PASS without ever running it") |
|
|
190
|
+
| **Release** | Resubmit the complete card | `activation_pending` clears → normal dispatch proceeds |
|
|
191
|
+
|
|
192
|
+
> Safety constraint: when the session **already has a card**, auto-activation skips card creation (it never overwrites an existing task). Auto-activation only handles "record + enter the gate" — it **never decides which files may change** on the agent's behalf.
|
|
193
|
+
|
|
194
|
+
##### Code usage
|
|
195
|
+
```javascript
|
|
196
|
+
import TriggerEngine from './src/trigger.js';
|
|
197
|
+
|
|
198
|
+
const engine = TriggerEngine.create('session-123');
|
|
199
|
+
const result = engine.shouldTrigger('run dispatch workflow', { complexity: 1.2 });
|
|
200
|
+
|
|
201
|
+
// {
|
|
202
|
+
// shouldTrigger: true,
|
|
203
|
+
// decision: 'trigger', // trigger | review | ignore | throttled
|
|
204
|
+
// score: 38, // weighted total, 0~38
|
|
205
|
+
// confidence: 0.9,
|
|
206
|
+
// breakdown: { keyword: {...}, context: {...}, intent: {...} },
|
|
207
|
+
// action: { type: 'workflow_trigger', recommendedAction: 'auto' },
|
|
208
|
+
// activationPlan: { // ← the verdict translated into actions
|
|
209
|
+
// activated: true,
|
|
210
|
+
// steps: [
|
|
211
|
+
// { tool: 'flow_add_user_msg', auto: true },
|
|
212
|
+
// { tool: 'flow_submit_requirement', auto: true },
|
|
213
|
+
// { tool: 'flow_submit_requirement', auto: false, needsFill: ['scope','acceptance','verify.cmd'] }
|
|
214
|
+
// ],
|
|
215
|
+
// pendingFields: ['scope', 'acceptance', 'verify.cmd'],
|
|
216
|
+
// prompt: '【Carlos 触发引擎已激活工作流】…'
|
|
217
|
+
// }
|
|
218
|
+
// }
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
##### One-line activation from the CLI
|
|
222
|
+
```bash
|
|
223
|
+
# pass the real user text via triggerMessage (or the CARLOS_TRIGGER_MESSAGE env var)
|
|
224
|
+
node client/carlos.js flow_status '{"sessionId":"my-task","triggerMessage":"run dispatch workflow"}'
|
|
225
|
+
```
|
|
226
|
+
> ⚠️ `triggerMessage` **must be passed explicitly** — without it automatic triggering is **entirely off**.
|
|
227
|
+
> Chinese workflow words are built in (工作流 / 门禁 / 派发 / 审计 / 复核 / 任务卡 …),
|
|
228
|
+
> so Chinese requests trigger too; override the vocabulary via
|
|
229
|
+
> `CARLOS_FLOW_HOME/trigger-config.json` (`keywordWeights`).
|
|
230
|
+
|
|
231
|
+
##### MCP tool triggering (path ①)
|
|
232
|
+
```jsonc
|
|
233
|
+
// Call from any MCP host; it actually activates when the message qualifies
|
|
234
|
+
{ "name": "flow_trigger_check",
|
|
235
|
+
"arguments": { "sessionId": "my-task", "message": "走门禁流程,执行 dispatch 任务" } }
|
|
236
|
+
// → { "decision": "trigger", "score": 34, "activated": true, "has_card": true,
|
|
237
|
+
// "activation_pending": ["scope", "acceptance", "verify.cmd"] }
|
|
238
|
+
```
|
|
239
|
+
> Pass `execute: false` to score only, without taking any action.
|
|
240
|
+
|
|
241
|
+
##### Custom trigger vocabulary (optional)
|
|
242
|
+
**Chinese and English workflow words are built in** and work out of the box — Chinese requests
|
|
243
|
+
("走门禁流程", "执行工作流") trigger normally, while ordinary development requests
|
|
244
|
+
("给接口加个参数校验") do **not** misfire.
|
|
245
|
+
|
|
246
|
+
To add your own words, edit `CARLOS_FLOW_HOME/trigger-config.json` (default `~/.carlos-flow/trigger-config.json`):
|
|
247
|
+
|
|
248
|
+
```jsonc
|
|
249
|
+
{
|
|
250
|
+
// Merged / overrides same-name entries — the default vocabulary (incl. built-in Chinese) is **kept**
|
|
251
|
+
"keywordWeights": { "评审": 3, "走查": 3 },
|
|
252
|
+
// Appended, de-duplicated
|
|
253
|
+
"readOnlyIntentWords": ["讲一下"],
|
|
254
|
+
"mutatingActionWords": ["改造一下"]
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
> 📌 Merge semantics: **append, not replace**. Just write the entries you care about — no need to copy the whole default table.
|
|
259
|
+
> Restart the host (MCP server / plugin) after editing for the config to be re-read.
|
|
260
|
+
> Ready-made templates ship with the package: `trigger-config.usable.json` (drop-in) and `trigger-config.example.json` (documented).
|
|
261
|
+
|
|
262
|
+
> **Cindy edition note**: the Cindy plugin is a `kind: "mcp"` package (a pure MCP tool set) — the host exposes no message-event hook,
|
|
263
|
+
> so there is no "evaluate on every message" plugin here.
|
|
264
|
+
> Use path ① (the agent calls `flow_trigger_check`) or path ② (the CLI) — the gate constraints
|
|
265
|
+
> themselves (scope enforcement / real verification / rejected fake PASS) are identical either way.
|
|
266
|
+
##### Engine highlights
|
|
267
|
+
- **L1 dynamic cap** — `5 + sessionHours×0.5 + complexity×2 − triggersInWindow×0.3`, capped at 15
|
|
268
|
+
- **L2 trigger scoring** — keywords (0–50, weight 0.5) + context (0–30, weight 0.3) + intent (0–20, weight 0.2), weighted maximum **38**
|
|
269
|
+
- **L3 decision engine** — four outcomes: `trigger` / `review` (borderline, needs confirmation) / `ignore` (below 10) / `throttled` (rate-limited)
|
|
270
|
+
- **Per-session isolation** — trigger history and throttling state are stored **per session file**, so sessions never throttle each other
|
|
271
|
+
- **Tunable thresholds** — `triggerThreshold: 15`, `autoTriggerThreshold: 25`, `lowConfidenceThreshold: 10`
|
|
272
|
+
- **Zero external dependencies** — plain JavaScript, no new npm packages
|
|
273
|
+
- **Learns from feedback** — records accepted / rejected triggers (persisted); when negative feedback dominates, the **trigger threshold is raised automatically**
|
|
274
|
+
|
|
275
|
+
> Full configuration and usage: [TRIGGER_GUIDE.md](TRIGGER_GUIDE.md)
|
|
276
|
+
|
|
277
|
+
### 1️⃣ Real verification — `flow_run_verify`
|
|
278
|
+
```typescript
|
|
279
|
+
const result = await runVerifyCommand(card.verify.cmd, cwd);
|
|
280
|
+
// { ok: boolean, exitCode: number, stdout: string, stderr: string, durationMs: number }
|
|
281
|
+
```
|
|
282
|
+
Actually spawns the command. Captures full output. 60-second circuit breaker. No "trust me, it passed."
|
|
283
|
+
### 2️⃣ Scope enforcement — `flow_check_scope`
|
|
284
|
+
```typescript
|
|
285
|
+
const result = enforceScope(scopeWhitelist, changedFiles);
|
|
286
|
+
// { ok: boolean, violations: string[] }
|
|
287
|
+
```
|
|
288
|
+
Machine-level comparison of the working tree against the card's whitelist. File-level precision, zero false positives on unchanged files.
|
|
289
|
+
### 3️⃣ Tamper-proof audit chain — `verifyAuditChain`
|
|
290
|
+
```typescript
|
|
291
|
+
const result = verifyAuditChain({ sinceIndex: 0 });
|
|
292
|
+
// { ok: boolean, brokenAt?: number, detail?: string }
|
|
293
|
+
```
|
|
294
|
+
Every record carries `prevHash`, `hash` and `seq`. A single edited byte invalidates everything downstream — mathematically, not administratively.
|
|
295
|
+
### 4️⃣ Controlled bypass — `flow_bypass` + `isBypassed()`
|
|
296
|
+
- Must be explicitly enabled (`bypass=true` **and** `confirmed=true`)
|
|
297
|
+
- Auto-resets on every dispatch — you cannot "forget to turn it off"
|
|
298
|
+
- Every toggle is written to the audit chain
|
|
299
|
+
### 5️⃣ Honest dispatch budget — `dispatch_count`
|
|
300
|
+
- Increments **only** in `flow_dispatch`; `flow_claim` / `flow_verdict` never count
|
|
301
|
+
- Quota exhaustion blocks **both** claim and dispatch
|
|
302
|
+
- No infinite-retry path
|
|
303
|
+
### 6️⃣ Snapshot & restore — `flow_dispatch` → `flow_revert_plan`
|
|
304
|
+
- Files in `scope` are snapshotted automatically before each dispatch
|
|
305
|
+
- `flow_revert_plan` emits an atomic, ordered restore plan (newest first)
|
|
306
|
+
- Partial rollback supported
|
|
307
|
+
### 7️⃣ Independent review — `auditor` role
|
|
308
|
+
- Separate four-part contract with an evidence-gathering mandate
|
|
309
|
+
- Auditor must run `git status --porcelain` / `git diff` itself
|
|
310
|
+
- Verdict enum is strict: `PASS` / `DIRECTION` / `LOCAL`
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
## 📖 Use cases
|
|
314
|
+
### Scenario 1 — New feature development
|
|
315
|
+
```mermaid
|
|
316
|
+
flowchart LR
|
|
317
|
+
A[Requirement] --> B[Submit card]
|
|
318
|
+
B --> C[Dispatch Executor]
|
|
319
|
+
C --> D[Implement]
|
|
320
|
+
D --> E[Save result]
|
|
321
|
+
E --> F[Real verify]
|
|
322
|
+
F --> G[Scope check]
|
|
323
|
+
G --> H[Dispatch Auditor]
|
|
324
|
+
H --> I[Independent review]
|
|
325
|
+
I --> J[Verdict PASS]
|
|
326
|
+
```
|
|
327
|
+
### Scenario 2 — Bug fix
|
|
328
|
+
- Card `quote` is anchored to the user's original words — the agent cannot silently redefine the request
|
|
329
|
+
- `scope` narrowed to the single file
|
|
330
|
+
- `verify.cmd` runs the regression test, not a hand-written summary
|
|
331
|
+
### Scenario 3 — Large refactor
|
|
332
|
+
- Multi-file `scope` managed as one whitelist
|
|
333
|
+
- Snapshots protect against a half-finished refactor
|
|
334
|
+
- Restore plan is the safety net
|
|
335
|
+
### Scenario 4 — Security audit / sensitive paths
|
|
336
|
+
- T2 risk tier requires explicit `confirmed=true`
|
|
337
|
+
- Sensitive paths (`config/`, `secrets/`, `infra/`, …) are flagged and gated
|
|
338
|
+
- Audit chain provides tamper-evident evidence trail
|
|
339
|
+
### Scenario 5 — CI / PR gating
|
|
340
|
+
- Same flow, driven from CI
|
|
341
|
+
- Verdict can block a merge
|
|
342
|
+
- Audit log archived for compliance
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
## 🏗️ Architecture
|
|
346
|
+
```mermaid
|
|
347
|
+
flowchart TB
|
|
348
|
+
subgraph Cindy["Cindy App"]
|
|
349
|
+
UI[Plugin settings] --> ENV[Encrypted env vault]
|
|
350
|
+
ENV --> BR[Bridge daemon]
|
|
351
|
+
end
|
|
352
|
+
subgraph Server["MCP Server (src/)"]
|
|
353
|
+
T[14 tools] --> C[Card parse & validate]
|
|
354
|
+
C --> S[State & audit chain]
|
|
355
|
+
S --> D[Dispatch / snapshot / verify]
|
|
356
|
+
end
|
|
357
|
+
BR <-- "TCP 127.0.0.1:19099 · token · rate-limited" --> Server
|
|
358
|
+
CLI[CLI client] --> BR
|
|
359
|
+
REA[rea MCP] -. optional .-> BR
|
|
360
|
+
```
|
|
361
|
+
### Why a Bridge in the Cindy edition?
|
|
362
|
+
| | Cindy edition (this repo) | OpenCode edition |
|
|
363
|
+
|---|---|---|
|
|
364
|
+
| Transport | TCP Bridge on `127.0.0.1:19099` | Pure stdio |
|
|
365
|
+
| Daemon lifecycle | **Automatic** — launched on first call, health-checked | Managed by OpenCode |
|
|
366
|
+
| Configuration | Plugin settings page + env vars | `.mcprc` / `opencode.json` |
|
|
367
|
+
| Secret storage | **Cindy encrypted vault** — no plaintext in code | Plaintext config (user-managed) |
|
|
368
|
+
| rea integration | Built-in `client/rea.js` | Register a second MCP server |
|
|
369
|
+
| Best for | Cindy App users | OpenCode 2.2.2+ users |
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
## 🛠️ The 15 tools
|
|
373
|
+
### 📝 Card & record
|
|
374
|
+
| Tool | Purpose | Key params |
|
|
375
|
+
|------|---------|------------|
|
|
376
|
+
| `flow_protocol` | Read the full protocol (tiers T0/T1/T2, contracts, error layers, state schema) | — |
|
|
377
|
+
| `flow_add_user_msg` | Record the user's original words (anchor source) | `sessionId`, `text` |
|
|
378
|
+
| `flow_submit_requirement` | Submit the task card (validate + record) | `goal`, `quote`, `scope`, `acceptance`, `confirmed` |
|
|
379
|
+
### 🚀 Dispatch & execution
|
|
380
|
+
| Tool | Purpose | Key params |
|
|
381
|
+
|------|---------|------------|
|
|
382
|
+
| `flow_claim` | Claim a dispatch slot, get the four-part contract | `sessionId`, `role` (`executor`\|`auditor`) |
|
|
383
|
+
| `flow_dispatch` | Generate the contract prompt + automatic file snapshot | `sessionId`, `role`, `message`, `run?` |
|
|
384
|
+
| `flow_run_verify` | **Really execute `verify.cmd`** | `sessionId` |
|
|
385
|
+
| `flow_check_scope` | **Machine-level scope enforcement** | `sessionId`, `paths[]` |
|
|
386
|
+
### ⚖️ Verdict & status
|
|
387
|
+
| Tool | Purpose | Key params |
|
|
388
|
+
|------|---------|------------|
|
|
389
|
+
| `flow_verdict` | Record the verdict (`PASS`/`DIRECTION`/`LOCAL`) | `sessionId`, `verdict`, `notes` |
|
|
390
|
+
| `flow_status` | Query the full gate state | `sessionId` |
|
|
391
|
+
### 🔍 Audit & forensics
|
|
392
|
+
| Tool | Purpose | Key params |
|
|
393
|
+
|------|---------|------------|
|
|
394
|
+
| `flow_audit` | Read the audit trail (filter by type/time/session) | `sessionId`, `type?`, `since?` |
|
|
395
|
+
| `flow_diff_hunks` | git diff hunk-level analysis | `sessionId`, `scope?` |
|
|
396
|
+
| `flow_revert_plan` | Generate the atomic restore plan | `sessionId` |
|
|
397
|
+
### 🛡️ Bypass & restore
|
|
398
|
+
| Tool | Purpose | Key params |
|
|
399
|
+
|------|---------|------------|
|
|
400
|
+
| `flow_bypass` | Bypass switch (requires `confirmed`) | `sessionId`, `bypass`, `confirmed` |
|
|
401
|
+
> Full tool reference: call `flow_protocol` at runtime — it is the authoritative, machine-readable spec.
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
## ⚙️ Environment variables
|
|
405
|
+
| Variable | Required | Description | Example |
|
|
406
|
+
|----------|----------|-------------|---------|
|
|
407
|
+
| `CARLOS_FLOW_MCP_ROOT` | ✅ | MCP source root (contains `src/` `bridge/` `client/`) | `/opt/carlos-flow-cindy` |
|
|
408
|
+
| `CARLOS_FLOW_HOME` | ✅ | State / audit / snapshot root | `~/carlos-flow` |
|
|
409
|
+
| `BRIDGE_PORT` | ❌ | Bridge listen port (default `19099`) | `19099` |
|
|
410
|
+
| `REA_MCP_ROOT` | ❌ | rea MCP source root | `/opt/rea` |
|
|
411
|
+
| `GHIDRA_HOME` | ❌ | Ghidra install dir | `/opt/ghidra_12.1.4_PUBLIC` |
|
|
412
|
+
| `JAVA_HOME` | ❌ | JDK 21 install dir | `/usr/lib/jvm/java-21-openjdk` |
|
|
413
|
+
| `NODE_PATH` | ❌ | Node.js executable path (default `node`) | `node` |
|
|
414
|
+
> **Tip**: changes made on the Cindy plugin settings page require a **full Cindy restart** to take effect.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
## 🧪 Testing
|
|
418
|
+
```bash
|
|
419
|
+
npm test # smoke test — isolated temp dir, < 10s
|
|
420
|
+
npm run test:e2e # 16-case end-to-end suite
|
|
421
|
+
npm run test:p0 # 10-case gate suite (role whitelist / scope / bypass confirmation …)
|
|
422
|
+
npm run test:trigger # 25-case trigger engine suite (incl. 10 regression cases)
|
|
423
|
+
npm run test:all # all four suites chained
|
|
424
|
+
```
|
|
425
|
+
> No environment setup needed locally (the suites fall back to the repo root automatically). CI runs all four suites on **ubuntu-latest** and **windows-latest** for every push and pull request.
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
## 📋 Changelog
|
|
429
|
+
Full history → [CHANGELOG.md](CHANGELOG.md)
|
|
430
|
+
### v2.5.5 — 2026-11-05 · Smart trigger engine + 7 real defects fixed
|
|
431
|
+
| Type | Change |
|
|
432
|
+
|------|--------|
|
|
433
|
+
| ✨ New | Smart trigger engine (`src/trigger.js`): L1 dynamic cap / L2 three-axis scoring / L3 four-way decision |
|
|
434
|
+
| ✨ New | `TRIGGER_GUIDE.md` complete usage guide (config, scoring formula, troubleshooting) |
|
|
435
|
+
| ✨ New | `test/trigger-e2e.mjs` — 25 cases incl. 10 regression cases; `npm run test:all` chains all five suites |
|
|
436
|
+
| ✨ New | `scripts/release.mjs` release script + `npm run check:readme` bilingual consistency hook |
|
|
437
|
+
| ✨ New | `docs/QA_REPORT_v2.5.5.md` independent QA acceptance report (5 suites green) |
|
|
438
|
+
| 🐛 Fixed | Trigger engine silently swallowed by `require()` in the ESM client → dynamic `import()` |
|
|
439
|
+
| 🐛 Fixed | Trigger cap compared a 0–1 average against 5–15 → never fired → now uses the raw count |
|
|
440
|
+
| 🐛 Fixed | History factor in the dynamic cap was additive (more triggers → higher cap) → now a penalty |
|
|
441
|
+
| 🐛 Fixed | `processUserMessage()` hard-coded the session id → now passed through from context |
|
|
442
|
+
| 🐛 Fixed | Trigger CLI entry never matched because of the `file:///` prefix → `fileURLToPath()` |
|
|
443
|
+
| 🐛 Fixed | Score collapsed to 0 and confidence was lost while throttled → now reported honestly |
|
|
444
|
+
| 🐛 Fixed | Test result file written into the publish directory → now the system temp directory |
|
|
445
|
+
| 🔒 Security | `.gitignore` collision meant the npm-token-bearing `.npmrc.local` was never ignored → split rules |
|
|
446
|
+
| 🔒 Security | Trigger state written to the CWD → unified under `CARLOS_FLOW_HOME` |
|
|
447
|
+
| 🔒 Security | Hard-coded machine path → cross-platform `~/.carlos-flow` default |
|
|
448
|
+
| 🧹 Cleanup | 42 one-off fix scripts and scratch files removed (net −5325 lines) |
|
|
449
|
+
| 🔑 Release | GitHub Actions OIDC publishing — no npm token in the repo any more |
|
|
450
|
+
| 📚 Docs | Removed README language-bar / version-line noise (24–26 per file → 1 at the top) |
|
|
451
|
+
|
|
452
|
+
### v2.5.3 — 2026-11-04 · Fatal syntax fixes + verified gates
|
|
453
|
+
| Type | Change |
|
|
454
|
+
|------|--------|
|
|
455
|
+
| ✨ New tools | `flow_run_verify`, `flow_check_scope` |
|
|
456
|
+
| ✨ Core | `runVerifyCommand()` really executes `verify.cmd` |
|
|
457
|
+
| ✨ Core | `enforceScope()` machine-level scope enforcement |
|
|
458
|
+
| ✨ Core | `verifyAuditChain()` SHA-256 audit-chain validation |
|
|
459
|
+
| ✨ Core | `isBypassed()` real bypass semantics |
|
|
460
|
+
| 🐛 Fixed | role whitelist (only `executor`/`auditor`; typos now error) |
|
|
461
|
+
| 🐛 Fixed | `dispatch_count` increments on dispatch only |
|
|
462
|
+
| 🐛 Fixed | bypass auto-resets on new dispatch |
|
|
463
|
+
| 🐛 Fixed | stale-card / quota / verdict-enum / param validation |
|
|
464
|
+
> ⚠️ **v2.5.1 contained 18 P0 defects.** Upgrade to **v2.5.2 or later**.
|
|
465
|
+
|
|
466
|
+
---
|
|
467
|
+
## ❓ FAQ
|
|
468
|
+
| Symptom | Fix |
|
|
469
|
+
|---------|-----|
|
|
470
|
+
| Bridge port conflict (`EADDRINUSE`) | Change `BRIDGE_PORT`, or `lsof -ti:19099 \| xargs kill` |
|
|
471
|
+
| Plugin settings changes have no effect | **Fully quit Cindy and restart** (not minimize-to-tray) |
|
|
472
|
+
| Audit chain validation fails | Check `CARLOS_FLOW_HOME` permissions, or delete `audit/` and let it rebuild |
|
|
473
|
+
| Verification command times out | `verify.cmd` is killed after 60s — split it into fast commands |
|
|
474
|
+
| Scope violation false positive | Use relative paths in `scope`; `git diff --name-only` must match |
|
|
475
|
+
| The trigger engine never fires | Check whether your input hits the `keywordWeights` vocabulary; the default list is English, so extend it for other languages |
|
|
476
|
+
| The trigger engine fires too often | Raise `triggerThreshold`, increase `minTriggerIntervalSeconds`, or lower `historyCoeff` |
|
|
477
|
+
| Where do trigger state files live? | Under `CARLOS_FLOW_HOME` (default `~/.carlos-flow`) — never in the current working directory |
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
## 📄 License
|
|
481
|
+
MIT — see [LICENSE](LICENSE)
|
|
482
|
+
|
|
483
|
+
---
|
|
484
|
+
## 🤝 Contributing
|
|
485
|
+
PRs welcome! Please make sure `npm test` and `npm run test:e2e` pass first. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
486
|
+
|
|
487
|
+
---
|
|
488
|
+
**Using OpenCode instead?** → [carlos-flow-opencode](https://github.com/skyer-now/carlos-flow-opencode) — pure stdio, no Bridge, configured via `.mcprc` / `opencode.json`.
|