phasegate 0.136.0 → 0.137.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.137.0] - 2026-05-09
+
+### Added
+
+- **WI-032 — AGENTS.md / CLAUDE.md auto-refresh pipeline** — `ci:auto-refresh-agent-context --dry-run|--apply|--json` を追加し、lesson artifact 由来の AGENTS.md pointer 更新と CLAUDE.md 標準セクション更新を 1 コマンドで実行できるようにした。
+  - `refresh-claude-md --dry-run|--apply|--json` を追加し、CLAUDE.md の user-owned section を保持しながら bundled template から標準セクションを再生成。
+  - `p2:check-agent-context --threshold-days <n> --json` を追加し、AGENTS.md / CLAUDE.md の鮮度を検査可能にした。
+  - `docs/templates/ci/agent-context-refresh.yml` を追加し、`ci:generate-template --type agent-context-refresh --render` と `phasegate init --with-ci` で配布可能にした。
+  - PhaseGate 自身にも `.github/workflows/agent-context-refresh.yml` を追加し、週次 refresh PR を作成する構成にした。
+
 ## [0.136.0] - 2026-05-09
 
 ### Added

package/README.ja.md

@@ -87,7 +87,7 @@ claude
 - `docs/principles/*.md` — アーキテクチャ哲学・テスト規約（immutable）
 - `docs/folder_management_rules.md` — ドキュメント配置ルール（**正本**）
 - `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` も配置
-- `--with-ci` を付けると `.github/workflows/aidlc-gate.yml` ・ `.github/workflows/consistency-check.yml` も配置
+- `--with-ci` を付けると `.github/workflows/aidlc-gate.yml` ・ `.github/workflows/consistency-check.yml` ・ `.github/workflows/agent-context-refresh.yml` も配置
 
 **`init` が生成しないもの**（後で skill が作る）:
 
