phasegate 0.152.2 → 0.152.6

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.6] - 2026-05-13
+
+### Changed
+
+- **WI-152 / WI-153 / WI-154 / WI-157 / WI-169 — setup lifecycle documentation refresh** — adds the setup artifact inventory, aligns installation product construction docs with the current doctor/install/reconcile contract, refreshes bundled setup guidance skills, and modernizes developer skill documentation before publish prep.
+
+## [0.152.3] - 2026-05-12
+
+### Fixed
+
+- **Historical WI status closure / WI-012 / WI-027 / WI-035 / WI-036 / WI-085 / WI-086 / WI-087 / WI-088 / WI-089 / WI-090 / WI-091 / WI-092 / WI-093 / WI-096** — completes missing product reflection and implementation traceability evidence for the remaining targeted historical WI backlog, then applies derived statuses for fix/chore items so the target set no longer reports stale.
+
 ## [0.152.2] - 2026-05-12
 
 ### Fixed

package/README.md

@@ -492,40 +492,53 @@ Because Codex's native `apply_patch` tool is routed through an internal `ApplyPa
 
 ## CLI Reference
 
+<!-- @work-item-id WI-150 -->
+
 ```bash
 npx phasegate <command> [options]
 ```
 
+README keeps only the entry points most users need. The full public/compatibility/internal catalog, including commands shown by `phasegate --help`, lives in [CLI Reference](docs/guide/cli-reference.md).
+
 | Command | Description |
 |---|---|
-| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Prefer `install` when the project may already have hooks, scripts, or CI files. |
-| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into the current project, preserve existing user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. |
-| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects. Supports `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--with-husky`, `--with-ci`, and `--yes`. Prefer `install` when the project may already have hooks, scripts, or CI files. |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into the current project, preserve existing user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. Use `--force` only for managed-file replacement. |
+| `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. |
-| `lint` | Run L1 Biome AST checks |
-| `validate --layer <L1-L4\|all>` | Run validators for specified layer (`--layer L0` prints runtime hook guidance; explicit L4 runs even when scheduled L4 is disabled) |
-| `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
+| `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`. |
 | `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` | Compatibility alias for `reconcile` |
-| `phasegate:status` | Display overall harness health summary |
+| `phasegate:status --json` | Display overall harness health summary, including configuration, cached artifact, and live validation state where available |
+| `phasegate:detect-drift --json` | Design/code drift summary. Drift findings are advisory unless strict warning handling is enabled. |
 | `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter. Apply refuses downgrades unless `--allow-downgrade` is supplied. |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
 | `check-change-category --paths <csv>` | Classify changed files into Quick Mode categories and report whether Full Mode is required (`--format json`, `--fail-on-full-required`) |
 | `baseline` | Create `.phasegate/baseline.json` snapshot for Phase A-2 retrofit grandfather (`--dry-run`, `--force`, `--paths <glob,glob,...>`, `--json`). `baseline.enabled` defaults to `true` since v0.71.0. |
 | `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | Generate minimum viable design doc from `templates/*.template.md` into `docs/product/construction/{unit}/*.md` (`--force`, `--json`). Materializes the `scaffold: ...` line emitted by phase-gate errors. |
+| `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. |
 | `list-errors --layer <L0-L4>` | List error definitions with fix examples |
-| `hook <pre-tool-use\|post-tool-use\|stop>` | Run a Claude Code hook (reads JSON from stdin) |
+| `hook <pre-tool-use\|post-tool-use\|stop\|session-start\|user-prompt-submit>` | Run an agent hook (reads JSON from stdin; session-start/user-prompt-submit write JSON context) |
 | `pre-commit` | Run L2 pre-commit validators on staged files |
 | `bypass:audit --base <ref> [--head <ref>]` | Replay pre-commit validation over a push/CI range and require structured bypass evidence for gate failures |
 | `delegate-sonnet [...args]` | Delegate task to Sonnet 4.6 (transparent wrapper) |
 | `migrate work-items --dry-run` / `--apply` | Migrate legacy `ISSUE-XXX` / `H{NN}-{NN}` directories under `docs/inception/` to the unified `WI-XXX` layout (frontmatter `type` / `legacy_id` / `affects` injected). Sequential allocator skips numbers already used by existing WIs. See [CLI Reference -- Work Item Migration](docs/guide/cli-reference.md#work-item-migration). |
 | `migrate --schema v3` | Upgrade `phasegate.config.json` to v3 schema by adding the `architecture` key (idempotent). |
 
-See the [Japanese README](README.ja.md) for the complete CLI reference.
+### L4 warnings and strictness
+
+<!-- @work-item-id WI-151 -->
+
+Standard projects keep `layers.L4.enabled: false`; `validate --layer all` and `phasegate:ci-check` report disabled L4 validators as skipped. Explicit `validate --layer L4` runs the scheduled validators on demand. Warning-only L4 drift/consistency/dead-code findings remain advisory unless `validate.failOnWarning: true`, the `strict` preset, or `--fail-on-warning` is used. Use that strict mode only after the project has real drift keys, consistency targets, pointer/freshness ownership, and semantic drift coverage.
+
+See the [CLI Reference](docs/guide/cli-reference.md) for the complete catalog and the [Japanese README](README.ja.md) for Japanese-language onboarding.
 
 ---
 

package/docs/guide/cli-reference.md

@@ -6,22 +6,42 @@ Entry point:
 npx phasegate <command> [options]
 ```
 
