speckeeper 0.10.0 → 0.11.0

package/docs/design/cli-commands.md

@@ -9,6 +9,11 @@
 | init | Initialize a new speckeeper project with starter templates |
 | new | Create a new element with auto-generated ID |
 | scaffold | Generate _models/ from a mermaid flowchart definition |
+| audit-requirements | Semantic requirement quality audit via LLM (verifiability, ambiguity, granularity, terminology, design-mixing) |
+| propose-trace-links | Propose candidate traceability links between specs with confidence scores and rationale |
+| explain-impact | Translate impact analysis JSON (from stdin) into human-readable explanation for PM/executive audiences |
+| propose-acceptance-criteria | Propose testable acceptance criteria in Given/When/Then format for specified specs |
+| convert | Convert a TS spec data file to YAML format |
 | impact | Analyze the change impact scope of a specified ID |
 
 ---
@@ -293,6 +298,218 @@ speckeeper scaffold -s spec.md --dry-run
 
 ---
 
+## CMD-AUDIT-REQ: audit-requirements
+
+Semantic requirement quality audit via LLM (verifiability, ambiguity, granularity, terminology, design-mixing)
+
+### Usage
+
+```bash
+speckeeper audit-requirements [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -a, --adapter | option | enum |  | - | SDK adapter for LLM execution |
+| --model | option | string |  | - | LLM model override |
+| -n, --dry-run | option | boolean |  | false | Output constructed prompt without calling LLM |
+| --fail-on | option | enum |  | error | Minimum severity for non-zero exit |
+| -o, --output | option | path |  | - | Write result to file instead of stdout |
+| --report-format | option | enum |  | json | Output format for audit report |
+| --show-prompt | option | boolean |  | false | Display constructed LLM prompt on stderr |
+
+### Examples
+
+```bash
+speckeeper audit-requirements
+speckeeper audit-requirements --adapter openai --dry-run
+speckeeper audit-requirements --report-format json --output audit.json
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | No blocking findings |
+| 1 | Unexpected error |
+| 2 | Configuration or input error |
+| 10 | Completed with blocking findings |
+| 11 | Runtime dependency missing |
+| 12 | LLM provider or adapter error |
+
+---
+
+## CMD-PROPOSE-TRACE: propose-trace-links
+
+Propose candidate traceability links between specs with confidence scores and rationale
+
+### Usage
+
+```bash
+speckeeper propose-trace-links [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -a, --adapter | option | enum |  | - | SDK adapter for LLM execution |
+| --model | option | string |  | - | LLM model override |
+| -n, --dry-run | option | boolean |  | false | Output constructed prompt without calling LLM |
+| --fail-on | option | enum |  | error | Minimum severity for non-zero exit |
+| -o, --output | option | path |  | - | Write result to file instead of stdout |
+| --report-format | option | enum |  | json | Output format for report |
+| --show-prompt | option | boolean |  | false | Display constructed LLM prompt on stderr |
+
+### Examples
+
+```bash
+speckeeper propose-trace-links
+speckeeper propose-trace-links --adapter claude --report-format json
+speckeeper propose-trace-links --dry-run
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | No blocking findings |
+| 1 | Unexpected error |
+| 2 | Configuration or input error |
+| 10 | Completed with blocking findings |
+| 11 | Runtime dependency missing |
+| 12 | LLM provider or adapter error |
+
+---
+
+## CMD-EXPLAIN-IMPACT: explain-impact
+
+Translate impact analysis JSON (from stdin) into human-readable explanation for PM/executive audiences
+
+### Usage
+
+```bash
+speckeeper explain-impact [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| -c, --config | option | path |  | - | Path to config file |
+| -a, --adapter | option | enum |  | - | SDK adapter for LLM execution |
+| --model | option | string |  | - | LLM model override |
+| -n, --dry-run | option | boolean |  | false | Output constructed prompt without calling LLM |
+| --fail-on | option | enum |  | error | Minimum severity for non-zero exit |
+| -o, --output | option | path |  | - | Write result to file instead of stdout |
+| --report-format | option | enum |  | json | Output format for report |
+| --show-prompt | option | boolean |  | false | Display constructed LLM prompt on stderr |
+
+### Examples
+
+```bash
+speckeeper impact FR-001 --format json | speckeeper explain-impact
+speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter claude
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Explanation completed |
+| 1 | Unexpected error |
+| 2 | Configuration or input error |
+| 3 | No input on stdin |
+| 10 | Completed with blocking findings |
+| 11 | Runtime dependency missing |
+| 12 | LLM provider or adapter error |
+
+---
+
+## CMD-PROPOSE-AC: propose-acceptance-criteria
+
+Propose testable acceptance criteria in Given/When/Then format for specified specs
+
+### Usage
+
+```bash
+speckeeper propose-acceptance-criteria [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| <specIds> | argument | string |  | - | Spec IDs to propose criteria for (defaults to all) |
+| -c, --config | option | path |  | - | Path to config file |
+| -a, --adapter | option | enum |  | - | SDK adapter for LLM execution |
+| --model | option | string |  | - | LLM model override |
+| -n, --dry-run | option | boolean |  | false | Output constructed prompt without calling LLM |
+| --fail-on | option | enum |  | error | Minimum severity for non-zero exit |
+| -o, --output | option | path |  | - | Write result to file instead of stdout |
+| --report-format | option | enum |  | json | Output format for report |
+| --show-prompt | option | boolean |  | false | Display constructed LLM prompt on stderr |
+
+### Examples
+
+```bash
+speckeeper propose-acceptance-criteria
+speckeeper propose-acceptance-criteria FR-001 FR-002
+speckeeper propose-acceptance-criteria --adapter gemini --dry-run
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | No blocking findings |
+| 1 | Unexpected error |
+| 2 | Configuration or input error |
+| 10 | Completed with blocking findings |
+| 11 | Runtime dependency missing |
+| 12 | LLM provider or adapter error |
+
+---
+
+## CMD-CONVERT: convert
+
+Convert a TS spec data file to YAML format
+
+### Usage
+
+```bash
+speckeeper convert [options]
+```
+
+### Parameters
+
+| Name | Kind | Type | Required | Default | Description |
+|------|------|------|----------|---------|-------------|
+| <file> | argument | path | ✓ | - | Path to TS spec data file |
+| -o, --output | option | path |  | - | Output file path (default: same name with .yaml extension) |
+| -n, --dry-run | option | boolean |  | false | Preview conversion without writing |
+
+### Examples
+
+```bash
+speckeeper convert design/glossary.ts
+speckeeper convert design/requirements.ts --output reqs.yaml
+speckeeper convert design/glossary.ts --dry-run
+```
+
+### Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Conversion successful |
+| 1 | Conversion error |
+
+---
+
 ## CMD-IMPACT: impact
 
 Analyze the change impact scope of a specified ID

