agent-contracts 0.30.1 → 0.30.3

package/README.md

@@ -340,6 +340,7 @@ Design regressions become testable.
 * **Software bindings** (DI) for tool-specific guardrail implementation (Cursor, Git, GitHub)
 * **Guardrail generation** from DSL + policy + bindings via `generate guardrails`
 * **Navigation index** — compile-time artifact-centric model mapping artifacts to operations, agent permissions, relations, and action routes
+* **Artifact coverage** — measure what percentage of project files are covered by artifact `path_patterns` definitions, with CI gating via `--min-coverage`
 * **Tool `extends`** — tool inheritance for sharing `cli_contract`, `artifact_bindings`, and other metadata across related tool definitions
 * **Interface generation** from DSL via `generate interface` for cross-team contracts
 * **Flexible file splitting** via `$ref` (replacement), `$refs` (import + deep-merge), and JSON Pointer `$ref` (in-document)
@@ -1130,6 +1131,7 @@ npx agent-contracts
 | `agent-contracts audit <type>`    | Run LLM-based semantic audit (render/dsl/prompt/all)   |
 | `agent-contracts check`           | Run resolve → validate → lint → render --check         |
 | `agent-contracts navigation-index` | Build artifact-centric navigation index |
+| `agent-contracts artifact-coverage` | Measure file coverage by artifact definitions |
 | `agent-contracts render`          | _(deprecated)_ Alias for `generate templates`          |
 
 The `[path]` argument defaults to `agent-contracts.yaml` in the current directory.
@@ -1209,6 +1211,25 @@ audit:
   model: gpt-4.1
 ```
 
+#### `artifact-coverage` options
+
+| Option | Description |
+|--------|-------------|
+| `--format <text\|json>` | Output format (default: `text`) |
+| `--min-coverage <number>` | Minimum coverage %; exit 1 if below (for CI gates) |
+| `-c, --config <path>` | Path to `agent-contracts.config.yaml` |
+| `--team <id>` | Limit to one team (multi-team config only) |
+
+Configure additional exclude patterns in `agent-contracts.config.yaml`:
+
+```yaml
+artifact_coverage:
+  exclude_patterns:
+    - "*.lock"
+    - "**/*.snap"
+    - ".cursor/**"
+```
+
 The score command evaluates 7 dimensions:
 
 | Dimension | What it measures | Weight |
@@ -1245,6 +1266,10 @@ agent-contracts audit dsl -c agent-contracts.config.yaml --dry-run
 agent-contracts navigation-index
 agent-contracts navigation-index --format yaml
 agent-contracts navigation-index --artifact api-contracts
+agent-contracts artifact-coverage
+agent-contracts artifact-coverage --format json
+agent-contracts artifact-coverage --min-coverage 80
+agent-contracts artifact-coverage -c agent-contracts.config.yaml
 ````
 
 ---
@@ -1451,6 +1476,10 @@ Templates can use these built-in helpers:
 | `notEmpty` | `{{#if (notEmpty obj)}}` | True when object has at least one key |
 | `inc` | `{{inc @index}}` | Increment number by 1 (for 1-based indexing) |
 | `yamlBlock` | `{{{yamlBlock obj}}}` | Render value as YAML-formatted text |
+| `jsonBlock` | `{{{jsonBlock obj}}}` | Render value as pretty-printed JSON |
+| `yamlFrontmatter` | `{{{yamlFrontmatter obj}}}` | Render value as YAML frontmatter (`---` delimiters) |
+| `handoffPayload` | `(handoffPayload handoffType)` | Resolve handoff payload (`example` or schema skeleton) |
+| `handoffEnvelope` | `(handoffEnvelope handoffType id=@key)` | Build `{ type, version, payload }` envelope object |
 | `lookupPayloadFields` | `{{#each (lookupPayloadFields schema)}}` | Extract schema field info (name, type, required, enum); resolves `allOf` internally |
 | `join` | `{{join arr ", "}}` | Join array elements with separator |
 | `contains` | `{{#if (contains arr "x")}}` | True when array includes value |

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
 
 info:
   title: agent-contracts CLI
-  version: 0.30.1
+  version: 0.30.2
   description: >-
     Declarative YAML DSL toolkit for defining, validating, and rendering
     multi-agent development workflows. Provides static validation,
@@ -911,3 +911,82 @@ command_sets:
             description: Build failed — schema validation error, config error, or resolution failure.
             stderr:
               format: text
+
+      # ── artifact-coverage ────────────────────────────────
+      artifact-coverage:
+        summary: Measure file coverage by artifact path_patterns definitions.
+        description: >-
+          Cross-references git ls-files output against compiled artifact
+          path_patterns / exclude_patterns to measure what percentage of
+          a project's tracked files are covered by artifact definitions.
+          Reports uncovered files, overlapping files, and per-artifact
+          match counts. Supports CI gating via --min-coverage.
+        usage:
+          - agent-contracts artifact-coverage
+          - agent-contracts artifact-coverage -c agent-contracts.config.yaml
+          - agent-contracts artifact-coverage --format json
+          - agent-contracts artifact-coverage --min-coverage 80
+
+        arguments:
+          - name: dir
+            index: 0
+            required: false
+            description: Path to agent-contracts.yaml.
+            schema:
+              type: string
+              default: agent-contracts.yaml
+            file:
+              mode: read
+              exists: true
+              media_type: application/yaml
+              encoding: utf-8
+
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to agent-contracts.config.yaml.
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+          - name: team
+            description: Limit to one team (multi-team config only).
+            value_name: id
+            schema:
+              type: string
+
+          - name: format
+            description: Output format.
+            value_name: format
+            schema:
+              type: string
+              enum: [text, json]
+              default: text
+
+          - name: min-coverage
+            description: Minimum coverage percentage; exit 1 if below (for CI gates).
+            value_name: number
+            schema:
+              type: number
+
+        exits:
+          '0':
+            description: Coverage report generated (and above threshold if --min-coverage specified).
+            stdout:
+              format: '{options.format}'
+              schema_note: >-
+                Output format depends on --format option. Text shows
+                human-readable coverage report; json produces structured
+                ArtifactCoverageReport object.
+
+          '1':
+            description: >-
+              Coverage below threshold, schema validation failed,
+              or unexpected error.
+            stderr:
+              format: text