@planu/cli 4.11.9 → 4.12.2

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -1,4 +1,5 @@
 import { hasAnyAffirmedMatch } from '../text-signal-boundaries.js';
+import { createCriterionIdentity } from '../criterion-identity.js';
 const CONTRACT_HINTS = {
     api: [
         /\b(?:public|external|rest|http)[ -]?api\b/i,
@@ -20,30 +21,6 @@ const CONTRACT_HINTS = {
 function isNonTrivial(spec) {
     return spec.scope !== 'trivial';
 }
-function normalizeCriterion(value) {
-    const withoutCheckbox = value.replace(/^-\s*\[[ x]\]\s*/i, '').trim();
-    const criterionOnly = /^([A-Z]{2}\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
-    if (criterionOnly) {
-        return criterionOnly.toLowerCase();
-    }
-    return withoutCheckbox
-        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .toLowerCase();
-}
-function criterionAliases(value, index) {
-    const aliases = new Set([
-        normalizeCriterion(value),
-        `ac${String(index + 1)}`,
-        `ab${String(index + 1)}`,
-    ]);
-    const explicit = /^([A-Z]{2}\d+)\b/i.exec(value)?.[1];
-    if (explicit) {
-        aliases.add(normalizeCriterion(explicit));
-    }
-    return [...aliases].filter((alias) => alias.length > 0);
-}
 function hasText(value) {
     return value !== undefined && value.trim().length > 0;
 }
@@ -90,8 +67,8 @@ export function checkTaskPlanGate(spec, criteria, artifacts) {
             },
         ];
     }
-    const covered = new Set(artifacts.taskPlan.tasks.flatMap((task) => task.acceptanceCriteria.map(normalizeCriterion)));
-    const uncovered = criteria.filter((criterion, index) => !criterionAliases(criterion, index).some((alias) => covered.has(alias)));
+    const covered = new Set(artifacts.taskPlan.tasks.flatMap((task) => task.acceptanceCriteria.flatMap((criterion, index) => createCriterionIdentity(criterion, { index }).aliases)));
+    const uncovered = criteria.filter((criterion, index) => !createCriterionIdentity(criterion, { index }).aliases.some((alias) => covered.has(alias)));
     if (uncovered.length === 0) {
         return [];
     }
@@ -108,6 +85,22 @@ function rowHasEvidence(row) {
         (row.contractEvidence !== undefined && row.contractEvidence.length > 0) ||
         hasText(row.manualEvidence));
 }
+function describeIncompleteRow(row) {
+    const missing = [];
+    if (!rowHasEvidence(row)) {
+        missing.push('scenario/testEvidence/contractEvidence/manualEvidence');
+    }
+    if (row.changedFiles.length === 0) {
+        missing.push('changedFiles');
+    }
+    if (!hasText(row.validationEvidence)) {
+        missing.push('validationEvidence');
+    }
+    if (!hasText(row.reviewerEvidence)) {
+        missing.push('reviewerEvidence');
+    }
+    return `${row.acceptanceCriterion}: missing ${missing.join(', ')}`;
+}
 export function checkDoneEvidenceGate(spec, criteria, artifacts) {
     const issues = [];
     const matrix = artifacts.traceabilityMatrix;
@@ -118,8 +111,8 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
         });
     }
     else {
-        const covered = new Set(matrix.rows.map((row) => normalizeCriterion(row.acceptanceCriterion)));
-        const uncovered = criteria.filter((criterion, index) => !criterionAliases(criterion, index).some((alias) => covered.has(alias)));
+        const covered = new Set(matrix.rows.flatMap((row, index) => createCriterionIdentity(row.acceptanceCriterion, { index }).aliases));
+        const uncovered = criteria.filter((criterion, index) => !createCriterionIdentity(criterion, { index }).aliases.some((alias) => covered.has(alias)));
         if (uncovered.length > 0) {
             issues.push({
                 code: 'traceability_uncovered_criteria',
@@ -131,22 +124,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
             !hasText(row.validationEvidence) ||
             !hasText(row.reviewerEvidence));
         if (incompleteRows.length > 0) {
-            const rowDetails = incompleteRows.map((row) => {
-                const missing = [];
-                if (!rowHasEvidence(row)) {
-                    missing.push('scenario/testEvidence/contractEvidence/manualEvidence');
-                }
-                if (row.changedFiles.length === 0) {
-                    missing.push('changedFiles');
-                }
-                if (!hasText(row.validationEvidence)) {
-                    missing.push('validationEvidence');
-                }
-                if (!hasText(row.reviewerEvidence)) {
-                    missing.push('reviewerEvidence');
-                }
-                return `${row.acceptanceCriterion}: missing ${missing.join(', ')}`;
-            });
+            const rowDetails = incompleteRows.map(describeIncompleteRow);
             issues.push({
                 code: 'traceability_incomplete_rows',
                 message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}`,

package/dist/engine/evidence-index/index-builder.js

@@ -1,16 +1,16 @@
-import { createHash } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { isAbsolute, join, normalize } from 'node:path';
+import { createCriterionIdentity, criterionIdentitiesMatch } from '../criterion-identity.js';
 export function criterionKey(criterion) {
-    const normalized = normalizeCriterion(criterion);
-    return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+    return createCriterionIdentity(criterion).stableKey;
 }
 export async function buildSpecEvidenceIndex(args) {
     const diagnostics = [...args.artifacts.invalidArtifacts];
     const matrixRows = args.artifacts.traceabilityMatrix?.rows ?? [];
     const contractValidations = args.artifacts.contractValidations;
-    const entries = await Promise.all(args.criteria.map(async (criterion) => {
-        const rows = matrixRows.filter((row) => normalizeCriterion(row.acceptanceCriterion) === normalizeCriterion(criterion));
+    const entries = await Promise.all(args.criteria.map(async (criterion, criterionIndex) => {
+        const identity = createCriterionIdentity(criterion, { index: criterionIndex });
+        const rows = matrixRows.filter((row, rowIndex) => criterionIdentitiesMatch(createCriterionIdentity(row.acceptanceCriterion, { index: rowIndex }), identity));
         const evidence = await collectEvidence({
             rows,
             contractValidations,
@@ -19,7 +19,7 @@ export async function buildSpecEvidenceIndex(args) {
         });
         return {
             criterion,
-            criterionKey: criterionKey(criterion),
+            criterionKey: identity.stableKey,
             evidence,
         };
     }));
@@ -149,7 +149,7 @@ function looksLikeShellCommand(value) {
     if (/\s/.test(trimmed) && !/\.[A-Za-z0-9]+$/.test(trimmed)) {
         return true;
     }
-    return /^(?:pnpm|npm|yarn|bun|npx|node|tsx|tsc|vitest|jest|git|bash|sh)\b/.test(trimmed);
+    return /^(?:pnpm|npm|yarn|bun|npx|node|tsx|tsc|vitest|jest|git|bash|sh)(?:\s|$)/.test(trimmed);
 }
 function looksLikeGlob(value) {
     return /[*?[\]{}]/.test(value);
@@ -157,16 +157,4 @@ function looksLikeGlob(value) {
 function record(kind, value, status, source, reason) {
     return { kind, value, status, source, ...(reason ? { reason } : {}) };
 }
-function normalizeCriterion(value) {
-    const withoutCheckbox = value.replace(/^-\s*\[[ x]\]\s*/i, '').trim();
-    const criterionOnly = /^([A-Z]{2}\d+)\s*[:.)-]?\s*$/i.exec(withoutCheckbox)?.[1];
-    if (criterionOnly) {
-        return criterionOnly.toLowerCase();
-    }
-    return withoutCheckbox
-        .replace(/^[A-Z]{2}\d+\s*[:.)-]?\s*/i, '')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .toLowerCase();
-}
 //# sourceMappingURL=index-builder.js.map

package/dist/engine/frontmatter-parser.d.ts

@@ -5,6 +5,11 @@ import type { FrontmatterResult } from '../types/frontmatter.js';
  * Returns the original content as body if no frontmatter is found.
  */
 export declare function parseFrontmatter(content: string): FrontmatterResult;
+/**
+ * Read one unambiguous top-level string field from the canonical frontmatter block.
+ * Missing, malformed, nested, non-string, or duplicated fields fail closed.
+ */
+export declare function getUniqueTopLevelFrontmatterString(content: string, key: string): string | null;
 /**
  * Strip YAML frontmatter from markdown content, returning only the body.
  * If no frontmatter is present, returns the original content unchanged.

package/dist/engine/frontmatter-parser.js

@@ -36,6 +36,30 @@ export function parseFrontmatter(content) {
     }
     return { metadata, body: match[2] };
 }
+/**
+ * Read one unambiguous top-level string field from the canonical frontmatter block.
+ * Missing, malformed, nested, non-string, or duplicated fields fail closed.
+ */
+export function getUniqueTopLevelFrontmatterString(content, key) {
+    if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) {
+        return null;
+    }
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match?.[1] || match[2] === undefined) {
+        return null;
+    }
+    const fieldPattern = new RegExp(`^${key}:\\s*(.*)$`);
+    const values = match[1]
+        .split('\n')
+        .map((line) => fieldPattern.exec(line)?.[1])
+        .filter((value) => value !== undefined);
+    const value = values[0];
+    if (values.length !== 1 || value === undefined) {
+        return null;
+    }
+    const parsed = parseScalar(value.trim());
+    return typeof parsed === 'string' && parsed.length > 0 ? parsed : null;
+}
 function parseScalar(value) {
     if (value.startsWith('[') && value.endsWith(']')) {
         return value

package/dist/engine/project-command-runtime.d.ts

@@ -0,0 +1,5 @@
+import type { AbortableProcessResult, ProjectCommandPlan } from '../types/abortable-process.js';
+export declare function resolveProjectCommandPlan(projectPath: string, requestedCommand: string, corepackAvailable?: boolean): ProjectCommandPlan;
+export declare function formatLintFailureDiagnostics(plan: ProjectCommandPlan, output: string): string;
+export declare function runProjectCommandPlan(plan: ProjectCommandPlan, projectPath: string, timeoutMs: number, signal?: AbortSignal): Promise<AbortableProcessResult>;
+//# sourceMappingURL=project-command-runtime.d.ts.map

package/dist/{tools/validate-runtime.js → engine/project-command-runtime.js}

@@ -1,6 +1,5 @@
-// tools/validate-runtime.ts — Project-aware command execution helpers for validate.
-import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { runAbortableProcess } from './abortable-process-runner.js';
 function readProjectPackageManager(projectPath) {
     try {
         const raw = readFileSync(`${projectPath}/package.json`, 'utf-8');
@@ -14,20 +13,7 @@ function readProjectPackageManager(projectPath) {
 function shellTokens(command) {
     return command.split(/\s+/).filter((token) => token.length > 0);
 }
-function canRunCorepack(projectPath) {
-    try {
-        execFileSync('corepack', ['--version'], {
-            cwd: projectPath,
-            stdio: ['ignore', 'ignore', 'ignore'],
-            timeout: 5_000,
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function resolveProjectCommandPlan(projectPath, requestedCommand, corepackAvailable = canRunCorepack(projectPath)) {
+export function resolveProjectCommandPlan(projectPath, requestedCommand, corepackAvailable = true) {
     const projectPackageManager = readProjectPackageManager(projectPath);
     const tokens = shellTokens(requestedCommand);
     const usesPnpm = tokens[0] === 'pnpm';
@@ -75,11 +61,12 @@ export function formatLintFailureDiagnostics(plan, output) {
     }
     return lines.filter((line, index) => index !== 0 || line.length > 0).join('\n');
 }
-export function runProjectCommandPlan(plan, projectPath, timeoutMs) {
-    execFileSync(plan.executable, plan.args, {
+export function runProjectCommandPlan(plan, projectPath, timeoutMs, signal) {
+    return runAbortableProcess(plan.executable, plan.args, {
         cwd: projectPath,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: timeoutMs,
+        timeoutMs,
+        maxBufferBytes: 64 * 1024 * 1024,
+        signal,
     });
 }
-//# sourceMappingURL=validate-runtime.js.map
+//# sourceMappingURL=project-command-runtime.js.map

package/dist/engine/project-graph/builder.js

@@ -135,37 +135,6 @@ function nativeCoreCacheVersion(runtime) {
         : 'typescript-fallback';
     return `${NATIVE_PROJECT_GRAPH_IMPLEMENTATION_VERSION}:${mode}`;
 }
-async function collectGitSource(projectPath) {
-    try {
-        const { execFile } = await import('node:child_process');
-        const stdout = await new Promise((resolveOutput, reject) => {
-            execFile('git', ['rev-parse', 'HEAD'], { cwd: projectPath }, (error, output) => {
-                if (error) {
-                    reject(new Error('git rev-parse failed', { cause: error }));
-                    return;
-                }
-                resolveOutput(output);
-            });
-        });
-        const head = stdout.trim();
-        if (head.length === 0) {
-            return null;
-        }
-        return {
-            id: 'project-git',
-            kind: 'project-git',
-            path: '.git/log',
-            content: head,
-            hash: hashText(head),
-            size: Buffer.byteLength(head),
-            mtimeMs: 0,
-            contentLoaded: true,
-        };
-    }
-    catch {
-        return null;
-    }
-}
 async function extractSourceFragment(args) {
     if (args.source.kind === 'spec') {
         return extractSpecGraph(args.source, args.policy);
@@ -209,16 +178,13 @@ async function buildProjectKnowledgeGraphUnlocked(args) {
     const cacheResult = await readProjectGraphCache(args.projectId, args.policy);
     const previousCache = cacheResult.cache;
     const previousRecords = previousCache?.records ?? {};
-    const collected = await collectProjectGraphSources({
+    let sources = await collectProjectGraphSources({
         projectId: args.projectId,
         projectPath: args.projectPath,
         policy: args.policy,
         previous: previousRecords,
         nativeCoreVersion,
     });
-    const gitSource = await collectGitSource(args.projectPath);
-    let sources = gitSource === null ? collected : [...collected, gitSource];
-    sources.sort((a, b) => a.id.localeCompare(b.id));
     let diff = diffSourceHashes(sources, previousRecords, nativeCoreVersion, {
         fragments: previousCache?.fragments,
         knownSourceIds: cacheResult.knownSourceIds,

package/dist/engine/project-graph/cache.js

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines -- cache validation, collection, and freshness share one artifact contract. */
 // @crash-shield-ignore-file - graph artifacts are Planu-owned JSON written by this subsystem.
 import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
 import { open, readdir, readFile, stat } from 'node:fs/promises';
 import { dirname, extname, join, relative, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -422,6 +423,36 @@ export async function hydrateProjectGraphSource(source, maxFileBytes) {
         maxFileBytes,
     });
 }
+async function collectGitSource(projectPath) {
+    try {
+        const stdout = await new Promise((resolveOutput, reject) => {
+            execFile('git', ['rev-parse', 'HEAD'], { cwd: projectPath }, (error, output) => {
+                if (error) {
+                    reject(new Error('git rev-parse failed', { cause: error }));
+                    return;
+                }
+                resolveOutput(output);
+            });
+        });
+        const head = stdout.trim();
+        if (head.length === 0) {
+            return null;
+        }
+        return {
+            id: 'project-git',
+            kind: 'project-git',
+            path: '.git/log',
+            content: head,
+            hash: hashText(head),
+            size: Buffer.byteLength(head),
+            mtimeMs: 0,
+            contentLoaded: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 // eslint-disable-next-line max-lines-per-function -- source inventory is normalized in one deterministic pass.
 export async function collectProjectGraphSources(args) {
     const projectRoot = resolve(args.projectPath);
@@ -482,7 +513,12 @@ export async function collectProjectGraphSources(args) {
         nativeCoreVersion: args.nativeCoreVersion,
         maxFileBytes,
     })));
-    return sources.filter((source) => source !== null);
+    const available = sources.filter((source) => source !== null);
+    const gitSource = await collectGitSource(projectRoot);
+    if (gitSource !== null) {
+        available.push(gitSource);
+    }
+    return available.sort((left, right) => left.id.localeCompare(right.id));
 }
 export async function getProjectGraphFreshness(args) {
     const policy = args.policy ?? (await loadProjectGraphPolicy());

package/dist/engine/qa-gate.d.ts

@@ -2,5 +2,8 @@ import type { QaGateResult } from '../types/qa-gate.js';
 import type { Spec } from '../types/spec/core.js';
 export declare function extractCoverageThreshold(spec: Spec): number | null;
 export declare function computeQaGateFingerprint(spec: Spec, projectPath: string): string;
-export declare function runQaGate(spec: Spec, projectPath: string): Promise<QaGateResult>;
+export declare function runQaGate(spec: Spec, projectPath: string, options?: {
+    projectId?: string;
+    signal?: AbortSignal;
+}): Promise<QaGateResult>;
 //# sourceMappingURL=qa-gate.d.ts.map

package/dist/engine/qa-gate.js

@@ -1,22 +1,12 @@
 // engine/qa-gate.ts — SPEC-642
-import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { resolveProjectCommandPlan } from '../tools/validate-runtime.js';
+import { resolveProjectCommandPlan } from './project-command-runtime.js';
+import { computeValidationEvidenceIdentity, computeValidationEvidenceKey, readMatchingValidationEvidence, recordSuccessfulValidationEvidence, recordValidationOutcome, } from './validation-evidence-ledger.js';
+import { runAbortableProcess } from './abortable-process-runner.js';
+import { VALIDATION_COMMANDS } from './validation-impact-planner.js';
 const TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_BUFFER_BYTES = 64 * 1024 * 1024;
-const QA_FINGERPRINT_FILES = [
-    'package.json',
-    'pnpm-lock.yaml',
-    'package-lock.json',
-    'yarn.lock',
-    'bun.lockb',
-    'tsconfig.json',
-    'vitest.config.ts',
-    'vitest.config.mts',
-    'vitest.config.js',
-];
 export function extractCoverageThreshold(spec) {
     const text = [spec.title, ...spec.tags].join(' ');
     const match = /coverage\s*[>=]+\s*(\d+)%/i.exec(text);
@@ -25,34 +15,75 @@ export function extractCoverageThreshold(spec) {
     }
     return parseInt(match[1], 10);
 }
-function runCheck(name, command, args, cwd) {
+async function runCheck(name, command, args, cwd, signal) {
     const start = Date.now();
-    const result = spawnSync(command, args, {
+    const result = await runAbortableProcess(command, args, {
         cwd,
-        timeout: TIMEOUT_MS,
-        encoding: 'utf-8',
-        maxBuffer: MAX_OUTPUT_BUFFER_BYTES,
+        timeoutMs: TIMEOUT_MS,
+        maxBufferBytes: MAX_OUTPUT_BUFFER_BYTES,
+        signal,
     });
     const durationMs = Date.now() - start;
     const passed = result.status === 0 && !result.error;
     const output = [result.stdout, result.stderr].join('\n').trim().slice(0, 2000);
-    const errorCode = result.error && 'code' in result.error
-        ? String(result.error.code)
-        : undefined;
-    const timedOut = errorCode === 'ETIMEDOUT' || result.signal === 'SIGTERM';
     return {
         name,
         passed,
         output,
         durationMs,
         command: [command, ...args].join(' '),
-        timedOut,
+        timedOut: result.timedOut,
         errorMessage: result.error?.message,
     };
 }
-function runRequestedCheck(name, requestedCommand, cwd) {
+async function runRequestedCheck(name, requestedCommand, cwd, projectId, signal) {
     const plan = resolveProjectCommandPlan(cwd, requestedCommand);
-    return runCheck(name, plan.executable, plan.args, cwd);
+    const input = {
+        projectPath: cwd,
+        capability: name === 'typecheck' ? 'typecheck' : 'test-full',
+        command: requestedCommand,
+        scope: ['src', 'tests'],
+    };
+    const expectedKey = computeValidationEvidenceKey(computeValidationEvidenceIdentity(input));
+    if (projectId) {
+        const receipt = readMatchingValidationEvidence(projectId, input);
+        if (receipt) {
+            return {
+                name,
+                passed: true,
+                output: `reused canonical validation receipt ${receipt.key}`,
+                durationMs: 0,
+                command: plan.executedCommand,
+            };
+        }
+    }
+    const result = await runCheck(name, plan.executable, plan.args, cwd, signal);
+    if (projectId && result.passed) {
+        recordSuccessfulValidationEvidence({
+            projectId,
+            input,
+            expectedKey,
+            producer: 'planu-qa-gate',
+            durationMs: result.durationMs,
+            output: result.output,
+            reason: `${name} passed during the canonical QA gate.`,
+        });
+    }
+    else if (projectId) {
+        recordValidationOutcome({
+            projectId,
+            input,
+            action: result.timedOut || signal?.aborted === true ? 'aborted' : 'executed',
+            producer: 'planu-qa-gate',
+            status: result.timedOut || signal?.aborted === true ? 'cancelled' : 'failed',
+            durationMs: result.durationMs,
+            output: result.output,
+            reason: result.timedOut || signal?.aborted === true
+                ? `${name} was cancelled before evidence persistence.`
+                : `${name} failed during the canonical QA gate.`,
+        });
+    }
+    return result;
 }
 function readProjectPackageManager(projectPath) {
     try {
@@ -67,57 +98,39 @@ function readProjectPackageManager(projectPath) {
 function resolveRequestedQaCommand(projectPath, check) {
     const manager = readProjectPackageManager(projectPath)?.split('@')[0] ?? 'pnpm';
     if (check === 'typecheck') {
-        return `${manager} typecheck`;
+        return manager === 'pnpm' ? VALIDATION_COMMANDS.typecheck : `${manager} typecheck`;
     }
     if (check === 'test-coverage') {
         return `${manager} test:coverage`;
     }
-    return `${manager} test`;
-}
-function asStableString(value) {
-    return typeof value === 'string' ? value : '';
-}
-function asStableStringArray(value) {
-    return Array.isArray(value)
-        ? value.filter((item) => typeof item === 'string')
-        : [];
+    return manager === 'pnpm' ? VALIDATION_COMMANDS['test-full'] : `${manager} test`;
 }
 export function computeQaGateFingerprint(spec, projectPath) {
-    const hash = createHash('sha256');
-    hash.update(spec.id);
-    hash.update(asStableString(spec.updatedAt));
-    hash.update(asStableString(spec.title));
-    hash.update(asStableStringArray(spec.tags).join('|'));
-    for (const file of QA_FINGERPRINT_FILES) {
-        const fullPath = join(projectPath, file);
-        try {
-            const stats = statSync(fullPath);
-            hash.update(`${file}:${String(stats.mtimeMs)}:${String(stats.size)}`);
-        }
-        catch {
-            hash.update(`${file}:missing`);
-        }
-    }
-    return hash.digest('hex');
+    return computeValidationEvidenceKey(computeValidationEvidenceIdentity({
+        projectPath,
+        capability: extractCoverageThreshold(spec) === null ? 'test-full' : 'test-full',
+        command: resolveRequestedQaCommand(projectPath, extractCoverageThreshold(spec) === null ? 'test' : 'test-coverage'),
+        scope: ['src', 'tests'],
+    }));
 }
-export function runQaGate(spec, projectPath) {
+export async function runQaGate(spec, projectPath, options = {}) {
     const coverageThreshold = extractCoverageThreshold(spec);
     const checks = [];
-    checks.push(runRequestedCheck('typecheck', resolveRequestedQaCommand(projectPath, 'typecheck'), projectPath));
+    checks.push(await runRequestedCheck('typecheck', resolveRequestedQaCommand(projectPath, 'typecheck'), projectPath, options.projectId, options.signal));
     if (coverageThreshold === null) {
-        checks.push(runRequestedCheck('test', resolveRequestedQaCommand(projectPath, 'test'), projectPath));
+        checks.push(await runRequestedCheck('test', resolveRequestedQaCommand(projectPath, 'test'), projectPath, options.projectId, options.signal));
     }
     else {
-        checks.push(runRequestedCheck('test-coverage', resolveRequestedQaCommand(projectPath, 'test-coverage'), projectPath));
+        checks.push(await runRequestedCheck('test-coverage', resolveRequestedQaCommand(projectPath, 'test-coverage'), projectPath, options.projectId, options.signal));
     }
     const passed = checks.every((c) => c.passed);
-    return Promise.resolve({
+    return {
         specId: spec.id,
         passed,
         checks,
         ranAt: new Date().toISOString(),
         coverageThreshold,
         fingerprint: computeQaGateFingerprint(spec, projectPath),
-    });
+    };
 }
 //# sourceMappingURL=qa-gate.js.map

package/dist/engine/safety/cross-process-lock.d.ts

@@ -1,4 +1,5 @@
 import type { CrossProcessLockMetadata, AcquireLockOptions, LockHandle, LockInfo } from '../../types/spec-lock-v2.js';
+export { getLockScavengeMetrics, resetLockScavengeMetricsForTests, scavengeStaleLockArtifacts, } from './lock-scavenger.js';
 declare const HEARTBEAT_INTERVAL_MS = 30000;
 export { HEARTBEAT_INTERVAL_MS };
 /** Thrown by withSpecLock when the lock is held by another live session. */
@@ -13,12 +14,6 @@ export declare class LockBusyError extends Error {
  * Returns a LockHandle on success, or null if the lock is held by another live session.
  * Stale locks (PID dead, heartbeat expired, or TTL expired) are reclaimed automatically.
  *
- * Implementation:
- * - Attempt `fs.open(lockPath, 'wx')` (O_EXCL) — succeeds only when no lockfile exists.
- * - On EEXIST, read the existing lockfile and check staleness.
- * - If stale: overwrite atomically via SPEC-718 writeJsonSafe and return a new handle.
- * - If live: log a structured warning and return null.
- *
  * @remarks
  * NFS / SMB caveat: O_EXCL is not guaranteed atomic on network filesystems.
  * This implementation is reliable on local POSIX filesystems (APFS, HFS+, ext4, tmpfs).

package/dist/engine/safety/cross-process-lock.js

@@ -1,21 +1,16 @@
 // src/engine/safety/cross-process-lock.ts — Cross-process spec lockfile (SPEC-719)
 //
-// Provides disk-backed mutual exclusion across Node.js processes for spec.md mutations.
-// Stale lock detection uses three signals: PID death, heartbeat expiry, TTL expiry.
-//
-// NFS / Network FS caveat: lockfile correctness assumes local POSIX filesystem semantics.
-// SMB / NFSv3 may produce false acquires because O_EXCL is not guaranteed atomic on
-// network filesystems. For local-disk POSIX (HFS+, APFS, ext4, tmpfs) this is reliable.
-//
 // Lockfiles live at: <projectPath>/data/.locks/planu/<specId>.lock
 // File mode: 0o600 (owner read/write only)
-import { open, unlink, readFile, mkdir, chmod } from 'node:fs/promises';
+import { open, unlink, readFile, mkdir, chmod, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { hostname as osHostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { writeJsonSafe } from './atomic-writer.js';
 import { enrichWithStaleness } from './lock-staleness.js';
+import { readValidatedLockFile, scavengeStaleLockArtifacts } from './lock-scavenger.js';
+export { getLockScavengeMetrics, resetLockScavengeMetricsForTests, scavengeStaleLockArtifacts, } from './lock-scavenger.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -139,17 +134,12 @@ function buildHandle(metadata, path) {
  * Returns a LockHandle on success, or null if the lock is held by another live session.
  * Stale locks (PID dead, heartbeat expired, or TTL expired) are reclaimed automatically.
  *
- * Implementation:
- * - Attempt `fs.open(lockPath, 'wx')` (O_EXCL) — succeeds only when no lockfile exists.
- * - On EEXIST, read the existing lockfile and check staleness.
- * - If stale: overwrite atomically via SPEC-718 writeJsonSafe and return a new handle.
- * - If live: log a structured warning and return null.
- *
  * @remarks
  * NFS / SMB caveat: O_EXCL is not guaranteed atomic on network filesystems.
  * This implementation is reliable on local POSIX filesystems (APFS, HFS+, ext4, tmpfs).
  */
 export async function acquireLock(projectPath, specId, opts) {
+    await scavengeStaleLockArtifacts(projectPath, specId);
     const path = lockPath(projectPath, specId);
     const now = Date.now();
     const sessionId = resolveSessionId(opts);
@@ -236,6 +226,18 @@ export async function releaseLock(handle) {
         }
         throw err;
     }
+    const dir = dirname(path);
+    const base = basename(path);
+    const backups = await readdir(dir).catch(() => []);
+    await Promise.all(backups
+        .filter((entry) => entry.startsWith(`${base}.bak.`))
+        .map(async (entry) => {
+        const backupPath = join(dir, entry);
+        const backup = await readValidatedLockFile(backupPath);
+        if (backup?.metadata.sessionId === handle.metadata.sessionId) {
+            await unlink(backupPath).catch(() => undefined);
+        }
+    }));
 }
 /**
  * Read the current lockfile state for a spec.
@@ -259,7 +261,7 @@ export async function listActiveCrossProcessLocks(projectPath) {
     if (!existsSync(dir)) {
         return [];
     }
-    const { readdir } = await import('node:fs/promises');
+    await scavengeStaleLockArtifacts(projectPath);
     let entries;
     try {
         entries = await readdir(dir);