@hienlh/ppm 0.9.80 → 0.9.81

package/.opencode/skills/ck-autoresearch/references/metric-library.md

@@ -0,0 +1,200 @@
+# Metric Library
+
+Quick-reference verify commands by domain. Copy-paste into ck:loop config.
+Direction: **lower** = fewer errors/ms/bytes is better. **higher** = more coverage/accuracy is better.
+
+## Code Quality
+
+### Test Coverage
+
+**Node.js — Jest**
+```bash
+npx jest --coverage --coverageReporters=json-summary 2>/dev/null \
+  | node -e "const s=require('./coverage/coverage-summary.json'); console.log(s.total.lines.pct)"
+```
+Direction: higher | Noise: low | Guard: `npm test`
+
+**Node.js — Vitest**
+```bash
+npx vitest run --coverage 2>/dev/null \
+  | grep 'All files' | awk '{print $NF}' | tr -d '%'
+```
+Direction: higher | Noise: low | Guard: `npm test`
+
+**Python — pytest-cov**
+```bash
+pytest --cov=src --cov-report=term-missing -q 2>/dev/null \
+  | grep 'TOTAL' | awk '{print $NF}' | tr -d '%'
+```
+Direction: higher | Noise: low | Guard: `pytest`
+
+**Go**
+```bash
+go test ./... -coverprofile=coverage.out -covermode=atomic 2>/dev/null \
+  && go tool cover -func=coverage.out | grep total | awk '{print $3}' | tr -d '%'
+```
+Direction: higher | Noise: low | Guard: `go test ./...`
+
+
+### Lint Errors
+
+**ESLint**
+```bash
+npx eslint src --format json 2>/dev/null \
+  | node -e "const r=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(r.reduce((a,f)=>a+f.errorCount,0))"
+```
+Direction: lower | Noise: low | Guard: `npm test`
+
+**Pylint**
+```bash
+pylint src/ --output-format=json 2>/dev/null \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(sum(1 for m in d if m['type'] in ('error','fatal')))"
+```
+Direction: lower | Noise: low | Guard: `pytest`
+
+**Clippy (Rust)**
+```bash
+cargo clippy --message-format=json 2>/dev/null \
+  | jq -r 'select(.reason=="compiler-message") | .message.level' | grep -c 'error'
+```
+Direction: lower | Noise: low | Guard: `cargo test`
+
+
+### Type Errors
+
+**TypeScript — tsc**
+```bash
+npx tsc --noEmit 2>&1 | grep -c '^src/.*error TS' || true
+```
+Direction: lower | Noise: low | Guard: `npm test`
+
+**Python — mypy**
+```bash
+mypy src/ --ignore-missing-imports 2>&1 | tail -1 | awk '{print $1}'
+```
+Direction: lower | Noise: low | Guard: `pytest`
+
+
+## Performance
+
+### API Latency
+
+**wrk (mean latency, ms)**
+```bash
+wrk -t2 -c10 -d10s http://localhost:3000/api/health 2>/dev/null \
+  | grep 'Latency' | awk '{print $2}' | sed 's/ms//'
+```
+Direction: lower | Noise: high | Guard: `npm test`
+
+**curl (single request, ms)**
+```bash
+curl -o /dev/null -s -w "%{time_total}" http://localhost:3000/api/health \
+  | awk '{printf "%.0f\n", $1*1000}'
+```
+Direction: lower | Noise: high | Guard: `npm test`
+
+
+### Build / Bundle Size
+
+**Webpack / Vite (main bundle, bytes)**
+```bash
+npm run build 2>/dev/null \
+  && find dist -name '*.js' ! -name '*.map' | xargs wc -c | tail -1 | awk '{print $1}'
+```
+Direction: lower | Noise: low | Guard: `tsc --noEmit`
+
+**Go binary (bytes)**
+```bash
+go build -o /tmp/app_measure . 2>/dev/null && wc -c < /tmp/app_measure
+```
+Direction: lower | Noise: low | Guard: `go test ./...`
+
+
+### Build Time
+
+**Node.js (ms)**
+```bash
+start=$(date +%s%N); npm run build 2>/dev/null; echo $(( ($(date +%s%N) - start) / 1000000 ))
+```
+Direction: lower | Noise: medium | Guard: `tsc --noEmit`
+
+**Go (ms)**
+```bash
+start=$(date +%s%N); go build ./... 2>/dev/null; echo $(( ($(date +%s%N) - start) / 1000000 ))
+```
+Direction: lower | Noise: medium | Guard: `go test ./...`
+
+
+## Security
+
+### Vulnerability Count
+
+**npm audit**
+```bash
+npm audit --json 2>/dev/null \
+  | node -e "const r=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(r.metadata?.vulnerabilities?.total ?? 0)"
+```
+Direction: lower | Noise: low | Guard: `npm test`
+
+**pip-audit**
+```bash
+pip-audit --format=json 2>/dev/null \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('dependencies',[])))"
+```
+Direction: lower | Noise: low | Guard: `pytest`
+
+## Lines of Code
+
+**find + wc (TS/JS)**
+```bash
+find src -name '*.ts' -o -name '*.js' | xargs wc -l | tail -1 | awk '{print $1}'
+```
+Direction: lower | Noise: low | Guard: `npm test`
+
+**cloc (any language)**
+```bash
+cloc src --json 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin)['SUM']['code'])"
+```
+Direction: lower | Noise: low | Guard: `npm test`
+
+## ML / Data Science
+
+### Accuracy
+
+**PyTorch (eval script)**
+```bash
+python3 scripts/evaluate.py --split val 2>/dev/null | grep 'accuracy' | awk '{print $NF}'
+```
+Direction: higher | Noise: high | Guard: `pytest tests/`
+
+**sklearn — F1 Score**
+```bash
+python3 -c "from sklearn.metrics import f1_score; import numpy as np; print(f'{f1_score(np.load(\"data/y_true.npy\"), np.load(\"data/y_pred.npy\"), average=\"weighted\"):.4f}')"
+```
+Direction: higher | Noise: high | Guard: `pytest tests/`
+
+
+## Creating Custom Metrics
+
+### Template
+
+```bash
+# 1. Measure exactly one numeric value
+# 2. Print it to stdout as the last (or only) line
+# 3. Exit 0 on success, non-zero on failure (treated as crash)
+# 4. Complete in < 30 seconds (or configure timeout)
+# 5. Be deterministic, or declare Noise: high
+
+YOUR_MEASURE_COMMAND | YOUR_EXTRACT_COMMAND
+```
+
+### Rules
+
+| Rule | Detail |
+|------|--------|
+| One number | stdout last line must be a bare number (integer or float) |
+| Exit codes | exit 0 = valid measurement, exit non-zero = crash (logged, skipped) |
+| Runtime | keep under 30s; use sampling for expensive workloads |
+| Determinism | if output varies run-to-run, set `noise: high` and use 3-5 runs |
+| Units | consistent across all iterations; never change mid-loop |
+| Direction | declare explicitly: `lower` or `higher` is better |

