phasegate 0.15.0

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/markdown-plan-document-reader.ts

@@ -0,0 +1,134 @@
+/**
+ * @layer infrastructure
+ * @unit phase-dependency-model
+ */
+
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import type { PlanDocumentReaderPort } from '../../domain/ports/plan-document-reader-port.js';
+import type { PhaseNode } from '../../domain/values/phase-node.js';
+import type { PlanningMode } from '../../domain/values/planning-mode.js';
+import { PlanEvidence } from '../../domain/values/plan-evidence.js';
+
+export interface MarkdownPlanDocumentReaderDeps {
+  readonly rootDir: string;
+}
+
+const QA_SECTION_PATTERN = /^## QA\b/m;
+const QUESTION_PATTERN = /^Q:/gm;
+const ANSWER_PATTERN = /^A:/gm;
+
+export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
+  private readonly rootDir: string;
+
+  constructor(deps: MarkdownPlanDocumentReaderDeps) {
+    this.rootDir = deps.rootDir;
+  }
+
+  async readEvidence(
+    node: PhaseNode,
+    scope: { unitId?: string; storyId?: string },
+    expectedMode: PlanningMode,
+  ): Promise<PlanEvidence> {
+    const planArtifacts = node.planArtifacts();
+
+    if (planArtifacts.length === 0) {
+      return PlanEvidence.create({
+        exists: false,
+        qaComplete: false,
+        planningModeMatch: false,
+      });
+    }
+
+    const artifact = planArtifacts[0];
+    let resolvedPath: string;
+    try {
+      resolvedPath = artifact.resolve(scope);
+    } catch {
+      return PlanEvidence.create({
+        exists: false,
+        qaComplete: false,
+        planningModeMatch: false,
+      });
+    }
+    const absolutePath = path.join(this.rootDir, resolvedPath);
+
+    let content: string;
+    try {
+      content = await readFile(absolutePath, 'utf8');
+    } catch {
+      return PlanEvidence.create({
+        exists: false,
+        qaComplete: false,
+        planningModeMatch: false,
+      });
+    }
+
+    const hasQaSection = QA_SECTION_PATTERN.test(content);
+    const qaComplete = this.isQaComplete(content, hasQaSection, expectedMode);
+    const planningModeMatch = this.detectPlanningModeMatch(
+      content,
+      hasQaSection,
+      expectedMode,
+    );
+
+    return PlanEvidence.create({
+      exists: true,
+      qaComplete,
+      planningModeMatch,
+    });
+  }
+
+  private isQaComplete(
+    content: string,
+    hasQaSection: boolean,
+    expectedMode: PlanningMode,
+  ): boolean {
+    if (expectedMode.requiresAnsweredQa()) {
+      if (!hasQaSection) return false;
+      const qaSection = this.extractQaSection(content);
+      const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
+      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      return questionCount > 0 && questionCount === answerCount;
+    }
+
+    if (expectedMode.requiresQaSection()) {
+      return hasQaSection;
+    }
+
+    return true;
+  }
+
+  private detectPlanningModeMatch(
+    content: string,
+    hasQaSection: boolean,
+    expectedMode: PlanningMode,
+  ): boolean {
+    if (expectedMode.requiresAnsweredQa()) {
+      if (!hasQaSection) return false;
+      const qaSection = this.extractQaSection(content);
+      const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
+      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      return questionCount > 0 && answerCount === questionCount;
+    }
+
+    if (expectedMode.requiresQaSection()) {
+      return hasQaSection;
+    }
+
+    return true;
+  }
+
+  private extractQaSection(content: string): string {
+    const match = content.match(QA_SECTION_PATTERN);
+    if (!match || match.index === undefined) return '';
+
+    const start = match.index;
+    const nextSectionMatch = content.slice(start + match[0].length).match(/^## /m);
+    const end = nextSectionMatch?.index
+      ? start + match[0].length + nextSectionMatch.index
+      : content.length;
+
+    return content.slice(start, end);
+  }
+}

package/scripts/harness/phase-dependency-model/infrastructure/logging/phase-override-audit-logger.ts

