phasegate 0.15.0

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "phasegate",
+  "version": "0.15.0",
+  "packageManager": "pnpm@10.30.1",
+  "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junpei-9898/phasegate.git"
+  },
+  "homepage": "https://github.com/junpei-9898/phasegate#readme",
+  "bugs": {
+    "url": "https://github.com/junpei-9898/phasegate/issues"
+  },
+  "keywords": [
+    "quality",
+    "clean-architecture",
+    "ddd",
+    "ai-agent",
+    "governance",
+    "phase-gate",
+    "phasegate"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "files": [
+    "bin/harness",
+    "scripts/harness/**/*.ts",
+    "!scripts/harness/__tests__/**",
+    "scripts/harness/**/*.json",
+    "!scripts/harness/__tests__/**/*.json",
+    "skills/**",
+    "templates/**",
+    "docs/ADR/**",
+    "docs/principles/**",
+    "docs/guide/**",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "harness": "./bin/harness"
+  },
+  "scripts": {
+    "harness": "npx tsx scripts/harness/main.ts",
+    "harness:status": "npx tsx scripts/harness/main.ts harness:status",
+    "harness:enable": "npx tsx scripts/harness/main.ts enable-feature",
+    "harness:disable": "npx tsx scripts/harness/main.ts disable-feature",
+    "harness:check-phase": "npx tsx scripts/harness/main.ts harness:check-phase",
+    "harness:check-ready": "npx tsx scripts/harness/main.ts harness:check-ready",
+    "test": "vitest run --config scripts/harness/__tests__/vitest.config.ts"
+  },
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@types/node": "^25.3.5",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": false
+    }
+  }
+}

package/scripts/harness/adr-foundation/application/dto/adr-detail-dto.ts

@@ -0,0 +1,30 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface ArchgateEntryDto {
+  readonly validatorId: string;
+  readonly errorCode: string;
+}
+
+export interface ArchgateMappingDto {
+  readonly enforcedBy: readonly ArchgateEntryDto[];
+}
+
+export interface AdrBodyDto {
+  readonly context: string;
+  readonly decision: string;
+  readonly consequences: string;
+  readonly alternatives?: string;
+}
+
+export interface AdrDetailDto {
+  readonly adrRef: string;
+  readonly title: string;
+  readonly status: string;
+  readonly date: string;
+  readonly body: AdrBodyDto;
+  readonly archgate?: ArchgateMappingDto;
+  readonly supersededBy?: string;
+  readonly filePath: string;
+}

package/scripts/harness/adr-foundation/application/dto/adr-list-item-dto.ts

@@ -0,0 +1,12 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface AdrListItemDto {
+  readonly adrRef: string;
+  readonly title: string;
+  readonly status: string;
+  readonly date: string;
+  readonly hasArchgate: boolean;
+  readonly supersededBy?: string;
+}

package/scripts/harness/adr-foundation/application/dto/adr-list-summary-dto.ts

@@ -0,0 +1,11 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface AdrListSummaryDto {
+  readonly total: number;
+  readonly proposed: number;
+  readonly accepted: number;
+  readonly deprecated: number;
+  readonly superseded: number;
+}

package/scripts/harness/adr-foundation/application/dto/adr-template-dto.ts

@@ -0,0 +1,21 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { ArchgateMappingDto } from './adr-detail-dto.js';
+
+export interface AdrTemplateFrontmatterDefaultsDto {
+  readonly adrId: string;
+  readonly title: string;
+  readonly status: string;
+  readonly date: string;
+  readonly archgate?: ArchgateMappingDto;
+}
+
+export interface AdrTemplateDto {
+  readonly adrRef: string;
+  readonly filePath: string;
+  readonly recommendedPath: string;
+  readonly markdown: string;
+  readonly frontmatterDefaults: AdrTemplateFrontmatterDefaultsDto;
+}

package/scripts/harness/adr-foundation/application/dto/adr-validation-result-dto.ts

