speckeeper 0.10.0 → 0.10.1

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: speckeeper CLI
-  version: 0.10.0
+  version: 0.10.1
   description: >-
     TypeScript-first specification validation framework — validate design
     consistency, external SSOT integrity, and traceability with type-safe

package/docs/design/cli-commands.md

@@ -9,6 +9,10 @@
 | 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 |
 | impact | Analyze the change impact scope of a specified ID |
 
 ---
@@ -293,6 +297,183 @@ 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-IMPACT: impact
 
 Analyze the change impact scope of a specified ID

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',
     },
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speckeeper",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "TypeScript-first specification validation framework with external SSOT integration",
   "type": "module",
   "main": "./dist/index.js",