phasegate 0.91.0 → 0.108.0

package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -7,23 +7,20 @@
  * PreToolUse Hook処理のオーケストレーション
  */
 
-import { AsyncHookToCliTranslator } from '../../domain/services/hook-to-cli-translator.js';
-import { HookEvent } from '../../domain/value-objects/hook-event.js';
-import type { BlockMetadata } from '../../domain/value-objects/hook-translation-result.js';
-import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
-import type { PhaseGateQueryPort } from '../../domain/ports/phase-gate-query-port.js';
-import type { StoryReflectionQueryPort } from '../../domain/ports/story-reflection-query-port.js';
-import type { FullModeRequirementQueryPort } from '../../domain/ports/full-mode-requirement-query-port.js';
 import type {
   BaselineGrandfatherCheckResult,
   BaselineGrandfatherQueryPort,
-} from '../../domain/ports/baseline-grandfather-query-port.js';
-import type {
-  ErrorGuidance,
-  ErrorGuidanceQueryPort,
-} from '../../domain/ports/error-guidance-query-port.js';
-import { WriteTargetScope } from '../../domain/value-objects/write-target-scope.js';
-import type { HandlePreToolUseInput, HandlePreToolUseOutput } from '../dto/handle-pre-tool-use-dto.js';
+} from "../../domain/ports/baseline-grandfather-query-port.js";
+import type { ConfigQueryPort } from "../../domain/ports/config-query-port.js";
+import type { ErrorGuidance, ErrorGuidanceQueryPort } from "../../domain/ports/error-guidance-query-port.js";
+import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
+import type { PhaseGateQueryPort } from "../../domain/ports/phase-gate-query-port.js";
+import type { StoryReflectionQueryPort } from "../../domain/ports/story-reflection-query-port.js";
+import { AsyncHookToCliTranslator } from "../../domain/services/hook-to-cli-translator.js";
+import { HookEvent } from "../../domain/value-objects/hook-event.js";
+import type { BlockMetadata } from "../../domain/value-objects/hook-translation-result.js";
+import { WriteTargetScope } from "../../domain/value-objects/write-target-scope.js";
+import type { HandlePreToolUseInput, HandlePreToolUseOutput } from "../dto/handle-pre-tool-use-dto.js";
 
 export interface HandlePreToolUseUseCasePorts {
   configQueryPort: ConfigQueryPort;
@@ -38,14 +35,17 @@ export interface HandlePreToolUseUseCasePorts {
 export class HandlePreToolUseInputValidationError extends Error {
   constructor(message: string) {
     super(message);
-    this.name = 'HandlePreToolUseInputValidationError';
+    this.name = "HandlePreToolUseInputValidationError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
 
 export class HandlePreToolUseUseCase {
   private static readonly WRITE_TOOLS: ReadonlySet<string> = new Set([
-    'Write', 'Edit', 'NotebookEdit', 'str_replace_editor',
+    "Write",
+    "Edit",
+    "NotebookEdit",
+    "str_replace_editor",
   ]);
 
   private readonly translator: AsyncHookToCliTranslator;
@@ -55,10 +55,7 @@ export class HandlePreToolUseUseCase {
   private readonly fullModeRequirementQueryPort?: FullModeRequirementQueryPort;
   private readonly baselineGrandfatherQueryPort?: BaselineGrandfatherQueryPort;
   private readonly errorGuidanceQueryPort?: ErrorGuidanceQueryPort;
-  private readonly grandfatherLogger: (
-    reason: string,
-    targetFilePaths: readonly string[],
-  ) => void;
+  private readonly grandfatherLogger: (reason: string, targetFilePaths: readonly string[]) => void;
 
   constructor(ports: HandlePreToolUseUseCasePorts) {
     this.configQueryPort = ports.configQueryPort;
@@ -69,10 +66,7 @@ export class HandlePreToolUseUseCase {
     this.errorGuidanceQueryPort = ports.errorGuidanceQueryPort;
     this.grandfatherLogger =
       ports.grandfatherLogger ??
-      ((reason, paths) =>
-        process.stderr.write(
-          `[baseline] grandfather skip (${reason}): ${paths.join(', ')}\n`,
-        ));
+      ((reason, paths) => process.stderr.write(`[baseline] grandfather skip (${reason}): ${paths.join(", ")}\n`));
     this.translator = new AsyncHookToCliTranslator({
       configQueryPort: ports.configQueryPort,
       reentryGuard: { isActive: () => false } as never,
@@ -83,7 +77,10 @@ export class HandlePreToolUseUseCase {
 
   private async isFullModeBypassedByDesignDocs(targetFilePaths: readonly string[]): Promise<boolean> {
     const unitId = this.deriveUnitIdFromPaths(targetFilePaths);
-    if (unitId === undefined || unitId === '') {
+    if (unitId === undefined || unitId === "") {
+      return false;
+    }
+    if (typeof this.phaseGateQueryPort.checkDesignDocsExist !== "function") {
       return false;
     }
 
@@ -95,8 +92,8 @@ export class HandlePreToolUseUseCase {
   }
 
   async execute(input: HandlePreToolUseInput): Promise<HandlePreToolUseOutput> {
-    if (!input.toolName || input.toolName.trim() === '') {
-      throw new HandlePreToolUseInputValidationError('toolNameは必須です（空文字不可）');
+    if (!input.toolName || input.toolName.trim() === "") {
+      throw new HandlePreToolUseInputValidationError("toolNameは必須です（空文字不可）");
     }
 
     const grandfather = await this.checkGrandfather(input.targetFilePaths);
@@ -108,18 +105,17 @@ export class HandlePreToolUseUseCase {
       const metadata = result.blockMetadata;
       const blockedFilePath = metadata?.blockedFilePath ?? input.targetFilePaths[0];
 
-      if (metadata?.reason === 'PROTECTED_FILE') {
+      if (metadata?.reason === "PROTECTED_FILE") {
         return HandlePreToolUseUseCase.buildProtectedFileBlockOutput(blockedFilePath);
       }
 
-      if (metadata?.reason === 'PHASE_GATE') {
+      if (metadata?.reason === "PHASE_GATE") {
         if (grandfather.allGrandfathered) {
-          this.grandfatherLogger('phase-gate', input.targetFilePaths);
+          this.grandfatherLogger("phase-gate", input.targetFilePaths);
           // fallthrough: continue to full-mode / story-reflection checks (which may also grandfather)
         } else {
-          const guidance = await this.resolveGuidance('L2-001');
-          const unitIdForGuidance =
-            metadata?.unitId ?? this.deriveUnitIdFromPaths(input.targetFilePaths);
+          const guidance = await this.resolveGuidance("L2-001");
+          const unitIdForGuidance = metadata?.unitId ?? this.deriveUnitIdFromPaths(input.targetFilePaths);
           return HandlePreToolUseUseCase.buildPhaseGateBlockOutput(
             blockedFilePath,
             metadata,
@@ -132,17 +128,19 @@ export class HandlePreToolUseUseCase {
           shouldBlock: true,
           blockedFilePath,
           error: {
-            message: `ブロックされました: ${blockedFilePath ?? '不明なファイル'}`,
+            message: `ブロックされました: ${blockedFilePath ?? "不明なファイル"}`,
           },
         };
       }
     }
 
-    if (HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName)
-        && this.fullModeRequirementQueryPort !== undefined
-        && input.targetFilePaths.length > 0) {
+    if (
+      HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName) &&
+      this.fullModeRequirementQueryPort !== undefined &&
+      input.targetFilePaths.length > 0
+    ) {
       if (grandfather.allGrandfathered) {
-        this.grandfatherLogger('full-mode', input.targetFilePaths);
+        this.grandfatherLogger("full-mode", input.targetFilePaths);
       } else {
         const fullModeResult = await this.fullModeRequirementQueryPort.check(input.targetFilePaths);
         if (fullModeResult.requiresFullMode) {
@@ -150,7 +148,7 @@ export class HandlePreToolUseUseCase {
           //（hook がスキルコンテキストを参照できない構造的ギャップへの対処）
           const bypassedByDesignDocs = await this.isFullModeBypassedByDesignDocs(input.targetFilePaths);
           if (!bypassedByDesignDocs) {
-            const guidance = await this.resolveGuidance('L2-001');
+            const guidance = await this.resolveGuidance("L2-001");
             const unitIdForGuidance = this.deriveUnitIdFromPaths(input.targetFilePaths);
             return HandlePreToolUseUseCase.buildFullModeRequiredBlockOutput(
               input.targetFilePaths[0],
@@ -169,11 +167,16 @@ export class HandlePreToolUseUseCase {
     }
 
     if (grandfather.allGrandfathered) {
-      this.grandfatherLogger('story-reflection', input.targetFilePaths);
+      this.grandfatherLogger("story-reflection", input.targetFilePaths);
+      return { shouldBlock: false };
+    }
+
+    const unitId = scope.unitId;
+    if (unitId === undefined) {
       return { shouldBlock: false };
     }
 
-    const reflectionResult = await this.storyReflectionQueryPort.checkReflection(scope.unitId!);
+    const reflectionResult = await this.storyReflectionQueryPort.checkReflection(unitId);
 
     if (reflectionResult.skipped || reflectionResult.passed) {
       return { shouldBlock: false };
@@ -186,9 +189,7 @@ export class HandlePreToolUseUseCase {
     );
   }
 
-  private async checkGrandfather(
-    targetFilePaths: readonly string[],
-  ): Promise<BaselineGrandfatherCheckResult> {
+  private async checkGrandfather(targetFilePaths: readonly string[]): Promise<BaselineGrandfatherCheckResult> {
     if (this.baselineGrandfatherQueryPort === undefined) {
       return {
         allGrandfathered: false,
@@ -222,17 +223,15 @@ export class HandlePreToolUseUseCase {
     blockedFilePath: string | undefined,
     result: {
       requiresFullMode: boolean;
-      rejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
+      rejectionRule?: "MIXED_CHANGES" | "NEW_DOMAIN" | "API_CONTRACT";
       rejectionReason?: string;
       dominantCategory?: string;
     },
     guidance: ErrorGuidance | null,
     unitId: string | undefined,
   ): HandlePreToolUseOutput {
-    const fp = blockedFilePath ?? '不明なファイル';
-    const lines: string[] = [
-      `Full mode 必須変更が検出されました: ${fp}`,
-    ];
+    const fp = blockedFilePath ?? "不明なファイル";
+    const lines: string[] = [`Full mode 必須変更が検出されました: ${fp}`];
     if (result.dominantCategory) {
       lines.push(`カテゴリ: ${result.dominantCategory}`);
     }
@@ -242,31 +241,28 @@ export class HandlePreToolUseUseCase {
     if (result.rejectionReason) {
       lines.push(`理由: ${result.rejectionReason}`);
     }
-    const suggestedSkill = guidance?.suggestedSkill ?? '/story-implementor';
+    const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
     HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance, unitId);
 
     return {
       shouldBlock: true,
       blockedFilePath,
-      blockReason: 'FULL_MODE_REQUIRED',
-      error: { message: lines.join('\n') },
+      blockReason: "FULL_MODE_REQUIRED",
+      error: { message: lines.join("\n") },
       fullModeRejectionRule: result.rejectionRule,
       fullModeDominantCategory: result.dominantCategory,
       nextAction: suggestedSkill,
     };
   }
 
-  private static appendGuidanceLines(
-    lines: string[],
-    guidance: ErrorGuidance | null,
-    unitId?: string,
-  ): void {
+  private static appendGuidanceLines(lines: string[], guidance: ErrorGuidance | null, unitId?: string): void {
     if (guidance === null) return;
     if (guidance.scaffoldCommand !== null) {
-      const command = unitId !== undefined && unitId !== ''
-        ? guidance.scaffoldCommand.replaceAll('<unit-id>', unitId)
-        : guidance.scaffoldCommand;
+      const command =
+        unitId !== undefined && unitId !== ""
+          ? guidance.scaffoldCommand.replaceAll("<unit-id>", unitId)
+          : guidance.scaffoldCommand;
       lines.push(`  scaffold: ${command}`);
     }
     if (guidance.templatePath !== null) {
@@ -291,8 +287,17 @@ export class HandlePreToolUseUseCase {
     }
 
     const projectPaths = this.configQueryPort.getProjectPaths();
+    const inceptionPath = projectPaths.getDocsInception();
 
     for (const targetFilePath of input.targetFilePaths) {
+      // WI-026 G1: inception 配下の書込は Phase 1 work であり Phase 3 reflection 対象外。
+      // 仕様上 Phase 3 = scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
+      // のみが reflection check の対象。inception 編集を含めると _cross/{WI-XXX}/ 編集が
+      // 仮想パス docs/product/construction/_cross/ への反映を要求し常時 block される。
+      if (HandlePreToolUseUseCase.isUnderInception(targetFilePath, inceptionPath)) {
+        continue;
+      }
+
       const scope = WriteTargetScope.fromPath(targetFilePath, projectPaths);
       if (scope?.level === 3 && scope.unitId !== undefined) {
         return scope;
@@ -302,10 +307,16 @@ export class HandlePreToolUseUseCase {
     return null;
   }
 
+  private static isUnderInception(targetFilePath: string, inceptionPath: string): boolean {
+    const normalizedTarget = targetFilePath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
+    const normalizedBase = inceptionPath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/").replace(/\/$/, "");
+    return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
+  }
+
   private static readonly LEVEL_LABELS: Record<number, string> = {
-    1: 'プロダクト設計',
-    2: '構築設計',
-    3: '実装',
+    1: "プロダクト設計",
+    2: "構築設計",
+    3: "実装",
   };
 
   private static buildPhaseGateBlockOutput(
@@ -315,22 +326,22 @@ export class HandlePreToolUseUseCase {
     unitId: string | undefined,
   ): HandlePreToolUseOutput {
     const levelLabel = metadata.scopeLevel
-      ? HandlePreToolUseUseCase.LEVEL_LABELS[metadata.scopeLevel] ?? `Level ${metadata.scopeLevel}`
-      : '不明';
+      ? (HandlePreToolUseUseCase.LEVEL_LABELS[metadata.scopeLevel] ?? `Level ${metadata.scopeLevel}`)
+      : "不明";
     const blockers = metadata.phaseGateBlockers ?? [];
     const lines: string[] = [
-      `フェーズゲート違反: ${blockedFilePath ?? '不明なファイル'}`,
-      `対象スコープ: Level ${metadata.scopeLevel ?? '?'} (${levelLabel})${metadata.unitId ? `, Unit: ${metadata.unitId}` : ''}`,
+      `フェーズゲート違反: ${blockedFilePath ?? "不明なファイル"}`,
+      `対象スコープ: Level ${metadata.scopeLevel ?? "?"} (${levelLabel})${metadata.unitId ? `, Unit: ${metadata.unitId}` : ""}`,
     ];
 
     if (blockers.length > 0) {
-      lines.push('ブロック理由:');
+      lines.push("ブロック理由:");
       for (const b of blockers) {
         lines.push(`  - ${b}`);
       }
     }
 
-    const suggestedSkill = guidance?.suggestedSkill ?? '/story-implementor';
+    const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
     if (metadata.unitId) {
       lines.push(`  実行例: ${suggestedSkill} --unit ${metadata.unitId}`);
@@ -340,12 +351,10 @@ export class HandlePreToolUseUseCase {
     return {
       shouldBlock: true,
       blockedFilePath,
-      blockReason: 'PHASE_GATE',
-      error: { message: lines.join('\n') },
+      blockReason: "PHASE_GATE",
+      error: { message: lines.join("\n") },
       phaseGateBlockers: [...blockers],
-      nextAction: metadata.unitId
-        ? `${suggestedSkill} --unit ${metadata.unitId}`
-        : suggestedSkill,
+      nextAction: metadata.unitId ? `${suggestedSkill} --unit ${metadata.unitId}` : suggestedSkill,
     };
   }
 
@@ -375,13 +384,9 @@ export class HandlePreToolUseUseCase {
     },
   ];
 
-  private static buildProtectedFileBlockOutput(
-    blockedFilePath: string | undefined,
-  ): HandlePreToolUseOutput {
-    const fp = blockedFilePath ?? '不明なファイル';
-    const matched = HandlePreToolUseUseCase.PROTECTED_FILE_GUIDANCE.find(
-      ({ pattern }) => pattern.test(fp),
-    );
+  private static buildProtectedFileBlockOutput(blockedFilePath: string | undefined): HandlePreToolUseOutput {
+    const fp = blockedFilePath ?? "不明なファイル";
+    const matched = HandlePreToolUseUseCase.PROTECTED_FILE_GUIDANCE.find(({ pattern }) => pattern.test(fp));
     const message = matched
       ? matched.message(fp)
       : `保護ファイルへの書き込みがブロックされました: ${fp}\nこのファイルは保護されています。/quick-implementor スキルで変更可能か確認してください。`;
@@ -389,7 +394,7 @@ export class HandlePreToolUseUseCase {
     return {
       shouldBlock: true,
       blockedFilePath,
-      blockReason: 'PROTECTED_FILE',
+      blockReason: "PROTECTED_FILE",
       error: { message },
     };
   }
@@ -402,7 +407,7 @@ export class HandlePreToolUseUseCase {
     return {
       shouldBlock: true,
       blockedFilePath,
-      blockReason: 'STORY_REFLECTION',
+      blockReason: "STORY_REFLECTION",
       error: {
         message: HandlePreToolUseUseCase.buildStoryReflectionErrorMessage(blockers),
       },
@@ -413,39 +418,42 @@ export class HandlePreToolUseUseCase {
 
   private static buildStoryReflectionErrorMessage(blockers: readonly string[]): string {
     const firstBlocker = blockers[0];
-    const details = firstBlocker === undefined
-      ? null
-      : HandlePreToolUseUseCase.extractStoryReflectionDetails(firstBlocker);
+    const details =
+      firstBlocker === undefined ? null : HandlePreToolUseUseCase.extractStoryReflectionDetails(firstBlocker);
     const lines: string[] = [];
 
+    const annotationKey = HandlePreToolUseUseCase.annotationKeyFor(details?.storyId);
+
     if (details !== null) {
       lines.push(`[L2-STORY-REFLECTION] ${details.productPath} に`);
-      lines.push(`@story-id ${details.storyId} が反映されていません。`);
-      lines.push('');
+      lines.push(`@${annotationKey} ${details.storyId} が反映されていません。`);
+      lines.push("");
     } else {
-      lines.push('[L2-STORY-REFLECTION] product 文書に @story-id が反映されていません。');
-      lines.push('');
+      lines.push(`[L2-STORY-REFLECTION] product 文書に @${annotationKey} が反映されていません。`);
+      lines.push("");
     }
 
     for (const blocker of blockers) {
       lines.push(`- ${blocker}`);
     }
 
-    lines.push('');
-    lines.push('修正方法:');
-    lines.push('  1. cascade-updater を実行して product 文書を更新');
+    lines.push("");
+    lines.push("修正方法:");
+    lines.push("  1. cascade-updater を実行して product 文書を更新");
     lines.push(
-      `  2. または手動で該当 product 文書に @story-id ${details?.storyId ?? '<STORY-ID>'} を追加`,
+      `  2. または手動で該当 product 文書に @${annotationKey} ${details?.storyId ?? "<WORK-ITEM-ID>"} を追加`,
     );
-    lines.push('');
-    lines.push('参照: ADR-XXX');
+    lines.push("");
+    lines.push("参照: ADR-XXX");
+
+    return lines.join("\n");
+  }
 
-    return lines.join('\n');
+  private static annotationKeyFor(storyId: string | undefined): "work-item-id" | "story-id" {
+    return storyId !== undefined && /^WI-\d+$/.test(storyId) ? "work-item-id" : "story-id";
   }
 
-  private static extractStoryReflectionDetails(
-    blocker: string,
-  ): { productPath: string; storyId: string } | null {
+  private static extractStoryReflectionDetails(blocker: string): { productPath: string; storyId: string } | null {
     const productPathMatch = blocker.match(/docs\/product\/construction\/[^\s]+\.md/);
     const storyIdMatch = blocker.match(/@story-id\s+([A-Z][\w-]*-\d+)|\b([A-Z][\w-]*-\d+)\b/);
     const storyId = storyIdMatch?.[1] ?? storyIdMatch?.[2];

package/scripts/harness/agent-integration/domain/ports/phase-gate-query-port.ts

@@ -1,8 +1,8 @@
 // @unit agent-integration
 // @layer domain
 
-import type { WriteTargetScope } from '../value-objects/write-target-scope.js';
-import type { PhaseGateQueryResult } from '../value-objects/phase-gate-query-result.js';
+import type { PhaseGateQueryResult } from "../value-objects/phase-gate-query-result.js";
+import type { WriteTargetScope } from "../value-objects/write-target-scope.js";
 
 export interface PhaseGateQueryPort {
   checkGate(scope: WriteTargetScope, targetFilePath?: string): Promise<PhaseGateQueryResult>;
@@ -11,5 +11,5 @@ export interface PhaseGateQueryPort {
    * 指定Unitの必須設計文書（logical_design.md / domain_model.md）が揃っているかを確認する。
    * full mode 判定の bypass 条件として用いる（ISSUE-021）。
    */
-  checkDesignDocsExist(unitId: string): Promise<boolean>;
+  checkDesignDocsExist?(unitId: string): Promise<boolean>;
 }

package/scripts/harness/agent-integration/domain/value-objects/write-target-scope.ts

@@ -1,10 +1,10 @@
 // @unit agent-integration
 // @layer domain
 
-import { posix as path } from 'node:path';
-import { WriteTargetScopeInvariantError } from '../errors/write-target-scope-invariant-error.js';
-import { type PhaseGateLevel } from '../types/phase-gate-level.js';
-import { ProjectPaths } from './project-paths.js';
+import { posix as path } from "node:path";
+import { WriteTargetScopeInvariantError } from "../errors/write-target-scope-invariant-error.js";
+import type { PhaseGateLevel } from "../types/phase-gate-level.js";
+import type { ProjectPaths } from "./project-paths.js";
 
 type WriteTargetScopeProps = {
   level: PhaseGateLevel;
@@ -27,19 +27,19 @@ export class WriteTargetScope {
 
   static create(props: WriteTargetScopeProps): WriteTargetScope {
     if (props.level !== 1 && props.level !== 2 && props.level !== 3) {
-      throw new WriteTargetScopeInvariantError('level は 1, 2, 3 のいずれかである必要があります（INV-6違反）');
+      throw new WriteTargetScopeInvariantError("level は 1, 2, 3 のいずれかである必要があります（INV-6違反）");
     }
 
     if (props.level === 1 && (props.unitId !== undefined || props.storyId !== undefined)) {
-      throw new WriteTargetScopeInvariantError('level=1 の場合、unitId と storyId は指定できません（INV-7違反）');
+      throw new WriteTargetScopeInvariantError("level=1 の場合、unitId と storyId は指定できません（INV-7違反）");
     }
 
     if (props.level === 2 && (props.unitId === undefined || props.storyId !== undefined)) {
-      throw new WriteTargetScopeInvariantError('level=2 の場合、unitId は必須で storyId は指定できません（INV-8違反）');
+      throw new WriteTargetScopeInvariantError("level=2 の場合、unitId は必須で storyId は指定できません（INV-8違反）");
     }
 
     if (props.level === 3 && props.unitId === undefined) {
-      throw new WriteTargetScopeInvariantError('level=3 の場合、unitId は必須です（INV-9違反）');
+      throw new WriteTargetScopeInvariantError("level=3 の場合、unitId は必須です（INV-9違反）");
     }
 
     return new WriteTargetScope(props);
@@ -48,11 +48,11 @@ export class WriteTargetScope {
   static fromPath(filePath: string, projectPaths: ProjectPaths): WriteTargetScope | null {
     const normalizedPath = normalize(filePath);
 
-    if (normalizedPath === '') {
+    if (normalizedPath === "") {
       return null;
     }
 
-    if (normalizedPath.includes('/__tests__/') || normalizedPath.startsWith('__tests__/')) {
+    if (normalizedPath.includes("/__tests__/") || normalizedPath.startsWith("__tests__/")) {
       return null;
     }
 
@@ -75,19 +75,18 @@ export class WriteTargetScope {
 
     const inceptionMatch = matchPrefix(normalizedPath, inceptionPath);
     if (inceptionMatch !== null) {
-      const [unitId, secondSegment, thirdSegment] = inceptionMatch;
+      const [unitId, secondSegment] = inceptionMatch;
 
-      // 横断的 issue: docs/inception/issues/{ISSUE-XXX}/ → Level 1
-      if (unitId === 'issues') {
-        return WriteTargetScope.create({ level: 1 });
-      }
+      // 横断的 WI: docs/inception/_cross/{WI-XXX}/ → Level 3
+      if (unitId === "_cross") {
+        if (secondSegment !== undefined && WORK_ITEM_ID_PATTERN.test(secondSegment)) {
+          return WriteTargetScope.create({ level: 3, unitId, storyId: secondSegment });
+        }
 
-      // Unit固有 issue: docs/inception/{unit}/issues/{ISSUE-XXX}/ → Level 3
-      if (unitId !== undefined && secondSegment === 'issues' && thirdSegment !== undefined && WORK_ITEM_ID_PATTERN.test(thirdSegment)) {
-        return WriteTargetScope.create({ level: 3, unitId, storyId: thirdSegment });
+        return WriteTargetScope.create({ level: 1 });
       }
 
-      // 既存 US パス: docs/inception/{unit}/{storyId}/ → Level 3
+      // Unit 所有 WI / 既存 US パス: docs/inception/{unit}/{storyId}/ → Level 3
       if (unitId !== undefined && secondSegment !== undefined && WORK_ITEM_ID_PATTERN.test(secondSegment)) {
         return WriteTargetScope.create({ level: 3, unitId, storyId: secondSegment });
       }
@@ -110,12 +109,7 @@ export class WriteTargetScope {
 
     const productRoot = normalize(path.dirname(normalize(projectPaths.getDocsConstruction())));
     const productMatch = matchPrefix(normalizedPath, productRoot);
-    if (
-      productMatch !== null
-      && productMatch.length === 1
-      && productMatch[0] !== undefined
-      && productMatch[0].includes('.')
-    ) {
+    if (productMatch !== null && productMatch.length === 1 && productMatch[0]?.includes(".")) {
       return WriteTargetScope.create({ level: 1 });
     }
 
@@ -123,14 +117,16 @@ export class WriteTargetScope {
   }
 
   equals(other: WriteTargetScope): boolean {
-    return this.level === other.level
-      && this.unitId === other.unitId
-      && this.storyId === other.storyId;
+    return this.level === other.level && this.unitId === other.unitId && this.storyId === other.storyId;
   }
 }
 
 const normalize = (value: string): string =>
-  value.replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+/g, '/').replace(/\/$/, '');
+  value
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+/g, "/")
+    .replace(/\/$/, "");
 
 const matchPrefix = (targetPath: string, basePath: string): string[] | null => {
   const normalizedBase = normalize(basePath);
@@ -144,5 +140,5 @@ const matchPrefix = (targetPath: string, basePath: string): string[] | null => {
   }
 
   const remainder = targetPath.slice(normalizedBase.length + 1);
-  return remainder === '' ? [] : remainder.split('/');
+  return remainder === "" ? [] : remainder.split("/");
 };

package/scripts/harness/agent-integration/infrastructure/adapters/file-system-story-reflection-query-adapter.ts

@@ -105,7 +105,7 @@ export class FileSystemStoryReflectionQueryAdapter
   ): StoryReflectionQueryResult {
     const warnings = result.warnings.map(
       (w) =>
-        `${w.storyId}: ${w.productPath} に @story-id ${w.storyId} が未反映 (optional, inception: ${w.inceptionPath})`,
+        `${w.storyId}: ${w.productPath} に @${FileSystemStoryReflectionQueryAdapter.annotationKeyFor(w.storyId)} ${w.storyId} が未反映 (optional, inception: ${w.inceptionPath})`,
     );
 
     if (!result.isBlocked()) {
@@ -114,9 +114,13 @@ export class FileSystemStoryReflectionQueryAdapter
 
     const blockers = result.violations.map(
       (v) =>
-        `${v.productPath} に @story-id ${v.storyId} が反映されていません (inception: ${v.inceptionPath})`,
+        `${v.productPath} に @${FileSystemStoryReflectionQueryAdapter.annotationKeyFor(v.storyId)} ${v.storyId} が反映されていません (inception: ${v.inceptionPath})`,
     );
 
     return StoryReflectionQueryResult.block(blockers, warnings);
   }
+
+  private static annotationKeyFor(storyId: string): "work-item-id" | "story-id" {
+    return /^WI-\d+$/.test(storyId) ? "work-item-id" : "story-id";
+  }
 }

package/scripts/harness/biome-ast-engine/application/dto/analyze-import-graph-input.ts

@@ -3,6 +3,9 @@
  * @unit biome-ast-engine
  */
 
+import type { ArchitectureSpec } from '../../domain/value-objects/architecture-spec.js';
+
 export type AnalyzeImportGraphInput = {
   readonly targets?: readonly string[];
+  readonly architecture?: ArchitectureSpec;
 };

package/scripts/harness/biome-ast-engine/application/dto/resolve-enabled-rules-output.ts

@@ -3,10 +3,12 @@
  * @unit biome-ast-engine
  */
 
+import type { ArchitectureSpec } from '../../domain/value-objects/architecture-spec.js';
 import type { RuleDefinition } from '../../domain/value-objects/rule-definition.js';
 import type { RuleName } from '../../domain/value-objects/rule-name.js';
 
 export type ResolveEnabledRulesOutput = {
   readonly enabledRules: readonly RuleDefinition[];
   readonly skippedRules: readonly RuleName[];
+  readonly architectureSpec: ArchitectureSpec;
 };

package/scripts/harness/biome-ast-engine/application/mappers/resolve-enabled-rules-output-mapper.ts

@@ -3,15 +3,18 @@
  * @unit biome-ast-engine
  */
 
+import type { ArchitectureSpec } from '../../domain/value-objects/architecture-spec.js';
 import type { RuleDefinition } from '../../domain/value-objects/rule-definition.js';
 import type { RuleName } from '../../domain/value-objects/rule-name.js';
 import type { ResolveEnabledRulesOutput } from '../dto/resolve-enabled-rules-output.js';
 
 export const toResolveEnabledRulesOutput = (
   enabledRules: readonly RuleDefinition[],
-  skippedRules: readonly RuleName[]
+  skippedRules: readonly RuleName[],
+  architectureSpec: ArchitectureSpec
 ): Readonly<ResolveEnabledRulesOutput> =>
   Object.freeze({
     enabledRules: Object.freeze([...enabledRules]),
     skippedRules: Object.freeze([...skippedRules]),
+    architectureSpec,
   });

package/scripts/harness/biome-ast-engine/application/usecases/analyze-import-graph-usecase.ts

@@ -33,7 +33,10 @@ export class AnalyzeImportGraphUseCase {
     input: AnalyzeImportGraphInput = {}
   ): Promise<Readonly<AnalyzeImportGraphOutput>> {
     const files = await this.workspaceFilePort.listSourceFiles(input.targets);
-    const snapshots = await this.sourceModuleAnalyzerPort.analyzeMany(files);
+    const snapshots = await this.sourceModuleAnalyzerPort.analyzeMany(
+      files,
+      input.architecture
+    );
     const importGraph = this.importGraphBuilder.build(snapshots);
 
     return toAnalyzeImportGraphOutput(files, snapshots, importGraph);