phasegate 0.15.0

package/scripts/harness/adr-foundation/infrastructure/parsers/regex-adr-frontmatter-parser.ts

@@ -0,0 +1,147 @@
+/**
+ * @layer infrastructure
+ * @unit adr-foundation
+ */
+import type { AdrFrontmatterParserPort } from '../../domain/ports/adr-frontmatter-parser-port.js';
+import { AdrFrontmatter } from '../../domain/value-objects/adr-frontmatter.js';
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+type ParsedYaml = {
+  adr_id?: string;
+  title?: string;
+  status?: string;
+  date?: string;
+  superseded_by?: string;
+  archgate?: {
+    enforced_by?: Array<{
+      validator_id?: string;
+      error_code?: string;
+    }>;
+  };
+};
+
+function parseYamlValue(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseSimpleYaml(raw: string): ParsedYaml {
+  const result: ParsedYaml = {};
+  const lines = raw.split(/\r?\n/);
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!;
+
+    const topMatch = /^(\w[\w_]*):\s*(.*)$/.exec(line);
+    if (!topMatch) {
+      i++;
+      continue;
+    }
+
+    const key = topMatch[1]!;
+    const inlineValue = topMatch[2]!.trim();
+
+    if (key === 'archgate') {
+      const archgate: ParsedYaml['archgate'] = { enforced_by: [] };
+      i++;
+
+      // expect enforced_by:
+      if (i < lines.length && /^\s+enforced_by:\s*$/.test(lines[i]!)) {
+        i++;
+
+        while (i < lines.length) {
+          const entryLine = lines[i]!;
+          const itemMatch = /^\s+-\s+validator_id:\s*(.+)$/.exec(entryLine);
+          if (!itemMatch) break;
+
+          const validatorId = parseYamlValue(itemMatch[1]!);
+          i++;
+
+          if (i < lines.length) {
+            const errorMatch = /^\s+error_code:\s*(.+)$/.exec(lines[i]!);
+            if (errorMatch) {
+              archgate.enforced_by!.push({
+                validator_id: validatorId,
+                error_code: parseYamlValue(errorMatch[1]!),
+              });
+              i++;
+            }
+          }
+        }
+      }
+
+      result.archgate = archgate;
+      continue;
+    }
+
+    if (inlineValue.length > 0) {
+      (result as Record<string, string>)[key] = parseYamlValue(inlineValue);
+    }
+
+    i++;
+  }
+
+  return result;
+}
+
+export class RegexAdrFrontmatterParser implements AdrFrontmatterParserPort {
+  parseFrontmatter(raw: string): AdrFrontmatter {
+    const match = FRONTMATTER_PATTERN.exec(raw);
+    if (!match?.[1]) {
+      throw new Error('YAML frontmatterが見つかりません');
+    }
+
+    const parsed = parseSimpleYaml(match[1]);
+
+    return AdrFrontmatter.create({
+      adr_id: parsed.adr_id,
+      title: parsed.title,
+      status: parsed.status,
+      date: parsed.date,
+      superseded_by: parsed.superseded_by,
+      archgate: parsed.archgate?.enforced_by?.length
+        ? {
+            adr_id: parsed.adr_id,
+            enforced_by: parsed.archgate.enforced_by.map((entry) => ({
+              validator_id: entry.validator_id ?? '',
+              error_code: entry.error_code ?? '',
+            })),
+          }
+        : undefined,
+    });
+  }
+
+  serializeFrontmatter(frontmatter: AdrFrontmatter): string {
+    const primitives = frontmatter.toPrimitives();
+    const lines: string[] = ['---'];
+
+    lines.push(`adr_id: ${primitives.adr_id}`);
+    lines.push(`title: ${primitives.title}`);
+    lines.push(`status: ${primitives.status}`);
+    lines.push(`date: ${primitives.date}`);
+
+    if (primitives.superseded_by) {
+      lines.push(`superseded_by: ${primitives.superseded_by}`);
+    }
+
+    if (primitives.archgate) {
+      lines.push('archgate:');
+      lines.push('  enforced_by:');
+      for (const entry of primitives.archgate.enforced_by) {
+        lines.push(`    - validator_id: ${entry.validator_id}`);
+        lines.push(`      error_code: ${entry.error_code}`);
+      }
+    }
+
+    lines.push('---');
+    return lines.join('\n');
+  }
+}

