phasegate 0.44.0 → 0.63.0

package/scripts/harness/agent-integration/presentation/phasegate-status-context.ts

@@ -0,0 +1,299 @@
+/**
+ * @layer presentation
+ * @unit agent-integration
+ *
+ * Phasegate 状態を context 文字列として組み立てる共有ヘルパー。
+ * SessionStart / UserPromptSubmit hook が共通で使用する。
+ *
+ * 副作用: phasegate.config.json の読み込み / docs/product/construction/ の走査のみ。
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+export interface PhasegateConfig {
+  protectedFiles?: {
+    patterns?: string[];
+    exclude?: string[];
+  };
+  project?: {
+    paths?: {
+      docs?: {
+        construction?: string;
+      };
+    };
+  };
+}
+
+export interface PhasegateStatus {
+  configFound: boolean;
+  protectedPatterns: readonly string[];
+  blockedUnits: readonly string[];
+}
+
+export type ViolationType = 'protected_file' | 'phase_gate';
+
+export interface RecentViolation {
+  readonly type: ViolationType;
+  readonly filePath: string;
+  readonly detail: string;
+}
+
+const DEFAULT_PROTECTED_PATTERNS = [
+  'biome.json',
+  '.biome.json',
+  'tsconfig.json',
+  'package.json',
+  'package-lock.json',
+] as const;
+
+export async function findConfigPath(startDir: string): Promise<string | null> {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, 'phasegate.config.json');
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  }
+}
+
+async function loadConfig(configPath: string): Promise<PhasegateConfig> {
+  try {
+    const raw = await fs.readFile(configPath, 'utf8');
+    return JSON.parse(raw) as PhasegateConfig;
+  } catch {
+    return {};
+  }
+}
+
+function computeProtectedPatterns(config: PhasegateConfig): string[] {
+  const additional = config.protectedFiles?.patterns ?? [];
+  const exclude = new Set(config.protectedFiles?.exclude ?? []);
+  const base = DEFAULT_PROTECTED_PATTERNS.filter((p) => !exclude.has(p));
+  return [...base, ...additional];
+}
+
+async function findBlockedUnits(projectRoot: string, config: PhasegateConfig): Promise<string[]> {
+  const constructionDir = config.project?.paths?.docs?.construction
+    ?? path.join('docs', 'product', 'construction');
+  const absConstructionDir = path.isAbsolute(constructionDir)
+    ? constructionDir
+    : path.join(projectRoot, constructionDir);
+
+  try {
+    await fs.access(absConstructionDir);
+  } catch {
+    return [];
+  }
+
+  let unitDirs: string[];
+  try {
+    const entries = await fs.readdir(absConstructionDir, { withFileTypes: true });
+    unitDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+
+  const blocked: string[] = [];
+  for (const unit of unitDirs) {
+    const unitDir = path.join(absConstructionDir, unit);
+    const hasLogicalDesign = await fs.access(path.join(unitDir, 'logical_design.md')).then(() => true).catch(() => false);
+    const hasDomainModel = await fs.access(path.join(unitDir, 'domain_model.md')).then(() => true).catch(() => false);
+    if (!hasLogicalDesign || !hasDomainModel) {
+      const missing: string[] = [];
+      if (!hasLogicalDesign) missing.push('logical_design.md');
+      if (!hasDomainModel) missing.push('domain_model.md');
+      blocked.push(`${unit} (missing: ${missing.join(', ')})`);
+    }
+  }
+  return blocked;
+}
+
+export async function collectPhasegateStatus(cwd: string): Promise<PhasegateStatus> {
+  const configPath = await findConfigPath(cwd);
+  const configFound = configPath !== null;
+  const config: PhasegateConfig = configFound ? await loadConfig(configPath) : {};
+  const projectRoot = configFound ? path.dirname(configPath) : cwd;
+
+  const protectedPatterns = computeProtectedPatterns(config);
+  const blockedUnits = await findBlockedUnits(projectRoot, config);
+
+  return { configFound, protectedPatterns, blockedUnits };
+}
+
+/**
+ * `git diff --name-only HEAD` で working tree + staged の変更ファイル一覧を取得する。
+ * git 未初期化 / gitコマンド無しの場合は空配列を返す。
+ */
+async function getChangedFiles(projectRoot: string): Promise<string[]> {
+  try {
+    const { stdout } = await execAsync('git diff --name-only HEAD', {
+      cwd: projectRoot,
+      timeout: 5000,
+    });
+    return stdout.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function matchesProtectedPattern(filePath: string, pattern: string): boolean {
+  if (filePath === '') return false;
+  if (pattern === filePath) return true;
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '__DOUBLE_STAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__DOUBLE_STAR__/g, '.*')
+    .replace(/\?/g, '[^/]');
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(filePath) || regex.test(path.basename(filePath));
+}
+
+/**
+ * 現在の working tree (git diff HEAD) をスキャンし、保護ファイル違反 /
+ * 既知の phase-gate ブロック Unit への書き込みを列挙する。
+ *
+ * ISSUE-013 Wave 3 / C-6 (軽量版): Codex のネイティブ apply_patch など hook を
+ * バイパスする経路で起きた違反を、次ターン UserPromptSubmit で遅延検知する。
+ */
+export async function collectRecentViolations(
+  projectRoot: string,
+  status: PhasegateStatus,
+): Promise<RecentViolation[]> {
+  const changedFiles = await getChangedFiles(projectRoot);
+  if (changedFiles.length === 0) return [];
+
+  const violations: RecentViolation[] = [];
+  const seen = new Set<string>();
+
+  const blockedUnitNames = status.blockedUnits.map((entry) => entry.split(' ')[0]);
+
+  for (const file of changedFiles) {
+    // 保護ファイルチェック
+    for (const pattern of status.protectedPatterns) {
+      if (matchesProtectedPattern(file, pattern)) {
+        const key = `protected:${file}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          violations.push({
+            type: 'protected_file',
+            filePath: file,
+            detail: `matched pattern \`${pattern}\``,
+          });
+        }
+        break;
+      }
+    }
+
+    // 簡易 phase-gate チェック: 変更ファイルのパスに blocked unit 名が含まれるか
+    for (const unitName of blockedUnitNames) {
+      if (unitName.length === 0) continue;
+      if (file.includes(`/${unitName}/`) || file.startsWith(`${unitName}/`)) {
+        const key = `phase_gate:${file}:${unitName}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          violations.push({
+            type: 'phase_gate',
+            filePath: file,
+            detail: `within blocked unit \`${unitName}\``,
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  return violations;
+}
+
+export function buildSessionStartContext(status: PhasegateStatus): string {
+  const lines: string[] = [
+    '# Phasegate status (auto-injected by SessionStart hook)',
+    '',
+    'This project uses Phasegate for AIDLC quality enforcement. Follow these rules:',
+    '',
+    '- Do NOT write to protected files without going through `/quick-implementor` skill.',
+    '- Do NOT create/structurally modify source files under units listed as "blocked" below — the required design docs (logical_design.md / domain_model.md) are missing, and pre-tool-use hooks will block writes.',
+    '- Prefer the native `apply_patch` tool for edits, BUT note that Codex\'s apply_patch bypasses pre-edit hooks. Violations surface at pre-commit time.',
+    '',
+  ];
+
+  if (!status.configFound) {
+    lines.push('_(phasegate.config.json not found — using default patterns.)_');
+    lines.push('');
+  }
+
+  lines.push('## Protected files (pre-tool-use blocks writes to these)');
+  if (status.protectedPatterns.length === 0) {
+    lines.push('- (none)');
+  } else {
+    for (const p of status.protectedPatterns) {
+      lines.push(`- \`${p}\``);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Units currently blocked by phase-gate');
+  if (status.blockedUnits.length === 0) {
+    lines.push('- (none — all units have required design docs)');
+  } else {
+    for (const u of status.blockedUnits) {
+      lines.push(`- ${u}`);
+    }
+  }
+  lines.push('');
+  lines.push('If you attempt to write to a blocked unit, your edit will be rejected. Use the `/story-implementor` skill (Phase 1 planning first) to create the required design docs.');
+
+  return lines.join('\n');
+}
+
+export function buildUserPromptSubmitContext(
+  status: PhasegateStatus,
+  violations: readonly RecentViolation[] = [],
+): string {
+  // UserPromptSubmit は毎ターン発火するため、簡潔に最新状態のみを通知する。
+  // SessionStart で既に運用ルールは注入済みの前提。
+  const lines: string[] = [
+    '# Phasegate status refresh',
+    '',
+    `- Protected files (${status.protectedPatterns.length}): ${
+      status.protectedPatterns.length === 0
+        ? '(none)'
+        : status.protectedPatterns.map((p) => `\`${p}\``).join(', ')
+    }`,
+  ];
+
+  if (status.blockedUnits.length === 0) {
+    lines.push('- Phase-gate: all units unlocked (no missing logical_design.md / domain_model.md)');
+  } else {
+    lines.push(`- Phase-gate: ${status.blockedUnits.length} unit(s) currently blocked — writes will be rejected:`);
+    for (const u of status.blockedUnits) {
+      lines.push(`  - ${u}`);
+    }
+    lines.push('  Use `/story-implementor` to create the missing design docs.');
+  }
+
+  if (violations.length > 0) {
+    lines.push('');
+    lines.push(`## ⚠️ Phasegate violations detected in current working tree (${violations.length})`);
+    lines.push('');
+    lines.push('These changes violate Phasegate rules and WILL be blocked at pre-commit time. Native `apply_patch` edits bypass pre-edit hooks, so this turn-boundary check is the only early warning. Consider reverting with `git checkout <file>` or `git restore <file>` if unintended.');
+    lines.push('');
+    for (const v of violations) {
+      const label = v.type === 'protected_file' ? 'PROTECTED FILE' : 'PHASE-GATE';
+      lines.push(`- [${label}] \`${v.filePath}\` — ${v.detail}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/scripts/harness/agent-integration/presentation/session-start-hook.ts

@@ -0,0 +1,54 @@
+/**
+ * @layer presentation
+ * @unit agent-integration
+ *
+ * SessionStart Hook Adapter (ISSUE-013 Wave 3 / C-4)
+ *
+ * Codex CLI のセッション開始時に phase-gate 状態 (運用ルール + 保護ファイル一覧 +
+ * ブロック中 Unit) を `hookSpecificOutput.additionalContext` として注入する。
+ *
+ * 出力スキーマ (Codex 公式):
+ *   {
+ *     "hookSpecificOutput": {
+ *       "hookEventName": "SessionStart",
+ *       "additionalContext": "<developer context を string で>"
+ *     }
+ *   }
+ */
+
+import { buildSessionStartContext, collectPhasegateStatus } from './phasegate-status-context.js';
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main(): Promise<void> {
+  try {
+    await readStdin();
+  } catch {
+    // stdin が無くても続行
+  }
+
+  const status = await collectPhasegateStatus(process.cwd());
+  const additionalContext = buildSessionStartContext(status);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+main().catch((error) => {
+  process.stderr.write(`SessionStart hook error: ${String(error)}\n`);
+  // SessionStart で失敗してもセッション継続できるよう exit 0
+  process.exit(0);
+});

package/scripts/harness/agent-integration/presentation/user-prompt-submit-hook.ts

@@ -0,0 +1,70 @@
+/**
+ * @layer presentation
+ * @unit agent-integration
+ *
+ * UserPromptSubmit Hook Adapter (ISSUE-013 Wave 3 / C-5)
+ *
+ * Codex CLI の UserPromptSubmit 時 (ユーザーが prompt を送信する毎) に、
+ * 最新の phase-gate 状態を簡潔に `hookSpecificOutput.additionalContext` として注入する。
+ *
+ * SessionStart と異なり毎ターン発火するため、運用ルールの再掲は省いて
+ * 「現在の保護ファイル数」「ブロック中 Unit 数と内訳」のみを通知する。
+ * ルール本体は SessionStart hook で既に injection 済みの前提。
+ *
+ * 出力スキーマ (Codex 公式):
+ *   {
+ *     "hookSpecificOutput": {
+ *       "hookEventName": "UserPromptSubmit",
+ *       "additionalContext": "<developer context を string で>"
+ *     }
+ *   }
+ */
+
+import * as path from 'node:path';
+import {
+  buildUserPromptSubmitContext,
+  collectPhasegateStatus,
+  collectRecentViolations,
+  findConfigPath,
+} from './phasegate-status-context.js';
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main(): Promise<void> {
+  try {
+    await readStdin();
+  } catch {
+    // stdin が無くても続行
+  }
+
+  const cwd = process.cwd();
+  const status = await collectPhasegateStatus(cwd);
+  // 違反検知の起点は config が見つかったディレクトリ (= project root)。
+  // config が無ければ cwd をそのまま使う。
+  const configPath = await findConfigPath(cwd);
+  const projectRoot = configPath !== null ? path.dirname(configPath) : cwd;
+  const violations = await collectRecentViolations(projectRoot, status);
+  const additionalContext = buildUserPromptSubmitContext(status, violations);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+main().catch((error) => {
+  process.stderr.write(`UserPromptSubmit hook error: ${String(error)}\n`);
+  // UserPromptSubmit で失敗してもターン継続できるよう exit 0
+  process.exit(0);
+});

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v2.schema.json

@@ -153,6 +153,21 @@
             "type": "string"
           },
           "uniqueItems": true
+        },
+        "fullModeRequiredWhen": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mixedCategories": {
+              "type": "boolean"
+            },
+            "newDomainFile": {
+              "type": "boolean"
+            },
+            "apiContractChange": {
+              "type": "boolean"
+            }
+          }
         }
       }
     },

package/scripts/harness/integrations/pre-commit.ts

@@ -3,8 +3,9 @@
  * @layer presentation
  *
  * Pre-commit CLI entry.
- * Runs L2 validators (phase-gate / metadata / test-quality) against staged
- * TypeScript files. Invoked from `.husky/pre-commit` or `npx phasegate pre-commit`.
+ * Runs L2 validators against staged TypeScript files AND design-document
+ * metadata checks against staged Markdown files. Invoked from `.husky/pre-commit`
+ * or `npx phasegate pre-commit`.
  *
  * Exit codes:
  *   0 = pass (or nothing to check)
@@ -17,6 +18,8 @@ import { createValidatorSystemModule } from '../validator-system/composition-roo
 import { HumanValidationResultFormatter } from '../validator-system/presentation/formatters/human-validation-result-formatter.js';
 import type { AggregatedValidationReport } from '../validator-system/application/dto/aggregated-validation-report.js';
 import type { ValidationResultContract } from '../validator-system/application/dto/validation-result-contract.js';
+import { createTraceabilityModelModule } from '../traceability-model/composition-root.js';
+import type { ValidateMetadataCommandOutput } from '../traceability-model/presentation/cli/validate-metadata-command-handler.js';
 
 const GREEN = '\x1b[32m';
 const RED = '\x1b[31m';
@@ -24,6 +27,48 @@ const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 
+const TS_EXTENSION = '.ts';
+const MD_EXTENSION = '.md';
+const TEST_FILE_SUFFIXES = Object.freeze([
+  '.test.ts',
+  '.test.tsx',
+  '.spec.ts',
+  '.spec.tsx',
+]);
+
+function isTestFile(path: string): boolean {
+  return TEST_FILE_SUFFIXES.some((suffix) => path.endsWith(suffix));
+}
+
+interface RunL2Input {
+  readonly targetPaths: readonly string[];
+  readonly unitName: string;
+  readonly currentPhase: string;
+}
+
+interface RunL2UseCaseLike {
+  execute(input: RunL2Input): Promise<readonly ValidationResultContract[]>;
+}
+
+interface ValidateMetadataInput {
+  readonly filePaths: readonly string[];
+  readonly json?: boolean;
+}
+
+interface ValidateMetadataHandlerLike {
+  execute(input: ValidateMetadataInput): Promise<ValidateMetadataCommandOutput>;
+}
+
+export interface PreCommitDeps {
+  readonly runL2ValidatorsUseCase: RunL2UseCaseLike;
+  readonly validateMetadataCommandHandler: ValidateMetadataHandlerLike;
+}
+
+export interface PreCommitResult {
+  readonly exitCode: 0 | 1 | 2;
+  readonly stdout: string;
+}
+
 function getStagedFiles(): string[] {
   try {
     const output = execSync('git diff --cached --name-only --diff-filter=ACM', {
@@ -39,7 +84,9 @@ function getStagedFiles(): string[] {
   }
 }
 
-function buildReport(results: readonly ValidationResultContract[]): AggregatedValidationReport {
+function buildReport(
+  results: readonly ValidationResultContract[],
+): AggregatedValidationReport {
   const passed = results.filter((r) => r.passed && !r.skipped).length;
   const failed = results.filter((r) => !r.passed && !r.skipped).length;
   const skipped = results.filter((r) => r.skipped).length;
@@ -62,37 +109,90 @@ function buildReport(results: readonly ValidationResultContract[]): AggregatedVa
   };
 }
 
-async function main(): Promise<void> {
-  const stagedFiles = getStagedFiles();
-  const tsFiles = stagedFiles.filter((f) => f.endsWith('.ts'));
+function maxExitCode(a: 0 | 1 | 2, b: 0 | 1 | 2): 0 | 1 | 2 {
+  return (Math.max(a, b) as 0 | 1 | 2);
+}
 
-  if (tsFiles.length === 0) {
-    process.stdout.write(`${DIM}[phasegate] No staged TypeScript files. Skipping.${RESET}\n`);
-    process.exit(0);
+export async function runPreCommit(
+  stagedFiles: readonly string[],
+  deps: PreCommitDeps,
+): Promise<PreCommitResult> {
+  const tsFiles = stagedFiles.filter((f) => f.endsWith(TS_EXTENSION));
+  const mdFiles = stagedFiles.filter((f) => f.endsWith(MD_EXTENSION));
+  const testFiles = tsFiles.filter((f) => isTestFile(f));
+  const metadataFiles = [...mdFiles, ...testFiles];
+
+  if (tsFiles.length === 0 && mdFiles.length === 0) {
+    return {
+      exitCode: 0,
+      stdout: `${DIM}[phasegate] No staged files to check. Skipping.${RESET}`,
+    };
   }
 
-  process.stdout.write(`${BOLD}[phasegate]${RESET} Pre-commit check (${tsFiles.length} file(s))\n`);
+  const sections: string[] = [];
+  sections.push(
+    `${BOLD}[phasegate]${RESET} Pre-commit check ` +
+      `(${tsFiles.length} .ts file(s), ${mdFiles.length} .md file(s))`,
+  );
+
+  let exitCode: 0 | 1 | 2 = 0;
 
-  const mod = createValidatorSystemModule();
-  const results = await mod.runL2ValidatorsUseCase.execute({
-    targetPaths: tsFiles,
-    unitName: '',
-    currentPhase: '',
-  });
+  if (tsFiles.length > 0) {
+    const results = await deps.runL2ValidatorsUseCase.execute({
+      targetPaths: tsFiles,
+      unitName: '',
+      currentPhase: '',
+    });
+    const report = buildReport(results);
+    sections.push('');
+    sections.push(`${BOLD}== TypeScript 実装 (${tsFiles.length} file(s)) ==${RESET}`);
+    sections.push(new HumanValidationResultFormatter().format(report));
+    if (!report.overallPassed) {
+      exitCode = maxExitCode(exitCode, 1);
+    }
+  }
 
-  const report = buildReport(results);
-  process.stdout.write(`${new HumanValidationResultFormatter().format(report)}\n`);
+  if (metadataFiles.length > 0) {
+    const metadataResult = await deps.validateMetadataCommandHandler.execute({
+      filePaths: metadataFiles,
+    });
+    sections.push('');
+    sections.push(
+      `${BOLD}== 設計 / テスト メタデータ注釈 (${metadataFiles.length} file(s)) ==${RESET}`,
+    );
+    sections.push(metadataResult.text);
+    exitCode = maxExitCode(exitCode, metadataResult.exitCode);
+  }
 
-  if (!report.overallPassed) {
-    process.stdout.write(`\n${RED}${BOLD}[phasegate] Commit blocked.${RESET}\n`);
-    process.exit(1);
+  sections.push('');
+  if (exitCode === 0) {
+    sections.push(`${GREEN}[phasegate]${RESET} All checks passed.`);
+  } else {
+    sections.push(`${RED}${BOLD}[phasegate] Commit blocked.${RESET}`);
   }
-  process.stdout.write(`\n${GREEN}[phasegate]${RESET} All checks passed.\n`);
-  process.exit(0);
+
+  return {
+    exitCode,
+    stdout: sections.join('\n'),
+  };
 }
 
-main().catch((err) => {
-  const msg = err instanceof Error ? err.message : String(err);
-  process.stderr.write(`${RED}[phasegate] Unexpected error:${RESET} ${msg}\n`);
-  process.exit(2);
-});
+export async function runPreCommitCli(): Promise<void> {
+  try {
+    const stagedFiles = getStagedFiles();
+    const validatorMod = createValidatorSystemModule();
+    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+
+    const result = await runPreCommit(stagedFiles, {
+      runL2ValidatorsUseCase: validatorMod.runL2ValidatorsUseCase,
+      validateMetadataCommandHandler: traceabilityMod.validateMetadataCommandHandler,
+    });
+
+    process.stdout.write(`${result.stdout}\n`);
+    process.exit(result.exitCode);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${RED}[phasegate] Unexpected error:${RESET} ${msg}\n`);
+    process.exit(2);
+  }
+}