package/.opencode/skills/ck-autoresearch/references/results-logging.md

@@ -0,0 +1,74 @@
+# Results Logging
+
+## TSV Format
+
+One row per iteration. Tab-separated. Header row required.
+
+```
+iteration	commit	metric	delta	status	description
+```
+
+### Column Definitions
+
+| Column | Type | Notes |
+|--------|------|-------|
+| iteration | integer | 0-indexed. 0 = baseline. |
+| commit | string | Short SHA (7 chars) or `-` if discarded/crashed |
+| metric | float | Measured value from verify command |
+| delta | float | Signed change from previous best. Negative = improvement for "lower is better". `-` for baseline. |
+| status | enum | See status values below |
+| description | string | One sentence: what was attempted |
+
+### Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `baseline` | Initial measurement before any changes |
+| `keep` | Improvement passed guard, committed |
+| `keep (reworked)` | Failed guard on first attempt, reworked, then passed |
+| `discard` | No improvement or below min-delta threshold |
+| `guard-failed` | Metric improved but guard command exited non-zero; reverted |
+| `crash` | Verify command errored or timed out |
+| `no-op` | Improvement below min-delta threshold (not a failure, just insufficient) |
+
+### Example Log
+
+```tsv
+iteration	commit	metric	delta	status	description
+0	a1b2c3d	842	-	baseline	Initial bundle size measurement
+1	e4f5a6b	810	-32	keep	Tree-shake unused lodash imports
+2	-	798	-44	discard	Remove dead CSS — metric improved but below min-delta
+3	c7d8e9f	771	-71	keep	Replace moment.js with day.js
+4	-	-	-	crash	Build script errored on dynamic import rewrite
+5	1a2b3c4	751	-91	guard-failed	Inline critical CSS — bundle smaller but tests failed
+6	5d6e7f8	758	-84	keep (reworked)	Inline critical CSS with fallback (guard-safe version)
+7	9a0b1c2	741	-101	keep	Lazy-load admin panel chunk
+```
+
+---
+
+## Progressive Summaries
+
+### Every-5-Iteration Summary
+
+Print after iterations 5, 10, 15, ...:
+
+```
+--- Progress @ iteration 5 ---
+Best so far: 751 (baseline: 842, -10.8%)
+Kept: 3  |  Discarded: 1  |  Crashed: 1  |  Guard-failed: 1
+Top strategy: dependency replacement (moment→day.js: -71)
+```
+
+### Final Summary
+
+Print at loop end (budget exhausted or goal reached):
+
+```
+--- Final Summary ---
+Baseline → Final: 842 → 741  (-11.9%, -101 units)
+Iterations: 7 total  |  Kept: 4  |  Discarded: 1  |  Crashed: 1  |  Guard-failed: 1
+Best single iteration: #7 lazy-load admin chunk (-20)
+Worst outcome: #4 crash (build script)
+Key insight: Dependency replacement yielded most gains; CSS inlining required guard-safe rework
+```

