@hienlh/ppm 0.9.81 → 0.9.82

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

@@ -1,153 +0,0 @@
----
-name: ck:autoresearch
-description: "Autonomous iterative optimization loop — run N iterations against a mechanical metric, learn from git history, auto-keep/discard changes. Use for improving measurable metrics (coverage, performance, bundle size, etc.) through repeated experimentation."
-argument-hint: "[Goal/Metric description] or inline config block"
-metadata:
-  author: claudekit
-  attribution: "Core patterns adapted from autoresearch by Udit Goenka (MIT)"
-  license: MIT
-  version: "1.0.0"
----
-
-# ck:autoresearch — Autonomous Optimization Loop
-
-> Constraint + Mechanical Metric + Fast Verification = Autonomous Improvement
-
-## When to Use
-
-- Improve a measurable metric (test coverage, bundle size, ESLint errors, Lighthouse score, etc.)
-- Autonomous execution over N iterations without manual intervention
-- Git-tracked experiments where you want rollback on regression
-- Exploring a search space of code changes with consistent evaluation
-
-## When NOT to Use
-
-| Situation | Better Tool |
-|-----------|-------------|
-| Subjective goals ("make it cleaner") | `ck:cook` |
-| Bug fixing with known root cause | `ck:fix` or `ck:debug` |
-| One-shot tasks, no repetition needed | `ck:cook` |
-| No mechanical metric to measure progress | `ck:cook --interactive` |
-| Files outside a defined scope | manual approach |
-
-## Configuration Format
-
-Parsed from user message. Missing required fields trigger a **batched** `AskUserQuestion`.
-
-### Required
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `Goal` | Human description of what to improve | `"Increase test coverage in src/utils"` |
-| `Scope` | Glob pattern(s) for editable files | `"src/utils/**/*.ts"` |
-| `Verify` | Shell command that outputs **a single number** | `"npx jest --coverage --json \| jq '.coverageMap \| .. \| .s? \| to_entries \| map(.value) \| (map(select(.>0)) \| length) / length * 100' \| tail -1"` |
-
-### Optional
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `Guard` | none | Regression check command (exit 0 = pass) |
-| `Iterations` | 10 | Maximum iterations to run |
-| `Noise` | medium | Tolerance for metric variance: `low` / `medium` / `high` |
-| `Min-Delta` | 0 | Minimum improvement to count as progress |
-| `Direction` | higher | Whether `higher` or `lower` metric value is better |
-
-## Interactive Setup
-
-When required fields are missing, ask all at once:
-
-```
-AskUserQuestion({
-  questions: [
-    { question: "What metric do you want to improve? (e.g. 'test coverage in src/utils')", field: "Goal" },
-    { question: "Which files may be edited? (glob, e.g. 'src/utils/**/*.ts')", field: "Scope" },
-    { question: "Verify command — must print a single number to stdout", field: "Verify" },
-    { question: "Guard command for regression check? (optional, press Enter to skip)", field: "Guard" }
-  ]
-})
-```
-
-## Core Protocol
-
-See [`references/autonomous-loop-protocol.md`](references/autonomous-loop-protocol.md) for the full 8-phase specification.
-
-**Key invariants:**
-- ONE atomic change per iteration — atomicity test: can you describe it in one sentence without "and"?
-- Commit BEFORE verify — git is memory, not a safety net
-- Guard files are **read-only** — never modify files in guard command's scope
-- Prefer `git revert` over `git reset` — preserve history
-
-## Results Logging
-
-Each iteration appends a TSV line to `loop-results.tsv` in the working directory:
-
-```
-iteration	commit	metric	delta	status	description
-0	a1b2c3d	80.0	-	baseline	initial measurement
-1	e4f5a6b	82.4	+2.4	keep	add null checks to parser.ts
-2	-	81.9	-0.5	discard	extract helper function
-```
-
-See [`references/autonomous-loop-protocol.md`](references/autonomous-loop-protocol.md) — Phase 7 for full schema.
-
-## Stuck Detection
-
-| Condition | Action |
-|-----------|--------|
-| 5 consecutive discards | Analyze patterns → shift strategy (different files, different approach) |
-| 10 consecutive discards | STOP — report findings, surface to user |
-
-## Example Invocations
-
-### 1. Increase test coverage
-
-```
-/ck:autoresearch
-Goal: Increase test coverage in src/utils from ~60% to 80%
-Scope: src/utils/**/*.ts, tests/utils/**/*.test.ts
-Verify: npx jest tests/utils --coverage --coverageReporters=json-summary 2>/dev/null | node -e "const d=require('./coverage-summary.json');console.log(d.total.lines.pct)"
-Guard: npx tsc --noEmit && npx jest --passWithNoTests
-Iterations: 15
-Direction: higher
-```
-
-### 2. Reduce bundle size
-
-```
-/ck:autoresearch
-Goal: Reduce main bundle size below 200KB
-Scope: src/**/*.ts, src/**/*.tsx
-Verify: npx vite build 2>/dev/null | grep "dist/index" | awk '{print $2}' | sed 's/kB//'
-Guard: npx tsc --noEmit
-Direction: lower
-Min-Delta: 0.5
-```
-
-### 3. Eliminate ESLint errors
-
-```
-/ck:autoresearch
-Goal: Drive ESLint error count to zero in src/api
-Scope: src/api/**/*.ts
-Verify: npx eslint src/api --format=json 2>/dev/null | node -e "const r=require('/dev/stdin');console.log(r.reduce((a,f)=>a+f.errorCount,0))" || echo 999
-Direction: lower
-Iterations: 20
-```
-
-## Limitations (Honest)
-
-- Cannot optimize subjective or aesthetic goals
-- Cannot modify files outside the declared `Scope`
-- Cannot modify files referenced by the `Guard` command
-- Cannot guarantee improvement — some metrics have hard ceilings
-- Requires a **git repository with a clean working tree** before starting
-- `Verify` command must complete in **< 30 seconds** (otherwise loop is impractical)
-- Does not parallelize iterations — sequential by design (each iteration learns from the last)
-
-## References
-
-- [`references/autonomous-loop-protocol.md`](references/autonomous-loop-protocol.md) — Full 8-phase loop spec, decision matrix, anti-patterns
-- [`references/git-memory-pattern.md`](references/git-memory-pattern.md) — Git as cross-iteration memory, revert vs reset, commit conventions
-- [`references/guard-and-noise.md`](references/guard-and-noise.md) — Guard pattern for regression prevention, noise-aware verification
-- [`references/results-logging.md`](references/results-logging.md) — TSV format spec, progressive summaries
-- [`references/metric-library.md`](references/metric-library.md) — Common verify commands by domain

