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

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,13 @@ 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… |
+| [Preset Creation Guide](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/creating_presets.md) |  |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.702",
+  "version": "0.1.0-alpha.774",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",
@@ -10,12 +10,17 @@
   "bin": {
     "sdd-forge": "./src/sdd-forge.js"
   },
+  "exports": {
+    ".": "./src/sdd-forge.js",
+    "./api": "./src/api.js",
+    "./presets/*": "./src/presets/*"
+  },
   "files": [
     "src/",
     "!src/presets/*/tests/"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.19.0"
   },
   "keywords": [
     "sdd",
@@ -25,7 +30,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 が内部で呼ぶ）
@@ -152,16 +152,12 @@ base → api → graphql
 ```
 presets/<key>/
 ├── preset.json              プリセット定義
-├── data/                    DataSource クラス群
+├── data/                    DataSource クラス群（scan + resolve を兼ねる）
 │   ├── config.js            設定解析
 │   ├── controllers.js       コントローラ解析
 │   └── ...
-├── scan/                    scan パーサー群
-│   ├── routes.js            ルート解析
-│   ├── config.js            設定解析
-│   └── ...
 ├── tests/                   プリセット固有テスト
-│   ├── unit/                ユニットテスト（scan パーサー I/O テスト等）
+│   ├── unit/                ユニットテスト（DataSource の match/parse I/O テスト等）
 │   ├── e2e/                 E2E テスト（統合スキャンテスト等）
 │   └── acceptance/          acceptance テスト（preset ローカル fixture + test.js）
 └── templates/               章テンプレート
@@ -177,21 +173,36 @@ presets/<key>/
 
 ## プリセット作成ルール
 
+### MUST: プリセット作成ガイドとの同期
+
+プリセットの仕様・作成手順・契約（`preset.json` スキーマ、DataSource のインターフェース、`match()` / `parse()` の引数契約、resolve メソッドの戻り値型、import ルール、テンプレートディレクティブ、scan/data ペアリング規則等）を変更した場合、**`.sdd-forge/templates/*/docs/creating_presets.md`（全言語）を同じコミット内で必ず更新すること。**
+
+対象となる変更の例:
+
+- `src/api.js` の公開クラス追加・削除・シグネチャ変更
+- `package.json` の `exports` 変更
+- `DataSource` / `Scannable` / `AnalysisEntry` / `Table` / `MarkdownText` のインターフェース変更
+- `preset.json` スキーマの追加・変更
+- `data/` loader のロード規約変更
+- テンプレートディレクティブ（`{%extends%}`, `{%block%}`, `{{data}}`, `{{text}}`）の文法・挙動変更
+- プリセット作成手順・MUST ルールの追加・変更
+
+本ガイドは AI エージェントがプリセットを作成する際の単一の参照ドキュメントである。**ガイドが実装とズレるとプリセット作成が破綻する**ため、実装変更と文書更新を同一 PR で行うこと。別 PR に分割してはならない。
+
 ### MUST: プリセット作成手順（トップダウン設計）
 
 プリセットの構成要素は以下の順序で作成すること:
 
 1. **テンプレート** (`templates/`) — どんなドキュメントを出力するか定義する
-2. **DataSource** (`data/`) — テンプレートが必要とするデータを定義する
-3. **scan パーサー** (`scan/`) — DataSource にデータを供給するパーサーを実装する
+2. **DataSource** (`data/`) — テンプレートが必要とするデータを `Scannable` DataSource の `match` / `parse` / `scan` で収集し、resolve メソッドで提供する
 
-消費者（テンプレート）→ 仲介者（DataSource）→ 生産者（scan）の順に作ることで、不要なパーサーを書かず、必要なデータの漏れがなくなる。
+消費者（テンプレート）→ 生産者（DataSource）の順に作ることで、不要な解析を書かず、必要なデータの漏れがなくなる。scan 処理は独立した `scan/` ディレクトリではなく DataSource クラス自身が `Scannable` mixin 経由で担う。
 
 ### MUST: プリセットテストの作成
 
 プリセットは `tests/` ディレクトリを含むこと。
 
-- `tests/unit/` — scan パーサーの I/O テスト。最小限のフィクスチャを `createTmpDir()` で作成し、パーサー関数の入出力を検証する
+- `tests/unit/` — DataSource の `match` / `parse` I/O テスト。最小限のフィクスチャを `createTmpDir()` で作成し、入出力を検証する
 - `tests/e2e/` — preset.json の scan 設定検証、フルスキャンパイプラインテスト
 - `tests/acceptance/test.js` — preset ローカル fixture を使う acceptance テスト。共有処理は `tests/acceptance/lib/` を使う
 - テンプレートを作成・変更した場合は acceptance テストも実装し、実行すること
@@ -295,6 +306,42 @@ export default class SchemaSource extends DataSource {
 - analysis にデータがあれば動作する（なければ null を返す）
 - **MUST**: このパターンを使う場合、読む analysis キーを書く scan DataSource がチェーン内に存在する必要がある。対応する scan がないなら data DataSource を作ってはならない
 
+### DataSource メソッドの戻り値型（設計方針）
+
+DataSource の resolve メソッド（`list()` / `tables()` 等、テンプレートから `{{data}}` で呼ばれるメソッド）の戻り値は、**レンダリング可能な値クラスのインスタンスまたは null** とする。生の Markdown 文字列を返してはならない。
+
+プロジェクトは TypeScript を採用しないため、値の構造は OOP（クラス）で表現する（プロジェクト `CLAUDE.md` の「OOP による型表現」を参照）。戻り値には以下の専用クラスを用いる。
+
+- `Table` — 表形式データ（labels と rows を保持、列数の整合を invariant として強制）
+- `MarkdownText` — そのまま埋め込む Markdown 断片
+- （必要に応じて）`BulletList` / `Heading` 等の追加クラス
+
+```javascript
+import { Table } from "../../../docs/lib/renderable.js";
+
+export default class RoutesSource extends DataSource {
+  list(analysis, labels) {
+    const routes = analysis.routes?.entries || [];
+    if (routes.length === 0) return null;
+    const rows = routes.map(r => [r.pattern, r.controller, r.action]);
+    return new Table(labels, rows);
+  }
+}
+```
+
+**利点**:
+
+- コンストラクタで invariant を強制（例: Table は列数一致、labels 非空）
+- `instanceof` による確実な型判別
+- `toMarkdown()` を型に所属させることで、出力形式の拡張（将来の `toHtml()` 等）が Open/Closed に従う
+- テンプレート展開層は `result.toMarkdown()` をポリモルフィックに呼ぶだけで済む
+- オブジェクトリテラル（`{ type: "table", ... }`）のような discriminated union もどきは採用しない
+
+**禁止事項**:
+
+- 基底 `DataSource` の `toMarkdownTable()` のような Markdown 文字列生成ヘルパーを新設してはならない（既存のものは `Table` クラスへの段階移行対象）
+- 戻り値として生の文字列を返してはならない。構造が単なるテキストなら `MarkdownText` でラップする
+
 ---
 
 ## テンプレート構文

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/data-source-loader.js

@@ -6,9 +6,9 @@
 
 import fs from "fs";
 import path from "path";
-import { createLogger } from "../../lib/progress.js";
+import { pathToFileURL } from "url";
 
-const logger = createLogger("datasource");
+const MAX_DATA_SOURCE_FILES = 1000;
 
 /**
  * Load DataSource classes from a directory and instantiate them.
@@ -23,22 +23,34 @@ const logger = createLogger("datasource");
 export async function loadDataSources(dataDir, opts) {
   const { existing, onInstance } = opts || {};
   const sources = new Map(existing || []);
-  if (!fs.existsSync(dataDir)) return sources;
-
-  const files = fs.readdirSync(dataDir).filter((f) => f.endsWith(".js"));
+  let entries;
+  try {
+    entries = await fs.promises.readdir(dataDir);
+  } catch (err) {
+    if (err.code === "ENOENT") return sources;
+    throw err;
+  }
+  const files = entries.filter((f) => f.endsWith(".js"));
+  if (files.length > MAX_DATA_SOURCE_FILES) {
+    throw new Error(
+      `DataSource directory ${dataDir} contains ${files.length} files, exceeding limit ${MAX_DATA_SOURCE_FILES}`,
+    );
+  }
   for (const file of files) {
     const name = path.basename(file, ".js");
+    const filePath = path.join(dataDir, file);
+    let mod;
     try {
-      const mod = await import(path.join(dataDir, file));
-      const Source = mod.default;
-      if (typeof Source === "function") {
-        const instance = new Source();
-        instance._sourceFilePath = path.join(dataDir, file);
-        if (onInstance && onInstance(instance, name) === false) continue;
-        sources.set(name, instance);
-      }
+      mod = await import(pathToFileURL(filePath).href);
     } catch (err) {
-      logger.verbose(`failed to load DataSource ${name}: ${err.message}`);
+      throw new Error(`failed to load DataSource at ${filePath}: ${err.message}`, { cause: err });
+    }
+    const Source = mod.default;
+    if (typeof Source === "function") {
+      const instance = new Source();
+      instance._sourceFilePath = filePath;
+      if (onInstance && onInstance(instance, name) === false) continue;
+      sources.set(name, instance);
     }
   }
   return sources;

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/merge.js

@@ -9,7 +9,7 @@ import { readFileSync } from "fs";
 import { runCmd, assertOk } from "../../lib/process.js";
 import path from "path";
 import { loadConfig } from "../../lib/config.js";
-import { isGhAvailable } from "../../lib/git-helpers.js";
+import { isGhAvailable, runGit } from "../../lib/git-helpers.js";
 
 /**
  * Resolve push remote from config.
@@ -165,7 +165,7 @@ function main(ctx) {
     const title = buildPrTitle(spec, fallbackTitle);
     const body = buildPrBody(state, spec);
 
-    const pushRes = runCmd("git", ["push", "-u", remote, featureBranch]);
+    const pushRes = runGit(["push", "-u", remote, featureBranch]);
     assertOk(pushRes, "git push failed");
     const prRes = runCmd("gh", [
       "pr", "create",
@@ -185,12 +185,12 @@ function main(ctx) {
   function runSquashMerge(gitPrefix, hint) {
     const mergeArgs = [...gitPrefix, "merge", "--squash", featureBranch];
     const resetArgs = [...gitPrefix, "reset", "--merge"];
-    const mergeRes = runCmd("git", mergeArgs);
+    const mergeRes = runGit(mergeArgs);
     if (!mergeRes.ok) {
-      runCmd("git", resetArgs);
+      runGit(resetArgs);
       throw new Error(`Merge conflict detected. ${hint}`);
     }
-    const commitRes = runCmd("git", [...gitPrefix, "commit", "-m", commitMsg]);
+    const commitRes = runGit([...gitPrefix, "commit", "-m", commitMsg]);
     assertOk(commitRes, "commit after squash merge failed");
   }
 
@@ -200,7 +200,7 @@ function main(ctx) {
   }
 
   // Branch mode
-  const checkoutRes = runCmd("git", ["checkout", baseBranch]);
+  const checkoutRes = runGit(["checkout", baseBranch]);
   assertOk(checkoutRes, "git checkout failed");
   runSquashMerge([], `Run 'git rebase ${baseBranch}' and retry finalize.`);
   return { strategy: "squash" };