+<!-- @work-item-id WI-150 -->
+
+Command names in this document are split into three surfaces:
+
+| Surface | How to run | Contract |
+|---|---|---|
+| Binary subcommand | `npx phasegate <command>` | Public CLI shipped by the package. This includes `phasegate:*` compatibility subcommands shown by `phasegate --help`. |
+| npm script | `npm run <script>` / `pnpm <script>` | Only available when the consuming project's `package.json` defines that script. The package itself currently defines `phasegate`, `phasegate:status`, `phasegate:enable`, `phasegate:disable`, `phasegate:check-phase`, `phasegate:check-ready`, and `harness:*` aliases. |
+| Internal / compatibility | `npx phasegate <command>` | Supported for migration, dogfooding, or legacy workflows; prefer the canonical command listed in the description when one exists. |
+
 ---
 
 ## Setup
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI |
-| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, and write `.phasegate/manifest.json` |
-| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`) |
-| `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json` |
-| `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes |
-| `update-skills` | Compatibility alias for `reconcile` |
+| `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. |
+| `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. |
+| `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. |
 | `list-features` | List available features |
 | `enable-feature <name>` | Enable a feature |
 | `disable-feature <name>` | Disable a feature |
 
+### Setup JSON and report outputs
+
+<!-- @work-item-id WI-158 -->
+
+Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --report-out <path>` persists the doctor JSON payload to that exact path. Relative paths are resolved from the project root; absolute paths are used as-is.
+
+This is separate from `reporting.outputDir`. The configured report directory is used by phase-dependency / phase-gate reporting, while regression-suite result files are fixed under `reports/regression/` and status/drift JSON is emitted to stdout.
+
 ---
 
 ## Quality Checks
@@ -29,8 +49,8 @@ npx phasegate <command> [options]
 | Command | Options | Description |
 |---|---|---|
 | `lint` | `--target <path>` `--json` | L1 Biome AST check |
-| `validate` | `--layer L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` | L2-L4 validators |
-| `ci-check` | `--quick` `--fail-on-reject` `--dry-run` `--files` | Full CI check (L2-L4) |
+| `validate` | `--layer L0\|L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` `--fail-on-warning` `--no-fail-on-warning` `--no-l4` | Validators. `--layer L0` prints runtime hook guidance. Explicit `--layer L4` runs L4 on demand; `all` and CI-style execution honor disabled L4 unless overridden by command-specific behavior. |
+| `ci-check` | `--quick` `--fail-on-reject` `--dry-run` `--files` | Full CI check (L2-L4). `--quick` applies Quick Mode relaxation policy, `--fail-on-reject` turns a rejected quick decision into a failing exit, `--dry-run` reports without enforcing, and `--files` supplies the changed-file set. |
 | `validate-metadata <files>` | | Validate implementation metadata |
 | `check-phase-gate` | `--level 1\|2\|3` | Phase gate check |
 
@@ -258,7 +278,9 @@ unit-scoped WI（H-ID 由来）の reflection check でも継続認識される
 
 ## Harness API
 
-Commands exposed as npm scripts (`npm run <command>`).
+<!-- @work-item-id WI-150 -->
+
+The following are binary subcommands (`npx phasegate <command>`). Do not assume they are npm scripts unless the consuming project defines a matching `package.json` script. In this package, only `phasegate:status`, `phasegate:check-ready`, and `phasegate:check-phase` are currently exposed as package scripts among the `phasegate:*` commands.
 
 | Command | Options | Description |
 |---|---|---|
