phasegate 0.152.7 → 0.152.9

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.9] - 2026-05-13
+
+### Added
+
+- **WI-171 / WI-172 / WI-173 / WI-174 — user onboarding and agent-driven setup** — adds first-run recipes and troubleshooting guides, managed `AGENTS.md` / `CLAUDE.md` setup sections, dedicated AGENTS lesson pointer refresh, `setup:agent` setup planning/apply flow, and `config:plan` configuration-change intent planning.
+
+## [0.152.8] - 2026-05-13
+
+### Changed
+
+- **WI-155 / WI-165 / WI-166 / WI-167 / WI-168 — product reflection and catalog cleanup** — aligns product unit catalog policy, ADR validator catalog references, Work Item reflection wording, hook skip observability docs, and coverage/test design refresh for WI-117..148 follow-up semantics.
+
 ## [0.152.7] - 2026-05-13
 
 ### Changed

package/README.md

@@ -60,6 +60,8 @@ The point is not just to fail the edit. The error gives the AI agent enough stru
 
 ## Quick Start
 
+For a guided first run, start with [Getting Started](docs/guide/getting-started.md). It maps new repo, existing repo, CI-only, agent-hook, and strict rollout paths to the next command and success state. <!-- @work-item-id WI-171 -->
+
 ### Requirements
 
 Node.js >= 18, npm >= 9, TypeScript 5.x
@@ -98,7 +100,16 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`.
+`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes `AGENTS.md` / `CLAUDE.md` PhaseGate managed sections for the selected agent targets, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`. <!-- @work-item-id WI-174 -->
+
+For agent-driven setup planning, use:
+
+```bash
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+The first command reports detected setup state, missing questions, planned managed targets, rollback, and validation. The second maps a configuration change intent to files, commands, risks, and checks. <!-- @work-item-id WI-172, WI-173 -->
 
 To remove PhaseGate from that project later, run:
 
@@ -507,6 +518,8 @@ README keeps only the entry points most users need. The full public/compatibilit
 | `doctor` | Diagnose silent or partial installations (`--json`, `--strict`, `--report-out <path>`). `--report-out` is an explicit file path, not `reporting.outputDir`. |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`, preserving user content. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to the current package templates and refresh manifest hashes. |
+| `setup:agent --dry-run` / `--apply` | Diagnose repository setup and produce or apply an agent-readable setup plan with questions, risks, rollback, and validation. |
+| `config:plan --intent <intent>` | Map a safe configuration-change intent to target files, commands, risks, rollback, and validation. |
 | `lint` / `phasegate:lint` | Run L1 Biome AST checks. The `phasegate:*` form is a binary subcommand, not an npm script unless `package.json` defines it locally. |
 | `validate --layer <L1-L4\|all>` | Run validators for the specified layer (`--layer L0` prints runtime hook guidance). `--fail-on-warning` / `--no-fail-on-warning` override config. |
 | `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped). Supports `--quick`, `--fail-on-reject`, `--dry-run`, and `--files`. |
@@ -547,6 +560,9 @@ See the [CLI Reference](docs/guide/cli-reference.md) for the complete catalog an
 Detailed guides are available under `docs/guide/`:
 
 - [Installation](docs/guide/installation.md) -- Detailed install and setup instructions
+- [Getting Started](docs/guide/getting-started.md) -- First-run, daily-use, CI-use, and agent-use paths
+- [Recipes](docs/guide/recipes.md) -- Focused onboarding and configuration recipes
+- [Troubleshooting](docs/guide/troubleshooting.md) -- Doctor finding, repairHint, suggestedSkill, and setup recovery guide
 - [Configuration](docs/guide/configuration.md) -- `phasegate.config.json` full reference
 - [CLI Reference](docs/guide/cli-reference.md) -- All CLI commands and options
 - [Skills Overview](docs/guide/skills-overview.md) -- 30 skills with AIDLC execution order

package/docs/ADR/ADR-002-pre-commit-validators.md

