phasegate 0.160.1 → 0.160.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.2] - 2026-05-14
+
+### Fixed
+
+- **WI-185 / WI-186 / WI-188 — validator and gate trust** — fixes downstream P2 freshness/pointer scans so package-bin execution resolves caller project docs, makes `phasegate:status` JSON fail when enabled live layer validation fails while preserving its informational exit-code contract, and prevents `skill:check-coverage` from launching Vitest or network-prone auto-install paths before story/test prerequisites are validated.
+
 ## [0.160.1] - 2026-05-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.1",
+  "version": "0.160.2",
   "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/harness-api/domain/services/command-dispatch-service.ts

@@ -1,6 +1,6 @@
 // @layer domain
 // @unit harness-api
-// @work-item-id WI-108 / WI-114
+// @work-item-id WI-108 / WI-114, WI-186
 // command-dispatch-service.ts — CommandDispatchService Domain Service
 
 import { CommandRegistry } from './command-registry.js';
@@ -68,6 +68,16 @@ function summarizeLayerResults(items: readonly { validatorId: string; passed: bo
   return result;
 }
 
+function hasEnabledLiveFailure(
+  enabledLayers: readonly LayerId[],
+  liveValidationByLayer: Partial<Record<LayerId, LiveValidationState>>,
+): boolean {
+  return enabledLayers.some((layerId) => {
+    const liveState = liveValidationByLayer[layerId];
+    return liveState === 'fail' || liveState === 'error';
+  });
+}
+
 function buildOperationalWarnings(
   hookHealth: HookHealth | undefined,
   baselineHealth: BaselineHealth | undefined,
@@ -257,6 +267,13 @@ export class CommandDispatchService {
           baselineHealth,
           operationalWarnings,
         });
+        if (hasEnabledLiveFailure(presetInfo.enabledLayers, liveValidationByLayer)) {
+          const errors = statusSummary.layers
+            .filter((layer) => layer.enabled && (layer.liveValidationState === 'fail' || layer.liveValidationState === 'error'))
+            .map((layer) => makeError(`Layer ${layer.layerId} live validation ${layer.liveValidationState}`));
+          const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 }, statusSummary);
+          return { status: 'fail', errors: r.errors, summary: r.summary, data: statusSummary as unknown as T, exitCode: 0 };
+        }
         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/main.ts

@@ -193,6 +193,12 @@ Commands:
   phasegate:impact-analysis      Impact analysis for story (<storyId>, --json)
   phasegate:generate-matrix      Generate requirement-test matrix (--requirements, --tests, --out, --json)
 
+Gate semantics:
+  phasegate:complete-check       Gate: lint + all validators; exits 1 on failure
+  phasegate:check-ready          Gate: story phase readiness; exits 1 on pending/failed stories
+  validate --layer <Lx>          Gate: requested validator layer; exits 1 on layer failure
+  phasegate:status              Informational health; JSON status may be fail, exit remains 0 unless command error
+
   ci:generate-template         Generate CI template (--preset <id>, default: standard; --type <aidlc-gate|consistency-check|pre-commit|agent-context-refresh>, --render, --json)
   ci:migrate-agents-md         Migrate AGENTS.md (--dry-run, --validate-only, --json)
   ci:auto-refresh-agent-context Refresh AGENTS.md / CLAUDE.md (--dry-run, --apply, --json)
@@ -219,7 +225,7 @@ Commands:
   regression:migrate-v0-tests    Execute V0 test migration (--confirm)
 
   p2:check-freshness             Check doc freshness (--pattern <glob>, --dry-run, --format text|json)
-  p2:validate-pointers           Validate doc pointers (--include-urls, --format text|json)
+  p2:validate-pointers           Validate doc pointers (--pattern <glob>, --include-urls, --format text|json)
   p2:generate-e2e-template       Generate E2E test template (--phase <phase>, --output <path>)
   p2:check-initial-creation      Public compatibility detector for long-lived initial_creation:true docs (--pattern <glob>, --format text|json)
   hook <pre-tool-use|post-tool-use|stop|session-start|user-prompt-submit>  Run agent hook (reads JSON from stdin; writes JSON to stdout for session-start/user-prompt-submit)

package/scripts/harness/phase2-extensions/application/usecases/check-doc-freshness-usecase.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit phase2-extensions
+ * @work-item-id WI-185
  */
 import type { CheckDocFreshnessInput } from '../dto/check-doc-freshness-input.js';
 import type { CheckDocFreshnessOutput } from '../dto/check-doc-freshness-output.js';
