phasegate 0.283.0 → 0.335.0

package/scripts/harness/agent-integration/infrastructure/adapters/file-system-full-mode-session-query-adapter.ts

@@ -1,17 +1,59 @@
 // @unit agent-integration
 // @layer infrastructure
 // @work-item-id WI-206
+// @work-item-id WI-348
+// @work-item-id WI-350
 
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ConfigQueryPort } from "../../domain/ports/config-query-port.js";
 import type {
   FullModeSessionQueryInput,
   FullModeSessionQueryPort,
   FullModeSessionQueryResult,
-} from '../../domain/ports/full-mode-session-query-port.js';
-import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
-import { WriteTargetScope } from '../../domain/value-objects/write-target-scope.js';
+} from "../../domain/ports/full-mode-session-query-port.js";
+import { WriteTargetScope } from "../../domain/value-objects/write-target-scope.js";
+
+/**
+ * quick-mode の `ChangeCategoryValue` と同一の語彙。
+ * 照合相手は quick-mode 分類結果（`dominantCategory`）なので、この語彙以外は
+ * session.json 側の書式誤りとして扱う。
+ * `session begin` 側との同期は
+ * `__tests__/integration/harness-api/session-begin-allowed-categories.integration.test.ts`
+ * が検証する（WI-348）。
+ */
+const KNOWN_CHANGE_CATEGORIES: ReadonlySet<string> = new Set([
+  "bugfix",
+  "docs",
+  "test",
+  "config",
+  "feature",
+  "domain",
+  "api",
+]);
+
+/**
+ * WI-348: v0.301.0 以前の `phasegate session begin` は allowedCategories に
+ * レイヤー名（domain / application / infrastructure / presentation / config）を
+ * 書き出していた。この語彙は ChangeCategory と domain / config でしか交差せず、
+ * 旧形式 session.json をそのまま照合すると feature / api / bugfix などが
+ * 恒常的に拒否され session が事実上無力化する。
+ *
+ * `session begin` はカテゴリ指定フラグを持たず常に定数を書き出すため、
+ * 「ChangeCategory 語彙に無い値が混ざっている」= 旧形式生成物と判断できる。
+ * その場合のみ全カテゴリ許可へ正規化する。
+ * 全要素が既知カテゴリなら手編集による意図的な絞り込みとみなし原文を尊重する。
+ * unit / 期限 / target path のスコープ判定は正規化後も従来どおり効く。
+ */
+function normalizeAllowedCategories(rawCategories: readonly string[]): readonly string[] {
+  if (rawCategories.length === 0) {
+    return rawCategories;
+  }
+  if (rawCategories.every((value) => KNOWN_CHANGE_CATEGORIES.has(value))) {
+    return rawCategories;
+  }
+  return [...KNOWN_CHANGE_CATEGORIES];
+}
 
 interface FullModeSessionDocument {
   readonly mode?: unknown;
@@ -35,52 +77,62 @@ export class FileSystemFullModeSessionQueryAdapter implements FullModeSessionQue
   async check(input: FullModeSessionQueryInput): Promise<FullModeSessionQueryResult> {
     let document: FullModeSessionDocument;
     try {
-      const raw = await fs.readFile(path.join(this.options.rootDir, '.phasegate', 'session.json'), 'utf8');
+      const raw = await fs.readFile(path.join(this.options.rootDir, ".phasegate", "session.json"), "utf8");
       document = JSON.parse(raw) as FullModeSessionDocument;
     } catch {
-      return { active: false, allowed: false, reason: 'session marker not found or unreadable' };
+      return { active: false, allowed: false, reason: "session marker not found or unreadable" };
     }
 
-    if (document.mode !== 'full') {
-      return { active: false, allowed: false, reason: 'session mode is not full' };
+    if (document.mode !== "full") {
+      return { active: false, allowed: false, reason: "session mode is not full" };
     }
-    if (typeof document.unit !== 'string' || document.unit === '') {
-      return { active: true, allowed: false, reason: 'session unit is missing' };
+    if (typeof document.unit !== "string" || document.unit === "") {
+      return { active: true, allowed: false, reason: "session unit is missing" };
     }
-    if (typeof document.workItemId !== 'string' || !/^WI-\d+$/.test(document.workItemId)) {
-      return { active: true, allowed: false, reason: 'session work item is invalid' };
+    if (typeof document.workItemId !== "string" || !/^WI-\d+$/.test(document.workItemId)) {
+      return { active: true, allowed: false, reason: "session work item is invalid" };
     }
-    if (typeof document.expiresAt !== 'string' || Number.isNaN(Date.parse(document.expiresAt))) {
-      return { active: true, allowed: false, reason: 'session expiry is invalid' };
+    if (typeof document.expiresAt !== "string" || Number.isNaN(Date.parse(document.expiresAt))) {
+      return { active: true, allowed: false, reason: "session expiry is invalid" };
     }
     if ((this.options.now?.() ?? new Date()).getTime() >= Date.parse(document.expiresAt)) {
       return {
         active: true,
         allowed: false,
-        reason: 'session expired',
+        reason: "session expired",
         workItemId: document.workItemId,
         unit: document.unit,
         expiresAt: document.expiresAt,
       };
     }
-    if (!Array.isArray(document.allowedCategories) || document.allowedCategories.some((value) => typeof value !== 'string')) {
-      return { active: true, allowed: false, reason: 'session allowedCategories is invalid' };
+    if (
+      !Array.isArray(document.allowedCategories) ||
+      document.allowedCategories.some((value) => typeof value !== "string")
+    ) {
+      return { active: true, allowed: false, reason: "session allowedCategories is invalid" };
     }
-    if (input.dominantCategory === undefined || !document.allowedCategories.includes(input.dominantCategory)) {
+    const allowedCategories = normalizeAllowedCategories(document.allowedCategories as readonly string[]);
+    if (input.dominantCategory === undefined || !allowedCategories.includes(input.dominantCategory)) {
       return {
         active: true,
         allowed: false,
-        reason: `category ${input.dominantCategory ?? '<unknown>'} is not allowed by session`,
+        reason: `category ${input.dominantCategory ?? "<unknown>"} is not allowed by session`,
         workItemId: document.workItemId,
         unit: document.unit,
         expiresAt: document.expiresAt,
       };
     }
-    if (input.unitId === undefined || input.unitId !== document.unit) {
+    // WI-350: unit を持たないパス（プロジェクト直下のファイル・__tests__ 配下など）は
+    // 集約 unitId が undefined になる。旧実装はこれを即拒否していたが、
+    // 直下の allTargetPathsBelongToUnit は unitless パスを許容しており内部矛盾していた。
+    // 集約チェックは「unitId が定義済みかつ session unit と不一致」の場合のみ拒否し、
+    // unitless は per-path チェックへ委ねる。unit 付きパスが 1 つでも混ざれば
+    // per-path 側が従来どおり拒否するため、unit 境界は緩まない。
+    if (input.unitId !== undefined && input.unitId !== document.unit) {
       return {
         active: true,
         allowed: false,
-        reason: `target unit ${input.unitId ?? '<unknown>'} does not match session unit ${document.unit}`,
+        reason: `target unit ${input.unitId} does not match session unit ${document.unit}`,
         workItemId: document.workItemId,
         unit: document.unit,
         expiresAt: document.expiresAt,

package/scripts/harness/agent-integration/infrastructure/adapters/harness-config-config-query-adapter.ts

@@ -83,9 +83,24 @@ export class HarnessConfigConfigQueryAdapter implements ConfigQueryPort {
     // GitHub #40: config が JSON として壊れている場合に hook プロセス全体を throw で
     // 落とすと、エージェントの全ツール呼び出しが遮断され config の修復自体が不能になる。
     // main.ts の ConfigPersistenceError と同じ意味論（警告 + 既定値で続行）に揃える。
-    // ファイル不在等の fs エラーは既存契約どおり throw する（上流の catch が defaults を
-    // 適用する）。gated スコープへの書き込みは phase-gate 側が fail-closed でブロックする。
-    const raw = fs.readFileSync(this.configPath, "utf8");
+    // ADR-038 §4 G1 / WI-333: config **不在**（ENOENT）も同じデッドロックを起こすため、
+    // invalid-json と同じ「警告 + 既定値で続行」の fail-open とする。config を作成する
+    // Write 自体が遮断されない（自己修復経路が残る）ことがこの adapter の契約。
+    // それ以外の fs エラー（EACCES 等の真の異常）は従来どおり throw する。
+    // gated スコープへの書き込みは phase-gate 側が既定設定で fail-closed を維持する。
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.configPath, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        process.stderr.write(
+          `Warning: phasegate.config.json not found at ${this.configPath}; continuing with default hook settings so self-repair stays possible (run \`phasegate init\` to generate one).\n`,
+        );
+        this.cachedConfig = {};
+        return this.cachedConfig;
+      }
+      throw error;
+    }
     let doc: HarnessConfigDocument;
     try {
       doc = JSON.parse(raw) as HarnessConfigDocument;

package/scripts/harness/agent-integration/infrastructure/adapters/quick-mode-full-mode-requirement-adapter.ts

@@ -1,5 +1,6 @@
 // @unit agent-integration
 // @layer infrastructure
+// @work-item-id WI-373
 
 import type {
   FullModeRequirementQueryPort,
@@ -7,6 +8,7 @@ import type {
   FullModeTargetChange,
 } from '../../domain/ports/full-mode-requirement-query-port.js';
 import type { ClassifyChangeCategoryUseCase } from '../../../quick-mode/application/usecases/classify-change-category-usecase.js';
+import { QuickModeConfigError } from '../../../quick-mode/domain/errors/quick-mode-config-error.js';
 
 export interface QuickModeFullModeRequirementAdapterDeps {
   classifyUseCaseFactory: () => ClassifyChangeCategoryUseCase;
@@ -45,7 +47,19 @@ export class QuickModeFullModeRequirementAdapter implements FullModeRequirementQ
         rejectionReason: contract.rejectionReason,
         dominantCategory: contract.dominantCategory ?? undefined,
       };
-    } catch {
+    } catch (error) {
+      // WI-373: quickMode 設定そのものが不正な場合は fail-closed。
+      // allowedCategories / categoryOverrides の enum 検証が入ったことで
+      // config の typo が例外になるため、ここで一律 fail-open のままだと
+      // 「設定を壊すと全書き込みが素通りする」という最悪の穴になる。
+      // config 不在・IO エラー等その他の例外は WI-333 の fail-open を維持する。
+      if (error instanceof QuickModeConfigError) {
+        return {
+          requiresFullMode: true,
+          rejectionRule: 'MIXED_CHANGES',
+          rejectionReason: `quickMode 設定が不正なため Quick Mode 判定を実行できません: ${error.message}`,
+        };
+      }
       return { requiresFullMode: false };
     }
   }

package/scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts

@@ -4,6 +4,9 @@
  * @work-item-id WI-202 / WI-204
  * @work-item-id WI-206
  * @work-item-id WI-208
+ * @work-item-id WI-345
+ * @work-item-id WI-347
+ * @work-item-id WI-376
  *
  * PreToolUse Hook Adapter
  * Claude Code の PreToolUse Hook エントリポイント
@@ -23,10 +26,14 @@ import { createQuickModeCompositionRoot } from '../../quick-mode/composition-roo
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 
+/**
+ * WI-376 (ADR-039): 呼び出し元 skill 名を受け取るフィールド（caller_skill）は持たない。
+ * Claude Code の PreToolUse payload に skill 情報は無く、エージェントの自己申告値は
+ * authorization / guidance の入力にしない。未知キーが来ても単に無視される。
+ */
 interface PreToolUseHookInput {
   cwd?: string;
   tool_name?: string;
-  caller_skill?: string;
   tool_input?: {
     path?: string;
     file_path?: string;
@@ -80,8 +87,10 @@ function projectRootForConfig(configPath: string): string {
   return path.basename(configDir) === '.phasegate-local' ? path.dirname(configDir) : configDir;
 }
 
-function isProjectExternalAbsolutePath(filePath: string): boolean {
-  return path.isAbsolute(filePath);
+function isProjectExternalPath(filePath: string, cwd: string, projectRoot: string): boolean {
+  const resolvedPath = path.resolve(cwd, filePath);
+  const relativePath = path.relative(projectRoot, resolvedPath);
+  return relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
 }
 
 async function main(): Promise<void> {
@@ -141,15 +150,29 @@ async function main(): Promise<void> {
     const bashTargets = extractor.extract(input.tool_input.command);
     if (bashTargets.length > 0) {
       targetFilePaths.push(...bashTargets.map(toRelative));
+      const recordedTargetPaths = new Set(targetChanges.map((change) => change.filePath));
+      const bashTargetChanges = await Promise.all(
+        bashTargets.map((bashTarget) => buildBashTargetChange(cwd, bashTarget, toRelative)),
+      );
+      for (const change of bashTargetChanges) {
+        if (!recordedTargetPaths.has(change.filePath)) {
+          targetChanges.push(change);
+          recordedTargetPaths.add(change.filePath);
+        }
+      }
       effectiveToolName = 'Write';
     }
   }
 
   try {
     const configPath = await findConfigPath(cwd);
-    const projectTargetFilePaths = targetFilePaths.filter((filePath) => !isProjectExternalAbsolutePath(filePath));
-    const projectTargetChanges = targetChanges.filter((change) => !isProjectExternalAbsolutePath(change.filePath));
     const projectRoot = projectRootForConfig(configPath);
+    const projectTargetFilePaths = targetFilePaths.filter(
+      (filePath) => !isProjectExternalPath(filePath, cwd, projectRoot),
+    );
+    const projectTargetChanges = targetChanges.filter(
+      (change) => !isProjectExternalPath(change.filePath, cwd, projectRoot),
+    );
     const configQueryPort = new HarnessConfigConfigQueryAdapter(configPath);
     const phaseGateQueryPort = new PhaseGateQueryAdapter();
     const storyReflectionQueryPort = new FileSystemStoryReflectionQueryAdapter({
@@ -157,7 +180,8 @@ async function main(): Promise<void> {
       configPath,
     });
     const fullModeRequirementQueryPort = new QuickModeFullModeRequirementAdapter({
-      classifyUseCaseFactory: () => createQuickModeCompositionRoot().classifyUseCase,
+      classifyUseCaseFactory: () =>
+        createQuickModeCompositionRoot({ configPath, rootDir: projectRoot }).classifyUseCase,
     });
     const baselineGrandfatherQueryPort = new CiGovernanceBaselineGrandfatherAdapter({
       baseDir: projectRoot,
@@ -180,11 +204,9 @@ async function main(): Promise<void> {
       fullModeSessionQueryPort,
     });
 
-    const callerSkill = input.caller_skill ?? process.env.PHASEGATE_CALLER_SKILL;
     const output = await useCase.execute({
       toolName: effectiveToolName,
       targetFilePaths: projectTargetFilePaths,
-      callerSkill,
       targetChanges: projectTargetChanges,
     });
 
@@ -222,7 +244,7 @@ async function buildTargetChanges(
   toRelative: (p: string) => string,
 ): Promise<TargetChange[]> {
   const toolInput = input.tool_input;
-  if (toolInput === undefined) {
+  if (toolInput == null || typeof toolInput !== 'object') {
     return [];
   }
 
@@ -258,6 +280,32 @@ async function readExistingContent(cwd: string, filePath: string): Promise<strin
   }
 }
 
+async function buildBashTargetChange(
+  cwd: string,
+  rawPath: string,
+  toRelative: (p: string) => string,
+): Promise<TargetChange> {
+  const filePath = toRelative(rawPath);
+  if (rawPath.includes('$') || rawPath.includes('`') || rawPath.startsWith('~')) {
+    // hook ではシェル展開後の実パスを解決できないため、存在チェックを避けて MODIFY 既定にする。
+    return { filePath };
+  }
+  const absolutePath = path.isAbsolute(rawPath) ? rawPath : path.join(cwd, rawPath);
+  try {
+    await fs.stat(absolutePath);
+    return { filePath };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      // Bash では afterContent を取得できないため、空文字を CREATE 判定用の
+      // 「変更後内容あり」sentinel として渡す。実ファイルへの書き込みは行わない。
+      return { filePath, beforeContent: null, afterContent: '' };
+    }
+    // 権限エラー等で存在を確認できない場合は従来どおり MODIFY 既定（安全側）。
+    return { filePath };
+  }
+}
+
 main().catch((error) => {
   process.stderr.write(`予期しないエラー: ${String(error)}\n`);
   process.exit(2);

package/scripts/harness/ci-governance/application/dto/scaffold-inception-input.ts

@@ -0,0 +1,9 @@
+// @unit ci-governance
+// @layer application
+// @work-item-id WI-368
+
+export interface ScaffoldInceptionInput {
+  readonly kind: string;
+  readonly dryRun?: boolean;
+  readonly force?: boolean;
+}

package/scripts/harness/ci-governance/application/dto/scaffold-inception-output.ts

@@ -0,0 +1,13 @@
+// @unit ci-governance
+// @layer application
+// @work-item-id WI-368
+
+export interface ScaffoldInceptionOutput {
+  readonly targetPath: string;
+  readonly templatePath: string;
+  readonly kind: string;
+  readonly dryRun: boolean;
+  readonly written: boolean;
+  readonly alreadyExists: boolean;
+  readonly overwritten: boolean;
+}

package/scripts/harness/ci-governance/application/usecases/list-templates-usecase.ts

@@ -0,0 +1,30 @@
+// @unit ci-governance
+// @layer application
+// @work-item-id WI-367
+
+import type { TemplateCatalogPort } from "../../domain/ports/template-catalog-port.js";
+
+export interface ListTemplatesOutputEntry {
+  readonly name: string;
+  readonly fileName: string;
+}
+
+export interface ListTemplatesOutput {
+  readonly directoryPath: string;
+  readonly templates: readonly ListTemplatesOutputEntry[];
+}
+
+export class ListTemplatesUseCase {
+  constructor(private readonly catalog: TemplateCatalogPort) {}
+
+  async execute(): Promise<ListTemplatesOutput> {
+    const entries = await this.catalog.list();
+    return {
+      directoryPath: this.catalog.directoryPath(),
+      templates: entries.map((entry) => ({
+        name: entry.name.value,
+        fileName: entry.fileName,
+      })),
+    };
+  }
+}

package/scripts/harness/ci-governance/application/usecases/scaffold-inception-usecase.ts

@@ -0,0 +1,63 @@
+// @unit ci-governance
+// @layer application
+// @work-item-id WI-368
+
+import type { InceptionDocWriterPort } from "../../domain/ports/inception-doc-writer-port.js";
+import type { InceptionTemplateRepositoryPort } from "../../domain/ports/inception-template-repository-port.js";
+import { InceptionDocKind } from "../../domain/value-objects/inception-doc-kind.js";
+import type { ScaffoldInceptionInput } from "../dto/scaffold-inception-input.js";
+import type { ScaffoldInceptionOutput } from "../dto/scaffold-inception-output.js";
+
+export class ScaffoldInceptionUseCase {
+  constructor(
+    private readonly templates: InceptionTemplateRepositoryPort,
+    private readonly writer: InceptionDocWriterPort,
+  ) {}
+
+  async execute(input: ScaffoldInceptionInput): Promise<ScaffoldInceptionOutput> {
+    const kind = InceptionDocKind.create(input.kind);
+    const dryRun = input.dryRun === true;
+    const force = input.force === true;
+
+    const templatePath = this.templates.resolvePath(kind);
+    const targetPath = this.writer.resolvePath(kind);
+    const alreadyExists = await this.writer.exists(kind);
+
+    if (dryRun) {
+      return {
+        targetPath,
+        templatePath,
+        kind: kind.value,
+        dryRun: true,
+        written: false,
+        alreadyExists,
+        overwritten: false,
+      };
+    }
+
+    if (alreadyExists && !force) {
+      return {
+        targetPath,
+        templatePath,
+        kind: kind.value,
+        dryRun: false,
+        written: false,
+        alreadyExists: true,
+        overwritten: false,
+      };
+    }
+
+    const raw = await this.templates.read(kind);
+    await this.writer.write(kind, raw);
+
+    return {
+      targetPath,
+      templatePath,
+      kind: kind.value,
+      dryRun: false,
+      written: true,
+      alreadyExists,
+      overwritten: alreadyExists && force,
+    };
+  }
+}

package/scripts/harness/ci-governance/application/usecases/show-template-usecase.ts

@@ -0,0 +1,39 @@
+// @unit ci-governance
+// @layer application
+// @work-item-id WI-367
+
+import type { TemplateCatalogPort } from "../../domain/ports/template-catalog-port.js";
+import { TemplateName } from "../../domain/value-objects/template-name.js";
+
+export type ShowTemplateOutput =
+  | { readonly found: true; readonly name: string; readonly content: string }
+  | {
+      readonly found: false;
+      readonly reason: "invalid-name" | "not-found";
+      readonly availableNames: readonly string[];
+    };
+
+export class ShowTemplateUseCase {
+  constructor(private readonly catalog: TemplateCatalogPort) {}
+
+  async execute(rawName: string): Promise<ShowTemplateOutput> {
+    if (!TemplateName.isValid(rawName)) {
+      // 不正名では catalog を引かない。パス由来の情報を一切露出させない。
+      return { found: false, reason: "invalid-name", availableNames: [] };
+    }
+
+    const name = TemplateName.create(rawName);
+    const content = await this.catalog.read(name);
+
+    if (content === null) {
+      const entries = await this.catalog.list();
+      return {
+        found: false,
+        reason: "not-found",
+        availableNames: entries.map((entry) => entry.name.value),
+      };
+    }
+
+    return { found: true, name: name.value, content };
+  }
+}

package/scripts/harness/ci-governance/composition-root.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit ci-governance
+ * @work-item-id WI-367, WI-368, WI-369
  *
  * Composition Root - 依存性の組み立て
  */
@@ -10,6 +11,7 @@ import { CheckAgentContextUseCase } from "./application/usecases/check-agent-con
 import { CheckEscalationUseCase } from "./application/usecases/check-escalation-usecase.js";
 import { CreateBaselineUseCase } from "./application/usecases/create-baseline-usecase.js";
 import { GenerateCiTemplateUseCase } from "./application/usecases/generate-ci-template-usecase.js";
+import { ListTemplatesUseCase } from "./application/usecases/list-templates-usecase.js";
 import { MigrateAgentsMdUseCase } from "./application/usecases/migrate-agents-md-usecase.js";
 import { PinIntegrityUseCase } from "./application/usecases/pin-integrity-usecase.js";
 import { RecordErrorOccurrenceUseCase } from "./application/usecases/record-error-occurrence-usecase.js";
@@ -18,6 +20,8 @@ import { RefreshClaudeMdUseCase } from "./application/usecases/refresh-claude-md
 import { RenderCiTemplateUseCase } from "./application/usecases/render-ci-template-usecase.js";
 import { ResetRepetitionUseCase } from "./application/usecases/reset-repetition-usecase.js";
 import { ScaffoldDesignUseCase } from "./application/usecases/scaffold-design-usecase.js";
+import { ScaffoldInceptionUseCase } from "./application/usecases/scaffold-inception-usecase.js";
+import { ShowTemplateUseCase } from "./application/usecases/show-template-usecase.js";
 import { ValidatePointersUseCase } from "./application/usecases/validate-pointers-usecase.js";
 import { VerifyIntegrityUseCase } from "./application/usecases/verify-integrity-usecase.js";
 import { ClaudeMdComposer } from "./domain/services/claude-md-composer.js";
@@ -34,8 +38,11 @@ import { ErrorRepetitionJsonRepository } from "./infrastructure/adapters/error-r
 import { EscalationLogExecutorAdapter } from "./infrastructure/adapters/escalation-log-executor-adapter.js";
 import { FileSystemDesignDocWriterAdapter } from "./infrastructure/adapters/file-system-design-doc-writer-adapter.js";
 import { FileSystemExistenceAdapter } from "./infrastructure/adapters/file-system-existence-adapter.js";
+import { FileSystemInceptionDocWriterAdapter } from "./infrastructure/adapters/file-system-inception-doc-writer-adapter.js";
+import { FileSystemInceptionTemplateRepositoryAdapter } from "./infrastructure/adapters/file-system-inception-template-repository-adapter.js";
 import { FileSystemSha1HasherAdapter } from "./infrastructure/adapters/file-system-sha1-hasher-adapter.js";
 import { FileSystemSha256HasherAdapter } from "./infrastructure/adapters/file-system-sha256-hasher-adapter.js";
+import { FileSystemTemplateCatalogAdapter } from "./infrastructure/adapters/file-system-template-catalog-adapter.js";
 import { FileSystemTemplateRepositoryAdapter } from "./infrastructure/adapters/file-system-template-repository-adapter.js";
 import { GlobFileScannerAdapter } from "./infrastructure/adapters/glob-file-scanner-adapter.js";
 import { HarnessApiCommandExistenceAdapter } from "./infrastructure/adapters/harness-api-command-existence-adapter.js";
@@ -53,6 +60,8 @@ import { MigrateAgentsMdHandler } from "./presentation/handlers/migrate-agents-m
 import { RefreshAgentContextHandler } from "./presentation/handlers/refresh-agent-context-handler.js";
 import { RefreshClaudeMdHandler } from "./presentation/handlers/refresh-claude-md-handler.js";
 import { ScaffoldDesignHandler } from "./presentation/handlers/scaffold-design-handler.js";
+import { ScaffoldInceptionHandler } from "./presentation/handlers/scaffold-inception-handler.js";
+import { TemplatesHandler } from "./presentation/handlers/templates-handler.js";
 
 export interface CiGovernanceCompositionRoot {
   generateCiTemplateHandler: GenerateCiTemplateHandler;
@@ -63,6 +72,8 @@ export interface CiGovernanceCompositionRoot {
   checkRepetitionHandler: CheckRepetitionHandler;
   createBaselineHandler: CreateBaselineHandler;
   scaffoldDesignHandler: ScaffoldDesignHandler;
+  scaffoldInceptionHandler: ScaffoldInceptionHandler;
+  templatesHandler: TemplatesHandler;
   // Use cases exposed for direct access
   recordErrorOccurrenceUseCase: RecordErrorOccurrenceUseCase;
   checkEscalationUseCase: CheckEscalationUseCase;
@@ -71,10 +82,33 @@ export interface CiGovernanceCompositionRoot {
   validatePointersUseCase: ValidatePointersUseCase;
   createBaselineUseCase: CreateBaselineUseCase;
   scaffoldDesignUseCase: ScaffoldDesignUseCase;
+  scaffoldInceptionUseCase: ScaffoldInceptionUseCase;
   integrityHandler: IntegrityHandler;
 }
 
-export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir): CiGovernanceCompositionRoot {
+/**
+ * 解決済みの設計文書ルート（`phasegate.config.json` の `paths`）。
+ * 省略時は従来どおり `docs/product/construction` / `docs/inception` を使う。
+ *
+ * WI-369: これを渡さないと `scaffold-design` の書き込み先が
+ * `docs/product/construction` に固定され、`paths.designDocs` を移設した PJ で
+ * scaffold 先とフェーズゲートの検査先がズレる。
+ */
+export interface CiGovernanceDocPaths {
+  readonly designDocs?: string;
+  readonly inceptionDocs?: string;
+}
+
+const DEFAULT_DESIGN_DOCS_ROOT = "docs/product/construction";
+const DEFAULT_INCEPTION_DOCS_ROOT = "docs/inception";
+
+export function buildCiGovernance(
+  baseDir: string,
+  harnessRoot: string = baseDir,
+  docPaths: CiGovernanceDocPaths = {},
+): CiGovernanceCompositionRoot {
+  const designDocsRoot = docPaths.designDocs ?? DEFAULT_DESIGN_DOCS_ROOT;
+  const inceptionDocsRoot = docPaths.inceptionDocs ?? DEFAULT_INCEPTION_DOCS_ROOT;
   // Infrastructure adapters
   const validatorIdRegistryAdapter = new ValidatorIdRegistryAdapter();
   const presetConfigAdapter = new PresetConfigAdapter();
@@ -119,20 +153,35 @@ export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir
   const baselineRepository = new BaselineJsonRepositoryAdapter(baseDir);
   const createBaselineUseCase = new CreateBaselineUseCase(fileScanner, fileHasher, baselineRepository);
 
-  // Scaffold design adapters & use case (ISSUE-007 Wave 4)
+  // Scaffold design adapters & use case (ISSUE-007 Wave 4 / WI-369 paths 追従)
   const templateRepository = new FileSystemTemplateRepositoryAdapter(harnessRoot);
-  const designDocWriter = new FileSystemDesignDocWriterAdapter(baseDir);
+  const designDocWriter = new FileSystemDesignDocWriterAdapter(baseDir, designDocsRoot);
   const scaffoldDesignUseCase = new ScaffoldDesignUseCase(templateRepository, designDocWriter);
 
+  // Scaffold inception adapters & use case (WI-368)
+  const inceptionTemplateRepository = new FileSystemInceptionTemplateRepositoryAdapter(harnessRoot);
+  const inceptionDocWriter = new FileSystemInceptionDocWriterAdapter(baseDir, {
+    designDocsRoot,
+    inceptionDocsRoot,
+  });
+  const scaffoldInceptionUseCase = new ScaffoldInceptionUseCase(inceptionTemplateRepository, inceptionDocWriter);
+
+  // Template catalog adapters & use cases (WI-367)
+  const templateCatalog = new FileSystemTemplateCatalogAdapter(harnessRoot);
+  const listTemplatesUseCase = new ListTemplatesUseCase(templateCatalog);
+  const showTemplateUseCase = new ShowTemplateUseCase(templateCatalog);
+
   // Handlers
   const generateCiTemplateHandler = new GenerateCiTemplateHandler(generateCiTemplateUseCase, renderCiTemplateUseCase);
-  const migrateAgentsMdHandler = new MigrateAgentsMdHandler(migrateAgentsMdUseCase);
+  const migrateAgentsMdHandler = new MigrateAgentsMdHandler(migrateAgentsMdUseCase, validatePointersUseCase);
   const refreshAgentContextHandler = new RefreshAgentContextHandler(refreshAgentContextUseCase);
   const refreshClaudeMdHandler = new RefreshClaudeMdHandler(refreshClaudeMdUseCase);
   const checkAgentContextHandler = new CheckAgentContextHandler(checkAgentContextUseCase);
-  const checkRepetitionHandler = new CheckRepetitionHandler(checkEscalationUseCase);
+  const checkRepetitionHandler = new CheckRepetitionHandler(checkEscalationUseCase, resetRepetitionUseCase);
   const createBaselineHandler = new CreateBaselineHandler(createBaselineUseCase);
   const scaffoldDesignHandler = new ScaffoldDesignHandler(scaffoldDesignUseCase);
+  const scaffoldInceptionHandler = new ScaffoldInceptionHandler(scaffoldInceptionUseCase);
+  const templatesHandler = new TemplatesHandler(listTemplatesUseCase, showTemplateUseCase);
 
   // Integrity pin adapters & handler (WI-254 / ADR-030 §Decision.3.①)
   const integrityChecker = new IntegrityChecker();
@@ -156,6 +205,8 @@ export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir
     checkRepetitionHandler,
     createBaselineHandler,
     scaffoldDesignHandler,
+    scaffoldInceptionHandler,
+    templatesHandler,
     recordErrorOccurrenceUseCase,
     checkEscalationUseCase,
     resetRepetitionUseCase,
@@ -163,6 +214,7 @@ export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir
     validatePointersUseCase,
     createBaselineUseCase,
     scaffoldDesignUseCase,
+    scaffoldInceptionUseCase,
     integrityHandler,
   };
 }