package/.opencode/skills/ck-debug/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ck:debug
+description: "Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation, log analysis, CI/CD failures, database diagnostics, system investigation."
+languages: all
+argument-hint: "[error or issue description]"
+metadata:
+  author: claudekit
+  version: "4.0.0"
+---
+
+# Debugging & System Investigation
+
+Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems
+**System-level:** Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis
+**Always:** Before claiming work complete
+
+## Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes `scripts/find-polluter.sh` for bisecting test pollution.
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+### 5. Investigation Methodology (`references/investigation-methodology.md`)
+
+Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development
+
+**Load when:** Server incidents, system behavior analysis, multi-component failures
+
+### 6. Log & CI/CD Analysis (`references/log-and-ci-analysis.md`)
+
+Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: `gh` CLI, structured log queries, correlation across sources.
+
+**Load when:** CI/CD pipeline failures, server errors, deployment issues
+
+### 7. Performance Diagnostics (`references/performance-diagnostics.md`)
+
+Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.
+
+**Load when:** Performance degradation, slow queries, high latency, resource exhaustion
+
+### 8. Reporting Standards (`references/reporting-standards.md`)
+
+Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence
+
+**Load when:** Need to produce investigation report or diagnostic summary
+
+### 9. Task Management (`references/task-management-debugging.md`)
+
+Track investigation pipelines via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. **Fallback:** Task tools are CLI-only — if unavailable (VSCode extension), use `TodoWrite` for tracking. Debug workflow remains fully functional.
+
+**Load when:** Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents
+
+### 10. Frontend Verification (`references/frontend-verification.md`)
+
+Visual verification of frontend implementations via Chrome MCP (Claude Chrome Extension) or `ck:chrome-devtools` skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.
+
+**Load when:** Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions
+
+## Quick Reference
+
+```
+Code bug       → systematic-debugging.md (Phase 1-4)
+  Deep in stack  → root-cause-tracing.md (trace backward)
+  Found cause    → defense-in-depth.md (add layers)
+  Claiming done  → verification.md (verify first)
+
+System issue   → investigation-methodology.md (5 steps)
+  CI/CD failure  → log-and-ci-analysis.md
+  Slow system    → performance-diagnostics.md
+  Need report    → reporting-standards.md
+
+Frontend fix   → frontend-verification.md (Chrome/devtools)
+```
+
+## Tools Integration
+
+- **Database:** `psql` for PostgreSQL queries and diagnostics
+- **CI/CD:** `gh` CLI for GitHub Actions logs and pipeline debugging
+- **Codebase:** `ck:docs-seeker` skill for package/plugin docs; `ck:repomix` skill for codebase summary
+- **Scouting:** `/ck:scout` or `/ck:scout ext` for finding relevant files
+- **Frontend:** Chrome browser or `ck:chrome-devtools` skill for visual verification (screenshots, console, network)
+- **Skills:** Activate `ck:problem-solving` skill when stuck on complex issues
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.

package/.opencode/skills/ck-debug/references/defense-in-depth.md

