# How No-Mistakes Tracks Intent Provenance and Validates Conformance: A Deep Dive

> Discover how No-Mistakes tracks intent provenance via Run.IntentSource and validates conformance using prompt clauses, ensuring accurate user intent and automatic escalation for contradictory changes.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-07-12

---

**No-Mistakes tracks intent provenance by storing the source of user intent in `Run.IntentSource` and validates conformance through the review step's prompt clause, automatically escalating contradictory fixes to `ask-user` status.**

The open-source repository `kunchenguid/no-mistakes` treats user intent as a first-class datum that persists through the entire pipeline. Understanding how it tracks intent provenance and validates conformance reveals a robust system where the origin of an intent—whether from an explicit command-line flag or inferred from context—determines how strictly downstream steps enforce compliance. This mechanism ensures that agent-provided instructions remain authoritative while allowing flexibility for inferred intents.

## How Intent Provenance Is Recorded in the Database

The foundation of provenance tracking lives in the database schema defined in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go). The `Run` struct includes a dedicated field that captures exactly where the intent originated:

```go
type Run struct {
    // …
    IntentSource    *string // provenance of the user intent
    // …
}

```

A specific constant marks authoritative sources. When intent is supplied explicitly via the driving agent (e.g., `axi run --intent`), the system stores the value `"agent"` using the constant defined in the same file:

```go
const RunIntentSourceAgent = "agent"

```

This nullable string field allows the system to distinguish between explicit user instructions, LLM-transcript inferred intents, and other automated generation methods.

## Propagating Intent Source Through the Pipeline

When a run starts, the executor in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go) reads the stored intent and its source, then injects them into the per-step context. The `pipeline.StepContext` carries the `IntentSource` field, making provenance available to every downstream step:

```go
ctx := pipeline.StepContext{
    UserIntent:    run.Intent,
    IntentSource:  *run.IntentSource, // "agent"
}

```

Steps query this provenance using the helper function `intentSourceIsAuthoritative` located in [`internal/pipeline/steps/intent_prompt.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/intent_prompt.go). This boolean check determines whether the pipeline should treat the intent as the definitive specification. When the source equals `db.RunIntentSourceAgent`, the system considers the intent authoritative and applies strict conformance rules.

The high-level design comment in [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go) explicitly states: *"IntentSource records the provenance of UserIntent so steps can weigh..."* This architectural decision ensures that each step can adjust its behavior based on how much trust to place in the incoming intent.

## Validating Conformance During the Review Step

The review step enforces conformance validation through prompt engineering and automated escalation logic. The helper function `intentConformanceReviewClause` in [`internal/pipeline/steps/intent_prompt.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/intent_prompt.go) conditionally adds enforcement language to the reviewer LLM's instructions:

```go
func intentConformanceReviewClause(sctx *pipeline.StepContext) string {
    if intentSourceIsAuthoritative(sctx) {
        return "The changes must not violate the intent you supplied."
    }
    return ""
}

```

When the intent source is authoritative, this clause appears in the review prompt, instructing the LLM that fixes must not violate the original intent. If the review step detects that a proposed fix contradicts the intent, the finding is automatically upgraded:

```go
if fixViolatesIntent {
    finding.Action = types.FindingActionAskUser
}

```

This upgrade to `ask-user` status causes the pipeline to pause and request human clarification, preventing silent deviations from the original specification. The system guarantees that any fix altering or discarding the intent undergoes explicit human review.

## Test Coverage for Intent Provenance

The codebase includes comprehensive tests that verify the provenance contract. In [`internal/pipeline/steps/review_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review_test.go), the test `TestReviewStep_ConformanceObligationTracksIntentProvenance` ensures the review step adds the conformance clause only when the intent source is `"agent"`.

Similarly, [`internal/pipeline/executor_intent_conformance_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor_intent_conformance_test.go) contains `TestExecutorIntentConformance`, which validates that a run with an agent-provided intent is correctly stored and propagated to the step context. These tests ensure that the provenance tracking and conformance validation remain intact across code changes.

## Summary

- **Intent provenance** is stored in the `Run.IntentSource` database field as a nullable string, with `"agent"` indicating authoritative sources.
- The executor propagates this provenance through `pipeline.StepContext`, making it available to all pipeline steps via the `IntentSource` field.
- The `intentSourceIsAuthoritative` helper determines whether strict conformance rules apply based on the source value.
- **Conformance validation** occurs in the review step through the `intentConformanceReviewClause` function, which adds enforcement language to LLM prompts only for authoritative intents.
- Contradictory fixes are automatically escalated to `ask-user` status, ensuring human review before any deviation from the original intent is applied.

## Frequently Asked Questions

### What qualifies as an "authoritative" intent source in No-Mistakes?

An authoritative intent source is any intent where `IntentSource` equals `"agent"` (the constant `db.RunIntentSourceAgent`). This typically occurs when a user explicitly provides intent via the command line using `axi run --intent`. Intents inferred from LLM transcripts or generated by other automated means receive different source values and are not treated as authoritative specifications.

### How does the review step prevent fixes from violating the original intent?

The review step uses the `intentConformanceReviewClause` helper to inject a specific constraint into the reviewer's prompt when the intent source is authoritative. This clause states that changes must not violate the supplied intent. If the review logic detects a contradiction between the proposed fix and the original intent, it automatically upgrades the finding to `ask-user` status, pausing the pipeline for human clarification.

### Where is the intent provenance stored and how is it accessed by pipeline steps?

The provenance is stored in the `IntentSource` field of the `Run` struct in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go). When the executor initializes a run, it reads this field and injects it into `pipeline.StepContext`. Downstream steps access this value through the context and use helpers like `intentSourceIsAuthoritative` in [`internal/pipeline/steps/intent_prompt.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/intent_prompt.go) to determine how to handle the intent.

### Can the conformance validation be bypassed for certain types of intents?

Yes, the conformance clause is only added to review prompts when `intentSourceIsAuthoritative` returns true. For non-authoritative sources (such as inferred intents without explicit user confirmation), the review step operates without the strict conformance constraint, allowing the system flexibility when the intent origin is uncertain or automated.