@planu/cli 4.6.1 → 4.7.0

package/dist/engine/project-graph/extractors/spec-extractor.js

@@ -0,0 +1,189 @@
+import YAML from 'yaml';
+import { hashText } from '../cache.js';
+import { redactGraphText } from '../query.js';
+function frontmatter(content) {
+    if (!content.startsWith('---')) {
+        return {};
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) {
+        return {};
+    }
+    try {
+        const parsed = YAML.parse(content.slice(3, end));
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function criterionTexts(fm, content) {
+    const raw = Array.isArray(fm.criteria) ? fm.criteria : [];
+    const fromFrontmatter = raw
+        .map((item) => typeof item === 'object' && item !== null && 'text' in item
+        ? asString(item.text)
+        : undefined)
+        .filter((item) => item !== undefined);
+    if (fromFrontmatter.length > 0) {
+        return fromFrontmatter;
+    }
+    return [...content.matchAll(/^- \[[ x]\]\s+(.+)$/gim)]
+        .map((match) => (match[1] ?? '').trim())
+        .filter((item) => item.length > 0);
+}
+function extractBacktickPaths(text, prefix) {
+    const idx = text.indexOf(prefix);
+    if (idx === -1) {
+        return [];
+    }
+    const fragment = text.slice(idx + prefix.length);
+    return [...fragment.matchAll(/`([^`]+)`/g)]
+        .map((match) => (match[1] ?? '').trim())
+        .filter((item) => item.length > 0);
+}
+function uniqueById(items) {
+    return [...new Map(items.map((item) => [item.id, item])).values()];
+}
+function node(args) {
+    return {
+        id: args.id,
+        type: args.type,
+        label: redactGraphText(args.label, args.policy),
+        source: 'spec-extractor',
+        evidence: [{ path: args.source.path, hash: args.source.hash }],
+        metadata: args.metadata,
+        updatedAt: new Date().toISOString(),
+    };
+}
+function edge(args) {
+    const id = `edge:${hashText(`${args.from}:${args.type}:${args.to}:${args.selector ?? ''}`)}`;
+    return {
+        id,
+        from: args.from,
+        to: args.to,
+        type: args.type,
+        source: 'spec-extractor',
+        confidence: args.confidence ?? 'high',
+        classification: args.classification ?? 'extracted',
+        evidence: { path: args.source.path, selector: args.selector, hash: args.source.hash },
+        updatedAt: new Date().toISOString(),
+    };
+}
+function sectionBullets(content, heading) {
+    const pattern = new RegExp(`^##+\\s+${heading}\\s*$`, 'im');
+    const match = pattern.exec(content);
+    if (!match) {
+        return [];
+    }
+    const start = match.index + match[0].length;
+    const rest = content.slice(start);
+    const nextHeading = rest.search(/^##+\s+/m);
+    const section = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+    return [...section.matchAll(/^-+\s+(.+)$/gm)]
+        .map((item) => (item[1] ?? '').trim())
+        .filter((item) => item.length > 0)
+        .slice(0, 20);
+}
+function appendRiskAndDecisionNodes(args) {
+    for (const [index, risk] of [
+        ...sectionBullets(args.source.content, 'Risks'),
+        ...sectionBullets(args.source.content, 'Edge Cases And Failure Modes'),
+    ].entries()) {
+        const riskId = `risk:${args.specId}:${String(index + 1)}`;
+        args.nodes.push(node({
+            id: riskId,
+            type: 'risk',
+            label: risk,
+            source: args.source,
+            policy: args.policy,
+            metadata: { specId: args.specId },
+        }));
+        args.edges.push(edge({ from: args.specNodeId, to: riskId, type: 'has_risk', source: args.source }));
+    }
+    for (const [index, decision] of [
+        ...sectionBullets(args.source.content, 'Hard constraints'),
+        ...sectionBullets(args.source.content, 'Non-Goals And Forbidden Approaches'),
+    ].entries()) {
+        const decisionId = `decision:${args.specId}:${String(index + 1)}`;
+        args.nodes.push(node({
+            id: decisionId,
+            type: 'decision',
+            label: decision,
+            source: args.source,
+            policy: args.policy,
+            metadata: { specId: args.specId },
+        }));
+        args.edges.push(edge({ from: args.specNodeId, to: decisionId, type: 'decides', source: args.source }));
+    }
+}
+function appendToolNodes(args) {
+    for (const toolName of args.policy.toolNamePatterns) {
+        if (args.source.content.includes(toolName)) {
+            const toolId = `tool:${toolName}`;
+            args.nodes.push(node({
+                id: toolId,
+                type: 'tool',
+                label: toolName,
+                source: args.source,
+                policy: args.policy,
+            }));
+            args.edges.push(edge({
+                from: args.specNodeId,
+                to: toolId,
+                type: 'uses_tool',
+                source: args.source,
+                confidence: 'medium',
+                classification: 'inferred',
+            }));
+        }
+    }
+}
+export function extractSpecGraph(source, policy) {
+    const fm = frontmatter(source.content);
+    const specId = asString(fm.id) ?? source.path.split('/').find((part) => /^SPEC-\d+/.test(part));
+    if (specId === undefined) {
+        return { nodes: [], edges: [] };
+    }
+    const title = asString(fm.title) ?? specId;
+    const specNodeId = `spec:${specId}`;
+    const nodes = [
+        node({
+            id: specNodeId,
+            type: 'spec',
+            label: `${specId} ${title}`,
+            source,
+            policy,
+            metadata: { specId, status: asString(fm.status) ?? null },
+        }),
+    ];
+    const edges = [];
+    for (const [index, text] of criterionTexts(fm, source.content).entries()) {
+        const criterionId = `criterion:${specId}:${String(index + 1)}`;
+        nodes.push(node({
+            id: criterionId,
+            type: 'criterion',
+            label: text,
+            source,
+            policy,
+            metadata: { specId, index: index + 1 },
+        }));
+        edges.push(edge({ from: specNodeId, to: criterionId, type: 'contains', source }));
+        for (const file of extractBacktickPaths(text, 'FILES:')) {
+            const fileId = `file:${file}`;
+            nodes.push(node({ id: fileId, type: 'file', label: file, source, policy }));
+            edges.push(edge({ from: criterionId, to: fileId, type: 'implements', source }));
+        }
+        for (const test of extractBacktickPaths(text, 'TEST:')) {
+            const testId = `test:${test}`;
+            nodes.push(node({ id: testId, type: 'test', label: test, source, policy }));
+            edges.push(edge({ from: criterionId, to: testId, type: 'tests', source }));
+        }
+    }
+    appendRiskAndDecisionNodes({ nodes, edges, specNodeId, specId, source, policy });
+    appendToolNodes({ nodes, edges, specNodeId, source, policy });
+    return { nodes: uniqueById(nodes), edges: uniqueById(edges) };
+}
+//# sourceMappingURL=spec-extractor.js.map

package/dist/engine/project-graph/extractors/validation-extractor.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectGraphExtractionResult, ProjectGraphPolicy, ProjectGraphSource } from '../../../types/project-knowledge-graph.js';
+export declare function extractValidationGraph(source: ProjectGraphSource, policy: ProjectGraphPolicy): ProjectGraphExtractionResult;
+//# sourceMappingURL=validation-extractor.d.ts.map

package/dist/engine/project-graph/extractors/validation-extractor.js

@@ -0,0 +1,36 @@
+import { hashText } from '../cache.js';
+import { redactGraphText } from '../query.js';
+function specIdFromPath(path) {
+    return path.split('/').find((part) => /^SPEC-\d+$/i.test(part));
+}
+function basename(path) {
+    return path.split('/').slice(-1)[0] ?? path;
+}
+export function extractValidationGraph(source, policy) {
+    const specId = specIdFromPath(source.path);
+    if (specId === undefined || !source.path.includes('validation')) {
+        return { nodes: [], edges: [] };
+    }
+    const validationId = `validation:${specId}:${hashText(source.path).slice(0, 10)}`;
+    const node = {
+        id: validationId,
+        type: 'validation',
+        label: redactGraphText(basename(source.path), policy),
+        source: 'validation-extractor',
+        evidence: [{ path: source.path, hash: source.hash }],
+        updatedAt: new Date().toISOString(),
+    };
+    const edge = {
+        id: `edge:${hashText(`spec:${specId}:validated_by:${validationId}`)}`,
+        from: `spec:${specId}`,
+        to: validationId,
+        type: 'validated_by',
+        source: 'validation-extractor',
+        confidence: 'medium',
+        classification: 'extracted',
+        evidence: { path: source.path, hash: source.hash },
+        updatedAt: new Date().toISOString(),
+    };
+    return { nodes: [node], edges: [edge] };
+}
+//# sourceMappingURL=validation-extractor.js.map

package/dist/engine/project-graph/index.d.ts

@@ -0,0 +1,4 @@
+export { buildProjectKnowledgeGraph } from './builder.js';
+export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, redactGraphText, } from './query.js';
+export { getProjectGraphFreshness, loadProjectGraphPolicy, projectGraphPath, projectGraphCachePath, } from './cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/project-graph/index.js

@@ -0,0 +1,4 @@
+export { buildProjectKnowledgeGraph } from './builder.js';
+export { queryProjectGraphSlice, formatProjectGraphContext, getProjectGraphFreshnessHint, redactGraphText, } from './query.js';
+export { getProjectGraphFreshness, loadProjectGraphPolicy, projectGraphPath, projectGraphCachePath, } from './cache.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/project-graph/query.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectGraphPolicy, ProjectGraphQueryInput, ProjectGraphSlice } from '../../types/project-knowledge-graph.js';
+export declare function redactGraphText(text: string, policy: ProjectGraphPolicy, maxChars?: number): string;
+export declare function queryProjectGraphSlice(input: ProjectGraphQueryInput): Promise<ProjectGraphSlice | null>;
+export declare function formatProjectGraphContext(slice: ProjectGraphSlice): Promise<string>;
+export declare function getProjectGraphFreshnessHint(args: {
+    projectId?: string;
+    projectPath: string;
+}): Promise<string | undefined>;
+//# sourceMappingURL=query.d.ts.map

package/dist/engine/project-graph/query.js

@@ -0,0 +1,161 @@
+import { hashProjectPath } from '../../storage/base-store.js';
+import { buildProjectKnowledgeGraph } from './builder.js';
+import { getProjectGraphFreshness, loadProjectGraphPolicy, readProjectGraph } from './cache.js';
+function escapeInert(text) {
+    return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function redactGraphText(text, policy, maxChars = policy.redaction.maxSnippetChars) {
+    const truncated = text.slice(0, maxChars);
+    return policy.redaction.redactPatterns.reduce((current, pattern) => {
+        const re = new RegExp(pattern, 'gi');
+        return current.replace(re, '[redacted]');
+    }, truncated);
+}
+function sanitizeLabel(label, policy) {
+    return escapeInert(redactGraphText(label, policy));
+}
+function relatedNodeIds(nodes, edges, input) {
+    const seeds = new Set();
+    for (const node of nodes) {
+        const specMatch = input.specId !== undefined &&
+            (node.id === `spec:${input.specId}` || node.metadata?.specId === input.specId);
+        const fileMatch = input.filePath !== undefined &&
+            (node.id === `file:${input.filePath}` || node.label === input.filePath);
+        const nodeMatch = input.nodeId !== undefined && node.id === input.nodeId;
+        if (specMatch || fileMatch || nodeMatch) {
+            seeds.add(node.id);
+        }
+    }
+    if (seeds.size === 0 && input.specId === undefined && input.filePath === undefined) {
+        for (const node of nodes.slice(0, 20)) {
+            seeds.add(node.id);
+        }
+    }
+    const related = new Set(seeds);
+    for (const edge of edges) {
+        if (seeds.has(edge.from)) {
+            related.add(edge.to);
+        }
+        if (seeds.has(edge.to)) {
+            related.add(edge.from);
+        }
+    }
+    return related;
+}
+function summarize(nodes) {
+    const count = (type) => nodes.filter((node) => node.type === type).length;
+    return {
+        specs: count('spec'),
+        criteria: count('criterion'),
+        files: count('file'),
+        tests: count('test'),
+        decisions: count('decision'),
+        risks: count('risk'),
+        tools: count('tool'),
+        releases: count('release'),
+    };
+}
+export async function queryProjectGraphSlice(input) {
+    const projectId = input.projectId ?? hashProjectPath(input.projectPath);
+    const policy = await loadProjectGraphPolicy();
+    if (!policy.enabled) {
+        return null;
+    }
+    let freshness = await getProjectGraphFreshness({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    if (!freshness.exists ||
+        freshness.reason === 'source_changed' ||
+        freshness.reason === 'corrupt') {
+        await buildProjectKnowledgeGraph({ projectId, projectPath: input.projectPath, policy });
+        freshness = await getProjectGraphFreshness({
+            projectId,
+            projectPath: input.projectPath,
+            policy,
+        });
+    }
+    const graph = await readProjectGraph(projectId, policy);
+    if (graph === null) {
+        return null;
+    }
+    const maxNodes = input.maxNodes ?? policy.query.maxNodes;
+    const maxEdges = input.maxEdges ?? policy.query.maxEdges;
+    const ids = relatedNodeIds(graph.nodes, graph.edges, input);
+    const nodes = graph.nodes.filter((node) => ids.has(node.id)).slice(0, maxNodes);
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = graph.edges
+        .filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to))
+        .slice(0, maxEdges);
+    return {
+        graphVersion: graph.graphVersion,
+        generatedAt: graph.generatedAt,
+        freshness,
+        nodes,
+        edges,
+        summary: summarize(nodes),
+        tokenSavings: {
+            compactNodes: nodes.length,
+            compactEdges: edges.length,
+            estimatedRawContextAvoided: Math.max(0, graph.nodes.length + graph.edges.length - nodes.length - edges.length),
+        },
+    };
+}
+function listByType(slice, type, policy) {
+    return slice.nodes
+        .filter((node) => node.type === type)
+        .map((node) => sanitizeLabel(node.label, policy))
+        .slice(0, policy.query.maxListItems);
+}
+export async function formatProjectGraphContext(slice) {
+    const policy = await loadProjectGraphPolicy();
+    const files = listByType(slice, 'file', policy);
+    const tests = listByType(slice, 'test', policy);
+    const decisions = listByType(slice, 'decision', policy);
+    const risks = listByType(slice, 'risk', policy);
+    const specs = listByType(slice, 'spec', policy);
+    const tools = listByType(slice, 'tool', policy);
+    const lines = ['## Graph Context', ''];
+    lines.push(`Freshness: ${slice.freshness.stale ? `stale (${slice.freshness.reason})` : 'fresh'}; compact slice: ${String(slice.nodes.length)} nodes / ${String(slice.edges.length)} edges.`);
+    if (files.length > 0) {
+        lines.push(`Related files: ${files.join(', ')}`);
+    }
+    if (tests.length > 0) {
+        lines.push(`Related tests: ${tests.join(', ')}`);
+    }
+    if (decisions.length > 0) {
+        lines.push(`Decisions: ${decisions.join('; ')}`);
+    }
+    if (risks.length > 0) {
+        lines.push(`Risks: ${risks.join('; ')}`);
+    }
+    if (specs.length > 1) {
+        lines.push(`Neighboring specs: ${specs.join(', ')}`);
+    }
+    if (tools.length > 0) {
+        lines.push(`Tools: ${tools.join(', ')}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export async function getProjectGraphFreshnessHint(args) {
+    const projectId = args.projectId ?? hashProjectPath(args.projectPath);
+    const policy = await loadProjectGraphPolicy();
+    if (!policy.enabled) {
+        return undefined;
+    }
+    const freshness = await getProjectGraphFreshness({
+        projectId,
+        projectPath: args.projectPath,
+        policy,
+    });
+    if (!freshness.stale) {
+        return undefined;
+    }
+    const suffix = freshness.changedSources.length > 0
+        ? `; ${String(freshness.changedSources.length)} changed source(s)`
+        : '';
+    return `project graph ${freshness.reason}${suffix}`;
+}
+//# sourceMappingURL=query.js.map

package/dist/tools/create-spec/post-creation.js

@@ -13,6 +13,7 @@ import { join, dirname } from 'node:path';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
 import { analyzeContextPreflight, buildTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../../engine/token-optimizer/index.js';
+import { queryProjectGraphSlice } from '../../engine/project-graph/index.js';
 const ASYNC_ANALYSIS_HOOK = 'create-spec-async-analysis';
 export function getAsyncAnalysisPath(projectPath, specId) {
     const projectId = hashProjectPath(projectPath);
@@ -24,10 +25,21 @@ export async function buildInitialTokenWasteMetadata(specId, projectPath, descri
         if (!policy.enabled) {
             return null;
         }
+        const graphSlice = await queryProjectGraphSlice({ projectPath, specId }).catch(() => null);
+        const graphCandidates = graphSlice?.nodes
+            .filter((node) => node.type === 'file' || node.type === 'test')
+            .slice(0, 12)
+            .map((node) => ({
+            path: node.label,
+            reason: 'Related by Project Knowledge Graph compact slice.',
+        })) ?? [];
         const context = analyzeContextPreflight({
             action: 'create_spec',
             policy,
-            candidates: [{ path: 'planu/specs', reason: 'New spec workspace metadata.' }],
+            candidates: [
+                ...graphCandidates,
+                { path: 'planu/specs', reason: 'New spec workspace metadata.' },
+            ],
             spec: { id: specId },
         });
         const tools = recommendRelevantTools({

package/dist/tools/package-handoff.js

@@ -5,6 +5,7 @@ import { packageHandoff } from '../engine/handoff-packager.js';
 import { detectParadigms } from '../engine/paradigm-detector.js';
 import { analyzeContextPreflight, buildTokenWasteReport, formatTokenWasteReport, loadTokenWastePolicy, recommendRelevantTools, toolsFromPolicyGroups, } from '../engine/token-optimizer/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
+import { formatProjectGraphContext, queryProjectGraphSlice, } from '../engine/project-graph/index.js';
 // ── Formatting helpers ───────────────────────────────────────────────────────
 function formatHandoff(pkg) {
     const lines = [];
@@ -176,6 +177,25 @@ async function buildHandoffTokenWasteReport(pkg, knowledge, spec) {
         return null;
     }
 }
+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;
+    }
+}
 // ── Handler ──────────────────────────────────────────────────────────────────
 export async function handlePackageHandoff(args) {
     const { projectId, specId } = args;
@@ -231,9 +251,17 @@ export async function handlePackageHandoff(args) {
         constraints: paradigmConstraints,
     };
     const tokenWasteReport = await buildHandoffTokenWasteReport(pkgWithScore, knowledge, spec);
-    const formatted = tokenWasteReport !== null
-        ? `${formatHandoff(pkgWithScore)}\n${formatTokenWasteReport(tokenWasteReport)}`
+    const graphContext = await buildGraphContextSection({
+        projectId,
+        projectPath: knowledge.projectPath,
+        specId,
+    });
+    const handoffText = graphContext !== null
+        ? `${formatHandoff(pkgWithScore)}\n${graphContext.text}`
         : formatHandoff(pkgWithScore);
+    const formatted = tokenWasteReport !== null
+        ? `${handoffText}\n${formatTokenWasteReport(tokenWasteReport)}`
+        : handoffText;
     void appendTransitionEvent({
         projectId,
         specId,
@@ -255,6 +283,7 @@ export async function handlePackageHandoff(args) {
             handoffPath: pkgWithScore.handoffPath,
             contextHash: pkgWithScore.contextHash,
             ...(tokenWasteReport !== null ? { tokenWaste: tokenWasteReport } : {}),
+            ...(graphContext !== null ? { graphContext: graphContext.structured } : {}),
         },
     };
 }

package/dist/tools/schemas/index.d.ts

@@ -13,6 +13,7 @@ export { SecurityReportTimeRangeEnum, SecurityReportFormatEnum } from './runtime
 export { WorkerStatusInputSchema, ConfigureWorkersInputSchema } from './workers-schema.js';
 export { TokenUsagePeriodEnum, TokenUsageGroupByEnum } from './token-optimization.js';
 export { TokenIntelligencePeriodEnum, TokenIntelligenceGroupByEnum, TokenIntelligenceViewEnum, } from './token-intelligence.js';
+export { ProjectGraphActionEnum, ProjectGraphQueryKindEnum } from './project-graph.js';
 export { ConfigureLLMProvidersActionEnum, LoadBalancingStrategyEnum, } from './llm-provider-schemas.js';
 export { PluginActionEnum } from './plugins-schemas.js';
 export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, LicenseStatusOutputSchema, } from './output-schemas.js';

package/dist/tools/schemas/index.js

@@ -14,6 +14,7 @@ export { SecurityReportTimeRangeEnum, SecurityReportFormatEnum } from './runtime
 export { WorkerStatusInputSchema, ConfigureWorkersInputSchema } from './workers-schema.js';
 export { TokenUsagePeriodEnum, TokenUsageGroupByEnum } from './token-optimization.js';
 export { TokenIntelligencePeriodEnum, TokenIntelligenceGroupByEnum, TokenIntelligenceViewEnum, } from './token-intelligence.js';
+export { ProjectGraphActionEnum, ProjectGraphQueryKindEnum } from './project-graph.js';
 export { ConfigureLLMProvidersActionEnum, LoadBalancingStrategyEnum, } from './llm-provider-schemas.js';
 export { PluginActionEnum } from './plugins-schemas.js';
 export { ListSpecsOutputSchema, EstimateOutputSchema, ValidateOutputSchema, CheckReadinessOutputSchema, LicenseStatusOutputSchema, } from './output-schemas.js';

package/dist/tools/schemas/project-graph.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const ProjectGraphActionEnum: z.ZodEnum<{
+    status: "status";
+    query: "query";
+    explain: "explain";
+    rebuild: "rebuild";
+}>;
+export declare const ProjectGraphQueryKindEnum: z.ZodEnum<{
+    release: "release";
+    decision: "decision";
+    spec: "spec";
+    file: "file";
+    risk: "risk";
+    tool: "tool";
+    test: "test";
+    criterion: "criterion";
+}>;
+//# sourceMappingURL=project-graph.d.ts.map

package/dist/tools/schemas/project-graph.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const ProjectGraphActionEnum = z
+    .enum(['status', 'query', 'explain', 'rebuild'])
+    .describe('Project graph inspection action.');
+export const ProjectGraphQueryKindEnum = z
+    .enum(['spec', 'file', 'criterion', 'test', 'release', 'decision', 'risk', 'tool'])
+    .describe('Graph entity kind to query.');
+//# sourceMappingURL=project-graph.js.map

package/dist/tools/schemas/token-intelligence.d.ts

@@ -12,6 +12,7 @@ export declare const TokenIntelligenceGroupByEnum: z.ZodEnum<{
     day: "day";
 }>;
 export declare const TokenIntelligenceViewEnum: z.ZodEnum<{
+    graph: "graph";
     summary: "summary";
     budget: "budget";
     detailed: "detailed";

package/dist/tools/schemas/token-intelligence.js

@@ -9,11 +9,12 @@ export const TokenIntelligenceGroupByEnum = z
     .describe('Group results by: tool (per MCP tool name), model (per AI model), ' +
     'spec (per spec ID), day (daily breakdown)');
 export const TokenIntelligenceViewEnum = z
-    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends', 'autopilot'])
+    .enum(['summary', 'detailed', 'budget', 'reconciliation', 'trends', 'autopilot', 'graph'])
     .describe('Dashboard view: summary (high-level overview with top consumers), ' +
     'detailed (full per-tool and per-model breakdown), ' +
     'budget (spending vs monthly limits with projections), ' +
     'reconciliation (estimated vs actual cost accuracy per spec), ' +
     'trends (usage patterns over time, week-over-week changes, and anomaly alerts), ' +
-    'autopilot (policy-driven recommendations to reduce wasted context, output, and tool usage)');
+    'autopilot (policy-driven recommendations to reduce wasted context, output, and tool usage), ' +
+    'graph (project knowledge graph freshness, compact context savings, and stale graph risks)');
 //# sourceMappingURL=token-intelligence.js.map

package/dist/tools/status-handler.js

@@ -18,6 +18,7 @@ import { readPlanuConfig } from '../engine/planu-config-writer.js';
 import { computePlanuDriftScore } from '../engine/dashboard/drift-score.js';
 import { findStaleBranches, findStaleWorktrees, findStaleStashes, } from '../engine/housekeeping/index.js';
 import { loadTokenWastePolicy } from '../engine/token-optimizer/index.js';
+import { getProjectGraphFreshnessHint } from '../engine/project-graph/index.js';
 // SPEC-1011 Bug G: fire-and-forget status.json reconciliation
 import { reconcileStatusFromDisk } from '../engine/status-reconciler/index.js';
 const execFile = promisify(execFileCb);
@@ -128,7 +129,7 @@ function buildSuggestion(snapshot) {
 // Output builder
 // ---------------------------------------------------------------------------
 function buildOutput(params) {
-    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip, tokenWasteHint, } = params;
+    const { snapshot, git, ci, slaBreaches, workMode, updateBanner, autoCompleted, sessionTip, tokenWasteHint, graphFreshnessHint, } = params;
     const lines = ['Planu Status', '━━━━━━━━━━━━━━━'];
     if (snapshot.active !== null) {
         const title = snapshot.active.title.slice(0, 40);
@@ -166,6 +167,9 @@ function buildOutput(params) {
     if (tokenWasteHint !== undefined) {
         lines.push(`TOKEN WASTE ${tokenWasteHint}`);
     }
+    if (graphFreshnessHint !== undefined) {
+        lines.push(`GRAPH     ${graphFreshnessHint}`);
+    }
     lines.push(`SUGGEST   ${buildSuggestion(snapshot)}`);
     if (workMode !== undefined) {
         lines.push(`WORK MODE ${workMode}`);
@@ -210,7 +214,7 @@ export async function handlePlanStatus(args) {
             /* best-effort */
         });
     }
-    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup, tokenWastePolicy,] = await Promise.all([
+    const [snapshot, git, ci, slaBreaches, planuConfig, autoCompleted, sessionState, driftScore, pendingCleanup, tokenWastePolicy, graphFreshnessHint,] = await Promise.all([
         getStatusSpecSnapshot(projectId),
         getGitState(args.projectPath),
         getCiState(args.projectPath),
@@ -244,6 +248,7 @@ export async function handlePlanStatus(args) {
         loadTokenWastePolicy(args.projectPath)
             .then((loaded) => loaded.policy)
             .catch(() => null),
+        getProjectGraphFreshnessHint({ projectId, projectPath: args.projectPath }).catch(() => undefined),
     ]);
     // SPEC-1012: Detect stale release status (best-effort, non-blocking)
     let staleStatusWarnings = [];
@@ -277,6 +282,7 @@ export async function handlePlanStatus(args) {
         autoCompleted,
         sessionTip,
         tokenWasteHint,
+        graphFreshnessHint,
     });
     // SPEC-256: Always show /btw hint as educational tip (no context percent available from MCP layer)
     const DEMO_CONTEXT_PERCENT = 65;
@@ -301,6 +307,7 @@ export async function handlePlanStatus(args) {
             ...(autoCompleted.length > 0 ? { autoCompleted } : {}),
             ...(sessionTip !== undefined ? { sessionTip } : {}),
             ...(tokenWasteHint !== undefined ? { tokenWasteHint } : {}),
+            ...(graphFreshnessHint !== undefined ? { graphFreshnessHint } : {}),
             ...(btwHint !== undefined ? { btw_hint: btwHint } : {}),
             ...(updateBanner !== undefined ? { update_banner: updateBanner } : {}),
             // SPEC-751: pending cleanup counters