⚙️ FEATURE: Plan-as-Contract — declare file scope before run, enforce after

[FernandoCelmer]

Problem

pycodeloop agents run free-form: no pre-declared scope, no post-run check that only intended files were touched. In long sessions the agent may edit files outside the intended scope without any warning.

Expected behavior

# Before run:
plan = await codeloop.plan("Refactor auth module")
# plan.files = ["src/auth.py", "tests/test_auth.py"]

# After run, if plan was active:
# ⚠️  Out-of-scope change detected: src/config.py was modified

Or via CLI:

pycodeloop run "Refactor auth" --plan-scope "src/auth.py,tests/"

Suggested implementation

• Add Plan dataclass: id, intent, files_in_scope: list[str], created_at
• Add plan_write(prompt) -> Plan method to CodeLoop (uses LLM to extract scope)
• Add PlanScopeSensor that runs git diff --name-only after session and checks against Plan.files_in_scope
• Store plans in .pycodeloop/plans/<id>.md
• Add plan_id: str | None to Config

References

• "Code as Agent Harness" — arXiv 2605.18747, Section 4.1 (State consistency)