@@ -0,0 +1,37 @@
+/**
+ * @layer infrastructure
+ * @unit phase-dependency-model
+ */
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import * as path from 'node:path';
+import type { PhaseAuditLoggerPort } from '../../domain/ports/phase-audit-logger-port.js';
+
+export interface PhaseOverrideAuditLoggerDeps {
+  readonly outputDir: string;
+}
+
+const AUDIT_FILE_NAME = 'phase-override-audit.jsonl';
+
+export class PhaseOverrideAuditLogger implements PhaseAuditLoggerPort {
+  private readonly outputDir: string;
+
+  constructor(deps: PhaseOverrideAuditLoggerDeps) {
+    this.outputDir = deps.outputDir;
+  }
+
+  async record(payload: {
+    scope: { unitId?: string; storyId?: string };
+    targetLevel: 1 | 2 | 3;
+    appliedRules: readonly string[];
+    generatedAt: string;
+    requestedOverride: boolean;
+  }): Promise<void> {
+    await mkdir(this.outputDir, { recursive: true });
+
+    const filePath = path.join(this.outputDir, AUDIT_FILE_NAME);
+    const line = JSON.stringify(payload) + '\n';
+
+    await appendFile(filePath, line, 'utf8');
+  }
+}

package/scripts/harness/phase-dependency-model/presentation/cli/check-phase-gate-command-handler.ts

@@ -0,0 +1,95 @@
+/**
+ * @layer presentation
+ * @unit phase-dependency-model
+ */
+
+import type { CheckPhaseGateUseCase, CheckPhaseGateInput } from '../../application/usecases/check-phase-gate-usecase.js';
+import type { PhaseGateResultDto } from '../../application/dto/phase-gate-result-dto.js';
+
+export interface CheckPhaseGateCommandInput {
+  readonly targetLevel: number;
+  readonly unitId?: string;
+  readonly storyId?: string;
+  readonly json?: boolean;
+}
+
+export interface CheckPhaseGateCommandOutput {
+  readonly exitCode: 0 | 1 | 2;
+  readonly result: PhaseGateResultDto | null;
+  readonly text: string;
+}
+
+export interface CheckPhaseGateCommandHandlerDeps {
+  readonly checkPhaseGateUseCase: Pick<CheckPhaseGateUseCase, 'execute'>;
+}
+
+export class CheckPhaseGateCommandHandler {
+  private readonly useCase: Pick<CheckPhaseGateUseCase, 'execute'>;
+
+  constructor(deps: CheckPhaseGateCommandHandlerDeps) {
+    this.useCase = deps.checkPhaseGateUseCase;
+  }
+
+  async execute(
+    input: CheckPhaseGateCommandInput,
+  ): Promise<Readonly<CheckPhaseGateCommandOutput>> {
+    if (![1, 2, 3].includes(input.targetLevel)) {
+      return Object.freeze({
+        exitCode: 2,
+        result: null,
+        text: `Error: invalid target level ${input.targetLevel}. Must be 1, 2, or 3`,
+      });
+    }
+
+    try {
+      const useCaseInput: CheckPhaseGateInput = {
+        targetLevel: input.targetLevel as 1 | 2 | 3,
+        unitId: input.unitId,
+        storyId: input.storyId,
+      };
+
+      const result = await this.useCase.execute(useCaseInput);
+      const text = input.json
+        ? JSON.stringify(result, null, 2)
+        : this.formatText(result);
+
+      return Object.freeze({
+        exitCode: result.passed ? 0 : 1,
+        result,
+        text,
+      });
+    } catch {
+      return Object.freeze({
+        exitCode: 2,
+        result: null,
+        text: 'Error: phase gate check failed unexpectedly',
+      });
+    }
+  }
+
+  private formatText(result: PhaseGateResultDto): string {
+    const lines: string[] = [];
+    const status = result.passed ? 'PASSED' : 'FAILED';
+    lines.push(`Phase Gate Level ${result.targetLevel}: ${status}`);
+
+    if (result.blockers.length > 0) {
+      lines.push('Blockers:');
+      for (const b of result.blockers) {
+        lines.push(`  - ${b}`);
+      }
+    }
+
+    if (result.warnings.length > 0) {
+      lines.push('Warnings:');
+      for (const w of result.warnings) {
+        lines.push(`  - ${w}`);
+      }
+    }
+
+    if (result.auditRecorded) {
+      lines.push('(audit recorded)');
+    }
+
+    return lines.join('\n');
+  }
+}

package/scripts/harness/phase2-extensions/application/dto/check-doc-freshness-input.ts

