phasegate 0.140.0 → 0.142.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.142.0] - 2026-05-10
+
+### Added
+
+- **WI-126 — work item status derivation** — `work-items:status --dry-run|--apply` を追加し、WI frontmatter `status` を inception / product reflection / implementation / test evidence から導出できるようにした。
+  - `--id WI-XXX` で単一 WI に絞り込み、`--fail-on-stale` で stale status を exit code 1 として検出できる。
+  - `--apply` は stale な `description.md` の YAML frontmatter `status:` 行だけを書き戻す。
+  - `fix` / `chore` の shortcut path は README / README.ja の説明と一致する。
+
+### Fixed
+
+- publish 前回帰として、標準 L2 validator set に `L2-013` を含む現行契約と `preCommit.implementationExtensions` default をテスト期待値に反映した。
+
+## [0.141.0] - 2026-05-09
+
+### Fixed
+
+- **WI-024 follow-up — metadataTags suggestion text** — `architecture.metadataTags.unit` / `architecture.metadataTags.layer` を使った L1-001 / L1-002 の `suggestion` も、固定の `@unit` / `@layer` ではなく設定タグ名を表示するようにした。
+
 ## [0.140.0] - 2026-05-09
 
 ### Added

package/README.ja.md

@@ -148,7 +148,8 @@ npx phasegate update-skills   # スキルを最新版に再デプロイ
 |     security, performance, coverage 90%/95%, 要件カバレッジ        |
 +------------------------------------------------------------------+
 | L4  週次 (default off)                                           |
-|     設計-コード乖離, 文書整合性, デッドコード                    |
+|     設計-コード乖離, 文書整合性, デッドコード,                  |
+|     doc-freshness, pointer-validation                            |
 +------------------------------------------------------------------+
 ```
 
@@ -292,6 +293,7 @@ npx phasegate <command> [options]
 | `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
 | `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
 | `phasegate:status` | 全体の健全性サマリ |
+| `work-items:status --dry-run` / `--apply` | 成果物から WI status を導出し、必要に応じて `description.md` frontmatter を更新 |
 | `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
 | `phasegate:detect-drift` | 設計-コード乖離レポート |
 | `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
@@ -405,6 +407,8 @@ TESTED (@work-item-id 付きテストあり / green)
 
 `type: chore` は DRAFTED で完結。`type: fix` は DRAFTED → REFLECTED → IMPLEMENTED の簡略パス。`status` は PhaseGate が自動更新します。
 
+`phasegate work-items:status --dry-run` で current status / derived status / reason / next action を確認できます。単一 WI に絞る場合は `--id WI-XXX`、CI 風に stale status を検出する場合は `--fail-on-stale`、`description.md` frontmatter の `status:` 行だけを書き戻す場合は `--apply` を指定します。
+
 詳細仕様: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 
 ---
@@ -455,9 +459,9 @@ reports/
 
 | Work Item | 内容 |
 |---|---|
-| **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
+| **[WI-128](docs/inception/_cross/WI-128/description.md)** | L4 運用ロールアウトの仕上げ。`doc-freshness` / `pointer-validation` は L4-004 / L4-005 として登録済みで、`p2:*` 互換コマンドも維持。WI-033 は完了済みとして閉じ、残りの scheduling / default / 運用 docs は後続 WI で扱う。@work-item-id WI-128 |
 
-L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。現時点では手動セットアップで利用できます。
+L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。[WI-125](docs/inception/_cross/WI-125/description.md) と L3 guide を参照してください。現時点では手動セットアップで利用できます。
 
 ---
 

package/README.md

@@ -156,7 +156,7 @@ npx phasegate update-skills
 | L1 | Editor save / `phasegate lint` | `@unit` / `@layer` metadata, layer violations, AI anti-patterns, dead code |
 | L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`), test quality |
 | L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
-| L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code. Doc freshness and pointer checks are standalone `p2:*` commands until WI-033. |
+| L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code, doc freshness, and pointer validation. `p2:*` standalone commands remain available as compatibility entry points. |
 
 ---
 
@@ -247,6 +247,8 @@ TESTED  (test files annotated with @work-item-id, all green)
 
 `type: chore` ends at DRAFTED. `type: fix` shortcuts via DRAFTED → REFLECTED → IMPLEMENTED. PhaseGate auto-updates `status`.
 
