speckeeper 0.10.0 → 0.11.0

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { z } from 'zod';
-import { Command } from 'commander';
 import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
-import { dirname, join, resolve, isAbsolute } from 'path';
+import { dirname, join, resolve, basename, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { isOptionActive, derivePolicy } from 'cli-contracts/policy';
 import chalk4 from 'chalk';
-import { parse } from 'yaml';
+import { stringify, parse } from 'yaml';
 import 'crypto';
 import { glob } from 'glob';
 import nodeSqlParser from 'node-sql-parser';
@@ -535,6 +536,1108 @@ var init_dsl = __esm({
     init_workflows();
   }
 });
+var commandDefinitions = {
+  "init": {
+    "effects": {
+      "riskLevel": "medium",
+      "writes": [
+        {
+          "target": "speckeeper.config.ts, design/ directory",
+          "description": "generates config and starter template files",
+          "idempotent": false
+        }
+      ]
+    },
+    "options": [
+      {
+        "name": "force",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        },
+        "effects": {
+          "riskLevel": "high",
+          "writes": [
+            {
+              "target": "existing project files",
+              "description": "overwrites existing config and design files",
+              "overwrite": true,
+              "destructive": true
+            }
+          ]
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "ts",
+          "enum": [
+            "ts",
+            "yaml"
+          ]
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "build": {
+    "effects": {
+      "riskLevel": "low",
+      "writes": [
+        {
+          "target": "docs/ directory",
+          "description": "generated Markdown documentation files",
+          "overwrite": true,
+          "idempotent": true
+        }
+      ]
+    },
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string",
+          "default": "."
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "both",
+          "enum": [
+            "markdown",
+            "json",
+            "both"
+          ]
+        }
+      },
+      {
+        "name": "watch",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        },
+        "effects": {
+          "executionMode": "watch"
+        }
+      },
+      {
+        "name": "verbose",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "lint": {
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "phase",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "REQ",
+            "HLD",
+            "LLD",
+            "OPS"
+          ]
+        }
+      },
+      {
+        "name": "strict",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "fix",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "text",
+          "enum": [
+            "text",
+            "json",
+            "github"
+          ]
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "drift": {
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "update",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "text",
+          "enum": [
+            "text",
+            "json",
+            "diff"
+          ]
+        }
+      },
+      {
+        "name": "fail-on-drift",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "check": {
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "strict",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "verbose",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "coverage",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "new": {
+    "effects": {
+      "riskLevel": "low",
+      "writes": [
+        {
+          "target": "design/ directory",
+          "description": "new TypeScript spec file with auto-generated ID",
+          "idempotent": false
+        }
+      ]
+    },
+    "options": [
+      {
+        "name": "kind",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "name",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "template",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "impact": {
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "depth",
+        "schema": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3
+        }
+      },
+      {
+        "name": "direction",
+        "schema": {
+          "type": "string",
+          "default": "both",
+          "enum": [
+            "upstream",
+            "downstream",
+            "both"
+          ]
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "text",
+          "enum": [
+            "text",
+            "json",
+            "mermaid"
+          ]
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "scaffold": {
+    "effects": {
+      "riskLevel": "low",
+      "writes": [
+        {
+          "target": "design/ directory",
+          "description": "generated _models/ and spec data files",
+          "idempotent": false
+        }
+      ]
+    },
+    "options": [
+      {
+        "name": "source",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string",
+          "default": "design/"
+        }
+      },
+      {
+        "name": "force",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        },
+        "effects": {
+          "riskLevel": "medium",
+          "writes": [
+            {
+              "target": "existing model and spec files",
+              "description": "overwrites existing TypeScript model source files",
+              "overwrite": true
+            }
+          ]
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "default": "ts",
+          "enum": [
+            "ts",
+            "yaml"
+          ]
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "convert": {
+    "effects": {
+      "riskLevel": "low",
+      "writes": [
+        {
+          "target": ".yaml output file",
+          "description": "YAML conversion of the TS spec data",
+          "idempotent": true
+        }
+      ]
+    },
+    "options": [
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "write",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "audit-requirements": {
+    "effects": {
+      "network": {
+        "description": "LLM API calls to configured provider",
+        "idempotent": true
+      }
+    },
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "adapter",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "cursor",
+            "claude",
+            "openai",
+            "gemini",
+            "mock"
+          ]
+        }
+      },
+      {
+        "name": "model",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "show-prompt",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "fail-on",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "error",
+            "critical"
+          ],
+          "default": "error"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "write",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "report-format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "json",
+            "text",
+            "yaml"
+          ],
+          "default": "json"
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "propose-trace-links": {
+    "effects": {
+      "network": {
+        "description": "LLM API calls to configured provider",
+        "idempotent": true
+      }
+    },
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "adapter",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "cursor",
+            "claude",
+            "openai",
+            "gemini",
+            "mock"
+          ]
+        }
+      },
+      {
+        "name": "model",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "show-prompt",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "fail-on",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "error",
+            "critical"
+          ],
+          "default": "error"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "write",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "report-format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "json",
+            "text",
+            "yaml"
+          ],
+          "default": "json"
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "explain-impact": {
+    "effects": {
+      "network": {
+        "description": "LLM API calls to configured provider",
+        "idempotent": true
+      }
+    },
+    "options": [
+      {
+        "name": "adapter",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "cursor",
+            "claude",
+            "openai",
+            "gemini",
+            "mock"
+          ]
+        }
+      },
+      {
+        "name": "model",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "show-prompt",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "fail-on",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "error",
+            "critical"
+          ],
+          "default": "error"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "write",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "report-format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "json",
+            "text",
+            "yaml"
+          ],
+          "default": "json"
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  },
+  "propose-acceptance-criteria": {
+    "effects": {
+      "network": {
+        "description": "LLM API calls to configured provider",
+        "idempotent": true
+      }
+    },
+    "options": [
+      {
+        "name": "config",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "adapter",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "cursor",
+            "claude",
+            "openai",
+            "gemini",
+            "mock"
+          ]
+        }
+      },
+      {
+        "name": "model",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "show-prompt",
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      {
+        "name": "fail-on",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "error",
+            "critical"
+          ],
+          "default": "error"
+        }
+      },
+      {
+        "name": "output",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "write",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "report-format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "json",
+            "text",
+            "yaml"
+          ],
+          "default": "json"
+        }
+      }
+    ],
+    "env": {
+      "CURSOR_API_KEY": {
+        "sensitive": true
+      },
+      "GEMINI_API_KEY": {
+        "sensitive": true
+      },
+      "OPENAI_API_KEY": {
+        "sensitive": true
+      },
+      "ANTHROPIC_API_KEY": {
+        "sensitive": true
+      }
+    }
+  }
+};
+function deriveCommandPolicy(commandId, optionValues) {
+  const def = commandDefinitions[commandId];
+  if (!def) throw new Error(`Unknown command: ${commandId}`);
+  const cmdDef = def;
+  const options = {};
+  const activeOptions = [];
+  for (const optDef of cmdDef.options ?? []) {
+    const value = optionValues[optDef.name];
+    const specified = optDef.name in optionValues && value !== void 0;
+    options[optDef.name] = { value, specified, definition: optDef };
+    if (isOptionActive(optDef, value, specified)) {
+      activeOptions.push(optDef.name);
+    }
+  }
+  const policy = derivePolicy({
+    commandId,
+    commandEffects: cmdDef.effects,
+    options,
+    env: cmdDef.env
+  });
+  return { command: commandId, activeOptions, policy };
+}
+
+// src/generated/program.ts
+function createProgram(handlers2, version) {
+  const program = new Command();
+  program.name("speckeeper").version(version, "-V, --version").description("Requirements and design management framework with TypeScript DSL.");
+  program.option("--introspect", "Output derived policy as JSON without executing the command");
+  program.command("init").description("Initialize a new speckeeper project with starter templates.").option("-F, --force", "Overwrite existing files.", false).option("--format <format>", "Spec data format: ts (default) or yaml.", "ts").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("init", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.init(opts, globalOpts);
+  });
+  program.command("build").description("Generate docs/ and specs/ from TypeScript models.").option("-c, --config <path>", "Path to config file.").option("-o, --output <path>", "Base output directory path.", ".").option("-f, --format <format>", "Output format: markdown, json, both.", "both").option("-w, --watch", "Watch for changes and auto-regenerate.", false).option("-v, --verbose", "Show detailed output.", false).action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("build", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.build(opts, globalOpts);
+  });
+  program.command("lint").description("Check design integrity (ID duplicates, references, layer violations, etc.).").option("-c, --config <path>", "Path to config file.").option("-p, --phase <phase>", "Phase gate to check against: REQ, HLD, LLD, OPS.").option("-s, --strict", "Treat warnings as errors.", false).option("--fix", "Attempt to fix auto-fixable issues (not yet implemented).", false).option("-f, --format <format>", "Output format: text, json, github.", "text").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("lint", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.lint(opts, globalOpts);
+  });
+  program.command("drift").description("Check if generated files have been manually edited.").option("-c, --config <path>", "Path to config file.").option("-u, --update", "Auto-update if differences are found (not yet implemented).", false).option("-f, --format <format>", "Output format: text, json, diff.", "text").option("--fail-on-drift", "Exit with code 1 if drift is detected (for CI).", false).action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("drift", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.drift(opts, globalOpts);
+  });
+  program.command("check").description("Check external SSOT conformance (including custom models).").argument("[type]", "Type of check to run. Filters sources by type.").option("-c, --config <path>", "Path to config file.").option("--strict", "Treat warnings as errors.", false).option("-v, --verbose", "Show detailed output.", false).option("--coverage", "Check if all testable acceptance criteria are covered by TestRefs.", false).action(async (type, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("check", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.check(type, opts, globalOpts);
+  });
+  program.command("new").description("Create a new element with auto-generated ID.").argument("<type>", "Element type to create.").option("-k, --kind <kind>", "Sub-kind (e.g. functional, non-functional for requirements).").option("-n, --name <name>", "Name of the element.").option("-o, --output <path>", "Output directory path.").option("-t, --template <path>", "Path to template file.").option("--dry-run", "Preview generated file content without writing.", false).action(async (type, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("new", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.new(type, opts, globalOpts);
+  });
+  program.command("impact").description("Analyze impact of changes to an ID.").argument("<id>", "Spec ID to analyze (e.g. REQ-001, ENT-ORDER).").option("-c, --config <path>", "Path to config file.").option("-d, --depth <n>", "Analysis depth (reference tracking level).", "3").option("--direction <direction>", "Analysis direction: upstream, downstream, both.", "both").option("-f, --format <format>", "Output format: text, json, mermaid.", "text").action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("impact", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.impact(id, opts, globalOpts);
+  });
+  program.command("scaffold").description("Generate _models/ from a Mermaid flowchart definition.").option("-s, --source <path>", "Path to Markdown file containing Mermaid flowchart.").option("-o, --output <path>", "Output directory.", "design/").option("-F, --force", "Overwrite existing files.", false).option("--dry-run", "Preview generated files without writing.", false).option("--format <format>", "Spec data format: ts (default) or yaml.", "ts").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("scaffold", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.scaffold(opts, globalOpts);
+  });
+  program.command("convert").description("Convert a TS spec data file to YAML format.").argument("<file>", "Path to TS spec data file.").option("-o, --output <path>", "Output file path (default: same name with .yaml extension).").option("-n, --dry-run", "Preview conversion without writing.", false).action(async (file, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("convert", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.convert(file, opts, globalOpts);
+  });
+  program.command("audit-requirements").description("Run LLM-based requirement quality audit.").option("-c, --config <path>", "Path to config file.").option("-a, --adapter <name>", "SDK adapter to use for LLM execution.").option("--model <name>", "LLM model override.").option("-n, --dry-run", "Output the constructed prompt without calling LLM.", false).option("--show-prompt", "Display the constructed LLM prompt on stderr.", false).option("--fail-on <level>", "Minimum severity that causes a non-zero exit.", "error").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Output format for the audit report.", "json").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("audit-requirements", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.auditRequirements(opts, globalOpts);
+  });
+  program.command("propose-trace-links").description("LLM-based traceability link proposal.").option("-c, --config <path>", "Path to config file.").option("-a, --adapter <name>", "SDK adapter to use for LLM execution.").option("--model <name>", "LLM model override.").option("-n, --dry-run", "Output the constructed prompt without calling LLM.", false).option("--show-prompt", "Display the constructed LLM prompt on stderr.", false).option("--fail-on <level>", "Minimum severity that causes a non-zero exit.", "error").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Output format for the report.", "json").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("propose-trace-links", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.proposeTraceLinks(opts, globalOpts);
+  });
+  program.command("explain-impact").description("LLM-based explanation of impact analysis output.").option("-a, --adapter <name>", "SDK adapter to use for LLM execution.").option("--model <name>", "LLM model override.").option("-n, --dry-run", "Output the constructed prompt without calling LLM.", false).option("--show-prompt", "Display the constructed LLM prompt on stderr.", false).option("--fail-on <level>", "Minimum severity that causes a non-zero exit.", "error").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Output format for the report.", "json").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("explain-impact", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.explainImpact(opts, globalOpts);
+  });
+  program.command("propose-acceptance-criteria").description("LLM-based acceptance criteria proposal.").argument("[specIds...]", "Spec IDs to propose criteria for. Defaults to all specs if omitted.").option("-c, --config <path>", "Path to config file.").option("-a, --adapter <name>", "SDK adapter to use for LLM execution.").option("--model <name>", "LLM model override.").option("-n, --dry-run", "Output the constructed prompt without calling LLM.", false).option("--show-prompt", "Display the constructed LLM prompt on stderr.", false).option("--fail-on <level>", "Minimum severity that causes a non-zero exit.", "error").option("-o, --output <file>", "Write result to a file instead of stdout.").option("--report-format <fmt>", "Output format for the report.", "json").action(async (specIds, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("propose-acceptance-criteria", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.proposeAcceptanceCriteria(specIds, opts, globalOpts);
+  });
+  return program;
+}
 var defaultConfig = {
   srcDir: "src",
   designDir: "design",
@@ -1961,6 +3064,8 @@ async function runInit(options = {}) {
     console.log(chalk4.gray("  Please ensure the package is properly installed."));
     return;
   }
+  const isYaml = options.format === "yaml";
+  const skipForYaml = /* @__PURE__ */ new Set(["design/requirements.ts"]);
   let packageJsonCreated = false;
   copyTemplateDir(templatesDir, cwd, projectName, options.force || false, (relativePath, created) => {
     if (created) {
@@ -1971,25 +3076,29 @@ async function runInit(options = {}) {
     } else {
       console.log(chalk4.yellow(`  Skipped: ${relativePath} (already exists)`));
     }
-  });
+  }, "", isYaml ? skipForYaml : void 0);
+  if (isYaml) {
+    writeYamlInitFiles(cwd, options.force || false);
+  }
   console.log("");
   console.log(chalk4.cyan("  Project initialized successfully!"));
   console.log("");