@@ -0,0 +1,9 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+export interface CheckDocFreshnessInput {
+  dryRun?: boolean;
+  targetPattern?: string;
+  format?: 'text' | 'json';
+}

package/scripts/harness/phase2-extensions/application/dto/check-doc-freshness-output.ts

@@ -0,0 +1,17 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
+import type { FreshnessCheckResult } from '../../domain/services/freshness-check-service.js';
+
+export interface CheckDocFreshnessOutput {
+  results: FreshnessCheckResult[];
+  summary: {
+    total: number;
+    ok: number;
+    warn: number;
+    error: number;
+  };
+  errors: HarnessErrorContract[];
+}

package/scripts/harness/phase2-extensions/application/dto/generate-e2e-template-input.ts

@@ -0,0 +1,9 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+export interface GenerateE2ETemplateInput {
+  targetPhase: string;
+  outputPath?: string;
+  format?: 'text' | 'json';
+}

package/scripts/harness/phase2-extensions/application/dto/generate-e2e-template-output.ts

@@ -0,0 +1,13 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
+
+export interface GenerateE2ETemplateOutput {
+  templateContent: string;
+  targetPhase: string;
+  generatedAt: string;
+  outputPath: string | null;
+  errors: HarnessErrorContract[];
+}

package/scripts/harness/phase2-extensions/application/dto/validate-doc-pointers-input.ts

@@ -0,0 +1,9 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+export interface ValidateDocPointersInput {
+  targetPattern?: string;
+  includeUrlPointers?: boolean;
+  format?: 'text' | 'json';
+}

package/scripts/harness/phase2-extensions/application/dto/validate-doc-pointers-output.ts

@@ -0,0 +1,25 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
+
+export interface PointerValidationResultDto {
+  documentPath: string;
+  pointerTarget: string;
+  pointerType: 'file-path' | 'url';
+  isResolvable: boolean;
+  errorMessage: string | null;
+}
+
+export interface ValidateDocPointersOutput {
+  results: PointerValidationResultDto[];
+  summary: {
+    totalDocuments: number;
+    totalPointers: number;
+    brokenPointers: number;
+    skippedUrlPointers: number;
+  };
+  passed: boolean;
+  errors: HarnessErrorContract[];
+}

package/scripts/harness/phase2-extensions/application/usecases/check-doc-freshness-usecase.ts

@@ -0,0 +1,68 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { CheckDocFreshnessInput } from '../dto/check-doc-freshness-input.js';
+import type { CheckDocFreshnessOutput } from '../dto/check-doc-freshness-output.js';
+import type { FreshnessConfigPort } from '../../domain/ports/freshness-config-port.js';
+import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
+import type { DocumentAgePort } from '../../domain/ports/document-age-port.js';
+import type { FreshnessCheckService } from '../../domain/services/freshness-check-service.js';
+
+function toHarnessError(message: string) {
+  return {
+    code: 'L4-299',
+    severity: 'error' as const,
+    message,
+    suggestion: '設定または入力を確認してください',
+  };
+}
+
+export class CheckDocFreshnessUseCase {
+  constructor(
+    private readonly freshnessConfigPort: FreshnessConfigPort,
+    private readonly documentScannerPort: DocumentScannerPort,
+    private readonly documentAgePort: DocumentAgePort,
+    private readonly freshnessCheckService: FreshnessCheckService,
+  ) {}
+
+  async execute(input: CheckDocFreshnessInput): Promise<CheckDocFreshnessOutput> {
+    try {
+      const rules = await this.freshnessConfigPort.loadRules();
+      const filteredRules = input.targetPattern
+        ? rules.filter((rule) => rule.documentPattern === input.targetPattern)
+        : rules;
+
+      const results = [];
+
+      for (const rule of filteredRules) {
+        if (!rule.isEnabled()) {
+          continue;
+        }
+
+        const documentPaths = await this.documentScannerPort.scan(rule.documentPattern);
+        for (const documentPath of documentPaths) {
+          const age = await this.documentAgePort.getAge(documentPath);
+          results.push(this.freshnessCheckService.check(rule, age, documentPath));
+        }
+      }
+
+      return {
+        results,
+        summary: {
+          total: results.length,
+          ok: results.filter((result) => result.level === 'ok').length,
+          warn: results.filter((result) => result.level === 'warn').length,
+          error: results.filter((result) => result.level === 'error').length,
+        },
+        errors: [],
+      };
+    } catch (error) {
+      return {
+        results: [],
+        summary: { total: 0, ok: 0, warn: 0, error: 0 },
+        errors: [toHarnessError(error instanceof Error ? error.message : 'unknown error')],
+      };
+    }
+  }
+}

