@winspan/claude-forge 8.54.4 → 9.2.0

package/README.md

@@ -24,7 +24,7 @@ daemon 以 Unix socket 形式与 Claude Code 的 Hook 脚本通信。每次 `Use
 Agent 还可以通过 MCP 工具 `skill_invoke` 按需获取 Skill 的完整方法论内容（需先运行 `cf mcp register`）。
 
 ### 4. Web 管理后台
-`claude-forge daemon start` 默认在 `http://127.0.0.1:<port>`（默认端口 `3721`，可在 `~/.claude-forge/config.yaml` 的 `web.port` 修改）开放一个 React 管理后台，覆盖：会话浏览、事件流、执行追踪、Agent/Skill 编辑、AI 配置、实时 SSE 日志。
+`claude-forge daemon start` 默认在 `http://127.0.0.1:<port>`（默认端口 `3721`，可在 `~/.claude-forge/config.yaml` 的 `web.port` 修改）开放一个 React 管理后台，覆盖：会话浏览、事件流、执行追踪、Agent/Skill 编辑、实时 SSE 日志。（AI Provider 配置面在 spec `0902` 子 spec D R-C 永久下线，AI 流程改走本地 `claude` CLI 订阅）。
 
 ### 5. 长跑稳定性
 - **自动同步**：daemon 启动时自动将内置 hook 脚本同步到 `~/.claude/hooks/`、将内置 skill 同步到 `~/.claude/skills/`，防止 npm 升级后用户副本陈旧
@@ -53,19 +53,18 @@ npm install -g @winspan/claude-forge
 # 2. 初始化（把 hook 脚本装到 ~/.claude/hooks/）
 cf init
 
-# 3. 配置 AI Provider（可选）
-cf config
-
-# 4. 启动 daemon
+# 3. 启动 daemon
+#    （AI Provider 配置已下线 — 见 spec 0902 子 spec D R-C，
+#     AI 流程走本地 `claude` CLI 订阅，不再需要 daemon 持 API key）
 cf daemon start
 
-# 5. 打开管理后台（默认 3721，可在 ~/.claude-forge/config.yaml 修改 web.port）
+# 4. 打开管理后台（默认 3721，可在 ~/.claude-forge/config.yaml 修改 web.port）
 open http://127.0.0.1:3721
 
-# 5.5（可选）注册 MCP 服务器（让 Agent 能动态调用 Skill）
+# 4.5（可选）注册 MCP 服务器（让 Agent 能动态调用 Skill）
 cf mcp register
 
