speckeeper 0.9.4 → 0.10.0

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/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';
@@ -7,9 +8,533 @@ import chalk4 from 'chalk';
 import { parse } from 'yaml';
 import 'crypto';
 import { glob } from 'glob';
-import { z } from 'zod';
 import nodeSqlParser from 'node-sql-parser';
+import { writeFile as writeFile$1 } from 'fs/promises';
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/generated/dsl/agents.ts
+var specQualityReviewer, agentRegistry;
+var init_agents = __esm({
+  "src/generated/dsl/agents.ts"() {
+    specQualityReviewer = {
+      id: "spec-quality-reviewer",
+      role_name: "Spec Quality Reviewer",
+      purpose: "Review design specifications for quality, verifiability, consistency, and traceability. Evaluates requirements from a PM/architect perspective, identifying ambiguity, untestable criteria, mixed abstraction levels, and missing traceability links.",
+      mode: "read-only",
+      dispatch_only: false,
+      can_read_artifacts: [
+        "spec-definitions",
+        "agent-review-output"
+      ],
+      can_write_artifacts: [],
+      can_execute_tools: [
+        "speckeeper-cli"
+      ],
+      can_invoke_agents: [],
+      can_return_handoffs: [
+        "requirement-audit-result",
+        "trace-link-result",
+        "impact-explain-result",
+        "acceptance-criteria-result"
+      ],
+      responsibilities: [
+        "Evaluate requirement verifiability and measurability",
+        "Detect ambiguous or vague wording in specifications",
+        "Identify mixed requirement vs design content",
+        "Assess granularity consistency across spec types",
+        "Detect terminology inconsistencies across models",
+        "Estimate traceability link candidates with confidence scores",
+        "Explain impact analysis results for non-technical stakeholders",
+        "Propose acceptance criteria drafts for requirements and use cases"
+      ],
+      constraints: [
+        "Do not modify spec definition files or assign spec IDs",
+        "Do not claim a spec is valid without citing specific evidence",
+        "Reference speckeeper lint results when findings overlap",
+        "Candidate trace links must always include confidence scores",
+        "explain output must use language suitable for PM and executive audiences",
+        "Output must conform to the task\u2019s result handoff schema: RequirementAuditResult, TraceLinkResult, ImpactExplainResult, or AcceptanceCriteriaResult",
+        "Findings must use speckeeper category vocabulary (verifiability, ambiguity, granularity, terminology, design-mixing, traceability, completeness)",
+        "Each finding must include a recommendation when severity is warning or above"
+      ],
+      rules: [
+        {
+          "id": "R-SPEC-001",
+          "description": "Requirements without measurable acceptance criteria are flagged",
+          "severity": "mandatory"
+        },
+        {
+          "id": "R-SPEC-002",
+          "description": 'Ambiguous terms (e.g. "appropriate", "fast", "user-friendly") without quantification are flagged',
+          "severity": "mandatory"
+        },
+        {
+          "id": "R-SPEC-003",
+          "description": "Mixed requirement and design content in the same spec is flagged",
+          "severity": "recommended"
+        },
+        {
+          "id": "R-SPEC-004",
+          "description": "Trace link candidates must include confidence score and rationale",
+          "severity": "mandatory"
+        },
+        {
+          "id": "R-SPEC-005",
+          "description": "Explain output must be readable by non-technical stakeholders",
+          "severity": "mandatory"
+        },
+        {
+          "id": "R-SPEC-006",
+          "description": "Terminology inconsistencies across spec models must be flagged with specific examples",
+          "severity": "mandatory"
+        }
+      ],
+      escalation_criteria: [
+        {
+          "condition": "Config file cannot be loaded or design models are structurally invalid",
+          "action": "stop_and_report"
+        },
+        {
+          "condition": "No specs found in the loaded configuration",
+          "action": "stop_and_report"
+        },
+        {
+          "condition": "speckeeper-cli execution fails (lint or impact returns unexpected error)",
+          "action": "stop_and_report"
+        },
+        {
+          "condition": "Output schema validation fails on generated result",
+          "action": "stop_and_report"
+        },
+        {
+          "condition": "Stdin is absent or malformed for explain-impact-result task",
+          "action": "stop_and_report"
+        },
+        {
+          "condition": "Context exceeds LLM context window limit",
+          "action": "stop_and_report"
+        }
+      ]
+    };
+    agentRegistry = {
+      "spec-quality-reviewer": specQualityReviewer
+    };
+  }
+});
+
+// src/generated/dsl/tasks.ts
+var auditRequirementQuality, proposeTraceLinks, explainImpactResult, proposeAcceptanceCriteria, taskRegistry;
+var init_tasks = __esm({
+  "src/generated/dsl/tasks.ts"() {
+    auditRequirementQuality = {
+      id: "audit-requirement-quality",
+      description: "Audit design specs for quality, verifiability, and consistency",
+      target_agent: "spec-quality-reviewer",
+      allowed_from_agents: [
+        "spec-quality-reviewer"
+      ],
+      workflow: "requirement-audit",
+      invocation_handoff: "spec-review-request",
+      result_handoff: "requirement-audit-result",
+      input_artifacts: [
+        "spec-definitions"
+      ],
+      responsibilities: [
+        "Evaluate all specs for verifiability and measurability",
+        "Detect ambiguous or vague wording",
+        "Identify mixed requirement vs design content",
+        "Check terminology consistency across models",
+        "Assess granularity appropriateness"
+      ],
+      completion_criteria: [
+        "All target specs have been evaluated",
+        "Findings classified by severity and category",
+        "Each finding includes a recommendation",
+        "Output conforms to RequirementAuditResult schema"
+      ],
+      optional: false
+    };
+    proposeTraceLinks = {
+      id: "propose-trace-links",
+      description: "Propose candidate traceability links between specs and external artifacts",
+      target_agent: "spec-quality-reviewer",
+      allowed_from_agents: [
+        "spec-quality-reviewer"
+      ],
+      workflow: "trace-link-proposal",
+      invocation_handoff: "spec-review-request",
+      result_handoff: "trace-link-result",
+      input_artifacts: [
+        "spec-definitions"
+      ],
+      responsibilities: [
+        "Analyze spec definitions and global scanner results",
+        "Identify candidate links between specs and external artifacts",
+        "Assign confidence scores to each candidate",
+        "Provide rationale for each proposed link"
+      ],
+      completion_criteria: [
+        "All specs and scanner results have been cross-referenced",
+        "Each candidate link has a confidence score and rationale",
+        "Existing relations are not duplicated",
+        "Output conforms to TraceLinkResult schema"
+      ],
+      optional: false
+    };
+    explainImpactResult = {
+      id: "explain-impact-result",
+      description: "Explain speckeeper impact command output in human-readable form",
+      target_agent: "spec-quality-reviewer",
+      allowed_from_agents: [
+        "spec-quality-reviewer"
+      ],
+      workflow: "impact-explanation",
+      invocation_handoff: "spec-review-request",
+      result_handoff: "impact-explain-result",
+      input_artifacts: [
+        "spec-definitions"
+      ],
+      responsibilities: [
+        "Summarize impact output for non-technical readers",
+        "Provide concrete next steps as recommendedActions",
+        "Explain spec relationships in plain language"
+      ],
+      completion_criteria: [
+        "Explanation accurately summarizes the impact output",
+        "Action items are concrete and actionable",
+        "Technical terms explained for PM/executive audiences",
+        "Severity reflects urgency of the underlying change"
+      ],
+      optional: false
+    };
+    proposeAcceptanceCriteria = {
+      id: "propose-acceptance-criteria",
+      description: "Propose acceptance criteria drafts for design specs",
+      target_agent: "spec-quality-reviewer",
+      allowed_from_agents: [
+        "spec-quality-reviewer"
+      ],
+      workflow: "acceptance-proposal",
+      invocation_handoff: "spec-review-request",
+      result_handoff: "acceptance-criteria-result",
+      input_artifacts: [
+        "spec-definitions"
+      ],
+      responsibilities: [
+        "Analyze target spec definitions and related specs",
+        "Propose testable acceptance criteria for each spec",
+        "Provide rationale for each proposed criterion"
+      ],
+      completion_criteria: [
+        "Proposed criteria are specific and testable",
+        "Each proposal includes a rationale",
+        "Criteria do not duplicate existing acceptance conditions",
+        "Output conforms to AcceptanceCriteriaResult handoff schema"
+      ],
+      optional: false
+    };
+    taskRegistry = {
+      "audit-requirement-quality": auditRequirementQuality,
+      "propose-trace-links": proposeTraceLinks,
+      "explain-impact-result": explainImpactResult,
+      "propose-acceptance-criteria": proposeAcceptanceCriteria
+    };
+  }
+});
+var SpecReviewRequestSchema, RequirementAuditResultSchema, TraceLinkResultSchema, ImpactExplainResultSchema, AcceptanceCriteriaResultSchema, handoffSchemas, handoffs;
+var init_handoffs = __esm({
+  "src/generated/dsl/handoffs.ts"() {
+    SpecReviewRequestSchema = z.object({
+      task_id: z.string(),
+      context: z.string()
+    });
+    RequirementAuditResultSchema = z.object({
+      summary: z.string(),
+      riskLevel: z.enum(["low", "medium", "high", "critical"]),
+      findings: z.array(z.object({
+        id: z.string().optional(),
+        severity: z.enum(["info", "warning", "error", "critical"]),
+        category: z.string(),
+        target: z.string().optional(),
+        location: z.string().optional(),
+        message: z.string(),
+        recommendation: z.string().optional(),
+        confidence: z.number().optional(),
+        evidence: z.array(z.object({
+          kind: z.enum(["file", "command", "schema", "diff", "stdout", "stderr", "text"]).optional(),
+          target: z.string().optional(),
+          location: z.string().optional(),
+          excerpt: z.string().optional()
+        })).optional(),
+        details: z.record(z.string(), z.unknown()).optional()
+      })),
+      recommendedActions: z.array(z.object({
+        kind: z.enum(["run_command", "edit_file", "review", "confirm", "block", "ignore"]),
+        title: z.string(),
+        command: z.string().optional(),
+        target: z.string().optional(),
+        rationale: z.string().optional()
+      })).optional(),
+      metadata: z.object({
+        tool: z.string().optional(),
+        command: z.string().optional(),
+        version: z.string().optional(),
+        generatedAt: z.string().optional(),
+        adapter: z.string().optional(),
+        model: z.string().optional()
+      }).optional()
+    });
+    TraceLinkResultSchema = z.object({
+      summary: z.string(),
+      riskLevel: z.enum(["low", "medium", "high", "critical"]),
+      findings: z.array(z.object({
+        severity: z.enum(["info", "warning", "error", "critical"]),
+        category: z.string(),
+        message: z.string(),
+        recommendation: z.string().optional()
+      })),
+      candidateLinks: z.array(z.object({
+        from: z.string(),
+        relation: z.string(),
+        to: z.string(),
+        confidence: z.number(),
+        reason: z.string()
+      })),
+      recommendedActions: z.array(z.object({
+        kind: z.enum(["run_command", "edit_file", "review", "confirm", "block", "ignore"]),
+        title: z.string(),
+        command: z.string().optional(),
+        target: z.string().optional(),
+        rationale: z.string().optional()
+      })).optional(),
+      metadata: z.object({
+        tool: z.string().optional(),
+        command: z.string().optional(),
+        version: z.string().optional(),
+        generatedAt: z.string().optional(),
+        adapter: z.string().optional(),
+        model: z.string().optional()
+      }).optional()
+    });
+    ImpactExplainResultSchema = z.object({
+      summary: z.string(),
+      riskLevel: z.enum(["low", "medium", "high", "critical"]),
+      explanation: z.string(),
+      findings: z.array(z.object({
+        severity: z.enum(["info", "warning", "error", "critical"]),
+        category: z.string(),
+        message: z.string()
+      })).optional(),
+      affectedArtifacts: z.array(z.object({
+        type: z.enum(["spec", "api", "ddl", "test", "annotation"]),
+        id: z.string(),
+        summary: z.string()
+      })).optional(),
+      testConsiderations: z.array(z.string()).optional(),
+      releaseRisk: z.enum(["low", "medium", "high"]).optional(),
+      recommendedActions: z.array(z.object({
+        kind: z.enum(["run_command", "edit_file", "review", "confirm", "block", "ignore"]),
+        title: z.string(),
+        rationale: z.string().optional()
+      })).optional(),
+      sourceCommand: z.string().optional(),
+      metadata: z.object({
+        tool: z.string().optional(),
+        command: z.string().optional(),
+        version: z.string().optional(),
+        generatedAt: z.string().optional(),
+        adapter: z.string().optional(),
+        model: z.string().optional()
+      }).optional()
+    });
+    AcceptanceCriteriaResultSchema = z.object({
+      summary: z.string(),
+      riskLevel: z.enum(["low", "medium", "high", "critical"]),
+      findings: z.array(z.object({
+        severity: z.enum(["info", "warning", "error", "critical"]),
+        category: z.string(),
+        message: z.string(),
+        recommendation: z.string().optional()
+      })),
+      criteriaProposals: z.array(z.object({
+        specId: z.string(),
+        criteria: z.array(z.string()),
+        rationale: z.string()
+      })),
+      recommendedActions: z.array(z.object({
+        kind: z.enum(["run_command", "edit_file", "review", "confirm", "block", "ignore"]),
+        title: z.string(),
+        command: z.string().optional(),
+        target: z.string().optional(),
+        rationale: z.string().optional()
+      })).optional(),
+      metadata: z.object({
+        tool: z.string().optional(),
+        command: z.string().optional(),
+        version: z.string().optional(),
+        generatedAt: z.string().optional(),
+        adapter: z.string().optional(),
+        model: z.string().optional()
+      }).optional()
+    });
+    handoffSchemas = {
+      "spec-review-request": SpecReviewRequestSchema,
+      "requirement-audit-result": RequirementAuditResultSchema,
+      "trace-link-result": TraceLinkResultSchema,
+      "impact-explain-result": ImpactExplainResultSchema,
+      "acceptance-criteria-result": AcceptanceCriteriaResultSchema
+    };
+    handoffs = {
+      specReviewRequest(payload) {
+        return {
+          type: "spec-review-request",
+          version: 1,
+          payload: SpecReviewRequestSchema.parse(payload)
+        };
+      },
+      requirementAuditResult(payload) {
+        return {
+          type: "requirement-audit-result",
+          version: 1,
+          payload: RequirementAuditResultSchema.parse(payload)
+        };
+      },
+      traceLinkResult(payload) {
+        return {
+          type: "trace-link-result",
+          version: 1,
+          payload: TraceLinkResultSchema.parse(payload)
+        };
+      },
+      impactExplainResult(payload) {
+        return {
+          type: "impact-explain-result",
+          version: 1,
+          payload: ImpactExplainResultSchema.parse(payload)
+        };
+      },
+      acceptanceCriteriaResult(payload) {
+        return {
+          type: "acceptance-criteria-result",
+          version: 1,
+          payload: AcceptanceCriteriaResultSchema.parse(payload)
+        };
+      }
+    };
+  }
+});
+
+// src/generated/dsl/workflows.ts
+var requirementAudit, traceLinkProposal, impactExplanation, acceptanceProposal, workflowRegistry;
+var init_workflows = __esm({
+  "src/generated/dsl/workflows.ts"() {
+    requirementAudit = {
+      id: "requirement-audit",
+      description: "Audit requirement specs for quality, verifiability, and consistency",
+      trigger: "cli-command",
+      entry_conditions: [
+        "Design models are loaded and specs are available"
+      ],
+      steps: [
+        {
+          type: "delegate",
+          task: "audit-requirement-quality",
+          from_agent: "spec-quality-reviewer",
+          description: "",
+          optional: false,
+          max_retries: 0
+        }
+      ]
+    };
+    traceLinkProposal = {
+      id: "trace-link-proposal",
+      description: "Propose candidate traceability links between specs and external artifacts",
+      trigger: "cli-command",
+      entry_conditions: [
+        "Design models and global scanner results are available"
+      ],
+      steps: [
+        {
+          type: "delegate",
+          task: "propose-trace-links",
+          from_agent: "spec-quality-reviewer",
+          description: "",
+          optional: false,
+          max_retries: 0
+        }
+      ]
+    };
+    impactExplanation = {
+      id: "impact-explanation",
+      description: "Explain impact analysis results in human-readable form",
+      trigger: "cli-command",
+      entry_conditions: [
+        "JSON output from speckeeper impact is available on stdin"
+      ],
+      steps: [
+        {
+          type: "delegate",
+          task: "explain-impact-result",
+          from_agent: "spec-quality-reviewer",
+          description: "",
+          optional: false,
+          max_retries: 0
+        }
+      ]
+    };
+    acceptanceProposal = {
+      id: "acceptance-proposal",
+      description: "Propose acceptance criteria drafts for specs",
+      trigger: "cli-command",
+      entry_conditions: [
+        "Target specs are loaded and available"
+      ],
+      steps: [
+        {
+          type: "delegate",
+          task: "propose-acceptance-criteria",
+          from_agent: "spec-quality-reviewer",
+          description: "",
+          optional: false,
+          max_retries: 0
+        }
+      ]
+    };
+    workflowRegistry = {
+      "requirement-audit": requirementAudit,
+      "trace-link-proposal": traceLinkProposal,
+      "impact-explanation": impactExplanation,
+      "acceptance-proposal": acceptanceProposal
+    };
+  }
+});
+
+// src/generated/dsl/index.ts
+var dsl_exports = {};
+__export(dsl_exports, {
+  agentRegistry: () => agentRegistry,
+  handoffSchemas: () => handoffSchemas,
+  handoffs: () => handoffs,
+  taskRegistry: () => taskRegistry,
+  workflowRegistry: () => workflowRegistry
+});
+var init_dsl = __esm({
+  "src/generated/dsl/index.ts"() {
+    init_agents();
+    init_tasks();
+    init_handoffs();
+    init_workflows();
+  }
+});
 var defaultConfig = {
   srcDir: "src",
   designDir: "design",
@@ -2252,6 +2777,605 @@ function printDiagnostics(diagnostics) {
   }
 }
 