package/docs/design/functional-requirements.md

@@ -51,6 +51,11 @@
 | FR-1017 | Source Path Fallback | must | check |
 | FR-1018 | Minimal New Dependencies | must | check |
 | FR-1019 | Checker Documentation Accuracy | must | check |
+| FR-1100 | LLM-Powered Requirement Audit | should | llm |
+| FR-1101 | LLM-Powered Trace Link Proposal | should | llm |
+| FR-1102 | LLM-Powered Impact Explanation | should | llm |
+| FR-1103 | LLM-Powered Acceptance Criteria Proposal | should | llm |
+| FR-1104 | TypeScript to YAML Conversion | should | conversion |
 
 ---
 
@@ -395,8 +400,8 @@ Since consistency checks are implemented per model, filter by model name
 ### Acceptance Criteria
 
 - **FR-602-01**: speckeeper check runs external SSOT consistency check for all models [test]
-- **FR-602-02**: speckeeper check --model <model-name> checks only specific model [test]
-- **FR-602-03**: Model name is the model ID defined in design/_models/ [review]
+- **FR-602-02**: speckeeper check [type] filters checks by type (openapi, ddl, iac, external-ssot, test, contract) [test]
+- **FR-602-03**: Type argument corresponds to check categories, not model IDs [review]
 - **FR-602-04**: Only models with externalChecker are targeted [test]
 
 ---