-# 6. （可选）查看架构图
+# 5. （可选）查看架构图
 open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / web 打开
 ```
 
@@ -79,7 +78,7 @@ open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / we
 |---|---|
 | `cf init` | 初始化 hook 脚本到 `~/.claude/hooks/` |
 | `cf daemon {start,stop,status}` | daemon 生命周期 |
-| `cf config` | AI Provider 配置（API key、base_url、model） |
+| `cf config {show,path,edit,list,get,set}` | 配置管理 — runtime feature flags (forge_config 表) + YAML view/edit。**`ai.*` / `skill_matching.*` 字段已在 spec [`0902`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md) 子 spec D R-D 从 schema 中彻底删除**（AI 流程改走 `claude` CLI 子进程，不再读 `ANTHROPIC_API_KEY`）；老 `~/.claude-forge/config.yaml` 中的残留 `ai:` / `skill_matching:` 会被静默丢弃，daemon 启动时 warn 一次提示用户清理 |
 | `cf status` | 当前 daemon + Web + 存储概况 |
 | `cf logs [--tail]` | 查看 daemon 日志 |
 | `cf stats` | 近期 intent / 路由统计 |
@@ -92,7 +91,8 @@ open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / we
 | `cf trace <commit>` | 查看 commit 关联的 session |
 | `cf executions {list,show}` | 浏览历史执行记录 |
 | `cf mcp` | MCP 配置 |
-| `cf claudemd` | 生成/更新项目 CLAUDE.md |
+| `cf claudemd` | 生成/更新项目 CLAUDE.md（通过 `claude` CLI 子进程 + `claudemd-writer` agent，**不再读 `ANTHROPIC_API_KEY`**） |
+| `cf knowledge {init,build,update,query,list,audit,clean,rollback}` (alias: `cf kb`) | 项目知识库（`.forge-knowledge/`）。`init` / `build` / `update` 通过 `claude` CLI 子进程 + `knowledge-builder` agent，**不再读 `ANTHROPIC_API_KEY`**；query / list / audit / clean / rollback 纯本地 |
 | `cf template` | 模板管理 |
 | `cf menu` | 交互式菜单（推荐入口） |
 
@@ -106,18 +106,155 @@ open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / we
 
 主要页面：
 
-- `/dashboard` — 总览
-- `/sessions` — 会话列表 + 详情
+- `/health` — 整体健康度（默认入口）
 - `/tasks` — 任务列表 + 详情
-- `/events` — Hook 事件流
-- `/skills` — 在线查看 `~/.claude/skills/*.md`
-- `/ai-config` — 切换 AI Provider / 测试连接
-- `/reports` — 周报与统计
+- `/context` — Knowledge / Skills / Agents 浏览（旧 `/skills` `/knowledge` redirect 进来）
+- `/violations` — 治理违规记录
+- `/settings` — 主题 / 关于（**AI 配置面已在 spec `0902` 子 spec D R-C 删除**）
+
+> 老 v2/v3 URL（`/sessions` `/events` `/dashboard` `/pipeline` `/resources` `/skills` `/knowledge`）会自动 redirect 到新位置。`/ai-config` 老 URL 在 R-C 永久下线，落 NotFound。
 
 所有列表支持搜索 + JSON/CSV 导出。
 
 ---
 
+## Skill Distillation
+
+claude-forge 内置 **12 个开箱即用的 distilled skill**（已蒸馏自上游优秀开源 skill 仓库），首次 `cf daemon start` 时自动同步到 `~/.claude/skills/`，无需任何配置。
+
+```bash
+# 查看本机已安装的 distilled skills
+ls ~/.claude/skills/distilled-*.md
+
+# 同步触发（通常 daemon 启动时已经做了，无需手动）
+cf daemon restart
+
+# 列出所有 skill（distilled + user-owned）
+cf skills list
+
+# 调用某个 distilled skill 看完整方法论
+cf skills invoke distilled-systematic-debugging
+```
+
+### 自己蒸馏额外的 skill
+
+蒸馏入口已收敛到 **Web 仪表盘**：打开 `http://127.0.0.1:3721/context?tab=distill` →
+点【开始蒸馏】。daemon 通过本地 `claude` CLI 子进程跑（`child_process.spawn` +
+`-p --agent skill-distiller --bare --output-format stream-json`），**走你已经
+付费的 Claude Code 订阅 / OAuth keychain**，daemon 自身不持
+`ANTHROPIC_API_KEY`。
+
+**前置条件**：本机已安装 `claude` CLI（`brew install claude` 或
+`npm i -g @anthropic-ai/claude-code`）。Web 仪表盘顶部会自动检测并显示
+binary 路径（`claude CLI: ✓ /opt/homebrew/bin/claude`）。未安装时按钮会被
+disable + 显示安装提示。
+
+蒸馏流程（单次按钮点击发生的事情）：
+
+1. daemon spawn `claude -p --agent skill-distiller …`
+2. agent 读 upstream skill markdown → 按 D1-D5 维度自评分（0-5）
+3. 评分 < 3 → 输出 `---SKIP---` envelope（含 score + rationale，UI 显示为 skipped）
+4. 评分 ≥ 3 → 输出 `---SKILL---` envelope（含通用化 markdown body）
+5. daemon `parseSkillBlock()` 提取 body → `project-anchor-guard` 自查 → 写入
+   `src/skills/distilled/distilled-xxx.md` + NOTICE 归因
+
+> 设计 spec：[`docs/design/2026-05-28/1851-distill-via-claude-cli-shellout-spec.md`](docs/design/2026-05-28/1851-distill-via-claude-cli-shellout-spec.md)
+
+### 自定义 / 覆盖建议
+
+- **不要直接编辑 `~/.claude/skills/distilled-*.md`** —— daemon 重启时若 hash 不一致会跳过覆盖（保护你的改动），但版本升级时新 skill 不会自动应用，需手动 diff
+- **要做项目级自定义**：另存为 `my-<name>.md` 或 `team-<name>.md`，`my-*` 前缀不在内置 sourceSet 内，永不被覆盖
+- 想完全替换某个 distilled skill：删掉它然后 `cf daemon restart`，会按当前最新版本重新生成
+
+更多细节见 [DEVELOPMENT.md § Skill 蒸馏](./DEVELOPMENT.md#skill-蒸馏) 与 [§ skill-distiller agent 使用说明](./DEVELOPMENT.md#skill-distiller-agent-使用说明)。
+
+---
+
+## CLAUDE.md 生成（`cf claudemd init/update`）
+
+`cf claudemd init` / `cf claudemd update` 现在通过本地 `claude` CLI 子进程跑 ——
+daemon spawn `claude -p --agent claudemd-writer --bare`，agent 读取项目技术栈 +
+目录树 + persona + 已有 conventions（由 host 通过 stdin 注入），输出包在
+`---CLAUDEMD---...---END---` envelope 内的 markdown body。
+
+**前置条件**：本机已安装 `claude` CLI（`brew install claude` 或
+`npm i -g @anthropic-ai/claude-code`）—— 与 Skill Distillation 相同的 install hint。
+
+**不再依赖** `ANTHROPIC_API_KEY` —— 走你已经付费的 Claude Code 订阅 / OAuth
+keychain，daemon 自身不持 API key。
+
+更多细节见 [DEVELOPMENT.md § CLAUDE.md 生成与维护](./DEVELOPMENT.md#claudemd-生成与维护)
+与 [§ claudemd-writer agent 使用说明](./DEVELOPMENT.md#claudemd-writer-agent-使用说明)。
+
+> 设计 spec：[`docs/design/2026-05-29/0902-ai-config-removal-master-spec.md`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md) 子 spec A
+
+---
+
+## 项目知识库（`cf knowledge`）
+
+`cf knowledge init` / `cf knowledge build` / `cf knowledge update` 现在通过本地
+`claude` CLI 子进程跑 —— host 起 `claude -p --agent knowledge-builder --bare`
+子进程，agent 每个 KB page 输出一个 `---KB---...---END---` envelope，host 解析
+后写入 `.forge-knowledge/modules/*.md` + `.forge-knowledge/<cross-module>.md` +
+`.meta.json` + `repo-map.json`。
+
+**前置条件**：本机已安装 `claude` CLI（`brew install claude` 或
+`npm i -g @anthropic-ai/claude-code`）—— 与 Skill Distillation / CLAUDE.md
+生成相同的 install hint。
+
+**不再依赖** `ANTHROPIC_API_KEY` —— 走你已经付费的 Claude Code 订阅 / OAuth
+keychain，daemon 自身不持 API key。
+
+```bash
+# 首次构建（含 git hook 安装）
+cf knowledge init
+
+# 增量更新（基于 git diff）
+cf knowledge update
+
+# 查询（纯本地 keyword + repo-map，不需要 claude CLI）
+cf knowledge query "daemon socket"
+```
+
+**注意**：`cf knowledge query --strategy rerank`（AI 重排序）已在 Spec 2 Stage
+B（commit `797326f8`）下线 —— 现在仅 keyword + repo-map 检索。
+
+更多细节见 [DEVELOPMENT.md § knowledge-builder agent 使用说明](./DEVELOPMENT.md#knowledge-builder-agent-使用说明)。
+
+> 设计 spec：[`docs/design/2026-05-29/0902-ai-config-removal-master-spec.md`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md) 子 spec B
+
+---
+
+## AI 辅助 Patch 预览（Web `POST /api/patch/preview`）
+
+Web 仪表盘 / 外部脚本可以 `POST` 一段 `{ targetType, targetName, recommendation,
+rationale }` 到 `/api/patch/preview`，daemon 会通过本地 `claude` CLI 子进程跑
+`claude -p --agent patch-applier --bare`，agent 输出 PATCH（unified diff）或
+NOPATCH（连同 reason）envelope，host 解析后回 JSON。
+
+**前置条件**：本机已安装 `claude` CLI（`brew install claude` 或
+`npm i -g @anthropic-ai/claude-code`）—— 与 Skill Distillation / CLAUDE.md
+生成 / 项目知识库相同的 install hint。
+
+**不再依赖** `ANTHROPIC_API_KEY` —— 走你已经付费的 Claude Code 订阅 / OAuth
+keychain，daemon 自身不持 API key。
+
+⚠️ **响应字段 BREAKING（R-A → R-B）**：R-A 阶段 `/api/patch/preview` 返回
+`{after, summary, risk}`；R-B 之后改为 discriminated union
+`{patch} | {noPatch, reason}`。HTTP 错误码也细分为 `499`（cancel）/
+`504`（timeout）/ `500`（missing / exit / unknown）。前端 / 脚本如果有调用
+该端点，必须按新 schema 适配。
+
+> 当前 `web/src/` 内置前端尚未集成 patch UI（`grep api/patch web/src` = 0
+> 命中）。如未来加 Web 前端 patch 预览界面，参照 spec C 「前端处理」段落。
+> `POST /api/patch/apply` 路径未变（始终是纯 fs write + backup，不走 LLM）。
+
+更多细节见 [DEVELOPMENT.md § patch-applier agent 使用说明](./DEVELOPMENT.md#patch-applier-agent-使用说明)。
+
+> 设计 spec：[`docs/design/2026-05-29/0902-ai-config-removal-master-spec.md`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md) 子 spec C
+
+---
+
 ## Project Map
 
 | 模块 | 一句话职责 |
@@ -128,6 +265,7 @@ open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / we
 | `src/web/` | Express + SSE 后端 + React 仪表盘 |
 | `src/cli/` | claude-forge / cf 命令入口 |
 | `src/hooks/` | bash 脚本，与 daemon 通过 Unix socket 通信 |
+| `src/knowledge/` | v9.3 项目知识库（cf knowledge build/update/query/audit/list/clean/rollback），含 5 跨模块页、3 个 MCP 工具（knowledge_query / knowledge_get_page / repo_map_lookup）。build 通过本地 `claude` CLI 子进程 + `knowledge-builder` agent（spec [`0902`](docs/design/2026-05-29/0902-ai-config-removal-master-spec.md) 子 spec B），不再读 `ANTHROPIC_API_KEY`。**注**：AI rerank 检索路径已在 Spec 2 Stage B（commit `797326f8`）下线，仅保留 keyword + repo-map 查询。 |
 
 ## 贡献
 

package/dist/catalogs/agents.json

@@ -0,0 +1,72 @@
+[
+  {
+    "name": "claudemd-writer",
+    "description": "",
+    "source_file": ".claude/agents/claudemd-writer.md"
+  },
+  {
+    "name": "coder",
+    "description": "Standard BMAD implementation agent for spec-driven work in well-tested modules. Use when a spec exists at docs/design/**/*-spec.md AND the target module has >=50% test coverage (or is a brand new modu",
+    "source_file": ".claude/agents/coder.md"
+  },
+  {
+    "name": "decision-maker",
+    "description": "Lightweight decision agent for prompts the daemon flagged as decision-worthy. NOT a planner (no implementation plan) — produces a 1-page decision document covering Options + Recommendation + Open Ques",
+    "source_file": ".claude/agents/decision-maker.md"
+  },
+  {
+    "name": "doc-reviewer",
+    "description": "Read-only code, spec, or document analysis. Returns a structured report. Use when user asks to review/analyze/compare/audit existing code or docs WITHOUT modifying anything. Triggers on \"review this\",",
+    "source_file": ".claude/agents/doc-reviewer.md"
+  },
+  {
+    "name": "harness-debug-full",
+    "description": "Unknown or intermittent bug — reproduce, then find root cause, then fix, then verify. Use when symptoms are described but root cause is NOT known, or when behavior is intermittent / random / flaky / \"",
+    "source_file": ".claude/agents/harness-debug-full.md"
+  },
+  {
+    "name": "harness-hotfix",
+    "description": "Known-cause bug fixer with safety-net discipline. Use when the root cause of a bug is already identified AND the affected module has <50% test coverage. Triggers on \"修复 X bug\", \"hotfix\", \"urgent fix\",",
+    "source_file": ".claude/agents/harness-hotfix.md"
+  },
+  {
+    "name": "hybrid-feature-with-safety",
+    "description": "New feature that touches legacy low-coverage code. Use when adding new functionality that requires modifying files in modules with <50% test coverage. Triggers on \"新功能 + 改老代码\", \"add X to legacy module",
+    "source_file": ".claude/agents/hybrid-feature-with-safety.md"
+  },
+  {
+    "name": "knowledge-builder",
+    "description": "",
+    "source_file": ".claude/agents/knowledge-builder.md"
+  },
+  {
+    "name": "patch-applier",
+    "description": "",
+    "source_file": ".claude/agents/patch-applier.md"
+  },
+  {
+    "name": "planner",
+    "description": "Spec writer for non-trivial work. Research current state, propose 2-3 options, recommend one, write spec to docs/design/, then STOP. Use for BMAD Phase 1. Triggers on \"write a spec\", \"plan this\", \"BMA",
+    "source_file": ".claude/agents/planner.md"
+  },
+  {
+    "name": "refactor-specialist",
+    "description": "Behavior-preserving restructure of low-coverage code. Use when user asks to refactor, restructure, clean up, simplify, or extract from a module with <50% test coverage. Triggers on \"重构\", \"refactor\", \"",
+    "source_file": ".claude/agents/refactor-specialist.md"
+  },
+  {
+    "name": "skill-distiller",
+    "description": "",
+    "source_file": ".claude/agents/skill-distiller.md"
+  },
+  {
+    "name": "task-boundary-classifier",
+    "description": "",
+    "source_file": ".claude/agents/task-boundary-classifier.md"
+  },
+  {
+    "name": "verify-agent",
+    "description": "Live runtime verifier. Runs the actual app/CLI/browser, drives the changed surface, probes edges, returns PASS/FAIL/BLOCKED/SKIP with evidence. Use after implementation and before commit. Triggers on ",
+    "source_file": ".claude/agents/verify-agent.md"
+  }
+]

