Scope drift detection

The plan said 4 files. The agent touched 6. /review catches it.

How it works

When you run /nano, it saves a list of planned files in the plan artifact under planned_files. Later, when/review runs, it compares that list against the actual files changed in git diff --name-only. Any file that appears in the diff but not in the plan gets flagged as drift.

# /nano saves this in .nanostack/plan/artifact.json
{
  "planned_files": [
    "src/routes/habits.ts",
    "src/routes/checkins.ts",
    "db/schema.sql",
    "db/migrate.sh"
  ]
}

# git diff --name-only shows:
src/routes/habits.ts
src/routes/checkins.ts
src/routes/streaks.ts    ← not in plan
src/lib/utils.ts         ← not in plan
db/schema.sql
db/migrate.sh

What the drift report looks like

{
  "drift_detected": true,
  "planned_count": 4,
  "actual_count": 6,
  "unplanned_files": [
    "src/routes/streaks.ts",
    "src/lib/utils.ts"
  ],
  "missing_files": [],
  "verdict": "informational"
}

The missing_files array catches the opposite problem: files the plan promised but that never got created.

Drift is informational, not punitive

In --quick and --standard modes, drift produces a warning. The review continues. The agent notes the unplanned files and checks them like any other changed file.

In --thorough mode, drift is blocking. The review pauses and asks you to confirm the extra files were intentional before continuing. This is useful for auth, payment, or infrastructure changes where unexpected file touches could signal a confused agent.

Common causes of drift

• The agent extracted a shared utility during implementation that it did not anticipate during planning. This is usually fine.
• A linter or formatter auto-modified files when the agent saved. Check your editor config if you see unexpected .prettierrc oreslint changes.
• The agent misunderstood scope and started working on a related feature. This is the drift you actually want to catch.
• Test files got created that were not in the plan. If your convention is to co-locate tests, consider listing test files explicitly in the plan.

Reducing false positives

If certain file patterns always drift (lock files, generated types, snapshots), add them to drift_ignore in your project config:

// .nanostack/config.json
{
  "drift_ignore": [
    "*.lock",
    "**/*.snap",
    "src/generated/**"
  ]
}

Ignored files still show up in the git diff, but they will not trigger a drift warning.