phasegate 0.283.0 → 0.335.0

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>;
+}

package/scripts/harness/ci-governance/domain/services/claude-md-composer.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit ci-governance
+ * @work-item-id WI-331
  */
 
 export interface ClaudeMdTemplateValues {
@@ -9,20 +10,28 @@ export interface ClaudeMdTemplateValues {
   readonly presets: readonly string[];
 }
 
-const USER_SECTION_START = '<!-- phasegate:user-section:start -->';
-const USER_SECTION_END = '<!-- phasegate:user-section:end -->';
-const DEFAULT_USER_SECTION = 'Project-specific agent instructions go here.';
+const USER_SECTION_START = "<!-- phasegate:user-section:start -->";
+const USER_SECTION_END = "<!-- phasegate:user-section:end -->";
+const DEFAULT_USER_SECTION = "Project-specific agent instructions go here.";
 
 export class ClaudeMdComposer {
+  // Rebuilds CLAUDE.md from the current template, carrying over the existing
+  // user-section body. Because the whole file is re-rendered, a legacy file
+  // whose user-section still sits inside the managed block (pre-WI-331
+  // template shape) is migrated to the current outside-of-block structure.
   compose(template: string, existing: string | null, values: ClaudeMdTemplateValues): string {
     const userSection = this.extractUserSection(existing) ?? DEFAULT_USER_SECTION;
-    return template
-      .replace('{{PHASEGATE_COMMANDS}}', this.toList(values.commands))
-      .replace('{{PHASEGATE_SKILLS}}', this.toList(values.skills))
-      .replace('{{PHASEGATE_PRESETS}}', this.toList(values.presets))
-      .replace('{{PHASEGATE_USER_SECTION}}', userSection)
-      .replace(/\n{3,}/g, '\n\n')
-      .trimEnd() + '\n';
+    const rendered = template
+      .replace("{{PHASEGATE_COMMANDS}}", this.toList(values.commands))
+      .replace("{{PHASEGATE_SKILLS}}", this.toList(values.skills))
+      .replace("{{PHASEGATE_PRESETS}}", this.toList(values.presets))
+      // Collapse blank-line runs before injecting the user body so
+      // user-authored spacing is preserved byte-for-byte.
+      .replace(/\n{3,}/g, "\n\n")
+      // Replacer function keeps `$`-sequences in the user body from being
+      // interpreted as String.replace substitution patterns.
+      .replace("{{PHASEGATE_USER_SECTION}}", () => userSection);
+    return `${rendered.trimEnd()}\n`;
   }
 
   private extractUserSection(existing: string | null): string | null {
@@ -34,6 +43,6 @@ export class ClaudeMdComposer {
   }
 
   private toList(values: readonly string[]): string {
-    return values.map((value) => `- \`${value}\``).join('\n');
+    return values.map((value) => `- \`${value}\``).join("\n");
   }
 }

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/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/check-repetition-handler.ts

@@ -29,6 +29,13 @@ export class CheckRepetitionHandler {
   async handle(args: CheckRepetitionHandlerArgs): Promise<CheckRepetitionHandlerResult> {
     const { errorCode, reset = false, format = 'human' } = args;
 
+    if (errorCode.trim().length === 0) {
+      return {
+        exitCode: 1,
+        output: 'Error: --code <errorCode> is required. Usage: phasegate ci:check-repetition --code <errorCode> [--reset] [--json]',
+      };
+    }
+
     if (reset && this.resetUseCase) {
       const result = await this.resetUseCase.execute({ errorCode, confirmedResolution: true });
 
@@ -49,9 +56,10 @@ export class CheckRepetitionHandler {
     }
 
     const result = await this.checkUseCase.execute({ errorCode });
+    const exitCode = result.escalated === true ? 1 : 0;
 
     if (format === 'json') {
-      return { exitCode: result.exists ? 0 : 1, output: JSON.stringify(result, null, 2) };
+      return { exitCode, output: JSON.stringify(result, null, 2) };
     }
 
     const lines: string[] = [];
@@ -63,6 +71,6 @@ export class CheckRepetitionHandler {
       lines.push(`  Escalated: ${result.escalated}`);
     }
 
-    return { exitCode: result.exists ? 0 : 1, output: lines.join('\n') };
+    return { exitCode, output: lines.join('\n') };
   }
 }

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 };
+  }
+}