phasegate 0.229.0 → 0.264.0

package/scripts/harness/nyquist-validation/application/dto/generate-matrix-output.ts

@@ -2,6 +2,7 @@
 // @unit nyquist-validation
 // @work-item-id WI-125
 // @work-item-id WI-131
+// @work-item-id WI-292
 
 // Intent coverage 系の型は domain 層（value-objects/intent-coverage）を正準とし、
 // application 層はそれを参照・再エクスポートする（domain ← application の正しい依存方向）。
@@ -13,8 +14,14 @@ import type {
 export interface RequirementSourceDto {
   readonly storyId: string;
   readonly acIds: readonly string[];
+  /** 省略された legacy Story は fail-closed の required として扱う。 */
+  readonly coverageStatus?: StoryCoverageStatus;
+  /** Git 管理された順方向遷移履歴。省略時は現在 status から導出する。 */
+  readonly coverageLifecycle?: readonly StoryCoverageStatus[];
 }
 
+export type StoryCoverageStatus = 'planned' | 'required';
+
 /**
  * HF2-05: @ac が story 外の AC を指した／複数 @story のため相対 AC が解決できなかった等の
  * 「解決に失敗した @ac タグ」を advisory として記録する（error ではない）。
@@ -61,6 +68,10 @@ export interface MatrixAcMappingDto {
 
 export interface MatrixStoryDto {
   readonly storyId: string;
+  /** schema 1.0/1.1 の読み取りでは省略可。省略時は required。 */
+  readonly coverageStatus?: StoryCoverageStatus;
+  /** schema 1.0/1.1 の読み取りでは省略可。省略時は [required]。 */
+  readonly coverageLifecycle?: readonly StoryCoverageStatus[];
   readonly storyMappings: readonly MatrixAcMappingDto[];
 }
 

package/scripts/harness/nyquist-validation/application/usecases/check-ac-coverage-gate-usecase.ts

@@ -4,6 +4,7 @@
  *
  * H07-02: AcCoverageGatePolicy チェック
  */
+// @work-item-id WI-292
 import type { MatrixFilePort } from '../../domain/ports/matrix-file-port.js';
 import type { AjvValidatorPort } from './validate-matrix-usecase.js';
 import type { MatrixValidationService } from '../../domain/services/matrix-validation-service.js';
@@ -45,9 +46,14 @@ function buildMatrix(data: unknown): RequirementTestMatrix {
       return AcMapping.create({ acId: String(acm.acId ?? ''), testReferences });
     });
 
+    const coverageStatus = story.coverageStatus === 'planned' ? 'planned' : 'required';
     return StoryMapping.create({
       storyId: String(story.storyId ?? ''),
       acMappings,
+      coverageStatus,
+      coverageLifecycle: Array.isArray(story.coverageLifecycle)
+        ? story.coverageLifecycle.map((value) => String(value) as 'planned' | 'required')
+        : [coverageStatus],
     });
   });
 

package/scripts/harness/nyquist-validation/application/usecases/generate-requirement-test-matrix-usecase.ts

@@ -2,6 +2,7 @@
 // @unit nyquist-validation
 // @work-item-id WI-125
 // @work-item-id WI-131
+// @work-item-id WI-292
 
 import type { RequirementIntentCoverageService } from '../../domain/services/requirement-intent-coverage-service.js';
 import type {
@@ -175,6 +176,10 @@ export class GenerateRequirementTestMatrixUseCase {
       }
       return {
         storyId: requirement.storyId,
+        coverageStatus: requirement.coverageStatus ?? 'required',
+        coverageLifecycle: Object.freeze([
+          ...(requirement.coverageLifecycle ?? [requirement.coverageStatus ?? 'required']),
+        ]),
         storyMappings: Object.freeze(storyMappings),
       };
     });
