Scope Contracts and Task Boundaries

Agents creep. The task is "fix the login bug." The diff touches the login route, the email helper, the database driver, the README, and the release script. Each touch had a plausible reason in the moment, but together they make a different change than the one that was reviewed.

Scope creep is easy to miss in agent work because the agent narrates each step in good faith. A stricter prompt doesn't fix that. A contract on disk that records what was promised, plus a check that compares the result against the promise, does.

A scope contract is a per-task file that records where the work begins, where it ends, and how to roll back if it spills. The agent reads it at task start. A verifier reads it at task end.

What goes in a scope contract

A contract without forbidden_files is incomplete. The negative space is half the contract.

Globs, not raw paths

Repos move files. Pin the contract to globs (app/**/*.py, tests/test_signup*.py) and a refactor between sessions won't invalidate it.

Rollback is part of scope

Writing down the rollback forces the author to think about what could go wrong. If you can't roll back from a contract, don't approve it.

Scope check is a diff check

The agent writes a diff. The checker takes that diff, the allowed globs, the forbidden globs, and the list of acceptance commands that ran. Every violation becomes a tagged finding that the verification gate can refuse.

Two altitudes of scope: the feature list and the task contract

The scope contract bounds one task, not the project. An agent can stay perfectly inside the contract for the login fix and still decide, on the next turn, that the project also needs a settings page, a dark mode toggle, and a rewrite of the router. The contract answers which files are in scope for the task. It says nothing about which work is in scope for the project.

That second altitude needs its own primitive: a feature_list.json the agent reads at session start. It's the project backlog as an ordered, machine-readable file. The agent picks exactly one feature whose status is todo, writes its id into the active scope contract, and may not start a second feature in the same session. "One feature at a time" stops being a line in the prompt that the agent can rationalize past. It becomes a value read off disk and a check the gate enforces.

{
  "project": "knowledge-base",
  "active": "import-pdf",
  "features": [
    { "id": "import-pdf",   "status": "in_progress", "goal": "import a PDF into the library",        "done_when": "pytest tests/test_import.py && a sample PDF appears in the library view" },
    { "id": "full-text-search", "status": "todo",     "goal": "search document text and rank hits",   "done_when": "query returns ranked results with snippets" },
    { "id": "cite-answers", "status": "todo",         "goal": "answers carry source citations",        "done_when": "every answer renders at least one clickable citation" }
  ]
}

Two rules keep the list load-bearing instead of decorative. First, "at most one in_progress" is itself a startup check (Phase 14 · 33). If the list shows two, the session refuses to start until a human resolves it. Second, the feature list is a file, not a chat message. Chat scrolls out of context, while the file persists across sessions and across agents. The handoff (Phase 14 · 40) writes the finished feature's status back to done, so the next session opens to an accurate board instead of re-deriving what's left.

The contract and the list compose by least privilege, using the same least-privilege merge that the production-patterns section spells out later: the task contract's allowed_files must sit inside whatever the active feature touches, never outside it.

code/main.py implements four pieces:

• A ScopeContract dataclass (glob lists for allowed, forbidden and soft docs paths, plus acceptance commands, rollback plan, approvals and the time, network and violation budgets) and a merge_contracts function for the least-privilege merge.
• A RunSummary dataclass holding the touched files, the commands run, the elapsed minutes and the network hosts. There is no diff parser; the demo builds both summaries by hand.
• A scope_check that compares a RunSummary against the contract and returns a ScopeReport: writes sorted into in-scope, off-scope, soft off-scope and forbidden, plus severity-tagged findings.
• Two demo runs: one stays in scope, one creeps. The checker flags the creep with the exact file and reason.

Run it:

python3 code/main.py

The output shows the contract, the two runs, the per-run verdicts, and the reports archived to closed/T-001.json (both runs share a task id, so the creep run overwrites the clean one).

One write-up (a single dev.to post) reports that a practitioner running "specsmaxxing" (scope contracts in YAML before invoking the agent) saw the rabbit-hole rate drop from 52% to 21% in three weeks without changing the agent. The post credits the contract, not the model. Four patterns make the gain stick.

Violation budgets, not binary failures. agent-guardrails (the OSS merge gate used by Claude Code, Cursor, Windsurf, Codex via MCP) ships a violationBudget per task. Minor scope slips within budget surface as warnings, and the merge gate refuses only once the budget is exceeded. Pair it with violationSeverity: "error" | "warning". The budget is the difference between a gate that ships and a gate that gets disabled by the team that hated it.

Severity asymmetry by path family. Off-scope writes to docs/** are usually warn. The demo goes one step softer: paths matching docs_paths_soft (docs/**, README.md, **/*.md) produce an info finding (scope.soft_off_scope), and any other off-scope write is a warn that counts against the budget. Writes to scripts/**, migrations/**, config/prod/** are always block, which in the demo means listing them in forbidden_files. That asymmetry belongs in the contract, not the runtime, because it's project-specific and changes per task.

Time and network budgets next to file budgets. A time_budget_minutes field bounds the wall clock, and the runtime refuses to continue past it without re-approval. A network_egress allowlist on hostnames stops the agent from quietly hitting an external API that wasn't part of the task. These are scope dimensions too. File globs are necessary but not sufficient.

Multi-contract merge semantics (least privilege). When two scope contracts apply (say, a project-wide one plus a task-specific one), the merge works like this:

• Intersect allowed_files: both contracts must permit the path.
• Union forbidden_files: either contract can prohibit it.
• time_budget_minutes takes the most restrictive value (min).
• approvals_required accumulates.
• network_egress is None for no enforcement, [] for deny-all, and [...] as an allowlist. Under merge, None defers to the other side, two lists intersect, and deny-all stays deny-all.

State this in the contract schema so the merge is mechanical and reviewable.

Three places this shows up in production:

• Claude Code slash commands. A /scope command writes the contract and pins it as session context. Subagents read the contract before acting.
• GitHub PRs. Push the contract as a JSON file in the PR body or as a checked-in artifact, and let CI run the scope checker against the merge diff.
• LangGraph interrupts. A scope violation triggers an interrupt. The handler asks the human whether the contract needs to grow or the agent needs to back off.

The contract travels with the task. When the task closes, archive it under outputs/scope/closed/.

outputs/skill-scope-contract.md generates a scope contract from a task description, along with a glob-aware checker that runs in CI on every agent diff.

1. Add a network_egress field listing allowed external hosts. Refuse runs that touch other hosts.
2. Extend the checker to fail soft on docs/** and hard on scripts/**. Justify the asymmetry.
3. Make the contract derive allowed_files from a goal field using a static rule set (no LLM). What goes wrong on the first edge case?
4. Add a time_budget_minutes and refuse to continue once the wall clock exceeds it.
5. Run two contracts against the same diff. What is the right merge semantics when both apply?

• LangGraph human-in-the-loop interrupts
• OpenAI Agents SDK tool approval policies
• logi-cmd/agent-guardrails, merge gates and scope validation: violation budgets, severity tiers
• Dev|Journal, Preventing AI Agent Configuration Drift with Agent Contract Testing: --strict mode without external deps
• Agentic Coding Is Not a Trap (production logs): specsmaxxing receipts, 52% → 21%
• OpenCode permission globs: fine-grained per-permission scope
• Knostic, AI Coding Agent Security: Threat Models and Protection Strategies: scope as part of least privilege
• Augment Code, AI Spec Template: three-tier boundary system (must/ask/never)
• Phase 14 · 27: prompt injection defenses that pair with scope locks
• Phase 14 · 33: the rule set this contract specializes per task
• Phase 14 · 38: the verification gate the checker reports into