+  const dataFormat = isYaml ? "design/*.yaml" : "design/*.ts using defineSpecs()";
   console.log("  Next steps:");
   if (packageJsonCreated) {
     console.log(chalk4.gray("    1. Run `npm install` to install dependencies"));
-    console.log(chalk4.gray("    2. Add spec data in design/*.ts using defineSpecs()"));
+    console.log(chalk4.gray(`    2. Add spec data in ${dataFormat}`));
     console.log(chalk4.gray("    3. Import new spec files in design/index.ts"));
     console.log(chalk4.gray("    4. Run `npx speckeeper lint` to validate"));
   } else {
     console.log(chalk4.gray("    1. Add speckeeper and zod to your package.json dependencies"));
     console.log(chalk4.gray('    2. Ensure "type": "module" is set in package.json'));
-    console.log(chalk4.gray("    3. Add spec data in design/*.ts using defineSpecs()"));
+    console.log(chalk4.gray(`    3. Add spec data in ${dataFormat}`));
     console.log(chalk4.gray("    4. Import new spec files in design/index.ts"));
     console.log(chalk4.gray("    5. Run `npx speckeeper lint` to validate"));
   }
 }
-function copyTemplateDir(srcDir, destDir, projectName, force, onFile, relativePath = "") {
+function copyTemplateDir(srcDir, destDir, projectName, force, onFile, relativePath = "", skipRelPaths) {
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     const srcPath = join(srcDir, entry);
@@ -2002,8 +3111,9 @@ function copyTemplateDir(srcDir, destDir, projectName, force, onFile, relativePa
         mkdirSync(destPath, { recursive: true });
         onFile(relPath + "/", true);
       }
-      copyTemplateDir(srcPath, destPath, projectName, force, onFile, relPath);
+      copyTemplateDir(srcPath, destPath, projectName, force, onFile, relPath, skipRelPaths);
     } else {
+      if (skipRelPaths?.has(relPath)) continue;
       if (!force && existsSync(destPath)) {
         onFile(relPath, false);
         continue;
@@ -2019,6 +3129,91 @@ function copyTemplateDir(srcDir, destDir, projectName, force, onFile, relativePa
     }
   }
 }
+function writeYamlInitFiles(cwd, force) {
+  const designDir = join(cwd, "design");
+  if (!existsSync(designDir)) {
+    mkdirSync(designDir, { recursive: true });
+  }
+  const reqYaml = join(designDir, "requirements.yaml");
+  if (force || !existsSync(reqYaml)) {
+    writeFileSync(reqYaml, `# Requirements
+model: requirement
+specs:
+  - id: REQ-001
+    name: User Authentication
+    type: functional
+    priority: must
+    description: Users can authenticate using email and password
+    acceptanceCriteria:
+      - id: REQ-001-01
+        description: Valid credentials grant access
+        verificationMethod: test
+      - id: REQ-001-02
+        description: Invalid credentials show error message
+        verificationMethod: test
+`);
+    console.log(chalk4.green("  Created: design/requirements.yaml"));
+  }
+  const indexTs = join(designDir, "index.ts");
+  if (force || !existsSync(indexTs)) {
+    writeFileSync(indexTs, `/**
+ * Design entry point
+ */
+import { mergeSpecs, loadYamlDir } from 'speckeeper';
+import { allModels } from './_models/index.ts';
+
+const yamlSpecs = loadYamlDir(import.meta.dirname, allModels);
+
+export default mergeSpecs(...yamlSpecs);
+`);
+    console.log(chalk4.green("  Created: design/index.ts (yaml mode)"));
+  }
+}
+async function runConvert(file, options = {}) {
+  const filePath = resolve(file);
+  if (!existsSync(filePath)) {
+    console.error(chalk4.red(`  Error: File not found: ${filePath}`));
+    process.exit(1);
+  }
+  if (!filePath.endsWith(".ts") && !filePath.endsWith(".js") && !filePath.endsWith(".mjs")) {
+    console.error(chalk4.red("  Error: Source file must be a .ts, .js, or .mjs file"));
+    process.exit(1);
+  }
+  console.log(chalk4.cyan("speckeeper convert"));
+  console.log(chalk4.gray(`  Source: ${filePath}`));
+  console.log("");
+  let specModule;
+  try {
+    const imported = await import(filePath);
+    specModule = imported.default ?? imported;
+  } catch (err) {
+    console.error(chalk4.red(`  Error: Failed to import ${filePath}`));
+    console.error(chalk4.gray(`  ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+  }
+  if (!specModule?.entries || !Array.isArray(specModule.entries)) {
+    console.error(chalk4.red("  Error: File does not export a valid SpecModule (missing entries array)"));
+    console.error(chalk4.gray("  The file must export a SpecModule via defineSpecs()"));
+    process.exit(1);
+  }
+  const yamlData = specModule.entries.length === 1 ? { model: specModule.entries[0].model.id, specs: specModule.entries[0].data } : { entries: specModule.entries.map((e) => ({ model: e.model.id, specs: e.data })) };
+  const yamlString = stringify(yamlData, {
+    lineWidth: 120,
+    defaultStringType: "PLAIN",
+    defaultKeyType: "PLAIN"
+  });
+  if (options.dryRun) {
+    console.log(chalk4.yellow("  Dry run \u2014 showing conversion result:"));
+    console.log("");
+    console.log(yamlString);
+    return;
+  }
+  const outputPath = options.output ? resolve(options.output) : join(dirname(filePath), basename(filePath).replace(/\.(ts|js|mjs)$/, ".yaml"));
+  writeFileSync(outputPath, yamlString);
+  console.log(chalk4.green(`  Created: ${outputPath}`));
+  console.log("");
+  console.log(chalk4.gray("  Remember to update design/index.ts to use loadYamlDir() for YAML files."));
+}
 
 // src/scaffold/mermaid-parser.ts
 function extractMermaidBlocks(markdown) {
@@ -2549,12 +3744,27 @@ function generateModelFile(node, _incomingEdges, _outgoingEdges, _allNodes) {
     content
   };
 }
-function generateSpecDataFile(node) {
+function generateSpecDataFile(node, format = "ts") {
   const templateInfo = resolveModelTemplate(node.id, node.classes, node.subgraph);
   const className = `${templateInfo.modelName}Model`;
   const typeName = templateInfo.modelName;
   const varName = toCamelCase(templateInfo.modelName) + "s";
   const fileName = templateInfo.fileName;
+  if (format === "yaml") {
+    const content2 = `# ${templateInfo.modelName} Specifications
+#
+# Generated by speckeeper scaffold \u2014 add your specs below.
+model: ${templateInfo.fileName}
+specs:
+  # - id: ${templateInfo.defaultIdPrefix}-001
+  #   name: "..."
+  #   description: "..."
+`;
+    return {
+      relativePath: `${fileName}.yaml`,
+      content: content2
+    };
+  }
   const content = `/**
  * ${templateInfo.modelName} Specifications
  *
@@ -2580,7 +3790,7 @@ export default defineSpecs(
 function toCamelCase(pascalCase) {
   return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
-function generateDesignIndex(speckeeperNodes) {
+function generateDesignIndex(speckeeperNodes, format = "ts") {
   const generated = /* @__PURE__ */ new Set();
   const specFiles = [];
   for (const node of speckeeperNodes) {
@@ -2594,6 +3804,21 @@ function generateDesignIndex(speckeeperNodes) {
       fileName: templateInfo.fileName
     });
   }
+  if (format === "yaml") {
+    const content2 = `/**
+ * Design entry point \u2014 generated by speckeeper scaffold
+ *
+ * YAML spec files in this directory are auto-discovered by loadYamlDir().
+ */
+import { mergeSpecs, loadYamlDir } from 'speckeeper';
+import { allModels } from './_models';
+
+const yamlSpecs = loadYamlDir(import.meta.dirname, allModels);
+
+export default mergeSpecs(...yamlSpecs);
+`;
+    return { relativePath: "index.ts", content: content2 };
+  }
   const imports = specFiles.map((f) => `import ${f.varName} from './${f.fileName}';`).join("\n");
   const args = specFiles.map((f) => f.varName).join(", ");
   const content = `/**
@@ -2609,7 +3834,7 @@ export default mergeSpecs(${args});
     content
   };
 }
-function generateAllModelFiles(speckeeperNodes, resolvedEdges, allNodes) {
+function generateAllModelFiles(speckeeperNodes, resolvedEdges, allNodes, format = "ts") {
   const files = [];
   const generated = /* @__PURE__ */ new Set();
   const templateNodeGroups = /* @__PURE__ */ new Map();
@@ -2632,9 +3857,9 @@ function generateAllModelFiles(speckeeperNodes, resolvedEdges, allNodes) {
     resolvedEdges.filter((e) => groupNodeIds.has(e.targetId));
     resolvedEdges.filter((e) => groupNodeIds.has(e.sourceId));
     files.push(generateModelFile(node));
-    files.push(generateSpecDataFile(node));
+    files.push(generateSpecDataFile(node, format));
   }
-  files.push(generateDesignIndex(speckeeperNodes));
+  files.push(generateDesignIndex(speckeeperNodes, format));
   return files;
 }
 
@@ -2727,7 +3952,8 @@ async function scaffoldCommand(options) {
   );
   printDiagnostics(diagnostics);
   const outputDir = options.output ? resolve(options.output) : join(process.cwd(), "design");
-  const modelFiles = generateAllModelFiles(speckeeperNodes, resolved, flowchart.nodes);
+  const specFormat = options.format ?? "ts";
+  const modelFiles = generateAllModelFiles(speckeeperNodes, resolved, flowchart.nodes, specFormat);
   const indexFile = generateModelsIndex(modelFiles);
   const allFiles = [...modelFiles, indexFile];
   console.log("");
@@ -3330,13 +4556,13 @@ async function commandExplainImpact(opts) {
   }
 }
 function readStdin() {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const chunks = [];
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve3(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("end", () => resolve4(Buffer.concat(chunks).toString("utf-8")));
     process.stdin.on("error", reject);
     if (process.stdin.isTTY) {
-      resolve3("");
+      resolve4("");
     }
   });
 }
@@ -3386,68 +4612,78 @@ function getVersion() {
     return "0.0.0";
   }
 }
-var program = new Command();
-program.name("speckeeper").description("Requirements and design management framework with TypeScript DSL").version(getVersion());
-program.command("build").description("Generate docs/ and specs/ from TypeScript models").option("-c, --config <path>", "Path to config file").option("-o, --output <path>", "Base output directory path", ".").option("-f, --format <format>", "Output format: markdown, json, both", "both").option("-w, --watch", "Watch for changes and auto-regenerate").option("-v, --verbose", "Show detailed output").action(buildCommand);
-program.command("lint").description("Check design integrity (ID duplicates, references, layer violations, etc.)").option("-c, --config <path>", "Path to config file").option("-p, --phase <phase>", "Phase gate to check against (REQ, HLD, LLD, OPS)").option("-s, --strict", "Treat warnings as errors").option("--fix", "Attempt to fix auto-fixable issues").option("-f, --format <format>", "Output format: text, json, github", "text").action(lintCommand);
-program.command("drift").description("Check if generated files have been manually edited").option("-c, --config <path>", "Path to config file").option("-u, --update", "Auto-update if differences are found").option("-f, --format <format>", "Output format: text, json, diff", "text").option("--fail-on-drift", "Exit with code 1 if drift is detected (for CI)").action(driftCommand);
-program.command("check").description("Check external SSOT conformance (including custom models)").argument("[type]", "Type of check: external-ssot, openapi, ddl, iac, custom, all, test").option("-c, --config <path>", "Path to config file").option("--strict", "Treat warnings as errors").option("-v, --verbose", "Show detailed output").option("--coverage", "Check if all testable acceptance criteria are covered by TestRefs").action(checkCommand);
-program.command("new").description("Create a new element with auto-generated ID").argument("<type>", "Type: requirement, usecase, entity, component, screen, flow, error-case, term").option("-k, --kind <kind>", "Sub-kind (e.g., functional, non-functional for requirements)").option("-n, --name <name>", "Name of the element").option("-o, --output <path>", "Output directory path").option("-t, --template <path>", "Path to template file").action(newCommand);
-program.command("impact").description("Analyze impact of changes to an ID").argument("<id>", "ID to analyze (e.g., REQ-001, ENT-ORDER)").option("-c, --config <path>", "Path to config file").option("-d, --depth <depth>", "Analysis depth (reference tracking level)", "3").option("--direction <direction>", "Analysis direction: upstream, downstream, both", "both").option("-f, --format <format>", "Output format: text, json, mermaid", "text").action(impactCommand);
-program.command("init").description("Initialize a new speckeeper project with starter templates").option("-f, --force", "Overwrite existing files").action(runInit);
-program.command("scaffold").description("Generate _models/ from a mermaid flowchart definition").requiredOption("-s, --source <path>", "Path to Markdown file containing mermaid flowchart").option("-o, --output <path>", "Output directory (default: design/)").option("-f, --force", "Overwrite existing files").option("--dry-run", "Preview generated files without writing").action(scaffoldCommand);
-var llmOptions = (cmd) => cmd.option("-a, --adapter <name>", "SDK adapter (cursor, claude, openai, gemini, mock)").option("--model <name>", "LLM model override").option("-n, --dry-run", "Output prompt without calling LLM").option("--fail-on <level>", "Minimum severity for non-zero exit (warning, error, critical)", "error").option("-o, --output <file>", "Write result to a file instead of stdout").option("--report-format <fmt>", "Output format (json, text, yaml)", "text");
-llmOptions(
-  program.command("audit-requirements").description("LLM-based requirement quality audit").option("-c, --config <path>", "Path to config file")
-).action((opts) => {
-  commandAuditRequirements({
-    config: opts.config,
-    adapter: opts.adapter,
-    model: opts.model,
-    dryRun: opts.dryRun,
-    failOn: opts.failOn,
-    output: opts.output,
-    reportFormat: opts.reportFormat
-  });
-});
-llmOptions(
-  program.command("propose-trace-links").description("LLM-based traceability link proposal").option("-c, --config <path>", "Path to config file")
-).action((opts) => {
-  commandProposeTraceLinks({
-    config: opts.config,
-    adapter: opts.adapter,
-    model: opts.model,
-    dryRun: opts.dryRun,
-    failOn: opts.failOn,
-    output: opts.output,
-    reportFormat: opts.reportFormat
-  });
-});
-llmOptions(
-  program.command("explain-impact").description("LLM-based explanation of impact analysis output")
-).action((opts) => {
-  commandExplainImpact({
-    adapter: opts.adapter,
-    model: opts.model,
-    dryRun: opts.dryRun,
-    failOn: opts.failOn,
-    output: opts.output,
-    reportFormat: opts.reportFormat
-  });
-});
-llmOptions(
-  program.command("propose-acceptance-criteria [specIds...]").description("LLM-based acceptance criteria proposal").option("-c, --config <path>", "Path to config file")
-).action((specIds, opts) => {
-  commandProposeAcceptanceCriteria(specIds, {
-    config: opts.config,
-    adapter: opts.adapter,
-    model: opts.model,
-    dryRun: opts.dryRun,
-    failOn: opts.failOn,
-    output: opts.output,
-    reportFormat: opts.reportFormat
-  });
-});
-program.parse();
+var handlers = {
+  init: async (opts) => {
+    await runInit(opts);
+  },
+  build: async (opts) => {
+    await buildCommand(opts);
+  },
+  lint: async (opts) => {
+    await lintCommand(opts);
+  },
+  drift: async (opts) => {
+    await driftCommand(opts);
+  },
+  check: async (type, opts) => {
+    await checkCommand(type, opts);
+  },
+  new: async (type, opts) => {
+    await newCommand({ type, output: opts.output, dryRun: opts.dryRun });
+  },
+  impact: async (id, opts) => {
+    await impactCommand(id, opts);
+  },
+  scaffold: async (opts) => {
+    await scaffoldCommand(opts);
+  },
+  convert: async (file, opts) => {
+    await runConvert(file, opts);
+  },
+  auditRequirements: async (opts) => {
+    await commandAuditRequirements({
+      config: opts.config,
+      adapter: opts.adapter,
+      model: opts.model,
+      dryRun: opts.dryRun,
+      failOn: opts.failOn,
+      output: opts.output,
+      reportFormat: opts.reportFormat
+    });
+  },
+  proposeTraceLinks: async (opts) => {
+    await commandProposeTraceLinks({
+      config: opts.config,
+      adapter: opts.adapter,
+      model: opts.model,
+      dryRun: opts.dryRun,
+      failOn: opts.failOn,
+      output: opts.output,
+      reportFormat: opts.reportFormat
+    });
+  },
+  explainImpact: async (opts) => {
+    await commandExplainImpact({
+      adapter: opts.adapter,
+      model: opts.model,
+      dryRun: opts.dryRun,
+      failOn: opts.failOn,
+      output: opts.output,
+      reportFormat: opts.reportFormat
+    });
+  },
+  proposeAcceptanceCriteria: async (specIds, opts) => {
+    await commandProposeAcceptanceCriteria(specIds, {
+      config: opts.config,
+      adapter: opts.adapter,
+      model: opts.model,
+      dryRun: opts.dryRun,
+      failOn: opts.failOn,
+      output: opts.output,
+      reportFormat: opts.reportFormat
+    });
+  }
+};
+createProgram(handlers, getVersion()).parse();
 //# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map