package/.opencode/skills/ck-autoresearch/references/autonomous-loop-protocol.md

@@ -1,193 +0,0 @@
-# Autonomous Loop Protocol
-
-8-phase specification executed each iteration. Complete phases in order — no skipping.
-
----
-
-## Phase 0: Precondition Checks (first iteration only)
-
-Run once before the loop starts. Abort with clear error if any check fails.
-
-1. Confirm current directory is a git repository (`git rev-parse --git-dir`)
-2. Confirm working tree is clean (`git status --porcelain` → empty output)
-3. Confirm current HEAD is on a named branch (not detached)
-4. Check no stale lock files (`loop-results.tsv.lock`)
-5. Resolve scope glob — confirm at least one file matches
-6. Dry-run verify command — confirm it exits 0 and outputs a number
-7. Dry-run guard command (if set) — confirm it exits 0
-8. Record **baseline metric** as iteration 0 in `loop-results.tsv`
-
----
-
-## Phase 1: Review
-
-Read context before every iteration — do not skip even if "nothing changed".
-
-```bash
-git log --oneline -20              # recent history
-git diff HEAD~1                    # last change detail
-cat loop-results.tsv               # full results so far
-```
-
-Extract patterns:
-- Which file types / functions yielded improvements?
-- Which changes were consistently discarded?
-- Is the metric trending, plateauing, or oscillating?
-
----
-
-## Phase 2: Ideate
-
-Pick **ONE** focused change. Rules:
-
-- **Exploit** patterns from successful iterations
-- **Avoid** repeating failed patterns (same file + same approach)
-- **Atomicity test:** describe the change in one sentence. If the sentence contains "and", split into two iterations.
-- Prefer high-leverage targets (files with low coverage, large bundle contributors, most lint errors)
-- When stuck (3+ consecutive discards on same area), pivot to a different file or technique
-
----
-
-## Phase 3: Modify
-
-- Edit files within `Scope` only
-- **Never** modify files referenced by the `Guard` command
-- Ensure syntax is valid after edit (run `tsc --noEmit` or equivalent linter for the language)
-- Keep changes minimal — one logical unit
-
----
-
-## Phase 4: Commit
-
-Commit **before** running verification. Git is the undo mechanism, not a post-hoc save.
-
-```bash
-git add <changed files>
-git commit -m "loop(iter-N): <one-line description>"
-```
-
-Convention: `loop(iter-N):` prefix enables log filtering later.
-
----
-
-## Phase 5: Verify
-
-Run the configured verify command. Extract the numeric result.
-
-```bash
-RESULT=$(eval "$VERIFY_CMD")
-DELTA=$(echo "$RESULT - $PREV_METRIC" | bc)
-```
-
-### Crash Recovery
-
-| Outcome | Meaning | Action |
-|---------|---------|--------|
-| Exit 0, number printed | Success | Proceed to Phase 5.5 / 6 |
-| Exit 0, no number | Bad command | Log `error:no-number`, revert, fix verify cmd |
-| Exit non-zero | Verify crash | Log `error:verify-crash`, revert, treat as discard |
-| Timeout (>30s) | Too slow | Log `error:timeout`, abort loop, surface to user |
-
----
-
-## Phase 5.5: Guard (optional — skip if no Guard configured)
-
-Run guard command after verify.
-
-```bash
-eval "$GUARD_CMD"
-GUARD_EXIT=$?
-```
-
-| Guard Exit | Action |
-|------------|--------|
-| 0 (pass) | Proceed to Phase 6 |
-| Non-zero (fail) | Revert commit, rework change (max 2 rework attempts), then discard |
-
-If rework attempts exhausted: log as discarded with reason `guard-fail`, proceed to Phase 7.
-
----
-
-## Phase 6: Decide
-
-### Decision Matrix
-
-| Metric Direction | Delta vs Min-Delta | Guard | Decision |
-|------------------|--------------------|-------|----------|
-| higher is better | delta ≥ Min-Delta | pass | **KEEP** |
-| higher is better | delta < Min-Delta | pass | **DISCARD** (no progress) |
-| lower is better  | delta ≤ -Min-Delta | pass | **KEEP** |
-| lower is better  | delta > -Min-Delta | pass | **DISCARD** (no progress) |
-| any | any | fail | **DISCARD** (guard fail) |
-| any | verify crash | n/a | **DISCARD** (error) |
-
-### Keep
-
-- Update `PREV_METRIC` to current result
-- Reset consecutive-discard counter to 0
-
-### Discard
-
-```bash
-git revert HEAD --no-edit    # preferred: preserves history
-# fallback only if revert conflicts:
-# git reset --hard HEAD~1
-```
-
-- Increment consecutive-discard counter
-
----
-
-## Phase 7: Log
-
-Append one TSV line to `loop-results.tsv`:
-
-```
-{iteration}\t{commit}\t{metric}\t{delta:+.2f}\t{status}\t{description}
-```
-
-Example:
-```
-3	c7d8e9f	84.7	+2.3	keep	add branch coverage to tokenizer edge cases
-4	-	84.7	+0.0	discard	extract shared assertion helper
-```
-
----
-
-## Phase 8: Repeat or Stop
-
-Continue if ALL conditions met:
-- Iteration count < configured max
-- Consecutive discards < 10
-- User has not interrupted (check for `loop-stop` file or Ctrl-C signal)
-
-### Stuck Detection
-
-| Consecutive Discards | Action |
-|----------------------|--------|
-| 5 | Analyze `loop-results.tsv` for patterns → shift strategy (different scope area, different technique) |
-| 10 | **STOP** — surface findings to user, recommend manual intervention |
-
-### Final Report
-
-When loop ends (limit reached, stuck, or interrupted):
-
-```
-Loop complete: N iterations, K kept, best metric: X (baseline: Y, delta: +Z)
-Kept changes: [list commit hashes and descriptions]
-Discarded: [count] iterations
-Recommendation: [continue / diminishing returns / target met]
-```
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Correct Approach |
-|--------------|--------------|------------------|
-| Multiple changes per iteration | Cannot attribute metric change to specific edit | One atomic change only |
-| Verify before commit | No rollback point if verify crashes mid-run | Always commit first |
-| Editing guard-scope files | Guard becomes meaningless if you edit what it checks | Guard files are read-only |
-| `git reset` instead of `git revert` | Destroys history, breaks pattern analysis | Use `git revert` |
-| Skipping Phase 1 review | Repeats failed patterns, wastes iterations | Always read log + diff |
-| Ignoring `Min-Delta` | Micro-improvements cause noise, no real progress | Set meaningful threshold |

