phasegate 0.44.0 → 0.63.0

package/scripts/harness/quick-mode/presentation/handlers/check-change-category-handler.ts

@@ -0,0 +1,50 @@
+/**
+ * @layer presentation
+ * @unit quick-mode
+ * @story H10-05
+ *
+ * phasegate check-change-category CLI のハンドラ
+ */
+
+import type { ClassifyChangeCategoryUseCase } from '../../application/usecases/classify-change-category-usecase.js';
+import { ChangeCategoryFormatter, type ChangeCategoryOutputFormat } from '../formatters/change-category-formatter.js';
+
+export interface CheckChangeCategoryHandlerDeps {
+  useCase: Pick<ClassifyChangeCategoryUseCase, 'execute'>;
+  writer?: (s: string) => void;
+}
+
+export interface CheckChangeCategoryHandlerOptions {
+  paths?: string;
+  format?: ChangeCategoryOutputFormat;
+  failOnFullRequired?: boolean;
+}
+
+export interface CheckChangeCategoryHandlerResult {
+  exitCode: number;
+}
+
+export class CheckChangeCategoryHandler {
+  private readonly useCase: Pick<ClassifyChangeCategoryUseCase, 'execute'>;
+  private readonly writer: (s: string) => void;
+  private readonly formatter = new ChangeCategoryFormatter();
+
+  constructor(deps: CheckChangeCategoryHandlerDeps) {
+    this.useCase = deps.useCase;
+    this.writer = deps.writer ?? ((s: string) => process.stdout.write(s));
+  }
+
+  async handle(options: CheckChangeCategoryHandlerOptions): Promise<CheckChangeCategoryHandlerResult> {
+    const { paths: pathsRaw, format = 'human', failOnFullRequired = false } = options;
+
+    const paths = pathsRaw
+      ? pathsRaw.split(',').map((p) => p.trim()).filter((p) => p.length > 0)
+      : [];
+
+    const contract = await this.useCase.execute({ paths });
+    this.writer(this.formatter.format(contract, format));
+
+    const exitCode = failOnFullRequired && contract.fullModeRequired ? 1 : 0;
+    return { exitCode };
+  }
+}

package/scripts/harness/setup/skill-deployer.ts

@@ -391,3 +391,33 @@ export async function deployHuskyHook(
 
   return { created: true, path: targetPath };
 }
+
+export interface DeployCodexHooksResult {
+  created: boolean;
+  path: string;
+}
+
+/**
+ * Codex CLI 向け hooks.json を対象プロジェクトの .codex/ にデプロイする。
+ * 既存があればスキップする (ユーザー定義 hooks を上書きしない)。
+ * ISSUE-013 Wave 2: --agent codex フラグ経由で init から呼び出される。
+ */
+export async function deployCodexHooks(
+  harnessRoot: string,
+  projectRoot: string,
+): Promise<DeployCodexHooksResult> {
+  const targetPath = join(projectRoot, '.codex', 'hooks.json');
+
+  try {
+    await fs.access(targetPath);
+    return { created: false, path: targetPath };
+  } catch {
+    // 配置先が存在しない場合は新規作成
+  }
+
+  const sourcePath = join(harnessRoot, 'templates', '.codex', 'hooks.json');
+  await fs.mkdir(join(projectRoot, '.codex'), { recursive: true });
+  await fs.copyFile(sourcePath, targetPath);
+
+  return { created: true, path: targetPath };
+}

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/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経由、またはメインセッションで直接実行）が行う

package/skills/logical-designer/SKILL.md

@@ -179,6 +179,40 @@ Unit単位でアーキテクチャの各層（DB → ドメイン → ユース
 
 ---
 
+## 🔗 成果物のトレーサビリティメタデータ（必須）
+
+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` インライン注釈
+
+ユーザーストーリーに紐づく設計要素の直前に `@story-id HXX-XX` を独立行で記述する。
+
+```markdown
+@story-id H03-02
+### ユースケース: 注文を確定する
+```
+
+形式ルール:
+- **独立行** — 他のテキストと混在させない
+- **直後に設計要素** — 空行を挟まない
+- **StoryCatalog 存在** — `HXX-XX` は `docs/product/user_stories.md` に存在する ID
+- **複数ストーリー時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
+
+---
+
 ## 注意事項
 
 - **コードスニペットは生成しない**（設計文書のみ）

package/skills/quick-implementor/SKILL.md

@@ -62,7 +62,16 @@ Quick Mode下での軽微変更実装スキル。story-implementorの緩和版
 
 1. **修正コードの実装** — 最小限の変更で問題を解決する
 2. **テストの確認/追加** — 修正に対応するテストが存在するか確認、なければ追加
-3. **L1チェック** — `@unit` / `@layer` コメントの維持を確認
+3. **L1チェック（メタデータ付与）** —
+   - **既存ファイル編集時**: `@unit` / `@layer` コメントを勝手に削除しない（意図せぬ欠落は L1-001 / L1-002 違反）
+   - **新規テストファイル作成時**: 先頭に必ず以下 3 行を付与する
+     ```typescript
+     // @unit <被テストコードと同じ Unit ID>
+     // @layer <被テストコードと同じ layer>
+     // @story <HXX-XX 形式のストーリーID>
+     ```
+     `@story` は `docs/inception/{unit}/{story_id}/` の `story_id` を使用。複数カバー時は `// @story H09-01, H09-02` のように列挙。
+   - **新規の非テストソースファイル作成**: Quick Mode のスコープ外 — `story-implementor` にエスカレーションする（quick-implementor は既存コードの修正と新規テスト追加が主スコープ）
 4. **L2チェック** — metadata 整合性、テスト品質（AAA, actual変数, 日本語テスト名）を確認
 
 ### Step 4: 検証

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

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