package/scripts/harness/adr-foundation/infrastructure/repositories/file-system-adr-repository.ts

@@ -0,0 +1,115 @@
+/**
+ * @layer infrastructure
+ * @unit adr-foundation
+ */
+import { readdir, readFile, writeFile, rename, stat } from 'node:fs/promises';
+import * as path from 'node:path';
+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 { AdrId } from '../../domain/value-objects/adr-id.js';
+import type { AdrStatus } from '../../domain/value-objects/adr-status.js';
+
+const TEMPLATE_FILENAME = 'template.md';
+const ADR_FILE_PATTERN = /^[0-9]{3}-[a-z0-9-]+\.md$/;
+
+export class FileSystemAdrRepository implements AdrRepositoryPort {
+  private readonly rootDir: string;
+  private readonly documentParser: AdrDocumentParserPort;
+
+  constructor(rootDir: string, documentParser: AdrDocumentParserPort) {
+    this.rootDir = rootDir;
+    this.documentParser = documentParser;
+  }
+
+  async findById(id: AdrId): Promise<ADR | null> {
+    const allAdrs = await this.loadAll();
+    return allAdrs.find((adr) => adr.id.equals(id)) ?? null;
+  }
+
+  async findByRef(adrRef: string): Promise<ADR | null> {
+    const id = AdrId.create(adrRef);
+    return this.findById(id);
+  }
+
+  async findAll(filters?: {
+    statuses?: AdrStatus[];
+    includeTemplate?: boolean;
+  }): Promise<ADR[]> {
+    const allAdrs = await this.loadAll();
+
+    if (!filters?.statuses?.length) {
+      return allAdrs;
+    }
+
+    return allAdrs.filter((adr) =>
+      filters.statuses!.some((status) => adr.getStatus().equals(status)),
+    );
+  }
+
+  async save(adr: ADR): Promise<void> {
+    const filePath = AdrFilePath.fromAdr(adr.id, adr.getFrontmatter().title);
+    const markdown = this.documentParser.serializeDocument(adr);
+    const absolutePath = path.join(this.rootDir, filePath.value.replace('docs/ADR/', ''));
+
+    const existingFile = await this.findExistingFile(adr.id);
+    if (existingFile) {
+      const existingAbsolutePath = path.join(this.rootDir, existingFile);
+      if (existingAbsolutePath !== absolutePath) {
+        await rename(existingAbsolutePath, absolutePath);
+      }
+    }
+
+    await writeFile(absolutePath, markdown, 'utf8');
+  }
+
+  async exists(id: AdrId): Promise<boolean> {
+    const adr = await this.findById(id);
+    return adr !== null;
+  }
+
+  async nextId(): Promise<AdrId> {
+    const allAdrs = await this.loadAll();
+    if (allAdrs.length === 0) {
+      return AdrId.create('001');
+    }
+
+    const maxNumber = Math.max(...allAdrs.map((adr) => adr.id.toNumber()));
+    const nextNumber = maxNumber + 1;
+    return AdrId.create(String(nextNumber).padStart(3, '0'));
+  }
+
+  private async loadAll(): Promise<ADR[]> {
+    const files = await this.listAdrFiles();
+    const adrs: ADR[] = [];
+    const validationService = new AdrValidationService();
+
+    for (const file of files) {
+      const absolutePath = path.join(this.rootDir, file);
+      const content = await readFile(absolutePath, 'utf8');
+      const document = this.documentParser.parseDocument(content);
+      const adr = ADR.reconstitute(document, validationService);
+      adrs.push(adr);
+    }
+
+    return adrs.sort((a, b) => a.id.compare(b.id));
+  }
+
+  private async listAdrFiles(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.rootDir);
+      return entries
+        .filter((entry) => entry !== TEMPLATE_FILENAME && ADR_FILE_PATTERN.test(entry));
+    } catch {
+      return [];
+    }
+  }
+
+  private async findExistingFile(id: AdrId): Promise<string | null> {
+    const files = await this.listAdrFiles();
+    const prefix = `${id.value}-`;
+    return files.find((f) => f.startsWith(prefix)) ?? null;
+  }
+}