@@ -0,0 +1,124 @@
+# Defense-in-Depth Validation
+
+Validate at every layer data passes through to make bugs impossible.
+
+## Core Principle
+
+**Validate at EVERY layer data passes through. Make bug structurally impossible.**
+
+When fix bug caused by invalid data, adding validation at one place feels sufficient. But single check can be bypassed by different code paths, refactoring, or mocks.
+
+## Why Multiple Layers
+
+Single validation: "We fixed bug"
+Multiple layers: "We made bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // proceed
+}
+```
+
+## Applying the Pattern
+
+When find bug:
+
+1. **Trace data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Real Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/.opencode/skills/ck-debug/references/frontend-verification.md

@@ -0,0 +1,103 @@
+# Frontend Verification
+
+Visual verification of frontend implementations using Chrome MCP (Claude Chrome Extension) or `ck:chrome-devtools` skill fallback.
+
+## Applicability Check
+
+**Skip entirely if task is NOT frontend-related.** Frontend indicators:
+- Files modified: `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.css`, `*.scss`
+- Changes to: components, layouts, pages, styles, DOM structure, UI behavior
+- Keywords: render, display, layout, responsive, animation, visual, UI, UX
+
+If none match, skip this technique.
+
+## Step 1: Detect Chrome MCP Availability
+
+Check if Chrome MCP server is available via `ck:mcp-management` skill or `ListMcpResourcesTool`:
+
+```
+Use ListMcpResourcesTool to check for Chrome MCP tools.
+Look for tools prefixed with "chrome__" (e.g., chrome__navigate, chrome__screenshot).
+```
+
+**Available** → Proceed to Step 2A (Chrome MCP)
+**Not available** → Proceed to Step 2B (chrome-devtools fallback)
+
+## Step 2A: Chrome MCP Available — Direct Verification
+
+Use Chrome MCP tools to verify the implementation in the user's actual browser. Ensure dev server is running first.
+
+### Navigate & Screenshot
+
+```
+1. chrome__navigate → http://localhost:3000 (or project dev URL)
+2. chrome__screenshot → capture current page state
+3. Read the screenshot with Read tool to visually inspect
+```
+
+### Visual Inspection Checklist
+
+After capturing screenshot, verify:
+1. **Layout** — Elements positioned correctly, no overflow/overlap
+2. **Content** — Text, images, data rendered as expected
+3. **Responsiveness** — Resize viewport if MCP supports it
+4. **Interactions** — Use chrome__click / chrome__type to test interactive elements
+5. **Console errors** — Use chrome__evaluate to check `console.error` output
+
+### Console Error Check
+
+```
+chrome__evaluate → "JSON.stringify(window.__consoleErrors || [])"
+```
+
+Or navigate and observe any error output from Chrome MCP tool responses.
+
+### Get Page Content
+
+```
+chrome__get_content → extract DOM/text to verify rendered output matches expectations
+```
+
+## Step 2B: Chrome MCP NOT Available — Fallback to chrome-devtools Skill
+
+When Chrome MCP is not configured, use `ck:chrome-devtools` skill (Puppeteer with bundled Chromium):
+
+```bash
+SKILL_DIR="$HOME/.opencode/skills/chrome-devtools/scripts"
+
+# Install deps if first time
+npm install --prefix "$SKILL_DIR" 2>/dev/null
+
+# Screenshot + console error check
+node "$SKILL_DIR/screenshot.js" --url http://localhost:3000 --output ./verification-screenshot.png
+node "$SKILL_DIR/console.js" --url http://localhost:3000 --types error,pageerror --duration 5000
+```
+
+If `ck:chrome-devtools` skill is also unavailable, skip visual verification and note in report:
+> "Visual verification skipped — no Chrome MCP or chrome-devtools available."
+
+## Step 3: Analyze Results
+
+After capture:
+1. **Read screenshot** — Use Read tool on the PNG to visually inspect
+2. **Check console output** — Zero errors = pass; errors = investigate before claiming done
+3. **Compare with expected** — Match against design specs or user description
+4. **Document findings** — Include screenshot path and any issues found in verification report
+
+## Integration with Verification Protocol
+
+This technique extends `verification.md`. After standard verification (tests pass, build succeeds), add frontend verification as final gate:
+
+```
+Standard verification → Tests pass → Build succeeds → Frontend visual verification → Claim complete
+```
+
+Report format:
+```
+## Frontend Verification
+- Method: [Chrome MCP | chrome-devtools | skipped]
+- Screenshot: ./verification-screenshot.png
+- Console errors: [none | list]
+- Visual check: [pass | issues found]
+- Responsive: [checked at X viewports | skipped]
+```