@planu/cli 5.7.5 → 5.7.7

package/dist/engine/evidence-gates/evidence-autofill.js

@@ -1,22 +1,4 @@
 // engine/evidence-gates/evidence-autofill.ts — SPEC-1356: automated lifecycle evidence pipeline
-//
-// Generates traceability-matrix.json in the handoff evidence store when it is
-// missing, so a `done` transition never fails purely because nobody hand-wrote
-// the traceability artifact.
-//
-// ORDERING CAVEAT (documented per SPEC-1356 T-A3): writing traceability-matrix.json
-// *after* `validate` has already computed and bound durable validation receipts
-// would make those bindings stale relative to the newly-written evidence — the
-// receipt would be certifying a repository state that does not include this file.
-// This module does NOT attempt to re-run or re-bind validation. Instead, callers
-// (see `src/tools/update-status/index.ts`) MUST treat a write from this module as
-// "evidence created, not yet bound": when autofill actually writes the file, the
-// caller must block the `done` transition with a message telling the operator to
-// re-run `validate` once so the freshly-created evidence gets bound, then retry
-// `done`. This is the simpler, safe choice given SPEC-1356 could not fully verify
-// that skipping straight through to the done gates after autofill would keep
-// receipt bindings correct in every code path (reconciliation, forced bypass,
-// legacy harnesses, etc.).
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
@@ -113,6 +95,18 @@ function filterExistingRepoFiles(projectPath, paths) {
         }
     });
 }
+/** Prose template + matching regex for the generator's validation evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export function buildValidationEvidenceText(specId, score) {
+    return `Validated by handoffs/${specId}/validation-report.json (score=${score ?? 'n/a'}).`;
+}
+export const VALIDATION_EVIDENCE_PATTERN = /^Validated by handoffs\/.+\/validation-report\.json \(score=.+\)\.$/;
+/** Prose template + matching regex for the generator's reviewer evidence, shared by the
+ * generator (renders it) and the staleness classifier (recognizes it). */
+export function buildReviewerEvidenceText(agent, kind, verdict) {
+    return `Reviewed by ${agent} (${kind}), verdict=${verdict}.`;
+}
+export const REVIEWER_EVIDENCE_PATTERN = /^Reviewed by .+ \(.+\), verdict=.+\.$/;
 /** Best-effort read + sha256 summary of the persisted validation report, for prose evidence. */
 async function readValidationReportSummary(projectId, specId) {
     const reportPath = join(projectDataDir(projectId), 'handoffs', specId, 'validation-report.json');
@@ -124,47 +118,103 @@ async function readValidationReportSummary(projectId, specId) {
         }
         const { score, reviewer } = parsed.data;
         return {
-            validationEvidence: `Validated by handoffs/${specId}/validation-report.json (score=${score ?? 'n/a'}).`,
-            reviewerEvidence: `Reviewed by ${reviewer.agent} (${reviewer.kind}), verdict=${reviewer.verdict}.`,
+            validationEvidence: buildValidationEvidenceText(specId, score),
+            reviewerEvidence: buildReviewerEvidenceText(reviewer.agent, reviewer.kind, reviewer.verdict),
         };
     }
     catch {
         return {};
     }
 }
