phasegate 0.152.5 → 0.152.7

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.7] - 2026-05-13
+
+### Changed
+
+- **WI-159 / WI-160 / WI-161 / WI-162 / WI-163 / WI-164 — validator and JSON contract foundation** — aligns the public validator catalog, Quick Mode relaxation contract, contract traceability guide, status/drift JSON semantics, G5 operational validator payload docs, CI/L4 rollout docs, and pointer/freshness semantics.
+
+### Fixed
+
+- **WI-159 — Quick Mode validator catalog** — includes `L2-013` and `L2-015` in the Quick Mode validator ID registry and relaxation invariant so skipped/maintained L2 sets match the validator-system catalog.
+
+## [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

package/README.md

@@ -551,6 +551,7 @@ Detailed guides are available under `docs/guide/`:
 - [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
 - [5-Layer Defense Model](docs/guide/layer-model.md) -- L0-L4 layer details and HarnessError format
+- [Contract Traceability](docs/guide/contract-traceability.md) -- `L2-015` public contract, boundary, error, state, and observation annotations
 - [Hooks Integration](docs/guide/hooks-integration.md) -- Claude Code Hooks setup and behavior
 - [Codex Integration](docs/guide/codex-integration.md) -- Codex CLI setup, coverage matrix, and native `apply_patch` limitation
 - [Quick Mode vs Full Mode](docs/guide/quick-vs-full-mode.md) -- When to use `/story-implementor` vs `/quick-implementor`, with decision flow and case studies

package/docs/guide/cli-reference.md

@@ -296,7 +296,7 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
 
 ### Status and drift JSON semantics
 
-<!-- @work-item-id WI-151 -->
+<!-- @work-item-id WI-151, WI-162 -->
 
 `phasegate:status --json` is intended for humans, CI, and agents that need to distinguish configured intent from observed results. Layer entries may include:
 
@@ -308,6 +308,16 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
 
 `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.
 
+Status JSON may also include:
+
+| Key | Meaning |
+|---|---|
+| `hookHealth` | Configured hook files, latest skipped hook event, skip counts by reason, and the Codex native `apply_patch` limitation with the pre-commit backstop. |
+| `baselineHealth` | Baseline enabled state, baseline path, grandfathered file count, SHA mismatch count, missing file count, and removal rate. |
+| `operationalWarnings` | Non-gating warnings with `code`, `message`, and `nextAction`. |
+
+Drift JSON findings should preserve the most precise available `location`, `unit`, `category`, `severity`, and `nextAction`. Structural drift (`L4-001`) compares product design and code structure. Semantic drift compares `DesignIntent`, `ImplementationBehavior`, and `TestObservation` by `unitName + behaviorId`; it is an L4 report producer above structural drift and does not replace `L4-001`.
+
 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.
 
 ---
@@ -391,7 +401,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 |
 
 ---

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
@@ -22,8 +24,8 @@ This file is the **Single Source of Truth** for all quality configuration in a P
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": ["phase-gate", "2-phase-execution"],
+    "maintainedLayers": ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
+    "relaxedGates": ["L2-001", "L3-002", "L3-003", "L3-004", "L4"],
     "fullModeRequiredWhen": {
       "mixedCategories": true,
       "newDomainFile": true,
@@ -119,8 +121,8 @@ The five layers are:
 | Sub-field              | Type       | Default                                 | Description                                                                 |
 |------------------------|------------|-----------------------------------------|-----------------------------------------------------------------------------|
 | `allowedCategories`    | `string[]` | `["bugfix", "docs", "test", "config"]`  | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. |
-| `maintainedLayers`     | `string[]` | `["L1", "L2"]`                          | Layers that remain fully enforced even in Quick Mode.                       |
-| `relaxedGates`         | `string[]` | `["phase-gate", "2-phase-execution"]`   | Gates that are relaxed (not skipped) when Quick Mode is active.             |
+| `maintainedLayers`     | `string[]` | `["L1", "L2-002", "L2-003", "L2-014", "L3-001"]` | Exact validator IDs that remain enforced in Quick Mode. `L1` is the only layer shorthand; `L2` is not expanded. |
+| `relaxedGates`         | `string[]` | `["L2-001", "L3-002", "L3-003", "L3-004", "L4"]` | Validators/layers relaxed by Quick Mode. `L4` means all L4 validators are skipped. |
 | `fullModeRequiredWhen` | `object`   | all flags `true`                        | Conditions that force a Quick Mode change to escalate to the full `/story-implementor` flow. See below. |
 
 ##### `fullModeRequiredWhen`
@@ -137,6 +139,9 @@ Introduced in ISSUE-006 Story A (v0.63.0) and wired into the pre-tool-use hook b
 
 Set a flag to `false` only when the project intentionally accepts the risk of merging that category of change without the design ceremony -- e.g. an early-stage prototype where new domain files are expected to churn.
 
+<!-- @work-item-id WI-159 -->
+Quick Mode uses exact validator IDs for `maintainedLayers`. To keep all L2 validators active, list `L2-001`, `L2-002`, `L2-003`, `L2-013`, `L2-014`, and `L2-015` explicitly. The default keeps metadata, test-quality, work-item status, and security checks active while skipping phase-gate, CLI E2E coverage, contract traceability coverage, performance, coverage, nyquist, and L4 scheduled validators.
+
 #### `phaseDependencies`
 
 | Sub-field          | Type       | Default      | Description                                                        |
@@ -444,7 +449,7 @@ Controls how warning-severity validator failures are aggregated into the overall
 
 | Sub-field        | Type      | Default by preset                                                | Description                                                                                                                                                          |
 |------------------|-----------|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `failOnWarning`  | `boolean` | `false` (`minimal` / `standard`), `true` (`strict`)              | When `true`, warning-only validator fails (e.g. L4-001 drift, L4-002 consistency, L4-003 dead-code) count as overall FAIL / exit 1. When `false`, they count as PASS / exit 0. |
+| `failOnWarning`  | `boolean` | `false` (`minimal` / `standard`), `true` (`strict`)              | When `true`, warning-only validator fails (for example L4-001 drift, L4-002 consistency, L4-003 dead-code, L4-004 doc-freshness, or L4-005 pointer-validation) count as overall FAIL / exit 1. When `false`, they count as PASS / exit 0. |
 
 CLI override: `--fail-on-warning` / `--no-fail-on-warning` (CLI > config). Both unspecified → config value used.
 

package/docs/guide/contract-traceability.md

@@ -0,0 +1,55 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# Contract Traceability
+
+<!-- @work-item-id WI-160 -->
+
+`L2-015 contract-traceability-coverage` validates opt-in semantic records that connect public contracts to tests and product reflection.
+
+## Annotations
+
+Use `@phasegate-contract` on the file or section that declares a public behavior, boundary, error, state, or traceability contract. Use `@phasegate-observation` on tests or evidence that covers that contract.
+
+```ts
+// @phasegate-contract id=phasegate-status-json kind=PublicContract behaviors=hook-health,baseline-health
+// @phasegate-observation covers=phasegate-status-json:hook-health kind=integration
+```
+
+The current scanner is deliberately annotation based. It avoids treating every Markdown heading or exported symbol as a public contract while keeping the domain model ready for richer AST/Markdown extractors.
+
+## Semantic keys
+
+| Key | Meaning |
+|---|---|
+| `behavior` | A required public behavior under a CLI, API, Port, config, domain, or error contract. |
+| `boundary` | A boundary case such as invalid input, adapter edge, compatibility mode, or public/private API distinction. |
+| `observation` | Test or other evidence that covers a behavior or boundary. |
+
+## Model types
+
+| Type | What it represents |
+|---|---|
+| `PublicContract` | CLI/API/Port/config/domain/error contract and its required behavior cases. |
+| `BoundaryCase` | Edge behavior that must be covered separately from the happy path. |
+| `ErrorContract` | Stable error code, severity, message, suggestion, documentation reference, exit code, and machine-readable fields. |
+| `StateMachineModel` | States, transitions, terminal states, and invalid transitions. |
+| `TraceabilityGraphSlice` | WI, affected Unit, product reflection, implementation evidence, test evidence, and public-doc sync status. |
+
+## Findings
+
+`L2-015` findings use the standard validator result contract. Important fields are:
+
+| Field | Meaning |
+|---|---|
+| `kind` | Finding class such as missing behavior observation, missing boundary observation, incomplete error contract, state transition gap, or traceability graph gap. |
+| `subject` | Contract, behavior, error, state, or WI graph node that needs attention. |
+| `sourcePath` | File where the contract or observation was collected. |
+| `severity` | Current policy severity for the finding. |
+| `suggestion` | Repair action, usually adding an observation, completing an error contract, or reflecting a WI edge. |
+
+## WI-133 severity policy
+
+WI-133 made boundary/error/traceability coverage severity configurable at the validator policy layer. It is implemented as validator-system policy behavior, not as a new top-level `phasegate.config.json` field. Treat additional user-facing severity knobs as follow-up work unless the schema explicitly documents them.

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
@@ -130,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.7"
   }
 }
 ```
@@ -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

@@ -113,6 +113,7 @@ L2 validators run before every commit. They enforce process discipline and test
 | **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. |
+| **contract-traceability-coverage** | L2-015 | Checks opt-in public contract, boundary, error, state-machine, and traceability observations declared with `@phasegate-contract` / `@phasegate-observation`. |
 
 **Command:**
 
@@ -133,6 +134,16 @@ L3 validators run in the CI/CD pipeline before a merge is permitted. They cover
 | **coverage** | Enforces test coverage thresholds. Standard preset requires 90%; strict preset requires 95%. |
 | **nyquist** | Bidirectional requirements-test traceability. Validates that every requirement in `requirement-test-matrix.json` has corresponding tests and vice versa. |
 
+<!-- @work-item-id WI-161 -->
+Operational L3 findings use stable payloads:
+
+| Validator | Key payload fields |
+|---|---|
+| `L3-001 security` | `ruleId`, redacted value or redaction marker, token family, file location, fixture/allowlist context, suggestion. |
+| `L3-002 performance` | smell id, file location, observed metric, threshold, optional suppression marker, suggestion. |
+
+Security findings must redact matched token values. Fixture allowlists are for tests and examples only. Performance suppression should be explicit in source, and suppressed findings remain visible as accepted risk rather than disappearing from the model.
+
 **Command:**
 
 ```bash
@@ -169,6 +180,44 @@ 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
 
+### Validator execution contract
+
+<!-- @work-item-id WI-159, WI-164 -->
+
+The canonical validator catalog is:
+
+| Layer | Validator IDs |
+|---|---|
+| L2 | `L2-001`, `L2-002`, `L2-003`, `L2-013`, `L2-014`, `L2-015` |
+| L3 | `L3-001`, `L3-002`, `L3-003`, `L3-004` |
+| L4 | `L4-001`, `L4-002`, `L4-003`, `L4-004`, `L4-005` |
+
+`validate --layer L2` runs all enabled L2 validators. `validate --layer L4` is an explicit operator request and runs L4 even when standard preset config leaves `layers.L4.enabled: false`. `validate --layer all`, `phasegate:ci-check`, and aggregate CI-style commands preserve disabled L4 entries as skipped results; skipped results do not fail the process and are not promoted by `--fail-on-warning`.
+
+Quick Mode does not expand `maintainedLayers: ["L2"]` into every L2 validator. It treats entries as exact validator IDs, plus `L1` for all L1 lint behavior and `L4` as an all-skipped layer marker. The default Quick Mode profile maintains `L2-002`, `L2-003`, `L2-014`, and `L3-001`; it skips `L2-001`, `L2-013`, `L2-015`, `L3-002`, `L3-003`, `L3-004`, and all L4 validators.
+
+### L4 pointer and freshness report shape
+
+<!-- @work-item-id WI-164 -->
+
+`L4-004 doc-freshness` and `L4-005 pointer-validation` findings are registered L4 validator results, not separate hidden checks. Reports should be read with these fields:
+
+| Field | Meaning |
+|---|---|
+| `owner` | Unit or workflow responsible for the document/pointer policy. |
+| `pointerType` | Semantic type such as `reference`, `implementation`, `adr`, `product-doc`, or `external-url`. |
+| `sourceDocument` / `documentPath` | Document where the freshness or pointer finding originated. |
+| `severity` | `warning` or `error`; warning remains advisory unless fail-on-warning is active. |
+| `nextAction` / `suggestion` | Human or agent action that repairs the stale document or broken pointer. |
+
+External URL pointers are skipped by default unless a policy explicitly asks for URL validation.
+
+### Dead-code graph boundaries
+
+<!-- @work-item-id WI-161 -->
+
+`L4-003 dead-code` uses import/export graph analysis rather than simple text search. It accounts for direct exports, named re-exports, wildcard re-exports, default exports, dynamic imports, public API boundaries, and generated/test/fixture exclusions. Because module boundaries and public entrypoints can be project-specific, dead-code findings are warnings by default and become blocking only under fail-on-warning policy.
+
 ### Status and drift states
 
 `phasegate:status --json` separates three ideas that should not be collapsed in CI or agent logic:

package/docs/guide/quick-vs-full-mode.md

@@ -41,12 +41,12 @@ flowchart TD
 | Test design doc | Required before coding | Not required |
 | Coverage target | 90% or above | Existing coverage maintained |
 | L1 Biome rules | All 8 rules | **All 8 rules** |
-| L2 Pre-commit | phase-gate + metadata + test-quality | **metadata + test-quality** (phase-gate relaxed) |
+| L2 Pre-commit | phase-gate + metadata + test-quality + CLI E2E coverage + WI status + contract traceability | **metadata + test-quality + WI status** (phase-gate, CLI E2E coverage, and contract traceability relaxed) |
 | L3 CI | security + performance + coverage + nyquist | security only |
 | L4 Scheduled | drift + consistency + dead-code | skipped |
 | Commit prefix | conventional (`feat:`, `fix:`, ...) | `[quick] ...` |
 
-Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `@unit` / `@layer` comments, semantic AAA structure, and assertion-strength checks are non-negotiable regardless of flow.
+Both modes keep **L1 in full strength** and **L2 metadata / test-quality / WI status** — `@unit` / `@layer` comments, semantic AAA structure, assertion-strength checks, and stale WI status checks are non-negotiable regardless of flow. Quick Mode treats `maintainedLayers` entries as exact validator IDs; `L2` is not expanded into every L2 validator. <!-- @work-item-id WI-159 -->
 
 ---
 

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.5",
+  "version": "0.152.7",
   "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/quick-mode/domain/value-objects/validator-relaxation-profile.ts

@@ -6,7 +6,7 @@
  * Quick Mode時のバリデータ実行構成を表す値オブジェクト
  */
 
-const L2_IDS = ['L2-001', 'L2-002', 'L2-003', 'L2-014'] as const;
+const L2_IDS = ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] as const;
 const L3_IDS = ['L3-001', 'L3-002', 'L3-003', 'L3-004'] as const;
 
 type L2Id = (typeof L2_IDS)[number];
@@ -49,7 +49,7 @@ export class ValidatorRelaxationProfile {
     return new ValidatorRelaxationProfile({
       levelDependencyRelaxed: false,
       l1: { all: true },
-      l2: { maintained: ['L2-002', 'L2-003', 'L2-014'], skipped: ['L2-001'] },
+      l2: { maintained: ['L2-002', 'L2-003', 'L2-014'], skipped: ['L2-001', 'L2-013', 'L2-015'] },
       l3: { maintained: ['L3-001'], skipped: ['L3-002', 'L3-003', 'L3-004'] },
       l4: { all: false },
       phaseExecution: { twoPhaseRequired: false },
@@ -66,7 +66,7 @@ export class ValidatorRelaxationProfile {
   }): ValidatorRelaxationProfile {
     const { l2, l3 } = params;
 
-    // INV-P5: l2.maintained ∪ l2.skipped = {L2-001, L2-002, L2-003, L2-014}
+    // INV-P5: l2.maintained ∪ l2.skipped = the canonical L2 validator catalog.
     const l2Union = [...l2.maintained, ...l2.skipped].sort();
     const l2Expected = [...L2_IDS].sort();
     if (JSON.stringify(l2Union) !== JSON.stringify(l2Expected)) {

package/scripts/harness/quick-mode/infrastructure/adapters/validator-system-validator-id-registry-adapter.ts

@@ -8,7 +8,7 @@
 
 const STATIC_VALIDATOR_IDS: readonly string[] = Object.freeze([
   'L1-001', 'L1-002', 'L1-003', 'L1-004', 'L1-005', 'L1-006', 'L1-007', 'L1-008',
-  'L2-001', 'L2-002', 'L2-003', 'L2-014',
+  'L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015',
   'L3-001', 'L3-002', 'L3-003', 'L3-004',
   'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005',
 ]);

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 一覧と使い分け