speckeeper 0.13.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/cli-contract.yaml +6 -58
  2. package/dist/cli.js +73 -134
  3. package/dist/cli.js.map +1 -1
  4. package/docs/cli-reference.md +6 -2428
  5. package/package.json +1 -1
package/docs/cli-reference.md CHANGED
@@ -463,7 +463,7 @@ Performs semantic analysis of design specs using LLM to identify quality issues
463
463
  speckeeper audit-requirements
464
464
  ```
465
465
  ```
466
- speckeeper audit-requirements --adapter gemini --dry-run
466
+ speckeeper audit-requirements --adapter gemini --show-prompt
467
467
  ```
468
468
  ```
469
469
  speckeeper audit-requirements --report-format json --output audit.json
@@ -476,8 +476,6 @@ speckeeper audit-requirements --report-format json --output audit.json
476
476
  | `--config` | -c | No | | Path to config file. |
477
477
  | `--adapter` | -a | No | | SDK adapter to use for LLM execution. |
478
478
  | `--model` | | No | | LLM model override. |
479
- | `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
480
- | `--show-prompt` | | No | `false` | Display the constructed LLM prompt on stderr. |
481
479
  | `--fail-on` | | No | `"error"` | Minimum severity that causes a non-zero exit. |
482
480
  | `--output` | -o | No | | Write result to a file instead of stdout. |
483
481
  | `--report-format` | | No | `"json"` | Output format for the audit report. |
@@ -488,222 +486,6 @@ speckeeper audit-requirements --report-format json --output audit.json
488
486
 
489
487
  - **stdout:** format=`{options.report-format}`
490
488
 
491
- | Property | Type | Required | Description |
492
- |---|---|---|---|
493
- | `summary` | `string` | Yes | |
494
- | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
495
- | `findings` | `object[]` | Yes | |
496
- | `findings[].id` | `string` | No | Unique finding identifier. |
497
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
498
- | `findings[].category` | `string` | Yes | Finding category (e.g. verifiability, ambiguity, granularity). |
499
- | `findings[].target` | `string` | No | Target of the finding (spec ID, model type). |
500
- | `findings[].location` | `string` | No | Location within the target. |
501
- | `findings[].message` | `string` | Yes | |
502
- | `findings[].recommendation` | `string` | No | |
503
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
504
- | `findings[].evidence` | `object[]` | No | |
505
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
506
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
507
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
508
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
509
- | `findings[].details` | `Record<string, any>` | No | |
510
- | `recommendedActions` | `object[]` | No | |
511
- | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
512
- | `recommendedActions[].title` | `string` | Yes | |
513
- | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
514
- | `recommendedActions[].target` | `string` | No | Target file or resource. |
515
- | `recommendedActions[].rationale` | `string` | No | |
516
- | `metadata` | `object` | No | |
517
- | `metadata.tool` | `string` | No | |
518
- | `metadata.command` | `string` | No | |
519
- | `metadata.version` | `string` | No | |
520
- | `metadata.generatedAt` | `string` | No | |
521
- | `metadata.adapter` | `string` | No | |
522
- | `metadata.model` | `string` | No | |
523
-
524
- <details>
525
- <summary>JSON Schema</summary>
526
-
527
- ```json
528
- {
529
- "type": "object",
530
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
531
- "required": [
532
- "summary",
533
- "riskLevel",
534
- "findings"
535
- ],
536
- "properties": {
537
- "summary": {
538
- "type": "string"
539
- },
540
- "riskLevel": {
541
- "type": "string",
542
- "enum": [
543
- "low",
544
- "medium",
545
- "high",
546
- "critical"
547
- ]
548
- },
549
- "findings": {
550
- "type": "array",
551
- "items": {
552
- "type": "object",
553
- "description": "A single finding from an agent audit or analysis.",
554
- "required": [
555
- "severity",
556
- "category",
557
- "message"
558
- ],
559
- "properties": {
560
- "id": {
561
- "type": "string",
562
- "description": "Unique finding identifier."
563
- },
564
- "severity": {
565
- "type": "string",
566
- "enum": [
567
- "info",
568
- "warning",
569
- "error",
570
- "critical"
571
- ]
572
- },
573
- "category": {
574
- "type": "string",
575
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
576
- },
577
- "target": {
578
- "type": "string",
579
- "description": "Target of the finding (spec ID, model type)."
580
- },
581
- "location": {
582
- "type": "string",
583
- "description": "Location within the target."
584
- },
585
- "message": {
586
- "type": "string"
587
- },
588
- "recommendation": {
589
- "type": "string"
590
- },
591
- "confidence": {
592
- "type": "number",
593
- "minimum": 0,
594
- "maximum": 1,
595
- "description": "Confidence score (0-1) for LLM-generated findings."
596
- },
597
- "evidence": {
598
- "type": "array",
599
- "items": {
600
- "type": "object",
601
- "description": "Evidence supporting an agent finding.",
602
- "required": [
603
- "kind"
604
- ],
605
- "properties": {
606
- "kind": {
607
- "type": "string",
608
- "enum": [
609
- "file",
610
- "command",
611
- "schema",
612
- "diff",
613
- "stdout",
614
- "stderr",
615
- "text"
616
- ]
617
- },
618
- "target": {
619
- "type": "string",
620
- "description": "Target identifier (file path, command ID, schema name)."
621
- },
622
- "location": {
623
- "type": "string",
624
- "description": "Location within the target (line number, JSON pointer)."
625
- },
626
- "excerpt": {
627
- "type": "string",
628
- "description": "Relevant excerpt from the target."
629
- }
630
- }
631
- }
632
- },
633
- "details": {
634
- "type": "object",
635
- "additionalProperties": true
636
- }
637
- }
638
- }
639
- },
640
- "recommendedActions": {
641
- "type": "array",
642
- "items": {
643
- "type": "object",
644
- "description": "A recommended action from an agent audit.",
645
- "required": [
646
- "kind",
647
- "title"
648
- ],
649
- "properties": {
650
- "kind": {
651
- "type": "string",
652
- "enum": [
653
- "run_command",
654
- "edit_file",
655
- "review",
656
- "confirm",
657
- "block",
658
- "ignore"
659
- ]
660
- },
661
- "title": {
662
- "type": "string"
663
- },
664
- "command": {
665
- "type": "string",
666
- "description": "CLI command to run (for run_command kind)."
667
- },
668
- "target": {
669
- "type": "string",
670
- "description": "Target file or resource."
671
- },
672
- "rationale": {
673
- "type": "string"
674
- }
675
- }
676
- }
677
- },
678
- "metadata": {
679
- "type": "object",
680
- "properties": {
681
- "tool": {
682
- "type": "string"
683
- },
684
- "command": {
685
- "type": "string"
686
- },
687
- "version": {
688
- "type": "string"
689
- },
690
- "generatedAt": {
691
- "type": "string"
692
- },
693
- "adapter": {
694
- "type": "string"
695
- },
696
- "model": {
697
- "type": "string"
698
- }
699
- }
700
- }
701
- }
702
- }
703
- ```
704
-
705
- </details>
706
-
707
489
  **Exit 1:** Unexpected error.
708
490
 
709
491
  - **stderr:** format=`text`
@@ -716,222 +498,6 @@ speckeeper audit-requirements --report-format json --output audit.json
716
498
 
717
499
  - **stdout:** format=`{options.report-format}`
718
500
 
719
- | Property | Type | Required | Description |
720
- |---|---|---|---|
721
- | `summary` | `string` | Yes | |
722
- | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
723
- | `findings` | `object[]` | Yes | |
724
- | `findings[].id` | `string` | No | Unique finding identifier. |
725
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
726
- | `findings[].category` | `string` | Yes | Finding category (e.g. verifiability, ambiguity, granularity). |
727
- | `findings[].target` | `string` | No | Target of the finding (spec ID, model type). |
728
- | `findings[].location` | `string` | No | Location within the target. |
729
- | `findings[].message` | `string` | Yes | |
730
- | `findings[].recommendation` | `string` | No | |
731
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
732
- | `findings[].evidence` | `object[]` | No | |
733
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
734
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
735
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
736
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
737
- | `findings[].details` | `Record<string, any>` | No | |
738
- | `recommendedActions` | `object[]` | No | |
739
- | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
740
- | `recommendedActions[].title` | `string` | Yes | |
741
- | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
742
- | `recommendedActions[].target` | `string` | No | Target file or resource. |
743
- | `recommendedActions[].rationale` | `string` | No | |
744
- | `metadata` | `object` | No | |
745
- | `metadata.tool` | `string` | No | |
746
- | `metadata.command` | `string` | No | |
747
- | `metadata.version` | `string` | No | |
748
- | `metadata.generatedAt` | `string` | No | |
749
- | `metadata.adapter` | `string` | No | |
750
- | `metadata.model` | `string` | No | |
751
-
752
- <details>
753
- <summary>JSON Schema</summary>
754
-
755
- ```json
756
- {
757
- "type": "object",
758
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
759
- "required": [
760
- "summary",
761
- "riskLevel",
762
- "findings"
763
- ],
764
- "properties": {
765
- "summary": {
766
- "type": "string"
767
- },
768
- "riskLevel": {
769
- "type": "string",
770
- "enum": [
771
- "low",
772
- "medium",
773
- "high",
774
- "critical"
775
- ]
776
- },
777
- "findings": {
778
- "type": "array",
779
- "items": {
780
- "type": "object",
781
- "description": "A single finding from an agent audit or analysis.",
782
- "required": [
783
- "severity",
784
- "category",
785
- "message"
786
- ],
787
- "properties": {
788
- "id": {
789
- "type": "string",
790
- "description": "Unique finding identifier."
791
- },
792
- "severity": {
793
- "type": "string",
794
- "enum": [
795
- "info",
796
- "warning",
797
- "error",
798
- "critical"
799
- ]
800
- },
801
- "category": {
802
- "type": "string",
803
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
804
- },
805
- "target": {
806
- "type": "string",
807
- "description": "Target of the finding (spec ID, model type)."
808
- },
809
- "location": {
810
- "type": "string",
811
- "description": "Location within the target."
812
- },
813
- "message": {
814
- "type": "string"
815
- },
816
- "recommendation": {
817
- "type": "string"
818
- },
819
- "confidence": {
820
- "type": "number",
821
- "minimum": 0,
822
- "maximum": 1,
823
- "description": "Confidence score (0-1) for LLM-generated findings."
824
- },
825
- "evidence": {
826
- "type": "array",
827
- "items": {
828
- "type": "object",
829
- "description": "Evidence supporting an agent finding.",
830
- "required": [
831
- "kind"
832
- ],
833
- "properties": {
834
- "kind": {
835
- "type": "string",
836
- "enum": [
837
- "file",
838
- "command",
839
- "schema",
840
- "diff",
841
- "stdout",
842
- "stderr",
843
- "text"
844
- ]
845
- },
846
- "target": {
847
- "type": "string",
848
- "description": "Target identifier (file path, command ID, schema name)."
849
- },
850
- "location": {
851
- "type": "string",
852
- "description": "Location within the target (line number, JSON pointer)."
853
- },
854
- "excerpt": {
855
- "type": "string",
856
- "description": "Relevant excerpt from the target."
857
- }
858
- }
859
- }
860
- },
861
- "details": {
862
- "type": "object",
863
- "additionalProperties": true
864
- }
865
- }
866
- }
867
- },
868
- "recommendedActions": {
869
- "type": "array",
870
- "items": {
871
- "type": "object",
872
- "description": "A recommended action from an agent audit.",
873
- "required": [
874
- "kind",
875
- "title"
876
- ],
877
- "properties": {
878
- "kind": {
879
- "type": "string",
880
- "enum": [
881
- "run_command",
882
- "edit_file",
883
- "review",
884
- "confirm",
885
- "block",
886
- "ignore"
887
- ]
888
- },
889
- "title": {
890
- "type": "string"
891
- },
892
- "command": {
893
- "type": "string",
894
- "description": "CLI command to run (for run_command kind)."
895
- },
896
- "target": {
897
- "type": "string",
898
- "description": "Target file or resource."
899
- },
900
- "rationale": {
901
- "type": "string"
902
- }
903
- }
904
- }
905
- },
906
- "metadata": {
907
- "type": "object",
908
- "properties": {
909
- "tool": {
910
- "type": "string"
911
- },
912
- "command": {
913
- "type": "string"
914
- },
915
- "version": {
916
- "type": "string"
917
- },
918
- "generatedAt": {
919
- "type": "string"
920
- },
921
- "adapter": {
922
- "type": "string"
923
- },
924
- "model": {
925
- "type": "string"
926
- }
927
- }
928
- }
929
- }
930
- }
931
- ```
932
-
933
- </details>
934
-
935
501
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime).
936
502
 
937
503
  - **stderr:** format=`text`
@@ -945,7 +511,7 @@ speckeeper audit-requirements --report-format json --output audit.json
945
511
  ```yaml