package/scripts/harness/phase2-extensions/application/usecases/generate-e2e-template-usecase.ts

@@ -0,0 +1,39 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import { E2EStrategyTemplate } from '../../domain/value-objects/e2e-strategy-template.js';
+import { Phase2ExtensionsDomainError } from '../../domain/errors/phase2-extensions-domain-error.js';
+import type { GenerateE2ETemplateInput } from '../dto/generate-e2e-template-input.js';
+import type { GenerateE2ETemplateOutput } from '../dto/generate-e2e-template-output.js';
+
+export class GenerateE2ETemplateUseCase {
+  async execute(input: GenerateE2ETemplateInput): Promise<GenerateE2ETemplateOutput> {
+    try {
+      const template = E2EStrategyTemplate.create(input.targetPhase);
+      return {
+        templateContent: template.templateContent,
+        targetPhase: template.targetPhase,
+        generatedAt: template.generatedAt,
+        outputPath: input.outputPath ?? null,
+        errors: [],
+      };
+    } catch (error) {
+      const message = error instanceof Phase2ExtensionsDomainError ? error.message : 'テンプレート生成に失敗しました';
+      return {
+        templateContent: '',
+        targetPhase: input.targetPhase,
+        generatedAt: new Date().toISOString(),
+        outputPath: input.outputPath ?? null,
+        errors: [
+          {
+            code: 'L4-297',
+            severity: 'error',
+            message,
+            suggestion: 'targetPhase を確認してください',
+          },
+        ],
+      };
+    }
+  }
+}

package/scripts/harness/phase2-extensions/application/usecases/validate-doc-pointers-usecase.ts

@@ -0,0 +1,98 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { FreshnessConfigPort } from '../../domain/ports/freshness-config-port.js';
+import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
+import type { PointerExtractorPort } from '../../domain/ports/pointer-extractor-port.js';
+import type { PointerResolutionService } from '../../domain/services/pointer-resolution-service.js';
+import type { ValidateDocPointersInput } from '../dto/validate-doc-pointers-input.js';
+import type { ValidateDocPointersOutput } from '../dto/validate-doc-pointers-output.js';
+
+function toHarnessError(message: string) {
+  return {
+    code: 'L4-298',
+    severity: 'error' as const,
+    message,
+    suggestion: '入力またはポインタ設定を確認してください',
+  };
+}
+
+export class ValidateDocPointersUseCase {
+  constructor(
+    private readonly freshnessConfigPort: FreshnessConfigPort,
+    private readonly documentScannerPort: DocumentScannerPort,
+    private readonly pointerExtractorPort: PointerExtractorPort,
+    private readonly pointerResolutionService: PointerResolutionService,
+  ) {}
+
+  async execute(input: ValidateDocPointersInput): Promise<ValidateDocPointersOutput> {
+    try {
+      const rules = await this.freshnessConfigPort.loadPointerRules();
+      const filteredRules = input.targetPattern
+        ? rules.filter((rule) => rule.documentPattern === input.targetPattern)
+        : rules;
+
+      const results = [];
+      let totalDocuments = 0;
+
+      for (const rule of filteredRules) {
+        const documentPaths = await this.documentScannerPort.scan(rule.documentPattern);
+        totalDocuments += documentPaths.length;
+
+        for (const documentPath of documentPaths) {
+          const pointers = await this.pointerExtractorPort.extract(documentPath);
+          const validationResults = await this.pointerResolutionService.resolve(pointers);
+
+          for (const validationResult of validationResults) {
+            if (validationResult.pointer.isUrl() && !input.includeUrlPointers) {
+              continue;
+            }
+
+            results.push({
+              documentPath,
+              pointerTarget: validationResult.pointer.target,
+              pointerType: validationResult.pointer.type,
+              isResolvable: validationResult.isResolvable,
+              errorMessage: validationResult.errorMessage,
+            });
+          }
+
+          const hasBrokenPointers = validationResults.some((entry) => !entry.isResolvable);
+          if (hasBrokenPointers && !rule.shouldFailOnBroken()) {
+            continue;
+          }
+        }
+      }
+
+      const brokenPointers = results.filter((result) => !result.isResolvable).length;
+      const skippedUrlPointers = results.filter((result) => result.pointerType === 'url').length;
+      const failingRules = filteredRules.filter((rule) => rule.shouldFailOnBroken());
+      const passed = failingRules.length === 0 || brokenPointers === 0;
+
+      return {
+        results,
+        summary: {
+          totalDocuments,
+          totalPointers: results.length,
+          brokenPointers,
+          skippedUrlPointers,
+        },
+        passed,
+        errors: [],
+      };
+    } catch (error) {
+      return {
+        results: [],
+        summary: {
+          totalDocuments: 0,
+          totalPointers: 0,
+          brokenPointers: 0,
+          skippedUrlPointers: 0,
+        },
+        passed: false,
+        errors: [toHarnessError(error instanceof Error ? error.message : 'unknown error')],
+      };
+    }
+  }
+}