@@ -270,6 +292,23 @@ Commands exposed as npm scripts (`npm run <command>`).
 | `phasegate:lint` | `--target <path>` `--json` | Lint via harness-api |
 | `phasegate:complete-check` | `--json` | L2-L4 full check |
 | `phasegate:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
+| `phasegate:generate-matrix` | `--requirements <path>` `--tests <path>` `--out <path>` `--json` | Generate the requirement-test matrix |
+
+### Status and drift JSON semantics
+
+<!-- @work-item-id WI-151 -->
+
+`phasegate:status --json` is intended for humans, CI, and agents that need to distinguish configured intent from observed results. Layer entries may include:
+
+| Key | Meaning | How to use it |
+|---|---|---|
+| `configurationState` | Whether the layer is enabled by resolved config (`enabled` / `disabled`) | Use this to explain why a layer should run or be skipped. |
+| `cachedArtifactState` | Whether a previously generated artifact/report is present (`present` / `missing`) | Use this to decide whether a report needs to be generated before relying on cached evidence. `missing` means no artifact exists; it is not the same as a validator limitation. |
+| `liveValidationState` | Result of the current live check (`pass` / `fail` / `skipped`) | Use this as the current gate signal. `skipped` usually follows disabled configuration. |
+
+`phasegate:detect-drift --json` returns drift findings from live design/code comparison. A finding with a real mismatch is different from a validator `limitation`: `missing` means expected evidence or artifacts were absent, while `limitation` means the validator cannot currently prove the condition and should be treated as advisory until coverage is improved.
+
+L4 warning findings fail the process only when warning strictness is enabled (`validate.failOnWarning: true`, the `strict` preset, or `--fail-on-warning`). `--no-fail-on-warning` forces advisory behavior for the current command.
 
 ---
 
@@ -334,15 +373,17 @@ ISSUE-005 P3-10 で明確化された境界:
 
 ## Regression Tests
 
+<!-- @work-item-id WI-150, WI-158 -->
+
 | Command | Description |
 |---|---|
-| `regression:run-k-requirements` | K1-K15 non-negotiable requirements |
-| `regression:run-gng-gate` | Go/No-Go Gate 3 quality conditions |
-| `regression:run-agent-guard` | Agent-independence guard |
-| `regression:run-k14-k15` | K14/K15 regression |
-| `regression:configure-ci-gate` | Configure CI gate |
-| `regression:analyze-migration` | Analyze v0 test migration |
-| `regression:migrate-v0-tests` | Execute v0 test migration |
+| `regression:run-k-requirements` | K1-K15 non-negotiable requirements. Writes suite result JSON under fixed `reports/regression/`. |
+| `regression:run-gng-gate` | Go/No-Go Gate 3 quality conditions. Writes suite result JSON under fixed `reports/regression/`. |
+| `regression:run-agent-guard` | Agent-independence guard. Writes suite result JSON under fixed `reports/regression/`. |
+| `regression:run-k14-k15` | K14/K15 regression. Writes suite result JSON under fixed `reports/regression/`. |
+| `regression:configure-ci-gate` | Configure CI gate (`--suites <ids>`, `--threshold <n>`). |
+| `regression:analyze-migration` | Analyze v0 test migration (`--dry-run`). |
+| `regression:migrate-v0-tests` | Execute v0 test migration (`--confirm`). |
 
 ---
 
@@ -350,7 +391,7 @@ ISSUE-005 P3-10 で明確化された境界:
 
 | Command | Options | Description |
 |---|---|---|
-| `hooks:config validate` | | Validate `.harness-hooks.yml` |
+| `hooks:config validate` | | Compatibility validator for legacy `.harness-hooks.yml`; new setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate` |
 | `hooks:gate-check` | `--story <id>` | Completion gate check |
 
 ---
@@ -362,6 +403,7 @@ ISSUE-005 P3-10 で明確化された境界:
 | `p2:check-freshness` | `--pattern <glob>` `--dry-run` `--format text\|json` | Compatibility entry point for L4-004 doc freshness; canonical L4 execution is `validate --layer L4` |
 | `p2:validate-pointers` | `--include-urls` `--format text\|json` | Compatibility entry point for L4-005 pointer validation; canonical L4 execution is `validate --layer L4` |
 | `p2:generate-e2e-template` | `--phase <phase>` `--output <path>` | Generate E2E test template |
+| `p2:check-initial-creation` | `--pattern <glob>` `--format text\|json` | Compatibility detector for long-lived `initial_creation: true` docs. |
 
 ### `phasegate:generate-matrix`
 

package/docs/guide/configuration.md

@@ -6,6 +6,8 @@ Place at project root. Generated by `npx phasegate init`.
 
 This file is the **Single Source of Truth** for all quality configuration in a Phasegate project. Every layer validator, skill, and harness behavior reads from this file.
 
