selftune 0.1.2 → 0.2.0

package/skill/Workflows/Composability.md

@@ -0,0 +1,100 @@
+# selftune Composability Workflow
+
+Analyze how skills interact when triggered together in the same session.
+Detects conflict candidates — skill pairs that produce more errors when
+co-occurring than when used alone.
+
+## Default Command
+
+```bash
+selftune composability --skill <name> [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--skill <name>` | Skill to analyze | Required |
+| `--window <n>` | Only analyze sessions from last N days | All sessions |
+| `--telemetry-log <path>` | Path to telemetry log | `~/.claude/session_telemetry_log.jsonl` |
+
+## Output Format
+
+```json
+{
+  "skill_name": "Research",
+  "analyzed_sessions": 150,
+  "co_occurring_skills": [
+    {
+      "skill_a": "Research",
+      "skill_b": "Browser",
+      "co_occurrence_count": 42,
+      "conflict_score": 0.12,
+      "avg_errors_together": 1.5,
+      "avg_errors_alone": 1.3
+    }
+  ],
+  "conflict_candidates": [
+    {
+      "skill_a": "Research",
+      "skill_b": "Content",
+      "co_occurrence_count": 15,
+      "conflict_score": 0.45,
+      "avg_errors_together": 3.2,
+      "avg_errors_alone": 1.1
+    }
+  ],
+  "generated_at": "2026-03-04T12:00:00.000Z"
+}
+```
+
+## How It Works
+
+The analyzer is a pure function that computes conflict scores from telemetry:
+
+1. Filters sessions where `skills_triggered` includes the target skill
+2. For each co-occurring skill, computes:
+   - Average errors when both skills are triggered together
+   - Average errors when each skill is triggered alone
+   - `conflict_score = clamp((errors_together - errors_alone) / (errors_alone + 1), 0, 1)`
+3. Pairs with `conflict_score > 0.3` are flagged as conflict candidates
+4. Results sorted by co-occurrence count (most common first)
+
+## Steps
+
+### 1. Run Analysis
+
+```bash
+selftune composability --skill Research
+```
+
+### 2. Interpret Results
+
+| Conflict Score | Interpretation |
+|---------------|---------------|
+| 0.0–0.1 | No conflict — skills work well together |
+| 0.1–0.3 | Minor friction — monitor but no action needed |
+| 0.3–0.6 | Moderate conflict — investigate trigger overlap |
+| 0.6–1.0 | Severe conflict — skills likely interfere with each other |
+
+### 3. Address Conflicts
+
+For conflict candidates:
+- Check for trigger keyword overlap between the skills
+- Check if one skill's workflow interferes with the other's
+- Consider evolving descriptions to reduce false triggers
+- Use the `pattern-analyst` agent for deeper cross-skill analysis
+
+## Common Patterns
+
+**"Are there conflicts between my skills?"**
+> `selftune composability --skill Research`
+
+**"Check composability for recent sessions only"**
+> `selftune composability --skill pptx --window 7`
+
+**"Which skills conflict with Research?"**
+> Run composability and check the `conflict_candidates` array.
+
+**"Why are sessions with multiple skills failing?"**
+> Run composability for each skill involved, look for high conflict scores.

package/skill/Workflows/Contribute.md