package/.opencode/skills/ck-autoresearch/references/git-memory-pattern.md

@@ -1,109 +0,0 @@
-# Git as Long-Term Memory
-
-Git history is the loop's only persistent memory across iterations. Read it every time.
-
----
-
-## Required Reads — Every Iteration
-
-Run these at the start of Phase 1 (Review) without exception:
-
-```bash
-git log --oneline -20              # what changed and in what order
-git diff HEAD~1                    # exact diff of last iteration
-cat loop-results.tsv               # metric trend + keep/discard record
-```
-
-Together these answer three questions:
-1. **What worked?** (kept=yes rows with positive delta)
-2. **What failed?** (kept=no rows, repeated file paths)
-3. **Where is the trend going?** (last 5 deltas — accelerating, flat, or reversing?)
-
----
-
-## Pattern Recognition
-
-### Exploit Successful Patterns
-
-- Same file category that improved before → try adjacent files
-- Same technique (e.g. adding edge-case tests) → apply to untouched functions
-- Larger delta correlates with specific module → prioritize that module
-
-### Avoid Failed Patterns
-
-- File + technique combination that was discarded → do not retry same pair
-- Zero-delta changes (e.g. refactors that don't move the metric) → skip unless required by guard
-- Oscillating metric on a file → leave it, move elsewhere
-
-### Detect Diminishing Returns
-
-If last 5 kept iterations all have `delta < Min-Delta * 2`, the low-hanging fruit is gone. Signal:
-- Broaden scope to adjacent files
-- Switch technique entirely
-- Report plateau to user rather than grinding
-
----
-
-## Stuck Detection Integration
-
-Track consecutive discards in a shell variable or temp file across phases:
-
-```bash
-CONSEC_DISCARDS=0   # reset on keep, increment on discard
-
-# After Phase 6 decision:
-if kept; then
-  CONSEC_DISCARDS=0
-else
-  CONSEC_DISCARDS=$((CONSEC_DISCARDS + 1))
-fi
-
-# Phase 8 checks:
-[ $CONSEC_DISCARDS -ge 5 ]  && shift_strategy
-[ $CONSEC_DISCARDS -ge 10 ] && stop_loop
-```
-
----
-
-## Revert vs Reset
-
-Always prefer `git revert`. Only fall back to `git reset` when revert produces a conflict.
-
-| Command | Preserves history | Safe for pattern analysis | Use when |
-|---------|------------------|--------------------------|----------|
-| `git revert HEAD --no-edit` | Yes | Yes | Default discard path |
-| `git reset --hard HEAD~1` | No | No | Revert conflicts only |
-
-Reason: `git log --grep="loop(iter-"` relies on intact history. A reset destroys the record of what was tried and silently breaks pattern analysis in future iterations.
-
----
-
-## Commit Message Convention
-
-```
-loop(iter-N): <one-line description of the change>
-```
-
-Examples:
-```
-loop(iter-3): add null guard to parseToken in lexer.ts
-loop(iter-7): split large test fixture into focused unit cases
-loop(iter-12): remove unused lodash import reducing bundle 1.2kB
-```
-
-This convention enables targeted log queries:
-
-```bash
-# All loop commits
-git log --oneline --grep="loop(iter-"
-
-# Only kept changes (cross-reference with loop-results.tsv)
-git log --oneline --grep="loop(iter-" | head -20
-```
-
-Reverted commits remain in history with the standard revert message:
-```
-Revert "loop(iter-4): ..."
-```
-
-This is intentional — discards are part of the experiment record.

package/.opencode/skills/ck-autoresearch/references/guard-and-noise.md

@@ -1,140 +0,0 @@
-# Guard Pattern & Noise-Aware Verification
-
-## Guard Pattern (Regression Prevention)
-
-The verify command measures improvement. The guard command confirms nothing else broke.
-
-**Separation of concerns:**
-- Verify = "did the target metric improve?"
-- Guard = "did anything else break?"
-
-### How It Works
-
-1. Baseline run: guard command must exit 0 before loop starts (establishes clean baseline)
-2. After verify succeeds (Phase 5.5), run guard command — BEFORE the keep/discard decision
-3. If guard exits non-zero: trigger recovery flow
-
-### Guard Recovery Flow
-
-```
-Guard fails →
-  revert to previous commit →
-  rework attempt 1 (different approach) →
-    if guard fails again →
-  rework attempt 2 (minimal change) →
-    if guard fails again →
-  discard (log status: guard-failed)
-```
-
-**Rule:** If guard cannot pass at baseline, fix it before starting the loop — never relax the guard.
-
-**Rule:** Guard files are READ-ONLY. Never modify test files, spec files, or guard scripts as part of an optimization attempt.
-
-**Rule:** Guard failure means the optimization is wrong, not that the guard is wrong.
-
-### Common Guard Commands
-
-| Stack | Guard Command | Notes |
-|-------|--------------|-------|
-| Node.js | `npm test` | Runs Jest/Vitest suite |
-| Python | `pytest` | Full test suite |
-| Go | `go test ./...` | All packages |
-| Rust | `cargo test` | Unit + integration |
-| TypeScript | `tsc --noEmit && npm test` | Type check then tests |
-| Any | `npm run lint && npm test` | Lint + test combined |
-
-### Guard Command Selection Heuristic
-
-- If optimizing runtime code → guard = full test suite
-- If optimizing build/bundle → guard = `tsc --noEmit` + smoke test
-- If optimizing ML pipeline → guard = test suite + data schema validation
-- Default when unsure → `npm test` / `pytest` / `go test ./...`
-
----
-
-## Noise-Aware Verification
-
-Noisy metrics produce false positives. A "5% improvement" that's really measurement variance leads to keeping bad changes.
-
-### Noise Levels
-
-| Level | Description | Strategy |
-|-------|-------------|----------|
-| Low | Deterministic output (LOC, type errors, lint count) | Single run, trust result |
-| Medium | Slight variance (build time ±5%, unit test timing) | 2 runs, use worse result |
-| High | High variance (API latency, benchmark, ML accuracy) | 3-5 runs, use median |
-
-### Multi-Run Median (High Noise)
-
-```
-runs = []
-repeat 3-5 times:
-  result = run verify command
-  runs.append(result)
-metric = median(runs)
-```
-
-Use median, not mean — median is resistant to single outlier spikes.
-
-### Min-Delta Threshold
-
-Only keep an attempt if improvement exceeds the threshold:
-
-```
-improvement = previous_best - new_metric   # for "lower is better"
-if improvement < min_delta:
-  status = no-op   # do not keep, but not a failure
-```
-
-**Default thresholds by noise level:**
-- Low noise: 0 (any improvement counts)
-- Medium noise: 1-2% of baseline
-- High noise: 3-5% of baseline
-
-### Confirmation Run
-
-For high-stakes metrics (final 3 iterations, or improvement > 20%), re-verify before committing:
-
-```
-candidate looks good →
-  run verify one more time →
-  compare to initial measurement this iteration →
-  if within 2% → confirm keep
-  if outside 2% → treat as medium noise, average the two
-```
-
-### Environment Pinning (User Responsibility)
-
-ck:loop cannot control the environment. User must ensure:
-- Fixed random seeds for ML workloads
-- Warmed caches (or cold caches) consistently
-- No background processes competing for CPU
-- Same input data across runs
-
-### Config Examples
-
-**Low noise (lint errors):**
-```
-verify: eslint src --format json | jq '[.[] | .errorCount] | add'
-noise: low
-min_delta: 0
-guard: npm test
-```
-
-**Medium noise (build time):**
-```
-verify: { start=$(date +%s%N); npm run build; echo $(( ($(date +%s%N) - start) / 1000000 )); }
-noise: medium
-runs: 2
-min_delta: 200   # ms
-guard: tsc --noEmit
-```
-
-**High noise (API latency):**
-```
-verify: wrk -t2 -c10 -d10s http://localhost:3000/api/health | grep 'Latency' | awk '{print $2}' | sed 's/ms//'
-noise: high
-runs: 5
-min_delta: 5   # ms
-guard: npm test
-```