> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Rules: All 15 agentic-spec Validation Checks

> The 15 validation rules that agentic-spec enforces on every spec — from identity checks to cascade correctness to AI-Ready honesty gates.

The `agentic-spec` validator enforces 15 rules on every component spec. Each rule prevents a specific class of bug that emerges when AI agents write code against a design system: a spec the agent can't parse, a token the agent references that doesn't exist, a status field that claims readiness the spec hasn't earned. These rules are not stylistic preferences. They are the mechanical checks that keep the contract trustworthy.

## Identity & structure rules

These rules verify that the spec and its companion token file exist, are parseable, and agree with each other. A spec that fails any of these can't be read — by the validator, by an agent, or by a developer.

| Rule | What it checks | Why |
| - | - | - |
| `missing-spec` | `index.md` exists in the spec directory | Without a spec, there is no contract. An agent pointed at a missing spec has nothing to load. |
| `missing-tokens` | `tokens.json` exists in the spec directory | The closed token list lives here. Without it, `token_contract` in the frontmatter has nothing to validate against. |
| `no-frontmatter` | `index.md` contains a parseable YAML frontmatter block | The frontmatter is the machine-readable contract. A spec without parseable frontmatter is prose, not a contract. |
| `bad-frontmatter` | The YAML in the frontmatter block parses cleanly | A spec the agent cannot parse is worse than no spec — it silently produces wrong output. |
| `identity-mismatch` | The `component:` field in `index.md` matches the `component:` field in `tokens.json` | Drift between the two files means they're describing different things. This is a wiring error, not a style issue. |

## Token cascade rules

These rules enforce the integrity of the 3-tier cascade. Each one catches a different way the token contract can become inconsistent — a name that points nowhere, an entry that's never referenced, a tier value that's malformed, a path that can't resolve.

| Rule | What it checks | Why |
| - | - | - |
| `missing-token-entry` | Every name listed in `token_contract` has a corresponding entry in `tokens.json` | A contract that points at a non-existent entry is not a contract — it's a list of broken references. |
| `orphan-token-entry` | Every entry in `tokens.json` is referenced by at least one name in `token_contract` | Orphans indicate either stale tokens that were never cleaned up, or a spec update that forgot to add the new entry to `token_contract`. |
| `bad-token-tier` | Each entry's `tier` field is one of `primitive`, `semantic`, or `component` | Any other value means the entry is malformed and the validator can't reason about cascade correctness. |
| `bad-token-path` | Each entry has a non-empty `path` field | Without a path, the entry can't resolve to a value. An agent that reads it has nothing to bind. |
| `missing-token-role` | Each entry has a non-empty `role` field | The role is what tells an agent which value to pick when multiple entries could apply. Missing roles produce ambiguous lookups. |

## Metadata sanity rules

These rules check the bookkeeping fields that agents and humans use to assess how much to trust a spec.

| Rule | What it checks | Why |
| - | - | - |
| `bad-status` | `status` is exactly one of `AI-Ready`, `In progress`, or `Draft` | Any other value breaks the gate logic. The validator can't apply the `ai-ready-gate` rule if it doesn't recognize the status. |
| `bad-date` | `last_verified` matches `YYYY-MM-DD` format | Other date formats aren't sortable by tooling. Staleness checks depend on consistent formatting. |
| `future-date` | `last_verified` is not set to a date in the future | A spec verified tomorrow has not been verified. This usually indicates a copy-paste error or a date bump that ran ahead of the actual verification. |

## Honesty gates

These two rules prevent specs from misrepresenting their own readiness. A spec that falsely claims to be `AI-Ready` corrupts the system for every agent and developer who trusts it.

| Rule | What it checks | Why |
| - | - | - |
| `lying-check` | `checks.tokens_valid: true` is only present when the validator independently agrees that all token entries are valid | A `checks` block is self-reported. Without a cross-check, a spec could claim `tokens_valid: true` while the token entries are broken. This rule is what makes `checks` trustworthy. |
| `ai-ready-gate` | `status: AI-Ready` is only set when all five `checks` fields (`aria_correct`, `structure_correct`, `states_complete`, `tokens_valid`, `no_invented_styles`) are `true` | `AI-Ready` is a defined term in Clementine: it means all five gates passed. A spec that sets `AI-Ready` with any check `false` is making a false claim. |

## Fixing a failure

Every line of validator output includes the rule name. Look it up in the tables above to understand what's broken, then apply the relevant fix.

### Example error (blocks the build)

```
FAIL button (./specs/button)
  error  missing-token-entry    Spec lists "button.bg.invalid" in token_contract but tokens.json has no entry  (token_contract → button.bg.invalid)
```

This means `button.bg.invalid` appears in the `token_contract` list in `specs/button/index.md` but has no corresponding entry in `specs/button/tokens.json`. You have two options:

1. Add `button.bg.invalid` to `tokens.json` with a real `path`, `tier`, `role`, and `references` — if the token should genuinely exist.
2. Remove `button.bg.invalid` from `token_contract` in the frontmatter — if the entry was added by mistake or is no longer needed.

### Example warning (does not block the build, but blocks AI-Ready promotion)

```
PASS button (./specs/button)
  warn   orphan-token-entry     tokens.json entry "button.legacy" is not referenced by token_contract
```

This means `tokens.json` contains an entry named `button.legacy` that nothing in `token_contract` points at. The spec passes, but the warning will prevent the spec from being promoted to `AI-Ready`. Fix it by:

1. Adding `button.legacy` to `token_contract` — if the token is still in use and should be part of the contract.
2. Removing `button.legacy` from `tokens.json` — if the token is stale and no longer needed.

Warnings represent inconsistencies that don't block code from shipping but do compromise the spec's reliability as an agent contract.

## Output formats

Run the validator in human-readable mode when working locally:

```bash theme={null}
agentic-spec validate specs/button
```

Run it with `--json` for machine-readable output in CI pipelines, pre-commit hooks, or any tool that needs to parse the results:

```bash theme={null}
agentic-spec validate specs/button --json
```

The exit code is non-zero on any error, and zero on warning-only or clean pass. This makes it straightforward to use in a `package.json` script or a GitHub Actions step — the build fails on errors, and warnings are visible in output without blocking the pipeline.

## What the rules do NOT check

The validator is mechanical. It checks for structural consistency between the spec and its token file. It does not check:

* **Correctness about behavior.** The spec might correctly describe a broken component. The validator won't know.
* **Design quality.** Whether the chosen semantic tokens represent good design decisions is out of scope.
* **ARIA sufficiency.** The validator confirms that `required_aria` is present and non-empty. It doesn't evaluate whether the listed attributes are sufficient for the component's accessibility needs.
* **State coverage.** The validator confirms that `interaction_states` is present. It doesn't check whether the listed states cover real user needs or edge cases.

That evaluation is human work. The 15 rules above keep the spec internally consistent and structurally sound — so that when a human or agent reads it, what they find is accurate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.