phasegate 0.181.0 → 0.191.0

package/docs/guide/skills-overview.md

@@ -37,15 +37,16 @@ Artifacts are placed in `inception/{unit}/{US-XXX}/`.
 Skills run per User Story:
 
 1. `/logical-designer` (US-specific mode) — Story-scoped logical design refinement.
-2. `/uiux-designer` — Final UI/UX definition incorporating test cases, logical design, and existing UI.
-3. `/unit-test-designer` — Unit test case design from domain model.
-4. `/it-test-designer` — Integration test case design from logical design.
-5. `/scenario-test-designer` — E2E scenario test case design.
-6. `/unit-test-logic-designer` — Vitest implementation logic with pseudocode.
-7. `/it-test-logic-designer` — IT Vitest implementation logic with pseudocode.
-8. `/scenario-test-logic-designer` — Playwright E2E test implementation logic.
-9. `/implementation-readiness-checker` — Automated pre-implementation readiness verification.
-10. `/story-implementor` — TDD implementation with atomic commits.
+2. `/scenario-test-designer` — E2E scenario test case design. Its `scenario_test_design.md` output is a required input of `/uiux-designer`.
+3. `/uiux-designer` — Final UI/UX definition incorporating test cases, logical design, and existing UI.
+4. `/unit-test-designer` — Unit test case design from domain model.
+5. `/it-test-designer` — Integration test case design from logical design.
+6. `/test-coverage-checker` — Coverage verification of all three test case designs before test logic design.
+7. `/unit-test-logic-designer` — Vitest implementation logic with pseudocode.
+8. `/it-test-logic-designer` — IT Vitest implementation logic with pseudocode.
+9. `/scenario-test-logic-designer` — Playwright E2E test implementation logic.
+10. `/implementation-readiness-checker` — Automated pre-implementation readiness verification.
+11. `/story-implementor` — TDD implementation with atomic commits.
 
 ### Phase Dependency Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.181.0",
+  "version": "0.191.0",
   "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/biome-ast-engine/infrastructure/parsers/comment-density-parser.ts

