phasegate 0.315.0 → 0.340.0

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

@@ -0,0 +1,228 @@
+/**
+ * @unit agent-integration
+ * @layer presentation
+ * @work-item-id WI-385
+ *
+ * Runtime 固有の未信頼 payload を、agent 名に依存せず canonical input へ変換する。
+ */
+
+import type {
+  CanonicalPreToolUseInput,
+  HookResponseProfile,
+  NormalizedPreToolUseRequest,
+  PayloadShape,
+  PreToolUseNormalizationResult,
+} from "../application/dto/normalized-pre-tool-use-request.js";
+
+type UnknownRecord = Record<string, unknown>;
+
+const PATH_KEYS = ["file_path", "filePath", "TargetFile", "targetFile", "target_file", "path"] as const;
+const CONTENT_KEYS = ["content", "CodeContent", "codeContent"] as const;
+const OLD_CONTENT_KEYS = ["old_string", "oldString", "old_str", "oldContent", "OldContent"] as const;
+const NEW_CONTENT_KEYS = ["new_string", "newString", "new_str", "newContent", "NewContent"] as const;
+const COMMAND_KEYS = ["command", "CommandLine", "Command"] as const;
+
+const DIRECT_WRITE_TOOLS = new Set(["Write", "write", "write_to_file"]);
+const DIRECT_EDIT_TOOLS = new Set([
+  "Edit",
+  "search_replace",
+  "hashline_edit",
+  "replace_file_content",
+  "multi_replace_file_content",
+]);
+const COMMAND_TOOLS = new Set(["Bash", "run_terminal_command", "run_command"]);
+
+const PROFILE_BY_SHAPE: Readonly<Record<PayloadShape, HookResponseProfile>> = Object.freeze({
+  FLAT_SNAKE_CASE: "LEGACY_EXIT_ONLY",
+  FLAT_CAMEL_CASE: "COMPATIBILITY_DENY_ENVELOPE",
+  NESTED_TOOL_CALL: "TOP_LEVEL_DENY_ENVELOPE",
+});
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(record: UnknownRecord, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) return value;
+  }
+  return undefined;
+}
+
+function optionalString(record: UnknownRecord, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string") return value;
+  }
+  return undefined;
+}
+
+function canonicalToolName(observedName: string): string {
+  if (DIRECT_WRITE_TOOLS.has(observedName)) return "Write";
+  if (DIRECT_EDIT_TOOLS.has(observedName)) return "Edit";
+  if (COMMAND_TOOLS.has(observedName)) return "Bash";
+  return observedName;
+}
+
+function canonicalDirectInput(toolInput: UnknownRecord): CanonicalPreToolUseInput {
+  const filePath = nonEmptyString(toolInput, PATH_KEYS);
+  const paths = Array.isArray(toolInput.paths)
+    ? toolInput.paths.filter(
+        (candidate): candidate is string => typeof candidate === "string" && candidate.trim().length > 0,
+      )
+    : undefined;
+  const content = optionalString(toolInput, CONTENT_KEYS);
+  const oldString = optionalString(toolInput, OLD_CONTENT_KEYS);
+  const newString = optionalString(toolInput, NEW_CONTENT_KEYS);
+  return {
+    ...(filePath === undefined ? {} : { file_path: filePath }),
+    ...(paths === undefined ? {} : { paths }),
+    ...(content === undefined ? {} : { content }),
+    ...(oldString === undefined ? {} : { old_string: oldString }),
+    ...(newString === undefined ? {} : { new_string: newString }),
+  };
+}
+
+function canonicalLegacyInput(toolInput: UnknownRecord): CanonicalPreToolUseInput {
+  const paths = Array.isArray(toolInput.paths)
+    ? toolInput.paths.filter((candidate): candidate is string => typeof candidate === "string")
+    : undefined;
+  const oldString = optionalString(toolInput, ["old_string", "old_str"]);
+  const newString = optionalString(toolInput, ["new_string", "new_str"]);
+  return {
+    ...(typeof toolInput.path === "string" ? { path: toolInput.path } : {}),
+    ...(typeof toolInput.file_path === "string" ? { file_path: toolInput.file_path } : {}),
+    ...(paths === undefined ? {} : { paths }),
+    ...(typeof toolInput.command === "string" ? { command: toolInput.command } : {}),
+    ...(typeof toolInput.content === "string" ? { content: toolInput.content } : {}),
+    ...(oldString === undefined ? {} : { old_string: oldString }),
+    ...(newString === undefined ? {} : { new_string: newString }),
+  };
+}
+
+function extractionFailure(
+  profile: HookResponseProfile,
+  observedName: string,
+  expected: "path" | "command" | "patch",
+): PreToolUseNormalizationResult {
+  const candidates =
+    expected === "path" ? PATH_KEYS.join(", ") : expected === "command" ? COMMAND_KEYS.join(", ") : "patch, command";
+  return {
+    ok: false,
+    responseProfile: profile,
+    reason: `${observedName} の書き込み対象を抽出できませんでした。受理可能な ${expected} key: ${candidates}`,
+  };
+}
+
+function normalizeKnownInput(
+  observedName: string,
+  toolInput: UnknownRecord,
+  profile: HookResponseProfile,
+  inputTruncated: boolean,
+  shape: PayloadShape,
+): { readonly toolName: string; readonly toolInput: CanonicalPreToolUseInput } | PreToolUseNormalizationResult {
+  if (observedName === "apply_patch") {
+    if (inputTruncated) {
+      return { ok: false, responseProfile: profile, reason: "切り詰められた apply_patch は全対象を保証できません" };
+    }
+    const patch =
+      shape === "FLAT_SNAKE_CASE"
+        ? nonEmptyString(toolInput, ["command"])
+        : nonEmptyString(toolInput, ["patch", "command"]);
+    if (patch === undefined) return extractionFailure(profile, observedName, "patch");
+    return { toolName: "apply_patch", toolInput: { command: patch } };
+  }
+
+  if (COMMAND_TOOLS.has(observedName)) {
+    if (inputTruncated) {
+      return { ok: false, responseProfile: profile, reason: "切り詰められた command は全対象を保証できません" };
+    }
+    const command = nonEmptyString(toolInput, COMMAND_KEYS);
+    if (command === undefined) return extractionFailure(profile, observedName, "command");
+    return { toolName: "Bash", toolInput: { command } };
+  }
+
+  if (DIRECT_WRITE_TOOLS.has(observedName) || DIRECT_EDIT_TOOLS.has(observedName)) {
+    const directInput = canonicalDirectInput(toolInput);
+    if (directInput.file_path === undefined && (directInput.paths === undefined || directInput.paths.length === 0))
+      return extractionFailure(profile, observedName, "path");
+    return { toolName: canonicalToolName(observedName), toolInput: directInput };
+  }
+
+  return { toolName: canonicalToolName(observedName), toolInput: canonicalLegacyInput(toolInput) };
+}
+
+export class PreToolUsePayloadNormalizer {
+  normalize(payload: unknown): PreToolUseNormalizationResult {
+    if (!isRecord(payload)) return { ok: false, reason: "PreToolUse payload は JSON object である必要があります" };
+
+    const toolCall = isRecord(payload.toolCall) ? payload.toolCall : undefined;
+    const shapes: PayloadShape[] = [];
+    if (typeof payload.tool_name === "string") shapes.push("FLAT_SNAKE_CASE");
+    if (typeof payload.toolName === "string" && isRecord(payload.toolInput)) shapes.push("FLAT_CAMEL_CASE");
+    if (toolCall !== undefined && typeof toolCall.name === "string" && isRecord(toolCall.args)) {
+      shapes.push("NESTED_TOOL_CALL");
+    }
+
+    if (shapes.length === 0) {
+      if ("hook_event_name" in payload || "session_id" in payload || "tool_input" in payload) {
+        return {
+          ok: false,
+          responseProfile: "LEGACY_EXIT_ONLY",
+          reason: "tool_nameフィールドが必要です",
+        };
+      }
+      if (toolCall !== undefined) {
+        return {
+          ok: false,
+          responseProfile: "TOP_LEVEL_DENY_ENVELOPE",
+          reason: "toolCall payload の name と args を検出できないため拒否しました",
+        };
+      }
+      return { ok: false, reason: "対応する PreToolUse payload shape を検出できませんでした" };
+    }
+    if (shapes.length > 1)
+      return { ok: false, reason: "複数の PreToolUse payload shape が混在しているため拒否しました" };
+
+    const shape = shapes[0];
+    const responseProfile = PROFILE_BY_SHAPE[shape];
+    const observedName =
+      shape === "FLAT_SNAKE_CASE"
+        ? (payload.tool_name as string)
+        : shape === "FLAT_CAMEL_CASE"
+          ? (payload.toolName as string)
+          : (toolCall?.name as string);
+    const toolInput =
+      shape === "FLAT_SNAKE_CASE"
+        ? isRecord(payload.tool_input)
+          ? payload.tool_input
+          : {}
+        : shape === "FLAT_CAMEL_CASE"
+          ? (payload.toolInput as UnknownRecord)
+          : (toolCall?.args as UnknownRecord);
+    const inputTruncated = payload.toolInputTruncated === true;
+    const normalizedInput = normalizeKnownInput(observedName, toolInput, responseProfile, inputTruncated, shape);
+    if ("ok" in normalizedInput) return normalizedInput;
+
+    const cwd =
+      shape === "NESTED_TOOL_CALL"
+        ? Array.isArray(payload.workspacePaths)
+          ? payload.workspacePaths.find(
+              (candidate): candidate is string => typeof candidate === "string" && candidate.length > 0,
+            )
+          : undefined
+        : typeof payload.cwd === "string"
+          ? payload.cwd
+          : undefined;
+    const request: NormalizedPreToolUseRequest = {
+      shape,
+      responseProfile,
+      cwd,
+      toolName: normalizedInput.toolName,
+      toolInput: normalizedInput.toolInput,
+      inputTruncated,
+    };
+    return { ok: true, request };
+  }
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @unit agent-integration
+ * @layer presentation
+ * @work-item-id WI-385
+ */
+
+import type { HookResponseProfile } from "../application/dto/normalized-pre-tool-use-request.js";
+
+export interface RenderedPreToolUseResponse {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: 0 | 2;
+}
+
+export class PreToolUseResponseRenderer {
+  deny(profile: HookResponseProfile, reason: string): RenderedPreToolUseResponse {
+    if (profile === "LEGACY_EXIT_ONLY") {
+      return { stdout: "", stderr: `${reason}\n`, exitCode: 2 };
+    }
+    const envelope =
+      profile === "COMPATIBILITY_DENY_ENVELOPE"
+        ? {
+            decision: "deny",
+            reason,
+            hookSpecificOutput: {
+              hookEventName: "PreToolUse",
+              permissionDecision: "deny",
+              permissionDecisionReason: reason,
+            },
+          }
+        : { decision: "deny", reason };
+    return { stdout: `${JSON.stringify(envelope)}\n`, stderr: `${reason}\n`, exitCode: 2 };
+  }
+
+  allow(_profile: HookResponseProfile): RenderedPreToolUseResponse {
+    return { stdout: "", stderr: "", exitCode: 0 };
+  }
+}

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,11 +153,24 @@ 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, validatePointersUseCase);
@@ -133,6 +180,8 @@ export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir
   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,
   };
 }

