sdd-forge 0.1.0-alpha.23 → 0.1.0-alpha.25

package/docs/04_internal_design.md

@@ -2,26 +2,260 @@
 
 ## Overview
 
-<!-- {{text: Describe the purpose of this chapter in 1–2 sentences. Cover the project structure, module dependency direction, and key processing flows.}} -->
+<!-- {{text: Describe the purpose of this chapter in 1–2 sentences. Cover the project structure, direction of module dependencies, and key processing flows.}} -->
+
+This chapter describes the internal architecture of sdd-forge, including its directory layout, module responsibilities, and the direction of dependencies across the three-layer dispatch structure. It also covers the key processing flows that connect the CLI entry point through to AI invocation and file output.
 
 ## Contents
 
 ### Project Structure
 
-<!-- {{text: Describe the directory structure of this project in a tree-format code block. Include role comments for major directories and files. Cover the dispatchers directly under src/ (sdd-forge.js, docs.js, spec.js, flow.js), docs/commands/ (subcommand implementations), docs/lib/ (document generation library), lib/ (shared utilities), presets/ (preset definitions), and templates/ (bundled templates).}} -->
+<!-- {{text: Describe the directory structure of this project in a tree-format code block. Include role comments for major directories and files. Cover the top-level dispatchers under src/ (sdd-forge.js, docs.js, spec.js, flow.js), docs/commands/ (subcommand implementations), docs/lib/ (document generation libraries), lib/ (shared utilities), presets/ (preset definitions), and templates/ (bundled templates).}} -->
+
+```
+sdd-forge/
+├── package.json                      ← Package manifest; bin entry: ./src/sdd-forge.js
+└── src/
+    ├── sdd-forge.js                  ← Top-level CLI entry point; routes to dispatchers
+    ├── docs.js                       ← Dispatcher for all docs subcommands
+    ├── spec.js                       ← Dispatcher for spec/gate subcommands
+    ├── flow.js                       ← SDD flow automation (DIRECT_COMMAND)
+    ├── presets-cmd.js                ← Presets listing command (DIRECT_COMMAND)
+    ├── help.js                       ← Help text output
+    ├── docs/
+    │   ├── commands/                 ← Subcommand implementations
+    │   │   ├── scan.js               ← Source analysis → analysis.json / summary.json
+    │   │   ├── init.js               ← Initialize docs/ from templates
+    │   │   ├── data.js               ← Resolve {{data}} directives
+    │   │   ├── text.js               ← Resolve {{text}} directives via AI
+    │   │   ├── readme.js             ← Auto-generate README.md
+    │   │   ├── forge.js              ← Iterative docs improvement via AI
+    │   │   ├── review.js             ← Docs quality check via AI
+    │   │   ├── agents.js             ← Regenerate AGENTS.md sections
+    │   │   ├── changelog.js          ← Generate change_log.md from specs/
+    │   │   ├── setup.js              ← Project registration + config generation
+    │   │   └── ...                   ← upgrade, translate, default-project, etc.
+    │   └── lib/                      ← Document generation library modules
+    │       ├── scanner.js            ← File discovery and PHP/JS/YAML parsing
+    │       ├── directive-parser.js   ← Parse {{data}} / {{text}} / @block / @extends
+    │       ├── template-merger.js    ← Resolve template inheritance (@extends / @block)
+    │       ├── data-source.js        ← DataSource base class
+    │       ├── data-source-loader.js ← Dynamic DataSource loader per preset
+    │       ├── resolver-factory.js   ← createResolver() factory for data command
+    │       ├── forge-prompts.js      ← Prompt builders for forge/agents; summaryToText()
+    │       ├── text-prompts.js       ← Prompt builders for text command
+    │       ├── review-parser.js      ← Parse AI review output
+    │       ├── renderers.js          ← Markdown rendering utilities
+    │       ├── scan-source.js        ← Scan configuration loader
+    │       ├── concurrency.js        ← Parallel file processing utilities
+    │       └── ...                   ← composer-utils.js, php-array-parser.js
+    ├── specs/
+    │   └── commands/
+    │       ├── init.js               ← spec.md creation + feature branch setup
+    │       └── gate.js               ← Spec gate check (pre/post phase)
+    ├── lib/                          ← Shared utilities used across all layers
+    │   ├── agent.js                  ← AI agent invocation (sync/async)
+    │   ├── cli.js                    ← Argument parsing, path resolution utilities
+    │   ├── config.js                 ← Config loading, path utilities (.sdd-forge/)
+    │   ├── flow-state.js             ← SDD flow state management (current-spec)
+    │   ├── presets.js                ← Preset auto-discovery and lookup
+    │   ├── i18n.js                   ← Internationalization utilities
+    │   ├── types.js                  ← Type aliases and project type definitions
+    │   └── ...                       ← agents-md.js, process.js, projects.js, entrypoint.js
+    ├── presets/                      ← Preset definitions per project type
+    │   ├── base/                     ← Base preset (arch layer)
+    │   │   ├── preset.json
+    │   │   └── templates/            ← Doc templates (ja/ and en/)
+    │   ├── webapp/, cli/, library/   ← Architecture-layer presets
+    │   ├── cakephp2/, laravel/, symfony/ ← Framework-specific presets
+    │   └── node-cli/                 ← Node.js CLI preset
+    └── templates/                    ← Bundled templates (config.example.json, review-checklist.md, skills/)
+```
 
 ### Module Overview
 
 <!-- {{text: List the major modules in a table format. Include module name, file path, and responsibility. Cover the dispatcher layer (sdd-forge.js, docs.js, spec.js), command layer (docs/commands/*.js, specs/commands/*.js), library layer (lib/agent.js, lib/cli.js, lib/config.js, lib/flow-state.js, lib/presets.js, lib/i18n.js), and document generation layer (docs/lib/scanner.js, directive-parser.js, template-merger.js, forge-prompts.js, text-prompts.js, review-parser.js, data-source.js, resolver-factory.js).}} -->
 
+| Layer | Module | File Path | Responsibility |
+|---|---|---|---|
+| **Dispatcher** | CLI Entry Point | `src/sdd-forge.js` | Parses top-level subcommand; resolves project context via env vars; routes to dispatcher or direct command |
+| **Dispatcher** | Docs Dispatcher | `src/docs.js` | Routes all docs-related subcommands (`build`, `scan`, `init`, `data`, `text`, `readme`, `forge`, `review`, `agents`, `changelog`, `setup`, etc.) |
+| **Dispatcher** | Spec Dispatcher | `src/spec.js` | Routes `spec` and `gate` subcommands |
+| **Command** | scan | `src/docs/commands/scan.js` | Analyzes source files; writes `analysis.json` and `summary.json` |
+| **Command** | data | `src/docs/commands/data.js` | Resolves `{{data}}` directives in docs using analysis data |
+| **Command** | text | `src/docs/commands/text.js` | Resolves `{{text}}` directives by invoking an AI agent |
+| **Command** | forge | `src/docs/commands/forge.js` | Iteratively improves existing docs content via AI |
+| **Command** | review | `src/docs/commands/review.js` | Runs AI-based quality check against the review checklist |
+| **Command** | readme | `src/docs/commands/readme.js` | Auto-generates `README.md` from docs and analysis data |
+| **Command** | agents | `src/docs/commands/agents.js` | Regenerates SDD and PROJECT sections of `AGENTS.md` |
+| **Command** | spec init | `src/specs/commands/init.js` | Creates a new spec file and feature branch |
+| **Command** | gate | `src/specs/commands/gate.js` | Validates a spec file against gate criteria (pre/post phase) |
+| **Library** | agent | `src/lib/agent.js` | Synchronous and asynchronous AI agent invocation; prompt injection; timeout management |
+| **Library** | cli | `src/lib/cli.js` | `parseArgs()`, `repoRoot()`, `sourceRoot()`, `isInsideWorktree()`, `PKG_DIR` constant |
+| **Library** | config | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; manages `.sdd-forge/` path helpers |
+| **Library** | flow-state | `src/lib/flow-state.js` | Reads and writes `.sdd-forge/current-spec` to track SDD flow progress |
+| **Library** | presets | `src/lib/presets.js` | Auto-discovers `preset.json` files under `src/presets/`; exposes `PRESETS` constant and lookup helpers |
+| **Library** | i18n | `src/lib/i18n.js` | Locale string loading and translation utilities |
+| **Doc Gen** | scanner | `src/docs/lib/scanner.js` | File discovery; PHP/JS/YAML parsing utilities; `genericScan()` |
+| **Doc Gen** | directive-parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}`, `{{text}}`, `@block`, and `@extends` directives from markdown files |
+| **Doc Gen** | template-merger | `src/docs/lib/template-merger.js` | Resolves template inheritance (`@extends` / `@block`) before directive processing |
+| **Doc Gen** | forge-prompts | `src/docs/lib/forge-prompts.js` | Builds prompts for the `forge` and `agents` commands; provides `summaryToText()` |
+| **Doc Gen** | text-prompts | `src/docs/lib/text-prompts.js` | Builds per-directive prompts for the `text` command |
+| **Doc Gen** | review-parser | `src/docs/lib/review-parser.js` | Parses structured AI output from the `review` command into pass/fail results |
+| **Doc Gen** | data-source | `src/docs/lib/data-source.js` | Base class for all `{{data}}` resolver implementations |
+| **Doc Gen** | resolver-factory | `src/docs/lib/resolver-factory.js` | `createResolver()` factory that instantiates the correct DataSource for a given preset |
+
 ### Module Dependencies
 
-<!-- {{text: Generate a mermaid graph showing inter-module dependencies. Reflect the three-layer dispatch structure and show the dependency direction from dispatcher → command → library. Output only the mermaid code block.}} -->
+<!-- {{text: Generate a mermaid graph showing the dependencies between modules. Reflect the three-layer dispatch structure and show the dependency direction from dispatcher → command → library. Output only the mermaid code block.}} -->
+
+```mermaid
+graph TD
+    CLI["sdd-forge.js\n(Entry Point)"]
+
+    subgraph Dispatchers
+        DOCS["docs.js"]
+        SPEC["spec.js"]
+        FLOW["flow.js"]
+    end
+
+    subgraph Commands_Docs["docs/commands/"]
+        SCAN["scan.js"]
+        DATA["data.js"]
+        TEXT["text.js"]
+        FORGE["forge.js"]
+        REVIEW["review.js"]
+        README["readme.js"]
+        AGENTS["agents.js"]
+        INIT_D["init.js"]
+    end
+
+    subgraph Commands_Spec["specs/commands/"]
+        SPEC_INIT["init.js"]
+        GATE["gate.js"]
+    end
+
+    subgraph Lib["lib/"]
+        AGENT["agent.js"]
+        CLI_LIB["cli.js"]
+        CONFIG["config.js"]
+        FLOW_STATE["flow-state.js"]
+        PRESETS["presets.js"]
+        I18N["i18n.js"]
+    end
+
+    subgraph DocLib["docs/lib/"]
+        SCANNER["scanner.js"]
+        DIRECTIVE["directive-parser.js"]
+        MERGER["template-merger.js"]
+        FORGE_P["forge-prompts.js"]
+        TEXT_P["text-prompts.js"]
+        REVIEW_P["review-parser.js"]
+        DS["data-source.js"]
+        RESOLVER["resolver-factory.js"]
+    end
+
+    CLI --> DOCS
+    CLI --> SPEC
+    CLI --> FLOW
+
+    DOCS --> SCAN
+    DOCS --> DATA
+    DOCS --> TEXT
+    DOCS --> FORGE
+    DOCS --> REVIEW
+    DOCS --> README
+    DOCS --> AGENTS
+    DOCS --> INIT_D
+
+    SPEC --> SPEC_INIT
+    SPEC --> GATE
+
+    SCAN --> SCANNER
+    DATA --> DIRECTIVE
+    DATA --> RESOLVER
+    DATA --> DS
+    TEXT --> DIRECTIVE
+    TEXT --> TEXT_P
+    TEXT --> AGENT
+    FORGE --> FORGE_P
+    FORGE --> AGENT
+    REVIEW --> REVIEW_P
+    AGENTS --> FORGE_P
+    AGENTS --> AGENT
+
+    RESOLVER --> DS
+    TEXT_P --> CONFIG
+    FORGE_P --> CONFIG
+    SPEC_INIT --> FLOW_STATE
+    GATE --> FLOW_STATE
+    FLOW --> FLOW_STATE
+
+    SCAN --> CLI_LIB
+    DATA --> CLI_LIB
+    TEXT --> CLI_LIB
+    FORGE --> CLI_LIB
+    REVIEW --> CLI_LIB
+
+    CLI_LIB --> CONFIG
+    AGENT --> CONFIG
+    PRESETS --> CLI_LIB
+```
 
 ### Key Processing Flows
 
-<!-- {{text: Explain the data and control flow between modules when a representative command (build or forge) is executed, using numbered steps. Include the sequence: entry point → dispatch → config loading → analysis data preparation → AI invocation → file writing.}} -->
+<!-- {{text: Explain the inter-module data and control flow when a representative command (build or forge) is executed, using numbered steps. Include the flow from entry point → dispatch → config loading → analysis data preparation → AI invocation → file writing.}} -->
+
+The following steps describe the control and data flow for the `sdd-forge forge` command, which represents a complete end-to-end AI-assisted documentation update.
+
+1. **Entry point** — `sdd-forge.js` receives `forge` as the subcommand. It resolves the project context (from `--project`, `.sdd-forge/projects.json`, or the current directory), sets `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` environment variables, and forwards control to `docs.js`.
+2. **Dispatch** — `docs.js` matches `forge` and dynamically imports `docs/commands/forge.js`, passing the parsed arguments.
+3. **Config loading** — `forge.js` calls `loadConfig()` from `lib/config.js` to read `.sdd-forge/config.json`. The active language, AI agent settings, and document style options are extracted from the config.
+4. **Analysis data preparation** — `forge.js` reads `.sdd-forge/output/summary.json` (falling back to `analysis.json` if absent). The `summaryToText()` function from `docs/lib/forge-prompts.js` converts the JSON structure into a condensed text representation suitable for inclusion in an AI prompt.
+5. **Prompt construction** — `forge-prompts.js` assembles the full system prompt and user prompt, incorporating the analysis summary, the existing docs content, and any `documentStyle` configuration (tone, purpose, custom instructions).
+6. **AI invocation** — `lib/agent.js` is called with the constructed prompt. `callAgentAsync()` spawns the configured AI agent process (via `spawn` + `stdin: "ignore"`) and streams the response back through a callback.
+7. **Response parsing** — The AI-generated output is parsed and validated. For the `forge` command, the response contains updated markdown content for one or more docs files.
+8. **File writing** — Updated content is written back to the appropriate files under `docs/`. Directive markers (`{{data}}` / `{{text}}` blocks) in the output are preserved so that future automated runs can re-process them.
+9. **Review (optional)** — After `forge`, the SDD workflow recommends running `sdd-forge review`, which follows a similar flow but uses `review-parser.js` to parse structured pass/fail results from the AI response.
+
+For the `build` command, the same pipeline is orchestrated sequentially: `scan` → `init` → `data` → `text` → `readme`, with each step producing output consumed by the next.
 
 ### Extension Points
 
-<!-- {{text: Explain what needs to change and the extension patterns when adding new commands or features. Cover each of the following: (1) adding a new docs subcommand, (2) adding a new spec subcommand, (3) adding a new preset, (4) adding a new DataSource ({{data}} resolver), and (5) adding a new AI prompt.}} -->
+<!-- {{text: Explain where changes are needed and the extension patterns when adding new commands or features. Provide steps for each of the following: (1) adding a new docs subcommand, (2) adding a new spec subcommand, (3) adding a new preset, (4) adding a new DataSource ({{data}} resolver), and (5) adding a new AI prompt.}} -->
+
+**1. Adding a new docs subcommand**
+
+1. Create `src/docs/commands/<name>.js`. Export a `main(args)` function (or call `main()` at the bottom for direct-run support).
+2. Open `src/docs.js` and add a case for the new subcommand name in the dispatch map, pointing to the new file path.
+3. Add an entry to the command table in `src/help.js` so the new command appears in `sdd-forge help` output.
+4. Add corresponding test files under `tests/docs/commands/`.
+
+**2. Adding a new spec subcommand**
+
+1. Create `src/specs/commands/<name>.js` with a `main(args)` function.
+2. Register the new subcommand in `src/spec.js` by adding a dispatch case.
+3. Update `src/help.js` to include the new command description.
+4. Add tests under `tests/specs/commands/`.
+
+**3. Adding a new preset**
+
+1. Create a directory under `src/presets/<key>/` containing a `preset.json` file. Set the required fields: `type`, `arch`, and `chapters` (the list of doc template files to include).
+2. Place doc templates under `src/presets/<key>/templates/{ja,en}/` using the filenames declared in `chapters`.
+3. If the preset requires custom source scanning logic, add an analyzer module and reference it from `preset.json`. Implement scan logic following the pattern in existing presets (e.g., `cakephp2`).
+4. The preset is automatically discovered by `src/lib/presets.js` via recursive `preset.json` discovery — no manual registration is required.
+5. Add type aliases in `src/lib/types.js` if the preset should be reachable by shorthand names.
+
+**4. Adding a new DataSource (`{{data}}` resolver)**
+
+1. Create a class that extends `DataSource` from `src/docs/lib/data-source.js`. Implement the required `resolve(key, args)` method to return the data value for a given directive key.
+2. Register the new DataSource in `src/docs/lib/data-source-loader.js` by mapping it to the appropriate preset type(s).
+3. Ensure `resolver-factory.js` can instantiate the DataSource via `createResolver()` — add a case if the factory uses explicit type matching.
+4. Write tests that verify the resolved output for representative directive keys.
+
+**5. Adding a new AI prompt**
+
+1. Determine which command the prompt belongs to. For docs improvement prompts, add a builder function in `src/docs/lib/forge-prompts.js`. For `{{text}}` directive prompts, add to `src/docs/lib/text-prompts.js`.
+2. The prompt builder should accept the relevant config and analysis data as arguments and return a `{ system, user }` object.
+3. Invoke the prompt builder from the corresponding command file (`forge.js`, `text.js`, etc.) and pass the result to `callAgent()` or `callAgentAsync()` in `lib/agent.js`.
+4. If the prompt requires a custom system prompt file (for `--system-prompt-file`), ensure `ensureAgentWorkDir()` is called and the temporary file is cleaned up after invocation.

package/docs/ja/01_overview.md

@@ -0,0 +1,114 @@
+# 01. システム概要
+
+## 説明
+
+<!-- {{text: Write a 1-2 sentence overview of this chapter. Include the project's architecture and whether it integrates with external systems.}} -->
+
+本章では、ソースコード解析によるドキュメント自動生成と、Spec-Driven Development（SDD）ワークフローによる機能開発を推進する Node.js CLI ツール「sdd-forge」の構造概要を説明する。本ツールは3層のコマンドディスパッチアーキテクチャを採用し、ドキュメントテキストの生成・改善のために外部 AI エージェント（Claude CLI など）と連携する。
+
+## 内容
+
+### アーキテクチャ図
+
+<!-- {{text: Generate a mermaid flowchart showing the project architecture. Include data flows between major components. Output only the mermaid code block.}} -->
+
+```mermaid
+flowchart TD
+    User["ユーザー (CLI)"]
+
+    subgraph Entry["エントリ層"]
+        SDF["sdd-forge.js\n(エントリポイント)"]
+    end
+
+    subgraph Dispatch["ディスパッチャー層"]
+        DOCS["docs.js"]
+        SPEC["spec.js"]
+        FLOW["flow.js"]
+        HELP["help.js"]
+    end
+
+    subgraph Commands["コマンド層"]
+        SCAN["scan"]
+        DATA["data"]
+        TEXT["text"]
+        FORGE["forge"]
+        REVIEW["review"]
+        SPEC_INIT["spec init"]
+        GATE["gate"]
+        OTHER["readme / agents / changelog / …"]
+    end
+
+    subgraph Lib["コアライブラリ"]
+        AGENT["agent.js\n(AI エージェント呼び出し)"]
+        CONFIG["config.js\n(設定・パス管理)"]
+        SCANNER["scanner.js\n(ソース解析)"]
+        PARSER["directive-parser.js"]
+    end
+
+    subgraph Storage["ファイルシステム"]
+        SRC["ソースコード\n(プロジェクトルート)"]
+        ANALYSIS[".sdd-forge/output/\nanalysis.json / summary.json"]
+        DOCFILES["docs/*.md\n(生成ドキュメント)"]
+        SPECS["specs/NNN-xxx/spec.md"]
+        CFGFILE[".sdd-forge/config.json"]
+    end
+
+    AI["外部 AI エージェント\n(例: Claude CLI)"]
+
+    User --> SDF
+    SDF --> DOCS & SPEC & FLOW & HELP
+    DOCS --> SCAN & DATA & TEXT & FORGE & REVIEW & OTHER
+    SPEC --> SPEC_INIT & GATE
+    SCAN --> SCANNER --> SRC
+    SCANNER --> ANALYSIS
+    DATA --> PARSER --> DOCFILES
+    TEXT --> AGENT --> AI
+    FORGE --> AGENT
+    REVIEW --> AGENT
+    AGENT --> DOCFILES
+    CONFIG --> CFGFILE
+    SPEC_INIT --> SPECS
+    GATE --> SPECS
+```
+
+### コンポーネントの責務
+
+<!-- {{text: Describe the major components with their location, responsibilities, and I/O in table format.}} -->
+
+| コンポーネント | 場所 | 責務 | 入力 | 出力 |
+|---|---|---|---|---|
+| CLI エントリポイント | `src/sdd-forge.js` | プロジェクトコンテキストを解決し、サブコマンドを適切なディスパッチャーへルーティングする | CLI 引数、環境変数（`SDD_SOURCE_ROOT`、`SDD_WORK_ROOT`） | ディスパッチされたコマンド実行 |
+| ドキュメントディスパッチャー | `src/docs.js` | `build`、`scan`、`init`、`data`、`text`、`forge`、`review` および関連サブコマンドをルーティングする | サブコマンド名＋フラグ | `docs/commands/*.js` へ委譲 |
+| スペックディスパッチャー | `src/spec.js` | `spec` および `gate` サブコマンドをルーティングする | サブコマンド名＋フラグ | `specs/commands/*.js` へ委譲 |
+| SDD フローランナー | `src/flow.js` | SDD サイクル全体をエンドツーエンドで自動実行する | `--request` プロンプト文字列 | spec → gate → 実装 → forge → review のオーケストレーション |
+| ソーススキャナー | `src/docs/lib/scanner.js` | プロジェクトのソースファイルを解析し、モジュール・ルート・構造を抽出する | ソースルートディレクトリ | `.sdd-forge/output/analysis.json`、`summary.json` |
+| ディレクティブパーサー | `src/docs/lib/directive-parser.js` | Markdown テンプレート内の `{{data}}` および `{{text}}` ディレクティブを解析する | `.md` テンプレートファイル | リゾルバー向けディレクティブ AST |
+| データリゾルバー | `src/docs/lib/resolver-factory.js` | 構造化された解析データを `{{data}}` ディレクティブに注入する | `analysis.json`、ディレクティブ AST | 解決済み Markdown セクション |
+| AI エージェント呼び出し | `src/lib/agent.js` | 外部 AI エージェントプロセスを同期または非同期で呼び出す | プロンプト文字列、エージェント設定 | AI 生成テキスト（stdout） |
+| 設定マネージャー | `src/lib/config.js` | `.sdd-forge/config.json` を読み込みバリデーションし、標準パスを解決する | `.sdd-forge/` ディレクトリ | 型付き設定オブジェクト、ファイルパス |
+| スペックゲート | `src/specs/commands/gate.js` | 実装前後のチェックリストに基づいてスペックを検証する | `spec.md` パス、`--phase` フラグ | PASS / FAIL レポート |
+| フォージエンジン | `src/docs/commands/forge.js` | AI エージェントへのプロンプトにより `docs/` を反復改善する | 変更内容サマリープロンプト、`spec.md` パス | 更新された `docs/*.md` ファイル |
+
+### 外部連携
+
+<!-- {{text: If there are external system integrations, describe their purpose and connection method in table format.}} -->
+
+| システム | 目的 | 接続方法 | 設定 |
+|---|---|---|---|
+| AI エージェント（例: Claude CLI） | `{{text}}` ディレクティブのドキュメントテキスト生成・改善、および `forge`、`review`、`agents`、`text` コマンドの実行を担う | `src/lib/agent.js` 内で `execFileSync`（同期）または `spawn`（非同期ストリーミング）によって子プロセスとして起動される | `.sdd-forge/config.json` の `providers` に定義し、`defaultAgent` キーで選択する |
+
+AI エージェントが唯一の外部連携である。ファイルスキャン、ディレクティブ解析、テンプレートマージ、スペック管理など、その他の処理はすべて Node.js 組み込みモジュール（`fs`、`path`、`child_process`、`os`）のみに依存する。エージェントのコマンド、引数、タイムアウト、システムプロンプトの渡し方（`--system-prompt` または `--system-prompt-file`）はプロジェクトごとに設定可能である。
+
+### 環境別の差異
+
+<!-- {{text: Describe the configuration differences across environments (local/staging/production).}} -->
+
+sdd-forge はローカル CLI ツールであるため、従来の意味での独立したデプロイ環境は存在しない。環境による設定の違いは、プロジェクトごとの `.sdd-forge/config.json` 設定と環境変数によって表現される。
+
+| 観点 | ローカル開発 | CI / 自動化パイプライン | マルチプロジェクト構成 |
+|---|---|---|---|
+| プロジェクト解決 | インタラクティブ；`--project` フラグまたは `.sdd-forge/projects.json` の `default` キーを使用 | ジョブごとに `SDD_SOURCE_ROOT` と `SDD_WORK_ROOT` 環境変数を明示的に設定 | `.sdd-forge/projects.json` に名前付きプロジェクトを登録し、`--project <name>` でターゲットを選択 |
+| AI エージェント | `config.json` の `providers` + `defaultAgent` で設定；インタラクティブに動作 | 同設定を使用；非 TTY 環境でのハングを防ぐため `stdin: "ignore"` を利用（`callAgentAsync`） | プロジェクトごとに独立したエージェント設定を持つ `config.json` を保持 |
+| 言語 / 出力 | `lang` と `output.languages` で CLI 言語とドキュメント出力ロケールを制御 | 同設定値が適用される；個別のオーバーライド機構はなし | プロジェクトごとの `config.json` により言語を個別に設定可能 |
+| 並列処理 | `limits.concurrency`（デフォルト: 5）でファイル並列処理数を制御 | 高コアマシンでは値を上げて高速化可能 | プロジェクトごとに独立して調整可能 |
+| タイムアウト | `limits.designTimeoutMs` / プロバイダーごとの `timeoutMs` | 低速な CI エージェントでは値を増やすべき；デフォルト定数: 120 秒 / 180 秒 / 300 秒 | プロジェクトごとに設定可能 |

package/docs/ja/02_cli_commands.md

@@ -0,0 +1,270 @@
+# 02. CLIコマンドリファレンス
+
+## 説明
+
+<!-- {{text: Write a 1–2 sentence overview of this chapter. Cover the total number of commands, whether global options exist, and the subcommand structure.}} -->
+
+本章では `sdd-forge` で利用可能な全18サブコマンドを解説します。ドキュメント生成コマンド（`docs.js` 経由でルーティング）、specワークフローコマンド（`spec.js` 経由でルーティング）、および直接実行コマンド（`flow`、`presets`）に分類されます。すべてのコマンドは共通のグローバルオプションを持ち、ほとんどのコマンドは実行前にプロジェクトコンテキストの解決が必要です。
+
+## 目次
+
+### コマンド一覧
+
+<!-- {{text: List all commands in a table format. Include command name, description, and main options. Commands can be identified from the modules list in the analysis data. Include both commands routed through dispatchers (docs.js, spec.js) and directly executed commands (flow, presets). Note that build is a composite command (scan → init → data → text → readme → agents → translate pipeline). Be sure to include translate (multilingual translation), upgrade (template update), and default (default project configuration).}} -->
+
+| コマンド | 説明 | 主なオプション |
+|---|---|---|
+| `build` | ドキュメント生成パイプライン全体（`scan → init → data → text → readme → agents → translate`）を一括実行する | `--project` |
+| `scan` | ソースコードを解析し、`analysis.json` と `summary.json` を生成する | `--project` |
+| `init` | プリセットテンプレートから `docs/` を初期化する | `--project` |
+| `data` | 解析出力を使用して `{{data: ...}}` ディレクティブを解決する | `--project` |
+| `text` | 設定済みAIエージェントを使用して `{{text: ...}}` ディレクティブを解決する | `--file`、`--agent`、`--project` |
+| `readme` | docsの内容をもとにAIで `README.md` を自動生成する | `--project` |
+| `forge` | プロンプトに基づき、AIを使ってdocsを反復的に改善する | `--prompt`、`--spec`、`--project` |
+| `review` | docsのAI品質チェックを実行し、PASS/FAILを報告する | `--project` |
+| `changelog` | `specs/` 配下の全specファイルから `change_log.md` を生成する | `--project` |
+| `agents` | 最新のSDDテンプレートとPROJECTセクションで `AGENTS.md` を更新する | `--sdd`、`--project-only`、`--dry-run` |
+| `translate` | configで定義された追加出力言語へdocsを翻訳する | `--lang`、`--force`、`--dry-run` |
+| `upgrade` | インストール済みパッケージバージョンに合わせてSDDマネージドテンプレートセクションを更新する | `--project` |
+| `setup` | プロジェクトを登録し、初期 `.sdd-forge/config.json` を生成する | — |
+| `default` | `projects.json` のデフォルトプロジェクトを設定または表示する | — |
+| `spec` | 新しいspecファイルを作成し、オプションでfeatureブランチを作成する | `--title`、`--no-branch` |
+| `gate` | 実装前または実装後にspecを受入基準に照らして検証する | `--spec`、`--phase` |
+| `flow` | 自然言語のリクエストからSDDフロー全体を自動実行する | `--request` |
+| `presets` | バンドル済みのプロジェクトタイププリセット一覧を表示する | — |
+| `help` | 利用可能なサブコマンドと説明を表示する | `-h`、`--help` |
+
+### グローバルオプション
+
+<!-- {{text: List global options common to all commands in a table format. Include --project, --help/-h, and --version/-v/-V. Also note that setup, default, help, and presets skip project context resolution.}} -->
+
+| オプション | エイリアス | 説明 |
+|---|---|---|
+| `--project <name>` | — | `.sdd-forge/projects.json` に登録されたプロジェクト名で対象プロジェクトを指定する。省略した場合は `projects.json` の `default` に設定されたプロジェクトが使用される。 |
+| `--help` | `-h` | 指定したサブコマンドのヘルプテキストを表示して終了する。 |
+| `--version` | `-v`、`-V` | `package.json` から現在の `sdd-forge` バージョンを表示して終了する。 |
+
+> **注意:** `setup`、`default`、`help`、`presets` コマンドはプロジェクトコンテキストの解決を完全にスキップします。これらのコマンドは登録済みプロジェクトを必要とせず、`--project` フラグを無視します。
+
+### コマンド詳細
+
+<!-- {{text: Describe the usage, options, and examples for each command in detail. Create a #### subsection for each command. For the build pipeline, list all steps: scan → init → data → text → readme → agents → translate. The translate command has --lang, --force, and --dry-run options.}} -->
+
+以下の各コマンドについて、目的・利用可能なオプション・代表的な使用例を解説します。AIを使って生成するコマンドには、`.sdd-forge/config.json` に有効な `defaultAgent` または `providers` エントリが必要です。ディスクへの書き込みを行うコマンドは、特記がない限り解決済みプロジェクトの `docs/` ディレクトリ内で動作します。
+
+#### build
+
+ドキュメント生成パイプライン全体を一括実行します。パイプラインは `scan → init → data → text → readme → agents → translate` の順で各ステージを実行します。プロジェクトのdocs初回作成や完全な再生成の標準的なエントリポイントです。
+
+```bash
+sdd-forge build
+sdd-forge build --project myproject
+```
+
+#### scan
+
+設定済みプリセット（例: `cli/node-cli`、`webapp/cakephp2`）に従ってプロジェクトのソースコードを解析し、`.sdd-forge/output/analysis.json` と `.sdd-forge/output/summary.json` に結果を書き込みます。`summary.json` はAI向けの軽量版です。
+
+```bash
+sdd-forge scan
+```
+
+#### init
+
+プリセットテンプレートをコピーして `docs/` ディレクトリ構造を初期化します。テンプレートは `src/presets/{preset}/templates/{lang}/` から解決されます。強制上書きを指定しない限り、既存ファイルは上書きされません。
+
+```bash
+sdd-forge init
+```
+
+#### data
+
+`docs/` ファイル内のすべての `{{data: ...}}` ディレクティブを解決し、`analysis.json` から抽出した構造化データに置き換えます。テンプレート境界の外にあるディレクティブはそのまま保持されます。
+
+```bash
+sdd-forge data
+```
+
+#### text
+
+設定済みAIエージェントを使用して `docs/` ファイル内の `{{text: ...}}` ディレクティブを解決します。`limits.concurrency` の設定に従ってファイルを並列処理します。特定のファイルのみを対象にすることもできます。
+
+| オプション | 説明 |
+|---|---|
+| `--file <path>` | 指定したdocsファイルのみを処理する |
+| `--agent <name>` | 使用するAIエージェントを上書きする |
+
+```bash
+sdd-forge text
+sdd-forge text --file docs/02_cli_commands.md
+```
+
+#### readme
+
+`docs/` の内容をソースとして、AIエージェントを使ってプロジェクトルートに `README.md` を自動生成します。使用するAIエージェントはプロジェクトconfigで定義します。
+
+```bash
+sdd-forge readme
+```
+
+#### forge
+
+最近の変更内容を説明するプロンプトに基づき、AIを使って1つ以上のdocsファイルを反復的に改善します。`--spec` を指定すると、specファイルがAIへの追加コンテキストとして含まれます。
+
+| オプション | 説明 |
+|---|---|
+| `--prompt <text>` | docsに反映する変更内容の説明（必須） |
+| `--spec <path>` | 追加コンテキストとして使用するspecファイルのパス |
+
+```bash
+sdd-forge forge --prompt "translateコマンドに--langオプションを追加"
+sdd-forge forge --prompt "scannerをリファクタリング" --spec specs/010-refactor/spec.md
+```
+
+#### review
+
+AIを使って生成済みdocsの品質チェックを実行し、完全性・正確性・ソースコードとの整合性を検証します。実行可能なフィードバックとともにPASSまたはFAILの結果を出力します。
+
+```bash
+sdd-forge review
+```
+
+#### changelog
+
+`specs/` 配下のすべてのspecファイルを集約して `change_log.md` を生成します。各specが表す機能または修正の説明としてchangelogエントリを提供します。
+
+```bash
+sdd-forge changelog
+```
+
+#### agents
+
+最新のSDDインストラクションテンプレートと `analysis.json` / `summary.json` から新たに生成したPROJECTセクションで `AGENTS.md` を更新します。フラグで部分的な更新も可能です。
+
+| オプション | 説明 |
+|---|---|
+| `--sdd` | `<!-- SDD:START/END -->` セクションのみを更新する |
+| `--project` | `<!-- PROJECT:START/END -->` セクションのみを更新する |
+| `--dry-run` | ディスクへの書き込みを行わずに出力をプレビューする |
+
+```bash
+sdd-forge agents
+sdd-forge agents --sdd
+sdd-forge agents --dry-run
+```
+
+#### translate
+
+プロジェクトconfigの `output.languages` で指定された1つ以上の追加出力言語へ生成済みdocsを翻訳します。翻訳戦略の決定には `output.mode`（`translate` または `generate`）が使用されます。
+
+| オプション | 説明 |
+|---|---|
+| `--lang <code>` | 翻訳先の言語コード（例: `en`、`ja`） |
+| `--force` | 既存の翻訳済みファイルを上書きする |
+| `--dry-run` | ディスクへの書き込みを行わずにプレビューする |
+
+```bash
+sdd-forge translate --lang en
+sdd-forge translate --lang en --force
+```
+
+#### upgrade
+
+`docs/` テンプレートのSDDマネージドセクションを、インストール済みの `sdd-forge` パッケージに同梱された最新バージョンに更新します。ディレクティブ境界の外にあるコンテンツは保持されます。
+
+```bash
+sdd-forge upgrade
+```
+
+#### setup
+
+新しいプロジェクトを `sdd-forge` に登録し、初期 `.sdd-forge/config.json` を生成します。プロジェクトタイプのプリセット選択と出力言語設定の構成をユーザーに案内します。`AGENTS.md` の作成と `CLAUDE.md` シンボリックリンクの作成も行います。
+
+```bash
+sdd-forge setup
+```
+
+#### default
+
+現在のツールインストールのデフォルトプロジェクトを設定または表示します。デフォルトプロジェクトは `.sdd-forge/projects.json` に保存され、`--project` が指定されていない場合に使用されます。
+
+```bash
+sdd-forge default
+sdd-forge default myproject
+```
+
+#### spec
+
+`specs/NNN-<slug>/spec.md` に新しいspecファイルを作成し、オプションでfeatureブランチを作成します。SDDワークフローにおいて新機能または修正の開始時に使用します。
+
+| オプション | 説明 |
+|---|---|
+| `--title <name>` | specおよび機能のタイトル（必須） |
+| `--no-branch` | ブランチ作成をスキップする（例: worktree内で作業している場合） |
+
+```bash
+sdd-forge spec --title "translateコマンドを追加"
+sdd-forge spec --title "scannerを修正" --no-branch
+```
+
+#### gate
+
+実装前（`--phase pre`）または実装後（`--phase post`）に、定義された受入基準に照らしてspecファイルを検証します。各チェック項目についてPASSまたはFAILを報告します。
+
+| オプション | 説明 |
+|---|---|
+| `--spec <path>` | 検証するspecファイルのパス（必須） |
+| `--phase <pre\|post>` | ゲートフェーズ。デフォルトは `pre` |
+
+```bash
+sdd-forge gate --spec specs/010-translate/spec.md
+sdd-forge gate --spec specs/010-translate/spec.md --phase post
+```
+
+#### flow
+
+自然言語のリクエストに対して、spec作成・ゲートチェック・実装スキャフォールディングを含むSDDフロー全体を自動実行します。手動でのステップ実行が現実的でないAIエージェント環境を想定しています。
+
+| オプション | 説明 |
+|---|---|
+| `--request <text>` | 機能または修正の自然言語による説明 |
+
+```bash
+sdd-forge flow --request "多言語出力のサポートを追加"
+```
+
+#### presets
+
+`sdd-forge` にバンドルされているすべてのプロジェクトタイププリセットを一覧表示します。アーキテクチャ層プリセット（`webapp`、`cli`、`library`）およびフレームワーク固有プリセット（`cakephp2`、`laravel`、`symfony`、`node-cli`）が含まれます。
+
+```bash
+sdd-forge presets
+```
+
+#### help
+
+利用可能なすべてのサブコマンドとその説明のまとめを表示します。引数なしで `sdd-forge` を実行した場合と同等です。
+
+```bash
+sdd-forge help
+sdd-forge -h
+```
+
+### 終了コードと出力
+
+<!-- {{text: Describe exit code definitions (0=success, 1=general error, etc.) and the rules for stdout/stderr usage in a table format. Include the fact that gate and review PASS/FAIL results are printed to stdout.}} -->
+
+| 終了コード | 意味 |
+|---|---|
+| `0` | コマンドが正常に完了した |
+| `1` | 一般エラー（必須オプションの欠如、ファイルが見つからない、設定が無効など） |
+| `2` | gateまたはreviewのチェックが失敗した（FAILの結果が報告される。詳細はstdoutを参照） |
+
+**stdout / stderr の使い分け:**
+
+| ストリーム | 内容 |
+|---|---|
+| `stdout` | 主要なコマンド出力: 生成テキスト、レンダリングされたテーブル、`gate` および `review` のPASS/FAIL結果、dry-runプレビュー |
+| `stderr` | 進捗インジケーター、警告、デバッグ情報、エラーメッセージ |
+
+`gate` と `review` は常にPASS/FAILの判定と各チェック項目の結果を **stdout** に出力するため、CIパイプラインでのキャプチャに適しています。コマンドが実行できない理由を示すエラーメッセージ（設定がない、引数が無効など）は **stderr** に書き込まれ、キャプチャしたstdoutには現れません。