@planu/cli 5.7.5 → 5.7.7

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(): {

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

@@ -635,15 +635,15 @@ async function readStableState(lease, expectedGeneration) {
     return undefined;
 }
 /** Drain invalidation work and verify epoch, generation, health, expiry and bound inputs. */
-export async function assertValidationFreshnessBarrier(lease, bindings) {
+export async function evaluateValidationFreshnessBarrier(lease, bindings) {
     const candidate = active.get(key(lease.projectId, lease.specId));
     if (!candidate?.healthy ||
         candidate.epoch !== lease.epoch ||
         candidate.generation !== lease.generation) {
-        return false;
+        return { fresh: false, reason: 'lease-superseded' };
     }
     if (!(await drainAmbiguousEvents(lease, candidate, candidate.bindings))) {
-        return false;
+        return { fresh: false, reason: 'invalidation-drain-failed' };
     }
     let fingerprintBefore;
     try {
@@ -652,23 +652,23 @@ export async function assertValidationFreshnessBarrier(lease, bindings) {
     catch (error) {
         reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
         invalidateExactEpoch(lease, candidate);
-        return false;
+        return { fresh: false, reason: 'evidence-check-failed', changedInput: candidate.handoffPath };
     }
     if (fingerprintBefore !== candidate.evidenceFingerprint) {
         invalidateExactEpoch(lease, candidate);
-        return false;
+        return { fresh: false, reason: 'evidence-changed', changedInput: candidate.handoffPath };
     }
     try {
         if (candidate.bindings &&
             (await gitSourceTreeDigest(candidate.projectPath)) !== candidate.bindings.sourceDigest) {
             invalidateExactEpoch(lease, candidate);
-            return false;
+            return { fresh: false, reason: 'source-changed', changedInput: candidate.projectPath };
         }
     }
     catch (error) {
         reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
         invalidateExactEpoch(lease, candidate);
-        return false;
+        return { fresh: false, reason: 'source-check-failed', changedInput: candidate.projectPath };
     }
     // A generation change invalidates the lease synchronously. Do not wait for
     // the durable receipt cleanup when the in-memory barrier already fails
@@ -684,15 +684,21 @@ export async function assertValidationFreshnessBarrier(lease, bindings) {
     }
     if (!state || fingerprintAfter !== fingerprintBefore) {
         invalidateExactEpoch(lease, candidate);
-        return false;
+        return { fresh: false, reason: 'state-lost', changedInput: candidate.handoffPath };
     }
     if (state.generation !== lease.generation) {
-        return false;
+        return { fresh: false, reason: 'lease-superseded' };
     }
     if (Date.now() >= state.expiresAt) {
-        return false;
+        return { fresh: false, reason: 'lease-expired' };
+    }
+    if (bindings !== undefined && JSON.stringify(state.bindings) !== JSON.stringify(bindings)) {
+        return { fresh: false, reason: 'bindings-mismatch' };
     }
-    return bindings === undefined || JSON.stringify(state.bindings) === JSON.stringify(bindings);
+    return { fresh: true };
+}
+export async function assertValidationFreshnessBarrier(lease, bindings) {
+    return (await evaluateValidationFreshnessBarrier(lease, bindings)).fresh;
 }
 export async function captureValidationFreshnessLease(identity, bindings) {
     const state = active.get(key(identity.projectId, identity.specId));
@@ -707,7 +713,7 @@ export async function rebaselineValidationFreshnessLeaseAfterRecompute(input) {
     for (let attempt = 0; attempt < 2; attempt += 1) {
         const before = await readStableState(input.lease);
         if (!before || Date.now() >= before.expiresAt) {
-            return undefined;
+            return { rejection: { reason: 'lease-expired' } };
         }
         const generationBefore = before.generation;
         let fingerprintBefore;
@@ -721,14 +727,14 @@ export async function rebaselineValidationFreshnessLeaseAfterRecompute(input) {
         catch (error) {
             reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
             invalidateExactEpoch(input.lease, before);
-            return undefined;
+            return { rejection: { reason: 'recompute-failed', changedInput: before.handoffPath } };
         }
         const after = await readStableState(input.lease);
         if (after?.generation !== generationBefore || fingerprintBefore !== fingerprintAfter) {
             continue;
         }
         if (JSON.stringify(input.expectedBindings) !== JSON.stringify(observedBindings)) {
-            return undefined;
+            return { rejection: { reason: 'bindings-mismatch' } };
         }
         const confirmed = await readStableState(input.lease);
         if (confirmed?.generation !== after.generation) {
@@ -736,9 +742,9 @@ export async function rebaselineValidationFreshnessLeaseAfterRecompute(input) {
         }
         confirmed.bindings = structuredClone(observedBindings);
         confirmed.evidenceFingerprint = fingerprintAfter;
-        return { ...input.lease, generation: confirmed.generation };
+        return { lease: { ...input.lease, generation: confirmed.generation } };
     }
-    return undefined;
+    return { rejection: { reason: 'lease-unstable' } };
 }
 export async function resetValidationFreshnessForTests() {
     const leases = [...active.entries()].map(([identity, state]) => {

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

@@ -9,6 +9,7 @@ const runFile = promisify(execFile);
 const ROOT_ID = /^[a-f0-9]{64}$/u;
 const SAFE_SPEC_ID = /^SPEC-[1-9]\d*$/u;
 const PORTABLE_SPEC = /^planu\/specs\/(SPEC-\d{3,}(?:-[^/]+)?)\/spec\.md$/u;
+const STALE_SPEC_TAIL = /planu[/\\]specs[/\\]([^/\\]+)[/\\]spec\.md$/u;
 export class ValidationWorktreeError extends Error {
     code;
     specId;
@@ -83,6 +84,35 @@ async function resolveGitRoot(projectPath, specId) {
     }
     return membership;
 }
+function derivePortableSuffix(specPath, specId) {
+    const match = STALE_SPEC_TAIL.exec(specPath);
+    const dir = match?.[1];
+    if (!dir || (dir !== specId && !dir.startsWith(`${specId}-`))) {
+        return undefined;
+    }
+    const portableSuffix = `planu/specs/${dir}/spec.md`;
+    return PORTABLE_SPEC.test(portableSuffix) ? portableSuffix : undefined;
+}
+async function classifyStaleSpecPath(specPath, specId) {
+    if (!isAbsolute(specPath)) {
+        return undefined;
+    }
+    const portableSuffix = derivePortableSuffix(specPath, specId);
+    if (!portableSuffix) {
+        return undefined;
+    }
+    try {
+        await lstat(dirname(specPath));
+        return undefined;
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return portableSuffix;
+        }
+        reportClassifiedDegradation('VALIDATION_STALE_PREFIX_PROBE_FAILED', error);
+        return undefined;
+    }
+}
 async function resolveSpecSourceRoot(input) {
     const specPath = isAbsolute(input.canonicalSpecPath)
         ? input.canonicalSpecPath
@@ -92,6 +122,10 @@ async function resolveSpecSourceRoot(input) {
         source = await resolveGitMembership(dirname(specPath), input.specId);
     }
     catch {
+        const portableSuffix = await classifyStaleSpecPath(specPath, input.specId);
+        if (portableSuffix) {
+            throw new ValidationWorktreeError('VALIDATION_STALE_SPEC_PATH', input.specId, portableSuffix);
+        }
         throw new ValidationWorktreeError('VALIDATION_SPEC_PATH_TRAVERSAL', input.specId);
     }
     if (source.gitCommonDir !== input.canonical.gitCommonDir) {

package/dist/hosts/claude-code/ux/mcp-prompts.js

@@ -87,7 +87,7 @@ function buildExecuteSddFlowPrompt(specId, projectPath, mode) {
     const branchStep = mode !== 'implement-only'
         ? '4. Create a feature branch: `git checkout -b feat/' + specId + '-<slug>`.'
         : '4. Implement in the current branch (implement-only mode).';
-    const prStep = mode !== 'implement-only' ? '12. Open a PR with `create_pr_from_spec`.' : '';
+    const prStep = mode !== 'implement-only' ? '12. Open a PR with `gh pr create`.' : '';
     return [
         `You are implementing Planu spec \`${specId}\`${pathHint}${modeHint} using the full SDD flow.`,
         '',
@@ -104,7 +104,7 @@ function buildExecuteSddFlowPrompt(specId, projectPath, mode) {
         '8. Call `validate({ specId: "' +
             specId +
             '" })` and capture the durable acknowledgement fields: `operationId`, `projectId`, `workspaceId`, and `cursor`.',
-        '9. Call `watch_job` with those identifiers and the latest cursor. Repeat while the job is non-terminal; do not treat an accepted or running job as a validation result.',
+        '9. Poll `get_job` with those identifiers and the latest cursor. Repeat while the job is non-terminal; do not treat an accepted or running job as a validation result.',
         '10. Require terminal state `completed`, then inspect `job.result.structuredContent`. If the job is failed, dead-letter, or cancelled, stop and report it. Fix every failing criterion and submit a new validation job when needed.',
         '11. Call `update_status({ specId: "' +
             specId +
@@ -118,18 +118,18 @@ function buildExecuteSddFlowPrompt(specId, projectPath, mode) {
 }
 function buildChallengeSpecPrompt(specId, focus) {
     const focusHint = focus !== undefined && focus !== 'all' ? ` with a focus on **${focus}**` : '';
-    const securityStep = focus === 'security' || focus === 'all'
-        ? '5. Call `red_team` for adversarial security scenarios.'
+    const securityHint = focus === 'security' || focus === 'all'
+        ? ' Pay special attention to adversarial and security-relevant scenarios.'
         : '';
     return [
         `You are stress-testing Planu spec \`${specId}\`${focusHint} to find weaknesses before implementation.`,
         '',
         'Steps:',
         `1. Call \`list_specs\` and read the full spec for \`${specId}\`.`,
-        `2. Call \`challenge_spec({ specId: "${specId}" })\` and read all findings.`,
-        '3. Call `ears_lint` to check criterion format quality.',
-        '4. Call `validate_criteria_quality` for testability gaps.',
-        securityStep,
+        `2. Call \`challenge_spec({ specId: "${specId}" })\` and read all findings.${securityHint}`,
+        '3. Call `check_readiness({ specId: "' +
+            specId +
+            '" })` to verify the spec has enough detail to implement.',
         '',
         'For each finding, provide:',
         '- Severity: 🔴 blocking | 🟡 missing edge case | 🟢 ambiguity',

package/dist/index.js

@@ -83,6 +83,9 @@ function scheduleStartupStateRecovery(startupSync, recoverPendingPostCommitTasks
     void import('./engine/execution/validate-job-executor.js').then(({ recoverValidateJobsAtStartup }) => {
         recoverValidateJobsAtStartup();
     });
+    void import('./engine/execution/package-handoff-job-executor.js').then(({ recoverPackageHandoffJobsAtStartup }) => {
+        recoverPackageHandoffJobsAtStartup();
+    });
 }
 const MCP_HOST_MARKERS = [
     ['claude-code', 'claude-code'],
@@ -139,23 +142,6 @@ async function setupPostHandshake(handshakeGate, officialToolNames) {
     checkForUpdates().catch(() => {
         /* best-effort */
     });
-    // SPEC-566: Auto-configure Claude Code keybindings (global, one-time)
-    void (async () => {
-        try {
-            const { globalStore: gs } = await import('./storage/index.js');
-            const cfg = await gs.getGlobalConfig();
-            if (!cfg.keybindingsConfigured) {
-                const { configureClaudeKeybindings } = await import('./engine/claude-setup/keybindings-configurator.js');
-                const configured = await configureClaudeKeybindings();
-                if (configured) {
-                    await gs.updateGlobalConfig({ keybindingsConfigured: true });
-                }
-            }
-        }
-        catch {
-            /* best-effort */
-        }
-    })();
     // SPEC-334: Sync planu/ YAML frontmatter status → data/ store (non-blocking)
     scheduleStartupStateRecovery(startupSync, recoverPendingPostCommitTasksAtStartup);
     // SPEC-1271: bounded, fair, durable spec.created outbox recovery — fire-and-forget so a