phasegate 0.315.0 → 0.340.0

package/scripts/harness/ci-governance/domain/value-objects/inception-doc-kind.ts

@@ -0,0 +1,109 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-368
+
+/**
+ * scaffold 可能な inception / product 文書の種別。
+ *
+ * `DesignPhase` と同型だが **unit 軸を持たない**。`DesignPhase` は `--unit` 必須を
+ * 前提とする書き込み先解決を持つため、`_shared` 配下や product 直下の文書を
+ * 混ぜると「unit 必須なのに unit を使わない phase」という不整合な不変条件になる。
+ *
+ * 収録範囲は L2 の Level-1 フェーズゲートを塞ぐ文書に限定する（GitHub issue #42）。
+ * `user_stories.md` / `user_story_mapping.md` / `units/*.md` は段階投入のため未収録。
+ */
+export const INCEPTION_DOC_KINDS = [
+  "product-overview-plan",
+  "product-overview",
+  "story-writer-plan",
+  "story-mapping-plan",
+  "unit-design-plan",
+] as const;
+
+export type InceptionDocKindValue = (typeof INCEPTION_DOC_KINDS)[number];
+
+/** 書き込み先解決に使う、解決済みドキュメントルート */
+export interface InceptionDocRoots {
+  /** `paths.inceptionDocs`（既定 `docs/inception`） */
+  readonly inceptionDocsRoot: string;
+  /** `paths.designDocs`（既定 `docs/product/construction`） */
+  readonly designDocsRoot: string;
+}
+
+export const DEFAULT_INCEPTION_DOC_ROOTS: InceptionDocRoots = Object.freeze({
+  inceptionDocsRoot: "docs/inception",
+  designDocsRoot: "docs/product/construction",
+});
+
+/** `docs/product/construction` -> `docs/product`（phase node の `{designDocsRoot}/..` と同一規則） */
+function productRootOf(designDocsRoot: string): string {
+  const normalized = designDocsRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+  const lastSlash = normalized.lastIndexOf("/");
+  return lastSlash <= 0 ? "." : normalized.slice(0, lastSlash);
+}
+
+export class InceptionDocKind {
+  private constructor(readonly value: InceptionDocKindValue) {
+    Object.freeze(this);
+  }
+
+  static create(input: string): InceptionDocKind {
+    if (!InceptionDocKind.isValid(input)) {
+      throw new Error(`未知の doc-kind: "${input}"。許容値: ${INCEPTION_DOC_KINDS.join(", ")}`);
+    }
+    return new InceptionDocKind(input);
+  }
+
+  static isValid(input: string): input is InceptionDocKindValue {
+    return (INCEPTION_DOC_KINDS as readonly string[]).includes(input);
+  }
+
+  equals(other: InceptionDocKind): boolean {
+    return this.value === other.value;
+  }
+
+  /** この kind に対応するテンプレートファイル名（`templates/` 配下） */
+  get templateFileName(): string {
+    switch (this.value) {
+      case "product-overview-plan":
+        return "product_overview_plan.template.md";
+      case "product-overview":
+        return "product_overview.template.md";
+      case "story-writer-plan":
+        return "story_writer_plan.template.md";
+      case "story-mapping-plan":
+        return "story_mapping_plan.template.md";
+      case "unit-design-plan":
+        return "unit_design_plan.template.md";
+    }
+  }
+
+  /** この kind が生成する文書のファイル名 */
+  get docFileName(): string {
+    switch (this.value) {
+      case "product-overview-plan":
+        return "product_overview_plan.md";
+      case "product-overview":
+        return "product_overview.md";
+      case "story-writer-plan":
+        return "story_writer_plan.md";
+      case "story-mapping-plan":
+        return "story_mapping_plan.md";
+      case "unit-design-plan":
+        return "unit_design_plan.md";
+    }
+  }
+
+  /**
+   * プロジェクトルートからの相対パス（POSIX 区切り）。
+   * `_shared/*_plan.md` は `{inceptionDocsRoot}/_shared/` 直下、
+   * `product_overview.md` は `dirname({designDocsRoot})` 直下に置く。
+   */
+  relativeTargetPath(roots: InceptionDocRoots = DEFAULT_INCEPTION_DOC_ROOTS): string {
+    if (this.value === "product-overview") {
+      return `${productRootOf(roots.designDocsRoot)}/${this.docFileName}`;
+    }
+    const inceptionRoot = roots.inceptionDocsRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+    return `${inceptionRoot}/_shared/${this.docFileName}`;
+  }
+}

