phasegate 0.135.0 → 0.137.0

package/scripts/harness/ci-governance/application/usecases/refresh-agent-context-usecase.ts

@@ -0,0 +1,31 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+import type { MigrateAgentsMdUseCase } from './migrate-agents-md-usecase.js';
+import type { RefreshClaudeMdUseCase } from './refresh-claude-md-usecase.js';
+import type { RefreshAgentContextInput } from '../dto/refresh-agent-context-input.js';
+import type { RefreshAgentContextOutput } from '../dto/refresh-agent-context-output.js';
+
+export class RefreshAgentContextUseCase {
+  constructor(
+    private readonly migrateAgentsMdUseCase: MigrateAgentsMdUseCase,
+    private readonly refreshClaudeMdUseCase: RefreshClaudeMdUseCase,
+  ) {}
+
+  async execute(input: RefreshAgentContextInput): Promise<RefreshAgentContextOutput> {
+    const [agentsMd, claudeMd] = await Promise.all([
+      this.migrateAgentsMdUseCase.execute({ dryRun: input.dryRun }),
+      this.refreshClaudeMdUseCase.execute({ dryRun: input.dryRun }),
+    ]);
+    const errors = [...agentsMd.errors, ...claudeMd.errors];
+    return {
+      success: agentsMd.success && claudeMd.success,
+      applied: !input.dryRun && agentsMd.success && claudeMd.success,
+      agentsMd,
+      claudeMd,
+      errors,
+    };
+  }
+}

package/scripts/harness/ci-governance/application/usecases/refresh-claude-md-usecase.ts

@@ -0,0 +1,73 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+import type { AgentContextDocumentPort } from '../../domain/ports/agent-context-document-port.js';
+import type { ClaudeMdComposer } from '../../domain/services/claude-md-composer.js';
+import type { RefreshClaudeMdInput } from '../dto/refresh-claude-md-input.js';
+import type { RefreshClaudeMdOutput } from '../dto/refresh-claude-md-output.js';
+
+const CLAUDE_MD_PATH = 'CLAUDE.md';
+const CLAUDE_MD_TEMPLATE_PATH = 'docs/templates/agent-context/CLAUDE.md.template.md';
+
+const PHASEGATE_COMMANDS = [
+  'phasegate init --with-ci',
+  'phasegate ci:auto-refresh-agent-context --dry-run',
+  'phasegate ci:auto-refresh-agent-context --apply',
+  'phasegate refresh-claude-md --apply',
+  'phasegate p2:check-agent-context',
+  'phasegate phasegate:check-ready',
+];
+
+const PHASE_PRESETS = ['minimal', 'standard', 'full', 'custom'];
+
+export class RefreshClaudeMdUseCase {
+  constructor(
+    private readonly documentPort: AgentContextDocumentPort,
+    private readonly composer: ClaudeMdComposer,
+  ) {}
+
+  async execute(input: RefreshClaudeMdInput): Promise<RefreshClaudeMdOutput> {
+    try {
+      const [template, existing, skills] = await Promise.all([
+        this.documentPort.readHarnessTemplate(CLAUDE_MD_TEMPLATE_PATH),
+        this.documentPort.readProjectFile(CLAUDE_MD_PATH),
+        this.documentPort.listHarnessSkillNames(),
+      ]);
+      const nextContent = this.composer.compose(template, existing, {
+        commands: PHASEGATE_COMMANDS,
+        skills,
+        presets: PHASE_PRESETS,
+      });
+      const changed = existing !== nextContent;
+
+      if (!input.dryRun && changed) {
+        await this.documentPort.writeProjectFile(CLAUDE_MD_PATH, nextContent);
+      }
+
+      return {
+        success: true,
+        path: CLAUDE_MD_PATH,
+        changed,
+        applied: !input.dryRun && changed,
+        preview: nextContent,
+        errors: [],
+      };
+    } catch (error) {
+      return {
+        success: false,
+        path: CLAUDE_MD_PATH,
+        changed: false,
+        applied: false,
+        preview: '',
+        errors: [
+          {
+            code: 'AGENT_CONTEXT_CLAUDE_REFRESH_FAILED',
+            message: error instanceof Error ? error.message : String(error),
+          },
+        ],
+      };
+    }
+  }
+}

package/scripts/harness/ci-governance/composition-root.ts

