# Better-than-found encountered-issue receipts

Agent docs index: /llms.txt

Wheelie agents should leave a system better than they found it when they encounter a concrete issue during scoped work. The contract is intentionally bounded: agents should not search for arbitrary improvements, invent polish tasks, or expand the work item when no concrete encountered issue exists.

Use `wheelie_better_than_found_receipt/v1` when a finding from agent work, validation, submit admission, or handoff needs a structured disposition.

## Receipt shape

The public schema is `/schemas/wheelie/better-than-found-receipt.schema.json`.

Every receipt records:

- `finding.finding`, `finding.check`, and `finding.target`: the exact finding, check, and target that produced the issue.
- `encounter.concreteIssueExists`: whether there was a real encountered issue.
- `scope.inCurrentScope` and `scope.rationale`: why the issue is or is not inside the current work item.
- `action.actionClass`: one of the action classes below.
- `action.actionTaken` or `action.proposedNextAction`: what happened or what should happen next.
- `evidenceRefs`: validation, work-item, change, checkpoint, handoff, policy, source, owner, or not-applicable refs.
- `noBusywork`: `concreteEncounterRequired=true` and `arbitraryImprovementSearchPerformed=false`.

## Action classes

| Action class | Use when | Required disposition |
| --- | --- | --- |
| `simple_fixable_fixed` | The issue is concrete, in scope, safe, and small enough to fix now. | Record the fix and validation evidence. |
| `followup_created` | The issue is concrete but independently ownable outside the current work item. | Record the follow-up work-item ref and handoff context. |
| `proposal_needed` | The issue is concrete but needs product, policy, or technical design choice before implementation. | Record the proposed next action and handoff/proposal ref. |
| `accepted_not_applicable` | No concrete encountered issue exists, or the encountered finding is explicitly not applicable to this run. | Record the no-op rationale and policy/evidence ref. |
| `blocked_requires_owner` | The issue is concrete but unsafe to resolve without an owner decision or unavailable authority. | Record the owner route and next unblock action. |

## No-busywork guardrail

A better-than-found receipt is not a license to search the repo for unrelated work. Agents should emit `accepted_not_applicable` when focused validation and the scoped task do not reveal a concrete issue. They should not create follow-ups for speculative cleanup, broad polish, or unrelated refactors.

## Advisory diagnostics as standard operating procedure

When Wheelie or a project language server labels touched-file diagnostics as
`advisory`, treat that as "not final authority," not "ignore." For files changed
in the current work item, an advisory diagnostic is a concrete encountered issue
when it is local and mechanical. Dispose of it through the same
`wheelie_better_than_found_receipt/v1` policy instead of a separate per-project
rule:

- fix it and rerun the touched-file diagnostic plus the owning validation lane;
- mark it stale/noisy only after a practical refresh or a stronger validator
  contradicts it;
- use a narrow waiver/suppression with rationale when the tradeoff is intentional;
- route a follow-up only when the issue is real, bounded, and outside the current
  chunk.

Gravity/Wheelie development and software developed with Wheelie use this shared
policy. Project overlays can tune budgets and evidence requirements, but should
not duplicate or weaken the rule.

If `encounter.concreteIssueExists=false`, the only valid action class is `accepted_not_applicable`, and `finding.finding` should be `no_concrete_encountered_issue`.

## Project policy profiles

The receipt is provider-neutral. Project profiles can require stricter evidence and smaller adjacent-fix budgets without changing the schema. For example, a stricter profile can require `validation` evidence for `simple_fixable_fixed`, `work_item` evidence for `followup_created`, and `owner` evidence for `blocked_requires_owner` while still accepting the same `wheelie_better_than_found_receipt/v1` shape.

Project policy is one shared Wheelie primitive, not repeated prompt prose. A repo or project profile can set these knobs:

- `adjacentFixBudget`: max files/lines and whether the issue must be in touched or adjacent code.
- `allowedLowRiskAutoFixes`: the specific mechanical classes agents may fix without owner routing.
- `complexIssueRouting`: the default action and required evidence for issues that are too complex or unsafe for local repair.
- `validationLanes`: lane-by-lane disposition, either `fix_immediately` or `classify_or_route`.

Generic Wheelie loops consume the same policy for agent checkpoints, validation handoff, submit admission, and handoff. Gravity/Continua can specialize by config only; it should not fork the agent behavior.

### No-busywork examples

| Encountered situation | Policy result |
| --- | --- |
| Touched TypeScript file has an unused import and the change stays within the adjacent-fix budget. | Fix immediately and emit `simple_fixable_fixed` with validation evidence. |
| Validation exposes a cross-surface runtime policy gap. | Do not opportunistically edit; classify or route with handoff/owner evidence. |
| Focused work and validation reveal no concrete issue. | Emit `accepted_not_applicable`; do not search for unrelated polish. |
| A healthy package could be made nicer if someone spent time on it. | No action; creating work solely for polish is busywork. |

## Example

```json
{
  "schemaVersion": "wheelie_better_than_found_receipt/v1",
  "receiptID": "btf.example.simple-fix",
  "generatedAt": "2026-06-01T12:00:00.000Z",
  "finding": {
    "finding": "touched_file_typescript_warning",
    "check": "typescript diagnostics for touched file",
    "target": "src/example.ts"
  },
  "encounter": {
    "concreteIssueExists": true,
    "sourceSurface": "validation"
  },
  "scope": {
    "inCurrentScope": true,
    "rationale": "The warning was in a file edited for the current change and was mechanically fixable."
  },
  "action": {
    "actionClass": "simple_fixable_fixed",
    "actionTaken": "Removed the unused variable and reran targeted validation.",
    "proposedNextAction": null
  },
  "evidenceRefs": [
    {
      "kind": "validation",
      "ref": "tap://validation/example-pass"
    }
  ],
  "noBusywork": {
    "concreteEncounterRequired": true,
    "arbitraryImprovementSearchPerformed": false
  }
}
```

## Policy profile example

```json
{
  "profileID": "wheelie.default",
  "policy": {
    "policyID": "wheelie.default.better_than_found.v1",
    "defaultSurfacePolicy": {
      "surface": "agent_checkpoint",
      "adjacentFixBudget": {
        "maxFiles": 2,
        "maxLinesChanged": 80,
        "requireTouchedOrAdjacent": true
      },
      "allowedLowRiskAutoFixes": [
        "formatting",
        "unused_import_or_variable",
        "touched_file_typecheck_diagnostic",
        "touched_doc_link_or_typo"
      ],
      "complexIssueRouting": {
        "defaultActionClass": "proposal_needed",
        "requiredEvidenceKinds": ["handoff"],
        "requireOwnerForBlocked": true
      },
      "validationLanes": [
        {
          "laneID": "touched_file_static_diagnostics",
          "disposition": "fix_immediately",
          "evidenceKinds": ["validation"]
        },
        {
          "laneID": "cross_surface_or_product_policy_gap",
          "disposition": "classify_or_route",
          "evidenceKinds": ["handoff", "owner"]
        }
      ]
    }
  }
}
```