package/dist/catalogs/skills.json

@@ -0,0 +1,194 @@
+[
+  {
+    "name": "distilled-api-design",
+    "description": "Distilled IT-universal skill: api-design (score 4.5/5)",
+    "source_file": "src/skills/distilled/distilled-api-design.md",
+    "keywords": [
+      "api",
+      "design",
+      "api design",
+      "api 设计",
+      "restful",
+      "openapi",
+      "接口设计"
+    ]
+  },
+  {
+    "name": "distilled-architecture-decision",
+    "description": "Distilled IT-universal skill: architecture decision records (portable, hand-rewritten 2026-05-27)",
+    "source_file": "src/skills/distilled/distilled-architecture-decision.md",
+    "keywords": [
+      "architecture",
+      "adr",
+      "decision",
+      "design",
+      "record",
+      "architecture decision",
+      "架构决策",
+      "技术选型"
+    ]
+  },
+  {
+    "name": "distilled-creator",
+    "description": "Distilled IT-universal skill: skill-creator (score 3.5/5)",
+    "source_file": "src/skills/distilled/distilled-creator.md",
+    "keywords": [
+      "creator",
+      "skill"
+    ]
+  },
+  {
+    "name": "distilled-db-schema-design",
+    "description": "Distilled IT-universal skill: db-schema-design (score 4.5/5)",
+    "source_file": "src/skills/distilled/distilled-db-schema-design.md",
+    "keywords": [
+      "db",
+      "schema",
+      "design",
+      "database",
+      "数据库设计",
+      "migration",
+      "迁移",
+      "sql"
+    ]
+  },
+  {
+    "name": "distilled-defi-amm-security",
+    "description": "Distilled IT-universal skill: defi-amm-security (score 3.5/5)",
+    "source_file": "src/skills/distilled/distilled-defi-amm-security.md",
+    "keywords": [
+      "defi",
+      "amm",
+      "security"
+    ]
+  },
+  {
+    "name": "distilled-executing-plans",
+    "description": "Distilled IT-universal skill: executing-plans (score 4/5)",
+    "source_file": "src/skills/distilled/distilled-executing-plans.md",
+    "keywords": [
+      "executing",
+      "plans"
+    ]
+  },
+  {
+    "name": "distilled-harness-engineering",
+    "description": "Distilled IT-universal skill: harness-engineering (score 5/5)",
+    "source_file": "src/skills/distilled/distilled-harness-engineering.md",
+    "keywords": [
+      "harness",
+      "engineering",
+      "legacy",
+      "遗留代码",
+      "特征测试",
+      "characterization",
+      "重构",
+      "refactor",
+      "改造",
+      "老代码"
+    ],
+    "spawn_agent": "refactor-specialist"
+  },
+  {
+    "name": "distilled-karpathy-guidelines",
+    "description": "Karpathy 4 条 LLM 编程铁律 — moved as-is, not re-distilled (already a distillation of multica-ai/andrej-karpathy-skills)",
+    "source_file": "src/skills/distilled/distilled-karpathy-guidelines.md",
+    "keywords": [
+      "karpathy",
+      "guidelines",
+      "编程原则",
+      "编程铁律",
+      "simplicity",
+      "surgical",
+      "goal-driven",
+      "简洁优先",
+      "外科手术",
+      "目标可验证",
+      "行数预算",
+      "可验证判据",
+      "事前思考",
+      "think before coding"
+    ]
+  },
+  {
+    "name": "distilled-performance-optimization",
+    "description": "Distilled IT-universal skill: performance optimization workflow (portable, hand-rewritten 2026-05-27)",
+    "source_file": "src/skills/distilled/distilled-performance-optimization.md",
+    "keywords": [
+      "performance",
+      "optimization",
+      "profiling",
+      "latency",
+      "bottleneck",
+      "optimize",
+      "优化",
+      "瓶颈",
+      "慢",
+      "slow",
+      "timeout",
+      "超时",
+      "卡顿",
+      "性能"
+    ]
+  },
+  {
+    "name": "distilled-spec-driven-design",
+    "description": "Distilled IT-universal skill: spec-driven design + file-based planning (portable, hand-rewritten 2026-05-27)",
+    "source_file": "src/skills/distilled/distilled-spec-driven-design.md",
+    "keywords": [
+      "spec",
+      "sdd",
+      "plan",
+      "design",
+      "requirements",
+      "acceptance",
+      "spec-driven",
+      "规格",
+      "需求文档",
+      "planning",
+      "规划",
+      "task plan",
+      "organize",
+      "组织任务",
+      "怎么做",
+      "方案",
+      "步骤",
+      "计划"
+    ],
+    "spawn_agent": "planner"
+  },
+  {
+    "name": "distilled-systematic-debugging",
+    "description": "Distilled IT-universal skill: systematic-debugging (score 5/5)",
+    "source_file": "src/skills/distilled/distilled-systematic-debugging.md",
+    "keywords": [
+      "systematic",
+      "debugging",
+      "debug",
+      "调试",
+      "bug",
+      "修复",
+      "fix",
+      "hotfix",
+      "报错",
+      "异常",
+      "error",
+      "不工作",
+      "失败",
+      "failed",
+      "crash",
+      "问题"
+    ],
+    "spawn_agent": "harness-debug-full"
+  },
+  {
+    "name": "distilled-verification-before-completion",
+    "description": "Distilled IT-universal skill: verification-before-completion (score 5/5)",
+    "source_file": "src/skills/distilled/distilled-verification-before-completion.md",
+    "keywords": [
+      "verification",
+      "before",
+      "completion"
+    ]
+  }
+]

