@planu/cli 5.7.5 → 5.7.6

package/dist/engine/handoff-artifacts/implementation-review-reader.js

@@ -16,6 +16,10 @@ async function findImplementingActor(specId, projectId) {
     }
     return undefined;
 }
+const PLACEHOLDER_REVIEWER_SESSION_IDS = new Set(['system', 'planu-implementation-reviewer']);
+function isVerifiableReviewerSessionId(sessionId) {
+    return Boolean(sessionId) && !PLACEHOLDER_REVIEWER_SESSION_IDS.has(sessionId ?? '');
+}
 export async function readVerifiedImplementationReview(projectId, specId) {
     try {
         const result = await readArtifact({ projectId, specId, kind: 'implementation_review' });
@@ -55,10 +59,19 @@ export async function readVerifiedImplementationReview(projectId, specId) {
                 readError: err instanceof Error ? err.message : String(err),
             };
         }
-        if (implementerActor !== undefined && implementerActor === review.reviewer.agent) {
+        const reviewerSessionId = review.reviewer.sessionId?.trim();
+        if (!isVerifiableReviewerSessionId(reviewerSessionId) || implementerActor === undefined) {
+            return {
+                ok: false,
+                reason: 'identity_unverifiable',
+                review,
+                implementingActor: implementerActor,
+            };
+        }
+        if (reviewerSessionId === implementerActor) {
             return { ok: false, reason: 'self_review', review, implementingActor: implementerActor };
         }
-        return { ok: true, review, implementingActor: implementerActor ?? null };
+        return { ok: true, review, implementingActor: implementerActor };
     }
     catch (err) {
         /* reliability-optional: IMPLEMENTATION_REVIEW_GATE_READ — typed gate error blocks done */

package/dist/engine/handoff-artifacts/schemas.d.ts

@@ -70,6 +70,7 @@ export declare const ImplementationReviewV1Schema: z.ZodObject<{
             approved: "approved";
             "changes-requested": "changes-requested";
         }>;
+        sessionId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     blockers: z.ZodArray<z.ZodString>;
     suggestions: z.ZodArray<z.ZodString>;
@@ -356,6 +357,7 @@ export declare const ARTIFACT_SCHEMAS: {
                 approved: "approved";
                 "changes-requested": "changes-requested";
             }>;
+            sessionId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
         blockers: z.ZodArray<z.ZodString>;
         suggestions: z.ZodArray<z.ZodString>;

package/dist/engine/handoff-artifacts/schemas.js

@@ -47,6 +47,7 @@ export const ImplementationReviewV1Schema = z.object({
         kind: z.enum(['implementation-review-agent', 'human']),
         agent: z.string().min(1),
         verdict: z.enum(['approved', 'changes-requested']),
+        sessionId: z.string().optional(),
     }),
     blockers: z.array(z.string()),
     suggestions: z.array(z.string()),

package/dist/engine/handoff-format.d.ts

@@ -0,0 +1,36 @@
+import type { HandoffPackage, TokenWasteReport, MinimalImplementationReport } from '../types/index.js';
+export declare function formatHandoff(pkg: HandoffPackage): string;
+export declare function topItems<T>(items: T[], limit: number): T[];
+export declare function buildHandoffSummaryText(args: {
+    pkg: HandoffPackage;
+    topBlockers: string[];
+    topRisks: string[];
+    minimalityBlocked: boolean | null;
+    tokenWasteRiskCount: number | null;
+}): string;
+export declare function summarizeMinimality(report: MinimalImplementationReport | null): Record<string, unknown> | undefined;
+export declare function summarizeTokenWaste(report: TokenWasteReport | null): Record<string, unknown> | undefined;
+export declare function summarizeGraphContext(graphContext: unknown): Record<string, unknown>;
+export declare function buildHandoffTokenWasteReport(pkg: HandoffPackage, knowledge: {
+    projectPath?: string;
+}, spec: {
+    id?: string;
+    risk?: string;
+    scope?: string;
+    target?: string;
+}): Promise<TokenWasteReport | null>;
+export declare function buildGraphContextSection(args: {
+    projectId: string;
+    projectPath?: string;
+    specId: string;
+}): Promise<{
+    text: string;
+    structured: unknown;
+} | null>;
+export declare function buildMinimalImplementationReport(pkg: HandoffPackage, knowledge: {
+    projectPath?: string;
+}, spec: {
+    id?: string;
+    risk?: string;
+}, handoffText: string): Promise<MinimalImplementationReport | null>;
+//# sourceMappingURL=handoff-format.d.ts.map

package/dist/engine/handoff-format.js

@@ -0,0 +1,314 @@
+// engine/handoff-format.ts — Handoff package formatting and enrichment summaries (SPEC-1240)
+// Relocated from tools/package-handoff.ts so the durable executor (engine layer) can render
+// results without importing across the tools/engine boundary.
+import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from './token-optimizer/index.js';
+import { formatProjectGraphContext, queryProjectGraphSlice } from './project-graph/index.js';
+import { analyzeMinimalImplementation, loadMinimalImplementationPolicy, } from './minimality/index.js';
+export function formatHandoff(pkg) {
+    const lines = [];
+    lines.push(`# Implementation Handoff Package — ${pkg.specId}`);
+    lines.push('');
+    lines.push(`Generated: ${pkg.generatedAt}`);
+    lines.push(`Readiness Score: ${pkg.readinessScore}/100`);
+    if (pkg.handoffPath) {
+        lines.push(`Handoff Path: ${pkg.handoffPath}`);
+    }
+    if (pkg.contextHash) {
+        lines.push(`Context Hash: ${pkg.contextHash}`);
+    }
+    lines.push(`Blocked: ${pkg.blocked ? 'yes' : 'no'}`);
+    lines.push('');
+    lines.push('## Objective');
+    lines.push('');
+    lines.push(pkg.objective);
+    lines.push('');
+    lines.push('## Acceptance Criteria');
+    lines.push('');
+    if (pkg.criteria.length > 0) {
+        for (const criterion of pkg.criteria) {
+            lines.push(`- [ ] ${criterion}`);
+        }
+    }
+    else {
+        lines.push('_(No criteria found — check spec.md acceptance criteria)_');
+    }
+    lines.push('');
+    lines.push('## Files to Modify');
+    lines.push('');
+    if (pkg.filesToModify.length > 0) {
+        for (const f of pkg.filesToModify) {
+            lines.push(`- ${f}`);
+        }
+    }
+    else {
+        lines.push('_(No files identified — check spec.md ## Technical / ## Files)_');
+    }
+    lines.push('');
+    lines.push('## Files to Create');
+    lines.push('');
+    if (pkg.filesToCreate.length > 0) {
+        for (const f of pkg.filesToCreate) {
+            lines.push(`- ${f}`);
+        }
+    }
+    else {
+        lines.push('_(None identified)_');
+    }
+    lines.push('');
+    lines.push('## Test Files');
+    lines.push('');
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+    const filesToTest = pkg.filesToTest ?? [];
+    if (filesToTest.length > 0) {
+        for (const f of filesToTest) {
+            lines.push(`- ${f}`);
+        }
+    }
+    else {
+        lines.push('_(None identified)_');
+    }
+    lines.push('');
+    lines.push('## Ownership');
+    lines.push('');
+    if (pkg.ownership.length > 0) {
+        for (const item of pkg.ownership) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing ownership — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Test Plan');
+    lines.push('');
+    if (pkg.testPlan.length > 0) {
+        for (const item of pkg.testPlan) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing test plan — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## Risks');
+    lines.push('');
+    if (pkg.risks.length > 0) {
+        for (const item of pkg.risks) {
+            lines.push(`- ${item}`);
+        }
+    }
+    else {
+        lines.push('_(Missing risk analysis — handoff is blocked)_');
+    }
+    lines.push('');
+    lines.push('## OUT OF SCOPE');
+    lines.push('');
+    lines.push('**The following must NOT be implemented:**');
+    lines.push('');
+    for (const item of pkg.outOfScope) {
+        lines.push(`- ${item}`);
+    }
+    lines.push('');
+    if (pkg.constraints.length > 0) {
+        lines.push('## Hard Constraints');
+        lines.push('');
+        for (const constraint of pkg.constraints) {
+            lines.push(`- [${constraint.type.toUpperCase()}] ${constraint.description}`);
+            if (constraint.affectedItems.length > 0) {
+                lines.push(`  Affects: ${constraint.affectedItems.join(', ')}`);
+            }
+        }
+        lines.push('');
+    }
+    if (pkg.warnings.length > 0) {
+        lines.push('## Warnings');
+        lines.push('');
+        for (const warning of pkg.warnings) {
+            lines.push(`- WARNING: ${warning}`);
+        }
+        lines.push('');
+    }
+    lines.push('## Current State');
+    lines.push('');
+    lines.push(pkg.currentState);
+    lines.push('');
+    lines.push('## Next Action');
+    lines.push('');
+    lines.push(pkg.nextAction);
+    lines.push('');
+    if (pkg.blockers.length > 0) {
+        lines.push('## Blockers');
+        lines.push('');
+        for (const blocker of pkg.blockers) {
+            lines.push(`- ${blocker}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function topItems(items, limit) {
+    return items.slice(0, limit);
+}
+export function buildHandoffSummaryText(args) {
+    const lines = [];
+    lines.push(`# Implementation Handoff Package - ${args.pkg.specId}`);
+    lines.push('');
+    lines.push(`Readiness Score: ${String(args.pkg.readinessScore)}/100`);
+    lines.push(`Blocked: ${args.pkg.blocked ? 'yes' : 'no'}`);
+    if (args.pkg.handoffPath) {
+        lines.push(`Handoff Path: ${args.pkg.handoffPath}`);
+    }
+    if (args.pkg.contextHash) {
+        lines.push(`Context Hash: ${args.pkg.contextHash}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+    const filesToTestCount = (args.pkg.filesToTest ?? []).length;
+    lines.push(`Counts: ${String(args.pkg.criteria.length)} criteria, ${String(args.pkg.filesToModify.length)} files to modify, ${String(args.pkg.filesToCreate.length)} files to create, ${String(filesToTestCount)} files to test, ${String(args.pkg.testPlan.length)} tests, ${String(args.pkg.risks.length)} risks.`);
+    if (args.topBlockers.length > 0) {
+        lines.push(`Top blockers: ${args.topBlockers.join('; ')}`);
+    }
+    if (args.topRisks.length > 0) {
+        lines.push(`Top risks: ${args.topRisks.join('; ')}`);
+    }
+    if (args.minimalityBlocked !== null) {
+        lines.push(`Minimality: ${args.minimalityBlocked ? 'blocked' : 'pass'}`);
+    }
+    if (args.tokenWasteRiskCount !== null) {
+        lines.push(`Token Waste Autopilot risks: ${String(args.tokenWasteRiskCount)}`);
+    }
+    lines.push(`Next Action: ${args.pkg.nextAction}`);
+    lines.push('');
+    lines.push('Full handoff is available via the handoffPath artifact; it is not embedded by default.');
+    return lines.join('\n');
+}
+export function summarizeMinimality(report) {
+    if (report === null) {
+        return undefined;
+    }
+    const blockingFindings = report.findings.filter((finding) => finding.blocksDone);
+    return {
+        enabled: report.enabled,
+        blocked: report.blocked,
+        findingCount: report.findings.length,
+        blockingFindingCount: blockingFindings.length,
+        blockersTop3: topItems(blockingFindings, 3).map((finding) => ({
+            ruleId: finding.ruleId,
+            target: finding.target,
+            evidence: finding.evidence,
+        })),
+        safetyExceptionCount: report.safetyExceptions.length,
+        debtEvidenceCount: report.debtEvidence.length,
+    };
+}
+export function summarizeTokenWaste(report) {
+    if (report === null) {
+        return undefined;
+    }
+    return {
+        actionsTakenCount: report.actionsTaken.length,
+        recommendationCount: report.recommendations.length,
+        riskCount: report.risks.length,
+        risksTop3: topItems(report.risks, 3).map((risk) => ({
+            decision: risk.decision,
+            target: risk.target,
+            reason: risk.reason,
+            confidence: risk.confidence,
+        })),
+        modelEffort: {
+            effort: report.modelEffort.effort,
+            reason: report.modelEffort.reason,
+        },
+    };
+}
+export function summarizeGraphContext(graphContext) {
+    if (graphContext === null || typeof graphContext !== 'object') {
+        return { available: false };
+    }
+    const graph = graphContext;
+    return {
+        available: true,
+        nodeCount: Array.isArray(graph.nodes) ? graph.nodes.length : 0,
+        edgeCount: Array.isArray(graph.edges) ? graph.edges.length : 0,
+        summary: graph.summary,
+        tokenSavings: graph.tokenSavings,
+        freshness: graph.freshness
+            ? {
+                graphPath: graph.freshness.graphPath,
+                stale: graph.freshness.stale,
+                reason: graph.freshness.reason,
+            }
+            : undefined,
+    };
+}
+export async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
+    const { policy } = await loadTokenWastePolicy(knowledge.projectPath);
+    if (!policy.enabled) {
+        return null;
+    }
+    const context = analyzeContextPreflight({
+        action: 'package_handoff',
+        policy,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+        candidates: [...pkg.filesToModify, ...pkg.filesToCreate, ...(pkg.filesToTest ?? [])].map((path) => ({
+            path,
+            reason: 'Referenced by handoff package.',
+        })),
+        spec: {
+            id: spec.id,
+            risk: spec.risk,
+            target: spec.target,
+        },
+    });
+    const tools = recommendRelevantTools({
+        action: 'package_handoff',
+        intentSignals: ['handoff', spec.scope ?? '', spec.target ?? ''].filter(Boolean),
+        tools: toolsFromPolicyGroups(policy),
+        policy,
+    });
+    return buildTokenWasteReport({
+        action: 'package_handoff',
+        policy,
+        context,
+        tools,
+        spec: {
+            id: spec.id,
+            risk: spec.risk,
+            scope: spec.scope,
+        },
+    });
+}
+export async function buildGraphContextSection(args) {
+    if (args.projectPath === undefined) {
+        return null;
+    }
+    try {
+        const slice = await queryProjectGraphSlice({
+            projectId: args.projectId,
+            projectPath: args.projectPath,
+            specId: args.specId,
+        });
+        if (slice === null || slice.nodes.length === 0) {
+            return null;
+        }
+        return { text: await formatProjectGraphContext(slice), structured: slice };
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildMinimalImplementationReport(pkg, knowledge, spec, handoffText) {
+    const { policy, evidence } = await loadMinimalImplementationPolicy(knowledge.projectPath);
+    return analyzeMinimalImplementation({
+        policy,
+        specId: spec.id,
+        specRisk: spec.risk,
+        handoffText,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+        files: [...pkg.filesToModify, ...pkg.filesToCreate, ...(pkg.filesToTest ?? [])].map((path) => ({
+            path,
+            content: path,
+        })),
+        evidence,
+    });
+}
+//# sourceMappingURL=handoff-format.js.map

package/dist/engine/handoff-packager.d.ts

@@ -1,4 +1,4 @@
-import type { Spec, ProjectKnowledge, HandoffPackage } from '../types/index.js';
+import type { Spec, ProjectKnowledge, HandoffPackage, HandoffVersionFence } from '../types/index.js';
 /** Normalize one repository-relative ownership path without retaining unsafe input in diagnostics. */
 export declare function normalizeOwnedPath(value: string): {
     status: 'valid';
@@ -7,7 +7,7 @@ export declare function normalizeOwnedPath(value: string): {
     status: 'none';
 } | {
     status: 'invalid';
-    code: 'INVALID_FILE_OWNERSHIP_EMPTY' | 'INVALID_FILE_OWNERSHIP_FENCED' | 'INVALID_FILE_OWNERSHIP_NUL' | 'INVALID_FILE_OWNERSHIP_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_HOME_RELATIVE' | 'INVALID_FILE_OWNERSHIP_UNC' | 'INVALID_FILE_OWNERSHIP_DRIVE_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_URI' | 'INVALID_FILE_OWNERSHIP_TRAVERSAL' | 'INVALID_FILE_OWNERSHIP_MARKDOWN' | 'INVALID_FILE_OWNERSHIP_DESCRIPTION';
+    code: 'INVALID_FILE_OWNERSHIP_EMPTY' | 'INVALID_FILE_OWNERSHIP_FENCED' | 'INVALID_FILE_OWNERSHIP_NUL' | 'INVALID_FILE_OWNERSHIP_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_HOME_RELATIVE' | 'INVALID_FILE_OWNERSHIP_UNC' | 'INVALID_FILE_OWNERSHIP_DRIVE_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_URI' | 'INVALID_FILE_OWNERSHIP_TRAVERSAL' | 'INVALID_FILE_OWNERSHIP_MARKDOWN' | 'INVALID_FILE_OWNERSHIP_DESCRIPTION' | 'INVALID_FILE_OWNERSHIP_CHARSET';
 };
 /** Normalize a raw traceability changed-file value without interpreting Markdown or prose. */
 export declare function normalizeChangedFilePath(value: string): ReturnType<typeof normalizeOwnedPath>;
@@ -21,5 +21,7 @@ export declare function extractCanonicalFileOwnership(content: string): {
     toTestDeclared: string[];
     blockers: string[];
 };
-export declare function packageHandoff(spec: Spec, knowledge: ProjectKnowledge): Promise<HandoffPackage>;
+export declare function packageHandoff(spec: Spec, knowledge: ProjectKnowledge, versionFence?: HandoffVersionFence): Promise<HandoffPackage & {
+    readonly staleVersionSkipped?: boolean;
+}>;
 //# sourceMappingURL=handoff-packager.d.ts.map

package/dist/engine/handoff-packager.js

@@ -1,6 +1,7 @@
 // engine/handoff-packager.ts — Assembles handoff context package for AI agents (SPEC-039)
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+/* eslint-disable max-lines -- package assembly and the SPEC-1240 atomic-publish/version-fence path stay co-located for auditability */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { stripFrontmatter } from './frontmatter-parser.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
@@ -118,6 +119,7 @@ function ownershipItems(content) {
     }
     return { items: extractListItems(visibleLines.join('\n')), fenced };
 }
+const OWNERSHIP_DESCRIPTION_SEPARATOR = /\s+(?:—|–|-)\s+/u;
 /** Normalize one repository-relative ownership path without retaining unsafe input in diagnostics. */
 export function normalizeOwnedPath(value) {
     const trimmed = value.trim();
@@ -125,7 +127,9 @@ export function normalizeOwnedPath(value) {
         return { status: 'none' };
     }
     const backticked = /^`([^`]+)`/.exec(trimmed)?.[1];
-    const candidate = (backticked ?? trimmed.split(/\s+(?:—|–|-)\s+|\s+\(/, 1)[0] ?? '').trim();
+    const candidate = (backticked ??
+        trimmed.split(new RegExp(`${OWNERSHIP_DESCRIPTION_SEPARATOR.source}|\\s+\\(`, 'u'), 1)[0] ??
+        '').trim();
     if (candidate.length === 0) {
         return { status: 'invalid', code: 'INVALID_FILE_OWNERSHIP_EMPTY' };
     }
@@ -323,34 +327,63 @@ function stripInertOwnershipMarkup(content) {
 function normalizeStrictOwnedPath(rawValue) {
     const normalized = normalizeOwnedPath(rawValue);
     if (normalized.status !== 'valid') {
-        return null;
+        return normalized;
     }
-    return /^[A-Za-z0-9._/()[\]@-]+$/u.test(normalized.path) ? normalized.path : null;
+    return /^[A-Za-z0-9._/()[\]@-]+$/u.test(normalized.path)
+        ? normalized
+        : { status: 'invalid', code: 'INVALID_FILE_OWNERSHIP_CHARSET' };
+}
+function ownershipHeadEnd(rawPath) {
+    const masked = rawPath.replaceAll(/`[^`\n]+`/gu, (match) => 'x'.repeat(match.length));
+    return OWNERSHIP_DESCRIPTION_SEPARATOR.exec(masked)?.index ?? rawPath.length;
+}
+const ownershipReasonCode = (result) => result.status === 'invalid' ? result.code : 'INVALID_FILE_OWNERSHIP_EMPTY';
+function ownershipInvalidTokenBlocker(token, classification, reasonCode) {
+    const printed = JSON.stringify(token.length > 120 ? token.slice(0, 120) : token);
+    const hint = `${OWNERSHIP_LINE_SHAPE_HINT} reason=${reasonCode}`;
+    return ownershipBlocker(printed, [classification, 'InvalidPath'], hint);
 }
 function collectStrictOwnershipEntry(rawValue, classification, state) {
     const rawPath = rawValue.trim();
-    const backtickedValues = [...rawPath.matchAll(/`([^`\n]+)`/gu)].map((match) => match[1] ?? '');
-    const backtickedPaths = backtickedValues.map(normalizeStrictOwnedPath);
-    const residual = rawPath.replaceAll(/`[^`\n]+`/gu, '').trim();
-    const residualIsSafe = isSafeOwnershipResidual(residual);
-    if (backtickedPaths.some((path) => path === null) ||
-        (backtickedValues.length > 0 && !residualIsSafe)) {
-        state.blockers.push(ownershipBlocker('<redacted>', [classification, 'InvalidPath'], OWNERSHIP_LINE_SHAPE_HINT));
+    const head = rawPath.slice(0, ownershipHeadEnd(rawPath));
+    const backtickMatches = [...head.matchAll(/`([^`\n]+)`/gu)].map((match) => match[1] ?? '');
+    const pathCandidates = backtickMatches.filter((token) => /[./]/u.test(token));
+    const pushInvalid = (token, code) => {
+        state.blockers.push(ownershipInvalidTokenBlocker(token, classification, code));
+    };
+    if (!/`[^`\n]+`/u.test(rawPath)) {
+        const direct = normalizeStrictOwnedPath(head);
+        if (direct.status !== 'valid') {
+            pushInvalid(head, ownershipReasonCode(direct));
+            return;
+        }
+        collectStrictOwnershipPath(direct.path, classification, state);
         return;
     }
-    const directPath = normalizeStrictOwnedPath(rawPath);
-    const paths = backtickedPaths.length > 0
-        ? backtickedPaths
-        : directPath === null
-            ? []
-            : [directPath];
-    if (paths.length === 0) {
-        const diagnosticPath = /^`[^`]+`$/u.test(rawPath) ? '<redacted>' : rawPath || '<empty>';
-        state.blockers.push(ownershipBlocker(diagnosticPath, [classification, 'InvalidPath'], OWNERSHIP_LINE_SHAPE_HINT));
+    if (backtickMatches.length === 0) {
+        pushInvalid(head, 'INVALID_FILE_OWNERSHIP_HEAD_RESIDUAL');
+        return;
+    }
+    const residual = head.replaceAll(/`[^`\n]+`/gu, '').trim();
+    if (!isSafeOwnershipResidual(residual)) {
+        pushInvalid(residual, 'INVALID_FILE_OWNERSHIP_HEAD_RESIDUAL');
+        return;
+    }
+    const normalizedCandidates = pathCandidates.map((token) => ({
+        token,
+        result: normalizeStrictOwnedPath(token),
+    }));
+    const failed = normalizedCandidates.filter(({ result }) => result.status !== 'valid');
+    if (failed.length > 0) {
+        for (const { token, result } of failed) {
+            pushInvalid(token, ownershipReasonCode(result));
+        }
         return;
     }
-    for (const path of paths) {
-        collectStrictOwnershipPath(path, classification, state);
+    for (const { result } of normalizedCandidates) {
+        if (result.status === 'valid') {
+            collectStrictOwnershipPath(result.path, classification, state);
+        }
     }
 }
 function collectStrictOwnershipPath(path, classification, state) {
@@ -435,7 +468,7 @@ function extractFileLevelWorkPlanOwnership(content) {
     };
 }
 function validateOwnershipAgreement(canonical, workPlan, testDeclaredPaths) {
-    if (!canonical.present || !workPlan.present) {
+    if (!canonical.present) {
         return [];
     }
     const testDeclared = new Set(testDeclaredPaths);
@@ -444,6 +477,13 @@ function validateOwnershipAgreement(canonical, workPlan, testDeclaredPaths) {
         : ownership.toModify.includes(path)
             ? 'Modify'
             : 'Absent';
+    if (!workPlan.present) {
+        const canonicalPaths = [...canonical.toCreate, ...canonical.toModify].filter((path) => !testDeclared.has(path));
+        return [...new Set(canonicalPaths)].sort().map((path) => {
+            const canonicalClass = classification(canonical, path);
+            return ownershipBlocker(path, [`Canonical:${canonicalClass}`, 'WorkPlan:Absent'], ownershipAgreementHint(canonicalClass, 'Absent', path));
+        });
+    }
     const paths = new Set([
         ...canonical.toCreate,
         ...canonical.toModify,
@@ -463,9 +503,9 @@ function validateOwnershipAgreement(canonical, workPlan, testDeclaredPaths) {
 function extractBacktickedFiles(content) {
     const files = new Set();
     for (const match of content.matchAll(/`([^`\n]+)`/gu)) {
-        const path = match[1] ? normalizeStrictOwnedPath(match[1]) : null;
-        if (path) {
-            files.add(path);
+        const normalized = match[1] ? normalizeStrictOwnedPath(match[1]) : null;
+        if (normalized?.status === 'valid') {
+            files.add(normalized.path);
         }
     }
     return [...files].sort();
@@ -602,7 +642,7 @@ function buildConstraints(knowledge) {
     return constraints;
 }
 // ── Public API ───────────────────────────────────────────────────────────────
-export async function packageHandoff(spec, knowledge) {
+export async function packageHandoff(spec, knowledge, versionFence) {
     const warnings = [];
     const rawSpecContent = spec.specPath
         ? await readFile(spec.specPath, 'utf-8').catch(() => '')
@@ -685,7 +725,7 @@ export async function packageHandoff(spec, knowledge) {
         blocked: blockers.length > 0,
         blockers,
     };
-    return persistHandoffIfPossible(pkg, knowledge);
+    return persistHandoffIfPossible(pkg, knowledge, versionFence);
 }
 function renderPersistedHandoff(pkg) {
     return [
@@ -733,19 +773,36 @@ function renderPersistedHandoff(pkg) {
         '',
     ].join('\n');
 }
-async function persistHandoffIfPossible(pkg, knowledge) {
+async function persistHandoffIfPossible(pkg, knowledge, versionFence) {
     if (!knowledge.projectPath) {
         return pkg;
     }
     const handoffDir = join(projectDataDir(hashProjectPath(knowledge.projectPath)), 'handoffs');
     const handoffPath = join(handoffDir, `${pkg.specId}.md`);
+    const tempPath = join(handoffDir, `.${pkg.specId}.md.tmp-${randomUUID()}`);
     const sessionContextPath = join(knowledge.projectPath, 'planu', 'session-context.md');
     const markdown = renderPersistedHandoff(pkg);
     try {
         await mkdir(handoffDir, { recursive: true });
-        await writeFile(handoffPath, markdown, 'utf-8');
+        await writeFile(tempPath, markdown, 'utf-8');
+        if (versionFence) {
+            const abandoned = versionFence.signal?.aborted === true;
+            const currentSpecVersion = abandoned ? undefined : await versionFence.getCurrentSpecVersion();
+            if (abandoned ||
+                (currentSpecVersion !== undefined && currentSpecVersion !== versionFence.specVersion)) {
+                await rm(tempPath, { force: true });
+                return { ...pkg, staleVersionSkipped: true };
+            }
+        }
+        await rename(tempPath, handoffPath);
     }
-    catch {
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => {
+            /* best-effort temp cleanup — the publish already failed */
+        });
+        if (versionFence) {
+            throw error;
+        }
         return {
             ...pkg,
             warnings: [