phasegate 0.15.0 → 0.31.0

package/scripts/harness/phase-dependency-model/domain/models/phase-structure.ts

@@ -3,9 +3,16 @@
  * @unit phase-dependency-model
  */
 
-import { DEFAULT_PHASE_DEPENDENCIES } from '../definitions/default-phase-dependencies.js';
-import { DEFAULT_PHASE_NODES } from '../definitions/default-phase-nodes.js';
+import { FULL_PHASE_DEPENDENCIES } from '../definitions/full-phase-dependencies.js';
+import { FULL_PHASE_NODES } from '../definitions/full-phase-nodes.js';
+import { MINIMAL_PHASE_DEPENDENCIES } from '../definitions/minimal-phase-dependencies.js';
+import { MINIMAL_PHASE_NODES } from '../definitions/minimal-phase-nodes.js';
+import { STANDARD_PHASE_DEPENDENCIES } from '../definitions/standard-phase-dependencies.js';
+import { STANDARD_PHASE_NODES } from '../definitions/standard-phase-nodes.js';
+import { GateGraph } from '../services/gate-graph.js';
+import { Artifact } from '../values/artifact.js';
 import { CustomRule, InvalidCustomRuleError } from '../values/custom-rule.js';
+import { GateDefinition } from '../values/gate-definition.js';
 import { PhaseCustomizationPolicy } from '../values/phase-customization-policy.js';
 import { PhaseDependency } from '../values/phase-dependency.js';
 import { PhaseGateResult } from '../values/phase-gate-result.js';
@@ -115,6 +122,34 @@ const createAuditPayload = (
   });
 };
 
