@planu/cli 5.0.0 → 5.2.0

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

@@ -70,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 {
@@ -127,8 +152,18 @@ export async function verifyCurrentDoneReceipt(identity) {
                     specPath,
                 });
                 const observedBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
-                if (JSON.stringify(observedBindings) !== JSON.stringify(currentBindings) ||
-                    !(await bindValidationFreshnessLease(ownedLease, observedBindings))) {
+                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' };
                 }
             }

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

@@ -68,6 +68,18 @@ import { captureValidationFreshnessLease } from '../../engine/validation/validat
 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 staleReconciliationEvidence = await checkReconciliationFreshness({
@@ -85,7 +97,7 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             requiredContractKinds: [],
         });
     }
-    const [criteriaResult, artifacts] = await Promise.all([
+    const [criteriaResult, initialArtifacts] = await Promise.all([
         extractLifecycleGateCriteriaAndBody(args.spec, args.projectPath),
         readEvidenceArtifacts({
             spec: args.spec,
@@ -94,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,
@@ -110,7 +132,6 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             requiredContractKinds: [],
         });
     }
-    const { criteria, body } = criteriaResult;
     const result = checkLifecycleEvidenceGate({
         transition: args.transition,
         spec: args.spec,
@@ -129,12 +150,14 @@ export async function checkLifecycleEvidenceTransitionGate(args) {
             ? extractCanonicalFileOwnership(body)
             : { present: false, toCreate: [], toModify: [], toTest: [], blockers: [] };
         const groundedTechnicalPaths = body ? parseGroundedTechnicalPaths(body) : [];
+        const problemTechnicalScopePaths = body ? extractCanonicalScopePathsFromSections(body) : [];
         const approvedScopePaths = [
             ...new Set([
                 ...canonicalOwnership.toCreate,
                 ...canonicalOwnership.toModify,
                 ...canonicalOwnership.toTest,
                 ...groundedTechnicalPaths,
+                ...problemTechnicalScopePaths,
             ]),
         ];
         if (canonicalOwnership.blockers.length > 0) {
@@ -159,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.

package/dist/tools/update-status/index.d.ts

@@ -1,8 +1,30 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { UpdateStatusInput, ToolResult } from '../../types/index.js';
+import type { UpdateStatusInput, ToolResult, Actuals, ReconciliationInvocationContext } from '../../types/index.js';
+type LifecycleAuthorityRoute = {
+    route: 'ordinary';
+} | {
+    route: 'reconcile';
+} | {
+    route: 'error';
+    result: ToolResult;
+};
+/** Select the lifecycle path before any transition, artifact, receipt, or log mutation. */
+export declare function classifyLifecycleAuthority(input: UpdateStatusInput, context: ReconciliationInvocationContext, options?: {
+    requireDoneDigest?: boolean;
+}): LifecycleAuthorityRoute;
+/**
+ * SPEC-1356 (T-A2): a `done` transition no longer requires the caller to supply
+ * actuals. When the whole object is omitted, synthesize a minimal record instead
+ * of blocking the transition with `actuals_required`. Every caller-provided
+ * field — including a caller-provided partial object once the MCP input schema
+ * accepts one — is preserved verbatim; only genuinely unmeasured numeric fields
+ * default to 0, and `completedAt`/`notes` only default when absent.
+ */
+export declare function synthesizeActuals(actuals: Partial<Actuals> | undefined, transitionedAt: string): Actuals;
 /** Bind deferred lifecycle work to one normalized absolute root without persisting that path. */
 export declare function computeTransitionRootBinding(projectPath: string): string;
 /** Recover durable post-commit work for every registered project after server startup. */
 export declare function recoverPendingPostCommitTasksAtStartup(): Promise<void>;
 export declare function handleUpdateStatus(params: UpdateStatusInput, server?: McpServer): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=index.d.ts.map