How No-Mistakes Tracks Intent Provenance and Checks Conformance During the Review Phase

No-Mistakes stores the origin of every run-time intent in the database and enforces strict conformance by injecting a mandatory clause into the review-agent prompt, flagging any contradiction as an ask-user finding.

The no-mistakes repository implements a rigorous pipeline that ensures automated changes never override human or agent-specified requirements. By recording who supplied an intent—its provenance—and validating that subsequent fixes respect that intent during the review phase, the system guarantees that automated remediation stays within guardrails. This article explains exactly how intent provenance is tracked in internal/db/run.go, how it flows through StepContext, and how the review step in internal/pipeline/steps/review.go checks for conformance.

Storing Intent Provenance in the Database

Intent provenance begins at the moment a run is created. The Run struct includes an IntentSource field that records the authoritative source of the intent, while constants in the database layer define the possible values.

In internal/db/run.go, the constant RunIntentSourceAgent marks an intent that originated from an LLM agent:

const (
    RunIntentSourceAgent = "agent"
    // Other sources such as CLI flags or API calls use distinct constants
)

type Run struct {
    ID           string
    IntentSource string // e.g., "agent"
    UserIntent   string // The actual intent text
    // ... other fields
}

When a pipeline starts, the executor populates this field. If an agent generated the intent, the value is set to RunIntentSourceAgent; if a user supplied it via a CLI flag, a different constant is used. This provenance record becomes immutable for the lifetime of the run, creating an audit trail that downstream steps can query.

Propagating Provenance Through StepContext

Once persisted, the provenance travels through the pipeline inside the StepContext struct. Every step—from analysis to review—receives this context, giving it read-only access to the intent’s origin.

The StepContext carries the IntentSource field, allowing the review step to distinguish between user-mandated requirements and suggestions. This propagation is critical because the review phase treats intents differently depending on their source. An intent marked as RunIntentSourceAgent triggers stricter conformance checks than a transient suggestion.

Enforcing Conformance with intentConformanceReviewClause

The core conformance logic resides in internal/pipeline/steps/review.go. Here, the review step assembles a multi-section prompt for the LLM reviewer. One of the final sections is the intent conformance clause, generated by the intentConformanceReviewClause function.

func (r *ReviewStep) Prompt(sctx *pipeline.StepContext) string {
    // 1. Execution context (file paths, repo state)
    executionCtx := executionContextPromptSection()
    
    // 2. Round history (previous attempts)
    history := roundHistoryPromptSection(sctx)
    
    // 3. The original user/agent intent
    userIntent := userIntentPromptSection(sctx)
    
    // 4. The conformance clause (enforced only for authoritative intents)
    conformance := intentConformanceReviewClause(sctx)
    
    return executionCtx + history + userIntent + conformance + pipelineDeliveryPhaseClause()
}

When sctx.IntentSource equals RunIntentSourceAgent, intentConformanceReviewClause appends a directive such as "Intent conformance (required)" to the prompt. This clause instructs the review agent to treat the original intent as a hard constraint. The LLM is explicitly directed to verify that any proposed fix does not contradict the required intent.

Detecting and Escalating Contradictions

If the review agent detects a contradiction between a proposed change and the required intent, the review step converts that finding into an ask-user action. Rather than allowing the pipeline to auto-apply a fix that violates the original provenance, the system parks the run and awaits human confirmation.

The logic (simplified from the source) inspects the agent’s output for conformance markers:

// Inside the review step execution
findings := parseAgentOutput(output)

for _, f := range findings {
    if f.Type == FindingTypeContradiction && sctx.IntentSource == RunIntentSourceAgent {
        // Escalate to user when authoritative intent is violated
        return StepResult{
            Action: ActionAskUser,
            Reason: "Intent contradiction detected against provenance " + sctx.IntentSource,
        }
    }
}

This mechanism ensures that intent provenance tracked and conformance checked during the review phase acts as a circuit breaker, preventing autonomous agents from drifting away from their original mandate.

Verifying Conformance in Unit Tests

The behavior is locked in by tests in internal/pipeline/steps/review_test.go. Two key test cases validate the provenance-to-conformance pipeline:

• TestReviewStep_ConformanceObligationTracksIntentProvenance: Asserts that when IntentSource is RunIntentSourceAgent, the generated prompt contains the substring "Intent conformance (required)". If the provenance is absent or different, the clause is omitted.
• TestReviewStep_RereviewFlagsIntentContradictionAsAskUser: Simulates an agent output that contradicts the required intent and verifies that the step returns an AskUser finding rather than AutoFix.

These tests confirm that the review phase correctly interprets the provenance stored in internal/db/run.go and enforces it via the prompt engineering in review.go.

Summary

• Provenance Storage: internal/db/run.go defines RunIntentSourceAgent and stores the intent source in the Run.IntentSource column, creating an immutable record of who supplied the requirement.
• Context Propagation: The StepContext struct carries IntentSource through every pipeline step, making provenance available at review time without additional database queries.
• Conformance Clause: intentConformanceReviewClause in internal/pipeline/steps/review.go injects a mandatory directive into the LLM prompt when the provenance indicates an authoritative agent intent.
• Contradiction Handling: The review step treats any violation of the required intent as an AskUser finding, parking the run rather than auto-applying a conflicting fix.
• Test Coverage: review_test.go guarantees that provenance drives the conformance clause and that contradictions are escalated to humans.

Frequently Asked Questions

How does No-Mistakes distinguish between user-provided and agent-generated intents?

The system uses the IntentSource field on the Run struct, defined in internal/db/run.go. Constants such as RunIntentSourceAgent mark LLM-generated intents, while other values represent CLI or API inputs. The review step checks this field to decide whether to append the strict conformance clause.

What happens if a proposed fix contradicts the original intent during review?

When the review agent detects a contradiction, the review step returns an AskUser action. According to internal/pipeline/steps/review.go, this parks the run and surfaces the conflict to a human operator rather than allowing the pipeline to proceed with an auto-fix that would violate the provenance-tracked intent.

Can the conformance clause be disabled for specific runs?

No. The intentConformanceReviewClause function automatically includes the directive whenever StepContext.IntentSource matches authoritative sources like RunIntentSourceAgent. This is a safety feature designed to prevent accidental override of requirements; disabling it would require changing the source code in internal/pipeline/steps/review.go.

Where is the intent provenance first recorded in the codebase?

Provenance is first persisted in internal/db/run.go when the Run record is created. The field is populated by the executor before the pipeline begins, ensuring that every subsequent step—including the review phase in internal/pipeline/steps/review.go—has access to the authoritative source of the intent.

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