@michaelxwb/code-flow 0.8.1 → 1.0.0

package/README.md

@@ -1,201 +1,122 @@
 # code-flow
 
-用于管理项目规范、任务和可执行验收的命令行工具。通过 `code-flow init` 安装四平台入口，再由持久化 Spec Context、场景源、阶段门禁和逐 check 执行证据约束开发流程。
+v1 是零依赖的全局 Node.js CLI，为 AI 编码工具提供两件事：按当前任务注入最新规范，以及把已完成任务的稳定约束沉淀为 Spec。默认 `hook` 工作流只要求最小 task 文档和声明测试；`full` 文档流程和过程采集按需开启。
 
-本仓库当前版本为 **0.8.1**；npm 的 `latest` 标签以注册表查询为准。使用说明见[使用手册](docs/USAGE.md)，场景与测试登记格式见[可执行验收契约](docs/acceptance-contract.md)。
+需要 Node.js 18 或更高版本。支持 Claude Code、Codex、Costrict 与 OpenCode；不需要 Python，不在项目中复制核心脚本。
 
-## 安装
-
-npm：
+## 安装与初始化
 
 ```bash
 npm i -g @michaelxwb/code-flow
+code-flow init --platform=codex
 ```
 
-pnpm：
-
-```bash
-pnpm add -g @michaelxwb/code-flow
-```
-
-## 升级
-
-先核对已安装版本与注册表版本：
-
-```bash
-code-flow --version
-npm view @michaelxwb/code-flow dist-tags --json
-```
+平台可选 claude、codex、costrict、opencode。Codex 按宿主要求审阅并信任新的 Hook。所有项目共享当前全局版本；更新 Node 或全局安装路径后，重新 init。
 
-从 npm 升级到已发布的最新版本：
+init 会安装 `.code-flow/templates/project-guidelines.md` 作为项目规范 starter；`cf-init` 会据此把项目特有规范写到 `CLAUDE.md`/`AGENTS.md` 的托管块之外，并把 `.code-flow/specs` 明确为规范来源。
 
-```bash
-npm i -g @michaelxwb/code-flow@latest
-```
+旧版本需要人工保存资料、清除旧平台入口后重新初始化；v1 不包含迁移、转换或自动删除逻辑。详见[使用说明](docs/USAGE.md)。
 
-pnpm：
+## 规范与任务
 
-```bash
-pnpm add -g @michaelxwb/code-flow@latest
+```text
+.code-flow/
+  config.json
+  specs/shared/base.md
+  specs/cli/runtime.md
+  tasks/2026-11-10/example/example.md
+  process/        # capture 开启时的过程事件与采集包（gitignored）
 ```
 
-需要使用本仓库尚未发布的修复时，在仓库根目录构建并安装本地包：
-
-```bash
-npm pack --ignore-scripts
-npm install --global ./michaelxwb-code-flow-0.8.1.tgz --ignore-scripts
-code-flow --version
-```
+Spec 身份就是相对路径，例如 cli/runtime；JSON frontmatter 包含 description 与 next_rule。完整规则引用为 cli/runtime#RULE-001。
 
-CLI 更新后，在目标项目执行运行时迁移，将脚本、已安装平台和 Hook 一起更新：
+一个需求一份任务文档，内部包含多个 `## TASK-NNN` 段。默认 `workflow: hook` 只需要 `example.md`；`workflow: full` 额外生成 PRD/前后端 design/scenarios：
 
-```bash
-code-flow migrate --runtime --dry-run
-code-flow migrate --runtime --apply
+```text
+tasks/2026-11-10/example/
+  example.md
+  # workflow=full:
+  # example.prd.md
+  # example.frontend.design.md
+  # example.backend.design.md
+  # example.scenarios.md
 ```
 
-CLI 与项目 runtime 必须匹配；版本不一致时按诊断升级 CLI 或迁移 runtime。备份与回滚步骤见 [0.8 迁移说明](docs/migrations/runtime-0.8.0.md)。
+任务文档的 TASK 段声明 status、source、scenarios、spec_refs 和 tests（hook 下 source/scenarios 可留空）：
 
-## 卸载
+````markdown
+## TASK-001: Implement behavior
 
-npm：
-
-```bash
-npm rm -g @michaelxwb/code-flow
-```
+- **Status**: draft
+- **Depends**:
+- **Source**:
+- **Scenarios**:
+- **Spec-Refs**: cli/runtime
 
-pnpm：
+### Tests
 
-```bash
-pnpm remove -g @michaelxwb/code-flow
+```json
+[
+  { "id": "unit", "argv": ["node", "--test", "test/hook.test.js"] }
+]
 ```
 