946
512
  x-agent:
947
513
  recommended_before_use:
948
- - Run with --dry-run first to preview the prompt
514
+ - Run with --show-prompt first to preview the prompt
949
515
  retryableExitCodes:
950
516
  - 12
951
517
  ```
@@ -974,8 +540,6 @@ speckeeper propose-trace-links --adapter claude --report-format json
974
540
  | `--config` | -c | No | | Path to config file. |
975
541
  | `--adapter` | -a | No | | SDK adapter to use for LLM execution. |
976
542
  | `--model` | | No | | LLM model override. |
977
- | `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
978
- | `--show-prompt` | | No | `false` | Display the constructed LLM prompt on stderr. |
979
543
  | `--fail-on` | | No | `"error"` | Minimum severity that causes a non-zero exit. |
980
544
  | `--output` | -o | No | | Write result to a file instead of stdout. |
981
545
  | `--report-format` | | No | `"json"` | Output format for the report. |
@@ -986,236 +550,6 @@ speckeeper propose-trace-links --adapter claude --report-format json
986
550
 
987
551
  - **stdout:** format=`{options.report-format}`
988
552
 
989
-
990
- <details>
991
- <summary>JSON Schema</summary>
992
-
993
- ```json
994
- {
995
- "type": "object",
996
- "description": "Result of trace link proposal with candidate links.",
997
- "allOf": [
998
- {
999
- "type": "object",
1000
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
1001
- "required": [
1002
- "summary",
1003
- "riskLevel",
1004
- "findings"
1005
- ],
1006
- "properties": {
1007
- "summary": {
1008
- "type": "string"
1009
- },
1010
- "riskLevel": {
1011
- "type": "string",
1012
- "enum": [
1013
- "low",
1014
- "medium",
1015
- "high",
1016
- "critical"
1017
- ]
1018
- },
1019
- "findings": {
1020
- "type": "array",
1021
- "items": {
1022
- "type": "object",
1023
- "description": "A single finding from an agent audit or analysis.",
1024
- "required": [
1025
- "severity",
1026
- "category",
1027
- "message"
1028
- ],
1029
- "properties": {
1030
- "id": {
1031
- "type": "string",
1032
- "description": "Unique finding identifier."
1033
- },
1034
- "severity": {
1035
- "type": "string",
1036
- "enum": [
1037
- "info",
1038
- "warning",
1039
- "error",
1040
- "critical"
1041
- ]
1042
- },
1043
- "category": {
1044
- "type": "string",
1045
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
1046
- },
1047
- "target": {
1048
- "type": "string",
1049
- "description": "Target of the finding (spec ID, model type)."
1050
- },
1051
- "location": {
1052
- "type": "string",
1053
- "description": "Location within the target."
1054
- },
1055
- "message": {
1056
- "type": "string"
1057
- },
1058
- "recommendation": {
1059
- "type": "string"
1060
- },
1061
- "confidence": {
1062
- "type": "number",
1063
- "minimum": 0,
1064
- "maximum": 1,
1065
- "description": "Confidence score (0-1) for LLM-generated findings."
1066
- },
1067
- "evidence": {
1068
- "type": "array",
1069
- "items": {
1070
- "type": "object",
1071
- "description": "Evidence supporting an agent finding.",
1072
- "required": [
1073
- "kind"
1074
- ],
1075
- "properties": {
1076
- "kind": {
1077
- "type": "string",
1078
- "enum": [
1079
- "file",
1080
- "command",
1081
- "schema",
1082
- "diff",
1083
- "stdout",
1084
- "stderr",
1085
- "text"
1086
- ]
1087
- },
1088
- "target": {
1089
- "type": "string",
1090
- "description": "Target identifier (file path, command ID, schema name)."
1091
- },
1092
- "location": {
1093
- "type": "string",
1094
- "description": "Location within the target (line number, JSON pointer)."
1095
- },
1096
- "excerpt": {
1097
- "type": "string",
1098
- "description": "Relevant excerpt from the target."
1099
- }
1100
- }
1101
- }
1102
- },
1103
- "details": {
1104
- "type": "object",
1105
- "additionalProperties": true
1106
- }
1107
- }
1108
- }
1109
- },
1110
- "recommendedActions": {
1111
- "type": "array",
1112
- "items": {
1113
- "type": "object",
1114
- "description": "A recommended action from an agent audit.",
1115
- "required": [
1116
- "kind",
1117
- "title"
1118
- ],
1119
- "properties": {
1120
- "kind": {
1121
- "type": "string",
1122
- "enum": [
1123
- "run_command",
1124
- "edit_file",
1125
- "review",
1126
- "confirm",
1127
- "block",
1128
- "ignore"
1129
- ]
1130
- },
1131
- "title": {
1132
- "type": "string"
1133
- },
1134
- "command": {
1135
- "type": "string",
1136
- "description": "CLI command to run (for run_command kind)."
1137
- },
1138
- "target": {
1139
- "type": "string",
1140
- "description": "Target file or resource."
1141
- },
1142
- "rationale": {
1143
- "type": "string"
1144
- }
1145
- }
1146
- }
1147
- },
1148
- "metadata": {
1149
- "type": "object",
1150
- "properties": {
1151
- "tool": {
1152
- "type": "string"
1153
- },
1154
- "command": {
1155
- "type": "string"
1156
- },
1157
- "version": {
1158
- "type": "string"
1159
- },
1160
- "generatedAt": {
1161
- "type": "string"
1162
- },
1163
- "adapter": {
1164
- "type": "string"
1165
- },
1166
- "model": {
1167
- "type": "string"
1168
- }
1169
- }
1170
- }
1171
- }
1172
- },
1173
- {
1174
- "type": "object",
1175
- "required": [
1176
- "candidateLinks"
1177
- ],
1178
- "properties": {
1179
- "candidateLinks": {
1180
- "type": "array",
1181
- "items": {
1182
- "type": "object",
1183
- "required": [
1184
- "from",
1185
- "relation",
1186
- "to",
1187
- "confidence",
1188
- "reason"
1189
- ],
1190
- "properties": {
1191
- "from": {
1192
- "type": "string"
1193
- },
1194
- "relation": {
1195
- "type": "string"
1196
- },
1197
- "to": {
1198
- "type": "string"
1199
- },
1200
- "confidence": {
1201
- "type": "number",
1202
- "minimum": 0,
1203
- "maximum": 1
1204
- },
1205
- "reason": {
1206
- "type": "string"
1207
- }
1208
- }
1209
- }
1210
- }
1211
- }
1212
- }
1213
- ]
1214
- }
1215
- ```
1216
-
1217
- </details>
1218
-
1219
553
  **Exit 1:** Unexpected error.
