> ## 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.

# agentic-spec CLI Troubleshooting: Fix Validation Failures

> Common agentic-spec CLI errors, validation failures, and how to fix them — from missing-token-entry to lying-check to ai-ready-gate.

Most validation failures follow predictable patterns. The rule name in the error output tells you exactly which contract constraint was violated. Look it up below, read the fix, and re-run `validate` to confirm.

## Common errors

> [accordion] missing-token-entry — token in contract has no tokens.json entry
>
> **What it means:**
> Your spec's `token_contract` field lists a token name that does not appear in `tokens.json`. The contract points at nothing.
>
> **Example output:**
>
> ```text theme={null}
> 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)
> ```
>
> **How to fix it:**
>
> Option A — Add the missing token to `tokens.json`:
>
> ```json theme={null}
> {
>   "component": "button",
>   "tokens": [
>     {
>       "name": "button.bg.invalid",
>       "tier": "component",
>       "path": "packages/tokens/src/components/button.json",
>       "role": "Background for invalid state"
>     }
>   ]
> }
> ```
>
> Option B — Remove the token name from `token_contract` in the spec frontmatter if you added it by mistake.
>
> Re-run `agentic-spec validate specs/button` after either change.

> [accordion] orphan-token-entry — tokens.json entry not referenced by token\_contract
>
> **What it means:**
> An entry exists in `tokens.json` but its name does not appear in `token_contract`. The entry is dangling — the spec does not claim to use it.
>
> **Example output:**
>
> ```text theme={null}
> PASS button (specs/button)
>   warn  orphan-token-entry     tokens.json entry "button.legacy" is not referenced by token_contract
> ```
>
> This is a warning, not an error. It does not fail the build on its own, but it does block `AI-Ready` promotion because a component with orphaned tokens cannot have `checks.tokens_valid: true`.
>
> **How to fix it:**
>
> Option A — Add `button.legacy` to `token_contract` in the spec frontmatter if the component genuinely uses it.
>
> Option B — Remove the entry from `tokens.json` if it is stale.

> [accordion] lying-check — tokens\_valid: true but validator disagrees
>
> **What it means:**
> The spec's `checks.tokens_valid` is set to `true`, but the validator found errors in the token contract. The spec is misrepresenting its own gate state.
>
> **Example output:**
>
> ```text theme={null}
> FAIL button (specs/button)
>   error lying-check            checks.tokens_valid is true but token validation found 2 errors
> ```
>
> **How to fix it:**
>
> 1. Fix the underlying token errors first (likely `missing-token-entry` or `orphan-token-entry`).
> 2. Re-run `agentic-spec validate specs/button`.
> 3. Only set `checks.tokens_valid: true` in the frontmatter after the validator confirms there are zero token errors.
>
> Never set a `checks:` gate to `true` manually unless the validator agrees. The validator is what `AI-Ready` status means.

> [accordion] ai-ready-gate — status is AI-Ready but a check is false
>
> **What it means:**
> The spec has `status: AI-Ready`, but at least one of the five `checks:` fields is `false`. `AI-Ready` requires all five to be `true`.
>
> **Example output:**
>
> ```text theme={null}
> FAIL modal (specs/modal)
>   error ai-ready-gate          status is AI-Ready but checks.states_complete is false
> ```
>
> **How to fix it:**
>
> Option A — Fix the failing gate. If `states_complete: false`, add the missing Storybook stories, verify they cover every state in `interaction_states`, then set `checks.states_complete: true`.
>
> Option B — If the component is genuinely not ready, drop `status` to `In progress` until all gates pass.
>
> The five gates are: `aria_correct`, `structure_correct`, `states_complete`, `tokens_valid`, `no_invented_styles`. All five must be `true` before you set `status: AI-Ready`.

> [accordion] identity-mismatch — component field differs between index.md and tokens.json
>
> **What it means:**
> The `component:` field in `index.md` does not match the `component:` field in `tokens.json`. The two files are wired to different components.
>
> **Example output:**
>
> ```text theme={null}
> FAIL button (specs/button)
>   error identity-mismatch      index.md has component "button" but tokens.json has component "btn"
> ```
>
> **How to fix it:**
>
> Make the `component:` field identical in both files. Use kebab-case and match the directory name. If you copied a spec from another component to bootstrap a new one, the `component:` field in `tokens.json` is the most common place to forget the update.

> [accordion] bad-token-tier — component token referencing a primitive
>
> **What it means:**
> A `tokens.json` entry has `"tier": "primitive"` or `"tier": "semantic"` when it should be `"tier": "component"`. Component specs must only list component-tier tokens. Referencing a primitive directly from a component token file violates the cascade rule.
>
> **Example output:**
>
> ```text theme={null}
> FAIL button (specs/button)
>   error bad-token-tier         tokens.json entry "button.bg.default" has tier "primitive" — component specs must use component-tier tokens only
> ```
>
> **How to fix it:**
>
> 1. Change the `tier` field for the entry to `"component"`.
> 2. Check that the token's `path` points to `packages/tokens/src/components/<name>.json`, not to `primitives.json`.
> 3. Check that the token in the JSON file references a semantic token (`{action.primary}`), not a primitive value directly (`{color.blue.6}`).
>
> If no suitable semantic token exists, add one to `semantic-light.json` and `semantic-dark.json` first, then reference it from the component token.

## General advice

* **Always run `validate` after adding tokens.** Add the entry to `tokens.json`, add the name to `token_contract`, then validate. Doing both edits in one pass and validating at the end catches errors from either side.

* **Use `--json` output for scripting.** If you are building a pre-commit hook or an agent workflow that checks spec state, parse the JSON rather than scraping the human-readable output. The JSON schema is stable.

* **Spec status should always reflect actual gate state.** Set `status: Draft` while you are building. Set `status: In progress` when the implementation exists but gates are not all passing. Set `status: AI-Ready` only after `agentic-spec validate` returns zero errors and all `checks:` are `true`. A spec that lies about its own status corrupts every agent and every human that reads it.


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