@@ -11,22 +11,37 @@ export type CommentDensityResult = {
 
 const SINGLE_LINE_COMMENT = /^\s*\/\//;
 const MULTI_LINE_COMMENT_START = /^\s*\/\*/;
+const DOC_COMMENT_START = /^\s*\/\*\*/;
 const MULTI_LINE_COMMENT_END = /\*\//;
 const BLANK_LINE = /^\s*$/;
+// L1 ルール (require-unit-comment / require-layer-comment) が必須化する
+// 先頭メタデータヘッダのタグ行。ファイル冒頭の連続コメント領域でのみ効力を持つ。
+const METADATA_HEADER_TAG = /^\s*\/\/\s*@(unit|layer|work-item-id|story|story-id|issue-id|module|feature|epic)\b/;
 
 /**
  * ソースコードのコメント密度と繰り返しブロック数を算出する。
  *
- * - commentLineCount: コメント行数（単一行・複数行両方）
- * - logicalLineCount: 空行を除いた行数
- * - repeatedCommentBlocks: 連続する同一コメントブロックの検出回数
+ * WI-239: commentLineCount（密度分子）は「密度に寄与する narrative コメント行数」
+ * を表すよう意味を再定義した。次は分子から除外する:
+ *   - 先頭の必須メタデータヘッダ行（`// @unit` / `// @layer` / `// @work-item-id` /
+ *     `// @story` 等。ファイル冒頭の連続コメント領域に限る）
+ *   - `/** … *\/` doc-comment ブロック（ブロック全体）
+ * 分子に残すのは narrative な `//` 行コメントと非 doc の `/* … *\/` ブロックのみ。
+ *
+ * - commentLineCount: 密度分子となる narrative コメント行数
+ * - logicalLineCount: 空行を除いた行数（分母。定義不変）
+ * - repeatedCommentBlocks: 連続する同一 narrative コメントブロックの検出回数
  */
 export const parseCommentDensity = (sourceCode: string): CommentDensityResult => {
-  const lines = sourceCode.split('\n');
+  const lines = sourceCode.split("\n");
 
   let commentLineCount = 0;
   let logicalLineCount = 0;
   let insideBlockComment = false;
+  let insideDocComment = false;
+  // ファイル冒頭の連続したメタデータヘッダ領域内かどうか。
+  // 最初のコード行または非メタデータコメントが現れた時点で false になる。
+  let insideHeaderZone = true;
 
   const commentBlocks: string[] = [];
   let currentBlock: string[] = [];
@@ -41,11 +56,14 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
     logicalLineCount += 1;
 
     if (insideBlockComment) {
-      commentLineCount += 1;
-      currentBlock.push(line.trim());
+      if (!insideDocComment) {
+        commentLineCount += 1;
+        currentBlock.push(line.trim());
+      }
 
       if (MULTI_LINE_COMMENT_END.test(line)) {
         insideBlockComment = false;
+        insideDocComment = false;
         flushBlock(currentBlock, commentBlocks);
         currentBlock = [];
       }
@@ -54,25 +72,48 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
     }
 
     if (SINGLE_LINE_COMMENT.test(line)) {
+      const isMetadataHeader = insideHeaderZone && METADATA_HEADER_TAG.test(line);
+
+      if (isMetadataHeader) {
+        // メタデータヘッダは分子・反復検出のいずれにも寄与しない。
+        continue;
+      }
+
+      // narrative な行コメントに到達 → ヘッダ領域は終了。
+      insideHeaderZone = false;
       commentLineCount += 1;
       currentBlock.push(line.trim());
       continue;
     }
 
     if (MULTI_LINE_COMMENT_START.test(line)) {
+      insideHeaderZone = false;
+      const isDocComment = DOC_COMMENT_START.test(line);
+      const isClosed = MULTI_LINE_COMMENT_END.test(line);
+
+      if (isDocComment) {
+        // doc-comment ブロックは分子・反復検出のいずれにも寄与しない。
+        if (!isClosed) {
+          insideBlockComment = true;
+          insideDocComment = true;
+        }
+        continue;
+      }
+
       commentLineCount += 1;
-      insideBlockComment = true;
       currentBlock.push(line.trim());
 
-      if (MULTI_LINE_COMMENT_END.test(line)) {
-        insideBlockComment = false;
+      if (isClosed) {
         flushBlock(currentBlock, commentBlocks);
         currentBlock = [];
+      } else {
+        insideBlockComment = true;
       }
 
       continue;
     }
 
+    insideHeaderZone = false;
     flushBlock(currentBlock, commentBlocks);
     currentBlock = [];
   }
@@ -86,7 +127,7 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
 
 const flushBlock = (current: string[], blocks: string[]): void => {
   if (current.length > 0) {
-    blocks.push(current.join('\n'));
+    blocks.push(current.join("\n"));
   }
 };
 

package/scripts/harness/ci-governance/composition-root.ts

@@ -84,7 +84,7 @@ export function buildCiGovernance(
   const templateRendererPort = new YamlTemplateRendererAdapter(harnessRoot);
   const fileExistencePort = new FileSystemExistenceAdapter(baseDir);
   const commandExistencePort = new HarnessApiCommandExistenceAdapter();
-  const adrExistencePort = new AdrFoundationExistenceAdapter();
+  const adrExistencePort = new AdrFoundationExistenceAdapter(baseDir);
   const agentsMdPort = new AgentsMdFileAdapter(baseDir);
   const agentContextDocumentPort = new AgentContextFileAdapter(baseDir, harnessRoot);
   const lessonArtifactReaderPort = new LessonArtifactFileReaderAdapter(baseDir);

package/scripts/harness/ci-governance/infrastructure/adapters/adr-foundation-existence-adapter.ts

@@ -5,12 +5,36 @@
  * AdrExistencePort実装
  */
 
+import * as path from 'node:path';
 import type { AdrExistencePort } from '../../domain/ports/adr-existence-port.js';
 
 export class AdrFoundationExistenceAdapter implements AdrExistencePort {
-  constructor(private readonly knownAdrIds: string[] = []) {}
+  private repositoryPromise: Promise<{
+    exists(id: { readonly value: string }): Promise<boolean>;
+  }> | null = null;
+
+  constructor(private readonly rootDir: string = process.cwd()) {}
 
   async exists(adrId: string): Promise<boolean> {
-    return this.knownAdrIds.includes(adrId);
+    try {
+      const { AdrId } = await import('../../../adr-foundation/domain/value-objects/adr-id.js');
+      const id = AdrId.create(adrId);
+      const repository = await this.getRepository();
+      return repository.exists(id);
+    } catch {
+      return false;
+    }
+  }
+
+  private async getRepository(): Promise<{
+    exists(id: { readonly value: string }): Promise<boolean>;
+  }> {
+    if (!this.repositoryPromise) {
+      this.repositoryPromise = (async () => {
+        const { createAdrFoundationModule } = await import('../../../adr-foundation/composition-root.js');
+        return createAdrFoundationModule(path.join(this.rootDir, 'docs', 'ADR')).adrRepository;
+      })();
+    }
+    return this.repositoryPromise;
   }
 }

package/scripts/harness/ci-governance/infrastructure/adapters/harness-api-command-existence-adapter.ts

@@ -3,10 +3,83 @@
 
 import type { CommandExistencePort } from '../../domain/ports/command-existence-port.js';
 
+const KNOWN_HARNESS_COMMANDS: readonly string[] = [
+  'baseline',
+  'bypass:audit',
+  'check-change-category',
+  'check-phase-gate',
+  'ci-check',
+  'ci:auto-refresh-agent-context',
+  'ci:check-repetition',
+  'ci:generate-template',
+  'ci:migrate-agents-md',
+  'commit-msg',
+  'complete-check',
+  'config:plan',
+  'delegate-sonnet',
+  'disable-feature',
+  'doctor',
+  'emit-agent-rules',
+  'enable-feature',
+  'hook',
+  'init',
+  'install',
+  'lint',
+  'list-adrs',
+  'list-errors',
+  'list-features',
+  'migrate',
+  'p2:check-agent-context',
+  'p2:check-freshness',
+  'p2:check-initial-creation',
+  'p2:generate-e2e-template',
+  'p2:validate-pointers',
+  'phasegate:attest',
+  'phasegate:check-phase',
+  'phasegate:check-ready',
+  'phasegate:ci-check',
+  'phasegate:complete-check',
+  'phasegate:detect-drift',
+  'phasegate:generate-matrix',
+  'phasegate:impact-analysis',
+  'phasegate:lint',
+  'phasegate:status',
+  'phasegate:verify-attestation',
+  'pre-commit',
+  'reconcile',
+  'refresh-claude-md',
+  'regression:analyze-migration',
+  'regression:configure-ci-gate',
+  'regression:migrate-v0-tests',
+  'regression:run-agent-guard',
+  'regression:run-gng-gate',
+  'regression:run-k-requirements',
+  'regression:run-k14-k15',
+  'render-errors',
+  'scaffold-design',
+  'scaffold-wi',
+  'session',
+  'setup:agent',
+  'skill:apply-cascade-update',
+  'skill:check-coverage',
+  'skill:collect-lessons',
+  'skill:execute-tdd-cycle',
+  'skill:validate-structure',
+  'skills',
+  'status',
+  'uninstall',
+  'update-skills',
+  'validate',
+  'validate-adr',
+  'validate-fix',
+  'validate-metadata',
+  'work-items:status',
+];
+
 export class HarnessApiCommandExistenceAdapter implements CommandExistencePort {
   private readonly knownCommands: Set<string>;
 
-  constructor(knownCommands: string[] = []) {
+  constructor(knownCommands: string[] = [...KNOWN_HARNESS_COMMANDS]) {
     this.knownCommands = new Set(knownCommands);
   }
 

package/scripts/harness/phase-dependency-model/domain/ports/story-reflection-file-system-port.ts

@@ -4,6 +4,8 @@
 export interface StoryReflectionFileSystemPort {
   listStoryDirectories(unitId: string): Promise<readonly string[]>;
   storyAffectsUnit(storyId: string, unitId: string): Promise<boolean>;
+  /** WI のコミット（Work-Item trailer）が scripts/harness/{unitId}/{layer}/ 配下のソースを変更したか */
+  storyTouchesUnitLayer(storyId: string, unitId: string, layer: string): Promise<boolean>;
   fileExists(path: string): Promise<boolean>;
   /** product 文書内に @story-id {storyId} アノテーションが含まれているか */
   fileContainsStoryAnnotation(productPath: string, storyId: string): Promise<boolean>;

package/scripts/harness/phase-dependency-model/domain/services/story-reflection-checker.ts

@@ -49,6 +49,14 @@ export class StoryReflectionChecker {
           continue;
         }
 
+        if (
+          resolvedInception.isCrossWorkItem &&
+          productPath.endsWith("domain_model.md") &&
+          !(await this.fsPort.storyTouchesUnitLayer(storyId, unitId, "domain"))
+        ) {
+          continue;
+        }
+
         const hasAnnotation = await this.fsPort.fileContainsStoryAnnotation(productPath, storyId);
 
         if (!hasAnnotation) {

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/file-system-story-reflection-adapter.ts

@@ -4,15 +4,18 @@
  * @work-item-id WI-115
  */
 
+import { execFile } from "node:child_process";
 import type { Dirent } from "node:fs";
 import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { promisify } from "node:util";
 import type { StoryReflectionFileSystemPort } from "../../domain/ports/story-reflection-file-system-port.js";
 
 const CROSS_WORK_ITEM_PATTERN = /^WI-\d+$/;
 const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
 const AFFECTS_INLINE_PATTERN = /^affects:\s*\[([^\]]*)\]\s*$/m;
 const LEGACY_ID_PATTERN = /^legacy_id:\s*([A-Z][\w]+-\d+)\s*$/m;
+const execFileAsync = promisify(execFile);
 
 export interface FileSystemStoryReflectionAdapterDeps {
   readonly rootDir: string;
@@ -34,6 +37,7 @@ export interface FileSystemStoryReflectionAdapterDeps {
 export class FileSystemStoryReflectionAdapter implements StoryReflectionFileSystemPort {
   private readonly rootDir: string;
   private readonly inceptionRoot: string;
+  private readonly changedPathsByStoryId = new Map<string, Promise<ReadonlySet<string>>>();
 
   constructor(deps: FileSystemStoryReflectionAdapterDeps) {
     this.rootDir = deps.rootDir;
@@ -110,7 +114,7 @@ export class FileSystemStoryReflectionAdapter implements StoryReflectionFileSyst
 
     const frontmatter = FRONTMATTER_PATTERN.exec(content)?.[1];
     if (frontmatter === undefined) {
-      return true;
+      return false;
     }
 
     const affects = AFFECTS_INLINE_PATTERN.exec(frontmatter)?.[1]
@@ -119,12 +123,81 @@ export class FileSystemStoryReflectionAdapter implements StoryReflectionFileSyst
       .filter((value) => value.length > 0);
 
     if (affects === undefined) {
-      return true;
+      return false;
     }
 
     return affects.includes(unitId);
   }
 
+  async storyTouchesUnitLayer(storyId: string, unitId: string, layer: string): Promise<boolean> {
+    const paths = await this.readChangedPathsForStory(storyId);
+    const prefix = `scripts/harness/${unitId}/${layer}/`;
+
+    for (const changedPath of paths) {
+      if (changedPath.startsWith(prefix)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private readChangedPathsForStory(storyId: string): Promise<ReadonlySet<string>> {
+    const cached = this.changedPathsByStoryId.get(storyId);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const promise = this.fetchChangedPathsForStory(storyId);
+    this.changedPathsByStoryId.set(storyId, promise);
+    return promise;
+  }
+
+  private async fetchChangedPathsForStory(storyId: string): Promise<ReadonlySet<string>> {
+    try {
+      const { stdout } = await execFileAsync(
+        "git",
+        [
+          "log",
+          "--format=@@COMMIT@@%x00%B%x00",
+          "--name-only",
+          "--grep",
+          `Work-Item:.*\\b${storyId}\\b`,
+        ],
+        { cwd: this.rootDir, maxBuffer: 32 * 1024 * 1024 },
+      );
+
+      return this.extractChangedPathsForStory(stdout, storyId);
+    } catch {
+      return new Set<string>();
+    }
+  }
+
+  private extractChangedPathsForStory(output: string, storyId: string): ReadonlySet<string> {
+    const changedPaths = new Set<string>();
+    const trailerPattern = new RegExp(`Work-Item:[^\\n]*\\b${storyId}\\b`);
+
+    for (const commitBlock of output.split("@@COMMIT@@\u0000")) {
+      if (commitBlock.length === 0) continue;
+
+      const bodyEnd = commitBlock.indexOf("\u0000");
+      if (bodyEnd === -1) continue;
+
+      const body = commitBlock.slice(0, bodyEnd);
+      if (!trailerPattern.test(body)) continue;
+
+      const nameOnly = commitBlock.slice(bodyEnd + 1);
+      for (const changedPath of nameOnly.split(/\r?\n/)) {
+        const trimmedPath = changedPath.trim();
+        if (trimmedPath.length > 0 && trimmedPath !== "@@COMMIT@@") {
+          changedPaths.add(trimmedPath);
+        }
+      }
+    }
+
+    return changedPaths;
+  }
+
   async fileContainsStoryAnnotation(productPath: string, storyId: string): Promise<boolean> {
     const absolutePath = path.join(this.rootDir, productPath);
 

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

@@ -173,9 +173,12 @@ export function renderSkillForModelDelegation(content: string, policy: ModelDele
   return content
     .replace(/^model:\s+\S+\n/gm, "")
     .replace(/^review:\s+\S+\n/gm, "")
-    .replaceAll("Sonnet 4.6 に委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）", "メインセッションが成果物を生成する")
+    .replaceAll(
+      "委任先モデルに委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）",
+      "メインセッションが成果物を生成する",
+    )
     .replaceAll("Opus が", "メインセッションが")
-    .replaceAll("Sonnet 4.6", "メインセッション")
+    .replaceAll("委任先モデル", "メインセッション")
     .replaceAll("`npx phasegate delegate-sonnet`", "メインセッション");
 }
 
@@ -726,10 +729,7 @@ export async function deployHuskyCommitMsgHook(
   return { created: true, path: targetPath };
 }
 
-export async function deployHuskyPrePushHook(
-  harnessRoot: string,
-  projectRoot: string,
-): Promise<DeployHuskyHookResult> {
+export async function deployHuskyPrePushHook(harnessRoot: string, projectRoot: string): Promise<DeployHuskyHookResult> {
   const targetPath = join(projectRoot, ".husky", "pre-push");
 
   try {

package/scripts/harness/skill-quality/domain/services/skill-structure-validator.ts

@@ -1,12 +1,13 @@
 /**
  * @layer domain
  * @unit skill-quality
- * @work-item-id WI-212
+ * @work-item-id WI-212, WI-241
  */
 import { SkillStructure } from '../value-objects/skill-structure.js';
 import { SkillValidationResult } from '../value-objects/skill-validation-result.js';
 import type { SkillFileReaderPort } from '../ports/skill-file-reader-port.js';
 import type { SectionName } from '../types/section-name.js';
+import type { SkillKind } from '../types/skill-kind.js';
 
 export class SkillStructureValidator {
   constructor(private readonly skillFileReaderPort: SkillFileReaderPort) {}
@@ -14,7 +15,8 @@ export class SkillStructureValidator {
   async validate(skillFilePath: string): Promise<SkillValidationResult> {
     const rawContent = await this.skillFileReaderPort.read(skillFilePath);
     const actualSections = this.extractSections(rawContent);
-    const structure = SkillStructure.default();
+    const kind = this.extractKind(rawContent);
+    const structure = SkillStructure.forKind(kind);
     const missingSections = structure.getMissingSections(actualSections);
 
     if (missingSections.length === 0) {
@@ -74,6 +76,15 @@ export class SkillStructureValidator {
     return sections;
   }
 
+  private extractKind(content: string): SkillKind {
+    const lines = content.split('\n');
+    const closingDelimiterIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (lines[0]?.trim() !== '---' || closingDelimiterIndex < 0) return 'lifecycle';
+
+    const frontmatterLines = lines.slice(1, closingDelimiterIndex);
+    return frontmatterLines.some((line) => /^\s*kind\s*:\s*advisory\s*$/.test(line)) ? 'advisory' : 'lifecycle';
+  }
+
   private hasLanguageMetadata(lines: readonly string[]): boolean {
     const closingDelimiterIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
     if (closingDelimiterIndex < 0) return false;

package/scripts/harness/skill-quality/domain/types/skill-kind.ts

@@ -0,0 +1,6 @@
+/**
+ * @layer domain
+ * @unit skill-quality
+ * @work-item-id WI-241
+ */
+export type SkillKind = 'lifecycle' | 'advisory';

package/scripts/harness/skill-quality/domain/value-objects/skill-structure.ts

@@ -1,11 +1,12 @@
 /**
  * @layer domain
  * @unit skill-quality
- * @work-item-id WI-212
+ * @work-item-id WI-212, WI-241
  */
 import type { SectionName } from '../types/section-name.js';
+import type { SkillKind } from '../types/skill-kind.js';
 
-const REQUIRED_SECTIONS: readonly SectionName[] = [
+const REQUIRED_SECTIONS: readonly SectionName[] = Object.freeze([
   'frontmatter',
   'languageMetadata',
   'purpose',
@@ -13,7 +14,13 @@ const REQUIRED_SECTIONS: readonly SectionName[] = [
   'outputs',
   'prerequisites',
   'executionFlow',
-];
+]);
+
+const ADVISORY_REQUIRED_SECTIONS: readonly SectionName[] = Object.freeze([
+  'frontmatter',
+  'languageMetadata',
+  'purpose',
+]);
 
 export class SkillStructure {
   readonly requiredSections: readonly SectionName[];
@@ -23,13 +30,22 @@ export class SkillStructure {
     Object.freeze(this);
   }
 
-  private static _instance: SkillStructure | null = null;
+  private static _instances: Partial<Record<SkillKind, SkillStructure>> = {};
 
-  static default(): SkillStructure {
-    if (!SkillStructure._instance) {
-      SkillStructure._instance = new SkillStructure(REQUIRED_SECTIONS);
+  static forKind(kind: SkillKind): SkillStructure {
+    const cached = SkillStructure._instances[kind];
+    if (cached) {
+      return cached;
     }
-    return SkillStructure._instance;
+
+    const requiredSections = kind === 'advisory' ? ADVISORY_REQUIRED_SECTIONS : REQUIRED_SECTIONS;
+    const instance = new SkillStructure(requiredSections);
+    SkillStructure._instances[kind] = instance;
+    return instance;
+  }
+
+  static default(): SkillStructure {
+    return SkillStructure.forKind('lifecycle');
   }
 
   getMissingSections(actualSections: readonly SectionName[]): readonly SectionName[] {

package/skills/cascade-updater/SKILL.md

@@ -12,7 +12,7 @@ languages: [typescript]
 
 ## storyReflection ゲート通過の標準手段
 
-`phaseDependencies.storyReflection`（ADR-013）は、`docs/inception/{unit}/{storyId}/` 配下の US/issue 設計が `docs/product/construction/{unit}/` の累積設計文書に反映されていない場合、`src/{unit}/*` および `scripts/harness/{unit}/*` への Write/Edit（Bash 迂回経由の書き込みも含む）を pre-tool-use hook でブロックする。
+`phaseDependencies.storyReflection`（ADR-013）は、`docs/inception/{unit}/{storyId}/` 配下の US/issue 設計が `docs/product/construction/{unit}/` の累積設計文書に反映されていない場合、`src/{unit}/*`（phasegate 自リポジトリ（dogfood）では `scripts/harness/{unit}/*`）への Write/Edit（Bash 迂回経由の書き込みも含む）を pre-tool-use hook でブロックする。
 
 **cascade-updater はこの storyReflection ゲートを通過する標準手段である。**
 
@@ -21,7 +21,7 @@ languages: [typescript]
 - `minimal` プリセットでは storyReflection が無効化されるためゲート連動しないが、cascade-updater による設計整合性の維持は推奨される
 - Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和されるため、cascade-updater 実行の必須性は緩まる（ただし品質維持のため実行は推奨）
 
-詳細は ADR-013 および `docs/guide/configuration.md` の storyReflection セクションを参照。
+詳細は ADR-013 および `docs/guide/configuration.md` の storyReflection セクションを参照（consumer プロジェクトでは `node_modules/phasegate/docs/ADR/...` / `node_modules/phasegate/docs/guide/...`、phasegate 自リポジトリでは `docs/...` を参照する）。
 
 ## 前提条件チェック
 
@@ -120,7 +120,7 @@ languages: [typescript]
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む

package/skills/codebase-mapper/SKILL.md

@@ -8,9 +8,21 @@ languages: [typescript]
 
 # Codebase Mapper
 
+## 目的
+
 全ソースファイルの `@unit`/`@layer` アノテーションとimportグラフを解析し、
 コードベースの構造マップを生成するスキル。
 
+## 入力
+
+- 解析対象ソース: `phasegate.config.json` の `sourceDir` 配下の `**/*.ts`（`__tests__/`・`*.test.ts` は除外）
+- 各ソースファイルの `@unit` / `@layer` アノテーションと `import` 文（Unit間依存グラフの構築に使用）
+
+## 前提条件
+
+- `phasegate.config.json` に `sourceDir` が設定されていること
+- 解析対象ソースに `@unit` / `@layer` アノテーションが付与されていること（欠落ファイルは後述「アノテーション欠落の対処」で報告される）
+
 ## 出力物
 
 `{constructionDir}/codebase-map.md` — Unit・レイヤー分布・依存関係の可視化文書（パスは `phasegate.config.json` で設定）
@@ -99,7 +111,7 @@ Unit間依存グラフを深さ優先探索でサイクル検出する。
 
 | Unit | ファイル数 | レイヤー分布 |
 |------|----------|-----------|
-| harness-error | 12 | domain:4, app:4, infra:2, pres:2 |
+| unit-a | 12 | domain:4, app:4, infra:2, pres:2 |
 | ...
 
 ---
@@ -107,11 +119,11 @@ Unit間依存グラフを深さ優先探索でサイクル検出する。
 ## Unit 間依存グラフ
 
 ```
-harness-api
-  └── depends on: biome-ast-engine, validator-system, ...
+unit-a
+  └── depends on: unit-b, unit-c, ...
 
-validator-system
-  └── depends on: harness-error, config-foundation
+unit-c
+  └── depends on: unit-d, unit-e
 ```
 
 ---