agent-contracts 0.22.4 → 0.22.6

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 (8) hide show
  1. package/cli-contract.yaml +1 -1
  2. package/dist/cli.js +208 -4
  3. package/dist/cli.js.map +1 -1
  4. package/dist/index.d.ts +6 -3
  5. package/dist/index.js +20 -3
  6. package/dist/index.js.map +1 -1
  7. package/docs/cli-reference.md +438 -3
  8. package/package.json +3 -3
package/docs/cli-reference.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows. Provides static validation, semantic linting, prompt rendering, guardrail generation, and completeness scoring for agent contract definitions.
4
4
 
5
- **Version:** 0.22.0
5
+ **Version:** 0.22.3
6
6
 
7
7
  ## Table of Contents
8
8
 
@@ -332,7 +332,7 @@ agent-contracts score -c agent-contracts.config.yaml
332
332
 
333
333
  Run LLM-based semantic audit on DSL definitions and generated outputs.
334
334
 
335
- Performs LLM-based semantic analysis on DSL definitions and/or generated outputs. Three audit types are available: "render" checks whether generated files faithfully reflect the resolved DSL, "dsl" reviews DSL design for semantic coherence, and "prompt" verifies that generated prompts accurately express DSL intent. Uses agent-contracts-runtime (optional peer dependency) for LLM execution with handoff schema validation and follow-up recovery.
335
+ Performs LLM-based semantic analysis on DSL definitions and/or generated outputs. Four audit types are available: "render" checks whether generated files faithfully reflect the resolved DSL, "dsl" reviews DSL design for semantic coherence, "prompt" verifies that generated prompts accurately express DSL intent, and "extensions" detects declared x-* properties that are not consumed by render templates or runtime codegen. Uses agent-contracts-runtime (optional peer dependency) for LLM execution with handoff schema validation and follow-up recovery.
336
336
 
337
337
  **Usage:**
338
338
 
@@ -346,6 +346,9 @@ agent-contracts audit dsl -c agent-contracts.config.yaml
346
346
  agent-contracts audit prompt -c agent-contracts.config.yaml
347
347
  ```
348
348
  ```
349
+ agent-contracts audit extensions -c agent-contracts.config.yaml
350
+ ```
351
+ ```
349
352
  agent-contracts audit all -c agent-contracts.config.yaml
350
353
  ```
351
354
  ```
@@ -362,7 +365,7 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
362
365
 
363
366
  | Name | Required | Description |
364
367
  |---|---|---|
365
- | `type` | No | Audit type to run: render (semantic diff of generated outputs vs DSL), dsl (design coherence review), prompt (generated prompt fidelity check), or all (run all three). |
368
+ | `type` | No | Audit type to run: render (semantic diff of generated outputs vs DSL), dsl (design coherence review), prompt (generated prompt fidelity check), extensions (unconsumed x-* property detection), or all (run all four). |
366
369
 
367
370
  #### Options
368
371
 
@@ -385,6 +388,222 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
385
388
 
386
389
  - **stdout:** format=`{options.format}`
387
390
 
