sysprom 1.16.1 → 1.18.0

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

@@ -5,9 +5,17 @@ import { inferCompletenessOp, inferLifecycleOp, inferImpactOp, inferDerivedOp, }
 // ---------------------------------------------------------------------------
 // Presentation helpers
 // ---------------------------------------------------------------------------
+function getScoreColour(score) {
+    if (score === 1)
+        return pc.green;
+    if (score >= 0.5)
+        return pc.yellow;
+    return pc.red;
+}
 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)}%]`)}`);
+    const scoreColour = getScoreColour(r.score);
+    const scoreText = `[${(r.score * 100).toFixed(0)}%]`;
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${scoreColour(scoreText)}`);
     for (const issue of r.issues) {
         console.log(`  ${pc.dim("•")} ${pc.red(issue)}`);
     }
@@ -21,7 +29,8 @@ function printLifecycleNode(r) {
         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)}`);
+    const phaseLabel = colour(`[${r.inferredPhase}]`);
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)} ${phaseLabel} ${pc.dim(r.inferredState)}`);
 }
 function printImpactNode(r) {
     const typeColours = {
@@ -32,7 +41,9 @@ function printImpactNode(r) {
     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)}`);
+    const distanceLabel = pc.dim(`(${String(r.distance)})`);
+    const typeLabel = colour(`[${r.impactType}]`);
+    console.log(`${indent}${pc.cyan(r.id)} ${distanceLabel} ${typeLabel} ${pc.bold(nodeName)}`);
 }
 function printDerivedRelationship(r) {
     const typeColours = {
@@ -41,7 +52,8 @@ function printDerivedRelationship(r) {
         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}]`)}`);
+    const derivationLabel = pc.dim(`[${r.derivationType}]`);
+    console.log(`${pc.cyan(r.from.padEnd(12))} ${colour(r.type.padEnd(20))} ${pc.cyan(r.to)} ${derivationLabel}`);
 }
 // ---------------------------------------------------------------------------
 // Arg/opt schemas