package/scripts/harness/phase2-extensions/composition-root.ts

@@ -0,0 +1,52 @@
+/**
+ * @layer composition
+ * @unit phase2-extensions
+ */
+import type { HarnessConfigV2 } from '../config-foundation/domain/harness-config.js';
+import { CheckDocFreshnessUseCase } from './application/usecases/check-doc-freshness-usecase.js';
+import { GenerateE2ETemplateUseCase } from './application/usecases/generate-e2e-template-usecase.js';
+import { ValidateDocPointersUseCase } from './application/usecases/validate-doc-pointers-usecase.js';
+import { FreshnessCheckService } from './domain/services/freshness-check-service.js';
+import { PointerResolutionService } from './domain/services/pointer-resolution-service.js';
+import { FileSystemDocumentScannerAdapter } from './infrastructure/adapters/file-system-document-scanner-adapter.js';
+import { FileSystemPointerResolverAdapter } from './infrastructure/adapters/file-system-pointer-resolver-adapter.js';
+import { GitLogDocumentAgeAdapter } from './infrastructure/adapters/git-log-document-age-adapter.js';
+import { HarnessConfigFreshnessAdapter } from './infrastructure/adapters/harness-config-freshness-adapter.js';
+import { RegexPointerExtractorAdapter } from './infrastructure/adapters/regex-pointer-extractor-adapter.js';
+import { CheckFreshnessHandler } from './presentation/handlers/check-freshness-handler.js';
+import { GenerateE2ETemplateHandler } from './presentation/handlers/generate-e2e-template-handler.js';
+import { ValidatePointersHandler } from './presentation/handlers/validate-pointers-handler.js';
+
+export function buildPhase2Extensions(projectRoot: string, config?: HarnessConfigV2) {
+  const configAdapter = new HarnessConfigFreshnessAdapter(config);
+  const documentScanner = new FileSystemDocumentScannerAdapter(projectRoot);
+  const documentAge = new GitLogDocumentAgeAdapter(projectRoot);
+  const pointerExtractor = new RegexPointerExtractorAdapter(projectRoot);
+  const pointerResolver = new FileSystemPointerResolverAdapter(projectRoot);
+
+  const freshnessCheckService = new FreshnessCheckService();
+  const pointerResolutionService = new PointerResolutionService(pointerResolver);
+
+  const checkDocFreshnessUseCase = new CheckDocFreshnessUseCase(
+    configAdapter,
+    documentScanner,
+    documentAge,
+    freshnessCheckService,
+  );
+  const validateDocPointersUseCase = new ValidateDocPointersUseCase(
+    configAdapter,
+    documentScanner,
+    pointerExtractor,
+    pointerResolutionService,
+  );
+  const generateE2ETemplateUseCase = new GenerateE2ETemplateUseCase();
+
+  return {
+    checkDocFreshnessUseCase,
+    validateDocPointersUseCase,
+    generateE2ETemplateUseCase,
+    checkFreshnessHandler: new CheckFreshnessHandler(checkDocFreshnessUseCase),
+    validatePointersHandler: new ValidatePointersHandler(validateDocPointersUseCase),
+    generateE2ETemplateHandler: new GenerateE2ETemplateHandler(generateE2ETemplateUseCase),
+  };
+}