Protection & Compliance Skills
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Protection & Compliance Skills represent a core subsystem within the Engineering Platform designed to safeguard stable code and enforce development standards. The system provides a multi-layered defense mechanism—ranging from inline source code annotations to real-time pre-commit hooks and automated auditing—to prevent regressions and unauthorized modifications by both human developers and AI agents.
The scope of these skills covers the entire lifecycle of code stabilization, from identifying passing features via manual tests to locking down critical APIs and monitoring protection coverage over time. By establishing a formalized "Code Protection Policy," the project ensures that high-impact components like core services, external API integrations, and extension activation sequences remain stable across versions.
Sources: skills/protect/SKILL.md:6-12, README.md:105-112, CHANGELOG.md:120-131
Code Protection Framework
The protection framework categorizes source code into three distinct protection levels based on stability and the risk of regression.
Protection Levels
| Level | Description | Use Case |
|---|---|---|
| @immutable | Never change. Requires architecture review for any modification. | External API integrations (Whisper, GitHub), core data structures, and persisted formats. |
| @protected | Refactor only. Behavior must remain identical to the tested state. | UI components, working feature workflows, and services with correct business logic. |
| @maintainable | Bug fixes allowed. Core functionality works but has known edge cases. | Features with partial test passes or known performance issues. |
Sources: skills/protect/SKILL.md:14-27, audits/adhub/decisions/decisions/ADR-002-protection-guard-hook.md:81-87
Annotation Architecture
Protection is primarily established via JSDoc-style annotations placed immediately before a class or function export. These annotations must include a lock date, a reference to the manual test result validating the feature, and a status indicator (e.g., PASSING, STABLE, PARTIAL).
Sources: skills/protect/SKILL.md:85-115
Automated Enforcement System
The system moves beyond manual checklists by implementing real-time blocking mechanisms that prevent the modification of protected code without explicit justification.
Pre-Commit Guardrails
The enforcement logic is distributed between a validation script (scripts/validate-protection.js) and a Git pre-commit hook. When a developer attempts to commit changes, the system scans staged files for protection markers. If a protected file is detected, the commit is blocked unless the commit message contains a PROTECTED: prefix followed by a justification.
The diagram above illustrates the decision logic executed during the Git pre-commit phase to ensure protected code is only modified with proper intent.
Sources: skills/validate-protection/SKILL.md:11-20, skills/validate-protection.js:142-178
Protection Guard Hook (ADR-002)
For AI-native environments, the "Protection Guard Hook" utilizes a PreToolUse trigger. This fires before an AI tool (like Edit or Write) can execute, checking the target file against a protection registry. If the file is protected and no valid override exists, the tool execution is blocked with an exit code 2.
Sources: audits/adhub/decisions/decisions/ADR-002-protection-guard-hook.md:46-63, audits/adhub/decisions/decisions/ADR-002-protection-guard-hook.md:128-142
Auditing and Compliance
The Compliance subsystem provides visibility into the health and coverage of the protection framework through automated reporting and consistency checks.
Audit Reporting
The protection-audit skill identifies discrepancies between the CODE_PROTECTION_POLICY.md registry and the actual annotations present in the source code. It tracks "Protection Coverage," which is the ratio of protected files to total source files.
Audit Workflow
- Scan: Recursively identifies all
.tsand.jsfiles (excludingnode_modules,dist, etc.). - Extract: Parses regex patterns for
@immutable,@protected, and@maintainable. - Compare: Validates found annotations against the policy document.
- Report: Generates summary, detailed, or JSON-formatted compliance reports.
The sequence diagram shows the automated verification process used to maintain synchronization between documentation and code implementation.
Sources: skills/protection-audit/SKILL.md:12-25, scripts/audit-protection.js:233-281
Implementation Components
The following table summarizes the key scripts and configuration files supporting the Protection & Compliance ecosystem:
| Component | Path | Purpose |
|---|---|---|
| Validation Script | scripts/validate-protection.js | Scans staged files during pre-commit for unauthorized changes. |
| Audit Script | scripts/audit-protection.js | Generates coverage reports and verifies policy consistency. |
| Pre-Commit Hook | .git/hooks/pre-commit | Integrates validation into the Git lifecycle. |
| Policy Registry | docs/CODE_PROTECTION_POLICY.md | Central document listing all protected files and their justifications. |
| Guard Hook | .claude/hooks/protection-guard.js | Real-time blocking script for AI tool usage. |
Sources: skills/validate-protection/SKILL.md:195-202, skills/protection-audit/SKILL.md:387-395, audits/adhub/decisions/decisions/ADR-002-protection-guard-hook.md:144-158
Conclusion
The Protection & Compliance Skills provide a robust, automated framework for maintaining software quality as a project matures. By codifying protection levels into source code and enforcing them via Git hooks and AI-specific guards, the system ensures that "what works stays working." This methodology significantly reduces the risk of costly regressions in core services and maintains a clear audit trail for every intentional modification to stable code.
Sources: skills/protect/SKILL.md:215-227, audits/adhub/decisions/decisions/ADR-002-protection-guard-hook.md:188-195