1220
554
 
1221
555
  - **stderr:** format=`text`
@@ -1228,236 +562,6 @@ speckeeper propose-trace-links --adapter claude --report-format json
1228
562
 
1229
563
  - **stdout:** format=`{options.report-format}`
1230
564
 
1231
-
1232
- <details>
1233
- <summary>JSON Schema</summary>
1234
-
1235
- ```json
1236
- {
1237
- "type": "object",
1238
- "description": "Result of trace link proposal with candidate links.",
1239
- "allOf": [
1240
- {
1241
- "type": "object",
1242
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
1243
- "required": [
1244
- "summary",
1245
- "riskLevel",
1246
- "findings"
1247
- ],
1248
- "properties": {
1249
- "summary": {
1250
- "type": "string"
1251
- },
1252
- "riskLevel": {
1253
- "type": "string",
1254
- "enum": [
1255
- "low",
1256
- "medium",
1257
- "high",
1258
- "critical"
1259
- ]
1260
- },
1261
- "findings": {
1262
- "type": "array",
1263
- "items": {
1264
- "type": "object",
1265
- "description": "A single finding from an agent audit or analysis.",
1266
- "required": [
1267
- "severity",
1268
- "category",
1269
- "message"
1270
- ],
1271
- "properties": {
1272
- "id": {
1273
- "type": "string",
1274
- "description": "Unique finding identifier."
1275
- },
1276
- "severity": {
1277
- "type": "string",
1278
- "enum": [
1279
- "info",
1280
- "warning",
1281
- "error",
1282
- "critical"
1283
- ]
1284
- },
1285
- "category": {
1286
- "type": "string",
1287
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
1288
- },
1289
- "target": {
1290
- "type": "string",
1291
- "description": "Target of the finding (spec ID, model type)."
1292
- },
1293
- "location": {
1294
- "type": "string",
1295
- "description": "Location within the target."
1296
- },
1297
- "message": {
1298
- "type": "string"
1299
- },
1300
- "recommendation": {
1301
- "type": "string"
1302
- },
1303
- "confidence": {
1304
- "type": "number",
1305
- "minimum": 0,
1306
- "maximum": 1,
1307
- "description": "Confidence score (0-1) for LLM-generated findings."
1308
- },
1309
- "evidence": {
1310
- "type": "array",
1311
- "items": {
1312
- "type": "object",
1313
- "description": "Evidence supporting an agent finding.",
1314
- "required": [
1315
- "kind"
1316
- ],
1317
- "properties": {
1318
- "kind": {
1319
- "type": "string",
1320
- "enum": [
1321
- "file",
1322
- "command",
1323
- "schema",
1324
- "diff",
1325
- "stdout",
1326
- "stderr",
1327
- "text"
1328
- ]
1329
- },
1330
- "target": {
1331
- "type": "string",
1332
- "description": "Target identifier (file path, command ID, schema name)."
1333
- },
1334
- "location": {
1335
- "type": "string",
1336
- "description": "Location within the target (line number, JSON pointer)."
1337
- },
1338
- "excerpt": {
1339
- "type": "string",
1340
- "description": "Relevant excerpt from the target."
1341
- }
1342
- }
1343
- }
1344
- },
1345
- "details": {
1346
- "type": "object",
1347
- "additionalProperties": true
1348
- }
1349
- }
1350
- }
1351
- },
1352
- "recommendedActions": {
1353
- "type": "array",
1354
- "items": {
1355
- "type": "object",
1356
- "description": "A recommended action from an agent audit.",
1357
- "required": [
1358
- "kind",
1359
- "title"
1360
- ],
1361
- "properties": {
1362
- "kind": {
1363
- "type": "string",
1364
- "enum": [
1365
- "run_command",
1366
- "edit_file",
1367
- "review",
1368
- "confirm",
1369
- "block",
1370
- "ignore"
1371
- ]
1372
- },
1373
- "title": {
1374
- "type": "string"
1375
- },
1376
- "command": {
1377
- "type": "string",
1378
- "description": "CLI command to run (for run_command kind)."
1379
- },
1380
- "target": {
1381
- "type": "string",
1382
- "description": "Target file or resource."
1383
- },
1384
- "rationale": {
1385
- "type": "string"
1386
- }
1387
- }
1388
- }
1389
- },
1390
- "metadata": {
1391
- "type": "object",
1392
- "properties": {
1393
- "tool": {
1394
- "type": "string"
1395
- },
1396
- "command": {
1397
- "type": "string"
1398
- },
1399
- "version": {
1400
- "type": "string"
1401
- },
1402
- "generatedAt": {
1403
- "type": "string"
1404
- },
1405
- "adapter": {
1406
- "type": "string"
1407
- },
1408
- "model": {
1409
- "type": "string"
1410
- }
1411
- }
1412
- }
1413
- }
1414
- },
1415
- {
1416
- "type": "object",
1417
- "required": [
1418
- "candidateLinks"
1419
- ],
1420
- "properties": {
1421
- "candidateLinks": {
1422
- "type": "array",
1423
- "items": {
1424
- "type": "object",
1425
- "required": [
1426
- "from",
1427
- "relation",
1428
- "to",
1429
- "confidence",
1430
- "reason"
1431
- ],
1432
- "properties": {
1433
- "from": {
1434
- "type": "string"
1435
- },
1436
- "relation": {
1437
- "type": "string"
1438
- },
1439
- "to": {
1440
- "type": "string"
1441
- },
1442
- "confidence": {
1443
- "type": "number",
1444
- "minimum": 0,
1445
- "maximum": 1
1446
- },
1447
- "reason": {
1448
- "type": "string"
1449
- }
1450
- }
1451
- }
1452
- }
1453
- }
1454
- }
1455
- ]
1456
- }
1457
- ```
1458
-
1459
- </details>
1460
-
1461
565
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime).
1462
566
 
1463
567
  - **stderr:** format=`text`