+Use `phasegate work-items:status --dry-run` to inspect current status, derived status, reason, and next action. Add `--id WI-XXX` to scope the report, `--fail-on-stale` for CI-style stale status detection, or `--apply` to update only the `status:` line in each stale `description.md` frontmatter.
+
 Full spec: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 
 ---
@@ -466,14 +468,15 @@ npx phasegate <command> [options]
 |---|---|
 | `init --name <name>` | Initialize project, deploy skills, generate config. Use `--with-ci` to deploy GitHub Actions workflows. |
 | `lint` | Run L1 Biome AST checks |
-| `validate --layer <L2-L4\|all>` | Run validators for specified layer (`--layer L0` prints runtime hook guidance) |
-| `ci-check` | Full CI check (L2-L4) |
+| `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) |
 | `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` | Update skills to latest version |
 | `phasegate:status` | Display overall harness health summary |
+| `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter |
 | `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. |
@@ -517,9 +520,9 @@ The main path is ready for project use, but a few documented behaviors still req
 
 | Work Item | Title | Why it matters |
 |---|---|---|
-| **[WI-033](docs/inception/_cross/WI-033/description.md)** | Promote `doc-freshness` / `pointer-validation` to L4 validators | Both capabilities exist as `p2:check-freshness` / `p2:validate-pointers` CLI commands but are not registered as L4 validators, so `validate --layer L4` skips them. WI-033 plumbs them through `validator-system` so they run via the standard L4 path and presets. |
+| **[WI-128](docs/inception/_cross/WI-128/description.md)** | Finish L4 operational rollout | `doc-freshness` and `pointer-validation` are registered as L4-004/L4-005 and also remain available through `p2:*` compatibility commands. WI-033 is closed; remaining rollout polish around scheduling, defaults, and operational docs is tracked separately. @work-item-id WI-128 |
 
-`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see the L3 guide for the current manual setup.
+`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see [WI-125](docs/inception/_cross/WI-125/description.md) and the L3 guide for the current manual setup.
 
 ---
 

package/docs/guide/cli-reference.md

@@ -261,7 +261,7 @@ Commands exposed as npm scripts (`npm run <command>`).
 | `phasegate:status` | `--json` | Health summary |
 | `phasegate:check-ready` | `--json` | Phase Gate pass status for all stories |
 | `phasegate:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
-| `phasegate:ci-check` | `--json` | All L3 validators |
+| `phasegate:ci-check` | `--json` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
 | `phasegate:detect-drift` | `--json` | Design-code drift report |
 | `phasegate:lint` | `--target <path>` `--json` | Lint via harness-api |
 | `phasegate:complete-check` | `--json` | L2-L4 full check |

package/docs/guide/layer-model.md

@@ -147,8 +147,11 @@ L4 validators are designed to run on a weekly schedule and detect slow-moving dr
 | **drift-detect** | L4-001 | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
 | **consistency-check** | L4-002 | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
 | **dead-code** | L4-003 | Detects unused exports and unreachable code that should be removed. |
+| **doc-freshness** | L4-004 | Checks design document freshness against the configured threshold. Also available through the `p2:check-freshness` compatibility command. |
+| **pointer-validation** | L4-005 | Resolves and validates design document pointers. Also available through the `p2:validate-pointers` compatibility command. |
 
-`doc-freshness` and `pointer-validation` are implemented as `phase2-extensions` CLI commands (`p2:check-freshness` and `p2:validate-pointers`). They are not registered as L4 validators yet, so `validate --layer L4` does not run them until WI-033 promotes them into `validator-system`.
+<!-- @work-item-id WI-116 -->
+`doc-freshness` and `pointer-validation` are registered as L4-004/L4-005. The standalone `p2:check-freshness` and `p2:validate-pointers` commands remain as compatibility entry points; WI-033's remaining scope is operational rollout, not validator registration.
 
 ### Drift-detect design pointers
 
@@ -219,6 +222,8 @@ Each error catalog entry declares a `defaultSeverity` of `error` or `warning`. A
 
 **Opt-in to strict mode** via `phasegate.config.json` `validate.failOnWarning: true` or CLI `--fail-on-warning` (CLI > config). The `strict` preset defaults to `failOnWarning: true` to match the precedent set by the `ci-governance` preset adapter.
 
