V2

.babelrc.js

@@ -0,0 +1,26 @@
+/**
+ * Babel Configuration Pointer File
+ * 
+ * This file serves as the entry point for Babel configuration and MUST remain 
+ * in the project root directory. Here's why:
+ * 
+ * What Babel does:
+ * - Transpiles modern JavaScript (ES6+) to backwards-compatible code
+ * - Enables use of latest JS features while maintaining browser/Node compatibility
+ * - Currently configured for Node.js environment via @babel/preset-env
+ * 
+ * Why this file is in the root:
+ * - Babel's file discovery mechanism looks for config files starting from the
+ *   current directory and moving upward through parent directories
+ * - Tools like Jest, bundlers, and other build tools expect to find Babel
+ *   config following this standard discovery pattern
+ * - Moving this file would break automatic detection by these tools
+ * 
+ * Project organization:
+ * - This file acts as a lightweight pointer to the actual configuration
+ * - Real config is in ./config/babel.config.js for better organization
+ * - This approach keeps tooling compatibility while organizing configs centrally
+ * 
+ * Used by: Jest (via babel-jest), and potentially other build tools
+ */
+module.exports = require('./config/babel.config.js');

.githooks/pre-push

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+# Block pushes unless the full test suite passes.
+
+set -eu
+
+echo "🧪 Running npm test before push..."
+npm test --silent || {
+  echo "❌ npm test failed; push aborted."
+  exit 1
+}
+
+echo "✅ npm test passed; proceeding with push."

.github/ISSUE_TEMPLATE/agent_task.md

@@ -0,0 +1,86 @@
+---
+name: Agent Task
+about: Task specifically designed for autonomous AI agents
+title: '[AGENT] '
+labels: ['agent-task', 'automation']
+assignees: ''
+---
+
+## Task Overview
+**Objective:**
+<!-- Clear, specific description of what the agent should accomplish -->
+
+**Priority:** <!-- High/Medium/Low -->
+
+## Detailed Requirements
+
+### Primary Goals
+- [ ] Goal 1
+- [ ] Goal 2
+- [ ] Goal 3
+
+### Technical Constraints
+- [ ] Must maintain 100% test coverage
+- [ ] Must pass all quality gates (`npm run check:all`)
+- [ ] Must follow existing code patterns
+- [ ] Must not introduce breaking changes
+
+### Success Criteria
+<!-- Very specific, measurable criteria for completion -->
+- [ ] All tests pass: `npm test`
+- [ ] Quality checks pass: `npm run check:all`
+- [ ] Mutation testing >50%: `npm run mutation`
+- [ ] Specific functionality works as described
+- [ ] Documentation is updated if needed
+
+## Implementation Guidance
+
+### Suggested Approach
+<!-- Step-by-step guidance for the agent -->
+1. Analyze existing code structure
+2. Write tests first (TDD approach)
+3. Implement incrementally
+4. Validate continuously
+
+### Files to Consider
+<!-- List relevant files the agent should examine/modify -->
+```
+src/
+├── components/
+├── utils/
+├── index.js
+index.html
+package.json
+```
+
+### Testing Strategy
+- **Unit tests:** Test individual functions/components
+- **Property tests:** Use fast-check for complex logic
+- **Integration tests:** Test component interactions
+- **Manual verification:** Test in browser if UI changes
+
+## Quality Gates
+Before opening PR, ensure:
+```bash
+npm test              # All tests pass
+npm run check:all     # All quality checks pass
+npm run validate:all  # Complete validation
+```
+
+## Agent Instructions
+**Branch naming:** `agent/[issue-number]-[short-description]`
+
+**Commit strategy:**
+- Small, focused commits
+- Clear commit messages
+- Reference this issue number
+
+**Error handling:**
+- If tests fail, analyze each failure individually
+- Fix simplest issues first
+- Make minimal changes
+- Verify fixes immediately
+
+---
+
+**Ready for agent assignment:** Comment `@claude` or `/cursor start` to assign this task to an autonomous agent.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,69 @@
+---
+name: Bug Report
+about: Report a bug or issue with the template
+title: '[BUG] '
+labels: ['bug', 'needs-triage']
+assignees: ''
+---
+
+## Bug Description
+**Current behavior:**
+<!-- Describe what is currently happening -->
+
+**Expected behavior:**
+<!-- Describe what should happen instead -->
+
+**Steps to reproduce:**
+1. 
+2. 
+3. 
+
+## Environment
+- Browser: <!-- e.g., Chrome 91, Firefox 89 -->
+- Node version: <!-- run `node --version` -->
+- NPM version: <!-- run `npm --version` -->
+- Operating System: <!-- e.g., Windows 10, macOS 11, Ubuntu 20.04 -->
+
+## Code/Error Details
+**Error messages:**
+```
+<!-- Paste any error messages here -->
+```
+
+**Relevant code:**
+```javascript
+// Paste relevant code here
+```
+
+**Test failures:**
+```
+<!-- If tests are failing, paste the output -->
+```
+
+## Investigation Notes
+**Files involved:**
+<!-- List files where the bug might be located -->
+
+**Potential causes:**
+<!-- Any theories about what might be causing this -->
+
+## Fix Requirements
+- [ ] Must fix the reported behavior
+- [ ] Must not break existing functionality
+- [ ] Must include test coverage for the fix
+- [ ] Must pass all quality gates
+
+## Acceptance Criteria
+- [ ] Bug is resolved
+- [ ] Tests pass: `npm test`
+- [ ] Quality checks pass: `npm run check:all`
+- [ ] No regression in existing features
+
+---
+
+**For AI Agents:**
+To fix this bug, create a branch named `agent/[issue-number]-fix-[bug-description]` and:
+1. Write a failing test that reproduces the bug
+2. Implement the minimal fix
+3. Ensure all tests pass
+4. Run complete validation with `npm run validate:all`

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,64 @@
+---
+name: Feature Request
+about: Suggest a new feature for the template
+title: '[FEATURE] '
+labels: ['enhancement', 'needs-specification']
+assignees: ''
+---
+
+## Feature Description
+**Brief description of the feature:**
+<!-- Provide a clear and concise description of what you want to add -->
+
+**Problem it solves:**
+<!-- Explain what problem this feature addresses -->
+
+## Requirements
+
+### Functional Requirements
+<!-- What should this feature do? -->
+- [ ] Requirement 1
+- [ ] Requirement 2
+- [ ] Requirement 3
+
+### Technical Requirements
+<!-- Any specific technical constraints or considerations -->
+- [ ] Must maintain 100% test coverage
+- [ ] Must follow existing code structure
+- [ ] Must not break existing functionality
+
+### Acceptance Criteria
+<!-- How will we know this feature is complete and working? -->
+- [ ] Criteria 1
+- [ ] Criteria 2
+- [ ] Criteria 3
+
+## Implementation Notes
+**Suggested approach:**
+<!-- If you have ideas about how to implement this -->
+
+**Files likely to be affected:**
+<!-- List files that might need changes -->
+- `src/`
+- `index.html`
+- `package.json`
+
+## Testing Strategy
+<!-- How should this feature be tested? -->
+- [ ] Unit tests for core functionality
+- [ ] Property-based tests for complex logic
+- [ ] Integration tests if needed
+- [ ] Manual testing scenarios
+
+## Additional Context
+<!-- Add any other context, mockups, or examples -->
+
+---
+
+**For AI Agents:**
+To implement this feature, create a branch named `agent/[issue-number]-[short-description]` and ensure all quality gates pass before opening a PR.
+
+Test commands:
+- `npm test` - Run all tests
+- `npm run check:all` - Run quality checks
+- `npm run validate:all` - Complete validation

