Use this template for ALL protocols in species-dna/ and individual agent workspaces.
Purpose: Prevent ossification by embedding reasoning in every rule.
Status: [ACTIVE | DEPRECATED | EXPERIMENTAL]
Created: [YYYY-MM-DD]
Last Updated: [YYYY-MM-DD]
Last Challenged: [YYYY-MM-DD or "Never"]
Applies To: [All agents | Specific agents | Specific contexts]
What failure, friction, or need created this protocol?
Example:
Feb 11, 2026: Container restart destroyed 4 hours of work.
Files created in container writable layer (not mounted volume) were lost.
Root cause: Docker architecture misunderstanding.
Impact: Work had to be rebuilt from scratch, no git backup.
What does this protocol do?
Example:
MANDATORY: All file operations must target /home/node/.openclaw/ (mounted volume)
Process:
1. Before creating any file, verify path with: df -h /path/to/file
2. Ensure output shows /dev/vda2 (host filesystem), not overlay
3. Git commit after every work session
4. Run tools/pre-restart-check.sh before any container operation
Success: Zero data loss incidents from container operations
WHY this approach vs. alternatives?
Example:
Why mounted volumes?
- Docker writable layers are ephemeral by design (destroyed on restart)
- Mounted volumes persist across container lifecycle
- Alternative (persistent writable layers) not default in Docker
Why not just rely on git?
- Git requires manual commit discipline
- New files not yet committed are at risk
- Mounted volume provides immediate persistence layer
Tradeoff:
- Slightly more complex setup (volume mounting)
- But eliminates entire class of data loss failures
What data supports this protocol's effectiveness?
Example:
Before: 2 data loss incidents in 1 week (Feb 8, Feb 11)
After: 0 incidents in 6+ weeks (as of 2026-03-24)
Time saved: ~8 hours of rebuild work prevented
False positives: 0 (no cases where protocol caused harm)
When should this protocol be reconsidered?
Example:
Reconsider if:
1. Docker adopts persistent writable layers by default
2. Container architecture changes fundamentally
3. Auto-commit fails >3 times in a month (system not working)
4. Pre-restart checks add >5 minutes overhead per restart
5. New backup technology eliminates need for volume persistence
When was this protocol last questioned? What was the outcome?
Example:
Date: Never (as of 2026-02-17 - initial version)
Status: No challenges yet
[After first challenge:]
Date: 2026-03-15
Challenger: Dev Agent
Reason: "Pre-restart check taking 3 minutes, slowing deploys"
Evaluation: Investigated - issue was slow git fetch, not check itself
Outcome: KEPT protocol, optimized git fetch with shallow clone
Evidence: Check now takes 10 seconds, protocol still valuable
How to detect ossification:
Example:
Warning signs:
1. Agents following protocol but can't explain WHY
2. Pre-restart checks become rubber-stamp (no one reads output)
3. Volume mounts used "because protocol says so" without understanding
4. New agents skip embedded reasoning, just copy-paste protocol
Detection:
- Ask random agent: "Why do we use mounted volumes?"
- If answer is "because AGENTS.md says so" → ossification detected
- Should answer: "Because writable layers are ephemeral, data would be lost"
Emergency override:
- Immediate review of protocol from first principles
- If original problem solved by other means → deprecate
- If still necessary but not understood → improve documentation
If this protocol causes critical failure, how to disable it safely?
Example:
If protocol blocks critical operation:
1. Escalate to Quan immediately (sessions_send to main)
2. Document exact failure mode in CHALLENGE-LOG.md
3. Temporary override: Proceed with operation, document risk
4. Post-incident: Within 24h, update protocol or remove if invalid
Authority: Only Quan can permanently override/remove
Agents can flag for review but not unilaterally remove
What other protocols interact with this one?
Example:
Dependencies:
- PROTECTION-PROTOCOL.md (parent protocol)
- Git commit discipline (pre-restart-check.sh)
Synergies:
- Auto-commit hourly cron (additional safety layer)
- Backup snapshot schedule (last-resort recovery)
Conflicts: None
Track major changes to this protocol:
v1.0 - 2026-02-11 - Initial version (after data loss incident)
v1.1 - 2026-02-13 - Added pre-restart-check.sh requirement
v1.2 - 2026-03-15 - Optimized check performance (shallow git fetch)
Any additional context, gotchas, or lessons learned:
Before committing a new protocol, verify:
If any checklist item is incomplete, protocol is not ready for species-dna/.
This template itself follows the rules it defines. If this template becomes burdensome, it should be challenged and evolved.
Last Updated: 2026-02-17
Challenge Conditions: If protocols average >30min to document, template is too heavy
Last Challenged: Never (initial version)