@@ -1471,7 +575,7 @@ speckeeper propose-trace-links --adapter claude --report-format json
1471
575
  ```yaml
1472
576
  x-agent:
1473
577
  recommended_before_use:
1474
- - Run with --dry-run first to preview the prompt
578
+ - Run with --show-prompt first to preview the prompt
1475
579
  retryableExitCodes:
1476
580
  - 12
1477
581
  ```
@@ -1499,8 +603,6 @@ speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter
1499
603
  |---|---|---|---|---|
1500
604
  | `--adapter` | -a | No | | SDK adapter to use for LLM execution. |
1501
605
  | `--model` | | No | | LLM model override. |
1502
- | `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
1503
- | `--show-prompt` | | No | `false` | Display the constructed LLM prompt on stderr. |
1504
606
  | `--fail-on` | | No | `"error"` | Minimum severity that causes a non-zero exit. |
1505
607
  | `--output` | -o | No | | Write result to a file instead of stdout. |
1506
608
  | `--report-format` | | No | `"json"` | Output format for the report. |
@@ -1511,253 +613,6 @@ speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter
1511
613
 
1512
614
  - **stdout:** format=`{options.report-format}`
1513
615
 
1514
-
1515
- <details>
1516
- <summary>JSON Schema</summary>
1517
-
1518
- ```json
1519
- {
1520
- "type": "object",
1521
- "description": "Human-readable explanation of impact analysis output.",
1522
- "allOf": [
1523
- {
1524
- "type": "object",
1525
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
1526
- "required": [
1527
- "summary",
1528
- "riskLevel",
1529
- "findings"
1530
- ],
1531
- "properties": {
1532
- "summary": {
1533
- "type": "string"
1534
- },
1535
- "riskLevel": {
1536
- "type": "string",
1537
- "enum": [
1538
- "low",
1539
- "medium",
1540
- "high",
1541
- "critical"
1542
- ]
1543
- },
1544
- "findings": {
1545
- "type": "array",
1546
- "items": {
1547
- "type": "object",
1548
- "description": "A single finding from an agent audit or analysis.",
1549
- "required": [
1550
- "severity",
1551
- "category",
1552
- "message"
1553
- ],
1554
- "properties": {
1555
- "id": {
1556
- "type": "string",
1557
- "description": "Unique finding identifier."
1558
- },
1559
- "severity": {
1560
- "type": "string",
1561
- "enum": [
1562
- "info",
1563
- "warning",
1564
- "error",
1565
- "critical"
1566
- ]
1567
- },
1568
- "category": {
1569
- "type": "string",
1570
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
1571
- },
1572
- "target": {
1573
- "type": "string",
1574
- "description": "Target of the finding (spec ID, model type)."
1575
- },
1576
- "location": {
1577
- "type": "string",
1578
- "description": "Location within the target."
1579
- },
1580
- "message": {
1581
- "type": "string"
1582
- },
1583
- "recommendation": {
1584
- "type": "string"
1585
- },
1586
- "confidence": {
1587
- "type": "number",
1588
- "minimum": 0,
1589
- "maximum": 1,
1590
- "description": "Confidence score (0-1) for LLM-generated findings."
1591
- },
1592
- "evidence": {
1593
- "type": "array",
1594
- "items": {
1595
- "type": "object",
1596
- "description": "Evidence supporting an agent finding.",
1597
- "required": [
1598
- "kind"
1599
- ],
1600
- "properties": {
1601
- "kind": {
1602
- "type": "string",
1603
- "enum": [
1604
- "file",
1605
- "command",
1606
- "schema",
1607
- "diff",
1608
- "stdout",
1609
- "stderr",
1610
- "text"
1611
- ]
1612
- },
1613
- "target": {
1614
- "type": "string",
1615
- "description": "Target identifier (file path, command ID, schema name)."
1616
- },
1617
- "location": {
1618
- "type": "string",
1619
- "description": "Location within the target (line number, JSON pointer)."
1620
- },
1621
- "excerpt": {
1622
- "type": "string",
1623
- "description": "Relevant excerpt from the target."
1624
- }
1625
- }
1626
- }
1627
- },
1628
- "details": {
1629
- "type": "object",
1630
- "additionalProperties": true
1631
- }
1632
- }
1633
- }
1634
- },
1635
- "recommendedActions": {
1636
- "type": "array",
1637
- "items": {
1638
- "type": "object",
1639
- "description": "A recommended action from an agent audit.",
1640
- "required": [
1641
- "kind",
1642
- "title"
1643
- ],
1644
- "properties": {
1645
- "kind": {
1646
- "type": "string",
1647
- "enum": [
1648
- "run_command",
1649
- "edit_file",
1650
- "review",
1651
- "confirm",
1652
- "block",
1653
- "ignore"
1654
- ]
1655
- },
1656
- "title": {
1657
- "type": "string"
1658
- },
1659
- "command": {
1660
- "type": "string",
1661
- "description": "CLI command to run (for run_command kind)."
1662
- },
1663
- "target": {
1664
- "type": "string",
1665
- "description": "Target file or resource."
1666
- },
1667
- "rationale": {
1668
- "type": "string"
1669
- }
1670
- }
1671
- }
1672
- },
1673
- "metadata": {
1674
- "type": "object",
1675
- "properties": {
1676
- "tool": {
1677
- "type": "string"
1678
- },
1679
- "command": {
1680
- "type": "string"
1681
- },
1682
- "version": {
1683
- "type": "string"
1684
- },
1685
- "generatedAt": {
1686
- "type": "string"
1687
- },
1688
- "adapter": {
1689
- "type": "string"
1690
- },
1691
- "model": {
1692
- "type": "string"
1693
- }
1694
- }
1695
- }
1696
- }
1697
- },
1698
- {
1699
- "type": "object",
1700
- "required": [
1701
- "explanation"
1702
- ],
1703
- "properties": {
1704
- "explanation": {
1705
- "type": "string"
1706
- },
1707
- "affectedArtifacts": {
1708
- "type": "array",
1709
- "items": {
1710
- "type": "object",
1711
- "required": [
1712
- "type",
1713
- "id",
1714
- "summary"
1715
- ],
1716
- "properties": {
1717
- "type": {
1718
- "type": "string",
1719
- "enum": [
1720
- "spec",
1721
- "api",
1722
- "ddl",
1723
- "test",
1724
- "annotation"
1725
- ]
1726
- },
1727
- "id": {
1728
- "type": "string"
1729
- },
1730
- "summary": {
1731
- "type": "string"
1732
- }
1733
- }
1734
- }
1735
- },
1736
- "testConsiderations": {
1737
- "type": "array",
1738
- "items": {
1739
- "type": "string"
1740
- }
1741
- },
1742
- "releaseRisk": {
1743
- "type": "string",
1744
- "enum": [
1745
- "low",
1746
- "medium",
1747
- "high"
1748
- ]
1749
- },
1750
- "sourceCommand": {
1751
- "type": "string"
1752
- }
1753
- }
1754
- }
1755
- ]
1756
- }
1757
- ```
1758
-
1759
- </details>
1760
-
1761
616
  **Exit 1:** Unexpected error.
1762
617
 
1763
618
  - **stderr:** format=`text`
@@ -1770,253 +625,6 @@ speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter
1770
625
 
1771
626
  - **stdout:** format=`{options.report-format}`
1772
627
 
1773
-
1774
- <details>
1775
- <summary>JSON Schema</summary>
1776
-
1777
- ```json
1778
- {
1779
- "type": "object",
1780
- "description": "Human-readable explanation of impact analysis output.",
1781
- "allOf": [
1782
- {
1783
- "type": "object",
1784
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
1785
- "required": [
1786
- "summary",
1787
- "riskLevel",
1788
- "findings"
1789
- ],
1790
- "properties": {
1791
- "summary": {
1792
- "type": "string"
1793
- },
1794
- "riskLevel": {
1795
- "type": "string",
1796
- "enum": [
1797
- "low",
1798
- "medium",
1799
- "high",
1800
- "critical"
1801
- ]
1802
- },
1803
- "findings": {
1804
- "type": "array",
1805
- "items": {
1806
- "type": "object",
1807
- "description": "A single finding from an agent audit or analysis.",
1808
- "required": [
1809
- "severity",
1810
- "category",
1811
- "message"
1812
- ],
1813
- "properties": {
1814
- "id": {
1815
- "type": "string",
1816
- "description": "Unique finding identifier."
1817
- },
1818
- "severity": {
1819
- "type": "string",
1820
- "enum": [
1821
- "info",
1822
- "warning",
1823
- "error",
1824
- "critical"
1825
- ]
1826
- },
1827
- "category": {
1828
- "type": "string",
1829
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
1830
- },
1831
- "target": {
1832
- "type": "string",
1833
- "description": "Target of the finding (spec ID, model type)."
1834
- },
1835
- "location": {
1836
- "type": "string",
1837
- "description": "Location within the target."
1838
- },
1839
- "message": {
1840
- "type": "string"
1841
- },
1842
- "recommendation": {
1843
- "type": "string"
1844
- },
1845
- "confidence": {
1846
- "type": "number",
1847
- "minimum": 0,
1848
- "maximum": 1,
1849
- "description": "Confidence score (0-1) for LLM-generated findings."
1850
- },
1851
- "evidence": {
1852
- "type": "array",
1853
- "items": {
1854
- "type": "object",
1855
- "description": "Evidence supporting an agent finding.",
1856
- "required": [
1857
- "kind"
1858
- ],
1859
- "properties": {
1860
- "kind": {
1861
- "type": "string",
1862
- "enum": [
1863
- "file",
1864
- "command",
1865
- "schema",
1866
- "diff",
1867
- "stdout",
1868
- "stderr",
1869
- "text"
1870
- ]
1871
- },
1872
- "target": {
1873
- "type": "string",
1874
- "description": "Target identifier (file path, command ID, schema name)."
1875
- },
1876
- "location": {
1877
- "type": "string",
1878
- "description": "Location within the target (line number, JSON pointer)."
1879
- },
1880
- "excerpt": {
1881
- "type": "string",
1882
- "description": "Relevant excerpt from the target."
1883
- }
1884
- }
1885
- }
1886
- },
1887
- "details": {
1888
- "type": "object",
1889
- "additionalProperties": true
1890
- }
1891
- }
1892
- }
1893
- },
1894
- "recommendedActions": {
1895
- "type": "array",
1896
- "items": {
1897
- "type": "object",
1898
- "description": "A recommended action from an agent audit.",
1899
- "required": [
1900
- "kind",
1901
- "title"
1902
- ],
1903
- "properties": {
1904
- "kind": {
1905
- "type": "string",
1906
- "enum": [
1907
- "run_command",
1908
- "edit_file",
1909
- "review",
1910
- "confirm",
1911
- "block",
1912
- "ignore"
1913
- ]
1914
- },
1915
- "title": {
1916
- "type": "string"
1917
- },
1918
- "command": {
1919
- "type": "string",
1920
- "description": "CLI command to run (for run_command kind)."
1921
- },
1922
- "target": {
1923
- "type": "string",
1924
- "description": "Target file or resource."
1925
- },
1926
- "rationale": {
1927
- "type": "string"
1928
- }
1929
- }
1930
- }
1931
- },
1932
- "metadata": {
1933
- "type": "object",
1934
- "properties": {
1935
- "tool": {
1936
- "type": "string"
1937
- },
1938
- "command": {
1939
- "type": "string"
1940
- },
1941
- "version": {
1942
- "type": "string"
1943
- },
1944
- "generatedAt": {
1945
- "type": "string"
1946
- },
1947
- "adapter": {
1948
- "type": "string"
1949
- },
1950
- "model": {
1951
- "type": "string"
1952
- }
1953
- }
1954
- }
1955
- }
1956
- },
1957
- {
1958
- "type": "object",
1959
- "required": [
1960
- "explanation"
1961
- ],
1962
- "properties": {
1963
- "explanation": {
1964
- "type": "string"
1965
- },
1966
- "affectedArtifacts": {
1967
- "type": "array",
1968
- "items": {
1969
- "type": "object",
1970
- "required": [
1971
- "type",
1972
- "id",
1973
- "summary"
1974
- ],
1975
- "properties": {
1976
- "type": {
1977
- "type": "string",
1978
- "enum": [
1979
- "spec",
1980
- "api",
1981
- "ddl",
1982
- "test",
1983
- "annotation"
1984
- ]
1985
- },
1986
- "id": {
1987
- "type": "string"
1988
- },
1989
- "summary": {
1990
- "type": "string"
1991
- }
1992
- }
1993
- }
1994
- },
1995
- "testConsiderations": {
1996
- "type": "array",
1997
- "items": {
1998
- "type": "string"
1999
- }
2000
- },
2001
- "releaseRisk": {
2002
- "type": "string",
2003
- "enum": [
2004
- "low",
2005
- "medium",
2006
- "high"
2007
- ]
2008
- },
2009
- "sourceCommand": {
2010
- "type": "string"
2011
- }
2012
- }
2013
- }
2014
- ]
2015
- }
2016
- ```
2017
-
2018
- </details>
2019
-
2020
628
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime).
2021
629
 
2022
630
  - **stderr:** format=`text`
@@ -2030,7 +638,7 @@ speckeeper impact ENT-ORDER --format json | speckeeper explain-impact --adapter
2030
638
  ```yaml