+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 -->
+
 ### Full Reference
 
 ```jsonc
@@ -420,10 +422,23 @@ Quick Mode with `relaxedGates: ["phase-gate"]` relaxes `storyReflection` as well
 
 #### `reporting`
 
+<!-- @work-item-id WI-158 -->
+
 | Sub-field   | Type     | Default     | Description                                           |
 |-------------|----------|-------------|-------------------------------------------------------|
 | `format`    | `string` | `"json"`    | Output format for validation reports.                 |
-| `outputDir` | `string` | `"reports"` | Directory where reports are written.                  |
+| `outputDir` | `string` | `"reports"` | Configured report directory used by phase-gate / story-reflection reporting paths and status-derived phase dependency output. |
+
+`reporting.outputDir` is not a blanket sink for every command that writes a file:
+
+| Producer | Output path contract |
+|---|---|
+| Phase dependency / phase-gate reporting | Uses resolved `reporting.outputDir`; if no config can be read by the story-reflection provider, the legacy fallback is `.harness/reports`. |
+| `doctor --report-out <path>` | Writes exactly to `<path>` relative to the project root, or to the absolute path supplied. It does not derive a path from `reporting.outputDir`. |
+| `phasegate:status --json` / `phasegate:detect-drift --json` | Writes to stdout. Redirect explicitly if a persisted report is needed. |
+| `regression:*` suites | Write CI gate result JSON under fixed `reports/regression/`; this is a regression-suite contract and currently does not consult `reporting.outputDir`. |
+
+Use `reports/` as the canonical default for project-visible reports. Treat `.harness/reports` as a legacy fallback used only where the phase-dependency provider has no resolved config.
 
 #### `validate` (severity policy, ADR-017 / WI-094)
 
@@ -548,6 +563,8 @@ If you move your design documents to a non-default location, update `paths` acco
 
 **How paths flow into the L2 phase-gate validator (since v0.117.0 / WI-085):**
 
+<!-- @work-item-id WI-149 -->
+
 `STANDARD_PHASE_NODES` / `FULL_PHASE_NODES` / `MINIMAL_PHASE_NODES` express artifact locations using two placeholders, expanded at validation time from `paths`:
 
 | Placeholder | Resolved from | Default |
@@ -555,7 +572,7 @@ If you move your design documents to a non-default location, update `paths` acco
 | `{designDocsRoot}` | `paths.designDocs` | `docs/product/construction` |
 | `{inceptionDocsRoot}` | `paths.inceptionDocs` | `docs/inception` |
 
-Setting `paths.designDocs` to `mydocs/product/construction` makes the L2 phase-gate require `mydocs/product/construction/{unit}/domain_model.md` instead of the default. Default values match the v0.115.0 layout for full backward compatibility.
+Setting `paths.designDocs` to `mydocs/product/construction` makes the L2 phase-gate require `mydocs/product/construction/{unit}/domain_model.md` instead of the default. This setting points to the construction subtree, not the broader product root; product-wide artifacts under `docs/product/` stay literal unless you define a custom `phaseDependencies.gates[]` preset. Default values match the v0.115.0 layout for full backward compatibility.
 
 **Out of scope (paths handled by literal references):**
 

package/docs/guide/hooks-integration.md

@@ -4,6 +4,8 @@ Phasegate integrates natively with Claude Code through its hooks system. This en
 
 ## Setup
 
+For new or existing projects, prefer `npx phasegate install --dry-run` followed by `npx phasegate install --apply` so existing hook JSON is merged instead of replaced. Manual editing is still possible, but then `phasegate doctor` may report missing managed targets until the expected PhaseGate entries, skill links, Husky scripts, CI workflow, and manifest are present. See [Setup Artifacts](setup-artifacts.md). <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
+
 Add the following to `.claude/settings.json`:
 
 ```jsonc
@@ -94,6 +96,14 @@ Use /quick-implementor skill for version changes in package.json.
 - By default, the hook exits with the inner CLI's exit code, which Claude Code shows as a transcript warning but does not turn-block on.
 - Set `agentIntegration.stopHook.enforce: true` in `phasegate.config.json` to enable **strict mode**: on Complete Check failure, the hook emits `{"decision":"block","reason":"Complete Check failed (exitCode=N)"}` on stdout and exits with code 2, hard-blocking Claude Code's turn end. Reentry-detection still exits 0 regardless of this setting. See `docs/guide/configuration.md` `agentIntegration` section for details.
 
