@planu/cli 5.7.5 → 5.7.7

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: [

package/dist/engine/host-tool-filter.js

@@ -7,63 +7,34 @@ import { fileURLToPath } from 'node:url';
 // Core AGENTS.md tool reference — curated list of key Planu tools
 // ---------------------------------------------------------------------------
 export const CORE_AGENTS_MD_TOOLS = [
+    { name: 'init_project', description: 'Load or bootstrap Planu project context' },
+    { name: 'facilitate', description: 'Universal entry point for SDD workflow' },
     { name: 'create_spec', description: 'Create a new spec from a description' },
     { name: 'list_specs', description: 'List all specs and their status' },
     { name: 'update_status', description: 'Move a spec through workflow stages' },
+    {
+        name: 'update_status_batch',
+        description: 'Batch update many specs to the same status in one MCP execution',
+    },
     { name: 'validate', description: 'Check implementation against spec criteria' },
     { name: 'challenge_spec', description: 'Stress-test a spec for gaps before implementation' },
     { name: 'check_readiness', description: 'Verify spec has enough detail to implement' },
-    { name: 'planu_status', description: 'Quick project health snapshot' },
-    { name: 'facilitate', description: 'Universal entry point for SDD workflow' },
-    { name: 'plan_mode', description: 'Preview implementation plan before writing code' },
-    { name: 'generate_steering_file', description: 'Generate host-aware steering files' },
-    { name: 'search_specs', description: 'Search specs with fuzzy text matching' },
-    { name: 'spec_quality_score', description: 'Compute quality score for a spec' },
-    { name: 'analyze_spec_size', description: 'Analyze if a spec should be split' },
-    { name: 'decompose_spec', description: 'Decompose a spec into agent tasks' },
-    { name: 'estimate', description: 'Estimate time and cost for a spec' },
-    { name: 'session_checkpoint', description: 'Save session context' },
-    { name: 'project_overview', description: 'Single-call project state query' },
-    { name: 'scan_project', description: 'Scan project and generate specs' },
-    { name: 'validate_workflow', description: 'Validate a workflow definition' },
-    { name: 'tdd_scaffold', description: 'Generate TDD test stubs from spec criteria' },
-    { name: 'coverage_gap_analyzer', description: 'Analyze untested acceptance criteria' },
-    { name: 'security_scan', description: 'Scan dependencies for vulnerabilities' },
-    { name: 'bootstrap_skills', description: 'Auto-install skills for detected stack' },
-    { name: 'manage_drift', description: 'Detect and resolve spec drift' },
-    { name: 'sync_spec_state', description: 'Sync spec status between frontmatter and store' },
-    { name: 'health_check_all', description: 'Run health check on all specs' },
-    { name: 'tokens', description: 'Token usage dashboard' },
-    { name: 'configure_workers', description: 'Configure background analysis workers' },
     {
-        name: 'approve_spec',
-        description: 'Record that a reviewer has approved a spec — requires reviewer token',
+        name: 'bump_spec_version',
+        description: "Bump the SemVer spec_version of a spec's frontmatter",
+    },
+    { name: 'reconcile_spec', description: 'Reconcile implementation drift back into the spec' },
+    {
+        name: 'migrate_legacy_spec',
+        description: 'Persist a synthesized spec.md and retire legacy files',
     },
-    { name: 'lock_spec', description: 'Acquire exclusive lock on a spec' },
-    { name: 'register_api_surface', description: 'Register API surfaces exposed by a spec' },
-    { name: 'analyze_breaking_changes', description: 'Analyze specs impacted by API changes' },
-    { name: 'track_tech_debt', description: 'Track a new tech debt item' },
-    { name: 'capture_idea', description: 'Capture a lightweight idea' },
-    { name: 'log_lesson', description: 'Log a lesson learned' },
-    { name: 'semantic_search', description: 'Search project knowledge by meaning' },
-    { name: 'render_spec_for_provider', description: 'Render spec for target LLM provider' },
-    { name: 'convert_to_bdd', description: 'Convert spec criteria to BDD format' },
-    { name: 'generate_e2e_tests', description: 'Generate E2E tests from spec criteria' },
-    { name: 'run_spec_lint', description: 'Run custom lint rules against specs' },
-    { name: 'suggest_criteria', description: 'Suggest missing best-practice criteria' },
-    { name: 'check_compliance', description: 'Unified compliance tool' },
-    { name: 'create_release', description: 'Create a GitHub Release' },
-    { name: 'generate_changelog', description: 'Generate changelog from merged PRs' },
-    { name: 'create_pr_from_spec', description: 'Create a PR from a spec' },
-    { name: 'onboarding_progress', description: 'View onboarding progress' },
-    { name: 'list_templates', description: 'Browse spec template catalog' },
-    { name: 'generate_docs_site', description: 'Generate static HTML docs site' },
-    { name: 'plan_team_distribution', description: 'Distribute specs across agents' },
-    { name: 'optimize_spec_scheduling', description: 'Minimize agent idle time' },
-    { name: 'context_window_status', description: 'Estimate token consumption' },
-    { name: 'archive_spec_context', description: 'Archive a spec to free tokens' },
-    { name: 'workspace_overview', description: 'Get overview of all projects' },
-    { name: 'search_all_projects', description: 'Search specs across all projects' },
+    { name: 'package_handoff', description: 'Generate an implementation handoff package for a spec' },
+    { name: 'planu_status', description: 'Quick project health snapshot' },
+    { name: 'session_checkpoint', description: 'Save session context' },
+    { name: 'estimate', description: 'Estimate time and cost for a spec' },
+    { name: 'request_changes', description: 'Request changes on a spec, moving it back to draft' },
+    { name: 'get_job', description: 'Read the durable state of a local Planu job' },
+    { name: 'restart_job', description: 'Restart a cancelled or failed durable job' },
 ];
 // ---------------------------------------------------------------------------
 // Interactive detection heuristics

package/dist/engine/human-summary.js

@@ -89,20 +89,31 @@ export function buildListSpecsSummary(total, byStatus) {
         return `No plans found in this project yet. Use create_spec to add your first one.`;
     }
     const get = (key) => byStatus[key] ?? 0;
-    const inProgress = get('implementing') + get('approved');
+    const inProgress = get('implementing');
+    const approved = get('approved');
     const inReview = get('review');
+    const approvedClause = approved > 0 ? `${String(approved)} approved ready to implement` : '';
     if (inReview > 0 && inProgress > 0) {
         const reviewNoun = inReview === 1 ? 'plan' : 'plans';
-        return `You have ${String(inProgress)} in progress and ${String(inReview)} ${reviewNoun} ready to review. Start with the ones under review.`;
+        const suffix = approvedClause ? ` and ${approvedClause}` : '';
+        return `You have ${String(inProgress)} in progress and ${String(inReview)} ${reviewNoun} ready to review${suffix}. Start with the ones under review.`;
     }
     if (inReview > 0) {
         const noun = inReview === 1 ? 'plan' : 'plans';
-        return `You have ${String(inReview)} ${noun} ready to review. Approve or request changes to move forward.`;
+        const suffix = approvedClause ? ` You also have ${approvedClause}.` : '';
+        return `You have ${String(inReview)} ${noun} ready to review. Approve or request changes to move forward.${suffix}`;
+    }
+    if (inProgress > 0 && approved > 0) {
+        return `You have ${String(inProgress)} in progress and ${approvedClause}. Run validate when implementation is done.`;
     }
     if (inProgress > 0) {
         const noun = inProgress === 1 ? 'plan' : 'plans';
         return `You have ${String(inProgress)} ${noun} in progress. Run validate when implementation is done.`;
     }
+    if (approved > 0) {
+        const noun = approved === 1 ? 'plan' : 'plans';
+        return `You have ${String(approved)} ${noun} approved ready to implement. Run validate when implementation is done.`;
+    }
     return `You have ${String(total)} plans in this project. Approve a plan to start implementing.`;
 }
 /** estimate — time and cost estimated for a spec */