+// src/agents/context-builder.ts
+function extractSpecSummaries(models, specs) {
+  const summaries = [];
+  for (const model of models) {
+    const modelSpecs = getSpecsFromConfig(
+      specs,
+      model.id
+    );
+    for (const spec of modelSpecs) {
+      const s = spec;
+      summaries.push({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        modelType: model.name ?? model.id,
+        relations: s.relations
+      });
+    }
+  }
+  return summaries;
+}
+function formatSpecForContext(spec) {
+  const lines = [];
+  lines.push(`### ${spec.id} (${spec.modelType})`);
+  if (spec.name) lines.push(`Name: ${spec.name}`);
+  if (spec.description) lines.push(`Description: ${spec.description}`);
+  if (spec.relations && spec.relations.length > 0) {
+    lines.push("Relations:");
+    for (const rel of spec.relations) {
+      lines.push(`  - ${rel.type} \u2192 ${rel.target}`);
+    }
+  }
+  return lines.join("\n");
+}
+function runLintForContext(models, specs) {
+  const issues = [];
+  for (const model of models) {
+    const modelSpecs = getSpecsFromConfig(
+      specs,
+      model.id
+    );
+    if (modelSpecs.length === 0) continue;
+    try {
+      const lintResults = model.lintAll(modelSpecs);
+      for (const result of lintResults) {
+        issues.push({
+          rule: result.ruleId,
+          severity: result.severity,
+          message: result.message,
+          specId: result.specId,
+          modelType: model.name
+        });
+      }
+    } catch {
+    }
+  }
+  return issues;
+}
+async function buildAuditRequirementsContext(configPath) {
+  const config = await loadConfig(configPath);
+  const models = config.models || [];
+  const specs = config.specs;
+  const specSummaries = extractSpecSummaries(models, specs);
+  const lintIssues = runLintForContext(models, specs);
+  const sections = [];
+  sections.push("# Requirement Quality Audit Request");
+  sections.push(
+    `## Project Configuration
+
+- Design directory: ${config.designDir || "design"}
+- Models: ${models.length}
+- Total specs: ${specSummaries.length}`
+  );
+  if (specSummaries.length > 0) {
+    sections.push("## Spec Definitions\n");
+    for (const spec of specSummaries) {
+      sections.push(formatSpecForContext(spec));
+    }
+  }
+  if (lintIssues.length > 0) {
+    sections.push("## Existing Lint Issues\n");
+    for (const issue of lintIssues) {
+      const prefix = issue.specId ? `[${issue.specId}] ` : "";
+      sections.push(`- [${issue.severity}] ${prefix}${issue.message} (rule: ${issue.rule})`);
+    }
+  }
+  return sections.join("\n\n");
+}
+async function buildProposeTraceLinksContext(configPath) {
+  const config = await loadConfig(configPath);
+  const models = config.models || [];
+  const specs = config.specs;
+  const specSummaries = extractSpecSummaries(models, specs);
+  const sections = [];
+  sections.push("# Trace Link Proposal Request");
+  sections.push(
+    `## Project Configuration
+
+- Design directory: ${config.designDir || "design"}
+- Models: ${models.length}
+- Total specs: ${specSummaries.length}`
+  );
+  if (specSummaries.length > 0) {
+    sections.push("## Spec Definitions\n");
+    for (const spec of specSummaries) {
+      sections.push(formatSpecForContext(spec));
+    }
+  }
+  const existingRelations = [];
+  for (const spec of specSummaries) {
+    if (spec.relations) {
+      for (const rel of spec.relations) {
+        existingRelations.push(`${spec.id} --[${rel.type}]--> ${rel.target}`);
+      }
+    }
+  }
+  if (existingRelations.length > 0) {
+    sections.push("## Existing Relations\n\n" + existingRelations.join("\n"));
+  }
+  const sources = config.sources ?? [];
+  if (sources.length > 0) {
+    sections.push("## Configured External Sources\n");
+    for (const source of sources) {
+      sections.push(`- Type: ${source.type}, Paths: ${source.paths?.join(", ") ?? "N/A"}`);
+    }
+  }
+  return sections.join("\n\n");
+}
+function buildExplainImpactContext(stdinJson, sourceCommand) {
+  const sections = [];
+  sections.push("# Impact Explanation Request");
+  sections.push(`## Impact Output
+
+\`\`\`json
+${stdinJson}
+\`\`\``);
+  return sections.join("\n\n");
+}
+async function buildProposeAcceptanceCriteriaContext(configPath, targetSpecIds) {
+  const config = await loadConfig(configPath);
+  const models = config.models || [];
+  const specs = config.specs;
+  const allSummaries = extractSpecSummaries(models, specs);
+  const lintIssues = runLintForContext(models, specs);
+  const targetSpecs = targetSpecIds && targetSpecIds.length > 0 ? allSummaries.filter((s) => targetSpecIds.includes(s.id)) : allSummaries;
+  const sections = [];
+  sections.push("# Acceptance Criteria Proposal Request");
+  sections.push(
+    `## Project Configuration
+
+- Design directory: ${config.designDir || "design"}
+- Target specs: ${targetSpecs.length}` + (targetSpecIds ? ` (filtered from ${allSummaries.length} total)` : "")
+  );
+  if (targetSpecs.length > 0) {
+    sections.push("## Target Specs\n");
+    for (const spec of targetSpecs) {
+      sections.push(formatSpecForContext(spec));
+    }
+  }
+  if (targetSpecIds && targetSpecIds.length > 0) {
+    const relatedIds = /* @__PURE__ */ new Set();
+    for (const spec of targetSpecs) {
+      if (spec.relations) {
+        for (const rel of spec.relations) {
+          if (!targetSpecIds.includes(rel.target)) {
+            relatedIds.add(rel.target);
+          }
+        }
+      }
+    }
+    const relatedSpecs = allSummaries.filter((s) => relatedIds.has(s.id));
+    if (relatedSpecs.length > 0) {
+      sections.push("## Related Specs (for context)\n");
+      for (const spec of relatedSpecs) {
+        sections.push(formatSpecForContext(spec));
+      }
+    }
+  }
+  const relevantLintIssues = targetSpecIds ? lintIssues.filter((i) => i.specId && targetSpecIds.includes(i.specId)) : lintIssues;
+  if (relevantLintIssues.length > 0) {
+    sections.push("## Lint Issues (relevant)\n");
+    for (const issue of relevantLintIssues) {
+      sections.push(`- [${issue.severity}] [${issue.specId}] ${issue.message}`);
+    }
+  }
+  return sections.join("\n\n");
+}
+
+// src/agents/orchestrator.ts
+var EXIT_RUNTIME_MISSING = 11;
+var EXIT_ADAPTER_ERROR = 12;
+async function createAdapter(runtimePkg, name, config) {
+  switch (name) {
+    case "mock": {
+      const mod = await import(`${runtimePkg}/adapters/mock`);
+      return new mod.MockAdapter();
+    }
+    case "cursor": {
+      const mod = await import(`${runtimePkg}/adapters/cursor-sdk`);
+      const apiKey = process.env.CURSOR_API_KEY;
+      if (!apiKey) {
+        throw new Error(
+          "CURSOR_API_KEY environment variable is required for the cursor adapter.\nGet your key from: https://cursor.com/dashboard/integrations"
+        );
+      }
+      return mod.CursorSdkAdapter.create({ apiKey, model: config.model ?? "claude-sonnet-4" });
+    }
+    case "claude": {
+      const mod = await import(`${runtimePkg}/adapters/claude-agent-sdk`);
+      return new mod.ClaudeAgentSdkAdapter({
+        model: config.model,
+        tools: ["Read", "Glob", "Grep"],
+        permissionMode: "bypassPermissions"
+      });
+    }
+    case "openai": {
+      const mod = await import(`${runtimePkg}/adapters/openai-agents-sdk`);
+      return new mod.OpenAIAgentsSdkAdapter({
+        model: config.model ?? "o3-mini",
+        maxTurns: 1
+      });
+    }
+    case "gemini": {
+      const mod = await import(`${runtimePkg}/adapters/gemini-sdk`);
+      return new mod.GeminiSdkAdapter({
+        apiKey: process.env.GEMINI_API_KEY,
+        model: config.model ?? "gemini-2.5-pro",
+        temperature: config.temperature
+      });
+    }
+    default:
+      throw new Error(
+        `Unsupported adapter: "${name}". Available: mock, cursor, claude, openai, gemini.`
+      );
+  }
+}
+async function runAgentTask(userRequest, taskId, auditConfig, options) {
+  if (options.dryRun) {
+    return {
+      taskId,
+      data: null,
+      raw: "",
+      prompt: userRequest,
+      dryRun: true,
+      status: "success",
+      followUpsUsed: 0,
+      retriesUsed: 0
+    };
+  }
+  const RUNTIME_PKG = ["agent-contracts", "runtime"].join("-");
+  let runTask;
+  let agentRegistry2, taskRegistry2, handoffSchemas2;
+  try {
+    const runtime = await import(RUNTIME_PKG);
+    runTask = runtime.runTask;
+  } catch {
+    throw Object.assign(
+      new Error(
+        "agent-contracts-runtime is not installed. Install it to use this command, or use --dry-run to inspect the prompt.\n  npm install agent-contracts-runtime"
+      ),
+      { exitCode: EXIT_RUNTIME_MISSING }
+    );
+  }
+  try {
+    const dsl = await Promise.resolve().then(() => (init_dsl(), dsl_exports));
+    agentRegistry2 = dsl.agentRegistry;
+    taskRegistry2 = dsl.taskRegistry;
+    handoffSchemas2 = dsl.handoffSchemas;
+  } catch {
+    agentRegistry2 = {};
+    taskRegistry2 = {};
+    handoffSchemas2 = {};
+  }
+  const adapterName = auditConfig.adapter ?? "mock";
+  let adapter;
+  try {
+    adapter = await createAdapter(RUNTIME_PKG, adapterName, auditConfig);
+  } catch (err) {
+    throw Object.assign(err, { exitCode: EXIT_ADAPTER_ERROR });
+  }
+  const result = await runTask(adapter, taskId, {
+    user_request: userRequest
+  }, {
+    maxFollowUps: 3,
+    maxRetries: 1,
+    agentRegistry: agentRegistry2,
+    taskRegistry: taskRegistry2,
+    handoffSchemas: handoffSchemas2
+  });
+  const outcome = result.outcome;
+  return {
+    taskId,
+    data: outcome.status === "success" ? outcome.data : null,
+    raw: outcome.raw ?? "",
+    prompt: userRequest,
+    dryRun: false,
+    status: outcome.status,
+    errorMessage: outcome.status === "error" ? outcome.message : outcome.status === "escalation" ? outcome.reason : outcome.status === "validation_error" ? outcome.errors?.message : void 0,
+    followUpsUsed: result.follow_ups_used,
+    retriesUsed: result.retries_used
+  };
+}
+function computeExitCode(result, options) {
+  if (result.dryRun) return 0;
+  if (result.status !== "success" || !result.data) return 1;
+  const failOn = options.failOn ?? "error";
+  const severityOrder = ["info", "warning", "error", "critical"];
+  const threshold = severityOrder.indexOf(failOn);
+  const hasBlocking = result.data.findings.some(
+    (f) => severityOrder.indexOf(f.severity) >= threshold
+  );
+  return hasBlocking ? 10 : 0;
+}
+function formatResultText(result) {
+  if (result.dryRun) {
+    return result.prompt;
+  }
+  if (result.status !== "success" || !result.data) {
+    return result.errorMessage ?? `Task failed with status: ${result.status}`;
+  }
+  const data = result.data;
+  const lines = [];
+  lines.push(`Risk Level: ${data.riskLevel.toUpperCase()}`);
+  lines.push(`Summary: ${data.summary}`);
+  lines.push("");
+  if (data.findings.length > 0) {
+    lines.push(`Findings (${data.findings.length}):`);
+    lines.push("");
+    for (const finding of data.findings) {
+      const prefix = severityIcon(finding.severity);
+      lines.push(`  ${prefix} [${finding.category}] ${finding.message}`);
+      if (finding.location) {
+        lines.push(`    Location: ${finding.location}`);
+      }
+      if (finding.recommendation) {
+        lines.push(`    Recommendation: ${finding.recommendation}`);
+      }
+      lines.push("");
+    }
+  }
+  if (data.recommendedActions && data.recommendedActions.length > 0) {
+    lines.push("Recommended Actions:");
+    for (const action of data.recommendedActions) {
+      lines.push(`  - [${action.kind}] ${action.title}`);
+      if (action.command) {
+        lines.push(`    $ ${action.command}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function formatResultJson(result) {
+  if (result.dryRun) {
+    return JSON.stringify({ dryRun: true, prompt: result.prompt }, null, 2);
+  }
+  if (!result.data) {
+    return JSON.stringify({ error: result.errorMessage, status: result.status }, null, 2);
+  }
+  return JSON.stringify(result.data, null, 2);
+}
+function formatResultYaml(result) {
+  if (result.dryRun) {
+    return `dryRun: true
+prompt: |
+${indent(result.prompt)}`;
+  }
+  if (!result.data) {
+    return `error: ${JSON.stringify(result.errorMessage)}
+status: ${result.status}`;
+  }
+  return toSimpleYaml(result.data);
+}
+function formatResult(result, format) {
+  switch (format) {
+    case "json":
+      return formatResultJson(result);
+    case "yaml":
+      return formatResultYaml(result);
+    case "text":
+      return formatResultText(result);
+  }
+}
+async function writeOutput(content, outputPath) {
+  if (outputPath) {
+    await writeFile$1(outputPath, content + "\n", "utf-8");
+  } else {
+    process.stdout.write(content + "\n");
+  }
+}
+function severityIcon(severity) {
+  switch (severity) {
+    case "critical":
+      return "\u2716";
+    case "error":
+      return "\u2716";
+    case "warning":
+      return "\u26A0";
+    case "info":
+      return "\u2139";
+  }
+}
+function indent(text, spaces = 2) {
+  const pad = " ".repeat(spaces);
+  return text.split("\n").map((l) => pad + l).join("\n");
+}
+function toSimpleYaml(obj, depth = 0) {
+  const pad = "  ".repeat(depth);
+  if (obj === null || obj === void 0) return `${pad}null`;
+  if (typeof obj === "string") {
+    if (obj.includes("\n")) return `|
+${indent(obj, (depth + 1) * 2)}`;
+    return JSON.stringify(obj);
+  }
+  if (typeof obj === "number" || typeof obj === "boolean") return String(obj);
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return "[]";
+    return obj.map((item) => {
+      const val = toSimpleYaml(item, depth + 1);
+      if (typeof item === "object" && item !== null) {
+        return `${pad}- ${val.trimStart()}`;
+      }
+      return `${pad}- ${val}`;
+    }).join("\n");
+  }
+  if (typeof obj === "object") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) return "{}";
+    return entries.map(([k, v]) => {
+      const val = toSimpleYaml(v, depth + 1);
+      if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+        return `${pad}${k}:
+${val}`;
+      }
+      if (Array.isArray(v) && v.length > 0) {
+        return `${pad}${k}:
+${val}`;
+      }
+      return `${pad}${k}: ${val}`;
+    }).join("\n");
+  }
+  return String(obj);
+}
+
+// src/cli/audit-requirements.ts
+async function commandAuditRequirements(opts) {
+  const context = await buildAuditRequirementsContext(opts.config);
+  const auditConfig = {
+    adapter: opts.adapter,
+    model: opts.model
+  };
+  const auditOpts = {
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
+  };
+  try {
+    const result = await runAgentTask(
+      context,
+      "audit-requirement-quality",
+      auditConfig,
+      auditOpts
+    );
+    const content = formatResult(result, opts.reportFormat ?? "text");
+    await writeOutput(content, opts.output);
+    const exitCode = computeExitCode(result, auditOpts);
+    if (exitCode !== 0) process.exit(exitCode);
+  } catch (err) {
+    const exitCode = err.exitCode;
+    if (exitCode === EXIT_RUNTIME_MISSING) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_RUNTIME_MISSING);
+    }
+    if (exitCode === EXIT_ADAPTER_ERROR) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_ADAPTER_ERROR);
+    }
+    throw err;
+  }
+}
+async function commandProposeTraceLinks(opts) {
+  const context = await buildProposeTraceLinksContext(opts.config);
+  const auditConfig = {
+    adapter: opts.adapter,
+    model: opts.model
+  };
+  const auditOpts = {
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
+  };
+  try {
+    const result = await runAgentTask(
+      context,
+      "propose-trace-links",
+      auditConfig,
+      auditOpts
+    );
+    const content = formatResult(result, opts.reportFormat ?? "json");
+    await writeOutput(content, opts.output);
+    const exitCode = computeExitCode(result, auditOpts);
+    if (exitCode !== 0) process.exit(exitCode);
+  } catch (err) {
+    const exitCode = err.exitCode;
+    if (exitCode === EXIT_RUNTIME_MISSING) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_RUNTIME_MISSING);
+    }
+    if (exitCode === EXIT_ADAPTER_ERROR) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_ADAPTER_ERROR);
+    }
+    throw err;
+  }
+}
+async function commandExplainImpact(opts) {
+  const stdin = await readStdin();
+  if (!stdin.trim()) {
+    console.error(chalk4.red("Error: No input received on stdin."));
+    console.error("Usage: speckeeper impact FR-001 --format json | speckeeper explain-impact");
+    process.exit(2);
+  }
+  const context = buildExplainImpactContext(stdin);
+  const auditConfig = {
+    adapter: opts.adapter,
+    model: opts.model
+  };
+  const auditOpts = {
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
+  };
+  try {
+    const result = await runAgentTask(
+      context,
+      "explain-impact-result",
+      auditConfig,
+      auditOpts
+    );
+    const content = formatResult(result, opts.reportFormat ?? "json");
+    await writeOutput(content, opts.output);
+    const exitCode = computeExitCode(result, auditOpts);
+    if (exitCode !== 0) process.exit(exitCode);
+  } catch (err) {
+    const exitCode = err.exitCode;
+    if (exitCode === EXIT_RUNTIME_MISSING) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_RUNTIME_MISSING);
+    }
+    if (exitCode === EXIT_ADAPTER_ERROR) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_ADAPTER_ERROR);
+    }
+    throw err;
+  }
+}
+function readStdin() {
+  return new Promise((resolve3, 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("error", reject);
+    if (process.stdin.isTTY) {
+      resolve3("");
+    }
+  });
+}
+async function commandProposeAcceptanceCriteria(specIds, opts) {
+  const targetSpecIds = specIds.length > 0 ? specIds : void 0;
+  const context = await buildProposeAcceptanceCriteriaContext(opts.config, targetSpecIds);
+  const auditConfig = {
+    adapter: opts.adapter,
+    model: opts.model
+  };
+  const auditOpts = {
+    dryRun: opts.dryRun,
+    failOn: opts.failOn
+  };
+  try {
+    const result = await runAgentTask(
+      context,
+      "propose-acceptance-criteria",
+      auditConfig,
+      auditOpts
+    );
+    const content = formatResult(result, opts.reportFormat ?? "json");
+    await writeOutput(content, opts.output);
+    const exitCode = computeExitCode(result, auditOpts);
+    if (exitCode !== 0) process.exit(exitCode);
+  } catch (err) {
+    const exitCode = err.exitCode;
+    if (exitCode === EXIT_RUNTIME_MISSING) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_RUNTIME_MISSING);
+    }
+    if (exitCode === EXIT_ADAPTER_ERROR) {
+      console.error(chalk4.red(err.message));
+      process.exit(EXIT_ADAPTER_ERROR);
+    }
+    throw err;
+  }
+}
+
 // src/cli/index.ts
 function getVersion() {
   try {
@@ -2272,6 +3396,58 @@ program.command("new").description("Create a new element with auto-generated ID"
 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();
 //# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map