@planu/cli 4.14.1 → 5.1.1

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

@@ -0,0 +1,69 @@
+// evidence-skeletons.ts — SPEC-1356: auto-generate schema-valid discovery/task-plan skeletons
+// when the underlying handoff evidence file is missing, so lifecycle gates self-heal instead
+// of blocking on a manual authoring step. Skeletons still require review; they only unblock
+// the transition, they do not fabricate confidence.
+import { join } from 'node:path';
+import { extractListItems, extractSection } from '../spec-format/markdown-sections.js';
+import { parseCriterionGroundingRecords } from '../spec-grounding/contract.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
+const DEFAULT_OUT_OF_SCOPE = 'None declared beyond the spec scope.';
+const DEFAULT_RULE = 'Behavior must follow the approved spec Problem and Technical sections.';
+function specFrontmatter(specBody) {
+    return FRONTMATTER_RE.exec(specBody)?.[1] ?? '';
+}
+function outOfScopeFromBody(specBody) {
+    if (!specBody) {
+        return [DEFAULT_OUT_OF_SCOPE];
+    }
+    const section = extractSection(specBody, 'out of scope');
+    if (!section) {
+        return [DEFAULT_OUT_OF_SCOPE];
+    }
+    const items = extractListItems(section);
+    return items.length > 0 ? items : [DEFAULT_OUT_OF_SCOPE];
+}
+/** 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 rules = records.length > 0 ? [...new Set(records.map((record) => record.text))] : [DEFAULT_RULE];
+    const examples = records.length > 0
+        ? records.map((record) => ({
+            rule: record.text,
+            example: record.evidence[0] ??
+                `Derived from ${args.spec.id} (${args.spec.title}) grounding evidence.`,
+        }))
+        : [{ rule: DEFAULT_RULE, example: `Derived from spec ${args.spec.id}: ${args.spec.title}.` }];
+    return {
+        version: 1,
+        rules,
+        examples,
+        openQuestions: [],
+        outOfScope: outOfScopeFromBody(args.body),
+        glossary: [{ term: args.spec.title, meaning: args.spec.feature ?? args.spec.title }],
+    };
+}
+/** Build a strict-schema task-plan.json skeleton with one pending task per canonical criterion. */
+export function generateTaskPlanSkeleton(args) {
+    const criteria = args.criteria.length > 0 ? args.criteria : ['Implementation satisfies the approved spec.'];
+    return {
+        version: 1,
+        tasks: criteria.map((criterion, index) => ({
+            id: `AC-${String(index + 1)}`,
+            title: criterion.length > 500 ? `${criterion.slice(0, 497)}...` : criterion,
+            acceptanceCriteria: [`AC${String(index + 1)}`],
+            status: 'pending',
+        })),
+    };
+}
+function handoffPath(projectId, specId, filename) {
+    return join(projectDataDir(projectId), 'handoffs', specId, filename);
+}
+/** Persist an auto-generated evidence skeleton to the external handoff store. */
+export async function writeEvidenceSkeleton(args) {
+    const path = handoffPath(args.projectId, args.specId, args.filename);
+    await atomicWriteFile(path, `${JSON.stringify(args.artifact, null, 2)}\n`);
+    return path;
+}
+//# sourceMappingURL=evidence-skeletons.js.map

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

@@ -1,5 +1,5 @@
 import { evidenceArtifactCollectionDigest, evidenceArtifactDigest } from './artifact-reader.js';