+## Git hook metadata validation
+
+<!-- @work-item-id WI-149 -->
+
+When installed with Husky, `.husky/pre-commit` invokes `npx phasegate pre-commit`. That path runs the same L2 pre-commit contract used by CI and includes staged Markdown metadata validation in addition to implementation metadata checks. In practice, staged `docs/inception/**/description.md` files are checked for WI frontmatter shape, `docs/product/**` reflection updates are checked for `@work-item-id WI-XXX`, and staged implementation/test files are checked for source metadata.
+
+`validate-metadata <files>` remains available as a direct metadata command, but the public pre-commit contract for users is `phasegate pre-commit`; do not wire a separate Markdown metadata hook unless you have a project-specific reason.
+
 ## Optional Shell Script Hooks
 
 Additional hooks can be placed in `.claude/scripts/`:
@@ -122,3 +132,5 @@ Additional hooks can be placed in `.claude/scripts/`:
 | targetDirs | Directories where hooks apply (relative to project root) | [] (skip if empty) |
 | formatter | "biome" or "eslint-prettier" | "biome" |
 | formatterArgs | Arguments passed to formatter | ["check", "--write"] |
+
+Legacy `.harness-hooks.yml` and old Fuse hook files are not part of the current install lifecycle. Keep them only for archived integrations; new setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate`. <!-- @work-item-id WI-157 -->

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.147.0"
+    "phasegate": "^0.152.6"
   }
 }
 ```
@@ -56,7 +56,7 @@ 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 the CI workflow when missing, and records managed entries in `.phasegate/manifest.json`.
+`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 -->
 
 If a managed update must replace existing custom content, use:
 
@@ -116,6 +116,8 @@ npx phasegate reconcile --apply
 
 `phasegate update-skills` remains available as a compatibility alias, but `reconcile` is the preferred upgrade path because it updates all managed files recorded in `.phasegate/manifest.json`.
 
+`doctor --report-out <path>` writes exactly to the provided path. `.phasegate/last-doctor-report.json` is not a fixed output file unless you choose that path explicitly. <!-- @work-item-id WI-152 -->
+
 ## Recommended .gitignore additions
 
 ```

package/docs/guide/layer-model.md

@@ -102,13 +102,17 @@ npx phasegate lint
 
 ## L2: Pre-commit Validators
 
+<!-- @work-item-id WI-151 -->
+
 L2 validators run before every commit. They enforce process discipline and test quality standards.
 
-| Validator | Description |
-|-----------|-------------|
-| **phase-gate** | Enforces design-before-implementation order. Code changes to `scripts/harness/` are blocked unless the corresponding design documents exist in `docs/product/construction/`. |
-| **metadata** | Verifies completeness of source file annotations: `@unit`, `@layer`, `@US-XXX`, and `@story` |
-| **test-quality** | Enforces test authoring standards through a runner-independent semantic model: AAA pattern (Arrange/Act/Assert), named Act observation, single-act-per-test, assertion strength, lifecycle/E2E exceptions, and no domain/internal mocking in domain layer tests |
+| Validator | ID | Description |
+|-----------|----|-------------|
+| **phase-gate** | L2-001 | Enforces design-before-implementation order. Code changes to `scripts/harness/` are blocked unless the corresponding design documents exist in `docs/product/construction/` or the configured `paths.designDocs` root. |
+| **metadata** | L2-002 | Verifies completeness of source file annotations such as `@unit`, `@layer`, and story/WI metadata. |
+| **test-quality** | L2-003 | Enforces test authoring standards through a runner-independent semantic model: AAA pattern, named Act observation, single-act-per-test, assertion strength, lifecycle/E2E exceptions, and no domain/internal mocking in domain layer tests. |
+| **cli-e2e-test-existence** | L2-013 | Checks that public CLI commands have corresponding CLI/e2e coverage or an explicit documented reason for compatibility/internal handling. |
+| **work-item-status-staleness** | L2-014 | Compares `description.md` frontmatter status with derived artifact evidence and reports stale WI status. |
 
 **Command:**
 
@@ -139,6 +143,8 @@ npx phasegate validate --layer L3
 
 ## L4: Scheduled Validators
 
+<!-- @work-item-id WI-151 -->
+
 L4 validators are designed to run on a weekly schedule and detect slow-moving drift that accumulates over time.
 
 > **Status**: L4 is **disabled by default** (`layers.L4.enabled: false` in `phasegate.config.json`). Projects opt in by flipping the flag and scheduling the command via CI cron (see `ci:generate-template --type consistency-check --render`). Implementation-wise the validators listed below are functional; the default-off state is a conservative rollout choice, not a missing feature. @work-item-id WI-128
@@ -163,6 +169,18 @@ npx phasegate validate --layer L4
 
 Use a weekly cron such as `0 9 * * 1` for the generated consistency-check workflow. Standard projects normally keep L4 default-off and run the scheduled audit as advisory. Strict projects may opt into `layers.L4.enabled: true` and `failOnWarning` behavior when L4 warnings should block promotion. @work-item-id WI-128
 