@@ -10,13 +10,16 @@ AIエージェントは設計文書を無視して直接コードを書くこと
 
 ## Decision
 
-L2（Pre-commit）で以下の3バリデータにより設計-実装の順序を機械的に強制する。
+L2（Pre-commit）で以下のバリデータにより設計-実装の順序、メタデータ、テスト品質、CLI E2E、WI status、公開 contract traceability を機械的に強制または報告する。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry を正とする。<!-- @work-item-id WI-168 -->
 
 | バリデータ | コード | 検出対象 |
 |-----------|--------|---------|
 | phase-gate | L2-001 | 設計文書なしの実装コード変更を拒否 |
 | metadata | L2-002 | @unit/@layer/@US-XXX メタデータの完全性検証 |
 | test-quality | L2-003 | AAA パターン、actual 命名、日本語テスト名の検証 |
+| cli-e2e | L2-013 | public CLI entrypoint の基本 E2E 契約 |
+| wi-status | L2-014 | WI status と acceptance criteria の陳腐化検出 |
+| contract-traceability | L2-015 | public contract / boundary / observation の traceability coverage |
 
 ### Phase Gate の3層検証
 
@@ -27,7 +30,7 @@ L2（Pre-commit）で以下の3バリデータにより設計-実装の順序を
 ## Consequences
 
 - 設計文書なしのコード変更が物理的に不可能になる
-- `@US-XXX` によるトレーサビリティが機械的に保証される
+- `@work-item-id WI-XXX` と legacy annotation の対応によりトレーサビリティが機械的に保証される
 - テスト品質ルール（AAA, actual 命名）が全テストに強制される
 
 ## 関連要件

package/docs/ADR/ADR-004-scheduled-validators.md

@@ -10,13 +10,15 @@ Accepted
 
 ## Decision
 
-L4（Scheduled）で以下の3バリデータを週次で実行する。
+L4（Scheduled）で以下のバリデータを週次または明示実行で扱う。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry と `docs/guide/layer-model.md` を正とする。<!-- @work-item-id WI-168 -->
 
 | バリデータ | コード | 検出対象 |
 |-----------|--------|---------|
 | drift-detect | L4-001 | 設計にあるがコードにない / コードにあるが設計にない双方向乖離 |
 | consistency-check | L4-002 | 文書間のレイヤー整合性の破綻 |
 | dead-code | L4-003 | 未使用エクスポート、到達不能コード |
+| doc-freshness | L4-004 | 設計文書の freshness threshold 超過 |
+| pointer-validation | L4-005 | 設計文書 pointer の owner/type/source/severity/nextAction 付き検証 |
 
 ### 技術的実装
 
@@ -28,7 +30,7 @@ L4（Scheduled）で以下の3バリデータを週次で実行する。
 
 - 設計-実装の乖離が週次で自動検出される
 - 未使用コードの蓄積が防止される
-- strict プリセットでのみ L4 が有効（standard/minimal ではスキップ）
+- L4 は default-off の scheduled/advisory 層として扱い、strict または明示 `validate --layer L4` で実行できる。fail-on-warning policy がない限り warning-only findings は gate failure へ昇格しない。
 
 ## 関連要件
 

package/docs/ADR/ADR-013-story-reflection-gate.md

@@ -16,7 +16,7 @@ Phase Gate（L2-001）は設計文書の**存在**を検証するが、inception
 
 ## Decision
 
-`phaseDependencies.storyReflection` を導入し、**実装着手時（`src/` / `scripts/harness/` への Write/Edit）に inception → product 反映を機械的に検証**する。
+`phaseDependencies.storyReflection` を導入し、**実装着手時（`src/` / `scripts/harness/` への Write/Edit）に inception → product 反映を機械的に検証**する。現行の新規 reflection は `@work-item-id WI-XXX` を正とし、既存の `@story-id HXX-XX` / `@story-id US-XXX` は WI frontmatter の `legacy_id` 経由で履歴として解決する。<!-- @work-item-id WI-155 -->
 
 ### 設計原則
 
