Initial commit

2025-11-30 08:43:48 +08:00
commit cf118c4923
27 changed files with 10878 additions and 0 deletions
--- a/skills/wolf-adr/SKILL.md
+++ b/skills/wolf-adr/SKILL.md
@@ -0,0 +1,769 @@
+---
+name: wolf-adr
+description: Architecture Decision Records index with searchable topics and phase-based organization (120+ ADRs from 50+ phases)
+version: 1.1.0
+category: architecture
+triggers:
+  - architecture decision
+  - ADR
+  - design decision
+  - technical decision
+  - system design
+dependencies:
+  - wolf-principles
+size: large
+---
+
+# Wolf Architecture Decision Records (ADRs)
+
+Searchable index of 120+ Architecture Decision Records documenting Wolf's evolution through 50+ phases of development.
+
+## Overview
+
+Wolf's ADRs capture critical architectural decisions, including:
+- **Context**: Why the decision was needed
+- **Decision**: What was chosen and why
+- **Consequences**: Impact and tradeoffs
+- **Status**: Proposed, Accepted, Superseded, Deprecated
+- **Related ADRs**: Decision dependencies
+
+## How to Use This Skill
+
+### Finding Relevant ADRs
+
+1. **By Topic**: Use topic clusters below to find related decisions
+2. **By Phase**: Check phase-based organization for historical context
+3. **By Keywords**: Search for specific technologies or patterns
+4. **Current Architecture**: See "Living Snapshot" section
+
+### ADR Locations
+
+All ADRs in `/docs/adr/`:
+- **Current/Active**: `docs/adr/ADR-XXX-*.md` and `docs/adr/phase-*/shard-*/ADR-*.md`
+- **Archived**: `docs/adr/archive/ADR-*.md`
+- **Living Snapshot**: `docs/adr/phase-50/shard-50-5/current-architecture-2025-10-07.md`
+
+---
+
+## Topic Clusters
+
+### 🏗️ MCP Server Architecture
+
+**Key Decisions:**
+- **ADR-017**: MCP Server Conversion Strategy (identified 15-20 packages)
+- **ADR-018**: MCP Server Architecture (implementation of 3 operational servers)
+- **ADR-023**: **Knowledge-First Pivot** ⭐ (critical shift from operational to knowledge-serving)
+  - **Problem**: Built operational tools that duplicated agent capabilities
+  - **Solution**: MCP servers should expose Wolf's accumulated knowledge
+  - **Impact**: 9 of 15 tools identified as redundant; pivot to knowledge access
+- **ADR-025**: Hybrid MCP Consolidation Strategy
+  - **Decision**: Keep operational MCPs for Wolf-specific logic, sunset duplicates
+  - **Result**: wolf-knowledge-mcp (primary), wolf-governance-mcp, wolf-evals-mcp
+
+**When to Reference:**
+- Designing new MCP servers
+- Deciding operational vs. knowledge tools
+- Understanding Wolf's MCP evolution
+
+**Files**:
+- `/docs/adr/archive/ADR-017-mcp-server-conversion-strategy.md`
+- `/docs/adr/archive/ADR-023-mcp-server-knowledge-first-pivot.md`
+- `/docs/adr/archive/ADR-025-hybrid-mcp-consolidation.md`
+
+---
+
+### 🔍 Verification & Quality Assurance
+
+**Key Decisions:**
+- **ADR-043**: **Verification Architecture** ⭐ (CoVe, HSP, RAG)
+  - **CoVe**: Chain of Verification for systematic fact-checking
+  - **HSP**: Hierarchical Safety Prompts for multi-level validation
+  - **RAG**: Grounding evidence retrieval
+  - **Integration**: 3-layer verification pipeline
+- **ADR-0051**: Retrieval-CoVe Hybrid (combining retrieval with verification)
+- **ADR-0061**: Hallucination Drift Watchdog (detecting and preventing hallucinations)
+- **ADR-0050**: Policy Intelligence Engine Accuracy Enhancement
+
+**When to Reference:**
+- Implementing self-verification
+- Building quality gates
+- Hallucination detection
+- Evidence-based validation
+
+**Files**:
+- `/docs/adr/phase-43/shard-00/ADR-0043-verification-architecture.md` (if exists)
+- `/docs/adr/archive/ADR-0051-retrieval-cove-hybrid.md`
+- `/docs/adr/archive/ADR-0061-hallucination-drift-watchdog.md`
+
+---
+
+### 🐳 Sandbox & Containerization
+
+**Key Decisions:**
+- **ADR-0063**: Sandbox Containerization Strategy
+  - **Problem**: Need isolated code execution environment
+  - **Solution**: Docker-based sandbox with security constraints
+- **ADR-0064**: Sandbox Quota Enforcement Architecture
+  - **Resource Limits**: CPU, memory, disk I/O quotas
+  - **Enforcement**: Pre-execution checks and runtime monitoring
+- **ADR-0065**: Sandbox Security Architecture
+  - **Security Layers**: Network isolation, filesystem restrictions, capability dropping
+
+**When to Reference:**
+- Implementing code execution environments
+- Setting resource limits
+- Security hardening for sandboxes
+
+**Files**:
+- `/docs/adr/archive/ADR-0063-sandbox-containerization-strategy.md`
+- `/docs/adr/archive/ADR-0064-sandbox-quota-enforcement-architecture.md`
+- `/docs/adr/archive/ADR-0065-sandbox-security-architecture.md`
+
+---
+
+###⚙️ CI/CD & GitHub Actions
+
+**Key Decisions:**
+- **ADR-072**: **GitHub Actions Workflow Standards** ⭐ (mandatory patterns)
+  - **Problem**: 37% failure rate due to missing checkout steps, 100% failure with wrong API fields
+  - **Solution**: Mandatory checkout step, correct API field names, permissions declaration
+  - **Impact**: Prevents infrastructure failures across all workflows
+- **ADR-071**: CI Workflow Optimization Strategy (workflow consolidation, cost management)
+- **ADR-056**: Composite Actions Standard
+  - **Reusable Workflows**: Extract common patterns into composite actions
+  - **Benefits**: DRY, consistency, maintainability
+- **ADR-048-5**: Actions Audit (audit trail for GitHub Actions)
+- **ADR-070**: Agent Build Pipeline (agent-specific CI/CD)
+
+**When to Reference:**
+- Creating new GitHub workflows
+- Fixing workflow failures
+- Implementing composite actions
+- Workflow optimization
+
+**Files**:
+- `/docs/adr/ADR-072-github-actions-workflow-standards.md`
+- `/docs/adr/archive/ADR-056-composite-actions.md` (if exists)
+- `/docs/adr/archive/ADR-070-agent-build-pipeline.md`
+
+---
+
+### 📦 Packaging & Dependencies
+
+**Key Decisions:**
+- **ADR-016**: Dependency Optimization Strategy
+  - **Approach**: Fork and optimize 279 npm packages
+  - **Result**: 83.3% of dependencies optimized via `jdmiranda/*` repos
+  - **Branches**: All forks use `perf/*` branches
+- **ADR-055**: Packaging Standard
+  - **Conventions**: Package naming, versioning, distribution
+  - **Quality Gates**: Build, test, publish standards
+
+**When to Reference:**
+- Adding new dependencies
+- Optimizing existing packages
+- Package publishing decisions
+
+**Files**:
+- `/docs/adr/archive/ADR-016-dependency-optimization-strategy.md`
+- `/docs/adr/archive/ADR-055-packaging-standard.md`
+
+---
+
+### 📊 Metrics, Monitoring & Evals
+
+**Key Decisions:**
+- **ADR-0048-2**: Metrics Framework
+  - **Categories**: Agent efficiency, workflow latency, quality scores
+  - **Collection**: Privacy-preserving metrics with PII redaction
+- **ADR-0061**: Baseline-Target Tracking (performance baseline establishment)
+- **wolf-evals-mcp**: Agent efficiency metrics (latency, efficiency, token tracking)
+
+**When to Reference:**
+- Implementing telemetry
+- Performance monitoring
+- Establishing baselines
+- Efficiency tracking
+
+**Files**:
+- `/docs/adr/archive/ADR-0048-2-metrics.md`
+- `/docs/adr/archive/ADR-0061-baseline-target-tracking.md`
+
+---
+
+### 🛡️ Security & Compliance
+
+**Key Decisions:**
+- **ADR-0065**: Sandbox Security Architecture (isolation, restrictions, capability dropping)
+- **Security Hardener Archetype**: Threat reduction priority, defense-in-depth
+- **Governance Framework**: Mandatory security validation for security-labeled work
+
+**When to Reference:**
+- Security architecture decisions
+- Threat modeling
+- Compliance requirements
+- Secure code execution
+
+---
+
+### 🎭 Agent Roles & Behavioral Archetypes
+
+**Key Decisions:**
+- **ADR-0049**: Role Card Integrity
+  - **Problem**: Role card drift and inconsistency
+  - **Solution**: Validation framework, schema enforcement
+- **Archetype System**: 11 behavioral profiles (ADR embedded in archetype registry)
+  - product-implementer, security-hardener, perf-optimizer, reliability-fixer, etc.
+- **Lens System**: 4 overlay lenses (performance, security, accessibility, observability)
+
+**When to Reference:**
+- Defining new agent roles
+- Modifying existing archetypes
+- Understanding agent behavioral adaptation
+
+**Files**:
+- `/docs/adr/archive/ADR-0049-role-card-integrity.md`
+- `/agents/archetypes/registry.yml` (contains embedded archetype decisions)
+- `/agents/lenses/registry.yml` (contains lens application rules)
+
+---
+
+### 📝 Governance & Process
+
+**Key Decisions:**
+- **ADR-0048-7**: Conditional Approvals (automated approval workflows)
+- **ADR-0048-10**: Research Hygiene (research phase standards)
+- **ADR-047-C**: Output Summary Validation (standardized output format)
+- **Emergency Governance Activation**: Override mechanisms for critical issues
+
+**When to Reference:**
+- Governance policy decisions
+- Approval workflow design
+- Process standardization
+
+**Files**:
+- `/docs/adr/archive/ADR-0048-7-conditional-approvals.md`
+- `/docs/adr/archive/ADR-0048-10-research-hygiene.md`
+- `/docs/adr/archive/ADR-047-C-output-summary-validation.md`
+
+---
+
+### 🧪 Research & Experimentation
+
+**Key Decisions:**
+- **ADR-0053**: Research Agent Workflow
+  - **Process**: Hypothesis → Experiment → Validation → Documentation
+  - **Time-boxing**: Fixed duration for research spikes
+- **Research-Prototyper Archetype**: Hypothesis testing, feasibility analysis
+
+**When to Reference:**
+- Planning research spikes
+- Experimentation workflows
+- Proof-of-concept development
+
+**Files**:
+- `/docs/adr/archive/ADR-0053-research-agent-workflow.md`
+
+---
+
+### 🔧 Tooling & Infrastructure
+
+**Key Decisions:**
+- **wolfctl**: Safe command runner with policy enforcement
+  - **Command Policy**: `tools/wolfctl/command-policy.json`
+  - **Hardened Shell**: Policy-enforced execution
+- **ADR-024**: MCP Tool Candidates Comprehensive Discovery
+  - **Survey**: Identified 15-20 candidate packages for MCP conversion
+- **ADR-0069**: Claude Code SDK Integration (Phase 3 before/after analysis)
+
+**When to Reference:**
+- Tool development decisions
+- Infrastructure patterns
+- SDK integration approaches
+
+**Files**:
+- `/docs/adr/archive/ADR-024-mcp-tool-candidates-comprehensive-discovery.md`
+- `/docs/adr/archive/ADR-0069-claude-code-sdk-integration.md`
+
+---
+
+## Phase-Based Organization
+
+### Phase Evolution
+
+**Phases 1-40**: Foundation
+- Agent role definitions
+- Core principles establishment
+- Initial workflow patterns
+
+**Phases 41-45**: Quality Systems
+- Verification frameworks (CoVe, HSP, RAG)
+- Testing pipelines
+- Quality gates
+
+**Phases 46-50**: MCP Integration
+- ADR-017: MCP conversion strategy
+- ADR-023: Knowledge-first pivot ⭐
+- ADR-025: Hybrid consolidation
+- wolf-knowledge-mcp operational
+
+**Phase 50+ (Current)**: Refinement
+- ADR-072: Workflow standards
+- Composite actions
+- Enhanced verification
+
+### Key Phase Milestones
+
+| Phase | Key Decision | ADR | Impact |
+|-------|--------------|-----|--------|
+| 43 | Verification Architecture | ADR-043 | 3-layer verification (CoVe/HSP/RAG) |
+| 46-48 | MCP Server Strategy | ADR-017/018 | Operational MCP servers built |
+| 49 | Knowledge-First Pivot | ADR-023 | Recognized operational redundancy |
+| 50 | Hybrid Consolidation | ADR-025 | wolf-knowledge-mcp primary |
+| 50+ | Workflow Standards | ADR-072 | Mandatory GitHub Actions patterns |
+
+---
+
+## Living Architecture Snapshot
+
+**Current Architecture (October 2025)**
+
+The most comprehensive current view is at:
+`/docs/adr/phase-50/shard-50-5/current-architecture-2025-10-07.md`
+
+This living document synthesizes all 50+ phases into a current system snapshot, including:
+- 4 active MCP servers
+- 44 agent roles with inheritance
+- 3-layer verification architecture
+- Docker-based sandbox infrastructure
+- GitHub-native workflow integration
+- 335 npm packages (279 optimized forks)
+
+**When to Use**: Starting new work, onboarding, architecture review, system understanding
+
+---
+
+## ADR Format Standard
+
+Wolf ADRs follow this structure:
+
+```markdown
+# ADR-XXX: Title
+
+**Status**: Proposed | Accepted | Superseded | Deprecated
+**Date**: YYYY-MM-DD
+**Deciders**: Role names
+**Related ADRs**: Links to related decisions
+
+---
+
+## Context
+[Why this decision is needed, background, constraints]
+
+## Problem Statement
+[Specific problem being solved]
+
+## Decision
+[What was chosen and why]
+
+## Consequences
+[Impact, tradeoffs, what changes]
+
+## Alternatives Considered
+[Other options and why rejected]
+
+---
+
+## References
+[Related docs, issues, PRs]
+```
+
+---
+
+## How to Navigate ADRs
+
+### By Status
+- **Proposed**: Under review, not yet implemented
+- **Accepted**: Approved and active
+- **Superseded**: Replaced by newer ADR
+- **Deprecated**: No longer applicable
+
+### By Priority
+- ⭐ **Critical ADRs** (starred above): Must-read for architecture understanding
+- **Topic ADRs**: Read when working in specific domain
+- **Historical ADRs**: Context for evolution, not always current
+
+### Search Strategies
+
+**Problem-Based**: "I need to solve X"
+→ Check topic cluster for X
+→ Read ADRs in that cluster
+→ Follow related ADRs
+
+**Technology-Based**: "I'm working with Y"
+→ Search ADR index for Y
+→ Check current architecture doc
+→ Trace decision history
+
+**Phase-Based**: "What changed in Phase Z?"
+→ Look at phase-Z ADRs
+→ Compare with previous phase
+→ Understand evolution
+
+---
+
+## Integration with Wolf Skills
+
+**Wolf ADR skill** integrates with other Wolf skills:
+
+- **wolf-governance**: Search governance rules (may include ADR references)
+  - Use: `Skill tool → wolf-governance`
+  - Purpose: Understand governance requirements that drive ADR creation
+
+- **wolf-principles**: Query principles (foundational to many ADRs)
+  - Use: `Skill tool → wolf-principles`
+  - Purpose: Ensure ADRs align with Wolf's 10 core principles
+
+---
+
+## Best Practices
+
+### Creating ADRs
+- ✅ Document **why** not just **what**
+- ✅ Include alternatives considered
+- ✅ Link related ADRs
+- ✅ Update status when superseded
+- ❌ Don't create ADRs for trivial decisions
+- ❌ Don't skip consequences section
+
+### Using ADRs
+- ✅ Read current architecture first for overview
+- ✅ Trace decision history for context
+- ✅ Check status before applying patterns
+- ✅ Reference ADRs in new decisions
+- ❌ Don't assume old ADRs are current
+- ❌ Don't skip related ADRs
+
+### Maintaining ADRs
+- ✅ Mark superseded ADRs clearly
+- ✅ Keep index up to date
+- ✅ Archive old ADRs properly
+- ✅ Update living architecture doc
+- ❌ Don't delete ADRs (archive instead)
+- ❌ Don't modify accepted ADRs (create new superseding ADR)
+
+---
+
+## Related Skills
+
+- **wolf-principles**: Foundation for many ADRs
+- **wolf-governance**: Process decisions documented in ADRs
+- **wolf-archetypes**: Behavioral archetype decisions
+- **wolf-workflows-ci**: GitHub Actions patterns from ADR-072
+- **wolf-verification**: Verification architecture from ADR-043
+
+---
+
+## When ADRs Are REQUIRED vs OPTIONAL
+
+### REQUIRED (MUST create ADR)
+
+✅ **Architectural Changes:**
+- Changing system architecture or major component structure
+- Adding/removing services or significant dependencies
+- Modifying data flow or integration patterns
+- Infrastructure architecture decisions
+
+✅ **Process Changes:**
+- Modifying Wolf's core workflows or methodology
+- Changing governance policies or quality gates
+- Updating agent role definitions or responsibilities
+- Altering approval hierarchies or authority matrix
+
+✅ **Tool Selections:**
+- Choosing between competing technologies or frameworks
+- Adopting new core dependencies (databases, frameworks, etc.)
+- Changing build systems or CI/CD platforms
+- MCP server architecture decisions
+
+✅ **Security Decisions:**
+- Authentication/authorization approaches
+- Security architecture or threat mitigation strategies
+- Compliance framework changes
+
+### OPTIONAL (Consider creating ADR)
+
+⚠️ **Significant Patterns:**
+- New code patterns that will be reused across codebase
+- Design patterns that affect multiple components
+- Performance optimization strategies
+
+⚠️ **Experimental Approaches:**
+- Research spikes with significant findings
+- Proof-of-concept results that inform future direction
+
+### NOT REQUIRED (Skip ADR)
+
+❌ **Trivial Decisions:**
+- Bug fixes (use journal entry instead)
+- Refactoring without behavior change (use journal entry)
+- Minor code cleanup or formatting
+- Documentation updates (unless process change)
+
+❌ **Implementation Details:**
+- Variable naming conventions
+- File organization within existing structure
+- Code comment standards
+
+**Rule of Thumb**: If the decision affects future work or needs to be understood months later by different agents, create an ADR.
+
+---
+
+## Red Flags - STOP
+
+If you catch yourself thinking:
+
+- ❌ **"ADRs are optional documentation"** - NO. ADRs are REQUIRED for architectural, process, and tool decisions. They prevent repeated debates.
+- ❌ **"I'll write the ADR later"** - FORBIDDEN. ADRs must be created BEFORE or DURING decision-making, not after. Later = never.
+- ❌ **"This decision is too small for an ADR"** - Wrong metric. If it affects future work or needs historical context, ADR is required.
+- ❌ **"I can modify an accepted ADR"** - NO. Accepted ADRs are immutable. Create a new superseding ADR instead.
+- ❌ **"ADR format doesn't matter"** - False. Wolf has a standard ADR format. Follow it for consistency and discoverability.
+
+**STOP. Create ADR using standard format BEFORE making architectural/process decisions.**
+
+## After Using This Skill
+
+**RECOMMENDED NEXT STEPS:**
+
+```
+ADRs document decisions - used for context and reference
+```
+
+1. **Creating an ADR**: Use wolf-governance for quality gates
+   - **When**: Before making architectural/process/tool decisions
+   - **Why**: ADRs are part of Definition of Done for architectural changes
+   - **Tool**: Use Skill tool to load wolf-governance
+
+2. **Understanding Decisions**: Use wolf-principles for decision framework
+   - **When**: Evaluating alternatives for ADR
+   - **Why**: Principles guide decision-making (e.g., Research-First, Evidence-Based)
+   - **Tool**: Use Skill tool to load wolf-principles (focus on Principle #5: Evidence-Based Decisions)
+
+3. **No specific next skill**: ADRs are referenced throughout work
+   - This skill provides ADR index and navigation
+   - wolf-governance specifies when ADRs are required
+   - wolf-principles guide ADR content (alternatives, consequences)
+
+### ADR Creation Checklist
+
+Before claiming ADR complete:
+
+- [ ] Status clearly marked (Proposed, Accepted, Superseded, Deprecated)
+- [ ] Context section explains WHY decision is needed (not just WHAT)
+- [ ] Decision section documents WHAT was chosen AND WHY
+- [ ] Consequences section lists tradeoffs and impacts (positive AND negative)
+- [ ] Alternatives Considered section documents rejected options with rationale
+- [ ] Related ADRs linked (if decision builds on or supersedes previous ADRs)
+- [ ] ADR follows standard format (Context → Problem → Decision → Consequences → Alternatives)
+
+**Can't check all boxes? ADR incomplete. Return to this skill.**
+
+### Good/Bad Examples: ADR Quality
+
+#### Example 1: Well-Structured ADR
+
+<Good>
+**ADR-072: GitHub Actions Workflow Standards**
+
+**Status**: Accepted
+**Date**: 2025-10-15
+**Deciders**: DevOps Team, Code Reviewers
+**Related ADRs**: ADR-071 (CI Workflow Optimization), ADR-056 (Composite Actions)
+
+---
+
+## Context
+
+GitHub Actions workflows across WolfAgents had a 37% failure rate due to:
+1. Missing checkout steps (37% of failures)
+2. Incorrect API field usage (100% failure when wrong fields used)
+3. Undeclared permissions causing authorization failures
+
+Investigation of 43 workflows revealed systemic anti-patterns. Need standardized patterns to prevent infrastructure failures.
+
+## Problem Statement
+
+How do we prevent recurring workflow failures caused by missing checkout steps, incorrect GitHub API usage, and permission errors?
+
+## Decision
+
+**Mandate the following standards for all GitHub Actions workflows:**
+
+1. **Mandatory Checkout Step:**
+   ```yaml
+   - uses: actions/checkout@v4  # MUST be first step
+   ```
+   Rationale: Without checkout, workflows cannot access repository files.
+
+2. **Correct API Field Names:**
+   - Use `closingIssuesReferences` not `closes` for gh pr view
+   - Use `labels` not `label` for gh issue view
+   Rationale: GitHub CLI expects specific field names; typos cause 100% failure.
+
+3. **Explicit Permissions:**
+   ```yaml
+   permissions:
+     contents: read
+     pull-requests: write
+     issues: write
+   ```
+   Rationale: Prevent authorization failures with least-privilege declarations.
+
+## Consequences
+
+**Positive:**
+- ✅ Eliminates 37% of workflow failures (missing checkout)
+- ✅ Prevents 100% failure rate from API field typos
+- ✅ Clear permission boundaries prevent security issues
+- ✅ Reusable pattern across all 43+ workflows
+
+**Negative:**
+- ⚠️ Requires updating all existing workflows (one-time cost)
+- ⚠️ Adds 3-5 lines to each workflow (minimal verbosity)
+
+## Alternatives Considered
+
+**Alternative 1:** Documentation only (no enforcement)
+- Rejected: Documentation alone didn't prevent recurring failures
+- Teams repeatedly forgot checkout step despite documentation
+
+**Alternative 2:** Pre-commit hooks to validate workflows
+- Rejected: Hooks can be bypassed; workflow validation happens too late
+- Better to mandate in CI template
+
+**Alternative 3:** Composite action wrapper
+- Rejected: Hides checkout step, makes debugging harder
+- Mandatory explicit step is more transparent
+
+---
+
+## References
+- Issue #789: 37% workflow failure analysis
+- PR #845: Workflow standards implementation
+- docs/governance/workflow-validation.md
+
+---
+
+**Why this is excellent**:
+- ✅ Context explains WHY (failure rates, specific problems)
+- ✅ Decision documents WHAT + WHY + HOW (with code examples)
+- ✅ Consequences lists both positive AND negative impacts
+- ✅ Alternatives explained with rejection rationale
+- ✅ Quantified impact (37% failure rate, 100% API field failures)
+- ✅ Related ADRs linked for context
+- ✅ References provide evidence trail
+</Good>
+
+<Bad>
+**ADR-999: Use Docker**
+
+**Status**: Proposed
+**Date**: 2025-10-20
+
+---
+
+## Context
+
+We should use Docker.
+
+## Decision
+
+Use Docker for containerization.
+
+## Consequences
+
+It will be good.
+
+---
+
+**Why this is terrible**:
+- ❌ No context about WHY Docker is needed
+- ❌ No problem statement (what problem does Docker solve?)
+- ❌ Decision lacks rationale (WHY Docker vs alternatives?)
+- ❌ "It will be good" is not a consequence (no tradeoffs, no specifics)
+- ❌ No alternatives considered (why not Podman, VMs, native execution?)
+- ❌ No related ADRs (surely there are related infra decisions?)
+- ❌ No references (no evidence, no analysis)
+- ❌ Not enough detail to understand decision months later
+
+**What this should include**:
+```markdown
+## Context
+Current code execution happens on host machine, causing:
+1. Security concerns (untrusted code access to host)
+2. Resource contention (no isolation between jobs)
+3. Dependency conflicts (version mismatches)
+
+Analyzed 200+ execution failures: 45% due to dependency conflicts, 30% resource contention.
+
+## Problem Statement
+How do we provide isolated, reproducible code execution environments with resource limits and security boundaries?
+
+## Decision
+Use Docker containers for code execution with:
+- Resource limits (CPU, memory, disk quotas)
+- Network isolation
+- Filesystem restrictions
+- Capability dropping
+
+Rationale:
+- Industry standard (widespread knowledge, tooling)
+- Strong isolation model (namespaces, cgroups)
+- Reproducible environments (Dockerfile = config as code)
+- Resource control (native cgroup support)
+
+## Consequences
+Positive:
+- ✅ Eliminates 45% of dependency conflict failures
+- ✅ Prevents resource contention (isolated CPU/memory)
+- ✅ Stronger security boundaries (container escape harder than process escape)
+- ✅ Reproducible across dev/CI/prod
+
+Negative:
+- ⚠️ Adds Docker dependency (ops overhead)
+- ⚠️ Container startup latency (200-500ms vs instant process)
+- ⚠️ Increased disk usage (images ~100-500MB)
+- ⚠️ Requires Docker daemon (privilege escalation risk)
+
+## Alternatives Considered
+1. **Podman**: rootless containers
+   - Rejected: Less mature tooling, team unfamiliar
+   - May revisit if Docker security concerns grow
+
+2. **VMs (Firecracker)**: microVMs
+   - Rejected: Higher overhead (2-3 second startup)
+   - Overkill for current security requirements
+
+3. **Native Execution with chroot**: OS-level isolation
+   - Rejected: Weaker isolation, no resource limits
+   - Insufficient for untrusted code
+
+## References
+- Spike results: docs/research/containerization-spike-2025-10.md
+- Security analysis: docs/security/execution-isolation-threats.md
+- Performance benchmarks: docs/benchmarks/container-overhead.md
+```
+
+Now THAT would be an acceptable ADR.
+</Bad>
+
+---
+
+**Total ADRs**: 120+
+**Active ADRs**: ~70
+**Archived ADRs**: ~50
+**Living Documents**: 1 (current-architecture)
+
+**Last Updated**: 2025-11-14
+**Phase**: Superpowers Skill-Chaining Enhancement v2.0.0
+**Maintainer**: Architecture Team