package/dist/claudemd/claudemd-generator.d.ts

@@ -1,63 +1,63 @@
 /**
- * CLAUDE.md Generator — AI 驱动的 CLAUDE.md 生成与管理
+ * CLAUDE.md Generator — file I/O + directory scan helpers.
+ *
+ * History: this module used to drive a host-side AI completion to synthesize
+ * CLAUDE.md.  After spec `0902-ai-config-removal-master-spec.md` (decision
+ * `f5a5b030`, sub-spec A R-D) all AI synthesis moved to the `claude` CLI
+ * shell-out path in `src/cli/commands/claudemd.ts` (via
+ * `src/core/utils/claude-cli-spawn.ts` against the `claudemd-writer`
+ * sub-agent).  This module now only retains:
+ *
+ *   - AUTO marker read/write helpers (used by callers that still want to
+ *     preserve user-authored content outside the auto block — currently a
+ *     reusable primitive with no production consumer, but kept since the
+ *     associated tests still pin its contract)
+ *   - The directory-tree scanner (also imported by the CLI to build the
+ *     `<project_directory_tree>` payload for the agent)
+ *
+ * No `ai: ClaudeProvider` field; no `complete(...)` call sites.
  */
-import type { ClaudeProvider } from '../core/ai/provider.js';
-import { TechDetector } from './tech-detector.js';
+import { TechDetector, type TechStack } from './tech-detector.js';
+/**
+ * Scan a project directory and return a tree representation suitable for
+ * embedding in markdown.  Used by both `ClaudeMdGenerator` (legacy callers /
+ * tests) and `src/cli/commands/claudemd.ts` (current `cf claudemd` flow that
+ * feeds the tree to the `claudemd-writer` agent).
+ *
+ * - `maxDepth` controls how deep to recurse (typical: 2 for non-Java, 4 for
+ *   Java where the package nesting matters).
+ * - `addComments=true` enables Java directory-name annotations (controller,
+ *   service, mapper, …) — host caller decides based on detected stack.
+ */
+export declare function scanDirectoryTree(projectPath: string, maxDepth: number, addComments?: boolean): string;
 export declare class ClaudeMdGenerator {
-    private ai;
     readonly detector: TechDetector;
-    constructor(ai: ClaudeProvider, detector?: TechDetector);
-    /**
-     * 检测技术栈 + 生成 CLAUDE.md
-     *
-     * 策略：Swarm 协议是固定内容（不依赖 AI），项目信息尝试用 AI 生成，
-     * 失败时回退到基于技术栈检测的模板。
-     */
-    generate(projectPath: string, userContent?: string): Promise<string>;
+    constructor(detector?: TechDetector);
     /**
-     * 基于技术栈检测的回退模板（不依赖 AI）
+     * Write a CLAUDE.md file with the auto-generated block wrapped in
+     * `<!-- forge:claudemd-auto -->` markers, preserving any user-authored
+     * content that sits outside the block.
      *
-     * 即使 AI 调用失败，也要生成足够丰富的项目指引，让 Claude Code 拿到：
-     *   - 技术栈概览（含版本、包管理器、测试 / Linter）
-     *   - 构建 / 测试 / 运行命令（按包管理器分发）
-     *   - 目录结构（扫描项目根目录真实结构）
-     *   - 代码规范（命名、提交信息、PR 流程）
-     *   - 常见陷阱（按技术栈定制）
-     *   - 贡献指南
-     */
-    private buildFallbackContent;
-    private sectionOverview;
-    private sectionTechStack;
-    private frameworkHint;
-    private ecosystemNotes;
-    private sectionBuildCommands;
-    private sectionDirectoryStructure;
-    /**
-     * 扫描项目根目录，生成树形结构（过滤噪声目录）
-     */
-    private scanDirectoryTree;
-    private sectionCodingStandards;
-    private sectionCommonPitfalls;
-    private sectionContributionGuide;
-    /**
-     * 写入 CLAUDE.md，保留用户手动编辑的内容
+     * Note: as of sub-spec A R-D, the `cf claudemd init/update` path no longer
+     * routes through this helper — it writes the file directly from the
+     * `claudemd-writer` agent output.  This method remains for any external
+     * embedder that still wants the marker-preserving merge semantics.
      */
     write(projectPath: string, content: string): void;
     /**
-     * 读取并分离自动生成和用户内容
+     * Read a CLAUDE.md file and split the auto-generated block from the
+     * surrounding user content.
      */
     read(projectPath: string): {
         auto: string;
         user: string;
     };
-    private buildPrompt;
     /**
-     * 强制替换 AI 输出中的"目录结构"章节为真实扫描结果。
-     *
-     * AI 经常即使拿到真实目录也会退化成模板（project-root/com/example/project）。
-     * 做字符串替换是最稳妥的兜底。
+     * Instance-level convenience wrapper around the module-level
+     * `scanDirectoryTree` export, kept for any external caller that already
+     * holds a `ClaudeMdGenerator` instance.
      */
-    private overrideDirectoryStructure;
-    private merge;
+    scanDirectoryTree(projectPath: string, maxDepth: number, addComments?: boolean): string;
 }