@@ -296,7 +296,10 @@ npx phasegate <command> [options]
 | `phasegate:detect-drift` | 設計-コード乖離レポート |
 | `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
 | `migrate --schema v3` | `phasegate.config.json` を v3 schema へ昇格（`architecture` キー追加） |
-| `ci:generate-template --type <aidlc-gate\|pre-commit\|consistency-check>` | CI/CD テンプレート生成（`--render` で bundled template を stdout 出力） |
+| `ci:generate-template --type <aidlc-gate\|pre-commit\|consistency-check\|agent-context-refresh>` | CI/CD テンプレート生成（`--render` で bundled template を stdout 出力） |
+| `ci:auto-refresh-agent-context --dry-run` / `--apply` | AGENTS.md pointer と CLAUDE.md 標準セクションを更新 |
+| `refresh-claude-md --dry-run` / `--apply` | user section を保持して CLAUDE.md だけを更新 |
+| `p2:check-agent-context` | AGENTS.md / CLAUDE.md の鮮度を検査 |
 | `list-errors --layer <L0-L4>` | エラー定義一覧 |
 | `hook <pre-tool-use\|post-tool-use\|stop>` | agent hook を起動（stdin から JSON） |
 | `pre-commit` | L2 pre-commit バリデータをステージファイルに適用 |
@@ -452,7 +455,6 @@ reports/
 
 | Work Item | 内容 |
 |---|---|
-| **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh パイプライン |
 | **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
 
 L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。現時点では手動セットアップで利用できます。

package/README.md

@@ -86,7 +86,7 @@ claude
 - `.claude/settings.json` and/or `.codex/hooks.json` hook configuration
 - `docs/principles/*.md` and `docs/folder_management_rules.md`
 - `.husky/pre-commit` and `.husky/commit-msg` when `--with-husky` is passed
-- `.github/workflows/aidlc-gate.yml` and `.github/workflows/consistency-check.yml` when `--with-ci` is passed
+- `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml` when `--with-ci` is passed
 
 `init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
 
@@ -468,7 +468,10 @@ npx phasegate <command> [options]
 | `lint` | Run L1 Biome AST checks |
 | `validate --layer <L2-L4\|all>` | Run validators for specified layer (`--layer L0` prints runtime hook guidance) |
 | `ci-check` | Full CI check (L2-L4) |
-| `ci:generate-template --type <aidlc-gate\|consistency-check\|pre-commit> --render` | Render the bundled CI/hook template to stdout |
+| `ci:generate-template --type <aidlc-gate\|consistency-check\|pre-commit\|agent-context-refresh> --render` | Render the bundled CI/hook template to stdout |
+| `ci:auto-refresh-agent-context --dry-run` / `--apply` | Refresh AGENTS.md pointers and CLAUDE.md standard sections |
+| `refresh-claude-md --dry-run` / `--apply` | Refresh only CLAUDE.md while preserving the user-owned section |
+| `p2:check-agent-context` | Check AGENTS.md / CLAUDE.md freshness |
 | `update-skills` | Update skills to latest version |
 | `phasegate:status` | Display overall harness health summary |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
@@ -514,7 +517,6 @@ The main path is ready for project use, but a few documented behaviors still req
 
 | Work Item | Title | Why it matters |
 |---|---|---|
-| **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh pipeline | `ci:migrate-agents-md` exists as a one-shot CLI but there is no scheduled job, and CLAUDE.md is fully hand-maintained. WI-032 adds an `auto-refresh-agent-context` workflow plus a template-driven CLAUDE.md regenerator that preserves user-owned sections. |
 | **[WI-033](docs/inception/_cross/WI-033/description.md)** | Promote `doc-freshness` / `pointer-validation` to L4 validators | Both capabilities exist as `p2:check-freshness` / `p2:validate-pointers` CLI commands but are not registered as L4 validators, so `validate --layer L4` skips them. WI-033 plumbs them through `validator-system` so they run via the standard L4 path and presets. |
 
 `requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see the L3 guide for the current manual setup.

package/docs/guide/cli-reference.md

@@ -321,6 +321,9 @@ ISSUE-005 P3-10 で明確化された境界:
 |---|---|---|
 | `ci:generate-template` | `--preset <id>` `--type <type>` `--render` `--json` | Generate CI/CD template |
 | `ci:migrate-agents-md` | `--dry-run` `--validate-only` `--json` | Migrate AGENTS.md to pointer format |
+| `ci:auto-refresh-agent-context` | `--dry-run` `--apply` `--json` | Refresh AGENTS.md pointers and CLAUDE.md standard sections |
+| `refresh-claude-md` | `--dry-run` `--apply` `--json` | Refresh CLAUDE.md while preserving the user-owned section |
+| `p2:check-agent-context` | `--threshold-days <n>` `--json` | Check AGENTS.md / CLAUDE.md freshness |
 | `ci:check-repetition` | `--code <errorCode>` `--reset` `--json` | Detect repetitive errors |
 
 ---

package/docs/templates/agent-context/CLAUDE.md.template.md

@@ -0,0 +1,29 @@
+# CLAUDE.md
+
+## 必読ドキュメント
+
+- `docs/folder_management_rules.md`
+- `docs/principles/architecture-philosophy.md`
+- `docs/principles/testing-rules.md`
+
+## PhaseGate Commands
+
+{{PHASEGATE_COMMANDS}}
+
+## Phase Presets
+
+{{PHASEGATE_PRESETS}}
+
+## Skills
+
+{{PHASEGATE_SKILLS}}
+
+## User Section
+
+<!-- phasegate:user-section:start -->
+{{PHASEGATE_USER_SECTION}}
+<!-- phasegate:user-section:end -->
+
+## Agent Context Refresh
+
+Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.

package/docs/templates/ci/agent-context-refresh.yml

@@ -0,0 +1,59 @@
+# Phasegate — Agent context refresh workflow
+#
+# 使い方:
+#   このファイルを .github/workflows/agent-context-refresh.yml にコピーして使用する。
+#
+# 実行タイミング: 毎週火曜 04:00 UTC（手動トリガーも可）
+# 実行内容:
+#   1. AGENTS.md pointer refresh
+#   2. CLAUDE.md standard section refresh
+#   3. 変更検出時: refresh branch を push して PR を作成
+
+name: Agent Context Refresh
+
+on:
+  schedule:
+    - cron: '0 4 * * 2'
+  workflow_dispatch:
+
+jobs:
+  refresh-agent-context:
+    name: Refresh AGENTS.md and CLAUDE.md
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Refresh agent context
+        run: pnpm run harness ci:auto-refresh-agent-context --apply
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          branch: phasegate/agent-context-refresh
+          title: 'chore: refresh agent context'
+          commit-message: 'chore: refresh agent context'
+          body: |
+            Automated AGENTS.md / CLAUDE.md refresh generated by PhaseGate.
+          labels: |
+            aidlc
+            agent-context
+            automated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.136.0",
+  "version": "0.137.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/ci-governance/application/dto/check-agent-context-input.ts

@@ -0,0 +1,8 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+export interface CheckAgentContextInput {
+  readonly thresholdDays?: number;
+}

package/scripts/harness/ci-governance/application/dto/check-agent-context-output.ts

@@ -0,0 +1,17 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+export interface AgentContextFreshnessFinding {
+  readonly path: string;
+  readonly status: 'pass' | 'error';
+  readonly ageInDays: number | null;
+  readonly message: string;
+}
+
+export interface CheckAgentContextOutput {
+  readonly passed: boolean;
+  readonly thresholdDays: number;
+  readonly findings: readonly AgentContextFreshnessFinding[];
+}

package/scripts/harness/ci-governance/application/dto/refresh-agent-context-input.ts

@@ -0,0 +1,8 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+export interface RefreshAgentContextInput {
+  readonly dryRun: boolean;
+}

package/scripts/harness/ci-governance/application/dto/refresh-agent-context-output.ts

@@ -0,0 +1,15 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+import type { MigrateAgentsMdOutput } from './migrate-agents-md-output.js';
+import type { RefreshClaudeMdOutput } from './refresh-claude-md-output.js';
+
+export interface RefreshAgentContextOutput {
+  readonly success: boolean;
+  readonly applied: boolean;
+  readonly agentsMd: MigrateAgentsMdOutput;
+  readonly claudeMd: RefreshClaudeMdOutput;
+  readonly errors: Array<{ code: string; message: string }>;
+}

package/scripts/harness/ci-governance/application/dto/refresh-claude-md-input.ts

@@ -0,0 +1,8 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+export interface RefreshClaudeMdInput {
+  readonly dryRun: boolean;
+}

package/scripts/harness/ci-governance/application/dto/refresh-claude-md-output.ts

@@ -0,0 +1,13 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+export interface RefreshClaudeMdOutput {
+  readonly success: boolean;
+  readonly path: string;
+  readonly changed: boolean;
+  readonly applied: boolean;
+  readonly preview: string;
+  readonly errors: Array<{ code: string; message: string }>;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @layer application
+ * @unit ci-governance
+ */
+
+import type { AgentContextDocumentPort } from '../../domain/ports/agent-context-document-port.js';
+import type { CheckAgentContextInput } from '../dto/check-agent-context-input.js';
+import type { AgentContextFreshnessFinding, CheckAgentContextOutput } from '../dto/check-agent-context-output.js';
+
+const AGENT_CONTEXT_PATHS = ['AGENTS.md', 'CLAUDE.md'] as const;
+const DEFAULT_THRESHOLD_DAYS = 30;
+
+export class CheckAgentContextUseCase {
+  constructor(private readonly documentPort: AgentContextDocumentPort) {}
+
+  async execute(input: CheckAgentContextInput): Promise<CheckAgentContextOutput> {
+    const thresholdDays = input.thresholdDays ?? DEFAULT_THRESHOLD_DAYS;
+    const findings: AgentContextFreshnessFinding[] = [];
+
+    for (const path of AGENT_CONTEXT_PATHS) {
+      const stat = await this.documentPort.statProjectFile(path);
+      if (!stat.exists) {
+        findings.push({
+          path,
+          status: 'error',
+          ageInDays: null,
+          message: `${path} does not exist`,
+        });
+        continue;
+      }
+      const stale = stat.ageInDays !== null && stat.ageInDays > thresholdDays;
+      findings.push({
+        path,
+        status: stale ? 'error' : 'pass',
+        ageInDays: stat.ageInDays,
+        message: stale
+          ? `${path} is older than ${thresholdDays} days`
+          : `${path} is fresh`,
+      });
+    }
+
+    return {
+      passed: findings.every((finding) => finding.status === 'pass'),
+      thresholdDays,
+      findings,
+    };
+  }
+}

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;
@@ -75,6 +86,7 @@ export function buildCiGovernance(
   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

@@ -14,12 +14,14 @@ 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 {

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/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}`,
+    };
+  }
+}

package/scripts/harness/main.ts

@@ -123,8 +123,11 @@ Commands:
   phasegate:complete-check       Complete L2-L4 check (--json)
   phasegate:impact-analysis      Impact analysis for story (<storyId>, --json)
 
-  ci:generate-template         Generate CI template (--preset <id>, --type <aidlc-gate|consistency-check|pre-commit>, --render, --json)
+  ci:generate-template         Generate CI template (--preset <id>, --type <aidlc-gate|consistency-check|pre-commit|agent-context-refresh>, --render, --json)
   ci:migrate-agents-md         Migrate AGENTS.md (--dry-run, --validate-only, --json)
+  ci:auto-refresh-agent-context Refresh AGENTS.md / CLAUDE.md (--dry-run, --apply, --json)
+  refresh-claude-md            Refresh CLAUDE.md standard sections (--dry-run, --apply, --json)
+  p2:check-agent-context       Check AGENTS.md / CLAUDE.md freshness (--threshold-days <n>, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
   scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --force, --json)
@@ -346,6 +349,7 @@ Options:
                      aidlc-gate        — AIDLC phase gate checks
                      consistency-check — Doc/code consistency checks
                      pre-commit        — Pre-commit hook template
+                     agent-context-refresh — AGENTS.md / CLAUDE.md refresh workflow
   --render         Render the template to stdout
   --json           Output in JSON format
 
@@ -1233,6 +1237,39 @@ Examples:
         break;
       }
 
+      case "ci:auto-refresh-agent-context": {
+        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const dryRun = hasFlag(args, "--dry-run");
+        const apply = hasFlag(args, "--apply");
+        const format = json ? "json" : "human";
+        const result = await mod.refreshAgentContextHandler.handle({ dryRun, apply, format });
+        console.log(result.output);
+        process.exit(result.exitCode);
+        break;
+      }
+
+      case "refresh-claude-md": {
+        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const dryRun = hasFlag(args, "--dry-run");
+        const apply = hasFlag(args, "--apply");
+        const format = json ? "json" : "human";
+        const result = await mod.refreshClaudeMdHandler.handle({ dryRun, apply, format });
+        console.log(result.output);
+        process.exit(result.exitCode);
+        break;
+      }
+
+      case "p2:check-agent-context": {
+        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const thresholdRaw = parseFlag(args, "--threshold-days");
+        const thresholdDays = thresholdRaw === undefined ? undefined : Number(thresholdRaw);
+        const format = json ? "json" : "human";
+        const result = await mod.checkAgentContextHandler.handle({ thresholdDays, format });
+        console.log(result.output);
+        process.exit(result.exitCode);
+        break;
+      }
+
       case "ci:check-repetition": {
         const mod = buildCiGovernance(rootDir, harnessRoot);
         const errorCode = parseFlag(args, "--code") ?? "";

package/scripts/harness/setup/skill-deployer.ts

@@ -555,6 +555,10 @@ export async function deployCiWorkflows(harnessRoot: string, projectRoot: string
       relativeSource: join("docs", "templates", "ci", "consistency-check.yml"),
       relativeTarget: join(".github", "workflows", "consistency-check.yml"),
     },
+    {
+      relativeSource: join("docs", "templates", "ci", "agent-context-refresh.yml"),
+      relativeTarget: join(".github", "workflows", "agent-context-refresh.yml"),
+    },
   ];
 
   await fs.mkdir(join(projectRoot, ".github", "workflows"), { recursive: true });