@winspan/claude-forge 8.41.0 → 8.51.0

package/CLAUDE.md.backup

@@ -0,0 +1,488 @@
+<!-- forge:claudemd-auto -->
+# claude-forge 工作区规范
+
+## Behavioral Rules (Always Enforced)
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless they're absolutely necessary for achieving your goal
+- ALWAYS prefer editing an existing file to creating a new one
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
+- ALWAYS read a file before editing it
+- Never continuously check status after spawning a swarm — wait for results
+
+### Two-Phase Workflow (Design-First for Non-Trivial Tasks)
+
+**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
+
+#### Phase 1: Generate Spec (Mandatory)
+
+1. **Spawn planner/researcher agent** with `run_in_background: true`
+2. **Agent 任务**：
+   - 调研现有代码和架构
+   - 设计实现方案
+   - 将方案写入 `docs/design/[task]-spec-YYYYMMDD-HHMM.md`
+   - 包含：目标、改动文件清单、关键设计决策、风险点、测试策略
+   - **禁止写任何代码，只输出设计文档**
+3. **主线程行为**：
+   - 告诉用户"已 spawn planner，等待 spec 生成"
+   - **然后结束响应，不做任何其他操作**
+   - 等待 agent 完成通知
+
+#### Phase 1.5: User Review (Critical Gate)
+
+Agent 完成后，**主线程必须停止并等待用户确认**：
+
+```
+设计方案已生成：docs/design/xxx-spec.md
+
+请 review 后回复：
+- "批准" / "approve" / "开始实现" → 我会 spawn coder 实现
+- "修改 [具体意见]" → 我会让 planner 调整 spec
+- "取消" / "cancel" → 停止任务
+```
+
+**绝对禁止**：
+- ❌ 主线程自行判断 spec 质量并进入 Phase 2
+- ❌ 主线程说"spec 看起来不错，我开始实现"
+- ❌ 主线程直接 spawn coder 而不等用户确认
+
+**只有收到用户明确的批准指令，才能进入 Phase 2。**
+
+#### Phase 2: Implement per Spec
+
+收到用户"批准"后：
+
+1. Spawn coder agent with `run_in_background: true`
+2. **Agent 任务**：
+   - 严格按 `docs/design/xxx-spec.md` 执行
+   - 不偏离 spec（如需调整，先更新 spec 并再次请求批准）
+   - 完成后写 `docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md` 记录实际改动
+3. **主线程行为**：
+   - 告诉用户"已 spawn coder，按 spec 实现"
+   - 等待 agent 完成通知
+   - 汇总结果
+
+#### 例外：简单任务可跳过
+
+以下情况可以跳过两阶段，直接实现：
+- 单文件 1-2 行修改（typo 级别）
+- 用户明确说"不需要 spec，直接做"
+- 纯查询/调研任务（不涉及代码改动）
+
+**其他所有情况必须走两阶段流程。**
+
+### MANDATORY Agent Delegation Rule (NEVER SKIP)
+
+#### 默认行为：spawn Agent，不是自己做
+
+接到任务时，**第一反应是 spawn Agent**。"我自己做" 是需要主动决策并解释的例外，不是默认。
+
+#### 激进策略：最大化 Agent 使用（提高效率）
+
+**几乎所有任务都 spawn Agent**，包括查询、调研、代码阅读。主线程只做极简协调。
+
+#### 不 spawn 的例外清单（仅这 4 条）
+
+只有以下情况允许主线程直接处理：
+
+1. **单行 typo**：1 个文件，1 行，纯拼写错误（如 `fucntion` → `function`）
+2. **协调与汇总**：把多个 Agent 的结果整合给用户，或等待 Agent 完成通知
+3. **元任务（meta-task）**：修改本规则文件本身、git commit/push、配置 daemon 等"工具的工具"操作
+4. **即时问答**：用户问"现在几点"、"你是谁"、"帮助命令是什么"等不涉及代码/文件的纯对话
+
+**以下情况必须 spawn Agent（不再是例外）**：
+- ❌ ~~"查看文件内容"~~ → ✅ spawn Explore agent 并行搜索
+- ❌ ~~"这个函数做什么"~~ → ✅ spawn doc-reviewer 深度分析
+- ❌ ~~"找出 X 在哪"~~ → ✅ spawn Explore agent 定位
+- ❌ ~~"单文件 3 行修改"~~ → ✅ spawn coder（除非是 1 行 typo）
+- ❌ ~~"读取了解上下文"~~ → ✅ spawn researcher 系统化调研
+
+#### 强制理由声明
+
+**每次决定不 spawn 时，必须在响应开头用一句话说明理由**，格式：
+
+> 不 spawn 理由：例外 #N [具体原因]
+
+如果一句话写不出像样的理由 → 说明应该 spawn，立刻改正。
+
+写理由的目的不是仪式感，而是**让"自己做"成为可见的决策**。决策可见，才能被纠正。
+
+#### 触发关键词（强制 spawn）
+
+只要用户的 prompt 出现以下**任意一个**词或类似意图，**直接 spawn**，不要犹豫：
+
+**实现类**：
+- 实现 / implement / 开发 / develop / 创建 / create / 添加 / add / 构建 / build
+
+**修改类**：
+- 修复 / fix / 调试 / debug / 改 / change / 更新 / update / 升级 / upgrade
+
+**优化类**：
+- 重构 / refactor / 优化 / optimize / 性能 / performance / 清理 / cleanup
+
+**调研类**（新增，不再是例外）：
+- 调研 / research / 分析 / analyze / 查 / find / 找 / search / 看 / read / 列出 / list / 梳理 / review
+
+**测试类**：
+- 测试 / test / 验证 / verify / 检查 / check / 审查 / audit
+
+#### 最小 Agent 模式
+
+不需要每次都开完整 pipeline。简单任务用单个 Agent 就行：
+
+```javascript
+// 单个 Agent 即可
+Agent({
+  description: "修复 X bug",
+  subagent_type: "coder",
+  prompt: "具体任务描述，包含文件路径和修改要求..."
+})
+```
+
+复杂任务才 spawn 多个 Agent 或 pipeline（参考下方 Pipeline Templates）。
+
+#### 自检流程（接到任务后必走）
+
+1. 这是不是 5 条例外里的？→ 是 → 直接做（写出理由）
+2. 不是 → spawn Agent。多文件改动 → 多个 Agent；调研 → researcher；测试 → tester；最不济单个 coder
+
+**违规判定**：一次响应里执行了 Edit/Write 修改 ≥ 2 个文件 + 没写"不 spawn 理由"=违规。
+
+## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
+
+- All operations MUST be concurrent/parallel in a single message
+- Use Claude Code's Task tool for spawning agents, not just MCP
+
+**Mandatory patterns:**
+- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
+- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL terminal operations in ONE Bash message
+
+---
+
+## Swarm Orchestration (AGGRESSIVE PARALLELISM)
+
+**核心原则：成本不是考量因素，响应速度和覆盖面是唯一目标。**
+
+- **默认开多个 Agent，不要节约** — 只要任务不是"单行修改/问候语"，一律 spawn swarm
+- **宁滥勿缺** — 拿不准就开 pipeline；多开一个 reviewer/tester 的边际成本 << 漏掉问题的代价
+- **永远并行，不要串行** — 所有能并行的 Agent 在 ONE message 里同时 spawn
+- **不要自己直接做复杂任务** — 主线程只负责协调，实现/调研/测试/审查全部委托
+
+### Auto-Start Swarm Protocol
+
+#### 不确定是否需要 Pipeline？调用 pipeline_suggest
+
+如果你不确定当前任务是否需要启动 swarm pipeline，可以调用 MCP 工具 `pipeline_suggest` 获取建议：
+
+```typescript
+// 通过 MCP 调用（如果可用）
+pipeline_suggest({
+  task_description: "修复用户登录时的 session 过期问题",
+  file_count: 5,
+  is_bug_fix: true
+})
+
+// 返回
+{
+  should_invoke: true,
+  pipeline_type: "bug_fix",
+  pipeline_code: "Task({ subagent_type: 'researcher', name: 'investigator', ... })\n...",
+  reason: "Bug 修复任务建议使用 Pipeline（调查 → 修复 → 验证）"
+}
+```
+
+**决策逻辑**：
+- `file_count >= 3` OR `is_new_feature` OR `is_refactor` OR `is_bug_fix` OR `is_performance` → 建议使用 Pipeline
+- 返回可直接复制的 Task 调用代码
+
+**10 种内置模板**：
+- Bug Fix：investigator → fixer → verifier（3 agents）
+- Feature：analyst → designer → developer → tester → reviewer（5 agents）
+- Refactor：safety-net → planner → refactorer → verifier（4 agents）
+- Investigation：reproducer → analyst（2 agents）
+- Performance：benchmarker → analyst → optimizer → verifier（4 agents）
+- BMAD Feature：product-analyst → architect → developer → qa → reviewer（5 agents，完整产品开发）
+- Harness Safe Refactor：safety-net → analyzer → planner → executor → validator（5 agents，先织安全网再动代码）
+- Harness Debug：reproducer → tracer → root-cause → fixer → verifier（5 agents，系统化排查）
+- Migration：impact-analyst + safety-net → planner → migrator → verifier（5 agents，技术迁移）
+- Security Audit：threat-modeler → code-auditor → fixer → verifier（4 agents，安全审计）
+
+---
+
+When the user requests a complex task (multi-file changes, feature implementation, refactoring), **immediately execute this pattern in a SINGLE message:**
+
+```javascript
+// STEP 1: Spawn NAMED agents concurrently — all in ONE message
+// Each agent knows WHO to message next in the pipeline
+Task({
+  prompt: "Research requirements and codebase. SendMessage findings to 'architect' when done.",
+  subagent_type: "researcher", name: "researcher", run_in_background: true
+})
+Task({
+  prompt: "Wait for research from 'researcher'. Design implementation. SendMessage design to 'coder'.",
+  subagent_type: "planner", name: "architect", run_in_background: true
+})
+Task({
+  prompt: "Wait for design from 'architect'. Implement the solution. SendMessage code paths to 'tester'.",
+  subagent_type: "coder", name: "coder", run_in_background: true
+})
+Task({
+  prompt: "Wait for implementation from 'coder'. Write tests. SendMessage results to 'reviewer'.",
+  subagent_type: "tester", name: "tester", run_in_background: true
+})
+Task({
+  prompt: "Wait for test results from 'tester'. Review code quality and security. Report findings.",
+  subagent_type: "reviewer", name: "reviewer", run_in_background: true
+})
+
+// STEP 2: Kick off the pipeline
+SendMessage({ to: "researcher", summary: "Start research", message: "[task description and context]" })
+
+// Pipeline flow via SendMessage:
+// researcher ──→ architect ──→ coder ──→ tester ──→ reviewer
+```
+
+### Agent Routing (Anti-Drift)
+
+| Code | Task | Agents |
+|------|------|--------|
+| 1 | Bug Fix | researcher, coder, tester, reviewer |
+| 3 | Feature | researcher, architect, coder, tester, reviewer |
+| 5 | Refactor | researcher, architect, refactor-specialist, tester, reviewer |
+| 7 | Performance | researcher, coder, tester, reviewer |
+| 9 | Investigation | tester, researcher |
+
+**All codes: hierarchical/specialized (anti-drift)**
+
+### Task Complexity Detection
+
+**ALWAYS INVOKE SWARM**（默认行为，不要犹豫）：
+- 任何涉及代码变更的任务
+- 任何需要理解现有代码的任务
+- 新功能实现（无论大小）
+- Bug 修复（除 1-2 行 typo）
+- 重构、性能优化、架构调整
+- 调研、技术选型、方案对比
+- 测试编写、代码审查
+- 数据库变更、安全相关改动
+
+**SKIP SWARM 仅限**：
+- 单行 typo / 格式修正
+- 纯粹的问答（"这个函数做什么？"）
+- 查看文件内容（Read 即可）
+
+当用户说"调研 X"、"实现 Y"、"修复 Z"时，**不要问"要不要用 swarm"，直接开**。
+
+### Parallel Research Pattern
+
+调研类任务：**同时 spawn 多个 researcher 并行搜索不同方面**，而不是让一个 researcher 串行查。
+
+```javascript
+// 例：调研一个新框架
+Task({ subagent_type: "researcher", name: "docs-reader", prompt: "Read official docs, report API surface", run_in_background: true })
+Task({ subagent_type: "researcher", name: "code-explorer", prompt: "Find existing uses in codebase", run_in_background: true })
+Task({ subagent_type: "researcher", name: "comparator", prompt: "Compare with alternatives", run_in_background: true })
+```
+
+### Phase 文档产出（强制）
+
+每个 pipeline 阶段的 Agent 都 **MUST** 在项目 `docs/` 下生成对应阶段文档，作为可追溯的执行产物。
+
+**目录约定（自动创建，不存在则 mkdir -p）**：
+
+```
+docs/
+├── requirements/   # 需求阶段：需求分析、问题发现、范围定义、复现报告
+├── design/         # 设计阶段：架构设计、详细设计、ADR
+├── implementation/ # 编码阶段：改造点分析、详细执行计划、变更日志
+├── testing/        # 测试阶段：测试报告、回归记录、性能基线
+├── review/         # 审查阶段：代码审查、安全审计、根因分析
+└── operations/     # 运维阶段：迁移手册、回滚预案
+```
+
+**命名规范**：`<phase-prefix>-<topic>-<yyyymmdd-hhmm>.md`，例如：
+- `docs/requirements/feature-requirements-20260514-1430.md`
+- `docs/design/feature-architecture-20260514-1500.md`
+- `docs/implementation/feature-plan-20260514-1530.md`
+- `docs/testing/feature-test-report-20260514-1700.md`
+- `docs/review/feature-review-20260514-1730.md`
+
+**强制规则**：
+- Pipeline 中**每个 Agent 必须先写文档再做后续操作**（设计师先写架构再交给开发，开发先写计划再写代码）
+- SendMessage 给下游时**必须包含文档路径**，下游 Agent 必须先 Read 该文档
+- 文档要可独立阅读：包含上下文、决策、依据、产出，不依赖会话历史
+- 每个 pipeline 模板（pipeline_suggest 工具返回的 Task 调用）已经内置了文档输出指令，**不要省略**
+
+### Skill 方法论调用
+
+当任务涉及特定领域时，**主动调用 MCP 工具 `skill_invoke` 获取方法论指导**：
+
+```javascript
+// 重构任务 → 获取 Harness 安全重构方法论
+skill_invoke({ skill_id: "official-harness-legacy", reason: "需要安全重构指导" })
+
+// 调试任务 → 获取系统化调试方法论
+skill_invoke({ skill_id: "official-debug-methodology", reason: "需要调试方法论" })
+
+// 性能优化 → 获取性能优化方法论
+skill_invoke({ skill_id: "official-performance-optimization", reason: "需要性能优化指导" })
+
+// 安全审计 → 获取安全加固方法论
+skill_invoke({ skill_id: "official-security-hardening", reason: "需要安全审计指导" })
+
+// 代码审查 → 获取审查方法论
+skill_invoke({ skill_id: "official-code-review", reason: "需要代码审查指导" })
+
+// 不确定用哪个 → 先列出所有可用 skill
+skill_list({ keywords: ["debug"] })
+```
+
+**触发时机**：在 spawn swarm 之前或同时调用，将方法论内容传给对应的 Agent 作为指导。
+
+## Swarm Configuration & Anti-Drift
+
+### Anti-Drift Coding Swarm (PREFERRED DEFAULT)
+
+- ALWAYS use hierarchical topology for coding swarms
+- 不要为了"省 token"合并步骤 — 每个 Agent 都有独立的 context window，拆开更准确
+- Use specialized strategy for clear role boundaries
+- Keep task cycles short with verification gates
+- Each agent MUST end with SendMessage to the next agent in the chain
+- Do NOT implement code directly when a swarm is active — delegate to the coder step
+- Do NOT collapse a multi-step swarm into a single Task call
+
+## 项目概述
+
+本仓库是 Claude Code 工程化工具集的研发工作区。源码分布在 `src/` 下的以下模块：
+
+- `src/core/` — 核心基础设施：`types.ts`（`ForgeEvent`、`HookResult` 等跨层契约）、`config.ts`、`constants.ts`、`storage/`（SQLite + `schema.sql`）、`ai/`（ClaudeProvider）、`utils/`（logger / lru-cache / token-tracker / path 等）
+- `src/engine/` — 规则与治理引擎：`dsl/`（types / parser / compiler / runtime）、`rule-engine.ts`、`context-builder.ts`、`evidence-store.ts`、`agent-router.ts`、`experiment-router.ts`、`recommender.ts`、`conventions/*.yaml`
+- `src/capability/` — 方法论执行核心：`methodology-registry.ts`、`methodology-planner.ts`、`execution-manager.ts`、`executor/`（foreground / background / orchestrator / stream-parser / worker-auth-probe）、`methodologies/*.yaml`
+- `src/daemon/` — 守护进程：`server.ts`、`router.ts`、`lifecycle.ts`、`event-parser.ts`、`idle-detector.ts`、`idle-trigger.ts`、`auto-disable-scheduler.ts`、`methodology-pending-queue.ts`、`routing-observer.ts`、`routing-state.ts`、`handlers/`（pre-tool-use / post-tool-use / user-prompt / stop / history-exporter / methodology-formatter）、`services/`（task-segmenter）
+- `src/cli/` — CLI 入口与子命令：`init/` + `commands/`（claudemd / config / daemon / init / logs / menu / rules / skills / stats / status / template）
+- `src/skills/` — Skill 注册与匹配（registry / matcher / semantic-matcher / official-skills）
+- `src/claudemd/` — CLAUDE.md 生成与维护（tech-detector / claudemd-generator / convention-extractor / persona-manager / resume-manager）
+- `src/templates/` — 项目模板（`*.yaml` + `template-manager.ts`）
+- `src/hooks/` — Claude Code Hook shell 脚本（构建时复制到 `dist/hooks/`）
+- `src/web/` — 嵌入式 Web 服务器（Express + 静态资源 + auth/ssrf 中间件）
+- `web/` — Web 前端（React + TanStack Query + Vite）
+
+## 技术栈
+
+- 运行时：Node.js
+- 语言：TypeScript（`strict: true`）
+- 测试：Vitest
+- 构建：`tsc`（后端）+ Vite（前端）
+- 存储：SQLite（`better-sqlite3`）
+- Web：Express（后端）+ React + TanStack Query（前端）
+
+## 架构要点
+
+- 架构以声明式治理为核心：Convention YAML + DSL 表达式驱动规则引擎，而非命令式编排
+- `src/core/types.ts` 承载 `ForgeEvent`、`HookResult` 等跨层类型契约；`src/core/storage/sqlite.ts` 直接封装 SQL（文件头注释明确写了 `No repository pattern, no base class — just direct SQL in one file`），不要误以为存在 Repository 层
+- `src/engine/dsl/` 由 types / parser / compiler / runtime 四件组成；规则模型、事件模型、DSL 类型的变更属于高影响改动，**类型契约先行**收敛后再动实现
+- **决策分级：`block` / `confirm` / `warn` / `allow` 四档**（见 `src/engine/rule-engine.ts` 的 level 优先级定义）。`block` 级在 `pre-tool-use.ts` 中会硬阻断工具执行，不是"仅告知"。实际行为以 `rule-engine.ts` 为准
+- `src/capability/` 是方法论执行核心：planner 负责编排 phase，executor 分前台/后台两条路径，orchestrator 负责推进。daemon **无法主动推送消息**，前台方法论的兜底路径是 Stop → pending 队列 → 下一次 UserPromptSubmit 消费
+
+### 目录依赖约束
+
+- `core` 不反向依赖业务层
+- `engine` 可依赖 `core`
+- `capability` 可依赖 `core`、`engine`
+- `skills` / `templates` / `claudemd` 可依赖 `core`（必要时依赖 `engine`）
+- `daemon` 可依赖 `core`、`engine`、`capability`、`skills`
+- `cli` 是装配层：组合上述模块，不把规则/执行核心逻辑塞回命令实现
+- `web` 作为服务壳：HTTP 路由只做参数收敛与响应序列化，不在路由里写业务逻辑
+
+### 存储
+
+- 单一运行时数据库：`~/.claude-forge/data.db`（由 `FORGE_PATHS.database()` 统一返回），存放 events / sessions / routing_events / methodology_executions / phase_executions / tasks / injections / decisions / token_usage 等
+- Schema 通过 `src/core/storage/schema.sql` 初始化；增量迁移走 `runMigrations()`，使用幂等 `ALTER TABLE` + `PRAGMA table_info` 检测
+- 索引见 `src/core/storage/performance-indexes.sql`
+
+## 开发规范
+
+### 构建与测试
+
+```bash
+# 类型检查
+npx tsc --noEmit
+
+# 后端构建
+npx tsc
+
+# 前端构建
+cd web && npm run build
+
+# 测试
+npm run test
+
+# 完整构建（含 hook 脚本拷贝）
+npm run build
+```
+
+### Convention YAML 规范
+
+- Convention 配置统一使用 YAML（见 `src/engine/conventions/*.yaml`）
+- 每个 Convention 文件通常包含 `forbidden`（禁止规则）与 `escalation`（升级策略）段落
+- 规则的 `when` 条件使用 DSL 表达式，由 `src/engine/dsl/parser.ts` + `compiler.ts` 处理
+- 变更后需运行项目测试或对应 demo 脚本验证加载与解析
+
+### 边界层类型收敛
+
+- `src/daemon/handlers/`、`src/web/` 路由、`src/hooks/` 监听器禁止未经收敛直接访问深层字段
+- 处理动态数据时优先使用显式类型守卫、局部变量收窄或小范围断言
+- 不得把 `any` 或未收窄的 `unknown` 扩散到 `engine`、`core` 等核心层
+
+### 守护进程事件推送
+
+- SSE 推送按需触发，不要在高频事件上无条件推送完整快照
+- 会话结束、进程启动、异常恢复路径都要检查过期任务与残留索引
+- daemon 不能主动向 Claude 主会话推送消息；跨轮传递必须走 pending 队列 + 下一次 Hook 事件消费
+
+### 注意
+
+- 用户的全局 `~/.claude/CLAUDE.md` 里有一段 "Pipeline 模块架构约定（claude-forge）"，列出 `src/pipeline/` 下六个文件（`completion-gate.ts`、`completion-detector.ts`、`artifact-validator.ts`、`dynamic-node-executor.ts`、`dynamic-pipeline-repository.ts`、`pipeline/index.ts`）。**这些文件在当前代码库中不存在**，属于未落地规划。请忽略该段约束，以本项目 CLAUDE.md 为准。
+<!-- forge:end-claudemd-auto -->
+
+<!-- forge:convention-start:custom-claude-forge -->
+## 项目规范约束：claude-forge 综合规范 (v1.2.0)
+
+### 来自 Harness Engineering 安全重构规范
+
+**核心理念：先织安全网，再动代码**
+
+**TypeScript 专项原则**
+
+- 严格启用 `strict: true`，禁止 `any`
+- 模块边界用 `interface`，内部用 `type`
+- 统一 `async/await`，禁止混用 Promise 链
+- 错误处理必须显式，不得静默吞异常
+- 禁止硬编码敏感信息
+
+## 架构决策记录
+
+_架构决策将在此记录_
+
+<!-- forge:convention-end:custom-claude-forge -->
+
+<!-- forge:resume-begin:99112f2d-5b13-46f9-b39c-44429ea99302 -->
+```forge-resume-body
+## 上次工作续接
+
+⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**
+
+**上次在做**:
+- 当前的claude.md看起来很长，这个会不会导致理解或者指令偏差呢？
+
+**上次活跃**: 刚刚
+
+**会话行为**: 工具调用 5194 次 | Agent 委托 108 次 (Explore, coder, feature-developer) | Skill 调用 11 次
+
+_生成时间: 2026-05-15T07:10:05.173Z_
+```
+
+_生成时间: 2026-05-15T07:10:05.203Z_
+<!-- forge:resume-end:99112f2d-5b13-46f9-b39c-44429ea99302 -->