phasegate 0.152.6 → 0.152.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +1 -0
- package/docs/ADR/ADR-002-pre-commit-validators.md +5 -2
- package/docs/ADR/ADR-004-scheduled-validators.md +4 -2
- package/docs/ADR/ADR-013-story-reflection-gate.md +2 -2
- package/docs/guide/cli-reference.md +11 -1
- package/docs/guide/configuration.md +8 -5
- package/docs/guide/contract-traceability.md +55 -0
- package/docs/guide/installation.md +1 -1
- package/docs/guide/layer-model.md +49 -0
- package/docs/guide/quick-vs-full-mode.md +2 -2
- package/docs/guide/setup-artifacts.md +17 -0
- package/package.json +1 -1
- package/scripts/harness/quick-mode/domain/value-objects/validator-relaxation-profile.ts +3 -3
- package/scripts/harness/quick-mode/infrastructure/adapters/validator-system-validator-id-registry-adapter.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.152.8] - 2026-05-13
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **WI-155 / WI-165 / WI-166 / WI-167 / WI-168 — product reflection and catalog cleanup** — aligns product unit catalog policy, ADR validator catalog references, Work Item reflection wording, hook skip observability docs, and coverage/test design refresh for WI-117..148 follow-up semantics.
|
|
15
|
+
|
|
16
|
+
## [0.152.7] - 2026-05-13
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- **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.
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
|
|
24
|
+
- **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.
|
|
25
|
+
|
|
10
26
|
## [0.152.6] - 2026-05-13
|
|
11
27
|
|
|
12
28
|
### Changed
|
package/README.md
CHANGED
|
@@ -551,6 +551,7 @@ Detailed guides are available under `docs/guide/`:
|
|
|
551
551
|
- [CLI Reference](docs/guide/cli-reference.md) -- All CLI commands and options
|
|
552
552
|
- [Skills Overview](docs/guide/skills-overview.md) -- 30 skills with AIDLC execution order
|
|
553
553
|
- [5-Layer Defense Model](docs/guide/layer-model.md) -- L0-L4 layer details and HarnessError format
|
|
554
|
+
- [Contract Traceability](docs/guide/contract-traceability.md) -- `L2-015` public contract, boundary, error, state, and observation annotations
|
|
554
555
|
- [Hooks Integration](docs/guide/hooks-integration.md) -- Claude Code Hooks setup and behavior
|
|
555
556
|
- [Codex Integration](docs/guide/codex-integration.md) -- Codex CLI setup, coverage matrix, and native `apply_patch` limitation
|
|
556
557
|
- [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
|
|
@@ -10,13 +10,16 @@ AIエージェントは設計文書を無視して直接コードを書くこと
|
|
|
10
10
|
|
|
11
11
|
## Decision
|
|
12
12
|
|
|
13
|
-
L2(Pre-commit
|
|
13
|
+
L2(Pre-commit)で以下のバリデータにより設計-実装の順序、メタデータ、テスト品質、CLI E2E、WI status、公開 contract traceability を機械的に強制または報告する。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry を正とする。<!-- @work-item-id WI-168 -->
|
|
14
14
|
|
|
15
15
|
| バリデータ | コード | 検出対象 |
|
|
16
16
|
|-----------|--------|---------|
|
|
17
17
|
| phase-gate | L2-001 | 設計文書なしの実装コード変更を拒否 |
|
|
18
18
|
| metadata | L2-002 | @unit/@layer/@US-XXX メタデータの完全性検証 |
|
|
19
19
|
| test-quality | L2-003 | AAA パターン、actual 命名、日本語テスト名の検証 |
|
|
20
|
+
| cli-e2e | L2-013 | public CLI entrypoint の基本 E2E 契約 |
|
|
21
|
+
| wi-status | L2-014 | WI status と acceptance criteria の陳腐化検出 |
|
|
22
|
+
| contract-traceability | L2-015 | public contract / boundary / observation の traceability coverage |
|
|
20
23
|
|
|
21
24
|
### Phase Gate の3層検証
|
|
22
25
|
|
|
@@ -27,7 +30,7 @@ L2(Pre-commit)で以下の3バリデータにより設計-実装の順序を
|
|
|
27
30
|
## Consequences
|
|
28
31
|
|
|
29
32
|
- 設計文書なしのコード変更が物理的に不可能になる
|
|
30
|
-
- `@
|
|
33
|
+
- `@work-item-id WI-XXX` と legacy annotation の対応によりトレーサビリティが機械的に保証される
|
|
31
34
|
- テスト品質ルール(AAA, actual 命名)が全テストに強制される
|
|
32
35
|
|
|
33
36
|
## 関連要件
|
|
@@ -10,13 +10,15 @@ Accepted
|
|
|
10
10
|
|
|
11
11
|
## Decision
|
|
12
12
|
|
|
13
|
-
L4(Scheduled
|
|
13
|
+
L4(Scheduled)で以下のバリデータを週次または明示実行で扱う。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry と `docs/guide/layer-model.md` を正とする。<!-- @work-item-id WI-168 -->
|
|
14
14
|
|
|
15
15
|
| バリデータ | コード | 検出対象 |
|
|
16
16
|
|-----------|--------|---------|
|
|
17
17
|
| drift-detect | L4-001 | 設計にあるがコードにない / コードにあるが設計にない双方向乖離 |
|
|
18
18
|
| consistency-check | L4-002 | 文書間のレイヤー整合性の破綻 |
|
|
19
19
|
| dead-code | L4-003 | 未使用エクスポート、到達不能コード |
|
|
20
|
+
| doc-freshness | L4-004 | 設計文書の freshness threshold 超過 |
|
|
21
|
+
| pointer-validation | L4-005 | 設計文書 pointer の owner/type/source/severity/nextAction 付き検証 |
|
|
20
22
|
|
|
21
23
|
### 技術的実装
|
|
22
24
|
|
|
@@ -28,7 +30,7 @@ L4(Scheduled)で以下の3バリデータを週次で実行する。
|
|
|
28
30
|
|
|
29
31
|
- 設計-実装の乖離が週次で自動検出される
|
|
30
32
|
- 未使用コードの蓄積が防止される
|
|
31
|
-
- strict
|
|
33
|
+
- L4 は default-off の scheduled/advisory 層として扱い、strict または明示 `validate --layer L4` で実行できる。fail-on-warning policy がない限り warning-only findings は gate failure へ昇格しない。
|
|
32
34
|
|
|
33
35
|
## 関連要件
|
|
34
36
|
|
|
@@ -16,7 +16,7 @@ Phase Gate(L2-001)は設計文書の**存在**を検証するが、inception
|
|
|
16
16
|
|
|
17
17
|
## Decision
|
|
18
18
|
|
|
19
|
-
`phaseDependencies.storyReflection` を導入し、**実装着手時(`src/` / `scripts/harness/` への Write/Edit)に inception → product
|
|
19
|
+
`phaseDependencies.storyReflection` を導入し、**実装着手時(`src/` / `scripts/harness/` への Write/Edit)に inception → product 反映を機械的に検証**する。現行の新規 reflection は `@work-item-id WI-XXX` を正とし、既存の `@story-id HXX-XX` / `@story-id US-XXX` は WI frontmatter の `legacy_id` 経由で履歴として解決する。<!-- @work-item-id WI-155 -->
|
|
20
20
|
|
|
21
21
|
### 設計原則
|
|
22
22
|
|
|
@@ -72,7 +72,7 @@ inception/order/US-002/logical_design.md は存在しますが、
|
|
|
72
72
|
### 関連コンポーネント
|
|
73
73
|
|
|
74
74
|
- `PhaseConfigProviderPort.getStoryReflectionConfig()` — プリセット + config から有効な mappings を解決
|
|
75
|
-
- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@story-id` 検索
|
|
75
|
+
- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@work-item-id` / legacy `@story-id` 検索
|
|
76
76
|
- `HandlePreToolUseUseCase` — src/ への Write 発火時に storyReflection チェックを呼び出し、未反映ならブロック
|
|
77
77
|
- Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和される(§4.6)
|
|
78
78
|
|
|
@@ -296,7 +296,7 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
|
|
|
296
296
|
|
|
297
297
|
### Status and drift JSON semantics
|
|
298
298
|
|
|
299
|
-
<!-- @work-item-id WI-151 -->
|
|
299
|
+
<!-- @work-item-id WI-151, WI-162 -->
|
|
300
300
|
|
|
301
301
|
`phasegate:status --json` is intended for humans, CI, and agents that need to distinguish configured intent from observed results. Layer entries may include:
|
|
302
302
|
|
|
@@ -308,6 +308,16 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
|
|
|
308
308
|
|
|
309
309
|
`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.
|
|
310
310
|
|
|
311
|
+
Status JSON may also include:
|
|
312
|
+
|
|
313
|
+
| Key | Meaning |
|
|
314
|
+
|---|---|
|
|
315
|
+
| `hookHealth` | Configured hook files, latest skipped hook event, skip counts by reason, and the Codex native `apply_patch` limitation with the pre-commit backstop. |
|
|
316
|
+
| `baselineHealth` | Baseline enabled state, baseline path, grandfathered file count, SHA mismatch count, missing file count, and removal rate. |
|
|
317
|
+
| `operationalWarnings` | Non-gating warnings with `code`, `message`, and `nextAction`. |
|
|
318
|
+
|
|
319
|
+
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`.
|
|
320
|
+
|
|
311
321
|
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.
|
|
312
322
|
|
|
313
323
|
---
|
|
@@ -24,8 +24,8 @@ It is not the whole setup state. Hook JSON, Husky scripts, CI workflow files, sk
|
|
|
24
24
|
},
|
|
25
25
|
"quickMode": {
|
|
26
26
|
"allowedCategories": ["bugfix", "docs", "test", "config"],
|
|
27
|
-
"maintainedLayers": ["L1", "L2"],
|
|
28
|
-
"relaxedGates": ["
|
|
27
|
+
"maintainedLayers": ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
|
|
28
|
+
"relaxedGates": ["L2-001", "L3-002", "L3-003", "L3-004", "L4"],
|
|
29
29
|
"fullModeRequiredWhen": {
|
|
30
30
|
"mixedCategories": true,
|
|
31
31
|
"newDomainFile": true,
|
|
@@ -121,8 +121,8 @@ The five layers are:
|
|
|
121
121
|
| Sub-field | Type | Default | Description |
|
|
122
122
|
|------------------------|------------|-----------------------------------------|-----------------------------------------------------------------------------|
|
|
123
123
|
| `allowedCategories` | `string[]` | `["bugfix", "docs", "test", "config"]` | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. |
|
|
124
|
-
| `maintainedLayers` | `string[]` | `["L1", "L2"]`
|
|
125
|
-
| `relaxedGates` | `string[]` | `["
|
|
124
|
+
| `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. |
|
|
125
|
+
| `relaxedGates` | `string[]` | `["L2-001", "L3-002", "L3-003", "L3-004", "L4"]` | Validators/layers relaxed by Quick Mode. `L4` means all L4 validators are skipped. |
|
|
126
126
|
| `fullModeRequiredWhen` | `object` | all flags `true` | Conditions that force a Quick Mode change to escalate to the full `/story-implementor` flow. See below. |
|
|
127
127
|
|
|
128
128
|
##### `fullModeRequiredWhen`
|
|
@@ -139,6 +139,9 @@ Introduced in ISSUE-006 Story A (v0.63.0) and wired into the pre-tool-use hook b
|
|
|
139
139
|
|
|
140
140
|
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.
|
|
141
141
|
|
|
142
|
+
<!-- @work-item-id WI-159 -->
|
|
143
|
+
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.
|
|
144
|
+
|
|
142
145
|
#### `phaseDependencies`
|
|
143
146
|
|
|
144
147
|
| Sub-field | Type | Default | Description |
|
|
@@ -446,7 +449,7 @@ Controls how warning-severity validator failures are aggregated into the overall
|
|
|
446
449
|
|
|
447
450
|
| Sub-field | Type | Default by preset | Description |
|
|
448
451
|
|------------------|-----------|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
449
|
-
| `failOnWarning` | `boolean` | `false` (`minimal` / `standard`), `true` (`strict`) | When `true`, warning-only validator fails (
|
|
452
|
+
| `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. |
|
|
450
453
|
|
|
451
454
|
CLI override: `--fail-on-warning` / `--no-fail-on-warning` (CLI > config). Both unspecified → config value used.
|
|
452
455
|
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
traceability:
|
|
3
|
+
initial_creation: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Contract Traceability
|
|
7
|
+
|
|
8
|
+
<!-- @work-item-id WI-160 -->
|
|
9
|
+
|
|
10
|
+
`L2-015 contract-traceability-coverage` validates opt-in semantic records that connect public contracts to tests and product reflection.
|
|
11
|
+
|
|
12
|
+
## Annotations
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
// @phasegate-contract id=phasegate-status-json kind=PublicContract behaviors=hook-health,baseline-health
|
|
18
|
+
// @phasegate-observation covers=phasegate-status-json:hook-health kind=integration
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
## Semantic keys
|
|
24
|
+
|
|
25
|
+
| Key | Meaning |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `behavior` | A required public behavior under a CLI, API, Port, config, domain, or error contract. |
|
|
28
|
+
| `boundary` | A boundary case such as invalid input, adapter edge, compatibility mode, or public/private API distinction. |
|
|
29
|
+
| `observation` | Test or other evidence that covers a behavior or boundary. |
|
|
30
|
+
|
|
31
|
+
## Model types
|
|
32
|
+
|
|
33
|
+
| Type | What it represents |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `PublicContract` | CLI/API/Port/config/domain/error contract and its required behavior cases. |
|
|
36
|
+
| `BoundaryCase` | Edge behavior that must be covered separately from the happy path. |
|
|
37
|
+
| `ErrorContract` | Stable error code, severity, message, suggestion, documentation reference, exit code, and machine-readable fields. |
|
|
38
|
+
| `StateMachineModel` | States, transitions, terminal states, and invalid transitions. |
|
|
39
|
+
| `TraceabilityGraphSlice` | WI, affected Unit, product reflection, implementation evidence, test evidence, and public-doc sync status. |
|
|
40
|
+
|
|
41
|
+
## Findings
|
|
42
|
+
|
|
43
|
+
`L2-015` findings use the standard validator result contract. Important fields are:
|
|
44
|
+
|
|
45
|
+
| Field | Meaning |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `kind` | Finding class such as missing behavior observation, missing boundary observation, incomplete error contract, state transition gap, or traceability graph gap. |
|
|
48
|
+
| `subject` | Contract, behavior, error, state, or WI graph node that needs attention. |
|
|
49
|
+
| `sourcePath` | File where the contract or observation was collected. |
|
|
50
|
+
| `severity` | Current policy severity for the finding. |
|
|
51
|
+
| `suggestion` | Repair action, usually adding an observation, completing an error contract, or reflecting a WI edge. |
|
|
52
|
+
|
|
53
|
+
## WI-133 severity policy
|
|
54
|
+
|
|
55
|
+
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.
|
|
@@ -113,6 +113,7 @@ L2 validators run before every commit. They enforce process discipline and test
|
|
|
113
113
|
| **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. |
|
|
114
114
|
| **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. |
|
|
115
115
|
| **work-item-status-staleness** | L2-014 | Compares `description.md` frontmatter status with derived artifact evidence and reports stale WI status. |
|
|
116
|
+
| **contract-traceability-coverage** | L2-015 | Checks opt-in public contract, boundary, error, state-machine, and traceability observations declared with `@phasegate-contract` / `@phasegate-observation`. |
|
|
116
117
|
|
|
117
118
|
**Command:**
|
|
118
119
|
|
|
@@ -133,6 +134,16 @@ L3 validators run in the CI/CD pipeline before a merge is permitted. They cover
|
|
|
133
134
|
| **coverage** | Enforces test coverage thresholds. Standard preset requires 90%; strict preset requires 95%. |
|
|
134
135
|
| **nyquist** | Bidirectional requirements-test traceability. Validates that every requirement in `requirement-test-matrix.json` has corresponding tests and vice versa. |
|
|
135
136
|
|
|
137
|
+
<!-- @work-item-id WI-161 -->
|
|
138
|
+
Operational L3 findings use stable payloads:
|
|
139
|
+
|
|
140
|
+
| Validator | Key payload fields |
|
|
141
|
+
|---|---|
|
|
142
|
+
| `L3-001 security` | `ruleId`, redacted value or redaction marker, token family, file location, fixture/allowlist context, suggestion. |
|
|
143
|
+
| `L3-002 performance` | smell id, file location, observed metric, threshold, optional suppression marker, suggestion. |
|
|
144
|
+
|
|
145
|
+
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.
|
|
146
|
+
|
|
136
147
|
**Command:**
|
|
137
148
|
|
|
138
149
|
```bash
|
|
@@ -169,6 +180,44 @@ npx phasegate validate --layer L4
|
|
|
169
180
|
|
|
170
181
|
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
|
|
171
182
|
|
|
183
|
+
### Validator execution contract
|
|
184
|
+
|
|
185
|
+
<!-- @work-item-id WI-159, WI-164 -->
|
|
186
|
+
|
|
187
|
+
The canonical validator catalog is:
|
|
188
|
+
|
|
189
|
+
| Layer | Validator IDs |
|
|
190
|
+
|---|---|
|
|
191
|
+
| L2 | `L2-001`, `L2-002`, `L2-003`, `L2-013`, `L2-014`, `L2-015` |
|
|
192
|
+
| L3 | `L3-001`, `L3-002`, `L3-003`, `L3-004` |
|
|
193
|
+
| L4 | `L4-001`, `L4-002`, `L4-003`, `L4-004`, `L4-005` |
|
|
194
|
+
|
|
195
|
+
`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`.
|
|
196
|
+
|
|
197
|
+
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.
|
|
198
|
+
|
|
199
|
+
### L4 pointer and freshness report shape
|
|
200
|
+
|
|
201
|
+
<!-- @work-item-id WI-164 -->
|
|
202
|
+
|
|
203
|
+
`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:
|
|
204
|
+
|
|
205
|
+
| Field | Meaning |
|
|
206
|
+
|---|---|
|
|
207
|
+
| `owner` | Unit or workflow responsible for the document/pointer policy. |
|
|
208
|
+
| `pointerType` | Semantic type such as `reference`, `implementation`, `adr`, `product-doc`, or `external-url`. |
|
|
209
|
+
| `sourceDocument` / `documentPath` | Document where the freshness or pointer finding originated. |
|
|
210
|
+
| `severity` | `warning` or `error`; warning remains advisory unless fail-on-warning is active. |
|
|
211
|
+
| `nextAction` / `suggestion` | Human or agent action that repairs the stale document or broken pointer. |
|
|
212
|
+
|
|
213
|
+
External URL pointers are skipped by default unless a policy explicitly asks for URL validation.
|
|
214
|
+
|
|
215
|
+
### Dead-code graph boundaries
|
|
216
|
+
|
|
217
|
+
<!-- @work-item-id WI-161 -->
|
|
218
|
+
|
|
219
|
+
`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.
|
|
220
|
+
|
|
172
221
|
### Status and drift states
|
|
173
222
|
|
|
174
223
|
`phasegate:status --json` separates three ideas that should not be collapsed in CI or agent logic:
|
|
@@ -41,12 +41,12 @@ flowchart TD
|
|
|
41
41
|
| Test design doc | Required before coding | Not required |
|
|
42
42
|
| Coverage target | 90% or above | Existing coverage maintained |
|
|
43
43
|
| L1 Biome rules | All 8 rules | **All 8 rules** |
|
|
44
|
-
| L2 Pre-commit | phase-gate + metadata + test-quality | **metadata + test-quality** (phase-gate relaxed) |
|
|
44
|
+
| 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) |
|
|
45
45
|
| L3 CI | security + performance + coverage + nyquist | security only |
|
|
46
46
|
| L4 Scheduled | drift + consistency + dead-code | skipped |
|
|
47
47
|
| Commit prefix | conventional (`feat:`, `fix:`, ...) | `[quick] ...` |
|
|
48
48
|
|
|
49
|
-
Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `@unit` / `@layer` comments, semantic AAA structure,
|
|
49
|
+
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 -->
|
|
50
50
|
|
|
51
51
|
---
|
|
52
52
|
|
|
@@ -53,6 +53,23 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
|
|
|
53
53
|
- `.harness/reports` is a legacy fallback used only when a phase-dependency provider cannot resolve project config.
|
|
54
54
|
- `.phasegate/hook-skip-events.jsonl` records hook bypass/skip observations for diagnosis; it is runtime state, not a managed install target.
|
|
55
55
|
|
|
56
|
+
## Hook Skip Events
|
|
57
|
+
|
|
58
|
+
<!-- @work-item-id WI-166 -->
|
|
59
|
+
|
|
60
|
+
`.phasegate/hook-skip-events.jsonl` is a best-effort JSON Lines runtime log written by agent hooks when a hook intentionally skips or cannot complete its normal validation path. Each record is diagnostic evidence for `phasegate status --json`, not a gate result by itself.
|
|
61
|
+
|
|
62
|
+
Typical fields are:
|
|
63
|
+
|
|
64
|
+
| Field | Meaning |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `hookType` | Hook family, for example `PostToolUse` or `Stop`. |
|
|
67
|
+
| `reason` | Stable skip reason such as disabled hook, reentry detection, timeout, or unsupported native pre-edit path. |
|
|
68
|
+
| `targetPaths` | Files or paths relevant to the hook event when available. |
|
|
69
|
+
| `timestamp` | Event time in ISO format. |
|
|
70
|
+
|
|
71
|
+
Recording is best-effort. A write failure must not change the original hook exit code. Operators should use the latest skip event and counts in `phasegate status --json` to decide whether to run `phasegate doctor`, refresh hooks with `reconcile`, enable Codex hook support, or rely on the L2 pre-commit backstop for edits that native hooks cannot observe before mutation.
|
|
72
|
+
|
|
56
73
|
## Legacy Retirement
|
|
57
74
|
|
|
58
75
|
Current setup does not require `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, or `.harness/context-priority.json`. Treat them as project-local compatibility artifacts. Before deleting them, check whether an archived workflow or local script still references them; otherwise prefer documenting them as retired rather than wiring new guidance around them.
|
package/package.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* Quick Mode時のバリデータ実行構成を表す値オブジェクト
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
|
-
const L2_IDS = ['L2-001', 'L2-002', 'L2-003', 'L2-014'] as const;
|
|
9
|
+
const L2_IDS = ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] as const;
|
|
10
10
|
const L3_IDS = ['L3-001', 'L3-002', 'L3-003', 'L3-004'] as const;
|
|
11
11
|
|
|
12
12
|
type L2Id = (typeof L2_IDS)[number];
|
|
@@ -49,7 +49,7 @@ export class ValidatorRelaxationProfile {
|
|
|
49
49
|
return new ValidatorRelaxationProfile({
|
|
50
50
|
levelDependencyRelaxed: false,
|
|
51
51
|
l1: { all: true },
|
|
52
|
-
l2: { maintained: ['L2-002', 'L2-003', 'L2-014'], skipped: ['L2-001'] },
|
|
52
|
+
l2: { maintained: ['L2-002', 'L2-003', 'L2-014'], skipped: ['L2-001', 'L2-013', 'L2-015'] },
|
|
53
53
|
l3: { maintained: ['L3-001'], skipped: ['L3-002', 'L3-003', 'L3-004'] },
|
|
54
54
|
l4: { all: false },
|
|
55
55
|
phaseExecution: { twoPhaseRequired: false },
|
|
@@ -66,7 +66,7 @@ export class ValidatorRelaxationProfile {
|
|
|
66
66
|
}): ValidatorRelaxationProfile {
|
|
67
67
|
const { l2, l3 } = params;
|
|
68
68
|
|
|
69
|
-
// INV-P5: l2.maintained ∪ l2.skipped =
|
|
69
|
+
// INV-P5: l2.maintained ∪ l2.skipped = the canonical L2 validator catalog.
|
|
70
70
|
const l2Union = [...l2.maintained, ...l2.skipped].sort();
|
|
71
71
|
const l2Expected = [...L2_IDS].sort();
|
|
72
72
|
if (JSON.stringify(l2Union) !== JSON.stringify(l2Expected)) {
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
const STATIC_VALIDATOR_IDS: readonly string[] = Object.freeze([
|
|
10
10
|
'L1-001', 'L1-002', 'L1-003', 'L1-004', 'L1-005', 'L1-006', 'L1-007', 'L1-008',
|
|
11
|
-
'L2-001', 'L2-002', 'L2-003', 'L2-014',
|
|
11
|
+
'L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015',
|
|
12
12
|
'L3-001', 'L3-002', 'L3-003', 'L3-004',
|
|
13
13
|
'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005',
|
|
14
14
|
]);
|