@planu/cli 4.8.0 → 4.10.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [4.10.0] - 2026-07-01
+
+### Features
+- feat(SPEC-1100): add reliable feedback sync
+
+### Bug Fixes
+- fix(SPEC-1102): honor release preflight test skip
+- fix(SPEC-1101): harden validate runtime and status
+
+### Chores
+- chore(deps): refresh direct dependencies
+
+
+## [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/license-plans.json

@@ -92,6 +92,7 @@
     "export_spec",
     "expose_spec_as_prompt",
     "facilitate",
+    "feedback_status",
     "gc_data_projects",
     "generate_api_client",
     "generate_attestation",
@@ -163,6 +164,7 @@
     "render_spec_for_provider",
     "repair_frontmatter_drift",
     "request_changes",
+    "resolve_feedback",
     "reverse_engineer",
     "rewrite_criteria_ears",
     "run_mutation_hints",
@@ -189,13 +191,16 @@
     "suggest_token_optimizer",
     "suggest_tooling",
     "summarize_spec",
+    "submit_feedback",
     "sync_ai_configs",
+    "sync_feedback",
     "sync_spec_state",
     "tdd_scaffold",
     "tdd_status",
     "telemetry_health",
     "token_optimizer_status",
     "transform_code",
+    "triage_feedback",
     "triage_request",
     "type_safety_gate",
     "unregister_project_path",

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/config/registries/hosts/codex.json

@@ -294,6 +294,8 @@
     "submit_feedback",
     "triage_feedback",
     "resolve_feedback",
+    "sync_feedback",
+    "feedback_status",
     "delete_spec",
     "delete_project",
     "delete_pattern",
@@ -373,10 +375,7 @@
     "analyze_performance_impact",
     "recommend_model"
   ],
-  "unsupportedTools": [
-    "challenge_spec",
-    "red_team"
-  ],
+  "unsupportedTools": ["challenge_spec", "red_team"],
   "restrictedTools": {
     "challenge_spec": "Requires interactive UI — use planu_facilitate instead",
     "approve_spec": "Requires reviewer token — use planu_facilitate instead"

package/dist/engine/evidence-index/index-builder.js

@@ -37,16 +37,16 @@ async function collectEvidence(args) {
             records.push(record('scenario', row.scenario, 'valid', 'traceability-matrix'));
         }
         for (const test of row.testEvidence ?? []) {
-            records.push(await pathRecord('test', test, 'traceability-matrix', args));
+            records.push(await pathRecord('test', test, 'traceability-matrix', args, 'testEvidence'));
         }
         for (const contract of row.contractEvidence ?? []) {
-            records.push(await pathRecord('contract', contract, 'traceability-matrix', args));
+            records.push(await pathRecord('contract', contract, 'traceability-matrix', args, 'contractEvidence'));
         }
         if (row.manualEvidence) {
             records.push(record('manual', row.manualEvidence, 'valid', 'traceability-matrix'));
         }
         for (const changedFile of row.changedFiles) {
-            records.push(await pathRecord('changed-file', changedFile, 'traceability-matrix', args));
+            records.push(await pathRecord('changed-file', changedFile, 'traceability-matrix', args, 'changedFiles'));
         }
         if (row.validationEvidence) {
             records.push(validationRecord(row.validationEvidence));
@@ -57,7 +57,7 @@ async function collectEvidence(args) {
     }
     for (const validation of args.contractValidations) {
         if (validation.reportPath) {
-            records.push(await pathRecord('contract', validation.reportPath, `contract-validation:${validation.kind}`, args));
+            records.push(await pathRecord('contract', validation.reportPath, `contract-validation:${validation.kind}`, args, 'contractValidation.reportPath'));
         }
         if (validation.summary) {
             records.push({
@@ -95,36 +95,62 @@ function parseValidationEvidence(value) {
         return { command: value };
     }
 }
-async function pathRecord(kind, value, source, args) {
-    const safe = resolveSafeProjectPath(value, args.projectPath);
+async function pathRecord(kind, value, source, args, fieldName) {
+    const safe = resolveSafeProjectPath(value, args.projectPath, fieldName);
     if (!safe.ok) {
         args.diagnostics.push(`${value}: ${safe.reason}`);
         return record(kind, value, 'invalid', source, safe.reason);
     }
     if (!args.projectPath) {
-        return record(kind, value, 'missing', source, 'projectPath unavailable');
+        return record(kind, value, 'missing', source, evidencePathReason(fieldName, 'projectPath unavailable'));
     }
     const exists = await stat(safe.path)
         .then(() => true)
         .catch(() => false);
-    return record(kind, value, exists ? 'valid' : 'stale', source, exists ? undefined : 'file missing');
+    const missingReason = evidencePathReason(fieldName, `Missing path: ${value}`);
+    return record(kind, value, exists ? 'valid' : 'stale', source, exists ? undefined : missingReason);
 }
-function resolveSafeProjectPath(value, projectPath) {
+function resolveSafeProjectPath(value, projectPath, fieldName) {
     if (value.trim().length === 0) {
-        return { ok: false, reason: 'empty evidence path' };
+        return { ok: false, reason: evidencePathReason(fieldName, 'Empty path.') };
+    }
+    if (looksLikeShellCommand(value)) {
+        return { ok: false, reason: evidencePathReason(fieldName, 'Commands are not valid paths.') };
+    }
+    if (looksLikeGlob(value)) {
+        return { ok: false, reason: evidencePathReason(fieldName, 'Globs are not valid paths.') };
     }
     if (isAbsolute(value)) {
-        return { ok: false, reason: 'absolute evidence paths are not allowed' };
+        return { ok: false, reason: evidencePathReason(fieldName, 'Absolute paths are not allowed.') };
     }
     const normalized = normalize(value);
     if (normalized.startsWith('..') || normalized.includes('/../')) {
-        return { ok: false, reason: 'path traversal is not allowed' };
+        return { ok: false, reason: evidencePathReason(fieldName, 'Path traversal is not allowed.') };
     }
     if (!projectPath) {
         return { ok: true, path: normalized };
     }
     return { ok: true, path: join(projectPath, normalized) };
 }
+function evidencePathReason(fieldName, detail) {
+    if (fieldName === 'testEvidence') {
+        return `testEvidence must contain existing file paths only; put command output in validationEvidence. ${detail}`;
+    }
+    if (fieldName === 'changedFiles') {
+        return `changedFiles must contain existing repository-relative paths only; no globs or commands. ${detail}`;
+    }
+    return `Evidence path must be an existing repository-relative path. ${detail}`;
+}
+function looksLikeShellCommand(value) {
+    const trimmed = value.trim();
+    if (/\s/.test(trimmed) && !/\.[A-Za-z0-9]+$/.test(trimmed)) {
+        return true;
+    }
+    return /^(?:pnpm|npm|yarn|bun|npx|node|tsx|tsc|vitest|jest|git|bash|sh)\b/.test(trimmed);
+}
+function looksLikeGlob(value) {
+    return /[*?[\]{}]/.test(value);
+}
 function record(kind, value, status, source, reason) {
     return { kind, value, status, source, ...(reason ? { reason } : {}) };
 }

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