@planu/cli 4.8.0 → 4.9.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [4.9.0] - 2026-06-30
+
+### Features
+- feat(SPEC-1099): add structural memory layer
+
+### Chores
+- chore(planu): clear released pending specs
+
+
 ## [4.8.0] - 2026-06-24
 
 ### Features

package/dist/config/project-knowledge-graph.json

@@ -18,7 +18,14 @@
     "tool",
     "handoff",
     "validation",
-    "commit"
+    "commit",
+    "adr",
+    "validation_evidence",
+    "release_risk",
+    "architecture_risk",
+    "drift",
+    "contract",
+    "git_change"
   ],
   "edgeTypes": [
     "contains",
@@ -31,7 +38,13 @@
     "has_risk",
     "uses_tool",
     "mentions",
-    "neighbors"
+    "neighbors",
+    "affects",
+    "covers",
+    "depends_on",
+    "has_evidence",
+    "has_status",
+    "has_contract"
   ],
   "classifications": ["extracted", "inferred", "ambiguous"],
   "confidenceLabels": ["high", "medium", "low"],
@@ -52,6 +65,61 @@
       "(api[_-]?key|token|secret|password)\\s*[:=]\\s*[^\\s,;]+"
     ]
   },
+  "structuralMemory": {
+    "schemaVersion": "1.0.0",
+    "nodeTypes": [
+      "spec",
+      "criterion",
+      "file",
+      "test",
+      "adr",
+      "decision",
+      "validation_evidence",
+      "validation",
+      "release",
+      "release_risk",
+      "architecture_risk",
+      "drift",
+      "risk",
+      "tool",
+      "contract",
+      "git_change"
+    ],
+    "edgeTypes": [
+      "contains",
+      "references",
+      "implements",
+      "tests",
+      "validated_by",
+      "decides",
+      "has_risk",
+      "uses_tool",
+      "affects",
+      "covers",
+      "depends_on",
+      "has_evidence",
+      "has_status",
+      "has_contract"
+    ],
+    "response": {
+      "defaultLimit": 60,
+      "maxLimit": 200
+    },
+    "propertySchemas": {
+      "spec": ["specId", "status"],
+      "criterion": ["specId", "index"],
+      "file": ["path"],
+      "test": ["path"],
+      "decision": ["specId", "decisionId"],
+      "adr": ["specId", "decisionId"],
+      "validation_evidence": ["specId", "kind", "status"],
+      "release_risk": ["specId", "severity"],
+      "architecture_risk": ["path", "ruleId", "severity"],
+      "drift": ["specId", "status", "severity"],
+      "contract": ["kind", "passed"],
+      "git_change": ["path", "status"]
+    }
+  },
   "toolNamePatterns": [
     "package_handoff",
     "validate",

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

@@ -1,6 +1,7 @@
 import { collectProjectGraphSources, diffSourceHashes, hashText, loadProjectGraphPolicy, projectGraphCachePath, projectGraphPath, readProjectGraph, readProjectGraphSourceHashes, writeProjectGraph, writeProjectGraphSourceHashes, } from './cache.js';
 import { extractGitGraph, extractReleaseGraph } from './extractors/git-extractor.js';
 import { extractHandoffGraph } from './extractors/handoff-extractor.js';
+import { extractDecisionStoreGraph } from './extractors/decision-store-extractor.js';
 import { extractSpecGraph } from './extractors/spec-extractor.js';
 import { extractValidationGraph } from './extractors/validation-extractor.js';
 function uniqueNodes(nodes) {
@@ -11,10 +12,7 @@ function uniqueEdges(edges) {
 }
 function validateAgainstPolicy(result, policy) {
     const nodes = result.nodes.filter((node) => policy.nodeTypes.includes(node.type));
-    const nodeIds = new Set(nodes.map((node) => node.id));
-    const edges = result.edges.filter((edge) => nodeIds.has(edge.from) &&
-        nodeIds.has(edge.to) &&
-        policy.edgeTypes.includes(edge.type) &&
+    const edges = result.edges.filter((edge) => policy.edgeTypes.includes(edge.type) &&
         policy.confidenceLabels.includes(edge.confidence) &&
         policy.classifications.includes(edge.classification));
     return { nodes, edges };
@@ -50,6 +48,9 @@ export async function buildProjectKnowledgeGraph(args) {
         else if (source.kind === 'handoff') {
             extracted.push(extractHandoffGraph(source, policy));
         }
+        else if (source.kind === 'decisions') {
+            extracted.push(extractDecisionStoreGraph(source, policy));
+        }
         else if (source.kind === 'release-events') {
             extracted.push(extractReleaseGraph(source, policy));
         }
@@ -57,7 +58,10 @@ export async function buildProjectKnowledgeGraph(args) {
     extracted.push(await extractGitGraph({ projectPath: args.projectPath, policy }));
     const validated = extracted.map((result) => validateAgainstPolicy(result, policy));
     const nodes = uniqueNodes(validated.flatMap((result) => result.nodes));
-    const edges = uniqueEdges(validated.flatMap((result) => result.edges));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = uniqueEdges(validated
+        .flatMap((result) => result.edges)
+        .filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to)));
     const sourceHashes = diff.next;
     const sourceHash = hashText(JSON.stringify(sourceHashes));
     const graph = {

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

@@ -83,6 +83,7 @@ export async function collectProjectGraphSources(args) {
     const specFiles = await collectFiles(join(projectRoot, 'planu', 'specs'), (path) => path.endsWith('/spec.md'));
     const handoffFiles = await collectFiles(join(dataRoot, 'handoffs'), (path) => /\.(json|md)$/.test(path));
     const validationFiles = handoffFiles.filter((path) => path.includes('validation'));
+    const decisions = join(dataRoot, 'decisions.json');
     const transitionLog = join(dataRoot, 'transition-log.jsonl');
     const releaseEvents = join(dataRoot, '..', '..', 'release-events.jsonl');
     const raw = [
@@ -99,6 +100,9 @@ export async function collectProjectGraphSources(args) {
         ...((await fileExists(transitionLog))
             ? [{ id: 'transition-log', kind: 'transition-log', path: transitionLog }]
             : []),
+        ...((await fileExists(decisions))
+            ? [{ id: 'decisions', kind: 'decisions', path: decisions }]
+            : []),
         ...((await fileExists(releaseEvents))
             ? [{ id: 'release-events', kind: 'release-events', path: releaseEvents }]
             : []),

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

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

package/dist/engine/project-graph/extractors/decision-store-extractor.js

@@ -0,0 +1,57 @@
+import { safeJsonParse } from '../../../storage/base-store.js';
+import { hashText } from '../cache.js';
+import { redactGraphText } from '../query.js';
+function isDecision(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.id === 'string' &&
+        typeof value.what === 'string' &&
+        typeof value.why === 'string');
+}
+function decisionsFromSource(source) {
+    const parsed = safeJsonParse(source.content, { decisions: [] });
+    return Array.isArray(parsed.decisions) ? parsed.decisions.filter(isDecision) : [];
+}
+function node(args) {
+    return {
+        id: `decision:${args.decision.id}`,
+        type: 'decision',
+        label: redactGraphText(`${args.decision.what}: ${args.decision.why}`, args.policy),
+        source: 'decision-store-extractor',
+        evidence: [{ path: args.source.path, hash: args.source.hash }],
+        metadata: {
+            decisionId: args.decision.id,
+            specId: args.decision.specId ?? null,
+            category: args.decision.category,
+            status: args.decision.status,
+            decidedBy: args.decision.decidedBy,
+        },
+        updatedAt: args.decision.date,
+    };
+}
+function edge(decision, source) {
+    if (!decision.specId) {
+        return null;
+    }
+    const decisionId = `decision:${decision.id}`;
+    return {
+        id: `edge:${hashText(`spec:${decision.specId}:decides:${decisionId}`)}`,
+        from: `spec:${decision.specId}`,
+        to: decisionId,
+        type: 'decides',
+        source: 'decision-store-extractor',
+        confidence: 'high',
+        classification: 'extracted',
+        evidence: { path: source.path, hash: source.hash },
+        updatedAt: decision.date,
+    };
+}
+export function extractDecisionStoreGraph(source, policy) {
+    const decisions = decisionsFromSource(source);
+    const nodes = decisions.map((decision) => node({ decision, source, policy }));
+    const edges = decisions
+        .map((decision) => edge(decision, source))
+        .filter((item) => item !== null);
+    return { nodes, edges };
+}
+//# sourceMappingURL=decision-store-extractor.js.map

package/dist/engine/structural-memory/architecture-snapshot.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureSnapshotInput, ArchitectureSnapshotResult } from './contracts.js';
+export declare function getArchitectureSnapshot(input: ArchitectureSnapshotInput): Promise<ArchitectureSnapshotResult>;
+//# sourceMappingURL=architecture-snapshot.d.ts.map

package/dist/engine/structural-memory/architecture-snapshot.js

@@ -0,0 +1,132 @@
+import { clampLimit, loadFreshGraph, nextActionForFreshness, pagination, resolveProjectId, safeRelativeProjectPath, structuralPolicy, } from './helpers.js';
+function aspects(input) {
+    const requested = input.aspects ?? ['all'];
+    if (requested.includes('all')) {
+        return new Set(['packages', 'hotspots', 'boundaries', 'releaseRisks', 'tests', 'decisions']);
+    }
+    return new Set(requested);
+}
+function packageName(path) {
+    const parts = path.split('/');
+    return parts.length > 1 ? parts.slice(0, 2).join('/') : (parts[0] ?? path);
+}
+function packageAspect(nodes, limit) {
+    const counts = new Map();
+    for (const node of nodes.filter((item) => item.type === 'file' || item.type === 'test')) {
+        counts.set(packageName(node.label), (counts.get(packageName(node.label)) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([name, fileCount]) => ({ name, fileCount }))
+        .sort((a, b) => b.fileCount - a.fileCount)
+        .slice(0, limit);
+}
+function hotspotAspect(nodes, edges, limit) {
+    const degree = new Map();
+    for (const edge of edges) {
+        degree.set(edge.from, (degree.get(edge.from) ?? 0) + 1);
+        degree.set(edge.to, (degree.get(edge.to) ?? 0) + 1);
+    }
+    return nodes
+        .map((node) => ({
+        id: node.id,
+        label: node.label,
+        type: node.type,
+        degree: degree.get(node.id) ?? 0,
+    }))
+        .filter((node) => node.degree > 0)
+        .sort((a, b) => b.degree - a.degree)
+        .slice(0, limit);
+}
+function boundaryAspect(edges, limit) {
+    return edges
+        .filter((edge) => edge.type === 'references' || edge.type === 'implements' || edge.type === 'tests')
+        .map((edge) => ({ from: edge.from, to: edge.to, type: edge.type }))
+        .slice(0, limit);
+}
+function simpleNodes(nodes, types, limit) {
+    return nodes
+        .filter((node) => types.includes(node.type))
+        .map((node) => ({ id: node.id, label: node.label, type: node.type }))
+        .slice(0, limit);
+}
+function snapshotAspects(args) {
+    const result = {};
+    if (args.requested.has('packages')) {
+        result.packages = packageAspect(args.nodes, args.limit);
+    }
+    if (args.requested.has('hotspots')) {
+        result.hotspots = hotspotAspect(args.nodes, args.edges, args.limit);
+    }
+    if (args.requested.has('boundaries')) {
+        result.boundaries = boundaryAspect(args.edges, args.limit);
+    }
+    if (args.requested.has('releaseRisks')) {
+        result.releaseRisks = simpleNodes(args.nodes, ['risk', 'release_risk', 'architecture_risk'], args.limit).map((node) => ({ id: node.id, label: node.label, type: node.type ?? 'risk' }));
+    }
+    if (args.requested.has('tests')) {
+        result.tests = simpleNodes(args.nodes, ['test'], args.limit).map(({ id, label }) => ({
+            id,
+            label,
+        }));
+    }
+    if (args.requested.has('decisions')) {
+        result.decisions = simpleNodes(args.nodes, ['decision', 'adr'], args.limit).map(({ id, label }) => ({ id, label }));
+    }
+    return result;
+}
+export async function getArchitectureSnapshot(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const limit = clampLimit(input.limit, policy);
+    const { graph, freshness } = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const prefix = input.pathPrefix === undefined
+        ? undefined
+        : safeRelativeProjectPath(input.projectPath, input.pathPrefix);
+    if (input.pathPrefix !== undefined && prefix === null) {
+        const page = pagination(0, limit, 0);
+        return {
+            freshness,
+            pagination: page,
+            ...page,
+            nextAction: {
+                type: 'inspect_evidence',
+                message: 'Rejecting unsafe pathPrefix filter; pass a project-relative path inside the repo.',
+            },
+            aspects: {},
+        };
+    }
+    const page = pagination(graph?.nodes.length ?? 0, limit, 0);
+    if (graph === null) {
+        return {
+            freshness,
+            pagination: page,
+            ...page,
+            nextAction: nextActionForFreshness(freshness, true),
+            aspects: {},
+        };
+    }
+    const scopedNodes = graph.nodes.filter((node) => {
+        if (prefix === undefined) {
+            return true;
+        }
+        return node.label === prefix || node.label.startsWith(`${prefix}/`);
+    });
+    const scopedIds = new Set(scopedNodes.map((node) => node.id));
+    const scopedEdges = graph.edges.filter((edge) => scopedIds.has(edge.from) && scopedIds.has(edge.to));
+    const requested = aspects(input);
+    const result = snapshotAspects({ nodes: scopedNodes, edges: scopedEdges, requested, limit });
+    const scopedPage = pagination(scopedNodes.length, limit, 0);
+    return {
+        graphVersion: graph.graphVersion,
+        freshness,
+        pagination: scopedPage,
+        ...scopedPage,
+        nextAction: nextActionForFreshness(freshness, scopedNodes.length === 0),
+        aspects: result,
+    };
+}
+//# sourceMappingURL=architecture-snapshot.js.map

package/dist/engine/structural-memory/artifact-policy.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectGraphPolicy } from '../../types/project-knowledge-graph.js';
+import type { StructuralMemoryArtifactPolicy } from '../../types/structural-memory.js';
+export declare function createStructuralMemoryArtifactPolicy(projectId: string, policy: ProjectGraphPolicy): StructuralMemoryArtifactPolicy;
+export declare function isStructuralMemoryArtifactPathAllowed(path: string): boolean;
+//# sourceMappingURL=artifact-policy.d.ts.map

package/dist/engine/structural-memory/artifact-policy.js

@@ -0,0 +1,17 @@
+import { projectGraphDir, projectGraphPath } from '../project-graph/cache.js';
+export function createStructuralMemoryArtifactPolicy(projectId, policy) {
+    const artifactRoot = projectGraphDir(projectId, policy);
+    return {
+        artifactRoot,
+        graphPath: projectGraphPath(projectId, policy),
+        projectDataDirectory: artifactRoot.split('/project-graph')[0] ?? artifactRoot,
+        forbiddenPathFragment: 'planu/specs',
+        specDirectoryPolicy: 'spec.md-only',
+        evidenceAndGraphArtifactsRemainOutsideSpecs: true,
+    };
+}
+export function isStructuralMemoryArtifactPathAllowed(path) {
+    const normalized = path.replace(/\\/g, '/');
+    return !normalized.includes('/planu/specs/') && !normalized.endsWith('/planu/specs');
+}
+//# sourceMappingURL=artifact-policy.js.map

package/dist/engine/structural-memory/change-impact.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralChangeImpactInput, StructuralChangeImpactResult } from './contracts.js';
+export declare function detectStructuralChangeImpact(input: StructuralChangeImpactInput): Promise<StructuralChangeImpactResult>;
+//# sourceMappingURL=change-impact.d.ts.map

package/dist/engine/structural-memory/change-impact.js

@@ -0,0 +1,159 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { clampLimit, loadFreshGraph, nextActionForFreshness, pagination, resolveProjectId, safeRelativeProjectPath, structuralPolicy, } from './helpers.js';
+const execFile = promisify(execFileCb);
+function safeGitRef(ref) {
+    return (/^[A-Za-z0-9][A-Za-z0-9._/@{}:+-]{0,200}$/.test(ref) &&
+        !ref.includes('..') &&
+        !ref.startsWith('-'));
+}
+function statusFromCode(code) {
+    if (code.includes('A')) {
+        return 'added';
+    }
+    if (code.includes('D')) {
+        return 'deleted';
+    }
+    if (code.includes('R')) {
+        return 'renamed';
+    }
+    if (code.includes('?')) {
+        return 'untracked';
+    }
+    if (code.trim().length > 0) {
+        return 'modified';
+    }
+    return 'unknown';
+}
+function parseNameStatus(stdout, projectPath) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .flatMap((line) => {
+        const [status, ...paths] = line.split(/\s+/);
+        const path = paths.at(-1);
+        if (!status || !path) {
+            return [];
+        }
+        const safePath = safeRelativeProjectPath(projectPath, path);
+        return safePath === null ? [] : [{ path: safePath, status: statusFromCode(status) }];
+    });
+}
+function parsePorcelain(stdout, projectPath, includeUntracked) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .flatMap((line) => {
+        const code = line.slice(0, 2);
+        if (!includeUntracked && code === '??') {
+            return [];
+        }
+        const rawPath = line.slice(3).split(' -> ').at(-1);
+        if (!rawPath) {
+            return [];
+        }
+        const safePath = safeRelativeProjectPath(projectPath, rawPath);
+        return safePath === null ? [] : [{ path: safePath, status: statusFromCode(code) }];
+    });
+}
+async function gitChangedFiles(input) {
+    if (input.changedFiles !== undefined) {
+        return input.changedFiles.flatMap((path) => {
+            const safePath = safeRelativeProjectPath(input.projectPath, path);
+            return safePath === null ? [] : [{ path: safePath, status: 'unknown' }];
+        });
+    }
+    if (input.baseRef !== undefined) {
+        if (!safeGitRef(input.baseRef)) {
+            throw new Error('Unsafe git baseRef for structural change impact.');
+        }
+        const { stdout } = await execFile('git', ['diff', '--name-status', input.baseRef, '--'], {
+            cwd: input.projectPath,
+            maxBuffer: 1024 * 1024,
+        });
+        return parseNameStatus(stdout, input.projectPath);
+    }
+    const { stdout } = await execFile('git', ['status', '--porcelain'], {
+        cwd: input.projectPath,
+        maxBuffer: 1024 * 1024,
+    });
+    return parsePorcelain(stdout, input.projectPath, input.includeUntracked ?? true);
+}
+function uniqueNodes(nodes) {
+    return [...new Map(nodes.map((node) => [node.id, node])).values()];
+}
+function collectAffected(graphNodes, graphEdges, changedFiles) {
+    const changed = new Set(changedFiles.map((file) => file.path));
+    const fileNodeIds = new Set(graphNodes
+        .filter((node) => node.type === 'file' && changed.has(node.label))
+        .map((node) => node.id));
+    const affectedIds = new Set(fileNodeIds);
+    for (let depth = 0; depth < 3; depth += 1) {
+        for (const edge of graphEdges) {
+            if (affectedIds.has(edge.from)) {
+                affectedIds.add(edge.to);
+            }
+            if (affectedIds.has(edge.to)) {
+                affectedIds.add(edge.from);
+            }
+        }
+    }
+    const nodes = graphNodes.filter((node) => affectedIds.has(node.id));
+    const ids = new Set(nodes.map((node) => node.id));
+    const edges = graphEdges.filter((edge) => ids.has(edge.from) && ids.has(edge.to));
+    return { nodes, edges };
+}
+export async function detectStructuralChangeImpact(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const limit = clampLimit(input.limit, policy);
+    const changedFiles = await gitChangedFiles(input);
+    const { graph, freshness } = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const page = pagination(changedFiles.length, limit, 0);
+    if (graph === null) {
+        return {
+            freshness,
+            pagination: page,
+            ...page,
+            nextAction: nextActionForFreshness(freshness, true),
+            changedFiles: changedFiles.slice(0, limit),
+            affected: {
+                specs: [],
+                criteria: [],
+                tests: [],
+                decisions: [],
+                evidence: [],
+                risks: [],
+                releaseRisk: [],
+            },
+            affectedEdges: [],
+        };
+    }
+    const affected = collectAffected(graph.nodes, graph.edges, changedFiles);
+    const byType = (types) => uniqueNodes(affected.nodes.filter((node) => types.includes(node.type))).slice(0, limit);
+    return {
+        graphVersion: graph.graphVersion,
+        freshness,
+        pagination: page,
+        ...page,
+        nextAction: nextActionForFreshness(freshness, affected.nodes.length === 0),
+        changedFiles: changedFiles.slice(0, limit),
+        affected: {
+            specs: byType(['spec']),
+            criteria: byType(['criterion']),
+            tests: byType(['test']),
+            decisions: byType(['decision', 'adr']),
+            evidence: byType(['handoff', 'validation', 'validation_evidence', 'contract']),
+            risks: byType(['risk', 'architecture_risk', 'drift']),
+            releaseRisk: byType(['release', 'release_risk']),
+        },
+        affectedEdges: affected.edges.slice(0, policy.query.maxEdges),
+    };
+}
+//# sourceMappingURL=change-impact.js.map

package/dist/engine/structural-memory/contracts.d.ts

@@ -0,0 +1,2 @@
+export type * from '../../types/structural-memory.js';
+//# sourceMappingURL=contracts.d.ts.map

package/dist/engine/structural-memory/contracts.js

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

package/dist/engine/structural-memory/helpers.d.ts

@@ -0,0 +1,28 @@
+import type { ProjectGraphEdge, ProjectGraphFreshness, ProjectGraphNode, ProjectGraphPolicy } from '../../types/project-knowledge-graph.js';
+import { readProjectGraph } from '../project-graph/cache.js';
+import type { StructuralMemoryFreshness, StructuralMemoryNextAction, StructuralMemoryPagination } from './contracts.js';
+export declare function resolveProjectId(input: {
+    projectId?: string;
+    projectPath: string;
+}): string;
+export declare function freshnessStatus(freshness: ProjectGraphFreshness): StructuralMemoryFreshness;
+export declare function nextActionForFreshness(freshness: StructuralMemoryFreshness, empty?: boolean): StructuralMemoryNextAction;
+export declare function pagination(total: number, limit: number, offset: number): StructuralMemoryPagination;
+export declare function clampLimit(limit: number | undefined, policy: ProjectGraphPolicy): number;
+export declare function safeRelativeProjectPath(projectPath: string, candidate: string): string | null;
+export declare function loadFreshGraph(args: {
+    projectId: string;
+    projectPath: string;
+    policy: ProjectGraphPolicy;
+}): Promise<{
+    graph: Awaited<ReturnType<typeof readProjectGraph>>;
+    freshness: StructuralMemoryFreshness;
+}>;
+export declare function summarizeNodes(nodes: ProjectGraphNode[]): Record<string, number>;
+export declare function relatedNodeIds(nodes: ProjectGraphNode[], edges: ProjectGraphEdge[], input: {
+    specId?: string;
+    filePath?: string;
+    nodeId?: string;
+}): Set<string>;
+export declare function structuralPolicy(): Promise<ProjectGraphPolicy>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/engine/structural-memory/helpers.js

@@ -0,0 +1,122 @@
+import { isAbsolute, normalize, relative, resolve } from 'node:path';
+import { hashProjectPath } from '../../storage/base-store.js';
+import { getProjectGraphFreshness, loadProjectGraphPolicy, readProjectGraph, } from '../project-graph/cache.js';
+export function resolveProjectId(input) {
+    return input.projectId ?? hashProjectPath(input.projectPath);
+}
+export function freshnessStatus(freshness) {
+    const status = freshness.reason === 'missing'
+        ? 'missing'
+        : freshness.reason === 'corrupt'
+            ? 'corrupt'
+            : freshness.stale
+                ? 'stale'
+                : 'fresh';
+    return {
+        status,
+        graphPath: freshness.graphPath,
+        generatedAt: freshness.generatedAt,
+        changedSources: freshness.changedSources,
+        reason: freshness.reason,
+    };
+}
+export function nextActionForFreshness(freshness, empty = false) {
+    if (freshness.status === 'missing' || freshness.status === 'corrupt') {
+        return {
+            type: 'rebuild_graph',
+            message: 'Rebuild the project graph before trusting structural memory results.',
+        };
+    }
+    if (freshness.status === 'stale' || freshness.status === 'partial') {
+        return {
+            type: 'run_validate',
+            message: 'Run validation or rebuild graph context before using this result as gate evidence.',
+        };
+    }
+    if (empty) {
+        return {
+            type: 'broaden_filters',
+            message: 'No structural memory nodes matched; broaden filters or inspect evidence coverage.',
+        };
+    }
+    return { type: 'none', message: 'Structural memory result is ready to use.' };
+}
+export function pagination(total, limit, offset) {
+    const hasMore = offset + limit < total;
+    return {
+        total,
+        limit,
+        offset,
+        hasMore,
+        has_more: hasMore,
+        truncated: hasMore,
+    };
+}
+export function clampLimit(limit, policy) {
+    const defaultLimit = policy.structuralMemory?.response.defaultLimit ?? policy.query.maxNodes;
+    const maxLimit = policy.structuralMemory?.response.maxLimit ?? policy.query.maxNodes;
+    return Math.max(1, Math.min(limit ?? defaultLimit, maxLimit));
+}
+export function safeRelativeProjectPath(projectPath, candidate) {
+    if (candidate.trim().length === 0 || isAbsolute(candidate) || candidate.includes('\0')) {
+        return null;
+    }
+    const normalized = normalize(candidate).replace(/\\/g, '/');
+    if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+        return null;
+    }
+    const root = resolve(projectPath);
+    const absolute = resolve(root, normalized);
+    const rel = relative(root, absolute).replace(/\\/g, '/');
+    if (rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
+        return null;
+    }
+    return rel;
+}
+export async function loadFreshGraph(args) {
+    const rawFreshness = await getProjectGraphFreshness(args);
+    return {
+        graph: await readProjectGraph(args.projectId, args.policy),
+        freshness: freshnessStatus(rawFreshness),
+    };
+}
+export function summarizeNodes(nodes) {
+    return nodes.reduce((acc, node) => {
+        return { ...acc, [node.type]: (acc[node.type] ?? 0) + 1 };
+    }, {});
+}
+export 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 &&
+        input.nodeId === undefined) {
+        for (const node of nodes) {
+            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;
+}
+export async function structuralPolicy() {
+    return loadProjectGraphPolicy();
+}
+//# sourceMappingURL=helpers.js.map

package/dist/engine/structural-memory/index.d.ts

@@ -0,0 +1,7 @@
+export type * from './contracts.js';
+export { queryStructuralMemory } from './query.js';
+export { detectStructuralChangeImpact } from './change-impact.js';
+export { getArchitectureSnapshot } from './architecture-snapshot.js';
+export { getStructuralMemoryStatus } from './status.js';
+export { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/structural-memory/index.js

@@ -0,0 +1,6 @@
+export { queryStructuralMemory } from './query.js';
+export { detectStructuralChangeImpact } from './change-impact.js';
+export { getArchitectureSnapshot } from './architecture-snapshot.js';
+export { getStructuralMemoryStatus } from './status.js';
+export { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/structural-memory/query.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralMemoryQueryInput, StructuralMemoryQueryResult } from './contracts.js';
+export declare function queryStructuralMemory(input: StructuralMemoryQueryInput): Promise<StructuralMemoryQueryResult>;
+//# sourceMappingURL=query.d.ts.map

package/dist/engine/structural-memory/query.js

@@ -0,0 +1,67 @@
+import { clampLimit, loadFreshGraph, nextActionForFreshness, pagination, relatedNodeIds, resolveProjectId, safeRelativeProjectPath, structuralPolicy, summarizeNodes, } from './helpers.js';
+export async function queryStructuralMemory(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const filePath = input.filePath === undefined
+        ? undefined
+        : safeRelativeProjectPath(input.projectPath, input.filePath);
+    const freshnessGraph = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const limit = clampLimit(input.limit, policy);
+    const offset = Math.max(0, input.offset ?? 0);
+    if (input.filePath !== undefined && filePath === null) {
+        const page = pagination(0, limit, offset);
+        return {
+            freshness: freshnessGraph.freshness,
+            pagination: page,
+            ...page,
+            nextAction: {
+                type: 'inspect_evidence',
+                message: 'Rejecting unsafe filePath filter; pass a project-relative path inside the repo.',
+            },
+            nodes: [],
+            edges: [],
+            summary: {},
+        };
+    }
+    const graph = freshnessGraph.graph;
+    if (graph === null) {
+        const page = pagination(0, limit, offset);
+        return {
+            freshness: freshnessGraph.freshness,
+            pagination: page,
+            ...page,
+            nextAction: nextActionForFreshness(freshnessGraph.freshness, true),
+            nodes: [],
+            edges: [],
+            summary: {},
+        };
+    }
+    const ids = relatedNodeIds(graph.nodes, graph.edges, {
+        specId: input.specId,
+        nodeId: input.nodeId,
+        filePath: filePath ?? undefined,
+    });
+    const typeFilter = new Set(input.nodeTypes ?? []);
+    const filteredNodes = graph.nodes.filter((node) => ids.has(node.id) && (typeFilter.size === 0 || typeFilter.has(node.type)));
+    const nodePage = filteredNodes.slice(offset, offset + limit);
+    const nodeIds = new Set(nodePage.map((node) => node.id));
+    const edges = graph.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+    const page = pagination(filteredNodes.length, limit, offset);
+    return {
+        graphVersion: graph.graphVersion,
+        freshness: freshnessGraph.freshness,
+        pagination: page,
+        ...page,
+        nextAction: nextActionForFreshness(freshnessGraph.freshness, filteredNodes.length === 0),
+        nodes: nodePage,
+        edges,
+        summary: summarizeNodes(nodePage),
+        sourceHash: graph.sourceHash,
+        sourceHashes: graph.sourceHashes,
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/engine/structural-memory/status.d.ts

@@ -0,0 +1,3 @@
+import type { StructuralMemoryStatusInput, StructuralMemoryStatusResult } from './contracts.js';
+export declare function getStructuralMemoryStatus(input: StructuralMemoryStatusInput): Promise<StructuralMemoryStatusResult>;
+//# sourceMappingURL=status.d.ts.map

package/dist/engine/structural-memory/status.js

@@ -0,0 +1,30 @@
+import { createStructuralMemoryArtifactPolicy, isStructuralMemoryArtifactPathAllowed, } from './artifact-policy.js';
+import { loadFreshGraph, nextActionForFreshness, resolveProjectId, structuralPolicy, } from './helpers.js';
+export async function getStructuralMemoryStatus(input) {
+    const policy = await structuralPolicy();
+    const projectId = resolveProjectId(input);
+    const { graph, freshness } = await loadFreshGraph({
+        projectId,
+        projectPath: input.projectPath,
+        policy,
+    });
+    const artifactPolicy = createStructuralMemoryArtifactPolicy(projectId, policy);
+    if (!isStructuralMemoryArtifactPathAllowed(artifactPolicy.graphPath)) {
+        throw new Error('Structural memory graph artifacts must remain outside planu/specs.');
+    }
+    return {
+        freshness,
+        nextAction: nextActionForFreshness(freshness, graph === null),
+        artifactPolicy,
+        graph: graph === null
+            ? undefined
+            : {
+                graphVersion: graph.graphVersion,
+                generatedAt: graph.generatedAt,
+                sourceHash: graph.sourceHash,
+                counts: graph.metadata,
+                sourceHashCount: Object.keys(graph.sourceHashes).length,
+            },
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/tools/tool-registry.js

@@ -22,6 +22,9 @@ export function withToolTracking(server) {
                 // Return a wrapper function that calls the original method and captures the result
                 return (...args) => {
                     const name = args[0];
+                    if (registeredTools.has(name)) {
+                        throw new Error(`Duplicate MCP tool registration: ${name}`);
+                    }
                     const originalMethod = Reflect.get(target, prop, receiver);
                     const registered = originalMethod.apply(target, args);
                     registeredTools.set(name, registered);

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@ export * from './common/index.js';
 export * from './estimation.js';
 export * from './spec/index.js';
 export * from './project.js';
+export * from './project-knowledge-graph.js';
+export * from './structural-memory.js';
 export * from './schema.js';
 export * from './ui.js';
 export * from './analysis.js';

package/dist/types/index.js

@@ -6,6 +6,8 @@ export * from './common/index.js';
 export * from './estimation.js';
 export * from './spec/index.js';
 export * from './project.js';
+export * from './project-knowledge-graph.js';
+export * from './structural-memory.js';
 export * from './schema.js';
 export * from './ui.js';
 export * from './analysis.js';

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

@@ -27,6 +27,16 @@ export interface ProjectGraphPolicy {
         maxSnippetChars: number;
         redactPatterns: string[];
     };
+    structuralMemory?: {
+        schemaVersion: string;
+        nodeTypes: string[];
+        edgeTypes: string[];
+        response: {
+            defaultLimit: number;
+            maxLimit: number;
+        };
+        propertySchemas: Record<string, string[]>;
+    };
     toolNamePatterns: string[];
 }
 export interface ProjectGraphEvidencePointer {

package/dist/types/structural-memory.d.ts

@@ -0,0 +1,138 @@
+import type { ProjectGraphEdge, ProjectGraphFreshness, ProjectGraphNode, ProjectKnowledgeGraph } from './project-knowledge-graph.js';
+export type StructuralMemoryStatus = 'fresh' | 'stale' | 'missing' | 'corrupt' | 'partial';
+export type StructuralMemoryNextActionType = 'none' | 'rebuild_graph' | 'broaden_filters' | 'inspect_evidence' | 'run_validate';
+export interface StructuralMemoryNextAction {
+    type: StructuralMemoryNextActionType;
+    message: string;
+}
+export interface StructuralMemoryPagination {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    has_more: boolean;
+    truncated: boolean;
+}
+export interface StructuralMemoryFreshness {
+    status: StructuralMemoryStatus;
+    graphPath: string;
+    generatedAt?: string;
+    changedSources: string[];
+    reason: ProjectGraphFreshness['reason'] | 'partial';
+}
+export interface StructuralMemoryEnvelope {
+    graphVersion?: string;
+    freshness: StructuralMemoryFreshness;
+    pagination: StructuralMemoryPagination;
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    has_more: boolean;
+    truncated: boolean;
+    nextAction: StructuralMemoryNextAction;
+}
+export interface StructuralMemoryQueryInput {
+    projectId?: string;
+    projectPath: string;
+    specId?: string;
+    filePath?: string;
+    nodeId?: string;
+    nodeTypes?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface StructuralMemoryQueryResult extends StructuralMemoryEnvelope {
+    nodes: ProjectGraphNode[];
+    edges: ProjectGraphEdge[];
+    summary: Record<string, number>;
+    sourceHash?: string;
+    sourceHashes?: Record<string, string>;
+}
+export type ArchitectureAspect = 'packages' | 'hotspots' | 'boundaries' | 'releaseRisks' | 'tests' | 'decisions' | 'all';
+export interface ArchitectureSnapshotInput {
+    projectId?: string;
+    projectPath: string;
+    pathPrefix?: string;
+    aspects?: ArchitectureAspect[];
+    limit?: number;
+}
+export interface ArchitectureSnapshotResult extends StructuralMemoryEnvelope {
+    aspects: {
+        packages?: {
+            name: string;
+            fileCount: number;
+        }[];
+        hotspots?: {
+            id: string;
+            label: string;
+            type: string;
+            degree: number;
+        }[];
+        boundaries?: {
+            from: string;
+            to: string;
+            type: string;
+        }[];
+        releaseRisks?: {
+            id: string;
+            label: string;
+            type: string;
+        }[];
+        tests?: {
+            id: string;
+            label: string;
+        }[];
+        decisions?: {
+            id: string;
+            label: string;
+        }[];
+    };
+}
+export interface StructuralMemoryStatusInput {
+    projectId?: string;
+    projectPath: string;
+}
+export interface StructuralMemoryArtifactPolicy {
+    artifactRoot: string;
+    graphPath: string;
+    projectDataDirectory: string;
+    forbiddenPathFragment: 'planu/specs';
+    specDirectoryPolicy: 'spec.md-only';
+    evidenceAndGraphArtifactsRemainOutsideSpecs: true;
+}
+export interface StructuralMemoryStatusResult {
+    freshness: StructuralMemoryFreshness;
+    nextAction: StructuralMemoryNextAction;
+    artifactPolicy: StructuralMemoryArtifactPolicy;
+    graph?: Pick<ProjectKnowledgeGraph, 'graphVersion' | 'generatedAt' | 'sourceHash'> & {
+        counts: ProjectKnowledgeGraph['metadata'];
+        sourceHashCount: number;
+    };
+}
+export interface StructuralChangeImpactInput {
+    projectId?: string;
+    projectPath: string;
+    baseRef?: string;
+    changedFiles?: string[];
+    includeUntracked?: boolean;
+    limit?: number;
+}
+export interface StructuralChangedFile {
+    path: string;
+    status: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked' | 'unknown';
+}
+export interface StructuralChangeImpactResult extends StructuralMemoryEnvelope {
+    changedFiles: StructuralChangedFile[];
+    affected: {
+        specs: ProjectGraphNode[];
+        criteria: ProjectGraphNode[];
+        tests: ProjectGraphNode[];
+        decisions: ProjectGraphNode[];
+        evidence: ProjectGraphNode[];
+        risks: ProjectGraphNode[];
+        releaseRisk: ProjectGraphNode[];
+    };
+    affectedEdges: ProjectGraphEdge[];
+}
+//# sourceMappingURL=structural-memory.d.ts.map

package/dist/types/structural-memory.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.8.0",
-    "@planu/core-darwin-x64": "4.8.0",
-    "@planu/core-linux-arm64-gnu": "4.8.0",
-    "@planu/core-linux-arm64-musl": "4.8.0",
-    "@planu/core-linux-x64-gnu": "4.8.0",
-    "@planu/core-linux-x64-musl": "4.8.0",
-    "@planu/core-win32-arm64-msvc": "4.8.0",
-    "@planu/core-win32-x64-msvc": "4.8.0"
+    "@planu/core-darwin-arm64": "4.9.0",
+    "@planu/core-darwin-x64": "4.9.0",
+    "@planu/core-linux-arm64-gnu": "4.9.0",
+    "@planu/core-linux-arm64-musl": "4.9.0",
+    "@planu/core-linux-x64-gnu": "4.9.0",
+    "@planu/core-linux-x64-musl": "4.9.0",
+    "@planu/core-win32-arm64-msvc": "4.9.0",
+    "@planu/core-win32-x64-msvc": "4.9.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -129,7 +129,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.105.0",
+    "@anthropic-ai/sdk": "^0.107.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "glob": "^13.0.6",
     "yaml": "^2.9.0",
@@ -168,8 +168,8 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.1.0",
-    "@commitlint/config-conventional": "^21.1.0",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@napi-rs/cli": "^3.7.2",
     "@secretlint/secretlint-rule-no-homedir": "^13.0.2",
@@ -182,30 +182,30 @@
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
-    "@supabase/supabase-js": "^2.108.2",
-    "@types/node": "^26.0.0",
+    "@supabase/supabase-js": "^2.110.0",
+    "@types/node": "^26.0.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-v8": "^4.1.9",
     "@vue/test-utils": "^2.4.11",
-    "eslint": "^10.5.0",
+    "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.20.0",
+    "knip": "^6.23.0",
     "lint-staged": "^17.0.8",
     "madge": "^8.0.0",
-    "prettier": "^3.8.4",
+    "prettier": "^3.9.4",
     "secretlint": "^13.0.2",
     "semantic-release": "^25.0.5",
     "tsc-alias": "^1.8.17",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.0",
-    "vite": "^8.1.0",
+    "typescript-eslint": "^8.62.1",
+    "vite": "^8.1.1",
     "vitest": "^4.1.9",
-    "vue": "^3.5.38"
+    "vue": "^3.5.39"
   }
 }

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

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": "4.8.0",
+  "version": "4.9.0",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",