@@ -79,12 +91,13 @@ const completenessSubcommand = {
             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");
+            const avgScore = (result.averageScore * 100).toFixed(1);
+            const completeText = pc.green(`${String(result.completeNodes)} complete`);
+            const incompleteText = pc.red(`${String(result.incompleteNodes)} incomplete`);
+            const scorePrefix = pc.dim(`Average score: ${avgScore}% | `);
+            const separator = pc.dim(" | ");
+            const summary = scorePrefix + completeText + separator + incompleteText;
+            console.log(pc.bold("\nCompleteness Analysis\n") + summary + "\n");
             // Show incomplete nodes first
             const incomplete = result.nodes.filter((n) => n.score < 1);
             const complete = result.nodes.filter((n) => n.score === 1);
@@ -111,9 +124,9 @@ const lifecycleSubcommand = {
             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");
+            const { early, middle, late, terminal, unknown } = result.summary;
+            const summary = pc.dim(`Early: ${String(early)} | Middle: ${String(middle)} | Late: ${String(late)} | Terminal: ${String(terminal)} | Unknown: ${String(unknown)}`);
+            console.log(pc.bold("\nLifecycle Analysis\n") + summary + "\n");
             for (const n of result.nodes)
                 printLifecycleNode(n);
         }
@@ -149,9 +162,10 @@ const impactSubcommand = {
                 ? ` [depth: ${String(args.maxDepth)}]`
                 : "";
             const filterLabel = args.filter ? ` [filter: ${args.filter}]` : "";
-            console.log(pc.bold(`\nImpact Analysis from ${args.id}${directionLabel}${depthLabel}${filterLabel}\n`) +
-                pc.dim(`Direct: ${String(result.summary.direct)} | Transitive: ${String(result.summary.transitive)} | Potential: ${String(result.summary.potential)} | Total: ${String(result.summary.total)}`) +
-                "\n");
+            const title = `\nImpact Analysis from ${args.id}${directionLabel}${depthLabel}${filterLabel}\n`;
+            const { direct, transitive, potential, total } = result.summary;
+            const summary = pc.dim(`Direct: ${String(direct)} | Transitive: ${String(transitive)} | Potential: ${String(potential)} | Total: ${String(total)}`);
+            console.log(pc.bold(title) + summary + "\n");
             if (result.impactedNodes.length === 0) {
                 console.log(pc.dim("No impacted nodes found"));
             }
@@ -175,9 +189,9 @@ const derivedSubcommand = {
             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");
+            const { transitive, composite, inverse, total } = result.summary;
+            const summary = pc.dim(`Transitive: ${String(transitive)} | Composite: ${String(composite)} | Inverse: ${String(inverse)} | Total: ${String(total)}`);
+            console.log(pc.bold("\nDerived Relationships\n") + summary + "\n");
             if (result.derivedRelationships.length === 0) {
                 console.log(pc.dim("No derived relationships found"));
             }
@@ -198,18 +212,23 @@ const allSubcommand = {
         // 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`) +
+        const completeScore = (completeness.averageScore * 100).toFixed(1);
+        const completeText = pc.green(`${String(completeness.completeNodes)} complete`);
+        const incompleteText = pc.red(`${String(completeness.incompleteNodes)} incomplete`);
+        console.log(pc.dim(`Average score: ${completeScore}% | `) +
+            completeText +
             pc.dim(" | ") +
-            pc.red(`${String(completeness.incompleteNodes)} incomplete`));
+            incompleteText);
         // 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)}`));
+        const { early, middle, late, terminal, unknown } = lifecycle.summary;
+        console.log(pc.dim(`Early: ${String(early)} | Middle: ${String(middle)} | Late: ${String(late)} | Terminal: ${String(terminal)} | Unknown: ${String(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)}`));
+        const { transitive, composite, inverse, total } = derived.summary;
+        console.log(pc.dim(`Transitive: ${String(transitive)} | Composite: ${String(composite)} | Inverse: ${String(inverse)} | Total: ${String(total)}`));
         if (opts.json) {
             console.log(JSON.stringify({
                 completeness,

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

@@ -10,5 +10,5 @@ declare const optsSchema: z.ZodObject<{
         dir: "dir";
     }>>;
 }, z.core.$strict>;
-export declare const initCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const initCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

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

@@ -4,6 +4,35 @@ declare const optsSchema: z.ZodObject<{
     input: z.ZodString;
     output: z.ZodString;
     singleFile: z.ZodOptional<z.ZodBoolean>;
+    embedDiagrams: z.ZodOptional<z.ZodBoolean>;
+    labelMode: z.ZodOptional<z.ZodEnum<{
+        friendly: "friendly";
+        compact: "compact";
+    }>>;
+    relationshipLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    refinementLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    decisionLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    dependencyLayout: z.ZodOptional<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
 }, z.core.$strict>;
-export declare const json2mdCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const json2mdCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

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

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import * as z from "zod";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -12,6 +13,30 @@ const optsSchema = z
         .boolean()
         .optional()
         .describe("Force single-file output format"),
+    embedDiagrams: z
+        .boolean()
+        .optional()
+        .describe("Embed Mermaid diagrams in the output"),
+    labelMode: z
+        .enum(["friendly", "compact"])
+        .optional()
+        .describe("Node label mode for embedded diagrams"),
+    relationshipLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for relationship diagrams"),
+    refinementLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for refinement diagrams"),
+    decisionLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for decision diagrams"),
+    dependencyLayout: z
+        .enum(["LR", "TD", "RL", "BT"])
+        .optional()
+        .describe("Override layout for dependency diagrams"),
 })
     .strict();
 export const json2mdCommand = {
@@ -23,6 +48,7 @@ export const json2mdCommand = {
         const inputPath = resolve(opts.input);
         const outputPath = resolve(opts.output);
         const raw = JSON.parse(readFileSync(inputPath, "utf8"));
+        // Use the attached type guard for clearer intent and narrower runtime checks
         if (!SysProMDocument.is(raw)) {
             const result = SysProMDocument.safeParse(raw);
             if (!result.success) {
@@ -36,7 +62,22 @@ export const json2mdCommand = {
         const form = opts.singleFile || outputPath.endsWith(".md")
             ? "single-file"
             : "multi-doc";
-        jsonToMarkdown(raw, outputPath, { form });
+        // Forward per-diagram layout overrides via environment-like flags.
+        // We accept flags on the command line for common diagram layouts but also
+        // preserve sensible per-diagram defaults in jsonToMarkdown when not set.
+        // For now we expose a single --label-mode flag and keep per-diagram layout
+        // defaults internal; a future enhancement could expose per-diagram
+        // flags such as --relationship-layout, --dependency-layout, etc.
+        jsonToMarkdown(raw, outputPath, {
+            form,
+            embedDiagrams: opts.embedDiagrams,
+            // forward labelMode for embedded diagrams (default friendly)
+            labelMode: opts.labelMode ?? "friendly",
+            relationshipLayout: opts.relationshipLayout,
+            refinementLayout: opts.refinementLayout,
+            decisionLayout: opts.decisionLayout,
+            dependencyLayout: opts.dependencyLayout,
+        });
         if (form === "single-file") {
             console.log(`Written to ${outputPath}`);
         }

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

@@ -4,5 +4,5 @@ declare const optsSchema: z.ZodObject<{
     input: z.ZodString;
     output: z.ZodString;
 }, z.core.$strict>;
-export declare const md2jsonCommand: CommandDef<z.ZodObject<z.ZodRawShape>, typeof optsSchema>;
+export declare const md2jsonCommand: CommandDef<z.ZodObject, typeof optsSchema>;
 export {};

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

@@ -7,43 +7,41 @@ import { NodeType, NodeStatus } from "../../schema.js";
 // ---------------------------------------------------------------------------
 // Presentation helpers
 // ---------------------------------------------------------------------------
-function printNode(r, verbose) {
-    if (verbose) {
-        console.log(`${pc.cyan(r.id)} — ${pc.bold(r.name)}`);
-        console.log(`  ${pc.dim("Type")}: ${r.type}`);
-        if (r.status)
-            console.log(`  ${pc.dim("Status")}: ${pc.yellow(r.status)}`);
-        if (r.description)
-            console.log(`  ${pc.dim("Description")}: ${textToString(r.description)}`);
-        if (r.context)
-            console.log(`  ${pc.dim("Context")}: ${textToString(r.context)}`);
-        if (r.rationale)
-            console.log(`  ${pc.dim("Rationale")}: ${textToString(r.rationale)}`);
-        if (r.selected)
-            console.log(`  ${pc.dim("Selected")}: ${r.selected}`);
-        if (r.options) {
-            console.log(`  ${pc.dim("Options")}:`);
-            for (const o of r.options)
-                console.log(`    ${o.id}: ${textToString(o.description)}`);
-        }
-        if (r.scope)
-            console.log(`  ${pc.dim("Scope")}: ${r.scope.join(", ")}`);
-        if (r.lifecycle) {
-            const states = Object.entries(r.lifecycle)
-                .map(([k, v]) => `${k}=${String(v)}`)
-                .join(", ");
-            console.log(`  ${pc.dim("Lifecycle")}: ${states}`);
-        }
-        if (r.includes)
-            console.log(`  ${pc.dim("Includes")}: ${r.includes.join(", ")}`);
-        console.log("");
+function printNodeCompact(r) {
+    const desc = r.description
+        ? " — " + textToString(r.description).slice(0, 60)
+        : "";
+    console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)}${desc}`);
+}
+function printNodeVerbose(r) {
+    console.log(`${pc.cyan(r.id)} — ${pc.bold(r.name)}`);
+    console.log(`  ${pc.dim("Type")}: ${r.type}`);
+    if (r.status)
+        console.log(`  ${pc.dim("Status")}: ${pc.yellow(r.status)}`);
+    if (r.description)
+        console.log(`  ${pc.dim("Description")}: ${textToString(r.description)}`);
+    if (r.context)
+        console.log(`  ${pc.dim("Context")}: ${textToString(r.context)}`);
+    if (r.rationale)
+        console.log(`  ${pc.dim("Rationale")}: ${textToString(r.rationale)}`);
+    if (r.selected)
+        console.log(`  ${pc.dim("Selected")}: ${r.selected}`);
+    if (r.options) {
+        console.log(`  ${pc.dim("Options")}:`);
+        for (const o of r.options)
+            console.log(`    ${o.id}: ${textToString(o.description)}`);
     }
-    else {
-        const desc = r.description
-            ? " — " + textToString(r.description).slice(0, 60)
-            : "";
-        console.log(`${pc.cyan(r.id.padEnd(12))} ${pc.dim(r.type.padEnd(16))} ${pc.bold(r.name)}${desc}`);
+    if (r.scope)
+        console.log(`  ${pc.dim("Scope")}: ${r.scope.join(", ")}`);
+    if (r.lifecycle) {
+        const states = Object.entries(r.lifecycle)
+            .map(([k, v]) => `${k}=${String(v)}`)
+            .join(", ");
+        console.log(`  ${pc.dim("Lifecycle")}: ${states}`);
     }
+    if (r.includes)
+        console.log(`  ${pc.dim("Includes")}: ${r.includes.join(", ")}`);
+    console.log("");
 }
 function isTraceTreeNode(value) {
     if (typeof value !== "object" || value === null)
@@ -103,7 +101,7 @@ const nodesSubcommand = {
         }
         else {
             for (const n of nodes)
-                printNode(n, false);
+                printNodeCompact(n);
             console.log(`\n${String(nodes.length)} node(s)`);
         }
     },
@@ -127,7 +125,7 @@ const nodeSubcommand = {
             console.log(JSON.stringify(result.node, null, 2));
         }
         else {
-            printNode(result.node, true);
+            printNodeVerbose(result.node);
             if (result.outgoing.length > 0) {
                 console.log(`${pc.dim("Outgoing relationships")}:`);
                 for (const r of result.outgoing)

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

@@ -18,6 +18,82 @@ function detectFormat(outputPath) {
     }
     return "json"; // default
 }
+/**
+ * Validate that both paths exist, exits with error if not.
+ * @param inputPath - Path to SysProM document
+ * @param specKitDir - Path to Spec-Kit directory
+ * @example
+ * ```ts
+ * validatePaths(inputPath, specKitDir);
+ * ```
+ */
+function validatePaths(inputPath, specKitDir) {
+    if (!existsSync(inputPath)) {
+        console.error(`Error: Input file does not exist: ${inputPath}`);
+        process.exit(1);
+    }
+    if (!existsSync(specKitDir)) {
+        console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
+        process.exit(1);
+    }
+}
+/**
+ * Search up to 5 parent directories for Spec-Kit constitution file.
+ * @param specKitDir - Path to Spec-Kit directory to start search from
+ * @returns Path to constitution file if found, undefined otherwise
+ * @example
+ * ```ts
+ * const path = findConstitutionPath(specKitDir);
+ * ```
+ */
+function findConstitutionPath(specKitDir) {
+    let searchDir = dirname(specKitDir);
+    for (let i = 0; i < 5; i++) {
+        const project = detectSpecKitProject(searchDir);
+        if (project.constitutionPath)
+            return project.constitutionPath;
+        const parent = dirname(searchDir);
+        if (parent === searchDir)
+            break;
+        searchDir = parent;
+    }
+    return undefined;
+}
+/**
+ * Print diff results in human-readable format.
+ * @param diff - The diff structure containing added, modified, and removed nodes
+ * @example
+ * ```ts
+ * printDiffResults(diff);
+ * ```
+ */
+function printDiffResults(diff) {
+    console.log(`Diff between SysProM document and Spec-Kit directory:`);
+    if (diff.added.length === 0 &&
+        diff.modified.length === 0 &&
+        diff.removed.length === 0) {
+        console.log(`  (no changes)`);
+        return;
+    }
+    if (diff.added.length > 0) {
+        console.log(`  Added: ${String(diff.added.length)} node(s)`);
+        for (const node of diff.added) {
+            console.log(`    - ${node.id}: ${node.name}`);
+        }
+    }
+    if (diff.modified.length > 0) {
+        console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
+        for (const { old } of diff.modified) {
+            console.log(`    - ${old.id}: ${old.name}`);
+        }
+    }
+    if (diff.removed.length > 0) {
+        console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
+        for (const node of diff.removed) {
+            console.log(`    - ${node.id}: ${node.name}`);
+        }
+    }
+}
 function compareDocuments(oldDoc, newDoc) {
     const oldNodes = new Map(oldDoc.nodes.map((n) => [n.id, n]));
     const newNodes = new Map(newDoc.nodes.map((n) => [n.id, n]));
@@ -134,32 +210,10 @@ const syncSubcommand = {
     action(_args, opts) {
         const inputPath = resolve(opts.input);
         const specKitDir = resolve(opts.speckitDir);
-        if (!existsSync(inputPath)) {
-            console.error(`Error: Input file does not exist: ${inputPath}`);
-            process.exit(1);
-        }
-        if (!existsSync(specKitDir)) {
-            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
-            process.exit(1);
-        }
-        // Determine the prefix: use flag if provided, otherwise use directory name
+        validatePaths(inputPath, specKitDir);
         const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
-        // Load SysProM document
         const { doc: syspromDoc, format } = loadDocument(inputPath);
-        // Find constitution file
-        let constitutionPath;
-        let searchDir = dirname(specKitDir);
-        for (let i = 0; i < 5; i++) {
-            const project = detectSpecKitProject(searchDir);
-            if (project.constitutionPath) {
-                constitutionPath = project.constitutionPath;
-                break;
-            }
-            const parent = dirname(searchDir);
-            if (parent === searchDir)
-                break;
-            searchDir = parent;
-        }
+        const constitutionPath = findConstitutionPath(specKitDir);
         // Parse Spec-Kit feature
         const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
         // Compare documents
@@ -232,63 +286,13 @@ const diffSubcommand = {
     action(_args, opts) {
         const inputPath = resolve(opts.input);
         const specKitDir = resolve(opts.speckitDir);
-        if (!existsSync(inputPath)) {
-            console.error(`Error: Input file does not exist: ${inputPath}`);
-            process.exit(1);
-        }
-        if (!existsSync(specKitDir)) {
-            console.error(`Error: Spec-Kit directory does not exist: ${specKitDir}`);
-            process.exit(1);
-        }
-        // Determine the prefix: use flag if provided, otherwise use directory name
+        validatePaths(inputPath, specKitDir);
         const idPrefix = opts.prefix ?? specKitDir.split("/").pop() ?? "FEAT";
-        // Load SysProM document
         const { doc: syspromDoc } = loadDocument(inputPath);
-        // Find constitution file
-        let constitutionPath;
-        let searchDir = dirname(specKitDir);
-        for (let i = 0; i < 5; i++) {
-            const project = detectSpecKitProject(searchDir);
-            if (project.constitutionPath) {
-                constitutionPath = project.constitutionPath;
-                break;
-            }
-            const parent = dirname(searchDir);
-            if (parent === searchDir)
-                break;
-            searchDir = parent;
-        }
-        // Parse Spec-Kit feature
+        const constitutionPath = findConstitutionPath(specKitDir);
         const specKitDoc = parseSpecKitFeature(specKitDir, idPrefix, constitutionPath);
-        // Compare documents
         const diff = compareDocuments(syspromDoc, specKitDoc);
-        // Print what would change (read-only)
-        console.log(`Diff between SysProM document and Spec-Kit directory:`);
-        if (diff.added.length === 0 &&
-            diff.modified.length === 0 &&
-            diff.removed.length === 0) {
-            console.log(`  (no changes)`);
-        }
-        else {
-            if (diff.added.length > 0) {
-                console.log(`  Added: ${String(diff.added.length)} node(s)`);
-                for (const node of diff.added) {
-                    console.log(`    - ${node.id}: ${node.name}`);
-                }
-            }
-            if (diff.modified.length > 0) {
-                console.log(`  Modified: ${String(diff.modified.length)} node(s)`);
-                for (const { old } of diff.modified) {
-                    console.log(`    - ${old.id}: ${old.name}`);
-                }
-            }
-            if (diff.removed.length > 0) {
-                console.log(`  Removed: ${String(diff.removed.length)} node(s)`);
-                for (const node of diff.removed) {
-                    console.log(`    - ${node.id}: ${node.name}`);
-                }
-            }
-        }
+        printDiffResults(diff);
     },
 };
 // ============================================================================

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

@@ -12,13 +12,13 @@ export const statsCommand = {
         console.log(`${pc.bold("SysProM Document")}: ${s.title}`);
         console.log("");
         console.log(pc.bold("Nodes by type:"));
-        for (const [type, count] of Object.entries(s.nodesByType).sort()) {
+        for (const [type, count] of Object.entries(s.nodesByType).sort(([a], [b]) => a.localeCompare(b))) {
             console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
         }
         console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalNodes))}`);
         console.log("");
         console.log(pc.bold("Relationships by type:"));
-        for (const [type, count] of Object.entries(s.relationshipsByType).sort()) {
+        for (const [type, count] of Object.entries(s.relationshipsByType).sort(([a], [b]) => a.localeCompare(b))) {
             console.log(`  ${type.padEnd(20)} ${pc.cyan(String(count))}`);
         }
         console.log(`  ${"TOTAL".padEnd(20)} ${pc.cyan(String(s.totalRelationships))}`);
@@ -30,14 +30,14 @@ export const statsCommand = {
         if (Object.keys(s.decisionLifecycle).length > 0) {
             console.log("");
             console.log(pc.bold("Decision lifecycle:"));
-            for (const [state, count] of Object.entries(s.decisionLifecycle).sort()) {
+            for (const [state, count] of Object.entries(s.decisionLifecycle).sort(([a], [b]) => a.localeCompare(b))) {
                 console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
             }
         }
         if (Object.keys(s.changeLifecycle).length > 0) {
             console.log("");
             console.log(pc.bold("Change lifecycle:"));
-            for (const [state, count] of Object.entries(s.changeLifecycle).sort()) {
+            for (const [state, count] of Object.entries(s.changeLifecycle).sort(([a], [b]) => a.localeCompare(b))) {
                 console.log(`  ${state.padEnd(20)} ${pc.cyan(String(count))}`);
             }
         }

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

@@ -23,5 +23,5 @@ declare const syncOpts: z.ZodObject<{
     dryRun: z.ZodOptional<z.ZodBoolean>;
     report: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
-export declare const syncCommandDef: CommandDef<z.ZodObject<z.ZodRawShape>, typeof syncOpts>;
+export declare const syncCommandDef: CommandDef<z.ZodObject, typeof syncOpts>;
 export {};

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

@@ -6,21 +6,44 @@ import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 // CLI helper functions
 // ---------------------------------------------------------------------------
 function parseLifecycleValue(rawVal) {
-    if (rawVal === "true") {
+    if (rawVal === "true")
         return true;
-    }
-    if (rawVal === "false") {
+    if (rawVal === "false")
         return false;
-    }
-    if (/^\d{4}-\d{2}-\d{2}/.test(rawVal)) {
-        return rawVal; // ISO date string
-    }
+    if (/^\d{4}-\d{2}-\d{2}/.test(rawVal))
+        return rawVal;
     return rawVal;
 }
 function parseMetaValue(val) {
     const numVal = Number(val);
     return Number.isFinite(numVal) && val === String(numVal) ? numVal : val;
 }
+/**
+ * Parse lifecycle field updates from key=value format.
+ * @param nodeLifecycle - Optional existing lifecycle object from the node
+ * @param lifecycleArgs - Array of key=value strings to parse
+ * @returns Lifecycle object with parsed values, or null if no args
+ * @example
+ * ```ts
+ * const lifecycle = parseLifecycleFields(node.lifecycle, ["created=2026-01-01"]);
+ * ```
+ */
+function parseLifecycleFields(nodeLifecycle, lifecycleArgs) {
+    if (!lifecycleArgs.length)
+        return null;
+    const lifecycle = { ...nodeLifecycle };
+    for (const kv of lifecycleArgs) {
+        const eqIdx = kv.indexOf("=");
+        if (eqIdx < 0) {
+            console.error(`Invalid --lifecycle format: ${kv} (expected key=value)`);
+            process.exit(1);
+        }
+        const key = kv.slice(0, eqIdx);
+        const rawVal = kv.slice(eqIdx + 1);
+        lifecycle[key] = parseLifecycleValue(rawVal);
+    }
+    return lifecycle;
+}
 // ---------------------------------------------------------------------------
 // Arg/opt schemas
 // ---------------------------------------------------------------------------
@@ -80,19 +103,9 @@ const nodeSubcommand = {
             fields.context = opts.context;
         if (opts.rationale !== undefined)
             fields.rationale = opts.rationale;
-        if (opts.lifecycle && opts.lifecycle.length > 0) {
-            const lifecycle = { ...node.lifecycle };
-            for (const kv of opts.lifecycle) {
-                const eqIdx = kv.indexOf("=");
-                if (eqIdx < 0) {
-                    console.error(`Invalid --lifecycle format: ${kv} (expected key=value)`);
-                    process.exit(1);
-                }
-                const key = kv.slice(0, eqIdx);
-                const rawVal = kv.slice(eqIdx + 1);
-                lifecycle[key] = parseLifecycleValue(rawVal);
-            }
-            fields.lifecycle = lifecycle;
+        const lifecycleFields = parseLifecycleFields(node.lifecycle, opts.lifecycle ?? []);
+        if (lifecycleFields) {
+            fields.lifecycle = lifecycleFields;
         }
         if (Object.keys(fields).length === 0) {
             console.error("No fields specified to update.");