phasegate 0.157.0 → 0.159.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.159.0] - 2026-05-13
+
+### Added
+
+- **WI-156 — documentation drift guardrail** — adds `L4-006 skill-catalog-drift` to compare the shipped `skills/*/SKILL.md` catalog with maintained skill-count declarations and skills overview category totals, plus release checklist guidance for remaining manual drift checks.
+
+## [0.158.0] - 2026-05-13
+
+### Changed
+
+- **WI-180 — scoped-out doctor effective repair contract** — adds current-scope repair target and repair-mode applicability fields to doctor JSON, lists scoped-out check IDs in human output, and updates docs/skills so single-agent diagnostics are harder to misread.
+
 ## [0.157.0] - 2026-05-13
 
 ### Changed

package/README.md

@@ -551,7 +551,7 @@ README keeps only the entry points most users need. The full public/compatibilit
 
 <!-- @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.
+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/skill-catalog 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, semantic drift coverage, and maintained skill-count declarations.
 
 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/ADR/ADR-004-scheduled-validators.md

@@ -19,6 +19,7 @@ L4（Scheduled）で以下のバリデータを週次または明示実行で扱
 | dead-code | L4-003 | 未使用エクスポート、到達不能コード |
 | doc-freshness | L4-004 | 設計文書の freshness threshold 超過 |
 | pointer-validation | L4-005 | 設計文書 pointer の owner/type/source/severity/nextAction 付き検証 |
+| skill-catalog-drift | L4-006 | `skills/*/SKILL.md` 実数と maintained docs の skill count 宣言差分検出 | <!-- @work-item-id WI-156 -->
 
 ### 技術的実装
 

package/docs/guide/cli-reference.md

@@ -40,7 +40,7 @@ Command names in this document are split into three surfaces:
 
 <!-- @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 --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. Scoped-out findings suppress immediate repair guidance with `repairHint: null`, `suggestedSkill: null`, and `repairHintApplicability: "only-if-agent-selected"`. `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. <!-- @work-item-id WI-178, WI-179 -->
+Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. Scoped-out findings suppress immediate repair guidance with `repairHint: null`, `suggestedSkill: null`, `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"`; applicable `findings[]` use `currentScopeRepairTarget: true` with applicable repair fields. `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. <!-- @work-item-id WI-178, WI-179, WI-180 -->
 
 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.
 

package/docs/guide/configuration.md

