phasegate 0.138.0 → 0.138.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **WI-106 — inception WI ID 重複防止** — `docs/inception/**/WI-XXX/description.md` の frontmatter `id` を global scan し、`_cross` と Unit 配下をまたぐ重複、および parent directory 名と `id` の不一致を `validate-metadata` 経路で検出するようにした。
+  - `docs/folder_management_rules.md` / `AGENTS.md` に、新規 WI 作成時の global unique ルールを明記。
+  - `migrate work-items` の採番が `_cross` と Unit 配下の既存 WI 番号を避けることを回帰テストで固定。
+
 ## [0.138.0] - 2026-05-09
 
 ### Fixed

package/docs/folder_management_rules.md

@@ -77,6 +77,8 @@ scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
 | `inception/_cross/{WI-XXX}/` | 複数 Unit に影響する cross-cutting WI | `_cross/WI-026/`, `_cross/WI-031/` |
 | `inception/{unit}/{WI-XXX}/` | 単一 Unit が所有する WI | `validator-system/WI-074/` |
 
+`WI-XXX` は `docs/inception/**` 全体で一意でなければなりません。`_cross/WI-031` と `{unit}/WI-031` のように配置先が違っても同じ ID は使えません。`description.md` の frontmatter `id` は parent directory 名と一致させます。
+
 > **廃止された配置**（v0.104.0 で物理削除）:
 > - `docs/inception/issues/{ISSUE-XXX}/`
 > - `docs/inception/{unit}/issues/{ISSUE-XXX}/`
@@ -266,7 +268,8 @@ TESTED        @work-item-id 付きテストが存在し green
 
 `migrate work-items --apply` および新規 WI 起票時の採番:
 
-- 既存 WI 番号は予約（重複しない）
+- 既存 WI 番号は `docs/inception/**/WI-XXX` 全体で予約（`_cross` と Unit 配下をまたいで重複しない）
+- `description.md` の frontmatter `id` は parent directory 名 `WI-XXX` と一致させる
 - 空き番号の **若い順**で sequential allocation
 - legacy ID（`ISSUE-XXX` / `US-XXX` / `H{NN}-{NN}`）が存在する場合、frontmatter の `legacy_id` に保持
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.138.0",
+  "version": "0.138.1",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/traceability-model/application/usecases/validate-design-story-annotations-usecase.ts