+### Status and drift states
+
+`phasegate:status --json` separates three ideas that should not be collapsed in CI or agent logic:
+
+| State key | Meaning |
+|---|---|
+| `configurationState` | The resolved config intent for the layer or check. Disabled configuration means the layer should be skipped in aggregate execution. |
+| `cachedArtifactState` | Whether a persisted artifact/report exists. `missing` means no report artifact is available; it is not proof that validation failed. |
+| `liveValidationState` | The current live execution result: pass, fail, or skipped. This is the gate signal to use for current decisions. |
+
+For drift output, treat `missing` and `limitation` differently. `missing` means expected product docs, pointers, reports, or code evidence are absent. `limitation` means the current detector cannot prove the condition even though inputs may exist; keep those findings advisory until detector coverage is improved.
+
 ### Drift-detect design pointers
 
 L4-001 normally matches design headings to code exports by name. When a heading intentionally maps to a differently named implementation file, add a pointer directly under the heading:

package/docs/guide/setup-artifacts.md

@@ -0,0 +1,60 @@
+# Setup Artifacts
+
+PhaseGate setup is more than `phasegate.config.json`. A healthy installation is the combination of project configuration, managed targets, generated state, runtime reports, and a small number of user-level settings.
+
+<!-- @work-item-id WI-152 -->
+<!-- @work-item-id WI-157 -->
+<!-- @work-item-id WI-169 -->
+
+## Artifact Classes
+
+| 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` |
+| 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 |
+| Legacy artifact | `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, `.harness/context-priority.json`, `.harness/reports` fallback | Compatibility only | Not required for current install lifecycle unless a project intentionally keeps an archived integration |
+| User-level setting | Codex CLI `codex_hooks` feature flag | User machine | Must be enabled manually with `codex features enable codex_hooks`; project commands do not modify it |
+
+## Managed Targets
+
+`install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
+
+- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- 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`
+
+`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
+
+`phasegate doctor` evaluates setup health from the managed targets and related project state. Findings include `repairMode`, optional `repairHint`, and optional `suggestedSkill`.
+
+| Field | Meaning |
+|---|---|
+| `repairMode: "mechanical"` | A PhaseGate command can usually fix the target, for example `npx phasegate install --apply` or `--force`. |
+| `repairMode: "ai-assisted"` | Existing user content needs judgment before merging. Doctor includes `suggestedSkill`, usually `phasegate-config-doctor`. |
+| `repairMode: "manual"` | Human review is required, commonly for semantic CI/workflow conflicts. |
+| `repairHint` | Copyable command for mechanical cases. |
+| `suggestedSkill` | Skill name, rationale, and invoke command for agent-assisted repair planning. |
+
+`doctor --report-out <path>` writes exactly to the path you pass. `.phasegate/last-doctor-report.json` is not created automatically; it is only a conventional path you may choose.
+
+## Reports And Runtime Files
+
+`reporting.outputDir` is the default project-visible report directory for phase dependency and phase-gate reports. Some command families have their own contracts:
+
+- `doctor --report-out <path>` writes to the explicit path only.
+- `regression:*` commands write under `reports/regression/`.
+- `.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.
+
+## 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.
+
+`hooks:config validate` is a compatibility command for old `.harness-hooks.yml` projects. New setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.2",
+  "version": "0.152.6",
   "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/config-foundation/domain/harness-config.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit config-foundation
+ * @work-item-id WI-012
  */
 import { ConfigFoundationDomainError } from './errors/config-foundation-domain-error.js';
 import { ConfigValidationError } from './errors/config-validation-error.js';

package/scripts/harness/harness-api/infrastructure/adapters/harness-config-query-adapter.ts

@@ -1,6 +1,7 @@
 // @layer infrastructure
 // @unit harness-api
 // @work-item-id WI-123
+// @work-item-id WI-096
 // harness-config-query-adapter.ts — HarnessConfigQueryAdapter
 
 import * as fs from 'node:fs/promises';

package/scripts/harness/main.ts

@@ -1,6 +1,7 @@
 /**
  * @unit harness-api
  * @layer presentation
+ * @work-item-id WI-090 / WI-091
  * @work-item-id WI-113 / WI-142
  *
  * Phasegate CLI エントリポイント。

package/scripts/harness/phase-dependency-model/domain/values/artifact.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit phase-dependency-model
+ * @work-item-id WI-085
  */
 import path from 'node:path';
 

package/scripts/harness/phase2-extensions/infrastructure/adapters/git-log-document-age-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit phase2-extensions
+ * @work-item-id WI-035
  */
 import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';

