flow-comet 1.5.1 → 1.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.
Files changed (37) hide show
  1. package/.flow-comet/rules/flow-comet-orchestration.md +1 -2
  2. package/.flow-comet/skills/flow-comet/GUIDANCE.md +22 -3
  3. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  4. package/.flow-comet/skills/flow-comet/SKILL.md +40 -3
  5. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
  6. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +18 -17
  7. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +27 -12
  8. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
  9. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
  10. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
  11. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +6687 -330
  12. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +25 -5
  13. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +1145 -15
  14. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +72 -3
  15. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +2077 -14
  16. package/.flow-comet/skills/flow-comet/scripts/task-parsing.mjs +13 -0
  17. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +568 -501
  18. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +331 -14
  19. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +783 -40
  20. package/.flow-comet/skills/flow-comet-archive/SKILL.md +17 -0
  21. package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -0
  22. package/.flow-comet/skills/flow-comet-design/SKILL.md +2 -0
  23. package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
  24. package/.flow-comet/skills/flow-comet-execute/SKILL.md +21 -1
  25. package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
  26. package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
  27. package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
  28. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
  29. package/.flow-comet/skills/flow-comet-review/SKILL.md +23 -3
  30. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +23 -11
  31. package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
  32. package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
  33. package/.flow-comet/skills/flow-comet-verify/SKILL.md +21 -4
  34. package/README.md +45 -115
  35. package/package.json +1 -1
  36. package/scripts/dsh-bridge.mjs +2 -2
  37. package/scripts/prepare-env.mjs +77 -46
package/README.md CHANGED
@@ -28,107 +28,70 @@
28
28
  <p align="center">
29
29
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
30
30
  <a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
31
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.5.1-blue.svg" alt="Version" /></a>
31
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.1-blue.svg" alt="Version" /></a>
32
32
  </p>
33
33
 
34
34
  ---
35
35
 
36
- ## Why
37
-
38
- If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a **verifiable deterministic state machine**:
39
-
40
- - **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
41
- - **Protocol-driven** — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see [Custom Protocols](docs/PROTOCOL.md))
42
- - **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
43
- - **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
44
- - **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
45
-
46
36
  ## Quick Start
47
37
 