@@ -458,7 +458,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 (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. |
+| `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, L4-005 pointer-validation, or L4-006 skill-catalog-drift) 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/layer-model.md

@@ -167,6 +167,7 @@ L4 validators are designed to run on a weekly schedule and detect slow-moving dr
 | **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. |
+| **skill-catalog-drift** | L4-006 | Compares `skills/*/SKILL.md` count with maintained public/operator skill-count declarations and `skills-overview` category totals. |
 
 <!-- @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; canonical L4 execution is `validate --layer L4`. WI-033 remains closed as validator registration work; WI-128 tracks scheduling/default/policy rollout.
@@ -190,7 +191,7 @@ The canonical validator catalog is:
 |---|---|
 | 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` |
+| L4 | `L4-001`, `L4-002`, `L4-003`, `L4-004`, `L4-005`, `L4-006` |
 
 `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`.
 

package/docs/guide/troubleshooting.md

@@ -63,7 +63,7 @@ The planner output is intentionally agent-readable: detected state, questions, p
 
 `doctor` green means the local managed setup is consistent for the inspected targets. It does not prove user-level Codex feature flags, hosted GitHub Actions execution, npm registry state, or team policy acceptance.
 
-By default, `phasegate doctor` inspects the full Claude + Codex + shared setup. For a deliberate single-agent setup, use `phasegate doctor --agent claude --json` or `phasegate doctor --agent codex --json`. Single-agent reports keep shared targets applicable and place the unselected agent's findings under `scopedOutFindings` with `applicability: "not-applicable"`; those findings are explanatory, not repair targets for the selected agent. Their `repairHint` and `suggestedSkill` fields are intentionally `null`; `repairHintApplicability: "only-if-agent-selected"` means the repair guidance matters only if the user chooses that agent. <!-- @work-item-id WI-178, WI-179 -->
+By default, `phasegate doctor` inspects the full Claude + Codex + shared setup. For a deliberate single-agent setup, use `phasegate doctor --agent claude --json` or `phasegate doctor --agent codex --json`. Single-agent reports keep shared targets applicable and place the unselected agent's findings under `scopedOutFindings` with `applicability: "not-applicable"`; those findings are explanatory, not repair targets for the selected agent. Their `repairHint` and `suggestedSkill` fields are intentionally `null`; `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"` mean the original repair fields only become actionable if the user chooses that agent. Applicable `findings[]` use `currentScopeRepairTarget: true` and applicable repair fields. <!-- @work-item-id WI-178, WI-179, WI-180 -->
 
 Check `plan.completeness` in `setup:agent --json`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.157.0",
+  "version": "0.159.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/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -1,7 +1,7 @@
 /**
  * @layer application
  * @unit config-foundation
- * @work-item-id WI-133
+ * @work-item-id WI-133 / WI-156
  */
 import type { HarnessConfigV2 } from '../../domain/harness-config.js';
 
@@ -25,6 +25,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
     'doc-freshness-checker': 'L4-004',
     'pointer-validation': 'L4-005',
     'pointer-validator': 'L4-005',
+    'skill-catalog-drift': 'L4-006',
   }, /^L4-\d{3}$/);
 
   return {

package/scripts/harness/config-foundation/infrastructure/presets/minimal.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": false,
-      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator"],
+      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator", "skill-catalog-drift"],
       "schedule": "0 0 * * *"
     }
   },

package/scripts/harness/config-foundation/infrastructure/presets/standard.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": false,
-      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator"],
+      "validators": ["drift-detector", "doc-freshness-checker", "pointer-validator", "skill-catalog-drift"],
       "schedule": "0 0 * * *"
     }
   },

package/scripts/harness/config-foundation/infrastructure/presets/strict.json

@@ -15,7 +15,7 @@
     },
     "L4": {
       "enabled": true,
-      "validators": ["drift-detector", "consistency-checker", "dead-code-detector", "doc-freshness-checker", "pointer-validator"],
+      "validators": ["drift-detector", "consistency-checker", "dead-code-detector", "doc-freshness-checker", "pointer-validator", "skill-catalog-drift"],
       "schedule": "0 1 * * *"
     }
   },

package/scripts/harness/harness-error/infrastructure/adapters/validator-registry-bridge-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit harness-error
+ * @work-item-id WI-156
  */
 export interface ValidatorIssueSnapshot {
   readonly code: string;
@@ -66,6 +67,7 @@ const DEFAULT_VALIDATOR_IDS = [
   'dead-code',
   'doc-freshness',
   'pointer-validation',
+  'skill-catalog-drift',
 ] as const;
 
 export const DEFAULT_VALIDATOR_ENTRYPOINTS = new Map<

package/scripts/harness/harness-error/infrastructure/registry/l4-error-definitions.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit harness-error
+ * @work-item-id WI-156
  */
 import { AdrRef } from '../../domain/value-objects/adr-ref.js';
 import { ErrorCode } from '../../domain/value-objects/error-code.js';
@@ -64,4 +65,11 @@ export const L4_ERROR_DEFINITIONS = Object.freeze([
     ownerValidatorId: 'pointer-validation',
     defaultFixExample: 'const actual = "fix unresolved document pointer";',
   }),
+  createDefinition({
+    code: 'L4-006',
+    title: 'スキルカタログ数とドキュメント宣言が一致しない',
+    category: 'consistency',
+    ownerValidatorId: 'skill-catalog-drift',
+    defaultFixExample: 'const actual = "update skill count declarations with the skill catalog";',
+  }),
 ]);

package/scripts/harness/installation/presentation/formatters/diagnostic-report-formatter.ts

@@ -3,6 +3,7 @@
 // @work-item-id WI-145
 // @work-item-id WI-178
 // @work-item-id WI-179