-## 基本用法
+### Checklist
 
-初始化（默认 `--platform=claude`）：
+- [ ] 实现相关行为并验证回归。
+````
 
-```bash
-code-flow init
-code-flow init --platform=codex
-code-flow init --platform=costrict
-code-flow init --platform=opencode
-code-flow init --force                # 覆盖所有文件，包括用户已编辑内容
-```
+`Source`/`Scenarios` 在 hook 工作流可留空；full 工作流填 design/scenarios 引用。
 
-查看帮助：
+完整示例见[使用说明](docs/USAGE.md)。
 
 ```bash
-code-flow --help
+code-flow task start .code-flow/tasks/2026-11-10/example/example.md --task TASK-001
+code-flow task finish .code-flow/tasks/2026-11-10/example/example.md --task TASK-001 --json
+code-flow task archive .code-flow/tasks/2026-11-10/example --dry-run
+code-flow task archive .code-flow/tasks/2026-11-10/example
 ```
 
-## 开发与验收
+cf-task skill 把 prompt Hook 给出的 session token 传给 start --session，之后按会话自动续选任务。用户也可用独立行 `task: <任务文档>#TASK-001` 选择本轮任务。绑定缺失时按明确文件路径映射或显示 catalog，不猜测唯一 in-progress。
 
-需求文件集中在 `.code-flow/tasks/<日期>/<需求>/`。通常依次使用 `cf-task:prd` → `cf-task:align` → `cf-task:plan` → `cf-task:start` → `cf-task:verify-e2e` → `cf-task:archive`；Codex 使用对应的 `cf-task-*` skills。
+Hook 只在用户提交 prompt 时读取并交付上下文。没有编辑/Stop 门禁；规范修改后下次适用注入读取最新内容。finish 实际执行本任务声明测试；archive 仅应用 Delta 并移动需求目录，CI 独立承担全量与 E2E。
 
-| 阶段 | 正式运行时入口 | 检查内容 |
-|------|----------------|----------|
-| 场景 | `code-flow scenarios parse --file "<需求>.scenarios.md" --quality --json` | 浏览器边界、具体预期与步骤/断言引用、延期责任 |
-| 设计 | `code-flow design lint --file "<需求>.design.md" --scenarios-file "<需求>.scenarios.md" --json` | ID 闭环、功能场景覆盖与已声明模板章节 |
-| 计划 | `code-flow acceptance manifest --task-dir "<需求目录>" --task-file "<任务文件>" --verify-plan --json` | manifest、场景、设计、测试登记/收集与 Spec Gate |
-| 开发中 | `code-flow task verify --task-dir "<需求目录>" --checks --profile full --root "$PWD" --json` | 只运行 validators，不推进任务状态 |
-| 需求终验 | `code-flow task verify --task-dir "<需求目录>" --layers validators,review,e2e --profile full --root "$PWD" --json` | 全层执行与当前输入证据 |
-| 诊断 | `code-flow spec doctor --task-dir "<需求目录>" --root "$PWD" --json` | 安装/Context 健康、未解决 Rule 引用与阶段 readiness |
+批次 worktree 从包含 specs/当前需求/config 的 baseline 创建；业务代码 dirty 时拒绝。worker 默认使用全局 CLI，prepare 不再自动 init；只有需要 worker 内宿主会话时才用 `--init`。随后校验 specs 快照并自动合并。
 
