phasegate 0.152.6 → 0.152.7

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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

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.
 
 ---

package/docs/guide/configuration.md

@@ -24,8 +24,8 @@ It is not the whole setup state. Hook JSON, Husky scripts, CI workflow files, sk
   },
   "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,
@@ -121,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`
@@ -139,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                                                        |
@@ -446,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/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.152.6"
+    "phasegate": "^0.152.7"
   }
 }
 ```

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

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.6",
+  "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',
 ]);