LLMtoMD logoLLMtoMD
All docs

How-to guides

Scope guard — keep agents on task

Record what an AI coding agent is allowed to change, then catch edits outside that boundary — checked against your stored spec.

When you give an AI coding agent a narrow task — "fix this one function" — it sometimes edits far outside that boundary because it thought it was being helpful. git diff shows you what changed, not what the agent was authorized to change.

Scope guard makes the boundary explicit. The agent records the approved scope before it edits; afterward you check the changed files against it and get a Review Packet showing exactly what landed outside the boundary — judged against your project's stored requirements. Nothing is auto-reverted: a human decides to approve the wider scope or roll it back.

Only file paths are ever sent to LLMtoMD — never your code.

The flow

  1. Record the boundary before editing (start_task): the files/globs the agent may touch, plus the project whose spec to check against.
  2. Check the diff after editing (check_scope): pass the changed files (e.g. git diff --name-only). Get the Review Packet.
  3. Decide: approve_scope to authorize the extra files, or revert them.
  4. Close the task when it's merged.

From your agent (MCP)

If LLMtoMD is connected as an MCP server, just talk to your agent:

Before you start, record a scope: only app/billing/credits.py and app/billing/utils/ for this task, in the "Billing service" project.

You're done — check your changes against the scope.

The agent calls start_task, then check_scope with the files it changed. If it strayed, the packet flags each out-of-scope file and whether the spec mentions that area. You can then say "approve src/auth/session.py" or "revert those and try again."

ToolPurpose
start_task(title, intent, allowed_paths, collection?)Record the approved boundary.
check_scope(task_id, changed_files, assess?)Check a diff → Review Packet. assess adds a one-line AI verdict per out-of-scope file.
approve_scope(task_id, paths)Widen the boundary.
close_task / list_tasksFinish / list scopes.

From the app (Scope guard page)

Open Scope guard in the app to drive it by hand: see your task scopes and their boundaries, paste a changed-file list (straight from git diff --name-only) to run a check, read the Review Packet inline, tick Assess with AI for per-file verdicts, and click Approve on any out-of-scope file to widen the boundary. Handy for reviewing what an agent did without an MCP connection.

At commit time (CLI)

Install the local hook so a commit is blocked when it includes files outside the approved boundary. It runs entirely on your machine and sends only file paths.

npm install -g @llmtomd/guard
export LLMTOMD_API_KEY=mic_...      # your connection key

llmtomd-guard init                  # install the pre-commit hook (once per repo)

llmtomd-guard start "Fix rounding" \
  --paths app/billing/credits.py,app/billing/utils/ \
  --collection "Billing service"

# …agent makes edits…
git commit -m "fix rounding"        # hook checks STAGED files, blocks on drift

llmtomd-guard approve app/auth/session.py   # if the extra change is fine
llmtomd-guard close

Run an advisory check any time with llmtomd-guard check (add --assess for AI verdicts). Set LLMTOMD_GUARD=warn to make the hook advisory instead of blocking.

The Review Packet

A check returns:

  • verdict — clean (everything inside the boundary) or review.
  • in_scope / out_of_scope — the classified files.
  • spec_hint — for each out-of-scope file, the most relevant excerpt from your stored spec (and a match score), so you can tell a likely-justified change from an unexplained one.
  • verdict (with assess) — a one-line AI judgement per out-of-scope file: likely justified (with the reason) or unexplained.

Related