@@ -807,4 +812,97 @@ README and scaffold-mermaid-spec.md accurately describe all three built-in check
 ### Acceptance Criteria
 
 - **FR-1019-01**: README checker table describes validation levels [review]
-- **FR-1019-02**: scaffold-mermaid-spec.md Section 7 describes validation levels [review]
+- **FR-1019-02**: scaffold-mermaid-spec.md Section 7 describes validation levels [review]
+
+---
+
+## FR-1100: LLM-Powered Requirement Audit
+
+**Type**: functional | **Priority**: should | **Category**: llm
+
+Provide LLM-based semantic quality audit for requirement definitions, detecting verifiability issues, ambiguity, granularity problems, terminology inconsistency, and design-mixing
+
+### Rationale
+
+Static lint rules cannot detect semantic issues such as ambiguous wording or design details mixed into requirements; LLM review complements structural checks
+
+### Acceptance Criteria
+
+- **FR-1100-01**: audit-requirements command constructs a prompt from all registered specs and sends it to configured LLM adapter [test]
+- **FR-1100-02**: Audit report includes findings with severity (error/warning/info) and affected spec IDs [test]
+- **FR-1100-03**: --dry-run outputs the constructed prompt without calling LLM [test]
+- **FR-1100-04**: --fail-on controls minimum severity that causes non-zero exit [test]
+- **FR-1100-05**: Report format is selectable via --report-format (json, text, yaml) [test]
+
+---
+
+## FR-1101: LLM-Powered Trace Link Proposal
+
+**Type**: functional | **Priority**: should | **Category**: llm
+
+Propose candidate traceability links between specs with confidence scores and rationale using LLM analysis
+
+### Rationale
+
+Manual traceability maintenance is error-prone; LLM can identify semantically related specs that humans may overlook
+
+### Acceptance Criteria
+
+- **FR-1101-01**: propose-trace-links command analyzes all specs and proposes missing trace links [test]
+- **FR-1101-02**: Each proposed link includes source ID, target ID, relation type, confidence score, and rationale [test]
+- **FR-1101-03**: --dry-run outputs the constructed prompt without calling LLM [test]
+
+---
+
+## FR-1102: LLM-Powered Impact Explanation
+
+**Type**: functional | **Priority**: should | **Category**: llm
+
+Translate impact analysis JSON output into human-readable explanation for PM/executive audiences using LLM
+
+### Rationale
+
+Raw impact analysis JSON is not consumable by non-technical stakeholders; LLM can generate natural language summaries
+
+### Acceptance Criteria
+
+- **FR-1102-01**: explain-impact command reads impact analysis JSON from stdin [test]
+- **FR-1102-02**: Output is a human-readable explanation suitable for PM/executive audiences [review]
+- **FR-1102-03**: --dry-run outputs the constructed prompt without calling LLM [test]
+
+---
+
+## FR-1103: LLM-Powered Acceptance Criteria Proposal
+
+**Type**: functional | **Priority**: should | **Category**: llm
+
+Propose testable acceptance criteria in Given/When/Then format for specified specs using LLM
+
+### Rationale
+
+Writing testable acceptance criteria is time-consuming; LLM can propose initial criteria that humans refine
+
+### Acceptance Criteria
+
+- **FR-1103-01**: propose-acceptance-criteria command generates criteria for specified spec IDs (or all) [test]
+- **FR-1103-02**: Proposed criteria follow Given/When/Then format [review]
+- **FR-1103-03**: --dry-run outputs the constructed prompt without calling LLM [test]
+
+---
+
+## FR-1104: TypeScript to YAML Conversion
+
+**Type**: functional | **Priority**: should | **Category**: conversion
+
+Convert TypeScript spec data files to equivalent YAML format, enabling non-TypeScript workflows and interoperability
+
+### Rationale
+
+YAML input lowers participation barriers for non-developers (NFR-005) and enables interoperability with external tools
+
+### Acceptance Criteria
+
+- **FR-1104-01**: convert command reads a TS file exporting a SpecModule via defineSpecs() and writes equivalent YAML [test]
+- **FR-1104-02**: Output defaults to same filename with .yaml extension [test]
+- **FR-1104-03**: --output allows specifying a custom output path [test]
+- **FR-1104-04**: --dry-run previews conversion without writing files [test]

