@planu/cli 4.14.1 → 5.1.1

package/dist/tools/update-status/dod-gates.js

@@ -1,3 +1,11 @@
+/* eslint-disable max-lines -- done evidence gates remain co-located for one auditable fail-closed boundary */
+// tools/update-status/dod-gates.ts — DoD gate checks and forceStatus bypass
+// SPEC-729: Validate gate wrapped with withEscalation for bounded retries.
+// SPEC-780: checkApprovedFormatGate honours forceApprove, mirroring SPEC-769 readiness gate.
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve as resolvePath, sep } from 'node:path';
 import { validateSpec } from '../../engine/validator.js';
 import { generateDoD } from '../../engine/validator/dor-dod.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
@@ -9,6 +17,8 @@ import { writeSpecReviewFeedback } from '../../engine/validator/spec-review-writ
 import { formatKeyValue } from '../output-formatter.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { verifyCurrentDoneReceipt } from './done-receipt-verifier.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { ValidationReportV1Schema } from '../../engine/handoff-artifacts/schemas.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
@@ -275,6 +285,176 @@ function validationReceiptGateError(specId, reason) {
         },
     };
 }
+function doneReviewDigestError(specId, code, message) {
+    const artifactPath = `external Planu project data: handoffs/${specId}/validation-report.json`;
+    const fixHint = 'Run validate, then recompute the sha256 digest from the exact report bytes.';
+    return {
+        content: [{ type: 'text', text: `${code}: ${message}\nFix: ${fixHint}` }],
+        isError: true,
+        structuredContent: {
+            error: code,
+            code: 422,
+            context: { specId, artifactPath },
+            fixHint,
+        },
+    };
+}
+const MAX_VALIDATION_REPORT_BYTES = 5 * 1024 * 1024;
+function isContained(root, candidate) {
+    const pathFromRoot = relative(root, candidate);
+    return (pathFromRoot === '' ||
+        (!isAbsolute(pathFromRoot) && pathFromRoot !== '..' && !pathFromRoot.startsWith(`..${sep}`)));
+}
+function sameFileMetadata(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+async function readStableDoneReviewReport(specId, projectId) {
+    const handoffsRoot = resolvePath(projectDataDir(projectId), 'handoffs');
+    const specRoot = resolvePath(handoffsRoot, specId);
+    const reportPath = resolvePath(specRoot, 'validation-report.json');
+    if (!isContained(handoffsRoot, specRoot) || !isContained(specRoot, reportPath)) {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report path escapes its contained handoff directory.');
+    }
+    let canonicalHandoffs;
+    let canonicalSpecRoot;
+    let canonicalReport;
+    let pathStats;
+    try {
+        [canonicalHandoffs, canonicalSpecRoot, canonicalReport, pathStats] = await Promise.all([
+            realpath(handoffsRoot),
+            realpath(specRoot),
+            realpath(reportPath),
+            lstat(reportPath, { bigint: true }),
+        ]);
+    }
+    catch {
+        return {
+            ...doneReviewDigestError(specId, 'DONE_REVIEW_DIGEST_MISMATCH', 'No persisted validation report was found for this spec. Run validate first, then retry done.'),
+            isError: true,
+        };
+    }
+    if (!isContained(canonicalHandoffs, canonicalSpecRoot) ||
+        !isContained(canonicalSpecRoot, canonicalReport) ||
+        pathStats.isSymbolicLink() ||
+        !pathStats.isFile() ||
+        pathStats.size > BigInt(MAX_VALIDATION_REPORT_BYTES)) {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report is not a contained bounded regular file.');
+    }
+    if (typeof constants.O_NOFOLLOW !== 'number') {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The platform cannot safely open the validation report without following links.');
+    }
+    let handle;
+    try {
+        handle = await open(reportPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return {
+            ...doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report could not be opened without following links.'),
+            isError: true,
+        };
+    }
+    try {
+        const openedStats = await handle.stat({ bigint: true });
+        if (!openedStats.isFile() || !sameFileMetadata(pathStats, openedStats)) {
+            return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_CHANGED', 'The validation report identity changed before it was opened.');
+        }
+        const reportBytes = Buffer.alloc(Number(openedStats.size));
+        let offset = 0;
+        while (offset < reportBytes.length) {
+            const { bytesRead } = await handle.read(reportBytes, offset, reportBytes.length - offset, offset);
+            if (bytesRead === 0) {
+                return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_CHANGED', 'The validation report changed while it was being read.');
+            }
+            offset += bytesRead;
+        }
+        const finalHandleStats = await handle.stat({ bigint: true });
+        if (!sameFileMetadata(openedStats, finalHandleStats)) {
+            return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_CHANGED', 'The opened validation report changed while it was being read.');
+        }
+        let finalPathStats;
+        let finalCanonicalReport;
+        try {
+            [finalPathStats, finalCanonicalReport] = await Promise.all([
+                lstat(reportPath, { bigint: true }),
+                realpath(reportPath),
+            ]);
+        }
+        catch {
+            return {
+                ...doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_CHANGED', 'The validation report path changed while it was being read.'),
+                isError: true,
+            };
+        }
+        if (!isContained(canonicalSpecRoot, finalCanonicalReport)) {
+            return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report path escaped containment while it was being read.');
+        }
+        if (finalPathStats.isSymbolicLink() ||
+            !finalPathStats.isFile() ||
+            !sameFileMetadata(openedStats, finalPathStats)) {
+            return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_CHANGED', 'The validation report path identity changed while it was being read.');
+        }
+        return reportBytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * SPEC-1356 (T-A1): auto-derive the sha256 digest of the persisted
+ * `validation-report.json` so callers no longer have to compute it by hand.
+ * Reads and hashes the exact same bytes `checkDoneReviewDigest` would validate
+ * against, using the same hardened path/identity checks. Returns the digest, or
+ * the exact blocking `ToolResult` when the report cannot be safely read (e.g.
+ * validate has not run yet). Exported for direct unit testing and for the
+ * orchestration layer (`update-status/index.ts`) that no longer requires the
+ * caller to supply `implementationReviewDigest`.
+ */
+export async function deriveDoneReviewDigest(specId, projectId) {
+    const reportResult = await readStableDoneReviewReport(specId, projectId);
+    if (!Buffer.isBuffer(reportResult)) {
+        return { error: reportResult };
+    }
+    return { digest: `sha256:${createHash('sha256').update(reportResult).digest('hex')}` };
+}
+async function checkDoneReviewDigest(specId, projectId, implementationReviewDigest) {
+    if (!/^sha256:[a-f0-9]{64}$/u.test(implementationReviewDigest)) {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_DIGEST_INVALID', 'The implementation review digest is malformed.');
+    }
+    const reportResult = await readStableDoneReviewReport(specId, projectId);
+    if (!Buffer.isBuffer(reportResult)) {
+        return reportResult;
+    }
+    const observed = `sha256:${createHash('sha256').update(reportResult).digest('hex')}`;
+    if (observed !== implementationReviewDigest) {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_DIGEST_MISMATCH', 'The implementation review digest does not match the persisted validation report.');
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(reportResult.toString('utf8'));
+    }
+    catch {
+        return {
+            ...doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report bytes are not valid JSON.'),
+            isError: true,
+        };
+    }
+    const parsed = ValidationReportV1Schema.safeParse(decoded);
+    if (!parsed.success ||
+        parsed.data.specId !== specId ||
+        !parsed.data.passed ||
+        parsed.data.gates.some((gate) => !gate.passed) ||
+        parsed.data.minimalityReport?.blocked === true ||
+        parsed.data.reviewer.kind !== 'implementation-review-agent' ||
+        parsed.data.reviewer.agent !== 'planu-implementation-reviewer' ||
+        parsed.data.reviewer.verdict !== 'approved') {
+        return doneReviewDigestError(specId, 'DONE_REVIEW_REPORT_UNSAFE', 'The validation report schema or independent reviewer evidence is invalid.');
+    }
+    return null;
+}
 /**
  * SPEC-725: Check the validation-report artifact gate before marking done.
  * SPEC-1050: Fail closed. A done transition requires a fresh validation-report
@@ -493,8 +673,18 @@ function specReviewGateError(args) {
  * When force=true, gates are not blocking but failing items are recorded in
  * the project's force-bypass-log.json for traceability (guard: done ≠ implemented).
  */
-export async function checkDoneGates(spec, specId, projectId, projectPath, _force, _forceReason = 'No force reason provided', verifyReceipt = verifyCurrentDoneReceipt) {
+export async function checkDoneGates(spec, specId, projectId, projectPath, _force, _forceReason = 'No force reason provided', verifyReceipt = verifyCurrentDoneReceipt, implementationReviewDigest) {
     try {
+        if (implementationReviewDigest !== undefined) {
+            const digestError = await checkDoneReviewDigest(specId, projectId, implementationReviewDigest);
+            if (digestError) {
+                return {
+                    blocked: digestError,
+                    forcedBypassWarning: null,
+                    freshnessLease: null,
+                };
+            }
+        }
         const result = await verifyReceipt({ projectId, specId, projectPath, specPath: spec.specPath });
         return result.valid
             ? {

package/dist/tools/update-status/done-receipt-verifier.d.ts

@@ -1,5 +1,6 @@
 import { type DurableJobRecord } from '../../storage/runtime-db.js';
 import { type ValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
+import type { ValidationReceiptBindings } from '../../types/validation-receipt.js';
 export type DoneReceiptVerifier = (identity: {
     projectId: string;
     specId: string;
@@ -11,5 +12,12 @@ export type DoneReceiptVerifier = (identity: {
     freshnessLease?: ValidationFreshnessLease;
 }>;
 export declare function completedJobPublishesReceipt(job: DurableJobRecord | undefined, receiptId: string): boolean;
+/**
+ * Evidence artifacts (discovery/task-plan/traceability/contract-validation) may legitimately
+ * be regenerated after a receipt was issued (e.g. autopilot skeleton fill). If ONLY the evidence
+ * digests changed while every code-facing binding stayed byte-identical, the receipt is rebound
+ * to the freshly observed evidence digests instead of being rejected as stale.
+ */
+export declare function doneReceiptBindingsDifferOnlyInEvidence(observed: ValidationReceiptBindings | undefined, stored: ValidationReceiptBindings | undefined): boolean;
 export declare function verifyCurrentDoneReceipt(identity: Parameters<DoneReceiptVerifier>[0]): ReturnType<DoneReceiptVerifier>;
 //# sourceMappingURL=done-receipt-verifier.d.ts.map

package/dist/tools/update-status/done-receipt-verifier.js

@@ -54,8 +54,9 @@ import { isAbsolute, join } from 'node:path';
 import { RuntimeDatabase } from '../../storage/runtime-db.js';
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
 import { projectDataDir } from '../../storage/base-store.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidationReceiptAuthority, readCurrentValidationReceipt, } from '../../engine/validation/validation-receipt.js';
-import { beginValidationFreshnessBarrier, bindValidationFreshnessLease, captureValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
+import { beginValidationFreshnessBarrier, bindValidationFreshnessLease, captureValidationFreshnessLease, closeValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
 export function completedJobPublishesReceipt(job, receiptId) {
     if (job?.state !== 'completed' || !job.result || typeof job.result !== 'object') {
@@ -69,6 +70,31 @@ export function completedJobPublishesReceipt(job, receiptId) {
     return (published.receiptId === receiptId &&
         published.receiptKey === `validation-receipt:${receiptId.slice('sha256:'.length)}`);
 }
+/**
+ * Evidence artifacts (discovery/task-plan/traceability/contract-validation) may legitimately
+ * be regenerated after a receipt was issued (e.g. autopilot skeleton fill). If ONLY the evidence
+ * digests changed while every code-facing binding stayed byte-identical, the receipt is rebound
+ * to the freshly observed evidence digests instead of being rejected as stale.
+ */
+export function doneReceiptBindingsDifferOnlyInEvidence(observed, stored) {
+    if (!observed?.artifactDigests || !stored?.artifactDigests) {
+        return false;
+    }
+    const codeBindingsMatch = observed.projectId === stored.projectId &&
+        observed.specId === stored.specId &&
+        observed.sourceDigest === stored.sourceDigest &&
+        observed.specDigest === stored.specDigest &&
+        observed.policyDigest === stored.policyDigest &&
+        observed.toolchainDigest === stored.toolchainDigest &&
+        observed.artifactDigests.approvedSpec === stored.artifactDigests.approvedSpec;
+    if (!codeBindingsMatch) {
+        return false;
+    }
+    return (observed.artifactDigests.discovery !== stored.artifactDigests.discovery ||
+        observed.artifactDigests.taskPlan !== stored.artifactDigests.taskPlan ||
+        observed.artifactDigests.traceability !== stored.artifactDigests.traceability ||
+        observed.artifactDigests.contractValidation !== stored.artifactDigests.contractValidation);
+}
 export async function verifyCurrentDoneReceipt(identity) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
@@ -105,34 +131,56 @@ export async function verifyCurrentDoneReceipt(identity) {
         if (!receiptJobExists) {
             return { valid: false, reason: 'missing-receipt' };
         }
-        let freshnessLease = await captureValidationFreshnessLease(identity, currentBindings);
-        if (!freshnessLease && identity.projectPath && identity.specPath) {
-            const projectPath = identity.projectPath;
-            const specPath = isAbsolute(identity.specPath)
-                ? identity.specPath
-                : join(projectPath, identity.specPath);
-            const lease = await beginValidationFreshnessBarrier({
-                projectId: identity.projectId,
-                specId: identity.specId,
-                projectPath,
-                handoffPath: join(projectDataDir(identity.projectId), 'handoffs', identity.specId),
-                invalidateCurrentBindings: false,
-            });
-            const observed = await computeDurableValidationBindings({
-                canonicalProjectId: identity.projectId,
-                specId: identity.specId,
-                projectPath,
-                specPath,
-            });
-            const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
-            if (JSON.stringify(observedBindings) === JSON.stringify(currentBindings) &&
-                (await bindValidationFreshnessLease(lease, observedBindings))) {
-                freshnessLease = lease;
+        let ownedLease = await captureValidationFreshnessLease(identity, currentBindings);
+        try {
+            if (!ownedLease && identity.projectPath && identity.specPath) {
+                const projectPath = identity.projectPath;
+                const specPath = isAbsolute(identity.specPath)
+                    ? identity.specPath
+                    : join(projectPath, identity.specPath);
+                ownedLease = await beginValidationFreshnessBarrier({
+                    projectId: identity.projectId,
+                    specId: identity.specId,
+                    projectPath,
+                    handoffPath: join(projectDataDir(identity.projectId), 'handoffs', identity.specId),
+                    invalidateCurrentBindings: false,
+                });
+                const observed = await computeDurableValidationBindings({
+                    canonicalProjectId: identity.projectId,
+                    specId: identity.specId,
+                    projectPath,
+                    specPath,
+                });
+                const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
+                if (JSON.stringify(observedBindings) !== JSON.stringify(currentBindings)) {
+                    if (!doneReceiptBindingsDifferOnlyInEvidence(observedBindings, currentBindings)) {
+                        return { valid: false, reason: 'stale-bindings' };
+                    }
+                    await store.projectCurrentBindings(observedBindings);
+                    console.warn('[planu:evidence-rebind]', {
+                        projectId: identity.projectId,
+                        specId: identity.specId,
+                        rebindAt: new Date().toISOString(),
+                    });
+                }
+                if (!(await bindValidationFreshnessLease(ownedLease, observedBindings))) {
+                    return { valid: false, reason: 'stale-bindings' };
+                }
+            }
+            if (!ownedLease) {
+                return { valid: false, reason: 'stale-bindings' };
+            }
+            const transferred = ownedLease;
+            ownedLease = undefined;
+            return { ...verification, freshnessLease: transferred };
+        }
+        finally {
+            if (ownedLease) {
+                await closeValidationFreshnessLease(ownedLease).catch((error) => {
+                    reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+                });
             }
         }
-        return freshnessLease
-            ? { ...verification, freshnessLease }
-            : { valid: false, reason: 'stale-bindings' };
     }
     catch (e_1) {
         env_1.error = e_1;

package/dist/tools/update-status/evidence-gate.d.ts

@@ -1,6 +1,10 @@
 import type { ToolResult } from '../../types/index.js';
 import type { Spec } from '../../types/spec/core.js';
 import type { EvidenceGateTransition } from '../../types/evidence-gates.js';
+/** SPEC-1356: repo-relative paths mentioned in the spec's Problem/Technical prose also count
+ * as approved canonical scope, even when they are not in the file-ownership checklist. Paths
+ * do not need to exist yet (a spec may name files it has not created). */
+export declare function extractCanonicalScopePathsFromSections(body: string): string[];
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export declare function checkLifecycleEvidenceTransitionGate(args: {
     spec: Spec;

package/dist/tools/update-status/evidence-gate.js

@@ -66,9 +66,38 @@ import { ValidationReceiptStore, LOCAL_VALIDATION_RECEIPT_ISSUER, createValidati
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { captureValidationFreshnessLease } from '../../engine/validation/validation-freshness.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../../engine/validation/durable-validation.js';
+import { checkReconciliationFreshness } from '../../engine/evidence-gates/reconciliation-freshness.js';
+import { extractCanonicalFileOwnership } from '../../engine/handoff-packager.js';
+import { generateDiscoverySkeleton, generateTaskPlanSkeleton, writeEvidenceSkeleton, } from '../../engine/evidence-gates/evidence-skeletons.js';
+import { extractSection } from '../../engine/spec-format/markdown-sections.js';
+const CANONICAL_SCOPE_PATH = /(?:src|tests|scripts|website)\/[\w/.@-]+\.\w+/g;
+/** SPEC-1356: repo-relative paths mentioned in the spec's Problem/Technical prose also count
+ * as approved canonical scope, even when they are not in the file-ownership checklist. Paths
+ * do not need to exist yet (a spec may name files it has not created). */
+export function extractCanonicalScopePathsFromSections(body) {
+    const problem = extractSection(body, 'problem') ?? '';
+    const technical = extractSection(body, 'technical') ?? '';
+    const matches = `${problem}\n${technical}`.match(CANONICAL_SCOPE_PATH) ?? [];
+    return [...new Set(matches)];
+}
 /** SPEC-1054: BDD/SDD lifecycle evidence gate. */
 export async function checkLifecycleEvidenceTransitionGate(args) {
-    const [criteriaResult, artifacts] = await Promise.all([
+    const staleReconciliationEvidence = await checkReconciliationFreshness({
+        projectId: args.projectId,
+        specId: args.specId,
+    });
+    if (staleReconciliationEvidence.length > 0) {
+        return evidenceGateError({
+            specId: args.specId,
+            transition: args.transition,
+            issues: staleReconciliationEvidence.map(({ artifactId }) => ({
+                code: 'SUPERSEDED_RECONCILIATION_EVIDENCE',
+                message: artifactId,
+            })),
+            requiredContractKinds: [],
+        });
+    }
+    const [criteriaResult, initialArtifacts] = await Promise.all([
         extractLifecycleGateCriteriaAndBody(args.spec, args.projectPath),
         readEvidenceArtifacts({
             spec: args.spec,
@@ -77,6 +106,16 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             projectPath: args.projectPath,
         }),
     ]);
+    const { criteria, body } = criteriaResult;
+    const artifacts = await autofillMissingEvidenceSkeletons({
+        spec: args.spec,
+        projectId: args.projectId,
+        specId: args.specId,
+        transition: args.transition,
+        criteria,
+        body,
+        artifacts: initialArtifacts,
+    });
     const receiptResult = args.transition === 'done'
         ? await readVerifiedCurrentReceipt({
             projectId: args.projectId,
@@ -93,7 +132,6 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             requiredContractKinds: [],
         });
     }
-    const { criteria, body } = criteriaResult;
     const result = checkLifecycleEvidenceGate({
         transition: args.transition,
         spec: args.spec,
@@ -108,8 +146,28 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             artifacts,
             projectPath: args.projectPath,
         });
+        const canonicalOwnership = body
+            ? extractCanonicalFileOwnership(body)
+            : { present: false, toCreate: [], toModify: [], toTest: [], blockers: [] };
         const groundedTechnicalPaths = body ? parseGroundedTechnicalPaths(body) : [];
-        result.issues.push(...checkDoneDriftContract({ index, groundedTechnicalPaths }));
+        const problemTechnicalScopePaths = body ? extractCanonicalScopePathsFromSections(body) : [];
+        const approvedScopePaths = [
+            ...new Set([
+                ...canonicalOwnership.toCreate,
+                ...canonicalOwnership.toModify,
+                ...canonicalOwnership.toTest,
+                ...groundedTechnicalPaths,
+                ...problemTechnicalScopePaths,
+            ]),
+        ];
+        if (canonicalOwnership.blockers.length > 0) {
+            const safeBlockers = canonicalOwnership.blockers.map((blocker) => blocker.startsWith('CONFLICTING_FILE_OWNERSHIP:') ? blocker : 'INVALID_FILE_OWNERSHIP');
+            result.issues.push({
+                code: 'done_drift_unapproved_scope',
+                message: `Approved canonical ownership is invalid: ${[...new Set(safeBlockers)].join(', ')}.`,
+            });
+        }
+        result.issues.push(...checkDoneDriftContract({ index, approvedScopePaths }));
     }
     if (result.issues.length === 0) {
         return null;
@@ -124,6 +182,48 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
         requiredContractKinds: result.requiredContractKinds,
     });
 }
+/** True when the artifact truly has no file yet, as opposed to failing schema validation. */
+function isArtifactAbsent(artifacts, label) {
+    return !artifacts.invalidArtifacts.some((entry) => entry.startsWith(label));
+}
+/**
+ * SPEC-1356: self-heal missing (not malformed) discovery/task-plan handoff evidence by
+ * generating a schema-valid skeleton and persisting it, instead of blocking the transition
+ * on a manual authoring step. Malformed existing artifacts still fail the gate as before.
+ */
+async function autofillMissingEvidenceSkeletons(args) {
+    if (args.spec.scope === 'trivial') {
+        return args.artifacts;
+    }
+    let artifacts = args.artifacts;
+    if (args.transition === 'approved' &&
+        !artifacts.discovery &&
+        isArtifactAbsent(artifacts, 'Discovery evidence')) {
+        const skeleton = generateDiscoverySkeleton({ spec: args.spec, body: args.body });
+        await writeEvidenceSkeleton({
+            projectId: args.projectId,
+            specId: args.specId,
+            filename: 'discovery.json',
+            artifact: skeleton,
+        });
+        console.warn('[planu:evidence-skeleton]', { specId: args.specId, filename: 'discovery.json' });
+        artifacts = { ...artifacts, discovery: skeleton };
+    }
+    if (args.transition === 'implementing' &&
+        !artifacts.taskPlan &&
+        isArtifactAbsent(artifacts, 'Task plan evidence')) {
+        const skeleton = generateTaskPlanSkeleton({ criteria: args.criteria });
+        await writeEvidenceSkeleton({
+            projectId: args.projectId,
+            specId: args.specId,
+            filename: 'task-plan.json',
+            artifact: skeleton,
+        });
+        console.warn('[planu:evidence-skeleton]', { specId: args.specId, filename: 'task-plan.json' });
+        artifacts = { ...artifacts, taskPlan: skeleton };
+    }
+    return artifacts;
+}
 async function readVerifiedCurrentReceipt(identity) {
     try {
         const env_1 = { stack: [], error: void 0, hasError: false };

package/dist/tools/update-status/file-sync.d.ts

@@ -1,6 +1,6 @@
-import type { SpecStatus, UpdateStatusInput } from '../../types/index.js';
+import type { SpecStatus, Actuals } from '../../types/index.js';
 import type { Spec } from '../../types/spec/core.js';
-export declare function recordDoneMetrics(projectId: string, specId: string, spec: Spec, actuals: NonNullable<UpdateStatusInput['actuals']>, projectPath?: string): Promise<void>;
+export declare function recordDoneMetrics(projectId: string, specId: string, spec: Spec, actuals: Actuals, projectPath?: string): Promise<void>;
 /**
  * SPEC-698: A frontmatter sync warning surfaced when `update_status` could not
  * keep the on-disk spec.md status in sync with the data store.
@@ -10,7 +10,7 @@ export interface FrontmatterSyncWarning {
     specPath: string | null;
     reason: string;
 }
-export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string): Promise<{
+export declare function syncSpecFiles(updatedSpec: Spec, _currentStatus: SpecStatus, newStatus: SpecStatus, projectPath?: string, qualityWarnings?: readonly string[]): Promise<{
     warning?: FrontmatterSyncWarning;
 }>;
 export declare function tryReconcile(newStatus: string, specId: string, projectId: string): Promise<string | null>;
@@ -32,5 +32,6 @@ export declare function recordTerminalTransitionEvent(args: {
     modelId?: string;
     gateResults?: Record<string, 'pass' | 'fail' | 'skip' | 'forced'>;
     meta?: Record<string, unknown>;
+    projectPath?: string;
 }): Promise<void>;
 //# sourceMappingURL=file-sync.d.ts.map

package/dist/tools/update-status/file-sync.js

@@ -3,11 +3,12 @@ import { metricsStore } from '../../storage/index.js';
 import { addLesson, getLessons } from '../../storage/lessons-store.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { autoReconcileOnDone } from '../update-status-reconcile.js';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile, realpath } from 'node:fs/promises';
 import { parseFrontmatter } from '../../engine/frontmatter-parser.js';
 import { computeFrontmatterSha } from '../../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 export async function recordDoneMetrics(projectId, specId, spec, actuals, projectPath) {
     if (actuals.devHours + actuals.reviewHours === 0) {
@@ -74,6 +75,46 @@ async function autoCaptureLessonEstimation(spec, actuals, accuracy, projectId, p
 }
 const SPEC_BODY_SHRINK_ABSOLUTE_THRESHOLD = 200;
 const SPEC_BODY_SHRINK_RATIO_THRESHOLD = 0.05;
+async function resolveSpecPathForTransition(spec, projectPath) {
+    if (!projectPath) {
+        return spec.specPath;
+    }
+    const normalizedPath = normalize(spec.specPath);
+    const segments = normalizedPath.split(sep).filter(Boolean);
+    const planuIndex = segments.lastIndexOf('planu');
+    const specDirectory = segments[planuIndex + 2];
+    const isPortableContract = planuIndex >= 0 &&
+        segments[planuIndex + 1] === 'specs' &&
+        segments[planuIndex + 3] === 'spec.md' &&
+        planuIndex + 4 === segments.length &&
+        specDirectory !== undefined &&
+        (specDirectory === spec.id || specDirectory.startsWith(`${spec.id}-`));
+    if (!isPortableContract) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a portable spec contract');
+    }
+    const selectedRoot = resolve(projectPath);
+    const candidate = resolve(selectedRoot, 'planu', 'specs', specDirectory, 'spec.md');
+    const relativeCandidate = relative(selectedRoot, candidate);
+    if (relativeCandidate.startsWith(`..${sep}`) ||
+        relativeCandidate === '..' ||
+        isAbsolute(relativeCandidate)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath escapes the selected root');
+    }
+    const [rootRealpath, candidateRealpath, candidateStat] = await Promise.all([
+        realpath(selectedRoot),
+        realpath(candidate),
+        lstat(candidate),
+    ]);
+    const realRelative = relative(rootRealpath, candidateRealpath);
+    if (candidateStat.isSymbolicLink() ||
+        !candidateStat.isFile() ||
+        realRelative.startsWith(`..${sep}`) ||
+        realRelative === '..' ||
+        isAbsolute(realRelative)) {
+        throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: specPath is not a contained regular file');
+    }
+    return candidateRealpath;
+}
 function bodyWithoutFrontmatter(content) {
     return parseFrontmatter(content).body;
 }
@@ -95,13 +136,23 @@ function assertSpecBodyIntegrity(args) {
         throw new Error(`SPEC_INTEGRITY_WRITE_FAILED: refusing to write ${args.specId} because update_status(${args.newStatus}) would shrink spec.md body by ${String(lost)} characters without an explicit migration marker.`);
     }
 }
-export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath) {
+export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, projectPath, qualityWarnings = []) {
     let warning;
     if (updatedSpec.specPath) {
         try {
-            const specContent = await readFile(updatedSpec.specPath, 'utf-8');
+            const transitionSpecPath = await resolveSpecPathForTransition(updatedSpec, projectPath);
+            const specContent = await readFile(transitionSpecPath, 'utf-8');
+            if (projectPath) {
+                const parsedId = parseFrontmatter(specContent).metadata.id;
+                if (parsedId !== updatedSpec.id) {
+                    throw new Error('SPEC_PATH_RELOCALIZATION_FAILED: spec frontmatter ID does not match');
+                }
+            }
             const { updateFrontmatterField } = await import('../../engine/frontmatter-parser.js');
             let updatedContent = updateFrontmatterField(specContent, 'status', newStatus);
+            if (qualityWarnings.length > 0) {
+                updatedContent = updateFrontmatterField(updatedContent, 'qualityWarnings', JSON.stringify(qualityWarnings));
+            }
             if (newStatus === 'done') {
                 updatedContent = markAllCriteriaDone(updatedContent);
                 if (isLeanSpecContent(updatedContent)) {
@@ -114,7 +165,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 newStatus,
                 specId: updatedSpec.id,
             });
-            await atomicWriteFile(updatedSpec.specPath, updatedContent);
+            await atomicWriteFile(transitionSpecPath, updatedContent);
             // SPEC-544: Auto-stage spec.md after writing so it's included in the user's next commit
             // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
             // Commit message must reflect the actual transition — 'mark-done' is only
@@ -125,7 +176,7 @@ export async function syncSpecFiles(updatedSpec, _currentStatus, newStatus, proj
                 process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
                 try {
                     const { git: gitCmd } = await import('../git/git-helpers.js');
-                    await gitCmd(projectPath, ['add', '--', updatedSpec.specPath]);
+                    await gitCmd(projectPath, ['add', '--', transitionSpecPath]);
                     const { planuAutoCommit } = await import('../../engine/git/planu-autocommit.js');
                     void planuAutoCommit({
                         projectPath,
@@ -197,7 +248,7 @@ export async function recordTerminalTransitionEvent(args) {
         let frontmatterSha;
         if (args.specPath) {
             try {
-                const content = await readFile(args.specPath, 'utf-8');
+                const content = await readFile(await resolveSpecPathForTransition({ id: args.specId, specPath: args.specPath }, args.projectPath), 'utf-8');
                 const { metadata } = parseFrontmatter(content);
                 frontmatterSha = computeFrontmatterSha(metadata);
             }