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

package/README.md

@@ -129,6 +129,7 @@ See the [configuration reference](docs/configuration.md) for details.
 | [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.759",
+  "version": "0.1.0-alpha.774",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",
@@ -12,7 +12,8 @@
   },
   "exports": {
     ".": "./src/sdd-forge.js",
-    "./api": "./src/api.js"
+    "./api": "./src/api.js",
+    "./presets/*": "./src/presets/*"
   },
   "files": [
     "src/",

package/src/AGENTS.md

@@ -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/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/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" };

package/src/flow/commands/review.js

@@ -24,7 +24,7 @@ import { loadAgentConfig, callAgentAwaitLog, resolveAgent, ensureAgentWorkDir }
  */
 const callReviewAgent = (agent, prompt, root, systemPrompt) =>
   callAgentAwaitLog(agent, prompt, undefined, root, { systemPrompt });
-import { runCmd } from "../../lib/process.js";
+import { runGit } from "../../lib/git-helpers.js";
 import { EXIT_ERROR } from "../../lib/exit-codes.js";
 import { VALID_PHASES } from "../../lib/constants.js";
 
@@ -70,12 +70,7 @@ function resolveReviewTarget(root, flow) {
         for (const f of scopeFiles) {
           const abs = path.resolve(root, f);
           if (!fs.existsSync(abs)) continue;
-          // Committed changes against base branch
-          const committed = runCmd("git", ["-C", root, "diff", flow.baseBranch, "--", f]);
-          if (committed.ok && committed.stdout.trim()) diffs.push(committed.stdout);
-          // Staged but uncommitted changes
-          const staged = runCmd("git", ["-C", root, "diff", "--cached", "--", f]);
-          if (staged.ok && staged.stdout.trim()) diffs.push(staged.stdout);
+          diffs.push(...collectCommittedAndStagedDiff(root, flow.baseBranch, f));
         }
         if (diffs.length > 0) return diffs.join("\n");
       }
@@ -83,12 +78,24 @@ function resolveReviewTarget(root, flow) {
   }
 
   // Fallback: committed diff against base branch + staged changes
-  const parts = [];
-  const committed = runCmd("git", ["-C", root, "diff", flow.baseBranch]);
-  if (committed.ok && committed.stdout.trim()) parts.push(committed.stdout);
-  const staged = runCmd("git", ["-C", root, "diff", "--cached"]);
-  if (staged.ok && staged.stdout.trim()) parts.push(staged.stdout);
-  return parts.join("\n");
+  return collectCommittedAndStagedDiff(root, flow.baseBranch).join("\n");
+}
+
+/**
+ * Collect non-empty committed (vs base) and staged diff outputs.
+ * @param {string} root
+ * @param {string} baseBranch
+ * @param {string} [filePath] - optional path to scope the diff to
+ * @returns {string[]} array of non-empty diff outputs
+ */
+function collectCommittedAndStagedDiff(root, baseBranch, filePath) {
+  const out = [];
+  const fileArgs = filePath ? ["--", filePath] : [];
+  const committed = runGit(["-C", root, "diff", baseBranch, ...fileArgs]);
+  if (committed.ok && committed.stdout.trim()) out.push(committed.stdout);
+  const staged = runGit(["-C", root, "diff", "--cached", ...fileArgs]);
+  if (staged.ok && staged.stdout.trim()) out.push(staged.stdout);
+  return out;
 }
 
 /**

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

@@ -6,8 +6,7 @@
  * ctx.target — one of: impl, finalize, dirty, gh
  */
 
-import { runCmd } from "../../lib/process.js";
-import { isGhAvailable } from "../../lib/git-helpers.js";
+import { isGhAvailable, runGit } from "../../lib/git-helpers.js";
 import { VALID_CHECK_TARGETS } from "../../lib/constants.js";
 import { FlowCommand } from "./base-command.js";
 
