myconvergio 2.1.0

package/.claude/rules/ethical-guidelines.md

@@ -0,0 +1,383 @@
+# Ethical Guidelines
+
+> This rule is enforced by the MyConvergio agent ecosystem.
+
+## Overview
+Technology has profound impact on individuals and society. All development in the MyConvergio ecosystem must adhere to ethical principles that prioritize user welfare, privacy, accessibility, and fairness. These guidelines complement our [CONSTITUTION.md](../CONSTITUTION.md) and ensure responsible, inclusive technology development.
+
+## Requirements
+
+### User Privacy Protection
+- Collect only necessary data (data minimization principle)
+- Obtain explicit consent before collecting personal information
+- Provide clear, understandable privacy policies
+- Implement privacy by design and by default
+- Allow users to access, modify, and delete their data
+- Encrypt sensitive data in transit and at rest
+- Comply with GDPR, CCPA, and relevant privacy regulations
+- Regular privacy impact assessments
+
+### Accessibility (WCAG 2.1 AA Compliance)
+- All user interfaces must be keyboard navigable
+- Provide text alternatives for non-text content
+- Ensure sufficient color contrast (4.5:1 for normal text)
+- Support screen readers and assistive technologies
+- Provide captions for audio/video content
+- Allow text resizing up to 200% without loss of functionality
+- Design for diverse abilities (motor, visual, auditory, cognitive)
+- Test with actual users with disabilities
+
+### Inclusive Language
+- Use gender-neutral language in code and documentation
+- Avoid terms with historical negative connotations (blacklist/whitelist → blocklist/allowlist)
+- Use person-first language when discussing disabilities
+- Avoid cultural assumptions in examples and defaults
+- Support internationalization and localization
+- Be mindful of cultural sensitivities in imagery and content
+- Use clear, simple language (avoid jargon when possible)
+
+### Non-Discriminatory Algorithms
+- Audit algorithms for bias across protected characteristics
+- Ensure training data represents diverse populations
+- Test for disparate impact on different demographic groups
+- Document limitations and potential biases in AI/ML systems
+- Provide explanations for automated decisions affecting users
+- Enable human review for high-stakes decisions
+- Monitor deployed systems for emerging biases
+
+### Transparency in AI Decisions
+- Clearly disclose when users interact with AI systems
+- Provide explanations for AI-driven recommendations
+- Allow users to opt out of automated decision-making when possible
+- Document AI model capabilities and limitations
+- Make training data sources transparent (when appropriate)
+- Provide confidence scores for AI predictions
+- Enable user feedback on AI decisions
+
+### Data Minimization
+- Collect only data necessary for stated purposes
+- Delete data when no longer needed
+- Avoid "just in case" data collection
+- Aggregate or anonymize data when possible
+- Provide users with data portability
+- Regular data audits to remove unnecessary information
+- Clear data retention policies
+
+### Consent and Control
+- Obtain informed consent for data collection
+- Use clear, plain language in consent requests
+- Granular consent options (not all-or-nothing)
+- Easy-to-use privacy controls and preferences
+- Respect "Do Not Track" and similar signals
+- Allow consent withdrawal at any time
+- No dark patterns or manipulative design
+
+### Security as User Protection
+- Security measures protect users, not just systems
+- Prompt notification of data breaches
+- Secure defaults (opt-in for sharing, not opt-out)
+- Regular security audits and penetration testing
+- Vulnerability disclosure program
+- User education about security features
+
+### Environmental Responsibility
+- Optimize code for energy efficiency
+- Consider carbon footprint of infrastructure choices
+- Use renewable energy for hosting when possible
+- Implement efficient caching and data transfer strategies
+- Monitor and reduce resource consumption
+
+### Honesty and Integrity
+- Never mislead users about product capabilities
+- Clearly communicate limitations and risks
+- Acknowledge and fix mistakes promptly
+- No deceptive design patterns
+- Transparent about business model and incentives
+- Honest marketing and feature claims
+
+## Examples
+
+### Good Examples
+
+#### Privacy by Design
+```typescript
+// Good: Minimal data collection with explicit consent
+interface UserRegistration {
+  email: string;          // Required for account
+  name: string;           // Required for personalization
+  // Optional fields require separate consent
+  marketingConsent?: boolean;
+  analyticsConsent?: boolean;
+}
+
+const registerUser = async (data: UserRegistration) => {
+  // Only collect consented data
+  const userData = {
+    email: data.email,
+    name: data.name,
+    preferences: {
+      marketing: data.marketingConsent ?? false,
+      analytics: data.analyticsConsent ?? false
+    },
+    createdAt: new Date()
+  };
+
+  // No tracking without consent
+  if (userData.preferences.analytics) {
+    trackEvent('user_registered');
+  }
+
+  return await createUser(userData);
+};
+```
+
+#### Accessible UI Components
+```typescript
+// Good: Accessible button with ARIA labels
+const AccessibleButton: React.FC<{
+  onClick: () => void;
+  icon: React.ReactNode;
+  label: string;
+}> = ({ onClick, icon, label }) => {
+  return (
+    <button
+      onClick={onClick}
+      aria-label={label}
+      className="btn"
+      // Ensure focus is visible
+      style={{ outline: '2px solid transparent' }}
+      onFocus={(e) => e.target.style.outline = '2px solid blue'}
+      onBlur={(e) => e.target.style.outline = '2px solid transparent'}
+    >
+      {icon}
+      <span className="sr-only">{label}</span>
+    </button>
+  );
+};
+
+// Good: Sufficient color contrast
+const styles = {
+  text: {
+    color: '#1a1a1a',        // Dark text
+    backgroundColor: '#ffffff' // White background
+    // Contrast ratio: 18.5:1 (exceeds WCAG AAA)
+  },
+  link: {
+    color: '#0066cc',        // Blue link
+    textDecoration: 'underline' // Not relying on color alone
+    // Contrast ratio: 8.6:1 (exceeds WCAG AA)
+  }
+};
+```
+
+#### Inclusive Language
+```python
+# Good: Inclusive terminology
+ALLOWED_DOMAINS = ['example.com', 'trusted.com']  # Instead of "whitelist"
+BLOCKED_DOMAINS = ['spam.com', 'malicious.com']   # Instead of "blacklist"
+
+# Good: Gender-neutral language
+def notify_users(users: list[User]) -> None:
+    """Send notifications to users."""
+    for user in users:
+        send_email(user.email, f"Hello {user.name}")  # Not "Hi guys"
+
+# Good: Person-first language
+class AccessibilityFeature:
+    """Features for users with visual impairments."""
+    # Not "features for blind users" or "for the disabled"
+```
+
+#### Bias Detection in ML
+```python
+# Good: Audit model for bias across demographics
+def audit_model_fairness(
+    model: Model,
+    test_data: pd.DataFrame,
+    protected_attributes: list[str]
+) -> FairnessReport:
+    """Audit ML model for bias across protected characteristics.
+
+    Args:
+        model: Trained ML model to audit
+        test_data: Test dataset with demographic attributes
+        protected_attributes: Attributes to check for bias (race, gender, age)
+
+    Returns:
+        FairnessReport with metrics across demographic groups
+    """
+    report = FairnessReport()
+
+    for attr in protected_attributes:
+        for group_value in test_data[attr].unique():
+            group_data = test_data[test_data[attr] == group_value]
+            predictions = model.predict(group_data)
+
+            # Calculate metrics for this demographic group
+            accuracy = calculate_accuracy(predictions, group_data['label'])
+            false_positive_rate = calculate_fpr(predictions, group_data['label'])
+
+            report.add_group_metrics(attr, group_value, {
+                'accuracy': accuracy,
+                'false_positive_rate': false_positive_rate,
+                'sample_size': len(group_data)
+            })
+
+    # Flag disparate impact
+    if report.has_disparate_impact(threshold=0.8):
+        logger.warning(f"Model shows disparate impact: {report.summary()}")
+
+    return report
+```
+
+#### Transparent AI Disclosure
+```typescript
+// Good: Clear AI disclosure with explanation
+const AIRecommendation: React.FC<{ recommendation: Product }> = ({
+  recommendation
+}) => {
+  return (
+    <div className="ai-recommendation">
+      <div className="ai-badge" role="status" aria-label="AI-generated recommendation">
+        <RobotIcon /> AI Recommendation
+      </div>
+      <ProductCard product={recommendation} />
+      <details>
+        <summary>Why are we recommending this?</summary>
+        <p>
+          This recommendation is based on:
+          <ul>
+            <li>Your recent browsing history</li>
+            <li>Similar users' preferences</li>
+            <li>Product popularity in your region</li>
+          </ul>
+          <a href="/privacy/ai-recommendations">
+            Learn more about our recommendation system
+          </a>
+        </p>
+      </details>
+      <button onClick={handleOptOut}>
+        Don't show AI recommendations
+      </button>
+    </div>
+  );
+};
+```
+
+### Bad Examples
+
+#### Privacy Violations
+```typescript
+// Bad: Excessive data collection without consent
+interface UserRegistration {
+  email: string;
+  name: string;
+  phoneNumber: string;        // Why do we need this?
+  dateOfBirth: string;        // Why do we need this?
+  location: GeoLocation;      // Collected without consent!
+  deviceFingerprint: string;  // Tracking without disclosure!
+}
+
+// Bad: Sharing data without consent
+const registerUser = async (data: UserRegistration) => {
+  await createUser(data);
+
+  // Sharing with third parties without consent!
+  await sendToAnalytics(data);
+  await sendToMarketingPartner(data);
+  await trackUserBehavior(data);
+};
+```
+
+#### Inaccessible Design
+```typescript
+// Bad: Not keyboard accessible, poor contrast
+const InaccessibleButton = ({ onClick, icon }) => {
+  return (
+    <div
+      onClick={onClick}  // Not keyboard accessible!
+      style={{
+        color: '#999',           // Poor contrast
+        backgroundColor: '#aaa'  // Contrast ratio: 1.7:1 (fails WCAG)
+      }}
+    >
+      {icon}
+      {/* No text label for screen readers! */}
+    </div>
+  );
+};
+```
+
+#### Biased Algorithm
+```python
+# Bad: No bias checking, discriminatory features
+def predict_loan_approval(applicant: dict) -> bool:
+    """Predict if loan should be approved."""
+    # Using protected characteristics directly!
+    if applicant['zip_code'] in LOW_INCOME_ZIPS:  # Proxy for race
+        return False
+    if applicant['gender'] == 'female':  # Direct discrimination
+        return False
+    if applicant['age'] > 65:  # Age discrimination
+        return False
+    return True
+    # No fairness audit, no explanation provided
+```
+
+#### Dark Patterns
+```typescript
+// Bad: Deceptive design patterns
+const NewsletterSignup = () => {
+  return (
+    <div>
+      <h2>Complete Your Registration</h2>
+      {/* Deceptive: Makes it seem required */}
+      <label>
+        <input type="checkbox" checked={true} />
+        <small style={{ color: '#999' }}>
+          I agree to receive marketing emails, share data with partners,
+          and allow tracking across websites
+        </small>
+        {/* Bad: Pre-checked, tiny text, bundled consent */}
+      </label>
+
+      {/* Deceptive: Prominent "agree" vs hidden "decline" */}
+      <button className="big-green-button">
+        AGREE AND CONTINUE
+      </button>
+      <a href="/decline" style={{ fontSize: '10px', color: '#999' }}>
+        No thanks
+      </a>
+    </div>
+  );
+};
+```
+
+#### Non-Inclusive Language
+```python
+# Bad: Non-inclusive terminology
+WHITELIST = ['allowed.com']  # Use "allowlist"
+BLACKLIST = ['blocked.com']  # Use "blocklist"
+
+def notify_users(users):
+    """Send notifications to users."""
+    for user in users:
+        # Bad: Gender assumption
+        send_email(user.email, f"Hey guys, ...")
+
+# Bad: Insensitive terminology
+MASTER_SERVER = 'main.example.com'  # Use "primary" or "main"
+SLAVE_SERVERS = ['replica1', 'replica2']  # Use "replica" or "secondary"
+```
+
+## References
+- [MyConvergio CONSTITUTION.md](../CONSTITUTION.md)
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [GDPR Compliance](https://gdpr.eu/)
+- [Inclusive Design Principles](https://inclusivedesignprinciples.org/)
+- [AI Ethics Guidelines by IEEE](https://standards.ieee.org/industry-connections/ec/autonomous-systems/)
+- [Algorithmic Fairness](https://fairmlbook.org/)
+- [Inclusive Naming Initiative](https://inclusivenaming.org/)
+- [Dark Patterns Hall of Shame](https://www.darkpatterns.org/)
+- [Privacy by Design Principles](https://www.ipc.on.ca/wp-content/uploads/resources/7foundationalprinciples.pdf)
+- [UN Sustainable Development Goals](https://sdgs.un.org/)

package/.claude/rules/security-requirements.md

@@ -0,0 +1,182 @@
+# Security Requirements
+
+> This rule is enforced by the MyConvergio agent ecosystem.
+
+## Overview
+Security is a first-class concern in the MyConvergio ecosystem. All code must adhere to industry-standard security practices, with awareness of OWASP Top 10 vulnerabilities and implementation of defense-in-depth strategies.
+
+## Requirements
+
+### Input Validation
+- Validate all user input on both client and server side
+- Use allowlists (whitelist) over denylists (blacklist) when possible
+- Sanitize input before processing or storage
+- Implement length limits on all text inputs
+- Validate data types, formats, and ranges
+- Reject unexpected or malformed input
+
+### SQL Security
+- Always use parameterized queries or prepared statements
+- Never concatenate user input into SQL strings
+- Use ORM frameworks with built-in protection (SQLAlchemy, Prisma)
+- Apply principle of least privilege for database accounts
+- Implement connection pooling with proper timeout settings
+
+### Cross-Site Scripting (XSS) Prevention
+- Escape all user-generated content before rendering in HTML
+- Use Content Security Policy (CSP) headers
+- Sanitize HTML input using established libraries (DOMPurify)
+- Never use `dangerouslySetInnerHTML` without sanitization
+- Set appropriate `X-Content-Type-Options` headers
+
+### Secrets Management
+- Never commit secrets, API keys, or credentials to version control
+- Use environment variables for all sensitive configuration
+- Use secret management services (HashiCorp Vault, AWS Secrets Manager)
+- Rotate secrets regularly
+- Use `.env` files locally, never commit them (`.gitignore`)
+- Use different secrets for different environments
+
+### Authentication & Authorization
+- Implement proper authentication for all protected resources
+- Use industry-standard protocols (OAuth 2.0, OpenID Connect)
+- Implement role-based access control (RBAC)
+- Verify authorization on every request (server-side)
+- Use secure session management
+- Implement account lockout after failed login attempts
+- Require strong passwords (minimum length, complexity)
+
+### HTTPS & Transport Security
+- Use HTTPS for all external communication
+- Implement HSTS (HTTP Strict Transport Security)
+- Use secure cookies (`Secure`, `HttpOnly`, `SameSite` flags)
+- Validate SSL/TLS certificates
+- Use TLS 1.2 or higher
+
+### Dependencies & Supply Chain
+- Keep all dependencies up to date
+- Use dependency scanning tools (Snyk, npm audit, safety)
+- Review security advisories regularly
+- Pin dependency versions in production
+- Verify package integrity using checksums
+
+### Error Handling & Logging
+- Never expose stack traces or internal details to users
+- Log security events (failed logins, access violations)
+- Sanitize logs to prevent log injection
+- Implement rate limiting to prevent abuse
+- Monitor for suspicious patterns
+
+## Examples
+
+### Good Examples
+
+#### SQL Parameterization (Python)
+```python
+# Good: Parameterized query
+def get_user_by_email(email: str) -> Optional[User]:
+    query = "SELECT * FROM users WHERE email = ?"
+    result = db.execute(query, (email,))
+    return result.fetchone()
+
+# Good: ORM usage
+def get_user_by_email(email: str) -> Optional[User]:
+    return db.query(User).filter(User.email == email).first()
+```
+
+#### Input Validation (TypeScript)
+```typescript
+// Good: Comprehensive validation
+const validateEmail = (email: string): boolean => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return email.length <= 255 && emailRegex.test(email);
+};
+
+const createUser = async (email: string, name: string) => {
+  if (!validateEmail(email)) {
+    throw new ValidationError('Invalid email format');
+  }
+  if (name.length < 2 || name.length > 100) {
+    throw new ValidationError('Name must be 2-100 characters');
+  }
+  // Proceed with sanitized input
+};
+```
+
+#### Secrets Management
+```typescript
+// Good: Environment variables
+const apiKey = process.env.STRIPE_API_KEY;
+if (!apiKey) {
+  throw new Error('STRIPE_API_KEY not configured');
+}
+
+// Good: .env file (not committed)
+// .env
+STRIPE_API_KEY=sk_live_xxxxxxxxxxxxx
+DATABASE_URL=postgresql://user:pass@host:5432/db
+```
+
+#### XSS Prevention (React)
+```typescript
+// Good: Sanitized HTML
+import DOMPurify from 'dompurify';
+
+const SafeHtmlDisplay = ({ htmlContent }: { htmlContent: string }) => {
+  const sanitized = DOMPurify.sanitize(htmlContent);
+  return <div dangerouslySetInnerHTML={{ __html: sanitized }} />;
+};
+
+// Good: Escaped by default
+const UserComment = ({ comment }: { comment: string }) => {
+  return <p>{comment}</p>; // React escapes by default
+};
+```
+
+### Bad Examples
+
+#### SQL Injection Vulnerability
+```python
+# Bad: String concatenation - SQL injection risk!
+def get_user_by_email(email: str):
+    query = f"SELECT * FROM users WHERE email = '{email}'"
+    return db.execute(query)
+# Attacker can use: email = "'; DROP TABLE users; --"
+```
+
+#### Hardcoded Secrets
+```typescript
+// Bad: Secret in code!
+const API_KEY = 'NEVER_HARDCODE_SECRETS_USE_ENV_VARS';
+fetch('https://api.stripe.com/v1/charges', {
+  headers: { 'Authorization': `Bearer ${API_KEY}` }
+});
+```
+
+#### No Input Validation
+```typescript
+// Bad: No validation
+const createUser = async (email: string, age: number) => {
+  await db.users.create({ email, age });
+  // What if email is malicious HTML? What if age is -1000?
+};
+```
+
+#### XSS Vulnerability
+```typescript
+// Bad: Unescaped user content
+const UserProfile = ({ bio }: { bio: string }) => {
+  return <div dangerouslySetInnerHTML={{ __html: bio }} />;
+  // Attacker can inject: <script>steal_cookies()</script>
+};
+```
+
+## References
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)
+- [CWE Top 25 Most Dangerous Software Weaknesses](https://cwe.mitre.org/top25/)
+- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
+- [MyConvergio Security Framework](../frameworks/security-framework.md)
+- [SQLAlchemy Security Considerations](https://docs.sqlalchemy.org/en/20/faq/security.html)
+- [OWASP SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html)
+- [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)