sysprom 1.21.2 → 1.22.1

package/dist/src/speckit/plan.js

@@ -1,4 +1,5 @@
 import { textToString } from "../text.js";
+import { hasLifecycleState } from "../lifecycle-state.js";
 // ============================================================================
 // Helper functions
 // ============================================================================
@@ -279,7 +280,7 @@ export function addTask(doc, prefix, name, parentId) {
             id: changeId,
             type: "change",
             name: taskName,
-            plan: [],
+            lifecycle: { proposed: true },
         };
         // Build new relationships
         const newRels = [];
@@ -353,7 +354,7 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
                 id: changeId,
                 type: "change",
                 name: childName,
-                plan: [],
+                lifecycle: { proposed: true },
             };
             // Build new relationships for child
             const newRels = [];
@@ -449,41 +450,144 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
         nodes: updatedNodes,
     };
 }
+/**
+ * Set lifecycle state on a task (change node) within a plan implementation protocol.
+ *
+ * - start: marks introduced + in_progress true
+ * - complete: marks complete true and clears in_progress
+ * - reopen: clears complete and marks in_progress true
+ */
+export function setTaskLifecycle(doc, prefix, taskId, action) {
+    const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
+    if (!protImpl?.subsystem) {
+        throw new Error(`Node ${prefix}-PROT-IMPL not found`);
+    }
+    function updateInSubsystem(subsystem) {
+        let found = false;
+        const updatedNodes = subsystem.nodes.map((node) => {
+            if (node.id === taskId) {
+                if (node.type !== "change") {
+                    throw new Error(`Task node ${taskId} is not a change node`);
+                }
+                found = true;
+                const lifecycle = { ...(node.lifecycle ?? {}) };
+                if (action === "start") {
+                    lifecycle.introduced = lifecycle.introduced ?? true;
+                    lifecycle.in_progress = true;
+                }
+                else if (action === "complete") {
+                    lifecycle.complete = true;
+                    delete lifecycle.in_progress;
+                }
+                else {
+                    delete lifecycle.complete;
+                    lifecycle.in_progress = true;
+                }
+                return {
+                    ...node,
+                    lifecycle,
+                };
+            }
+            if (!node.subsystem) {
+                return node;
+            }
+            const child = updateInSubsystem(node.subsystem);
+            if (child.found) {
+                found = true;
+                return {
+                    ...node,
+                    subsystem: child.updated,
+                };
+            }
+            return node;
+        });
+        return {
+            found,
+            updated: {
+                ...(subsystem.metadata ? { metadata: subsystem.metadata } : {}),
+                nodes: updatedNodes,
+                ...(subsystem.relationships
+                    ? { relationships: subsystem.relationships }
+                    : {}),
+                ...(subsystem.external_references
+                    ? { external_references: subsystem.external_references }
+                    : {}),
+            },
+        };
+    }
+    const updated = updateInSubsystem(protImpl.subsystem);
+    if (!updated.found) {
+        throw new Error(`Task ${taskId} not found in ${prefix}-PROT-IMPL`);
+    }
+    const updatedNodes = doc.nodes.map((node) => node.id === protImpl.id
+        ? { ...protImpl, subsystem: updated.updated }
+        : node);
+    return {
+        ...doc,
+        nodes: updatedNodes,
+    };
+}
 // ============================================================================
 // isTaskDone
 // ============================================================================
 /**
- * Check if a change node's task is complete.
- *
- * If no subsystem or no change children in subsystem:
- *   - All items in node.plan must have done === true AND at least one item must exist.
- * If subsystem has change children:
- *   - All children must be recursively done AND own plan items (if any) must be done.
+ * Check if a task change node is complete.
  * @param node - The change node to evaluate.
- * @returns Whether all tasks in the node's plan are complete.
+ * @returns Whether the task lifecycle includes complete.
  * @example
  * ```ts
- * isTaskDone(changeNode); // => true if all plan items done
+ * isTaskDone(changeNode); // => true when lifecycle.complete is reached
  * ```
  */
 export function isTaskDone(node) {
-    // If the node has a subsystem with change children, check those recursively
-    if (node.subsystem) {
-        const changeChildren = node.subsystem.nodes.filter((n) => n.type === "change");
-        if (changeChildren.length > 0) {
-            // All change children must be done, and own plan items must be done
-            const allChildrenDone = changeChildren.every((child) => isTaskDone(child));
-            const ownPlanDone = (node.plan ?? []).length === 0 ||
-                (node.plan ?? []).every((item) => item.done === true);
-            return allChildrenDone && ownPlanDone;
+    return hasLifecycleState(node, "complete");
+}
+function isGateReady(node) {
+    if (node.type !== "gate")
+        return false;
+    const lifecycle = node.lifecycle ?? {};
+    const values = Object.values(lifecycle);
+    if (values.length === 0)
+        return false;
+    return values.every((value) => value === true || typeof value === "string");
+}
+function collectNodes(subsystem) {
+    if (!subsystem)
+        return [];
+    const nodes = [];
+    for (const node of subsystem.nodes) {
+        nodes.push(node);
+        if (node.subsystem) {
+            nodes.push(...collectNodes(node.subsystem));
         }
     }
-    // No subsystem or no change children: check own plan
-    const planItems = node.plan ?? [];
-    if (planItems.length === 0) {
-        return false;
+    return nodes;
+}
+function taskBlockageReasons(doc, subsystem, taskNode) {
+    if (taskNode.type !== "change")
+        return [];
+    const relationships = subsystem?.relationships ?? [];
+    const scopedNodeMap = new Map((subsystem?.nodes ?? []).map((n) => [n.id, n]));
+    const globalNodeMap = new Map(doc.nodes.map((n) => [n.id, n]));
+    const reasons = [];
+    for (const rel of relationships) {
+        if (rel.from !== taskNode.id || rel.type !== "depends_on")
+            continue;
+        const dependency = scopedNodeMap.get(rel.to) ?? globalNodeMap.get(rel.to);
+        const dependencyComplete = dependency?.type === "change" && isTaskDone(dependency);
+        if (!dependencyComplete) {
+            reasons.push({ kind: "dependency_unmet", nodeId: rel.to });
+        }
     }
-    return planItems.every((item) => item.done === true);
+    for (const rel of relationships) {
+        if (rel.from !== taskNode.id || rel.type !== "constrained_by")
+            continue;
+        const gate = scopedNodeMap.get(rel.to) ?? globalNodeMap.get(rel.to);
+        if (!gate || !isGateReady(gate)) {
+            reasons.push({ kind: "gate_not_ready", nodeId: rel.to });
+        }
+    }
+    return reasons;
 }
 // ============================================================================
 // countTasks
@@ -501,22 +605,49 @@ export function isTaskDone(node) {
  * ```
  */
 export function countTasks(node) {
+    if (node.type !== "change") {
+        return { total: 0, done: 0, blocked: 0, blockedTasks: [] };
+    }
+    const localDoc = {
+        nodes: [node, ...collectNodes(node.subsystem)],
+        relationships: [],
+    };
+    return countTasksInSubsystem(localDoc, {
+        nodes: [node],
+        relationships: [],
+    });
+}
+function countTasksInSubsystem(doc, subsystem) {
     let total = 0;
     let done = 0;
-    // Count own plan items
-    const ownPlan = node.plan ?? [];
-    total += ownPlan.length;
-    done += ownPlan.filter((item) => item.done === true).length;
-    // Recursively count from change children in subsystem
-    if (node.subsystem) {
-        const changeChildren = node.subsystem.nodes.filter((n) => n.type === "change");
-        for (const child of changeChildren) {
-            const childCount = countTasks(child);
-            total += childCount.total;
-            done += childCount.done;
+    let blocked = 0;
+    const blockedTasks = [];
+    if (!subsystem) {
+        return { total, done, blocked, blockedTasks };
+    }
+    for (const node of subsystem.nodes) {
+        if (node.type !== "change")
+            continue;
+        const childChanges = (node.subsystem?.nodes ?? []).filter((child) => child.type === "change");
+        if (childChanges.length > 0) {
+            const childCounts = countTasksInSubsystem(doc, node.subsystem);
+            total += childCounts.total;
+            done += childCounts.done;
+            blocked += childCounts.blocked;
+            blockedTasks.push(...childCounts.blockedTasks);
+            continue;
+        }
+        total += 1;
+        if (isTaskDone(node)) {
+            done += 1;
+        }
+        const reasons = taskBlockageReasons(doc, subsystem, node);
+        if (reasons.length > 0) {
+            blocked += 1;
+            blockedTasks.push({ taskId: node.id, reasons });
         }
     }
-    return { total, done };
+    return { total, done, blocked, blockedTasks };
 }
 // ============================================================================
 // planStatus
@@ -543,15 +674,10 @@ export function planStatus(doc, prefix) {
         .map((us) => us.id);
     // Count phases (top-level change nodes)
     const phaseCount = (protImpl?.subsystem?.nodes ?? []).filter((n) => n.type === "change").length;
-    // Count tasks using the helper
-    let totalTasks = 0;
-    let doneTasks = 0;
-    const changeNodes = (protImpl?.subsystem?.nodes ?? []).filter((n) => n.type === "change");
-    for (const change of changeNodes) {
-        const taskCount = countTasks(change);
-        totalTasks += taskCount.total;
-        doneTasks += taskCount.done;
-    }
+    const taskCounts = countTasksInSubsystem(doc, protImpl?.subsystem);
+    const totalTasks = taskCounts.total;
+    const doneTasks = taskCounts.done;
+    const blockedTasks = taskCounts.blocked;
     // Checklist stats
     const checklistLifecycle = checklist?.lifecycle ?? {};
     const checklistItemCount = Object.keys(checklistLifecycle).length;
@@ -614,6 +740,8 @@ export function planStatus(doc, prefix) {
         tasks: {
             total: totalTasks,
             done: doneTasks,
+            blocked: blockedTasks,
+            blockedTasks: taskCounts.blockedTasks,
         },
         checklist: {
             defined: checklist !== null,
@@ -649,17 +777,23 @@ export function planProgress(doc, prefix) {
     for (let i = 0; i < sortedTasks.length; i++) {
         const task = sortedTasks[i];
         const taskNum = i + 1;
-        // Count tasks for this change node
-        const taskCount = countTasks(task);
+        const taskCount = countTasksInSubsystem(doc, {
+            nodes: [task],
+            relationships: task.subsystem?.relationships ?? [],
+        });
+        const reasons = taskBlockageReasons(doc, subsystem, task);
         const percent = taskCount.total === 0
             ? 0
             : Math.round((taskCount.done / taskCount.total) * 100);
         result.push({
             phase: taskNum,
+            id: task.id,
             name: task.name,
             done: taskCount.done,
             total: taskCount.total,
             percent,
+            blocked: reasons.length > 0,
+            blockageReasons: reasons,
         });
     }
     return result;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sysprom",
-	"version": "1.21.2",
+	"version": "1.22.1",
 	"description": "SysProM — System Provenance Model CLI and library",
 	"author": "ExaDev",
 	"homepage": "https://exadev.github.io/SysProM",

package/schema.json

@@ -302,37 +302,6 @@
 						},
 						"type": "array"
 					},
-					"plan": {
-						"description": "Execution plan as a sequence of tasks. Applicable to change nodes.",
-						"items": {
-							"additionalProperties": {},
-							"description": "A single task within a change's execution plan.",
-							"properties": {
-								"description": {
-									"anyOf": [
-										{
-											"type": "string"
-										},
-										{
-											"items": {
-												"type": "string"
-											},
-											"type": "array"
-										}
-									]
-								},
-								"done": {
-									"default": false,
-									"type": "boolean"
-								}
-							},
-							"required": [
-								"description"
-							],
-							"type": "object"
-						},
-						"type": "array"
-					},
 					"propagation": {
 						"additionalProperties": {
 							"type": "boolean"

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

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

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

@@ -1,157 +0,0 @@
-import * as z from "zod";
-import { loadDoc, mutationOpts, persistDoc } from "../shared.js";
-import { addPlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, } from "../../operations/index.js";
-// ============================================================================
-// Subcommands
-// ============================================================================
-const listOpts = mutationOpts.pick({ path: true, json: true }).extend({
-    change: z.string().optional().describe("Filter by change ID"),
-    pending: z.boolean().optional().describe("Show only pending tasks"),
-});
-const listSubcommand = {
-    name: "list",
-    description: taskListOp.def.description,
-    apiLink: taskListOp.def.name,
-    opts: listOpts,
-    action(_args, opts) {
-        const { doc } = loadDoc(opts.path);
-        try {
-            const rows = taskListOp({
-                doc,
-                changeId: opts.change,
-                pendingOnly: opts.pending,
-            });
-            if (opts.json) {
-                console.log(JSON.stringify(rows, null, 2));
-                return;
-            }
-            const header = `${"Change".padEnd(12)} ${"#".padEnd(4)} ${"Done".padEnd(6)} Description`;
-            const divider = `${"-".repeat(12)} ${"-".repeat(4)} ${"-".repeat(6)} ${"-".repeat(30)}`;
-            console.log(header);
-            console.log(divider);
-            for (const row of rows) {
-                const doneStr = row.done ? "[x]" : "[ ]";
-                console.log(`${row.changeId.padEnd(12)} ${String(row.index).padEnd(4)} ${doneStr.padEnd(6)} ${row.description}`);
-            }
-            console.log(`\n${String(rows.length)} task(s)`);
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    },
-};
-const addArgs = z.object({
-    changeId: z.string().describe("Change node ID"),
-    description: z.string().describe("Task description"),
-});
-const addOpts = mutationOpts.pick({ path: true });
-const addSubcommand = {
-    name: "add",
-    description: addPlanTaskOp.def.description,
-    apiLink: addPlanTaskOp.def.name,
-    args: addArgs,
-    opts: addOpts,
-    action(args, opts) {
-        const loaded = loadDoc(opts.path);
-        const { doc } = loaded;
-        try {
-            const newDoc = addPlanTaskOp({
-                doc,
-                changeId: args.changeId,
-                description: args.description,
-            });
-            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
-            const node = newDoc.nodes.find((n) => n.id === args.changeId);
-            if (!node)
-                throw new Error(`Node ${args.changeId} not found`);
-            const newIndex = (node.plan?.length ?? 1) - 1;
-            console.log(`Added task ${String(newIndex)} to ${args.changeId}`);
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    },
-};
-const doneArgs = z.object({
-    changeId: z.string().describe("Change node ID"),
-    taskIndex: z.string().describe("Task index"),
-});
-const doneOpts = mutationOpts.pick({ path: true });
-const doneSubcommand = {
-    name: "done",
-    description: markTaskDoneOp.def.description,
-    apiLink: markTaskDoneOp.def.name,
-    args: doneArgs,
-    opts: doneOpts,
-    action(args, opts) {
-        const loaded = loadDoc(opts.path);
-        const { doc } = loaded;
-        const taskIndex = parseInt(args.taskIndex, 10);
-        if (isNaN(taskIndex) || taskIndex < 0) {
-            console.error(`Invalid task index: ${args.taskIndex}`);
-            process.exit(1);
-        }
-        try {
-            const newDoc = markTaskDoneOp({
-                doc,
-                changeId: args.changeId,
-                taskIndex,
-            });
-            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
-            console.log(`Marked task ${String(taskIndex)} done on ${args.changeId}`);
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    },
-};
-const undoneArgs = z.object({
-    changeId: z.string().describe("Change node ID"),
-    taskIndex: z.string().describe("Task index"),
-});
-const undoneOpts = mutationOpts.pick({ path: true });
-const undoneSubcommand = {
-    name: "undone",
-    description: markTaskUndoneOp.def.description,
-    apiLink: markTaskUndoneOp.def.name,
-    args: undoneArgs,
-    opts: undoneOpts,
-    action(args, opts) {
-        const loaded = loadDoc(opts.path);
-        const { doc } = loaded;
-        const taskIndex = parseInt(args.taskIndex, 10);
-        if (isNaN(taskIndex) || taskIndex < 0) {
-            console.error(`Invalid task index: ${args.taskIndex}`);
-            process.exit(1);
-        }
-        try {
-            const newDoc = markTaskUndoneOp({
-                doc,
-                changeId: args.changeId,
-                taskIndex,
-            });
-            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
-            console.log(`Marked task ${String(taskIndex)} undone on ${args.changeId}`);
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-    },
-};
-// ============================================================================
-// Main command
-// ============================================================================
-export const taskCommand = {
-    name: "task",
-    description: "Manage tasks within change nodes",
-    subcommands: [
-        listSubcommand,
-        addSubcommand,
-        doneSubcommand,
-        undoneSubcommand,
-    ],
-};

package/dist/src/operations/add-plan-task.js

@@ -1,29 +0,0 @@
-import * as z from "zod";
-import { defineOperation } from "./define-operation.js";
-import { SysProMDocument } from "../schema.js";
-/**
- * Append a new task to a change node's plan array. Returns a new document with the task added.
- * @throws {Error} If the change node is not found.
- */
-export const addPlanTaskOp = defineOperation({
-    name: "addPlanTask",
-    description: "Append a new task to a change node's plan array. Returns a new document.",
-    input: z.object({
-        doc: SysProMDocument,
-        changeId: z.string(),
-        description: z.string(),
-    }),
-    output: SysProMDocument,
-    fn({ doc, changeId, description }) {
-        const node = doc.nodes.find((n) => n.id === changeId);
-        if (!node) {
-            throw new Error(`Node not found: ${changeId}`);
-        }
-        const newTask = { description, done: false };
-        const updatedNode = { ...node, plan: [...(node.plan ?? []), newTask] };
-        const newNodes = [...doc.nodes];
-        const idx = newNodes.findIndex((n) => n.id === changeId);
-        newNodes[idx] = updatedNode;
-        return { ...doc, nodes: newNodes };
-    },
-});

package/dist/src/operations/mark-task-done.js

@@ -1,30 +0,0 @@
-import * as z from "zod";
-import { defineOperation } from "./define-operation.js";
-import { SysProMDocument } from "../schema.js";
-/**
- * Mark a task as done within a change node's plan.
- * @throws {Error} If the change node is not found or the task index is out of range.
- */
-export const markTaskDoneOp = defineOperation({
-    name: "markTaskDone",
-    description: "Mark a task as done",
-    input: z.object({
-        doc: SysProMDocument,
-        changeId: z.string().describe("ID of the change node"),
-        taskIndex: z.number().describe("Zero-based index of the task in the plan"),
-    }),
-    output: SysProMDocument,
-    fn: (input) => {
-        const node = input.doc.nodes.find((n) => n.id === input.changeId);
-        if (!node)
-            throw new Error(`Node not found: ${input.changeId}`);
-        const plan = node.plan ?? [];
-        if (input.taskIndex < 0 || input.taskIndex >= plan.length) {
-            throw new Error(`Task index ${String(input.taskIndex)} out of range (plan has ${String(plan.length)} task(s))`);
-        }
-        const newPlan = [...plan];
-        newPlan[input.taskIndex] = { ...newPlan[input.taskIndex], done: true };
-        const newNodes = input.doc.nodes.map((n) => n.id === input.changeId ? { ...n, plan: newPlan } : n);
-        return { ...input.doc, nodes: newNodes };
-    },
-});

package/dist/src/operations/mark-task-undone.js

@@ -1,30 +0,0 @@
-import * as z from "zod";
-import { defineOperation } from "./define-operation.js";
-import { SysProMDocument } from "../schema.js";
-/**
- * Mark a task as undone (incomplete) within a change node's plan.
- * @throws {Error} If the change node is not found or the task index is out of range.
- */
-export const markTaskUndoneOp = defineOperation({
-    name: "markTaskUndone",
-    description: "Mark a task as undone",
-    input: z.object({
-        doc: SysProMDocument,
-        changeId: z.string().describe("ID of the change node"),
-        taskIndex: z.number().describe("Zero-based index of the task in the plan"),
-    }),
-    output: SysProMDocument,
-    fn: (input) => {
-        const node = input.doc.nodes.find((n) => n.id === input.changeId);
-        if (!node)
-            throw new Error(`Node not found: ${input.changeId}`);
-        const plan = node.plan ?? [];
-        if (input.taskIndex < 0 || input.taskIndex >= plan.length) {
-            throw new Error(`Task index ${String(input.taskIndex)} out of range (plan has ${String(plan.length)} task(s))`);
-        }
-        const newPlan = [...plan];
-        newPlan[input.taskIndex] = { ...newPlan[input.taskIndex], done: false };
-        const newNodes = input.doc.nodes.map((n) => n.id === input.changeId ? { ...n, plan: newPlan } : n);
-        return { ...input.doc, nodes: newNodes };
-    },
-});