2031
639
  x-agent:
2032
640
  recommended_before_use:
2033
- - Run with --dry-run first to preview the prompt
641
+ - Run with --show-prompt first to preview the prompt
2034
642
  retryableExitCodes:
2035
643
  - 12
2036
644
  ```
@@ -2052,7 +660,7 @@ speckeeper propose-acceptance-criteria
2052
660
  speckeeper propose-acceptance-criteria FR-001 FR-002
2053
661
  ```
2054
662
  ```
2055
- speckeeper propose-acceptance-criteria --adapter gemini --dry-run
663
+ speckeeper propose-acceptance-criteria --adapter gemini --show-prompt
2056
664
  ```
2057
665
 
2058
666
  #### Arguments
@@ -2068,8 +676,6 @@ speckeeper propose-acceptance-criteria --adapter gemini --dry-run
2068
676
  | `--config` | -c | No | | Path to config file. |
2069
677
  | `--adapter` | -a | No | | SDK adapter to use for LLM execution. |
2070
678
  | `--model` | | No | | LLM model override. |
2071
- | `--dry-run` | -n | No | `false` | Output the constructed prompt without calling LLM. |
2072
- | `--show-prompt` | | No | `false` | Display the constructed LLM prompt on stderr. |
2073
679
  | `--fail-on` | | No | `"error"` | Minimum severity that causes a non-zero exit. |
2074
680
  | `--output` | -o | No | | Write result to a file instead of stdout. |
2075
681
  | `--report-format` | | No | `"json"` | Output format for the report. |
@@ -2080,229 +686,6 @@ speckeeper propose-acceptance-criteria --adapter gemini --dry-run
2080
686
 
2081
687
  - **stdout:** format=`{options.report-format}`
2082
688
 