@@ -185,10 +190,9 @@ export class GenerateRequirementTestMatrixUseCase {
     };
 
     const matrix: RequirementTestMatrixDto = {
-      // HF2-05: binding フィールドを付与するため schema 1.1 として出力する。
-      // 1.1 は 1.0 に対し optional な binding のみ追加であり、L3-004 の判定（各 AC に
-      // testReference が 1 件以上あるか）には一切影響しない。
-      version: '1.1',
+      // WI-292: Story coverage status/lifecycle を owner-derived field として追加する。
+      // schema 1.0/1.1 の読み取りは required へ正規化して後方互換を維持する。
+      version: '1.2',
       generatedAt: this.now().toISOString(),
       stories: Object.freeze(stories),
     };

package/scripts/harness/nyquist-validation/domain/entities/story-mapping.ts

@@ -4,25 +4,46 @@
  *
  * ストーリー単位のAC→テスト参照マッピングエンティティ
  */
+// @work-item-id WI-292
 import type { AcMapping, RawAcMapping } from '../value-objects/ac-mapping.js';
 
+export type StoryCoverageStatus = 'planned' | 'required';
+
 export interface StoryMappingCreateProps {
   readonly storyId: string;
   readonly acMappings: readonly AcMapping[];
+  readonly coverageStatus?: StoryCoverageStatus;
+  readonly coverageLifecycle?: readonly StoryCoverageStatus[];
 }
 
 export class StoryMapping {
   readonly storyId: string;
   readonly acMappings: readonly AcMapping[];
+  readonly coverageStatus: StoryCoverageStatus;
+  readonly coverageLifecycle: readonly StoryCoverageStatus[];
 
-  private constructor(storyId: string, acMappings: readonly AcMapping[]) {
+  private constructor(
+    storyId: string,
+    acMappings: readonly AcMapping[],
+    coverageStatus: StoryCoverageStatus,
+    coverageLifecycle: readonly StoryCoverageStatus[],
+  ) {
     this.storyId = storyId;
     this.acMappings = acMappings;
+    this.coverageStatus = coverageStatus;
+    this.coverageLifecycle = coverageLifecycle;
     Object.freeze(this);
   }
 
   static create(props: StoryMappingCreateProps): StoryMapping {
-    return new StoryMapping(props.storyId, Object.freeze([...props.acMappings]));
+    const coverageStatus = props.coverageStatus ?? 'required';
+    const coverageLifecycle = props.coverageLifecycle ?? [coverageStatus];
+    return new StoryMapping(
+      props.storyId,
+      Object.freeze([...props.acMappings]),
+      coverageStatus,
+      Object.freeze([...coverageLifecycle]),
+    );
   }
 
   findAcMapping(acId: string): AcMapping | null {
@@ -35,6 +56,10 @@ export class StoryMapping {
     );
   }
 
+  testReferenceCount(): number {
+    return this.acMappings.reduce((total, mapping) => total + mapping.testReferences.length, 0);
+  }
+
   equals(other: StoryMapping): boolean {
     return this.storyId === other.storyId;
   }
@@ -43,4 +68,6 @@ export class StoryMapping {
 export interface RawStoryMapping {
   readonly storyId: string;
   readonly acMappings: readonly RawAcMapping[];
+  readonly coverageStatus?: StoryCoverageStatus;
+  readonly coverageLifecycle?: readonly StoryCoverageStatus[];
 }

package/scripts/harness/nyquist-validation/domain/services/ac-coverage-gate-policy.ts

@@ -5,7 +5,9 @@
  * AC網羅ゲート判定ポリシー
  * validator-system の L3-004 が実行主体として呼び出す公開ポリシー
  */
+// @work-item-id WI-292
 import type { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
+import type { StoryMapping, StoryCoverageStatus } from '../entities/story-mapping.js';
 
 export interface NyquistHarnessError {
   readonly code: string;
@@ -23,6 +25,24 @@ export class AcCoverageGatePolicy {
     const errors: NyquistHarnessError[] = [];
 
     for (const sm of matrix.getAllStoryMappings()) {
+      if (!this.hasValidCoverageLifecycle(sm)) {
+        errors.push({
+          code: 'L3-004',
+          severity: 'error',
+          message: `Invalid coverage lifecycle: ${sm.storyId} (${sm.coverageLifecycle.join(' -> ')}; status=${sm.coverageStatus})`,
+        });
+        continue;
+      }
+      if (sm.coverageStatus === 'planned') {
+        if (sm.testReferenceCount() > 0) {
+          errors.push({
+            code: 'L3-004',
+            severity: 'error',
+            message: `Planned Story has test references; transition coverage status to required: ${sm.storyId}`,
+          });
+        }
+        continue;
+      }
       for (const acId of sm.uncoveredAcIds()) {
         errors.push({
           code: 'L3-004',
@@ -37,4 +57,12 @@ export class AcCoverageGatePolicy {
     }
     return { passed: false, errors: Object.freeze(errors) };
   }
+
+  private hasValidCoverageLifecycle(story: StoryMapping): boolean {
+    const lifecycle: readonly StoryCoverageStatus[] = story.coverageLifecycle;
+    const validSequence =
+      (lifecycle.length === 1 && (lifecycle[0] === 'planned' || lifecycle[0] === 'required'))
+      || (lifecycle.length === 2 && lifecycle[0] === 'planned' && lifecycle[1] === 'required');
+    return validSequence && lifecycle[lifecycle.length - 1] === story.coverageStatus;
+  }
 }

package/scripts/harness/nyquist-validation/infrastructure/adapters/markdown-requirement-source-adapter.ts

@@ -1,38 +1,105 @@
 // @layer infrastructure
 // @unit nyquist-validation
 // @work-item-id WI-125
+// @work-item-id WI-292
 
 import { readFile } from 'node:fs/promises';
 import type { RequirementSourcePort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
-import type { RequirementSourceDto } from '../../application/dto/generate-matrix-output.js';
+import type {
+  RequirementSourceDto,
+  StoryCoverageStatus,
+} from '../../application/dto/generate-matrix-output.js';
 
 // StoryId は HXX-XX 形式に加え Phase 2 拡張 Epic の HF\d+-XX 形式も許容する
 // （traceability-model の StoryId 正規表現と整合）。旧 /H\d{2}-\d{2}/ は HF2-01 を取りこぼしていた。
 const STORY_HEADING = /^###\s+(H(?:F\d+|\d{2})-\d{2}):/;
+const SECTION_HEADING = /^#{1,3}\s+/;
 const AC_ITEM = /^\s*-\s+\[[ xX]\]\s+(AC-[1-9][0-9]*):/;
+const COVERAGE_STATUS = /^\*\*Coverage status\*\*:\s*(\S+)\s*$/;
+const COVERAGE_LIFECYCLE = /^\*\*Coverage lifecycle\*\*:\s*(.+?)\s*$/;
+
+interface PendingStory {
+  readonly storyId: string;
+  readonly acIds: string[];
+  coverageStatus?: string;
+  coverageLifecycle?: readonly string[];
+}
+
+const isCoverageStatus = (value: string): value is StoryCoverageStatus =>
+  value === 'planned' || value === 'required';
+
+const isValidLifecycle = (values: readonly StoryCoverageStatus[]): boolean =>
+  (values.length === 1 && (values[0] === 'planned' || values[0] === 'required'))
+  || (values.length === 2 && values[0] === 'planned' && values[1] === 'required');
+
+function completeStory(story: PendingStory): RequirementSourceDto {
+  const rawStatus = story.coverageStatus ?? 'required';
+  if (!isCoverageStatus(rawStatus)) {
+    throw new Error(`Invalid coverage lifecycle for ${story.storyId}: unknown status ${rawStatus}`);
+  }
+  const rawLifecycle = story.coverageLifecycle ?? [rawStatus];
+  if (!rawLifecycle.every(isCoverageStatus)) {
+    throw new Error(`Invalid coverage lifecycle for ${story.storyId}: unknown lifecycle value`);
+  }
+  const lifecycle: readonly StoryCoverageStatus[] = Object.freeze([...rawLifecycle]);
+  if (!isValidLifecycle(lifecycle) || lifecycle[lifecycle.length - 1] !== rawStatus) {
+    throw new Error(
+      `Invalid coverage lifecycle for ${story.storyId}: ${lifecycle.join(' -> ')} does not end at ${rawStatus}`,
+    );
+  }
+  return {
+    storyId: story.storyId,
+    acIds: Object.freeze([...new Set(story.acIds)]),
+    coverageStatus: rawStatus,
+    coverageLifecycle: lifecycle,
+  };
+}
 
 export class MarkdownRequirementSourceAdapter implements RequirementSourcePort {
   async readRequirements(sourcePath: string): Promise<readonly RequirementSourceDto[]> {
     const content = await readFile(sourcePath, 'utf-8');
     const results: RequirementSourceDto[] = [];
-    let current: { storyId: string; acIds: string[] } | null = null;
+    let current: PendingStory | null = null;
 
     for (const line of content.split(/\r?\n/)) {
       const storyMatch = line.match(STORY_HEADING);
       if (storyMatch) {
         if (current) {
-          results.push({ storyId: current.storyId, acIds: Object.freeze([...new Set(current.acIds)]) });
+          results.push(completeStory(current));
         }
         current = { storyId: storyMatch[1], acIds: [] };
         continue;
       }
+      if (current && SECTION_HEADING.test(line)) {
+        results.push(completeStory(current));
+        current = null;
+        continue;
+      }
+      const statusMatch = line.match(COVERAGE_STATUS);
+      if (current && statusMatch) {
+        if (current.coverageStatus !== undefined) {
+          throw new Error(`Invalid coverage lifecycle for ${current.storyId}: duplicate status`);
+        }
+        current.coverageStatus = statusMatch[1];
+        continue;
+      }
+      const lifecycleMatch = line.match(COVERAGE_LIFECYCLE);
+      if (current && lifecycleMatch) {
+        if (current.coverageLifecycle !== undefined) {
+          throw new Error(`Invalid coverage lifecycle for ${current.storyId}: duplicate lifecycle`);
+        }
+        current.coverageLifecycle = Object.freeze(
+          lifecycleMatch[1].split(/\s*->\s*/).map((value) => value.trim()),
+        );
+        continue;
+      }
       const acMatch = line.match(AC_ITEM);
       if (current && acMatch) {
         current.acIds.push(acMatch[1]);
       }
     }
     if (current) {
-      results.push({ storyId: current.storyId, acIds: Object.freeze([...new Set(current.acIds)]) });
+      results.push(completeStory(current));
     }
     return Object.freeze(results.filter((result) => result.acIds.length > 0));
   }

package/scripts/harness/nyquist-validation/infrastructure/schema/matrix-schema-loader.ts

@@ -2,12 +2,16 @@
  * @layer infrastructure
  * @unit nyquist-validation
  * @work-item-id WI-222
+ * @work-item-id WI-292
  *
  * requirement-test-matrix.schema.json ローダー（シングルトンキャッシュ付き）
  *
  * HF2-05 (schema 1.1): testReferences に optional な `binding` enum（"ac"|"file"）を追加。
  * 1.1 は追加フィールドが optional かつ additionalProperties:false を満たすため、
  * `binding` を持たない 1.0 マトリクスも引き続き検証を通過する（後方互換）。
+ *
+ * WI-292 (schema 1.2): Story に optional な coverageStatus / coverageLifecycle を追加。
+ * 省略された 1.0/1.1 Story は application 層で required / [required] へ正規化する。
  */
 import { readFile } from 'node:fs/promises';
 import { resolve, join } from 'node:path';

package/scripts/harness/traceability-model/application/dto/changed-design-fragment-dto.ts

@@ -0,0 +1,31 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-305
+
+export type DesignFragmentCorpusRole = "product" | "inception";
+export type DesignFragmentChangeKind = "added" | "modified" | "deleted";
+
+export interface ChangedDesignFragmentDto {
+  readonly corpusRole: DesignFragmentCorpusRole;
+  readonly declaredKey: string;
+  readonly path: string;
+  readonly changeKind: DesignFragmentChangeKind;
+  readonly workItemIds: readonly string[];
+  readonly reflectionTargets: readonly string[];
+}
+
+export interface DesignChangeReadDiagnosticDto {
+  readonly code: string;
+  readonly path: string | null;
+}
+
+export type DesignChangeReadResultDto =
+  | {
+      readonly state: "available";
+      readonly fragments: readonly ChangedDesignFragmentDto[];
+      readonly diagnostics: readonly DesignChangeReadDiagnosticDto[];
+    }
+  | {
+      readonly state: "unavailable";
+      readonly diagnostics: readonly DesignChangeReadDiagnosticDto[];
+    };

package/scripts/harness/traceability-model/application/dto/traceability-world-read-dto.ts

@@ -0,0 +1,67 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-288
+
+export const TRACEABILITY_WORLD_READ_SCHEMA_VERSION = "phasegate-traceability-world-read/v1" as const;
+
+export type TraceabilityTestType = "unit" | "it" | "scenario";
+
+export interface TraceabilityUnitDto {
+  readonly unitId: string;
+  readonly definitionPath: string;
+  readonly constructionRoot: string | null;
+}
+
+export interface TraceabilityStoryDto {
+  readonly storyId: string;
+  readonly legacyIds: readonly string[];
+  readonly sourcePath: string;
+  readonly line: number;
+}
+
+export interface TraceabilityAcceptanceCriterionDto {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly sourcePath: string;
+  readonly line: number;
+}
+
+export interface TraceabilityWorkItemDto {
+  readonly workItemId: string;
+  readonly legacyIds: readonly string[];
+  readonly type: string;
+  readonly severity: string | null;
+  readonly status: string | null;
+  readonly affects: readonly string[];
+  readonly descriptionPath: string;
+}
+
+export interface TraceabilityTestReferenceDto {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly binding: "file";
+  readonly testType: TraceabilityTestType;
+  readonly filePath: string;
+  readonly testName: null;
+  readonly provenance: readonly {
+    readonly sourcePath: string;
+    readonly line: number;
+  }[];
+}
+
+export interface TraceabilityReadDiagnosticDto {
+  readonly code: string;
+  readonly subjectId: string | null;
+  readonly sourcePaths: readonly string[];
+  readonly message: string;
+}
+
+export interface TraceabilityWorldReadDto {
+  readonly schemaVersion: typeof TRACEABILITY_WORLD_READ_SCHEMA_VERSION;
+  readonly units: readonly TraceabilityUnitDto[];
+  readonly stories: readonly TraceabilityStoryDto[];
+  readonly acceptanceCriteria: readonly TraceabilityAcceptanceCriterionDto[];
+  readonly workItems: readonly TraceabilityWorkItemDto[];
+  readonly testReferences: readonly TraceabilityTestReferenceDto[];
+  readonly diagnostics: readonly TraceabilityReadDiagnosticDto[];
+}

package/scripts/harness/traceability-model/application/facades/design-change-read-facade.ts

@@ -0,0 +1,14 @@
+// @unit traceability-model
+// @layer application
+// @work-item-id WI-305
+
+import type { DesignChangeReadResultDto } from "../dto/changed-design-fragment-dto.js";
+import type { StagedDesignChangeSourcePort } from "../ports/staged-design-change-source-port.js";
+
+export class DesignChangeReadFacade {
+  constructor(private readonly source: StagedDesignChangeSourcePort) {}
+
+  observe(stagedFiles: readonly string[]): Promise<DesignChangeReadResultDto> {
+    return this.source.observe(stagedFiles);
+  }
+}