package/skills/story-implementor/SKILL.md

@@ -108,6 +108,64 @@ model: codex
 
 ---
 
+## ⚠️ 生成ファイルへのメタデータ付与（必須）
+
+**新規ソースファイルを作成する際、ファイル先頭に必ず `@unit` / `@layer` メタデータを記述する。これは L1 Biome ルール (`L1-001: require-unit-comment`, `L1-002: require-layer-comment`) の要件であり、欠落した状態での生成は許容されない。**
+
+### TypeScript / JavaScript ファイル
+
+```typescript
+// @unit <対象Unit名 — logical_design.md の Unit ID を使用>
+// @layer <domain | application | infrastructure | presentation>
+
+// 以下、実装コード
+```
+
+### `@unit` の決定方法
+
+- `docs/product/construction/{unit}/logical_design.md` の Unit ID をそのまま引用する
+- ストーリー固有実装の場合は、該当ストーリーが属する Unit の ID を使用
+- **複数 Unit にまたがる場合は story-implementor のスコープ違反** — `implementation-readiness-checker` に差し戻し、Unit 分割を検討する
+
+### `@layer` の決定方法
+
+生成ファイルの配置パスから機械的に決定する:
+
+| 配置パス | `@layer` の値 |
+|---------|-------------|
+| `**/domain/**` | `domain` |
+| `**/application/**` | `application` |
+| `**/infrastructure/**` | `infrastructure` |
+| `**/presentation/**` | `presentation` |
+
+Clean Architecture の 4 層構成に従わないプロジェクトは、プロジェクト側で層名を定義した上で phasegate のルール設定に同期させること。
+
+### テストファイルの場合
+
+テストファイル（`**/__tests__/**`, `*.test.ts`, `*.spec.ts`）には `@unit` / `@layer` に加えて **`@story` タグを付与する**:
+
+```typescript
+// @unit <被テストコードと同じ Unit ID>
+// @layer <被テストコードと同じ layer>
+// @story <HXX-XX 形式のストーリーID>
+```
+
+- `@story` は `docs/inception/{unit}/{story_id}/` の `story_id` を使用
+- 複数ストーリーをカバーするテストは `// @story H09-01, H09-02` のように列挙
+- US↔テストの逆引きが機械的に可能になることが目的（test-coverage-checker / nyquist が集計に使用）
+
+### 検証
+
+実装完了後、以下で L1 違反が無いことを確認する:
+
+```bash
+npx phasegate lint
+```
+
+`L1-001` / `L1-002` で違反が検出された場合、本スキル終了前に必ず解決すること。スキルを抜けた後で付け直すのはアンチパターン（直後の L1 有効化時に全違反がまとめて噴出する）。
+
+---
+
 ## ⚠️ 2フェーズ実行ルール
 
 **このスキルは必ず2フェーズに分けて実行する。Phase 1で実装計画を作成し、人間の承認を得てからPhase 2でTDD実装を行う。Phase 1とPhase 2を同時に実行してはならない。**

package/skills/unit-designer/SKILL.md

@@ -154,6 +154,47 @@ Unit分割の方針・グルーピングの根拠・不明点を整理し、人
 
 ---
 
+## 🔗 成果物のトレーサビリティメタデータ（必須）
+
+Phase 2 で生成する Unit 定義文書には、以下 2 種類のメタデータを emit する。`MetadataValidator.validateDesignDocument` が検証対象とし、ISSUE-008 Phase B-2/B-3 完了後は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+
+### 1. YAML frontmatter（新規作成時）
+
+`docs/product/units/{unit_name}.md` の先頭に以下を付与する。既存 Unit 定義の改訂時は省略してよい。`integration_contract.md` は Unit 横断のため任意。
+
+```yaml
+---
+traceability:
+  initial_creation: true
+---
+```
+
+`initial_creation: true` は「新規作成であり、後述の `@story-id` 注釈が必須」であることを示す。
+
+### 2. `@story-id` インライン注釈
+
+ユーザーストーリーに紐づく機能要件・エンドポイント定義の直前に `@story-id HXX-XX` を独立行で記述する。
+
+```markdown
+@story-id H03-02
+### 機能要件: 注文確定
+```
+
+形式ルール:
+- **独立行** — 他のテキストと混在させない
+- **直後に設計要素** — 空行を挟まない
+- **StoryCatalog 存在** — `HXX-XX` は `docs/product/user_stories.md` に存在する ID
+- **複数ストーリー時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
+
+### 3. Phase 3 レビューでの BLOCK 確認
+
+Phase 3 レビューで以下を BLOCK 基準として確認する:
+- 新規作成文書に `initial_creation: true` frontmatter が付与されているか
+- 担当ストーリーに対応する機能要件の直前に `@story-id` が配置されているか
+- 上記形式ルールに準拠しているか
+
+---
+
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体

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

@@ -189,6 +189,24 @@ TDD実装フェーズ
 
 ---
 
+## 🔗 テストファイルのトレーサビリティメタデータ（必須）
+
+Phase 2 で設計するテストファイル（`*.test.ts` / `*.spec.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）
+- 複数ストーリーをカバーするテストは `// @story H03-01, H03-02` のようにカンマ区切りで列挙
+- 目的: US↔テストの逆引きを機械化（test-coverage-checker / nyquist の集計入力）
+
+---
+
 ## 注意事項
 
 - **テストコードは生成しない**（設計文書のみ）— 実装は `story-implementor` が行う