package/scripts/harness/phase2-extensions/infrastructure/adapters/git-log-initial-creation-age-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit phase2-extensions
+ * @work-item-id WI-035
  */
 import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';

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

@@ -1,5 +1,6 @@
 // @unit harness-api
 // @layer infrastructure
+// @work-item-id WI-086 / WI-087
 // @work-item-id WI-127
 // Note: import.meta.url を使わず、呼び出し元 (main.ts) がパスを解決して渡す設計。
 

package/scripts/harness/skill-quality/infrastructure/adapters/git-commit-executor-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit skill-quality
+ * @work-item-id WI-036
  */
 import { execFileSync } from 'node:child_process';
 import type { CommitExecutorPort } from '../../domain/ports/commit-executor-port.js';

package/scripts/harness/traceability-model/composition-root.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit traceability-model
+ * @work-item-id WI-093
  *
  * traceability-model ユニットの Composition Root。
  * 全コンポーネントを生成・配線し、外部に公開するハンドラー群を返す。

package/scripts/harness/traceability-model/domain/ports/work-item-migration-source-port.ts

@@ -1,5 +1,6 @@
 // @unit traceability-model
 // @layer domain
+// @work-item-id WI-027
 
 import type { LegacyIssueDirectory } from "../value-objects/work-item-migration-candidate.js";
 

package/scripts/harness/traceability-model/domain/services/work-item-migration-planner.ts

@@ -1,5 +1,6 @@
 // @unit traceability-model
 // @layer domain
