Protected files: Agent context package

Declares files and paths that AI coding agents and contributors must not modify without explicit approval, with enforcement hooks and escalation when a protected boundary is crossed.

Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.

Decision

Treat selected repository paths as change boundaries that require human approval before modification. AI coding agents may read protected areas for context but must not write, rename, or delete them unless an explicit, auditable approval exists. Enforcement is fail-closed: ambiguous paths default to protected when they match a documented category.

Scope

• Protected path categories, rationale, and owning teams.
• Approval workflow, exception duration, and audit evidence.
• Agent instructions injected into project context and CI path guards.
• Escalation when a boundary is crossed or an exception expires.

Outside this block

• Full secrets management or key rotation procedures.
• Code review style guides unrelated to protected paths.
• Definition-of-done evidence for unrelated change types.

Contract

• Every protected category has a stable ID, owner, glob or path rules, and documented reason.
• Writes to protected paths fail CI unless a linked approval ticket matches the category prefix declared in protection-policy.yaml.
• Break-glass edits use ticket prefix BREAK-, include all required audit fields, expire within the profile window, and trigger post-incident review.
• AI agents receive explicit stop instructions naming the category when a write is attempted.
• Time-bound exceptions include owner, expiry date, and scope; expired exceptions cannot authorize new edits.
• Read access to protected paths for context does not imply write permission.
• Violations trigger revert of automated edits where feasible and block merge until resolved.

Implementation guidance

• Encode rules in protection-policy.yaml and load them in pre-commit hooks and CI.
• Mirror the policy in AI agent system prompts or repository rules files.
• Keep protected paths minimal and review quarterly to avoid blanket lockdown.
• Pair with the definition-of-done block so protected-path changes require elevated verification.

Failure handling and safeguards

• If a critical hotfix must touch protected infrastructure, use the break-glass flow with BREAK- ticket, required audit fields, and post-incident review within the profile window.
• If path rules overlap, the strictest deny rule wins until owners reconcile the policy.
• If an agent bypasses local hooks, CI path guard remains authoritative.

Verification and operations

• Track violation attempts, approved exceptions, and mean time to approval.
• Audit monthly that protected globs still match actual sensitive locations.
• Test agent behavior with synthetic edit requests in a staging repository.

The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Ticket prefixes, paths, and exception duration in example.yaml and protection-policy.yaml are profile choices for a sample monorepo, not universal defaults.
• Teams must map categories to their own security classification and ownership model.

References

• No external normative source is required; this package defines repository change-boundary policy.