sdd-forge 0.1.0-alpha.702 → 0.1.0-alpha.759

package/README.md

@@ -88,9 +88,9 @@ If you already have source code, generate documentation to get a complete pictur
 
 | Command | Phase |
 |---|---|
-| `$sdd-forge flow prepare --title "..." --base main` | plan (create spec + branch) |
-| `$sdd-forge flow run review` | implement (AI code review) |
-| `$sdd-forge flow run finalize --mode all` | finalize (wrap-up) |
+| `$sdd-forge.flow-plan` | plan (specification) |
+| `$sdd-forge.flow-impl` | implement (coding + review) |
+| `$sdd-forge.flow-finalize` | finalize (commit, merge, docs sync, cleanup) |
 
 ## Commands
 
@@ -98,12 +98,6 @@ If you already have source code, generate documentation to get a complete pictur
 |---|---|
 | `setup` | Register project and generate config |
 | `docs build` | Run the full documentation pipeline |
-| `docs readme` | Generate `README.md` from `docs/` |
-| `docs review` | Check documentation quality |
-| `flow prepare` | Create spec and branch |
-| `flow get status` | Show flow progress |
-| `presets` | List available presets |
-| `help` | Show all commands |
 
 See `sdd-forge help` or the [command reference](docs/cli_commands.md) for the full list.
 
@@ -129,12 +123,12 @@ See the [configuration reference](docs/configuration.md) for details.
 <!-- {{data("cli.docs.chapters", {header: "", labels: "Chapter|Summary", ignoreError: true})}} -->
 | Chapter | Summary |
 | --- | --- |
-| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) |  |
-| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) |  |
-| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) |  |
-| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) |  |
-| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) |  |
-| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) |  |
+| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces sdd-forge, a CLI tool that automates documentation generation from source code analysis and e… |
+| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | This chapter covers the technology stack, dependency management, deployment, and operations procedures for sdd-forge,… |
+| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | This chapter describes the overall directory organization of the sdd-forge project, which is structured around seven … |
+| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | This chapter documents 8 CLI entrypoints and routed commands in the analyzed files: setup, check, check freshness, do… |
+| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge is configured through a single project-level JSON file (.sdd-forge/config.json) and optionally extended by … |
+| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes the internal structure of sdd-forge: a layered CLI tool built entirely on Node.js built-in mod… |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.702",
+  "version": "0.1.0-alpha.759",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",
@@ -10,12 +10,16 @@
   "bin": {
     "sdd-forge": "./src/sdd-forge.js"
   },
+  "exports": {
+    ".": "./src/sdd-forge.js",
+    "./api": "./src/api.js"
+  },
   "files": [
     "src/",
     "!src/presets/*/tests/"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.19.0"
   },
   "keywords": [
     "sdd",
@@ -25,7 +29,6 @@
     "technical-docs"
   ],
   "scripts": {
-    "test": "node tests/run.js",
     "test:unit": "node tests/run.js --scope unit",
     "test:e2e": "node tests/run.js --scope e2e",
     "test:acceptance": "node tests/acceptance/run.js"

package/src/AGENTS.md

@@ -43,7 +43,7 @@ src/
 │   ├── set.js               set サブディスパッチャ
 │   ├── run.js               run サブディスパッチャ
 │   ├── get/                 status, resolve-context, check, prompt, qa-count, guardrail, issue
-│   ├── set/                 step, request, issue, note, summary, req, metric, redo
+│   ├── set/                 step, request, issue, note, summary, req, metric
 │   ├── run/                 prepare-spec, gate, review, impl-confirm, finalize, sync
 │   └── commands/            内部ヘルパー（merge, cleanup, review の実体）
 ├── spec/commands/            init, gate, guardrail（flow/run/prepare-spec, gate が内部で呼ぶ）

package/src/api.js

@@ -0,0 +1,12 @@
+/**
+ * src/api.js — sdd-forge public API entry point
+ *
+ * Re-exports the base classes needed by external presets and
+ * .sdd-forge/data/ DataSource overrides.
+ *
+ * Usage (from external preset files):
+ *   import { DataSource, Scannable, AnalysisEntry } from 'sdd-forge/api';
+ */
+export { DataSource } from "./docs/lib/data-source.js";
+export { Scannable } from "./docs/lib/scan-source.js";
+export { AnalysisEntry } from "./docs/lib/analysis-entry.js";

package/src/docs/commands/agents.js

@@ -178,7 +178,7 @@ async function main(ctx) {
 
   // Load generated docs as context (instead of raw analysis.json)
   const docsDir = path.join(root, "docs");
-  const chapterFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: ctx.config?.chapters });
+  const chapterFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: ctx.config?.chapters, projectRoot: root });
   const docsContent = chapterFiles.map((f) => readText(path.join(docsDir, f))).join("\n\n");
   const readmeContent = readText(path.join(srcRoot, "README.md"));
   const combinedDocs = [docsContent, readmeContent].filter(Boolean).join("\n\n---\n\n");

