@planu/cli 4.11.9 → 4.12.2

package/dist/engine/validation-evidence-ledger.js

@@ -0,0 +1,274 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, linkSync, appendFileSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { projectDataDir } from '../storage/base-store.js';
+import { VALIDATION_EVIDENCE_SCHEMA_VERSION, } from '../types/validation-evidence.js';
+import { digestValidationPaths, resolveValidationToolchain } from './validation-evidence-digest.js';
+const MAX_RECEIPT_BYTES = 128 * 1024;
+const PACKAGE_LOCKS = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb'];
+const LOCK_PATHS = {
+    typecheck: PACKAGE_LOCKS,
+    lint: PACKAGE_LOCKS,
+    'test-related': PACKAGE_LOCKS,
+    'test-full': PACKAGE_LOCKS,
+    security: [...PACKAGE_LOCKS, 'Cargo.lock'],
+    native: [...PACKAGE_LOCKS, 'Cargo.lock'],
+    website: PACKAGE_LOCKS,
+    reproducibility: [...PACKAGE_LOCKS, 'Cargo.lock'],
+};
+const CONFIG_PATHS = {
+    typecheck: ['package.json', 'pnpm-workspace.yaml', 'tsconfig.json', 'tsconfig.build.json'],
+    lint: ['package.json', 'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'],
+    'test-related': ['package.json', 'vitest.config.ts', 'vitest.config.mts', 'vitest.config.js'],
+    'test-full': ['package.json', 'vitest.config.ts', 'vitest.config.mts', 'vitest.config.js'],
+    security: ['package.json', 'pnpm-workspace.yaml', 'Cargo.toml'],
+    native: ['package.json', 'pnpm-workspace.yaml', 'Cargo.toml'],
+    website: ['package.json', 'website/package.json'],
+    reproducibility: ['package.json', 'pnpm-workspace.yaml', 'tsconfig.build.json', 'Cargo.toml'],
+};
+const CAPABILITY_PATHS = {
+    typecheck: [
+        'src',
+        'tests',
+        'package.json',
+        'pnpm-lock.yaml',
+        'tsconfig.json',
+        'tsconfig.build.json',
+    ],
+    lint: ['src', 'tests', 'package.json', 'pnpm-lock.yaml', 'eslint.config.js', 'eslint.config.mjs'],
+    'test-related': ['src', 'tests', 'package.json', 'pnpm-lock.yaml', 'vitest.config.ts'],
+    'test-full': ['src', 'tests', 'package.json', 'pnpm-lock.yaml', 'vitest.config.ts'],
+    security: [
+        'package.json',
+        'pnpm-lock.yaml',
+        'pnpm-workspace.yaml',
+        'Cargo.toml',
+        'Cargo.lock',
+        'npm',
+    ],
+    native: ['rust', 'npm', 'Cargo.toml', 'Cargo.lock', 'package.json', 'pnpm-lock.yaml'],
+    website: ['website', 'package.json', 'pnpm-lock.yaml'],
+    reproducibility: [
+        'src',
+        'rust',
+        'npm',
+        'scripts',
+        'package.json',
+        'pnpm-lock.yaml',
+        'tsconfig.build.json',
+    ],
+};
+export function normalizeValidationCommand(command) {
+    return command.trim().split(/\s+/).join(' ');
+}
+export function computeValidationEvidenceIdentity(input) {
+    const relevantPaths = input.relevantPaths ?? CAPABILITY_PATHS[input.capability];
+    const toolchain = resolveValidationToolchain(input);
+    return {
+        schemaVersion: VALIDATION_EVIDENCE_SCHEMA_VERSION,
+        capability: input.capability,
+        normalizedCommand: normalizeValidationCommand(input.command),
+        sourceTreeDigest: digestValidationPaths(input.projectPath, relevantPaths),
+        lockDigest: digestValidationPaths(input.projectPath, LOCK_PATHS[input.capability]),
+        configDigest: digestValidationPaths(input.projectPath, CONFIG_PATHS[input.capability]),
+        toolchainDigest: digestJson(toolchain),
+        selectedScopeDigest: digestJson([...new Set(input.scope.map(normalizeRelativePath))].sort()),
+    };
+}
+export function computeValidationEvidenceKey(identity) {
+    return digestJson(identity);
+}
+export function validationReceiptPath(projectId, key) {
+    if (!/^[a-f0-9]{64}$/.test(key)) {
+        throw new Error('Validation evidence key must be a SHA-256 hex digest.');
+    }
+    return join(projectDataDir(projectId), 'validation-evidence', `${key}.json`);
+}
+export function readMatchingValidationEvidence(projectId, input) {
+    const identity = computeValidationEvidenceIdentity(input);
+    const key = computeValidationEvidenceKey(identity);
+    const path = validationReceiptPath(projectId, key);
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_RECEIPT_BYTES) {
+            return null;
+        }
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!isMatchingSuccessfulReceipt(parsed, key, identity)) {
+            return null;
+        }
+        recordValidationEvidenceAudit(projectId, auditValidationEvidence(parsed, 'reused'));
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function recordSuccessfulValidationEvidence(args) {
+    const identity = computeValidationEvidenceIdentity(args.input);
+    const key = computeValidationEvidenceKey(identity);
+    if (args.expectedKey !== undefined && args.expectedKey !== key) {
+        recordValidationEvidenceAudit(args.projectId, {
+            key,
+            capability: args.input.capability,
+            action: 'invalidated',
+            producer: bounded(args.producer),
+            status: 'invalidated',
+            durationMs: Math.max(0, Math.round(args.durationMs)),
+            outputDigest: digestText(args.output),
+            reason: 'Validation inputs changed before evidence persistence.',
+            source: bounded(args.source ?? `local:${args.producer}`),
+            completedAt: new Date().toISOString(),
+            timeSavedMs: 0,
+        });
+        return null;
+    }
+    const existing = readMatchingValidationEvidence(args.projectId, args.input);
+    if (existing) {
+        return existing;
+    }
+    const receipt = {
+        schemaVersion: VALIDATION_EVIDENCE_SCHEMA_VERSION,
+        key,
+        identity,
+        producer: bounded(args.producer),
+        status: 'passed',
+        durationMs: Math.max(0, Math.round(args.durationMs)),
+        outputDigest: digestText(args.output),
+        reason: bounded(args.reason),
+        source: bounded(args.source ?? `local:${args.producer}`),
+        completedAt: new Date().toISOString(),
+        timeSavedMs: 0,
+    };
+    const persisted = writeReceiptAtomically(args.projectId, receipt);
+    recordValidationEvidenceAudit(args.projectId, auditValidationEvidence(persisted, 'executed'));
+    return persisted;
+}
+export function auditValidationEvidence(receipt, action) {
+    return {
+        key: receipt.key,
+        capability: receipt.identity.capability,
+        action,
+        producer: receipt.producer,
+        status: receipt.status,
+        durationMs: action === 'reused' ? 0 : receipt.durationMs,
+        outputDigest: receipt.outputDigest,
+        reason: receipt.reason,
+        source: receipt.source,
+        completedAt: receipt.completedAt,
+        timeSavedMs: action === 'reused' ? receipt.durationMs : receipt.timeSavedMs,
+    };
+}
+export function recordValidationEvidenceAudit(projectId, audit) {
+    const directory = join(projectDataDir(projectId), 'validation-evidence');
+    mkdirSync(directory, { recursive: true });
+    appendFileSync(join(directory, 'audit.jsonl'), `${JSON.stringify(audit)}\n`, {
+        encoding: 'utf-8',
+        flag: 'a',
+    });
+}
+export function recordValidationOutcome(args) {
+    const identity = computeValidationEvidenceIdentity(args.input);
+    recordValidationEvidenceAudit(args.projectId, {
+        key: computeValidationEvidenceKey(identity),
+        capability: args.input.capability,
+        action: args.action,
+        producer: bounded(args.producer),
+        status: args.status,
+        durationMs: Math.max(0, Math.round(args.durationMs)),
+        outputDigest: digestText(args.output),
+        reason: bounded(args.reason),
+        source: bounded(args.source ?? `local:${args.producer}`),
+        completedAt: new Date().toISOString(),
+        timeSavedMs: 0,
+    });
+}
+function writeReceiptAtomically(projectId, receipt) {
+    const path = validationReceiptPath(projectId, receipt.key);
+    mkdirSync(join(projectDataDir(projectId), 'validation-evidence'), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`, {
+            encoding: 'utf-8',
+            flag: 'wx',
+        });
+        try {
+            linkSync(temporary, path);
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) {
+                throw error;
+            }
+            const existing = JSON.parse(readFileSync(path, 'utf-8'));
+            if (!isMatchingSuccessfulReceipt(existing, receipt.key, receipt.identity) ||
+                stableJson(existing) !== stableJson(receipt)) {
+                throw new Error('Conflicting validation evidence already exists for the canonical key.', {
+                    cause: error,
+                });
+            }
+            return existing;
+        }
+        return receipt;
+    }
+    finally {
+        if (existsSync(temporary)) {
+            unlinkSync(temporary);
+        }
+    }
+}
+function isMatchingSuccessfulReceipt(value, key, identity) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const receipt = value;
+    if (receipt.schemaVersion !== VALIDATION_EVIDENCE_SCHEMA_VERSION ||
+        receipt.key !== key ||
+        receipt.status !== 'passed' ||
+        !receipt.identity ||
+        digestJson(receipt.identity) !== digestJson(identity) ||
+        typeof receipt.producer !== 'string' ||
+        receipt.producer.trim() === '' ||
+        typeof receipt.durationMs !== 'number' ||
+        receipt.durationMs < 0 ||
+        typeof receipt.outputDigest !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(receipt.outputDigest) ||
+        typeof receipt.reason !== 'string' ||
+        receipt.reason.trim() === '' ||
+        typeof receipt.source !== 'string' ||
+        receipt.source.trim() === '' ||
+        typeof receipt.completedAt !== 'string' ||
+        !Number.isFinite(Date.parse(receipt.completedAt)) ||
+        typeof receipt.timeSavedMs !== 'number') {
+        return false;
+    }
+    return computeValidationEvidenceKey(receipt.identity) === key;
+}
+function normalizeRelativePath(path) {
+    return path.trim().replaceAll('\\', '/').replace(/^\.\//, '');
+}
+function digestJson(value) {
+    return digestText(stableJson(value));
+}
+function digestText(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJson).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function bounded(value) {
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 2_000) {
+        throw new Error('Validation evidence strings must contain 1..2000 characters.');
+    }
+    return normalized;
+}
+//# sourceMappingURL=validation-evidence-ledger.js.map

package/dist/engine/validation-impact-planner.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationGateCapability, ValidationImpactPlan } from '../types/validation-evidence.js';
+export declare const VALIDATION_COMMANDS: Readonly<Record<ValidationGateCapability, string>>;
+export declare function planValidationImpact(paths: readonly string[]): ValidationImpactPlan;
+//# sourceMappingURL=validation-impact-planner.d.ts.map

package/dist/engine/validation-impact-planner.js

@@ -0,0 +1,71 @@
+export const VALIDATION_COMMANDS = {
+    typecheck: 'pnpm typecheck',
+    lint: 'pnpm lint',
+    'test-related': 'pnpm test --run --changed',
+    'test-full': 'pnpm test',
+    security: 'pnpm check:deps:fresh',
+    native: 'pnpm native:project-graph:e2e',
+    website: 'pnpm --dir website build',
+    reproducibility: 'bash scripts/check-reproducibility.sh',
+};
+const LIFECYCLE_RE = /^(?:planu\/|docs\/|README(?:\.|$)|CHANGELOG\.md$|[^/]+\.md$)/;
+const SOURCE_RE = /^(?:src\/|tests\/)/;
+const DEPENDENCY_RE = /^(?:package\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|npm\/[^/]+\/package\.json)/;
+const NATIVE_RE = /^(?:rust\/|Cargo\.(?:toml|lock)$|npm\/core-)/;
+const SHARED_RE = /^(?:\.github\/|\.husky\/|scripts\/|tsconfig(?:\.[^/]+)?\.json$|eslint\.config\.[^/]+$|vitest\.config\.[^/]+$)/;
+export function planValidationImpact(paths) {
+    const changedPaths = [...new Set(paths.map(normalizePath).filter(Boolean))].sort();
+    if (changedPaths.length === 0) {
+        return plan('none', [], false, 'No changed paths.', changedPaths);
+    }
+    if (changedPaths.every((path) => LIFECYCLE_RE.test(path))) {
+        return plan('lifecycle', [], false, 'Lifecycle/documentation-only change.', changedPaths);
+    }
+    if (changedPaths.some((path) => SHARED_RE.test(path))) {
+        return fullPlan('Shared validation, workflow, hook, or unknown infrastructure changed.', changedPaths);
+    }
+    const gates = new Set();
+    let kind = 'none';
+    for (const path of changedPaths) {
+        if (SOURCE_RE.test(path)) {
+            kind = kind === 'none' ? 'source' : kind;
+            gates.add('typecheck');
+            gates.add('lint');
+            gates.add('test-related');
+        }
+        else if (DEPENDENCY_RE.test(path)) {
+            kind = 'dependency';
+            gates.add('security');
+            gates.add('typecheck');
+            gates.add('lint');
+            gates.add('test-full');
+        }
+        else if (NATIVE_RE.test(path)) {
+            kind = 'native';
+            gates.add('native');
+            gates.add('test-full');
+        }
+        else if (path.startsWith('website/')) {
+            kind = kind === 'none' ? 'website' : kind;
+            gates.add('website');
+        }
+        else if (!LIFECYCLE_RE.test(path)) {
+            return fullPlan(`Unknown path selects fail-safe full validation: ${path}`, changedPaths);
+        }
+    }
+    return plan(kind, [...gates], gates.has('test-full'), `Selected by changed path class: ${kind}.`, changedPaths);
+}
+function fullPlan(reason, changedPaths) {
+    const gates = ['typecheck', 'lint', 'test-full', 'security'];
+    if (changedPaths.some((path) => path.startsWith('website/'))) {
+        gates.push('website');
+    }
+    return plan('full', gates, true, reason, changedPaths);
+}
+function plan(kind, gates, heavy, reason, changedPaths) {
+    return { kind, gates, heavy, reason, changedPaths };
+}
+function normalizePath(path) {
+    return path.trim().replaceAll('\\', '/').replace(/^\.\//, '');
+}
+//# sourceMappingURL=validation-impact-planner.js.map

package/dist/engine/validator/spec-compliance-runner.d.ts

@@ -40,7 +40,7 @@ export declare function parseFrontmatterScenarios(raw: string): FrontmatterScena
  * Run vitest-backed spec-compliance for the given spec.
  * Each frontmatter scenario must have a `tests` array; missing links count as `fail`.
  */
-export declare function runSpecCompliance(spec: Spec, projectPath: string): Promise<SpecComplianceResult>;
+export declare function runSpecCompliance(spec: Spec, projectPath: string, signal?: AbortSignal): Promise<SpecComplianceResult>;
 /**
  * Returns a list of scenario titles that lack a `tests` array.
  * Used by check-readiness to block `approved` when scenarios are untested.

package/dist/engine/validator/spec-compliance-runner.js

@@ -3,9 +3,10 @@
 // Replaces the text-matching approach in validateSpec with actual test execution.
 // Parses the `tests` array from each frontmatter scenario, spawns vitest, and
 // produces a per-scenario verdict based on real test outcomes.
-import { spawn } from 'node:child_process';
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readMatchingValidationEvidence } from '../validation-evidence-ledger.js';
+import { runAbortableProcess } from '../abortable-process-runner.js';
 // ---------------------------------------------------------------------------
 // Frontmatter scenario parser
 // ---------------------------------------------------------------------------
@@ -123,41 +124,26 @@ export function parseFrontmatterScenarios(raw) {
  * Spawn vitest with --reporter=json and collect the JSON output.
  * Returns null on timeout or spawn error.
  */
-function runVitest(testPaths, projectPath, timeoutMs = 120_000) {
-    return new Promise((resolve) => {
-        const args = ['--reporter=json', '--run', ...testPaths];
-        const child = spawn('pnpm', ['exec', 'vitest', ...args], {
-            cwd: projectPath,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        let stdout = '';
-        child.stdout.on('data', (chunk) => {
-            stdout += chunk.toString();
-        });
-        const timer = setTimeout(() => {
-            child.kill('SIGTERM');
-            resolve(null);
-        }, timeoutMs);
-        child.on('close', () => {
-            clearTimeout(timer);
-            try {
-                // vitest --reporter=json may include non-JSON lines; find the JSON object
-                const jsonStart = stdout.indexOf('{');
-                if (jsonStart === -1) {
-                    resolve(null);
-                    return;
-                }
-                const parsed = JSON.parse(stdout.slice(jsonStart));
-                resolve(parsed);
-            }
-            catch {
-                resolve(null);
-            }
-        });
-        child.on('error', () => {
-            clearTimeout(timer);
-            resolve(null);
-        });
+function runVitest(testPaths, projectPath, timeoutMs = 120_000, signal) {
+    const args = ['exec', 'vitest', '--reporter=json', '--run', ...testPaths];
+    return runAbortableProcess('pnpm', args, {
+        cwd: projectPath,
+        timeoutMs,
+        maxBufferBytes: 64 * 1024 * 1024,
+        signal,
+    }).then((result) => {
+        if (result.status !== 0 || result.error) {
+            return null;
+        }
+        try {
+            const jsonStart = result.stdout.indexOf('{');
+            return jsonStart === -1
+                ? null
+                : JSON.parse(result.stdout.slice(jsonStart));
+        }
+        catch {
+            return null;
+        }
     });
 }
 function resolveVitestTestFilePath(result) {
@@ -185,7 +171,7 @@ function resolveScenarioTestPath(link) {
  * Each frontmatter scenario must have a `tests` array; missing links count as `fail`.
  */
 // eslint-disable-next-line max-lines-per-function, complexity -- spec compliance runner: each section handles a discrete verification phase (file access, scenario parsing, test execution, verdict aggregation)
-export async function runSpecCompliance(spec, projectPath) {
+export async function runSpecCompliance(spec, projectPath, signal) {
     const { readFile } = await import('node:fs/promises');
     let raw;
     try {
@@ -227,11 +213,22 @@ export async function runSpecCompliance(spec, projectPath) {
     // ── Phase 3: run vitest for existing paths ───────────────────────────────
     const existingPaths = [...allTestPaths].filter((p) => existenceMap.get(p) === true);
     let vitestResult = null;
-    if (existingPaths.length > 0) {
-        vitestResult = await runVitest(existingPaths, projectPath);
+    const fullTestReceipt = readMatchingValidationEvidence(spec.projectId, {
+        projectPath,
+        capability: 'test-full',
+        command: 'pnpm test',
+        scope: ['src', 'tests'],
+    });
+    if (existingPaths.length > 0 && !fullTestReceipt) {
+        vitestResult = await runVitest(existingPaths, projectPath, 120_000, signal);
     }
     // Build a map: testFilePath -> pass/fail
     const testFileStatus = new Map();
+    if (fullTestReceipt) {
+        for (const path of existingPaths) {
+            testFileStatus.set(path, 'pass');
+        }
+    }
     if (vitestResult) {
         for (const tr of vitestResult.testResults) {
             const testFilePath = resolveVitestTestFilePath(tr);
@@ -272,7 +269,7 @@ export async function runSpecCompliance(spec, projectPath) {
                     verdicts.push('missing');
                     continue;
                 }
-                const status = testFileStatus.get(linkPath) ?? (vitestResult ? 'fail' : 'missing');
+                const status = testFileStatus.get(linkPath) ?? (vitestResult || fullTestReceipt ? 'fail' : 'missing');
                 if (status === 'pass') {
                     evidence.push(`${linkPath}: passed`);
                     verdicts.push('pass');

package/dist/engine/validator/validation-report-writer.d.ts

@@ -10,6 +10,7 @@ export declare function writeImplementationReviewReport(input: {
     lintPassed?: boolean;
     conventionRegression?: boolean;
     minimalityReport?: MinimalImplementationReport;
+    signal?: AbortSignal;
 }): Promise<{
     written: boolean;
     path?: string;

package/dist/engine/validator/validation-report-writer.js

@@ -1,7 +1,7 @@
 import { appendArtifact, readArtifact } from '../handoff-artifacts/io.js';
 import { runSpecCompliance, } from './spec-compliance-runner.js';
 export async function writeImplementationReviewReport(input) {
-    const specCompliance = await runSpecCompliance(input.spec, input.projectPath);
+    const specCompliance = await runSpecCompliance(input.spec, input.projectPath, input.signal);
     const reportScore = resolveExecutableValidationScore(input.score, specCompliance);
     const gates = buildGates({
         score: reportScore,

package/dist/engine/validator.js

@@ -7,6 +7,7 @@ import { scanCodeForSpec, checkCriterionEvidence, classifyDriftSeverity, quickQu
 import { resolveApplicableDimensions } from './validator/scope-resolver.js';
 import { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
 import { readEvidenceArtifacts } from './evidence-gates/artifact-reader.js';
+import { createCriterionIdentity } from './criterion-identity.js';
 // Re-export the full public API so external callers never need to know
 // about the sub-module layout.
 export { generateDoR, generateDoD } from './validator/dor-dod.js';
@@ -14,14 +15,6 @@ export { generateChecklist } from './validator/checklist.js';
 // SPEC-730: export scope-resolver and holistic-report for consumers
 export { resolveApplicableDimensions, normaliseScore } from './validator/scope-resolver.js';
 export { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
-function normalizeCriterionForEvidence(value) {
-    return value
-        .replace(/^-\s*\[[ xX]\]\s*/i, '')
-        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .toLowerCase();
-}
 function rowHasValidationEvidence(row) {
     const hasImplementationEvidence = [
         row.scenario?.trim(),
@@ -45,7 +38,7 @@ async function readTraceabilityEvidence(spec, projectPath) {
         const rows = artifacts.traceabilityMatrix?.rows ?? [];
         return new Map(rows
             .filter(rowHasValidationEvidence)
-            .map((row) => [normalizeCriterionForEvidence(row.acceptanceCriterion), row]));
+            .flatMap((row, index) => createCriterionIdentity(row.acceptanceCriterion, { index }).aliases.map((alias) => [alias, row])));
     }
     catch {
         return new Map();
@@ -100,9 +93,12 @@ export async function validateSpec(spec, projectPath) {
     const indeterminate = [];
     const extra = [];
     const qualityIssues = [];
-    for (const criterion of criteria) {
+    for (let criterionIndex = 0; criterionIndex < criteria.length; criterionIndex += 1) {
+        const criterion = criteria[criterionIndex] ?? '';
         const verifyBlock = verifyBlockMap.get(criterion);
-        const evidenceRow = traceabilityEvidence.get(normalizeCriterionForEvidence(criterion));
+        const evidenceRow = createCriterionIdentity(criterion, { index: criterionIndex })
+            .aliases.map((alias) => traceabilityEvidence.get(alias))
+            .find((row) => row !== undefined);
         if (evidenceRow !== undefined) {
             matches.push(criterion);
             continue;

package/dist/storage/convention-baseline.js

@@ -24,6 +24,11 @@ export async function getBaseline(projectId) {
  * Two violations with the same key are considered the same issue.
  */
 function violationKey(v) {
+    const claudeRule = /^(claude-md-[a-z-]+)-\d+$/.exec(v.ruleId);
+    if (claudeRule) {
+        const stableMessage = v.message.replace(/File has \d+ lines/, 'File exceeds line limit');
+        return `${claudeRule[1]}::${v.file}::${stableMessage}`;
+    }
     return `${v.ruleId}::${v.file}::${v.line ?? 0}`;
 }
 /**

package/dist/storage/session-state-store.js

@@ -3,6 +3,8 @@
 import { readJson, writeJson } from './base-store.js';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { getUniqueTopLevelFrontmatterString } from '../engine/frontmatter-parser.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -44,18 +46,23 @@ export async function getActiveSpecIds(projectPath) {
     try {
         const { glob } = await import('glob');
         const specFiles = await glob('planu/specs/*/spec.md', { cwd: projectPath });
-        const active = [];
+        const active = new Set();
         for (const f of specFiles) {
-            const { readFile } = await import('node:fs/promises');
-            const content = await readFile(join(projectPath, f), 'utf-8');
-            if (content.includes('status: implementing') || content.includes("status: 'implementing'")) {
+            try {
+                const content = await readFile(join(projectPath, f), 'utf-8');
+                if (getUniqueTopLevelFrontmatterString(content, 'status') !== 'implementing') {
+                    continue;
+                }
                 const match = /SPEC-\d+/.exec(f);
                 if (match) {
-                    active.push(match[0]);
+                    active.add(match[0]);
                 }
             }
+            catch {
+                // A single unreadable candidate must not suppress other valid active specs.
+            }
         }
-        return active;
+        return [...active];
     }
     catch {
         return [];

package/dist/storage/spec-store.d.ts

@@ -12,6 +12,11 @@ export declare function invalidateSpecsCache(projectId: string): void;
  * List every spec for a project.
  */
 export declare function listSpecs(projectId: string): Promise<Spec[]>;
+/**
+ * Run a read-modify side effect against a fresh spec snapshot while holding the
+ * same cross-process lock used by status mutations.
+ */
+export declare function withFreshSpecsLock<T>(projectId: string, fn: (specs: Spec[]) => Promise<T>): Promise<T>;
 /**
  * Get a single spec by ID. Returns `null` when not found.
  */

package/dist/storage/spec-store.js

@@ -131,6 +131,13 @@ export function invalidateSpecsCache(projectId) {
 export async function listSpecs(projectId) {
     return loadAll(projectId);
 }
+/**
+ * Run a read-modify side effect against a fresh spec snapshot while holding the
+ * same cross-process lock used by status mutations.
+ */
+export async function withFreshSpecsLock(projectId, fn) {
+    return withSpecMutationLock(projectId, async () => fn(await loadAll(projectId)));
+}
 /**
  * Get a single spec by ID. Returns `null` when not found.
  */

package/dist/tools/git/git-helpers.d.ts

@@ -1,6 +1,10 @@
 import { execFile as execFileCb } from 'node:child_process';
 import type { GitConfig, GitFlowType } from '../../types/index.js';
 export declare const execFile: typeof execFileCb.__promisify__;
+export interface GitExecutionOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
 /** Default branch prefixes by spec type. */
 export declare const DEFAULT_BRANCH_PREFIXES: Record<string, string>;
 /** Default protected branches. */
@@ -8,7 +12,7 @@ export declare const DEFAULT_PROTECTED_BRANCHES: string[];
 /** Default staleness threshold (commits behind). */
 export declare const DEFAULT_STALENESS_THRESHOLD = 50;
 /** Execute a git command in the project directory. */
-export declare function git(projectPath: string, args: string[]): Promise<{
+export declare function git(projectPath: string, args: string[], options?: GitExecutionOptions): Promise<{
     stdout: string;
     stderr: string;
 }>;

package/dist/tools/git/git-helpers.js

@@ -17,12 +17,13 @@ export const DEFAULT_PROTECTED_BRANCHES = ['main', 'master', 'develop', 'product
 /** Default staleness threshold (commits behind). */
 export const DEFAULT_STALENESS_THRESHOLD = 50;
 /** Execute a git command in the project directory. */
-export async function git(projectPath, args) {
+export async function git(projectPath, args, options = {}) {
     try {
         const result = await execFile('git', args, {
             cwd: projectPath,
             maxBuffer: 1024 * 1024 * 10,
-            timeout: 30_000,
+            timeout: options.timeoutMs ?? 30_000,
+            signal: options.signal,
         });
         return { stdout: result.stdout, stderr: result.stderr };
     }