speckeeper 0.9.4 → 0.10.1

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 TypeScript-first specification validation framework — validate design consistency, external SSOT integrity, and traceability with type-safe TypeScript DSL. Supports design lint, external source checks (OpenAPI, DDL, annotations), drift detection, impact analysis, and scaffolding from Mermaid flowcharts.
 
-**Version:** 0.9.4
+**Version:** 0.10.0
 
 ## Table of Contents
 
@@ -15,6 +15,10 @@ TypeScript-first specification validation framework — validate design consiste
   - [new](#speckeeper-new)
   - [impact](#speckeeper-impact)
   - [scaffold](#speckeeper-scaffold)
+  - [audit-requirements](#speckeeper-audit-requirements)
+  - [propose-trace-links](#speckeeper-propose-trace-links)
+  - [explain-impact](#speckeeper-explain-impact)
+  - [propose-acceptance-criteria](#speckeeper-propose-acceptance-criteria)
 
 ---
 
@@ -48,7 +52,7 @@ speckeeper init --force
 
 | Option | Aliases | Required | Default | Description |
 |---|---|---|---|---|
-| `--force` | -f | No | `false` | Overwrite existing files. |
+| `--force` | -F | No | `false` | Overwrite existing files. |
 
 #### Exit Codes
 
@@ -64,11 +68,12 @@ speckeeper init --force
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  riskLevel: medium
+  requiresConfirmation: true
   idempotent: false
   sideEffects: 
     - file_write
+  sideEffectNote: Creates config file and design/ directory structure. With --force, overwrites existing files.
 ```
 
 ---
@@ -120,6 +125,7 @@ x-agent:
   idempotent: true
   sideEffects: 
     - file_write
+  sideEffectNote: When --watch is used, the process runs indefinitely and is unsuitable for non-interactive agent invocation. Always writes generated files to docs/ and specs/.
 ```
 
 ---
@@ -156,11 +162,11 @@ speckeeper lint --phase HLD --fix
 
 **Exit 0:** No lint issues found (or all issues auto-fixed).
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Lint issues found (errors or warnings with --strict).
 
-- **stderr:** format=`text`
+- **stdout:** format=`{options.format}`
 
 #### Extensions
 
@@ -170,7 +176,9 @@ x-agent:
   requiresConfirmation: false
   idempotent: true
   sideEffects: 
-
+    - file_write
+  sideEffectNote: file_write applies only when --fix is provided. Without --fix the command is read-only.
+  safeDryRunOption: Omit --fix to run in read-only mode.
 ```
 
 ---
@@ -206,21 +214,22 @@ speckeeper drift --update --format diff
 
 **Exit 0:** No drift detected (or drift auto-updated with --update).
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Drift detected (with --fail-on-drift), or update failed.
 
-- **stderr:** format=`text`
+- **stdout:** format=`{options.format}`
 
 #### Extensions
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  riskLevel: medium
+  requiresConfirmation: true
   idempotent: true
   sideEffects: 
-
+    - file_write
+  sideEffectNote: file_write applies only when --update is provided. Without --update the command is read-only.
   safeDryRunOption: Omit --update to run in read-only mode.
 ```
 
@@ -261,16 +270,17 @@ speckeeper check openapi --strict
 | `--strict` |  | No | `false` | Treat warnings as errors. |
 | `--verbose` | -v | No | `false` | Show detailed output (e.g. list unmatched specs). |
 | `--coverage` |  | No | `false` | Check if all testable acceptance criteria are covered by TestRefs. |
+| `--format` | -f | No | `"text"` | Output format: text, json, github. |
 
 #### Exit Codes
 
 **Exit 0:** All checks passed (all specs found in sources, deep validation passed).
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Check failures found (missing specs, structural mismatches, or coverage gaps).
 
-- **stderr:** format=`text`
+- **stdout:** format=`{options.format}`
 
 #### Extensions
 
@@ -317,10 +327,11 @@ speckeeper new usecase --template custom-template.ts
 | `--name` | -n | No |  | Name of the element. |
 | `--output` | -o | No |  | Output directory path. |
 | `--template` | -t | No |  | Path to template file. |
+| `--dry-run` |  | No | `false` | Preview generated file content and ID without writing to disk. |
 
 #### Exit Codes
 
-**Exit 0:** Element file created with auto-generated ID.
+**Exit 0:** Element file created (or previewed with --dry-run) with auto-generated ID.
 
 - **stdout:** format=`text`
 
@@ -337,6 +348,8 @@ x-agent:
   idempotent: false
   sideEffects: 
     - file_write
+  sideEffectNote: Creates a new TypeScript spec file with auto-generated ID. With --dry-run, only previews the generated content without writing.
+  safeDryRunOption: --dry-run
 ```
 
 ---
@@ -370,7 +383,7 @@ speckeeper impact COMP-AUTH --format mermaid
 | Option | Aliases | Required | Default | Description |
 |---|---|---|---|---|
 | `--config` | -c | No |  | Path to config file. |
-| `--depth` | -d | No | `"3"` | Analysis depth (reference tracking level). |
+| `--depth` | -d | No | `3` | Analysis depth (reference tracking level). |
 | `--direction` |  | No | `"both"` | Analysis direction: upstream, downstream, both. |
 | `--format` | -f | No | `"text"` | Output format: text, json, mermaid. |
 
@@ -378,7 +391,7 @@ speckeeper impact COMP-AUTH --format mermaid
 
 **Exit 0:** Impact analysis completed and displayed.
 
-- **stdout:** format=`text`
+- **stdout:** format=`{options.format}`
 
 **Exit 1:** Analysis failed (ID not found or config error).
 
@@ -421,7 +434,7 @@ speckeeper scaffold --source arch.md --dry-run
 |---|---|---|---|---|
 | `--source` | -s | Yes |  | Path to Markdown file containing Mermaid flowchart. |
 | `--output` | -o | No | `"design/"` | Output directory. |
-| `--force` | -f | No | `false` | Overwrite existing files. |
+| `--force` | -F | No | `false` | Overwrite existing files. |
 | `--dry-run` |  | No | `false` | Preview generated files without writing. |
 
 #### Exit Codes
@@ -438,12 +451,324 @@ speckeeper scaffold --source arch.md --dry-run
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  riskLevel: high
+  requiresConfirmation: true
   idempotent: false
   sideEffects: 
     - file_write
+  sideEffectNote: --force overwrites existing TypeScript model source files.
+  safeDryRunOption: --dry-run
+```
+
+---
+
+### audit-requirements
+
+Run LLM-based requirement quality audit.
+
+Performs semantic analysis of design specs using LLM to identify quality issues that static lint cannot detect. Evaluates verifiability, ambiguity, granularity, terminology consistency, and design-mixing. Requires agent-contracts-runtime as an optional peer dependency.
+
+**Usage:**
+
+```
+speckeeper audit-requirements
+```
+```
+speckeeper audit-requirements --adapter gemini --dry-run
+```
+```
+speckeeper audit-requirements --report-format json --output audit.json
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file. |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
+| `--show-prompt` |  | No | `false` | Display the constructed LLM prompt on stderr. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"json"` | Output format for the audit report. |
+
+#### Exit Codes
+
+**Exit 0:** Audit completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 2:** Configuration or input error.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  riskLevel: medium
+  requiresConfirmation: false
+  idempotent: true
+  sideEffects: 
+    - network
+    - file_write
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write when --output is specified. Exit 10 = valid output with blocking findings (stdout contains result). Exit 11 = missing runtime dependency (non-retryable).
+  safeDryRunOption: --dry-run
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### propose-trace-links
+
+LLM-based traceability link proposal.
+
+Analyzes spec definitions and external source scan results to propose candidate traceability links between specs and implementation artifacts. Each link includes a confidence score and rationale.
+
+**Usage:**
+
+```
+speckeeper propose-trace-links
+```
+```
+speckeeper propose-trace-links --adapter claude --report-format json
+```
+```
+speckeeper propose-trace-links --dry-run
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file. |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
+| `--show-prompt` |  | No | `false` | Display the constructed LLM prompt on stderr. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"json"` | Output format for the report. |
+
+#### Exit Codes
+
+**Exit 0:** Proposal completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 2:** Configuration or input error.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  riskLevel: medium
+  requiresConfirmation: false
+  idempotent: true
+  sideEffects: 
+    - network
+    - file_write
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write when --output is specified. Exit 10 = valid output with blocking findings (stdout contains result). Exit 11 = missing runtime dependency (non-retryable).
+  safeDryRunOption: --dry-run
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### explain-impact
+
+LLM-based explanation of impact analysis output.
+
+Reads JSON output from speckeeper impact on stdin and generates a human-readable explanation suitable for PM/executive audiences. Includes affected artifact categorization, test considerations, and release risk assessment.
+
+**Usage:**
+
+```
+speckeeper impact FR-001 --format json | speckeeper explain-impact
+```
+```
+speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter claude
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file. |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
+| `--show-prompt` |  | No | `false` | Display the constructed LLM prompt on stderr. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"json"` | Output format for the report. |
+
+#### Exit Codes
+
+**Exit 0:** Explanation completed successfully.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 2:** Configuration or input error.
+
+- **stderr:** format=`text`
+
+**Exit 3:** No input on stdin.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  riskLevel: medium
+  requiresConfirmation: false
+  idempotent: true
+  sideEffects: 
+    - network
+    - file_write
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write when --output is specified. Exit 10 = valid output with blocking findings (stdout contains result). Exit 11 = missing runtime dependency (non-retryable).
+  safeDryRunOption: --dry-run
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### propose-acceptance-criteria
+
+LLM-based acceptance criteria proposal.
+
+Analyzes design specs and proposes testable acceptance criteria for each target spec. Optionally takes spec IDs as arguments to scope the proposal. Criteria are proposed in Given/When/Then or verification format.
+
+**Usage:**
+
+```
+speckeeper propose-acceptance-criteria
+```
+```
+speckeeper propose-acceptance-criteria FR-001 FR-002
+```
+```
+speckeeper propose-acceptance-criteria --adapter gemini --dry-run
+```
+
+#### Arguments
+
+| Name | Required | Description |
+|---|---|---|
+| `specIds` *(variadic)* | No | Spec IDs to propose criteria for. Defaults to all specs if omitted. |
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file. |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
+| `--show-prompt` |  | No | `false` | Display the constructed LLM prompt on stderr. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"json"` | Output format for the report. |
+
+#### Exit Codes
+
+**Exit 0:** Proposal completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 2:** Configuration or input error.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  riskLevel: medium
+  requiresConfirmation: false
+  idempotent: true
+  sideEffects: 
+    - network
+    - file_write
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write when --output is specified. Exit 10 = valid output with blocking findings (stdout contains result). Exit 11 = missing runtime dependency (non-retryable).
   safeDryRunOption: --dry-run
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
 ```
 
 ---

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