package/src/docs/commands/data.js

@@ -76,7 +76,7 @@ export function populateFromAnalysis(root, analysis, resolveFn, opts) {
   const docsDir = path.join(root, "docs");
   const changedFiles = [];
 
-  const docsFiles = getChapterFiles(docsDir, { type: opts?.type, configChapters: opts?.configChapters });
+  const docsFiles = getChapterFiles(docsDir, { type: opts?.type, configChapters: opts?.configChapters, projectRoot: root });
 
   for (const file of docsFiles) {
     const filePath = path.join(docsDir, file);
@@ -137,7 +137,7 @@ async function main(ctx) {
     throw new Error(t("messages:data.resolverFailed", { message: err.message }));
   }
 
-  const docsFiles = getChapterFiles(docsDir, { type, configChapters: ctx.config?.chapters });
+  const docsFiles = getChapterFiles(docsDir, { type, configChapters: ctx.config?.chapters, projectRoot: root });
 
   // Determine relative path prefix for lang.links context
   const docsDirRel = path.relative(root, docsDir).replace(/\\/g, "/");

package/src/docs/commands/forge.js

@@ -44,7 +44,7 @@ const DEFAULT_MODE = "local";
 
 function getTargetFiles(root, type, configChapters) {
   const docsDir = path.join(root, "docs");
-  return getChapterFiles(docsDir, { type, configChapters }).map((f) => `docs/${f}`);
+  return getChapterFiles(docsDir, { type, configChapters, projectRoot: root }).map((f) => `docs/${f}`);
 }
 
 /**

package/src/docs/commands/init.js

@@ -169,12 +169,13 @@ function main(ctx) {
     ? configLangs
     : [...configLangs, "en"];
   const configChapters = config?.chapters;
-  const chaptersOrder = resolveChaptersOrder(type, configChapters);
+  const chaptersOrder = resolveChaptersOrder(type, configChapters, root);
 
   const resolutions = resolveTemplates(type, lang, {
     projectLocalDir,
     fallbackLangs,
     chaptersOrder,
+    projectRoot: root,
   });
 
   // 解決結果からチャプターを生成（README は除外）

package/src/docs/commands/readme.js

@@ -75,11 +75,12 @@ async function main(ctx) {
 
   // ボトムアップでテンプレート解決
   const configChapters = config?.chapters;
-  const chaptersOrder = resolveChaptersOrder(type, configChapters);
+  const chaptersOrder = resolveChaptersOrder(type, configChapters, root);
   const resolutions = resolveTemplates(type, lang, {
     projectLocalDir,
     fallbackLangs,
     chaptersOrder,
+    projectRoot: root,
   });
 
   const readmeRes = resolutions.find((r) => r.fileName === "README.md");

package/src/docs/commands/review.js

@@ -114,7 +114,7 @@ function main() {
   // Discover chapter files
   let chapterFiles = [];
   if (fs.existsSync(targetDir) && fs.statSync(targetDir).isDirectory()) {
-    chapterFiles = getChapterFiles(targetDir, { type, configChapters: config.chapters });
+    chapterFiles = getChapterFiles(targetDir, { type, configChapters: config.chapters, projectRoot: root });
   }
 
   if (chapterFiles.length === 0) {
@@ -232,7 +232,7 @@ function main() {
           reportFail("messages:review.langDirMissing", { lang });
           continue;
         }
-        const langFiles = getChapterFiles(langDir, { type, configChapters: config.chapters });
+        const langFiles = getChapterFiles(langDir, { type, configChapters: config.chapters, projectRoot: root });
         if (langFiles.length === 0) {
           reportFail("messages:review.langNoChapters", { lang });
           continue;

package/src/docs/commands/scan.js

@@ -22,7 +22,7 @@ import crypto from "crypto";
 import { fileURLToPath } from "url";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { repoRoot, parseArgs } from "../../lib/cli.js";
-import { sddDataDir, sddOutputDir } from "../../lib/config.js";
+import { sddOutputDir } from "../../lib/config.js";
 import { collectFiles } from "../lib/scanner.js";
 import { loadDataSources } from "../lib/data-source-loader.js";
 import { presetByLeaf, resolveChainSafe, resolveMultiChains } from "../../lib/presets.js";
@@ -289,7 +289,7 @@ async function main(ctx) {
   const currentFilePaths = new Set(files.map((f) => f.relPath));
 
   // 3. Load Scannable DataSources from preset chain
-  const chains = resolveMultiChains(types);
+  const chains = resolveMultiChains(types, root);
   const seenDirs = new Set();
 
   let dataSources = new Map();
@@ -301,9 +301,6 @@ async function main(ctx) {
     }
   }
 
-  const projectDataDir = sddDataDir(root);
-  dataSources = await loadScanSources(projectDataDir, dataSources);
-
   // 3b. DataSource hash detection: clear entry hashes for categories whose DataSource changed
   if (existing) {
     for (const [name, source] of dataSources) {

package/src/docs/commands/text.js

@@ -489,7 +489,7 @@ export async function textFillFromAnalysis(root, analysis, commandId, srcRoot, o
   const docsDir = path.join(root, "docs");
   const resolvedSrcRoot = srcRoot || root;
 
-  const targetFiles = opts?.files || getChapterFiles(docsDir, { type, configChapters: cfg.chapters });
+  const targetFiles = opts?.files || getChapterFiles(docsDir, { type, configChapters: cfg.chapters, projectRoot: root });
 
   const changedFiles = [];
   let totalFilled = 0;
@@ -640,7 +640,7 @@ async function main(ctx) {
   if (ctx.files) {
     targetFiles = ctx.files;
   } else {
-    targetFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: cfg.chapters });
+    targetFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: cfg.chapters, projectRoot: root });
 
     // Diff-based chapter filtering: skip chapters whose entries are unchanged
     if (!ctx.force) {

package/src/docs/commands/translate.js

@@ -175,7 +175,7 @@ async function main(ctx) {
     throw new Error("docs/ directory not found. Run 'sdd-forge init' first.");
   }
 
-  const sourceFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: ctx.config?.chapters });
+  const sourceFiles = getChapterFiles(docsDir, { type: ctx.type, configChapters: ctx.config?.chapters, projectRoot: root });
   const readmePath = path.join(root, "README.md");
   const hasReadme = fs.existsSync(readmePath);
 

package/src/docs/data/docs.js

@@ -170,7 +170,7 @@ export default class DocsSource extends DataSource {
     const docsDir = this._docsDir || path.join(this._root, "docs");
     if (!fs.existsSync(docsDir)) return null;
 
-    const files = getChapterFiles(docsDir, { type: this._type, configChapters: this._configChapters });
+    const files = getChapterFiles(docsDir, { type: this._type, configChapters: this._configChapters, projectRoot: this._root });
 
     if (files.length === 0) return null;
 
@@ -240,7 +240,7 @@ export default class DocsSource extends DataSource {
     const docsDir = this._docsDir || path.join(this._root, "docs");
     if (!fs.existsSync(docsDir)) return null;
 
-    const files = getChapterFiles(docsDir, { type: this._type, configChapters: this._configChapters });
+    const files = getChapterFiles(docsDir, { type: this._type, configChapters: this._configChapters, projectRoot: this._root });
     if (files.length <= 1) return null;
 
     // Find current file in the chapter list

package/src/docs/lib/command-context.js

@@ -128,6 +128,7 @@ export function loadFullAnalysis(root) {
  * @param {Object} [options]
  * @param {string} [options.type] - プロジェクトタイプ（例: "cli/node-cli"）
  * @param {string[]} [options.configChapters] - config.json の chapters 配列（最優先）
+ * @param {string} [options.projectRoot] - プロジェクトルート（.sdd-forge/presets/ 検索用）
  * @returns {string[]} ファイル名の配列（順序付き）
  */
 export function getChapterFiles(docsDir, options) {
@@ -135,10 +136,11 @@ export function getChapterFiles(docsDir, options) {
 
   const type = options?.type;
   const configChapters = options?.configChapters;
+  const projectRoot = options?.projectRoot;
   const EXCLUDE = new Set(["README.md", "AGENTS.sdd.md", "layout.md"]);
 
   if (type || configChapters?.length) {
-    const chapters = resolveChaptersOrder(type || "base", configChapters);
+    const chapters = resolveChaptersOrder(type || "base", configChapters, projectRoot);
     if (chapters.length > 0) {
       const existing = chapters.filter((f) => fs.existsSync(path.join(docsDir, f)));
       if (existing.length > 0) return existing;

package/src/docs/lib/resolver-factory.js

@@ -8,7 +8,7 @@
 
 import fs from "fs";
 import path from "path";
-import { sddDir, sddDataDir } from "../../lib/config.js";
+import { sddDir } from "../../lib/config.js";
 import { loadDataSources as loadDataSourcesBase } from "./data-source-loader.js";
 import { resolveMultiChains, resolveChainSafe } from "../../lib/presets.js";
 import { createLogger } from "../../lib/progress.js";
@@ -66,7 +66,7 @@ const COMMON_DATA_DIR = path.resolve(
  * @param {Object} ctx - 共有コンテキスト
  * @returns {Promise<Map<string, Object>>} DataSource マップ
  */
-async function loadChainDataSources(chain, root, ctx) {
+async function loadChainDataSources(chain, ctx) {
   let dataSources = await loadDataSources(COMMON_DATA_DIR, ctx);
 
   for (const preset of chain) {
@@ -74,10 +74,6 @@ async function loadChainDataSources(chain, root, ctx) {
     dataSources = await loadDataSources(dataDir, ctx, dataSources);
   }
 
-  // プロジェクト固有 DataSource（最高優先）
-  const projectDataDir = sddDataDir(root);
-  dataSources = await loadDataSources(projectDataDir, ctx, dataSources);
-
   return dataSources;
 }
 
@@ -92,11 +88,19 @@ async function loadChainDataSources(chain, root, ctx) {
  * @returns {Promise<{ resolve: (preset: string, source: string, method: string, analysis: Object, labels: string[]) => string|null }>}
  */
 export async function createResolver(type, root, opts) {
+  // Warn about deprecated .sdd-forge/data/ directory
+  if (root) {
+    const deprecatedDataDir = path.join(root, ".sdd-forge", "data");
+    if (fs.existsSync(deprecatedDataDir)) {
+      process.stderr.write(`[sdd-forge] WARN: .sdd-forge/data/ is deprecated. Move DataSources to .sdd-forge/presets/<type>/data/ instead.\n`);
+    }
+  }
+
   const desc = descFactory(root);
   const loadOverrides = () => loadOverridesFor(root);
   const ctx = { desc, loadOverrides, root, docsDir: opts?.docsDir, type, configChapters: opts?.configChapters };
 
-  const chains = resolveMultiChains(type);
+  const chains = resolveMultiChains(type, root);
 
   // 各チェーンの leaf key → DataSource マップ
   const resolverMap = new Map();
@@ -104,7 +108,7 @@ export async function createResolver(type, root, opts) {
   const ancestorMap = new Map();
   for (const chain of chains) {
     const leafKey = chain[chain.length - 1].key;
-    const dataSources = await loadChainDataSources(chain, root, ctx);
+    const dataSources = await loadChainDataSources(chain, ctx);
     resolverMap.set(leafKey, dataSources);
     // chain 内の全プリセットを ancestor マップに登録
     for (const p of chain) {

package/src/docs/lib/template-merger.js

@@ -28,9 +28,10 @@ const SPECIAL_FILES = new Set(["README.md", "AGENTS.sdd.md", "layout.md"]);
  * @param {string} presetKey - preset 名（例: "cakephp2", "node-cli"）
  * @param {string} lang - ロケール（例: "ja"）
  * @param {string|null} [projectLocalDir] - プロジェクトローカルテンプレートディレクトリ
+ * @param {string} [projectRoot] - プロジェクトルート（.sdd-forge/presets/ 検索用）
  * @returns {string[]} レイヤーディレクトリ配列（優先度高い順）
  */
-export function buildLayers(presetKey, lang, projectLocalDir) {
+export function buildLayers(presetKey, lang, projectLocalDir, projectRoot) {
   const layers = [];
 
   // 1. project-local（最高優先）
@@ -39,7 +40,7 @@ export function buildLayers(presetKey, lang, projectLocalDir) {
   }
 
   // 2. parent チェーンを leaf → root の順で追加（優先度高い順）
-  const chain = resolveChainSafe(presetKey);
+  const chain = resolveChainSafe(presetKey, projectRoot);
 
   // chain は root → leaf の順なので、逆順（leaf → root）で追加
   for (let i = chain.length - 1; i >= 0; i--) {
@@ -195,20 +196,21 @@ function mergeSourcesAdditive(sources) {
  * @param {string|null} [opts.projectLocalDir] - プロジェクトローカルテンプレートディレクトリ
  * @param {string[]} [opts.fallbackLangs] - フォールバック言語リスト
  * @param {string[]} [opts.chaptersOrder] - preset.json の chapters 順序配列
+ * @param {string} [opts.projectRoot] - プロジェクトルート（.sdd-forge/presets/ 検索用）
  * @returns {FileResolution[]}
  */
 export function resolveTemplates(typePath, lang, opts = {}) {
-  const { projectLocalDir, fallbackLangs, chaptersOrder } = opts;
+  const { projectLocalDir, fallbackLangs, chaptersOrder, projectRoot } = opts;
 
   const types = Array.isArray(typePath) ? typePath : [typePath];
 
   // 各チェーンの leaf key ごとにレイヤーセットを構築
-  const chains = resolveMultiChains(types);
+  const chains = resolveMultiChains(types, projectRoot);
   const chainLayerSets = chains.map((chain) => {
     const leafKey = chain[chain.length - 1].key;
     return {
       leafKey,
-      layers: buildLayers(leafKey, lang, projectLocalDir),
+      layers: buildLayers(leafKey, lang, projectLocalDir, projectRoot),
       fallbackSets: (fallbackLangs || [])
         .filter((l) => l !== lang)
         .map((fbLang) => ({
@@ -217,6 +219,7 @@ export function resolveTemplates(typePath, lang, opts = {}) {
             leafKey,
             fbLang,
             deriveFallbackProjectLocalDir(projectLocalDir, fbLang),
+            projectRoot,
           ),
         })),
     };
@@ -359,9 +362,10 @@ function discoverFileNames(layers, fallbackSets, chaptersOrder) {
  *
  * @param {string|string[]} presetKeys - preset 名または配列
  * @param {string[]} [configChapters] - config.json の chapters 配列（最優先）
+ * @param {string} [projectRoot] - プロジェクトルート（.sdd-forge/presets/ 検索用）
  * @returns {string[]} 章ファイル名の順序配列
  */
-export function resolveChaptersOrder(presetKeys, configChapters) {
+export function resolveChaptersOrder(presetKeys, configChapters, projectRoot) {
   // config.json の chapters が定義されていればプリセットを完全上書き
   if (configChapters?.length) {
     // Support both old string[] and new object[] formats
@@ -377,7 +381,7 @@ export function resolveChaptersOrder(presetKeys, configChapters) {
   const result = [];
 
   for (const key of keys) {
-    const chain = resolveChainSafe(key);
+    const chain = resolveChainSafe(key, projectRoot);
 
     // chain 内で最も具体的な（leaf 側の）chapters を使用する。
     // 子が chapters を定義していれば親の chapters は含めない（上書き）。

package/src/flow/commands/report.js

@@ -11,19 +11,53 @@ import { loadIssueLog } from "../lib/set-issue-log.js";
 import { pushSection, DIVIDER } from "../../lib/formatter.js";
 
 /**
- * Aggregate metrics across all phases.
- * @param {Object|null} metrics - flow.json metrics object keyed by phase
- * @returns {{ docsRead: number, srcRead: number, question: number, redo: number }}
+ * Iterate over each phase object in metrics, skipping null/non-object entries.
+ * @param {Object|null} metrics
+ * @param {(phase: Object) => void} fn
  */
-function aggregateMetrics(metrics) {
-  const totals = { docsRead: 0, srcRead: 0, question: 0, issueLog: 0 };
-  if (!metrics) return totals;
+function forEachPhase(metrics, fn) {
+  if (!metrics) return;
   for (const phase of Object.values(metrics)) {
     if (!phase || typeof phase !== "object") continue;
+    fn(phase);
+  }
+}
+
+/**
+ * Aggregate activity metrics (docs/src reads, Q&A, issue-log) across all phases.
+ * @param {Object|null} metrics - flow.json metrics object keyed by phase
+ * @returns {{ docsRead: number, srcRead: number, question: number, issueLog: number }}
+ */
+function aggregateActivityMetrics(metrics) {
+  const totals = { docsRead: 0, srcRead: 0, question: 0, issueLog: 0 };
+  forEachPhase(metrics, (phase) => {
     for (const key of Object.keys(totals)) {
       totals[key] += phase[key] || 0;
     }
-  }
+  });
+  return totals;
+}
+
+/**
+ * Aggregate token/cost metrics across all phases (R3-1, R3-2).
+ * @param {Object|null} metrics - flow.json metrics object keyed by phase
+ * @returns {{ input: number, output: number, cacheRead: number, cacheCreation: number, cost: number|null, callCount: number }}
+ */
+function aggregateTokenMetrics(metrics) {
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, cost: null, callCount: 0 };
+  forEachPhase(metrics, (phase) => {
+    if (phase.tokens) {
+      totals.input += phase.tokens.input || 0;
+      totals.output += phase.tokens.output || 0;
+      totals.cacheRead += phase.tokens.cacheRead || 0;
+      totals.cacheCreation += phase.tokens.cacheCreation || 0;
+    }
+    // R3-2: only accumulate cost when it has been recorded (never treat null as 0)
+    if (phase.cost != null) {
+      totals.cost = (totals.cost || 0) + phase.cost;
+    }
+    totals.callCount += phase.callCount || 0;
+  });
   return totals;
 }
 
@@ -64,7 +98,8 @@ export function generateReport(input) {
   };
 
   // Metrics
-  const metrics = aggregateMetrics(state.metrics);
+  const metrics = aggregateActivityMetrics(state.metrics);
+  const tokenMetrics = aggregateTokenMetrics(state.metrics);
 
   // Sync
   let sync;
@@ -88,7 +123,7 @@ export function generateReport(input) {
   }
 
   // Tests (R1, R3)
-  const testSummary = state.metrics?.test?.summary;
+  const testSummary = state.test?.summary;
   let tests = null;
   if (testSummary) {
     const unit = testSummary.unit || 0;
@@ -97,7 +132,7 @@ export function generateReport(input) {
     tests = { unit, integration, acceptance, total: unit + integration + acceptance };
   }
 
-  const data = { implementation, retro, issueLog: issueLogData, metrics, tests, sync };
+  const data = { implementation, retro, issueLog: issueLogData, metrics, tokenMetrics, tests, sync };
   const text = formatText(data);
 
   return { data, text };
@@ -148,10 +183,31 @@ function formatText(data) {
     lines.push("    -");
   }
 
-  // Metrics (single line)
+  const formatInt = (value) => Number(value || 0).toLocaleString("en-US");
+  const metricLine = (label, value) => {
+    const dots = ".".repeat(Math.max(1, 28 - label.length));
+    return `    ${label} ${dots} ${value}`;
+  };
+
+  // Metrics
   pushSection(lines, "Metrics", thin);
   const m = data.metrics;
-  lines.push(`    docs read ${m.docsRead}  src read ${m.srcRead}  Q&A ${m.question}  issue-log ${m.issueLog}`);
+  lines.push(metricLine("docs read", formatInt(m.docsRead)));
+  lines.push(metricLine("src read", formatInt(m.srcRead)));
+  lines.push(metricLine("Q&A", formatInt(m.question)));
+  lines.push(metricLine("issue-log", formatInt(m.issueLog)));
+
+  // Agent metrics (token/cost) — R3-1, R3-2
+  if (data.tokenMetrics && data.tokenMetrics.callCount > 0) {
+    const t = data.tokenMetrics;
+    const costStr = t.cost != null ? `$${t.cost.toFixed(4)}` : "N/A";
+    lines.push(metricLine("agent calls", formatInt(t.callCount)));
+    lines.push(metricLine("input tokens", formatInt(t.input)));
+    lines.push(metricLine("output tokens", formatInt(t.output)));
+    lines.push(metricLine("cache-read tokens", formatInt(t.cacheRead)));
+    lines.push(metricLine("cache-create tokens", formatInt(t.cacheCreation)));
+    lines.push(metricLine("cost", costStr));
+  }
 
   // Tests (always shown)
   pushSection(lines, "Tests", thin);

package/src/flow/commands/review.js

@@ -26,7 +26,7 @@ const callReviewAgent = (agent, prompt, root, systemPrompt) =>
   callAgentAwaitLog(agent, prompt, undefined, root, { systemPrompt });
 import { runCmd } from "../../lib/process.js";
 import { EXIT_ERROR } from "../../lib/exit-codes.js";
-import { VALID_PHASES } from "../lib/phases.js";
+import { VALID_PHASES } from "../../lib/constants.js";
 
 /** Maximum retry iterations for review auto-fix loops (test and spec). */
 const MAX_REVIEW_RETRIES = 3;
@@ -499,7 +499,7 @@ async function runTestReview(root, flow, config, dryRun) {
     process.exit(EXIT_ERROR);
   }
 
-  const agent = loadAgentConfig(config, "flow.review.test");
+  const agent = loadAgentConfig(config, "flow.test.review");
   ensureAgentWorkDir(agent, root);
 
   // Step 1: Generate test design
@@ -683,9 +683,9 @@ async function runSpecReview(root, flow, config, dryRun) {
     console.error(`  [spec-review] Warning: failed to load codebase context: ${e.message}`);
   }
 
-  const agent = loadAgentConfig(config, "flow.review.spec");
+  const agent = loadAgentConfig(config, "flow.spec.review");
   ensureAgentWorkDir(agent, root);
-  const validationAgent = loadAgentConfig(config, "flow.review.final");
+  const validationAgent = loadAgentConfig(config, "flow.impl.review.final");
   ensureAgentWorkDir(validationAgent, root);
 
   const { history, finalIssues, verdict } = await runReviewLoop({
@@ -829,7 +829,7 @@ async function main() {
 
   // --- Draft phase ---
   console.error("  [draft] Generating proposals...");
-  const draftAgent = loadAgentConfig(config, "flow.review.draft");
+  const draftAgent = loadAgentConfig(config, "flow.impl.review.draft");
   ensureAgentWorkDir(draftAgent, root);
   const draftResult = await callReviewAgent(draftAgent, diff, root, buildDraftSystemPrompt());
 
@@ -852,7 +852,7 @@ async function main() {
 
   // --- Final phase ---
   console.error("  [final] Validating proposals...");
-  const finalAgent = loadAgentConfig(config, "flow.review.final");
+  const finalAgent = loadAgentConfig(config, "flow.impl.review.final");
   ensureAgentWorkDir(finalAgent, root);
   const finalPrompt = [
     "Validate these refactoring proposals:",

package/src/flow/lib/get-check.js

@@ -8,10 +8,9 @@
 
 import { runCmd } from "../../lib/process.js";
 import { isGhAvailable } from "../../lib/git-helpers.js";
+import { VALID_CHECK_TARGETS } from "../../lib/constants.js";
 import { FlowCommand } from "./base-command.js";
 
-const VALID_TARGETS = ["impl", "finalize", "dirty", "gh"];
-
 const PREREQS = {
   impl: ["gate", "test"],
   finalize: ["implement"],
@@ -58,11 +57,11 @@ export default class GetCheckCommand extends FlowCommand {
     const target = ctx.target;
 
     if (!target) {
-      throw new Error(`target required. valid: ${VALID_TARGETS.join(", ")}`);
+      throw new Error(`target required. valid: ${VALID_CHECK_TARGETS.join(", ")}`);
     }
 
-    if (!VALID_TARGETS.includes(target)) {
-      throw new Error(`unknown target '${target}'. valid: ${VALID_TARGETS.join(", ")}`);
+    if (!VALID_CHECK_TARGETS.includes(target)) {
+      throw new Error(`unknown target '${target}'. valid: ${VALID_CHECK_TARGETS.join(", ")}`);
     }
 
     if (target === "dirty") {

package/src/flow/lib/get-context.js

@@ -15,7 +15,7 @@ import path from "path";
 import { sddOutputDir, loadConfig } from "../../lib/config.js";
 import { FlowCommand } from "./base-command.js";
 import { ANALYSIS_META_KEYS } from "../../docs/lib/analysis-entry.js";
-import { resolveAgent, callAgentWithLog } from "../../lib/agent.js";
+import { resolveAgent, callAgentWithLog, ensureAgentWorkDir } from "../../lib/agent.js";
 
 const EXCLUDE_FIELDS = new Set(["hash", "mtime", "lines", "id", "enrich", "detail"]);
 
@@ -215,10 +215,11 @@ function aiSearch(allEntries, analysis, query, root) {
 
   let config;
   try { config = loadConfig(root); } catch (_) { config = {}; }
-  const agent = resolveAgent(config, "context.search");
+  const agent = resolveAgent(config, "flow.context.search");
   if (!agent) return fallbackSearch(allEntries, query);
 
   const prompt = buildKeywordSelectionPrompt(allKeywords, query);
+  ensureAgentWorkDir(agent, root);
   let response;
   try {
     response = callAgentWithLog(agent, prompt, 30000, root);