@planu/cli 5.7.5 → 5.7.6

package/dist/engine/spec-format/unified-spec-builder.js

@@ -3,6 +3,7 @@
 // two-file spec.md + technical.md pair only to be merged on the next list_specs run.
 import { stripFrontmatter } from '../frontmatter-parser.js';
 import { extractAcceptanceCriteriaTexts } from './acceptance-criteria.js';
+import { isRetiredScaffoldText } from './retired-scaffold.js';
 import { escapeRegex } from '../../core/shared/strings.js';
 const REQUIRED_SECTIONS = [
     'Problem',
@@ -24,7 +25,7 @@ export function buildCanonicalUnifiedSpecContent(input) {
     const goal = firstNonEmpty(explicitGoal, input.criteria[0]?.text, 'Needs decision: define the goal this spec must achieve.');
     const explicitTechnical = extractTopLevelSectionBody(source, 'Technical');
     const generatedNotes = extractTopLevelSectionBody(input.technicalBody, 'Implementation Notes');
-    const technical = firstNonEmpty(explicitTechnical, generatedNotes, 'Implement only the grounded ownership and observable behavior declared by this contract.');
+    const technical = firstNonEmpty(explicitTechnical, generatedNotes, groundedTechnicalFallback(input.files, input.criteria));
     const acceptance = extractExecutableCriteria(source, input.criteria);
     const explicitOutOfScope = extractTopLevelSectionBody(source, 'Out of scope');
     const outOfScope = input.outOfScope.length > 0
@@ -224,8 +225,12 @@ export function validateUnifiedSpecCandidate(candidate, options = {}) {
         });
     }
     const acceptanceSection = extractTopLevelSectionBody(scannable, 'Acceptance Criteria');
