ac-framework 1.2.0 → 1.3.0

package/framework/.cospec/skills/secure-coding-cybersecurity/references/ai_coding_pitfalls.md

@@ -0,0 +1,44 @@
+# AI-Generated Code: Security Pitfalls & Anti-Patterns
+
+This document lists the most common security errors made by LLMs when generating code. As an AI agent, you **MUST AVOID** these patterns and explicitly check for them in your output.
+
+## 1. The "Working but Insecure" Default
+LLMs prioritize functionality over security. They often provide the simplest code that works, which is usually the least secure.
+- **NEVER** skip input validation because it "makes the example cleaner."
+- **NEVER** use `http` when `https` is available.
+- **NEVER** disable SSL/TLS certificate verification for "easier testing."
+
+## 2. Dependency Hallucinations & Slopsquatting
+LLMs may suggest non-existent libraries or versions.
+- **NEVER** suggest a library without verifying its existence and reputation.
+- **BEWARE** of "slopsquatting": attackers registering hallucinated package names with malicious code.
+- **ALWAYS** prefer well-known, standard libraries over obscure ones suggested by the model.
+
+## 3. Stale & Outdated Security Patterns
+LLMs are trained on historical data and often suggest patterns that were "okay" years ago but are now insecure.
+- **DO NOT** use `MD5` or `SHA1` for password hashing; use `Argon2` or `bcrypt`.
+- **DO NOT** use `random.random()` for security-sensitive tokens; use `secrets` module in Python or `crypto.getRandomValues()` in JS.
+- **DO NOT** use deprecated APIs (e.g., `os.system()` when `subprocess.run()` with proper arguments is safer).
+
+## 4. Hardcoded Secrets & Debug Flags
+To make code "run out of the box," LLMs often hardcode sensitive values.
+- **NEVER** include hardcoded API keys, passwords, or tokens. Use environment variables.
+- **NEVER** leave `debug=True` or verbose error reporting enabled in "production-ready" snippets.
+
+## 5. Missing Contextual Security
+LLMs often miss the "big picture" of an application's security.
+- **DO NOT** assume authentication happened elsewhere. Always verify authorization at the function/endpoint level.
+- **DO NOT** suggest CORS configurations like `Access-Control-Allow-Origin: *` unless explicitly required and justified.
+
+## 6. Injection Vulnerabilities (The Most Common Error)
+LLMs frequently fall back to string concatenation for queries and commands.
+- **NEVER** use f-strings or string formatting for SQL queries. Use parameterized inputs.
+- **NEVER** pass unsanitized user input directly to shell commands.
+
+## AI Security Checklist (Before Delivering Code)
+1. [ ] Did I use any hallucinated or obscure libraries?
+2. [ ] Are all inputs validated and sanitized?
+3. [ ] Did I use the most modern, secure cryptographic standards?
+4. [ ] Are there any hardcoded secrets or debug flags?
+5. [ ] Does the code "fail closed" on errors?
+6. [ ] Did I verify permissions at the point of data access?

package/framework/.cospec/skills/secure-coding-cybersecurity/references/owasp_top_10_2025.md

@@ -0,0 +1,28 @@
+# OWASP Top 10:2025 Reference
+
+The OWASP Top 10 is the standard awareness document for developers and web application security. It represents a broad consensus about the most critical security risks to web applications.
+
+| ID | Name | Description | Key Prevention |
+| :--- | :--- | :--- | :--- |
+| **A01:2025** | **Broken Access Control** | Users can act outside of their intended permissions. | Implement least privilege; check permissions on every request. |
+| **A02:2025** | **Security Misconfiguration** | Insecure default settings, incomplete configurations, or open cloud storage. | Automate hardening; remove unused features/debug modes. |
+| **A03:2025** | **Software Supply Chain Failures** | Risks from third-party libraries, dependencies, and CI/CD pipelines. | Use SBOMs; verify signatures; use dependency scanning (SCA). |
+| **A04:2025** | **Cryptographic Failures** | Use of weak or no encryption for sensitive data. | Use strong algorithms (Argon2, AES-GCM); encrypt data at rest/transit. |
+| **A05:2025** | **Injection** | Malicious data sent to an interpreter (SQL, NoSQL, OS Command). | Use parameterized queries; validate and sanitize all inputs. |
+| **A06:2025** | **Insecure Design** | Flaws in the application's architecture and design. | Use secure design patterns; perform threat modeling early. |
+| **A07:2025** | **Authentication Failures** | Weaknesses in identity verification, session management, or password policies. | Implement MFA; use secure session managers; enforce strong passwords. |
+| **A08:2025** | **Software and Data Integrity Failures** | Insecure deserialization or lack of integrity checks on updates/data. | Sign code/data; verify integrity before processing; avoid insecure deserialization. |
+| **A09:2025** | **Security Logging & Alerting Failures** | Insufficient logging or monitoring to detect and respond to active attacks. | Log security events; implement real-time alerting; centralize logs. |
+| **A10:2025** | **Mishandling of Exceptional Conditions** | Improper error handling, failing open, or leaking info via error messages. | Fail closed; use generic error messages; handle all exceptions. |
+
+## Deep Dive: New/Updated Categories
+
+### A03:2025 Software Supply Chain Failures
+This category focuses on the risks associated with the components and services that make up the software development life cycle.
+- **Vulnerabilities**: Using libraries with known vulnerabilities (CVEs), dependency confusion attacks, compromised build pipelines.
+- **Prevention**: Generate and maintain a **Software Bill of Materials (SBOM)**, use tools like `npm audit`, `pip-audit`, or Snyk.
+
+### A10:2025 Mishandling of Exceptional Conditions
+Focuses on how the application behaves when things go wrong.
+- **Vulnerabilities**: "Fail-open" logic (e.g., if an auth check throws an error, it defaults to 'allow'), leaking stack traces or sensitive environment variables in error responses.
+- **Prevention**: Always "Fail-closed". Ensure that if an error occurs during a security check, access is denied by default.