@@ -72,7 +72,7 @@ inception/order/US-002/logical_design.md は存在しますが、
 ### 関連コンポーネント
 
 - `PhaseConfigProviderPort.getStoryReflectionConfig()` — プリセット + config から有効な mappings を解決
-- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@story-id` 検索
+- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@work-item-id` / legacy `@story-id` 検索
 - `HandlePreToolUseUseCase` — src/ への Write 発火時に storyReflection チェックを呼び出し、未反映ならブロック
 - Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和される（§4.6）
 

package/docs/guide/cli-reference.md

@@ -23,10 +23,12 @@ Command names in this document are split into three surfaces:
 | Command | Description |
 |---|---|
 | `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Options: `--preset <full\|standard\|minimal\|custom>`, `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--yes`. |
-| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. `--force` replaces managed targets after backup. |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, create selected `AGENTS.md` / `CLAUDE.md` managed sections, and write `.phasegate/manifest.json`. `--agent <claude\|codex\|both>`, `--skills <core\|all>`, and `--workflow <standard\|strict>` affect rendered agent context; `--force` replaces managed targets after backup. |
 | `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). `--report-out` writes exactly to the supplied path, not to `reporting.outputDir`. |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`; `--force` handles managed conflict cases. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
+| `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
+| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict>`, `--dry-run`, `--json`. <!-- @work-item-id WI-173 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
 | `scaffold-wi <unit> <type>` | Create `docs/inception/{unit}/WI-XXX/description.md` using the next free WI number. |
 | `emit-agent-rules` | Print the AGENTS.md / CLAUDE.md WI workflow rules block. |
@@ -374,7 +376,7 @@ ISSUE-005 P3-10 で明確化された境界:
 |---|---|---|
 | `ci:generate-template` | `--preset <id>`（省略時 `standard`） `--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 |
+| `ci:auto-refresh-agent-context` | `--dry-run` `--apply` `--json` | Refresh AGENTS.md lesson pointers in a dedicated section and CLAUDE.md standard sections without replacing user-owned agent instructions |
 | `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/guide/configuration.md

@@ -8,6 +8,15 @@ This file is the **Single Source of Truth** for all quality configuration in a P
 
 It is not the whole setup state. Hook JSON, Husky scripts, CI workflow files, skill links, `.phasegate/manifest.json`, runtime reports, and Codex user-level feature flags are tracked separately. Use [Setup Artifacts](setup-artifacts.md) when auditing whether a project is fully installed. <!-- @work-item-id WI-152 -->
 
+For agent-assisted changes, preview the intent before editing the config:
+
+```bash
+npx phasegate config:plan --intent l4-strict --dry-run --json
+npx phasegate config:plan --intent quick-mode-strict --dry-run --json
+```
+
+The plan identifies target fields, managed artifacts, commands, validation, risks, and rollback so an agent can explain the change before applying it. <!-- @work-item-id WI-173 -->
+
 ### Full Reference
 
 ```jsonc

package/docs/guide/getting-started.md

