sysprom 1.2.0 → 1.2.1

package/dist/src/schema.d.ts

@@ -930,6 +930,9 @@ export type Node = z.infer<typeof Node>;
 export declare const NODE_FILE_MAP: Record<string, string[]>;
 /** Conventional ID prefix for each node type. */
 export declare const NODE_ID_PREFIX: Record<string, string>;
-/** Generate the JSON Schema representation of the SysProM document schema. */
+/**
+ * Generate the JSON Schema representation of the SysProM document schema.
+ * @returns The JSON Schema object with Draft 2020-12 metadata.
+ */
 export declare function toJSONSchema(): Record<string, unknown>;
 export {};

package/dist/src/schema.js

@@ -371,7 +371,10 @@ export const NODE_ID_PREFIX = {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Generate the JSON Schema representation of the SysProM document schema. */
+/**
+ * Generate the JSON Schema representation of the SysProM document schema.
+ * @returns The JSON Schema object with Draft 2020-12 metadata.
+ */
 export function toJSONSchema() {
     const generated = z.toJSONSchema(SysProMDocument, {
         target: "draft-2020-12",

package/dist/src/speckit/generate.d.ts

@@ -1,13 +1,43 @@
 import type { SysProMDocument } from "../schema.js";
-/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
+/**
+ * Generate a Spec-Kit constitution file from a SysProM document's principles and invariants.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export declare function generateConstitution(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
+/**
+ * Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export declare function generateSpec(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
+/**
+ * Generate a Spec-Kit plan file from a SysProM document's phases and milestones.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export declare function generatePlan(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
+/**
+ * Generate a Spec-Kit tasks file from a SysProM document's change nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export declare function generateTasks(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
+/**
+ * Generate a Spec-Kit checklist file from a SysProM document's gate nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export declare function generateChecklist(doc: SysProMDocument, prefix: string): string;
-/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
+/**
+ * Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files.
+ * @param doc - The SysProM document.
+ * @param outputDir - Output directory path.
+ * @param prefix - ID prefix identifying nodes to include.
+ */
 export declare function generateSpecKitProject(doc: SysProMDocument, outputDir: string, prefix: string): void;

package/dist/src/speckit/generate.js

@@ -6,18 +6,28 @@ import { textToString } from "../text.js";
 // ============================================================================
 /**
  * Find a single node by ID, or null if not found.
+ * @param doc - The document to search.
+ * @param id - The node ID to find.
+ * @returns The matching node, or null.
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
 }
 /**
  * Find all nodes of a specific type.
+ * @param doc - The document to search.
+ * @param type - The node type to filter by.
+ * @returns Matching nodes.
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
 }
 /**
  * Find relationships from a source node to nodes of a target type.
+ * @param doc - The document to search.
+ * @param fromId - Source node ID.
+ * @param relationType - Optional relationship type filter.
+ * @returns Matching relationships.
  */
 function findRelationshipsFrom(doc, fromId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -30,6 +40,10 @@ function findRelationshipsFrom(doc, fromId, relationType) {
 }
 /**
  * Find relationships to a target node.
+ * @param doc - The document to search.
+ * @param toId - Target node ID.
+ * @param relationType - Optional relationship type filter.
+ * @returns Matching relationships.
  */
 function findRelationshipsTo(doc, toId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -43,6 +57,8 @@ function findRelationshipsTo(doc, toId, relationType) {
 /**
  * Extract priority from a node's name, description, or lifecycle fields.
  * Looks for patterns like "P1", "P2", "Priority: P1", etc.
+ * @param node - The node to extract priority from.
+ * @returns Priority string (e.g. "P1").
  */
 function extractPriority(node) {
     const text = [
@@ -57,6 +73,8 @@ function extractPriority(node) {
 }
 /**
  * Extract numeric suffix from an ID (e.g., "PREFIX-SPEC-001" -> "001").
+ * @param id - The node ID.
+ * @returns The numeric suffix.
  */
 function getIdSuffix(id) {
     const parts = id.split("-");
@@ -64,6 +82,8 @@ function getIdSuffix(id) {
 }
 /**
  * Parse tasks from a change node's plan array.
+ * @param node - The change node.
+ * @returns Array of task descriptions and done flags.
  */
 function parseTasks(node) {
     return (node.plan ?? []).map((task) => ({
@@ -73,6 +93,8 @@ function parseTasks(node) {
 }
 /**
  * Format the status for spec output: "proposed" -> "Draft", etc.
+ * @param status - The node status string.
+ * @returns Formatted status label.
  */
 function formatStatus(status) {
     if (!status)
@@ -87,7 +109,12 @@ function formatStatus(status) {
 // ============================================================================
 // generate Constitution
 // ============================================================================
-/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
+/**
+ * Generate a Spec-Kit constitution file from a SysProM document's principles and invariants.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export function generateConstitution(doc, prefix) {
     const protocolId = `${prefix}-CONST`;
     const protocol = findNode(doc, protocolId);
@@ -160,7 +187,12 @@ export function generateConstitution(doc, prefix) {
 // ============================================================================
 // generateSpec
 // ============================================================================
-/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
+/**
+ * Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export function generateSpec(doc, prefix) {
     const specId = `${prefix}-SPEC`;
     const spec = findNode(doc, specId);
@@ -274,7 +306,12 @@ export function generateSpec(doc, prefix) {
 // ============================================================================
 // generatePlan
 // ============================================================================
-/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
+/**
+ * Generate a Spec-Kit plan file from a SysProM document's phases and milestones.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export function generatePlan(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -325,7 +362,12 @@ export function generatePlan(doc, prefix) {
 // ============================================================================
 // generateTasks
 // ============================================================================
-/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
+/**
+ * Generate a Spec-Kit tasks file from a SysProM document's change nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export function generateTasks(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -465,7 +507,12 @@ export function generateTasks(doc, prefix) {
 // ============================================================================
 // generateChecklist
 // ============================================================================
-/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
+/**
+ * Generate a Spec-Kit checklist file from a SysProM document's gate nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ */
 export function generateChecklist(doc, prefix) {
     const gateId = `${prefix}-CHK`;
     const gate = findNode(doc, gateId);
@@ -520,7 +567,12 @@ export function generateChecklist(doc, prefix) {
 // ============================================================================
 // generateSpecKitProject
 // ============================================================================
-/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
+/**
+ * Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files.
+ * @param doc - The SysProM document.
+ * @param outputDir - Output directory path.
+ * @param prefix - ID prefix identifying nodes to include.
+ */
 export function generateSpecKitProject(doc, outputDir, prefix) {
     // Create output directory if it doesn't exist
     mkdirSync(outputDir, { recursive: true });

package/dist/src/speckit/parse.d.ts

@@ -6,15 +6,46 @@ export interface ParseResult {
     /** Relationships extracted from the parsed content. */
     relationships: Relationship[];
 }
-/** Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships. */
+/**
+ * Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export declare function parseConstitution(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria). */
+/**
+ * Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria).
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export declare function parseSpec(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships. */
+/**
+ * Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export declare function parsePlan(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit tasks file into SysProM change nodes with task plans. */
+/**
+ * Parse a Spec-Kit tasks file into SysProM change nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export declare function parseTasks(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit checklist file into SysProM gate nodes with task plans. */
+/**
+ * Parse a Spec-Kit checklist file into SysProM gate nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export declare function parseChecklist(content: string, idPrefix: string): ParseResult;
-/** Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist. */
+/**
+ * Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist.
+ * @param featureDir - Path to Spec-Kit feature directory.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @param constitutionPath - Path to constitution.md, or undefined.
+ * @returns The parsed SysProM document.
+ */
 export declare function parseSpecKitFeature(featureDir: string, idPrefix: string, constitutionPath?: string): SysProMDocument;

package/dist/src/speckit/parse.js

@@ -5,6 +5,8 @@ import { join, basename } from "node:path";
 // ---------------------------------------------------------------------------
 /**
  * Parse markdown content into a hierarchical section tree by heading level.
+ * @param body - Markdown body text.
+ * @returns The result.
  */
 function parseSections(body) {
     const lines = body.split("\n");
@@ -49,6 +51,8 @@ function parseSections(body) {
 }
 /**
  * Extract bold key-value pairs from markdown like "**Key**: value" or "**Key**: value text".
+ * @param content - Markdown file content.
+ * @returns The result.
  */
 function parseFrontMatterish(content) {
     const result = {};
@@ -64,6 +68,8 @@ function parseFrontMatterish(content) {
 }
 /**
  * Parse checkbox lines like "- [x] ID text" or "- [ ] ID text".
+ * @param body - Markdown body text.
+ * @returns The result.
  */
 function parseCheckboxes(body) {
     const items = [];
@@ -84,6 +90,8 @@ function parseCheckboxes(body) {
 }
 /**
  * Flatten all sections in the tree into a single array for easier searching.
+ * @param sections - Parsed section tree.
+ * @returns The result.
  */
 function flattenSections(sections) {
     const result = [];
@@ -98,12 +106,17 @@ function flattenSections(sections) {
 }
 /**
  * Find the first section whose heading matches a predicate (searches entire tree).
+ * @param sections - Parsed section tree.
+ * @param predicate - Filter function.
+ * @returns The result.
  */
 function findSection(sections, predicate) {
     return flattenSections(sections).find((s) => predicate(s.heading));
 }
 /**
  * Convert status-like strings to NodeStatus. Recognizes common spec-kit patterns.
+ * @param value - Raw status string.
+ * @returns The result.
  */
 function mapStatusValue(value) {
     const lower = value.toLowerCase().trim();
@@ -130,6 +143,9 @@ function mapStatusValue(value) {
 }
 /**
  * Extract a single line value from body text (e.g., "**Created**: 2025-01-01").
+ * @param body - Markdown body text.
+ * @param key - Front-matter key to extract.
+ * @returns The result.
  */
 function extractValue(body, key) {
     const pattern = new RegExp(`^\\*\\*${key}\\*\\*:\\s*(.+)$`, "m");
@@ -139,7 +155,12 @@ function extractValue(body, key) {
 // ---------------------------------------------------------------------------
 // constitution.md parser
 // ---------------------------------------------------------------------------
-/** Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships. */
+/**
+ * Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export function parseConstitution(content, idPrefix) {
     const sections = parseSections(content);
     const nodes = [];
@@ -228,7 +249,12 @@ export function parseConstitution(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // spec.md parser
 // ---------------------------------------------------------------------------
-/** Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria). */
+/**
+ * Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria).
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export function parseSpec(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -412,7 +438,12 @@ export function parseSpec(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // plan.md parser
 // ---------------------------------------------------------------------------
-/** Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships. */
+/**
+ * Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export function parsePlan(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -505,7 +536,12 @@ export function parsePlan(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // tasks.md parser
 // ---------------------------------------------------------------------------
-/** Parse a Spec-Kit tasks file into SysProM change nodes with task plans. */
+/**
+ * Parse a Spec-Kit tasks file into SysProM change nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export function parseTasks(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -611,7 +647,12 @@ export function parseTasks(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // checklist.md parser
 // ---------------------------------------------------------------------------
-/** Parse a Spec-Kit checklist file into SysProM gate nodes with task plans. */
+/**
+ * Parse a Spec-Kit checklist file into SysProM gate nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ */
 export function parseChecklist(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -660,7 +701,13 @@ export function parseChecklist(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // Full feature directory parser
 // ---------------------------------------------------------------------------
-/** Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist. */
+/**
+ * Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist.
+ * @param featureDir - Path to Spec-Kit feature directory.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @param constitutionPath - Path to constitution.md, or undefined.
+ * @returns The parsed SysProM document.
+ */
 export function parseSpecKitFeature(featureDir, idPrefix, constitutionPath) {
     const nodes = [];
     const relationships = [];

package/dist/src/speckit/plan.d.ts

@@ -74,6 +74,9 @@ export interface TaskCount {
  *   - {prefix}-CHK  governed_by  {prefix}-PROT-IMPL
  *
  * Tasks are not pre-scaffolded; use addTask to add them.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @returns The result.
  */
 export declare function initDocument(prefix: string, name: string): SysProMDocument;
 /**
@@ -88,6 +91,11 @@ export declare function initDocument(prefix: string, name: string): SysProMDocum
  *
  * Wires must_follow to previous sibling change node at the same level.
  * Default name: "Task N".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @param parentId - Parent task ID.
+ * @returns The result.
  */
 export declare function addTask(doc: SysProMDocument, prefix: string, name?: string, parentId?: string): SysProMDocument;
 /**
@@ -97,6 +105,8 @@ export declare function addTask(doc: SysProMDocument, prefix: string, name?: str
  *   - 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
+ * @param node - The node to check.
+ * @returns The result.
  */
 export declare function isTaskDone(node: Node): boolean;
 /**
@@ -104,16 +114,24 @@ export declare function isTaskDone(node: Node): boolean;
  *
  * Sums plan[] items from this node and recursively from all change nodes in
  * subsystem (and their subsystems).
+ * @param node - The node to check.
+ * @returns The result.
  */
 export declare function countTasks(node: Node): TaskCount;
 /**
  * Inspect a document and return workflow completeness for a given prefix.
  * Never throws — missing nodes are reported as "not defined".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
  */
 export declare function planStatus(doc: SysProMDocument, prefix: string): PlanStatus;
 /**
  * Return per-task completion data.
  * Tasks (change nodes) are discovered from PROT-IMPL.subsystem, sorted topologically.
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
  */
 export declare function planProgress(doc: SysProMDocument, prefix: string): PhaseProgress[];
 /**
@@ -126,5 +144,9 @@ export declare function planProgress(doc: SysProMDocument, prefix: string): Phas
  *
  * Additionally for phase N > 1:
  *   - All tasks in phase N-1 must be done
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param phase - Phase number (1-indexed).
+ * @returns Gate check result with readiness flag and issues.
  */
 export declare function checkGate(doc: SysProMDocument, prefix: string, phase: number): GateResult;

package/dist/src/speckit/plan.js

@@ -4,12 +4,18 @@ import { textToString } from "../text.js";
 // ============================================================================
 /**
  * Find a single node by ID, or null if not found.
+ * @param doc - The SysProM document.
+ * @param id - Node ID to find.
+ * @returns The result.
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
 }
 /**
  * Find a single node by ID in a subsystem, or null if not found.
+ * @param subsystem - The subsystem document.
+ * @param id - Node ID to find.
+ * @returns The result.
  */
 function findNodeInSubsystem(subsystem, id) {
     if (!subsystem)
@@ -18,12 +24,18 @@ function findNodeInSubsystem(subsystem, id) {
 }
 /**
  * Find all nodes of a specific type.
+ * @param doc - The SysProM document.
+ * @param type - Node type to filter by.
+ * @returns The result.
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
 }
 /**
  * Find all nodes of a specific type in a subsystem.
+ * @param subsystem - The subsystem document.
+ * @param type - Node type to filter by.
+ * @returns The result.
  */
 function findNodesByTypeInSubsystem(subsystem, type) {
     if (!subsystem)
@@ -32,6 +44,10 @@ function findNodesByTypeInSubsystem(subsystem, type) {
 }
 /**
  * Find relationships from a source node to nodes of a target type (within a subsystem).
+ * @param subsystem - The subsystem document.
+ * @param fromId - Source node ID.
+ * @param relationType - Relationship type filter.
+ * @returns The result.
  */
 function findRelationshipsFrom(subsystem, fromId, relationType) {
     if (!subsystem)
@@ -46,6 +62,10 @@ function findRelationshipsFrom(subsystem, fromId, relationType) {
 }
 /**
  * Find relationships to a target node (within a subsystem).
+ * @param subsystem - The subsystem document.
+ * @param toId - Target node ID.
+ * @param relationType - Relationship type filter.
+ * @returns The result.
  */
 function findRelationshipsTo(subsystem, toId, relationType) {
     if (!subsystem)
@@ -61,6 +81,8 @@ function findRelationshipsTo(subsystem, toId, relationType) {
 /**
  * Detect if a text contains non-placeholder acceptance criteria.
  * Looks for GIVEN/WHEN/THEN patterns (case-insensitive).
+ * @param description - Task description text.
+ * @returns The result.
  */
 function hasAcceptanceCriteria(description) {
     if (!description)
@@ -70,6 +92,9 @@ function hasAcceptanceCriteria(description) {
 }
 /**
  * Sort change nodes topologically using must_follow relationships.
+ * @param subsystem - The subsystem document.
+ * @param changeNodes - Array of change nodes.
+ * @returns The result.
  */
 function sortChangesByOrder(subsystem, changeNodes) {
     const subsystemToUse = subsystem ?? { nodes: [], relationships: [] };
@@ -122,6 +147,9 @@ function sortChangesByOrder(subsystem, changeNodes) {
  *   - {prefix}-CHK  governed_by  {prefix}-PROT-IMPL
  *
  * Tasks are not pre-scaffolded; use addTask to add them.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @returns The result.
  */
 export function initDocument(prefix, name) {
     const nodes = [
@@ -189,6 +217,11 @@ export function initDocument(prefix, name) {
  *
  * Wires must_follow to previous sibling change node at the same level.
  * Default name: "Task N".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @param parentId - Parent task ID.
+ * @returns The result.
  */
 export function addTask(doc, prefix, name, parentId) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -247,6 +280,12 @@ export function addTask(doc, prefix, name, parentId) {
 }
 /**
  * Helper function to recursively add a task to a parent change node's subsystem.
+ * @param doc - The SysProM document.
+ * @param protImpl - Implementation protocol node.
+ * @param prefix - Plan prefix.
+ * @param parentId - Parent task ID.
+ * @param name - Name for the new item.
+ * @returns The result.
  */
 function addTaskToParent(doc, protImpl, prefix, parentId, name) {
     // Find the parent change node in the subsystem tree
@@ -376,6 +415,8 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
  *   - 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
+ * @param node - The node to check.
+ * @returns The result.
  */
 export function isTaskDone(node) {
     // If the node has a subsystem with change children, check those recursively
@@ -404,6 +445,8 @@ export function isTaskDone(node) {
  *
  * Sums plan[] items from this node and recursively from all change nodes in
  * subsystem (and their subsystems).
+ * @param node - The node to check.
+ * @returns The result.
  */
 export function countTasks(node) {
     let total = 0;
@@ -429,6 +472,9 @@ export function countTasks(node) {
 /**
  * Inspect a document and return workflow completeness for a given prefix.
  * Never throws — missing nodes are reported as "not defined".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
  */
 export function planStatus(doc, prefix) {
     const constitution = findNode(doc, `${prefix}-CONST`);
@@ -527,6 +573,9 @@ export function planStatus(doc, prefix) {
 /**
  * Return per-task completion data.
  * Tasks (change nodes) are discovered from PROT-IMPL.subsystem, sorted topologically.
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
  */
 export function planProgress(doc, prefix) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -568,6 +617,10 @@ export function planProgress(doc, prefix) {
  *
  * Additionally for phase N > 1:
  *   - All tasks in phase N-1 must be done
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param phase - Phase number (1-indexed).
+ * @returns Gate check result with readiness flag and issues.
  */
 export function checkGate(doc, prefix, phase) {
     if (phase < 1) {