package/docs/design/nonfunctional-requirements.md

@@ -214,15 +214,15 @@ To ensure all acceptance criteria are covered by test cases and maintain spec-te
 
 **Type**: non-functional | **Priority**: must | **Category**: testability
 
-CLI command definitions in design/cli-commands.ts match actual implementation in src/cli/index.ts
+CLI command definitions in design/cli-commands.ts match cli-contract.yaml and generated code in src/generated/
 
 ### Rationale
 
-To ensure specification and implementation stay synchronized (e.g., no missing --config parameters)
+To ensure specification, DSL contract, and generated implementation stay synchronized
 
 ### Acceptance Criteria
 
-- **NFR-014-01**: All command definitions in design/cli-commands.ts match implementation (parameters, subcommands, exit codes) [test]
+- **NFR-014-01**: All command definitions in design/cli-commands.ts match cli-contract.yaml and generated code (parameters, subcommands, exit codes) [test]
 
 ---
 

package/docs/design/test-refs.md

@@ -12,6 +12,7 @@
 | TEST-023 | Impact command verification test | vitest | 1 |
 | TEST-024 | Drift command verification test | vitest | 1 |
 | TEST-025 | New command verification test | vitest | 1 |
+| TEST-026 | Scaffold integration verification test (mermaid parsing, class-based generation) | vitest | 1 |
 
 ---
 
@@ -256,3 +257,28 @@
 | FR-104-01 | `FR-104-01.*available model types header` | Outputs model types header when type omitted |
 
 ---
+
+## TEST-026: Scaffold integration verification test (mermaid parsing, class-based generation)
+
+### Test Source
+
+- **Path**: `test/scaffold/integration.test.ts`
+- **Framework**: vitest
+
+### Verified Requirements
+
+- FR-106
+
+### Implemented Command
+
+- CMD-SCAFFOLD
+
+### Test Case Patterns
+
+| Acceptance Criteria ID | Pattern | Description |
+|------------------------|---------|-------------|
+| FR-106-01 | `base template.*core factory|generated models.*base template` | Artifact class generates from base template |
+| FR-106-03 | `SR.*FR.*NFR.*map to requirement.*de-duplicated` | Same-class node aggregation into single model file |
+| FR-106-05 | `de-duplicated model files.*spec data` | Model file generation with naming conventions |
+
+---

package/docs/model-guide.md

@@ -109,7 +109,10 @@ export interface Exporter<T> {
   format: 'markdown' | 'json' | 'mermaid';
   single?: (spec: T) => string;
   index?: (specs: T[]) => string;
+  /** Subdirectory under docsDir (used with single + index/index.md) */
   outputDir?: string;
+  /** Direct output file path relative to docsDir (used with index-only exporters) */
+  outputFile?: string;
   filename?: (spec: T) => string;
 }
 
@@ -138,34 +141,31 @@ export interface CheckResult {
   }>;
 }
 
