speckeeper 0.9.3 → 0.10.0

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: speckeeper CLI
-  version: 0.9.3
+  version: 0.10.0
   description: >-
     TypeScript-first specification validation framework — validate design
     consistency, external SSOT integrity, and traceability with type-safe
@@ -45,7 +45,7 @@ commandSets:
 
         options:
           - name: force
-            aliases: [f]
+            aliases: [F]
             description: Overwrite existing files.
             schema:
               type: boolean
@@ -63,11 +63,14 @@ commandSets:
               format: text
 
         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.
 
       # ── build ─────────────────────────────────────────
       build:
@@ -142,6 +145,10 @@ commandSets:
           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/.
 
       # ── lint ──────────────────────────────────────────
       lint:
@@ -202,18 +209,23 @@ commandSets:
           '0':
             description: No lint issues found (or all issues auto-fixed).
             stdout:
-              format: text
+              format: '{options.format}'
 
           '1':
             description: Lint issues found (errors or warnings with --strict).
-            stderr:
-              format: text
+            stdout:
+              format: '{options.format}'
 
         x-agent:
           riskLevel: low
           requiresConfirmation: false
           idempotent: true
-          sideEffects: []
+          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.
 
       # ── drift ─────────────────────────────────────────
       drift:
@@ -266,18 +278,22 @@ commandSets:
           '0':
             description: No drift detected (or drift auto-updated with --update).
             stdout:
-              format: text
+              format: '{options.format}'
 
           '1':
             description: Drift detected (with --fail-on-drift), or update failed.
-            stderr:
-              format: text
+            stdout:
+              format: '{options.format}'
 
         x-agent:
-          riskLevel: low
-          requiresConfirmation: false
+          riskLevel: medium
+          requiresConfirmation: true
           idempotent: true
-          sideEffects: []
+          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.
 
       # ── check ─────────────────────────────────────────
@@ -338,16 +354,25 @@ commandSets:
               type: boolean
               default: false
 
+          - name: format
+            aliases: [f]
+            description: "Output format: text, json, github."
+            valueName: format
+            schema:
+              type: string
+              default: text
+              enum: [text, json, github]
+
         exits:
           '0':
             description: All checks passed (all specs found in sources, deep validation passed).
             stdout:
-              format: text
+              format: '{options.format}'
 
           '1':
             description: Check failures found (missing specs, structural mismatches, or coverage gaps).
-            stderr:
-              format: text
+            stdout:
+              format: '{options.format}'
 
         x-agent:
           riskLevel: low
@@ -411,9 +436,15 @@ commandSets:
               exists: true
               encoding: utf-8
 
+          - name: dry-run
+            description: Preview generated file content and ID without writing to disk.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Element file created with auto-generated ID.
+            description: Element file created (or previewed with --dry-run) with auto-generated ID.
             stdout:
               format: text
 
@@ -428,6 +459,10 @@ commandSets:
           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
 
       # ── impact ────────────────────────────────────────
       impact:
@@ -465,10 +500,11 @@ commandSets:
           - name: depth
             aliases: [d]
             description: Analysis depth (reference tracking level).
-            valueName: depth
+            valueName: n
             schema:
-              type: string
-              default: "3"
+              type: integer
+              minimum: 1
+              default: 3
 
           - name: direction
             description: "Analysis direction: upstream, downstream, both."
@@ -491,7 +527,7 @@ commandSets:
           '0':
             description: Impact analysis completed and displayed.
             stdout:
-              format: text
+              format: '{options.format}'
 
           '1':
             description: Analysis failed (ID not found or config error).
@@ -539,7 +575,7 @@ commandSets:
               default: design/
 
           - name: force
-            aliases: [f]
+            aliases: [F]
             description: Overwrite existing files.
             schema:
               type: boolean
@@ -566,9 +602,687 @@ commandSets:
               format: text
 
         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 ──────────────────────────────