@@ -0,0 +1,91 @@
+# selftune Contribute Workflow
+
+Export anonymized skill observability data as a JSON bundle for community
+contribution. Helps improve selftune's skill routing without exposing
+private data.
+
+## When to Use
+
+- Want to help improve selftune's skill routing
+- Sharing anonymized usage patterns with the community
+- Contributing eval data for skill evolution
+
+## Default Command
+
+```bash
+selftune contribute --skill selftune
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--skill <name>` | Skill to contribute data for (default: "selftune") |
+| `--output <path>` | Output file path (default: auto-generated in ~/.selftune/contributions/) |
+| `--preview` | Show what would be shared without writing |
+| `--sanitize <level>` | `conservative` (default) or `aggressive` |
+| `--since <date>` | Only include data from this date onward |
+| `--submit` | Auto-create GitHub Issue via `gh` CLI |
+
+## Sanitization Levels
+
+### Conservative (default)
+
+| Pattern | Replacement |
+|---------|-------------|
+| File paths | `[PATH]` |
+| Email addresses | `[EMAIL]` |
+| API keys, tokens, JWTs | `[SECRET]` |
+| IP addresses | `[IP]` |
+| Project name from cwd | `[PROJECT]` |
+| Session IDs | `[SESSION]` |
+
+### Aggressive
+
+Extends conservative with:
+
+| Pattern | Replacement |
+|---------|-------------|
+| camelCase/PascalCase identifiers > 8 chars | `[IDENTIFIER]` |
+| Quoted strings | `[STRING]` |
+| Import/require module paths | `[MODULE]` |
+| Queries > 200 chars | Truncated |
+
+## Bundle Contents
+
+The contribution bundle includes:
+- **Positive queries** -- queries that triggered the skill (sanitized)
+- **Eval entries** -- trigger eval set for the skill
+- **Grading summary** -- aggregate pass rates (no raw transcripts)
+- **Evolution summary** -- proposal counts and outcomes
+- **Session metrics** -- average turns, tool usage, error rates
+
+No raw transcripts, file contents, or identifiable information is included.
+
+## Submission
+
+- Default: writes JSON file to `~/.selftune/contributions/`
+- `--submit`: creates a GitHub Issue with the bundle
+  - Small bundles (< 50KB): inlined in issue body
+  - Large bundles (>= 50KB): uploaded as a gist
+
+## Steps
+
+1. Run `selftune contribute --preview --skill selftune` to see what would be shared
+2. Review the sanitized output
+3. Run `selftune contribute --skill selftune` to write the bundle
+4. Optionally: `selftune contribute --skill selftune --submit` to create GitHub issue
+
+## Common Patterns
+
+**"Preview what I'd share"**
+> `selftune contribute --preview`
+
+**"Use aggressive sanitization"**
+> `selftune contribute --sanitize aggressive`
+
+**"Submit directly to GitHub"**
+> `selftune contribute --submit`
+
+**"Only contribute recent data"**
+> `selftune contribute --since 2026-02-01`

package/skill/Workflows/Cron.md