-import { hasAnyAffirmedMatch } from '../text-signal-boundaries.js';
+import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../text-signal-boundaries.js';
 import { createCriterionIdentity } from '../criterion-identity.js';
 const CONTRACT_HINTS = {
     api: [
@@ -10,7 +10,8 @@ const CONTRACT_HINTS = {
     ],
     graphql: [/\b(?:graphql|gql)\s+(?:api|schema|resolver|contract)\b/i, /\bschema\.graphql\b/i],
     event: [
-        /\b(?:event|message)\s+(?:contract|schema|producer|consumer|handler|queue|topic)\b/i,
+        /\bevent\s+(?:contract|schema|producer|consumer|handler|queue|topic)\b/i,
+        /\bmessage\s+(?:schema|producer|consumer|handler|queue|topic)\b/i,
         /\b(?:message\s+broker|kafka|rabbitmq|pubsub|webhook\s+(?:delivery|contract|payload))\b/i,
     ],
     ui: [/\b(?:ui|component|screen|design)\s+contract\b/i],
@@ -76,7 +77,7 @@ function provenanceIssues(artifacts, context) {
     });
 }
 export function inferRequiredContractEvidence(spec, criteria) {
-    const text = `${spec.title} ${spec.tags.join(' ')} ${criteria.join(' ')}`;
+    const text = stripMetaAnalysisText(stripNonContractText([spec.title, ...spec.tags, ...criteria].join('\n')));
     const required = [];
     for (const [kind, patterns] of Object.entries(CONTRACT_HINTS)) {
         if (hasAnyAffirmedMatch(text, [...patterns])) {

package/dist/engine/evidence-gates/reconciliation-freshness.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns only project-relative IDs. Old evidence is rejected cumulatively: a
+ * later receipt cannot revive a digest superseded by an earlier receipt.
+ */
+export declare function checkReconciliationFreshness(args: {
+    projectId: string;
+    specId: string;
+}): Promise<{
+    artifactId: string;
+}[]>;
+//# sourceMappingURL=reconciliation-freshness.d.ts.map

package/dist/engine/evidence-gates/reconciliation-freshness.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { projectDataDir } from '../../storage/base-store.js';
+import { readCommittedReconciliations } from '../lifecycle-reconciliation.js';
+const BASE_ARTIFACTS = [
+    'spec.lock.json',
+    'review_feedback.md',
+    'task-plan.json',
+    'implementation-report.json',
+    'validation-report.json',
+    'traceability-matrix.json',
+    'context-package.json',
+];
+function sha256(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+/**
+ * Returns only project-relative IDs. Old evidence is rejected cumulatively: a
+ * later receipt cannot revive a digest superseded by an earlier receipt.
+ */
+export async function checkReconciliationFreshness(args) {
+    const receipts = await readCommittedReconciliations(args.projectId, args.specId);
+    const tombstones = new Set(receipts.flatMap((receipt) => receipt.supersededArtifacts.flatMap((artifact) => artifact.sha256 ? [`${artifact.artifactId}\0${artifact.sha256}`] : [])));
+    if (tombstones.size === 0) {
+        return [];
+    }
+    const root = projectDataDir(args.projectId);
+    const handoff = join(root, 'handoffs', args.specId);
+    const candidates = [
+        ...BASE_ARTIFACTS.map((name) => ({
+            artifactId: `handoffs/${args.specId}/${name}`,
+            path: join(handoff, name),
+        })),
+        { artifactId: `handoffs/${args.specId}.md`, path: join(root, 'handoffs', `${args.specId}.md`) },
+    ];
+    try {
+        const names = await readdir(handoff);
+        for (const artifactName of names) {
+            if (/^contract-validation-[A-Za-z0-9_-]+\.json$/u.test(artifactName)) {
+                candidates.push({
+                    artifactId: `handoffs/${args.specId}/${artifactName}`,
+                    path: join(handoff, artifactName),
+                });
+            }
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    const stale = [];
+    for (const candidate of candidates) {
+        try {
+            const stat = await lstat(candidate.path);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                continue;
+            }
+            if (tombstones.has(`${candidate.artifactId}\0${sha256(await readFile(candidate.path))}`)) {
+                stale.push({ artifactId: candidate.artifactId });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+                throw error;
+            }
+        }
+    }
+    return stale;
+}
+//# sourceMappingURL=reconciliation-freshness.js.map

package/dist/engine/evidence-index/done-drift.d.ts

@@ -1,6 +1,6 @@
 import type { EvidenceGateIssue, SpecEvidenceIndex } from '../../types/index.js';
 export declare function checkDoneDriftContract(args: {
     index: SpecEvidenceIndex;
-    groundedTechnicalPaths: readonly string[];
+    approvedScopePaths: readonly string[];
 }): EvidenceGateIssue[];
 //# sourceMappingURL=done-drift.d.ts.map

package/dist/engine/evidence-index/done-drift.js

@@ -1,3 +1,8 @@
+import { normalizeChangedFilePath } from '../handoff-packager.js';
+function normalizedChangedFile(value) {
+    const normalized = normalizeChangedFilePath(value);
+    return normalized.status === 'valid' ? normalized.path : null;
+}
 export function checkDoneDriftContract(args) {
     const issues = [];
     const uncovered = args.index.criteria.filter((entry) => {
@@ -14,33 +19,50 @@ export function checkDoneDriftContract(args) {
     }
     const staleOrInvalid = args.index.criteria.flatMap((entry) => entry.evidence
         .filter((record) => record.status === 'stale' || record.status === 'invalid')
-        .map((record) => `${entry.criterion}: ${record.value} (${record.status})`));
+        .map((record) => {
+        if (record.kind !== 'changed-file') {
+            return `${entry.criterion}: ${record.value} (${record.status})`;
+        }
+        const normalized = normalizedChangedFile(record.value);
+        return normalized
+            ? `${entry.criterion}: ${normalized} (${record.status})`
+            : `${entry.criterion}: invalid changed-file (${record.status})`;
+    }));
     if (staleOrInvalid.length > 0) {
         issues.push({
             code: 'done_drift_stale_evidence',
             message: `Done drift check found stale or invalid evidence: ${staleOrInvalid.join('; ')}`,
         });
     }
-    const grounded = new Set(args.groundedTechnicalPaths);
-    if (grounded.size > 0) {
-        const unapproved = args.index.criteria.flatMap((entry) => {
-            const hasScopeAmendment = entry.evidence.some((record) => record.kind === 'reviewer' && /scope amendment|approved scope/i.test(record.value));
-            if (hasScopeAmendment) {
+    const approvedScopePaths = args.approvedScopePaths.flatMap((path) => {
+        const normalized = normalizedChangedFile(path);
+        return normalized ? [normalized] : [];
+    });
+    const approved = new Set(approvedScopePaths);
+    const unapproved = args.index.criteria.flatMap((entry) => {
+        const hasScopeAmendment = entry.evidence.some((record) => record.kind === 'reviewer' && /scope amendment|approved scope/i.test(record.value));
+        if (hasScopeAmendment) {
+            return [];
+        }
+        return entry.evidence.flatMap((record) => {
+            if (record.kind !== 'changed-file' ||
+                (record.status !== 'valid' && record.status !== 'missing')) {
                 return [];
             }
-            return entry.evidence
-                .filter((record) => record.kind === 'changed-file' && !grounded.has(record.value))
-                .map((record) => `${entry.criterion}: ${record.value}`);
+            const normalized = normalizedChangedFile(record.value);
+            return normalized && approved.has(normalized)
+                ? []
+                : [`${entry.criterion}: ${normalized ?? 'invalid changed-file path'}`];
+        });
+    });
+    if (unapproved.length > 0) {
+        const approvedHint = approvedScopePaths.length > 0
+            ? ` Approved canonical paths: ${approvedScopePaths.join(', ')}.`
+            : ' No approved canonical paths were found in the approved spec.';
+        issues.push({
+            code: 'done_drift_unapproved_scope',
+            message: `Done drift check found changed files outside approved canonical scope: ${unapproved.join('; ')}.${approvedHint} Add the file to approved canonical ownership or include reviewerEvidence with an approved scope amendment.`,
         });
-        if (unapproved.length > 0) {
-            const groundedHint = args.groundedTechnicalPaths.length > 0
-                ? ` Grounded technical paths: ${args.groundedTechnicalPaths.join(', ')}.`
-                : ' No grounded technical paths were found in the approved spec.';
-            issues.push({
-                code: 'done_drift_unapproved_scope',
-                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}.${groundedHint} Add the file to approved technical references or include reviewerEvidence with an approved scope amendment.`,
-            });
-        }
     }
     return issues;
 }

package/dist/engine/execution/context.js

@@ -102,6 +102,7 @@ export function createChildCancellationScope(requestedMs) {
     const normalizedMs = Number.isFinite(requestedMs) ? Math.max(0, requestedMs) : 0;
     const timeoutMs = Math.max(0, Math.min(normalizedMs, parentRemaining));
     const controller = new AbortController();
+    let deadlineElapsed = false;
     const abortFromParent = () => {
         controller.abort(parent?.signal.reason ?? new ExecutionCancelledError());
     };
@@ -112,12 +113,14 @@ export function createChildCancellationScope(requestedMs) {
         parent?.signal.addEventListener('abort', abortFromParent, { once: true });
     }
     const timer = setTimeout(() => {
+        deadlineElapsed = true;
         controller.abort(new ExecutionCancelledError(`Execution budget elapsed after ${String(timeoutMs)}ms`));
     }, timeoutMs);
     timer.unref();
     return {
         signal: controller.signal,
         timeoutMs,
+        didDeadlineElapse: () => deadlineElapsed,
         dispose: () => {
             clearTimeout(timer);
             parent?.signal.removeEventListener('abort', abortFromParent);

package/dist/engine/execution/durable-job-heartbeat-runtime.d.ts

@@ -0,0 +1,4 @@
+import type { DurableJobHeartbeatController, DurableJobHeartbeatRuntimeOptions, DurableJobHeartbeatStartInput } from '../../types/durable-validation.js';
+/** Start one autonomous, fenced heartbeat and wait for its typed ready acknowledgement. */
+export declare function createDurableJobHeartbeat(input: DurableJobHeartbeatStartInput, options?: DurableJobHeartbeatRuntimeOptions): Promise<DurableJobHeartbeatController>;
+//# sourceMappingURL=durable-job-heartbeat-runtime.d.ts.map