# Illustrative design contract, not executable configuration for a product.
# Example budgets below must be justified and enforced by your orchestrator.
# Review this contract before adapting it to a repository.
version: 1
name: migrate-one-deprecated-attachment-validator
owner: "Set an accountable team or person before enabling"
enabled: false

goal:
  desired_property: "One eligible call site uses the supported validator"
  preserve: "Accepted uploads and documented error behaviour remain unchanged"
  out_of_scope:
    - "Product semantics or permission changes"
    - "Schema or production-data changes"
    - "Deleting or weakening acceptance checks"

trigger:
  kind: "scheduled or explicitly requested"
  cadence: "Choose according to review capacity, not a fixed best practice"
  duplicate_event_policy: "Reconcile existing work before starting another run"

concurrency:
  max_active_runs: 1
  lock_scope: "repository plus maintenance goal"
  lock_requirement: "Use an atomic claim with expiry and safe recovery"
  max_open_proposals: 1
  wait_when_review_pending: true

state:
  durable_store: "Configure a persistent run ledger; not just chat history"
  record:
    - "run identity and triggering event"
    - "work identity: repository, rule version and selected target"
    - "base revision and current workspace revision"
    - "harness version and model configuration"
    - "attempt count and consumed budget"
    - "external side effects and reconciliation status"
    - "checks, evidence references and terminal state"
  resume_rule: "Inspect current files and reconcile side effects before retrying"

selection:
  baseline: "Current default-branch revision"
  method: "Inspect one candidate and its relevant behaviour"
  skip_when:
    - "An active run or unresolved proposal already covers the work"
    - "No eligible candidate exists"
    - "The candidate requires an out-of-scope decision"
  prefer_deterministic_transform_when_sufficient: true

execution:
  workspace: "Isolated non-production environment with synthetic data"
  capabilities:
    - "Read the scoped repository"
    - "Edit the selected area on a work branch"
    - "Run approved verification commands"
    - "Create a review proposal using a restricted credential"
  prohibited:
    - "Production access"
    - "Merging the proposal"
    - "Changing this contract or its enforced budgets during a run"
  idempotency:
    stable_work_identity: true
    on_write_timeout: "Reconcile by work identity; do not blindly repeat writes"

verification:
  before_change:
    - "Confirm baseline environment and protected checks"
    - "Record existing failures separately"
  after_change:
    - "Verify the selected call site uses the supported validator"
    - "Run relevant behavioural and regression checks"
    - "Inspect diff for unintended semantics or scope changes"
  acceptance_checks:
    execution: "Run protected checks independently of the editing agent"
    modifications: "Require explicit review; green after weakening is not success"
  report:
    statuses: [PASS, FAIL, BLOCKED, NOT_RUN]
    evidence: "Actual command, environment, revision, exit status and full-log reference"

budgets:
  # Deliberately illustrative, not universal recommendations.
  max_attempts: 3
  max_elapsed_minutes: 20
  max_tool_calls: 60
  max_estimated_cost_usd: 2
  enforcement: "Outside the agent's editable prompt; include all child runs"
  cost_visibility_missing: "Do not start unattended execution"

stops:
  success: "READY_FOR_REVIEW: verified bounded proposal created"
  no_op: "NO_ELIGIBLE_WORK: current state needs no permitted change"
  wait: "REVIEW_PENDING: an earlier proposal remains unresolved"
  ask: "NEEDS_DECISION: ambiguous behaviour or changed requirements"
  blocked: "BLOCKED: unavailable evidence, environment or permission"
  exhausted: "BUDGET_EXHAUSTED: a limit reached"
  no_progress: "NO_PROGRESS: repeated failure without a justified new step"
  unsafe: "INVARIANT_VIOLATION: protected condition would be weakened"

output:
  proposal_contains:
    - "Reason, scope and stable work identity"
    - "Base revision and concise description of actual changes"
    - "Checks with evidence, including anything not run"
    - "Known limitations and reviewer decisions required"
  merge_policy: "A person reviews and approves under repository policy"

metrics:
  useful_outcomes:
    - "Accepted changes"
    - "Reviewer effort"
    - "Escaped defects and reversions"
    - "Duplicate proposals"
    - "Total model, infrastructure and review cost"
    - "No-op, blocked and stopped run reasons"
  not_success_by_itself:
    - "Generated lines of code"
    - "Number of agent turns"
    - "Opened pull requests"