-    if (acceptanceSection === null ||
-        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSection)) {
+    const acceptanceSectionForBddCheck = acceptanceSection
+        ?.split('\n')
+        .filter((line) => !isRetiredScaffoldText(line))
+        .join('\n');
+    if (!acceptanceSectionForBddCheck ||
+        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSectionForBddCheck)) {
         issues.push({
             code: 'MISSING_EXECUTABLE_CRITERIA',
             section: 'Acceptance Criteria',
@@ -248,7 +253,7 @@ export function validateUnifiedSpecCandidate(candidate, options = {}) {
     }
     return { valid: issues.length === 0, issues };
 }
-function maskFencedAndQuotedText(body) {
+export function maskFencedAndQuotedText(body) {
     const lines = body.split('\n');
     let fence = null;
     return lines
@@ -305,27 +310,18 @@ function firstNonEmpty(...values) {
     return (values.find((value) => value !== undefined && value !== null && value.length > 0) ?? '');
 }
 function fallbackCriteriaBullets(criteria) {
-    return criteria
-        .map((criterion) => `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${criterion.text}`)
-        .join('\n');
+    return criteria.map((criterion) => `- ${criterion.text}`).join('\n');
 }
-// Same BDD step vocabulary `acceptance-criteria.ts` recognizes (English + Spanish).
-// A criterion already starting with one of these is a genuine BDD fragment
-// (a full GIVEN/WHEN/THEN block, or an AND continuation of one) — leave it as-is.
-const BDD_STEP_START = /^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i;
 /**
- * Render one real criterion as an executable bullet. Criteria already
- * written in BDD form pass through untouched; plain-text criteria (e.g.
- * checkbox items) are wrapped in the same GIVEN/WHEN/THEN scaffold
- * `fallbackCriteriaBullets` uses, so every bullet stays BDD-executable
- * without ever discarding a real criterion.
+ * Render one real criterion as a bullet. Criteria already written in BDD form
+ * pass through untouched; plain-text criteria (e.g. checkbox items) render as
+ * plain bullets — SPEC-1435 retires the constant GIVEN/WHEN/THEN scaffold that
+ * used to wrap them, since it satisfied `MISSING_EXECUTABLE_CRITERIA` without
+ * adding any spec-specific content.
  */
 function toExecutableBullet(text) {
     const cleaned = text.trim().replace(/[.\s]+$/, '.');
-    if (BDD_STEP_START.test(cleaned)) {
-        return `- ${cleaned}`;
-    }
-    return `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${cleaned}`;
+    return `- ${cleaned}`;
 }
 /**
  * Criteria resolve through the canonical parser in `acceptance-criteria.ts`
@@ -339,6 +335,20 @@ function extractExecutableCriteria(source, criteria) {
     }
     return parsed.map(toExecutableBullet).join('\n');
 }
+/**
+ * SPEC-1435: replaces the constant Technical fallback sentence. When neither an
+ * author-written `## Technical` body nor generated implementation notes exist, compose
+ * the section from the spec's own grounded material instead of a fixed sentence that
+ * never varies with the spec: the grounded file records when present, otherwise the
+ * criteria texts.
+ */
+function groundedTechnicalFallback(files, criteria) {
+    const groundedFiles = [...files.create, ...files.modify, ...files.test];
+    if (groundedFiles.length > 0) {
+        return groundedFiles.map((entry) => `- \`${entry.path}\``).join('\n');
+    }
+    return criteria.map((criterion) => `- ${criterion.text}`).join('\n');
+}
 function renderOwnedFiles(files) {
     const sections = [];
     for (const [title, entries] of [

package/dist/engine/spec-grounding/contract.js

@@ -1,4 +1,17 @@
+import YAML from 'yaml';
 import { createCriterionIdentity, normalizeCriterionText } from '../criterion-identity.js';
+const GROUNDING_SOURCES = [
+    'user_input',
+    'project_evidence',
+    'documented_assumption',
+    'ungrounded_advisory',
+];
+const GROUNDING_CONFIDENCES = ['low', 'medium', 'high'];
+const TECHNICAL_REFERENCE_SECTIONS = [
+    'create',
+    'modify',
+    'test',
+];
 export { normalizeCriterionText } from '../criterion-identity.js';
 const GENERIC_CRITERION_PATTERNS = [
     /\bimplementation complete\b/i,
@@ -135,6 +148,107 @@ export function checkGroundedSpecContract(spec, content) {
     };
 }
 export function parseCriterionGroundingRecords(frontmatter) {
+    const outcome = parseFrontmatterYaml(frontmatter);
+    if (!outcome.parsed) {
+        return parseCriterionGroundingRecordsLegacy(frontmatter);
+    }
+    const grounding = readGroundingSection(outcome.document);
+    const entries = Array.isArray(grounding?.criteria) ? grounding.criteria : [];
+    const records = [];
+    for (const entry of entries) {
+        const record = toCriterionGroundingRecord(entry);
+        if (record) {
+            records.push(record);
+        }
+    }
+    return records;
+}
+export function parseTechnicalReferenceGroundingRecords(frontmatter) {
+    const outcome = parseFrontmatterYaml(frontmatter);
+    if (!outcome.parsed) {
+        return parseTechnicalReferenceGroundingRecordsLegacy(frontmatter);
+    }
+    const grounding = readGroundingSection(outcome.document);
+    const entries = grounding
+        ? Array.isArray(grounding.technicalReferences)
+            ? grounding.technicalReferences
+            : []
+        : Array.isArray(outcome.document?.technicalReferences)
+            ? outcome.document.technicalReferences
+            : [];
+    const records = [];
+    for (const entry of entries) {
+        const record = toTechnicalReferenceGroundingRecord(entry);
+        if (record) {
+            records.push(record);
+        }
+    }
+    return records;
+}
+function parseFrontmatterYaml(frontmatter) {
+    let value;
+    try {
+        value = YAML.parse(frontmatter);
+    }
+    catch {
+        return { parsed: false };
+    }
+    return { parsed: true, document: isRecord(value) ? value : undefined };
+}
+function readGroundingSection(document) {
+    const grounding = document?.grounding;
+    return isRecord(grounding) ? grounding : undefined;
+}
+function toCriterionGroundingRecord(entry) {
+    if (!isRecord(entry)) {
+        return null;
+    }
+    const text = typeof entry.text === 'string' && entry.text.length > 0 ? entry.text : null;
+    const source = toGroundingSource(entry.source);
+    const confidence = toGroundingConfidence(entry.confidence);
+    if (!text || !source || !confidence) {
+        return null;
+    }
+    return { text, source, evidence: toStringArray(entry.evidence), confidence };
+}
+function toTechnicalReferenceGroundingRecord(entry) {
+    if (!isRecord(entry)) {
+        return null;
+    }
+    const path = typeof entry.path === 'string' && entry.path.length > 0 ? entry.path : null;
+    const section = toTechnicalReferenceSection(entry.section);
+    const source = toGroundingSource(entry.source);
+    const confidence = toGroundingConfidence(entry.confidence);
+    if (!path || !section || !source || !confidence) {
+        return null;
+    }
+    return { path, section, source, evidence: toStringArray(entry.evidence), confidence };
+}
+function toGroundingSource(value) {
+    return typeof value === 'string' && GROUNDING_SOURCES.includes(value)
+        ? value
+        : null;
+}
+function toGroundingConfidence(value) {
+    return typeof value === 'string' && GROUNDING_CONFIDENCES.includes(value)
+        ? value
+        : null;
+}
+function toTechnicalReferenceSection(value) {
+    return typeof value === 'string' &&
+        TECHNICAL_REFERENCE_SECTIONS.includes(value)
+        ? value
+        : null;
+}
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseCriterionGroundingRecordsLegacy(frontmatter) {
     const records = [];
     const chunks = frontmatter.split(/\n\s{4}- text:\s*/).slice(1);
     for (const chunk of chunks) {
@@ -154,7 +268,7 @@ export function parseCriterionGroundingRecords(frontmatter) {
     }
     return records;
 }
-export function parseTechnicalReferenceGroundingRecords(frontmatter) {
+function parseTechnicalReferenceGroundingRecordsLegacy(frontmatter) {
     const records = [];
     const chunks = frontmatter.split(/\n\s{4}- path:\s*/).slice(1);
     for (const chunk of chunks) {

package/dist/engine/spec-quality/generic-output-gate.js

@@ -1,3 +1,5 @@
+import { maskFencedAndQuotedText } from '../spec-format/unified-spec-builder.js';
+import { RETIRED_SCAFFOLD_PREFIX } from '../spec-format/retired-scaffold.js';
 /** Bounds the search for criteria to the frontmatter block only (between the two `---`
  * delimiters), so criterion-shaped lines never leak in from the rendered body below it. */
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
@@ -21,7 +23,8 @@ const CRITERION_TEXT_RE = /^\s+- text:\s*"?(.+?)"?\s*$/gm;
  * the criterion-equivalent for `scenarios:`-format specs, which have no `- text:` entries. */
 const SCENARIO_TITLE_RE = /^\s+- title:\s*"?(.+?)"?\s*$/gm;
 const FILE_LINE_RE = /^-\s+(.+?)\s+\((pending|done)\)\s*$/gm;
-const H3_HEADING_RE = /^###[ \t]+(.+?)[ \t]*$/gm;
+const SECTION_HEADING_RE = /^#{1,3}[ \t]+(.+?)[ \t]*$/gm;
+const H3_HEADING_PREFIX_RE = /^###[ \t]/;
 const BULLET_LINE_RE = /^[-*][ \t]+(.+)$/;
 /** A bullet that, once a leading `Label:`, wrapping backticks, and a trailing `(status)`
  * marker are stripped, is just a file path: contains a `/` and ends in a short extension.
@@ -98,9 +101,40 @@ export function checkGenericSpecOutput(content) {
         ...checkCriteria(criteria),
         ...checkTechnicalReferences(content),
         ...checkInterpolatedSections(content, criteria),
+        ...checkRetiredFillerVocabulary(content),
     ];
     return { passed: issues.length === 0, issues };
 }
+/**
+ * SPEC-1435: dedicated scan for the constant filler sentences the renderer and the
+ * unified spec builder used to emit whenever nothing was grounded. Those sentences
+ * satisfied structural checks (a non-empty subsection, an executable-criteria match)
+ * without carrying any spec-specific content, and no existing rule matched their exact
+ * wording. Scans the whole body — prose and bullets, any heading level — with fenced
+ * code blocks and quoted text masked the same way `unified-spec-builder.ts` masks them,
+ * so a legitimate example inside a fence or blockquote is never flagged.
+ */
+const RETIRED_FILLER_SENTENCES = [
+    'Implement only the grounded ownership and observable behavior declared by this contract.',
+    'No repository-supported verification command was grounded for this candidate.',
+    'No file ownership was grounded for this behavior.',
+    'No repository-supported verification evidence was grounded for these criteria.',
+    RETIRED_SCAFFOLD_PREFIX,
+];
+function checkRetiredFillerVocabulary(content) {
+    const scannable = maskFencedAndQuotedText(content);
+    const issues = [];
+    for (const sentence of RETIRED_FILLER_SENTENCES) {
+        if (scannable.includes(sentence)) {
+            issues.push({
+                kind: 'generic-technical-reference',
+                phrase: sentence,
+                reason: `retired filler text must not appear in a persisted spec: "${sentence}"`,
+            });
+        }
+    }
+    return issues;
+}
 /**
  * SPEC-1406 (DEFECT 2, round 2 — detector rebuilt around CRITERION RESTATEMENT): the
  * previous prefix/suffix-length rule flagged `### File-Level Work Plan` (whose bullets
@@ -115,10 +149,10 @@ export function checkGenericSpecOutput(content) {
  */
 function checkInterpolatedSections(content, criteria) {
     const issues = [];
-    const headingMatches = [...content.matchAll(H3_HEADING_RE)];
+    const headingMatches = [...content.matchAll(SECTION_HEADING_RE)];
     for (let i = 0; i < headingMatches.length; i += 1) {
         const heading = headingMatches[i];
-        if (!heading?.[1]) {
+        if (!heading?.[1] || !H3_HEADING_PREFIX_RE.test(heading[0])) {
             continue;
         }
         const start = heading.index + heading[0].length;

package/dist/engine/technical-enricher/index.js

@@ -65,7 +65,10 @@ async function runEnricherFromSpecSection(opts) {
     if (result.enriched && result.enrichedContent) {
         const updated = `${specRaw.slice(0, section.contentStart)}${result.enrichedContent}${specRaw.slice(section.end)}`;
         assertEnrichmentPreservesContract(specRaw, updated, 'review-enricher');
-        await atomicWriteFile(physicalSpecPath, updated);
+        const relativeProposalPath = join('planu', '.runtime', 'enrichment-proposals', `${opts.specId}.md`);
+        const proposalPath = join(opts.projectPath, relativeProposalPath);
+        await atomicWriteFile(proposalPath, updated);
+        console.error(`Review enrichment proposal written to ${relativeProposalPath}`);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/engine/type-safety-gate.js

@@ -1,7 +1,7 @@
 // engine/type-safety-gate.ts — SPEC-968: Deterministic TypeScript anti-pattern scanner
-import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { execGitCapture } from './git/exec-git.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -9,11 +9,7 @@ function getChangedTsFiles(projectPath) {
     let names;
     // Try origin/main...HEAD (typical feature branch)
     try {
-        names = execSync('git diff --name-only --diff-filter=ACM origin/main...HEAD', {
-            cwd: projectPath,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        })
+        names = execGitCapture('git diff --name-only --diff-filter=ACM origin/main...HEAD', projectPath)
             .trim()
             .split('\n')
             .filter(Boolean);
@@ -21,11 +17,7 @@ function getChangedTsFiles(projectPath) {
     catch {
         // Fallback: last commit
         try {
-            names = execSync('git diff --name-only --diff-filter=ACM HEAD~1..HEAD', {
-                cwd: projectPath,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            })
+            names = execGitCapture('git diff --name-only --diff-filter=ACM HEAD~1..HEAD', projectPath)
                 .trim()
                 .split('\n')
                 .filter(Boolean);

package/dist/engine/universal-rules/catalog.js

@@ -3,7 +3,6 @@
 import { planuDogfoodBugsRule } from './rules/planu-dogfood-bugs.js';
 import { planuWorkflowRule } from './rules/planu-workflow.js';
 import { planuModesRule } from './rules/planu-modes.js';
-import { agentTeamsRule } from './rules/agent-teams.js';
 import { planuEnglishSpecsRule } from './rules/planu-english-specs.js';
 import { planuBddCriteriaRule } from './rules/planu-bdd-criteria.js';
 import { planuApprovalGatesRule } from './rules/planu-approval-gates.js';
@@ -26,7 +25,6 @@ export const UNIVERSAL_RULES = [
     planuMinimalChangeRule,
     planuReleasePolicyRule,
     planuModesRule,
-    agentTeamsRule,
     planuDogfoodBugsRule,
     planuDebateReviewRule,
     planuRevertProofTestsRule,

package/dist/engine/universal-rules/rules/planu-workflow.js

@@ -48,7 +48,7 @@ Any new feature, bug fix, refactor, integration, or task > 5 min.
 |------|------|
 | New feature | \`facilitate("what to build")\` |
 | Project status | \`planu_status\` |
-| Find related specs | \`semantic_search("keywords")\` |
+| Find related specs | \`list_specs\` and scan titles |
 | List approved work | \`list_specs\` with \`status: approved\` |
 | Mark done | \`update_status\` → \`done\` |
 | Verify | \`validate\` |

package/dist/engine/validation/durable-validation.d.ts

@@ -1,8 +1,9 @@
-import type { ValidationArtifactDigests, ValidationReceiptBindings } from '../../types/validation-receipt.js';
+import type { ValidationArtifactDigests, ValidationArtifactProvenanceWriteResult, ValidationReceiptBindings } from '../../types/validation-receipt.js';
 import type { DurableValidationBindings, ValidationPhase, ValidationPhaseGraphResult, ValidationPhaseProgress } from '../../types/durable-validation.js';
 export type { DurableValidationBindings } from '../../types/durable-validation.js';
 export { gitSourceTreeDigest } from './validation-source-digest.js';
 export { createPendingValidationSubmission, createValidationSubmission, validationOperationId, validationSubmissionOperationId, } from './validation-submission.js';
+export declare function absentArtifactDigest(kind: string): string;
 export declare function toValidationReceiptBindings(bindings: DurableValidationBindings, artifactDigests: ValidationArtifactDigests): ValidationReceiptBindings;
 /**
  * Evidence artifacts (discovery/task-plan/traceability/contract-validation) may legitimately
@@ -28,7 +29,7 @@ export declare function writeValidationArtifactProvenance(input: {
     readonly receiptId: string;
     readonly issuerId: string;
     readonly artifactDigests: ValidationArtifactDigests;
-}): Promise<readonly string[]>;
+}): Promise<ValidationArtifactProvenanceWriteResult>;
 /** Redact progress before it crosses the durable checkpoint boundary. */
 export declare function redactValidationProgress(progress: ValidationPhaseProgress): ValidationPhaseProgress;
 /** Execute independent validation gates with one shared deadline and cancellation tree. */

package/dist/engine/validation/durable-validation.js

@@ -1,6 +1,6 @@
 import { technologyValue } from '../technology-registry.js';
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { runAbortableProcess } from '../abortable-process-runner.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
@@ -15,6 +15,13 @@ const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 const DEFAULT_MAX_CONCURRENCY = 2;
 const MAX_CONCURRENCY = 8;
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+const APPROVED_SPEC_MISSING_LABEL = 'approved-spec';
+export function absentArtifactDigest(kind) {
+    return evidenceArtifactDigest({ missing: kind });
+}
+function missingFileDigest(label) {
+    return digest(`missing:${label}`);
+}
 function assertBindings(bindings) {
     if (!CANONICAL_PROJECT_ID.test(bindings.projectId)) {
         throw new Error('[Planu] Durable validation requires a canonical projectId');
@@ -47,6 +54,18 @@ export function toValidationReceiptBindings(bindings, artifactDigests) {
         artifactDigests,
     };
 }
+function codeBindingsMatch(observed, stored) {
+    return (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);
+}
+function digestRebindsToSentinel(observedDigest, storedDigest, kind) {
+    return observedDigest !== storedDigest && observedDigest === absentArtifactDigest(kind);
+}
 /**
  * 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
@@ -57,20 +76,22 @@ 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) {
+    if (!codeBindingsMatch(observed, stored)) {
         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);
+    const observedArtifacts = observed.artifactDigests;
+    const storedArtifacts = stored.artifactDigests;
+    const evidenceDiffers = observedArtifacts.discovery !== storedArtifacts.discovery ||
+        observedArtifacts.taskPlan !== storedArtifacts.taskPlan ||
+        observedArtifacts.traceability !== storedArtifacts.traceability ||
+        observedArtifacts.contractValidation !== storedArtifacts.contractValidation;
+    if (!evidenceDiffers) {
+        return false;
+    }
+    const rebindsToAbsentEvidence = digestRebindsToSentinel(observedArtifacts.discovery, storedArtifacts.discovery, 'discovery') ||
+        digestRebindsToSentinel(observedArtifacts.taskPlan, storedArtifacts.taskPlan, 'task-plan') ||
+        digestRebindsToSentinel(observedArtifacts.traceability, storedArtifacts.traceability, 'traceability');
+    return !rebindsToAbsentEvidence;
 }
 async function digestFile(path, missingLabel) {
     try {
@@ -78,7 +99,7 @@ async function digestFile(path, missingLabel) {
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            return digest(`missing:${missingLabel}`);
+            return missingFileDigest(missingLabel);
         }
         throw error;
     }
@@ -101,7 +122,7 @@ async function readEvidenceFile(path) {
 /** Compute immutable validation and lifecycle-artifact bindings without trusting spec metadata. */
 export async function computeDurableValidationBindings(input) {
     const handoff = join(projectDataDir(input.canonicalProjectId), 'handoffs', input.specId);
-    const specHash = await digestFile(input.specPath, 'approved-spec');
+    const specHash = await digestFile(input.specPath, APPROVED_SPEC_MISSING_LABEL);
     const [discovery, taskPlan, traceability, ...contracts] = await Promise.all([
         readEvidenceFile(join(handoff, 'discovery.json')),
         readEvidenceFile(join(handoff, 'task-plan.json')),
@@ -136,19 +157,76 @@ export async function computeDurableValidationBindings(input) {
         },
         artifactDigests: {
             approvedSpec: specHash,
-            discovery: discovery
-                ? evidenceArtifactDigest(discovery)
-                : evidenceArtifactDigest({ missing: 'discovery' }),
-            taskPlan: taskPlan
-                ? evidenceArtifactDigest(taskPlan)
-                : evidenceArtifactDigest({ missing: 'task-plan' }),
+            discovery: discovery ? evidenceArtifactDigest(discovery) : absentArtifactDigest('discovery'),
+            taskPlan: taskPlan ? evidenceArtifactDigest(taskPlan) : absentArtifactDigest('task-plan'),
             traceability: traceability
                 ? evidenceArtifactDigest(traceability)
-                : evidenceArtifactDigest({ missing: 'traceability' }),
+                : absentArtifactDigest('traceability'),
             contractValidation: evidenceArtifactCollectionDigest(contractArtifacts),
         },
     };
 }
+async function payloadFileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+function perFileArtifacts(artifactDigests) {
+    return [
+        {
+            name: 'approved-spec',
+            digestValue: artifactDigests.approvedSpec,
+            sentinel: missingFileDigest(APPROVED_SPEC_MISSING_LABEL),
+        },
+        {
+            name: 'discovery',
+            digestValue: artifactDigests.discovery,
+            sentinel: absentArtifactDigest('discovery'),
+            payloadFile: 'discovery.json',
+        },
+        {
+            name: 'task-plan',
+            digestValue: artifactDigests.taskPlan,
+            sentinel: absentArtifactDigest('task-plan'),
+            payloadFile: 'task-plan.json',
+        },
+        {
+            name: 'traceability-matrix',
+            digestValue: artifactDigests.traceability,
+            sentinel: absentArtifactDigest('traceability'),
+            payloadFile: 'traceability-matrix.json',
+        },
+    ];
+}
+async function writeProvenanceSidecars(directory, entries, identity) {
+    const absentArtifacts = [];
+    const entriesToWrite = [];
+    for (const entry of entries) {
+        if (entry.digestValue === entry.sentinel) {
+            absentArtifacts.push(entry.name);
+            continue;
+        }
+        if (entry.payloadFile !== undefined &&
+            !(await payloadFileExists(join(directory, entry.payloadFile)))) {
+            throw new Error(`[Planu] Validation artifact provenance digest for ${entry.name} references a payload that does not exist`);
+        }
+        entriesToWrite.push(entry);
+    }
+    const writtenPaths = [];
+    for (const entry of entriesToWrite) {
+        const path = join(directory, `${entry.name}.provenance.json`);
+        await atomicWriteFile(path, `${JSON.stringify({ ...identity, artifactDigest: entry.digestValue }, null, 2)}\n`);
+        writtenPaths.push(path);
+    }
+    return { writtenPaths, absentArtifacts };
+}
 /** Persist content-addressed receipt links beside machine-local lifecycle artifacts. */
 export async function writeValidationArtifactProvenance(input) {
     assertBindings({
@@ -163,24 +241,12 @@ export async function writeValidationArtifactProvenance(input) {
         throw new Error('[Planu] Invalid validation artifact provenance identity');
     }
     const directory = join(projectDataDir(input.canonicalProjectId), 'handoffs', input.specId);
-    const entries = [
-        ['approved-spec', input.artifactDigests.approvedSpec],
-        ['discovery', input.artifactDigests.discovery],
-        ['task-plan', input.artifactDigests.taskPlan],
-        ['traceability-matrix', input.artifactDigests.traceability],
-        ['contract-validation', input.artifactDigests.contractValidation],
-    ];
-    const sidecars = await Promise.all(entries.map(async ([name, artifactDigest]) => {
-        const path = join(directory, `${name}.provenance.json`);
-        await atomicWriteFile(path, `${JSON.stringify({
-            receiptId: input.receiptId,
-            artifactDigest,
-            specId: input.specId,
-            issuerId: input.issuerId,
-        }, null, 2)}\n`);
-        return path;
-    }));
-    return sidecars;
+    const identity = { receiptId: input.receiptId, specId: input.specId, issuerId: input.issuerId };
+    const { writtenPaths, absentArtifacts } = await writeProvenanceSidecars(directory, perFileArtifacts(input.artifactDigests), identity);
+    const contractSidecarPath = join(directory, 'contract-validation.provenance.json');
+    await atomicWriteFile(contractSidecarPath, `${JSON.stringify({ ...identity, artifactDigest: input.artifactDigests.contractValidation }, null, 2)}\n`);
+    writtenPaths.push(contractSidecarPath);
+    return { writtenPaths, absentArtifacts };
 }
 /** Redact progress before it crosses the durable checkpoint boundary. */
 export function redactValidationProgress(progress) {

package/dist/engine/validation/validation-freshness.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationFreshnessLease, ValidationReceiptBindings, ValidationWatchEventClassification } from '../../types/validation-receipt.js';
+import type { ValidationFreshnessBarrierResult, ValidationFreshnessLease, ValidationFreshnessRebaselineResult, ValidationReceiptBindings, ValidationWatchEventClassification } from '../../types/validation-receipt.js';
 export type { ValidationFreshnessLease } from '../../types/validation-receipt.js';
 /**
  * Invalidate the active validation lease for a spec.
@@ -49,6 +49,7 @@ export declare function closeValidationFreshnessLease(lease: Pick<ValidationFres
 /** Bind the post-watch snapshot; an event before this call makes the lease unusable. */
 export declare function bindValidationFreshnessLease(lease: ValidationFreshnessLease, bindings: ValidationReceiptBindings): Promise<boolean>;
 /** Drain invalidation work and verify epoch, generation, health, expiry and bound inputs. */
+export declare function evaluateValidationFreshnessBarrier(lease: ValidationFreshnessLease, bindings?: ValidationReceiptBindings): Promise<ValidationFreshnessBarrierResult>;
 export declare function assertValidationFreshnessBarrier(lease: ValidationFreshnessLease, bindings?: ValidationReceiptBindings): Promise<boolean>;
 export declare function captureValidationFreshnessLease(identity: {
     projectId: string;
@@ -59,7 +60,7 @@ export declare function rebaselineValidationFreshnessLeaseAfterRecompute(input:
     lease: ValidationFreshnessLease;
     expectedBindings: ValidationReceiptBindings;
     recompute: () => Promise<ValidationReceiptBindings>;
-}): Promise<ValidationFreshnessLease | undefined>;
+}): Promise<ValidationFreshnessRebaselineResult>;
 export declare function resetValidationFreshnessForTests(): Promise<void>;
 /** Count-only process diagnostic; intentionally absent from the package entrypoint. */
 export declare function getValidationFreshnessDiagnosticsForTests(): {