package/scripts/harness/adr-foundation/infrastructure/seeds/initial-adr-definitions.ts

@@ -0,0 +1,161 @@
+/**
+ * @layer infrastructure
+ * @unit adr-foundation
+ */
+import type { SeedAdrDefinition } from '../../application/dto/seed-adr-definition.js';
+
+export const INITIAL_ADR_DEFINITIONS: readonly SeedAdrDefinition[] = [
+  {
+    title: 'Package separation',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'The harness codebase has grown beyond a single-package structure. Build times increase and cross-cutting changes create unnecessary coupling.',
+      decision:
+        'Separate the repository into discrete packages aligned with bounded contexts, each with its own build and test lifecycle.',
+      consequences:
+        'Packages can evolve independently. CI must orchestrate multi-package builds. Shared kernel contracts must be explicitly published.',
+    },
+  },
+  {
+    title: 'Full migration from ESLint to Biome',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'The project currently uses ESLint for linting. Biome offers faster execution and unified formatting with linting in a single tool.',
+      decision:
+        'Migrate all linting and formatting from ESLint and Prettier to Biome as the sole toolchain.',
+      consequences:
+        'Tooling becomes simpler and faster. Custom ESLint rules must be re-implemented as Biome plugins or GritQL patterns.',
+      alternatives:
+        'Keep dual toolchain with ESLint for rules not yet supported by Biome.',
+    },
+  },
+  {
+    title: 'Quality harness owns K1-K13',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Quality indicators K1 through K13 are defined across multiple documents with no single owner enforcing them.',
+      decision:
+        'The quality harness unit owns the enforcement of all K1-K13 indicators, providing validators and gates for each.',
+      consequences:
+        'A single unit is accountable for quality enforcement. Other units must integrate through the harness contract rather than implementing ad-hoc checks.',
+    },
+  },
+  {
+    title: 'FUSE Hooks Engine is out of v1 scope',
+    status: 'Proposed',
+    date: '2026-03-13',
+    body: {
+      context:
+        'The FUSE Hooks Engine provides extensible event-driven hooks but adds significant complexity to the initial delivery.',
+      decision:
+        'Defer the FUSE Hooks Engine to a post-v1 phase. The v1 harness will use direct invocation patterns.',
+      consequences:
+        'Reduced initial scope and risk. Hook-based extensibility will require a migration path when introduced later.',
+      alternatives:
+        'Include a minimal hooks engine in v1 with limited extensibility.',
+    },
+  },
+  {
+    title: 'HarnessError requires fix_example',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Developers receiving harness errors often lack actionable guidance on how to resolve violations.',
+      decision:
+        'Every HarnessError definition must include a fix_example field demonstrating the corrective action.',
+      consequences:
+        'Error definitions are more verbose but significantly more useful. All existing error definitions must be updated to include examples.',
+    },
+  },
+  {
+    title: 'Strict quick mode eligibility',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Quick mode bypasses expensive validators but must not compromise quality gates for critical changes.',
+      decision:
+        'Define strict eligibility criteria for quick mode based on file change scope and affected layers.',
+      consequences:
+        'Quick mode runs faster for eligible changes. Complex cross-layer changes always run the full validator stack.',
+      alternatives:
+        'Allow developers to manually opt into quick mode regardless of change scope.',
+    },
+  },
+  {
+    title: 'Separate config files',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'A single monolithic configuration file makes it difficult to manage unit-specific settings and increases merge conflicts.',
+      decision:
+        'Split configuration into separate files per concern: phasegate.config.json for core settings, with unit-specific overrides.',
+      consequences:
+        'Configuration is modular and easier to maintain. The config loader must implement a merge strategy for layered configs.',
+    },
+  },
+  {
+    title: 'Nyquist integration for truths and artifacts',
+    status: 'Proposed',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Nyquist provides a truth-source registry and artifact tracking system that could centralize harness state management.',
+      decision:
+        'Integrate with Nyquist for truth registration and artifact lifecycle tracking.',
+      consequences:
+        'Harness gains a centralized truth source. A dependency on Nyquist availability is introduced.',
+      alternatives:
+        'Build a standalone truth registry within the harness codebase.',
+    },
+  },
+  {
+    title: 'Artifact-driven state derivation',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Harness state is currently computed on-the-fly, leading to inconsistent results across different invocation points.',
+      decision:
+        'Derive harness state exclusively from persisted artifacts, making state deterministic and reproducible.',
+      consequences:
+        'State becomes auditable and cacheable. All state-changing operations must produce artifacts as their primary output.',
+    },
+  },
+  {
+    title: 'Validator stack detection',
+    status: 'Accepted',
+    date: '2026-03-13',
+    body: {
+      context:
+        'Validators are registered individually, but their execution order and dependencies are not explicitly managed.',
+      decision:
+        'Implement automatic validator stack detection that resolves execution order based on declared dependencies and layer constraints.',
+      consequences:
+        'Validator execution order is deterministic and verifiable. Circular dependencies are detected at registration time.',
+    },
+  },
+  {
+    title: 'Temporary 4-layer definition with return path to 5-layer',
+    status: 'Proposed',
+    date: '2026-03-13',
+    body: {
+      context:
+        'The target architecture defines 5 layers, but the current codebase structure and team familiarity support only 4 layers.',
+      decision:
+        'Adopt a temporary 4-layer definition (domain, application, infrastructure, presentation) with a documented return path to the 5-layer target.',
+      consequences:
+        'Initial implementation is simpler. The migration plan to 5 layers must be maintained and reviewed periodically.',
+      alternatives:
+        'Adopt the full 5-layer structure from the start despite the complexity cost.',
+    },
+  },
+] as const;

