Scope Guard Trigger

Detects and warns when files outside the declared specification scope are modified, preventing scope creep during implementation.

When to Use This Hook

Attach this hook when you need to:

• Enforce specification-driven development where each task has a declared file scope
• Detect when implementation drifts beyond the planned set of files to modify
• Create visibility into unplanned file changes that may introduce side effects

Consider alternatives when:

• Your development workflow is exploratory and does not use formal specifications
• You intentionally modify files across the codebase during refactoring tasks

Quick Start

Configuration

Copy
name: scope-guard-trigger
type: hook
trigger: Stop
category: quality-gates

Example Trigger

Copy
# Hook triggers when Claude completes a session or task
claude> /stop
# Scope guard checks modified files against .spec.md declaration

Example Output

Scope Guard: Checking file modifications against spec...
  Declared scope: 4 files
  Modified files: 6 files
  Out-of-scope modifications:
    WARNING: src/utils/helpers.ts (not in spec)
    WARNING: src/config/constants.ts (not in spec)
  Auto-excluded: 3 files (tests, config, docs)
Scope check complete: 2 warnings (non-blocking)

Core Concepts

Scope Detection Overview

Aspect	Details
Spec Source	Files to Create/Modify section in .spec.md
Comparison	Git-modified files vs declared file list
Auto-Exclusions	Test files, config files, docs, infrastructure
Severity	Warning only (non-blocking by default)
Trigger Point	Stop event - runs when Claude finishes

Scope Check Workflow

Session Ends (Stop)
       |
  Find .spec.md
   /         \
Missing      Found
  |            |
 Skip     Parse "Files to
          Create/Modify"
              |
         git diff --name-only
              |
         Compare Lists
              |
        ┌─────┴─────┐
        |           |
   All in Scope   Out-of-Scope
        |           |
     Silent      Warn per File
     Pass        (after exclusions)

Configuration

Parameter	Type	Default	Description
spec_file	string	".spec.md"	Specification file to read for declared scope
scope_section	string	"Files to Create/Modify"	Heading that contains the file list
auto_exclude	string[]	["test","config","docs","infra"]	File categories to exclude from scope checking
block_on_violation	boolean	false	Block completion when out-of-scope files detected
max_warnings	number	10	Maximum warnings to display before summarizing

Best Practices

1. Write Specs Before Implementing - The scope guard is only effective if specs are written before implementation begins. Adopt a spec-first workflow where every task starts with a .spec.md file.

2. Keep Auto-Exclusions Reasonable - Test files, configuration, and documentation are commonly modified as side effects. Keep them auto-excluded to reduce noise while still catching unexpected source changes.

3. Review Warnings, Don't Ignore Them - Out-of-scope modifications are not always wrong, but they deserve attention. Each warning is a prompt to ask whether the change was necessary or represents scope creep.

4. Update Specs When Scope Changes - If implementation reveals that additional files need modification, update the spec's file list rather than ignoring warnings. This keeps the spec accurate as a historical record.

5. Use with Pre-flight Plan Auditor - Combine scope guard with the plan auditor for a complete spec-driven workflow: audit the plan before starting, guard the scope during implementation.

Common Issues

1. Spec File Not Found - If no .spec.md exists in the project, the hook silently skips. Consider requiring a spec file for all non-trivial tasks and alerting when one is missing.

2. Glob Patterns in File Lists - Specs may list directories or glob patterns rather than specific files. The scope guard needs to expand these patterns before comparison.

3. Renamed Files Appear Out-of-Scope - If a file is renamed during implementation, git reports both the old and new path. The new path may not match the spec, triggering a false warning.