2083
-
2084
- <details>
2085
- <summary>JSON Schema</summary>
2086
-
2087
- ```json
2088
- {
2089
- "type": "object",
2090
- "description": "Proposed acceptance criteria for design specs.",
2091
- "allOf": [
2092
- {
2093
- "type": "object",
2094
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
2095
- "required": [
2096
- "summary",
2097
- "riskLevel",
2098
- "findings"
2099
- ],
2100
- "properties": {
2101
- "summary": {
2102
- "type": "string"
2103
- },
2104
- "riskLevel": {
2105
- "type": "string",
2106
- "enum": [
2107
- "low",
2108
- "medium",
2109
- "high",
2110
- "critical"
2111
- ]
2112
- },
2113
- "findings": {
2114
- "type": "array",
2115
- "items": {
2116
- "type": "object",
2117
- "description": "A single finding from an agent audit or analysis.",
2118
- "required": [
2119
- "severity",
2120
- "category",
2121
- "message"
2122
- ],
2123
- "properties": {
2124
- "id": {
2125
- "type": "string",
2126
- "description": "Unique finding identifier."
2127
- },
2128
- "severity": {
2129
- "type": "string",
2130
- "enum": [
2131
- "info",
2132
- "warning",
2133
- "error",
2134
- "critical"
2135
- ]
2136
- },
2137
- "category": {
2138
- "type": "string",
2139
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
2140
- },
2141
- "target": {
2142
- "type": "string",
2143
- "description": "Target of the finding (spec ID, model type)."
2144
- },
2145
- "location": {
2146
- "type": "string",
2147
- "description": "Location within the target."
2148
- },
2149
- "message": {
2150
- "type": "string"
2151
- },
2152
- "recommendation": {
2153
- "type": "string"
2154
- },
2155
- "confidence": {
2156
- "type": "number",
2157
- "minimum": 0,
2158
- "maximum": 1,
2159
- "description": "Confidence score (0-1) for LLM-generated findings."
2160
- },
2161
- "evidence": {
2162
- "type": "array",
2163
- "items": {
2164
- "type": "object",
2165
- "description": "Evidence supporting an agent finding.",
2166
- "required": [
2167
- "kind"
2168
- ],
2169
- "properties": {
2170
- "kind": {
2171
- "type": "string",
2172
- "enum": [
2173
- "file",
2174
- "command",
2175
- "schema",
2176
- "diff",
2177
- "stdout",
2178
- "stderr",
2179
- "text"
2180
- ]
2181
- },
2182
- "target": {
2183
- "type": "string",
2184
- "description": "Target identifier (file path, command ID, schema name)."
2185
- },
2186
- "location": {
2187
- "type": "string",
2188
- "description": "Location within the target (line number, JSON pointer)."
2189
- },
2190
- "excerpt": {
2191
- "type": "string",
2192
- "description": "Relevant excerpt from the target."
2193
- }
2194
- }
2195
- }
2196
- },
2197
- "details": {
2198
- "type": "object",
2199
- "additionalProperties": true
2200
- }
2201
- }
2202
- }
2203
- },
2204
- "recommendedActions": {
2205
- "type": "array",
2206
- "items": {
2207
- "type": "object",
2208
- "description": "A recommended action from an agent audit.",
2209
- "required": [
2210
- "kind",
2211
- "title"
2212
- ],
2213
- "properties": {
2214
- "kind": {
2215
- "type": "string",
2216
- "enum": [
2217
- "run_command",
2218
- "edit_file",
2219
- "review",
2220
- "confirm",
2221
- "block",
2222
- "ignore"
2223
- ]
2224
- },
2225
- "title": {
2226
- "type": "string"
2227
- },
2228
- "command": {
2229
- "type": "string",
2230
- "description": "CLI command to run (for run_command kind)."
2231
- },
2232
- "target": {
2233
- "type": "string",
2234
- "description": "Target file or resource."
2235
- },
2236
- "rationale": {
2237
- "type": "string"
2238
- }
2239
- }
2240
- }
2241
- },
2242
- "metadata": {
2243
- "type": "object",
2244
- "properties": {
2245
- "tool": {
2246
- "type": "string"
2247
- },
2248
- "command": {
2249
- "type": "string"
2250
- },
2251
- "version": {
2252
- "type": "string"
2253
- },
2254
- "generatedAt": {
2255
- "type": "string"
2256
- },
2257
- "adapter": {
2258
- "type": "string"
2259
- },
2260
- "model": {
2261
- "type": "string"
2262
- }
2263
- }
2264
- }
2265
- }
2266
- },
2267
- {
2268
- "type": "object",
2269
- "required": [
2270
- "criteriaProposals"
2271
- ],
2272
- "properties": {
2273
- "criteriaProposals": {
2274
- "type": "array",
2275
- "items": {
2276
- "type": "object",
2277
- "required": [
2278
- "specId",
2279
- "criteria",
2280
- "rationale"
2281
- ],
2282
- "properties": {
2283
- "specId": {
2284
- "type": "string"
2285
- },
2286
- "criteria": {
2287
- "type": "array",
2288
- "items": {
2289
- "type": "string"
2290
- }
2291
- },
2292
- "rationale": {
2293
- "type": "string"
2294
- }
2295
- }
2296
- }
2297
- }
2298
- }
2299
- }
2300
- ]
2301
- }
2302
- ```
2303
-
2304
- </details>
2305
-
2306
689
  **Exit 1:** Unexpected error.
2307
690
 
2308
691
  - **stderr:** format=`text`
@@ -2315,229 +698,6 @@ speckeeper propose-acceptance-criteria --adapter gemini --dry-run
2315
698
 
2316
699
  - **stdout:** format=`{options.report-format}`
2317
700
 
2318
-
2319
- <details>
2320
- <summary>JSON Schema</summary>
2321
-
2322
- ```json
2323
- {
2324
- "type": "object",
2325
- "description": "Proposed acceptance criteria for design specs.",
2326
- "allOf": [
2327
- {
2328
- "type": "object",
2329
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
2330
- "required": [
2331
- "summary",
2332
- "riskLevel",
2333
- "findings"
2334
- ],
2335
- "properties": {
2336
- "summary": {
2337
- "type": "string"
2338
- },
2339
- "riskLevel": {
2340
- "type": "string",
2341
- "enum": [
2342
- "low",
2343
- "medium",
2344
- "high",
2345
- "critical"
2346
- ]
2347
- },
2348
- "findings": {
2349
- "type": "array",
2350
- "items": {
2351
- "type": "object",
2352
- "description": "A single finding from an agent audit or analysis.",
2353
- "required": [
2354
- "severity",
2355
- "category",
2356
- "message"
2357
- ],
2358
- "properties": {
2359
- "id": {
2360
- "type": "string",
2361
- "description": "Unique finding identifier."
2362
- },
2363
- "severity": {
2364
- "type": "string",
2365
- "enum": [
2366
- "info",
2367
- "warning",
2368
- "error",
2369
- "critical"
2370
- ]
2371
- },
2372
- "category": {
2373
- "type": "string",
2374
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
2375
- },
2376
- "target": {
2377
- "type": "string",
2378
- "description": "Target of the finding (spec ID, model type)."
2379
- },
2380
- "location": {
2381
- "type": "string",
2382
- "description": "Location within the target."
2383
- },
2384
- "message": {
2385
- "type": "string"
2386
- },
2387
- "recommendation": {
2388
- "type": "string"
2389
- },
2390
- "confidence": {
2391
- "type": "number",
2392
- "minimum": 0,
2393
- "maximum": 1,
2394
- "description": "Confidence score (0-1) for LLM-generated findings."
2395
- },
2396
- "evidence": {
2397
- "type": "array",
2398
- "items": {
2399
- "type": "object",
2400
- "description": "Evidence supporting an agent finding.",
2401
- "required": [
2402
- "kind"
2403
- ],
2404
- "properties": {
2405
- "kind": {
2406
- "type": "string",
2407
- "enum": [
2408
- "file",
2409
- "command",
2410
- "schema",
2411
- "diff",
2412
- "stdout",
2413
- "stderr",
2414
- "text"
2415
- ]
2416
- },
2417
- "target": {
2418
- "type": "string",
2419
- "description": "Target identifier (file path, command ID, schema name)."
2420
- },
2421
- "location": {
2422
- "type": "string",
2423
- "description": "Location within the target (line number, JSON pointer)."
2424
- },
2425
- "excerpt": {
2426
- "type": "string",
2427
- "description": "Relevant excerpt from the target."
2428
- }
2429
- }
2430
- }
2431
- },
2432
- "details": {
2433
- "type": "object",
2434
- "additionalProperties": true
2435
- }
2436
- }
2437
- }
2438
- },
2439
- "recommendedActions": {
2440
- "type": "array",
2441
- "items": {
2442
- "type": "object",
2443
- "description": "A recommended action from an agent audit.",
2444
- "required": [
2445
- "kind",
2446
- "title"
2447
- ],
2448
- "properties": {
2449
- "kind": {
2450
- "type": "string",
2451
- "enum": [
2452
- "run_command",
2453
- "edit_file",
2454
- "review",
2455
- "confirm",
2456
- "block",
2457
- "ignore"
2458
- ]
2459
- },
2460
- "title": {
2461
- "type": "string"
2462
- },
2463
- "command": {
2464
- "type": "string",
2465
- "description": "CLI command to run (for run_command kind)."
2466
- },
2467
- "target": {
2468
- "type": "string",
2469
- "description": "Target file or resource."
2470
- },
2471
- "rationale": {
2472
- "type": "string"
2473
- }
2474
- }
2475
- }
2476
- },
2477
- "metadata": {
2478
- "type": "object",
2479
- "properties": {
2480
- "tool": {
2481
- "type": "string"
2482
- },
2483
- "command": {
2484
- "type": "string"
2485
- },
2486
- "version": {
2487
- "type": "string"
2488
- },
2489
- "generatedAt": {
2490
- "type": "string"
2491
- },
2492
- "adapter": {
2493
- "type": "string"
2494
- },
2495
- "model": {
2496
- "type": "string"
2497
- }
2498
- }
2499
- }
2500
- }
2501
- },
2502
- {
2503
- "type": "object",
2504
- "required": [
2505
- "criteriaProposals"
2506
- ],
2507
- "properties": {
2508
- "criteriaProposals": {
2509
- "type": "array",
2510
- "items": {
2511
- "type": "object",
2512
- "required": [
2513
- "specId",
2514
- "criteria",
2515
- "rationale"
2516
- ],
2517
- "properties": {
2518
- "specId": {
2519
- "type": "string"
2520
- },
2521
- "criteria": {
2522
- "type": "array",
2523
- "items": {
2524
- "type": "string"
2525
- }
2526
- },
2527
- "rationale": {
2528
- "type": "string"
2529
- }
2530
- }
2531
- }
2532
- }
2533
- }
2534
- }
2535
- ]
2536
- }
2537
- ```
2538
-
2539
- </details>
2540
-
2541
701
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime).
2542
702
 