-浏览器关键旅程用 `e2e`，API/CLI/后台全链路用 `system`，容量用 `capacity`。计划通过与测试收集通过不能代替真实执行；格式、错误修复和各项数量口径见[验收契约](docs/acceptance-contract.md)。
+## 工作流与过程数据
 
-## 质量闭环（v0.5）
+`config.json` 的关键字段：
 
-零配置开箱即用，安装后自动获得两个闭环：
-
-**合规反馈**：spec 约束可在 frontmatter 标注机检规则，AI 编辑文件后自动检查，违规当场反馈给 AI 修正（只提示、不阻断）：
-
-```yaml
----
-description: 改 Python 脚本时适用
-checks:
-  - id: no-print-debug
-    type: regex
-    pattern: '^\s*print\('
-    files: "**/*.py"
-    message: 禁止 print() 调试，用日志到 stderr
----
+```json
+{
+  "version": 1,
+  "workflow": "hook",
+  "capture": { "enabled": false, "path": ".code-flow/process" }
+}
 ```
 
-**学习沉淀**：你在对话中纠正 AI 的行为（"不要用 print 调试"）会被记录，`/cf-learn` 将同类纠正聚合为候选规范（附 ✅/❌ 对照与机检草稿），由你确认后落盘——纠正一次，不用说第二遍。
-
-**误报治理**：反馈出现误报时直接告诉 AI"这是误报"即可，同一规则误报 3 次或误报率超 10% 自动停用；`cf-stats` 可查违规榜/修正率/误报率，`cf-stats --audit` 输出僵尸规范复审清单。
-
-**一键回退**：`config.yml` 中 `quality_loop.enabled: false` 完整回到 v0.5 行为。
-
-> **数据声明**：质量闭环产生的所有数据（违规事件、纠正语句摘录、统计计数）仅存储在项目本地 `.code-flow/` 目录（`.session-log.jsonl` / `.check-state.json`，已加入 .gitignore），不上传、不外发、30 天滚动清理。纠正采集可经 `quality_loop.correction_capture: false` 单独关闭。
+- `workflow`: `hook`（默认）要求 task 文档和声明测试；`full` 启用 PRD/design/scenarios。设计文档是项目资产，不作为 prompt 输入；只有 Spec 会注入。
+- `capture`: 开启后 CLI/Hook 自动写入 `.code-flow/process/events.jsonl`。验证结束用跨平台命令采集：
 
-## 支持的 AI 工具
-
-| 工具 | `--platform` | 状态 |
-|------|-------------|------|
-| [Claude Code](https://claude.ai/code) | `claude` | ✅ 完整支持 |
-| [Codex CLI](https://github.com/openai/codex) | `codex` | ✅ 完整支持 |
-| [Costrict](https://costrict.com) | `costrict` | ✅ 完整支持 |
-| [OpenCode](https://opencode.ai) | `opencode` | ✅ 完整支持 |
-
-## 生成的目录与文件
-
-运行 `code-flow init` 后，将在项目根目录生成（或更新）以下结构：
-
-```
-.code-flow/                       # 规范核心（共用）
-  scripts/                        # Python 运行时与 Hook（四平台共用）
-  runtime-commands.json            # 正式运行时命令契约
-  tasks/<日期>/<需求>/             # PRD、design、scenarios、任务与验收 manifest
-  specs/<domain>/                 # 领域 spec（_map.md + 约束规则）
-
-# Claude Code (--platform=claude)
-.claude/commands/                 # 命令模板
-.claude/settings.local.json       # Hook 注册（PreToolUse + UserPromptSubmit）
-CLAUDE.md                         # 全局指令
-
-# Codex CLI (--platform=codex)
-.codex/hooks.json                 # Hook 注册（SessionStart + UserPromptSubmit）
-.codex/config.toml                # Codex 配置
-.agents/skills/<skill>/SKILL.md   # 项目级 Skills
-AGENTS.md                         # 全局指令
-
-# Costrict (--platform=costrict)
-.costrict/commands/               # 命令模板
-.costrict/settings.local.json     # Hook 注册
-CLAUDE.md                         # 与 Claude 共用全局指令
-
-# OpenCode (--platform=opencode)
-.opencode/commands/               # 命令模板（含 cf-task/）
-.opencode/plugins/code-flow/      # v2 插件：session.prompt 转发到 cf_user_prompt_hook.py
-opencode.json                     # OpenCode 配置（`.opencode/plugins/` 自动发现，无需注册键）
-AGENTS.md                         # 全局指令
+```bash
+code-flow process collect --out <dir> [--transcript <host-session.jsonl>]
 ```
 
