scope-freeze git:20261008.67190abA

Immutable. This exact content never changes and is served at /api/v1/blob/5496ec55cb0f2df4.

---
name: scope-freeze
description: Explicitly limit blast radius before any implementation or file changes.
---

# 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:

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

13. 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:**

```text
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](../../docs/scope-gate.md) 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.