@planu/cli 5.2.0 → 5.3.0

package/dist/engine/validator/analyzer.js

@@ -50,6 +50,7 @@ async function buildBroadCache(projectPath) {
 }
 import { deepCheckCriterion } from './deep-code-checker.js';
 import { ConfigLoader } from '../config-loader.js';
+import { filterValidatedTestPaths, groundNumericLiteral, createProbeCache, groundAgainstDeclaredTests, findBacktickIdentifierEvidence, } from './test-evidence-grounding.js';
 // ---------------------------------------------------------------------------
 // SPEC-209: Drift severity config (loaded from src/config/drift-severity.json)
 // ---------------------------------------------------------------------------
@@ -155,6 +156,50 @@ export async function scanCodeForSpec(spec, projectPath) {
     }
     return { affectedFiles, unexpectedFiles, fileContents };
 }
+/**
+ * Search codeState (then a broader project-wide cache) for a component/function
+ * identifier. Extracted from checkCriterionEvidence to keep its complexity bounded.
+ * This is the pre-existing (legacy, unquoted/single/double-quoted) search path —
+ * unchanged by SPEC-1367.
+ */
+async function findComponentEvidence(name, projectPath, codeState, sharedFileContents) {
+    // Search in already-loaded codeState contents first (zero extra I/O)
+    for (const [, content] of codeState.fileContents) {
+        if (content.includes(name)) {
+            return { status: 'proven' };
+        }
+    }
+    // Broader search: reuse sharedFileContents when provided to avoid a
+    // second glob+readFile pass. Falls back to a fresh (capped) read only
+    // when no shared cache is available.
+    const broadContents = sharedFileContents ?? (await buildBroadCache(projectPath));
+    for (const [, content] of broadContents) {
+        if (content.includes(name)) {
+            return { status: 'proven' };
+        }
+    }
+    return { status: 'missing' };
+}
+/**
+ * Match a criterion's "component/function/class/module/service NAME" shape
+ * and ground it, or return null when no such shape is present. Extracted
+ * from checkCriterionEvidence to keep its complexity bounded.
+ */
+async function checkComponentMatch(criterion, projectPath, codeState, sharedFileContents, safeTestPaths) {
+    // Legacy (pre-existing) quote forms only. Unchanged from pre-SPEC-1367 behavior.
+    const legacyComponentMatch = /(?:component|function|class|module|service)\s+["']?(\w+)["']?/i.exec(criterion);
+    if (legacyComponentMatch?.[1]) {
+        return findComponentEvidence(legacyComponentMatch[1], projectPath, codeState, sharedFileContents);
+    }
+    // SPEC-1367: identifiers are frequently backtick-quoted in BDD THEN clauses
+    // (e.g. "function `classifyValidationWatchEventForTests`"). This quote form
+    // is NEW — see findBacktickIdentifierEvidence for its restricted scope.
+    const backtickComponentMatch = /(?:component|function|class|module|service)\s+`(\w+)`/i.exec(criterion);
+    if (backtickComponentMatch?.[1]) {
+        return findBacktickIdentifierEvidence(backtickComponentMatch[1], projectPath, codeState, safeTestPaths);
+    }
+    return null;
+}
 /**
  * Check whether a single criterion is satisfied in the given code state.
  * When `verifyBlock` is provided it is forwarded to deepCheckCriterion,
@@ -164,7 +209,15 @@ export async function scanCodeForSpec(spec, projectPath) {
  * buildFileContentsCache from criterion-matcher) to avoid a redundant
  * glob+readFile pass when checking multiple criteria in the same call.
  */
-export async function checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents) {
+export async function checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents, declaredTestPaths, probeCache) {
+    // SPEC-1367 review finding 1: validate declared test paths ONCE, up front —
+    // they reach both a readFile call and a spawnSync argv further down. Every
+    // grounding path below uses `safeTestPaths`, never the raw parameter, and
+    // an empty result here (no declared tests, or all rejected) makes every
+    // new grounding path a no-op, per review finding 4.
+    const safeTestPaths = declaredTestPaths && declaredTestPaths.length > 0
+        ? await filterValidatedTestPaths(projectPath, declaredTestPaths)
+        : [];
     // Check for file existence criteria
     const fileMatch = /(?:create|add|implement)\s+(?:file\s+)?["']?([^\s"']+\.\w+)["']?/i.exec(criterion);
     if (fileMatch?.[1]) {
@@ -176,26 +229,10 @@ export async function checkCriterionEvidence(criterion, projectPath, codeState,
             return { status: 'missing' };
         }
     }
-    // Check for component/function existence in code
-    const componentMatch = /(?:component|function|class|module|service)\s+["']?(\w+)["']?/i.exec(criterion);
-    if (componentMatch?.[1]) {
-        const name = componentMatch[1];
-        // Search in already-loaded codeState contents first (zero extra I/O)
-        for (const [, content] of codeState.fileContents) {
-            if (content.includes(name)) {
-                return { status: 'proven' };
-            }
-        }
-        // Broader search: reuse sharedFileContents when provided to avoid a
-        // second glob+readFile pass. Falls back to a fresh (capped) read only
-        // when no shared cache is available.
-        const broadContents = sharedFileContents ?? (await buildBroadCache(projectPath));
-        for (const [, content] of broadContents) {
-            if (content.includes(name)) {
-                return { status: 'proven' };
-            }
-        }
-        return { status: 'missing' };
+    // Check for component/function existence in code (legacy + SPEC-1367 backtick forms)
+    const componentResult = await checkComponentMatch(criterion, projectPath, codeState, sharedFileContents, safeTestPaths);
+    if (componentResult) {
+        return componentResult;
     }
     // Check for API endpoint criteria
     const endpointMatch = /(?:endpoint|route|api)\s+(?:for\s+)?["']?(\w+)["']?/i.exec(criterion);
@@ -206,6 +243,16 @@ export async function checkCriterionEvidence(criterion, projectPath, codeState,
             }
         }
     }
+    // SPEC-1367 AC1: a declared-test-owned criterion citing a numeric literal
+    // (e.g. a timeout) is grounded against its own declared file(s) first — this
+    // takes priority over the generic keyword classifier below so the result
+    // carries a concrete evidence citation instead of a bare pass/fail.
+    if (safeTestPaths.length > 0) {
+        const literalGrounded = await groundNumericLiteral(criterion, projectPath, safeTestPaths);
+        if (literalGrounded) {
+            return literalGrounded;
+        }
+    }
     // Deep code check: grep/metric/coverage analysis on the actual filesystem.
     // If a verify block is present it is passed explicitly (bypasses keyword inference).
     // For non-manual checks, the deep result is authoritative.
@@ -214,6 +261,17 @@ export async function checkCriterionEvidence(criterion, projectPath, codeState,
     if (deepResult.checkType !== 'manual') {
         return { status: deepResult.passed ? 'proven' : 'missing' };
     }
+    // SPEC-1367: ground test-only criteria against their declared TEST file(s)
+    // (numeric-literal match, then a bounded evidence probe) before dead-ending
+    // at indeterminate/missing.
+    if (safeTestPaths.length > 0) {
+        // Review finding 2: without a caller-provided per-run cache, fall back to
+        // a call-local one — correctness never depends on cross-call reuse.
+        const grounded = groundAgainstDeclaredTests(projectPath, safeTestPaths, probeCache ?? createProbeCache());
+        if (grounded) {
+            return grounded;
+        }
+    }
     // Affected files alone show scope, not proof. Keep this visible so validate
     // cannot report score 100 for manual/unclassified criteria without evidence.
     if (codeState.affectedFiles.length > 0) {
@@ -221,8 +279,8 @@ export async function checkCriterionEvidence(criterion, projectPath, codeState,
     }
     return { status: 'missing' };
 }
-export async function checkCriterion(criterion, projectPath, codeState, verifyBlock, sharedFileContents) {
-    return ((await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents)).status === 'proven');
+export async function checkCriterion(criterion, projectPath, codeState, verifyBlock, sharedFileContents, declaredTestPaths) {
+    return ((await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents, declaredTestPaths)).status === 'proven');
 }
 /**
  * Classify the severity of a missing criterion based on its content.

package/dist/engine/validator/deep-code-checker.d.ts

@@ -1,5 +1,15 @@
 import type { DeepCheckResult, DeepCheckConfig, DeepCheckType, VerifyBlock } from '../../types/index.js';
 export type { DeepCheckResult, DeepCheckConfig, DeepCheckType };
+/** Strip underscore separators so "45_000" and "45000" compare equal. */
+export declare function normalizeNumericLiteral(literal: string): string;
+/**
+ * Build a regex source that matches a numeric literal regardless of any
+ * underscore separators present in the target text (e.g. "45000" also
+ * matches "45_000", "4_5000", etc. — any grouping).
+ */
+export declare function buildNumericLiteralPattern(literal: string): string;
+/** Extract timeout-shaped numeric literals (>= 3 significant digits) from criterion text. */
+export declare function extractNumericLiterals(text: string): string[];
 /**
  * Classify criterion text into a check type using keyword heuristics.
  * Returns the type and optional config derived from the criterion.

package/dist/engine/validator/deep-code-checker.js

@@ -7,6 +7,32 @@ const DEFAULT_IGNORE = ['node_modules/**', 'dist/**', 'build/**', '.git/**', 'co
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// ─── Numeric literal normalization (SPEC-1367) ───────────────────────────────
+// Grounds criteria whose THEN names an explicit numeric timeout (e.g. "45_000")
+// against test files that may spell the same literal without underscores (or
+// vice versa) — JS numeric separators are cosmetic, so the matcher must not
+// dead-end on them.
+/** Strip underscore separators so "45_000" and "45000" compare equal. */
+export function normalizeNumericLiteral(literal) {
+    return literal.replace(/_/g, '');
+}
+/**
+ * Build a regex source that matches a numeric literal regardless of any
+ * underscore separators present in the target text (e.g. "45000" also
+ * matches "45_000", "4_5000", etc. — any grouping).
+ */
+export function buildNumericLiteralPattern(literal) {
+    const digits = normalizeNumericLiteral(literal).split('').join('_?');
+    // Digit-boundary guards (review finding 3): without them "45_000" also
+    // matches inside "145000" or "45_0001". Reject a digit/underscore
+    // immediately before or after the run of matched digits.
+    return `(?<![\\d_])${digits}(?![\\d_])`;
+}
+/** Extract timeout-shaped numeric literals (>= 3 significant digits) from criterion text. */
+export function extractNumericLiterals(text) {
+    const tokens = text.match(/\d[\d_]*/g) ?? [];
+    return [...new Set(tokens.filter((token) => normalizeNumericLiteral(token).length >= 3))];
+}
 // ─── Keyword classification ──────────────────────────────────────────────────
 /**
  * Classify criterion text into a check type using keyword heuristics.
@@ -22,6 +48,13 @@ export function classifyCriterion(text) {
         lower.includes('remove all')) {
         return { type: 'grep_absent', config: buildAbsentConfig(text) };
     }
+    // SPEC-1367 review: a global numeric_timeout bucket used to live here,
+    // grepping tests/**/*.test.ts for ANY criterion mentioning "timeout" plus a
+    // number — including specs with no declared test ownership. That let an
+    // unrelated test file's literal prove a criterion it was never scoped to.
+    // Numeric-literal grounding is now exclusively declared-test-scoped: see
+    // `groundNumericLiteral` in analyzer.ts, which only runs when the criterion
+    // has declaredTestPaths. No declared tests -> no numeric grounding at all.
     // metric_max: file-size / line-count thresholds
     if (lower.includes('max lines') ||
         lower.includes('no file exceeds') ||

package/dist/engine/validator/test-evidence-grounding.d.ts

@@ -0,0 +1,56 @@
+import type { CodeState, CriterionEvidenceResult } from '../../types/index.js';
+/**
+ * Parse the spec.md frontmatter `scenarios` block and return, per criterion
+ * (matched by normalized scenario title), the declared TEST file paths.
+ * Reuses the already-tested frontmatter scenario parser from
+ * spec-compliance-runner.ts instead of re-implementing YAML parsing here.
+ */
+export declare function extractDeclaredTestPaths(specContent: string): Map<string, string[]>;
+/**
+ * SPEC-1367 review finding 2: the probe cache is created per validate
+ * invocation (see validateSpec) and threaded through explicitly — never
+ * module-level — so concurrent validate runs share no state and a probe
+ * result never outlives the run that produced it. Within one run, two
+ * criteria that declare the exact same test file(s) legitimately share one
+ * probe result — that is the intended "own declared TEST file" scoping.
+ */
+export declare function createProbeCache(): Map<string, {
+    passed: boolean;
+    evidence: string;
+}>;
+/**
+ * SPEC-1367 review finding 1: declared test paths originate from spec.md
+ * frontmatter and are used both as a readFile argument and as spawnSync
+ * argv — untrusted input reaching both a filesystem read and a subprocess
+ * argument list. Reject flag-injection shapes (leading "-"), require
+ * *.test.* naming, and require the path to resolve to a real, non-symlink
+ * file contained within the project root (traversal-safe).
+ */
+export declare function filterValidatedTestPaths(projectPath: string, testPaths: string[]): Promise<string[]>;
+/**
+ * AC1: static grounding — an explicit numeric literal (e.g. a timeout) named
+ * in the criterion is present in one of its declared TEST file(s), tolerating
+ * underscore separators in either direction. Runs ahead of the generic
+ * keyword classifier so declared-test ownership wins and cites evidence.
+ */
+export declare function groundNumericLiteral(criterion: string, projectPath: string, testPaths: string[]): Promise<CriterionEvidenceResult | null>;
+/**
+ * Ground a manual (unclassified) criterion against its declared TEST file(s)
+ * via a bounded evidence probe, before it dead-ends as indeterminate. Returns
+ * null when grounding is inconclusive, leaving the existing affectedFiles-based
+ * fallback to decide the final status.
+ */
+export declare function groundAgainstDeclaredTests(projectPath: string, testPaths: string[], probeCache: Map<string, {
+    passed: boolean;
+    evidence: string;
+}>): CriterionEvidenceResult | null;
+/**
+ * SPEC-1367 review finding 5 / AC4: backtick-quoted identifiers are the NEW
+ * quote form this spec adds (the legacy regex never matched a backtick, so
+ * this path is additive, not a behavior change for existing specs). Its
+ * search never falls back to the unrestricted project-wide scan — only the
+ * already-loaded codeState (same trust level as the legacy path) and the
+ * criterion's OWN validated declared test file(s).
+ */
+export declare function findBacktickIdentifierEvidence(name: string, projectPath: string, codeState: CodeState, safeTestPaths: string[]): Promise<CriterionEvidenceResult>;
+//# sourceMappingURL=test-evidence-grounding.d.ts.map

package/dist/engine/validator/test-evidence-grounding.js

@@ -0,0 +1,187 @@
+// Planu — Validator: declared-test-owned criterion grounding (SPEC-1367)
+//
+// Criteria whose only ownership evidence is a declared TEST file (frontmatter
+// `scenarios[].tests`) previously dead-ended at 'manual' -> indeterminate.
+// These helpers ground such criteria by (1) reading the declared file(s) for
+// an explicit numeric-literal match, (2) a backtick-quoted identifier search
+// scoped to those files, and (3) failing both, running a bounded evidence
+// probe scoped to exactly those declared files. Extracted from analyzer.ts
+// to keep that file under the subdirectory line-count budget.
+import { readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { extractNumericLiterals, buildNumericLiteralPattern } from './deep-code-checker.js';
+import { parseFrontmatterScenarios } from './spec-compliance-runner.js';
+import { normalizeCriterionText } from '../criterion-identity.js';
+import { resolveContainedProjectFile } from '../safety/contained-project-file.js';
+import { technologyValue } from '../technology-registry.js';
+/**
+ * Parse the spec.md frontmatter `scenarios` block and return, per criterion
+ * (matched by normalized scenario title), the declared TEST file paths.
+ * Reuses the already-tested frontmatter scenario parser from
+ * spec-compliance-runner.ts instead of re-implementing YAML parsing here.
+ */
+export function extractDeclaredTestPaths(specContent) {
+    const map = new Map();
+    for (const scenario of parseFrontmatterScenarios(specContent)) {
+        const paths = (scenario.tests ?? []).map((test) => test.path).filter(Boolean);
+        if (paths.length === 0) {
+            continue;
+        }
+        const key = normalizeCriterionText(scenario.title);
+        map.set(key, [...(map.get(key) ?? []), ...paths]);
+    }
+    return map;
+}
+const DEFAULT_PROBE_TIMEOUT_MS = 60_000;
+/**
+ * SPEC-1367 review finding 2: the probe cache is created per validate
+ * invocation (see validateSpec) and threaded through explicitly — never
+ * module-level — so concurrent validate runs share no state and a probe
+ * result never outlives the run that produced it. Within one run, two
+ * criteria that declare the exact same test file(s) legitimately share one
+ * probe result — that is the intended "own declared TEST file" scoping.
+ */
+export function createProbeCache() {
+    return new Map();
+}
+/**
+ * SPEC-1367 review finding 1: declared test paths originate from spec.md
+ * frontmatter and are used both as a readFile argument and as spawnSync
+ * argv — untrusted input reaching both a filesystem read and a subprocess
+ * argument list. Reject flag-injection shapes (leading "-"), require
+ * *.test.* naming, and require the path to resolve to a real, non-symlink
+ * file contained within the project root (traversal-safe).
+ */
+export async function filterValidatedTestPaths(projectPath, testPaths) {
+    const valid = [];
+    for (const candidate of testPaths) {
+        if (candidate.trim() !== candidate ||
+            candidate.length === 0 ||
+            candidate.startsWith('-') ||
+            !/\.test\.[^/\\]+$/.test(candidate)) {
+            continue;
+        }
+        try {
+            await resolveContainedProjectFile(projectPath, join(projectPath, candidate));
+            valid.push(candidate);
+        }
+        catch {
+            // outside the project root, a symlink, or missing on disk — reject
+        }
+    }
+    return valid;
+}
+/**
+ * Run ONLY the given declared test file(s) as a bounded evidence probe.
+ * Safety contract (SPEC-1367):
+ *  - refuses to start when already inside a probe (PLANU_VALIDATE_PROBE=1) — no recursion
+ *  - bounded by `timeoutMs` (default 60s, configurable via PLANU_VALIDATE_PROBE_TIMEOUT_MS)
+ *  - on timeout or crash the caller must treat the criterion as needs-evidence, never passed
+ *  - cached per (projectPath, sorted test paths) within the caller-supplied
+ *    per-run cache so criteria sharing the same declared test file(s) do not
+ *    re-spawn the runner
+ */
+function runEvidenceProbe(testPaths, projectPath, cache, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+    if (process.env.PLANU_VALIDATE_PROBE === '1') {
+        return {
+            passed: false,
+            evidence: 'Evidence probe skipped: already running inside a validate probe (recursion guard).',
+        };
+    }
+    const cacheKey = `${projectPath}::${[...testPaths].sort().join(',')}`;
+    const cached = cache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const pnpmExecutable = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+    const result = spawnSync(pnpmExecutable, ['exec', technologyValue('technology-vitest-a9127f'), 'run', ...testPaths], {
+        cwd: projectPath,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        env: { ...process.env, PLANU_VALIDATE_PROBE: '1' },
+    });
+    const outcome = result.error
+        ? { passed: false, evidence: `Evidence probe crashed: ${result.error.message}` }
+        : result.status === 0
+            ? { passed: true, evidence: (result.stdout || result.stderr || '').slice(-2000) }
+            : {
+                passed: false,
+                evidence: `Evidence probe failed (exit ${String(result.status)}): ${(result.stdout || result.stderr || '').slice(-2000)}`,
+            };
+    cache.set(cacheKey, outcome);
+    return outcome;
+}
+/**
+ * AC1: static grounding — an explicit numeric literal (e.g. a timeout) named
+ * in the criterion is present in one of its declared TEST file(s), tolerating
+ * underscore separators in either direction. Runs ahead of the generic
+ * keyword classifier so declared-test ownership wins and cites evidence.
+ */
+export async function groundNumericLiteral(criterion, projectPath, testPaths) {
+    const literals = extractNumericLiterals(criterion);
+    if (literals.length === 0) {
+        return null;
+    }
+    for (const testPath of testPaths) {
+        let content;
+        try {
+            content = await readFile(join(projectPath, testPath), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const literal of literals) {
+            if (new RegExp(buildNumericLiteralPattern(literal)).test(content)) {
+                return { status: 'proven', evidence: `${testPath}: matched numeric literal "${literal}"` };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Ground a manual (unclassified) criterion against its declared TEST file(s)
+ * via a bounded evidence probe, before it dead-ends as indeterminate. Returns
+ * null when grounding is inconclusive, leaving the existing affectedFiles-based
+ * fallback to decide the final status.
+ */
+export function groundAgainstDeclaredTests(projectPath, testPaths, probeCache) {
+    // AC2: bounded evidence probe — run exactly the declared test file(s).
+    // Review finding 7: an invalid override (e.g. "-1", "abc") must fall back
+    // to the default, never propagate a non-positive/NaN timeout to spawnSync.
+    const overrideMs = Number(process.env.PLANU_VALIDATE_PROBE_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(overrideMs) && overrideMs > 0 ? overrideMs : DEFAULT_PROBE_TIMEOUT_MS;
+    const probe = runEvidenceProbe(testPaths, projectPath, probeCache, timeoutMs);
+    if (probe.passed) {
+        return { status: 'proven', evidence: probe.evidence };
+    }
+    return null;
+}
+/**
+ * SPEC-1367 review finding 5 / AC4: backtick-quoted identifiers are the NEW
+ * quote form this spec adds (the legacy regex never matched a backtick, so
+ * this path is additive, not a behavior change for existing specs). Its
+ * search never falls back to the unrestricted project-wide scan — only the
+ * already-loaded codeState (same trust level as the legacy path) and the
+ * criterion's OWN validated declared test file(s).
+ */
+export async function findBacktickIdentifierEvidence(name, projectPath, codeState, safeTestPaths) {
+    for (const [, content] of codeState.fileContents) {
+        if (content.includes(name)) {
+            return { status: 'proven' };
+        }
+    }
+    for (const testPath of safeTestPaths) {
+        try {
+            const content = await readFile(join(projectPath, testPath), 'utf-8');
+            if (content.includes(name)) {
+                return { status: 'proven', evidence: `${testPath}: found identifier "${name}"` };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return { status: 'missing' };
+}
+//# sourceMappingURL=test-evidence-grounding.js.map

package/dist/engine/validator.js

@@ -4,6 +4,7 @@
 import { readFile } from 'node:fs/promises';
 import { extractCriteria, extractVerifyBlocks } from './validator/extractors.js';
 import { scanCodeForSpec, checkCriterionEvidence, classifyDriftSeverity, quickQualityCheck, } from './validator/analyzer.js';
+import { extractDeclaredTestPaths, createProbeCache } from './validator/test-evidence-grounding.js';
 import { resolveApplicableDimensions } from './validator/scope-resolver.js';
 import { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
 import { readEvidenceArtifacts, traceabilityRowHasCurrentCommandEvidence, traceabilityRowHasCurrentTestEvidence, } from './evidence-gates/artifact-reader.js';
@@ -64,6 +65,10 @@ async function readTraceabilityEvidence(spec, projectPath) {
  * normalised over the applicable set only.
  */
 export async function validateSpec(spec, projectPath) {
+    // SPEC-1367 review finding 2: the bounded evidence probe cache lives only
+    // for this validate invocation — concurrent runs share no state and a
+    // stale probe result can never outlive the file edit that invalidated it.
+    const probeCache = createProbeCache();
     // SPEC-730: Resolve applicable dimensions BEFORE running any checks
     const { applicable, skipped } = resolveApplicableDimensions(spec);
     // Emit structured warning when no dimensions apply (malformed frontmatter or future edge case)
@@ -89,14 +94,17 @@ export async function validateSpec(spec, projectPath) {
     const criteria = await extractCriteria(spec);
     const traceabilityEvidence = await readTraceabilityEvidence(spec, projectPath);
     const codeState = await scanCodeForSpec(spec, projectPath);
-    // Extract verify blocks from spec file (forgiving — empty map if file unreadable)
+    // Extract verify blocks and declared TEST file ownership from the spec file
+    // (forgiving — empty maps if the file is unreadable).
     let verifyBlockMap = new Map();
+    let declaredTestsMap = new Map();
     try {
         const specContent = await readFile(spec.specPath, 'utf-8');
         verifyBlockMap = extractVerifyBlocks(specContent);
+        declaredTestsMap = extractDeclaredTestPaths(specContent);
     }
     catch {
-        // spec file not available — proceed without verify blocks
+        // spec file not available — proceed without verify blocks or declared tests
     }
     const matches = [];
     const missing = [];
@@ -117,7 +125,8 @@ export async function validateSpec(spec, projectPath) {
             matches.push(criterion);
             continue;
         }
-        const evidence = await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock);
+        const declaredTestPaths = declaredTestsMap.get(criterionIdentity.normalizedText);
+        const evidence = await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, undefined, declaredTestPaths, probeCache);
         if (evidence.status === 'proven') {
             matches.push(criterion);
         }
@@ -180,11 +189,13 @@ export async function detectDrift(spec, projectPath, _mode = 'full', threshold =
         });
     }
     for (const criterion of validation.indeterminate ?? []) {
+        // SPEC-1367: reported as "needs-evidence" — distinct wording from "Missing"
+        // even though it scores identically to failing (excluded from `matches`).
         drifts.push({
             file: '',
             specCriterion: criterion,
             expected: 'Proven implementation evidence',
-            actual: 'Indeterminate',
+            actual: 'needs-evidence',
             severity: classifyDriftSeverity(criterion),
             autoFixable: false,
             suggestedFix: 'Add explicit validation evidence or implement a recognizable check.',

package/dist/tools/validate.js

@@ -730,7 +730,9 @@ function buildValidateStructuredContent(args) {
     const minimalityBlockingFindings = args.minimalityReport?.findings.filter((finding) => finding.blocksDone) ?? [];
     const blockers = [
         ...args.result.missing.map((missing) => `missing: ${missing}`),
-        ...args.indeterminate.map((item) => `indeterminate: ${item}`),
+        // SPEC-1367 review finding 6: matches detectDrift's "needs-evidence"
+        // wording — display text only, the `indeterminate` field/enum is unchanged.
+        ...args.indeterminate.map((item) => `needs-evidence: ${item}`),
         ...args.qualityGateSummary.failures.map((failure) => `gate: ${failure}`),
         ...args.qualityIssues
             .filter((issue) => isBlockingQualitySeverity(issue.severity))
@@ -872,7 +874,9 @@ function buildCompactValidateText(args) {
     const MAX_FAILURES = 5;
     const labelledFailures = [
         ...missing.map((criterion) => ({ label: 'missing', criterion })),
-        ...indeterminate.map((criterion) => ({ label: 'indeterminate', criterion })),
+        // SPEC-1367 review finding 6: display label only — matches detectDrift's
+        // "needs-evidence" wording; the underlying `indeterminate` array is unchanged.
+        ...indeterminate.map((criterion) => ({ label: 'needs-evidence', criterion })),
     ];
     const shownFailures = labelledFailures.slice(0, MAX_FAILURES);
     const remainingCount = labelledFailures.length - shownFailures.length;

package/dist/types/analysis.d.ts

@@ -203,6 +203,8 @@ export interface ValidateResult {
 export type CriterionEvidenceStatus = 'proven' | 'missing' | 'indeterminate';
 export interface CriterionEvidenceResult {
     status: CriterionEvidenceStatus;
+    /** SPEC-1367: citation for how the status was grounded (e.g. probe runner output, matched literal). */
+    evidence?: string;
 }
 export interface CodeState {
     affectedFiles: string[];

package/dist/types/validation-receipt.d.ts

@@ -28,6 +28,13 @@ export interface ValidationFreshnessLease {
     readonly epoch: string;
     readonly generation: number;
 }
+/**
+ * Classification of one raw filesystem watcher event feeding the freshness
+ * barrier: a direct relevant/ignored child path, a synthetic root event (the
+ * host OS reporting activity on the watched directory itself), or an
+ * ambiguous filename-less event that needs authoritative verification.
+ */
+export type ValidationWatchEventClassification = 'direct-relevant' | 'ignored' | 'synthetic' | 'ambiguous';
 export interface ValidationFreshnessWatchState {
     readonly epoch: string;
     readonly expiresAt: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -35,14 +35,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "5.2.0",
-    "@planu/core-darwin-x64": "5.2.0",
-    "@planu/core-linux-arm64-gnu": "5.2.0",
-    "@planu/core-linux-arm64-musl": "5.2.0",
-    "@planu/core-linux-x64-gnu": "5.2.0",
-    "@planu/core-linux-x64-musl": "5.2.0",
-    "@planu/core-win32-arm64-msvc": "5.2.0",
-    "@planu/core-win32-x64-msvc": "5.2.0"
+    "@planu/core-darwin-arm64": "5.3.0",
+    "@planu/core-darwin-x64": "5.3.0",
+    "@planu/core-linux-arm64-gnu": "5.3.0",
+    "@planu/core-linux-arm64-musl": "5.3.0",
+    "@planu/core-linux-x64-gnu": "5.3.0",
+    "@planu/core-linux-x64-musl": "5.3.0",
+    "@planu/core-win32-arm64-msvc": "5.3.0",
+    "@planu/core-win32-x64-msvc": "5.3.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -161,8 +161,8 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.115.0",
-    "@hono/node-server": "2.0.11",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@hono/node-server": "2.1.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "glob": "^13.0.6",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
@@ -173,16 +173,16 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@lhci/cli": "0.15.1",
-    "@napi-rs/cli": "3.7.4",
+    "@napi-rs/cli": "3.8.2",
     "@noble/hashes": "2.2.0",
-    "@playwright/test": "1.62.0",
+    "@playwright/test": "1.62.1",
     "@scure/base": "2.2.0",
     "@secretlint/secretlint-rule-no-homedir": "^13.0.4",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.4",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@supabase/supabase-js": "^2.110.8",
-    "@types/node": "^26.1.1",
+    "@supabase/supabase-js": "^2.112.0",
+    "@types/node": "^26.1.2",
     "@types/qrcode": "1.5.6",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitejs/plugin-vue": "^6.0.8",
@@ -196,17 +196,17 @@
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.5.0",
     "jiti": "2.7.0",
-    "knip": "^6.29.0",
-    "lint-staged": "^17.2.0",
+    "knip": "^6.31.0",
+    "lint-staged": "^17.3.0",
     "madge": "^8.0.0",
     "prettier": "^3.9.6",
     "qrcode": "1.5.4",
     "secretlint": "^13.0.4",
     "tsc-alias": "^1.9.1",
-    "type-coverage": "^2.29.7",
+    "type-coverage": "^2.30.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "^8.65.0",
-    "vite": "^8.1.5",
+    "typescript-eslint": "^8.66.0",
+    "vite": "^8.2.0",
     "vitest": "^4.1.10",
     "vue": "^3.5.40"
   }