speckeeper 0.9.4 → 0.10.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speckeeper",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "TypeScript-first specification validation framework with external SSOT integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,7 @@
     "prepublishOnly": "npm run build",
     "docs": "embedoc build",
     "docs:watch": "embedoc watch",
+    "dsl:generate": "npx agent-runtime generate --config dsl/agent-runtime.config.yaml",
     "contract:validate": "npx cli-contracts validate",
     "contract:generate": "npx cli-contracts generate",
     "ci": "npm run ci:validate && npm run ci:generate && npm run ci:verify",
@@ -70,6 +71,14 @@
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
+  "peerDependencies": {
+    "agent-contracts-runtime": ">=0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "agent-contracts-runtime": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.11.0",
@@ -77,7 +86,9 @@
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "@vitest/coverage-v8": "^1.6.1",
-    "cli-contracts": "^0.2.0",
+    "agent-contracts": "^0.21.0",
+    "agent-contracts-runtime": "^0.13.0",
+    "cli-contracts": "^0.6.1",
     "eslint": "^9.39.2",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",