sysprom 1.14.0 → 1.15.0

package/README.md

@@ -52,13 +52,20 @@ sysprom update node D1 --status deprecated
 sysprom update add-rel D1 affects EL5
 sysprom update remove-rel D1 affects EL5
 sysprom update meta --fields version=2
+
+# Inference operations (deterministic graph analysis)
+sysprom infer completeness              # Score node completeness (0-1)
+sysprom infer lifecycle                 # Infer lifecycle phases
+sysprom infer impact I1                 # Trace impact from node
+sysprom infer derived                   # Compute transitive closure
+sysprom infer all                       # Run all analyses
 ```
 
 All commands auto-detect the document — they search the current directory for `.SysProM.json`, `.SysProM.md`, or `.SysProM/` (in that priority order), then fall back to `.spm.json`, `.spm.md`, or `.spm/`. Use `--path` to specify an explicit path. Note: `spm` is an alias for `sysprom` for backwards compatibility.
 
 ## MCP Server
 
-SysProM includes an MCP (Model Context Protocol) server exposing 11 tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.
+SysProM includes an MCP (Model Context Protocol) server exposing 15 tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.
 
 ### Configuration
 
@@ -96,6 +103,10 @@ sysprom mcp   # starts the MCP server on stdio
 | `update-node` | Update fields on an existing node |
 | `add-relationship` | Add a relationship between nodes |
 | `remove-relationship` | Remove a relationship |
+| `infer-completeness` | Score node completeness (0-1) based on refinement relationships |
+| `infer-lifecycle` | Infer lifecycle phase from status and lifecycle fields |
+| `infer-impact` | Trace impact propagation from a starting node |
+| `infer-derived` | Compute transitive closure and inverse relationships |
 
 All tools accept a `path` parameter to specify the SysProM document location.
 
@@ -134,6 +145,12 @@ import {
   removeRelationship,
   updateMetadata,
 
+  // Inference
+  inferCompletenessOp,
+  inferLifecycleOp,
+  inferImpactOp,
+  inferDerivedOp,
+
   // File I/O
   loadDocument,
   saveDocument,
@@ -212,7 +229,7 @@ SysProM models systems as directed graphs across abstraction layers — intent,
 <tr><td><a href="https://github.com/Priivacy-ai/spec-kitty">Spec Kitty</a></td><td>✅</td><td>🔶</td><td>✅</td><td>🔶</td><td></td><td>🔶</td><td>🔶</td><td>🔶</td><td></td><td></td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td></tr>
 <tr><td><a href="https://github.com/shotgun-sh/shotgun">Shotgun</a></td><td>✅</td><td>🔶</td><td>🔶</td><td></td><td></td><td>🔶</td><td></td><td>🔶</td><td></td><td></td><td>🔶</td><td>🔶</td><td>✅</td><td>🔶</td></tr>
 <tr><td><a href="https://github.com/obra/superpowers">Superpowers</a></td><td>✅</td><td>🔶</td><td>🔶</td><td>🔶</td><td></td><td>🔶</td><td>✅</td><td>🔶</td><td></td><td>✅</td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td></tr>
-<tr><td><strong>SysProM</strong></td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td></td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td></tr>
+<tr><td><strong>SysProM</strong></td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>🔶</td><td>✅</td><td>✅</td><td>✅</td></tr>
 </tbody>
 </table>
 

package/dist/src/cli/commands/infer.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDef } from "../define-command.js";
+export declare const inferCommand: CommandDef;

package/dist/src/cli/commands/infer.js

@@ -0,0 +1,206 @@
+import pc from "picocolors";
+import * as z from "zod";
+import { readOpts, loadDoc } from "../shared.js";
+import { inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, } from "../../operations/index.js";
+// ---------------------------------------------------------------------------
+// Presentation helpers
+// ---------------------------------------------------------------------------
+function printCompletenessNode(r) {
+    const scoreColour = r.score === 1 ? pc.green : r.score >= 0.5 ? pc.yellow : pc.red;
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${scoreColour(`[${(r.score * 100).toFixed(0)}%]`)}`);
+    for (const issue of r.issues) {
+        console.log(`  ${pc.dim("•")} ${pc.red(issue)}`);
+    }
+}
+function printLifecycleNode(r) {
+    const phaseColours = {
+        early: pc.blue,
+        middle: pc.yellow,
+        late: pc.green,
+        terminal: pc.red,
+        unknown: pc.dim,
+    };
+    const colour = phaseColours[r.inferredPhase] ?? pc.dim;
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${colour(`[${r.inferredPhase}]`)} ${pc.dim(r.inferredState)}`);
+}
+function printImpactNode(r) {
+    const typeColours = {
+        direct: pc.red,
+        transitive: pc.yellow,
+        potential: pc.blue,
+    };
+    const colour = typeColours[r.impactType] ?? pc.dim;
+    const nodeName = r.node ? r.node.name : "(unknown)";
+    const indent = "  ".repeat(r.distance);
+    console.log(`${indent}${pc.cyan(r.id)} ${pc.dim(`(${String(r.distance)})`)} ${colour(`[${r.impactType}]`)} ${pc.bold(nodeName)}`);
+}
+function printDerivedRelationship(r) {
+    const typeColours = {
+        transitive: pc.yellow,
+        composite: pc.blue,
+        inverse: pc.green,
+    };
+    const colour = typeColours[r.derivationType] ?? pc.dim;
+    console.log(`${pc.cyan(r.from.padEnd(12))} ${colour(r.type.padEnd(20))} ${pc.cyan(r.to)} ${pc.dim(`[${r.derivationType}]`)}`);
+}
+// ---------------------------------------------------------------------------
+// Arg/opt schemas
+// ---------------------------------------------------------------------------
+const impactArgs = z.object({
+    id: z.string().describe("node ID to start impact analysis from"),
+});
+// ---------------------------------------------------------------------------
+// Subcommands
+// ---------------------------------------------------------------------------
+const completenessSubcommand = {
+    name: "completeness",
+    description: inferCompletenessOp.def.description,
+    apiLink: inferCompletenessOp.def.name,
+    opts: readOpts,
+    action(_rawArgs, rawOpts) {
+        const opts = readOpts.parse(rawOpts);
+        const { doc } = loadDoc(opts.path);
+        const result = inferCompletenessOp({ doc });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(pc.bold("\nCompleteness Analysis\n") +
+                pc.dim(`Average score: ${(result.averageScore * 100).toFixed(1)}% | `) +
+                pc.green(`${String(result.completeNodes)} complete`) +
+                pc.dim(" | ") +
+                pc.red(`${String(result.incompleteNodes)} incomplete`) +
+                "\n");
+            // Show incomplete nodes first
+            const incomplete = result.nodes.filter((n) => n.score < 1);
+            const complete = result.nodes.filter((n) => n.score === 1);
+            if (incomplete.length > 0) {
+                console.log(pc.dim("Incomplete nodes:"));
+                for (const n of incomplete)
+                    printCompletenessNode(n);
+                console.log();
+            }
+            console.log(pc.dim(`${String(complete.length)} fully complete nodes`));
+        }
+    },
+};
+const lifecycleSubcommand = {
+    name: "lifecycle",
+    description: inferLifecycleOp.def.description,
+    apiLink: inferLifecycleOp.def.name,
+    opts: readOpts,
+    action(_rawArgs, rawOpts) {
+        const opts = readOpts.parse(rawOpts);
+        const { doc } = loadDoc(opts.path);
+        const result = inferLifecycleOp({ doc });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(pc.bold("\nLifecycle Analysis\n") +
+                pc.dim(`Early: ${String(result.summary.early)} | Middle: ${String(result.summary.middle)} | Late: ${String(result.summary.late)} | Terminal: ${String(result.summary.terminal)} | Unknown: ${String(result.summary.unknown)}`) +
+                "\n");
+            for (const n of result.nodes)
+                printLifecycleNode(n);
+        }
+    },
+};
+const impactSubcommand = {
+    name: "impact",
+    description: inferImpactOp.def.description,
+    apiLink: inferImpactOp.def.name,
+    args: impactArgs,
+    opts: readOpts,
+    action(rawArgs, rawOpts) {
+        const args = impactArgs.parse(rawArgs);
+        const opts = readOpts.parse(rawOpts);
+        const { doc } = loadDoc(opts.path);
+        const result = inferImpactOp({ doc, startId: args.id });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(pc.bold(`\nImpact Analysis from ${args.id}\n`) +
+                pc.dim(`Direct: ${String(result.summary.direct)} | Transitive: ${String(result.summary.transitive)} | Potential: ${String(result.summary.potential)} | Total: ${String(result.summary.total)}`) +
+                "\n");
+            if (result.impactedNodes.length === 0) {
+                console.log(pc.dim("No impacted nodes found"));
+            }
+            else {
+                for (const n of result.impactedNodes)
+                    printImpactNode(n);
+            }
+        }
+    },
+};
+const derivedSubcommand = {
+    name: "derived",
+    description: inferDerivedOp.def.description,
+    apiLink: inferDerivedOp.def.name,
+    opts: readOpts,
+    action(_rawArgs, rawOpts) {
+        const opts = readOpts.parse(rawOpts);
+        const { doc } = loadDoc(opts.path);
+        const result = inferDerivedOp({ doc });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(pc.bold("\nDerived Relationships\n") +
+                pc.dim(`Transitive: ${String(result.summary.transitive)} | Composite: ${String(result.summary.composite)} | Inverse: ${String(result.summary.inverse)} | Total: ${String(result.summary.total)}`) +
+                "\n");
+            if (result.derivedRelationships.length === 0) {
+                console.log(pc.dim("No derived relationships found"));
+            }
+            else {
+                for (const r of result.derivedRelationships)
+                    printDerivedRelationship(r);
+            }
+        }
+    },
+};
+const allSubcommand = {
+    name: "all",
+    description: "Run all inference analyses",
+    opts: readOpts,
+    action(_rawArgs, rawOpts) {
+        const opts = readOpts.parse(rawOpts);
+        const { doc } = loadDoc(opts.path);
+        // Completeness
+        console.log(pc.bold("\n=== Completeness ===\n"));
+        const completeness = inferCompletenessOp({ doc });
+        console.log(pc.dim(`Average score: ${(completeness.averageScore * 100).toFixed(1)}% | `) +
+            pc.green(`${String(completeness.completeNodes)} complete`) +
+            pc.dim(" | ") +
+            pc.red(`${String(completeness.incompleteNodes)} incomplete`));
+        // Lifecycle
+        console.log(pc.bold("\n=== Lifecycle ===\n"));
+        const lifecycle = inferLifecycleOp({ doc });
+        console.log(pc.dim(`Early: ${String(lifecycle.summary.early)} | Middle: ${String(lifecycle.summary.middle)} | Late: ${String(lifecycle.summary.late)} | Terminal: ${String(lifecycle.summary.terminal)} | Unknown: ${String(lifecycle.summary.unknown)}`));
+        // Derived
+        console.log(pc.bold("\n=== Derived Relationships ===\n"));
+        const derived = inferDerivedOp({ doc });
+        console.log(pc.dim(`Transitive: ${String(derived.summary.transitive)} | Composite: ${String(derived.summary.composite)} | Inverse: ${String(derived.summary.inverse)} | Total: ${String(derived.summary.total)}`));
+        if (opts.json) {
+            console.log(JSON.stringify({
+                completeness,
+                lifecycle,
+                derived,
+            }, null, 2));
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+export const inferCommand = {
+    name: "infer",
+    description: "Infer completeness, lifecycle, impact, and derived relationships",
+    subcommands: [
+        completenessSubcommand,
+        lifecycleSubcommand,
+        impactSubcommand,
+        derivedSubcommand,
+        allSubcommand,
+    ],
+};

package/dist/src/cli/program.js

@@ -43,6 +43,7 @@ import { speckitCommand } from "./commands/speckit.js";
 import { taskCommand } from "./commands/task.js";
 import { planCommand } from "./commands/plan.js";
 import { syncCommandDef } from "./commands/sync.js";
+import { inferCommand } from "./commands/infer.js";
 export const program = new Command();
 program
     .name("sysprom")
@@ -71,6 +72,7 @@ export const commands = [
     taskCommand,
     planCommand,
     syncCommandDef,
+    inferCommand,
 ];
 for (const cmd of commands) {
     buildCommander(cmd, program);

package/dist/src/index.d.ts

@@ -6,7 +6,7 @@
  * @packageDocumentation
  */
 export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, toJSONSchema, } from "./schema.js";
-export { defineOperation, type OperationDef, type DefinedOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, nextIdOp, initDocumentOp, addPlanTaskOp, updatePlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, timelineOp, nodeHistoryOp, stateAtOp, validateOp, statsOp, searchOp, checkOp, graphOp, renameOp, jsonToMarkdownOp, markdownToJsonOp, speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, type RemoveResult, type ValidationResult, type DocumentStats, type NodeDetail, type TraceNode, type TimelineEvent, type NodeState, type PlanStatusResult, type PhaseProgressResult, type GateResultOutput, type SyncResult, type DiffResult, } from "./operations/index.js";
+export { defineOperation, type OperationDef, type DefinedOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, nextIdOp, initDocumentOp, addPlanTaskOp, updatePlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, timelineOp, nodeHistoryOp, stateAtOp, validateOp, statsOp, searchOp, checkOp, graphOp, renameOp, jsonToMarkdownOp, markdownToJsonOp, speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, type RemoveResult, type ValidationResult, type DocumentStats, type NodeDetail, type TraceNode, type TimelineEvent, type NodeState, type PlanStatusResult, type PhaseProgressResult, type GateResultOutput, type SyncResult, type DiffResult, type CompletenessOutput, type LifecycleOutput, type ImpactOutput, type DerivedOutput, } from "./operations/index.js";
 export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, type ConvertOptions, } from "./json-to-md.js";
 export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";
 export { RELATIONSHIP_ENDPOINT_TYPES, isValidEndpointPair, } from "./endpoint-types.js";

package/dist/src/index.js

@@ -8,7 +8,7 @@
 // Schema types and validators
 export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, toJSONSchema, } from "./schema.js";
 // Operations (single source of truth for domain logic + metadata)
-export { defineOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, nextIdOp, initDocumentOp, addPlanTaskOp, updatePlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, timelineOp, nodeHistoryOp, stateAtOp, validateOp, statsOp, searchOp, checkOp, graphOp, renameOp, jsonToMarkdownOp, markdownToJsonOp, speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, } from "./operations/index.js";
+export { defineOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, nextIdOp, initDocumentOp, addPlanTaskOp, updatePlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, timelineOp, nodeHistoryOp, stateAtOp, validateOp, statsOp, searchOp, checkOp, graphOp, renameOp, jsonToMarkdownOp, markdownToJsonOp, speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, } from "./operations/index.js";
 // Conversion
 export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, } from "./json-to-md.js";
 export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";

package/dist/src/mcp/server.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import * as z from "zod";
 import { loadDocument, saveDocument } from "../io.js";
 import { NodeType, RelationshipType } from "../schema.js";
-import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, } from "../operations/index.js";
+import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, } from "../operations/index.js";
 // Create MCP server instance
 const server = new McpServer({
     name: "sysprom-mcp",
@@ -318,6 +318,79 @@ server.registerTool("remove-relationship", {
         ],
     };
 });
+// Register infer-completeness tool
+server.registerTool("infer-completeness", {
+    description: "Infer completeness of nodes based on expected refinement relationships",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+    }),
+}, ({ path }) => {
+    const { doc } = loadDocument(path);
+    const result = inferCompletenessOp({ doc });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register infer-lifecycle tool
+server.registerTool("infer-lifecycle", {
+    description: "Infer lifecycle state for nodes based on status and lifecycle fields",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+    }),
+}, ({ path }) => {
+    const { doc } = loadDocument(path);
+    const result = inferLifecycleOp({ doc });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register infer-impact tool
+server.registerTool("infer-impact", {
+    description: "Infer impact from a node through the graph following impact relationships",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+        startId: z.string().describe("Node ID to start impact analysis from"),
+    }),
+}, ({ path, startId }) => {
+    const { doc } = loadDocument(path);
+    const result = inferImpactOp({ doc, startId });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// Register infer-derived tool
+server.registerTool("infer-derived", {
+    description: "Infer derived relationships from transitive closure, inverses, and composites",
+    inputSchema: z.object({
+        path: z.string().describe("Path to SysProM file"),
+    }),
+}, ({ path }) => {
+    const { doc } = loadDocument(path);
+    const result = inferDerivedOp({ doc });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
 // Start server
 async function main() {
     const transport = new StdioServerTransport();

package/dist/src/operations/index.d.ts

@@ -37,3 +37,7 @@ export { speckitImportOp } from "./speckit-import.js";
 export { speckitExportOp } from "./speckit-export.js";
 export { speckitSyncOp, type SyncResult } from "./speckit-sync.js";
 export { speckitDiffOp, type DiffResult } from "./speckit-diff.js";
+export { inferCompletenessOp, type CompletenessResult, type CompletenessOutput, } from "./infer-completeness.js";
+export { inferLifecycleOp, type LifecycleResult, type LifecycleOutput, } from "./infer-lifecycle.js";
+export { inferImpactOp, type ImpactNode, type ImpactOutput, } from "./infer-impact.js";
+export { inferDerivedOp, type DerivedRelationship, type DerivedOutput, } from "./infer-derived.js";

package/dist/src/operations/index.js

@@ -45,3 +45,8 @@ export { speckitImportOp } from "./speckit-import.js";
 export { speckitExportOp } from "./speckit-export.js";
 export { speckitSyncOp } from "./speckit-sync.js";
 export { speckitDiffOp } from "./speckit-diff.js";
+// Inference operations
+export { inferCompletenessOp, } from "./infer-completeness.js";
+export { inferLifecycleOp, } from "./infer-lifecycle.js";
+export { inferImpactOp, } from "./infer-impact.js";
+export { inferDerivedOp, } from "./infer-derived.js";