48
- Requires [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) and [flow-kit](https://github.com/rihebty/flow-kit) in the target project (see [Installation](docs/INSTALLATION.md)).
38
+ Three steps, run from your project directory:
49
39
 
50
40
  ```bash
51
41
  # 1. Install the CLI globally (Node.js 18+)
52
42
  npm install -g flow-comet
53
43
 
54
- # 2. Install flow-comet into your project, from the project directory
44
+ # 2. Go to your project
55
45
  cd <your project>
46
+
47
+ # 3. Install flow-comet into it
56
48
  fcomet init
57
49
  ```
58
50
 
59
- The package ships two command names pointing at the same installer — `fcomet` (primary) and `flow-comet` (alias). The `init` token is optional whenever another argument expresses the intent (`fcomet --target <dir>` is equivalent to `fcomet init --target <dir>`), and `--target <dir>` is optional too (default: the current working directory); run with no arguments at all, the command prints its usage and exits non-zero instead of installing. `fcomet --version` prints the version of the installed CLI. Re-running the same command updates an existing install and is idempotent.
60
-
61
- On an interactive terminal, the first run prompts for the platform with a direction-key multi-select (arrow keys + space to toggle, Enter to confirm; the default is Claude Code) — `@clack/prompts` is the primary path, with an automatic readline number/comma multi-select fallback when the dependency is not installed, offline, or stdin has no raw mode (`FLOW_COMET_FORCE_READLINE=1` forces the fallback for testing); for a non-interactive pick, add `--platform codex` / `--platform dsh` / `--platform claude-code,dsh` (comma-separated) / `--platform all`.
62
-
63
- **Updating**: a global package upgrade does not touch projects that are already installed — re-run `fcomet init` in each project to pick up the new files. And because an npm install has no git history to derive a development marker from, the version marker it writes (`<project>/.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/…` for Codex, `.dsh/skills/…` for dsh) is the release version shipped inside the package; the `<release>-<n>-g<hash>` form appears only for installs run from a repository clone that has git and tags.
64
-
65
- By default the installer targets Claude Code (unchanged behavior). For Codex: `fcomet init --platform codex` — skills install to `.agents/skills/` (auto-discovered), orchestration rules are injected into an `AGENTS.md` managed block, and the write-guard hook intercepts Bash write commands via Codex's PreToolUse (trust the hook on first use: `/hooks`). For DeepSeek Harness: `fcomet init --platform dsh` — skills install to `.dsh/skills/flow-comet` (auto-discovered at rank 100, no restart), orchestration rules are injected into an `AGENTS.md` managed block, and a thin bridge loader is mounted globally in `$DSH_HOME` (see [Installation → Option D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform)). When run on an interactive terminal (TTY) without `--platform`, the installer prompts for the target platform with a multi-select (pre-checked from existing traces — default Claude Code — press Enter to accept); without a TTY (CI/scripts) existing `.claude/` / `.codex/` / `.dsh/` in the target project is detected, falling back to Claude Code.
66
-
67
- The installer also ensures `flow-kit` in the target project: when missing it clones the upstream and checks out the locked snapshot `9b5dda7`; an existing upstream clone is only inspected (current HEAD vs the locked snapshot is reported, read-only); a same-name non-clone directory is skipped with guidance; a network failure warns and continues; purge never touches it.
51
+ `fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal the first run asks which platform to set up; for a non-interactive pick use `--platform claude-code`, `--platform codex`, `--platform dsh`, a comma-separated combination such as `--platform claude-code,dsh`, or `--platform all`. Re-running the same command updates an existing install and is idempotent. Upgrading the global package only replaces the CLI — run `fcomet init` in a project again to refresh that project's copy.
68
52
 
69
- The same installer also runs straight from a repository clone, with no global package — that is the path this repository's own workflow and its distribution to other projects use (Option B in the installation guide):
53
+ **Verify**:
70
54
 
71
55
  ```bash
72
- cd <flow-comet repo>
73
- node scripts/prepare-env.mjs --target <absolute path to your project>
56
+ fcomet --version # the installed CLI version
57
+ cat .claude/skills/flow-comet/INSTALLED_VERSION # the version written into this project
74
58
  ```
75
59
 
76
- For DeepSeek Harness (dsh), install through the same installer — a dedicated dsh platform descriptor, with no separate plugin bundle:
60
+ The installer writes the marker to `.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/...` for Codex and `.dsh/skills/...` for dsh. It records the version the copy came from: the package's release version for an npm install, or the repository's `git describe` value for an install run from a clone (that form carries a `-<n>-g<hash>` suffix when the clone is ahead of its tag).
77
61
 
78
- ```bash
79
- cd <your project>
80
- fcomet init --platform dsh
81
- ```
62
+ ## Use it
82
63
 
83
- This installs the skill tree project-locally at `<project>/.dsh/skills/flow-comet` (dsh auto-discovers skills there at rank 100 without a restart — projects without that directory cannot see the skill, which makes activation naturally project-level), injects the orchestration rules into an `AGENTS.md` managed block (non-destructive merge), and mounts a thin bridge loader globally at `$DSH_HOME/plugins/dsh-flow-comet-bridge.mjs` with a managed block in `$DSH_HOME/cordis.patch.yml` (read-merge-write, preserves existing blocks such as dsh-skin, effective for all profiles). The bridge intercepts write tools via dsh's `tools/pre-execute` event. Interception only applies while a flow is running — in an idle session, writes outside the project root are not interrupted. Each install reports the dsh loader version transition (upgrade / downgrade / consistent) by comparing the embedded version stamp with the previously installed loader, and `workflow-state.mjs bridge-check` is a read-only health check with six states (healthy / file missing / not mounted / version skew / duplicate registration / not applicable). Minimum dsh `0.1.0-rc.6`. See [Installation → Option D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform) for the full dsh platform section.
64
+ Open a session in your project and invoke the workflow:
84
65
 
85
- ```bash
86
- # 3. Open your project in a new Claude Code session and run:
87
- /flow-comet
88
- # (Codex: invoke the skill in a Codex session — `/use flow-comet` or natural language;
89
- # same workflow, see Installation → "Using flow-comet on Codex")
90
- ```
66
+ - **Claude Code** — `/flow-comet`
67
+ - **Codex** — invoke the skill (`/use flow-comet`, or simply ask for the flow-comet workflow in natural language)
68
+ - **DeepSeek Harness** — invoke the `flow-comet` skill
91
69
 
92
- The first call confirms scope, then automatically creates the `change/<id>` branch, initializes state, enters the open node, and produces `CHANGE.md` / `REQUIREMENT.md`. Every subsequent stage is routed automatically — you only answer decision points (scope, tech stack, destructive changes, review findings, archive confirmation).
70
+ The first call confirms scope, then creates the branch for the change, initializes the state and enters the first node, producing that change's `CHANGE.md` / `REQUIREMENT.md` under `.specs/`. Every later stage is routed automatically — you only answer the decision points (scope, tech stack, destructive changes, review findings, archive confirmation). On first use in a project it detects a missing project context and offers to build one from your existing documents before starting.
93
71
 
94
- On first use in a project, the workflow automatically detects whether a project context (`CONTEXT.md`) exists and prompts to initialize it when missing — existing AI-context documents (such as `CLAUDE.md` / `AGENTS.md`) are read and integrated with source attribution, and existing files are never modified. Projects with a fresh context run silently. No separate command to remember.
72
+ To see where it is, just ask it — or inspect it from the command line with `status` and `next` in the project (the per-platform paths are in [Installation](docs/INSTALLATION.md)).
95
73
 
96
- ## Usage
74
+ Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is added to `.specs/CHANGELOG.md`. The node-by-node walkthrough — including what the workflow runs underneath, and how to drive a node by hand when you need to — is in [Usage](docs/USAGE.md).
97
75
 
98
- - **[8-node workflow](docs/USAGE.md)** — node-by-node responsibilities, branch mode, execution modes, decision points
99
- - **[Custom protocols](docs/PROTOCOL.md)** — compose any installed skill into a custom workflow via `/flow-comet-compose`
100
- - **[Core mechanisms](docs/MECHANISM.md)** — state machine, three defense layers, guard validation, execution model
101
- - **[Troubleshooting](docs/TROUBLESHOOTING.md)** — BLOCKED/WARN messages and their fixes
76
+ ## Pick a platform
102
77
 
103
- The entry point is the `/flow-comet` command; state is inspected and advanced from the command line (paths below assume the Claude Code install `.claude/skills/`; Codex installs to `.agents/skills/`, dsh to `.dsh/skills/` — see [Installation](docs/INSTALLATION.md)):
78
+ | Platform | Skills install to | Hook / bridge | First use |
79
+ |---|---|---|---|
80
+ | Claude Code (default) | `.claude/skills/` | `settings.local.json` → `hooks.PreToolUse` | the workspace must be trusted; headless sessions need that trust pre-accepted |
81
+ | Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs — see [Installation](docs/INSTALLATION.md) |
82
+ | DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
104
83
 
105
- ```bash
106
- node .claude/skills/flow-comet/scripts/workflow-state.mjs status # current change + node
107
- node .claude/skills/flow-comet/scripts/workflow-state.mjs next # next node + skill
108
- ```
109
-
110
- ## Architecture
111
-
112
- ```mermaid
113
- graph LR
114
- O[open] --> D[design] --> P[plan] --> E[execute]
115
- E <--> SE[subagent-execute]
116
- E --> R[review] --> V[verify] --> A[archive]
117
- style O fill:#e8f5e9
118
- style D fill:#e3f2fd
119
- style P fill:#fff3e0
120
- style E fill:#fce4ec
121
- style SE fill:#f3e5f5
122
- style R fill:#e8eaf6
123
- style V fill:#e0f7fa
124
- style A fill:#f1f8e9
125
- ```
84
+ Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
126
85
 
127
- The engine routes between nodes by deriving state from `.specs/` artifacts (determineNode), gated by guard exit validations.
86
+ ## Why
128
87
 
129
- ## What is flow-kit
88
+ If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a **verifiable deterministic state machine**:
130
89
 
131
- [flow-kit](https://github.com/rihebty/flow-kit) is a pure-Markdown development methodology that fuses mainstream AI coding workflows — [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [spec-kit](https://github.com/github/spec-kit), [GSD](https://github.com/open-gsd/gsd-core), [gstack](https://github.com/garrytan/gstack), [claude-task-master](https://github.com/eyaltoledano/claude-task-master) — into its own 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) with `.specs/` artifact templates and R1-R8 behavior rules. No runtime, no CLI — clone it into a project and it defines *what to produce and what rules to follow*, but progress relies on human (and AI) discipline.
90
+ - **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
91
+ - **Protocol-driven** — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see [Custom Protocols](docs/MECHANISM.md#custom-protocols))
92
+ - **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
93
+ - **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
94
+ - **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
132
95
 
133
96
  ## Why flow-comet
134
97
 
@@ -187,55 +150,22 @@ processor-pipeline/ (archived change, full artifact set)
187
150
 
188
151
  ![Verification run](images/long-run-5h.png)
189
152
 
190
- ## Ecosystem
191
-
192
- | Project | Role | Relationship to flow-comet |
193
- |---------|------|---------------------------|
194
- | [flow-kit](https://github.com/rihebty/flow-kit) | Methodology & artifact system (9-stage flow, `.specs/` templates, R1-R8 rules) | **Dependency** — flow-comet is its automation layer; artifacts and rules come from flow-kit |
195
- | [Comet](https://github.com/rpamis/comet) | Skill Creator ecosystem (bundle authoring, hook-guard pattern, state machine) | **Mechanism source** — flow-comet borrows Comet's mechanism patterns extensively (workflow-protocol as source of truth, script-owned state, guard gates, hook interception); **runtime optional** (copy install needs no Comet CLI). Details in [Ecosystem](docs/ECOSYSTEM.md) |
196
- | **Comet Classic** | Comet's classic workflow (OpenSpec + Superpowers) | **Not a dependency** — flow-comet is an independent workflow-kernel; state does not interoperate with classic (own `.flow-comet/flow-comet-state.json` + file-derived routing) |
197
-
198
- ## Directory Structure
199
-
200
- ```
201
- flow-comet/
202
- ├── .flow-comet/ ★ authoritative source (skills/ + rules/)
203
- ├── scripts/ prepare-env installer (npm bin: fcomet / flow-comet)
204
- ├── docs/
205
- │ ├── examples/ workflow artifact examples
206
- │ ├── ECOSYSTEM.md roles of flow-kit & Comet, borrowing boundaries
207
- │ ├── INSTALLATION.md installation guide
208
- │ ├── USAGE.md usage guide
209
- │ ├── PROTOCOL.md custom protocol guide
210
- │ ├── MECHANISM.md core mechanisms (behavior layer)
211
- │ ├── TROUBLESHOOTING.md failure diagnosis
212
- │ └── VERSIONS.md versioning & compatibility
213
- └── CHANGELOG.md Keep a Changelog style
214
- ```
215
-
216
- ## Tech Stack
153
+ ## Relationship to the upstream project
217
154
 
218
- | Layer | Technology |
219
- |-------|------------|
220
- | Runtime | Node.js ≥ 18 (ESM); third-party dependency: `@clack/prompts` (pinned exact version, installer TTY multi-select only — automatic readline fallback when unavailable) |
221
- | Platform | Claude Code (default — skills, `.claude/` installation, hooks); Codex (`.agents/skills/`, AGENTS.md managed rules, PreToolUse write interception); DeepSeek Harness (`.dsh/skills/flow-comet` project-level skill, AGENTS.md managed rules, bridge loader + `tools/pre-execute` interception) |
222
- | Methodology | [flow-kit](https://github.com/rihebty/flow-kit) (artifacts, rules, templates) |
155
+ flow-comet automates the methodology of [flow-kit](https://github.com/rihebty/flow-kit) — its stages, artifacts, rules and templates are inherited rather than reinvented. The two projects do not share files: flow-kit is consumed as a read-only, pinned dependency, and this repository vendors a copy only as a format baseline. What may be borrowed, and how divergences are declared, is written down in [CONTRIBUTING.md](CONTRIBUTING.md#borrowing-boundary).
223
156
 
224
157
  ## Documentation
225
158
 
226
- | Document | Description |
227
- |----------|-------------|
228
- | [Ecosystem](docs/ECOSYSTEM.md) | Roles of flow-kit & Comet, what flow-comet borrows and deliberately does not |
229
- | [Installation](docs/INSTALLATION.md) | Prerequisites, install options A–D (npm / prepare-env / manual copy / dsh), installation verification |
230
- | [Usage](docs/USAGE.md) | 8-node workflow, branch mode, execution modes, decision points |
231
- | [Custom Protocols](docs/PROTOCOL.md) | Compose skills into custom workflows |
232
- | [Core Mechanisms](docs/MECHANISM.md) | State machine, defense layers, guard validation |
233
- | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common errors and fixes |
234
- | [Versions](docs/VERSIONS.md) | SemVer policy, compatibility |
235
- | [Examples](docs/examples/) | Full workflow artifact examples |
236
- | [Changelog](CHANGELOG.md) | Version history (Keep a Changelog) |
237
- | [Security](SECURITY.md) | How to report vulnerabilities |
238
- | [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines |
159
+ | Document | What it is the single place for |
160
+ |---|---|
161
+ | [Installation](docs/INSTALLATION.md) | Prerequisites, the four install options, platform choice, verification, and reset (purge is delete-and-rebuild, not uninstall) |
162
+ | [Usage](docs/USAGE.md) | The 8-node workflow, the per-node lifecycle and its commands, artifacts, branch mode, execution modes, user entry points |
163
+ | [Core Mechanisms](docs/MECHANISM.md) | The behaviour contract, the three defense layers, guard validation, and custom protocols |
164
+ | [Troubleshooting](docs/TROUBLESHOOTING.md) | Symptoms grouped by where they bite: installation, first run, a stuck node, platform |
165
+ | [Versions](docs/VERSIONS.md) | Version semantics, the nine version surfaces, and the release checklist |
166
+ | [CHANGELOG](CHANGELOG.md) | Per-version history |
167
+ | [Contributing](CONTRIBUTING.md) | Contribution flow and the borrowing boundary |
168
+ | [Security](SECURITY.md) | Reporting a vulnerability |
239
169
 
240
170
  ## Contributing
241
171
 
@@ -243,7 +173,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
243
173
 
244
174
  1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
245
175
  2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
246
- 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 243 SCENARIOS PASSED`
176
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 275 SCENARIOS PASSED`
247
177
  4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
248
178
 
249
179
  CI enforces the repository conventions automatically on every PR and push (regression, PR discipline, version consistency, dead links). Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flow-comet",
3
- "version": "1.5.1",
3
+ "version": "1.6.1",
4
4
  "description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "files": [
@@ -28,7 +28,7 @@
28
28
  // 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
29
29
  // ESM 模块导出 { name, apply },ctx 由 dsh 注入。
30
30
  //
31
- // BRIDGE_VERSION: 1.5.1
31
+ // BRIDGE_VERSION: 1.6.1
32
32
 
33
33
  import { spawn } from 'node:child_process';
34
34
  import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -40,7 +40,7 @@ import path from 'node:path';
40
40
  // 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
41
41
  // bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
42
42
  export const name = 'dsh-flow-comet-bridge';
43
- export const version = '1.5.1';
43
+ export const version = '1.6.1';
44
44
 
45
45
  // guard 在项目内的相对路径常量(随 skill 包分发)。
46
46
  const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
@@ -150,7 +150,7 @@ const PLATFORMS = {
150
150
  const settings = injectSettingsHook(claudeDir);
151
151
  const injected = !!(settings.hooks && settings.hooks.PreToolUse);
152
152
  stats.files++;
153
- console.log(`[prepare-env] settings.local.json ${injected ? '注入完成(保留既有字段)' : '已生成'}`);
153
+ console.log(`[flow-comet] settings.local.json ${injected ? '注入完成(保留既有字段)' : '已生成'}`);
154
154
  },
155
155
  // rules 注入:.claude/rules/ 整树复制(自动加载 markdown 指令)
156
156
  installRules(target, stats) {
@@ -193,13 +193,13 @@ const PLATFORMS = {
193
193
  injectCodexHook(codexDir, target);
194
194
  injectCodexConfig(codexDir);
195
195
  stats.files += 2;
196
- console.log('[prepare-env] .codex/hooks.json + config.toml 注入完成(hooks 启用,保留既有字段)');
196
+ console.log('[flow-comet] .codex/hooks.json + config.toml 注入完成(hooks 启用,保留既有字段)');
197
197
  },
198
198
  // rules 注入:AGENTS.md 托管区内联(Codex 指令唯一自动加载路径;.codex/rules/ 是命令批准规则目录,不混用;
199
199
  // 注入函数与托管区标记 codex/dsh 共用——任一平台卸载可清,另一平台重装恢复)
200
200
  installRules(target, stats) {
201
201
  if (injectManagedRules(target, stats)) {
202
- console.log('[prepare-env] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
202
+ console.log('[flow-comet] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
203
203
  }
204
204
  },
205
205
  // purge 清理:只清 flow-comet 技能(.agents/ 为多工具共享位置——非 flow-comet 条目保留)
@@ -263,17 +263,17 @@ const PLATFORMS = {
263
263
  reportLoaderVersionTransition(loaderSrc, loaderDst);
264
264
  fs.copyFileSync(loaderSrc, loaderDst);
265
265
  stats.files++;
266
- console.log('[prepare-env] 桥接 loader 已复制到 $DSH_HOME/plugins/dsh-flow-comet-bridge.mjs');
266
+ console.log('[flow-comet] 桥接 loader 已复制到 $DSH_HOME/plugins/dsh-flow-comet-bridge.mjs');
267
267
  injectDshCordisPatch(dshHome, loaderDst);
268
268
  stats.files++;
269
- console.log('[prepare-env] $DSH_HOME/cordis.patch.yml 托管块注入完成(读-合并-写,保留既有块)');
269
+ console.log('[flow-comet] $DSH_HOME/cordis.patch.yml 托管块注入完成(读-合并-写,保留既有块)');
270
270
  } else {
271
271
  // 容错:scripts/dsh-bridge.mjs 由并行任务新建——源缺失时 WARN 跳过 loader 复制
272
272
  // **并跳过 cordis.patch.yml 托管块注入**(避免注入指向不存在文件的 file:// 引用,
273
273
  // 导致 dsh 每次启动尝试加载不存在的插件);仍完成其余安装
274
274
  // (AGENTS.md 托管区 / skills 复制照常)
275
275
  console.warn(
276
- '[prepare-env] 警告: scripts/dsh-bridge.mjs 不存在——跳过 loader 复制与 cordis.patch.yml 托管块注入' +
276
+ '[flow-comet] 警告: scripts/dsh-bridge.mjs 不存在——跳过 loader 复制与 cordis.patch.yml 托管块注入' +
277
277
  '(dsh 桥接拦截暂不生效,待源文件就位后重跑 prepare-env)'
278
278
  );
279
279
  }
@@ -281,7 +281,7 @@ const PLATFORMS = {
281
281
  // rules 注入:AGENTS.md 托管区(与 codex 共用注入函数与托管区标记——任一平台卸载可清)
282
282
  installRules(target, stats) {
283
283
  if (injectManagedRules(target, stats)) {
284
- console.log('[prepare-env] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
284
+ console.log('[flow-comet] AGENTS.md 托管区注入完成(保留托管区外用户内容)');
285
285
  }
286
286
  },
287
287
  // purge 清理:项目级 .dsh/skills 下全部 flow-comet* 技能(.dsh/skills 为 dsh 技能位置——
@@ -330,7 +330,7 @@ const PLATFORMS = {
330
330
  // 全局挂载语义警示:loader 位于 $DSH_HOME(所有 profile / 所有项目共享)——
331
331
  // 任一项目 purge 都会连带移除,其它已安装 flow-comet 的项目将静默失去拦截
332
332
  console.warn(
333
- '[prepare-env] 全局桥接 loader 被移除,其它已安装 flow-comet 的项目将停止拦截' +
333
+ '[flow-comet] 全局桥接 loader 被移除,其它已安装 flow-comet 的项目将停止拦截' +
334
334
  '($DSH_HOME 全局挂载——如需恢复请重跑 prepare-env --platform dsh)'
335
335
  );
336
336
  }
@@ -360,7 +360,7 @@ function parseArgs(argv) {
360
360
  // ——误敲或试探性执行会在当前目录铺开一套环境。`init` 词元仍可选:`fcomet --target X`
361
361
  // 与 `fcomet init --target X` 等价(有参数即表达了意图)。
362
362
  if (args.length === 0) {
363
- console.error('[prepare-env] 未指定任何参数——裸执行不安装。');
363
+ console.error('[flow-comet] 未指定任何参数——裸执行不安装。');
364
364
  printUsage((line) => console.error(line));
365
365
  process.exit(1);
366
366
  }
@@ -460,7 +460,7 @@ async function promptPlatformSelection(probe, traces, multiTrace) {
460
460
  return promptPlatformSelectionReadline(probe, traces, multiTrace);
461
461
  }
462
462
  const selected = await clack.multiselect({
463
- message: '[prepare-env] 选择要安装的平台(方向键移动、空格勾选、回车确认)',
463
+ message: '[flow-comet] 选择要安装的平台(方向键移动、空格勾选、回车确认)',
464
464
  options,
465
465
  required: true,
466
466
  initialValues: initialValues.length > 0 ? initialValues : undefined,
@@ -487,7 +487,7 @@ async function promptPlatformSelectionReadline(probe, traces, multiTrace) {
487
487
  ? `(检测到目标项目已有 ${probe === 'claude-code' ? '.claude/' : probe === 'codex' ? '.codex/' : '.dsh/'} 痕迹)`
488
488
  : '';
489
489
  const answer = await rl.question(
490
- `[prepare-env] 选择要安装的平台(可多选)${probeNote}:\n` +
490
+ `[flow-comet] 选择要安装的平台(可多选)${probeNote}:\n` +
491
491
  ` 1) Claude Code (claude-code)${traceNote('claude-code', '.claude/')}\n` +
492
492
  ` 2) Codex (codex)${traceNote('codex', '.codex/')}\n` +
493
493
  ` 3) DeepSeek Harness (dsh)${traceNote('dsh', '.dsh/')}\n` +
@@ -556,7 +556,7 @@ async function resolvePlatform(target, platformArg) {
556
556
  }
557
557
  if (multiTrace) {
558
558
  const fallbackId = probe ?? 'claude-code';
559
- console.log(`[prepare-env] 检测到目标项目同时有 .claude/、.codex/ 或 .dsh/ 中的多个痕迹——默认安装 ${PLATFORMS[fallbackId].label}。`);
559
+ console.log(`[flow-comet] 检测到目标项目同时有 .claude/、.codex/ 或 .dsh/ 中的多个痕迹——默认安装 ${PLATFORMS[fallbackId].label}。`);
560
560
  console.log(' 如需其它平台或组合:交互终端运行,或显式 --platform dsh / claude-code,dsh / all。');
561
561
  }
562
562
  return [PLATFORMS[probe ?? 'claude-code']];
@@ -795,7 +795,7 @@ function migrateRuntimeFiles(target) {
795
795
  for (const entry of RUNTIME_FILE_MIGRATIONS) {
796
796
  migrateRuntimeFile(target, entry, report);
797
797
  }
798
- console.log(`[prepare-env] 运行时文件迁移(${LEGACY_RUNTIME_DIR}/ → ${RUNTIME_DIR}/;白名单 ${RUNTIME_FILE_MIGRATIONS.length} 项):`);
798
+ console.log(`[flow-comet] 运行时文件迁移(${LEGACY_RUNTIME_DIR}/ → ${RUNTIME_DIR}/;白名单 ${RUNTIME_FILE_MIGRATIONS.length} 项):`);
799
799
  for (const line of report.migrated) {
800
800
  console.log(` - 已迁移: ${line}`);
801
801
  }
@@ -825,7 +825,7 @@ function isRuntimeDirIgnoreLine(line) {
825
825
  */
826
826
  function manageGitignore(target) {
827
827
  if (fs.existsSync(path.join(target, RUNTIME_DIR, 'skills', 'flow-comet', 'SKILL.md'))) {
828
- console.log(`[prepare-env] .gitignore 纳管跳过: 当前目录是 flow-comet 源仓库(${RUNTIME_DIR}/ 为权威源,需保持被版本控制跟踪)`);
828
+ console.log(`[flow-comet] .gitignore 纳管跳过: 当前目录是 flow-comet 源仓库(${RUNTIME_DIR}/ 为权威源,需保持被版本控制跟踪)`);
829
829
  return;
830
830
  }
831
831
  const gitignorePath = path.join(target, '.gitignore');
@@ -843,14 +843,14 @@ function manageGitignore(target) {
843
843
  }
844
844
  }
845
845
  if (existing.split(/\r?\n/).some(isRuntimeDirIgnoreLine)) {
846
- console.log(`[prepare-env] .gitignore 已含 ${RUNTIME_DIR}/ 条目——保持原样(幂等)`);
846
+ console.log(`[flow-comet] .gitignore 已含 ${RUNTIME_DIR}/ 条目——保持原样(幂等)`);
847
847
  return;
848
848
  }
849
849
  const eol = existing.includes('\r\n') ? '\r\n' : '\n';
850
850
  const appended = ['# flow-comet 运行时文件(不随仓库分发)', `${RUNTIME_DIR}/`].join(eol);
851
851
  const separator = !fileExists || existing === '' || existing.endsWith('\n') ? '' : eol;
852
852
  fs.writeFileSync(gitignorePath, existing + separator + appended + eol, 'utf8');
853
- console.log(`[prepare-env] .gitignore 追加 ${RUNTIME_DIR}/ 条目(既有内容原样保留): ${gitignorePath}`);
853
+ console.log(`[flow-comet] .gitignore 追加 ${RUNTIME_DIR}/ 条目(既有内容原样保留): ${gitignorePath}`);
854
854
  }
855
855
 
856
856
  // ---------- settings.local.json 注入(Claude Code 平台;参考 comet installClaudeCodeHooks) ----------
@@ -965,7 +965,7 @@ function injectSettingsHook(claudeDir) {
965
965
  if (existingHooks.PreToolUse !== undefined && !Array.isArray(existingHooks.PreToolUse)) {
966
966
  // PreToolUse 非数组(手写变体):保留原值 + 警告,不注入(避免破坏用户结构)
967
967
  console.error(
968
- '[prepare-env] 警告: settings.local.json 的 hooks.PreToolUse 不是数组(可能是手写变体)——' +
968
+ '[flow-comet] 警告: settings.local.json 的 hooks.PreToolUse 不是数组(可能是手写变体)——' +
969
969
  '为保护用户配置,未注入 comet hook。请手动添加(见 README 方案 B)。'
970
970
  );
971
971
  return settings;
@@ -1205,13 +1205,13 @@ function compareBridgeVersions(a, b) {
1205
1205
 
1206
1206
  /**
1207
1207
  * 覆盖前版本比对明示:从权威源 loader 与已装 loader 各提取版本戳,按数值序输出
1208
- * 首次安装 / 升级 A→B / 降级 A→B / 版本一致 四类结论之一(人读、带 [prepare-env] 前缀)。
1208
+ * 首次安装 / 升级 A→B / 降级 A→B / 版本一致 四类结论之一(人读、带 [flow-comet] 前缀)。
1209
1209
  * 任一侧提取失败(文件缺失/无标记行)→ 告警并跳过比对——不抛错、不中断安装;
1210
1210
  * 覆盖动作(copyFileSync)由调用方照常执行,幂等语义不变。
1211
1211
  */
1212
1212
  function reportLoaderVersionTransition(loaderSrc, loaderDst) {
1213
1213
  if (!fs.existsSync(loaderDst)) {
1214
- console.log('[prepare-env] 桥接 loader 首次安装($DSH_HOME/plugins 无已装 loader)');
1214
+ console.log('[flow-comet] 桥接 loader 首次安装($DSH_HOME/plugins 无已装 loader)');
1215
1215
  return;
1216
1216
  }
1217
1217
  const src = extractBridgeVersion(loaderSrc);
@@ -1220,7 +1220,7 @@ function reportLoaderVersionTransition(loaderSrc, loaderDst) {
1220
1220
  const failedSide = !src.ok ? '权威源 loader' : '已装 loader';
1221
1221
  const reason = !src.ok ? src.reason : installed.reason;
1222
1222
  console.warn(
1223
- `[prepare-env] 警告: ${failedSide} 版本戳提取失败(${reason})——跳过版本比对,继续覆盖安装`
1223
+ `[flow-comet] 警告: ${failedSide} 版本戳提取失败(${reason})——跳过版本比对,继续覆盖安装`
1224
1224
  );
1225
1225
  return;
1226
1226
  }
@@ -1228,11 +1228,11 @@ function reportLoaderVersionTransition(loaderSrc, loaderDst) {
1228
1228
  const b = src.version;
1229
1229
  const cmp = compareBridgeVersions(a, b);
1230
1230
  if (cmp < 0) {
1231
- console.log(`[prepare-env] 桥接 loader 升级 ${a} → ${b}`);
1231
+ console.log(`[flow-comet] 桥接 loader 升级 ${a} → ${b}`);
1232
1232
  } else if (cmp > 0) {
1233
- console.log(`[prepare-env] 桥接 loader 降级 ${a} → ${b}`);
1233
+ console.log(`[flow-comet] 桥接 loader 降级 ${a} → ${b}`);
1234
1234
  } else {
1235
- console.log(`[prepare-env] 桥接 loader 版本一致(${a})`);
1235
+ console.log(`[flow-comet] 桥接 loader 版本一致(${a})`);
1236
1236
  }
1237
1237
  }
1238
1238
 
@@ -1338,17 +1338,48 @@ function stripManagedBlock(content, startMarker, endMarker) {
1338
1338
 
1339
1339
  // ---------- 版本标识(全部平台共用) ----------
1340
1340
 
1341
+ /**
1342
+ * 目录**本身**是否为 git 仓库根。判据 = `git rev-parse --show-toplevel` 指回自身。
1343
+ * git 从 cwd 起**向上**找仓库,故嵌套在别人仓库里的目录同样能拿到结果——必须比对。
1344
+ * 同时静音 stderr:git 在非仓库目录会打印 `fatal: not a git repository`,不该漏给用户。
1345
+ */
1346
+ function isRepositoryRoot(dir) {
1347
+ try {
1348
+ const top = execFileSync('git', ['rev-parse', '--show-toplevel'], {
1349
+ cwd: dir, encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'ignore'],
1350
+ }).trim();
1351
+ if (!top) return false;
1352
+ const normalize = (value) => {
1353
+ let resolved = value;
1354
+ try { resolved = fs.realpathSync(value); } catch { /* 取不到真实路径时用词法路径 */ }
1355
+ return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
1356
+ };
1357
+ return normalize(top) === normalize(dir);
1358
+ } catch {
1359
+ return false; // 无 git / 非仓库:一律不采信
1360
+ }
1361
+ }
1362
+
1341
1363
  /**
1342
1364
  * 版本标识:优先从源仓库 git describe 生成(多人协作精确检测——发布版 = 精确 tag,
1343
1365
  * 开发态 = "<tag>-<领先提交数>-g<hash>",提 issue 时维护者可据此判断包含哪些积累);
1344
1366
  * 无 git(纯手动复制兜底)时用权威源随技能包分发的 INSTALLED_VERSION(最近发布版本)。
1367
+ *
1368
+ * **采信 git 的前提 = 本目录就是仓库根**(仓库检出形态)。包被装在别人的仓库里时
1369
+ * (本地安装进项目 → `<项目>/node_modules/flow-comet`),git 会向上找到**宿主仓库**,
1370
+ * 把宿主 tag 当成流工具版本——该值是错的,且它正是写进目标项目版本标识的那个值
1371
+ * (issue 报版本 / bridge-check 比对 / 套件跨值守卫会跟着全错)。故非仓库根一律回退包内文件。
1345
1372
  */
1346
1373
  function resolveInstalledVersion() {
1347
1374
  let installedVersion = '';
1348
- try {
1349
- const desc = execFileSync('git', ['describe', '--tags'], { cwd: REPO_ROOT, encoding: 'utf8', timeout: 30000 }).trim();
1350
- if (desc) installedVersion = desc.replace(/^v/, ''); // 剥 v 前缀,与 CHANGELOG 版本号一致
1351
- } catch { /* 无 tag 或非 git 仓库:回退权威源文件 */ }
1375
+ if (isRepositoryRoot(REPO_ROOT)) {
1376
+ try {
1377
+ const desc = execFileSync('git', ['describe', '--tags'], {
1378
+ cwd: REPO_ROOT, encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'ignore'],
1379
+ }).trim();
1380
+ if (desc) installedVersion = desc.replace(/^v/, ''); // 剥 v 前缀,与 CHANGELOG 版本号一致
1381
+ } catch { /* 无 tag:回退权威源文件 */ }
1382
+ }
1352
1383
  if (!installedVersion) {
1353
1384
  const bundled = path.join(BUNDLE_DRAFTS, 'skills', 'flow-comet', 'INSTALLED_VERSION');
1354
1385
  if (fs.existsSync(bundled)) installedVersion = fs.readFileSync(bundled, 'utf8').trim();
@@ -1375,9 +1406,9 @@ function gitErrorFirstLine(err) {
1375
1406
  /** 手动获取指引(clone/checkout 失败或目录非上游克隆时打印——含上游 URL 与目标路径;不抛错) */
1376
1407
  function printFlowKitManualGuide(target) {
1377
1408
  const flowKitDir = path.join(target, 'flow-kit');
1378
- console.warn(`[prepare-env] 手动获取指引: git clone ${FLOW_KIT_UPSTREAM_URL} "${flowKitDir}"`);
1379
- console.warn(`[prepare-env] 然后锁定快照: git -C "${flowKitDir}" checkout --detach ${FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN)}`);
1380
- console.warn('[prepare-env] 未获取 flow-kit 时技能协议引用悬空、guard 段名基准退化为内置 fallback——其余安装职责不受影响。');
1409
+ console.warn(`[flow-comet] 手动获取指引: git clone ${FLOW_KIT_UPSTREAM_URL} "${flowKitDir}"`);
1410
+ console.warn(`[flow-comet] 然后锁定快照: git -C "${flowKitDir}" checkout --detach ${FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN)}`);
1411
+ console.warn('[flow-comet] 未获取 flow-kit 时技能协议引用悬空、guard 段名基准退化为内置 fallback——其余安装职责不受影响。');
1381
1412
  }
1382
1413
 
1383
1414
  /**
@@ -1420,10 +1451,10 @@ function ensureFlowKit(target) {
1420
1451
  encoding: 'utf8',
1421
1452
  timeout: FLOW_KIT_GIT_TIMEOUT_MS,
1422
1453
  });
1423
- console.log(`[prepare-env] 已获取 flow-kit(锁定 ${shortLock})`);
1454
+ console.log(`[flow-comet] 已获取 flow-kit(锁定 ${shortLock})`);
1424
1455
  } catch (err) {
1425
1456
  // 路径 4:clone/checkout 任一失败 → WARN + 手动指引,不抛错
1426
- console.warn(`[prepare-env] 警告: flow-kit 自动获取失败(${gitErrorFirstLine(err)})`);
1457
+ console.warn(`[flow-comet] 警告: flow-kit 自动获取失败(${gitErrorFirstLine(err)})`);
1427
1458
  printFlowKitManualGuide(target);
1428
1459
  }
1429
1460
  return;
@@ -1434,9 +1465,9 @@ function ensureFlowKit(target) {
1434
1465
  if (originStatus !== 'match') {
1435
1466
  // 路径 3:同名非克隆目录(或 remote 无法确认归属)→ 跳过 + 指引,绝不改动
1436
1467
  if (originStatus === 'unreadable') {
1437
- console.warn('[prepare-env] 警告: flow-kit 目录存在且含 .git,但 origin remote 读取失败——无法确认归属');
1468
+ console.warn('[flow-comet] 警告: flow-kit 目录存在且含 .git,但 origin remote 读取失败——无法确认归属');
1438
1469
  }
1439
- console.log('[prepare-env] 目录存在但非上游克隆,已跳过');
1470
+ console.log('[flow-comet] 目录存在但非上游克隆,已跳过');
1440
1471
  printFlowKitManualGuide(target);
1441
1472
  return;
1442
1473
  }
@@ -1447,18 +1478,18 @@ function ensureFlowKit(target) {
1447
1478
  timeout: FLOW_KIT_GIT_TIMEOUT_MS,
1448
1479
  }).trim();
1449
1480
  const shortHead = head.slice(0, FLOW_KIT_SHORT_SHA_LEN);
1450
- console.log(`[prepare-env] 已有 flow-kit(HEAD=${shortHead},推荐锁定点=${shortLock})`);
1481
+ console.log(`[flow-comet] 已有 flow-kit(HEAD=${shortHead},推荐锁定点=${shortLock})`);
1451
1482
  if (head === FLOW_KIT_LOCKED_COMMIT) {
1452
- console.log('[prepare-env] 当前 HEAD 与推荐锁定点一致。');
1483
+ console.log('[flow-comet] 当前 HEAD 与推荐锁定点一致。');
1453
1484
  } else {
1454
1485
  console.warn(
1455
- `[prepare-env] 差异影响: 当前 HEAD 与推荐锁定点不一致——guard 段名基准与协议引用可能偏离安装器锁定内容` +
1486
+ `[flow-comet] 差异影响: 当前 HEAD 与推荐锁定点不一致——guard 段名基准与协议引用可能偏离安装器锁定内容` +
1456
1487
  `(安装器绝不改动已有克隆;如需对齐请手动执行 git -C "${flowKitDir}" fetch 后 checkout --detach ${shortLock})`
1457
1488
  );
1458
1489
  }
1459
1490
  } catch (err) {
1460
1491
  // HEAD 只读失败同样不改动、不中断安装(保守降级为警告)
1461
- console.warn(`[prepare-env] 警告: flow-kit HEAD 读取失败(${gitErrorFirstLine(err)}),已跳过比对`);
1492
+ console.warn(`[flow-comet] 警告: flow-kit HEAD 读取失败(${gitErrorFirstLine(err)}),已跳过比对`);
1462
1493
  }
1463
1494
  }
1464
1495
 
@@ -1485,13 +1516,13 @@ async function main() {
1485
1516
 
1486
1517
  // --purge(已在上方确认 --yes):逐平台删除生成物后重新生成
1487
1518
  if (purge) {
1488
- console.error(`[prepare-env] 警告: --purge 将删除 ${platformsLabel} 平台的以下生成物(不可恢复):`);
1519
+ console.error(`[flow-comet] 警告: --purge 将删除 ${platformsLabel} 平台的以下生成物(不可恢复):`);
1489
1520
  for (const platform of platforms) {
1490
1521
  for (const entry of platform.purge(target)) {
1491
1522
  console.error(` - ${entry}`);
1492
1523
  }
1493
1524
  }
1494
- console.error('[prepare-env] 已删除,开始重新生成。');
1525
+ console.error('[flow-comet] 已删除,开始重新生成。');
1495
1526
  }
1496
1527
 
1497
1528
  // flow-kit 获取链路(ADR-008 / D1~D6——平台无关,平台循环之前调用一次;
@@ -1503,7 +1534,7 @@ async function main() {
1503
1534
  const stats = { dirs: 0, files: 0, skills: [] };
1504
1535
 
1505
1536
  // 覆盖前打印将覆盖的生成物清单(默认非破坏:只覆盖生成物)
1506
- console.log(`[prepare-env] 平台: ${platform.label} — 将覆盖以下生成物(其他内容保留):`);
1537
+ console.log(`[flow-comet] 平台: ${platform.label} — 将覆盖以下生成物(其他内容保留):`);
1507
1538
  console.log(` - ${skillRoot}`);
1508
1539
  for (const line of platform.overwriteDescription(target)) {
1509
1540
  console.log(` - ${line}`);
@@ -1530,7 +1561,7 @@ async function main() {
1530
1561
  }
1531
1562
  const replacedFiles = applyPathReplacements(skillRoot, platform.pathReplacements);
1532
1563
  if (replacedFiles > 0) {
1533
- console.log(`[prepare-env] 平台路径替换: ${replacedFiles} 个 .md 文件(${platform.label} 命令路径)`);
1564
+ console.log(`[flow-comet] 平台路径替换: ${replacedFiles} 个 .md 文件(${platform.label} 命令路径)`);
1534
1565
  }
1535
1566
 
1536
1567
  // 4. 版本标识(写入平台技能根,随技能包分发)
@@ -1539,11 +1570,11 @@ async function main() {
1539
1570
  stats.files++;
1540
1571
 
1541
1572
  // 摘要(逐平台)
1542
- console.log(`[prepare-env] 已准备环境: ${target}(${platform.label})`);
1573
+ console.log(`[flow-comet] 已准备环境: ${target}(${platform.label})`);
1543
1574
  console.log(
1544
- `[prepare-env] 目录 ${stats.dirs} 个、文件 ${stats.files} 个、skills ${stats.skills.length} 个`
1575
+ `[flow-comet] 目录 ${stats.dirs} 个、文件 ${stats.files} 个、skills ${stats.skills.length} 个`
1545
1576
  );
1546
- console.log(`[prepare-env] skills: ${stats.skills.join(', ')}`);
1577
+ console.log(`[flow-comet] skills: ${stats.skills.join(', ')}`);
1547
1578
  }
1548
1579
 
1549
1580
  // 执行顺序第三段:.gitignore 保守纳管(部署成功后执行——失败即中止,可重跑自愈)
@@ -1553,6 +1584,6 @@ async function main() {
1553
1584
  try {
1554
1585
  await main();
1555
1586
  } catch (err) {
1556
- console.error(`[prepare-env] 错误: ${err.message}`);
1587
+ console.error(`[flow-comet] 错误: ${err.message}`);
1557
1588
  process.exit(1);
1558
1589
  }