+// @work-item-id WI-180
 
 import type { DoctorAgentScope, ScopedOutDiagnosticFinding } from "../../application/usecases/run-doctor-diagnostics.js";
 import type { DiagnosticReport } from "../../domain/diagnostic-report.js";
@@ -31,7 +32,9 @@ export class DiagnosticReportFormatter {
         findings: input.report.findings.map((finding) => ({
           ...finding.toJSON(),
           applicability: "applicable",
+          currentScopeRepairTarget: true,
           repairHintApplicability: "applicable",
+          repairModeApplicability: "applicable",
         })),
         scopedOutFindings: input.scopedOutFindings.map(({ finding, scopeReason }) => {
           const json = finding.toJSON();
@@ -40,7 +43,9 @@ export class DiagnosticReportFormatter {
             repairHint: null,
             suggestedSkill: null,
             applicability: "not-applicable",
+            currentScopeRepairTarget: false,
             repairHintApplicability: "only-if-agent-selected",
+            repairModeApplicability: "only-if-agent-selected",
             scopeReason,
           };
         }),
@@ -73,7 +78,8 @@ export class DiagnosticReportFormatter {
     const warnCount = input.report.findings.filter((finding) => finding.severity === "warn").length;
     lines.push(`Status: ${input.report.overallStatus.toUpperCase()} (${input.report.findings.length} findings: ${redCount} red, ${warnCount} warn)`);
     if (input.scopedOutFindings.length > 0) {
-      lines.push(`Scoped out: ${input.scopedOutFindings.length} informational findings not applicable to --agent ${input.agent}; not repair targets for this scope.`);
+      const checkIds = input.scopedOutFindings.map(({ finding }) => finding.checkId).join(", ");
+      lines.push(`Scoped out: ${input.scopedOutFindings.length} informational findings not applicable to --agent ${input.agent}; not repair targets for this scope: ${checkIds}.`);
     }
     lines.push(`Exit: ${input.exitCode}`);
     return lines.join("\n");

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

@@ -1,7 +1,7 @@
 /**
  * @layer infrastructure
  * @unit quick-mode
- * @work-item-id WI-140
+ * @work-item-id WI-140 / WI-156
  *
  * integration_contract.md §9 の確定ID一覧を静的定義で保持する ValidatorIdRegistry Adapter
  */
@@ -10,7 +10,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-013', 'L2-014', 'L2-015',
   'L3-001', 'L3-002', 'L3-003', 'L3-004',
-  'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005',
+  'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006',
 ]);
 
 export class ValidatorSystemValidatorIdRegistryAdapter {

package/scripts/harness/skill-quality/infrastructure/adapters/validator-id-registry-bridge-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit skill-quality
+ * @work-item-id WI-156
  */
 import type { ValidatorIdRegistryPort } from '../../domain/ports/validator-id-registry-port.js';
 
@@ -8,7 +9,7 @@ const FALLBACK_VALIDATOR_IDS = [
   'L1-001', 'L1-002', 'L1-003', 'L1-004', 'L1-005', 'L1-006', 'L1-007', 'L1-008',
   'L2-001', 'L2-002', 'L2-003',
   'L3-001', 'L3-002', 'L3-003', 'L3-004',
-  'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005',
+  'L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006',
 ];
 
 export class ValidatorIdRegistryBridgeAdapter implements ValidatorIdRegistryPort {

package/scripts/harness/validator-system/application/use-cases/run-l4-validators-usecase.ts

@@ -1,7 +1,7 @@
 /**
  * @layer application
  * @unit validator-system
- * @work-item-id WI-107
+ * @work-item-id WI-107 / WI-156
  *
  * RunL4ValidatorsUseCase — H08-03: L4バリデータ実行
  */
@@ -18,6 +18,8 @@ import type { DriftDetectionService } from '../../domain/services/l4/drift-detec
 import type { ConsistencyCheckService } from '../../domain/services/l4/consistency-check-service.js';
 import type { DeadCodeDetectionService } from '../../domain/services/l4/dead-code-detection-service.js';
 import type { ArchitectureSemanticAnalysisService } from '../../domain/services/l4/architecture-semantic-analysis-service.js';
+import { SkillCatalogDriftService } from '../../domain/services/l4/skill-catalog-drift-service.js';
+import type { SkillCatalogDriftPort } from '../../domain/ports/skill-catalog-drift-port.js';
 
 interface ScheduledHarnessErrorContract {
   readonly severity: string;
@@ -67,6 +69,7 @@ export interface RunL4ValidatorsUseCaseDeps {
   consistencyCheckService?: ConsistencyCheckService;
   deadCodeDetectionService?: DeadCodeDetectionService;
   architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
+  skillCatalogDriftPort?: SkillCatalogDriftPort;
   checkDocFreshnessUseCase?: CheckDocFreshnessUseCasePort;
   validateDocPointersUseCase?: ValidateDocPointersUseCasePort;
 }
@@ -80,6 +83,8 @@ export class RunL4ValidatorsUseCase {
   private readonly consistencyCheckService?: ConsistencyCheckService;
   private readonly deadCodeDetectionService?: DeadCodeDetectionService;
   private readonly architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
+  private readonly skillCatalogDriftPort?: SkillCatalogDriftPort;
+  private readonly skillCatalogDriftService = new SkillCatalogDriftService();
   private readonly checkDocFreshnessUseCase?: CheckDocFreshnessUseCasePort;
   private readonly validateDocPointersUseCase?: ValidateDocPointersUseCasePort;
 
@@ -92,6 +97,7 @@ export class RunL4ValidatorsUseCase {
     this.consistencyCheckService = deps.consistencyCheckService;
     this.deadCodeDetectionService = deps.deadCodeDetectionService;
     this.architectureSemanticAnalysisService = deps.architectureSemanticAnalysisService;
+    this.skillCatalogDriftPort = deps.skillCatalogDriftPort;
     this.checkDocFreshnessUseCase = deps.checkDocFreshnessUseCase;
     this.validateDocPointersUseCase = deps.validateDocPointersUseCase;
   }
@@ -206,6 +212,20 @@ export class RunL4ValidatorsUseCase {
       }
     }
 
+    if (this.skillCatalogDriftPort) {
+      const l4006Result = overrideMap.get('L4-006');
+      if (l4006Result && !l4006Result.skipped) {
+        const snapshot = await this.skillCatalogDriftPort.collect();
+        const report = this.skillCatalogDriftService.check(snapshot);
+        overrideMap.set(
+          'L4-006',
+          report.hasFindings()
+            ? ValidationResult.fail(ValidatorId.create('L4-006'), report.toHarnessErrors(), 0)
+            : ValidationResult.pass(ValidatorId.create('L4-006'), 0),
+        );
+      }
+    }
+
     const finalResults = definitions.map(
       (definition) => overrideMap.get(definition.validatorId.value) ?? ValidationResult.skip(definition.validatorId),
     );

package/scripts/harness/validator-system/composition-root.ts

@@ -3,7 +3,7 @@
  * @unit validator-system
  *
  * DI 組み立て — validator-system の全依存関係を構築する
- * @work-item-id WI-110 / WI-111 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+ * @work-item-id WI-110 / WI-111 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138 / WI-156
  */
 import { ValidatorId } from './domain/value-objects/validator-id.js';
 import { ValidatorDefinition } from './domain/value-objects/validator-definition.js';
@@ -36,6 +36,7 @@ import { BiomeAstSourceCodeAnalyzerAdapter } from './infrastructure/adapters/bio
 import { AdrFoundationReferenceAdapter } from './infrastructure/adapters/adr-foundation-reference-adapter.js';
 import { ImportGraphSourceAnalysisAdapter } from './infrastructure/adapters/import-graph-source-analysis-adapter.js';
 import { FileSystemArchitectureSemanticSourceAdapter } from './infrastructure/adapters/file-system-architecture-semantic-source-adapter.js';
+import { FileSystemSkillCatalogDriftAdapter } from './infrastructure/adapters/file-system-skill-catalog-drift-adapter.js';
 import { DriftDetectionService } from './domain/services/l4/drift-detection-service.js';
 import { ConsistencyCheckService } from './domain/services/l4/consistency-check-service.js';
 import { DeadCodeDetectionService } from './domain/services/l4/dead-code-detection-service.js';
@@ -52,7 +53,7 @@ const DEFAULT_CONFIG = {
   layers: {
     L2: { enabled: true, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] },
     L3: { enabled: true, validators: ['L3-001', 'L3-002', 'L3-003', 'L3-004'], coverageThreshold: 90, bundleSizeLimit: 512000 },
-    L4: { enabled: true, validators: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005'] },
+    L4: { enabled: true, validators: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006'] },
   },
   validate: { failOnWarning: false },
   architecture: {
@@ -108,6 +109,7 @@ export function buildDefaultRegistry(): ValidatorRegistry {
     createDef('L4-003', 'L4', 'strictOnly'),
     createDef('L4-004', 'L4', 'always'),
     createDef('L4-005', 'L4', 'always'),
+    createDef('L4-006', 'L4', 'always', 'SkillCatalogDriftPort'),
   ];
 
   return new ValidatorRegistry(definitions);
@@ -188,6 +190,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const adrReferencePort = new AdrFoundationReferenceAdapter();
   const sourceAnalysisPort = new ImportGraphSourceAnalysisAdapter();
   const architectureSemanticSourcePort = new FileSystemArchitectureSemanticSourceAdapter();
+  const skillCatalogDriftPort = new FileSystemSkillCatalogDriftAdapter(cwd);
 
   const driftDetectionService = new DriftDetectionService({
     designDocumentPort: markdownDesignDocumentPort,
@@ -215,6 +218,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     consistencyCheckService,
     deadCodeDetectionService,
     architectureSemanticAnalysisService,
+    skillCatalogDriftPort,
     checkDocFreshnessUseCase: phase2Extensions.checkDocFreshnessUseCase,
     validateDocPointersUseCase: phase2Extensions.validateDocPointersUseCase,
   });

package/scripts/harness/validator-system/domain/ports/skill-catalog-drift-port.ts

@@ -0,0 +1,10 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-156
+ */
+import type { SkillCatalogSnapshot } from '../services/l4/skill-catalog-drift-service.js';
+
+export interface SkillCatalogDriftPort {
+  collect(): Promise<SkillCatalogSnapshot>;
+}

package/scripts/harness/validator-system/domain/services/l4/skill-catalog-drift-service.ts

@@ -0,0 +1,108 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-156
+ */
+
+export interface SkillCountDeclaration {
+  readonly sourcePath: string;
+  readonly declaredCount: number;
+  readonly line: number;
+}
+
+export interface SkillCategoryDeclaration {
+  readonly sourcePath: string;
+  readonly categoryName: string;
+  readonly declaredCount: number;
+  readonly line: number;
+}
+
+export interface SkillCatalogSnapshot {
+  readonly actualSkillNames: readonly string[];
+  readonly countDeclarations: readonly SkillCountDeclaration[];
+  readonly categoryDeclarations: readonly SkillCategoryDeclaration[];
+}
+
+export interface SkillCatalogDriftFinding {
+  readonly kind: 'skill-count-mismatch' | 'skill-category-total-mismatch';
+  readonly sourcePath: string;
+  readonly message: string;
+  readonly suggestion: string;
+  readonly expectedCount: number;
+  readonly actualCount: number;
+  readonly line?: number;
+}
+
+export class SkillCatalogDriftReport {
+  readonly findings: readonly SkillCatalogDriftFinding[];
+
+  constructor(findings: readonly SkillCatalogDriftFinding[]) {
+    this.findings = Object.freeze([...findings]);
+    Object.freeze(this);
+  }
+
+  hasFindings(): boolean {
+    return this.findings.length > 0;
+  }
+
+  toHarnessErrors(): readonly {
+    readonly code: { readonly value: string; toString(): string };
+    readonly severity: { readonly value: string; toString(): string };
+    readonly message: string;
+    readonly suggestion: string;
+    readonly kind: string;
+    readonly sourcePath: string;
+    readonly expectedCount: number;
+    readonly actualCount: number;
+    readonly line?: number;
+  }[] {
+    return this.findings.map((finding) => ({
+      code: { value: 'L4-006', toString: () => 'L4-006' },
+      severity: { value: 'warning', toString: () => 'warning' },
+      message: finding.message,
+      suggestion: finding.suggestion,
+      kind: finding.kind,
+      sourcePath: finding.sourcePath,
+      expectedCount: finding.expectedCount,
+      actualCount: finding.actualCount,
+      line: finding.line,
+    }));
+  }
+}
+
+export class SkillCatalogDriftService {
+  check(snapshot: SkillCatalogSnapshot): SkillCatalogDriftReport {
+    const actualCount = snapshot.actualSkillNames.length;
+    const findings: SkillCatalogDriftFinding[] = [];
+
+    for (const declaration of snapshot.countDeclarations) {
+      if (declaration.declaredCount !== actualCount) {
+        findings.push({
+          kind: 'skill-count-mismatch',
+          sourcePath: declaration.sourcePath,
+          line: declaration.line,
+          expectedCount: actualCount,
+          actualCount: declaration.declaredCount,
+          message: `${declaration.sourcePath}:${declaration.line} declares ${declaration.declaredCount} skills, but skills/*/SKILL.md contains ${actualCount}.`,
+          suggestion: 'Update the documented skill count or add/remove the corresponding skill directory in the same release change.',
+        });
+      }
+    }
+
+    if (snapshot.categoryDeclarations.length > 0) {
+      const categoryTotal = snapshot.categoryDeclarations.reduce((sum, declaration) => sum + declaration.declaredCount, 0);
+      if (categoryTotal !== actualCount) {
+        findings.push({
+          kind: 'skill-category-total-mismatch',
+          sourcePath: snapshot.categoryDeclarations[0]?.sourcePath ?? 'docs/guide/skills-overview.md',
+          expectedCount: actualCount,
+          actualCount: categoryTotal,
+          message: `Skill category headings sum to ${categoryTotal} skills, but skills/*/SKILL.md contains ${actualCount}.`,
+          suggestion: 'Update docs/guide/skills-overview.md category heading counts so their sum matches the actual skill catalog.',
+        });
+      }
+    }
+
+    return new SkillCatalogDriftReport(findings);
+  }
+}

package/scripts/harness/validator-system/domain/value-objects/validator-id.ts

@@ -1,13 +1,14 @@
 /**
  * @layer domain
  * @unit validator-system
- * @work-item-id WI-116
+ * @work-item-id WI-116 / WI-156
  *
  * ValidatorId 値オブジェクト
- * L1-001〜L4-005 のバリデータを識別する不変値オブジェクト
+ * L1-001〜L4-006 のバリデータを識別する不変値オブジェクト
  * Wave 2A で L1-017, L1-018, L2-013 を追加
  * WI-140 で L2-014 を追加
  * WI-132/WI-133/WI-136/WI-137/WI-138 で L2-015 を追加
+ * WI-156 で L4-006 を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -40,6 +41,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   'L4-003': 'dead-code',
   'L4-004': 'doc-freshness',
   'L4-005': 'pointer-validation',
+  'L4-006': 'skill-catalog-drift',
 };
 
 /** バリデータ名 -> バリデータID の逆引きマップ */
@@ -50,6 +52,7 @@ const NAME_TO_ID_MAP: Record<string, string> = {
   'dead-code-detector': 'L4-003',
   'doc-freshness-checker': 'L4-004',
   'pointer-validator': 'L4-005',
+  'skill-catalog-drift': 'L4-006',
 };
 
 /** 有効なValidatorID集合 */

package/scripts/harness/validator-system/infrastructure/adapters/file-system-skill-catalog-drift-adapter.ts

@@ -0,0 +1,126 @@
+/**
+ * @layer infrastructure
+ * @unit validator-system
+ * @work-item-id WI-156
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type {
+  SkillCatalogSnapshot,
+  SkillCategoryDeclaration,
+  SkillCountDeclaration,
+} from '../../domain/services/l4/skill-catalog-drift-service.js';
+import type { SkillCatalogDriftPort } from '../../domain/ports/skill-catalog-drift-port.js';
+
+const MAINTAINED_COUNT_DOCS = [
+  'skills/README.md',
+  'README.md',
+  'DEVELOPMENT.md',
+  'docs/guide/installation.md',
+  'docs/guide/quick-vs-full-mode.md',
+  'docs/guide/skills-overview.md',
+] as const;
+
+const TOTAL_COUNT_PATTERNS = [
+  /\b(?:provides|contains|deploys)\s+(\d+)\s+skills\b/gi,
+  /\bfull catalogue of\s+(\d+)\s+skills\b/gi,
+  /--\s*(\d+)\s+skills\b/gi,
+  /#\s*(\d+)\s+skills\b/gi,
+  /配布対象は\s+(\d+)\s+skills\s+です/g,
+] as const;
+
+const CATEGORY_PATTERN = /^###\s+(.+?)\s+\((\d+)\s+skills\)\s*$/gm;
+
+export class FileSystemSkillCatalogDriftAdapter implements SkillCatalogDriftPort {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  async collect(): Promise<SkillCatalogSnapshot> {
+    const actualSkillNames = await this.readActualSkillNames();
+    const countDeclarations: SkillCountDeclaration[] = [];
+    let categoryDeclarations: SkillCategoryDeclaration[] = [];
+
+    for (const relativePath of MAINTAINED_COUNT_DOCS) {
+      const text = await this.readOptional(relativePath);
+      if (text === null) continue;
+      countDeclarations.push(...this.extractCountDeclarations(relativePath, text));
+      if (relativePath === 'docs/guide/skills-overview.md') {
+        categoryDeclarations = this.extractCategoryDeclarations(relativePath, text);
+      }
+    }
+
+    return {
+      actualSkillNames,
+      countDeclarations,
+      categoryDeclarations,
+    };
+  }
+
+  private async readActualSkillNames(): Promise<readonly string[]> {
+    const skillsRoot = join(this.cwd, 'skills');
+    let entries;
+    try {
+      entries = await readdir(skillsRoot, { withFileTypes: true });
+    } catch {
+      return Object.freeze([]);
+    }
+    const skillNames: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillPath = `skills/${entry.name}/SKILL.md`;
+      const text = await this.readOptional(skillPath);
+      if (text !== null) skillNames.push(entry.name);
+    }
+    return Object.freeze(skillNames.sort((a, b) => a.localeCompare(b)));
+  }
+
+  private async readOptional(relativePath: string): Promise<string | null> {
+    try {
+      return await readFile(join(this.cwd, relativePath), 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+
+  private extractCountDeclarations(sourcePath: string, text: string): SkillCountDeclaration[] {
+    const declarations: SkillCountDeclaration[] = [];
+    for (const pattern of TOTAL_COUNT_PATTERNS) {
+      for (const match of text.matchAll(pattern)) {
+        const rawCount = match[1];
+        const index = match.index;
+        if (!rawCount || index === undefined) continue;
+        if (this.lineTextAt(text, index).trimStart().startsWith('###')) continue;
+        declarations.push({
+          sourcePath,
+          declaredCount: Number.parseInt(rawCount, 10),
+          line: this.lineOf(text, index),
+        });
+      }
+    }
+    return declarations;
+  }
+
+  private extractCategoryDeclarations(sourcePath: string, text: string): SkillCategoryDeclaration[] {
+    return [...text.matchAll(CATEGORY_PATTERN)].flatMap((match) => {
+      const categoryName = match[1];
+      const rawCount = match[2];
+      const index = match.index;
+      if (!categoryName || !rawCount || index === undefined) return [];
+      return [{
+        sourcePath,
+        categoryName,
+        declaredCount: Number.parseInt(rawCount, 10),
+        line: this.lineOf(text, index),
+      }];
+    });
+  }
+
+  private lineOf(text: string, index: number): number {
+    return text.slice(0, index).split('\n').length;
+  }
+
+  private lineTextAt(text: string, index: number): string {
+    const lineStart = text.lastIndexOf('\n', index - 1) + 1;
+    const lineEnd = text.indexOf('\n', index);
+    return text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd);
+  }
+}

package/scripts/harness/validator-system/infrastructure/adapters/harness-config-validator-config-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-156
  *
  * HarnessConfigValidatorConfigAdapter — ValidatorConfigPort実装
  * HarnessConfigV2からLayerConfig VOを構築する
@@ -40,7 +41,7 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
     const defaultValidators: Record<string, string[]> = {
       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'],
+      L4: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006'],
     };
 
     const thresholds: Record<string, number> = {};

package/skills/phasegate-config-doctor/SKILL.md

@@ -127,7 +127,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 #### 観点 9: setup lifecycle と doctor finding
 
 - `phasegate doctor --json` の finding に `repairMode: "ai-assisted"` と `suggestedSkill.skillName = "phasegate-config-doctor"` がある → 本 skill が merge 方針、保持する user content、実行すべき `install --apply` / `--force` / `reconcile --apply` を提案する
-- Claude-only / Codex-only 導入後は `phasegate doctor --agent claude --json` または `phasegate doctor --agent codex --json` を使って selected agent の readiness を読む。`scopedOutFindings` は未選択 agent の `not-applicable` 情報なので、ユーザーがその agent を導入したいと言っていない限り repair 提案にしない。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`repairHintApplicability: "only-if-agent-selected"` はその agent を選んだ場合だけ修復 guidance が意味を持つという印である。<!-- @work-item-id WI-178, WI-179 -->
+- Claude-only / Codex-only 導入後は `phasegate doctor --agent claude --json` または `phasegate doctor --agent codex --json` を使って selected agent の readiness を読む。`scopedOutFindings` は未選択 agent の `not-applicable` 情報なので、ユーザーがその agent を導入したいと言っていない限り repair 提案にしない。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`currentScopeRepairTarget: false` と `repairModeApplicability: "only-if-agent-selected"` は raw `repairMode` が current scope の修復指示ではないという印である。<!-- @work-item-id WI-178, WI-179, WI-180 -->
 - `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
 - manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示
 - reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -132,7 +132,7 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 
 `setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->
 
-Claude-only / Codex-only setup の確認では、full `phasegate doctor` と scoped doctor を区別する。ユーザーが `setup:agent --agent claude` を選んだ場合は `phasegate doctor --agent claude --json` を優先し、`scopedOutFindings` の Codex finding は「未選択 agent の not-applicable 情報」であり修復対象ではないと説明する。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`repairHintApplicability: "only-if-agent-selected"` はその agent を選んだ場合だけ修復 guidance が意味を持つという印である。full doctor は両 agent を導入したい場合の診断として扱う。<!-- @work-item-id WI-178, WI-179 -->
+Claude-only / Codex-only setup の確認では、full `phasegate doctor` と scoped doctor を区別する。ユーザーが `setup:agent --agent claude` を選んだ場合は `phasegate doctor --agent claude --json` を優先し、`scopedOutFindings` の Codex finding は「未選択 agent の not-applicable 情報」であり修復対象ではないと説明する。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`currentScopeRepairTarget: false` と `repairModeApplicability: "only-if-agent-selected"` は `repairMode` が current scope の修復指示ではないという印である。full doctor は両 agent を導入したい場合の診断として扱う。<!-- @work-item-id WI-178, WI-179, WI-180 -->
 
 `setup:agent` は初回 setup / retrofit / CI-only / agent hook 有効化の agent-readable planner、`config:plan` は安全な設定変更 intent planner。質問が「次に何を実行するか」「この変更はどの file/validation に対応するか」に寄っている場合は、これらの guide と CLI を案内する。<!-- @work-item-id WI-171, WI-172, WI-173 -->