@@ -0,0 +1,155 @@
+# selftune Cron Workflow
+
+Manage OpenClaw cron jobs that run the selftune pipeline on a schedule.
+Enables fully autonomous skill evolution — skills improve while you sleep.
+
+## When to Use
+
+- Setting up selftune automation for the first time on OpenClaw
+- Checking which cron jobs are registered
+- Removing selftune cron jobs (cleanup or reconfiguration)
+- Enabling the autonomous observe-grade-evolve-deploy loop
+
+## Prerequisites
+
+OpenClaw must be installed and in your PATH. The setup command will check
+for this and exit with instructions if OpenClaw is not found.
+
+```bash
+which openclaw    # Must resolve
+```
+
+## Default Command
+
+```bash
+selftune cron setup
+```
+
+## Subcommands
+
+### `selftune cron setup`
+
+Register the default selftune cron jobs with OpenClaw.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Preview commands without registering jobs | Off |
+| `--tz <timezone>` | IANA timezone for job schedules | Flag > `TZ` env > system timezone |
+
+### `selftune cron list`
+
+Show all registered selftune cron jobs. Reads from
+`~/.openclaw/cron/jobs.json` and filters for `selftune-*` entries.
+No flags.
+
+### `selftune cron remove`
+
+Remove all selftune cron jobs from OpenClaw.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Preview which jobs would be removed without deleting | Off |
+
+## Default Job Schedule
+
+Setup registers these four jobs:
+
+| Name | Cron Expression | Schedule | Description |
+|------|----------------|----------|-------------|
+| `selftune-ingest` | `*/30 * * * *` | Every 30 minutes | Ingest new sessions from OpenClaw transcripts |
+| `selftune-status` | `0 8 * * *` | Daily at 8am | Health check — report skills with pass rate below 80% |
+| `selftune-evolve` | `0 3 * * 0` | Weekly at 3am Sunday | Full evolution pipeline for undertriggering skills |
+| `selftune-watch` | `0 */6 * * *` | Every 6 hours | Monitor recently evolved skills for regressions |
+
+All jobs run in **isolated session** mode — each execution gets a clean
+session with no context accumulation from previous runs.
+
+## Output
+
+- **setup:** Registers jobs via `openclaw cron add` and confirms each registration
+- **list:** Prints a formatted table of registered selftune cron jobs (name, schedule, description)
+- **remove:** Deletes each selftune cron job via `openclaw cron remove` and confirms
+
+Jobs persist at `~/.openclaw/cron/jobs.json` and survive OpenClaw restarts.
+
+## Steps
+
+1. Run `selftune cron setup --dry-run` to preview what would be registered
+2. Run `selftune cron setup` to register the default jobs
+3. Run `selftune cron list` to verify jobs are registered
+4. Wait for the first cron cycle to fire (ingest runs every 30 minutes)
+5. Check results with `selftune status` after the first daily health check
+
+## The Autonomous Evolution Loop
+
+When cron jobs are active, selftune operates as a self-correcting system:
+
+```
+Cron fires (isolated session)
+    |
+    v
+Agent runs selftune pipeline (ingest -> status -> evolve -> watch)
+    |
+    v
+Improved SKILL.md written to disk
+    |
+    v
+OpenClaw file watcher detects change (250ms debounce)
+    |
+    v
+Skill snapshot version bumped — next agent turn uses updated description
+    |
+    v
+Better triggering in real-time, no restart needed
+```
+
+The four jobs form a continuous loop:
+- **ingest** captures raw session data every 30 minutes
+- **status** identifies undertriggering skills daily
+- **evolve** proposes and deploys improvements weekly
+- **watch** monitors for regressions every 6 hours and auto-rolls back if needed
+
+Skills improve and take effect within seconds of the cron job completing.
+No deployment step, no restart, no manual intervention.
+
+## Safety Controls
+
+| Control | How It Works |
+|---------|-------------|
+| Dry-run first | `selftune cron setup --dry-run` previews commands before registering |
+| Regression threshold | Evolution only deploys if improvement exceeds 5% on existing triggers |
+| Auto-rollback | `selftune watch` automatically rolls back if pass rate drops below baseline minus threshold |
+| Audit trail | Every evolution recorded in `evolution_audit_log.jsonl` with full history |
+| SKILL.md backup | `.bak` file created before every deploy — primary rollback path exists via .bak; fallback depends on audit metadata integrity |
+| Isolated sessions | Each cron run gets a clean session (no context pollution between runs) |
+| Human override | `selftune rollback --skill <name> --skill-path <path>` available anytime to manually revert |
+| Pin descriptions | Config flag to freeze specific skills and prevent evolution on sensitive skills |
+
+## Common Patterns
+
+**"Set up autonomous skill evolution"**
+> Run `selftune cron setup`. The four default jobs handle ingestion,
+> health checks, evolution, and regression monitoring.
+
+**"Preview before registering"**
+> Run `selftune cron setup --dry-run` to see exactly what commands
+> would be executed without registering anything.
+
+**"Use a specific timezone"**
+> Run `selftune cron setup --tz America/New_York`. Without the flag,
+> timezone resolution is: `--tz` flag > `TZ` environment variable > system timezone.
+
+**"What jobs are registered?"**
+> Run `selftune cron list`. Shows a table of all selftune cron jobs
+> with their schedules and descriptions.
+
+**"Remove all cron automation"**
+> Run `selftune cron remove`. Preview first with `selftune cron remove --dry-run`.
+
+**"A skill regressed after cron evolution"**
+> The watch job should catch this automatically. If not, run
+> `selftune rollback --skill <name>` manually. See `Workflows/Rollback.md`.
+
+**"How do I know the cron loop is working?"**
+> Run `selftune status` after the first daily health check fires (8am).
+> Check `evolution_audit_log.jsonl` for entries with recent timestamps.

package/skill/Workflows/Dashboard.md