+For L4 specifically, `validate --layer L4` is an explicit operator request and runs L4 validators even when `layers.L4.enabled` is false. `validate --layer all` and `phasegate:ci-check` honor disabled L4 as skipped results, so skipped L4 validators are visible in the report but do not become failures under `--fail-on-warning`. @work-item-id WI-107
+
 History: prior to v0.131.0, the aggregator's `failOnWarning` flag was effectively dead code (`hasFail = !result.passed || ...` masked it), so every warning-only fail produced exit 1 regardless of severity declaration. See ADR-017 for the rationale.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.140.0",
+  "version": "0.142.0",
   "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/biome-ast-engine/infrastructure/adapters/harness-error-formatter-adapter.ts

@@ -18,6 +18,20 @@ const RULE_SUGGESTIONS: Readonly<Record<string, string>> = {
   'no-comment-flood': '不要なコメントを整理し自己説明的なコードへ改善する',
 };
 
+const METADATA_TAG_MESSAGE_PATTERN = /(@[a-z][a-zA-Z0-9]*)コメントが必要です/;
+
+const resolveSuggestion = (ruleName: string, message: string): string => {
+  if (ruleName === 'require-unit-comment' || ruleName === 'require-layer-comment') {
+    const tagName = message.match(METADATA_TAG_MESSAGE_PATTERN)?.[1];
+
+    if (tagName) {
+      return `ファイル先頭に ${tagName} コメントを追加する`;
+    }
+  }
+
+  return RULE_SUGGESTIONS[ruleName] ?? '';
+};
+
 /**
  * ViolationFormatterPort の実装。
  * RuleViolation をルール名から L1-001〜L1-008 コードへマッピングし、
@@ -40,7 +54,7 @@ export class HarnessErrorFormatterAdapter implements ViolationFormatterPort {
       violations.map((v) => {
         const ruleName = v.ruleName.toString();
         const code = mapRuleNameToCode(ruleName);
-        const suggestion = RULE_SUGGESTIONS[ruleName] ?? '';
+        const suggestion = resolveSuggestion(ruleName, v.message);
 
         const entry: {
           code: string;

package/scripts/harness/biome-ast-engine/infrastructure/adapters/typescript-source-module-analyzer-adapter.ts

@@ -19,6 +19,36 @@ export interface TypeScriptSourceModuleAnalyzerAdapterDeps {
   readonly rootDir: string;
 }
 
+const HARNESS_ROOT_PREFIX = 'scripts/harness/';
+const TESTS_SEGMENT = '__tests__';
+const TEST_SCOPE_SEGMENTS = new Set(['unit', 'integration', 'e2e']);
+
+function deriveUnitNameFromPath(filePath: FilePath): string | null {
+  const normalizedPath = filePath.toString();
+  if (!normalizedPath.startsWith(HARNESS_ROOT_PREFIX)) {
+    return null;
+  }
+
+  const parts = normalizedPath.slice(HARNESS_ROOT_PREFIX.length).split('/');
+  if (parts.length < 2) {
+    return null;
+  }
+
+  if (parts[0] !== TESTS_SEGMENT) {
+    return parts[0] || null;
+  }
+
+  if (parts.length < 3) {
+    return parts[1] || null;
+  }
+
+  if (TEST_SCOPE_SEGMENTS.has(parts[1])) {
+    return parts[2] || null;
+  }
+
+  return parts[1] || null;
+}
+
 /**
  * SourceModuleAnalyzerPort の実装。
  * TypeScript Compiler API を使用して各ファイルから
@@ -69,7 +99,7 @@ export class TypeScriptSourceModuleAnalyzerAdapter implements SourceModuleAnalyz
         SourceModuleSnapshot.create(
           {
             filePath,
-            declaredUnit: unitResult.unitNames[0] ?? null,
+            declaredUnit: unitResult.unitNames[0] ?? deriveUnitNameFromPath(filePath),
             declaredLayer: layerResult.layerName,
             imports,
             anyTypeCount: anyCount,

package/scripts/harness/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -11,7 +11,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
   return {
     project: { preset: resolvedConfig.project.preset },
     layers: {
-      L2: { enabled: resolvedConfig.layers.L2.enabled },
+      L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013'] },
       L3: { enabled: resolvedConfig.layers.L3.enabled },
       L4: { enabled: resolvedConfig.layers.L4.enabled, validators: resolvedConfig.layers.L4.validators },
     },

package/scripts/harness/harness-api/domain/services/command-dispatch-service.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // command-dispatch-service.ts — CommandDispatchService Domain Service
 
 import { CommandRegistry } from './command-registry.js';
@@ -13,6 +14,7 @@ import type { BiomeLintPort } from '../ports/biome-lint-port.js';
 import type { ImpactAnalysisPort } from '../ports/impact-analysis-port.js';
 import type { ArtifactScannerPort } from '../ports/artifact-scanner-port.js';
 import type { ConfigQueryPort } from '../ports/config-query-port.js';
+import type { LayerId } from '../value-objects/layer-health.js';
 
 export interface CommandDispatchPorts {
   validatorExecutionPort: ValidatorExecutionPort;
@@ -35,6 +37,29 @@ function makeError(message: string): HarnessError {
   return { code: 'HARNESS_ERROR', severity: 'error', message };
 }
 
+type LiveValidationState = 'pass' | 'fail' | 'skipped' | 'not-run' | 'error';
+
+function layerIdFromValidatorId(validatorId: string): LayerId | null {
+  const prefix = validatorId.slice(0, 2);
+  return prefix === 'L1' || prefix === 'L2' || prefix === 'L3' || prefix === 'L4' ? prefix : null;
+}
+
+function summarizeLayerResults(items: readonly { validatorId: string; passed: boolean; skipped?: boolean }[]): Partial<Record<LayerId, LiveValidationState>> {
+  const result: Partial<Record<LayerId, LiveValidationState>> = {};
+  for (const layerId of ['L2', 'L3', 'L4'] as const) {
+    const layerItems = items.filter((item) => layerIdFromValidatorId(item.validatorId) === layerId);
+    if (layerItems.length === 0) continue;
+    if (layerItems.every((item) => item.skipped === true)) {
+      result[layerId] = 'skipped';
+    } else if (layerItems.some((item) => !item.passed && item.skipped !== true)) {
+      result[layerId] = 'fail';
+    } else {
+      result[layerId] = 'pass';
+    }
+  }
+  return result;
+}
+
 const KNOWN_COMMANDS = new Set([
   'phasegate:check-ready',
   'phasegate:check-phase',
@@ -131,7 +156,7 @@ export class CommandDispatchService {
       }
 
       case 'phasegate:ci-check': {
-        const validatorResults = await this.ports.validatorExecutionPort.runL3Validators();
+        const validatorResults = await this.ports.validatorExecutionPort.runAllValidators();
         const result = CiCheckResult.fromResults(validatorResults);
         if (result.allPassed) {
           const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
@@ -152,13 +177,23 @@ export class CommandDispatchService {
           const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
           return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
         }
-        const errors = drifts.map((d) => makeError(`Drift detected in ${d.unit}: ${d.element}`));
-        const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 }, result);
-        return { status: 'fail', errors: r.errors, summary: r.summary, data: result as unknown as T, exitCode: 1 };
+        const r = HarnessApiResponse.pass({ ...summary, passed: 1, warnings: drifts.length }, result);
+        return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
       }
 
       case 'phasegate:status': {
         const scanResult = await this.ports.artifactScannerPort.scan();
+        const liveValidationByLayer: Partial<Record<LayerId, LiveValidationState>> = {};
+        try {
+          const [lintResult, validatorResults] = await Promise.all([
+            this.ports.biomeLintPort.runLint(),
+            this.ports.validatorExecutionPort.runAllValidators(),
+          ]);
+          liveValidationByLayer.L1 = lintResult.passed ? 'pass' : 'fail';
+          Object.assign(liveValidationByLayer, summarizeLayerResults(validatorResults));
+        } catch {
+          liveValidationByLayer.L1 = liveValidationByLayer.L1 ?? 'error';
+        }
         let presetInfo = { name: 'standard' as const, enabledLayers: ['L1', 'L2', 'L3'] as ('L1' | 'L2' | 'L3' | 'L4')[] };
         const configPort = this.ports.configQueryPort;
         if (configPort.getPresetInfo) {
@@ -172,6 +207,7 @@ export class CommandDispatchService {
           presetInfo,
           configSummary: { configPath: 'phasegate.config.json', lastModified: '', version: '2' },
           phaseGateSummary: { totalStories: 0, passedStories: 0, pendingStories: 0 },
+          liveValidationByLayer,
         });
         const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, statusSummary);
         return { status: 'pass', errors: [], summary: r.summary, data: statusSummary as unknown as T, exitCode: 0 };

package/scripts/harness/harness-api/domain/services/status-derivation-service.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // status-derivation-service.ts — StatusDerivationService Domain Service
 
 import { LayerHealth, type LayerId } from '../value-objects/layer-health.js';
@@ -88,27 +89,44 @@ export class StatusDerivationService {
     presetInfo: PresetInfo;
     configSummary: ConfigSummary;
     phaseGateSummary: PhaseGateSummary;
+    liveValidationByLayer?: Partial<Record<LayerId, 'pass' | 'fail' | 'skipped' | 'not-run' | 'error'>>;
   }): HarnessStatusSummary {
-    const { scanResult, presetInfo, configSummary, phaseGateSummary } = input;
+    const { scanResult, presetInfo, configSummary, phaseGateSummary, liveValidationByLayer } = input;
 
     const layers: LayerHealth[] = ALL_LAYER_IDS.map((layerId) => {
       const enabled = presetInfo.enabledLayers.includes(layerId);
+      const configurationState = enabled ? 'enabled' : 'disabled';
 
       // Find from derivedLayerHealth
       const existing = scanResult.derivedLayerHealth.find((l) => l.layerId === layerId);
+      const layerArtifacts = scanResult.foundArtifacts.filter((a) => getLayerId(a) === layerId);
+      const hasPresent = layerArtifacts.some((a) => a.present === true);
+      const cachedArtifactState = hasPresent ? 'present' : 'missing';
+      const liveValidationState = liveValidationByLayer?.[layerId] ?? 'not-run';
+      const liveLastResult =
+        liveValidationState === 'pass' || liveValidationState === 'fail'
+          ? liveValidationState
+          : undefined;
 
       if (enabled) {
-        // Check artifacts
-        const layerArtifacts = scanResult.foundArtifacts.filter((a) => getLayerId(a) === layerId);
-        const hasPresent = layerArtifacts.some((a) => a.present === true);
-
-        if (existing && existing.lastResult) {
-          return LayerHealth.create({ layerId, enabled, lastResult: existing.lastResult });
-        }
-        const lastResult = hasPresent ? 'pass' : 'unknown';
-        return LayerHealth.create({ layerId, enabled, lastResult });
+        const lastResult = liveLastResult ?? existing?.lastResult ?? (hasPresent ? 'pass' : 'unknown');
+        return LayerHealth.create({
+          layerId,
+          enabled,
+          lastResult,
+          configurationState,
+          cachedArtifactState,
+          liveValidationState,
+        });
       } else {
-        return LayerHealth.create({ layerId, enabled: false, lastResult: undefined });
+        return LayerHealth.create({
+          layerId,
+          enabled: false,
+          lastResult: undefined,
+          configurationState,
+          cachedArtifactState,
+          liveValidationState,
+        });
       }
     });
 

package/scripts/harness/harness-api/domain/value-objects/ci-check-result.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // ci-check-result.ts — CiCheckResult Value Object
 
 import type { HarnessError } from './harness-api-response.js';
@@ -6,6 +7,7 @@ import type { HarnessError } from './harness-api-response.js';
 export interface ValidatorCheckItem {
   validatorId: string;
   passed: boolean;
+  skipped?: boolean;
   errors?: readonly HarnessError[];
 }
 
@@ -29,8 +31,8 @@ export class CiCheckResult {
     if (!props.validatorResults || props.validatorResults.length === 0) {
       throw new Error('EmptyValidatorResultsError: validatorResults must have at least one item (INV-5)');
     }
-    // INV-6: allPassed === validatorResults.every(r => r.passed)
-    const computedAllPassed = props.validatorResults.every((r) => r.passed);
+    // INV-6: allPassed === validatorResults.every(r => r.passed || r.skipped)
+    const computedAllPassed = props.validatorResults.every((r) => r.passed || r.skipped);
     if (props.allPassed !== computedAllPassed) {
       throw new Error(
         `HarnessApiDomainError: allPassed=${props.allPassed} does not match validatorResults state (computed: ${computedAllPassed})`
@@ -43,12 +45,12 @@ export class CiCheckResult {
     if (!validatorResults || validatorResults.length === 0) {
       throw new Error('EmptyValidatorResultsError: validatorResults must have at least one item (INV-5)');
     }
-    const allPassed = validatorResults.every((r) => r.passed);
+    const allPassed = validatorResults.every((r) => r.passed || r.skipped);
     return new CiCheckResult(validatorResults, allPassed);
   }
 
   getFailedValidators(): readonly ValidatorCheckItem[] {
-    return this.validatorResults.filter((r) => !r.passed);
+    return this.validatorResults.filter((r) => !r.passed && !r.skipped);
   }
 
   collectAllErrors(): readonly HarnessError[] {

package/scripts/harness/harness-api/domain/value-objects/drift-report-summary.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // drift-report-summary.ts — DriftReportSummary Value Object
 
 export interface DriftItem {
@@ -8,18 +9,117 @@ export interface DriftItem {
   recommendation: string;
 }
 
+type DriftCategory =
+  | 'code-missing-design'
+  | 'design-missing-code'
+  | 'missing-pointer'
+  | 'design-granularity-mismatch'
+  | 'uncategorized';
+type DriftSeverity = 'info' | 'warning' | 'error';
+
+export interface ActionableDriftItem extends DriftItem {
+  category: DriftCategory;
+  severity: DriftSeverity;
+  nextAction: string;
+}
+
+export interface DriftCategorySummary {
+  category: DriftCategory;
+  severity: DriftSeverity;
+  count: number;
+  nextAction: string;
+}
+
 export interface DriftReportSummaryProps {
   drifts: readonly DriftItem[];
   totalCount: number;
+  sampleLimit?: number;
+}
+
+const DEFAULT_SAMPLE_LIMIT = 20;
+
+function classifyDrift(drift: DriftItem): { category: DriftCategory; severity: DriftSeverity; nextAction: string } {
+  const direction = drift.direction.toLowerCase();
+  const recommendation = drift.recommendation.toLowerCase();
+  const element = drift.element.toLowerCase();
+
+  if (recommendation.includes('pointer') || recommendation.includes('@work-item-id')) {
+    return {
+      category: 'missing-pointer',
+      severity: 'warning',
+      nextAction: 'Add or repair the traceability pointer before changing gating policy.',
+    };
+  }
+  if (element.includes('heading') || recommendation.includes('granularity')) {
+    return {
+      category: 'design-granularity-mismatch',
+      severity: 'info',
+      nextAction: 'Review the design granularity or baseline this class of advisory drift.',
+    };
+  }
+  if (direction.includes('code') && direction.includes('design')) {
+    return {
+      category: direction.indexOf('code') < direction.indexOf('design') ? 'code-missing-design' : 'design-missing-code',
+      severity: 'warning',
+      nextAction:
+        direction.indexOf('code') < direction.indexOf('design')
+          ? 'Update the matching product/construction docs with the implementation contract.'
+          : 'Implement the described design element or remove stale design text.',
+    };
+  }
+  return {
+    category: 'uncategorized',
+    severity: 'warning',
+    nextAction: 'Inspect the sampled drift and assign a narrower category or baseline rule.',
+  };
+}
+
+function enrichDrift(drift: DriftItem): ActionableDriftItem {
+  return { ...drift, ...classifyDrift(drift) };
+}
+
+function summarizeByCategory(drifts: readonly ActionableDriftItem[]): readonly DriftCategorySummary[] {
+  const byCategory = new Map<DriftCategory, DriftCategorySummary>();
+  for (const drift of drifts) {
+    const existing = byCategory.get(drift.category);
+    if (existing) {
+      byCategory.set(drift.category, { ...existing, count: existing.count + 1 });
+    } else {
+      byCategory.set(drift.category, {
+        category: drift.category,
+        severity: drift.severity,
+        count: 1,
+        nextAction: drift.nextAction,
+      });
+    }
+  }
+  return [...byCategory.values()].sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
 }
 
 export class DriftReportSummary {
-  readonly drifts: readonly DriftItem[];
+  readonly drifts: readonly ActionableDriftItem[];
   readonly totalCount: number;
+  readonly rawDriftCount: number;
+  readonly sampleLimit: number;
+  readonly truncated: boolean;
+  readonly categorySummaries: readonly DriftCategorySummary[];
+  readonly actionPlan: readonly DriftCategorySummary[];
 
-  private constructor(drifts: readonly DriftItem[], totalCount: number) {
-    this.drifts = Object.freeze([...drifts]);
+  private constructor(
+    drifts: readonly DriftItem[],
+    totalCount: number,
+    sampleLimit: number = DEFAULT_SAMPLE_LIMIT,
+    summarySource: readonly DriftItem[] = drifts,
+  ) {
+    const enriched = drifts.map(enrichDrift);
+    const enrichedSummarySource = summarySource.map(enrichDrift);
+    this.drifts = Object.freeze(enriched);
     this.totalCount = totalCount;
+    this.rawDriftCount = totalCount;
+    this.sampleLimit = sampleLimit;
+    this.truncated = totalCount > enriched.length;
+    this.categorySummaries = Object.freeze(summarizeByCategory(enrichedSummarySource));
+    this.actionPlan = Object.freeze(this.categorySummaries.slice(0, 5));
     Object.freeze(this);
   }
 
@@ -30,18 +130,18 @@ export class DriftReportSummary {
         `HarnessApiDomainError: totalCount=${props.totalCount} does not match drifts.length=${props.drifts.length} (INV-7)`
       );
     }
-    return new DriftReportSummary(props.drifts, props.totalCount);
+    return new DriftReportSummary(props.drifts, props.totalCount, props.sampleLimit);
   }
 
-  static fromDrifts(drifts: readonly DriftItem[]): DriftReportSummary {
-    return new DriftReportSummary(drifts, drifts.length);
+  static fromDrifts(drifts: readonly DriftItem[], sampleLimit: number = DEFAULT_SAMPLE_LIMIT): DriftReportSummary {
+    return new DriftReportSummary(drifts.slice(0, sampleLimit), drifts.length, sampleLimit, drifts);
   }
 
   hasDrift(): boolean {
-    return this.drifts.length > 0;
+    return this.totalCount > 0;
   }
 
-  filterByUnit(unitId: string): readonly DriftItem[] {
+  filterByUnit(unitId: string): readonly ActionableDriftItem[] {
     return this.drifts.filter((d) => d.unit === unitId);
   }
 }

package/scripts/harness/harness-api/domain/value-objects/layer-health.ts

@@ -1,8 +1,12 @@
 // @layer domain
+// @unit harness-api
 // layer-health.ts — LayerHealth Value Object
 
 export type LayerId = 'L1' | 'L2' | 'L3' | 'L4';
 type LastResult = 'pass' | 'fail' | 'unknown' | undefined;
+type ConfigurationState = 'enabled' | 'disabled';
+type CachedArtifactState = 'present' | 'missing' | 'unknown';
+type LiveValidationState = 'pass' | 'fail' | 'skipped' | 'not-run' | 'error';
 
 const VALID_LAYER_IDS: readonly LayerId[] = ['L1', 'L2', 'L3', 'L4'];
 const VALID_LAST_RESULTS: readonly string[] = ['pass', 'fail', 'unknown'];
@@ -11,17 +15,33 @@ export interface LayerHealthProps {
   layerId: string;
   enabled: boolean;
   lastResult?: string;
+  configurationState?: ConfigurationState;
+  cachedArtifactState?: CachedArtifactState;
+  liveValidationState?: LiveValidationState;
 }
 
 export class LayerHealth {
   readonly layerId: LayerId;
   readonly enabled: boolean;
   readonly lastResult: LastResult;
+  readonly configurationState: ConfigurationState;
+  readonly cachedArtifactState: CachedArtifactState;
+  readonly liveValidationState: LiveValidationState;
 
-  private constructor(layerId: LayerId, enabled: boolean, lastResult: LastResult) {
+  private constructor(
+    layerId: LayerId,
+    enabled: boolean,
+    lastResult: LastResult,
+    configurationState: ConfigurationState,
+    cachedArtifactState: CachedArtifactState,
+    liveValidationState: LiveValidationState,
+  ) {
     this.layerId = layerId;
     this.enabled = enabled;
     this.lastResult = lastResult;
+    this.configurationState = configurationState;
+    this.cachedArtifactState = cachedArtifactState;
+    this.liveValidationState = liveValidationState;
     Object.freeze(this);
   }
 
@@ -35,7 +55,10 @@ export class LayerHealth {
     return new LayerHealth(
       props.layerId as LayerId,
       props.enabled,
-      props.lastResult as LastResult
+      props.lastResult as LastResult,
+      props.configurationState ?? (props.enabled ? 'enabled' : 'disabled'),
+      props.cachedArtifactState ?? 'unknown',
+      props.liveValidationState ?? 'not-run',
     );
   }