sysprom 1.0.0 → 1.0.6

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

@@ -0,0 +1,125 @@
+import type { SysProMDocument, Node } from "../schema.js";
+export interface PlanStatus {
+    constitution: {
+        defined: boolean;
+        principleCount: number;
+    };
+    spec: {
+        defined: boolean;
+        userStoryCount: number;
+        storiesNeedingAcceptanceCriteria: string[];
+    };
+    plan: {
+        defined: boolean;
+        phaseCount: number;
+    };
+    tasks: {
+        total: number;
+        done: number;
+    };
+    checklist: {
+        defined: boolean;
+        total: number;
+        done: number;
+    };
+    nextStep: string;
+}
+export interface PhaseProgress {
+    phase: number;
+    name: string;
+    done: number;
+    total: number;
+    percent: number;
+}
+export type GateIssue = {
+    kind: "previous_tasks_incomplete";
+    phase: number;
+    remaining: number;
+} | {
+    kind: "user_story_no_change";
+    storyId: string;
+} | {
+    kind: "user_story_no_acceptance_criteria";
+    storyId: string;
+} | {
+    kind: "fr_no_change";
+    frId: string;
+};
+export interface GateResult {
+    phase: number;
+    ready: boolean;
+    issues: GateIssue[];
+}
+export interface TaskCount {
+    total: number;
+    done: number;
+}
+/**
+ * Scaffold a new SysProMDocument with the standard spec-kit-compatible node
+ * structure for a given prefix and name.
+ *
+ * Creates four skeleton nodes:
+ *   - {prefix}-CONST   protocol (constitution)
+ *   - {prefix}-SPEC    artefact (specification)
+ *   - {prefix}-PROT-IMPL protocol (implementation plan) — with empty subsystem
+ *   - {prefix}-CHK     gate (checklist)
+ *
+ * Relationships wired:
+ *   - {prefix}-SPEC  governed_by  {prefix}-CONST
+ *   - {prefix}-CHK  governed_by  {prefix}-PROT-IMPL
+ *
+ * Tasks are not pre-scaffolded; use addTask to add them.
+ */
+export declare function initDocument(prefix: string, name: string): SysProMDocument;
+/**
+ * Immutably add a new task (change node) to PROT-IMPL.subsystem or to a parent
+ * change node's subsystem.
+ *
+ * - If parentId is not provided: adds CHG-{N} to PROT-IMPL.subsystem
+ *   (where N = count of existing change nodes + 1)
+ * - If parentId is provided: recursively finds parent change node, adds {parentId}-{M}
+ *   to parent's subsystem (creating subsystem if needed, where M = count of existing
+ *   change children + 1)
+ *
+ * Wires must_follow to previous sibling change node at the same level.
+ * Default name: "Task N".
+ */
+export declare function addTask(doc: SysProMDocument, prefix: string, name?: string, parentId?: string): SysProMDocument;
+/**
+ * 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
+ */
+export declare function isTaskDone(node: Node): boolean;
+/**
+ * Count total and completed tasks within a change node.
+ *
+ * Sums plan[] items from this node and recursively from all change nodes in
+ * subsystem (and their subsystems).
+ */
+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".
+ */
+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.
+ */
+export declare function planProgress(doc: SysProMDocument, prefix: string): PhaseProgress[];
+/**
+ * Validate readiness to enter the given phase (1-indexed).
+ *
+ * Always checks:
+ *   - Each capability ({prefix}-US-*) has a change node that implements it
+ *   - Each capability has non-placeholder acceptance criteria
+ *   - Each invariant ({prefix}-FR-*) has a change node that implements it
+ *
+ * Additionally for phase N > 1:
+ *   - All tasks in phase N-1 must be done
+ */
+export declare function checkGate(doc: SysProMDocument, prefix: string, phase: number): GateResult;