wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/06-safety-guardrails/damage-control.md

@@ -0,0 +1,292 @@
+# Damage Control
+
+Pattern-based protection against destructive operations.
+
+---
+
+## Purpose
+
+Damage control prevents:
+- Accidental file deletions
+- Destructive git operations
+- Dangerous system commands
+- Configuration overwrites
+
+---
+
+## Configuration
+
+```json
+{
+  "damageControl": {
+    "enabled": false,
+    "patternsFile": ".workflow/damage-control.yaml",
+    "promptHook": {
+      "enabled": false,
+      "model": "haiku",
+      "timeout": 5000,
+      "skipSafeCommands": true
+    },
+    "onBlock": "error",
+    "onAsk": "prompt",
+    "logging": true
+  }
+}
+```
+
+---
+
+## Pattern File
+
+Define patterns in `.workflow/damage-control.yaml`:
+
+```yaml
+# Damage Control Patterns
+
+block:
+  # Block destructive git commands
+  - pattern: "git push.*--force"
+    message: "Force push is blocked. Use --force-with-lease instead."
+
+  # Block mass deletions
+  - pattern: "rm -rf /"
+    message: "Root deletion is always blocked."
+
+  - pattern: "rm -rf \\*"
+    message: "Wildcard deletion requires explicit approval."
+
+  # Block config overwrites
+  - pattern: "config\\.json.*--overwrite"
+    message: "Config overwrite requires approval."
+
+ask:
+  # Require confirmation for these
+  - pattern: "git reset --hard"
+    message: "Hard reset will lose uncommitted changes. Continue?"
+
+  - pattern: "drop.*table"
+    message: "Dropping database table. Are you sure?"
+
+  - pattern: "rm -rf node_modules"
+    message: "Removing node_modules. Reinstall will be needed."
+
+allow:
+  # Explicitly allow safe patterns
+  - pattern: "git push origin"
+  - pattern: "rm -rf dist"
+  - pattern: "rm -rf build"
+```
+
+---
+
+## How It Works
+
+```
+Command Detected
+      ↓
+┌─────────────────────────────────────────┐
+│ Check against block patterns            │
+├─────────────────────────────────────────┤
+│ Match? → Block with error               │
+└─────────────────────────────────────────┘
+      ↓
+┌─────────────────────────────────────────┐
+│ Check against ask patterns              │
+├─────────────────────────────────────────┤
+│ Match? → Prompt for confirmation        │
+└─────────────────────────────────────────┘
+      ↓
+┌─────────────────────────────────────────┐
+│ Check against allow patterns            │
+├─────────────────────────────────────────┤
+│ Match? → Allow immediately              │
+└─────────────────────────────────────────┘
+      ↓
+Execute command
+```
+
+---
+
+## Actions
+
+### Block
+
+```json
+{
+  "onBlock": "error"    // Options: "error" | "warn" | "log"
+}
+```
+
+| Setting | Behavior |
+|---------|----------|
+| `error` | Stop execution, show error |
+| `warn` | Show warning, continue |
+| `log` | Log silently, continue |
+
+### Ask
+
+```json
+{
+  "onAsk": "prompt"    // Options: "prompt" | "block" | "allow"
+}
+```
+
+| Setting | Behavior |
+|---------|----------|
+| `prompt` | Ask user for confirmation |
+| `block` | Treat ask patterns as blocks |
+| `allow` | Treat ask patterns as allowed |
+
+---
+
+## Prompt Hook
+
+For advanced protection, enable AI-powered review:
+
+```json
+{
+  "damageControl": {
+    "promptHook": {
+      "enabled": true,
+      "model": "haiku",          // Fast model for quick checks
+      "timeout": 5000,           // Max wait time
+      "skipSafeCommands": true   // Skip obvious safe commands
+    }
+  }
+}
+```
+
+### How Prompt Hook Works
+
+1. Command intercepted
+2. Sent to AI for risk assessment
+3. AI returns: safe, risky, or blocked
+4. Action taken based on result
+
+---
+
+## Common Patterns
+
+### Git Protection
+
+```yaml
+block:
+  - pattern: "git push.*--force$"
+    message: "Use --force-with-lease for safer force push"
+
+  - pattern: "git reset --hard HEAD~[0-9]+"
+    message: "Multiple commit reset blocked"
+
+ask:
+  - pattern: "git reset --hard"
+  - pattern: "git clean -fd"
+  - pattern: "git checkout -- \\."
+```
+
+### File Protection
+
+```yaml
+block:
+  - pattern: "rm -rf /$"
+  - pattern: "rm -rf ~"
+  - pattern: "> /dev/sd"
+
+ask:
+  - pattern: "rm -rf"
+  - pattern: "chmod 777"
+  - pattern: "chown -R"
+```
+
+### Database Protection
+
+```yaml
+block:
+  - pattern: "DROP DATABASE"
+  - pattern: "TRUNCATE.*CASCADE"
+
+ask:
+  - pattern: "DROP TABLE"
+  - pattern: "DELETE FROM.*WHERE 1"
+  - pattern: "UPDATE.*SET.*WHERE 1"
+```
+
+---
+
+## Logging
+
+When `logging` is enabled:
+
+```
+.workflow/logs/damage-control.log
+
+2024-01-15 10:30:00 | BLOCKED | git push --force | Force push blocked
+2024-01-15 10:31:00 | ASKED   | rm -rf dist | User approved
+2024-01-15 10:32:00 | ALLOWED | git push origin | Safe pattern
+```
+
+---
+
+## Integration with Auto-Inference
+
+Damage control can work with auto-inference verification:
+
+```json
+{
+  "damageControl": {
+    "enabled": true,
+    "integrateWithVerification": true
+  }
+}
+```
+
+Commands run during verification are also checked.
+
+---
+
+## Best Practices
+
+1. **Start Conservative**: Block more, ask for the rest
+2. **Customize Patterns**: Add project-specific dangers
+3. **Review Logs**: Check what's being caught
+4. **Whitelist Safe Ops**: Avoid prompt fatigue
+5. **Test Patterns**: Verify regex matches correctly
+
+---
+
+## Troubleshooting
+
+### Pattern Not Matching
+
+Test regex:
+```bash
+echo "git push --force" | grep -E "git push.*--force"
+```
+
+### Too Many Prompts
+
+Add common safe operations to allow:
+```yaml
+allow:
+  - pattern: "npm install"
+  - pattern: "npm run build"
+  - pattern: "git status"
+```
+
+### Blocking Safe Commands
+
+Check pattern specificity:
+```yaml
+# Too broad:
+- pattern: "rm"
+
+# Better:
+- pattern: "rm -rf /"
+```
+
+---
+
+## Related
+
+- [Security Scanning](./security-scanning.md) - Code security
+- [Checkpoint/Rollback](./checkpoint-rollback.md) - Recovery
+- [Configuration](../configuration/all-options.md) - All settings