@@ -0,0 +1,64 @@
+# Getting Started
+
+<!-- @work-item-id WI-171 -->
+
+Use this page when you want the shortest path from "PhaseGate is installed" to "the next command is obvious".
+
+## First Run
+
+Start with one question: what kind of repository are you setting up?
+
+| Answer | Command | Success state |
+|---|---|---|
+| New project with agent hooks | `npx phasegate init --name <project> --agent both --with-husky --with-ci` | `phasegate.config.json`, skills, hooks, agent context files, Husky, and CI targets exist |
+| Existing repository | `npx phasegate install --dry-run` then `npx phasegate install --apply` | Existing hooks/scripts are preserved and `.phasegate/manifest.json` records managed targets |
+| CI-only rollout | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` | The plan explains CI changes without requiring local hooks |
+| Codex-only project | `npx phasegate init --agent codex --with-husky` | `.codex/hooks.json`, `AGENTS.md`, `.codex/skills`, and pre-commit backstop are present |
+| Strict validation rollout | `npx phasegate setup:agent --intent strict --dry-run --json` | The plan lists strict checks, L4 risk, rollback, and validation commands |
+
+After any setup path:
+
+```bash
+npx phasegate doctor
+npx phasegate phasegate:check-ready
+npx phasegate validate --layer L2 --format human
+```
+
+The first successful run is:
+
+- `doctor` has no unexpected red finding for the targets you chose.
+- `phasegate:check-ready` exits successfully.
+- L2 validators pass or report only issues you intentionally left for a later rollout.
+- The active agent can read `AGENTS.md` or `CLAUDE.md` and see the PhaseGate managed instructions.
+
+## Daily Use
+
+```bash
+npx phasegate work-items:status --dry-run
+npx phasegate validate --layer L2 --format human
+npx phasegate phasegate:status --json
+```
+
+Use `work-items:status` before commit when a WI is close to completion. Use `phasegate:status --json` when an agent needs machine-readable hook, baseline, and validator health.
+
+## Agent Use
+
+```bash
+npx phasegate setup:agent --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+`setup:agent` reads repository setup state and returns missing targets, questions, risk, rollback, and validation steps. `config:plan` maps natural-language change intents such as "enable Codex hooks" or "make L4 stricter" to concrete files, commands, and checks.
+
+## CI Use
+
+```bash
+npx phasegate ci:generate-template --type aidlc-gate --render
+npx phasegate validate --layer all --format ci
+```
+
+For warning-as-failure rollout, preview the change first:
+
+```bash
+npx phasegate config:plan --intent ci-fail-on-warning --dry-run --json
+```

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.152.7"
+    "phasegate": "^0.152.9"
   }
 }
 ```
@@ -38,7 +38,7 @@ npx phasegate init --name <project-name>
 
 This deploys 30 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
 
-`init` is the legacy-compatible bootstrap path for new projects. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved.
+`init` is the legacy-compatible bootstrap path for new projects. It also runs the structured install path for the selected agent target so `CLAUDE.md` and/or `AGENTS.md` receive a PhaseGate managed section. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved. <!-- @work-item-id WI-174 -->
 
 For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
 
@@ -56,7 +56,16 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
+`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 -->
+
+For agent-readable planning before writing files:
+
+```bash
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate setup:agent --intent strict --with-ci --with-husky --dry-run --json
+```
+
+The setup plan includes detected state, questions, planned changes, risks, rollback, and validation commands. <!-- @work-item-id WI-172 -->
 
 If a managed update must replace existing custom content, use:
 