-## 依赖说明
+输出目录包含事件、任务/规范快照、状态、git 信息和可选 transcript；手动压缩传递。
+
+## 大测试集
 
-- 需要 Node.js 18 及以上
-- 需要 `python3` 版本 3.9 及以上
-- 需要安装 `pyyaml`（`cf_init` 会尝试自动安装，失败会提示手动处理）
-- 运行测试需要 `pytest`
+把相关测试文件合成一次框架调用，使用框架自己的 workers。不同命令确认独立后设置 parallel:true；用 group 串行共享数据库、端口或 fixture，--jobs 限制 CLI 并发。相同调用内完全相同命令只执行一次，不跨次缓存结果。
 
-### 运行测试
+## 开发
 
 ```bash
-python3 -m pip install pyyaml pytest
-python3 -m pytest -q tests
+code-flow doctor --json
+npm test
+npm run test:performance
+npm pack --ignore-scripts
 ```
 
-## 常见问题
-
-- EOTP（`--otp`）
-  - 原因：启用了 npm/pnpm 的一次性密码或 2FA。
-  - 处理：按提示输入 OTP，或使用 `--otp` 重新执行安装命令。
-
-- E402（`--access=public`）
-  - 原因：发布/安装时访问级别不匹配或权限不足。
-  - 处理：必要时使用 `--access=public` 重新发布或检查权限配置。
+运行源码使用 node bin/code-flow.js。测试覆盖真实子进程、全局包安装、worktree、平台原生协议和多文件失败重试。
 
-- name 冲突
-  - 原因：本地或全局已有同名命令/包。
-  - 处理：先卸载冲突包或更换名称后再安装。
+[文档索引](docs/README.md) · [设计](docs/v1-design.md) · [验收覆盖](docs/v1-implementation.md) · [使用说明](docs/USAGE.md)

package/bin/code-flow.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+process.stdout.on('error', error => {
+  if (error.code !== 'EPIPE') process.stderr.write('code-flow stdout: ' + error.message + '\n');
+  process.exitCode = process.argv[2] === 'hook' ? 0 : 1;
+});
+require('../lib/cli').main(process.argv.slice(2)).then(code => {
+  process.exitCode = code;
+}).catch(error => {
+  process.stderr.write('code-flow: ' + error.message + '\n');
+  process.exitCode = process.argv[2] === 'hook' ? 0 : 1;
+});

package/docs/README.md

@@ -0,0 +1,19 @@
+# 文档索引
+
+当前只保留 v1 有效文档：
+
+| 文档 | 用途 |
+|---|---|
+| [USAGE.md](USAGE.md) | 安装、Spec、Task、测试、worktree、诊断和旧版切换 |
+| [v1-design.md](v1-design.md) | v1 架构、数据格式、Hook、任务生命周期和验收契约 |
+| [v1-implementation.md](v1-implementation.md) | 实现范围、测试矩阵、CI 和已知限制 |
+
+以下历史资料不再维护，可从 Git 标签 `v0.8.1`（提交 `eb0e4c0`）查看：
+
+- 旧 Python 运行时与 `src/` 设计；
+- 旧 Spec Context、acceptance manifest、evidence、scenario/design gate 文档；
+- 0.6–0.9 迁移说明、0.8 计划和发布说明；
+- 旧 verification-efficiency 原始测量数据；
+- 旧 worktree-parallel 设计。
+
+当前工作树只使用 `.code-flow/config.json`、`.code-flow/specs/`、`.code-flow/tasks/` 和 `.code-flow/templates/`。v1 不读取、不转换、不自动清理旧文档。