carlos-flow 0.0.0-stage → 2.6.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/README.en.md ADDED
@@ -0,0 +1,473 @@
1
+ # Carlos Flow
2
+
3
+ [![npm](https://img.shields.io/npm/v/carlos-flow.svg)](https://www.npmjs.com/package/carlos-flow)
4
+ [![npm downloads](https://img.shields.io/npm/dm/carlos-flow.svg)](https://www.npmjs.com/package/carlos-flow)
5
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
6
+ [![MCP](https://img.shields.io/badge/MCP-1.29%2B-blue.svg)](https://modelcontextprotocol.io)
7
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
8
+ [![CI](https://img.shields.io/badge/CI-passing-brightgreen.svg)](./.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
193
+
194
+ ```bash
195
+ npm install -g carlos-flow
196
+ ```
197
+
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)
235
+
236
+ ```bash
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
240
+ ```
241
+
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
247
+
248
+ ```bash
249
+ node client/carlos.js flow_status '{"sessionId":"probe"}'
250
+ ```
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