package/scripts/harness/adr-foundation/infrastructure/serializers/adr-markdown-serializer.ts

@@ -0,0 +1,41 @@
+/**
+ * @layer infrastructure
+ * @unit adr-foundation
+ */
+import type { ADR } from '../../domain/aggregates/adr.js';
+
+export function toAsciiKebabCase(title: string): string {
+  const slug = title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+
+  return slug.length > 0 ? slug : 'untitled';
+}
+
+export class AdrMarkdownSerializer {
+  serialize(adr: ADR): string {
+    const title = adr.getFrontmatter().title;
+    const sections = adr.getBody().toSectionMap();
+
+    const lines: string[] = [`# ${title}`];
+
+    const canonicalOrder: Array<'Context' | 'Decision' | 'Consequences' | 'Alternatives'> = [
+      'Context',
+      'Decision',
+      'Consequences',
+      'Alternatives',
+    ];
+
+    for (const sectionName of canonicalOrder) {
+      const content = sections[sectionName];
+      if (content !== undefined) {
+        lines.push('', `## ${sectionName}`, '', content);
+      }
+    }
+
+    return lines.join('\n') + '\n';
+  }
+}

package/scripts/harness/adr-foundation/presentation/cli/list-adrs-command-handler.ts

@@ -0,0 +1,78 @@
+/**
+ * @layer presentation
+ * @unit adr-foundation
+ */
+
+import type { ListAdrsUseCase, ListAdrsInput, ListAdrsOutput } from '../../application/usecases/list-adrs-use-case.js';
+
+export interface ListAdrsCommandInput {
+  readonly statuses?: ReadonlyArray<'Proposed' | 'Accepted' | 'Deprecated' | 'Superseded'>;
+  readonly json?: boolean;
+}
+
+export interface ListAdrsCommandOutput {
+  readonly exitCode: 0 | 2;
+  readonly output: ListAdrsOutput | null;
+  readonly text: string;
+}
+
+export interface ListAdrsCommandHandlerDeps {
+  readonly listAdrsUseCase: Pick<ListAdrsUseCase, 'execute'>;
+}
+
+export class ListAdrsCommandHandler {
+  private readonly useCase: Pick<ListAdrsUseCase, 'execute'>;
+
+  constructor(deps: ListAdrsCommandHandlerDeps) {
+    this.useCase = deps.listAdrsUseCase;
+  }
+
+  async execute(
+    input: ListAdrsCommandInput,
+  ): Promise<Readonly<ListAdrsCommandOutput>> {
+    try {
+      const useCaseInput: ListAdrsInput = {
+        statuses: input.statuses as Array<'Proposed' | 'Accepted' | 'Deprecated' | 'Superseded'> | undefined,
+      };
+
+      const output = await this.useCase.execute(useCaseInput);
+      const text = input.json
+        ? JSON.stringify(output, null, 2)
+        : this.formatText(output);
+
+      return Object.freeze({
+        exitCode: 0,
+        output,
+        text,
+      });
+    } catch {
+      return Object.freeze({
+        exitCode: 2,
+        output: null,
+        text: 'Error: failed to list ADRs',
+      });
+    }
+  }
+
+  private formatText(output: ListAdrsOutput): string {
+    const lines: string[] = [];
+    lines.push(`ADR一覧 (${output.summary.total}件)`);
+    lines.push('---');
+
+    for (const item of output.items) {
+      const superseded = item.supersededBy
+        ? ` -> ${item.supersededBy}`
+        : '';
+      lines.push(
+        `${item.adrRef} [${item.status}] ${item.title}${superseded}`,
+      );
+    }
+
+    lines.push('---');
+    lines.push(
+      `Proposed: ${output.summary.proposed}, Accepted: ${output.summary.accepted}, Deprecated: ${output.summary.deprecated}, Superseded: ${output.summary.superseded}`,
+    );
+
+    return lines.join('\n');
+  }
+}

