agent-skill-kit 3.9.135

package/.agent/skills/code-constitution/CHANGELOG.md

@@ -0,0 +1,216 @@
+# 📜 Governance Doctrine Pack — CHANGELOG
+
+All notable changes to the **Governance Doctrine Pack** are documented in this file.
+
+This project follows **strict versioning and constitutional governance**.  
+Changes are **rare by design**.
+
+Any modification without an entry here  
+is considered a **governance violation**.
+
+---
+
+## [v1.1.0] — 2026-01-24  
+### 🚀 PROGRESSIVE DISCLOSURE COMPLETE
+
+This release completes the **100/100 PikaKit Compatibility Score**.
+
+---
+
+### 🔧 Scripts Enhancement
+- Added **audit_pr.ts** — Functional PR audit with pattern matching
+  - Doctrine violation detection
+  - JSON output support
+  - CI/CD integration ready
+- Added **validate_doctrine.ts** — Single file/directory validator
+  - Multi-doctrine support
+  - Configurable severity levels
+- Added **learn.ts** — Governance learning tool
+  - Pattern-based lesson recording
+  - YAML knowledge base management
+
+---
+
+### 📂 Progressive Disclosure Expansion
+- Added `metadata/` directory
+  - `precedence.yaml` — Authority resolution
+  - `scope-map.yaml` — Automatic doctrine routing
+
+---
+
+### 📚 Resources Enrichment
+- Added `resources/AUTHORITY_MODEL.md`
+  - Decision precedence order, agent operating mode
+- Added `resources/ENFORCEMENT_GUIDE.md`
+  - 4-level enforcement workflow, 3 examples
+- Added `resources/LOAD_ORDER.md`
+  - Progressive disclosure, scenario-based loading
+
+---
+
+### 📝 Examples Enhancement
+- Added `examples/violation-backend-mutation/` — Law 1 violation before/after
+- Added `examples/violation-chart-injection/` — Law 3+4 violation before/after
+
+---
+
+### 📊 Compatibility Score
+| Metric | v1.0.0 | v1.1.0 |
+|--------|--------|--------|
+| Overall Score | 85/100 | **100/100** |
+| Scripts Functional | 60% | 100% |
+| Progressive Disclosure | 80% | 100% |
+| Resources Depth | 70% | 100% |
+
+---
+
+## [v1.0.0] — 2026-01-23  
+### 🎉 OFFICIAL INITIAL RELEASE
+
+This release establishes the **foundational constitutional system** governing PikaKit.
+
+It defines how PikaKit is:
+- Designed
+- Implemented
+- Reviewed
+- Scaled
+- Governed (human + AI)
+
+This version is declared **LOCKED**.
+
+---
+
+### 👑 Supreme Constitution
+- Added **PikaKit Master Constitution**
+  - Prime Directives
+  - System Laws
+  - Decision precedence
+  - Controlled self-improvement rules
+
+---
+
+### 🏛️ Architecture & Data Truth
+- Added **Architecture Doctrine**
+  - System boundaries
+  - Ownership rules
+  - Scalability invariants
+- Added **Backend Data Engine Doctrine**
+  - Ingestion taxonomy
+  - Caching and cost control
+  - External dependency isolation
+- Added **Chart Data Doctrine**
+  - Historical immutability
+  - Realtime separation
+  - Financial truth enforcement
+
+---
+
+### 📱 Frontend & UX Systems
+- Added **Frontend Mobile Doctrine**
+  - Mobile-first invariants
+  - Scroll ownership
+  - Structural hierarchy
+- Added **Swipe Tabs Doctrine**
+  - Universal swipe implementation
+  - Gesture arbitration rules
+  - iOS-safe interaction guarantees
+
+---
+
+### ⚡ Performance & Stability
+- Added **Performance Doctrine**
+  - Cache-first rendering
+  - Background freshness
+  - Stability over freshness
+  - Perceived performance prioritization
+
+---
+
+### 💼 Commercial & Enterprise Safety
+- Added **Commercial Guardrails Doctrine**
+  - Breaking change policy
+  - Blast radius awareness
+  - Reversibility requirements
+
+---
+
+### 🛡️ Review & Enforcement
+- Added **Code Review Doctrine**
+  - Reviewer authority
+  - Mandatory rejection conditions
+- Added **Frontend Gesture Review Checklist**
+  - Hard gate for swipe & scroll changes
+
+---
+
+### 🤖 AI & Agent Governance
+- Added **Learning Engine Doctrine**
+  - Controlled reasoning improvement
+  - Explicit learning boundaries
+- Added **Agent Enforcement Protocol**
+  - Proposal-only AI operation
+  - Zero-trust agent model
+- Added **Agent System Prompt**
+  - Constitutional binding for all agents
+
+---
+
+### 🏷️ Controlled Evolution & Incident Handling
+- Added **v1.1 Change Proposal Template**
+  - Formal process for future doctrine changes
+- Added **Doctrine Violation Playbook**
+  - Severity levels (SEV-1 / SEV-2 / SEV-3)
+  - Incident response and remediation rules
+
+---
+
+### 🧠 PikaKit Skills Integration
+- Added **SKILL.md** as single entry point
+- Implemented **Progressive Disclosure architecture**
+- Added **metadata/**
+  - `precedence.yaml` for authority resolution
+  - `scope-map.yaml` for automatic doctrine routing
+- Packaged as **directory-based PikaKit Skill**
+
+---
+
+### 📦 Distribution
+- Published **single bundled ZIP**
+  - `PikaKit-doctrine-pack-pikakit.zip`
+- Supports:
+  - Workspace scope
+  - Global scope
+  - PikaKit / Gemini / Claude / GPT agents
+
+---
+
+### 🔒 Governance Status
+- All doctrine files marked **LOCKED**
+- All changes require:
+  - Explicit Change Proposal
+  - Constitutional review
+  - Version bump
+
+---
+
+## Versioning Policy
+
+- **MAJOR** (v2.0): Constitutional or Prime Directive changes
+- **MINOR** (v1.1): Doctrine evolution via approved proposal
+- **PATCH** (v1.0.x): Clarifications only (no behavior change)
+
+---
+
+## Enforcement Notice
+
+If a behavior exists in the system  
+that is not documented in this changelog,  
+it is considered **undefined and unsafe**.
+
+---
+
+**End of Changelog**
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/code-constitution/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: code-constitution
+description: >-
+  Constitutional governance for PikaKit: non-negotiable laws for correctness, trust, and durability.
+  Use when reviewing breaking changes, critical data operations, or governance violations.
+  NOT for general code review (use code-review) or security scanning (use security-scanner).
+category: governance
+triggers: ["architecture", "critical data", "breaking change", "governance", "doctrine"]
+coordinates_with: ["code-review", "security-scanner", "code-craft"]
+success_metrics: ["0 governance bypasses", "100% doctrine compliance"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# PikaKit Governance — Code Constitution
+
+> Supreme authority. Zero-trust agents. Fail-closed enforcement. Doctrine-first decisions.
+
+**Status:** OFFICIAL · LOCKED | **Authority:** SUPREME | **Override:** NONE
+
+---
+
+## Prerequisites
+
+**Required:** None — Code Constitution is a governance framework with no external dependencies.
+
+**Doctrine library:** 16 rule files in `rules/` directory (required for evaluation).
+
+---
+
+## When to Use
+
+| Scope | Activation | Default |
+|-------|-----------|---------|
+| System architecture or boundaries | **Mandatory** — always load | — |
+| Data ownership or persistence | **Mandatory** | — |
+| Critical business logic | **Mandatory** | — |
+| Breaking changes or commercial risk | **Mandatory** | — |
+| AI agent behavior or autonomy | **Mandatory** | — |
+| Ambiguous intent | **Mandatory** — load by default | Refuse |
+| Architecture review, contracts, security | See `rules/engineering-spec.md` | — |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Agent operating mode (STRICT/PROPOSAL_ONLY/ZERO_TRUST) | Agent implementation |
+| Doctrine library (16 rules in `rules/`) | Rule execution in other skills |
+| Enforcement behavior (Stop → Cite → Refuse) | Automated remediation |
+| Authority hierarchy definition | Skill priority in GEMINI.md |
+| Change Proposal review | Proposal tooling |
+
+**Pure decision skill:** Produces governance decisions (approve/refuse/escalate). Zero side effects.
+
+---
+
+## Execution Model — 4-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Classify** | Validate request type, extract scope, identify risk level | Validated input or error |
+| **Evaluate** | Load applicable doctrines from `rules/`, check each against context | Violation list (may be empty) |
+| **Decide** | 0 violations → approve; ≥1 blocking → refuse; ambiguous → escalate | Decision + conditions/violations |
+| **Emit** | Return structured output with enforcement action | Complete output schema |
+
+All phases synchronous. Fail-closed: any phase failure defaults to "refuse."
+
+---
+
+## Authority Hierarchy
+
+```
+Code Constitution (SUPREME)
+  └── GEMINI.md (P0)
+        └── Agent .md files (P1)
+              └── Skill .md files (P2)
+```
+
+No skill, agent, or workflow may override a constitutional decision.
+
+---
+
+## Agent Operating Mode
+
+| Setting | Value | Meaning |
+|---------|-------|---------|
+| POLICY_MODE | STRICT | All rules enforced without exception |
+| AUTONOMY | PROPOSAL_ONLY | Agents propose; never self-approve |
+| TRUST_LEVEL | ZERO | Agent declarations are inputs, not truth |
+
+**Agents MAY:** Propose actions, explain trade-offs, identify risks, cite doctrines.
+
+**Agents MUST NOT:** Approve without user consent, merge automatically, bypass enforcement.
+
+---
+
+## Enforcement Behavior
+
+When violation detected:
+
+1. **Stop** execution immediately
+2. **Cite** specific violated doctrine (file + rule)
+3. **Explain** systemic risk of the violation
+4. **Refuse** the request
+
+**Fail-closed invariant:** Partial compliance = enforcement failure. Ambiguity = refuse or escalate.
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Default Action |
+|------|-------------|----------------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Refuse |
+| `ERR_MISSING_CONTEXT` | Yes | Refuse |
+| `ERR_DOCTRINE_NOT_FOUND` | No | Refuse |
+| `ERR_AMBIGUOUS_SCOPE` | Yes | Escalate |
+| `ERR_TRUST_VIOLATION` | No | Refuse + restrict |
+| `ERR_INVALID_PROPOSAL` | Yes | Refuse |
+| `ERR_EVALUATION_FAILED` | No | Refuse |
+
+**All failures default to refuse.** No silent approvals. Zero internal retries.
+
+---
+
+## Quick Start
+
+```
+1. Agent proposes action with context (scope, files, change type, risk level)
+2. Code Constitution validates against applicable doctrines in rules/
+3. Decision returned: approve | refuse | escalate
+4. If refused: Stop, cite violation, do NOT proceed
+```
+
+Validation scripts: `scripts/validate_doctrine.ts` | PR audit: `scripts/audit_pr.ts`
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Self-approve agent actions | Propose and wait for user consent |
+| Ignore governance for "quick fix" | Load constitution; validate first |
+| Override constitution from another skill | Respect authority hierarchy |
+| Assume no violation = safe | Explicitly check applicable doctrines |
+| Modify doctrines directly | Submit Change Proposal |
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Resolution |
+|---------|-------|------------|
+| Every action refused | Scope set to "critical" for minor changes | Set accurate `risk_level` and `scope` |
+| Doctrine not found error | Skill installation incomplete | Verify `rules/doctrines/` contains all 8 domains |
+| Escalation loop | Ambiguous scope keeps re-triggering | Provide explicit scope: architecture, data, security |
+| Agent bypasses governance | Skill not loaded for the request type | Add trigger keywords to agent routing config |
+
+---
+
+## 📑 Content Map
+
+| Folder | Content | When to Read |
+|--------|---------|--------------|
+| [rules/](rules/) | 16 domain-specific governance rules | Doctrine evaluation |
+| [rules/engineering-spec.md](rules/engineering-spec.md) | Full engineering spec: contracts, security, scalability | Architecture review |
+| [metadata/](metadata/) | Routing & intent configuration | Skill routing |
+| [resources/](resources/) | Templates & reference materials | Building governance artifacts |
+| [scripts/](scripts/) | Validation & enforcement scripts | Automated checking |
+| [examples/](examples/) | Governance usage examples | Learning patterns |
+| [knowledge/](knowledge/) | Accumulated governance knowledge | Context building |
+| [proposals/](proposals/) | Change Proposals for doctrine updates | Modifying constitution |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `code-review` | Skill | Code quality review |
+| `security-scanner` | Skill | Security vulnerability detection |
+| `code-craft` | Skill | Code standards enforcement |
+| `skill-generator` | Skill | Skill file validation |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/code-constitution/VERSION

@@ -0,0 +1,3 @@
+# VERSION
+
+2.0.0

package/.agent/skills/code-constitution/examples/violation-backend-mutation/after.tsx

@@ -0,0 +1,59 @@
+// ✅ CORRECT: Backend as source of truth
+// Follows Law 1 (Truth Ownership)
+
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api';
+
+export function CoinPriceCard({ coinId }) {
+    // ✅ Frontend only consumes backend data
+    const { data } = useQuery({
+        queryKey: ['coin', coinId, 'price'],
+        queryFn: () => api.getCoinPrice(coinId),
+        refetchInterval: 5000, // Backend controls refresh rate
+    });
+
+    // ✅ NO local state for truth
+    // ✅ NO direct external API calls
+    // ✅ NO frontend calculations
+    // ✅ NO localStorage for financial data
+
+    if (!data) return <div>Loading...</div>;
+
+    return (
+        <div>
+            {/* ✅ Display backend-provided data only */}
+            <p>Price: ${data.currentPrice}</p>
+            <p>24h Avg: ${data.avg24h}</p>
+
+            {/* Backend metadata */}
+            <p className="text-xs text-gray-500">
+                Updated: {new Date(data.timestamp).toLocaleTimeString()}
+            </p>
+        </div>
+    );
+}
+
+// ✅ Backend API implementation (separate service)
+// /api/coins/[coinId]/price.js
+export async function GET(req, { params }) {
+    // ✅ Backend owns the truth
+    const price = await db.coinPrices.findFirst({
+        where: { coinId: params.coinId },
+        orderBy: { timestamp: 'desc' },
+    });
+
+    // ✅ Backend calculates aggregates
+    const avg24h = await db.coinPrices.aggregate({
+        where: {
+            coinId: params.coinId,
+            timestamp: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+        },
+        _avg: { price: true },
+    });
+
+    return Response.json({
+        currentPrice: price.price,
+        avg24h: avg24h._avg.price,
+        timestamp: price.timestamp,
+    });
+}

