phasegate 0.39.0 → 0.62.0

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

@@ -14,6 +14,8 @@ import { MetadataValidator } from './domain/services/metadata-validator.js';
 import { TraceabilityChainBuilder } from './domain/services/traceability-chain-builder.js';
 import { StoryIdAliasResolver } from './domain/services/story-id-alias-resolver.js';
 import { ValidateImplementationMetadataUseCase } from './application/usecases/validate-implementation-metadata-usecase.js';
+import { ValidateDesignStoryAnnotationsUseCase } from './application/usecases/validate-design-story-annotations-usecase.js';
+import { ValidateTestStoryMetadataUseCase } from './application/usecases/validate-test-story-metadata-usecase.js';
 import { ValidateMetadataCommandHandler } from './presentation/cli/validate-metadata-command-handler.js';
 import { ProjectRelativePath } from './domain/value-objects/project-relative-path.js';
 
@@ -45,10 +47,22 @@ export function createTraceabilityModelModule(rootDir: string) {
       metadataReaderPort: metadataReader,
       validator: metadataValidator,
     });
+  const validateDesignStoryAnnotationsUseCase =
+    new ValidateDesignStoryAnnotationsUseCase({
+      designDocumentPort: designDocument,
+      validator: metadataValidator,
+    });
+  const validateTestStoryMetadataUseCase =
+    new ValidateTestStoryMetadataUseCase({
+      metadataReaderPort: metadataReader,
+      validator: metadataValidator,
+    });
 
   // Presentation handlers
   const validateMetadataCommandHandler = new ValidateMetadataCommandHandler({
     validateImplementationMetadataUseCase,
+    validateDesignStoryAnnotationsUseCase,
+    validateTestStoryMetadataUseCase,
     createProjectRelativePath: (value: string) =>
       ProjectRelativePath.create(value),
   });

package/scripts/harness/traceability-model/domain/value-objects/project-relative-path.ts

@@ -7,9 +7,12 @@
 const ALLOWED_PROJECT_ROOTS = new Set(['docs', 'scripts']);
 
 export class ProjectRelativePathError extends Error {
+  readonly value: string;
+
   constructor(value: string) {
     super(`ProjectRelativePathが不正です: ${value}`);
     this.name = 'ProjectRelativePathError';
+    this.value = value;
   }
 }
 

package/scripts/harness/traceability-model/infrastructure/parsers/markdown-story-annotation-parser.ts

@@ -2,7 +2,8 @@
  * @layer infrastructure
  * @unit traceability-model
  *
