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

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. The Run struct includes a dedicated field that captures exactly where the intent originated:

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:

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 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:

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. 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 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 conditionally adds enforcement language to the reviewer LLM's instructions:

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:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}