package/framework/.cospec/skills/secure-coding-cybersecurity/references/secure_coding_examples.md

@@ -0,0 +1,102 @@
+# Secure Coding Examples
+
+This document provides comparisons between vulnerable and secure code across multiple languages.
+
+## 1. Injection (A05:2025) - SQL Injection
+
+### Python (Insecure)
+```python
+# VULNERABLE: String formatting allows SQL injection
+cursor.execute(f"SELECT * FROM users WHERE username = '{username}'")
+```
+
+### Python (Secure)
+```python
+# SECURE: Use parameterized queries
+cursor.execute("SELECT * FROM users WHERE username = %s", (username,))
+```
+
+### Node.js (Secure)
+```javascript
+// SECURE: Using placeholders in pg-promise or similar
+db.any('SELECT * FROM users WHERE username = $1', [username]);
+```
+
+---
+
+## 2. Broken Access Control (A01:2025) - IDOR
+
+### Node.js (Insecure)
+```javascript
+// VULNERABLE: No check if the user owns the record
+app.get('/api/invoice/:id', async (req, res) => {
+    const invoice = await db.getInvoice(req.params.id);
+    res.json(invoice);
+});
+```
+
+### Node.js (Secure)
+```javascript
+// SECURE: Verify ownership
+app.get('/api/invoice/:id', async (req, res) => {
+    const invoice = await db.getInvoice(req.params.id);
+    if (invoice.userId !== req.user.id) {
+        return res.status(403).send('Forbidden');
+    }
+    res.json(invoice);
+});
+```
+
+---
+
+## 3. Cryptographic Failures (A04:2025) - Password Hashing
+
+### Python (Secure)
+```python
+import argon2
+
+ph = argon2.PasswordHasher()
+hash = ph.hash("my_secure_password")
+# To verify:
+ph.verify(hash, "user_input_password")
+```
+
+---
+
+## 4. Mishandling of Exceptional Conditions (A10:2025) - Fail Closed
+
+### Java (Insecure)
+```java
+// VULNERABLE: Fail-open logic
+public boolean isAuthorized(User user) {
+    try {
+        return ldapService.checkAccess(user);
+    } catch (Exception e) {
+        // If service is down, it might return true or allow bypass
+        return true; 
+    }
+}
+```
+
+### Java (Secure)
+```java
+// SECURE: Fail-closed logic
+public boolean isAuthorized(User user) {
+    try {
+        return ldapService.checkAccess(user);
+    } catch (Exception e) {
+        logger.error("Auth service error", e);
+        return false; // Access denied by default
+    }
+}
+```
+
+---
+
+## 5. Software Supply Chain (A03:2025) - Dependency Management
+
+### Best Practices
+- **Python**: Use `pip-audit` to check for known vulnerabilities.
+- **Node.js**: Use `npm audit` or `pnpm audit`.
+- **General**: Use a Lockfile (`package-lock.json`, `poetry.lock`) to ensure consistent builds.
+- **SBOM**: Generate an SBOM using tools like `syft` or `cyclonedx-cli`.

package/framework/.cospec/skills/secure-coding-cybersecurity/scripts/security_audit.py

@@ -0,0 +1,46 @@
+import re
+import os
+import sys
+
+# Common patterns for hardcoded secrets and vulnerable code
+PATTERNS = {
+    "Hardcoded Secret": r"(?i)(api_key|secret|password|token|access_key)\s*=\s*['\"][a-zA-Z0-9_\-]{10,}['\"]",
+    "Potential SQL Injection (Python)": r"\.execute\(f?['\"].*\{.*\}",
+    "Insecure Randomness": r"import random\s+.*random\.random\(",
+    "Weak Hashing (MD5/SHA1)": r"(md5|sha1)\(",
+    "Debug Mode Enabled": r"debug\s*=\s*True",
+}
+
+def scan_file(file_path):
+    findings = []
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            for i, line in enumerate(f, 1):
+                for name, pattern in PATTERNS.items():
+                    if re.search(pattern, line):
+                        findings.append(f"[{name}] Found at line {i}: {line.strip()}")
+    except Exception as e:
+        print(f"Error reading {file_path}: {e}")
+    return findings
+
+def main(directory):
+    all_findings = {}
+    for root, _, files in os.walk(directory):
+        for file in files:
+            if file.endswith(('.py', '.js', '.java', '.go')):
+                path = os.path.join(root, file)
+                findings = scan_file(path)
+                if findings:
+                    all_findings[path] = findings
+    
+    if not all_findings:
+        print("No obvious security issues found by this simple scanner.")
+    else:
+        for path, findings in all_findings.items():
+            print(f"\n--- Findings in {path} ---")
+            for f in findings:
+                print(f)
+
+if __name__ == "__main__":
+    target_dir = sys.argv[1] if len(sys.argv) > 1 else "."
+    main(target_dir)

package/framework/.cospec/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common