@@ -0,0 +1,27 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface AdrValidationViolationDto {
+  readonly field: string;
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface AdrHarnessError {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly suggestion: string;
+  readonly metadata: {
+    readonly adr_ref?: string;
+    readonly field?: string;
+  };
+}
+
+export interface AdrValidationResultDto {
+  readonly adrRef: string;
+  readonly valid: boolean;
+  readonly violations: readonly AdrValidationViolationDto[];
+  readonly harnessErrors: readonly AdrHarnessError[];
+}

package/scripts/harness/adr-foundation/application/dto/application-errors.ts

@@ -0,0 +1,59 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export class AdrNotFoundApplicationError extends Error {
+  constructor(adrRef: string) {
+    super(`指定されたADRが見つかりません: ${adrRef}`);
+    this.name = 'AdrNotFoundApplicationError';
+  }
+}
+
+export class DuplicateAdrIdApplicationError extends Error {
+  constructor(adrRef: string) {
+    super(`ADR ID が重複しています: ${adrRef}`);
+    this.name = 'DuplicateAdrIdApplicationError';
+  }
+}
+
+export class SupersededTargetNotFoundApplicationError extends Error {
+  constructor(adrRef: string) {
+    super(`superseded_by の参照先ADRが存在しません: ${adrRef}`);
+    this.name = 'SupersededTargetNotFoundApplicationError';
+  }
+}
+
+export class SupersededByRequiredApplicationError extends Error {
+  constructor() {
+    super('supersede 実行時は supersededBy が必須です');
+    this.name = 'SupersededByRequiredApplicationError';
+  }
+}
+
+export class ArchgateSearchConditionRequiredError extends Error {
+  constructor() {
+    super('validatorId または errorCode の少なくとも一方を指定してください');
+    this.name = 'ArchgateSearchConditionRequiredError';
+  }
+}
+
+export class TemplateOutputConflictError extends Error {
+  constructor(filePath: string) {
+    super(`テンプレート出力先が既存ADRと衝突しています: ${filePath}`);
+    this.name = 'TemplateOutputConflictError';
+  }
+}
+
+export class InvalidAdrDateError extends Error {
+  constructor(date: string) {
+    super(`ADR日付は YYYY-MM-DD 形式で指定してください: ${date}`);
+    this.name = 'InvalidAdrDateError';
+  }
+}
+
+export class SeedAdrDefinitionCountError extends Error {
+  constructor(actualCount: number) {
+    super(`初期ADR定義は11件である必要があります: ${actualCount}`);
+    this.name = 'SeedAdrDefinitionCountError';
+  }
+}

package/scripts/harness/adr-foundation/application/dto/archgate-search-result-dto.ts

@@ -0,0 +1,11 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface ArchgateSearchResultDto {
+  readonly validatorId: string;
+  readonly errorCode: string;
+  readonly adrRef: string;
+  readonly title: string;
+  readonly status: string;
+}

package/scripts/harness/adr-foundation/application/dto/change-adr-status-command.ts

@@ -0,0 +1,9 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface ChangeAdrStatusCommand {
+  readonly adrRef: string;
+  readonly action: 'approve' | 'deprecate' | 'supersede' | 'repropose';
+  readonly supersededBy?: string;
+}

package/scripts/harness/adr-foundation/application/dto/seed-adr-definition.ts

@@ -0,0 +1,21 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+export interface SeedAdrDefinition {
+  readonly title: string;
+  readonly status: 'Proposed' | 'Accepted' | 'Deprecated' | 'Superseded';
+  readonly date: string;
+  readonly body: {
+    readonly context: string;
+    readonly decision: string;
+    readonly consequences: string;
+    readonly alternatives?: string;
+  };
+  readonly archgate?: {
+    readonly enforcedBy: ReadonlyArray<{
+      readonly validatorId: string;
+      readonly errorCode: string;
+    }>;
+  };
+}

package/scripts/harness/adr-foundation/application/mappers/adr-to-detail-dto-mapper.ts

@@ -0,0 +1,41 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { ADR } from '../../domain/aggregates/adr.js';
+import { AdrFilePath } from '../../domain/value-objects/adr-file-path.js';
+import type { AdrDetailDto } from '../dto/adr-detail-dto.js';
+
+export function toAdrDetailDto(adr: ADR): Readonly<AdrDetailDto> {
+  const frontmatter = adr.getFrontmatter();
+  const body = adr.getBody();
+  const archgate = adr.getArchgate();
+
+  return Object.freeze({
+    adrRef: adr.toAdrRef(),
+    title: frontmatter.title,
+    status: frontmatter.status.value,
+    date: frontmatter.date,
+    body: Object.freeze({
+      context: body.context,
+      decision: body.decision,
+      consequences: body.consequences,
+      alternatives: body.alternatives,
+    }),
+    archgate:
+      archgate === undefined
+        ? undefined
+        : Object.freeze({
+            enforcedBy: Object.freeze(
+              archgate.enforcedBy.map((entry) =>
+                Object.freeze({
+                  validatorId: entry.validatorId,
+                  errorCode: entry.errorCode,
+                })
+              )
+            ),
+          }),
+    supersededBy: frontmatter.superseded_by,
+    filePath: AdrFilePath.fromAdr(adr.id, frontmatter.title).toString(),
+  });
+}

package/scripts/harness/adr-foundation/application/mappers/adr-to-list-item-dto-mapper.ts

@@ -0,0 +1,19 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { ADR } from '../../domain/aggregates/adr.js';
+import type { AdrListItemDto } from '../dto/adr-list-item-dto.js';
+
+export function toAdrListItemDto(adr: ADR): Readonly<AdrListItemDto> {
+  const frontmatter = adr.getFrontmatter();
+
+  return Object.freeze({
+    adrRef: adr.toAdrRef(),
+    title: frontmatter.title,
+    status: frontmatter.status.value,
+    date: frontmatter.date,
+    hasArchgate: adr.getArchgate() !== undefined,
+    supersededBy: frontmatter.superseded_by,
+  });
+}

package/scripts/harness/adr-foundation/application/mappers/adr-validation-to-harness-error-mapper.ts

@@ -0,0 +1,31 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type {
+  AdrHarnessError,
+  AdrValidationResultDto,
+} from '../dto/adr-validation-result-dto.js';
+
+export function toHarnessErrors(
+  validationResult: AdrValidationResultDto,
+): ReadonlyArray<AdrHarnessError> {
+  if (validationResult.valid || validationResult.violations.length === 0) {
+    return Object.freeze([]);
+  }
+
+  return Object.freeze(
+    validationResult.violations.map((violation) =>
+      Object.freeze({
+        code: violation.code,
+        severity: 'error' as const,
+        message: violation.message,
+        suggestion: `${violation.field} を確認してください`,
+        metadata: Object.freeze({
+          adr_ref: validationResult.adrRef,
+          field: violation.field,
+        }),
+      })
+    )
+  );
+}

package/scripts/harness/adr-foundation/application/usecases/change-adr-status-use-case.ts

@@ -0,0 +1,67 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import { AdrId } from '../../domain/value-objects/adr-id.js';
+import type { ChangeAdrStatusCommand } from '../dto/change-adr-status-command.js';
+import {
+  AdrNotFoundApplicationError,
+  SupersededByRequiredApplicationError,
+  SupersededTargetNotFoundApplicationError,
+} from '../dto/application-errors.js';
+
+export interface ChangeAdrStatusOutput {
+  readonly adrRef: string;
+  readonly previousStatus: string;
+  readonly currentStatus: string;
+  readonly supersededBy?: string;
+}
+
+export class ChangeAdrStatusUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(input: ChangeAdrStatusCommand): Promise<Readonly<ChangeAdrStatusOutput>> {
+    const adr = await this.adrRepository.findByRef(input.adrRef);
+    if (!adr) {
+      throw new AdrNotFoundApplicationError(input.adrRef);
+    }
+
+    const previousStatus = adr.getStatus().value;
+    const nextAdr =
+      input.action === 'approve'
+        ? adr.approve()
+        : input.action === 'deprecate'
+          ? adr.deprecate()
+          : input.action === 'repropose'
+            ? adr.repropose()
+            : await this.supersede(adr, input.supersededBy);
+
+    await this.adrRepository.save(nextAdr);
+
+    return Object.freeze({
+      adrRef: nextAdr.toAdrRef(),
+      previousStatus,
+      currentStatus: nextAdr.getStatus().value,
+      supersededBy: nextAdr.getFrontmatter().superseded_by,
+    });
+  }
+
+  private async supersede(
+    adr: Awaited<ReturnType<AdrRepositoryPort['findByRef']>> extends infer T
+      ? Exclude<T, null>
+      : never,
+    supersededBy: string | undefined,
+  ) {
+    if (!supersededBy) {
+      throw new SupersededByRequiredApplicationError();
+    }
+
+    const nextAdrId = AdrId.fromAdrRef(supersededBy);
+    if (!(await this.adrRepository.exists(nextAdrId))) {
+      throw new SupersededTargetNotFoundApplicationError(supersededBy);
+    }
+
+    return adr.supersede(nextAdrId);
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/create-adr-template-use-case.ts

@@ -0,0 +1,97 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import { ADR } from '../../domain/aggregates/adr.js';
+import type { AdrDocumentParserPort } from '../../domain/ports/adr-document-parser-port.js';
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import { AdrValidationService } from '../../domain/services/adr-validation-service.js';
+import { AdrFilePath } from '../../domain/value-objects/adr-file-path.js';
+import type { AdrTemplateDto } from '../dto/adr-template-dto.js';
+import {
+  InvalidAdrDateError,
+  TemplateOutputConflictError,
+} from '../dto/application-errors.js';
+
+const DATE_PATTERN = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+export interface CreateAdrTemplateInput {
+  readonly title?: string;
+  readonly date?: string;
+  readonly status?: 'Proposed' | 'Accepted';
+  readonly includeArchgateExample?: boolean;
+}
+
+export class CreateAdrTemplateUseCase {
+  constructor(
+    private readonly adrRepository: AdrRepositoryPort,
+    private readonly documentParser: AdrDocumentParserPort,
+  ) {}
+
+  async execute(input: CreateAdrTemplateInput): Promise<Readonly<AdrTemplateDto>> {
+    const adrId = await this.adrRepository.nextId();
+    const title = input.title?.trim() || 'Short decision title';
+    const status = input.status ?? 'Proposed';
+    const date = input.date ?? new Date().toISOString().slice(0, 10);
+
+    if (!DATE_PATTERN.test(date)) {
+      throw new InvalidAdrDateError(date);
+    }
+
+    const filePath = AdrFilePath.fromAdr(adrId, title).toString();
+    if (await this.adrRepository.exists(adrId)) {
+      throw new TemplateOutputConflictError(filePath);
+    }
+
+    const adr = ADR.create(
+      {
+        adr_id: adrId.value,
+        title,
+        status,
+        date,
+        archgate: input.includeArchgateExample
+          ? {
+              adr_id: adrId.value,
+              enforced_by: [{ validator_id: 'phase-gate', error_code: 'L1-001' }],
+            }
+          : undefined,
+      },
+      {
+        context: 'Context',
+        decision: 'Decision',
+        consequences: 'Consequences',
+        alternatives: 'Alternatives',
+      },
+      new AdrValidationService(),
+    );
+
+    const markdown = this.documentParser.serializeDocument(adr);
+    const archgate = adr.getArchgate();
+
+    return Object.freeze({
+      adrRef: adr.toAdrRef(),
+      filePath,
+      recommendedPath: filePath,
+      markdown,
+      frontmatterDefaults: Object.freeze({
+        adrId: adrId.value,
+        title,
+        status,
+        date,
+        archgate:
+          archgate === undefined
+            ? undefined
+            : Object.freeze({
+                enforcedBy: Object.freeze(
+                  archgate.enforcedBy.map((entry) =>
+                    Object.freeze({
+                      validatorId: entry.validatorId,
+                      errorCode: entry.errorCode,
+                    })
+                  )
+                ),
+              }),
+      }),
+    });
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/get-adr-by-ref-use-case.ts

@@ -0,0 +1,26 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { AdrDetailDto } from '../dto/adr-detail-dto.js';
+import { AdrNotFoundApplicationError } from '../dto/application-errors.js';
+import { toAdrDetailDto } from '../mappers/adr-to-detail-dto-mapper.js';
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+
+export interface GetAdrByRefInput {
+  readonly adrRef: string;
+}
+
+export class GetAdrByRefUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(input: GetAdrByRefInput): Promise<Readonly<AdrDetailDto>> {
+    const adr = await this.adrRepository.findByRef(input.adrRef);
+
+    if (!adr) {
+      throw new AdrNotFoundApplicationError(input.adrRef);
+    }
+
+    return toAdrDetailDto(adr);
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/list-adrs-use-case.ts

@@ -0,0 +1,39 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import { AdrStatus } from '../../domain/value-objects/adr-status.js';
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import type { AdrListItemDto } from '../dto/adr-list-item-dto.js';
+import type { AdrListSummaryDto } from '../dto/adr-list-summary-dto.js';
+import { toAdrListItemDto } from '../mappers/adr-to-list-item-dto-mapper.js';
+
+export interface ListAdrsInput {
+  readonly statuses?: Array<'Proposed' | 'Accepted' | 'Deprecated' | 'Superseded'>;
+}
+
+export interface ListAdrsOutput {
+  readonly items: readonly AdrListItemDto[];
+  readonly summary: AdrListSummaryDto;
+}
+
+export class ListAdrsUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(input: ListAdrsInput): Promise<Readonly<ListAdrsOutput>> {
+    const statuses = input.statuses?.map((status) => AdrStatus.create(status));
+    const adrs = await this.adrRepository.findAll({ statuses });
+    const items = Object.freeze(adrs.map((adr) => toAdrListItemDto(adr)));
+
+    return Object.freeze({
+      items,
+      summary: Object.freeze({
+        total: items.length,
+        proposed: items.filter((item) => item.status === 'Proposed').length,
+        accepted: items.filter((item) => item.status === 'Accepted').length,
+        deprecated: items.filter((item) => item.status === 'Deprecated').length,
+        superseded: items.filter((item) => item.status === 'Superseded').length,
+      }),
+    });
+  }
+}

package/scripts/harness/adr-foundation/application/usecases/search-archgate-mappings-use-case.ts

@@ -0,0 +1,55 @@
+/**
+ * @layer application
+ * @unit adr-foundation
+ */
+import type { AdrRepositoryPort } from '../../domain/ports/adr-repository-port.js';
+import type { ArchgateSearchResultDto } from '../dto/archgate-search-result-dto.js';
+import { ArchgateSearchConditionRequiredError } from '../dto/application-errors.js';
+
+export interface SearchArchgateMappingsInput {
+  readonly validatorId?: string;
+  readonly errorCode?: string;
+}
+
+export class SearchArchgateMappingsUseCase {
+  constructor(private readonly adrRepository: AdrRepositoryPort) {}
+
+  async execute(
+    input: SearchArchgateMappingsInput,
+  ): Promise<ReadonlyArray<ArchgateSearchResultDto>> {
+    if (!input.validatorId && !input.errorCode) {
+      throw new ArchgateSearchConditionRequiredError();
+    }
+
+    const adrs = await this.adrRepository.findAll();
+    const results: ArchgateSearchResultDto[] = [];
+
+    for (const adr of adrs) {
+      const archgate = adr.getArchgate();
+      if (!archgate) {
+        continue;
+      }
+
+      for (const entry of archgate.enforcedBy) {
+        const matchesValidator =
+          input.validatorId === undefined || entry.matchesValidatorId(input.validatorId);
+        const matchesErrorCode =
+          input.errorCode === undefined || entry.matchesErrorCode(input.errorCode);
+
+        if (matchesValidator && matchesErrorCode) {
+          results.push(
+            Object.freeze({
+              validatorId: entry.validatorId,
+              errorCode: entry.errorCode,
+              adrRef: adr.toAdrRef(),
+              title: adr.getFrontmatter().title,
+              status: adr.getStatus().value,
+            })
+          );
+        }
+      }
+    }
+
+    return Object.freeze(results);
+  }
+}