package/.agent/skills/code-constitution/examples/violation-backend-mutation/before.tsx

@@ -0,0 +1,42 @@
+// ❌ VIOLATION: Frontend mutating backend data
+// This violates Law 1 (Truth Ownership)
+
+import { useState, useEffect } from 'react';
+
+export function CoinPriceCard({ coinId }) {
+    const [price, setPrice] = useState(0);
+    const [history, setHistory] = useState([]);
+
+    // VIOLATION: Frontend making truth decisions
+    const updatePrice = (newPrice) => {
+        // ❌ Directly mutating price state
+        setPrice(newPrice);
+
+        // ❌ CRITICAL VIOLATION: Frontend managing historical data
+        setHistory(prev => [...prev, newPrice]);
+
+        // ❌ Frontend calculating aggregates
+        const avg = history.reduce((a, b) => a + b, 0) / history.length;
+
+        // ❌ Frontend persisting to localStorage
+        localStorage.setItem(`coin_${coinId}_price`, newPrice.toString());
+        localStorage.setItem(`coin_${coinId}_history`, JSON.stringify(history));
+    };
+
+    // ❌ Frontend calling external API directly
+    useEffect(() => {
+        fetch(`https://api.coingecko.com/api/v3/coins/${coinId}`)
+            .then(res => res.json())
+            .then(data => {
+                // ❌ Frontend processing raw external data
+                updatePrice(data.market_data.current_price.usd);
+            });
+    }, [coinId]);
+
+    return (
+        <div>
+            <p>Price: ${price}</p>
+            <p>24h Avg: ${avg}</p>
+        </div>
+    );
+}

