@vibe-agent-toolkit/cli 0.2.0-rc.7 → 0.2.0-rc.9

package/docs/skill-test.md

@@ -161,21 +161,22 @@ The suite is never copied into anything the executor can reach. Each eval's decl
 
 ## Exit codes
 
-The harness deliberately separates "the evals failed" from "the harness broke", so
-CI can tolerate one and gate on the other.
+The same three-way contract as every other `vat` command, so a CI consumer can
+tolerate eval failures while failing closed on a harness that could not run.
 
-- `0` - Run completed, all expectations passed
-- `1` - Harness broke (internal error, stall, timeout, grader nonce failure)
-- `2` - Preflight failure (bad config, unresolvable required companion, auth guard, `build` hook failed)
-- `3` - Bootstrap failure
-- `4` - **Eval failure** — the run completed but expectations did not all pass
+- `0` - Run completed, all expectations passed (or `--allow-eval-failure` suppressed a failing verdict)
+- `1` - **Eval failure** — the run completed and produced a valid `grading.json`; expectations did not all pass
+- `2` - The harness could not run. A `Reason: <reason>` line on stderr says why:
+  - `internal` — the harness broke (executor/grader crash, stall, timeout, grader nonce failure)
+  - `preflight` — the environment or inputs need fixing (bad config, unresolvable required companion, auth guard, missing security ack, `build` hook failed)
+  - `bootstrap` — `evals.json` was absent, so VAT wrote a starter template next to the skill source; fill it in and re-run
 
 ```bash
 vat skill test run my-skill --i-understand-this-runs-skill-code
 case $? in
   0) ;;
-  4) echo "evals failed (tolerated)" ;;
-  *) exit 1 ;;    # harness broke — fail the build
+  1) echo "evals failed (tolerated)" ;;
+  *) exit 1 ;;    # harness could not run — fail the build; read Reason: on stderr
 esac
 ```
 

package/docs/skills.md