- * Markdown本文から @story-id HXX-XX の独立行を抽出するパーサー
+ * Markdown本文から @story-id HXX-XX の独立行を抽出するパーサー。
+ * code-span (backtick) と code-fence (``` / ~~~) 内部の @story-id は prose として扱わず無視する。
  */
 
 export interface ParsedStoryAnnotation {
@@ -14,22 +15,56 @@ export interface ParsedStoryAnnotation {
 
 const STORY_ID_LINE_PATTERN = /^@story-id\s+(.+)$/;
 const STORY_ID_INLINE_PATTERN = /@story-id\s+(\S+)/;
+const BACKTICK_FENCE_PATTERN = /^\s*```/;
+const TILDE_FENCE_PATTERN = /^\s*~~~/;
+
+type FenceChar = '`' | '~' | null;
+
+function detectFenceChar(line: string): FenceChar {
+  if (BACKTICK_FENCE_PATTERN.test(line)) return '`';
+  if (TILDE_FENCE_PATTERN.test(line)) return '~';
+  return null;
+}
+
+function stripCodeSpans(line: string): string {
+  return line.replace(/`[^`\n]*`/g, '');
+}
 
 /**
  * Markdown本文から @story-id 注釈を抽出する。
  * 行頭/行末空白を除去して独立行判定し、次行のコンテキストを contextLine として保持する。
+ * code-fence / code-span 内部の @story-id は除外する。
  */
 export function parseStoryAnnotations(
   content: string,
 ): readonly ParsedStoryAnnotation[] {
   const lines = content.split('\n');
   const annotations: ParsedStoryAnnotation[] = [];
+  let fenceChar: FenceChar = null;
 
   for (let i = 0; i < lines.length; i++) {
-    const trimmedLine = lines[i].trim();
+    const rawLine = lines[i];
+    const trimmedLine = rawLine.trim();
     const lineNumber = i + 1;
 
-    const standaloneMatch = STORY_ID_LINE_PATTERN.exec(trimmedLine);
+    const detected = detectFenceChar(rawLine);
+    if (fenceChar === null) {
+      if (detected !== null) {
+        fenceChar = detected;
+      }
+      if (fenceChar !== null) {
+        continue;
+      }
+    } else {
+      if (detected === fenceChar) {
+        fenceChar = null;
+      }
+      continue;
+    }
+
+    const sanitizedLine = stripCodeSpans(trimmedLine);
+
+    const standaloneMatch = STORY_ID_LINE_PATTERN.exec(sanitizedLine);
     if (standaloneMatch) {
       const contextLine =
         i + 1 < lines.length ? lines[i + 1].trim() : '';
@@ -42,7 +77,7 @@ export function parseStoryAnnotations(
       continue;
     }
 
-    const inlineMatch = STORY_ID_INLINE_PATTERN.exec(trimmedLine);
+    const inlineMatch = STORY_ID_INLINE_PATTERN.exec(sanitizedLine);
     if (inlineMatch) {
       const contextLine =
         i + 1 < lines.length ? lines[i + 1].trim() : '';

package/scripts/harness/traceability-model/presentation/cli/validate-metadata-command-handler.ts

@@ -4,8 +4,13 @@
  */
 
 import type { ValidateImplementationMetadataUseCase } from '../../application/usecases/validate-implementation-metadata-usecase.js';
+import type { ValidateDesignStoryAnnotationsUseCase } from '../../application/usecases/validate-design-story-annotations-usecase.js';
+import type { ValidateTestStoryMetadataUseCase } from '../../application/usecases/validate-test-story-metadata-usecase.js';
 import type { MetadataValidationOutput } from '../../application/dto/metadata-validation-output.js';
-import type { ProjectRelativePath } from '../../domain/value-objects/project-relative-path.js';
+import {
+  ProjectRelativePathError,
+  type ProjectRelativePath,
+} from '../../domain/value-objects/project-relative-path.js';
 
 export interface ValidateMetadataCommandInput {
   readonly filePaths: readonly string[];
@@ -19,21 +24,39 @@ export interface ValidateMetadataCommandOutput {
 }
 
 type PathFactory = (value: string) => ProjectRelativePath;
+type ImplUseCase = Pick<ValidateImplementationMetadataUseCase, 'execute'>;
+type DesignUseCase = Pick<ValidateDesignStoryAnnotationsUseCase, 'execute'>;
+type TestUseCase = Pick<ValidateTestStoryMetadataUseCase, 'execute'>;
+
+const DESIGN_DOCUMENT_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.md',
+  '.mdx',
+  '.markdown',
+]);
+const TEST_FILE_SUFFIXES = Object.freeze([
+  '.test.ts',
+  '.test.tsx',
+  '.spec.ts',
+  '.spec.tsx',
+]);
 
 export interface ValidateMetadataCommandHandlerDeps {
-  readonly validateImplementationMetadataUseCase: Pick<
-    ValidateImplementationMetadataUseCase,
-    'execute'
-  >;
+  readonly validateImplementationMetadataUseCase: ImplUseCase;
+  readonly validateDesignStoryAnnotationsUseCase: DesignUseCase;
+  readonly validateTestStoryMetadataUseCase?: TestUseCase;
   readonly createProjectRelativePath: PathFactory;
 }
 
 export class ValidateMetadataCommandHandler {
-  private readonly useCase: Pick<ValidateImplementationMetadataUseCase, 'execute'>;
+  private readonly implUseCase: ImplUseCase;
+  private readonly designUseCase: DesignUseCase;
+  private readonly testUseCase?: TestUseCase;
   private readonly createPath: PathFactory;
 
   constructor(deps: ValidateMetadataCommandHandlerDeps) {
-    this.useCase = deps.validateImplementationMetadataUseCase;
+    this.implUseCase = deps.validateImplementationMetadataUseCase;
+    this.designUseCase = deps.validateDesignStoryAnnotationsUseCase;
+    this.testUseCase = deps.validateTestStoryMetadataUseCase;
     this.createPath = deps.createProjectRelativePath;
   }
 
@@ -50,7 +73,26 @@ export class ValidateMetadataCommandHandler {
 
     try {
       const paths = input.filePaths.map((p) => this.createPath(p));
-      const results = await this.useCase.execute(paths);
+      const { designPaths, testPaths, implPaths } = this.classify(paths);
+
+      const [designResults, testResults, implResults] = await Promise.all([
+        designPaths.length > 0
+          ? this.designUseCase.execute(designPaths)
+          : Promise.resolve([] as readonly MetadataValidationOutput[]),
+        testPaths.length > 0 && this.testUseCase
+          ? this.testUseCase.execute(testPaths)
+          : Promise.resolve([] as readonly MetadataValidationOutput[]),
+        implPaths.length > 0
+          ? this.implUseCase.execute(implPaths)
+          : Promise.resolve([] as readonly MetadataValidationOutput[]),
+      ]);
+
+      const results = this.mergePreservingOrder(paths, [
+        ...designResults,
+        ...testResults,
+        ...implResults,
+      ]);
+
       const hasFailures = results.some((r) => !r.valid);
       const text = input.json
         ? JSON.stringify({ results }, null, 2)
@@ -61,7 +103,16 @@ export class ValidateMetadataCommandHandler {
         results,
         text,
       });
-    } catch {
+    } catch (err) {
+      if (err instanceof ProjectRelativePathError) {
+        return Object.freeze({
+          exitCode: 2,
+          results: Object.freeze([]),
+          text:
+            `Error: invalid file path: "${err.value}"\n` +
+            `  Hint: paths must be project-relative and start with 'docs/' or 'scripts/'.`,
+        });
+      }
       return Object.freeze({
         exitCode: 2,
         results: Object.freeze([]),
@@ -70,6 +121,49 @@ export class ValidateMetadataCommandHandler {
     }
   }
 
+  private classify(paths: readonly ProjectRelativePath[]): {
+    readonly designPaths: readonly ProjectRelativePath[];
+    readonly testPaths: readonly ProjectRelativePath[];
+    readonly implPaths: readonly ProjectRelativePath[];
+  } {
+    const designPaths: ProjectRelativePath[] = [];
+    const testPaths: ProjectRelativePath[] = [];
+    const implPaths: ProjectRelativePath[] = [];
+    for (const path of paths) {
+      if (DESIGN_DOCUMENT_EXTENSIONS.has(path.extname())) {
+        designPaths.push(path);
+      } else if (this.isTestFile(path) && this.testUseCase) {
+        testPaths.push(path);
+      } else {
+        implPaths.push(path);
+      }
+    }
+    return { designPaths, testPaths, implPaths };
+  }
+
+  private isTestFile(path: ProjectRelativePath): boolean {
+    const value = path.toString();
+    return TEST_FILE_SUFFIXES.some((suffix) => value.endsWith(suffix));
+  }
+
+  private mergePreservingOrder(
+    orderedPaths: readonly ProjectRelativePath[],
+    results: readonly MetadataValidationOutput[],
+  ): readonly MetadataValidationOutput[] {
+    const byPath = new Map<string, MetadataValidationOutput>();
+    for (const result of results) {
+      byPath.set(result.filePath, result);
+    }
+    const ordered: MetadataValidationOutput[] = [];
+    for (const path of orderedPaths) {
+      const result = byPath.get(path.toString());
+      if (result) {
+        ordered.push(result);
+      }
+    }
+    return Object.freeze(ordered);
+  }
+
   private formatText(results: readonly MetadataValidationOutput[]): string {
     const lines: string[] = [];
     for (const r of results) {

package/scripts/harness/validator-system/application/dto/run-full-validation-input.ts

@@ -13,4 +13,9 @@ export interface RunFullValidationInput {
   readonly failOnWarning?: boolean;
   readonly coverageReportPath?: string;
   readonly requirementMatrixPath?: string;
+  /**
+   * ISSUE-005 P1-4: 実行レイヤー絞り込み。未指定は全レイヤー実行。
+   * 指定された場合、`includeL4` より優先される。
+   */
+  readonly targetLayers?: readonly ('L2' | 'L3' | 'L4')[];
 }

package/scripts/harness/validator-system/application/use-cases/run-full-validation-usecase.ts

@@ -32,22 +32,50 @@ export class RunFullValidationUseCase {
   }
 
   async execute(input: RunFullValidationInput): Promise<AggregatedValidationReport> {
+    // ISSUE-005 P1-4: targetLayers で絞り込み。未指定時は従来の includeL4 挙動を維持。
     const includeL4 = input.includeL4 !== false;
+    const defaultLayers: readonly ('L2' | 'L3' | 'L4')[] = includeL4
+      ? ['L2', 'L3', 'L4']
+      : ['L2', 'L3'];
+    const effectiveLayers = input.targetLayers ?? defaultLayers;
+    const runL2 = effectiveLayers.includes('L2');
+    const runL3 = effectiveLayers.includes('L3');
+    const runL4 = effectiveLayers.includes('L4');
 
-    const l2Results = await this.l2UseCase.execute({
-      targetPaths: input.targetPaths,
-      unitName: input.unitName,
-      currentPhase: input.currentPhase,
-    });
+    type Result = {
+      validatorId: string;
+      passed: boolean;
+      errors: readonly {
+        code: string;
+        severity: string;
+        message: string;
+        suggestion: string;
+        [key: string]: unknown;
+      }[];
+      durationMs: number;
+      skipped?: boolean;
+    };
 
-    const l3Results = await this.l3UseCase.execute({
-      targetPaths: input.targetPaths,
-      coverageReportPath: input.coverageReportPath,
-      requirementMatrixPath: input.requirementMatrixPath,
-    });
+    let l2Results: readonly Result[] = [];
+    if (runL2) {
+      l2Results = await this.l2UseCase.execute({
+        targetPaths: input.targetPaths,
+        unitName: input.unitName,
+        currentPhase: input.currentPhase,
+      });
+    }
+
+    let l3Results: readonly Result[] = [];
+    if (runL3) {
+      l3Results = await this.l3UseCase.execute({
+        targetPaths: input.targetPaths,
+        coverageReportPath: input.coverageReportPath,
+        requirementMatrixPath: input.requirementMatrixPath,
+      });
+    }
 
-    let l4Results: readonly { validatorId: string; passed: boolean; errors: readonly { code: string; severity: string; message: string; suggestion: string; [key: string]: unknown }[]; durationMs: number; skipped?: boolean }[] = [];
-    if (includeL4) {
+    let l4Results: readonly Result[] = [];
+    if (runL4) {
       l4Results = await this.l4UseCase.execute({
         targetUnits: input.targetUnits,
       });

package/scripts/harness/validator-system/composition-root.ts

@@ -100,6 +100,7 @@ export interface ValidatorSystemModule {
   runQuickModeUseCase: RunQuickModeUseCase;
   aggregateValidationResultsUseCase: AggregateValidationResultsUseCase;
   runFullValidationUseCase: RunFullValidationUseCase;
+  driftDetectionService: DriftDetectionService;
   handlers: {
     runValidators: RunValidatorsHandler;
     runQuickMode: RunQuickModeHandler;
@@ -229,6 +230,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     runQuickModeUseCase,
     aggregateValidationResultsUseCase,
     runFullValidationUseCase,
+    driftDetectionService,
     handlers,
   };
 }

package/scripts/harness/validator-system/domain/services/l4/drift-detection-service.ts

@@ -9,10 +9,20 @@ import { DriftReport } from '../../value-objects/drift-report.js';
 
 export interface DriftDetectionDesignDocumentPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * ISSUE-005 P3-9: element → unit 名のマップ。
+   * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
+   */
+  getElementUnitMap?(targetUnits?: readonly string[]): Promise<Record<string, string>>;
 }
 
 export interface DriftDetectionSourceCodeAnalyzerPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * ISSUE-005 P3-9: element → unit 名のマップ。
+   * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
+   */
+  getElementUnitMap?(targetUnits?: readonly string[]): Promise<Record<string, string>>;
 }
 
 export interface DriftDetectionServiceDeps {
@@ -33,6 +43,23 @@ export class DriftDetectionService {
     const designElements = await this.designDocumentPort.getElements(targetUnits);
     const codeElements = await this.sourceCodeAnalyzerPort.getElements(targetUnits);
 
+    // ISSUE-005 P3-9: element → unit のマップを取得し、DriftReport.unitName の解決に使う
+    const designUnitMap = this.designDocumentPort.getElementUnitMap
+      ? await this.designDocumentPort.getElementUnitMap(targetUnits)
+      : {};
+    const codeUnitMap = this.sourceCodeAnalyzerPort.getElementUnitMap
+      ? await this.sourceCodeAnalyzerPort.getElementUnitMap(targetUnits)
+      : {};
+
+    const resolveUnit = (element: string): string => {
+      return (
+        designUnitMap[element] ??
+        codeUnitMap[element] ??
+        targetUnits?.[0] ??
+        'unknown'
+      );
+    };
+
     const designSet = new Set(designElements);
     const codeSet = new Set(codeElements);
 
@@ -44,7 +71,7 @@ export class DriftDetectionService {
         reports.push(
           DriftReport.create({
             direction: 'design→code',
-            unitName: (targetUnits?.[0]) ?? 'unknown',
+            unitName: resolveUnit(element),
             element,
             description: `設計に存在するがコードに存在しない: ${element}`,
             recommendation: `${element} をコードに実装してください`,
@@ -59,7 +86,7 @@ export class DriftDetectionService {
         reports.push(
           DriftReport.create({
             direction: 'code→design',
-            unitName: (targetUnits?.[0]) ?? 'unknown',
+            unitName: resolveUnit(element),
             element,
             description: `コードに存在するが設計に存在しない: ${element}`,
             recommendation: `${element} を設計文書に追記するか、コードから削除してください`,

package/scripts/harness/validator-system/infrastructure/adapters/biome-ast-source-code-analyzer-adapter.ts

@@ -44,6 +44,23 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
     const results = await this.analyzeExports(targetUnits);
     return results.flatMap((result) => result.exports.map((entry) => entry.name));
   }
+
+  /**
+   * ISSUE-005 P3-9: element 名から unit 名を引けるマップを返す。
+   * 同名 export が複数 unit に存在する場合は最初に見つかった unit を採用する。
+   */
+  async getElementUnitMap(targetUnits?: readonly string[]): Promise<Record<string, string>> {
+    const results = await this.analyzeExports(targetUnits);
+    const map: Record<string, string> = {};
+    for (const result of results) {
+      for (const entry of result.exports) {
+        if (!(entry.name in map)) {
+          map[entry.name] = result.unitName;
+        }
+      }
+    }
+    return map;
+  }
 }
 
 type ExportType = SourceAnalysisResult['exports'][number]['type'];

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -8,9 +8,55 @@ import type { DesignDocumentPort, StructuredDesignDoc } from '../../domain/ports
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
-const SECTION_PATTERN = /^#{2,3}\s+(.+)/gm;
 const ADR_PATTERN = /ADR-\d{3}/g;
 
+// ISSUE-005 P3-8: メタ見出し / 議論用セクションを drift 対象から除外するマーカー。
+// 見出し行の直後 (同一行末 or 次の非空行) に置かれたコメントを拾う。
+const SKIP_MARKER = /<!--\s*@drift-check\s*:\s*skip\s*-->/i;
+
+// 見出し文字列のうち、デフォルトで drift 対象から外す既知のメタパターン。
+// Unit 設計ドキュメントで頻出する「議論用」「自己評価」系セクション。
+const DEFAULT_META_HEADING_PATTERNS = [
+  /engineering[- ]perspective/i,
+  /自己評価/,
+  /レビュー(観点|コメント)/,
+  /議論/,
+  /TODO|未決事項|Open\s+Questions?/i,
+  /変更履歴|Change\s*Log/i,
+  /参考文献|References?/i,
+];
+
+function isMetaHeading(name: string): boolean {
+  return DEFAULT_META_HEADING_PATTERNS.some((p) => p.test(name));
+}
+
+function extractConceptNames(markdown: string): string[] {
+  const lines = markdown.split(/\r?\n/);
+  const headings: string[] = [];
+  const headingRegex = /^(#{2,3})\s+(.+?)\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const m = headingRegex.exec(lines[i]);
+    if (!m) continue;
+    const name = m[2].trim();
+    // 見出し行自体にスキップマーカーが付いている
+    if (SKIP_MARKER.test(lines[i])) continue;
+    // 次の非空行にスキップマーカーが付いている
+    // ただし、次行が新しい見出しの場合はそれ自身の注釈なので無視する
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === '') j++;
+    if (
+      j < lines.length &&
+      !headingRegex.test(lines[j]) &&
+      SKIP_MARKER.test(lines[j])
+    ) continue;
+    // 既知のメタ見出しは暗黙的にスキップ
+    if (isMetaHeading(name)) continue;
+    // 名前から末尾のスキップマーカーを落とす (念のため)
+    headings.push(name.replace(SKIP_MARKER, '').trim());
+  }
+  return headings;
+}
+
 export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
   private readonly docsRoot: string;
   private readonly cache = new Map<string, StructuredDesignDoc>();
@@ -38,10 +84,7 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
         const doc: StructuredDesignDoc = {
           unitName,
           docPath,
-          concepts: Array.from(markdown.matchAll(SECTION_PATTERN), (match) => ({
-            name: match[1].trim(),
-            type: 'class',
-          })),
+          concepts: extractConceptNames(markdown).map((name) => ({ name, type: 'class' })),
           layerDependencies: [],
           adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
         };
@@ -64,6 +107,23 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return docs.flatMap((doc) => doc.concepts.map((concept) => concept.name));
   }
 
+  /**
+   * ISSUE-005 P3-9: element 名から unit 名を引けるマップを返す。
+   * 同名 element が複数 unit に存在する場合は最初に見つかった unit を採用する。
+   */
+  async getElementUnitMap(targetUnits?: readonly string[]): Promise<Record<string, string>> {
+    const docs = await this.loadDesignDocuments(targetUnits);
+    const map: Record<string, string> = {};
+    for (const doc of docs) {
+      for (const concept of doc.concepts) {
+        if (!(concept.name in map)) {
+          map[concept.name] = doc.unitName;
+        }
+      }
+    }
+    return map;
+  }
+
   private async listUnitNames(): Promise<string[]> {
     try {
       const entries = await readdir(this.docsRoot, { withFileTypes: true });

package/scripts/harness/validator-system/presentation/handlers/run-validators-handler.ts

@@ -110,12 +110,21 @@ export class RunValidatorsHandler {
         return { output, exitCode: l1Report.overallPassed ? 0 : 1 };
       }
 
+      // ISSUE-005 P1-4: args.layer を targetLayers にマップ
+      let targetLayers: readonly ('L2' | 'L3' | 'L4')[] | undefined;
+      if (args.layer === 'L2') targetLayers = ['L2'];
+      else if (args.layer === 'L3') targetLayers = ['L3'];
+      else if (args.layer === 'L4') targetLayers = ['L4'];
+      else if (args.layer === 'all') targetLayers = ['L2', 'L3', 'L4'];
+      // undefined → フィルタなし（従来挙動）
+
       const report = await this.useCase.execute({
         targetPaths: args.targetPaths ?? [],
         unitName: args.unit ?? '',
         currentPhase: args.phase ?? '',
         includeL4: !args.noL4,
         failOnWarning: args.failOnWarning,
+        targetLayers,
       });
 
       const format = args.format ?? 'human';

package/skills/domain-designer/SKILL.md

@@ -142,6 +142,40 @@ DDD戦術パターンを用いてドメインモデルを設計するスキル
 
 ---
 
+## 🔗 成果物のトレーサビリティメタデータ（必須）
+
+Phase 2 で生成する設計文書には、以下 2 種類のメタデータを emit する。`MetadataValidator.validateDesignDocument` が検証対象とし、ISSUE-008 Phase B-2/B-3 完了後は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+
+### 1. YAML frontmatter（新規作成時）
+
+文書先頭に以下を付与する。既存文書の改訂時は省略してよい。
+
+```yaml
+---
+traceability:
+  initial_creation: true
+---
+```
+
+`initial_creation: true` は「新規作成であり、後述の `@story-id` 注釈が必須」であることを示す。
+
+### 2. `@story-id` インライン注釈
+
+ユーザーストーリーに紐づく集約・エンティティ・VO・ドメインイベントの直前に `@story-id HXX-XX` を独立行で記述する。
+
+```markdown
+@story-id H03-02
+### 集約: Order（注文）
+```
+
+形式ルール:
+- **独立行** — 他のテキストと混在させない
+- **直後に設計要素** — 空行を挟まない
+- **StoryCatalog 存在** — `HXX-XX` は `docs/product/user_stories.md` に存在する ID
+- **複数ストーリー時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
+
+---
+
 ## 注意事項
 
 - **ファイル配置は `docs/folder_management_rules.md` に従うこと**

package/skills/it-test-logic-designer/SKILL.md

@@ -231,6 +231,22 @@ Repositoryテストでは、`getTestClient()` でDBに直接クエリし永続
 - **WARNのみFAIL** → Opusが直接修正してから完了とする
 - **全PASS** → 完了
 
+## 🔗 テストファイルのトレーサビリティメタデータ（必須）
+
+Phase 2 で設計する IT テストファイル（`*.test.ts` / `*.it.test.ts`）の疑似コード冒頭には、ファイル先頭コメントブロックに `// @story HXX-XX` を emit するよう明記する。`MetadataValidator.validateTest` が検証対象とし、ISSUE-008 Phase C-2 以降は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+
+```typescript
+// @unit <被テストコードと同じ Unit ID>
+// @layer <被テストコードと同じ layer>
+// @story H03-02
+```
+
+形式ルール:
+- `@unit` / `@layer` と同じヘッダーコメントブロックに配置
+- `HXX-XX` は `docs/product/user_stories.md` に存在する ID（StoryCatalog）
+- 複数ストーリーをカバーする IT テストは `// @story H03-01, H03-02` のようにカンマ区切りで列挙
+- 目的: US↔テストの逆引きを機械化（test-coverage-checker / nyquist の集計入力）
+
 ## 注意事項
 
 - **テストコードは生成しない**（設計文書のみ）— 実装は `story-implementor` スキル（codex-delegator経由、またはメインセッションで直接実行）が行う