package/.claude/docs/knowledge-base/06-safety-guardrails/security-scanning.md

@@ -0,0 +1,291 @@
+# Security Scanning
+
+Pre-commit security checks for vulnerabilities.
+
+---
+
+## Purpose
+
+Security scanning detects:
+- Hardcoded secrets
+- SQL/XSS injection patterns
+- Known npm vulnerabilities
+- Sensitive data exposure
+
+---
+
+## Configuration
+
+```json
+{
+  "security": {
+    "scanBeforeCommit": true,
+    "blockOnHigh": true,
+    "checkPatterns": {
+      "secrets": true,
+      "injection": true,
+      "npmAudit": true
+    },
+    "ignoreFiles": ["*.test.ts", "*.spec.ts"]
+  }
+}
+```
+
+---
+
+## Scan Types
+
+### Secrets Detection
+
+Finds hardcoded credentials:
+
+| Pattern | Example |
+|---------|---------|
+| API Keys | `api_key: "sk-..."` |
+| Passwords | `password = "secret123"` |
+| Tokens | `AUTH_TOKEN=eyJhbG...` |
+| Private Keys | `-----BEGIN RSA PRIVATE KEY-----` |
+
+### Injection Patterns
+
+Detects vulnerable code:
+
+| Type | Example |
+|------|---------|
+| SQL Injection | `query("SELECT * FROM users WHERE id=" + userId)` |
+| XSS | `innerHTML = userInput` |
+| Command Injection | `exec(userInput)` |
+
+### NPM Audit
+
+Checks dependencies for known vulnerabilities:
+
+```bash
+npm audit --production
+```
+
+---
+
+## When Scans Run
+
+| Trigger | Condition |
+|---------|-----------|
+| Before Commit | `scanBeforeCommit: true` |
+| Quality Gates | `security` in qualityGates |
+| Manual | `flow security scan` |
+
+---
+
+## Scan Results
+
+### Clean Scan
+
+```
+Security scan results:
+  ✓ No secrets detected
+  ✓ No injection patterns found
+  ✓ npm audit: 0 vulnerabilities
+
+All checks passed!
+```
+
+### Issues Found
+
+```
+Security scan results:
+
+  ⚠️ Potential secret detected:
+     src/config.ts:15
+     const API_KEY = "sk-abc123..."
+
+  ⚠️ SQL injection pattern:
+     src/services/UserService.ts:42
+     const query = "SELECT * FROM users WHERE id=" + id;
+
+  ❌ npm audit: 3 vulnerabilities
+     2 moderate, 1 high
+     Run: npm audit fix
+
+Block commit? Yes (blockOnHigh: true)
+```
+
+---
+
+## Severity Levels
+
+| Level | Blocking | Description |
+|-------|----------|-------------|
+| Critical | Always | Severe vulnerability |
+| High | If `blockOnHigh` | Significant risk |
+| Moderate | Warning | Should fix |
+| Low | Info | Minor issue |
+
+---
+
+## Ignoring Files
+
+Exclude test files and other non-production code:
+
+```json
+{
+  "security": {
+    "ignoreFiles": [
+      "*.test.ts",
+      "*.spec.ts",
+      "*.mock.ts",
+      "fixtures/*",
+      "cypress/*"
+    ]
+  }
+}
+```
+
+---
+
+## False Positives
+
+### Inline Ignore
+
+```typescript
+// security-ignore: example API key for tests
+const EXAMPLE_KEY = "sk-example-not-real";
+```
+
+### Pattern Whitelist
+
+```json
+{
+  "security": {
+    "whitelist": [
+      "EXAMPLE_KEY",
+      "TEST_TOKEN"
+    ]
+  }
+}
+```
+
+---
+
+## Custom Patterns
+
+Add project-specific patterns:
+
+```json
+{
+  "security": {
+    "customPatterns": [
+      {
+        "name": "internal-token",
+        "pattern": "INTERNAL_.*=\\w{32,}",
+        "severity": "high",
+        "message": "Internal token should not be hardcoded"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Fixing Issues
+
+### Secrets
+
+Replace with environment variables:
+
+```typescript
+// Before
+const API_KEY = "sk-abc123...";
+
+// After
+const API_KEY = process.env.API_KEY;
+```
+
+### SQL Injection
+
+Use parameterized queries:
+
+```typescript
+// Before
+const query = "SELECT * FROM users WHERE id=" + id;
+
+// After
+const query = "SELECT * FROM users WHERE id = ?";
+db.query(query, [id]);
+```
+
+### NPM Vulnerabilities
+
+```bash
+# Auto-fix
+npm audit fix
+
+# Force fix (may include breaking changes)
+npm audit fix --force
+
+# Manual update
+npm update vulnerable-package
+```
+
+---
+
+## Integration with CI/CD
+
+Run scans in pipeline:
+
+```yaml
+# .github/workflows/security.yml
+- name: Security Scan
+  run: ./scripts/flow security scan --ci
+```
+
+### CI Mode
+
+```bash
+flow security scan --ci
+
+# Exit code 1 if high severity found
+# JSON output for parsing
+```
+
+---
+
+## Best Practices
+
+1. **Scan Before Commit**: Catch issues early
+2. **Block on High**: Don't let serious issues through
+3. **Update Dependencies**: Run npm audit regularly
+4. **Use .env Files**: Never commit secrets
+5. **Review False Positives**: Update whitelist
+
+---
+
+## Troubleshooting
+
+### Too Many False Positives
+
+- Add to ignoreFiles
+- Update whitelist
+- Use inline ignores
+
+### Scan Too Slow
+
+- Reduce files scanned
+- Disable npmAudit for each commit
+- Run full scan on CI only
+
+### npm audit Fails
+
+Check npm is installed and node_modules exists:
+```bash
+npm install
+npm audit
+```
+
+---
+
+## Related
+
+- [Damage Control](./damage-control.md) - Command protection
+- [Commit Gates](./commit-gates.md) - Approval workflow
+- [Quality Gates](../02-task-execution/03-verification.md) - Verification

package/.claude/docs/knowledge-base/README.md

@@ -0,0 +1,92 @@
+# WogiFlow Knowledge Base
+
+Welcome to the comprehensive knowledge base for WogiFlow, an AI workflow framework that ensures structured, high-quality code execution.
+
+## Quick Navigation
+
+| Category | Purpose | Start Here |
+|----------|---------|------------|
+| [Setup & Onboarding](./01-setup-onboarding/) | Initial setup, codebase analysis, populating workflow files | [Installation](./01-setup-onboarding/installation.md) |
+| [Task Execution](./02-task-execution/) | The `/wogi-start` pipeline - how tasks are enforced and completed | [Execution Flow](./02-task-execution/README.md) |
+| [Self-Improvement](./03-self-improvement/) | How WogiFlow learns and improves over time | [Learning Overview](./03-self-improvement/README.md) |
+| [Memory & Context](./04-memory-context/) | Preventing hallucinations, managing context, session persistence | [Context Management](./04-memory-context/context-management.md) |
+| [Development Tools](./05-development-tools/) | Figma analyzer, code traces, MCP integrations | [Tools Overview](./05-development-tools/README.md) |
+| [Safety & Guardrails](./06-safety-guardrails/) | Damage control, security scanning, checkpoint/rollback | [Safety Overview](./06-safety-guardrails/README.md) |
+| [Configuration](./configuration/) | Complete reference for all 200+ config options | [All Options](./configuration/all-options.md) |
+| [Future Features](./future-features.md) | Roadmap and planned features | [Roadmap](./future-features.md) |
+
+---
+
+## Quick Start
+
+### Install
+```bash
+npm install wogiflow
+```
+
+### Analyze Existing Project
+```bash
+npx flow onboard
+```
+
+### Start Working
+```bash
+/wogi-ready          # See available tasks
+/wogi-start TASK-XXX # Start a task
+```
+
+---
+
+## How This Knowledge Base Is Organized
+
+Unlike feature-by-feature documentation, this knowledge base is organized by **purpose** - what you're trying to accomplish:
+
+### 1. Setting Up (Once per project)
+Everything in [01-setup-onboarding](./01-setup-onboarding/) helps you get WogiFlow configured for your project. This includes analyzing your codebase, populating decisions and component registries, and setting up team sync.
+
+### 2. Executing Tasks (Daily workflow)
+The [02-task-execution](./02-task-execution/) category is the heart of WogiFlow. It explains the entire execution pipeline from task selection through completion, including:
+- Why task gating prevents incomplete work
+- How loops ensure acceptance criteria are met
+- Trade-offs between thoroughness and token consumption
+
+### 3. Getting Smarter Over Time
+[03-self-improvement](./03-self-improvement/) explains how WogiFlow learns from corrections and improves at four levels: project, skill, model, and team.
+
+### 4. Managing Context & Memory
+[04-memory-context](./04-memory-context/) addresses the biggest challenge in AI coding: context window limits and session persistence. These features prevent hallucinations and preserve history.
+
+### 5. Accelerating Development
+[05-development-tools](./05-development-tools/) covers additional tools that speed up specific workflows like design-to-code and understanding codebases.
+
+### 6. Staying Safe
+[06-safety-guardrails](./06-safety-guardrails/) documents protections against mistakes, including pattern-based damage control, security scanning, and recovery systems.
+
+---
+
+## Common Tasks
+
+| I want to... | Read this |
+|--------------|-----------|
+| Set up WogiFlow for the first time | [Installation](./01-setup-onboarding/installation.md) |
+| Understand how task execution works | [Execution Flow](./02-task-execution/README.md) |
+| Configure loops and verification | [Execution Loop](./02-task-execution/02-execution-loop.md) |
+| Reduce token consumption | [Trade-offs](./02-task-execution/trade-offs.md) |
+| Set up hybrid mode (local LLM) | [Execution Loop](./02-task-execution/02-execution-loop.md#hybrid-mode) |
+| Understand how learning works | [Self-Improvement](./03-self-improvement/README.md) |
+| Fix context/hallucination issues | [Context Management](./04-memory-context/context-management.md) |
+| Use Figma-to-code | [Figma Analyzer](./05-development-tools/figma-analyzer.md) |
+| Set up safety guardrails | [Damage Control](./06-safety-guardrails/damage-control.md) |
+| Find a specific config option | [All Options](./configuration/all-options.md) |
+| Import tasks from Jira/Linear | [External Integrations](./02-task-execution/external-integrations.md) |
+| Load PRD/specs for context | [PRD Management](./04-memory-context/prd-management.md) |
+| Manage memory & entropy | [Memory Commands](./04-memory-context/memory-commands.md) |
+| Configure multiple models | [Model Management](./02-task-execution/model-management.md) |
+
+---
+
+## Related Resources
+
+- [Command Reference](../commands.md) - All slash commands
+- [Main README](../../../README.md) - Project overview
+- [CLAUDE.md](../../../CLAUDE.md) - Workflow methodology