@@ -9,6 +9,7 @@ import { TemplateGenerator } from './domain/services/template-generator.js';
 import { RepetitionDetector } from './domain/services/repetition-detector.js';
 import { PointerValidator } from './domain/services/pointer-validator.js';
 import { LessonAggregator } from './domain/services/lesson-aggregator.js';
+import { ClaudeMdComposer } from './domain/services/claude-md-composer.js';
 
 import { GenerateCiTemplateUseCase } from './application/usecases/generate-ci-template-usecase.js';
 import { RenderCiTemplateUseCase } from './application/usecases/render-ci-template-usecase.js';
@@ -16,6 +17,9 @@ import { RecordErrorOccurrenceUseCase } from './application/usecases/record-erro
 import { CheckEscalationUseCase } from './application/usecases/check-escalation-usecase.js';
 import { ResetRepetitionUseCase } from './application/usecases/reset-repetition-usecase.js';
 import { MigrateAgentsMdUseCase } from './application/usecases/migrate-agents-md-usecase.js';
+import { RefreshAgentContextUseCase } from './application/usecases/refresh-agent-context-usecase.js';
+import { RefreshClaudeMdUseCase } from './application/usecases/refresh-claude-md-usecase.js';
+import { CheckAgentContextUseCase } from './application/usecases/check-agent-context-usecase.js';
 import { AggregateLessonsUseCase } from './application/usecases/aggregate-lessons-usecase.js';
 import { ValidatePointersUseCase } from './application/usecases/validate-pointers-usecase.js';
 
@@ -26,12 +30,16 @@ import { EscalationLogExecutorAdapter } from './infrastructure/adapters/escalati
 import { YamlTemplateRendererAdapter } from './infrastructure/adapters/yaml-template-renderer-adapter.js';
 import { FileSystemExistenceAdapter } from './infrastructure/adapters/file-system-existence-adapter.js';
 import { AgentsMdFileAdapter } from './infrastructure/adapters/agents-md-file-adapter.js';
+import { AgentContextFileAdapter } from './infrastructure/adapters/agent-context-file-adapter.js';
 import { LessonArtifactFileReaderAdapter } from './infrastructure/adapters/lesson-artifact-file-reader-adapter.js';
 import { HarnessApiCommandExistenceAdapter } from './infrastructure/adapters/harness-api-command-existence-adapter.js';
 import { AdrFoundationExistenceAdapter } from './infrastructure/adapters/adr-foundation-existence-adapter.js';
 
 import { GenerateCiTemplateHandler } from './presentation/handlers/generate-ci-template-handler.js';
 import { MigrateAgentsMdHandler } from './presentation/handlers/migrate-agents-md-handler.js';
+import { RefreshAgentContextHandler } from './presentation/handlers/refresh-agent-context-handler.js';
+import { RefreshClaudeMdHandler } from './presentation/handlers/refresh-claude-md-handler.js';
+import { CheckAgentContextHandler } from './presentation/handlers/check-agent-context-handler.js';
 import { CheckRepetitionHandler } from './presentation/handlers/check-repetition-handler.js';
 import { CreateBaselineHandler } from './presentation/handlers/create-baseline-handler.js';
 