package/scripts/harness/ci-governance/domain/value-objects/integrity-target.ts

@@ -1,5 +1,6 @@
 // @unit ci-governance
 // @layer domain
+// @work-item-id WI-384
 
 export interface IntegrityTargetProps {
   readonly include: readonly string[];
@@ -31,6 +32,7 @@ export class IntegrityTarget {
         "skills/*/SKILL.md",
         ".claude/settings.json",
         ".claude/scripts/*.sh",
+        ".codex/hooks.json",
         ".husky/*",
         "docs/templates/agent-context/**",
       ],

package/scripts/harness/ci-governance/domain/value-objects/template-catalog-entry.ts

@@ -0,0 +1,53 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-367
+
+import { TemplateName } from "./template-name.js";
+
+/** `<name>.template.<ext>` 形式のテンプレートファイル名を分解する */
+const TEMPLATE_FILE_PATTERN = /^(.+)\.template\.([a-z0-9]+)$/;
+
+export interface TemplateCatalogEntryProps {
+  readonly name: TemplateName;
+  readonly fileName: string;
+  readonly extension: string;
+}
+
+/**
+ * `templates/` 配下に実在する 1 テンプレートの記述子。
+ *
+ * `fileName` は readdir が返した実ファイル名であり、ユーザー入力を含まない。
+ * `templates show` はこのエントリを `name` で完全一致検索し、
+ * 見つかった `fileName` のみをテンプレートディレクトリに join する。
+ */
+export class TemplateCatalogEntry {
+  readonly name: TemplateName;
+  readonly fileName: string;
+  readonly extension: string;
+
+  private constructor(props: TemplateCatalogEntryProps) {
+    this.name = props.name;
+    this.fileName = props.fileName;
+    this.extension = props.extension;
+    Object.freeze(this);
+  }
+
+  /**
+   * テンプレートファイル名からエントリを生成する。
+   * `<name>.template.<ext>` 形式でない、または name 部分が
+   * `TemplateName` の不変条件を満たさない場合は null を返す（catalog から除外される）。
+   */
+  static fromFileName(fileName: string): TemplateCatalogEntry | null {
+    const matched = TEMPLATE_FILE_PATTERN.exec(fileName);
+    if (matched === null) return null;
+
+    const [, rawName, extension] = matched;
+    if (!TemplateName.isValid(rawName)) return null;
+
+    return new TemplateCatalogEntry({
+      name: TemplateName.create(rawName),
+      fileName,
+      extension,
+    });
+  }
+}

package/scripts/harness/ci-governance/domain/value-objects/template-name.ts

@@ -0,0 +1,50 @@
+// @unit ci-governance
+// @layer domain
+// @work-item-id WI-367
+
+/**
+ * テンプレート識別子。**ファイルパスではない**。
+ *
+ * `phasegate templates show <name>` の `<name>` を受け取る第一防壁。
+ * `..` / `/` / `\` を含む入力をここで弾くが、これは最終防壁ではない。
+ * 最終防壁は `TemplateCatalogPort` が readdir した実ファイル名との完全一致照合であり、
+ * ユーザー入力文字列が `path.join` の引数になる経路を持たないことで
+ * path traversal を構造的に不能にする。
+ */
+const TEMPLATE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+export class InvalidTemplateNameError extends Error {
+  constructor(input: string) {
+    super(`テンプレート名が不正です: "${input}"（使用可能: 英小文字・数字・_ ・-）`);
+    this.name = "InvalidTemplateNameError";
+  }
+}
+
+export class TemplateName {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(input: string): TemplateName {
+    if (!TemplateName.isValid(input)) {
+      throw new InvalidTemplateNameError(input);
+    }
+    return new TemplateName(input);
+  }
+
+  static isValid(input: string): boolean {
+    if (typeof input !== "string") return false;
+    return TEMPLATE_NAME_PATTERN.test(input);
+  }
+
+  equals(other: TemplateName): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-inception-doc-writer-adapter.ts

@@ -0,0 +1,42 @@
+// @unit ci-governance
+// @layer infrastructure
+// @work-item-id WI-368
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { InceptionDocWriterPort } from "../../domain/ports/inception-doc-writer-port.js";
+import {
+  DEFAULT_INCEPTION_DOC_ROOTS,
+  type InceptionDocKind,
+  type InceptionDocRoots,
+} from "../../domain/value-objects/inception-doc-kind.js";
+
+export class FileSystemInceptionDocWriterAdapter implements InceptionDocWriterPort {
+  private readonly baseDir: string;
+  private readonly roots: InceptionDocRoots;
+
+  constructor(baseDir: string, roots: InceptionDocRoots = DEFAULT_INCEPTION_DOC_ROOTS) {
+    this.baseDir = baseDir;
+    this.roots = roots;
+  }
+
+  resolvePath(kind: InceptionDocKind): string {
+    return path.join(this.baseDir, kind.relativeTargetPath(this.roots));
+  }
+
+  async exists(kind: InceptionDocKind): Promise<boolean> {
+    try {
+      await fs.access(this.resolvePath(kind));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async write(kind: InceptionDocKind, content: string): Promise<string> {
+    const targetPath = this.resolvePath(kind);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content, "utf-8");
+    return targetPath;
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-inception-template-repository-adapter.ts

@@ -0,0 +1,32 @@
+// @unit ci-governance
+// @layer infrastructure
+// @work-item-id WI-368
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { InceptionTemplateRepositoryPort } from "../../domain/ports/inception-template-repository-port.js";
+import type { InceptionDocKind } from "../../domain/value-objects/inception-doc-kind.js";
+
+export class FileSystemInceptionTemplateRepositoryAdapter implements InceptionTemplateRepositoryPort {
+  private readonly templatesDir: string;
+
+  constructor(harnessRoot: string, subDir: string = "templates") {
+    this.templatesDir = path.isAbsolute(subDir) ? subDir : path.join(harnessRoot, subDir);
+  }
+
+  resolvePath(kind: InceptionDocKind): string {
+    return path.join(this.templatesDir, kind.templateFileName);
+  }
+
+  async read(kind: InceptionDocKind): Promise<string> {
+    const filePath = this.resolvePath(kind);
+    try {
+      return await fs.readFile(filePath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(`テンプレートが見つかりません: ${filePath} (kind=${kind.value})`);
+      }
+      throw err;
+    }
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-template-catalog-adapter.ts

@@ -0,0 +1,60 @@
+// @unit ci-governance
+// @layer infrastructure
+// @work-item-id WI-367
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { TemplateCatalogPort } from "../../domain/ports/template-catalog-port.js";
+import { TemplateCatalogEntry } from "../../domain/value-objects/template-catalog-entry.js";
+import type { TemplateName } from "../../domain/value-objects/template-name.js";
+
+/**
+ * `harnessRoot/templates` を readdir して catalog を組み立てる。
+ *
+ * `read()` は catalog エントリの `fileName`（readdir 由来）だけを join する。
+ * 引数の `TemplateName` は照合キーとしてのみ使われ、パス構成要素にならないため
+ * `../` を含む入力があっても templatesDir の外へは出られない。
+ */
+export class FileSystemTemplateCatalogAdapter implements TemplateCatalogPort {
+  private readonly templatesDir: string;
+
+  constructor(harnessRoot: string, subDir: string = "templates") {
+    this.templatesDir = path.isAbsolute(subDir) ? subDir : path.join(harnessRoot, subDir);
+  }
+
+  directoryPath(): string {
+    return this.templatesDir;
+  }
+
+  async list(): Promise<readonly TemplateCatalogEntry[]> {
+    let dirEntries: import("node:fs").Dirent[];
+    try {
+      dirEntries = await fs.readdir(this.templatesDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const entries: TemplateCatalogEntry[] = [];
+    for (const dirEntry of dirEntries) {
+      if (!dirEntry.isFile()) continue;
+      const entry = TemplateCatalogEntry.fromFileName(dirEntry.name);
+      if (entry === null) continue;
+      entries.push(entry);
+    }
+
+    // name 昇順（同名は fileName で決定的に）。表示・照合ともに name が主キーであるため。
+    entries.sort((a, b) => {
+      if (a.name.value !== b.name.value) return a.name.value < b.name.value ? -1 : 1;
+      return a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0;
+    });
+    return entries;
+  }
+
+  async read(name: TemplateName): Promise<string | null> {
+    const entries = await this.list();
+    const matched = entries.find((entry) => entry.name.value === name.value);
+    if (matched === undefined) return null;
+
+    return await fs.readFile(path.join(this.templatesDir, matched.fileName), "utf-8");
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/scaffold-inception-handler.ts

@@ -0,0 +1,101 @@
+// @unit ci-governance
+// @layer presentation
+// @work-item-id WI-368
+
+import type { ScaffoldInceptionUseCase } from "../../application/usecases/scaffold-inception-usecase.js";
+import { INCEPTION_DOC_KINDS, InceptionDocKind } from "../../domain/value-objects/inception-doc-kind.js";
+
+export interface ScaffoldInceptionHandlerArgs {
+  readonly kind?: string;
+  readonly dryRun?: boolean;
+  readonly apply?: boolean;
+  readonly force?: boolean;
+  readonly format?: "human" | "json";
+}
+
+export interface ScaffoldInceptionHandlerResult {
+  readonly exitCode: number;
+  readonly output: string;
+}
+
+const ALLOWED = INCEPTION_DOC_KINDS.join(", ");
+
+export class ScaffoldInceptionHandler {
+  constructor(private readonly useCase: ScaffoldInceptionUseCase) {}
+
+  async handle(args: ScaffoldInceptionHandlerArgs): Promise<ScaffoldInceptionHandlerResult> {
+    const format = args.format ?? "human";
+    const apply = args.apply === true;
+    const dryRun = args.dryRun === true || !apply;
+
+    if (args.dryRun === true && apply) {
+      return this.fail(format, "--dry-run と --apply は同時に指定できません", 2);
+    }
+
+    if (!args.kind || args.kind.trim().length === 0) {
+      return this.fail(format, `--kind <doc-kind> は必須です（許容値: ${ALLOWED}）`, 2);
+    }
+    if (!InceptionDocKind.isValid(args.kind)) {
+      return this.fail(format, `未知の doc-kind: "${args.kind}"（許容値: ${ALLOWED}）`, 2);
+    }
+
+    let result: Awaited<ReturnType<ScaffoldInceptionUseCase["execute"]>>;
+    try {
+      result = await this.useCase.execute({
+        kind: args.kind,
+        dryRun,
+        force: args.force,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return this.fail(format, `scaffold 失敗: ${msg}`, 2);
+    }
+
+    if (format === "json") {
+      return {
+        exitCode: result.alreadyExists && !result.written ? 2 : 0,
+        output: JSON.stringify(result, null, 2),
+      };
+    }
+
+    if (result.alreadyExists && !result.written) {
+      return {
+        exitCode: result.dryRun ? 0 : 2,
+        output: [
+          result.dryRun ? `dry-run: 既に存在します: ${result.targetPath}` : `既に存在します: ${result.targetPath}`,
+          result.dryRun ? "書き込むには --apply を指定してください。" : "上書きするには --force を指定してください。",
+        ].join("\n"),
+      };
+    }
+
+    if (result.dryRun) {
+      return {
+        exitCode: 0,
+        output: [
+          `dry-run: 文書を生成予定: ${result.targetPath}`,
+          `テンプレ: ${result.templatePath}`,
+          `doc-kind: ${result.kind}`,
+          "書き込むには --apply を指定してください。",
+        ].join("\n"),
+      };
+    }
+
+    const headerVerb = result.overwritten ? "上書き保存しました" : "生成しました";
+    return {
+      exitCode: 0,
+      output: [
+        `文書を${headerVerb}: ${result.targetPath}`,
+        `テンプレ: ${result.templatePath}`,
+        `doc-kind: ${result.kind}`,
+        "TODO プレースホルダを実体で埋め、QA の [Answer] は人間が記入してください。",
+      ].join("\n"),
+    };
+  }
+
+  private fail(format: "human" | "json", message: string, exitCode: number): ScaffoldInceptionHandlerResult {
+    if (format === "json") {
+      return { exitCode, output: JSON.stringify({ error: message }, null, 2) };
+    }
+    return { exitCode, output: message };
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/templates-handler.ts

@@ -0,0 +1,103 @@
+// @unit ci-governance
+// @layer presentation
+// @work-item-id WI-367
+
+import type { ListTemplatesUseCase } from "../../application/usecases/list-templates-usecase.js";
+import type { ShowTemplateUseCase } from "../../application/usecases/show-template-usecase.js";
+
+export interface TemplatesHandlerResult {
+  readonly exitCode: number;
+  /** stdout に出す内容（空文字なら出力しない） */
+  readonly output: string;
+  /** stderr に出す内容（空文字なら出力しない） */
+  readonly errorOutput: string;
+}
+
+export interface TemplatesListArgs {
+  readonly format?: "human" | "json";
+}
+
+export interface TemplatesShowArgs {
+  readonly name?: string;
+}
+
+const USAGE = "Usage: phasegate templates <list|show <name>>";
+
+export class TemplatesHandler {
+  constructor(
+    private readonly listUseCase: ListTemplatesUseCase,
+    private readonly showUseCase: ShowTemplateUseCase,
+  ) {}
+
+  async list(args: TemplatesListArgs = {}): Promise<TemplatesHandlerResult> {
+    const result = await this.listUseCase.execute();
+
+    if (args.format === "json") {
+      return {
+        exitCode: 0,
+        output: JSON.stringify(result, null, 2),
+        errorOutput: "",
+      };
+    }
+
+    if (result.templates.length === 0) {
+      return {
+        exitCode: 0,
+        output: [
+          "Available templates (0):",
+          "",
+          `  テンプレートディレクトリが見つかりません: ${result.directoryPath}`,
+        ].join("\n"),
+        errorOutput: "",
+      };
+    }
+
+    const lines = [`Available templates (${result.templates.length}):`, ""];
+    for (const entry of result.templates) {
+      lines.push(`  ${entry.name}  (${entry.fileName})`);
+    }
+    lines.push("", "本文を表示: phasegate templates show <name>");
+
+    return { exitCode: 0, output: lines.join("\n"), errorOutput: "" };
+  }
+
+  async show(args: TemplatesShowArgs): Promise<TemplatesHandlerResult> {
+    const rawName = args.name ?? "";
+    if (rawName.length === 0) {
+      return {
+        exitCode: 2,
+        output: "",
+        errorOutput: "Usage: phasegate templates show <name>",
+      };
+    }
+
+    const result = await this.showUseCase.execute(rawName);
+
+    if (result.found) {
+      // テンプレート本文だけを stdout に出す。リダイレクトでそのまま文書として保存できる。
+      return { exitCode: 0, output: result.content, errorOutput: "" };
+    }
+
+    if (result.reason === "invalid-name") {
+      return {
+        exitCode: 2,
+        output: "",
+        errorOutput: [
+          `Invalid template name: ${rawName}`,
+          "テンプレート名は英小文字・数字・_ ・- のみで指定してください（パスは指定できません）。",
+          USAGE,
+        ].join("\n"),
+      };
+    }
+
+    return {
+      exitCode: 2,
+      output: "",
+      errorOutput: [`Template not found: ${rawName}`, `Available: ${result.availableNames.join(", ")}`].join("\n"),
+    };
+  }
+
+  usage(): TemplatesHandlerResult {
+    return { exitCode: 2, output: "", errorOutput: USAGE };
+  }
+}

package/scripts/harness/config-foundation/domain/harness-config.ts

@@ -99,6 +99,18 @@ export interface HarnessConfigResolvedDocument {
     allowedCategories: string[];
     maintainedLayers: string[];
     relaxedGates: string[];
+    // WI-377: JSON Schema (v2/v3) は当該キーを許容し preset 解決の deepMerge も
+    // 実行時には保持していたが、型宣言だけが欠けていた。preset 定義側は宣言しないため optional。
+    fullModeRequiredWhen?: {
+      mixedCategories?: boolean;
+      newDomainFile?: boolean;
+      apiContractChange?: boolean;
+    };
+    // WI-372: プロジェクト固有パスのカテゴリ割当（quick-mode unit が消費する）。
+    // preset には既定を持たせず、source config 側でのみ指定する任意項目。
+    // preset 解決の deepMerge は preset 側に無いキーを source からそのまま引き継ぐため、
+    // 明示宣言は WI-377 の preset 解決経路を通しても保持される。
+    categoryOverrides?: Record<string, string[]>;
   };
   phaseDependencies: {
     preset: PhaseDependenciesPresetId;

package/scripts/harness/config-foundation/infrastructure/presets/minimal.json

@@ -22,8 +22,8 @@
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": []
+    "maintainedLayers": ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
+    "relaxedGates": ["L2-001", "L3-002", "L3-003", "L3-004", "L4"]
   },
   "phaseDependencies": {
     "preset": "default",

package/scripts/harness/config-foundation/infrastructure/presets/standard.json

@@ -22,8 +22,8 @@
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": []
+    "maintainedLayers": ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
+    "relaxedGates": ["L2-001", "L3-002", "L3-003", "L3-004", "L4"]
   },
   "phaseDependencies": {
     "preset": "default",

package/scripts/harness/config-foundation/infrastructure/presets/strict.json

@@ -22,8 +22,8 @@
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": []
+    "maintainedLayers": ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
+    "relaxedGates": ["L2-001", "L3-002", "L3-003", "L3-004", "L4"]
   },
   "phaseDependencies": {
     "preset": "default",