+export type { TechStack };
 //# sourceMappingURL=claudemd-generator.d.ts.map

package/dist/claudemd/claudemd-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claudemd-generator.d.ts","sourceRoot":"","sources":["../../src/claudemd/claudemd-generator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAkB,MAAM,oBAAoB,CAAC;AA+BlE,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,EAAE;IAHZ,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;gBAGtB,EAAE,EAAE,cAAc,EAC1B,QAAQ,CAAC,EAAE,YAAY;IAKzB;;;;;OAKG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkC1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,oBAAoB;IA+B5B,OAAO,CAAC,yBAAyB;IASjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsGzB,OAAO,CAAC,sBAAsB;IAiD9B,OAAO,CAAC,qBAAqB;IAkC7B,OAAO,CAAC,wBAAwB;IAqChC;;OAEG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAYjD;;OAEG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IA2BzD,OAAO,CAAC,WAAW;IAgDnB;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,KAAK;CAKd"}
+{"version":3,"file":"claudemd-generator.d.ts","sourceRoot":"","sources":["../../src/claudemd/claudemd-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA8ClE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,UAAQ,GAClB,MAAM,CA0DR;AAED,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;gBAEpB,QAAQ,CAAC,EAAE,YAAY;IAInC;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAYjD;;;OAGG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAyBzD;;;;OAIG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,MAAM;CAGtF;AAID,YAAY,EAAE,SAAS,EAAE,CAAC"}