phasegate 0.152.1 → 0.152.5

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **WI status evidence closure / WI-119 / WI-120 / WI-121 / WI-127 / WI-128** — adds missing implementation/test traceability annotations and applies derived WI statuses so the remaining G1/G5 backlog items no longer report stale or reflected-only status.
+
 ## [0.152.1] - 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`). |
 
 ---
 
@@ -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

@@ -420,10 +420,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 +561,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 +570,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

@@ -94,6 +94,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/`:

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.1",
+  "version": "0.152.5",
   "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/validator-id-registry-adapter.ts

@@ -1,6 +1,6 @@
 // @unit ci-governance
 // @layer infrastructure
-// @work-item-id WI-124
+// @work-item-id WI-124 / WI-128
 
 import type { ValidatorIdRegistryPort } from '../../domain/ports/validator-id-registry-port.js';
 import { buildDefaultRegistry } from '../../../validator-system/composition-root.js';

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,7 @@
 // @unit harness-api
 // @layer infrastructure
+// @work-item-id WI-086 / WI-087
+// @work-item-id WI-127
 // Note: import.meta.url を使わず、呼び出し元 (main.ts) がパスを解決して渡す設計。
 
 import { promises as fs } from "node:fs";

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/ast-performance-scanner-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-121
  *
  * AstPerformanceScannerAdapter — PerformanceScannerPort実装
  * TypeScript Compiler API によるループ内 await 検出 + ファイルサイズチェック（L3-002）

package/scripts/harness/validator-system/infrastructure/adapters/file-system-security-pattern-scanner-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-120
  *
  * FileSystemSecurityPatternScannerAdapter — SecurityPatternScannerPort実装
  */

package/scripts/harness/validator-system/infrastructure/adapters/import-graph-source-analysis-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-119
  *
  * ImportGraphSourceAnalysisAdapter — SourceAnalysisPort実装
  */
@@ -19,9 +20,11 @@ const EXPORT_LIST_PATTERN = /export\s+(?:type\s+)?\{([^}]+)\}/g;
 
 export class ImportGraphSourceAnalysisAdapter implements SourceAnalysisPort {
   private readonly root: string;
+  private readonly includeExcludedFiles: boolean;
 
-  constructor(root: string = HARNESS_ROOT) {
+  constructor(root: string = HARNESS_ROOT, options: { includeExcludedFiles?: boolean } = {}) {
     this.root = root;
+    this.includeExcludedFiles = options.includeExcludedFiles ?? false;
   }
 
   async getImportGraph(): Promise<ImportGraphData> {
@@ -34,7 +37,7 @@ export class ImportGraphSourceAnalysisAdapter implements SourceAnalysisPort {
       try {
         const content = await readFile(filePath, 'utf8');
         const exports = extractExports(content);
-        const excludedReason = classifyDeadCodeExclusion(filePath);
+        const excludedReason = this.includeExcludedFiles ? undefined : classifyDeadCodeExclusion(filePath);
         nodes.push({
           filePath,
           exports,

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実装