@@ -39,7 +39,7 @@ skills:
 - `paths` is optional on `allow` entries and defaults to `["**/*"]` (the whole skill).
 - Expired `allow` entries still apply; a separate `ALLOW_EXPIRED` warning surfaces the stale date for re-review. Opt into strict expiry with `severity.ALLOW_EXPIRED: error`.
 - Unused `allow` entries surface as `ALLOW_UNUSED` (analogous to ESLint's unused-disable).
-- `vat audit` is advisory: it applies `severity` for display grouping only, ignores `allow`, and always exits 0.
+- `vat audit` applies `severity` (a code set to `error` gates, `warning` does not, `ignore` hides it) and ignores `allow`; its exit code follows the report's `status`.
 
 See `docs/validation-codes.md` for the full code reference with per-code descriptions and defaults.
 
@@ -159,8 +159,8 @@ discovery rule that this command participates in.
 
 **Exit Codes:**
 - `0` - Build successful (or dry-run preview)
-- `1` - Invalid source or build error
-- `2` - System error (missing package.json, invalid config)
+- `1` - A skill failed its validation gate, or a shipped link check found an error
+- `2` - The build could not run (missing package.json, invalid config, an unknown flag, an internal failure)
 
 **Output Format:**
 ```yaml
@@ -242,8 +242,8 @@ for terminology.
 
 **Exit Codes:**
 - `0` - Packaging successful (or dry-run preview)
-- `1` - Invalid skill path or packaging error
-- `2` - System error
+- `1` - The skill failed its validation gate, or its ZIP exceeds the upload size limit
+- `2` - Packaging could not run (skill path not found, an unknown flag, an internal failure)
 
 **What Gets Packaged:**
 - Root SKILL.md file
@@ -364,8 +364,7 @@ any other target lands correctly but is invisible to them.
 
 **Exit Codes:**
 - `0` - Install successful (or dry-run complete)
-- `1` - Install error (validation failed, conflict without `--force`, source not found, bad target/scope)
-- `2` - System error (unexpected exception)
+- `2` - Install could not proceed: the source was not found or failed validation, the skill is already present and `--force` was not passed, a bad target/scope, an unexpected exception. None of these is a finding about a skill, so none is exit `1`; the message says which.
 
 **YAML Output Format:**
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/cli",
-  "version": "0.2.0-rc.7",
+  "version": "0.2.0-rc.9",
   "description": "Command-line interface for vibe-agent-toolkit",
   "type": "module",
   "bin": {
@@ -18,18 +18,20 @@
   "files": [
     "dist",
     "docs",
+    "schemas",
     "README.md",
     "!dist/pipeline-oracles",
     "!dist/qa-snapshot"
   ],
   "scripts": {
-    "build": "tsx src/utils/validate-help-files.ts && tsx ../dev-tools/src/tsc-clean-build.ts && tsx ../dev-tools/src/prepare-bin.ts",
+    "build": "tsx src/utils/validate-help-files.ts && tsx ../dev-tools/src/tsc-clean-build.ts && bun run generate:schemas && tsx ../dev-tools/src/prepare-bin.ts",
+    "generate:schemas": "tsx scripts/generate-json-schemas.ts",
     "test:unit": "vitest run",
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:system": "vitest run --config vitest.system.config.ts",
     "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist *.tsbuildinfo"
+    "clean": "rimraf --glob dist \"*.tsbuildinfo\" .tsc-staging"
   },
   "keywords": [
     "cli",
@@ -46,35 +48,28 @@
   "//dependencies-note": "DO NOT add example agent packages or adopter packages here. Adopter packages (like vat-development-agents) depend on the CLI binary at build time — declaring them as deps creates a circular build dependency. They are built in a second turbo pass via package#task overrides in turbo.json.",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.71.2",
-    "@vibe-agent-toolkit/agent-config": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/agent-skills": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/claude-marketplace": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/discovery": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/gateway-mcp": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/projection-sqlite": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/resources": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/schema": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/utils": "0.2.0-rc.7",
-    "adm-zip": "^0.6.0",
+    "@vibe-agent-toolkit/agent-config": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/agent-skills": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/claude-marketplace": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/discovery": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/gateway-mcp": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/projection-sqlite": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/resources": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/schema": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/utils": "0.2.0-rc.9",
+    "adm-zip": "^0.6.1",
     "commander": "^12.1.0",
     "picomatch": "^4.0.3",
-    "semver": "^7.7.3",
+    "semver": "^7.8.5",
     "tar": "^7.5.7",
-    "yaml": "^2.6.1",
-    "zod": "^3.24.1"
+    "yaml": "^2.9.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@types/adm-zip": "^0.5.7",
-    "@types/node": "^22.10.5",
-    "@types/picomatch": "^4.0.2",
-    "@types/semver": "^7.7.1",
     "@types/tar": "^6.1.13",
-    "@vibe-agent-toolkit/dev-tools": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/rag": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.7",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.7.3",
-    "vitest": "^4.1.11"
+    "@vibe-agent-toolkit/dev-tools": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/rag": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.9"
   },
   "publishConfig": {
     "access": "public"
@@ -85,8 +80,8 @@
   },
   "//peerDependencies-note": "The RAG backends are OPTIONAL PEERS, never optionalDependencies. `optionalDependencies` are INSTALLED BY DEFAULT by npm and pnpm alike - 'optional' there means the install may fail without failing the build, not that it is skipped - so declaring them that way shipped ~287 MB unpacked (onnxruntime-web 137.5 MB, a LanceDB platform binary 97.8 MB, gpt-tokenizer 42.2 MB, apache-arrow 5.3 MB, protobufjs 3.0 MB; measured on darwin-arm64 against this release's pins, and the platform binary is larger on win32-x64) to every adopter, contradicting the seam in src/utils/optional-backend.ts that exists precisely to keep them out. Optional peers are NOT auto-installed, so the manifest now says what that module already says: these ship separately, and an absent one is a legible error naming the package to install. projection-sqlite is deliberately NOT in this group: it has zero third-party dependencies (only node:sqlite, which is built into Node) and a 152 KB dist, so the platform-binary argument that justifies the seam is simply false for it. It is also what `vat resources query` builds its ephemeral in-memory store from, and a query surface that works only where a backend was separately installed is the capability gate the projection design forbids.",
   "peerDependencies": {
-    "@vibe-agent-toolkit/rag": "0.2.0-rc.7",
-    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.7"
+    "@vibe-agent-toolkit/rag": "0.2.0-rc.9",
+    "@vibe-agent-toolkit/rag-lancedb": "0.2.0-rc.9"
   },
   "peerDependenciesMeta": {
     "@vibe-agent-toolkit/rag": {

package/schemas/ard-emit.json

@@ -0,0 +1,149 @@
+{
+  "$ref": "#/definitions/ard-emit",
+  "definitions": {
+    "ard-emit": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "ok",
+            "findings",
+            "error"
+          ]
+        },
+        "examined": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "location": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              },
+              "field": {
+                "type": "string"
+              },
+              "link": {
+                "type": "string"
+              },
+              "fix": {
+                "type": "string"
+              },
+              "reference": {
+                "type": "string"
+              },
+              "suggestion": {
+                "type": "string"
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "error",
+                  "warning",
+                  "info"
+                ]
+              },
+              "column": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "severity"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "summary": {
+          "type": "object",
+          "properties": {
+            "errors": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "warnings": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "info": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "required": [
+            "errors",
+            "warnings",
+            "info"
+          ],
+          "additionalProperties": false
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "error": {
+          "type": "string"
+        },
+        "data": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "outputPath": {
+                  "type": "string"
+                },
+                "entryCount": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "skippedCount": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "shadowedCount": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "outputPath",
+                "entryCount",
+                "skippedCount",
+                "shadowedCount"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "status",
+        "examined",
+        "findings",
+        "summary",
+        "data"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/schemas/okf-validate.json

@@ -0,0 +1,170 @@
+{
+  "$ref": "#/definitions/okf-validate",
+  "definitions": {
+    "okf-validate": {
+      "type": "object",
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "ok",
+            "findings",
+            "error"
+          ]
+        },
+        "examined": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "location": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              },
+              "field": {
+                "type": "string"
+              },
+              "link": {
+                "type": "string"
+              },
+              "fix": {
+                "type": "string"
+              },
+              "reference": {
+                "type": "string"
+              },
+              "suggestion": {
+                "type": "string"
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "error",
+                  "warning",
+                  "info"
+                ]
+              },
+              "column": {
+                "type": "integer",
+                "exclusiveMinimum": 0
+              }
+            },
+            "required": [
+              "code",
+              "message",
+              "severity"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "summary": {
+          "type": "object",
+          "properties": {
+            "errors": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "warnings": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "info": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "required": [
+            "errors",
+            "warnings",
+            "info"
+          ],
+          "additionalProperties": false
+        },
+        "durationMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "error": {
+          "type": "string"
+        },
+        "data": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "bundles": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "bundle": {
+                        "type": "string"
+                      },
+                      "root": {
+                        "type": "string"
+                      },
+                      "conceptDocuments": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "reservedDocuments": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "declaredOkfVersion": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "bundle",
+                      "root",
+                      "conceptDocuments",
+                      "reservedDocuments"
+                    ],
+                    "additionalProperties": false
+                  }
+                },
+                "notice": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "bundles"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "status",
+        "examined",
+        "findings",
+        "summary",
+        "data"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}