feat(#907): bounded per-cycle edit budget for skill edits (SkillOpt) (#918)

SkillOpt (arXiv:2605.23904) treats a skill's system-prompt text as an
optimized parameter and argues unbounded full-rewrites are unstable,
proposing an "edit budget" to bound add/delete/replace changes per cycle.

Extends scripts/evolution_skill_lint.py (not a new script) with a second,
independent gate alongside the existing dead-script-wiring check:

- check_skill_edit_budget / find_edit_budget_violations: pure functions
  that flag a skills/**/SKILL.md edit when changed lines exceed a
  proportional churn ratio (default 50% of the file's pre-edit line
  count), exempting brand-new skills and tiny files (< 20 lines) where
  the ratio isn't meaningful.
- lint_skill_edit_budget + git IO helpers: diffs the working tree against
  the merge-base with a ref (default origin/main), mirroring the exact
  git convention already documented in evolution-implementation's
  landability-gate step (git diff against `git merge-base HEAD origin/main`,
  not `base...HEAD`, so uncommitted work is included).
- New CLI mode: `python scripts/evolution_skill_lint.py --skill-edit-budget
  [--base <ref>]`. The existing no-flag static lint (lint_repo) is
  unchanged and still runs by default.

Wires the gate into the documented pipeline: evolution-implementation's
SKILL.md gets a new Step 2b, between lint/format and the landability gate,
telling the agent to run the new flag whenever a PR touches a SKILL.md.

Tests: 11 new cases in tests/scripts/test_evolution_skill_integrity.py
(TestCheckSkillEditBudget, TestFindEditBudgetViolations) covering the
budget boundary, ratio/min-lines overrides, and malformed-input safety.
Only the pure functions are unit-tested; the git-diff IO boundary is
exercised manually (matches this file's/evolution_merge_gate.py's existing
pure-function-only test convention).

Out of scope (larger SkillOpt proposal, needs an LLM eval harness):
held-out validation sets, a rejection buffer, cross-model validation.

Closes #907

Author: Lexus2016

scripts/evolution_skill_lint.py

@@ -23,11 +23,27 @@
 ``scripts/evolution_watchdog.sh`` named in #101's warning is correctly ignored).
 
 Pure functions + explicit IO boundary so it is import-safe and unit-testable.
+
+Part 2 — bounded skill edits (#907, SkillOpt)
+----------------------------------------------
+SkillOpt (arXiv:2605.23904) treats a skill's system-prompt text as an optimized
+parameter and argues for an "edit budget": bounded add/delete/replace changes per
+cycle instead of unstable full rewrites. This adds that ONE deterministic,
+CI-testable piece of the proposal — a per-cycle churn cap on ``skills/**/SKILL.md``
+— without the rest of SkillOpt (held-out validation sets, a rejection buffer,
+cross-model validation), which need an LLM-driven eval harness and are out of
+scope for a mechanical gate. ``check_skill_edit_budget`` / ``find_edit_budget_violations``
+are the pure core (unit-tested with synthetic diff stats); ``lint_skill_edit_budget``
+is the git-diff IO boundary, run via ``--skill-edit-budget`` (not part of the
+default ``lint_repo()`` static check, since it is inherently relative to a base
+ref — see ``main()``).
 """
 
 from __future__ import annotations
 
+import os
 import re
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -51,6 +67,72 @@ def skill_ref_to_name(skill_ref: str) -> str:
     return skill_ref.replace("/", "-")
 
 
+# ── Bounded skill edits (#907 — SkillOpt) ──────────────────────────────────────
+# "Edit budget": cap the FRACTION of a skill's pre-change lines a single cycle
+# may touch (added + removed), not an absolute line count — a 20-line and a
+# 2000-line skill are held to the same proportional standard. Below
+# MIN_SKILL_LINES_FOR_BUDGET the ratio is not meaningful (a brand-new skill, or
+# one tiny enough that its first real edit always looks like ~100% churn), so
+# such files are exempt — this is a "no wholesale rewrite" check, not a
+# "no big skill" check. Overridable via EVOLUTION_SKILL_EDIT_BUDGET_RATIO for
+# the same reason DEFAULT_MAX_LINES in evolution_merge_gate.py is
+# env-overridable via EVOLUTION_MERGE_MAX_LINES.
+DEFAULT_EDIT_BUDGET_RATIO = 0.5
+MIN_SKILL_LINES_FOR_BUDGET = 20
+
+
+def check_skill_edit_budget(
+    path: str,
+    before_lines: int,
+    added: int,
+    removed: int,
+    ratio: float = DEFAULT_EDIT_BUDGET_RATIO,
+    min_lines: int = MIN_SKILL_LINES_FOR_BUDGET,
+) -> Optional[Dict[str, str]]:
+    """Pure check for one changed ``SKILL.md``. ``before_lines`` is the file's
+    line count at the base ref; ``added``/``removed`` are the diff's numstat
+    counts. A brand-new file has ``before_lines == 0`` and is exempt (creation
+    is not a "rewrite"); so is any existing skill under ``min_lines`` (the
+    ratio isn't meaningful yet). Returns a violation dict, or ``None`` if the
+    edit is within budget."""
+    if before_lines < min_lines:
+        return None
+    frac = (added + removed) / before_lines
+    if frac <= ratio:
+        return None
+    return {
+        "path": path,
+        "kind": "edit_budget_exceeded",
+        "detail": (
+            f"{added + removed} changed lines ({frac:.0%}) of a {before_lines}-line "
+            f"skill exceed the {ratio:.0%} per-cycle edit budget — split into "
+            f"smaller incremental edits instead of a wholesale rewrite"
+        ),
+    }
+
+
+def find_edit_budget_violations(
+    diffs: List[Dict[str, Any]],
+    ratio: float = DEFAULT_EDIT_BUDGET_RATIO,
+    min_lines: int = MIN_SKILL_LINES_FOR_BUDGET,
+) -> List[Dict[str, str]]:
+    """Pure core, mirrors ``find_violations``. ``diffs`` = [{path, before_lines,
+    added, removed}, ...] for changed ``skills/**/SKILL.md`` files. No git IO."""
+    out: List[Dict[str, str]] = []
+    for d in diffs:
+        v = check_skill_edit_budget(
+            path=str(d.get("path") or ""),
+            before_lines=int(d.get("before_lines") or 0),
+            added=int(d.get("added") or 0),
+            removed=int(d.get("removed") or 0),
+            ratio=ratio,
+            min_lines=min_lines,
+        )
+        if v:
+            out.append(v)
+    return out
+
+
 def find_violations(
     stages: List[Dict[str, Any]],
     skill_texts: Dict[str, str],
@@ -144,7 +226,115 @@ def lint_repo(repo_root: Optional[Path] = None) -> List[Dict[str, str]]:
     return find_violations(stages, skill_texts, existing)
 
 
+def _git_show_line_count(repo_root: Path, ref: str, path: str) -> int:
+    """Line count of ``path`` at ``ref``, or 0 if it doesn't exist there (a
+    brand-new file) or git fails for any reason. Never raises."""
+    try:
+        proc = subprocess.run(
+            ["git", "show", f"{ref}:{path}"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return 0
+    if proc.returncode != 0:
+        return 0
+    return len(proc.stdout.splitlines())
+
+
+def _git_merge_base(repo_root: Path, base_ref: str) -> Optional[str]:
+    """``git merge-base HEAD base_ref``, or ``None`` if it can't be resolved."""
+    try:
+        proc = subprocess.run(
+            ["git", "merge-base", "HEAD", base_ref],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def _git_skill_md_diffs(repo_root: Path, base_ref: str) -> List[Dict[str, Any]]:
+    """Real git IO: numstat for changed ``skills/**/SKILL.md`` files vs the
+    merge-base of ``HEAD`` and ``base_ref``, plus each file's pre-change line
+    count. Diffed against the WORKING TREE (not just HEAD) so this can run
+    pre-commit — same convention as the evolution-implementation skill's
+    Step 3 landability gate (``git diff --shortstat "$(git merge-base HEAD
+    origin/main)"``). Best-effort — any git failure yields an empty list (a
+    broken/shallow checkout must never crash the gate, only skip it)."""
+    merge_base = _git_merge_base(repo_root, base_ref) or base_ref
+    try:
+        proc = subprocess.run(
+            ["git", "diff", "--numstat", merge_base, "--", "skills/**/SKILL.md"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if proc.returncode != 0:
+        return []
+    out: List[Dict[str, Any]] = []
+    for line in proc.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        added_s, removed_s, path = parts
+        if added_s == "-" or removed_s == "-":
+            continue  # binary — not applicable to a SKILL.md, skip defensively
+        try:
+            added, removed = int(added_s), int(removed_s)
+        except ValueError:
+            continue
+        out.append(
+            {
+                "path": path,
+                "added": added,
+                "removed": removed,
+                "before_lines": _git_show_line_count(repo_root, merge_base, path),
+            }
+        )
+    return out
+
+
+def lint_skill_edit_budget(
+    repo_root: Optional[Path] = None, base_ref: str = "origin/main"
+) -> List[Dict[str, str]]:
+    """Lint the real repo's pending diff: does any changed ``SKILL.md`` blow its
+    per-cycle edit budget vs ``base_ref``? Meant to run pre-PR in the
+    evolution-implementation stage (see skills/evolution/evolution-implementation),
+    mirroring how ``evolution_merge_gate.py``'s diff cap is checked locally
+    before committing."""
+    root = Path(repo_root) if repo_root else Path(__file__).resolve().parents[1]
+    try:
+        ratio = float(os.environ.get("EVOLUTION_SKILL_EDIT_BUDGET_RATIO", DEFAULT_EDIT_BUDGET_RATIO))
+    except ValueError:
+        ratio = DEFAULT_EDIT_BUDGET_RATIO
+    diffs = _git_skill_md_diffs(root, base_ref)
+    return find_edit_budget_violations(diffs, ratio=ratio)
+
+
 def main(argv: List[str]) -> int:
+    args = argv[1:]
+    if "--skill-edit-budget" in args:
+        base_ref = args[args.index("--base") + 1] if "--base" in args else "origin/main"
+        violations = lint_skill_edit_budget(base_ref=base_ref)
+        if not violations:
+            print("[evolution-skill-lint] OK — no skill exceeds its per-cycle edit budget")
+            return 0
+        print(f"[evolution-skill-lint] {len(violations)} edit-budget violation(s):", file=sys.stderr)
+        for v in violations:
+            print(f"  - [{v['kind']}] {v['path']}: {v['detail']}", file=sys.stderr)
+        return 1
+
     violations = lint_repo()
     if not violations:
         print("[evolution-skill-lint] OK — no dead skill→script wiring")

skills/evolution/evolution-implementation/SKILL.md

@@ -223,6 +223,22 @@ python -m pytest tests/ -x -q
   ```
 - Only when local checks are green do you continue to commit + push + PR.
 
+**Step 2b: If the PR touches any `skills/**/SKILL.md` — bounded skill edits
+(#907, SkillOpt).** SkillOpt treats a skill's text as an optimized parameter
+and argues unbounded full-rewrites are unstable; `evolution_skill_lint.py`
+enforces a per-cycle edit budget (default 50% of the skill's line count
+changed) so a skill is nudged incrementally, not rewritten wholesale:
+
+```bash
+python scripts/evolution_skill_lint.py --skill-edit-budget
+```
+
+- **Clean** → proceed to Step 3.
+- **Violation** → split the change into a smaller increment that stays inside
+  the budget, or (if the file genuinely needs a full rewrite this cycle)
+  document why in the PR body and accept it will need human review — do not
+  bump `EVOLUTION_SKILL_EDIT_BUDGET_RATIO` just to silence the gate.
+
 **Step 3: Landability gate — fit the autonomous self-merge cap.** Integration
 merges unattended ONLY when the PR's total changed lines (additions +
 deletions, summed over ALL files — tests and docs count) is ≤ 200

tests/scripts/test_evolution_skill_integrity.py

@@ -4,6 +4,12 @@
 stage to run a script that doesn't exist, or a command in a stage without the
 `terminal` toolset, CI fails — turning the lesson of #101/#188 from "the agent
 should notice" into "merge is blocked".
+
+``TestCheckSkillEditBudget`` / ``TestFindEditBudgetViolations`` cover the #907
+(SkillOpt) bounded-edit gate: the pure per-cycle churn-ratio check, exercised
+with synthetic diff stats (the git-diff IO boundary is untested here by design
+— same convention as ``evolution_merge_gate.py``'s atomic-merge IO, which is
+"exercised only via the pure policy" in its own test file).
 """
 
 import sys
@@ -12,7 +18,9 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "scripts"))
 
 from evolution_skill_lint import (  # noqa: E402
+    check_skill_edit_budget,
     extract_run_commands,
+    find_edit_budget_violations,
     find_violations,
     lint_repo,
     skill_ref_to_name,
@@ -92,3 +100,65 @@ def test_missing_skill_md_flagged(self):
 def test_skill_ref_to_name():
     assert skill_ref_to_name("evolution/research") == "evolution-research"
     assert skill_ref_to_name("evolution/upstream-sync") == "evolution-upstream-sync"
+
+
+class TestCheckSkillEditBudget:
+    """#907 (SkillOpt) — the per-cycle churn-ratio cap on one SKILL.md."""
+
+    def test_small_edit_within_budget_is_clean(self):
+        # 20 changed lines of 100 = 20%, well under the 50% default budget.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 100, 10, 10) is None
+
+    def test_edit_exceeding_budget_is_flagged(self):
+        v = check_skill_edit_budget("skills/x/SKILL.md", 100, 40, 20)  # 60%
+        assert v is not None
+        assert v["kind"] == "edit_budget_exceeded"
+        assert v["path"] == "skills/x/SKILL.md"
+        assert "60%" in v["detail"]
+
+    def test_edit_at_exact_ratio_is_ok(self):
+        # Exactly at the cap (50/100 = 50%) — inclusive, not a violation.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 100, 50, 0) is None
+
+    def test_edit_just_over_ratio_is_flagged(self):
+        v = check_skill_edit_budget("skills/x/SKILL.md", 100, 51, 0)
+        assert v is not None and v["kind"] == "edit_budget_exceeded"
+
+    def test_brand_new_skill_is_exempt(self):
+        # before_lines == 0 -> creation, not a rewrite.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 0, 500, 0) is None
+
+    def test_tiny_existing_skill_is_exempt(self):
+        # Below MIN_SKILL_LINES_FOR_BUDGET (20) the ratio isn't meaningful yet.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 10, 10, 0) is None
+
+    def test_custom_ratio_override(self):
+        # 30% churn passes the 50% default but fails a stricter 20% budget.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 100, 30, 0) is None
+        v = check_skill_edit_budget("skills/x/SKILL.md", 100, 30, 0, ratio=0.2)
+        assert v is not None
+
+    def test_custom_min_lines_override(self):
+        # A 15-line skill is exempt by default (< 20) but covered once the
+        # floor is lowered.
+        assert check_skill_edit_budget("skills/x/SKILL.md", 15, 15, 0) is None
+        v = check_skill_edit_budget("skills/x/SKILL.md", 15, 15, 0, min_lines=10)
+        assert v is not None
+
+
+class TestFindEditBudgetViolations:
+    def test_mixed_diffs_only_flags_the_oversized_one(self):
+        diffs = [
+            {"path": "skills/a/SKILL.md", "before_lines": 100, "added": 10, "removed": 5},
+            {"path": "skills/b/SKILL.md", "before_lines": 100, "added": 60, "removed": 10},
+        ]
+        v = find_edit_budget_violations(diffs)
+        assert [x["path"] for x in v] == ["skills/b/SKILL.md"]
+
+    def test_no_diffs_is_clean(self):
+        assert find_edit_budget_violations([]) == []
+
+    def test_missing_keys_default_safely(self):
+        # A malformed entry (missing counts) defaults to 0 everywhere rather
+        # than raising — before_lines=0 makes it exempt (looks "new").
+        assert find_edit_budget_violations([{"path": "skills/x/SKILL.md"}]) == []