+      audit-requirements:
+        summary: Run LLM-based requirement quality audit.
+        description: >-
+          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:
+          - name: config
+            aliases: [c]
+            description: Path to config file.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: true
+              encoding: utf-8
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            valueName: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            valueName: name
+            schema:
+              type: string
+
+          - name: dry-run
+            aliases: [n]
+            description: Output the constructed prompt without calling LLM.
+            schema:
+              type: boolean
+              default: false
+
+          - name: show-prompt
+            description: Display the constructed LLM prompt on stderr.
+            schema:
+              type: boolean
+              default: false
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the audit report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
+        exits:
+          '0':
+            description: Audit completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/RequirementAuditResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '2':
+            description: Configuration or input error.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/RequirementAuditResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        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 ─────────────────────────────
+      propose-trace-links:
+        summary: LLM-based traceability link proposal.
+        description: >-
+          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:
+          - name: config
+            aliases: [c]
+            description: Path to config file.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: true
+              encoding: utf-8
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            valueName: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            valueName: name
+            schema:
+              type: string
+
+          - name: dry-run
+            aliases: [n]
+            description: Output the constructed prompt without calling LLM.
+            schema:
+              type: boolean
+              default: false
+
+          - name: show-prompt
+            description: Display the constructed LLM prompt on stderr.
+            schema:
+              type: boolean
+              default: false
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
+        exits:
+          '0':
+            description: Proposal completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/TraceLinkResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '2':
+            description: Configuration or input error.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/TraceLinkResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        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 ──────────────────────────────────
+      explain-impact:
+        summary: LLM-based explanation of impact analysis output.
+        description: >-
+          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
+
+        stdin:
+          required: true
+          format: json
+          description: >-
+            JSON output from speckeeper impact --format json.
+            Must contain target, targetType, and impactedNodes fields.
+          schema:
+            $ref: '#/components/schemas/ImpactAnalysisOutput'
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: true
+              encoding: utf-8
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            valueName: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            valueName: name
+            schema:
+              type: string
+
+          - name: dry-run
+            aliases: [n]
+            description: Output the constructed prompt without calling LLM.
+            schema:
+              type: boolean
+              default: false
+
+          - name: show-prompt
+            description: Display the constructed LLM prompt on stderr.
+            schema:
+              type: boolean
+              default: false
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
+        exits:
+          '0':
+            description: Explanation completed successfully.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/ImpactExplainResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '2':
+            description: Configuration or input error.
+            stderr:
+              format: text
+
+          '3':
+            description: No input on stdin.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/ImpactExplainResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        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 ─────────────────────
+      propose-acceptance-criteria:
+        summary: LLM-based acceptance criteria proposal.
+        description: >-
+          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: specIds
+            index: 0
+            required: false
+            variadic: true
+            description: >-
+              Spec IDs to propose criteria for.
+              Defaults to all specs if omitted.
+            schema:
+              type: string
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to config file.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: true
+              encoding: utf-8
+
+          - name: adapter
+            aliases: [a]
+            description: SDK adapter to use for LLM execution.
+            valueName: name
+            schema:
+              type: string
+              enum: [cursor, claude, openai, gemini, mock]
+
+          - name: model
+            description: LLM model override.
+            valueName: name
+            schema:
+              type: string
+
+          - name: dry-run
+            aliases: [n]
+            description: Output the constructed prompt without calling LLM.
+            schema:
+              type: boolean
+              default: false
+
+          - name: show-prompt
+            description: Display the constructed LLM prompt on stderr.
+            schema:
+              type: boolean
+              default: false
+
+          - name: fail-on
+            description: Minimum severity that causes a non-zero exit.
+            valueName: level
+            schema:
+              type: string
+              enum: [warning, error, critical]
+              default: error
+
+          - name: output
+            aliases: [o]
+            description: Write result to a file instead of stdout.
+            valueName: file
+            schema:
+              type: string
+            file:
+              mode: write
+              encoding: utf-8
+
+          - name: report-format
+            description: Output format for the report.
+            valueName: fmt
+            schema:
+              type: string
+              enum: [json, text, yaml]
+              default: json
+
+        exits:
+          '0':
+            description: Proposal completed, no blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/AcceptanceCriteriaResult'
+
+          '1':
+            description: Unexpected error.
+            stderr:
+              format: text
+
+          '2':
+            description: Configuration or input error.
+            stderr:
+              format: text
+
+          '10':
+            description: Completed with blocking findings.
+            stdout:
+              format: '{options.report-format}'
+              schema:
+                $ref: '#/components/schemas/AcceptanceCriteriaResult'
+
+          '11':
+            description: Runtime dependency missing (agent-contracts-runtime).
+            stderr:
+              format: text
+
+          '12':
+            description: LLM provider or adapter error.
+            stderr:
+              format: text
+
+        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]
+
+components:
+  schemas:
+    # ── AI Agent Interoperability Schemas ──────────────────
+    AgentEvidence:
+      $ref: 'components.yaml#/schemas/agent-evidence'
+    AgentFinding:
+      $ref: 'components.yaml#/schemas/agent-finding'
+    AgentRecommendedAction:
+      $ref: 'components.yaml#/schemas/agent-recommended-action'
+    RequirementAuditResult:
+      $ref: 'components.yaml#/schemas/agent-audit-result'
+
+    TraceLinkResult:
+      type: object
+      description: Result of trace link proposal with candidate links.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [candidateLinks]
+          properties:
+            candidateLinks:
+              type: array
+              items:
+                type: object
+                required: [from, relation, to, confidence, reason]
+                properties:
+                  from:
+                    type: string
+                    description: Source spec ID.
+                  relation:
+                    type: string
+                    description: Relation type (implements, verifiedBy, satisfies, etc.).
+                  to:
+                    type: string
+                    description: Target ID.
+                  confidence:
+                    type: number
+                    minimum: 0
+                    maximum: 1
+                  reason:
+                    type: string
+
+    ImpactExplainResult:
+      type: object
+      description: Human-readable explanation of impact analysis output.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [explanation]
+          properties:
+            explanation:
+              type: string
+              description: Multi-paragraph human-readable explanation in Markdown format.
+            affectedArtifacts:
+              type: array
+              items:
+                type: object
+                required: [type, id, summary]
+                properties:
+                  type:
+                    type: string
+                    enum: [spec, api, ddl, test, annotation]
+                  id:
+                    type: string
+                  summary:
+                    type: string
+            testConsiderations:
+              type: array
+              items:
+                type: string
+            releaseRisk:
+              type: string
+              enum: [low, medium, high]
+            sourceCommand:
+              type: string
+
+    AcceptanceCriteriaResult:
+      type: object
+      description: Proposed acceptance criteria for design specs.
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [criteriaProposals]
+          properties:
+            criteriaProposals:
+              type: array
+              items:
+                type: object
+                required: [specId, criteria, rationale]
+                properties:
+                  specId:
+                    type: string
+                  criteria:
+                    type: array
+                    items:
+                      type: string
+                  rationale:
+                    type: string
+
+    ImpactAnalysisOutput:
+      type: object
+      description: >-
+        JSON output from speckeeper impact --format json.
+        Used as stdin input for explain-impact command.
+      required: [target, targetType, impactedNodes]
+      properties:
+        target:
+          type: string
+          description: The spec ID that was analyzed.
+        targetType:
+          type: string
+          description: Type of the target spec (requirement, usecase, entity, etc.).
+        direction:
+          type: string
+          enum: [upstream, downstream, both]
+        depth:
+          type: integer
+        impactedNodes:
+          type: array
+          items:
+            type: object
+            required: [id, type, depth, impactType]
+            properties:
+              id:
+                type: string
+              type:
+                type: string
+              depth:
+                type: integer
+              impactType:
+                type: string
+                enum: [direct, indirect]
+              relations:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                    from:
+                      type: string
+                    to:
+                      type: string