+// @work-item-id WI-027
 
 import type {
   LegacyIssueDirectory,

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-migration-source-gateway.ts

@@ -1,5 +1,6 @@
 // @unit traceability-model
 // @layer infrastructure
+// @work-item-id WI-027
 
 import * as fs from "node:fs";
 import { readdir, readFile } from "node:fs/promises";

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-story-catalog-gateway.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit traceability-model
+ * @work-item-id WI-093
  *
  * user_stories.md を読み込み StoryCatalogPort を実装するゲートウェイ
  */

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-091
  * @work-item-id WI-117, WI-118
  *
  * MarkdownDesignDocumentAdapter — DesignDocumentPort実装

package/skills/README.md

@@ -1,21 +1,21 @@
 # Skills ディレクトリ
 
-このディレクトリには、AIエージェントの共有スキル定義が含まれています。
+このディレクトリには、AIエージェントの共有スキル定義が含まれています。現在の配布対象は 30 skills です。公開一覧は `docs/guide/skills-overview.md`、setup lifecycle の管理対象は `docs/guide/setup-artifacts.md` を正とします。<!-- @work-item-id WI-154 -->
 
 ## ディレクトリ構成と同期
 
 このディレクトリはスキルの**唯一の信頼できる情報源 (Single Source of Truth)** です。
-`.agent` と `.claude` の両方の環境から同じスキルにアクセスできるように、各ディレクトリには以下のようなシンボリックリンクが作成されています：
+`.claude` と `.codex` の両方の環境から同じスキルにアクセスできるように、`phasegate install` / `phasegate reconcile` は必要に応じて以下のシンボリックリンクを管理します：
 
-- `.agent/skills` -> `./skills` (プロジェクトルートからの相対パス)
 - `.claude/skills` -> `./skills` (プロジェクトルートからの相対パス)
 - `.codex/skills` -> `./skills` (プロジェクトルートからの相対パス)
 
 技術的には、リンクは以下のように設定されています：
-- `.agent/skills` -> `../skills`
 - `.claude/skills` -> `../skills`
 - `.codex/skills` -> `../skills`
 
+`.agent/skills` は旧 setup 由来の互換パスです。新規導入では管理対象にしません。<!-- @work-item-id WI-157 -->
+
 ## 新しいスキルの追加
 
-新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。シンボリックリンクを通じて、両方のエージェントから自動的に利用可能になります。
+新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。あわせて `docs/guide/skills-overview.md`、README の skill 数、必要なら `skills/phasegate-toolkit-guide/SKILL.md` の参照先を更新します。シンボリックリンクを通じて、対応エージェントから利用可能になります。<!-- @work-item-id WI-154 -->

package/skills/phasegate-config-doctor/SKILL.md

@@ -9,7 +9,7 @@ description: 現在の phasegate.config.json を schema + プロジェクト検
 
 ## このスキルが解決する問題
 
-phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。AI が schema を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。
+phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。さらに setup lifecycle は `phasegate.config.json` だけでは完結せず、manifest、hook JSON、Husky、CI、skill link、doctor finding を合わせて読む必要がある。AI が schema や setup contract を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。<!-- @work-item-id WI-153 -->
 
 ## 設計原則
 
@@ -18,7 +18,7 @@ phasegate を導入した直後の config は単純な default で、実プロ
 3. **AI 推論は判断要素のみ** — architecture preset 選定、relaxedGates 推奨値などは AI が判断するが根拠を必ず示す
 4. **schema は enum 違反確認時のみ Read** — 日常診断は本 SKILL 内の判定基準で十分。schema 全文 Read は値域不明時に限定する
 5. **read-only な Q&A は phasegate-toolkit-guide に委譲** — 「L2 って何？」など概念質問は本 skill スコープ外
-6. **変更後は L2 検証必須** — `npx phasegate validate --layer L2` を走らせてからユーザーに完了報告
+6. **変更後は対象別に検証** — config 変更は `npx phasegate validate --layer L2`、setup lifecycle 変更は `npx phasegate doctor`、hook/script/metadata 変更は `npx phasegate lint` または `npm run phasegate:check-ready` を走らせてからユーザーに完了報告
 
 ## 診断プロセス
 
@@ -33,11 +33,19 @@ phasegate を導入した直後の config は単純な default で、実プロ
 | pnpm workspace | `pnpm-workspace.yaml` (存在すれば) | workspace 検出 |
 | lerna config | `lerna.json` (存在すれば) | workspace 検出 |
 | hook config | `.claude/scripts/hook-config.json` | 既存 hook 設定確認 |
+| doctor report | 明示された report path、またはユーザーが指定した `.phasegate/last-doctor-report.json` | `repairMode` / `repairHint` / `suggestedSkill` の確認 |
+| manifest | `.phasegate/manifest.json` | install / reconcile / uninstall の managed target と hash 状態確認 |
+| Claude hooks | `.claude/settings.json` | managed hook JSON と user customization の確認 |
+| Codex hooks | `.codex/hooks.json` | managed hook JSON と Codex hook 配線確認 |
+| Husky scripts | `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push` | pre-commit backstop と bypass audit の確認 |
+| CI workflows | `.github/workflows/*` | `phasegate-aidlc-gate.yml` や既存 workflow との競合確認 |
 
 **schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
 
 phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/` を `scripts/harness/config-foundation/...` に置換。
 
+`doctor --report-out <path>` は指定された path にだけ書く。`.phasegate/last-doctor-report.json` は固定生成物ではないため、存在しない場合は `npx phasegate doctor --json` を実行して現状を読み取る。<!-- @work-item-id WI-152 -->
+
 ### Step 1.5: Fresh init 判定 (重要)
 
 以下の **全条件** を満たす場合、フル診断は早期。Step 2 に進まず AIDLC 開始を案内する:
@@ -115,6 +123,15 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - `formatter: "biome"` だが `@biomejs/biome` が devDependencies に無い → WARN: prettier に切り替え推奨
 - v0.119 未満で deploy された hook script (bash 4 `mapfile` 使用) → WARN: macOS の bash 3.2 で silent fail。`phasegate init` 再実行で更新
 
+#### 観点 9: setup lifecycle と doctor finding
+
+- `phasegate doctor --json` の finding に `repairMode: "ai-assisted"` と `suggestedSkill.skillName = "phasegate-config-doctor"` がある → 本 skill が merge 方針、保持する user content、実行すべき `install --apply` / `--force` / `reconcile --apply` を提案する
+- `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
+- manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示
+- reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る
+- Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
+- Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
+
 ### Step 3: 診断レポート
 
 診断結果を以下の形式で提示する:
@@ -179,13 +196,21 @@ options:
 
 ユーザーが適用対象を確定したら `Edit` で `phasegate.config.json` を変更。
 
-**変更後の必須検証**:
+**変更後の検証**:
 
 ```bash
 npx phasegate validate --layer L2
 ```
 
-L2 でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
+setup target を触った場合は以下も使い分ける:
+
+```bash
+npx phasegate doctor
+npx phasegate lint
+npm run phasegate:check-ready
+```
+
+検証でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
 
 ## phasegate-toolkit-guide との使い分け
 

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -119,10 +119,15 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 - 「phasegate のインストール方法は？」
 - 「monorepo で使うときは？」
 - 「既存プロジェクトに後から導入したい」
+- 「doctor の repairMode / suggestedSkill って何？」
+- 「.phasegate/manifest.json や hook-skip-events は何？」
 
 **参照先**:
 - 新規導入: `docs/guide/installation.md`
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
+- setup artifact / doctor finding / legacy artifact: `docs/guide/setup-artifacts.md`
+
+`setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->
 
 ### 8. skill 一覧と使い分け