391
+ | Property | Type | Required | Description |
392
+ |---|---|---|---|
393
+ | `summary` | `string` | Yes | |
394
+ | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
395
+ | `findings` | `object[]` | Yes | |
396
+ | `findings[].id` | `string` | No | Unique finding identifier. |
397
+ | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
398
+ | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
399
+ | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
400
+ | `findings[].location` | `string` | No | Location within the target. |
401
+ | `findings[].message` | `string` | Yes | |
402
+ | `findings[].recommendation` | `string` | No | |
403
+ | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
404
+ | `findings[].evidence` | `object[]` | No | |
405
+ | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
406
+ | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
407
+ | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
408
+ | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
409
+ | `findings[].details` | `Record<string, any>` | No | |
410
+ | `recommendedActions` | `object[]` | No | |
411
+ | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
412
+ | `recommendedActions[].title` | `string` | Yes | |
413
+ | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
414
+ | `recommendedActions[].target` | `string` | No | Target file or resource. |
415
+ | `recommendedActions[].rationale` | `string` | No | |
416
+ | `metadata` | `object` | No | |
417
+ | `metadata.tool` | `string` | No | |
418
+ | `metadata.command` | `string` | No | |
419
+ | `metadata.version` | `string` | No | |
420
+ | `metadata.generatedAt` | `string` | No | |
421
+ | `metadata.adapter` | `string` | No | |
422
+ | `metadata.model` | `string` | No | |
423
+
424
+ <details>
425
+ <summary>JSON Schema</summary>
426
+
427
+ ```json
428
+ {
429
+ "type": "object",
430
+ "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
431
+ "required": [
432
+ "summary",
433
+ "riskLevel",
434
+ "findings"
435
+ ],
436
+ "properties": {
437
+ "summary": {
438
+ "type": "string"
439
+ },
440
+ "riskLevel": {
441
+ "type": "string",
442
+ "enum": [
443
+ "low",
444
+ "medium",
445
+ "high",
446
+ "critical"
447
+ ]
448
+ },
449
+ "findings": {
450
+ "type": "array",
451
+ "items": {
452
+ "type": "object",
453
+ "description": "A single finding from an agent audit or analysis.",
454
+ "required": [
455
+ "severity",
456
+ "category",
457
+ "message"
458
+ ],
459
+ "properties": {
460
+ "id": {
461
+ "type": "string",
462
+ "description": "Unique finding identifier."
463
+ },
464
+ "severity": {
465
+ "type": "string",
466
+ "enum": [
467
+ "info",
468
+ "warning",
469
+ "error",
470
+ "critical"
471
+ ]
472
+ },
473
+ "category": {
474
+ "type": "string",
475
+ "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
476
+ },
477
+ "target": {
478
+ "type": "string",
479
+ "description": "Target of the finding (command ID, schema path)."
480
+ },
481
+ "location": {
482
+ "type": "string",
483
+ "description": "Location within the target."
484
+ },
485
+ "message": {
486
+ "type": "string"
487
+ },
488
+ "recommendation": {
489
+ "type": "string"
490
+ },
491
+ "confidence": {
492
+ "type": "number",
493
+ "minimum": 0,
494
+ "maximum": 1,
495
+ "description": "Confidence score (0-1) for LLM-generated findings."
496
+ },
497
+ "evidence": {
498
+ "type": "array",
499
+ "items": {
500
+ "type": "object",
501
+ "description": "Evidence supporting an agent finding.",
502
+ "required": [
503
+ "kind"
504
+ ],
505
+ "properties": {
506
+ "kind": {
507
+ "type": "string",
508
+ "enum": [
509
+ "file",
510
+ "command",
511
+ "schema",
512
+ "diff",
513
+ "stdout",
514
+ "stderr",
515
+ "text"
516
+ ]
517
+ },
518
+ "target": {
519
+ "type": "string",
520
+ "description": "Target identifier (file path, command ID, schema name)."
521
+ },
522
+ "location": {
523
+ "type": "string",
524
+ "description": "Location within the target (line number, JSON pointer)."
525
+ },
526
+ "excerpt": {
527
+ "type": "string",
528
+ "description": "Relevant excerpt from the target."
529
+ }
530
+ }
531
+ }
532
+ },
533
+ "details": {
534
+ "type": "object",
535
+ "additionalProperties": true
536
+ }
537
+ }
538
+ }
539
+ },
540
+ "recommendedActions": {
541
+ "type": "array",
542
+ "items": {
543
+ "type": "object",
544
+ "description": "A recommended action from an agent audit.",
545
+ "required": [
546
+ "kind",
547
+ "title"
548
+ ],
549
+ "properties": {
550
+ "kind": {
551
+ "type": "string",
552
+ "enum": [
553
+ "run_command",
554
+ "edit_file",
555
+ "review",
556
+ "confirm",
557
+ "block",
558
+ "ignore"
559
+ ]
560
+ },
561
+ "title": {
562
+ "type": "string"
563
+ },
564
+ "command": {
565
+ "type": "string",
566
+ "description": "CLI command to run (for run_command kind)."
567
+ },
568
+ "target": {
569
+ "type": "string",
570
+ "description": "Target file or resource."
571
+ },
572
+ "rationale": {
573
+ "type": "string"
574
+ }
575
+ }
576
+ }
577
+ },
578
+ "metadata": {
579
+ "type": "object",
580
+ "properties": {
581
+ "tool": {
582
+ "type": "string"
583
+ },
584
+ "command": {
585
+ "type": "string"
586
+ },
587
+ "version": {
588
+ "type": "string"
589
+ },
590
+ "generatedAt": {
591
+ "type": "string"
592
+ },
593
+ "adapter": {
594
+ "type": "string"
595
+ },
596
+ "model": {
597
+ "type": "string"
598
+ }
599
+ }
600
+ }
601
+ }
602
+ }
603
+ ```
604
+
605
+ </details>
606
+
388
607
  **Exit 1:** Unexpected error (invalid input, config error, or internal failure).
