docs(speckit): add JSDoc and replace inline comments with doc comments

Author: Mearman

src/speckit/generate.ts

@@ -103,6 +103,7 @@ function formatStatus(status?: string): string {
 // generate Constitution
 // ============================================================================
 
+/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
 export function generateConstitution(
 	doc: SysProMDocument,
 	prefix: string,
@@ -191,6 +192,7 @@ export function generateConstitution(
 // generateSpec
 // ============================================================================
 
+/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
 export function generateSpec(doc: SysProMDocument, prefix: string): string {
 	const specId = `${prefix}-SPEC`;
 	const spec = findNode(doc, specId);
@@ -330,6 +332,7 @@ export function generateSpec(doc: SysProMDocument, prefix: string): string {
 // generatePlan
 // ============================================================================
 
+/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
 export function generatePlan(doc: SysProMDocument, prefix: string): string {
 	const implProtocolId = `${prefix}-PROT-IMPL`;
 	const protocol = findNode(doc, implProtocolId);
@@ -387,6 +390,7 @@ export function generatePlan(doc: SysProMDocument, prefix: string): string {
 // generateTasks
 // ============================================================================
 
+/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
 export function generateTasks(doc: SysProMDocument, prefix: string): string {
 	const implProtocolId = `${prefix}-PROT-IMPL`;
 	const protocol = findNode(doc, implProtocolId);
@@ -576,6 +580,7 @@ export function generateTasks(doc: SysProMDocument, prefix: string): string {
 // generateChecklist
 // ============================================================================
 
+/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
 export function generateChecklist(
 	doc: SysProMDocument,
 	prefix: string,
@@ -643,6 +648,7 @@ export function generateChecklist(
 // generateSpecKitProject
 // ============================================================================
 
+/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
 export function generateSpecKitProject(
 	doc: SysProMDocument,
 	outputDir: string,

src/speckit/parse.ts

@@ -18,8 +18,11 @@ interface Section {
 	children: Section[];
 }
 
+/** Result of parsing a Spec-Kit file — extracted nodes and relationships. */
 export interface ParseResult {
+	/** Nodes extracted from the parsed content. */
 	nodes: Node[];
+	/** Relationships extracted from the parsed content. */
 	relationships: Relationship[];
 }
 
@@ -187,6 +190,7 @@ function extractValue(body: string, key: string): string | undefined {
 // constitution.md parser
 // ---------------------------------------------------------------------------
 
+/** Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships. */
 export function parseConstitution(
 	content: string,
 	idPrefix: string,
@@ -296,6 +300,7 @@ export function parseConstitution(
 // spec.md parser
 // ---------------------------------------------------------------------------
 
+/** Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria). */
 export function parseSpec(content: string, idPrefix: string): ParseResult {
 	const sections = parseSections(content);
 	const allSections = flattenSections(sections);
@@ -508,6 +513,7 @@ export function parseSpec(content: string, idPrefix: string): ParseResult {
 // plan.md parser
 // ---------------------------------------------------------------------------
 
+/** Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships. */
 export function parsePlan(content: string, idPrefix: string): ParseResult {
 	const sections = parseSections(content);
 	const allSections = flattenSections(sections);
@@ -613,6 +619,7 @@ export function parsePlan(content: string, idPrefix: string): ParseResult {
 // tasks.md parser
 // ---------------------------------------------------------------------------
 
+/** Parse a Spec-Kit tasks file into SysProM change nodes with task plans. */
 export function parseTasks(content: string, idPrefix: string): ParseResult {
 	const sections = parseSections(content);
 	const allSections = flattenSections(sections);
@@ -739,6 +746,7 @@ export function parseTasks(content: string, idPrefix: string): ParseResult {
 // checklist.md parser
 // ---------------------------------------------------------------------------
 
+/** Parse a Spec-Kit checklist file into SysProM gate nodes with task plans. */
 export function parseChecklist(content: string, idPrefix: string): ParseResult {
 	const sections = parseSections(content);
 	const allSections = flattenSections(sections);
@@ -799,6 +807,7 @@ export function parseChecklist(content: string, idPrefix: string): ParseResult {
 // Full feature directory parser
 // ---------------------------------------------------------------------------
 
+/** Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist. */
 export function parseSpecKitFeature(
 	featureDir: string,
 	idPrefix: string,

src/speckit/plan.ts

@@ -5,6 +5,7 @@ import { textToString } from "../text.js";
 // Types
 // ============================================================================
 
+/** Comprehensive status of all plan components — constitution, spec, plan, tasks, checklist, and next step. */
 export interface PlanStatus {
 	constitution: { defined: boolean; principleCount: number };
 	spec: {
@@ -18,6 +19,7 @@ export interface PlanStatus {
 	nextStep: string;
 }
 
+/** Per-phase progress metrics — task counts and completion percentage. */
 export interface PhaseProgress {
 	phase: number;
 	name: string;
@@ -26,18 +28,21 @@ export interface PhaseProgress {
 	percent: number;
 }
 
+/** A specific issue preventing gate entry — incomplete tasks, missing acceptance criteria, or unlinked requirements. */
 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 };
 
+/** Result of a gate check — phase number, readiness flag, and any blocking issues. */
 export interface GateResult {
 	phase: number;
 	ready: boolean;
 	issues: GateIssue[];
 }
 
+/** Task completion counts — total and done. */
 export interface TaskCount {
 	total: number;
 	done: number;

src/speckit/project.ts

@@ -1,13 +1,19 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+/** Detected Spec-Kit project structure — root directory and paths to key directories and files. */
 export interface SpecKitProject {
-	root: string; // project root directory
-	specifyDir: string | null; // path to .specify/ if found
-	specsDir: string | null; // path to specs/ if found
-	constitutionPath: string | null; // path to constitution.md
+	/** Project root directory. */
+	root: string;
+	/** Path to `.specify/` directory, or null if not found. */
+	specifyDir: string | null;
+	/** Path to `specs/` directory, or null if not found. */
+	specsDir: string | null;
+	/** Path to `constitution.md`, or null if not found. */
+	constitutionPath: string | null;
 }
 
+/** A single Spec-Kit feature with its metadata and file paths. */
 export interface SpecKitFeature {
 	id: string; // e.g., "001-feature-name"
 	number: number; // e.g., 1