@@ -29,18 +30,16 @@ export class CheckDocFreshnessUseCase {
   async execute(input: CheckDocFreshnessInput): Promise<CheckDocFreshnessOutput> {
     try {
       const rules = await this.freshnessConfigPort.loadRules();
-      const filteredRules = input.targetPattern
-        ? rules.filter((rule) => rule.documentPattern === input.targetPattern)
-        : rules;
 
       const results = [];
 
-      for (const rule of filteredRules) {
+      for (const rule of rules) {
         if (!rule.isEnabled()) {
           continue;
         }
 
-        const documentPaths = await this.documentScannerPort.scan(rule.documentPattern);
+        const scanPattern = input.targetPattern ?? rule.documentPattern;
+        const documentPaths = await this.documentScannerPort.scan(scanPattern);
         for (const documentPath of documentPaths) {
           const age = await this.documentAgePort.getAge(documentPath);
           results.push(this.freshnessCheckService.check(rule, age, documentPath));

package/scripts/harness/phase2-extensions/application/usecases/validate-doc-pointers-usecase.ts

@@ -1,7 +1,7 @@
 /**
  * @layer application
  * @unit phase2-extensions
- * @work-item-id WI-122
+ * @work-item-id WI-122, WI-185
  */
 import type { FreshnessConfigPort } from '../../domain/ports/freshness-config-port.js';
 import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
@@ -30,16 +30,14 @@ export class ValidateDocPointersUseCase {
   async execute(input: ValidateDocPointersInput): Promise<ValidateDocPointersOutput> {
     try {
       const rules = await this.freshnessConfigPort.loadPointerRules();
-      const filteredRules = input.targetPattern
-        ? rules.filter((rule) => rule.documentPattern === input.targetPattern)
-        : rules;
 
       const results = [];
       let totalDocuments = 0;
       let skippedUrlPointers = 0;
 
-      for (const rule of filteredRules) {
-        const documentPaths = await this.documentScannerPort.scan(rule.documentPattern);
+      for (const rule of rules) {
+        const scanPattern = input.targetPattern ?? rule.documentPattern;
+        const documentPaths = await this.documentScannerPort.scan(scanPattern);
         totalDocuments += documentPaths.length;
 
         for (const documentPath of documentPaths) {

package/scripts/harness/phase2-extensions/infrastructure/adapters/harness-config-freshness-adapter.ts

@@ -1,7 +1,7 @@
 /**
  * @layer infrastructure
  * @unit phase2-extensions
- * @work-item-id WI-122
+ * @work-item-id WI-122, WI-185
  */
 import type { HarnessConfigV2 } from '../../../config-foundation/domain/harness-config.js';
 import { DocFreshnessRule } from '../../domain/aggregates/doc-freshness-rule.js';
@@ -32,16 +32,20 @@ type Phase2RuleConfig = {
   };
 };
 
+function getPhase2RuleConfig(config: HarnessConfigV2 | Phase2RuleConfig | undefined): Phase2RuleConfig['phase2Extensions'] {
+  return (config as Phase2RuleConfig | undefined)?.phase2Extensions;
+}
+
 function normalizePathPatternRoot(value: string | undefined): string {
   const normalized = value?.replace(/\\/g, '/').replace(/\/+$/g, '');
-  return normalized && normalized.length > 0 ? normalized : 'docs/product/construction';
+  return normalized && normalized.length > 0 ? normalized : 'docs';
 }
 
 export class HarnessConfigFreshnessAdapter implements FreshnessConfigPort {
   constructor(private readonly config?: HarnessConfigV2 | Phase2RuleConfig) {}
 
   async loadRules(): Promise<DocFreshnessRule[]> {
-    const configRules = this.config && 'phase2Extensions' in this.config ? this.config.phase2Extensions?.freshnessRules : undefined;
+    const configRules = getPhase2RuleConfig(this.config)?.freshnessRules;
     if (!configRules || configRules.length === 0) {
       const designDocsRoot = normalizePathPatternRoot(this.config?.paths?.designDocs);
       return [
@@ -68,7 +72,7 @@ export class HarnessConfigFreshnessAdapter implements FreshnessConfigPort {
   }
 
   async loadPointerRules(): Promise<PointerRule[]> {
-    const configRules = this.config && 'phase2Extensions' in this.config ? this.config.phase2Extensions?.pointerRules : undefined;
+    const configRules = getPhase2RuleConfig(this.config)?.pointerRules;
     if (!configRules || configRules.length === 0) {
       const designDocsRoot = normalizePathPatternRoot(this.config?.paths?.designDocs);
       return [

package/scripts/harness/phase2-extensions/presentation/handlers/validate-pointers-handler.ts

@@ -1,6 +1,7 @@
 /**
  * @layer presentation
  * @unit phase2-extensions
+ * @work-item-id WI-185
  */
 import type { ValidateDocPointersUseCase } from '../../application/usecases/validate-doc-pointers-usecase.js';
 import { PointerResultFormatter } from '../formatters/pointer-result-formatter.js';
@@ -13,18 +14,22 @@ export class ValidatePointersHandler {
   async handle(args: string[]): Promise<{ exitCode: number; stdout: string }> {
     let includeUrlPointers = false;
     let format: 'text' | 'json' = 'text';
+    let targetPattern: string | undefined;
 
     for (let index = 0; index < args.length; index += 1) {
       const arg = args[index];
       if (arg === '--include-urls') {
         includeUrlPointers = true;
+      } else if (arg === '--pattern') {
+        targetPattern = args[index + 1];
+        index += 1;
       } else if (arg === '--format') {
         format = (args[index + 1] as 'text' | 'json') ?? 'text';
         index += 1;
       }
     }
 
-    const result = await this.useCase.execute({ includeUrlPointers, format });
+    const result = await this.useCase.execute({ targetPattern, includeUrlPointers, format });
     return {
       exitCode: result.passed ? 0 : 1,
       stdout: format === 'json' ? this.formatter.formatJson(result) : this.formatter.formatText(result),

package/scripts/harness/skill-quality/application/dto/check-coverage-output.ts

@@ -9,4 +9,6 @@ export interface CheckCoverageOutput {
   readonly meetsThreshold: boolean;
   readonly requirementThreshold: number;
   readonly codeThreshold: number;
+  readonly skipped?: boolean;
+  readonly skipReason?: 'no-tests';
 }

package/scripts/harness/skill-quality/application/usecases/check-coverage-usecase.ts

@@ -1,9 +1,11 @@
 /**
  * @layer application
  * @unit skill-quality
+ * @work-item-id WI-188
  */
 import { CoverageReport } from '../../domain/value-objects/coverage-report.js';
 import { RequirementCoverageResult } from '../../domain/value-objects/requirement-coverage-result.js';
+import { CodeCoverageResult } from '../../domain/value-objects/code-coverage-result.js';
 import type { RequirementTestMatrixPort } from '../../domain/ports/requirement-test-matrix-port.js';
 import type { CoverageRunnerPort } from '../../domain/ports/coverage-runner-port.js';
 import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
@@ -25,6 +27,20 @@ export class CheckCoverageUseCase {
       matrix.covered,
       matrix.uncoveredIds,
     );
+    if (matrix.total === 0) {
+      const coverageReport = CoverageReport.create(
+        requirementCoverage,
+        CodeCoverageResult.create(100, 100, 100),
+      );
+      return {
+        coverageReport,
+        meetsThreshold: true,
+        requirementThreshold: threshold.requirement,
+        codeThreshold: threshold.code,
+        skipped: true,
+        skipReason: 'no-tests',
+      };
+    }
     const codeCoverage = await this.coverageRunnerPort.run(input.storyId);
     const coverageReport = CoverageReport.create(requirementCoverage, codeCoverage);
     const meetsThreshold = coverageReport.meetsThreshold(threshold.requirement, threshold.code);

package/scripts/harness/skill-quality/domain/errors/skill-quality-error.ts

@@ -28,6 +28,7 @@ export type SkillQualityErrorCode =
   | "GIT_COMMIT_FAILED"
   | "COVERAGE_RUN_FAILED"
   | "MATRIX_FILE_NOT_FOUND"
+  | "STORY_NOT_FOUND"
   | "LESSON_ARTIFACT_SCHEMA_VIOLATION";
 
 export class SkillQualityError extends Error {

package/scripts/harness/skill-quality/infrastructure/adapters/file-system-requirement-test-matrix-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit skill-quality
+ * @work-item-id WI-188
  */
 import { readFile } from 'node:fs/promises';
 import type { RequirementTestMatrixPort, RequirementTestMatrix } from '../../domain/ports/requirement-test-matrix-port.js';
@@ -17,7 +18,12 @@ export class FileSystemRequirementTestMatrixAdapter implements RequirementTestMa
       throw new SkillQualityError('MATRIX_FILE_NOT_FOUND', `requirement-test-matrix.json not found at ${this.matrixFilePath}`);
     }
     const data = JSON.parse(raw) as Record<string, unknown>;
-    const entry = (data[storyId] ?? data) as { total: number; covered: number; uncoveredIds: string[] };
+    const rootEntry = data as { total?: unknown; covered?: unknown; uncoveredIds?: unknown };
+    const explicitEntry = data[storyId];
+    if (explicitEntry === undefined && rootEntry.total === undefined) {
+      throw new SkillQualityError('STORY_NOT_FOUND', `Story ${storyId} not found in ${this.matrixFilePath}`);
+    }
+    const entry = (explicitEntry ?? data) as { total: number; covered: number; uncoveredIds: string[] };
     return {
       storyId,
       total: entry.total ?? 0,

package/scripts/harness/skill-quality/infrastructure/adapters/vitest-coverage-runner-adapter.ts

@@ -1,17 +1,15 @@
 /**
  * @layer infrastructure
  * @unit skill-quality
+ * @work-item-id WI-188
  */
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import type { CoverageRunnerPort } from '../../domain/ports/coverage-runner-port.js';
 import { CodeCoverageResult } from '../../domain/value-objects/code-coverage-result.js';
 import { SkillQualityError } from '../../domain/errors/skill-quality-error.js';
 
-const COVERAGE_SUMMARY_PATH = path.join(process.cwd(), '.harness', 'coverage-summary.json');
-const COVERAGE_REPORTS_DIR = path.join(process.cwd(), '.harness');
-
 interface CoverageSummary {
   total: {
     lines: { pct: number };
@@ -20,15 +18,15 @@ interface CoverageSummary {
   };
 }
 
-function parseCoverageSummary(): CodeCoverageResult {
-  if (!existsSync(COVERAGE_SUMMARY_PATH)) {
+function parseCoverageSummary(coverageSummaryPath: string): CodeCoverageResult {
+  if (!existsSync(coverageSummaryPath)) {
     throw new SkillQualityError(
       'INVALID_COVERAGE_REPORT',
-      `Coverage summary not found at ${COVERAGE_SUMMARY_PATH}. Run: pnpm test --coverage first.`,
+      `Coverage summary not found at ${coverageSummaryPath}. Run: pnpm test --coverage first.`,
     );
   }
   try {
-    const raw = readFileSync(COVERAGE_SUMMARY_PATH, 'utf-8');
+    const raw = readFileSync(coverageSummaryPath, 'utf-8');
     const data = JSON.parse(raw) as CoverageSummary;
     const line = Math.round(data.total.lines.pct);
     const branch = Math.round(data.total.branches.pct);
@@ -43,19 +41,36 @@ function parseCoverageSummary(): CodeCoverageResult {
 }
 
 export class VitestCoverageRunnerAdapter implements CoverageRunnerPort {
+  constructor(
+    private readonly projectRoot: string = process.cwd(),
+    private readonly execFile: typeof execFileSync = execFileSync,
+  ) {}
+
   async run(_storyId: string): Promise<CodeCoverageResult> {
+    const coverageSummaryPath = path.join(this.projectRoot, '.harness', 'coverage-summary.json');
+    const coverageReportsDir = path.join(this.projectRoot, '.harness');
+    const vitestBin = path.join(this.projectRoot, 'node_modules', '.bin', 'vitest');
+
     // Use pre-existing summary if available
-    if (existsSync(COVERAGE_SUMMARY_PATH)) {
-      return parseCoverageSummary();
+    if (existsSync(coverageSummaryPath)) {
+      return parseCoverageSummary(coverageSummaryPath);
+    }
+
+    if (!existsSync(vitestBin) && !existsSync(path.join(this.projectRoot, 'node_modules', 'vitest', 'package.json'))) {
+      throw new SkillQualityError(
+        'COVERAGE_RUN_FAILED',
+        'Install vitest locally before running coverage: npm install -D vitest @vitest/coverage-v8',
+      );
     }
 
-    // Try to run vitest coverage (requires @vitest/coverage-v8)
+    // Run the local Vitest binary only; never use npx auto-install.
     try {
-      execSync(
-        `npx vitest run --coverage --coverage.reporter=json-summary "--coverage.reportsDirectory=${COVERAGE_REPORTS_DIR}"`,
-        { stdio: 'pipe', cwd: process.cwd() },
+      this.execFile(
+        vitestBin,
+        ['run', '--coverage', '--coverage.reporter=json-summary', `--coverage.reportsDirectory=${coverageReportsDir}`],
+        { stdio: 'pipe', cwd: this.projectRoot },
       );
-      return parseCoverageSummary();
+      return parseCoverageSummary(coverageSummaryPath);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes('coverage-v8') || msg.includes('MISSING DEPENDENCY')) {

package/scripts/harness/skill-quality/presentation/handlers/check-coverage-handler.ts

@@ -1,6 +1,7 @@
 /**
  * @layer presentation
  * @unit skill-quality
+ * @work-item-id WI-188
  */
 import type { CheckCoverageUseCase } from '../../application/usecases/check-coverage-usecase.js';
 
@@ -25,6 +26,10 @@ export class CheckCoverageHandler {
       const codeRate = output.coverageReport.codeCoverage.lineCoverage.toFixed(1);
       const msg = `Requirement coverage: ${reqRate}% (threshold: ${output.requirementThreshold}%)\nCode coverage: ${codeRate}% (threshold: ${output.codeThreshold}%)`;
 
+      if (output.skipped === true && output.skipReason === 'no-tests') {
+        return { exitCode: 0, message: `Coverage SKIPPED (no tests)\n${msg}` };
+      }
+
       if (output.meetsThreshold) {
         return { exitCode: 0, message: `Coverage OK\n${msg}` };
       }