package/.agent/skills/code-constitution/examples/violation-backend-mutation/explanation.md

@@ -0,0 +1,91 @@
+# Backend Mutation Violation Example
+
+## Why This Matters
+
+This example demonstrates **Law 1: Truth Ownership** from the Master Constitution.
+
+### The Problem (before.tsx)
+
+The frontend is:
+1. ❌ Making truth decisions about prices
+2. ❌ Managing historical data locally
+3. ❌ Calculating financial aggregates
+4. ❌ Persisting data to localStorage
+5. ❌ Calling external APIs directly
+
+### The Systemic Risks
+
+1. **Data Inconsistency**
+   - Different users see different "truths"
+   - No single source of historical accuracy
+   - Aggregates vary by client state
+
+2. **Correctness Failure**
+   - Frontend can be manipulated via DevTools
+   - localStorage can be corrupted
+   - No data validation or normalization
+
+3. **Scalability Failure**
+   - Every client directly hammers external APIs
+   - No rate limiting or caching
+   - Amplification under load
+
+4. **Commercial Risk**
+   - Users making financial decisions on unverified data
+   - Potential for data manipulation
+   - No audit trail
+
+### The Solution (after.tsx)
+
+The backend:
+- ✅ Owns all truth
+- ✅ Manages historical data
+- ✅ Calculates aggregates
+- ✅ Validates and normalizes external data
+- ✅ Provides cacheable, rate-limited API
+
+The frontend:
+- ✅ Only displays backend-provided data
+- ✅ Has no local truth
+- ✅ Cannot manipulate financial data
+- ✅ Stateless and predictable
+
+## Constitutional Justification
+
+> **Law 1 — Truth Ownership**
+> 
+> The backend is the **single source of truth**.
+> 
+> If the frontend can alter financial meaning, the system is architecturally broken.
+
+From: Code Constitution — Master Laws
+
+## Architecture Doctrine
+
+> The frontend MUST NEVER:
+> - Depend directly on external APIs (production)
+> - Reconstruct backend meaning
+> - Patch missing data
+> 
+> If the frontend can "fix" backend data, the architecture is invalid.
+
+From: Code Constitution — Architecture Doctrine
+
+## When to Apply This Pattern
+
+- Any financial data (prices, volumes, balances)
+- Any historical data (charts, aggregates, trends)
+- Any calculated data (averages, percentiles, rankings)
+- Any persistent data (portfolios, watchlists, settings with financial impact)
+
+## Key Takeaway
+
+**The frontend is a VIEW, not a CALCULATOR.**
+
+If you're writing `localStorage.setItem()` with financial data, or calculating aggregates in a React component, you're violating the Constitution.
+
+Stop, redesign, and move the logic to the backend.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/code-constitution/examples/violation-chart-injection/after.tsx