+const resolvePresetDefinitions = (preset: string): {
+  nodes: readonly PhaseNode[];
+  dependencies: readonly PhaseDependency[];
+} => {
+  switch (preset) {
+    case 'standard':
+      return { nodes: STANDARD_PHASE_NODES, dependencies: STANDARD_PHASE_DEPENDENCIES };
+    case 'minimal':
+      return { nodes: MINIMAL_PHASE_NODES, dependencies: MINIMAL_PHASE_DEPENDENCIES };
+    case 'full':
+    case 'custom':
+    default:
+      return { nodes: FULL_PHASE_NODES, dependencies: FULL_PHASE_DEPENDENCIES };
+  }
+};
+
+const buildNonRelaxableDependencies = (
+  dependencies: readonly PhaseDependency[],
+): readonly PhaseDependency[] =>
+  Object.freeze(
+    dependencies.filter(
+      (dependency) =>
+        dependency.isLevelTransition() ||
+        dependency.to.nodeKey() === '3:implementation-readiness-checker' ||
+        dependency.to.nodeKey() === '3:story-implementor',
+    ),
+  );
+
 export class PhaseStructure {
   readonly levels: ReadonlyMap<1 | 2 | 3, readonly PhaseNode[]>;
   readonly nodeIndex: ReadonlyMap<string, PhaseNode>;
@@ -140,30 +175,43 @@ export class PhaseStructure {
   }
 
   static createDefault(policy: PhaseCustomizationPolicy): PhaseStructure {
-    const levels = buildLevels(DEFAULT_PHASE_NODES);
-    const nodeIndex = buildNodeIndex(DEFAULT_PHASE_NODES);
-    const nonRelaxableDependencies = Object.freeze(
-      DEFAULT_PHASE_DEPENDENCIES.filter(
-        (dependency) =>
-          dependency.isLevelTransition() ||
-          dependency.to.nodeKey() === '3:implementation-readiness-checker' ||
-          dependency.to.nodeKey() === '3:story-implementor',
+    const { nodes, dependencies } = resolvePresetDefinitions(policy.preset);
+
+    return PhaseStructure.createFromNodesAndDependencies(nodes, dependencies, policy);
+  }
+
+  static fromGates(gates: GateDefinition[], policy: PhaseCustomizationPolicy): PhaseStructure {
+    GateGraph.build(gates);
+
+    const nodes = gates.map((gate) =>
+      PhaseNode.create({
+        skillName: gate.name.value,
+        level: gate.level,
+        artifacts: gate.requires.map((requirement, index) =>
+          Artifact.create({
+            name: `${gate.name.value}-${index + 1}`,
+            path: requirement.path,
+            required: requirement.required,
+          }),
+        ),
+      }),
+    );
+    const nodeByGateName = new Map<string, PhaseNode>(
+      gates.map((gate, index) => [gate.name.value, nodes[index]]),
+    );
+    const dependencies = Object.freeze(
+      gates.flatMap((gate) =>
+        gate.dependsOn.map((dependencyName) =>
+          PhaseDependency.create({
+            from: nodeByGateName.get(dependencyName.value) as PhaseNode,
+            to: nodeByGateName.get(gate.name.value) as PhaseNode,
+            type: 'requires',
+          }),
+        ),
       ),
     );
-    const base = new PhaseStructure({
-      levels,
-      nodeIndex,
-      defaultDependencies: DEFAULT_PHASE_DEPENDENCIES,
-      effectiveDependencies: DEFAULT_PHASE_DEPENDENCIES,
-      customizationPolicy: policy,
-      nonRelaxableDependencies,
-    });
 
-    if (!policy.hasRules()) {
-      return base;
-    }
-
-    return base.applyCustomization(policy);
+    return PhaseStructure.createFromNodesAndDependencies(nodes, dependencies, policy);
   }
 
   checkPhaseGate(
@@ -486,4 +534,28 @@ export class PhaseStructure {
       visit(nodeKey);
     }
   }
+
+  private static createFromNodesAndDependencies(
+    nodes: readonly PhaseNode[],
+    dependencies: readonly PhaseDependency[],
+    policy: PhaseCustomizationPolicy,
+  ): PhaseStructure {
+    const levels = buildLevels(nodes);
+    const nodeIndex = buildNodeIndex(nodes);
+    const nonRelaxableDependencies = buildNonRelaxableDependencies(dependencies);
+    const base = new PhaseStructure({
+      levels,
+      nodeIndex,
+      defaultDependencies: dependencies,
+      effectiveDependencies: dependencies,
+      customizationPolicy: policy,
+      nonRelaxableDependencies,
+    });
+
+    if (!policy.hasRules()) {
+      return base;
+    }
+
+    return base.applyCustomization(policy);
+  }
 }

package/scripts/harness/phase-dependency-model/domain/ports/glob-matcher-port.ts

@@ -0,0 +1,8 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+export interface GlobMatcherPort {
+  match(pattern: string, path: string): boolean;
+}

package/scripts/harness/phase-dependency-model/domain/ports/phase-config-provider-port.ts

@@ -5,9 +5,11 @@
 
 import type { PhaseCustomizationPolicy } from '../values/phase-customization-policy.js';
 import type { PlanningMode } from '../values/planning-mode.js';
+import type { StoryReflectionConfig } from '../values/story-reflection-config.js';
 
 export interface PhaseConfigProviderPort {
   getPlanningMode(scope: { unitId?: string; storyId?: string }): Promise<PlanningMode>;
   getCustomizationPolicy(): Promise<PhaseCustomizationPolicy>;
   getReportingOutputDir(): Promise<string>;
+  getStoryReflectionConfig(): Promise<StoryReflectionConfig>;
 }

package/scripts/harness/phase-dependency-model/domain/ports/story-annotation-verifier-port.ts

@@ -0,0 +1,14 @@
+// @unit phase-dependency-model
+// @layer domain
+
+export interface StoryAnnotationVerificationResult {
+  readonly hasAnnotation: boolean;
+  readonly storyId?: string;
+}
+
+export interface StoryAnnotationVerifierPort {
+  verify(
+    targetFilePath: string,
+    tag: string,
+  ): Promise<StoryAnnotationVerificationResult>;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+export interface StoryReflectionFileSystemPort {
+  /** inception/{unit}/ 配下の storyId ディレクトリ名一覧を返す */
+  listStoryDirectories(unitId: string): Promise<readonly string[]>;
+  /** ファイルの存在チェック */
+  fileExists(path: string): Promise<boolean>;
+  /** product 文書内に @story-id {storyId} アノテーションが含まれているか */
+  fileContainsStoryAnnotation(
+    productPath: string,
+    storyId: string,
+  ): Promise<boolean>;
+}

package/scripts/harness/phase-dependency-model/domain/services/gate-graph.ts

@@ -0,0 +1,223 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import { GateDefinition } from '../values/gate-definition.js';
+import { GateName } from '../values/gate-name.js';
+
+export interface GateGraphViolation {
+  readonly code:
+    | 'DUPLICATE_GATE_NAME'
+    | 'UNKNOWN_DEPENDENCY'
+    | 'LEVEL_ORDER_VIOLATION'
+    | 'CYCLIC_DEPENDENCY';
+  readonly message: string;
+  readonly gateNames: readonly string[];
+}
+
+export class GateGraphValidationError extends Error {
+  readonly violations: readonly GateGraphViolation[];
+
+  constructor(violations: readonly GateGraphViolation[]) {
+    super(violations.map((violation) => violation.message).join('\n'));
+    this.name = 'GateGraphValidationError';
+    this.violations = Object.freeze([...violations]);
+  }
+}
+
+const toViolation = (
+  code: GateGraphViolation['code'],
+  message: string,
+  gateNames: readonly string[],
+): GateGraphViolation =>
+  Object.freeze({
+    code,
+    message,
+    gateNames: Object.freeze([...gateNames]),
+  });
+
+export class GateGraph {
+  readonly gates: ReadonlyMap<string, GateDefinition>;
+
+  private constructor(gates: ReadonlyMap<string, GateDefinition>) {
+    this.gates = gates;
+    Object.freeze(this);
+  }
+
+  static build(gates: GateDefinition[]): GateGraph {
+    const violations: GateGraphViolation[] = [];
+    const duplicateNames = new Set<string>();
+    const gateMap = new Map<string, GateDefinition>();
+
+    for (const gate of gates) {
+      const name = gate.name.value;
+      if (gateMap.has(name)) {
+        duplicateNames.add(name);
+        continue;
+      }
+      gateMap.set(name, gate);
+    }
+
+    for (const duplicateName of duplicateNames) {
+      violations.push(
+        toViolation(
+          'DUPLICATE_GATE_NAME',
+          `重複する GateName です: ${duplicateName}`,
+          [duplicateName],
+        ),
+      );
+    }
+
+    for (const gate of gateMap.values()) {
+      for (const dependencyName of gate.dependsOn) {
+        const dependency = gateMap.get(dependencyName.value);
+        if (!dependency) {
+          violations.push(
+            toViolation(
+              'UNKNOWN_DEPENDENCY',
+              `未知の dependsOn 参照です: ${gate.name.value} -> ${dependencyName.value}`,
+              [gate.name.value, dependencyName.value],
+            ),
+          );
+          continue;
+        }
+
+        if (dependency.level.value > gate.level.value) {
+          violations.push(
+            toViolation(
+              'LEVEL_ORDER_VIOLATION',
+              `レベル逆行です: ${gate.name.value} -> ${dependencyName.value}`,
+              [gate.name.value, dependencyName.value],
+            ),
+          );
+        }
+      }
+    }
+
+    const graph = new Map<string, string[]>();
+    for (const gate of gateMap.values()) {
+      graph.set(gate.name.value, []);
+    }
+    for (const gate of gateMap.values()) {
+      const neighbors = graph.get(gate.name.value);
+      if (!neighbors) {
+        continue;
+      }
+      for (const dependencyName of gate.dependsOn) {
+        if (gateMap.has(dependencyName.value)) {
+          neighbors.push(dependencyName.value);
+        }
+      }
+    }
+
+    for (const cycle of GateGraph.detectCycles(graph)) {
+      violations.push(
+        toViolation(
+          'CYCLIC_DEPENDENCY',
+          `循環依存が検出されました: ${cycle.join(' -> ')}`,
+          cycle,
+        ),
+      );
+    }
+
+    if (violations.length > 0) {
+      throw new GateGraphValidationError(violations);
+    }
+
+    return new GateGraph(gateMap);
+  }
+
+  resolveAncestors(name: GateName): GateName[] {
+    const target = this.gates.get(name.value);
+    if (!target) {
+      return [];
+    }
+
+    const visited = new Set<string>();
+    const ordered: GateName[] = [];
+
+    const visit = (gate: GateDefinition): void => {
+      for (const dependencyName of gate.dependsOn) {
+        if (visited.has(dependencyName.value)) {
+          continue;
+        }
+
+        const dependency = this.gates.get(dependencyName.value);
+        if (!dependency) {
+          continue;
+        }
+
+        visit(dependency);
+        visited.add(dependencyName.value);
+        ordered.push(dependencyName);
+      }
+    };
+
+    visit(target);
+
+    return ordered;
+  }
+
+  private static detectCycles(graph: ReadonlyMap<string, readonly string[]>): readonly string[][] {
+    let index = 0;
+    const indexMap = new Map<string, number>();
+    const lowLinkMap = new Map<string, number>();
+    const stack: string[] = [];
+    const inStack = new Set<string>();
+    const cycles: string[][] = [];
+
+    const strongConnect = (node: string): void => {
+      indexMap.set(node, index);
+      lowLinkMap.set(node, index);
+      index += 1;
+      stack.push(node);
+      inStack.add(node);
+
+      for (const next of graph.get(node) ?? []) {
+        if (!indexMap.has(next)) {
+          strongConnect(next);
+          lowLinkMap.set(node, Math.min(lowLinkMap.get(node) ?? 0, lowLinkMap.get(next) ?? 0));
+          continue;
+        }
+
+        if (inStack.has(next)) {
+          lowLinkMap.set(node, Math.min(lowLinkMap.get(node) ?? 0, indexMap.get(next) ?? 0));
+        }
+      }
+
+      if ((lowLinkMap.get(node) ?? -1) !== (indexMap.get(node) ?? -1)) {
+        return;
+      }
+
+      const component: string[] = [];
+      let current = '';
+      do {
+        current = stack.pop() ?? '';
+        if (current.length === 0) {
+          break;
+        }
+        inStack.delete(current);
+        component.push(current);
+      } while (current !== node);
+
+      if (component.length > 1) {
+        cycles.push(component.sort());
+        return;
+      }
+
+      const [single] = component;
+      if ((graph.get(single) ?? []).includes(single)) {
+        cycles.push(component);
+      }
+    };
+
+    for (const node of graph.keys()) {
+      if (!indexMap.has(node)) {
+        strongConnect(node);
+      }
+    }
+
+    return Object.freeze(cycles);
+  }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import type { StoryReflectionConfig } from '../values/story-reflection-config.js';
+import type { StoryReflectionFileSystemPort } from '../ports/story-reflection-file-system-port.js';
+import {
+  StoryReflectionResult,
+  type StoryReflectionViolation,
+} from '../values/story-reflection-result.js';
+
+export class StoryReflectionChecker {
+  constructor(private readonly fsPort: StoryReflectionFileSystemPort) {}
+
+  async check(
+    unitId: string,
+    config: StoryReflectionConfig,
+  ): Promise<StoryReflectionResult> {
+    if (!config.enabled) {
+      return StoryReflectionResult.pass();
+    }
+
+    const storyIds = await this.fsPort.listStoryDirectories(unitId);
+
+    if (storyIds.length === 0) {
+      return StoryReflectionResult.pass();
+    }
+
+    const violations: StoryReflectionViolation[] = [];
+    const warnings: StoryReflectionViolation[] = [];
+
+    for (const storyId of storyIds) {
+      for (const mapping of config.mappings) {
+        const { inception: inceptionPath, product: productPath } =
+          mapping.resolve({ unitId, storyId });
+
+        const inceptionExists = await this.fsPort.fileExists(inceptionPath);
+
+        if (!inceptionExists) {
+          continue;
+        }
+
+        const hasAnnotation =
+          await this.fsPort.fileContainsStoryAnnotation(productPath, storyId);
+
+        if (!hasAnnotation) {
+          const violation: StoryReflectionViolation = {
+            storyId,
+            mapping,
+            inceptionPath,
+            productPath,
+          };
+
+          if (mapping.required) {
+            violations.push(violation);
+          } else {
+            warnings.push(violation);
+          }
+        }
+      }
+    }
+
+    return StoryReflectionResult.create({ violations, warnings });
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-definition.ts

@@ -0,0 +1,127 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+import { GateName } from './gate-name.js';
+import { GateStoryAnnotation } from './gate-story-annotation.js';
+import { PhaseLevel } from './phase-level.js';
+
+export interface GateRequirement {
+  readonly path: string;
+  readonly required: boolean;
+}
+
+export interface GateDefinitionCreateArgs {
+  readonly name: GateName;
+  readonly level: PhaseLevel;
+  readonly requires: readonly GateRequirement[];
+  readonly blocks: readonly string[];
+  readonly dependsOn: readonly GateName[];
+  readonly storyAnnotation?: GateStoryAnnotation;
+}
+
+export class InvalidGateDefinitionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidGateDefinitionError';
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const parseRequirement = (raw: unknown): GateRequirement => {
+  if (!isRecord(raw) || typeof raw.path !== 'string' || typeof raw.required !== 'boolean') {
+    throw new InvalidGateDefinitionError('requires の形式が不正です');
+  }
+
+  const path = raw.path.trim();
+  if (path.length === 0) {
+    throw new InvalidGateDefinitionError('requires.path は必須です');
+  }
+
+  return Object.freeze({
+    path,
+    required: raw.required,
+  });
+};
+
+const parseStringArray = (raw: unknown, fieldName: string): readonly string[] => {
+  if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string')) {
+    throw new InvalidGateDefinitionError(`${fieldName} の形式が不正です`);
+  }
+
+  return Object.freeze(raw.map((entry) => entry.trim()));
+};
+
+export class GateDefinition {
+  readonly name: GateName;
+  readonly level: PhaseLevel;
+  readonly requires: readonly GateRequirement[];
+  readonly blocks: readonly string[];
+  readonly dependsOn: readonly GateName[];
+  readonly storyAnnotation?: GateStoryAnnotation;
+
+  private constructor(args: GateDefinitionCreateArgs) {
+    this.name = args.name;
+    this.level = args.level;
+    this.requires = Object.freeze([...args.requires]);
+    this.blocks = Object.freeze([...args.blocks]);
+    this.dependsOn = Object.freeze([...args.dependsOn]);
+    this.storyAnnotation = args.storyAnnotation;
+    Object.freeze(this);
+  }
+
+  static create(args: GateDefinitionCreateArgs): GateDefinition {
+    if (args.storyAnnotation && args.level.value !== 3) {
+      throw new InvalidGateDefinitionError('storyAnnotation は Level 3 のゲートにのみ指定できます');
+    }
+
+    return new GateDefinition(args);
+  }
+
+  static fromRaw(raw: unknown): GateDefinition {
+    if (!isRecord(raw)) {
+      throw new InvalidGateDefinitionError('GateDefinition の形式が不正です');
+    }
+
+    const name = GateName.create(String(raw.name ?? ''));
+    const level = PhaseLevel.create(Number(raw.level));
+    const requires = Array.isArray(raw.requires)
+      ? Object.freeze(raw.requires.map((requirement) => parseRequirement(requirement)))
+      : (() => {
+          throw new InvalidGateDefinitionError('requires の形式が不正です');
+        })();
+    const blocks = parseStringArray(raw.blocks ?? [], 'blocks');
+    const dependsOn = parseStringArray(raw.dependsOn ?? [], 'dependsOn').map((value) =>
+      GateName.create(value),
+    );
+    const storyAnnotation =
+      raw.storyAnnotation === undefined
+        ? undefined
+        : (() => {
+            if (
+              !isRecord(raw.storyAnnotation) ||
+              typeof raw.storyAnnotation.required !== 'boolean' ||
+              typeof raw.storyAnnotation.tag !== 'string'
+            ) {
+              throw new InvalidGateDefinitionError('storyAnnotation の形式が不正です');
+            }
+
+            return GateStoryAnnotation.create({
+              required: raw.storyAnnotation.required,
+              tag: raw.storyAnnotation.tag,
+            });
+          })();
+
+    return GateDefinition.create({
+      name,
+      level,
+      requires,
+      blocks,
+      dependsOn: Object.freeze(dependsOn),
+      storyAnnotation,
+    });
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-name.ts

@@ -0,0 +1,40 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+const GATE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export class InvalidGateNameError extends Error {
+  constructor(value: string) {
+    super(`GateNameが不正です: ${value}`);
+    this.name = 'InvalidGateNameError';
+  }
+}
+
+export class GateName {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): GateName {
+    const normalizedValue = value.trim();
+
+    if (
+      normalizedValue.length === 0 ||
+      !GATE_NAME_PATTERN.test(normalizedValue) ||
+      normalizedValue.endsWith('-')
+    ) {
+      throw new InvalidGateNameError(value);
+    }
+
+    return new GateName(normalizedValue);
+  }
+
+  equals(other: GateName): boolean {
+    return this.value === other.value;
+  }
+}

package/scripts/harness/phase-dependency-model/domain/values/gate-story-annotation.ts

@@ -0,0 +1,39 @@
+/**
+ * @layer domain
+ * @unit phase-dependency-model
+ */
+
+export interface GateStoryAnnotationCreateArgs {
+  readonly required: boolean;
+  readonly tag: string;
+}
+
+export class InvalidGateStoryAnnotationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidGateStoryAnnotationError';
+  }
+}
+
+export class GateStoryAnnotation {
+  readonly required: boolean;
+  readonly tag: string;
+
+  private constructor(args: GateStoryAnnotationCreateArgs) {
+    this.required = args.required;
+    this.tag = args.tag.trim();
+    Object.freeze(this);
+  }
+
+  static create(args: GateStoryAnnotationCreateArgs): GateStoryAnnotation {
+    if (args.tag.trim().length === 0) {
+      throw new InvalidGateStoryAnnotationError('tagは必須です');
+    }
+
+    return new GateStoryAnnotation(args);
+  }
+
+  equals(other: GateStoryAnnotation): boolean {
+    return this.required === other.required && this.tag === other.tag;
+  }
+}