.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+on: [push, pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - name: Core test suite
+        run: npm run test:core
+      - name: Upload coverage reports
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+
+  quality:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm ci
+      - name: Lint check
+        run: npm run lint
+      - name: Duplication guard (jscpd)
+        run: npm run check:dup
+      - name: Cycle guard (madge)
+        run: npm run check:cycles
+      - name: Boundaries (dependency-cruiser)
+        run: npm run check:boundaries
+      - name: Mutation Test
+        run: npm run mutation
+      - name: Upload mutation report
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: mutation-testing/reports/
+
+  # Agent-created PR validation
+  agent-pr-check:
+    if: github.event_name == 'pull_request' && contains(github.head_ref, 'agent/')
+    runs-on: ubuntu-latest
+    needs: [test, quality]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate agent PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prTitle = context.payload.pull_request?.title || '';
+            const prBody = context.payload.pull_request?.body || '';
+            const branch = context.payload.pull_request?.head?.ref || '';
+
+            let validationPassed = true;
+            let issues = [];
+
+            // Validate PR has issue reference
+            if (!prBody.match(/#\d+/) && !prTitle.match(/#\d+/)) {
+              issues.push('❌ PR must reference an issue number');
+              validationPassed = false;
+            }
+
+            // Check if PR template was used
+            if (!prBody.includes('## Description') || !prBody.includes('## Testing')) {
+              issues.push('❌ PR template should be used');
+              validationPassed = false;
+            }
+
+            // Post validation results
+            const status = validationPassed ? '✅ Agent PR Validation Passed' : '❌ Agent PR Validation Failed';
+            let comment = `## ${status}\n\n`;
+
+            if (validationPassed) {
+              comment += 'This agent-created PR meets all validation criteria:\n' +
+                        '- ✅ References an issue\n' +
+                        '- ✅ Uses PR template\n' +
+                        '- ✅ All CI checks pass\n\n' +
+                        '**Ready for human review!**';
+            } else {
+              comment += 'Issues found:\n' + issues.map(issue => `- ${issue}`).join('\n') + '\n\n' +
+                        'Please address these issues before merging.';
+            }
+
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: comment
+            });