@@ -73,7 +82,7 @@ npx phasegate uninstall --dry-run
 npx phasegate uninstall --apply
 ```
 
-`uninstall` reads `.phasegate/manifest.json`, deletes files that PhaseGate created, removes only PhaseGate-managed portions from merged JSON, Husky, and `package.json` files, and archives the manifest as `.phasegate/uninstalled-<timestamp>.json`. If a managed file was modified after install, `uninstall --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/uninstall-<timestamp>/`.
+`uninstall` reads `.phasegate/manifest.json`, deletes files that PhaseGate created, removes only PhaseGate-managed portions from merged JSON, markdown agent context files, Husky, and `package.json` files, and archives the manifest as `.phasegate/uninstalled-<timestamp>.json`. If a managed file was modified after install, `uninstall --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/uninstall-<timestamp>/`. <!-- @work-item-id WI-174 -->
 
 After upgrading PhaseGate, reconcile existing managed files with the bundled templates from the new version:
 

package/docs/guide/recipes.md

@@ -0,0 +1,65 @@
+# Recipes
+
+<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
+## First-Run Recipe
+
+```bash
+npm install --save-dev phasegate
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate install --apply
+npx phasegate doctor
+```
+
+Use this when you want an existing repository to keep user-owned hooks, scripts, and CI files. The dry-run explains the managed targets before any file is written.
+
+## Retrofit Recipe
+
+```bash
+npx phasegate setup:agent --intent retrofit --dry-run --json
+npx phasegate install --dry-run
+npx phasegate install --apply
+npx phasegate baseline --dry-run
+```
+
+Use this when a repository already has meaningful history or custom automation. Treat any refused target as an agent-assisted review task instead of forcing it blindly.
+
+## Agent Hooks Recipe
+
+```bash
+npx phasegate setup:agent --intent agent-hooks --agent both --with-husky --dry-run --json
+npx phasegate install --agent both --apply
+codex features enable codex_hooks
+npx phasegate doctor --json
+```
+
+The repository-managed portion covers `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, skills links, and the Husky backstop. The Codex user-level feature flag remains a local manual setting.
+
+## CI Recipe
+
+```bash
+npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json
+npx phasegate install --apply
+npx phasegate ci:generate-template --type aidlc-gate --render
+```
+
+Use this when local hooks are not part of the rollout. The plan still includes validation and rollback steps so the agent can explain what changed.
+
+## Strict L4 Recipe
+
+```bash
+npx phasegate config:plan --intent l4-strict --dry-run --json
+npx phasegate validate --layer L4 --fail-on-warning --format human
+```
+
+Only enable fail-on-warning after reviewing the drift, consistency, dead-code, pointer, and freshness findings. The plan output identifies the config fields and validations the agent should cite in its change summary.
+
+## Configuration Change Recipe
+
+```bash
+npx phasegate config:plan --intent quick-mode-strict --dry-run --json
+npx phasegate check-change-category --paths <changed-files> --format json
+npx phasegate ci-check --quick --dry-run
+```
+
+Use `config:plan` before changing `phasegate.config.json`. It separates repo-managed artifacts from user-level settings and lists the checks needed after the change.

package/docs/guide/setup-artifacts.md

@@ -10,7 +10,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
 | Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init`; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
@@ -22,12 +22,15 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 `install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
 
 - Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- Agent context files: `CLAUDE.md` and `AGENTS.md` managed sections. `AGENT.md` singular is not a PhaseGate managed target; treat it as user-owned content or migrate it manually. <!-- @work-item-id WI-174 -->
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
 - Agent skill links: `.claude/skills`, `.codex/skills`
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
 - Manifest: `.phasegate/manifest.json`
 
+`AGENTS.md` has two PhaseGate sections with separate ownership. `<!-- phasegate:managed-section:start -->` contains standard setup/WI workflow instructions. `<!-- phasegate:lesson-pointers:start -->` is reserved for `ci:auto-refresh-agent-context` lesson pointers. Refreshing lesson pointers must not replace the standard managed section or user-owned content. <!-- @work-item-id WI-174 -->
+
 `init --with-ci` still deploys the legacy-compatible template set, including `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml`. Structured `install` uses `.github/workflows/phasegate-aidlc-gate.yml` so it can coexist with existing project CI without taking over a generic workflow filename.
 
 ## Doctor Findings
@@ -53,6 +56,23 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 - `.harness/reports` is a legacy fallback used only when a phase-dependency provider cannot resolve project config.
 - `.phasegate/hook-skip-events.jsonl` records hook bypass/skip observations for diagnosis; it is runtime state, not a managed install target.
 