package/scripts/harness/ci-governance/domain/ports/inception-doc-writer-port.ts

@@ -0,0 +1,19 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-368
+
+import type { InceptionDocKind } from "../value-objects/inception-doc-kind.js";
+
+export interface InceptionDocWriterPort {
+  /** 書き込み先の絶対パスを返す（副作用なし） */
+  resolvePath(kind: InceptionDocKind): string;
+
+  /** 書き込み先が既に存在するか */
+  exists(kind: InceptionDocKind): Promise<boolean>;
+
+  /**
+   * inception / product 文書を書き込む（親ディレクトリが無ければ作成）。
+   * 書き込んだ絶対パスを返す。
+   */
+  write(kind: InceptionDocKind, content: string): Promise<string>;
+}

package/scripts/harness/ci-governance/domain/ports/inception-template-repository-port.ts

@@ -0,0 +1,16 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-368
+
+import type { InceptionDocKind } from "../value-objects/inception-doc-kind.js";
+
+export interface InceptionTemplateRepositoryPort {
+  /** テンプレートの絶対パスを返す（UI 出力用） */
+  resolvePath(kind: InceptionDocKind): string;
+
+  /**
+   * kind に対応するテンプレートファイルを読み込む。
+   * 存在しない場合は例外を投げる。
+   */
+  read(kind: InceptionDocKind): Promise<string>;
+}

package/scripts/harness/ci-governance/domain/ports/template-catalog-port.ts

@@ -0,0 +1,23 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-367
+
+import type { TemplateCatalogEntry } from "../value-objects/template-catalog-entry.js";
+import type { TemplateName } from "../value-objects/template-name.js";
+
+export interface TemplateCatalogPort {
+  /** テンプレートディレクトリの絶対パス（案内表示用） */
+  directoryPath(): string;
+
+  /**
+   * 実在するテンプレートを name 昇順で列挙する。
+   * ディレクトリが存在しない場合は空配列を返す（例外にしない）。
+   */
+  list(): Promise<readonly TemplateCatalogEntry[]>;
+
+  /**
+   * catalog に name 完全一致するテンプレート本文を読む。
+   * 一致するエントリが無い場合は null を返す。
+   */
+  read(name: TemplateName): Promise<string | null>;
+}