@agentskillkit/agent-skills 1.0.1

package/.agent/skills/governance/rules/enforcement/checklists/coinpika-frontend-gesture-review-checklist.md

@@ -0,0 +1,190 @@
+---
+name: coinpika-frontend-gesture-review-checklist
+version: 1.0.0
+status: LOCKED
+authority: ENFORCEMENT
+parent: coinpika-frontend-mobile-doctrine
+---
+
+# 🧾 CoinPika Frontend Gesture Review Checklist  
+**(Hard Merge Gate · Mobile UX Enforcement)**
+
+This checklist is a **MANDATORY enforcement gate** for any change involving:
+
+- Mobile layout
+- Scroll behavior
+- Swipe gestures
+- Tab navigation
+- Touch interaction
+- iOS / Android gesture handling
+
+If **ANY** item fails,  
+the change **MUST NOT BE MERGED**.
+
+This checklist enforces:
+- CoinPika Frontend Mobile Doctrine
+- CoinPika Swipe Tabs Doctrine
+- CoinPika Performance Doctrine
+- CoinPika Architecture Doctrine
+
+---
+
+## 1. Scope Declaration (MANDATORY)
+
+- [ ] This change explicitly declares whether it affects gestures or scroll
+- [ ] No gesture or scroll behavior is introduced implicitly
+- [ ] Scope is fully understood by the reviewer
+
+Unclear scope = **AUTOMATIC REJECTION**.
+
+---
+
+## 2. Scroll Ownership Verification
+
+Confirm ALL of the following:
+
+- [ ] Page root does **NOT** scroll
+- [ ] Swipe container does **NOT** scroll
+- [ ] Exactly **ONE** vertical scroll container exists
+- [ ] The scroll container is `ScrollContent`
+
+Multiple scroll containers = **CRITICAL UX VIOLATION**.
+
+---
+
+## 3. Swipe Architecture Compliance
+
+- [ ] The universal swipe implementation is used
+- [ ] No page-specific swipe overrides exist
+- [ ] Swipe logic is not duplicated
+- [ ] Swipe thresholds are global and unchanged
+
+If swipe behavior differs between pages → **REJECT**.
+
+---
+
+## 4. Gesture Arbitration Correctness
+
+- [ ] Horizontal intent triggers swipe
+- [ ] Vertical intent triggers scroll
+- [ ] Swipe cancels when vertical movement dominates
+- [ ] Gesture resolution is deterministic (no heuristics)
+
+Ambiguous gesture behavior = **INVALID IMPLEMENTATION**.
+
+---
+
+## 5. Structural Hierarchy Check
+
+Verify the layout order:
+
+```txt
+Header (non-scrolling)
+  ↓
+TabBar (non-scrolling)
+  ↓
+Swipe Container (horizontal only)
+  ↓
+Tab Panel
+  ↓
+ScrollContent (vertical only)
+````
+
+* [ ] Header is outside the swipe layer
+* [ ] TabBar is outside the swipe layer
+* [ ] Only ScrollContent scrolls
+
+Hierarchy violations break sticky and gestures.
+
+---
+
+## 6. iOS Stability Verification (MANDATORY)
+
+* [ ] Tested on real iOS device or simulator
+* [ ] No scroll bounce amplification
+* [ ] No gesture lock-ups or stuck states
+* [ ] Swipe + scroll interaction feels identical to other pages
+
+Not tested on iOS = **REJECT**.
+
+---
+
+## 7. Forbidden Pattern Scan (ZERO TOLERANCE)
+
+Confirm NONE of the following exist:
+
+* [ ] Swipe logic attached to scroll containers
+* [ ] Conditional gesture behavior per page
+* [ ] Gesture logic based on content height
+* [ ] JavaScript hacks to “fix” gestures
+* [ ] Mixing transform-based swipe with native scroll
+* [ ] Using `100vh` without subtracting system UI heights
+
+Presence of ANY item above = **AUTOMATIC REJECTION**.
+
+---
+
+## 8. Performance & Stability Check
+
+* [ ] No new layout shift introduced
+* [ ] No flicker during gesture
+* [ ] Cached content is not cleared
+* [ ] Gesture does not trigger unnecessary re-renders
+
+If the UI feels less stable → **REJECT**.
+
+---
+
+## 9. Cross-Page Consistency Check
+
+* [ ] Gesture feels identical across all pages
+* [ ] Scroll behavior is consistent
+* [ ] No page feels “special” or different
+
+If one page feels different,
+the **system has drifted**.
+
+---
+
+## 10. Reviewer Assertion (MANDATORY)
+
+The reviewer MUST be able to state:
+
+* [ ] Which doctrine this change complies with
+* [ ] Why no new invariant is introduced
+* [ ] Why future engineers need no special context
+* [ ] Why this change will not surprise users
+
+If the reviewer cannot explain this confidently → **REJECT**.
+
+---
+
+## Final Enforcement Gate
+
+* [ ] ALL checklist items pass
+* [ ] No doctrine is violated
+* [ ] No local patch is used to fix a systemic issue
+
+If **ANY** checkbox is unchecked,
+**DO NOT MERGE**.
+
+---
+
+## Enforcement Statement
+
+Gesture consistency is a **SYSTEM INVARIANT**, not a UI detail.
+
+Broken gestures:
+
+* Break navigation
+* Break trust
+* Break mobile UX irreversibly
+
+When in doubt — **REJECT THE CHANGE**.
+
+---
+
+**Status:** LOCKED
+**Version:** 1.0.0
+**Parent:** CoinPika Frontend Mobile Doctrine
+**Override Permission:** NONE

package/.agent/skills/governance/rules/enforcement/playbooks/doctrine-violation-playbook.md

@@ -0,0 +1,232 @@
+---
+name: doctrine-violation-playbook
+version: 1.0.0
+status: LOCKED
+authority: ENFORCEMENT
+parent: coinpika-master-constitution
+---
+
+# 🚨 CoinPika Doctrine Violation Playbook  
+**(Incident Response · Governance Enforcement · System Integrity)**
+
+This playbook defines **how CoinPika responds** when any doctrine,
+law, or constitutional rule is violated.
+
+Doctrine violations are **NOT personal failures**.  
+They are **system protection events**.
+
+Ignoring a violation causes:
+- Architectural drift
+- Hidden fragility
+- Loss of trust
+
+---
+
+## 1. What Is a Doctrine Violation?
+
+A doctrine violation occurs when **ANY** of the following happens:
+
+- A Prime Directive is broken
+- A system invariant is bypassed
+- Data truth ownership is violated
+- Historical or chart integrity is compromised
+- Mobile UX or gesture invariants are broken
+- Performance laws are violated
+- An AI agent exceeds its authority
+- A “temporary” exception is introduced
+
+If the system works **by luck or memory**,  
+it is already in violation.
+
+---
+
+## 2. Violation Severity Levels
+
+### 🔴 SEV-1 — Constitutional Violation
+
+Examples:
+
+- Frontend mutates financial meaning
+- Realtime data contaminates historical charts
+- Backend truth is bypassed
+- Irreversible breaking change deployed
+- AI agent overrides doctrine or enforcement
+
+**Required Response:**
+
+- Immediate rollback or shutdown
+- Incident declared
+- Full audit required
+
+---
+
+### 🟠 SEV-2 — System Doctrine Violation
+
+Examples:
+
+- Page-specific gesture logic
+- Multiple scroll containers introduced
+- Performance regression masked as optimization
+- Backend treated as thin proxy
+
+**Required Response:**
+
+- Block merge or revert
+- Root cause analysis
+- Doctrine reinforcement
+
+---
+
+### 🟡 SEV-3 — Process / Enforcement Violation
+
+Examples:
+
+- Missing checklist
+- Doctrine not cited in PR
+- Agent output merged without review
+- Enforcement skipped “for speed”
+
+**Required Response:**
+
+- Fix process
+- Retrain reviewers / agents
+- Strengthen enforcement gates
+
+---
+
+## 3. Immediate Response Protocol
+
+When a violation is detected:
+
+1. **STOP** further rollout or merges
+2. **ISOLATE** the violating change
+3. **CLASSIFY** severity (SEV-1 / SEV-2 / SEV-3)
+4. **REVERT or CONTAIN** the impact
+
+Speed of containment  
+is more important than explanation.
+
+---
+
+## 4. Root Cause Analysis (MANDATORY)
+
+Every violation MUST answer:
+
+- Which doctrine or law was violated?
+- Why was the violation possible?
+- Why was it not caught earlier?
+- Was enforcement missing or bypassed?
+- Was an AI agent involved?
+
+Blame is **FORBIDDEN**.  
+System learning is **REQUIRED**.
+
+---
+
+## 5. Remediation Paths
+
+Exactly **ONE** remediation path must be chosen.
+
+### A. Simple Restoration
+
+Use when:
+- Violation is clear
+- Fix is obvious
+- No doctrine change needed
+
+Actions:
+- Revert change
+- Restore invariant
+- Add test or checklist coverage
+
+---
+
+### B. Doctrine Clarification
+
+Use when:
+- Doctrine wording was ambiguous
+- Behavior was unclear
+
+Actions:
+- Clarify doctrine text
+- NO behavior change
+- Release as **v1.0.x**
+
+---
+
+### C. Legitimate Limitation
+
+Use when:
+- Real-world constraint is discovered
+- Current doctrine is insufficient
+
+Actions:
+- Submit **v1.1 Change Proposal**
+- Doctrine remains authoritative until approved
+- No workaround allowed
+
+---
+
+## 6. AI-Specific Violations
+
+If an AI agent caused or contributed:
+
+- Invalidate the agent output
+- Restrict or disable the agent
+- Audit past outputs
+- Update prompts or enforcement rules
+
+Repeated AI violations  
+require **agent suspension**.
+
+---
+
+## 7. Communication Rules
+
+All violations MUST be:
+
+- Documented
+- Visible to the team
+- Free of retroactive justification
+
+Forbidden behaviors:
+
+- Silent fixes
+- Normalizing exceptions
+- “We’ll clean it up later”
+- Blaming individuals
+
+Transparency preserves trust.
+
+---
+
+## 8. Post-Incident Safeguards
+
+After resolution, at least **ONE** must occur:
+
+- New checklist item
+- New automated test
+- Stronger agent restriction
+- Clearer doctrine wording
+
+If nothing changes,  
+the violation **WILL recur**.
+
+---
+
+## Final Principle
+
+Doctrine violations are **signals**, not annoyances.
+
+CoinPika chooses:
+
+**Correction over comfort**  
+**Integrity over speed**  
+**Trust over convenience**
+
+---
+
+**Status:** LOCKED  
+**Version:** 1.0.0  
+**Parent:** CoinPika Master Constitution  
+**Override Permission:** NONE  

package/.agent/skills/governance/scripts/audit_pr.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * CoinPika PR Audit Tool
+ * 
+ * Audits a Git branch or PR for doctrine compliance
+ * 
+ * Usage:
+ *   node scripts/audit_pr.js <branch-name>
+ *   node scripts/audit_pr.js --current  (audit current branch vs main)
+ * 
+ * Exit codes:
+ *   0 = All checks passed
+ *   1 = Violations found
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+};
+
+class PRAuditor {
+    constructor(targetBranch, baseBranch = 'main') {
+        this.targetBranch = targetBranch;
+        this.baseBranch = baseBranch;
+        this.changedFiles = [];
+        this.violations = [];
+    }
+
+    getChangedFiles() {
+        try {
+            const diff = execSync(
+                `git diff --name-only ${this.baseBranch}...${this.targetBranch}`,
+                { encoding: 'utf-8' }
+            );
+
+            this.changedFiles = diff
+                .split('\n')
+                .filter(f => f.trim())
+                .filter(f => f.match(/\.(ts|tsx|js|jsx)$/))
+                .filter(f => !f.includes('node_modules'))
+                .filter(f => !f.includes('.test.'))
+                .filter(f => !f.includes('.spec.'));
+
+            return this.changedFiles;
+        } catch (error) {
+            console.error(colors.red + 'Error getting changed files:' + colors.reset, error.message);
+            process.exit(1);
+        }
+    }
+
+    categorizePR() {
+        const categories = {
+            backend: false,
+            frontend: false,
+            api: false,
+            chart: false,
+            mobile: false,
+            data: false,
+        };
+
+        for (const file of this.changedFiles) {
+            if (file.match(/api\//)) categories.api = true;
+            if (file.match(/lib\/|server\/|db\//)) categories.backend = true;
+            if (file.match(/components\/|app\/|pages\//)) categories.frontend = true;
+            if (file.match(/chart|graph|ohlc|candle/i)) categories.chart = true;
+            if (file.match(/mobile|gesture|swipe|scroll/i)) categories.mobile = true;
+            if (file.match(/data|price|market|coin/i)) categories.data = true;
+        }
+
+        return categories;
+    }
+
+    getApplicableDoctrines(categories) {
+        const doctrines = [
+            'constitution/coinpika-master-constitution.md',
+        ];
+
+        if (categories.backend || categories.api) {
+            doctrines.push('doctrines/architecture/coinpika-architecture-doctrine.md');
+            doctrines.push('doctrines/backend/coinpika-backend-data-engine-doctrine.md');
+        }
+
+        if (categories.chart || categories.data) {
+            doctrines.push('doctrines/data/coinpika-chart-data-doctrine.md');
+        }
+
+        if (categories.frontend || categories.mobile) {
+            doctrines.push('doctrines/frontend/coinpika-frontend-mobile-doctrine.md');
+        }
+
+        if (categories.mobile) {
+            doctrines.push('doctrines/frontend/coinpika-swipe-tabs-doctrine.md');
+        }
+
+        doctrines.push('doctrines/performance/coinpika-performance-doctrine.md');
+        doctrines.push('doctrines/commercial/coinpika-commercial-guardrails-doctrine.md');
+
+        return doctrines;
+    }
+
+    async auditFiles() {
+        const validatorPath = path.join(__dirname, 'validate_doctrine.js');
+
+        for (const file of this.changedFiles) {
+            if (!fs.existsSync(file)) {
+                console.log(colors.yellow + `⚠️  File deleted: ${file}` + colors.reset);
+                continue;
+            }
+
+            console.log(colors.dim + `\nValidating: ${file}` + colors.reset);
+
+            try {
+                execSync(`node "${validatorPath}" "${file}"`, {
+                    stdio: 'inherit',
+                });
+            } catch (error) {
+                this.violations.push(file);
+            }
+        }
+    }
+
+    printSummary() {
+        const categories = this.categorizePR();
+        const doctrines = this.getApplicableDoctrines(categories);
+
+        console.log('\n' + colors.magenta + '═'.repeat(70) + colors.reset);
+        console.log(colors.magenta + colors.bold + `CoinPika PR Audit Report` + colors.reset);
+        console.log(colors.magenta + '═'.repeat(70) + colors.reset + '\n');
+
+        console.log(colors.cyan + `Branch: ${this.targetBranch}` + colors.reset);
+        console.log(colors.dim + `Base: ${this.baseBranch}` + colors.reset);
+        console.log(colors.dim + `Files changed: ${this.changedFiles.length}` + colors.reset);
+        console.log();
+
+        console.log(colors.bold + 'PR Categories:' + colors.reset);
+        Object.entries(categories).forEach(([cat, val]) => {
+            if (val) {
+                console.log(`  ✓ ${cat}`);
+            }
+        });
+        console.log();
+
+        console.log(colors.bold + 'Applicable Doctrines:' + colors.reset);
+        doctrines.forEach(d => {
+            console.log(colors.dim + `  • ${d}` + colors.reset);
+        });
+        console.log();
+
+        if (this.violations.length === 0) {
+            console.log(colors.green + '✅ All files passed doctrine validation!' + colors.reset);
+        } else {
+            console.log(colors.red + `❌ ${this.violations.length} file(s) with violations:` + colors.reset);
+            this.violations.forEach(file => {
+                console.log(colors.red + `  • ${file}` + colors.reset);
+            });
+        }
+
+        console.log('\n' + colors.magenta + '═'.repeat(70) + colors.reset + '\n');
+    }
+
+    async run() {
+        console.log(colors.cyan + '\n🔍 Starting CoinPika PR Audit...\n' + colors.reset);
+
+        this.getChangedFiles();
+
+        if (this.changedFiles.length === 0) {
+            console.log(colors.yellow + 'No relevant files changed.' + colors.reset);
+            return 0;
+        }
+
+        console.log(colors.dim + `Found ${this.changedFiles.length} file(s) to audit\n` + colors.reset);
+
+        await this.auditFiles();
+        this.printSummary();
+
+        return this.violations.length > 0 ? 1 : 0;
+    }
+}
+
+// Main execution
+const arg = process.argv[2];
+
+if (!arg) {
+    console.error('Usage: node audit_pr.js <branch-name>');
+    console.error('       node audit_pr.js --current');
+    process.exit(1);
+}
+
+let targetBranch;
+if (arg === '--current') {
+    try {
+        targetBranch = execSync('git branch --show-current', { encoding: 'utf-8' }).trim();
+    } catch (error) {
+        console.error(colors.red + 'Error getting current branch' + colors.reset);
+        process.exit(1);
+    }
+} else {
+    targetBranch = arg;
+}
+
+const auditor = new PRAuditor(targetBranch);
+auditor.run().then(exitCode => {
+    process.exit(exitCode);
+});