# Configuration Scope Audit: Python Service

## Instruction Hierarchy

The root guide contains purpose, layout, canonical commands, security boundary,
and links. API, migration, and documentation guidance remain at path scope.

## Path Rule Fixtures

The API allow fixture `src/api/orders.py` loads contract and authorization
guidance. The deny fixture `docs/orders.md` does not. Migration fixtures prove
append-only guidance loads only under `migrations/**`.

## Skill and Command

The migration-review Skill packages reusable evidence gathering. The legacy
explicit ADR command remains compatible, but new multi-step procedures use a
Skill so supporting files load on demand. Neither grants authorization.

## Skill Package

`migration-review-skill/SKILL.md` defines a trigger description and a narrow
`allowed-tools` grant. It routes detailed evidence to
`references/review-checklist.md` and validates every argument with
`scripts/check_scope.py`. The grant pre-approves that bundled checker for the
invocation turn; it does not restrict all other tools or override deny rules.

## Subagent Contract

`/agents` registers a migration auditor with read-only tools, `maxTurns: 10`,
and `isolation: worktree` when edits are requested. Its response contains
`status`, `evidence`, `blockers`, and `next_step`. It stops at the turn box and
reports an obstacle instead of claiming success or widening scope.

## Plugin Distribution

Project Skills and agents are committed under `.claude/`. Shared plugin sources
and defaults live in `.claude/settings.json` through
`extraKnownMarketplaces` and `enabledPlugins`, with folder trust and review.
Organization managed settings restrict allowed marketplaces and non-negotiable
permissions. Versions and rollback are recorded before rollout.

## Hooks

A deterministic pre-write hook blocks paths outside declared scope. A post-edit
hook formats only changed files. A pre-command hook blocks secret printing and
destructive operations. A `PreToolUse` structured decision uses exit 0 with JSON;
an exit 2 hook writes its blocking reason to stderr and prints no JSON. A
`PermissionRequest` hook uses its own nested decision shape.

## Headless CI

CI starts from a fresh checkout with versioned project configuration, read-only
review tools, bounded runtime, structured findings, and separate deterministic
tests. It never inherits an interactive session. As verified 2026-08-09,
managed Code Review is a Team and Enterprise research preview; it reports
findings without replacing gates. Repository automation uses
`anthropics/claude-code-action@v1` with explicit workflow permissions and tools.

## Remediation

Stable finding IDs, original evidence, current diff, tests, and acceptance rules
are passed to the remediation review. Local preferences are excluded.