@@ -0,0 +1,99 @@
+// ✅ CORRECT: Realtime and historical data strictly separated
+// Follows Law 3 (Realtime Ephemerality) and Law 4 (Chart Truthfulness)
+
+import { useEffect, useRef, useState } from 'react';
+import { createChart } from 'lightweight-charts';
+
+export function BitcoinChart() {
+    const chartRef = useRef(null);
+    const seriesRef = useRef(null);
+
+    // ✅ SEPARATE state for realtime display
+    const [realtimePrice, setRealtimePrice] = useState(null);
+    const [realtimeChange, setRealtimeChange] = useState(0);
+
+    useEffect(() => {
+        const chart = createChart(chartRef.current, { width: 600, height: 400 });
+        const series = chart.addLineSeries();
+
+        // ✅ Load ONLY historical data into chart
+        fetch('/api/bitcoin/historical')
+            .then(res => res.json())
+            .then(data => {
+                series.setData(data); // Immutable historical record
+
+                // ✅ Use last historical point as baseline for realtime change
+                const lastPrice = data[data.length - 1].value;
+                setRealtimeChange(0); // Reset change against history
+            });
+
+        // ✅ WebSocket for DISPLAY ONLY
+        const ws = new WebSocket('wss://stream.binance.com/ws/btcusdt@trade');
+
+        ws.onmessage = (event) => {
+            const tick = JSON.parse(event.data);
+            const price = parseFloat(tick.p);
+
+            // ✅ Update ephemeral display state ONLY
+            setRealtimePrice(price);
+
+            // ✅ Calculate change from last HISTORICAL close
+            const lastHistoricalPrice = series.data()[series.data().length - 1].value;
+            setRealtimeChange(((price - lastHistoricalPrice) / lastHistoricalPrice) * 100);
+
+            // ✅ NO modification to chart data
+            // ✅ NO persistence
+            // ✅ NO mixing historical and realtime
+        };
+
+        seriesRef.current = series;
+
+        return () => ws.close();
+    }, []);
+
+    return (
+        <div>
+            {/* ✅ Historical chart (immutable) */}
+            <div ref={chartRef} />
+
+            {/* ✅ Separate realtime display */}
+            <div className="realtime-ticker bg-gray-900 p-4 mt-2">
+                <p className="text-sm text-gray-400">Live Price (not in chart)</p>
+                <p className="text-2xl font-bold">
+                    ${realtimePrice?.toLocaleString() ?? '---'}
+                </p>
+                <p className={realtimeChange >= 0 ? 'text-green-500' : 'text-red-500'}>
+                    {realtimeChange >= 0 ? '↑' : '↓'} {Math.abs(realtimeChange).toFixed(2)}%
+                </p>
+                <p className="text-xs text-gray-500 mt-1">
+                    Since last close • Ephemeral • Not persisted
+                </p>
+            </div>
+        </div>
+    );
+}
+
+// ✅ Backend aggregates realtime into historical at fixed intervals
+// /api/cron/aggregate-bitcoin-price.js (runs every 5 minutes)
+export async function aggregateRealtimeToHistory() {
+    // ✅ Collect realtime ticks from last 5 minutes
+    const realtimeTicks = await redis.lrange('btc:ticks:last5m', 0, -1);
+
+    // ✅ Calculate OHLCV from ticks
+    const candle = calculateOHLCV(realtimeTicks);
+
+    // ✅ APPEND to historical data (immutable)
+    await db.bitcoinHistory.create({
+        data: {
+            timestamp: candle.timestamp,
+            open: candle.open,
+            high: candle.high,
+            low: candle.low,
+            close: candle.close,
+            volume: candle.volume,
+        },
+    });
+
+    // ✅ Clear realtime buffer
+    await redis.del('btc:ticks:last5m');
+}