+## Hook Skip Events
+
+<!-- @work-item-id WI-166 -->
+
+`.phasegate/hook-skip-events.jsonl` is a best-effort JSON Lines runtime log written by agent hooks when a hook intentionally skips or cannot complete its normal validation path. Each record is diagnostic evidence for `phasegate status --json`, not a gate result by itself.
+
+Typical fields are:
+
+| Field | Meaning |
+|---|---|
+| `hookType` | Hook family, for example `PostToolUse` or `Stop`. |
+| `reason` | Stable skip reason such as disabled hook, reentry detection, timeout, or unsupported native pre-edit path. |
+| `targetPaths` | Files or paths relevant to the hook event when available. |
+| `timestamp` | Event time in ISO format. |
+
+Recording is best-effort. A write failure must not change the original hook exit code. Operators should use the latest skip event and counts in `phasegate status --json` to decide whether to run `phasegate doctor`, refresh hooks with `reconcile`, enable Codex hook support, or rely on the L2 pre-commit backstop for edits that native hooks cannot observe before mutation.
+
 ## Legacy Retirement
 
 Current setup does not require `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, or `.harness/context-priority.json`. Treat them as project-local compatibility artifacts. Before deleting them, check whether an archived workflow or local script still references them; otherwise prefer documenting them as retired rather than wiring new guidance around them.

package/docs/guide/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting
+
+<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
+Start with:
+
+```bash
+npx phasegate doctor --json
+```
+
+Each finding has a severity, a repair mode, and optional next-step fields.
+
+| Field | Meaning |
+|---|---|
+| `severity` | `red` blocks the expected setup state; `warn` needs review but may be acceptable for partial rollout |
+| `repairMode` | `mechanical` can be handled by PhaseGate commands; `ai-assisted` needs an agent to preserve user intent; `manual` needs human review |
+| `repairHint` | Copyable command for mechanical repair |
+| `suggestedSkill` | Agent skill to invoke when a merge or setup choice needs reasoning |
+
+## Common Findings
+
+| Finding | First action |
+|---|---|
+| `claude-hook-missing` | `npx phasegate install --agent claude --dry-run` |
+| `codex-hook-missing` | `npx phasegate install --agent codex --dry-run` |
+| `husky-pre-commit-missing` | `npx phasegate setup:agent --intent agent-hooks --with-husky --dry-run --json` |
+| `ci-workflow-missing` | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` |
+| agent context drift | `npx phasegate reconcile --dry-run` |
+
+## Refused Managed Target
+
+If `install`, `reconcile`, or `uninstall` refuses a target, do not immediately force it. Inspect the diff and ask the agent to explain:
+
+- which file is repo-managed and which part is user-owned;
+- why the target cannot be merged mechanically;
+- what backup and rollback path will exist if `--force` is used;
+- which validation commands will be run afterward.
+
+## Codex Hooks Do Not Fire
+
+Check both project and user-level state:
+
+```bash
+npx phasegate doctor --json
+codex features enable codex_hooks
+npx phasegate phasegate:status --json
+```
+
+Native Codex `apply_patch` writes are validated by the pre-commit backstop. Bash-based writes can be blocked before execution when hooks are enabled.
+
+## Agent Setup Is Ambiguous
+
+Use the planner instead of guessing:
+
+```bash
+npx phasegate setup:agent --intent retrofit --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+The planner output is intentionally agent-readable: detected state, questions, planned targets, risks, rollback, and validation commands are all explicit.

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

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+<!-- @work-item-id WI-174 -->
+
+<!-- phasegate:managed-section:start -->
+## PhaseGate Managed Instructions
+
+### Required Documents
+
+- `docs/folder_management_rules.md`
+- `docs/principles/architecture-philosophy.md`
+- `docs/principles/testing-rules.md`
+
+### Workflow
+
+- Create or update the relevant `docs/inception/**/WI-XXX/` work item before planning, design, implementation, or tests.
+- Reflect accepted design into `docs/product/...` with `@work-item-id WI-XXX` before changing source files.
+- Run the relevant PhaseGate checks after changing docs, source, hooks, skills, or setup artifacts.
+- Do not bypass git hooks unless the user explicitly approves the reason, residual risk, and replacement validation.
+
+### Setup State
+
+- Agent target: `{{PHASEGATE_AGENT}}`
+- Skill set: `{{PHASEGATE_SKILLS_MODE}}`
+- Workflow mode: `{{PHASEGATE_WORKFLOW}}`
+- Husky hooks: `{{PHASEGATE_HUSKY_STATE}}`
+- CI workflow: `{{PHASEGATE_CI_STATE}}`
+
+### Common Commands
+
+{{PHASEGATE_COMMANDS}}
+
+### Codex Notes
+
+- Enable native hook execution with `codex features enable codex_hooks` when Codex hooks are installed.
+- Keep local-only Codex settings outside repository-managed targets unless PhaseGate explicitly reports them as managed.
+<!-- phasegate:managed-section:end -->
+
+<!-- phasegate:lesson-pointers:start -->
+<!-- lesson pointers are managed by phasegate ci:auto-refresh-agent-context -->
+<!-- phasegate:lesson-pointers:end -->
+
+<!-- phasegate:user-section:start -->
+Project-specific agent instructions go here.
+<!-- phasegate:user-section:end -->

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

@@ -1,5 +1,8 @@
 # CLAUDE.md
 
+<!-- @work-item-id WI-174 -->
+
+<!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
 
 - `docs/folder_management_rules.md`
@@ -27,3 +30,4 @@
 ## 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.
+<!-- phasegate:managed-section:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.7",
+  "version": "0.152.9",
   "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/infrastructure/adapters/agents-md-file-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit ci-governance
+ * @work-item-id WI-174
  *
  * AgentsMdPort実装（AGENTS.mdファイルI/O）
  */
@@ -13,6 +14,7 @@ import { PointerEntry } from '../../domain/value-objects/pointer-entry.js';
 
 export class AgentsMdFileAdapter implements AgentsMdPort {
   private readonly filePath: string;
+  private lastReadContent: string | null = null;
 
   constructor(baseDir: string) {
     this.filePath = path.join(baseDir, 'AGENTS.md');
@@ -21,8 +23,10 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
   async read(): Promise<AgentsMdPointer> {
     try {
       const content = await fs.readFile(this.filePath, 'utf-8');
+      this.lastReadContent = content;
       return this.parseAgentsMd(content);
     } catch {
+      this.lastReadContent = null;
       return AgentsMdPointer.create();
     }
   }
@@ -36,7 +40,7 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
       before = 0;
     }
 
-    const content = this.serializeAgentsMd(pointer);
+    const content = this.serializeAgentsMd(pointer, this.lastReadContent ?? null);
     await fs.writeFile(this.filePath, content, 'utf-8');
     const after = content.split('\n').length;
 
@@ -81,11 +85,28 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
     return AgentsMdPointer.create(pointers, adrLinks);
   }
 
-  private serializeAgentsMd(pointer: AgentsMdPointer): string {
-    const lines: string[] = ['# AGENTS.md', ''];
+  private serializeAgentsMd(pointer: AgentsMdPointer, existing: string | null): string {
+    const section = this.serializeLessonPointerSection(pointer);
+    if (existing !== null && existing.trim().length > 0) {
+      const start = '<!-- phasegate:lesson-pointers:start -->';
+      const end = '<!-- phasegate:lesson-pointers:end -->';
+      const pattern = new RegExp(`${this.escapeRegExp(start)}[\\s\\S]*?${this.escapeRegExp(end)}`);
+      if (pattern.test(existing)) {
+        return existing.replace(pattern, section.trim()).replace(/\s*$/, '\n');
+      }
+      return `${existing.replace(/\s*$/, '\n\n')}${section}`;
+    }
+    return ['# AGENTS.md', '', section].join('\n');
+  }
+
+  private serializeLessonPointerSection(pointer: AgentsMdPointer): string {
+    const lines: string[] = [
+      '<!-- phasegate:lesson-pointers:start -->',
+      '## PhaseGate Lesson Pointers',
+      '',
+    ];
 
     if (pointer.pointers.length > 0) {
-      lines.push('## Pointers', '');
       for (const entry of pointer.pointers) {
         if (entry.isCommand()) {
           lines.push(`- [cmd:${entry.key}](${entry.command ?? ''}) ${entry.description}`);
@@ -97,13 +118,18 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
     }
 
     if (pointer.adrLinks.length > 0) {
-      lines.push('## ADR Links', '');
+      lines.push('### ADR Links', '');
       for (const adr of pointer.adrLinks) {
         lines.push(`- ADR: ${adr}`);
       }
       lines.push('');
     }
 
+    lines.push('<!-- phasegate:lesson-pointers:end -->', '');
     return lines.join('\n');
   }
+
+  private escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
 }