carlos-flow 2.5.9 → 2.6.1
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 +184 -90
- package/MIGRATION.md +245 -0
- package/README.en.md +461 -476
- package/README.md +388 -138
- package/README.zh.md +388 -138
- package/TRIGGER_GUIDE.md +745 -554
- package/bridge/mcp-bridge.js +7 -1
- package/client/carlos.js +9 -2
- package/ghost.json +1 -1
- package/package.json +4 -2
- package/scripts/check-repo-parity.mjs +198 -253
- package/src/index.js +12 -2
package/README.en.md
CHANGED
|
@@ -1,488 +1,473 @@
|
|
|
1
|
-
# Carlos Flow
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
49
|
-
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
1
|
+
# Carlos Flow
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/carlos-flow)
|
|
4
|
+
[](https://www.npmjs.com/package/carlos-flow)
|
|
5
|
+
[](https://nodejs.org)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
7
|
+
[](./LICENSE)
|
|
8
|
+
[](./.github/workflows/ci.yml)
|
|
9
|
+
|
|
10
|
+
**Languages:** [中文](README.zh.md) | [English](README.en.md)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
> **Mechanical Gate for AI Coding Agents**
|
|
15
|
+
>
|
|
16
|
+
> Trace → Dispatch → Verify → Verdict → Audit → Revert
|
|
17
|
+
>
|
|
18
|
+
> Turn "trust the Agent" into "**verify** the Agent" — constraints live in code, not in prompts.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 📌 What is this (TL;DR)
|
|
23
|
+
|
|
24
|
+
Carlos Flow is an **MCP Server** that gives AI coding agents an **executable, auditable, self-deception-proof** workflow gate.
|
|
25
|
+
|
|
26
|
+
The problem with ordinary agent workflows: every constraint is **advisory**.
|
|
27
|
+
|
|
28
|
+
| You say | What the agent actually does |
|
|
29
|
+
|---------|-----------------------------|
|
|
30
|
+
| "Only edit `src/auth.py`" | Nods politely, then rewrites half the repo |
|
|
31
|
+
| "Run the tests" | Reports "tests passed" — never ran them |
|
|
32
|
+
| "Document the process" | Writes a few lines in a plain file — deletable, editable |
|
|
33
|
+
|
|
34
|
+
Carlos Flow takes the opposite approach: **every constraint is enforced at runtime against facts, never against self-report.**
|
|
35
|
+
|
|
36
|
+
- Out of scope? → Runtime `git diff` against the card whitelist, **blocks dispatch**
|
|
37
|
+
- Claims tests passed? → Really `spawn`s `verify.cmd`; **PASS requires a passing exitCode**
|
|
38
|
+
- Audit log? → SHA-256 **chained hashes** (`prevHash` → `hash`); **change one and the chain breaks**
|
|
39
|
+
- Want to skip? → Bypass needs explicit `confirmed=true`, and **auto-clears on every dispatch**
|
|
40
|
+
|
|
41
|
+
**In one line**: it brings code-review gates to AI agents — and the gates are executed by machines, not humans.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 🎯 8 Real Problems It Solves
|
|
46
|
+
|
|
47
|
+
| # | Problem | Status quo | Carlos Flow's mechanical answer |
|
|
48
|
+
|---|---------|------------|-------------------------------|
|
|
49
|
+
| 1 | **Out-of-scope edits** | "Only these files" is advice, not a rule | `enforceScope()` compares `git diff` to the whitelist at runtime — out-of-scope **blocks dispatch** |
|
|
50
|
+
| 2 | **Verification theater** | Agent self-reports "tests passed"; no proof | `runVerifyCommand()` really executes, capturing stdout/stderr/exitCode; **no evidence → no PASS** |
|
|
51
|
+
| 3 | **Mutable audit logs** | Plain files — deletable, editable | SHA-256 chained hashes — **change one and the whole chain breaks** |
|
|
52
|
+
| 4 | **Uncontrolled bypass** | One sentence disables all guards | Requires explicit `confirmed=true` on the card; **auto-cleared on every dispatch** |
|
|
53
|
+
| 5 | **Unlimited dispatch** | Claim resets the counter; infinite retries | `dispatch_count` increments only on dispatch; exhaustion blocks both claim and dispatch |
|
|
54
|
+
| 6 | **Self-certified review** | Same agent implements and approves | Built-in `auditor` role + independent contract, strict three-tier verdict |
|
|
55
|
+
| 7 | **No rollback after damage** | Manual `git revert` only | Auto-snapshot before dispatch → `flow_revert_plan` produces an atomic restore plan |
|
|
56
|
+
| 8 | **Manual trigger every time** | No shout = no gate; forget = naked run | **Smart Trigger Engine** auto-detects intent, triggers on score, and explains what matched |
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## ✨ Highlights
|
|
61
|
+
|
|
62
|
+
### 1. Zero-fork, cross-platform architecture
|
|
63
|
+
One core MCP Server, **6 platforms** out of the box. Platform differences live only in init templates; core logic has **zero forks**.
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
carlos-flow (single npm package)
|
|
67
|
+
├── src/index.js ← Core MCP Server (pure standard protocol, zero platform coupling)
|
|
68
|
+
├── client/carlos.js ← CLI + init --target <platform>
|
|
69
|
+
├── bridge/ ← Cindy only: resident Bridge daemon
|
|
70
|
+
├── plugins/ ← OpenCode only: chat.message hook
|
|
71
|
+
└── templates/ ← Cursor / Cline / VS Code / Claude templates
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### 2. Smart Trigger Engine — the workflow knows when to show up
|
|
75
|
+
Three layers, and **every decision comes with an explainable breakdown** (which words matched, what score, why).
|
|
76
|
+
|
|
77
|
+
- **L1 Dynamic limit**: `5 + session_hours×0.5 + complexity×2 − window_triggers×0.3`, capped at 15
|
|
78
|
+
- **L2 3-D scoring**: keywords 50 / context 30 / intent 20, weighted max 38
|
|
79
|
+
- **L3 4-tier decision**: `trigger` / `review` / `ignore` / `throttled`
|
|
80
|
+
|
|
81
|
+
Chinese workflow terms are **built in** (工作流/门禁/派发/审计/任务卡/子代理…) while ordinary dev requests **never false-trigger**.
|
|
82
|
+
|
|
83
|
+
### 3. Anti-self-deception activation gate
|
|
84
|
+
Auto-trigger **does not** mean "open the gates". After activation the session enters `activation_pending`:
|
|
85
|
+
until `scope` / `acceptance` / `verify.cmd` are filled in, `flow_claim` / `flow_dispatch` / `flow_verdict` are **all rejected**.
|
|
86
|
+
|
|
87
|
+
> What this prevents: placeholder card → dispatch → record PASS → fake closed loop.
|
|
88
|
+
|
|
89
|
+
### 4. Fail-closed semantics
|
|
90
|
+
An empty `scope` means **everything is out of scope** (not "empty whitelist = change anything"). That's the safe default, not the convenient one.
|
|
91
|
+
|
|
92
|
+
### 5. Mutation-tested guards
|
|
93
|
+
13 mutation classes (deliberate regressions) are **13/13 caught** by the test suite. Anchor uniqueness is guarded by `npm run check:anchors`, so tests can never *silently* lose their guarding power.
|
|
94
|
+
|
|
95
|
+
### 6. Cross-process concurrency safety
|
|
96
|
+
The read-modify-write in `flow_submit_requirement` is wrapped in a **cross-process exclusive lock** (`mkdir` atomicity).
|
|
97
|
+
A red-team run reproduced 4 state losses in 40 concurrent rounds; now it reports **0 leaks out of 453**.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 🏗️ Technical Architecture
|
|
102
|
+
|
|
103
|
+
### Overview
|
|
104
|
+
|
|
105
|
+
```mermaid
|
|
106
|
+
flowchart TB
|
|
107
|
+
subgraph Host["Host Agent Platform"]
|
|
108
|
+
Cindy[Cindy<br/>ghost.json]
|
|
109
|
+
OpenCode[OpenCode<br/>plugin + .mcprc]
|
|
110
|
+
Cursor[Cursor / Cline<br/>VS Code / Claude]
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
subgraph Client["Client Layer"]
|
|
114
|
+
CLI["client/carlos.js<br/>CLI + init + trigger check"]
|
|
115
|
+
Bridge["bridge/mcp-bridge.js<br/>resident daemon + token auth"]
|
|
116
|
+
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message hook"]
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
subgraph Core["Core MCP Server (src/index.js) — 15 tools"]
|
|
120
|
+
Protocol["flow_protocol"]
|
|
121
|
+
Submit["flow_submit_requirement"]
|
|
122
|
+
Dispatch["flow_claim / flow_dispatch"]
|
|
123
|
+
Verify["flow_run_verify / flow_check_scope"]
|
|
124
|
+
Verdict["flow_verdict"]
|
|
125
|
+
Audit["flow_status / flow_audit"]
|
|
126
|
+
Trigger["flow_trigger_check"]
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
subgraph Engine["Smart Trigger Engine (src/trigger.js)"]
|
|
130
|
+
L1["L1 DynamicTriggerManager"]
|
|
131
|
+
L2["L2 TriggerScorer"]
|
|
132
|
+
L3["L3 TriggerDecisionEngine"]
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
subgraph Storage["Persistence (CARLOS_FLOW_HOME)"]
|
|
136
|
+
State["gate-state/runs/<sid>/"]
|
|
137
|
+
AuditLog["gate-audit/YYYY-MM-DD.jsonl<br/>SHA-256 chained"]
|
|
138
|
+
Snap["snapshots/"]
|
|
139
|
+
TrigState["trigger-state/"]
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
Cindy --> CLI
|
|
143
|
+
OpenCode --> Plugin
|
|
144
|
+
Cursor --> CLI
|
|
145
|
+
Plugin --> Trigger
|
|
146
|
+
CLI --> Bridge
|
|
147
|
+
Bridge --> Core
|
|
148
|
+
Core --> Engine
|
|
149
|
+
Core --> Storage
|
|
150
|
+
Engine --> TrigState
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Layer Responsibilities
|
|
154
|
+
|
|
155
|
+
| Layer | Location | Responsibility | Platform coupling |
|
|
156
|
+
|-------|----------|----------------|-------------------|
|
|
157
|
+
| **Host adapter** | `ghost.json` / `plugins/` / `templates/` | Discovery, launch, config, lifecycle | ⚠️ The **only** platform-specific layer |
|
|
158
|
+
| **Client** | `client/carlos.js` / `bridge/` | CLI, trigger check, Bridge daemon | Bridge is Cindy-only |
|
|
159
|
+
| **Protocol** | `src/index.js` | 15 MCP tools + validation + gate semantics | ✅ Zero coupling, pure standard MCP |
|
|
160
|
+
| **Engine** | `src/trigger.js` / `src/card.js` / `src/state.js` | Trigger scoring, card validation, state/audit | ✅ Zero coupling, pure JS, no deps |
|
|
161
|
+
| **Persistence** | `~/.carlos-flow/` | State, audit chain, snapshots, trigger history | ✅ Cross-platform path convention |
|
|
162
|
+
|
|
163
|
+
> **Core design principle**: the MCP protocol is **passive** — a server cannot push.
|
|
164
|
+
> Therefore "auto-trigger" must be initiated by **the side that can see the user's message**
|
|
165
|
+
> (a host plugin hook, or the agent calling `flow_trigger_check`).
|
|
166
|
+
> Both paths share the exact same `src/trigger.js` implementation, so **behavior is identical**.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 📊 Capability Matrix
|
|
171
|
+
|
|
172
|
+
| Capability | Carlos Flow | Native MCP Server | Prompts / Scripts |
|
|
173
|
+
|------------|-------------|-------------------|-------------------|
|
|
174
|
+
| Scope enforcement | ✅ Runtime `git diff` | ❌ | ❌ Honor system |
|
|
175
|
+
| Real verification | ✅ spawn + capture; no evidence → no PASS | ❌ | ❌ Agent says so |
|
|
176
|
+
| Tamper-proof audit | ✅ SHA-256 chained hashes | ❌ | ❌ |
|
|
177
|
+
| Controlled bypass | ✅ Explicit + auto-cleared | ❌ | ❌ One sentence kills all |
|
|
178
|
+
| Honest dispatch quota | ✅ Counts only dispatches | ❌ | ❌ |
|
|
179
|
+
| Independent review | ✅ Built-in `auditor` role | ❌ | ❌ Optional |
|
|
180
|
+
| Snapshot + restore | ✅ Auto, atomic plan | ❌ | ❌ Manual `git revert` |
|
|
181
|
+
| Daemon lifecycle | ✅ Fully automatic (Cindy) | ❌ Manual | ❌ Manual |
|
|
182
|
+
| Smart triggering | ✅ 3-layer scoring + explainable decision | ❌ | ❌ |
|
|
183
|
+
| Cross-platform | ✅ Single package, 6 platforms | ⚠️ Write your own config | ❌ |
|
|
184
|
+
|
|
185
|
+
> **Trust boundary**: hand-editing `state.json` to fake a PASS verdict is possible — the state file is not inside the audit hash chain.
|
|
186
|
+
> This is a **local filesystem permission** boundary, not an MCP tool-surface hole: whoever can write
|
|
187
|
+
> `CARLOS_FLOW_HOME` could edit their own code anyway.
|
|
188
|
+
> Full explanation in the [QA Report](./docs/QA_REPORT_v2.5.5.md) §6.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 📦 Installation
|
|
133
193
|
|
|
134
194
|
```bash
|
|
135
|
-
|
|
136
|
-
cp .env.example .env # edit: CARLOS_FLOW_MCP_ROOT, CARLOS_FLOW_HOME
|
|
195
|
+
npm install -g carlos-flow
|
|
137
196
|
```
|
|
138
197
|
|
|
139
|
-
|
|
198
|
+
> ⚠️ `ETARGET: No matching version found`? That's npm's **registry metadata cache** not being refreshed:
|
|
199
|
+
> ```bash
|
|
200
|
+
> npm cache clean --force
|
|
201
|
+
> npm view carlos-flow versions # verify the version exists
|
|
202
|
+
> ```
|
|
203
|
+
|
|
204
|
+
**Requirements**: Node.js ≥ 22.0.0 | MCP SDK ≥ 1.29.0 | Zero runtime external dependencies
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 🖥️ Platform Support
|
|
209
|
+
|
|
210
|
+
One package, six platforms. The init command generates the right config file for each.
|
|
211
|
+
|
|
212
|
+
| Platform | Init command | Generated artifacts | Platform-specific extras |
|
|
213
|
+
|----------|--------------|--------------------|--------------------------|
|
|
214
|
+
| **Cindy** | `carlos-flow init --target cindy` | `~/.cindy/ghosts/carlos-flow.json` | Auto-managed Bridge + Settings UI |
|
|
215
|
+
| **OpenCode** | `carlos-flow init --target opencode` | `~/.config/opencode/plugin/opencode.json`<br/>+ project `.mcprc` | `chat.message` hook auto-trigger |
|
|
216
|
+
| **Cursor / Windsurf** | `carlos-flow init --target cursor` | Project `.cursor/mcp.json` | — |
|
|
217
|
+
| **Cline** | `carlos-flow init --target cline` | Project `.cline/mcp.json` | — |
|
|
218
|
+
| **VS Code (Copilot)** | `carlos-flow init --target vscode` | Project `.vscode/mcp.json` | — |
|
|
219
|
+
| **Claude Desktop** | `carlos-flow init --target claude` | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br/>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | — |
|
|
220
|
+
|
|
221
|
+
> 💡 All platforms share the same config fields: `CARLOS_FLOW_HOME` (state dir) + `node <root>/src/index.js` (stdio launch).
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 🚀 Quick Start
|
|
226
|
+
|
|
227
|
+
### 1. Install and initialize
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
npm install -g carlos-flow
|
|
231
|
+
carlos-flow init --target <your-platform> # cindy | opencode | cursor | cline | vscode | claude
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### 2. Environment variables (optional — all have defaults)
|
|
140
235
|
|
|
141
236
|
```bash
|
|
142
|
-
#
|
|
143
|
-
CARLOS_FLOW_MCP_ROOT=/
|
|
144
|
-
|
|
145
|
-
BRIDGE_PORT=19099
|
|
237
|
+
CARLOS_FLOW_HOME=~/.carlos-flow # state / audit directory (cross-platform)
|
|
238
|
+
CARLOS_FLOW_MCP_ROOT=/path/to/carlos-flow # repo root for source installs
|
|
239
|
+
BRIDGE_PORT=19099 # Cindy Bridge port
|
|
146
240
|
```
|
|
147
241
|
|
|
148
|
-
|
|
242
|
+
> Always use **forward slashes** (`/home/you/apps/carlos-flow`) or **double backslashes**
|
|
243
|
+
> (`D:\\apps\\carlos-flow`). A single backslash is treated as an escape in config files —
|
|
244
|
+
> `\c` and `\o` get eaten and the path silently breaks.
|
|
245
|
+
|
|
246
|
+
### 3. Verify the service is healthy
|
|
149
247
|
|
|
150
248
|
```bash
|
|
151
|
-
# ask Cindy “走门禁”, or verify via the CLI
|
|
152
249
|
node client/carlos.js flow_status '{"sessionId":"probe"}'
|
|
153
250
|
```
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
|
184
|
-
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
-
|
|
272
|
-
-
|
|
273
|
-
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
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`.
|
|
251
|
+
|
|
252
|
+
Expect `"has_card": false`.
|
|
253
|
+
|
|
254
|
+
### 4. Walk through one full gate cycle
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
# ① Trace — record the user's own words (the only quote anchor source)
|
|
258
|
+
node client/carlos.js flow_add_user_msg '{"sessionId":"demo","text":"add parameter validation to the login endpoint"}'
|
|
259
|
+
|
|
260
|
+
# ② Submit the task card (scope is the whitelist)
|
|
261
|
+
node client/carlos.js flow_submit_requirement '{"sessionId":"demo","goal":"add parameter validation","quote":"add parameter validation to the login endpoint","scope":["src/auth.py"],"acceptance":["invalid params return 400"],"verify":{"cmd":"npm test"},"cwd":"/path/to/project"}'
|
|
262
|
+
|
|
263
|
+
# ③ Claim a dispatch slot
|
|
264
|
+
node client/carlos.js flow_claim '{"sessionId":"demo","role":"executor"}'
|
|
265
|
+
|
|
266
|
+
# ④ Dispatch (auto-snapshots files in scope)
|
|
267
|
+
node client/carlos.js flow_dispatch '{"sessionId":"demo","role":"executor"}'
|
|
268
|
+
|
|
269
|
+
# ⑤ Really execute the verification command
|
|
270
|
+
node client/carlos.js flow_run_verify '{"sessionId":"demo","cwd":"/path/to/project"}'
|
|
271
|
+
|
|
272
|
+
# ⑥ Record the verdict (no PASS without passing verification evidence)
|
|
273
|
+
node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes":"tests pass"}'
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## 🔧 MCP Tool Reference (15 tools)
|
|
279
|
+
|
|
280
|
+
| Tool | Purpose | Key constraint |
|
|
281
|
+
|------|---------|----------------|
|
|
282
|
+
| `flow_protocol` | Read the full gate protocol (tiers, four-part contract, error layering) | — |
|
|
283
|
+
| `flow_add_user_msg` | Write the user's original message | **The only quote anchor source** |
|
|
284
|
+
| `flow_submit_requirement` | Submit / replace the task card | Required fields enforced per risk tier; fake fillers rejected |
|
|
285
|
+
| `flow_claim` | Claim a dispatch slot (executor / auditor) | Rejected while the activation gate is open |
|
|
286
|
+
| `flow_dispatch` | Dispatch a sub-agent per the four-part contract | Auto-snapshots files in scope before dispatch |
|
|
287
|
+
| `flow_save_result` | Save a sub-agent's result | — |
|
|
288
|
+
| `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr |
|
|
289
|
+
| `flow_check_scope` | Check whether files are in scope | Empty scope → fail-closed, everything out of scope |
|
|
290
|
+
| `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch; no PASS without passing verification |
|
|
291
|
+
| `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` |
|
|
292
|
+
| `flow_audit` | Read the audit stream | Includes 6 activation-related event kinds |
|
|
293
|
+
| `flow_diff_hunks` | Parse `git diff -U0` hunk ranges | — |
|
|
294
|
+
| `flow_bypass` | Toggle bypass mode | Requires `confirmed=true`; auto-cleared on dispatch |
|
|
295
|
+
| `flow_revert_plan` | Generate an atomic restore plan | Returns a plan only, never executes |
|
|
296
|
+
| `flow_trigger_check` | Smart trigger check | Activates on success; honestly reports score otherwise |
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## ⚙️ Configuration
|
|
301
|
+
|
|
302
|
+
### Trigger config
|
|
303
|
+
|
|
304
|
+
Path: `$CARLOS_FLOW_HOME/trigger-config.json` (auto-generated by `init`)
|
|
305
|
+
|
|
306
|
+
```json
|
|
307
|
+
{
|
|
308
|
+
"keywordWeights": {
|
|
309
|
+
"review": 5
|
|
310
|
+
},
|
|
311
|
+
"readOnlyIntentWords": ["explain to me"],
|
|
312
|
+
"mutatingActionWords": ["refactor it"]
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
**Merge semantics** (important):
|
|
317
|
+
- `keywordWeights` → **object merge** (custom words override same-named defaults; the rest are preserved)
|
|
318
|
+
- Word-list arrays → **appended and de-duplicated** (extension, not replacement)
|
|
319
|
+
- Other scalars → override
|
|
320
|
+
|
|
321
|
+
> The old implementation used a shallow merge — one custom word wiped the entire default table
|
|
322
|
+
> (including the built-in Chinese workflow terms), so Chinese requests scored 0 again. Fixed.
|
|
323
|
+
|
|
324
|
+
### Environment variables
|
|
325
|
+
|
|
326
|
+
| Variable | Default | Purpose |
|
|
327
|
+
|----------|---------|---------|
|
|
328
|
+
| `CARLOS_FLOW_HOME` | `~/.carlos-flow` | State / audit / snapshot directory. `~` is expanded |
|
|
329
|
+
| `CARLOS_FLOW_MCP_ROOT` | auto-derived | Repo root for source installs |
|
|
330
|
+
| `BRIDGE_PORT` | `19099` | Cindy Bridge listening port |
|
|
331
|
+
| `CARLOS_BRIDGE_TOKEN` | built-in default | Local Bridge auth token |
|
|
332
|
+
| `CARLOS_BRIDGE_TIMEOUT_MS` | `180000` | Bridge request timeout (must exceed the server's 120s verify limit) |
|
|
333
|
+
| `CARLOS_MCP_TIMEOUT_MS` | `180000` | CLI client MCP call timeout |
|
|
334
|
+
| `CARLOS_TRIGGER_MESSAGE` | — | Inject the user's original message for CLI trigger checks |
|
|
335
|
+
| `OPENCODE_DB_PATH` | multi-probe | OpenCode session DB path (used to read user utterances) |
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## 🧪 Development
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
git clone https://github.com/skyer-now/carlos-flow.git
|
|
343
|
+
cd carlos-flow
|
|
344
|
+
npm install
|
|
345
|
+
|
|
346
|
+
# Full suite (129 cases)
|
|
347
|
+
npm run test:all
|
|
348
|
+
|
|
349
|
+
# Individual
|
|
350
|
+
npm run test:e2e # E2E — 62 cases
|
|
351
|
+
npm run test:p0 # P0 gates — 22 cases
|
|
352
|
+
npm run test:trigger # Trigger engine — 29 cases
|
|
353
|
+
npm run test:concurrency # Cross-process concurrency — 3 cases
|
|
354
|
+
npm run test:acceptance # Acceptance — 13 cases
|
|
355
|
+
npm run test:mutation # Mutation testing (13/13 mutants caught)
|
|
356
|
+
npm run check:anchors # Mutation-anchor uniqueness guard
|
|
357
|
+
npm run check:readme # Bilingual README consistency
|
|
358
|
+
|
|
359
|
+
# Pack
|
|
360
|
+
npm pack
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
### Test Coverage Matrix
|
|
364
|
+
|
|
365
|
+
| Suite | Count | Covers |
|
|
366
|
+
|-------|-------|--------|
|
|
367
|
+
| `smoke` | 4 | Card parsing / validation / state round-trip |
|
|
368
|
+
| `e2e-carlos` | 62 | Full flow + activation gate + fake-loop prevention + scope enforcement |
|
|
369
|
+
| `p0-gates` | 22 | P0 gate semantics (fake fillers, type checks, fail-closed) |
|
|
370
|
+
| `trigger-e2e` | 29 | 3-layer engine + session isolation + config merge + `~` expansion |
|
|
371
|
+
| `concurrency-e2e` | 3 | Cross-process concurrency, zero leaks / zero exploits |
|
|
372
|
+
| `e2e-acceptance` | 13 | MCP-path triggering + Chinese word lists + plugin really opens a card |
|
|
373
|
+
| **Total** | **129** | **All passing** |
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## 📚 Documentation
|
|
378
|
+
|
|
379
|
+
| Document | Description |
|
|
380
|
+
|----------|-------------|
|
|
381
|
+
| [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | Deep guide to the Smart Trigger Engine (config, scoring, activation, feedback learning) |
|
|
382
|
+
| [CHANGELOG.md](./CHANGELOG.md) | Version history (Keep a Changelog + SemVer) |
|
|
383
|
+
| [MIGRATION.md](./MIGRATION.md) | Migrating from `carlos-flow-cindy` / `carlos-flow-opencode` |
|
|
384
|
+
| [QA Report](./docs/QA_REPORT_v2.5.5.md) | Third-party read-only audit (13/13 mutants caught) |
|
|
385
|
+
| [Mutation Report](./docs/MUTATION_REPORT_v2.5.5.md) | Mutation injection details and results |
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## ❓ FAQ
|
|
390
|
+
|
|
391
|
+
<details>
|
|
392
|
+
<summary><b>Q: How is this different from a plain MCP Server?</b></summary>
|
|
393
|
+
|
|
394
|
+
A plain MCP Server exposes tools but **doesn't enforce anything** — it trusts the caller to use them correctly.
|
|
395
|
+
Carlos Flow enforces at **server runtime**: out-of-scope files are stopped by `enforceScope()`,
|
|
396
|
+
PASS is refused without passing verification, and audit chain edits break the chain.
|
|
397
|
+
</details>
|
|
398
|
+
|
|
399
|
+
<details>
|
|
400
|
+
<summary><b>Q: I only use Cindy — do I still install all this?</b></summary>
|
|
401
|
+
|
|
402
|
+
No extra download. The single package is the **same install size** (~106 KB) for everyone;
|
|
403
|
+
only the template files differ per platform.
|
|
404
|
+
</details>
|
|
405
|
+
|
|
406
|
+
<details>
|
|
407
|
+
<summary><b>Q: Will this slow my agent down?</b></summary>
|
|
408
|
+
|
|
409
|
+
No. Gate state is **file-based** — no database, no network, no resident process
|
|
410
|
+
(except the Cindy Bridge, which only launches on first call).
|
|
411
|
+
The trigger engine is pure JS computation with zero dependencies.
|
|
412
|
+
</details>
|
|
413
|
+
|
|
414
|
+
<details>
|
|
415
|
+
<summary><b>Q: Is `CARLOS_FLOW_HOME=~/.carlos-flow` really expanded?</b></summary>
|
|
416
|
+
|
|
417
|
+
Yes. Early versions **did not expand it** — `path.normalize` only swaps separators, so the path stayed literal
|
|
418
|
+
and state landed in "a directory literally named `~` inside the current working directory".
|
|
419
|
+
Now `state.js` / `trigger.js` share `expandHome()`, with a regression test guarding it.
|
|
420
|
+
</details>
|
|
421
|
+
|
|
422
|
+
<details>
|
|
423
|
+
<summary><b>Q: Can bypass mode become a backdoor?</b></summary>
|
|
424
|
+
|
|
425
|
+
Bypass requires an **explicit** `confirmed=true` on the card, and `bypass_ts` must be later than `card_ts`
|
|
426
|
+
(an old card's bypass can't apply to a new card).
|
|
427
|
+
Most importantly it **auto-clears after every dispatch** — it applies to one dispatch, never becomes a permanent switch.
|
|
428
|
+
</details>
|
|
429
|
+
|
|
430
|
+
<details>
|
|
431
|
+
<summary><b>Q: Does it work in Chinese?</b></summary>
|
|
432
|
+
|
|
433
|
+
Fully. Chinese workflow terms are built in (工作流/门禁/派发/审计/复核/任务卡/子代理/流程/触发/执行/调度/留痕/裁定),
|
|
434
|
+
so Chinese requests trigger just like English ones — while ordinary dev requests
|
|
435
|
+
("给接口加个参数校验") never false-trigger.
|
|
436
|
+
</details>
|
|
437
|
+
|
|
438
|
+
<details>
|
|
439
|
+
<summary><b>Q: Can I still use the old packages?</b></summary>
|
|
440
|
+
|
|
441
|
+
Yes, but they are **Deprecated**. See [MIGRATION.md](./MIGRATION.md).
|
|
442
|
+
</details>
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
## 🔗 Links
|
|
447
|
+
|
|
448
|
+
| | |
|
|
449
|
+
|---|---|
|
|
450
|
+
| **Repository** | https://github.com/skyer-now/carlos-flow |
|
|
451
|
+
| **npm** | https://www.npmjs.com/package/carlos-flow |
|
|
452
|
+
| **Issues** | https://github.com/skyer-now/carlos-flow/issues |
|
|
453
|
+
| **Changelog** | [CHANGELOG.md](./CHANGELOG.md) |
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
## 🤝 Contributing
|
|
458
|
+
|
|
459
|
+
PRs welcome! Before submitting, make sure:
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
npm run test:all # 129/0 all passing
|
|
463
|
+
npm run check:anchors # mutation anchors intact
|
|
464
|
+
npm run check:readme # bilingual READMEs in sync
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## 📄 License
|
|
472
|
+
|
|
473
|
+
[MIT](./LICENSE) © Carlos Flow Contributors
|