+function isAutofillShapedMatrix(candidate) {
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        !Array.isArray(candidate.rows)) {
+        return false;
+    }
+    const rows = candidate.rows;
+    if (rows.length === 0) {
+        return false;
+    }
+    return rows.every((row) => row.validationEvidence !== undefined &&
+        row.reviewerEvidence !== undefined &&
+        VALIDATION_EVIDENCE_PATTERN.test(row.validationEvidence) &&
+        REVIEWER_EVIDENCE_PATTERN.test(row.reviewerEvidence));
+}
+const LEGACY_ROW_ALLOWED_KEYS = new Set(['acceptanceCriterion', 'testEvidence', 'changedFiles']);
+/** A pre-evidence-schema matrix: every row uses only the generator's original
+ * keys, with neither validationEvidence nor reviewerEvidence present. Safe to
+ * regenerate the same way a stale autofill-shaped matrix is. */
+function isLegacyGeneratorShapedMatrix(candidate) {
+    if (typeof candidate !== 'object' ||
+        candidate === null ||
+        !Array.isArray(candidate.rows)) {
+        return false;
+    }
+    const rows = candidate.rows;
+    if (rows.length === 0) {
+        return false;
+    }
+    return rows.every((row) => Object.keys(row).every((key) => LEGACY_ROW_ALLOWED_KEYS.has(key)));
+}
+/** Reads the on-disk matrix, if any, and classifies whether it is safe to
+ * regenerate. A hand-written, mixed, or unparseable matrix is never touched. */
+async function readRegeneratableMatrix(targetPath) {
+    if (!existsSync(targetPath)) {
+        return { kind: 'absent' };
+    }
+    const raw = await readFile(targetPath, 'utf-8');
+    try {
+        const parsed = JSON.parse(raw);
+        return isAutofillShapedMatrix(parsed) || isLegacyGeneratorShapedMatrix(parsed)
+            ? { kind: 'autofill-shaped', raw }
+            : { kind: 'manual' };
+    }
+    catch {
+        return { kind: 'manual' };
+    }
+}
+async function resolveChangedFiles(args) {
+    const exec = args.exec ?? defaultExec;
+    const baseBranch = args.baseBranch ?? 'main';
+    const gitEntries = args.projectPath
+        ? await computeChangedFilesFromGit(args.projectPath, exec, baseBranch)
+        : [];
+    const gitChangedFiles = excludeBookkeepingChanges(gitEntries, args.ownSpecMdPath);
+    const ownership = extractCanonicalFileOwnership(args.specBody);
+    const ownershipFiles = [...ownership.toCreate, ...ownership.toModify, ...ownership.toTest];
+    const rawChangedFiles = gitChangedFiles.length > 0 ? gitChangedFiles : ownershipFiles;
+    return [
+        ...new Set(args.projectPath
+            ? filterExistingRepoFiles(args.projectPath, rawChangedFiles)
+            : rawChangedFiles),
+    ];
+}
 /**
- * Generate `traceability-matrix.json` in the handoff evidence store when it does
- * not already exist. Never overwrites an existing file — if one is present this
- * is a no-op that reports `already-exists`. Tolerates every failure by returning
- * a typed non-throwing result; callers must never let this crash a lifecycle
- * transition.
+ * Generate `traceability-matrix.json` in the handoff evidence store, or regenerate
+ * it in place when it is autofill-shaped but stale relative to the current
+ * validation report. Never touches a hand-written or mixed matrix — those are a
+ * permanent no-op. Tolerates every failure by returning a typed non-throwing
+ * result; callers must never let this crash a lifecycle transition.
  */
 export async function autofillTraceabilityMatrix(args) {
     const targetPath = handoffEvidencePath(args.projectId, args.specId, 'traceability-matrix.json');
     try {
-        if (existsSync(targetPath)) {
-            return { written: false, reason: 'already-exists' };
-        }
         const criteria = extractAcceptanceCriteriaTexts(args.specBody);
         if (criteria.length === 0) {
             return { written: false, reason: 'no-criteria' };
         }
+        const existingLookup = await readRegeneratableMatrix(targetPath);
+        if (existingLookup.kind === 'manual') {
+            return { written: false, reason: 'already-exists-manual' };
+        }
+        const existingRaw = existingLookup.kind === 'autofill-shaped' ? existingLookup.raw : undefined;
         const scenarios = parseFrontmatterScenarios(args.specBody);
-        const exec = args.exec ?? defaultExec;
-        const baseBranch = args.baseBranch ?? 'main';
-        const gitEntries = args.projectPath
-            ? await computeChangedFilesFromGit(args.projectPath, exec, baseBranch)
-            : [];
-        const gitChangedFiles = excludeBookkeepingChanges(gitEntries, args.ownSpecMdPath);
-        const ownership = extractCanonicalFileOwnership(args.specBody);
-        const ownershipFiles = [...ownership.toCreate, ...ownership.toModify, ...ownership.toTest];
-        const rawChangedFiles = gitChangedFiles.length > 0 ? gitChangedFiles : ownershipFiles;
-        const changedFiles = [
-            ...new Set(args.projectPath
-                ? filterExistingRepoFiles(args.projectPath, rawChangedFiles)
-                : rawChangedFiles),
-        ];
+        const changedFiles = await resolveChangedFiles(args);
         const { validationEvidence, reviewerEvidence } = await readValidationReportSummary(args.projectId, args.specId);
+        if (existingRaw !== undefined && validationEvidence === undefined) {
+            return { written: false, reason: 'already-exists-current' };
+        }
         const rows = criteria.map((acceptanceCriterion, index) => {
             const testPaths = scenarios[index]?.tests?.map((test) => test.path) ?? [];
             return {
@@ -176,7 +226,20 @@ export async function autofillTraceabilityMatrix(args) {
             };
         });
         const payload = { version: 1, rows };
-        await atomicWriteFile(targetPath, JSON.stringify(payload, null, 2));
+        const payloadJson = JSON.stringify(payload, null, 2);
+        if (existingRaw !== undefined) {
+            if (existingRaw === payloadJson) {
+                return { written: false, reason: 'already-exists-current' };
+            }
+            await atomicWriteFile(targetPath, payloadJson);
+            return {
+                written: true,
+                path: targetPath,
+                rowCount: rows.length,
+                reason: 'regenerated-stale',
+            };
+        }
+        await atomicWriteFile(targetPath, payloadJson);
         return { written: true, path: targetPath, rowCount: rows.length };
     }
     catch (error) {

package/dist/engine/evidence-gates/evidence-skeletons.js

@@ -32,7 +32,9 @@ function outOfScopeFromBody(specBody) {
 }
 /** Build a strict-schema discovery.json skeleton grounded in the spec's own grounding metadata. */
 export function generateDiscoverySkeleton(args) {
-    const records = args.body ? parseCriterionGroundingRecords(specFrontmatter(args.body)) : [];
+    const records = args.body
+        ? parseCriterionGroundingRecords(specFrontmatter(args.body)).records
+        : [];
     const rules = records.length > 0 ? [...new Set(records.map((record) => record.text))] : [DEFAULT_RULE];
     const examples = records.length > 0
         ? records.map((record) => ({

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

@@ -1,5 +1,5 @@
 import { isAbsolute, join } from 'node:path';
-import { DISCOVERY_TEMPLATE_OVERRIDES, DiscoverySchema, evidenceArtifactCollectionDigest, evidenceArtifactDigest, } from './artifact-reader.js';
+import { DISCOVERY_TEMPLATE_OVERRIDES, DiscoverySchema, artifactHint, evidenceArtifactCollectionDigest, evidenceArtifactDigest, } from './artifact-reader.js';
 import { renderSchemaSkeleton } from '../handoff-artifacts/schema-skeleton.js';
 import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../text-signal-boundaries.js';
 import { createCriterionIdentity } from '../criterion-identity.js';
@@ -218,7 +218,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
     if (!matrix) {
         issues.push({
             code: 'traceability_missing',
-            message: 'Traceability matrix evidence is required before done. Add traceability-matrix.json covering each acceptance criterion.',
+            message: `Traceability matrix evidence is required before done. Add traceability-matrix.json covering each acceptance criterion. ${artifactHint('Traceability matrix evidence')}`,
         });
     }
     else {
@@ -238,7 +238,7 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
             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('; ')}`,
+                message: `Traceability rows must include evidence, changed files, validation evidence, and reviewer evidence. Incomplete rows: ${rowDetails.join('; ')}. Check traceability-matrix.json in this spec's handoff evidence store: a generator-shaped matrix regenerates automatically the next time validate runs and the done transition is retried, but a hand-written matrix must be edited in place.`,
             });
         }
     }
@@ -251,9 +251,12 @@ export function checkDoneEvidenceGate(spec, criteria, artifacts) {
         .map((artifact) => artifact.kind);
     const missingKinds = requiredKinds.filter((kind) => !passedKinds.has(kind));
     if (missingKinds.length > 0) {
+        const hints = missingKinds
+            .map((kind) => artifactHint(`contract-validation-${kind}.json`))
+            .join(' ');
         issues.push({
             code: 'contract_validation_missing',
-            message: `Contract validation evidence is required for: ${missingKinds.join(', ')}`,
+            message: `Contract validation evidence is required for: ${missingKinds.join(', ')}. ${hints}`,
         });
     }
     if (failedKinds.length > 0) {

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

@@ -1,5 +1,5 @@
-import { stat } from 'node:fs/promises';
 import { isAbsolute, join, normalize } from 'node:path';
+import { pathExistsByStat as pathExists } from '../../core/shared/fs.js';
 import { createCriterionIdentity, criterionIdentitiesMatch } from '../criterion-identity.js';
 export function criterionKey(criterion) {
     return createCriterionIdentity(criterion).stableKey;
@@ -9,6 +9,10 @@ function truncateAtEvidenceMarker(value) {
     const markerIndex = value.search(EVIDENCE_MARKER);
     return markerIndex === -1 ? value : value.slice(0, markerIndex);
 }
+const LINE_CITATION_SUFFIX = /:\d+(?:-\d+)?$/;
+function pathForExistenceCheck(value) {
+    return value.replace(LINE_CITATION_SUFFIX, '');
+}
 export async function buildSpecEvidenceIndex(args) {
     const diagnostics = [...args.artifacts.invalidArtifacts];
     const matrixRows = args.artifacts.traceabilityMatrix?.rows ?? [];
@@ -129,12 +133,25 @@ async function pathRecord(kind, value, source, args, fieldName) {
     if (!args.projectPath) {
         return record(kind, value, 'missing', source, evidencePathReason(fieldName, 'projectPath unavailable'));
     }
-    const exists = await stat(safe.path)
-        .then(() => true)
-        .catch(() => false);
+    const literalExists = await pathExists(safe.path);
+    const exists = literalExists || (await fallbackExists(value, fieldName, args.projectPath));
     const missingReason = evidencePathReason(fieldName, `Missing path: ${value}`);
     return record(kind, value, exists ? 'valid' : missingPathStatus(fieldName), source, exists ? undefined : missingReason);
 }
+async function fallbackExists(value, fieldName, projectPath) {
+    if (fieldName === 'changedFiles') {
+        return false;
+    }
+    const strippedValue = pathForExistenceCheck(value);
+    if (strippedValue === value || strippedValue.length === 0) {
+        return false;
+    }
+    const strippedSafe = resolveSafeProjectPath(strippedValue, projectPath, fieldName);
+    if (!strippedSafe.ok) {
+        return false;
+    }
+    return pathExists(strippedSafe.path);
+}
 function missingPathStatus(fieldName) {
     return fieldName === 'changedFiles' ? 'missing' : 'stale';
 }

package/dist/engine/execution/job-runtime.js

@@ -249,7 +249,7 @@ function isQueueRelevant(job) {
         return true;
     }
     const kind = job.payload.kind;
-    return kind === undefined || kind === 'validate';
+    return kind === undefined || kind === 'validate' || kind === 'package-handoff';
 }
 function remainingBudgetMs(job, now = Date.now()) {
     const payload = job.payload && typeof job.payload === 'object'

package/dist/engine/execution/package-handoff-job-executor.d.ts

@@ -0,0 +1,22 @@
+import { DurableJobRuntime } from './job-runtime.js';
+import type { DurableJobRecord, PackageHandoffDurableJobPayload, PackageHandoffStageResult } from '../../types/durable-job.js';
+export declare function isPackageHandoffJob(value: unknown): boolean;
+export declare function parsePackageHandoffPayload(value: unknown): PackageHandoffDurableJobPayload | undefined;
+/** Bounds one stage with AbortSignal.timeout + Promise.race; the stage's own promise is orphaned on timeout. */
+export declare function runStageWithDeadline<T>(stage: string, budgetMs: number, fn: (signal: AbortSignal) => Promise<T>): Promise<PackageHandoffStageResult<T>>;
+/** Executes accepted package-handoff jobs directly against the packaging engine, never through MCP. */
+export declare class PackageHandoffJobExecutor {
+    private readonly runtime;
+    private readonly workerId;
+    constructor(runtime: DurableJobRuntime, workerId?: string);
+    runOnce(projectId: string, workspaceId?: string): Promise<readonly DurableJobRecord[]>;
+    runUntilIdle(projectId: string, workspaceId?: string): Promise<void>;
+    private candidates;
+    private execute;
+    private runJob;
+}
+/** Schedules background execution after the submit response can be flushed. */
+export declare function schedulePackageHandoffJobExecution(projectId: string, workspaceId?: string): void;
+/** Re-enqueues accepted/checkpointed package-handoff work discovered after a process restart. */
+export declare function recoverPackageHandoffJobsAtStartup(): void;
+//# sourceMappingURL=package-handoff-job-executor.d.ts.map