@@ -12,6 +12,11 @@ import {
 import type { ProjectRelativePath } from "../../domain/value-objects/project-relative-path.js";
 import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
 import { WorkItemFrontmatterValidationError } from "../../domain/value-objects/work-item-frontmatter.js";
+import type { WorkItemIdentityPort } from "../../domain/ports/work-item-identity-port.js";
+import {
+  WorkItemIdentityValidationService,
+  type WorkItemIdentityViolation,
+} from "../../domain/services/work-item-identity-validation-service.js";
 import type { MetadataValidationOutput } from "../dto/metadata-validation-output.js";
 
 type DesignStoryAnnotationsValidator = Pick<MetadataValidator, "validateDesignDocument">;
@@ -41,6 +46,20 @@ status: drafted
 ---`,
   });
 
+const toWorkItemIdentityError = (violation: WorkItemIdentityViolation): TraceabilityHarnessError =>
+  Object.freeze({
+    code: "L2-002",
+    severity: "error",
+    message: violation.message,
+    suggestion: "docs/inception/**/WI-XXX/description.md の parent directory 名と frontmatter id を一致させ、WI id を inception 全体で一意にしてください",
+    fix_example: `---
+id: ${violation.workItemId}
+type: issue
+severity: normal
+status: drafted
+---`,
+  });
+
 const mergeValidationResult = (
   additionalErrors: readonly TraceabilityHarnessError[],
   result: MetadataValidationResult,
@@ -92,15 +111,22 @@ export class DesignDocumentReadApplicationError extends Error {
 export interface ValidateDesignStoryAnnotationsUseCaseDeps {
   readonly designDocumentPort: DesignDocumentPort;
   readonly validator: DesignStoryAnnotationsValidator;
+  readonly workItemIdentityPort?: WorkItemIdentityPort;
+  readonly workItemIdentityValidationService?: WorkItemIdentityValidationService;
 }
 
 export class ValidateDesignStoryAnnotationsUseCase {
   private readonly designDocumentPort: DesignDocumentPort;
   private readonly validator: DesignStoryAnnotationsValidator;
+  private readonly workItemIdentityPort?: WorkItemIdentityPort;
+  private readonly workItemIdentityValidationService: WorkItemIdentityValidationService;
 
   constructor(deps: ValidateDesignStoryAnnotationsUseCaseDeps) {
     this.designDocumentPort = deps.designDocumentPort;
     this.validator = deps.validator;
+    this.workItemIdentityPort = deps.workItemIdentityPort;
+    this.workItemIdentityValidationService =
+      deps.workItemIdentityValidationService ?? new WorkItemIdentityValidationService();
   }
 
   async execute(filePaths: readonly ProjectRelativePath[]): Promise<readonly Readonly<MetadataValidationOutput>[]> {
@@ -128,6 +154,11 @@ export class ValidateDesignStoryAnnotationsUseCase {
             }
           }
         }
+        if (this.workItemIdentityPort && isWorkItemDescriptionPath(filePath)) {
+          const entries = await this.workItemIdentityPort.listWorkItemIdentities();
+          const violations = this.workItemIdentityValidationService.validate(entries);
+          workItemFrontmatterErrors.push(...violations.map(toWorkItemIdentityError));
+        }
 
         const flags = await this.designDocumentPort.readFrontmatterFlags(filePath);
         const annotations = await this.designDocumentPort.readStoryAnnotations(filePath);
@@ -146,3 +177,7 @@ export class ValidateDesignStoryAnnotationsUseCase {
     return Object.freeze(results);
   }
 }
+
+function isWorkItemDescriptionPath(filePath: ProjectRelativePath): boolean {
+  return /(?:^|\/)WI-\d+\/description\.md$/.test(filePath.toString());
+}

package/scripts/harness/traceability-model/composition-root.ts

@@ -19,6 +19,7 @@ import { FileSystemInceptionPlanGateway } from "./infrastructure/gateways/file-s
 import { FileSystemMetadataReader } from "./infrastructure/gateways/file-system-metadata-reader.js";
 import { FileSystemWorkItemMigrationApplyGateway } from "./infrastructure/gateways/file-system-work-item-migration-apply-gateway.js";
 import { FileSystemWorkItemMigrationSourceGateway } from "./infrastructure/gateways/file-system-work-item-migration-source-gateway.js";
+import { FileSystemWorkItemIdentityGateway } from "./infrastructure/gateways/file-system-work-item-identity-gateway.js";
 import { MarkdownDesignDocumentGateway } from "./infrastructure/gateways/markdown-design-document-gateway.js";
 import { MarkdownStoryCatalogGateway } from "./infrastructure/gateways/markdown-story-catalog-gateway.js";
 import { MarkdownUnitDefinitionGateway } from "./infrastructure/gateways/markdown-unit-definition-gateway.js";
@@ -61,6 +62,7 @@ export function createTraceabilityModelModule(
   const inceptionPlan = new FileSystemInceptionPlanGateway({ rootDir });
   const workItemMigrationSource = new FileSystemWorkItemMigrationSourceGateway({ rootDir });
   const workItemMigrationApply = new FileSystemWorkItemMigrationApplyGateway({ rootDir });
+  const workItemIdentity = new FileSystemWorkItemIdentityGateway({ rootDir });
 
   // Domain services
   const metadataValidator = new MetadataValidator({
@@ -85,6 +87,7 @@ export function createTraceabilityModelModule(
   const validateDesignStoryAnnotationsUseCase = new ValidateDesignStoryAnnotationsUseCase({
     designDocumentPort: designDocument,
     validator: metadataValidator,
+    workItemIdentityPort: workItemIdentity,
   });
   const validateTestStoryMetadataUseCase = new ValidateTestStoryMetadataUseCase({
     metadataReaderPort: metadataReader,

package/scripts/harness/traceability-model/domain/ports/work-item-identity-port.ts

@@ -0,0 +1,13 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-106
+
+export interface WorkItemIdentityEntry {
+  readonly filePath: string;
+  readonly directoryId: string;
+  readonly frontmatterId: string;
+}
+
+export interface WorkItemIdentityPort {
+  listWorkItemIdentities(): Promise<readonly WorkItemIdentityEntry[]>;
+}

package/scripts/harness/traceability-model/domain/services/work-item-identity-validation-service.ts

@@ -0,0 +1,46 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-106
+
+import type { WorkItemIdentityEntry } from "../ports/work-item-identity-port.js";
+
+export interface WorkItemIdentityViolation {
+  readonly code: "duplicate-id" | "directory-id-mismatch";
+  readonly workItemId: string;
+  readonly filePaths: readonly string[];
+  readonly message: string;
+}
+
+export class WorkItemIdentityValidationService {
+  validate(entries: readonly WorkItemIdentityEntry[]): readonly WorkItemIdentityViolation[] {
+    const violations: WorkItemIdentityViolation[] = [];
+    const byId = new Map<string, WorkItemIdentityEntry[]>();
+
+    for (const entry of entries) {
+      if (entry.directoryId !== entry.frontmatterId) {
+        violations.push({
+          code: "directory-id-mismatch",
+          workItemId: entry.frontmatterId,
+          filePaths: Object.freeze([entry.filePath]),
+          message: `WI directory id ${entry.directoryId} does not match frontmatter id ${entry.frontmatterId}: ${entry.filePath}`,
+        });
+      }
+
+      const existing = byId.get(entry.frontmatterId) ?? [];
+      existing.push(entry);
+      byId.set(entry.frontmatterId, existing);
+    }
+
+    for (const [workItemId, sameIdEntries] of byId.entries()) {
+      if (sameIdEntries.length <= 1) continue;
+      violations.push({
+        code: "duplicate-id",
+        workItemId,
+        filePaths: Object.freeze(sameIdEntries.map((entry) => entry.filePath).sort()),
+        message: `WI id ${workItemId} is duplicated: ${sameIdEntries.map((entry) => entry.filePath).sort().join(", ")}`,
+      });
+    }
+
+    return Object.freeze(violations);
+  }
+}

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-identity-gateway.ts

@@ -0,0 +1,74 @@
+// @unit traceability-model
+// @layer infrastructure
+// @work-item-id WI-106
+
+import { readdir, readFile } from "node:fs/promises";
+import * as path from "node:path";
+import type {
+  WorkItemIdentityEntry,
+  WorkItemIdentityPort,
+} from "../../domain/ports/work-item-identity-port.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
+
+const WI_DIR_PATTERN = /^WI-\d+$/;
+const SKIPPED_DIRS = new Set(["archive", "_shared", "_operation", "share"]);
+
+export interface FileSystemWorkItemIdentityGatewayDeps {
+  readonly rootDir: string;
+  readonly inceptionRoot?: string;
+}
+
+export class FileSystemWorkItemIdentityGateway implements WorkItemIdentityPort {
+  private readonly rootDir: string;
+  private readonly inceptionRoot: string;
+
+  constructor(deps: FileSystemWorkItemIdentityGatewayDeps) {
+    this.rootDir = deps.rootDir;
+    this.inceptionRoot = deps.inceptionRoot ?? "docs/inception";
+  }
+
+  async listWorkItemIdentities(): Promise<readonly WorkItemIdentityEntry[]> {
+    const results: WorkItemIdentityEntry[] = [];
+    await this.collect(this.inceptionRoot, results);
+    return Object.freeze(results.sort((a, b) => a.filePath.localeCompare(b.filePath)));
+  }
+
+  private async collect(relativeDir: string, results: WorkItemIdentityEntry[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+
+      const childDir = path.posix.join(relativeDir, entry.name);
+      if (WI_DIR_PATTERN.test(entry.name)) {
+        const descriptionPath = path.posix.join(childDir, "description.md");
+        const frontmatter = await this.readFrontmatterId(descriptionPath);
+        if (frontmatter !== null) {
+          results.push({
+            filePath: descriptionPath,
+            directoryId: entry.name,
+            frontmatterId: frontmatter,
+          });
+        }
+        continue;
+      }
+
+      await this.collect(childDir, results);
+    }
+  }
+
+  private async readFrontmatterId(descriptionPath: string): Promise<string | null> {
+    try {
+      const content = await readFile(path.join(this.rootDir, descriptionPath), "utf8");
+      return parseWorkItemFrontmatter(content)?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
+}