@@ -48,6 +56,9 @@ import { ScaffoldDesignHandler } from './presentation/handlers/scaffold-design-h
 export interface CiGovernanceCompositionRoot {
   generateCiTemplateHandler: GenerateCiTemplateHandler;
   migrateAgentsMdHandler: MigrateAgentsMdHandler;
+  refreshAgentContextHandler: RefreshAgentContextHandler;
+  refreshClaudeMdHandler: RefreshClaudeMdHandler;
+  checkAgentContextHandler: CheckAgentContextHandler;
   checkRepetitionHandler: CheckRepetitionHandler;
   createBaselineHandler: CreateBaselineHandler;
   scaffoldDesignHandler: ScaffoldDesignHandler;
@@ -70,11 +81,12 @@ export function buildCiGovernance(
   const presetConfigAdapter = new PresetConfigAdapter();
   const errorRepetitionRepository = new ErrorRepetitionJsonRepository(baseDir);
   const escalationExecutorPort = new EscalationLogExecutorAdapter();
-  const templateRendererPort = new YamlTemplateRendererAdapter();
+  const templateRendererPort = new YamlTemplateRendererAdapter(harnessRoot);
   const fileExistencePort = new FileSystemExistenceAdapter(baseDir);
   const commandExistencePort = new HarnessApiCommandExistenceAdapter();
   const adrExistencePort = new AdrFoundationExistenceAdapter();
   const agentsMdPort = new AgentsMdFileAdapter(baseDir);
+  const agentContextDocumentPort = new AgentContextFileAdapter(baseDir, harnessRoot);
   const lessonArtifactReaderPort = new LessonArtifactFileReaderAdapter(baseDir);
 
   // Domain services
@@ -82,6 +94,7 @@ export function buildCiGovernance(
   const repetitionDetector = new RepetitionDetector(errorRepetitionRepository);
   const pointerValidator = new PointerValidator(commandExistencePort, fileExistencePort, adrExistencePort);
   const lessonAggregator = new LessonAggregator();
+  const claudeMdComposer = new ClaudeMdComposer();
 
   // Use cases
   const generateCiTemplateUseCase = new GenerateCiTemplateUseCase(templateGenerator);
@@ -95,6 +108,9 @@ export function buildCiGovernance(
     lessonAggregator,
     pointerValidator,
   );
+  const refreshClaudeMdUseCase = new RefreshClaudeMdUseCase(agentContextDocumentPort, claudeMdComposer);
+  const refreshAgentContextUseCase = new RefreshAgentContextUseCase(migrateAgentsMdUseCase, refreshClaudeMdUseCase);
+  const checkAgentContextUseCase = new CheckAgentContextUseCase(agentContextDocumentPort);
   const aggregateLessonsUseCase = new AggregateLessonsUseCase(lessonArtifactReaderPort, lessonAggregator);
   const validatePointersUseCase = new ValidatePointersUseCase(agentsMdPort, pointerValidator);
 
@@ -122,6 +138,9 @@ export function buildCiGovernance(
     renderCiTemplateUseCase,
   );
   const migrateAgentsMdHandler = new MigrateAgentsMdHandler(migrateAgentsMdUseCase);
+  const refreshAgentContextHandler = new RefreshAgentContextHandler(refreshAgentContextUseCase);
+  const refreshClaudeMdHandler = new RefreshClaudeMdHandler(refreshClaudeMdUseCase);
+  const checkAgentContextHandler = new CheckAgentContextHandler(checkAgentContextUseCase);
   const checkRepetitionHandler = new CheckRepetitionHandler(checkEscalationUseCase);
   const createBaselineHandler = new CreateBaselineHandler(createBaselineUseCase);
   const scaffoldDesignHandler = new ScaffoldDesignHandler(scaffoldDesignUseCase);
@@ -129,6 +148,9 @@ export function buildCiGovernance(
   return {
     generateCiTemplateHandler,
     migrateAgentsMdHandler,
+    refreshAgentContextHandler,
+    refreshClaudeMdHandler,
+    checkAgentContextHandler,
     checkRepetitionHandler,
     createBaselineHandler,
     scaffoldDesignHandler,

package/scripts/harness/ci-governance/domain/aggregates/ci-template.ts

@@ -29,7 +29,7 @@ export class CiTemplate {
     if (!isTemplateType(templateType)) {
       throw new CiGovernanceDomainError(
         'CI_TEMPLATE_INVALID_TYPE',
-        `INV-1: templateType must be one of 'aidlc-gate', 'consistency-check', 'pre-commit'. Got: ${templateType}`,
+        `INV-1: templateType must be one of 'aidlc-gate', 'consistency-check', 'pre-commit', 'agent-context-refresh'. Got: ${templateType}`,
       );
     }
     if (!presetRef || presetRef.trim() === '') {

package/scripts/harness/ci-governance/domain/ports/agent-context-document-port.ts

@@ -0,0 +1,17 @@
+/**
+ * @layer domain
+ * @unit ci-governance
+ */
+
+export interface AgentContextDocumentStat {
+  readonly exists: boolean;
+  readonly ageInDays: number | null;
+}
+
+export interface AgentContextDocumentPort {
+  readProjectFile(relativePath: string): Promise<string | null>;
+  writeProjectFile(relativePath: string, content: string): Promise<void>;
+  readHarnessTemplate(relativePath: string): Promise<string>;
+  statProjectFile(relativePath: string): Promise<AgentContextDocumentStat>;
+  listHarnessSkillNames(): Promise<string[]>;
+}

package/scripts/harness/ci-governance/domain/services/claude-md-composer.ts

@@ -0,0 +1,39 @@
+/**
+ * @layer domain
+ * @unit ci-governance
+ */
+
+export interface ClaudeMdTemplateValues {
+  readonly commands: readonly string[];
+  readonly skills: readonly string[];
+  readonly presets: readonly string[];
+}
+
+const USER_SECTION_START = '<!-- phasegate:user-section:start -->';
+const USER_SECTION_END = '<!-- phasegate:user-section:end -->';
+const DEFAULT_USER_SECTION = 'プロジェクト固有の指示をここに記載してください。';
+
+export class ClaudeMdComposer {
+  compose(template: string, existing: string | null, values: ClaudeMdTemplateValues): string {
+    const userSection = this.extractUserSection(existing) ?? DEFAULT_USER_SECTION;
+    return template
+      .replace('{{PHASEGATE_COMMANDS}}', this.toList(values.commands))
+      .replace('{{PHASEGATE_SKILLS}}', this.toList(values.skills))
+      .replace('{{PHASEGATE_PRESETS}}', this.toList(values.presets))
+      .replace('{{PHASEGATE_USER_SECTION}}', userSection)
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd() + '\n';
+  }
+
+  private extractUserSection(existing: string | null): string | null {
+    if (existing === null) return null;
+    const start = existing.indexOf(USER_SECTION_START);
+    const end = existing.indexOf(USER_SECTION_END);
+    if (start === -1 || end === -1 || end < start) return existing.trim();
+    return existing.slice(start + USER_SECTION_START.length, end).trim();
+  }
+
+  private toList(values: readonly string[]): string {
+    return values.map((value) => `- \`${value}\``).join('\n');
+  }
+}

package/scripts/harness/ci-governance/domain/services/template-generator.ts

@@ -17,6 +17,7 @@ const TRIGGER_CONDITION_MAP: Record<TemplateType, TriggerCondition> = {
   'aidlc-gate': 'pull_request',
   'consistency-check': 'schedule',
   'pre-commit': 'pre-commit',
+  'agent-context-refresh': 'schedule',
 };
 
 export class TemplateGenerator {

package/scripts/harness/ci-governance/domain/types/template-type.ts

@@ -1,12 +1,13 @@
 // @unit ci-governance
 // @layer domain
 
-export type TemplateType = 'aidlc-gate' | 'consistency-check' | 'pre-commit';
+export type TemplateType = 'aidlc-gate' | 'consistency-check' | 'pre-commit' | 'agent-context-refresh';
 
 export const TEMPLATE_TYPES: readonly TemplateType[] = [
   'aidlc-gate',
   'consistency-check',
   'pre-commit',
+  'agent-context-refresh',
 ] as const;
 
 export function isTemplateType(value: unknown): value is TemplateType {

package/scripts/harness/ci-governance/infrastructure/adapters/agent-context-file-adapter.ts

@@ -0,0 +1,55 @@
+/**
+ * @layer infrastructure
+ * @unit ci-governance
+ */
+
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { AgentContextDocumentPort, AgentContextDocumentStat } from '../../domain/ports/agent-context-document-port.js';
+
+export class AgentContextFileAdapter implements AgentContextDocumentPort {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly harnessRoot: string,
+  ) {}
+
+  async readProjectFile(relativePath: string): Promise<string | null> {
+    try {
+      return await readFile(join(this.projectRoot, relativePath), 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+
+  async writeProjectFile(relativePath: string, content: string): Promise<void> {
+    const targetPath = join(this.projectRoot, relativePath);
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, content, 'utf-8');
+  }
+
+  async readHarnessTemplate(relativePath: string): Promise<string> {
+    return await readFile(join(this.harnessRoot, relativePath), 'utf-8');
+  }
+
+  async statProjectFile(relativePath: string): Promise<AgentContextDocumentStat> {
+    try {
+      const fileStat = await stat(join(this.projectRoot, relativePath));
+      const ageInDays = Math.floor((Date.now() - fileStat.mtime.getTime()) / 86_400_000);
+      return { exists: true, ageInDays };
+    } catch {
+      return { exists: false, ageInDays: null };
+    }
+  }
+
+  async listHarnessSkillNames(): Promise<string[]> {
+    try {
+      const entries = await readdir(join(this.harnessRoot, 'skills'), { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/yaml-template-renderer-adapter.ts

@@ -5,6 +5,8 @@
  * TemplateRendererPort実装（YAML書き出し）
  */
 
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import type { TemplateRendererPort, TemplateRenderOutput } from '../../domain/ports/template-renderer-port.js';
 import type { CiTemplate } from '../../domain/aggregates/ci-template.js';
 
@@ -12,42 +14,25 @@ const OUTPUT_PATH_MAP: Record<string, string> = {
   'aidlc-gate': '.github/workflows/aidlc-gate.yml',
   'consistency-check': '.github/workflows/consistency-check.yml',
   'pre-commit': '.husky/pre-commit',
+  'agent-context-refresh': '.github/workflows/agent-context-refresh.yml',
+};
+
+const TEMPLATE_PATH_MAP: Record<string, string> = {
+  'aidlc-gate': 'docs/templates/ci/aidlc-gate.yml',
+  'consistency-check': 'docs/templates/ci/consistency-check.yml',
+  'pre-commit': 'docs/templates/hooks/pre-commit',
+  'agent-context-refresh': 'docs/templates/ci/agent-context-refresh.yml',
 };
 
 export class YamlTemplateRendererAdapter implements TemplateRendererPort {
+  constructor(private readonly harnessRoot: string = process.cwd()) {}
+
   async render(ciTemplate: CiTemplate): Promise<TemplateRenderOutput> {
     const outputPath = OUTPUT_PATH_MAP[ciTemplate.templateType] ?? '';
-    const content = this.generateContent(ciTemplate);
+    const templatePath = TEMPLATE_PATH_MAP[ciTemplate.templateType];
+    const content = templatePath === undefined
+      ? `# ${ciTemplate.templateType} template (not configured)`
+      : await readFile(join(this.harnessRoot, templatePath), 'utf-8');
     return { outputPath, content };
   }
-
-  private generateContent(ciTemplate: CiTemplate): string {
-    const { templateType, config } = ciTemplate;
-
-    if (!config) {
-      return `# ${templateType} template (not configured)`;
-    }
-
-    if (templateType === 'pre-commit') {
-      return [
-        '#!/bin/sh',
-        '. "$(dirname "$0")/_/husky.sh"',
-        '',
-        `npx phasegate lint --validators ${config.targetValidatorIds.join(',')}`,
-      ].join('\n');
-    }
-
-    return [
-      `name: ${templateType}`,
-      `on:`,
-      `  ${config.triggerCondition === 'pull_request' ? 'pull_request' : 'schedule'}:`,
-      config.triggerCondition === 'schedule' ? '    - cron: "0 2 * * *"' : '',
-      `jobs:`,
-      `  validate:`,
-      `    runs-on: ubuntu-latest`,
-      `    steps:`,
-      `      - uses: actions/checkout@v4`,
-      `      - run: npx phasegate lint --validators ${config.targetValidatorIds.join(',')}`,
-    ].filter((l) => l !== '').join('\n');
-  }
 }

package/scripts/harness/ci-governance/presentation/handlers/check-agent-context-handler.ts

@@ -0,0 +1,33 @@
+/**
+ * @layer presentation
+ * @unit ci-governance
+ */
+
+import type { CheckAgentContextUseCase } from '../../application/usecases/check-agent-context-usecase.js';
+
+export interface CheckAgentContextHandlerArgs {
+  thresholdDays?: number;
+  format?: 'human' | 'json';
+}
+
+export class CheckAgentContextHandler {
+  constructor(private readonly useCase: CheckAgentContextUseCase) {}
+
+  async handle(args: CheckAgentContextHandlerArgs): Promise<{ exitCode: number; output: string }> {
+    const result = await this.useCase.execute({ thresholdDays: args.thresholdDays });
+
+    if (args.format === 'json') {
+      return { exitCode: result.passed ? 0 : 1, output: JSON.stringify(result, null, 2) };
+    }
+
+    const lines = [
+      `Agent context freshness: ${result.passed ? 'PASS' : 'FAIL'}`,
+      `Threshold: ${result.thresholdDays} days`,
+      ...result.findings.map((finding) => {
+        const age = finding.ageInDays === null ? 'missing' : `${finding.ageInDays} days`;
+        return `- ${finding.path}: ${finding.status} (${age}) ${finding.message}`;
+      }),
+    ];
+    return { exitCode: result.passed ? 0 : 1, output: lines.join('\n') };
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/generate-ci-template-handler.ts

@@ -31,7 +31,25 @@ export class GenerateCiTemplateHandler {
   ) {}
 
   async handle(args: GenerateCiTemplateHandlerArgs): Promise<GenerateCiTemplateHandlerResult> {
-    const { presetId, templateType, format = 'human' } = args;
+    const { presetId, templateType, render = false, format = 'human' } = args;
+
+    if (render) {
+      const result = await this.renderUseCase.execute({
+        presetId,
+        templateType: templateType as TemplateType,
+      });
+      const hasErrors = result.errors.length > 0;
+      const output = format === 'json'
+        ? JSON.stringify(result, null, 2)
+        : hasErrors
+          ? result.errors.map((err) => `[${err.code}] ${err.message}`).join('\n')
+          : result.content;
+
+      return {
+        exitCode: hasErrors ? 1 : 0,
+        output,
+      };
+    }
 
     const result = await this.generateUseCase.execute({
       presetId,

package/scripts/harness/ci-governance/presentation/handlers/refresh-agent-context-handler.ts

@@ -0,0 +1,44 @@
+/**
+ * @layer presentation
+ * @unit ci-governance
+ */
+
+import type { RefreshAgentContextUseCase } from '../../application/usecases/refresh-agent-context-usecase.js';
+
+export interface RefreshAgentContextHandlerArgs {
+  dryRun?: boolean;
+  apply?: boolean;
+  format?: 'human' | 'json';
+}
+
+export class RefreshAgentContextHandler {
+  constructor(private readonly useCase: RefreshAgentContextUseCase) {}
+
+  async handle(args: RefreshAgentContextHandlerArgs): Promise<{ exitCode: number; output: string }> {
+    const dryRun = args.apply === true ? false : (args.dryRun ?? true);
+    const result = await this.useCase.execute({ dryRun });
+
+    if (args.format === 'json') {
+      return { exitCode: result.success ? 0 : 1, output: JSON.stringify(result, null, 2) };
+    }
+
+    if (!result.success) {
+      return {
+        exitCode: 1,
+        output: ['Agent context refresh failed', ...result.errors.map((error) => `[${error.code}] ${error.message}`)].join('\n'),
+      };
+    }
+
+    const mode = dryRun ? 'dry-run' : 'apply';
+    const preview = dryRun ? `\n\nCLAUDE.md preview:\n${result.claudeMd.preview}` : '';
+    return {
+      exitCode: 0,
+      output: [
+        `Agent context refresh ${mode} complete`,
+        `AGENTS.md added pointers: ${result.agentsMd.addedPointers}`,
+        `CLAUDE.md changed: ${result.claudeMd.changed}`,
+        `Applied: ${result.applied}`,
+      ].join('\n') + preview,
+    };
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/refresh-claude-md-handler.ts

@@ -0,0 +1,38 @@
+/**
+ * @layer presentation
+ * @unit ci-governance
+ */
+
+import type { RefreshClaudeMdUseCase } from '../../application/usecases/refresh-claude-md-usecase.js';
+
+export interface RefreshClaudeMdHandlerArgs {
+  dryRun?: boolean;
+  apply?: boolean;
+  format?: 'human' | 'json';
+}
+
+export class RefreshClaudeMdHandler {
+  constructor(private readonly useCase: RefreshClaudeMdUseCase) {}
+
+  async handle(args: RefreshClaudeMdHandlerArgs): Promise<{ exitCode: number; output: string }> {
+    const dryRun = args.apply === true ? false : (args.dryRun ?? true);
+    const result = await this.useCase.execute({ dryRun });
+
+    if (args.format === 'json') {
+      return { exitCode: result.success ? 0 : 1, output: JSON.stringify(result, null, 2) };
+    }
+
+    if (!result.success) {
+      return {
+        exitCode: 1,
+        output: ['CLAUDE.md refresh failed', ...result.errors.map((error) => `[${error.code}] ${error.message}`)].join('\n'),
+      };
+    }
+
+    const mode = dryRun ? 'dry-run' : 'apply';
+    return {
+      exitCode: 0,
+      output: `CLAUDE.md refresh ${mode}: changed=${result.changed}, applied=${result.applied}`,
+    };
+  }
+}