389
608
 
390
609
  - **stderr:** format=`text`
@@ -393,6 +612,222 @@ agent-contracts audit dsl --scope agents:architect,implementer -c config.yaml
393
612
 
394
613
  - **stdout:** format=`{options.format}`
395
614
 
615
+ | Property | Type | Required | Description |
616
+ |---|---|---|---|
617
+ | `summary` | `string` | Yes | |
618
+ | `riskLevel` | `"low" \| "medium" \| "high" \| "critical"` | Yes | |
619
+ | `findings` | `object[]` | Yes | |
620
+ | `findings[].id` | `string` | No | Unique finding identifier. |
621
+ | `findings[].severity` | `"info" \| "warning" \| "error" \| "critical"` | Yes | |
622
+ | `findings[].category` | `string` | Yes | Finding category (e.g. missing-policy, inconsistent-risk). |
623
+ | `findings[].target` | `string` | No | Target of the finding (command ID, schema path). |
624
+ | `findings[].location` | `string` | No | Location within the target. |
625
+ | `findings[].message` | `string` | Yes | |
626
+ | `findings[].recommendation` | `string` | No | |
627
+ | `findings[].confidence` | `number (min: 0, max: 1)` | No | Confidence score (0-1) for LLM-generated findings. |
628
+ | `findings[].evidence` | `object[]` | No | |
629
+ | `findings[].evidence[].kind` | `enum(7 values)` | Yes | |
630
+ | `findings[].evidence[].target` | `string` | No | Target identifier (file path, command ID, schema name). |
631
+ | `findings[].evidence[].location` | `string` | No | Location within the target (line number, JSON pointer). |
632
+ | `findings[].evidence[].excerpt` | `string` | No | Relevant excerpt from the target. |
633
+ | `findings[].details` | `Record<string, any>` | No | |
634
+ | `recommendedActions` | `object[]` | No | |
635
+ | `recommendedActions[].kind` | `enum(6 values)` | Yes | |
636
+ | `recommendedActions[].title` | `string` | Yes | |
637
+ | `recommendedActions[].command` | `string` | No | CLI command to run (for run_command kind). |
638
+ | `recommendedActions[].target` | `string` | No | Target file or resource. |
639
+ | `recommendedActions[].rationale` | `string` | No | |
640
+ | `metadata` | `object` | No | |
641
+ | `metadata.tool` | `string` | No | |
642
+ | `metadata.command` | `string` | No | |
643
+ | `metadata.version` | `string` | No | |
644
+ | `metadata.generatedAt` | `string` | No | |
645
+ | `metadata.adapter` | `string` | No | |
646
+ | `metadata.model` | `string` | No | |
647
+
648
+ <details>
649
+ <summary>JSON Schema</summary>
650
+
651
+ ```json
652
+ {
653
+ "type": "object",
654
+ "description": "Top-level result from an agent audit. Canonical schema for agent interoperability across toolchains.",
655
+ "required": [
656
+ "summary",
657
+ "riskLevel",
658
+ "findings"
659
+ ],
660
+ "properties": {
661
+ "summary": {
662
+ "type": "string"
663
+ },
664
+ "riskLevel": {
665
+ "type": "string",
666
+ "enum": [
667
+ "low",
668
+ "medium",
669
+ "high",
670
+ "critical"
671
+ ]
672
+ },
673
+ "findings": {
674
+ "type": "array",
675
+ "items": {
676
+ "type": "object",
677
+ "description": "A single finding from an agent audit or analysis.",
678
+ "required": [
679
+ "severity",
680
+ "category",
681
+ "message"
682
+ ],
683
+ "properties": {
684
+ "id": {
685
+ "type": "string",
686
+ "description": "Unique finding identifier."
687
+ },
688
+ "severity": {
689
+ "type": "string",
690
+ "enum": [
691
+ "info",
692
+ "warning",
693
+ "error",
694
+ "critical"
695
+ ]
696
+ },
697
+ "category": {
698
+ "type": "string",
699
+ "description": "Finding category (e.g. missing-policy, inconsistent-risk)."
700
+ },
701
+ "target": {
702
+ "type": "string",
703
+ "description": "Target of the finding (command ID, schema path)."
704
+ },
705
+ "location": {
706
+ "type": "string",
707
+ "description": "Location within the target."
708
+ },
709
+ "message": {
710
+ "type": "string"
711
+ },
712
+ "recommendation": {
713
+ "type": "string"
714
+ },
715
+ "confidence": {
716
+ "type": "number",
717
+ "minimum": 0,
718
+ "maximum": 1,
719
+ "description": "Confidence score (0-1) for LLM-generated findings."
720
+ },
721
+ "evidence": {
722
+ "type": "array",
723
+ "items": {
724
+ "type": "object",
725
+ "description": "Evidence supporting an agent finding.",
726
+ "required": [
727
+ "kind"
728
+ ],
729
+ "properties": {
730
+ "kind": {
731
+ "type": "string",
732
+ "enum": [
733
+ "file",
734
+ "command",
735
+ "schema",
736
+ "diff",
737
+ "stdout",
738
+ "stderr",
739
+ "text"
740
+ ]
741
+ },
742
+ "target": {
743
+ "type": "string",
744
+ "description": "Target identifier (file path, command ID, schema name)."
745
+ },
746
+ "location": {
747
+ "type": "string",
748
+ "description": "Location within the target (line number, JSON pointer)."
749
+ },
750
+ "excerpt": {
751
+ "type": "string",
752
+ "description": "Relevant excerpt from the target."
753
+ }
754
+ }
755
+ }
756
+ },
757
+ "details": {
758
+ "type": "object",
759
+ "additionalProperties": true
760
+ }
761
+ }
762
+ }
763
+ },
764
+ "recommendedActions": {
765
+ "type": "array",
766
+ "items": {
767
+ "type": "object",
768
+ "description": "A recommended action from an agent audit.",
769
+ "required": [
770
+ "kind",
771
+ "title"
772
+ ],
773
+ "properties": {
774
+ "kind": {
775
+ "type": "string",
776
+ "enum": [
777
+ "run_command",
778
+ "edit_file",
779
+ "review",
780
+ "confirm",
781
+ "block",
782
+ "ignore"
783
+ ]
784
+ },
785
+ "title": {
786
+ "type": "string"
787
+ },
788
+ "command": {
789
+ "type": "string",
790
+ "description": "CLI command to run (for run_command kind)."
791
+ },
792
+ "target": {
793
+ "type": "string",
794
+ "description": "Target file or resource."
795
+ },
796
+ "rationale": {
797
+ "type": "string"
798
+ }
799
+ }
800
+ }
801
+ },
802
+ "metadata": {
803
+ "type": "object",
804
+ "properties": {
805
+ "tool": {
806
+ "type": "string"
807
+ },
808
+ "command": {
809
+ "type": "string"
810
+ },
811
+ "version": {
812
+ "type": "string"
813
+ },
814
+ "generatedAt": {
815
+ "type": "string"
816
+ },
817
+ "adapter": {
818
+ "type": "string"
819
+ },
820
+ "model": {
821
+ "type": "string"
822
+ }
823
+ }
824
+ }
825
+ }
826
+ }
827
+ ```
828
+
829
+ </details>
830
+
396
831
  - **stderr:** format=`text`
397
832
 
398
833
  **Exit 11:** Runtime dependency missing (agent-contracts-runtime not installed).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-contracts",
3
- "version": "0.22.4",
3
+ "version": "0.22.6",
4
4
  "description": "Declarative YAML DSL toolkit for defining, validating, and rendering multi-agent development workflows",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -64,12 +64,12 @@
64
64
  "@stoplight/spectral-functions": "^1.9.0",
65
65
  "@stoplight/spectral-rulesets": "^1.22.1",
66
66
  "ajv": "^8.18.0",
67
+ "cli-contracts": "^0.7.2",
67
68
  "commander": "^14.0.3",
68
69
  "handlebars": "^4.7.9",
69
70
  "yaml": "^2.8.3",
70
71
  "zod": "^4.3.6",
71
- "zod-to-json-schema": "^3.25.2",
72
- "cli-contracts": "^0.7.0"
72
+ "zod-to-json-schema": "^3.25.2"
73
73
  },
74
74
  "devDependencies": {
75
75
  "@anthropic-ai/claude-agent-sdk": "^0.2.138",