2543
703
  - **stderr:** format=`text`
@@ -2551,591 +711,9 @@ speckeeper propose-acceptance-criteria --adapter gemini --dry-run
2551
711
  ```yaml
2552
712
  x-agent:
2553
713
  recommended_before_use:
2554
- - Run with --dry-run first to preview the prompt
714
+ - Run with --show-prompt first to preview the prompt
2555
715
  retryableExitCodes:
2556
716
  - 12
2557
717
  ```
2558
718
 
2559
719
  ---
2560
-
2561
- ---
2562
-
2563
- ## Schemas
2564
-
2565
- ### AgentEvidence
2566
-
2567
- Evidence supporting an agent finding.
2568
-
2569
- Type: `object`
2570
-
2571
- | Property | Type | Required | Description |
2572
- |---|---|---|---|
2573
- | `kind` | `enum(7 values)` | Yes | |
2574
- | `target` | `string` | No | Target identifier (file path, command ID, schema name). |
2575
- | `location` | `string` | No | Location within the target (line number, JSON pointer). |
2576
- | `excerpt` | `string` | No | Relevant excerpt from the target. |
2577
-
2578
- <details>
2579
- <summary>JSON Schema</summary>
2580
-
2581
- ```json
2582
- {
2583
- "type": "object",
2584
- "description": "Evidence supporting an agent finding.",
2585
- "required": [
2586
- "kind"
2587
- ],
2588
- "properties": {
2589
- "kind": {
2590
- "type": "string",
2591
- "enum": [
2592
- "file",
2593
- "command",
2594
- "schema",
2595
- "diff",
2596
- "stdout",
2597
- "stderr",
2598
- "text"
2599
- ]
2600
- },
2601
- "target": {
2602
- "type": "string",
2603
- "description": "Target identifier (file path, command ID, schema name)."
2604
- },
2605
- "location": {
2606
- "type": "string",
2607
- "description": "Location within the target (line number, JSON pointer)."
2608
- },
2609
- "excerpt": {
2610
- "type": "string",
2611
- "description": "Relevant excerpt from the target."
2612
- }
2613
- }
2614
- }
2615
- ```
2616
-
2617
- </details>
2618
-
2619
- ### AgentFinding
2620
-
2621
- A single finding from an agent audit or analysis.
2622
-
2623
- Type: `object`
2624
-
2625
- | Property | Type | Required | Description |
2626
- |---|---|---|---|
2627
- | `id` | `string` | No | Unique finding identifier. |
2628
- | `severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
2629
- | `category` | `string` | Yes | Finding category (e.g. verifiability, ambiguity, granularity). |
2630
- | `target` | `string` | No | Target of the finding (spec ID, model type). |
2631
- | `location` | `string` | No | Location within the target. |
2632
- | `message` | `string` | Yes | |
2633
- | `recommendation` | `string` | No | |
2634
- | `confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
2635
- | `evidence` | `object[]` | No | |
2636
- | `evidence[].kind` | `enum(7 values)` | Yes | |
2637
- | `evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
2638
- | `evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
2639
- | `evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
2640
- | `details` | `Record<string, any>` | No | |
2641
-
2642
- <details>
2643
- <summary>JSON Schema</summary>
2644
-
2645
- ```json
2646
- {
2647
- "type": "object",
2648
- "description": "A single finding from an agent audit or analysis.",
2649
- "required": [
2650
- "severity",
2651
- "category",
2652
- "message"
2653
- ],
2654
- "properties": {
2655
- "id": {
2656
- "type": "string",
2657
- "description": "Unique finding identifier."
2658
- },
2659
- "severity": {
2660
- "type": "string",
2661
- "enum": [
2662
- "info",
2663
- "warning",
2664
- "error",
2665
- "critical"
2666
- ]
2667
- },
2668
- "category": {
2669
- "type": "string",
2670
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
2671
- },
2672
- "target": {
2673
- "type": "string",
2674
- "description": "Target of the finding (spec ID, model type)."
2675
- },
2676
- "location": {
2677
- "type": "string",
2678
- "description": "Location within the target."
2679
- },
2680
- "message": {
2681
- "type": "string"
2682
- },
2683
- "recommendation": {
2684
- "type": "string"
2685
- },
2686
- "confidence": {
2687
- "type": "number",
2688
- "minimum": 0,
2689
- "maximum": 1,
2690
- "description": "Confidence score (0-1) for LLM-generated findings."
2691
- },
2692
- "evidence": {
2693
- "type": "array",
2694
- "items": {
2695
- "type": "object",
2696
- "description": "Evidence supporting an agent finding.",
2697
- "required": [
2698
- "kind"
2699
- ],
2700
- "properties": {
2701
- "kind": {
2702
- "type": "string",
2703
- "enum": [
2704
- "file",
2705
- "command",
2706
- "schema",
2707
- "diff",
2708
- "stdout",
2709
- "stderr",
2710
- "text"
2711
- ]
2712
- },
2713
- "target": {
2714
- "type": "string",
2715
- "description": "Target identifier (file path, command ID, schema name)."
2716
- },
2717
- "location": {
2718
- "type": "string",
2719
- "description": "Location within the target (line number, JSON pointer)."
2720
- },
2721
- "excerpt": {
2722
- "type": "string",
2723
- "description": "Relevant excerpt from the target."
2724
- }
2725
- }
2726
- }
2727
- },
2728
- "details": {
2729
- "type": "object",
2730
- "additionalProperties": true
2731
- }
2732
- }
2733
- }
2734
- ```
2735
-
2736
- </details>
2737
-
2738
- ### AgentRecommendedAction
2739
-
2740
- A recommended action from an agent audit.
2741
-
2742
- Type: `object`
2743
-
2744
- | Property | Type | Required | Description |
2745
- |---|---|---|---|
2746
- | `kind` | `enum(6 values)` | Yes | |
2747
- | `title` | `string` | Yes | |
2748
- | `command` | `string` | No | CLI command to run (for run_command kind). |
2749
- | `target` | `string` | No | Target file or resource. |
2750
- | `rationale` | `string` | No | |
2751
-
2752
- <details>
2753
- <summary>JSON Schema</summary>
2754
-
2755
- ```json
2756
- {
2757
- "type": "object",
2758
- "description": "A recommended action from an agent audit.",
2759
- "required": [
2760
- "kind",
2761
- "title"
2762
- ],
2763
- "properties": {
2764
- "kind": {
2765
- "type": "string",
2766
- "enum": [
2767
- "run_command",
2768
- "edit_file",
2769
- "review",
2770
- "confirm",
2771
- "block",
2772
- "ignore"
2773
- ]
2774
- },
2775
- "title": {
2776
- "type": "string"
2777
- },
2778
- "command": {
2779
- "type": "string",
2780
- "description": "CLI command to run (for run_command kind)."
2781
- },
2782
- "target": {
2783
- "type": "string",
2784
- "description": "Target file or resource."
2785
- },
2786
- "rationale": {
2787
- "type": "string"
2788
- }
2789
- }
2790
- }
2791
- ```
2792
-
2793
- </details>
2794
-
2795
- ### RequirementAuditResult
2796
-
2797
- Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.
2798
-
2799
- Type: `object`
2800
-
2801
- | Property | Type | Required | Description |
2802
- |---|---|---|---|
2803
- | `summary` | `string` | Yes | |
2804
- | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
2805
- | `findings` | `object[]` | Yes | |
2806
- | `findings[].id` | `string` | No | Unique finding identifier. |
2807
- | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
2808
- | `findings[].category` | `string` | Yes | Finding category (e.g. verifiability, ambiguity, granularity). |
2809
- | `findings[].target` | `string` | No | Target of the finding (spec ID, model type). |
2810
- | `findings[].location` | `string` | No | Location within the target. |
2811
- | `findings[].message` | `string` | Yes | |
2812
- | `findings[].recommendation` | `string` | No | |
2813
- | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
2814
- | `findings[].evidence` | `object[]` | No | |
2815
- | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
2816
- | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
2817
- | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
2818
- | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
2819
- | `findings[].details` | `Record<string, any>` | No | |
2820
- | `recommendedActions` | `object[]` | No | |
2821
- | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
2822
- | `recommendedActions[].title` | `string` | Yes | |
2823
- | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
2824
- | `recommendedActions[].target` | `string` | No | Target file or resource. |
2825
- | `recommendedActions[].rationale` | `string` | No | |
2826
- | `metadata` | `object` | No | |
2827
- | `metadata.tool` | `string` | No | |
2828
- | `metadata.command` | `string` | No | |
2829
- | `metadata.version` | `string` | No | |
2830
- | `metadata.generatedAt` | `string` | No | |
2831
- | `metadata.adapter` | `string` | No | |
2832
- | `metadata.model` | `string` | No | |
2833
-
2834
- <details>
2835
- <summary>JSON Schema</summary>
2836
-
2837
- ```json
2838
- {
2839
- "type": "object",
2840
- "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
2841
- "required": [
2842
- "summary",
2843
- "riskLevel",
2844
- "findings"
2845
- ],
2846
- "properties": {
2847
- "summary": {
2848
- "type": "string"
2849
- },
2850
- "riskLevel": {
2851
- "type": "string",
2852
- "enum": [
2853
- "low",
2854
- "medium",
2855
- "high",
2856
- "critical"
2857
- ]
2858
- },
2859
- "findings": {
2860
- "type": "array",
2861
- "items": {
2862
- "type": "object",
2863
- "description": "A single finding from an agent audit or analysis.",
2864
- "required": [
2865
- "severity",
2866
- "category",
2867
- "message"
2868
- ],
2869
- "properties": {
2870
- "id": {
2871
- "type": "string",
2872
- "description": "Unique finding identifier."
2873
- },
2874
- "severity": {
2875
- "type": "string",
2876
- "enum": [
2877
- "info",
2878
- "warning",
2879
- "error",
2880
- "critical"
2881
- ]
2882
- },
2883
- "category": {
2884
- "type": "string",
2885
- "description": "Finding category (e.g. verifiability, ambiguity, granularity)."
2886
- },
2887
- "target": {
2888
- "type": "string",
2889
- "description": "Target of the finding (spec ID, model type)."
2890
- },
2891
- "location": {
2892
- "type": "string",
2893
- "description": "Location within the target."
2894
- },
2895
- "message": {
2896
- "type": "string"
2897
- },
2898
- "recommendation": {
2899
- "type": "string"
2900
- },
2901
- "confidence": {
2902
- "type": "number",
2903
- "minimum": 0,
2904
- "maximum": 1,
2905
- "description": "Confidence score (0-1) for LLM-generated findings."
2906
- },
2907
- "evidence": {
2908
- "type": "array",
2909
- "items": {
2910
- "type": "object",
2911
- "description": "Evidence supporting an agent finding.",
2912
- "required": [
2913
- "kind"
2914
- ],
2915
- "properties": {
2916
- "kind": {
2917
- "type": "string",
2918
- "enum": [
2919
- "file",
2920
- "command",
2921
- "schema",
2922
- "diff",
2923
- "stdout",
2924
- "stderr",
2925
- "text"
2926
- ]
2927
- },
2928
- "target": {
2929
- "type": "string",
2930
- "description": "Target identifier (file path, command ID, schema name)."
2931
- },
2932
- "location": {
2933
- "type": "string",
2934
- "description": "Location within the target (line number, JSON pointer)."
2935
- },
2936
- "excerpt": {
2937
- "type": "string",
2938
- "description": "Relevant excerpt from the target."
2939
- }
2940
- }
2941
- }
2942
- },
2943
- "details": {
2944
- "type": "object",
2945
- "additionalProperties": true
2946
- }
2947
- }
2948
- }
2949
- },
2950
- "recommendedActions": {
2951
- "type": "array",
2952
- "items": {
2953
- "type": "object",
2954
- "description": "A recommended action from an agent audit.",
2955
- "required": [
2956
- "kind",
2957
- "title"
2958
- ],
2959
- "properties": {
2960
- "kind": {
2961
- "type": "string",
2962
- "enum": [
2963
- "run_command",
2964
- "edit_file",
2965
- "review",
2966
- "confirm",
2967
- "block",
2968
- "ignore"
2969
- ]
2970
- },
2971
- "title": {
2972
- "type": "string"
2973
- },
2974
- "command": {
2975
- "type": "string",
2976
- "description": "CLI command to run (for run_command kind)."
2977
- },
2978
- "target": {
2979
- "type": "string",
2980
- "description": "Target file or resource."
2981
- },
2982
- "rationale": {
2983
- "type": "string"
2984
- }
2985
- }
2986
- }
2987
- },
2988
- "metadata": {
2989
- "type": "object",
2990
- "properties": {
2991
- "tool": {
2992
- "type": "string"
2993
- },
2994
- "command": {
2995
- "type": "string"
2996
- },
2997
- "version": {
2998
- "type": "string"
2999
- },
3000
- "generatedAt": {
3001
- "type": "string"
3002
- },
3003
- "adapter": {
3004
- "type": "string"
3005
- },
3006
- "model": {
3007
- "type": "string"
3008
- }
3009
- }
3010
- }
3011
- }
3012
- }
3013
- ```
3014
-
3015
- </details>
3016
-
3017
- ### TraceLinkResult
3018
-
3019
- Result of trace link proposal with candidate links.
3020
-
3021
- Type: `object`
3022
-
3023
-
3024
- ### ImpactExplainResult
3025
-
3026
- Human-readable explanation of impact analysis output.
3027
-
3028
- Type: `object`
3029
-
3030
-
3031
- ### AcceptanceCriteriaResult
3032
-
3033
- Proposed acceptance criteria for design specs.
3034
-
3035
- Type: `object`
3036
-
3037
-
3038
- ### ImpactAnalysisOutput
3039
-
3040
- JSON output from speckeeper impact --format json.
3041
-
3042
- Type: `object`
3043
-
3044
- | Property | Type | Required | Description |
3045
- |---|---|---|---|
3046
- | `target` | `string` | Yes | |
3047
- | `targetType` | `string` | Yes | |
3048
- | `direction` | `"upstream" \| "downstream" \| "both"` | No | |
3049
- | `depth` | `integer` | No | |
3050
- | `impactedNodes` | `object[]` | Yes | |
3051
- | `impactedNodes[].id` | `string` | Yes | |
3052
- | `impactedNodes[].type` | `string` | Yes | |
3053
- | `impactedNodes[].depth` | `integer` | Yes | |
3054
- | `impactedNodes[].impactType` | `"direct" \| "indirect"` | Yes | |
3055
- | `impactedNodes[].relations` | `object[]` | No | |
3056
- | `impactedNodes[].relations[].type` | `string` | No | |
3057
- | `impactedNodes[].relations[].from` | `string` | No | |
3058
- | `impactedNodes[].relations[].to` | `string` | No | |
3059
-
3060
- <details>
3061
- <summary>JSON Schema</summary>
3062
-
3063
- ```json
3064
- {
3065
- "type": "object",
3066
- "description": "JSON output from speckeeper impact --format json.",
3067
- "required": [
3068
- "target",
3069
- "targetType",
3070
- "impactedNodes"
3071
- ],
3072
- "properties": {
3073
- "target": {
3074
- "type": "string"
3075
- },
3076
- "targetType": {
3077
- "type": "string"
3078
- },
3079
- "direction": {
3080
- "type": "string",
3081
- "enum": [
3082
- "upstream",
3083
- "downstream",
3084
- "both"
3085
- ]
3086
- },
3087
- "depth": {
3088
- "type": "integer"
3089
- },
3090
- "impactedNodes": {
3091
- "type": "array",
3092
- "items": {
3093
- "type": "object",
3094
- "required": [
3095
- "id",
3096
- "type",
3097
- "depth",
3098
- "impactType"
3099
- ],
3100
- "properties": {
3101
- "id": {
3102
- "type": "string"
3103
- },
3104
- "type": {
3105
- "type": "string"
3106
- },
3107
- "depth": {
3108
- "type": "integer"
3109
- },
3110
- "impactType": {
3111
- "type": "string",
3112
- "enum": [
3113
- "direct",
3114
- "indirect"
3115
- ]
3116
- },
3117
- "relations": {
3118
- "type": "array",
3119
- "items": {
3120
- "type": "object",
3121
- "properties": {
3122
- "type": {
3123
- "type": "string"
3124
- },
3125
- "from": {
3126
- "type": "string"
3127
- },
3128
- "to": {
3129
- "type": "string"
3130
- }
3131
- }
3132
- }
3133
- }
3134
- }
3135
- }
3136
- }
3137
- }
3138
- }
3139
- ```
3140
-
3141
- </details>