-/**
- * Coverage result
- */
-export interface CoverageResult {
-  /** Total target count */
-  total: number;
-  /** Covered count */
-  covered: number;
-  /** Uncovered count */
-  uncovered: number;
-  /** Coverage rate (%) */
-  coveragePercent: number;
-  /** Details of covered items */
-  coveredItems: { id: string; description?: string }[];
-  /** Details of uncovered items */
-  uncoveredItems: { id: string; description?: string; sourceId?: string }[];
+// ============================================================================
+// Deep Validation (replaces per-model externalChecker)
+// ============================================================================
+
+/** OpenAPI deep validation mapping */
+export interface OpenAPIValidationMapping {
+  path: string;
+  method?: string;
+  parameters?: Array<{ name: string; in?: string; type?: string }>;
+  responseProperties?: Array<{ name: string; type?: string }>;
+}
+
+/** DDL deep validation mapping */
+export interface DDLValidationMapping {
+  tableName: string;
+  columns?: Array<{ name: string; type?: string }>;
+  checkTypes?: boolean;
 }
 
 /**
- * Coverage checker definition
- * 
- * Verify cross-model consistency (coverage).
- * Example: Whether TestRef covers acceptanceCriteria of Requirement
+ * Deep validation rule for a specific source type.
+ * The mapper extracts expected structure from a spec for detailed comparison
+ * against the matched source object.
  */
-export interface CoverageChecker<T> {
-  /** Target model ID for coverage (e.g. 'requirement') */
-  targetModel: string;
-  /** Description of coverage check */
+export interface DeepValidationRule<T, TMapping = unknown> {
 ```
 <!--@embedoc:end-->
 
@@ -175,54 +175,54 @@ export interface CoverageChecker<T> {
 **src/core/model.ts (Model Class Properties)**
 
 ```typescript
-  /** Execute coverage check */
-  check: (
-    specs: T[],
-    registry: Record<string, Map<string, unknown>>
-  ) => CoverageResult;
 }
 
-// ============================================================================
-// Renderer (for embeds)
-// ============================================================================
-
 /**
- * Render context
- * Simplified version compatible with embedoc's EmbedContext
+ * Deep validation configuration keyed by source type.
+ * Models define this to enable Level 2/3 checks beyond existence.
  */
-export interface RenderContext {
-  /** Parameters (filter conditions other than format, etc.) */
-  params: Record<string, string | undefined>;
-  /** Markdown helpers */
-  markdown: {
-    /** Generate table */
-    table: (headers: string[], rows: (string | unknown)[][]) => string;
-  };
+export interface DeepValidationConfig<T> {
+  openapi?: DeepValidationRule<T, OpenAPIValidationMapping>;
+  ddl?: DeepValidationRule<T, DDLValidationMapping>;
+  [sourceType: string]: DeepValidationRule<T, unknown> | undefined;
 }
 
 /**
- * Renderer definition
- * 
- * Model-specific rendering called from embeds
+ * Lookup key configuration keyed by source type.
+ * When a model's spec ID differs from the external identifier
+ * (e.g. entity ID "user" vs DDL table name "users"),
+ * define a mapper per source type to derive the external key.
+ * If not defined for a source type, spec.id is used as-is.
  */
-export interface Renderer<T> {
-  /** Format ID ('table', 'list', 'detail', 'spec-chapter', etc.) */
-  format: string;
-  /** Rendering process */
-  render: (specs: T[], ctx: RenderContext) => string;
+export interface LookupKeyConfig<T> {
+  [sourceType: string]: ((spec: T) => string) | undefined;
 }
 
-// ============================================================================
-// Model Base Class
-// ============================================================================
+/**
+ * Coverage result
+ */
+export interface CoverageResult {
+  /** Total target count */
+  total: number;
+  /** Covered count */
+  covered: number;
+  /** Uncovered count */
+  uncovered: number;
+  /** Coverage rate (%) */
+  coveragePercent: number;
+  /** Details of covered items */
+  coveredItems: { id: string; description?: string }[];
+  /** Details of uncovered items */
+  uncoveredItems: { id: string; description?: string; sourceId?: string }[];
+}
 
 /**
- * Model base class
+ * Coverage checker definition
  * 
- * @template TSchema - Zod schema type
+ * Verify cross-model consistency (coverage).
+ * Example: Whether TestRef covers acceptanceCriteria of Requirement
  */
-export abstract class Model<TSchema extends ZodType> {
-  /** Singleton instance storage (per subclass) */
+export interface CoverageChecker<T> {
 ```
 <!--@embedoc:end-->
 
@@ -493,61 +493,65 @@ class TestRefModel extends Model<typeof TestRefSchema> {
   protected exporters: Exporter<TestRef>[] = [
     {
       format: 'markdown',
-      single: (spec) => {
+      index: (specs) => {
         const lines: string[] = [];
-        lines.push(`# ${spec.id}: ${spec.description}`);
-        lines.push('');
-        lines.push('## Test Source');
+        lines.push('# Test Reference List');
         lines.push('');
-        lines.push(`- **Path**: \`${spec.source.path}\``);
-        lines.push(`- **Framework**: ${spec.source.framework}`);
-        if (spec.source.resultPath) {
-          lines.push(`- **Result JSON**: \`${spec.source.resultPath}\``);
+        lines.push('| ID | Description | Framework | Requirements Count |');
+        lines.push('|----|-------------|-----------|-------------------|');
+        for (const spec of specs) {
+          lines.push(
+            `| ${spec.id} | ${spec.description} | ${spec.source.framework} | ${spec.verifiesRequirements.length} |`,
+          );
         }
         lines.push('');
-
-        lines.push('## Verified Requirements');
-        lines.push('');
-        for (const reqId of spec.verifiesRequirements) {
-          lines.push(`- ${reqId}`);
-        }
+        lines.push('---');
         lines.push('');
 
-        if (spec.implementsCommand) {
-          lines.push('## Implemented Command');
+        for (const spec of specs) {
+          lines.push(`## ${spec.id}: ${spec.description}`);
           lines.push('');
-          lines.push(`- ${spec.implementsCommand}`);
+          lines.push('### Test Source');
+          lines.push('');
+          lines.push(`- **Path**: \`${spec.source.path}\``);
+          lines.push(`- **Framework**: ${spec.source.framework}`);
+          if (spec.source.resultPath) {
+            lines.push(`- **Result JSON**: \`${spec.source.resultPath}\``);
+          }
           lines.push('');
-        }
 
-        if (spec.testCasePatterns && spec.testCasePatterns.length > 0) {
-          lines.push('## Test Case Patterns');
+          lines.push('### Verified Requirements');
           lines.push('');
-          lines.push('| Acceptance Criteria ID | Pattern | Description |');
-          lines.push('|------------------------|---------|-------------|');
-          for (const p of spec.testCasePatterns) {
-            lines.push(`| ${p.acceptanceCriteriaId} | \`${p.pattern}\` | ${p.description || '-'} |`);
+          for (const reqId of spec.verifiesRequirements) {
+            lines.push(`- ${reqId}`);
           }
           lines.push('');
-        }
 
-        return lines.join('\n');
-      },
-      index: (specs) => {
-        const lines: string[] = [];
-        lines.push('# Test Reference List');
-        lines.push('');
-        lines.push('| ID | Description | Framework | Requirements Count |');
-        lines.push('|----|-------------|-----------|-------------------|');
-        for (const spec of specs) {
-          lines.push(
-            `| [${spec.id}](./${spec.id}.md) | ${spec.description} | ${spec.source.framework} | ${spec.verifiesRequirements.length} |`,
-          );
+          if (spec.implementsCommand) {
+            lines.push('### Implemented Command');
+            lines.push('');
+            lines.push(`- ${spec.implementsCommand}`);
+            lines.push('');
+          }
+
+          if (spec.testCasePatterns && spec.testCasePatterns.length > 0) {
+            lines.push('### Test Case Patterns');
+            lines.push('');
+            lines.push('| Acceptance Criteria ID | Pattern | Description |');
+            lines.push('|------------------------|---------|-------------|');
+            for (const p of spec.testCasePatterns) {
+              lines.push(`| ${p.acceptanceCriteriaId} | \`${p.pattern}\` | ${p.description || '-'} |`);
+            }
+            lines.push('');
+          }
+
+          lines.push('---');
+          lines.push('');
         }
-        return lines.join('\n');
+
+        return lines.join('\n').replace(/\n---\n\n$/s, '\n');
       },
-      outputDir: 'test-refs',
-      filename: (spec) => spec.id,
+      outputFile: 'design/test-refs.md',
     },
   ];