SCOPE ENFORCEMENT SYSTEM:

Scope Configuration:
.claude/sessions/{session-name}/scope.json
├── scope.core     # boolean - Core/app/scripts/migrations access
├── scope.theme    # string|false - Theme name or disabled
├── scope.plugins  # array|false - Plugin names or disabled
└── exceptions     # array - Override paths

Path Mapping:
scope.core = true  → core/**/* + app/**/* + scripts/**/* + migrations/**/*
scope.theme = "x"  → contents/themes/x/**/*
scope.plugins = [] → contents/plugins/{name}/**/*

Always Allowed:
.claude/sessions/**/*  # Session files always accessible

Validation Flow:
1. Read scope.json from session
2. Build allowed paths list
3. Check modified files against scope
4. If violation → BLOCK until resolved
5. If compliant → PROCEED

Integration Points:
├── code-reviewer (Layer 0 check)
├── /task:scope-change (scope modification)
├── product-manager (scope definition)
└── All development agents (scope respect)

{
  "$schema": "Session Scope Configuration",
  "definedBy": "product-manager",
  "date": "YYYY-MM-DD",
  "scope": {
    "core": false,
    "theme": "theme-name",
    "plugins": false
  },
  "exceptions": [],
  "confirmedBy": "user",
  "confirmedAt": "YYYY-MM-DD"
}

// scope.core = true
const corePaths = [
  'core/**/*',
  'app/**/*',
  'scripts/**/*',
  'migrations/**/*'
]

// scope.theme = "default"
const themePaths = [
  'contents/themes/default/**/*'
]

// scope.plugins = ["analytics", "payment"]
const pluginPaths = [
  'contents/plugins/analytics/**/*',
  'contents/plugins/payment/**/*'
]

// Always allowed
const alwaysAllowed = [
  '.claude/sessions/**/*'
]

{
  "scope": {
    "core": false,
    "theme": "default",
    "plugins": false
  },
  "exceptions": []
}

{
  "scope": {
    "core": true,
    "theme": false,
    "plugins": false
  },
  "exceptions": []
}

{
  "scope": {
    "core": true,
    "theme": "default",
    "plugins": false
  },
  "exceptions": []
}

{
  "scope": {
    "core": false,
    "theme": "plugin-sandbox",
    "plugins": ["my-plugin"]
  },
  "exceptions": []
}

{
  "scope": {
    "core": true,
    "theme": "default",
    "plugins": ["analytics", "payment"]
  },
  "exceptions": []
}

{
  "scope": {
    "core": false,
    "theme": "default",
    "plugins": ["ai", "social-media-publisher"]
  },
  "exceptions": []
}

function validateScope(
  modifiedFiles: string[],
  scopeConfig: ScopeConfig
): ValidationResult {
  // Build allowed paths
  const allowedPaths: string[] = ['.claude/sessions/**/*']

  if (scopeConfig.scope.core) {
    allowedPaths.push(
      'core/**/*',
      'app/**/*',
      'scripts/**/*',
      'migrations/**/*'
    )
  }

  if (scopeConfig.scope.theme) {
    allowedPaths.push(
      `contents/themes/${scopeConfig.scope.theme}/**/*`
    )
  }

  if (Array.isArray(scopeConfig.scope.plugins)) {
    scopeConfig.scope.plugins.forEach(plugin => {
      allowedPaths.push(`contents/plugins/${plugin}/**/*`)
    })
  }

  // Add exceptions
  allowedPaths.push(...(scopeConfig.exceptions || []))

  // Check each file
  const violations: string[] = []

  for (const file of modifiedFiles) {
    const isAllowed = allowedPaths.some(pattern =>
      matchGlob(file, pattern)
    )

    if (!isAllowed) {
      violations.push(file)
    }
  }

  return {
    valid: violations.length === 0,
    violations,
    allowedPaths
  }
}

// Layer 0: Session Scope Compliance (FIRST CHECK)

// 1. Read scope.json from session folder
const sessionPath = getSessionPathFromTaskContext()
const scopeConfig = JSON.parse(await Read(`${sessionPath}/scope.json`))

// 2. Build allowed paths
const allowedPaths = buildAllowedPaths(scopeConfig)

// 3. Check all modified files
const changedFiles = await getChangedFilesFromBranch()
const violations = []

for (const file of changedFiles) {
  const isAllowed = allowedPaths.some(pattern =>
    matchesGlob(file, pattern)
  )
  if (!isAllowed) {
    violations.push(file)
  }
}

// 4. If violations found, REJECT immediately
if (violations.length > 0) {
  console.log(`
🚨 SCOPE VIOLATION DETECTED 🚨

Session: ${sessionPath}
Scope Configuration:
- Core: ${scopeConfig.scope.core ? 'ALLOWED' : 'DENIED'}
- Theme: ${scopeConfig.scope.theme || 'NONE'}
- Plugins: ${JSON.stringify(scopeConfig.scope.plugins) || 'NONE'}

Files Outside Scope:
${violations.map(f => '- ' + f).join('\n')}

Required Action:
1. Revert modifications to files outside scope
2. OR request scope expansion via /task:scope-change
3. OR move logic to an allowed path

Review BLOCKED until scope violations are resolved.
  `)
  throw new Error('SCOPE_VIOLATION')
}

# Revert specific file
git checkout HEAD -- path/to/file

# Revert all out-of-scope changes
git checkout HEAD -- core/  # if core not allowed

/task:scope-change .claude/sessions/2025-12-30-my-feature-v1/

I need to also modify:
- core/lib/services/my-service.ts (new service)
- migrations/020_new_table.sql (database change)

Reason: The feature requires core service layer changes

// Instead of modifying core/lib/utils.ts
// Create theme-specific utility:
// contents/themes/default/lib/utils/my-utility.ts

1. Verify session has started development
2. Read ALL session files
3. Analyze scope change request vs progress
4. Identify rework implications
5. Ask user to confirm rework
6. Launch PM agent to update requirements
7. Launch Architect to update plan
8. Update progress.md with rework markers
9. Trigger code review if needed

/task:scope-change .claude/sessions/{session-name}/

Requested changes:
- Add core access for [reason]
- Add plugin "x" for [reason]

Impact analysis:
- Current progress: [phase X]
- Affected items: [list]

{
  "scope": {
    "core": false,
    "theme": "default",
    "plugins": false
  },
  "exceptions": [
    "core/lib/constants.ts",
    "app/api/v1/custom-endpoint/**/*"
  ]
}

# Validate files against session scope
python .claude/skills/scope-enforcement/scripts/validate-scope.py \
  --session ".claude/sessions/2025-12-30-feature-v1" \
  --files "core/lib/services/x.ts,contents/themes/default/lib/y.ts"

// NEVER: Modify scope.json directly
fs.writeFileSync('scope.json', newScope)  // Use /task:scope-change

// NEVER: Ignore scope violations
if (scopeViolation) {
  continue  // WRONG - Must resolve violations
}

// NEVER: Use exceptions for broad access
{
  "exceptions": ["core/**/*"]  // WRONG - Use scope.core = true
}

// NEVER: Modify files then check scope
await modifyFile('core/lib/x.ts')  // Check BEFORE modifying
validateScope()

// NEVER: Skip scope check in code-reviewer
// Layer 0 is MANDATORY and FIRST