@@ -0,0 +1,203 @@
+# selftune Dashboard Workflow
+
+Visual dashboard for selftune telemetry, skill performance, evolution
+audit, and monitoring data. Supports static HTML export, file output,
+and a live server with SSE auto-refresh and action buttons.
+
+## Default Command
+
+```bash
+selftune dashboard
+```
+
+Opens a standalone HTML dashboard in the default browser with embedded
+data from all selftune log files.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--export` | Export data-embedded HTML to stdout | Off |
+| `--out FILE` | Write data-embedded HTML to FILE | None |
+| `--serve` | Start live dashboard server | Off |
+| `--port <port>` | Custom port for live server (requires `--serve`) | 3141 |
+
+## Modes
+
+### Static (Default)
+
+Builds an HTML file with all telemetry data embedded as JSON, saves it
+to `~/.selftune/dashboard.html`, and opens it in the default browser.
+The data is a point-in-time snapshot -- refresh by re-running the command.
+
+```bash
+selftune dashboard
+```
+
+### Export
+
+Writes the same data-embedded HTML to stdout. Useful for piping to other
+tools or capturing output programmatically.
+
+```bash
+selftune dashboard --export > dashboard.html
+```
+
+### File
+
+Writes the data-embedded HTML to a specific file path.
+
+```bash
+selftune dashboard --out /tmp/report.html
+```
+
+### Live Server
+
+Starts a Bun HTTP server with real-time data updates via Server-Sent
+Events (SSE). The dashboard auto-refreshes every 5 seconds and provides
+action buttons to trigger selftune commands.
+
+```bash
+selftune dashboard --serve
+selftune dashboard --serve --port 8080
+```
+
+## Live Server
+
+### Default Port
+
+The live server binds to `localhost:3141` by default. Use `--port` to
+override.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Serve dashboard HTML with embedded data and live mode flag |
+| `GET` | `/api/data` | JSON endpoint returning current telemetry data |
+| `GET` | `/api/events` | SSE stream sending data updates every 5 seconds |
+| `POST` | `/api/actions/watch` | Trigger `selftune watch` for a skill |
+| `POST` | `/api/actions/evolve` | Trigger `selftune evolve` for a skill |
+| `POST` | `/api/actions/rollback` | Trigger `selftune rollback` for a skill |
+
+### SSE Auto-Refresh
+
+The `/api/events` endpoint opens an SSE connection that pushes fresh
+data every 5 seconds. The dashboard client listens for `data` events
+and re-renders automatically. When `window.__SELFTUNE_LIVE__` is set
+(injected by the live server), the dashboard enables SSE polling.
+
+### Action Endpoints
+
+Action buttons in the dashboard trigger selftune commands via POST
+requests. Each endpoint spawns a `bun run` subprocess.
+
+**Watch and Evolve** request body:
+
+```json
+{
+  "skill": "skill-name",
+  "skillPath": "/path/to/SKILL.md"
+}
+```
+
+**Rollback** request body:
+
+```json
+{
+  "skill": "skill-name",
+  "skillPath": "/path/to/SKILL.md",
+  "proposalId": "proposal-uuid"
+}
+```
+
+All action endpoints return:
+
+```json
+{
+  "success": true,
+  "output": "command stdout",
+  "error": null
+}
+```
+
+On failure, `success` is `false` and `error` contains the error message.
+
+### Browser and Shutdown
+
+The live server auto-opens the dashboard URL in the default browser on
+macOS (`open`) and Linux (`xdg-open`).
+
+Graceful shutdown on `SIGINT` (Ctrl+C) and `SIGTERM`: closes all SSE
+client connections and stops the server.
+
+## Data Contents
+
+The dashboard displays data from these sources:
+
+| Data | Source | Description |
+|------|--------|-------------|
+| Telemetry | `session_telemetry_log.jsonl` | Session-level telemetry records |
+| Skills | `skill_usage_log.jsonl` | Skill activation and usage events |
+| Queries | `all_queries_log.jsonl` | All user queries across sessions |
+| Evolution | `evolution_audit_log.jsonl` | Evolution audit trail (create, deploy, rollback) |
+| Decisions | `~/.selftune/memory/` | Evolution decision records |
+| Snapshots | Computed | Per-skill monitoring snapshots (pass rate, regression status) |
+| Unmatched | Computed | Queries that did not trigger any skill |
+| Pending | Computed | Evolution proposals not yet deployed, rejected, or rolled back |
+
+If no log data is found, the static modes exit with an error message
+listing the checked file paths.
+
+## Steps
+
+### 1. Choose Mode
+
+| Goal | Command |
+|------|---------|
+| Quick visual check | `selftune dashboard` |
+| Save report to file | `selftune dashboard --out report.html` |
+| Pipe to another tool | `selftune dashboard --export` |
+| Live monitoring | `selftune dashboard --serve` |
+
+### 2. Run Command
+
+```bash
+# Static (opens browser)
+selftune dashboard
+
+# Live server
+selftune dashboard --serve
+```
+
+### 3. Interact with Dashboard
+
+- **Static mode**: View the snapshot. Re-run to refresh.
+- **Live mode**: Data refreshes automatically every 5 seconds. Use
+  action buttons to trigger watch, evolve, or rollback directly from
+  the dashboard.
+
+## Common Patterns
+
+**"Show me the dashboard"**
+> Run `selftune dashboard`. Opens a browser with current data.
+
+**"I want live updates"**
+> Run `selftune dashboard --serve`. The SSE stream refreshes every 5
+> seconds without manual intervention.
+
+**"Export a report"**
+> Use `selftune dashboard --out report.html` to save a self-contained
+> HTML file. Share it -- no server needed, all data is embedded.
+
+**"The dashboard shows no data"**
+> No log files found. Run some sessions first so hooks generate
+> telemetry. Check `selftune doctor` to verify hooks are installed.
+
+**"Use a different port"**
+> `selftune dashboard --serve --port 8080`. Port must be 1-65535.
+
+**"Trigger actions from the dashboard"**
+> In live server mode, the dashboard provides buttons to trigger watch,
+> evolve, and rollback for each skill. These call the action endpoints
+> which spawn selftune subprocesses.

package/skill/Workflows/Doctor.md

@@ -82,8 +82,37 @@ Doctor validates these areas:
 
 | Check | What it validates |
 |-------|-------------------|
-| Hooks installed | `UserPromptSubmit`, `PostToolUse`, and `Stop` hooks are configured in `~/.claude/settings.json` |
+| Hooks installed | `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` hooks are configured in `~/.claude/settings.json` |
 | Hook scripts exist | The script files referenced by hooks exist on disk |
+| Auto-activate hook | `hooks/auto-activate.ts` is registered in `UserPromptSubmit` and the file is executable |
+| Evolution guard hook | `hooks/evolution-guard.ts` is registered in `PreToolUse` and the file exists |
+
+### Memory Checks
+
+| Check | What it validates |
+|-------|-------------------|
+| Memory directory exists | `~/.selftune/memory/` directory is present |
+| Memory files valid | `context.md`, `decisions.md`, `plan.md` exist and are non-empty (if previously written) |
+
+### Activation Rules Checks
+
+| Check | What it validates |
+|-------|-------------------|
+| Rules file exists | `~/.selftune/activation-rules.json` is present |
+| Rules file valid | The file contains valid JSON conforming to the activation rules schema |
+
+### Agent Checks
+
+| Check | What it validates |
+|-------|-------------------|
+| Agent directory exists | `.claude/agents/` directory is present |
+| Agent files present | Expected agent files exist: `diagnosis-analyst.md`, `pattern-analyst.md`, `evolution-reviewer.md`, `integration-guide.md` |
+
+### Dashboard Checks (optional)
+
+| Check | What it validates |
+|-------|-------------------|
+| Dashboard server accessible | `dashboard-server.ts` exists in the CLI directory |
 
 ### Evolution Audit Checks
 
@@ -114,6 +143,13 @@ For each failed check, take the appropriate action:
 | Logs not parseable | Inspect the corrupted log file. Remove or fix invalid lines. |
 | Hooks not installed | Merge `skill/settings_snippet.json` into `~/.claude/settings.json`. Update paths. |
 | Hook scripts missing | Verify the selftune repo path. Re-run `init` if the repo was moved. |
+| Auto-activate missing | Add `hooks/auto-activate.ts` to `UserPromptSubmit` in settings. |
+| Evolution guard missing | Add `hooks/evolution-guard.ts` to `PreToolUse` in settings. |
+| Memory directory missing | Run `mkdir -p ~/.selftune/memory`. |
+| Memory files invalid | Delete and let the memory writer recreate them on next evolve/watch. |
+| Activation rules missing | Copy `templates/activation-rules-default.json` to `~/.selftune/activation-rules.json`. |
+| Activation rules invalid | Validate JSON syntax. Re-copy from template if corrupted. |
+| Agent files missing | Copy agents from the selftune repo `.claude/agents/` directory. |
 | Audit log invalid | Remove corrupted entries. Future operations will append clean entries. |
 
 ### 4. Re-run Doctor