@planu/cli 5.3.68 → 5.3.69

package/dist/tools/update-status/side-effects.js

@@ -1,9 +1,14 @@
 import { specStore } from '../../storage/index.js';
 import { runCascade } from '../../engine/cascade-hooks/runner.js';
+import { setDispatchHookEventHandler } from '../../engine/cascade-hooks/hooks/dispatch-hook-event.hook.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 import { getRuntimePolicy } from '../../engine/runtime-policy.js';
 import { createExecutionScope } from '../../engine/execution/context.js';
+import { dispatchHookEvent } from '../manage-hooks.js';
+// Wire the tools-layer hook dispatcher into the engine's cascade hook
+// (see engine/cascade-hooks/hooks/dispatch-hook-event.hook.ts — engine must not import tools/ directly).
+setDispatchHookEventHandler(dispatchHookEvent);
 const queuedTransitions = new Map();
 const CASCADE_ISOLATED_SCOPE_MS = 30_000;
 const pendingPostCommitWork = new Set();

package/dist/tools/update-status-actions.js

@@ -78,12 +78,18 @@ export async function runImplementingSideEffects(projectId, specId, transitionPr
     try {
         const spec = foundSpec ?? (await specStore.getSpec(projectId, specId));
         const results = await Promise.allSettled([
-            // SPEC-633: Write session state when spec moves to implementing
+            // SPEC-633: Write session state when spec moves to implementing, then refresh
+            // the paired session artifacts from the resulting store state.
             (async () => {
-                const { writeSpecSessionState } = await import('../engine/session-state/writer.js');
-                await writeSpecSessionState(projectPath, specId, spec?.title ?? specId, 'moved to implementing').catch(() => {
+                try {
+                    const { writeSpecSessionState } = await import('../engine/session-state/writer.js');
+                    await writeSpecSessionState(projectPath, specId, spec?.title ?? specId, 'moved to implementing');
+                    const { refreshSessionArtifacts } = await import('../engine/session-state/session-artifact-refresher.js');
+                    await refreshSessionArtifacts(projectPath, projectId);
+                }
+                catch {
                     /* best-effort */
-                });
+                }
             })(),
             // SPEC-635: Regenerate context.md
             (async () => {
@@ -92,19 +98,6 @@ export async function runImplementingSideEffects(projectId, specId, transitionPr
                     /* best-effort */
                 });
             })(),
-            // SPEC-656: Recalculate epicProgress when spec moves to implementing
-            (async () => {
-                try {
-                    const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
-                    const allSpecs = await specStore.listSpecs(projectId);
-                    await updateEpicProgressInSession(projectPath, allSpecs).catch(() => {
-                        /* best-effort */
-                    });
-                }
-                catch {
-                    /* best-effort */
-                }
-            })(),
             // recommend_model — suggest haiku/sonnet/opus based on spec complexity
             (async () => {
                 try {
@@ -166,13 +159,6 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
             try {
                 const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
                 const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
-                if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
-                    await gitCmd(projectPath, ['add', 'planu/']);
-                    const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
-                    void planuAutoCommit({ projectPath, specId, reason: 'mark-done' }).catch((err) => {
-                        console.error('[update-status] planuAutoCommit failed:', err instanceof Error ? err.message : String(err));
-                    });
-                }
                 const { stdout } = await gitCmd(projectPath, ['status', '--porcelain']);
                 const nonPlanuLines = stdout
                     .trim()
@@ -243,15 +229,6 @@ export async function runDoneSideEffects(projectId, specId, gitBranch, transitio
             const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');
             return withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch));
         })(),
-        (async () => {
-            const { removeSpecFromSession } = await import('../engine/session-state/writer.js');
-            await removeSpecFromSession(projectPath, specId);
-        })(),
-        (async () => {
-            const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
-            const allSpecs = await specStore.listSpecs(projectId);
-            await updateEpicProgressInSession(projectPath, allSpecs);
-        })(),
         (async () => {
             const { generateContextMd } = await import('../engine/context-md-generator.js');
             await generateContextMd(projectPath, projectId);
@@ -266,26 +243,37 @@ export async function runDoneSideEffects(projectId, specId, gitBranch, transitio
             return runHousekeepingSweep({ projectPath });
         })(),
         (async () => {
-            if (hasPending(specId, 'generateSessionContext')) {
+            if (hasPending(specId, 'refreshSessionArtifacts')) {
                 return;
             }
-            markPending(specId, 'generateSessionContext');
+            markPending(specId, 'refreshSessionArtifacts');
             try {
-                const { generateSessionContext } = await import('../engine/session-context-generator.js');
-                await generateSessionContext(projectPath, projectId);
+                const { refreshSessionArtifacts } = await import('../engine/session-state/session-artifact-refresher.js');
+                await refreshSessionArtifacts(projectPath, projectId);
             }
             finally {
-                clearPending(specId, 'generateSessionContext');
+                clearPending(specId, 'refreshSessionArtifacts');
             }
         })(),
     ]);
+    if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
+        try {
+            const { git: gitCmd } = await import('./git/git-helpers.js');
+            await gitCmd(projectPath, ['add', 'planu/']);
+            const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
+            await planuAutoCommit({ projectPath, specId, reason: 'mark-done' });
+        }
+        catch (err) {
+            console.error('[update-status] planuAutoCommit failed:', err instanceof Error ? err.message : String(err));
+        }
+    }
     const failures = results.filter((result) => result.status === 'rejected');
     if (failures.length > 0) {
         throw new AggregateError(normalizeRejectedReasons(failures), `${String(failures.length)} done side effect(s) failed`);
     }
     const cleanup = results[0].status === 'fulfilled' ? results[0].value : null;
-    const planuCleanup = results[4].status === 'fulfilled' ? results[4].value : null;
-    const housekeeping = results[5].status === 'fulfilled' ? results[5].value : null;
+    const planuCleanup = results[2].status === 'fulfilled' ? results[2].value : null;
+    const housekeeping = results[3].status === 'fulfilled' ? results[3].value : null;
     return {
         cleanupProposals: cleanup?.proposals ?? [],
         housekeepingProposal: housekeeping ?? {

package/dist/tools/validate-graph-coverage.js

@@ -11,6 +11,9 @@ function graphCoverageGaps(slice) {
         .map((criterion) => criterion.label)
         .slice(0, 10);
 }
+function graphCoverageWarnings(slice) {
+    return slice.oversizedSources.map((record) => `oversized source: ${record.path} (${record.kind}, ${record.action})`);
+}
 export async function buildGraphCoverageReport(args) {
     let graphSlice;
     try {
@@ -21,7 +24,13 @@ export async function buildGraphCoverageReport(args) {
         graphSlice = null;
     }
     if (graphSlice === null) {
-        return { availability: 'unavailable', gaps: [], compactNodes: 0, compactEdges: 0 };
+        return {
+            availability: 'unavailable',
+            gaps: [],
+            compactNodes: 0,
+            compactEdges: 0,
+            warnings: [],
+        };
     }
     return {
         availability: 'available',
@@ -29,14 +38,17 @@ export async function buildGraphCoverageReport(args) {
         gaps: graphCoverageGaps(graphSlice),
         compactNodes: graphSlice.nodes.length,
         compactEdges: graphSlice.edges.length,
+        warnings: graphCoverageWarnings(graphSlice),
     };
 }
 export function formatGraphCoverageText(report) {
     if (report.availability === 'unavailable') {
         return '\nGRAPH     unavailable (project graph unreadable)';
     }
-    return report.gaps.length > 0
+    const gapLine = report.gaps.length > 0
         ? `\nGRAPH     ${String(report.gaps.length)} graph-backed coverage gap(s)`
         : '';
+    const warningLines = report.warnings.map((warning) => `\nGRAPH     ${warning}`).join('');
+    return gapLine + warningLines;
 }
 //# sourceMappingURL=validate-graph-coverage.js.map

package/dist/tools/validate.js

@@ -867,6 +867,8 @@ function buildValidateStructuredContent(args) {
             availability: args.graphCoverage.availability,
             gapsCount: args.graphCoverage.gaps.length,
             gapsTop5: args.graphCoverage.gaps.slice(0, 5),
+            warningsCount: args.graphCoverage.warnings.length,
+            warningsTop5: args.graphCoverage.warnings.slice(0, 5),
             freshness: args.graphCoverage.freshness,
         },
         suggestionsTop5: args.suggestions.slice(0, 5),

package/dist/transports/middleware/types.d.ts

@@ -11,9 +11,9 @@ export interface ToolContext {
 /**
  * A tool handler function signature.
  */
-export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
+export type MiddlewareToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
 /**
- * A middleware is a higher-order function that wraps a ToolHandler.
+ * A middleware is a higher-order function that wraps a MiddlewareToolHandler.
  */
-export type Middleware = (handler: ToolHandler) => ToolHandler;
+export type Middleware = (handler: MiddlewareToolHandler) => MiddlewareToolHandler;
 //# sourceMappingURL=types.d.ts.map

package/dist/types/atomic-upgrade.d.ts

@@ -1,5 +1,5 @@
 import type { SpawnSyncReturns } from 'node:child_process';
-import type { InstallationManifest, InstallationRecord } from '../cli/commands/install.js';
+import type { InstallationManifest, InstallationRecord } from './installation.js';
 export type UpgradePhase = 'after-runtime-verification' | 'before-adapter-switch' | 'after-adapter-switch' | 'before-manifest-switch' | 'after-manifest-switch' | 'after-trust-switch';
 export type UpgradeJournalState = 'prepared' | 'switching' | 'trust-switched' | 'committed';
 export interface UpgradeJournal {

package/dist/types/cascade-hooks.d.ts

@@ -1,5 +1,8 @@
 import type { Spec } from './spec/core.js';
 import type { SpecStatus } from './common/primitives.js';
+import type { HookEventPayload } from './hooks.js';
+/** Port through which the dispatch-hook-event hook reaches the tools-layer hook dispatcher. */
+export type DispatchHookEventFn = (projectId: string, payload: HookEventPayload) => Promise<void>;
 export interface CascadeContext {
     specId: string;
     spec: Spec;

package/dist/types/dashboard.d.ts

@@ -1,4 +1,5 @@
-import type { Difficulty, RiskLevel, SpecStatus } from './common/index.js';
+import type { Difficulty, RiskLevel, SpecStatus, ToolResult } from './common/index.js';
+import type { UpdateStatusInput } from './spec/inputs.js';
 /** State of the dashboard HTTP server (singleton in memory) */
 export interface DashboardServerState {
     port: number;
@@ -69,6 +70,8 @@ export interface SpecStatusUpdateResult {
     newStatus: string;
     error?: string;
 }
+/** Port through which the dashboard status route reaches the tools-layer status gate. */
+export type UpdateStatusHandler = (input: UpdateStatusInput) => Promise<ToolResult>;
 /** Project health score with weighted components */
 export interface ProjectHealthScore {
     overall: number;

package/dist/types/durable-job.d.ts

@@ -35,4 +35,24 @@ export interface ValidateDurableJobPayload {
     readonly freshnessLease?: ValidationFreshnessLease;
     readonly specPath: string;
 }
+export declare const DURABLE_JOB_STATES: readonly ['accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed'];
+export type DurableJobState = (typeof DURABLE_JOB_STATES)[number];
+export interface DurableJobRecord {
+    readonly id: string;
+    readonly projectId: string;
+    readonly workspaceId: string;
+    readonly state: DurableJobState;
+    readonly payload: unknown;
+    readonly checkpoint?: unknown;
+    readonly result?: unknown;
+    readonly error?: string;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly cancelRequested: boolean;
+    readonly leaseOwner?: string;
+    readonly leaseExpiresAt?: string;
+    readonly fencingToken: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
 //# sourceMappingURL=durable-job.d.ts.map

package/dist/types/durable-job.js

@@ -1,2 +1,10 @@
-export {};
+export const DURABLE_JOB_STATES = [
+    'accepted',
+    'running',
+    'checkpointed',
+    'cancelled',
+    'failed',
+    'dead-letter',
+    'completed',
+];
 //# sourceMappingURL=durable-job.js.map

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './agent-roles.js';
+export * from './installation.js';
 export * from './cost-ledger.js';
 export * from './autopilot-summary.js';
 export * from './common/index.js';
@@ -264,6 +265,7 @@ export * from './agent-memory.js';
 export * from './agent-spawner.js';
 export * from './qa-gate.js';
 export * from './validation-evidence.js';
+export * from './spec-dependency-graph.js';
 export * from './project-drift.js';
 export * from './technical-enrichment.js';
 export * from './agent-team.js';

package/dist/types/index.js

@@ -1,5 +1,6 @@
 // Planu — SDD MCP Server Types (barrel re-export)
 export * from './agent-roles.js';
+export * from './installation.js';
 export * from './cost-ledger.js';
 export * from './autopilot-summary.js';
 export * from './common/index.js';
@@ -261,6 +262,7 @@ export * from './agent-memory.js';
 export * from './agent-spawner.js';
 export * from './qa-gate.js';
 export * from './validation-evidence.js';
+export * from './spec-dependency-graph.js';
 export * from './project-drift.js';
 export * from './technical-enrichment.js';
 export * from './agent-team.js';

package/dist/types/installation.d.ts

@@ -0,0 +1,16 @@
+export interface InstallationRecord {
+    host: string;
+    configPath: string;
+    format: 'standard' | 'zed';
+    scope: 'user' | 'project';
+    package: string;
+    version: string;
+    offline: boolean;
+    installedAt: string;
+}
+export interface InstallationManifest {
+    schemaVersion: 1;
+    updatedAt: string;
+    installations: InstallationRecord[];
+}
+//# sourceMappingURL=installation.d.ts.map

package/dist/types/installation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=installation.js.map

package/dist/types/project-knowledge-graph.d.ts

@@ -95,6 +95,14 @@ export interface ProjectKnowledgeGraph {
     };
     nodes: ProjectGraphNode[];
     edges: ProjectGraphEdge[];
+    oversizedSources: OversizedSourceRecord[];
+}
+export interface OversizedSourceRecord {
+    path: string;
+    kind: string;
+    bytes: number;
+    threshold: number;
+    action: 'tail' | 'skip';
 }
 export interface ProjectGraphSource {
     id: string;
@@ -148,6 +156,7 @@ export interface ProjectGraphBuildResult {
     removedSources: string[];
     skippedSources: string[];
     usedCache: boolean;
+    oversizedSources: OversizedSourceRecord[];
 }
 export interface ProjectGraphFreshness {
     exists: boolean;
@@ -170,6 +179,7 @@ export interface ProjectGraphSlice {
     freshness: ProjectGraphFreshness;
     nodes: ProjectGraphNode[];
     edges: ProjectGraphEdge[];
+    oversizedSources: OversizedSourceRecord[];
     summary: {
         specs: number;
         criteria: number;
@@ -203,6 +213,7 @@ export interface GraphCoverageReport {
     gaps: string[];
     compactNodes: number;
     compactEdges: number;
+    warnings: string[];
 }
 export interface NativeProjectGraphRuntime {
     nativeActive: boolean;

package/dist/types/session-checkpoint.d.ts

@@ -58,6 +58,22 @@ export interface SessionIndex {
     planVersion?: number;
     updatedAt: string;
 }
+/** SPEC-1320: Sanitized failure codes for the paired session-artifact refresher. */
+export type SessionArtifactRefreshFailureCode = 'STAGE_WRITE_FAILED' | 'COMMIT_FAILED' | 'UNEXPECTED_FAILURE';
+/** SPEC-1320: Outcome of a paired refresh of session.json and session-context.md. */
+export interface RefreshSessionArtifactsResult {
+    activeSpecIds: string[];
+    sessionJsonWritten: boolean;
+    sessionContextWritten: boolean;
+}
+/** SPEC-1320: A staged-but-not-yet-committed artifact write in the paired refresh. */
+export interface PreparedSessionArtifact {
+    finalPath: string;
+    content: string;
+    tmpPath: string;
+    changed: boolean;
+    previous: string | null;
+}
 /** SPEC-639: Status of a single agent worker in the handoff.json protocol. */
 export type AgentHandoffStatus = 'pending' | 'done' | 'failed';
 /** SPEC-639: Entry written by a worker agent when it completes its work. */

package/dist/types/spec-dependency-graph.d.ts

@@ -0,0 +1,21 @@
+export type EdgeKind = 'dependency' | 'supersedes' | 'depends_on';
+export interface GraphNode {
+    id: string;
+    status: string;
+    supersededBy?: string;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+}
+export interface SupersedesCycleDiagnostic {
+    code: 'SUPERSEDES_CYCLE';
+    cycle: string[];
+}
+export interface SpecGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    diagnostics: SupersedesCycleDiagnostic[];
+}
+//# sourceMappingURL=spec-dependency-graph.d.ts.map

package/dist/types/spec-dependency-graph.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spec-dependency-graph.js.map

package/dist/types/validation-evidence.d.ts

@@ -59,4 +59,49 @@ export interface ValidationImpactPlan {
     reason: string;
     changedPaths: string[];
 }
+export type ScenarioVerdict = 'pass' | 'fail' | 'missing';
+export interface ScenarioTestLink {
+    path: string;
+    line?: number;
+    runner?: string;
+    config?: string;
+    description?: string;
+}
+export interface ScenarioStep {
+    keyword: string;
+    text: string;
+}
+export interface FrontmatterScenario {
+    title: string;
+    done: boolean;
+    tests?: ScenarioTestLink[];
+    steps?: ScenarioStep[];
+}
+export interface PerScenarioResult {
+    title: string;
+    verdict: ScenarioVerdict;
+    evidence: string[];
+    unverifiable?: true;
+}
+export interface SpecComplianceResult {
+    dimensionScore: number;
+    perScenario: PerScenarioResult[];
+    command: string;
+    evidenceSource?: 'frontmatter' | 'criteria' | 'none';
+    ignoredCriteriaTitles?: string[];
+}
+export interface EvidenceTestLink {
+    path: string;
+}
+export interface EvidenceScenario {
+    title: string;
+    tests: EvidenceTestLink[];
+}
+export type ExecutableEvidenceSource = 'frontmatter' | 'criteria' | 'none';
+export interface ExecutableEvidence {
+    source: ExecutableEvidenceSource;
+    scenarios: EvidenceScenario[];
+    unmappedCriteria: string[];
+    ignoredCriteriaTitles: string[];
+}
 //# sourceMappingURL=validation-evidence.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.68",
+  "version": "5.3.69",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.3.68",
+  "version": "5.3.69",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",

package/dist/types/storage-bundle.d.ts

@@ -1,13 +0,0 @@
-import type { RuntimeDatabase, RuntimeProjectBundle } from '../storage/runtime-db.js';
-export interface StorageBundle {
-    readonly schemaVersion: 1;
-    readonly createdAt: string;
-    readonly runtimeSchemaVersion: number;
-    readonly projectId: string;
-    readonly payload: RuntimeProjectBundle;
-    readonly checksum: string;
-}
-export interface StorageBundleOptions {
-    readonly database?: RuntimeDatabase;
-}
-//# sourceMappingURL=storage-bundle.d.ts.map

package/dist/types/storage-bundle.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=storage-bundle.js.map