refactor-loop.yaml

name: refactor-loop
version: 0.1.0
description: >
  Refactor a module without changing behaviour. The test suite is the gate,
  and the loop is forbidden from editing tests to make them pass.

# --------------------------------------------------------------------
# intent — what this loop is for
# --------------------------------------------------------------------
intent:

  background:
    - key: target_module
      value: src/
      note: Scope. Widening this without widening the tests is how a refactor loop goes wrong.
    - key: test_command
      value: cargo test --workspace
    - key: behaviour_rule
      value: Public API and observable behaviour do not change. If they must, that is a different task.

  prerequisites:
    - step: Ran the refactor by hand on one file and kept the diff
      done: false
      evidence: "link the diff here"
    - step: Confirmed the suite is green before the loop starts
      done: false
    - step: "Recorded the baseline: test count, coverage, clippy warning count"
      done: false

  goals:
    - name: simplify
      description: Reduce duplication and nesting in the target module without changing behaviour.
    - name: stay-green
      description: Keep the entire test suite passing at every step, not just at the end.
    - name: no-test-edits
      description: Achieve the above without weakening, deleting, or rewriting any test.

  success:
    - target: overall
      name: green-and-simpler
      mode: percentage
      statement: Every blocking validation passes.
      threshold: 1.0

# --------------------------------------------------------------------
# execution — how the work gets done
# --------------------------------------------------------------------
execution:

  graph:
    nodes:
      - id: survey
        role: researcher
        instruction: Map the target module. Report duplication, deep nesting, and long functions with file and line references. Do not change anything.
        goals: [simplify]
        tier: cheap
        weight: 1.0

      - id: refactor-a
        role: builder
        instruction: Apply behaviour-preserving simplifications to the first half of the surveyed findings. Run the suite before reporting.
        depends_on: [survey]
        goals: [simplify, stay-green]
        tier: standard
        weight: 3.0
        isolated: true

      - id: refactor-b
        role: builder
        instruction: Apply behaviour-preserving simplifications to the second half of the surveyed findings. Run the suite before reporting.
        depends_on: [survey]
        goals: [simplify, stay-green]
        tier: standard
        weight: 3.0
        isolated: true

      - id: review
        role: judge
        instruction: Check each change against the behaviour-preservation rule and the test-edit ban. Report per-change PASS or FAIL with the diff hunk as evidence.
        depends_on: [refactor-a, refactor-b]
        goals: [no-test-edits, simplify]
        tier: strong
        provider: openai
        weight: 1.0

    # Two builders sit in the same wave, so both are isolated. Auto concurrency
    # will pick 2 here — the widest wave — and stop, because a third worker has
    # nothing to do.
    concurrency:
      mode: auto
      cap: 16
      min_marginal_gain: 0.05

  providers:
    providers:
      - id: ollama
        kind: ollama
        tiers: [cheap]
        command: ollama
        args: ["run", "{model}"]
        model: qwen2.5-coder
        prompt_on_stdin: true
        timeout_seconds: 600

      - id: claude
        kind: claude_code
        tiers: [standard, strong]
        command: claude
        args: ["-p", "{prompt}"]
        timeout_seconds: 1800

      - id: openai
        kind: openai
        tiers: [strong]
        command: curl
        args:
          - "-sS"
          - "https://api.openai.com/v1/chat/completions"
          - "-H"
          - "Content-Type: application/json"
          - "-H"
          - "Authorization: Bearer $OPENAI_API_KEY"
          - "-d"
          - "@-"
        model: gpt-4o
        requires_env: [OPENAI_API_KEY]
        prompt_on_stdin: true
        timeout_seconds: 600

    cascade:
      cheap: [ollama, claude]
      standard: [claude]
      strong: [openai, claude]

    enforce_judge_independence: true

  skills:
    acquisition_order: [installed, generate]
    quarantine_dir: generated-skills
    min_marketplace_stars: 100
    require_human_promotion: true

  triggers:
    triggers:
      - type: cron
        expr: "0 2 * * *"
      - type: file_change
        path: src/

# --------------------------------------------------------------------
# safety — what must not happen, and when to stop
# --------------------------------------------------------------------
safety:

  checks:
    - target: stay-green
      name: suite-passes
      mode: objective
      statement: The full test suite exits clean.
      detector: { type: script, command: cargo, args: ["test", "--workspace"] }

    - target: no-test-edits
      name: tests-unchanged
      mode: objective
      statement: "No file under tests/ or any #[cfg(test)] block was modified."
      # The failure this exists to catch: a loop "fixing" a red test by
      # weakening the test rather than the code. Watching one run is how you
      # learn to add this; it is cheaper to start with it.
      detector: { type: script, command: scripts/assert-tests-untouched.sh }

    - target: simplify
      name: clippy-clean
      mode: objective
      statement: Clippy reports no warnings at the configured level.
      detector: { type: script, command: cargo, args: ["clippy", "--workspace", "--", "-D", "warnings"] }

    - target: simplify
      name: complexity-down
      mode: percentage
      statement: Measured complexity is at or below the baseline.
      detector: { type: threshold, metric: complexity_ratio, op: lte, value: 1.0 }

    - target: simplify
      name: readable
      mode: subjective
      statement: The refactor reads as clearer to a reviewer who did not write it.
      detector:
        type: judge
        standard: "the repository's own CONTRIBUTING guidance on naming and function length"
        min_score: 7.0
      blocking: false

    - target: overall
      name: builds-and-passes
      mode: objective
      statement: The workspace builds and the suite is green.
      detector: { type: script, command: cargo, args: ["test", "--workspace"] }

  gates:
    stop:
      max_iterations: 12
      max_revisions_per_node: 3
      max_wall_clock_seconds: 7200
      max_tokens: 4000000
      max_cost_usd: 10.0
      no_progress_iterations: 3
      stop_on_overall_success: true

  limits:
    global:
      rules:
        # The frozen rule set that made large parallel runs survivable.
        - Never git stash. Never git reset.
        - No git command except committing a specific file.
        - No slow commands before the test phase.
        - Never edit a test to make it pass. Fix the code or report that you cannot.
        - One behaviour-preserving change per commit.
      forbidden_paths: [".git/", "target/", "state/"]
      forbidden_commands: ["rm -rf", "git push", "git reset", "git stash"]
      max_seconds: 1200
      human_checkpoint:
        - pushing to a remote
        - changing a public API signature
        - deleting a file