scope-gate

name	scope-gate
description	When sub-agents keep straying outside the approved file list from the plan, close the gap with a PreToolUse hook that reads .qwen/task_scope.json — same pattern as rendering_naming_guard and todo_gate_guard
source	auto-skill
extracted_at	2026-06-16T01:00:00.000Z

Scope Gate — Mechanical enforcement of plan file-scope boundaries

QWEN.md: NEVER deviate from an agreed spec or plan without BOTH (1) verifying against code + spec, and (2) consulting the user. File-scope drift — touching files the plan didn't list — is the most common deviation vector.

Why this keeps failing without a hook

• A sub-agent encounters a "cleanup opportunity" and silently adds it
• The main chain accepts the sub-agent report without verifying scope
• No mechanical check exists at Write/Edit time
• Session boundaries erase the memory of what was approved

The hook pattern

Write a Python script in .qwen/local-scripts/ following the existing guard convention:

1. Trigger: Write or Edit to .rs/.wgsl files
2. Read scope: check .qwen/task_scope.json for the approved file list. Inert when the file doesn't exist.
3. Match: the target file path (stripped of project root) must equal or start with an approved path. Directory-level approval via trailing /.
4. Deny with message: if out of scope, block the write with the task name, the offending file, and the rule citation
5. Fail-open: if the scope file is missing or malformed, allow — never block on infrastructure error
6. Non-code files bypassed: only .rs/.wgsl are gated (same as todo-gate)

Scope file format

{
  "task": "Task 2: SceneCull shader + indirect draw buffer",
  "files": [
    "crates/titan-rendering-scene-cull/src/indirect.rs",
    "crates/titan-rendering-scene-cull/src/shaders/scene_cull.wgsl",
    "crates/titan-rendering-scene-cull/src/lib.rs"
  ]
}

Paths are relative to the project root. A trailing / approves all files within that directory.

Usage flow

1. Main chain writes .qwen/task_scope.json with the approved files before dispatching a task
2. Sub-agent (or main chain during task work) hits the hook on any out-of-scope Write/Edit
3. After the task completes, the scope file is removed or updated for the next task

When to apply

When sub-agents or the main chain repeatedly add refactors, cleanups, or "improvements" beyond the task scope without explicit approval. Write the hook, add tests, commit — the gap closes at the next Write/Edit.

Existing implementation

C:\Dev\Titan\.qwen\local-scripts\scope_guard.py — 8 tests, test_scope_guard.py. Qwen Code auto-discovers hooks in .qwen/local-scripts/.