Scope Freeze

Purpose

Prevent uncontrolled changes by defining a narrow, enforceable boundary. This freezes write scope, not discovery.

When to use

Immediately before editing files or running state-changing commands.

Inputs

• SPEC.md / PLAN.md / TODO.md
• Selected task
• Current repo state
• Git base used to judge the implementation diff
• Optional SPEC implementation diff budget

Workflow

1. Name the exact task.
2. List allowed files/folders as exact paths, directory prefixes, or globs.
3. Do not use repo-wide catch-all patterns (*, **, **/*) in Allowed writes. If the task genuinely spans multiple areas, enumerate the narrowest relevant prefixes and set a changed-file budget.
4. List read-only files/folders.
5. List forbidden paths and operations.
6. Set max files changed and rename/deletion rules when helpful. If SPEC.md has an enforced implementation diff budget, keep the scope's hard file cap at or below that accepted file budget unless scope is renegotiated before implementation.
7. List allowed commands.
8. List compatibility seams and test-integrity triggers before editing.
9. Define clear stop condition.
10. Note that reads/searches are allowed unless explicitly forbidden.
11. Persist the canonical block as SCOPE.md before the first implementation write when the route invokes scope-freeze and scripts/scope_gate.py is available.
12. After the implementation diff is complete, run:

    python scripts/scope_gate.py --base <frozen-base>

1. Treat scope-gate FAIL as a hard stop: revert the violating write or renegotiate scope before continuing. Treat REVIEW_REQUIRED as unresolved review, not implicit permission.

Do not widen SCOPE.md after an out-of-scope change merely to make the gate pass. A legitimate scope expansion must be surfaced and agreed before the newly allowed write.

The scope gate's Max files changed is a hard write-boundary rule and remains a FAIL when exceeded. An optional SPEC implementation diff budget is different: verify_gate.py treats file/added-line overruns as REVIEW_REQUIRED so a legitimate but unexpectedly large patch can be reconsidered rather than mislabeled as a functional failure.

Outputs

Canonical output block:

SCOPE FREEZE
Task: ...
Allowed writes: ...
Read-only: ...
Forbidden: ...

Compatibility seams to preserve:
- Public imports / APIs: ...
- CLI behavior: ...
- Output schema: ...
- Fixture/data meaning: ...
- Existing tests that must remain meaningful: ...

Test integrity:
- Existing tests may be added to: yes/no
- Existing tests may be changed only if: ...

Review required if:
- tests changed
- dependencies changed
- protected paths touched
- compatibility seams changed

Max files changed: ...
Renames allowed: yes/no
Deletions allowed: yes/no

Allowed commands: ...
Stop when: ...
Invalid if: ...

Use path/glob entries for the machine-enforceable portions of Allowed writes, Read-only, and Forbidden. Allowed writes must remain meaningfully narrower than the repository root; repo-wide catch-all globs are invalid scope-freeze output. Non-path forbidden operations remain part of the human contract but cannot be proven by a file-diff gate.

See Deterministic Scope Gate for status semantics and supported review triggers.

Success looks like

• The canonical block above exists before implementation writes.
• Allowed writes names a real blast-radius boundary rather than a repo-wide catch-all.
• The final live diff receives scope-gate PASS, or an explicit human resolves every REVIEW_REQUIRED trigger.
• No violating write is justified retroactively by silently widening the scope artifact.

Stop conditions

• Scope is narrow enough for safe implementation.
• Task requires changes outside boundary → pause and renegotiate before the write.
• Scope gate returns FAIL → stop, revert, or renegotiate.
• Scope gate returns REVIEW_REQUIRED → obtain the named review before claiming completion.

Anti-patterns

• Roaming the entire repo for a small fix.
• Using *, **, or **/* as Allowed writes and calling the result scoped.
• Expanding scope because "nearby code looked easy."
• Running write commands before boundary is agreed.
• Editing SCOPE.md after a violation to manufacture compliance.
• Treating an allowed path as proof that all behavior inside it is authorized.
• Forbidding necessary discovery reads.