scope

name	scope
description	Hard-block edits outside declared frozen directories via PreToolUse hook.
practices	["ddd-bounded-context","design-by-contract","mythical-man-month"]
hexagonal_role	driven-adapter
consumes	[]
produces	["filesystem-gate"]
context_rel	[{"kind":"supplier-to","with":"domain"}]
skill_api_version	1
context	{"window":"isolated","intent":{"mode":"none"},"sections":{"exclude":["HISTORY","INTEL","TASK"]},"intel_scope":"none"}
metadata	{"tier":"meta","dependencies":[]}
output_contract	stdout: scope status / lock state; stderr: blocked-edit reason from hook

/scope — Edit Scope Guard

Purpose: Declare which directories are in scope for the current work session. Edits outside the declared scope are hard-blocked by a PreToolUse hook.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

---

Quick Start

/scope freeze cli/cmd/ao/                   # Freeze a single directory
/scope freeze cli/cmd/ao/ skills/scope/     # Freeze multiple (additive)
/scope unfreeze cli/cmd/ao/                 # Remove one frozen directory
/scope unfreeze                             # Clear ALL frozen directories
/scope status                               # Show current lock state
/scope status --json                        # JSON output

---

Behavior Contract

When .agents/scope.lock declares one or more frozen_dirs:

• Any Edit, Write, or Bash tool call whose target path is outside every frozen directory is rejected by hooks/edit-scope-guard.sh with a structured stderr reason and a non-zero exit code (Claude Code converts that into a tool-use refusal).
• Edits to paths under any frozen directory are allowed.
• When the lock file is missing OR frozen_dirs is empty, the hook short-circuits with exit 0 (no enforcement; allow everything).
• The hook fails open on malformed JSON or missing target-path fields — do not block when the input contract is violated. Defensive default protects against harness changes.

The lock file is written via cli/internal/llmwiki/scope_guard.go:SafeAtomicWrite, so concurrent freeze / unfreeze calls converge atomically (last writer wins, never tears).

---

Subcommands

/scope freeze <dir>...

Append one or more directories to the frozen set. Idempotent; re-freezing an already-frozen directory is a no-op. Updates acquired_at (ISO-8601) and acquired_by (session id or PID) on every write.

/scope unfreeze [<dir>]

Without arguments, clears the entire frozen set. With one or more directory arguments, removes just those entries. Removing a directory that is not frozen is a no-op.