@@ -29,7 +28,7 @@ function checkStepPrereqs(state, required) {
 }
 
 function checkDirty(root) {
-  const res = runCmd("git", ["status", "--short"], { cwd: root });
+  const res = runGit(["status", "--short"], { cwd: root });
   if (!res.ok) {
     return { pass: false, summary: "git status failed", checks: [{ id: "dirty", pass: false, message: res.stderr }] };
   }

package/src/flow/lib/run-finalize.js

@@ -15,7 +15,7 @@ import {
   resolveWorktreePaths, clearFlowState, specIdFromPath,
 } from "../../lib/flow-state.js";
 import { loadIssueLog, saveIssueLog } from "./set-issue-log.js";
-import { isGhAvailable, commentOnIssue, collectGitSummary } from "../../lib/git-helpers.js";
+import { isGhAvailable, commentOnIssue, collectGitSummary, runGit } from "../../lib/git-helpers.js";
 import { VALID_MERGE_STRATEGIES } from "../../lib/constants.js";
 import { FlowCommand } from "./base-command.js";
 import { FLOW_COMMANDS } from "../registry.js";
@@ -58,13 +58,13 @@ function executeCleanupImpl({ root, flowState, worktreePath, mainRepoPath }) {
   if (worktree && mainRepoPath) {
     const wtPath = worktreePath || root;
     if (fs.existsSync(wtPath)) {
-      runCmd("git", ["-C", mainRepoPath, "worktree", "remove", wtPath]);
+      runGit(["-C", mainRepoPath, "worktree", "remove", wtPath]);
     }
-    runCmd("git", ["-C", mainRepoPath, "branch", "-D", featureBranch]);
+    runGit(["-C", mainRepoPath, "branch", "-D", featureBranch]);
     return { status: "done" };
   }
 
-  runCmd("git", ["branch", "-D", featureBranch], { cwd: root });
+  runGit(["branch", "-D", featureBranch], { cwd: root });
   return { status: "done" };
 }
 
@@ -76,7 +76,7 @@ function executeCleanupImpl({ root, flowState, worktreePath, mainRepoPath }) {
  * @returns {{ status: string, message?: string }}
  */
 export function commitOrSkip(args, opts) {
-  const res = runCmd("git", ["commit", ...args], opts);
+  const res = runGit(["commit", ...args], opts);
   if (res.ok) return { status: "done" };
   const output = res.stderr || res.stdout || "";
   if (/nothing to commit|no changes added to commit/i.test(output)) {
@@ -86,7 +86,7 @@ export function commitOrSkip(args, opts) {
 }
 
 export function resolveGitCommonDir(root) {
-  const res = runCmd("git", ["-C", root, "rev-parse", "--git-common-dir"]);
+  const res = runGit(["-C", root, "rev-parse", "--git-common-dir"]);
   assertOk(res, "finalize preflight failed: unable to resolve git common dir");
   return path.resolve(root, res.stdout.trim());
 }
@@ -212,11 +212,12 @@ export async function executeCommitPost(ctx) {
   }
 
   // commit retro + report files
-  runCmd("git", ["add", "-A"], { cwd: root });
-  const commitRes = runCmd("git", ["commit", "-m", "chore: add retro and report"], { cwd: root });
-  if (!commitRes.ok && !/nothing to commit/i.test(commitRes.stderr || commitRes.stdout)) {
+  runGit(["add", "-A"], { cwd: root });
+  try {
+    commitOrSkip(["-m", "chore: add retro and report"], { cwd: root });
+  } catch (e) {
     if (results.report) {
-      results.report.commitNote = "retro/report commit failed: " + (commitRes.stderr || commitRes.stdout).slice(0, 200);
+      results.report.commitNote = "retro/report commit failed: " + String(e.message || e).slice(0, 200);
     }
   }
 }
@@ -274,7 +275,7 @@ export class RunFinalizeCommand extends FlowCommand {
         results.commit = { status: "dry-run", message: message || "(auto)" };
       } else {
         results.commit = await runSubStep("commit", () => {
-          runCmd("git", ["add", "-A"], { cwd: root });
+          runGit(["add", "-A"], { cwd: root });
           const msg = message || `feat: ${state.featureBranch || "finalize"}`;
           const res = commitOrSkip(["-m", msg], { cwd: root });
           return { ...res, message: msg };
@@ -329,12 +330,12 @@ export class RunFinalizeCommand extends FlowCommand {
           if (!buildRes.ok) {
             assertOk(buildRes, "docs build failed");
           }
-          runCmd("git", ["add", "docs/", "AGENTS.md", "CLAUDE.md", "README.md", ".sdd-forge/output/analysis.json"], { cwd: syncCwd });
+          runGit(["add", "docs/", "AGENTS.md", "CLAUDE.md", "README.md", ".sdd-forge/output/analysis.json"], { cwd: syncCwd });
           let diffStat = null;
           let diffSummary = null;
-          const statRes = runCmd("git", ["diff", "--cached", "--stat"], { cwd: syncCwd });
+          const statRes = runGit(["diff", "--cached", "--stat"], { cwd: syncCwd });
           if (statRes.ok) diffStat = statRes.stdout.trim();
-          const nameRes = runCmd("git", ["diff", "--cached", "--name-only"], { cwd: syncCwd });
+          const nameRes = runGit(["diff", "--cached", "--name-only"], { cwd: syncCwd });
           if (nameRes.ok) diffSummary = nameRes.stdout.trim();
           const commitRes = commitOrSkip(["-m", "docs: sync documentation"], { cwd: syncCwd });
           return { ...commitRes, ...(diffStat && { diffStat }), ...(diffSummary && { diffSummary }) };

package/src/flow/lib/run-gate.js

@@ -12,7 +12,8 @@
 
 import fs from "fs";
 import path from "path";
-import { runCmd, assertOk } from "../../lib/process.js";
+import { assertOk } from "../../lib/process.js";
+import { runGit } from "../../lib/git-helpers.js";
 import { callAgentWithLog, resolveAgent, ensureAgentWorkDir } from "../../lib/agent.js";
 import { filterByPhase, loadMergedGuardrails } from "../../lib/guardrail.js";
 import { getSpecName } from "../../lib/flow-state.js";
@@ -32,7 +33,7 @@ import { FlowCommand } from "./base-command.js";
  * @returns {string}
  */
 function runGitDiff(args, errorMessage, cwd) {
-  const res = runCmd("git", ["diff", ...args], { cwd });
+  const res = runGit(["diff", ...args], { cwd });
   assertOk(res, errorMessage);
   return res.stdout;
 }

package/src/flow/lib/run-impl-confirm.js

@@ -7,7 +7,7 @@
 
 import fs from "fs";
 import path from "path";
-import { runCmd } from "../../lib/process.js";
+import { runGit } from "../../lib/git-helpers.js";
 import { VALID_IMPL_CONFIRM_MODES } from "../../lib/constants.js";
 import { FlowCommand } from "./base-command.js";
 
@@ -18,7 +18,7 @@ import { FlowCommand } from "./base-command.js";
  * @returns {string[]} changed file paths
  */
 function getChangedFiles(root, baseBranch) {
-  const res = runCmd("git", ["-C", root, "diff", `${baseBranch}...HEAD`, "--name-only"]);
+  const res = runGit(["-C", root, "diff", `${baseBranch}...HEAD`, "--name-only"]);
   if (!res.ok) return [];
   return res.stdout.trim().split("\n").filter(Boolean);
 }

package/src/flow/lib/run-prepare-spec.js

@@ -9,17 +9,17 @@ import fs from "fs";
 import path from "path";
 import { isInsideWorktree } from "../../lib/cli.js";
 import { sddDir, DEFAULT_LANG } from "../../lib/config.js";
-import { runCmd, assertOk } from "../../lib/process.js";
+import { assertOk } from "../../lib/process.js";
 import { translate } from "../../lib/i18n.js";
 import {
   saveFlowState, buildInitialSteps, addActiveFlow, cleanStaleFlows,
   generateRunId, deletePreparingFlow, cleanStalePreparingFlows,
 } from "../../lib/flow-state.js";
-import { getWorktreeStatus } from "../../lib/git-helpers.js";
+import { getWorktreeStatus, runGit } from "../../lib/git-helpers.js";
 import { FlowCommand } from "./base-command.js";
 
-function runGit(root, args) {
-  const res = runCmd("git", ["-C", root, ...args]);
+function runGitTrim(root, args) {
+  const res = runGit(["-C", root, ...args]);
   if (res.ok) return res.stdout.trim();
   assertOk(res, `git ${args.join(" ")} failed`);
 }
@@ -44,7 +44,7 @@ function nextIndex(root) {
     }
   }
 
-  const branchLines = runGit(root, ["branch", "--list", "feature/[0-9][0-9][0-9]-*"])
+  const branchLines = runGitTrim(root, ["branch", "--list", "feature/[0-9][0-9][0-9]-*"])
     .split("\n")
     .map((x) => x.replace(/^[* ]+/, "").trim())
     .filter(Boolean);
@@ -57,7 +57,7 @@ function nextIndex(root) {
 }
 
 function ensureClean(root) {
-  const status = runGit(root, ["status", "--porcelain"]);
+  const status = runGitTrim(root, ["status", "--porcelain"]);
   if (status.trim()) {
     throw new Error("worktree is dirty. commit/stash before spec.");
   }
@@ -65,16 +65,17 @@ function ensureClean(root) {
 
 function ensureBaseBranch(root, base) {
   try {
-    runGit(root, ["rev-parse", "--verify", base]);
-  } catch (_) {
-    throw new Error(`base branch not found: ${base}`);
+    runGitTrim(root, ["rev-parse", "--verify", base]);
+  } catch (e) {
+    throw new Error(`base branch not found: ${base}: ${e.message}`);
   }
 }
 
 function detectBaseBranch(root) {
   try {
-    return runGit(root, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
-  } catch (_) {
+    return runGitTrim(root, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  } catch (e) {
+    process.stderr.write(`[sdd-forge] failed to detect current branch, falling back to "main": ${e.message}\n`);
     return "main";
   }
 }
@@ -273,7 +274,7 @@ export class RunPrepareSpecCommand extends FlowCommand {
     const lines = [];
 
     if (useWorktree) {
-      runGit(root, ["worktree", "add", worktreePath, "-b", branchName, resolvedBase]);
+      runGitTrim(root, ["worktree", "add", worktreePath, "-b", branchName, resolvedBase]);
       writeSpecFiles();
       writeFlowState({ worktree: true });
       addActiveFlow(root, specDirName, "worktree");
@@ -303,7 +304,7 @@ export class RunPrepareSpecCommand extends FlowCommand {
         `3) start implementation`,
       );
     } else {
-      runGit(root, ["checkout", "-b", branchName, resolvedBase]);
+      runGitTrim(root, ["checkout", "-b", branchName, resolvedBase]);
       writeSpecFiles();
       writeFlowState();
       addActiveFlow(root, specDirName, "branch");

package/src/flow/lib/run-retro.js

@@ -7,7 +7,7 @@
 
 import fs from "fs";
 import path from "path";
-import { runCmd } from "../../lib/process.js";
+import { runGit } from "../../lib/git-helpers.js";
 import { callAgentAwaitLog, resolveAgent, ensureAgentWorkDir } from "../../lib/agent.js";
 import { repairJson } from "../../lib/json-parse.js";
 import { getSpecName } from "../../lib/flow-state.js";
@@ -30,7 +30,7 @@ function extractRequirements(specText) {
  * Get git diff between base branch and HEAD.
  */
 function getDiff(root, baseBranch) {
-  const res = runCmd("git", ["diff", `${baseBranch}...HEAD`, "--stat"], { cwd: root });
+  const res = runGit(["diff", `${baseBranch}...HEAD`, "--stat"], { cwd: root });
   return res.ok ? res.stdout.trim() : "";
 }
 
@@ -38,7 +38,7 @@ function getDiff(root, baseBranch) {
  * Get detailed diff for AI evaluation.
  */
 function getDetailedDiff(root, baseBranch) {
-  const res = runCmd("git", ["diff", `${baseBranch}...HEAD`], { cwd: root });
+  const res = runGit(["diff", `${baseBranch}...HEAD`], { cwd: root });
   return res.ok ? res.stdout.trim() : "";
 }
 

package/src/flow/lib/run-sync.js

@@ -7,6 +7,7 @@
 
 import { PKG_DIR } from "../../lib/cli.js";
 import { runCmd, assertOk } from "../../lib/process.js";
+import { runGit } from "../../lib/git-helpers.js";
 import { FlowCommand } from "./base-command.js";
 import path from "path";
 
@@ -56,11 +57,11 @@ export class RunSyncCommand extends FlowCommand {
     }
 
     // Step 3: git add (ignore errors for missing files)
-    runCmd("git", ["add", "docs/", "AGENTS.md", "CLAUDE.md", "README.md", ".sdd-forge/output/"], { cwd: root });
+    runGit(["add", "docs/", "AGENTS.md", "CLAUDE.md", "README.md", ".sdd-forge/output/"], { cwd: root });
 
     // Collect changed files
     let changed = [];
-    const diffRes = runCmd("git", ["diff", "--cached", "--name-only"], { cwd: root });
+    const diffRes = runGit(["diff", "--cached", "--name-only"], { cwd: root });
     if (diffRes.ok) {
       const diff = diffRes.stdout.trim();
       changed = diff ? diff.split("\n").filter(Boolean) : [];
@@ -68,7 +69,7 @@ export class RunSyncCommand extends FlowCommand {
 
     // Step 4: commit (skip if nothing to commit)
     if (changed.length > 0) {
-      const commitRes = runCmd("git", ["commit", "-m", "docs: sync documentation"], { cwd: root });
+      const commitRes = runGit(["commit", "-m", "docs: sync documentation"], { cwd: root });
       if (!commitRes.ok && !/nothing to commit/i.test(commitRes.stderr || commitRes.stdout)) {
         assertOk(commitRes, "git commit failed");
       }

package/src/lib/cli.js

@@ -25,6 +25,8 @@ export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url))
  */
 export function repoRoot(importMetaUrl) {
   if (process.env.SDD_FORGE_WORK_ROOT) return process.env.SDD_FORGE_WORK_ROOT;
+  // Logger 基盤の依存元のため runCmd を直接使う。runGit に変更してはならない
+  // （Logger.git → resolveLogDir → repoRoot → runGit → Logger.git で無限再帰になる）。
   const res = runCmd("git", ["rev-parse", "--show-toplevel"]);
   if (res.ok) return res.stdout.trim();
   // npm パッケージとしてインストールされた場合、相対パス推定は
@@ -104,6 +106,8 @@ export function isInsideWorktree(root) {
  * @returns {string} メインリポジトリの絶対パス
  */
 export function getMainRepoPath(root) {
+  // Logger 基盤の依存元のため runCmd を直接使う。runGit に変更してはならない
+  // （Logger.git → resolveLogDir → getMainRepoPath → runGit → Logger.git で無限再帰になる）。
   const res = runCmd("git", ["-C", root, "rev-parse", "--git-common-dir"]);
   assertOk(res, "failed to resolve git-common-dir");
   const gitCommonDir = res.stdout.trim();

package/src/lib/flow-state.js

@@ -9,7 +9,7 @@
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
-import { runCmd } from "./process.js";
+import { runGit } from "./git-helpers.js";
 import { sddDir } from "./config.js";
 import { isInsideWorktree, getMainRepoPath } from "./cli.js";
 
@@ -18,6 +18,7 @@ const ACTIVE_FLOW_FILE = ".active-flow";
 const PREPARING_PREFIX = ".active-flow.";
 const PREPARING_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const PREPARING_SCAN_LIMIT = 100;
+const SCAN_FLOWS_LIMIT = 200;
 
 /**
  * Extract the spec name (e.g. "152-add-logger-to-callsites") from a flow object or state.
@@ -182,10 +183,29 @@ export function removeActiveFlow(workRoot, specId) {
  * @param {string} branch
  * @returns {boolean}
  */
+/**
+ * Run a git query and apply a stdout predicate; on git failure, log to stderr
+ * and return `true` (fail-open: prevents accidental deletion when status is unknown).
+ * @param {string[]} args - git arguments
+ * @param {(stdout: string) => boolean} predicate
+ * @param {string} contextLabel - label used in the stderr warning
+ * @returns {boolean}
+ */
+function runGitFailOpenBoolean(args, predicate, contextLabel) {
+  const res = runGit(args);
+  if (!res.ok) {
+    process.stderr.write(`[sdd-forge] ${contextLabel}: git ${args.join(" ")} failed, assuming exists: ${res.stderr}\n`);
+    return true;
+  }
+  return predicate(res.stdout);
+}
+
 function worktreeExists(mainRoot, branch) {
-  const res = runCmd("git", ["-C", mainRoot, "worktree", "list", "--porcelain"]);
-  if (!res.ok) return true; // on error, assume exists (avoid accidental deletion)
-  return res.stdout.includes(`branch refs/heads/${branch}`);
+  return runGitFailOpenBoolean(
+    ["-C", mainRoot, "worktree", "list", "--porcelain"],
+    (stdout) => stdout.includes(`branch refs/heads/${branch}`),
+    "worktreeExists",
+  );
 }
 
 /**
@@ -195,9 +215,11 @@ function worktreeExists(mainRoot, branch) {
  * @returns {boolean}
  */
 function branchExists(mainRoot, branch) {
-  const res = runCmd("git", ["-C", mainRoot, "branch", "--list", branch]);
-  if (!res.ok) return true; // on error, assume exists
-  return res.stdout.trim().length > 0;
+  return runGitFailOpenBoolean(
+    ["-C", mainRoot, "branch", "--list", branch],
+    (stdout) => stdout.trim().length > 0,
+    "branchExists",
+  );
 }
 
 /**
@@ -397,7 +419,7 @@ function resolveCurrentFlow(workRoot, flows) {
 
   // Try matching by current branch
   let currentBranch;
-  const res = runCmd("git", ["-C", workRoot, "rev-parse", "--abbrev-ref", "HEAD"]);
+  const res = runGit(["-C", workRoot, "rev-parse", "--abbrev-ref", "HEAD"]);
   if (!res.ok) return null;
   currentBranch = res.stdout.trim();
 
@@ -491,7 +513,7 @@ export function loadFlowState(workRoot, specId) {
  * @returns {string|null}
  */
 function specIdFromBranch(workRoot) {
-  const res = runCmd("git", ["-C", workRoot, "rev-parse", "--abbrev-ref", "HEAD"]);
+  const res = runGit(["-C", workRoot, "rev-parse", "--abbrev-ref", "HEAD"]);
   if (!res.ok) return null;
   const branch = res.stdout.trim();
   const prefix = "feature/";
@@ -732,12 +754,14 @@ export function scanAllFlows(workRoot) {
   const mainRoot = resolveMainRoot(workRoot);
   const results = [];
   const seen = new Set();
+  let truncated = false;
 
   // 1. Local: specs/*/ in main repo (with or without flow.json)
   const specsDir = path.join(mainRoot, "specs");
   if (fs.existsSync(specsDir)) {
     for (const entry of fs.readdirSync(specsDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || !/^\d{3}-/.test(entry.name)) continue;
+      if (results.length >= SCAN_FLOWS_LIMIT) { truncated = true; break; }
       const fp = path.join(specsDir, entry.name, STATE_FILE);
       if (fs.existsSync(fp)) {
         const state = JSON.parse(fs.readFileSync(fp, "utf8"));
@@ -751,54 +775,64 @@ export function scanAllFlows(workRoot) {
   }
 
   // 2. Worktrees: scan each worktree's specs/*/flow.json
-  const wtRes = runCmd("git", ["-C", mainRoot, "worktree", "list", "--porcelain"]);
-  if (wtRes.ok) {
-    const output = wtRes.stdout;
-    let wtPath = null;
-    for (const line of output.split("\n")) {
-      if (line.startsWith("worktree ")) {
-        wtPath = line.slice("worktree ".length);
-      } else if (line === "" && wtPath && wtPath !== mainRoot) {
-        const wtSpecs = path.join(wtPath, "specs");
-        if (fs.existsSync(wtSpecs)) {
-          for (const entry of fs.readdirSync(wtSpecs, { withFileTypes: true })) {
-            if (!entry.isDirectory() || seen.has(entry.name)) continue;
-            const fp = path.join(wtSpecs, entry.name, STATE_FILE);
-            if (fs.existsSync(fp)) {
-              const state = JSON.parse(fs.readFileSync(fp, "utf8"));
-              results.push({ specId: entry.name, mode: "worktree", state, location: wtPath });
-              seen.add(entry.name);
+  if (!truncated) {
+    const wtRes = runGit(["-C", mainRoot, "worktree", "list", "--porcelain"]);
+    if (wtRes.ok) {
+      const output = wtRes.stdout;
+      let wtPath = null;
+      outer: for (const line of output.split("\n")) {
+        if (line.startsWith("worktree ")) {
+          wtPath = line.slice("worktree ".length);
+        } else if (line === "" && wtPath && wtPath !== mainRoot) {
+          const wtSpecs = path.join(wtPath, "specs");
+          if (fs.existsSync(wtSpecs)) {
+            for (const entry of fs.readdirSync(wtSpecs, { withFileTypes: true })) {
+              if (!entry.isDirectory() || seen.has(entry.name)) continue;
+              if (results.length >= SCAN_FLOWS_LIMIT) { truncated = true; break outer; }
+              const fp = path.join(wtSpecs, entry.name, STATE_FILE);
+              if (fs.existsSync(fp)) {
+                const state = JSON.parse(fs.readFileSync(fp, "utf8"));
+                results.push({ specId: entry.name, mode: "worktree", state, location: wtPath });
+                seen.add(entry.name);
+              }
             }
           }
+          wtPath = null;
         }
-        wtPath = null;
       }
     }
   }
 
   // 3. Branches: check feature/* branches for specs/*/flow.json
-  const branchRes = runCmd("git", ["-C", mainRoot, "branch", "--list", "feature/*"]);
-  if (branchRes.ok) {
-    for (const line of branchRes.stdout.split("\n")) {
-      const branch = line.replace(/^[*+ ]+/, "").trim();
-      if (!branch) continue;
-      const specId = branch.replace("feature/", "");
-      if (seen.has(specId)) continue;
-      const showRes = runCmd(
-        "git", ["-C", mainRoot, "show", `${branch}:specs/${specId}/flow.json`],
-      );
-      if (showRes.ok) {
-        try {
-          const state = JSON.parse(showRes.stdout);
-          results.push({ specId, mode: "branch", state, location: `branch:${branch}` });
-          seen.add(specId);
-        } catch (_) {
-          // invalid JSON, skip
+  if (!truncated) {
+    const branchRes = runGit(["-C", mainRoot, "branch", "--list", "feature/*"]);
+    if (branchRes.ok) {
+      for (const line of branchRes.stdout.split("\n")) {
+        const branch = line.replace(/^[*+ ]+/, "").trim();
+        if (!branch) continue;
+        const specId = branch.replace("feature/", "");
+        if (seen.has(specId)) continue;
+        if (results.length >= SCAN_FLOWS_LIMIT) { truncated = true; break; }
+        const showRes = runGit(
+          ["-C", mainRoot, "show", `${branch}:specs/${specId}/flow.json`],
+        );
+        if (showRes.ok) {
+          try {
+            const state = JSON.parse(showRes.stdout);
+            results.push({ specId, mode: "branch", state, location: `branch:${branch}` });
+            seen.add(specId);
+          } catch (e) {
+            process.stderr.write(`[sdd-forge] scanAllFlows: invalid JSON in ${branch}:specs/${specId}/flow.json: ${e.message}\n`);
+          }
         }
       }
     }
   }
 
+  if (truncated) {
+    process.stderr.write(`[sdd-forge] scanAllFlows: truncated at ${SCAN_FLOWS_LIMIT} entries\n`);
+  }
+
   return results;
 }
 

package/src/lib/git-helpers.js

@@ -6,10 +6,31 @@
  */
 
 import { runCmd, formatError } from "./process.js";
+import { Logger } from "./log.js";
+
+/**
+ * Run a git command and record a JSONL log entry via Logger.
+ *
+ * All "business" git operations (commit, push, diff, branch, merge, worktree, status, log, etc.)
+ * SHOULD go through this wrapper instead of calling `runCmd("git", ...)` directly,
+ * so they are uniformly logged.
+ *
+ * Exception: git invocations that the Logger itself depends on (repo top-level /
+ * git-common-dir resolution in `cli.js`) MUST stay on `runCmd` to avoid recursion.
+ *
+ * @param {string[]} args - git argument array (without the leading "git")
+ * @param {Object}   [opts] - same shape as runCmd opts
+ * @returns {{ ok: boolean, status: number, stdout: string, stderr: string, signal: string|null, killed: boolean }}
+ */
+export function runGit(args, opts = {}) {
+  const result = runCmd("git", args, opts);
+  Logger.getInstance().git({ cmd: ["git", ...args], exitCode: result.status, stderr: result.stderr });
+  return result;
+}
 
 /** @returns {{ dirty: boolean, dirtyFiles: string[] }} */
 export function getWorktreeStatus(cwd) {
-  const res = runCmd("git", ["status", "--short"], { cwd });
+  const res = runGit(["status", "--short"], { cwd });
   if (!res.ok) return { dirty: false, dirtyFiles: [] };
   const files = res.stdout.trim().split("\n").filter(Boolean);
   return { dirty: files.length > 0, dirtyFiles: files };
@@ -17,19 +38,19 @@ export function getWorktreeStatus(cwd) {
 
 /** @returns {string|null} */
 export function getCurrentBranch(cwd) {
-  const res = runCmd("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
+  const res = runGit(["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
   return res.ok ? res.stdout.trim() : null;
 }
 
 /** @returns {number} */
 export function getAheadCount(cwd, baseBranch) {
-  const res = runCmd("git", ["rev-list", "--count", `${baseBranch}..HEAD`], { cwd });
+  const res = runGit(["rev-list", "--count", `${baseBranch}..HEAD`], { cwd });
   return res.ok ? parseInt(res.stdout.trim(), 10) || 0 : 0;
 }
 
 /** @returns {string|null} */
 export function getLastCommit(cwd) {
-  const res = runCmd("git", ["log", "-1", "--oneline"], { cwd });
+  const res = runGit(["log", "-1", "--oneline"], { cwd });
   return res.ok ? res.stdout.trim() : null;
 }
 
@@ -47,9 +68,9 @@ export function isGhAvailable() {
 export function collectGitSummary(root, baseBranch) {
   let diffStat = "";
   let commitMessages = [];
-  const diffRes = runCmd("git", ["diff", "--stat", `${baseBranch}...HEAD`], { cwd: root });
+  const diffRes = runGit(["diff", "--stat", `${baseBranch}...HEAD`], { cwd: root });
   if (diffRes.ok) diffStat = diffRes.stdout.trim();
-  const logRes = runCmd("git", ["log", "--format=%s", `${baseBranch}..HEAD`], { cwd: root });
+  const logRes = runGit(["log", "--format=%s", `${baseBranch}..HEAD`], { cwd: root });
   if (logRes.ok) commitMessages = logRes.stdout.trim().split("\n").filter(Boolean);
   return { diffStat, commitMessages };
 }

package/src/lib/lint.js

@@ -7,7 +7,8 @@
 
 import fs from "fs";
 import path from "path";
-import { runCmd, assertOk } from "./process.js";
+import { assertOk } from "./process.js";
+import { runGit } from "./git-helpers.js";
 import { filterByPhase, matchScope } from "./guardrail.js";
 
 /**
@@ -35,7 +36,7 @@ export function validateLintGuardrails(guardrails) {
  * @returns {string[]} Relative file paths
  */
 export function getChangedFiles(root, base) {
-  const res = runCmd("git", ["-C", root, "diff", "--name-only", `${base}...HEAD`]);
+  const res = runGit(["-C", root, "diff", "--name-only", `${base}...HEAD`]);
   if (!res.ok) {
     assertOk(res, "git diff failed");
   }

package/src/lib/process.js

@@ -6,11 +6,13 @@
  */
 
 import { execFileSync, execFile } from "child_process";
-import { Logger } from "./log.js";
 
 /**
  * Run a command synchronously.
  *
+ * Pure command runner: no domain-specific logging is performed here.
+ * For git command logging, callers should use `runGit` from `git-helpers.js`.
+ *
  * @param {string}   cmd  - Command to execute
  * @param {string[]} args - Argument array
  * @param {Object}   [opts]
@@ -31,12 +33,9 @@ export function runCmd(cmd, args, opts = {}) {
       stdio: ["pipe", "pipe", "pipe"],
       ...(opts.env && { env: opts.env }),
     });
-    const result = { ok: true, status: 0, stdout: String(stdout || ""), stderr: "", signal: null, killed: false };
-    // TODO: git logging in runCmd causes infinite recursion via resolveLogDir → getMainRepoPath → runCmd
-    // if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: 0, stderr: "" });
-    return result;
+    return { ok: true, status: 0, stdout: String(stdout || ""), stderr: "", signal: null, killed: false };
   } catch (e) {
-    const result = {
+    return {
       ok: false,
       status: e.status ?? 1,
       stdout: String(e.stdout || ""),
@@ -44,9 +43,6 @@ export function runCmd(cmd, args, opts = {}) {
       signal: e.signal ?? null,
       killed: e.killed ?? false,
     };
-    // TODO: git logging in runCmd causes infinite recursion via resolveLogDir → getMainRepoPath → runCmd
-    // if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: result.status, stderr: result.stderr });
-    return result;
   }
 }
 
@@ -96,8 +92,6 @@ export function runCmdAsync(cmd, args, opts = {}) {
             killed: false,
           };
         }
-        // TODO: git logging in runCmdAsync causes infinite recursion via resolveLogDir → getMainRepoPath → runCmd
-        // if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: result.status, stderr: result.stderr });
         resolve(result);
       },
     );

package/src/locale/en/messages.json

@@ -107,7 +107,7 @@
   "init": {
     "noType": "ERROR: type is not set. Set \"type\" in .sdd-forge/config.json or use --type option.",
     "noTemplates": "ERROR: no template files found in chain",
-    "conflictsExist": "ERROR: {{count}} file(s) already exist in docs/:",
+    "conflictsExist": "WARN: {{count}} file(s) already exist in docs/:",
     "useForce": "Use --force to overwrite.",
     "aiFilterFailed": "[init] WARN: AI chapter selection failed: {{message}}",
     "aiResponseInvalid": "[init] WARN: AI response is not valid JSON, skipping AI filter.",

package/src/locale/ja/messages.json

@@ -107,7 +107,7 @@
   "init": {
     "noType": "ERROR: type が設定されていません。.sdd-forge/config.json に \"type\" を設定するか --type オプションを指定してください。",
     "noTemplates": "ERROR: テンプレートファイルがチェーン内に見つかりません",
-    "conflictsExist": "ERROR: {{count}} 件のファイルが docs/ に既に存在します:",
+    "conflictsExist": "WARN: {{count}} 件のファイルが docs/ に既に存在します:",
     "useForce": "--force で上書きできます。",
     "aiFilterFailed": "[init] WARN: AI 章選択に失敗: {{message}}",
     "aiResponseInvalid": "[init] WARN: AI レスポンスが有効な JSON ではありません。AI フィルタをスキップします。",