package/scripts/harness/adr-foundation/presentation/cli/validate-adr-command-handler.ts

@@ -0,0 +1,113 @@
+/**
+ * @layer presentation
+ * @unit adr-foundation
+ */
+
+import type { ValidateAllAdrsUseCase, ValidateAllAdrsInput } from '../../application/usecases/validate-all-adrs-use-case.js';
+import type { ValidateAdrFrontmatterUseCase } from '../../application/usecases/validate-adr-frontmatter-use-case.js';
+import type { AdrValidationResultDto } from '../../application/dto/adr-validation-result-dto.js';
+
+export interface ValidateAdrCommandInput {
+  readonly adrRef?: string;
+  readonly all?: boolean;
+  readonly json?: boolean;
+}
+
+export interface ValidateAdrCommandOutput {
+  readonly exitCode: 0 | 1 | 2;
+  readonly results: readonly AdrValidationResultDto[];
+  readonly text: string;
+}
+
+export interface ValidateAdrCommandHandlerDeps {
+  readonly validateAllAdrsUseCase: Pick<ValidateAllAdrsUseCase, 'execute'>;
+  readonly validateAdrFrontmatterUseCase: Pick<ValidateAdrFrontmatterUseCase, 'execute'>;
+}
+
+export class ValidateAdrCommandHandler {
+  private readonly validateAllUseCase: Pick<ValidateAllAdrsUseCase, 'execute'>;
+  private readonly validateOneUseCase: Pick<ValidateAdrFrontmatterUseCase, 'execute'>;
+
+  constructor(deps: ValidateAdrCommandHandlerDeps) {
+    this.validateAllUseCase = deps.validateAllAdrsUseCase;
+    this.validateOneUseCase = deps.validateAdrFrontmatterUseCase;
+  }
+
+  async execute(
+    input: ValidateAdrCommandInput,
+  ): Promise<Readonly<ValidateAdrCommandOutput>> {
+    if (!input.all && !input.adrRef) {
+      return Object.freeze({
+        exitCode: 2,
+        results: Object.freeze([]),
+        text: 'Error: specify --all or <adrRef>',
+      });
+    }
+
+    try {
+      if (input.all) {
+        return await this.executeAll(input);
+      }
+      return await this.executeOne(input.adrRef!, input);
+    } catch {
+      return Object.freeze({
+        exitCode: 2,
+        results: Object.freeze([]),
+        text: 'Error: ADR validation failed unexpectedly',
+      });
+    }
+  }
+
+  private async executeAll(
+    input: ValidateAdrCommandInput,
+  ): Promise<Readonly<ValidateAdrCommandOutput>> {
+    const validateInput: ValidateAllAdrsInput = {};
+    const output = await this.validateAllUseCase.execute(validateInput);
+    const text = input.json
+      ? JSON.stringify({ valid: output.valid, results: output.results }, null, 2)
+      : this.formatResults(output.results, output.valid);
+
+    return Object.freeze({
+      exitCode: output.valid ? 0 : 1,
+      results: output.results,
+      text,
+    });
+  }
+
+  private async executeOne(
+    adrRef: string,
+    input: ValidateAdrCommandInput,
+  ): Promise<Readonly<ValidateAdrCommandOutput>> {
+    const result = await this.validateOneUseCase.execute({ adrRef });
+    const results = Object.freeze([result]);
+    const text = input.json
+      ? JSON.stringify({ valid: result.valid, results }, null, 2)
+      : this.formatResults(results, result.valid);
+
+    return Object.freeze({
+      exitCode: result.valid ? 0 : 1,
+      results,
+      text,
+    });
+  }
+
+  private formatResults(
+    results: readonly AdrValidationResultDto[],
+    valid: boolean,
+  ): string {
+    const lines: string[] = [];
+
+    for (const r of results) {
+      const status = r.valid ? 'PASS' : 'FAIL';
+      lines.push(`[${status}] ${r.adrRef}`);
+      for (const v of r.violations) {
+        lines.push(`  ${v.code}: ${v.message}`);
+      }
+    }
+
+    lines.push('---');
+    lines.push(valid ? 'All ADRs valid' : 'Validation failures detected');
+
+    return lines.join('\n');
+  }
+}

package/scripts/harness/agent-integration/application/dto/handle-post-tool-use-dto.ts

@@ -0,0 +1,24 @@
+/**
+ * @layer application
+ * @unit agent-integration
+ */
+
+import type { SkipReason } from '../../domain/value-objects/hook-translation-result.js';
+
+export interface HandlePostToolUseInput {
+  toolName: string;
+  affectedFilePaths: string[];
+}
+
+export interface CliExecutionResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export interface HandlePostToolUseOutput {
+  executed: boolean;
+  skipReason?: SkipReason;
+  cliResult?: CliExecutionResult;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @layer application
+ * @unit agent-integration
+ */
+
+export interface HandlePreToolUseInput {
+  toolName: string;
+  targetFilePaths: string[];
+}
+
+export interface HandlePreToolUseOutput {
+  shouldBlock: boolean;
+  blockedFilePath?: string;
+  blockReason?: 'PROTECTED_FILE' | 'PHASE_GATE';
+  error?: { message: string };
+  phaseGateBlockers?: string[];
+  nextAction?: string;
+}