selftune 0.1.4 → 0.2.1

package/skill/Workflows/Rollback.md

@@ -6,7 +6,7 @@ Records the rollback in the evolution audit log for traceability.
 ## Default Command
 
 ```bash
-selftune rollback --skill <name> --skill-path <path> [options]
+selftune evolve rollback --skill <name> --skill-path <path> [options]
 ```
 
 ## Options
@@ -75,6 +75,16 @@ Manual restoration from version control is required.
 
 ## Steps
 
+### 0. Read Evolution Context
+
+Before starting, read `~/.selftune/memory/context.md` for session context:
+- Active evolutions and their current status
+- Previous rollback history
+- Last update timestamp
+
+This provides continuity across context resets. If the file doesn't exist,
+proceed normally — it will be created after the first rollback.
+
 ### 1. Find the Last Evolution
 
 Read `~/.claude/evolution_audit_log.jsonl` and find the most recent
@@ -85,13 +95,13 @@ If `--proposal-id` is specified, use that instead.
 ### 2. Run Rollback
 
 ```bash
-selftune rollback --skill pptx --skill-path /path/to/SKILL.md
+selftune evolve rollback --skill pptx --skill-path /path/to/SKILL.md
 ```
 
 Or to rollback a specific proposal:
 
 ```bash
-selftune rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
+selftune evolve rollback --skill pptx --skill-path /path/to/SKILL.md --proposal-id evolve-pptx-1709125200000
 ```
 
 ### 3. Verify Restoration
@@ -101,7 +111,16 @@ After rollback, verify the SKILL.md content is restored:
 - Check the audit log for the `rolled_back` entry
 - Optionally re-run evals to confirm the original pass rate
 
-### 4. Post-Rollback Audit
+### 4. Update Memory
+
+After rollback completes, the memory writer updates:
+- `~/.selftune/memory/decisions.md` -- records the rollback decision and reason
+- `~/.selftune/memory/context.md` -- clears the active evolution state and notes the rollback
+
+This ensures future evolve and watch workflows have context about why the
+rollback occurred, even across context window resets.
+
+### 5. Post-Rollback Audit
 
 The rollback is logged. Future `evolve` runs will see the rollback in the
 audit trail and can use it to avoid repeating failed evolution patterns.

package/skill/Workflows/Schedule.md

@@ -0,0 +1,61 @@
+# selftune Schedule Workflow
+
+Generate ready-to-use scheduling examples for automating selftune with
+standard system tools. This is the **primary automation path** — it works
+on any machine without requiring a specific agent runtime.
+
+For OpenClaw-specific scheduling, see `Workflows/Cron.md`.
+
+## When to Use
+
+- Setting up selftune automation for the first time
+- Generating crontab entries for a Linux/macOS server
+- Creating a launchd plist for a macOS machine
+- Creating a systemd timer for a Linux server
+- Understanding the selftune automation loop
+
+## The Automation Loop
+
+The core selftune automation loop is one command:
+
+```bash
+selftune orchestrate
+```
+
+`selftune orchestrate` runs source-truth sync first, selects candidate skills,
+deploys validated low-risk description changes autonomously, and watches recent
+deployments with auto-rollback enabled.
+
+## Default Command
+
+```bash
+selftune schedule
+```
+
+Outputs examples for all three scheduling systems (cron, launchd, systemd).
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--format <type>` | Output only one format: `cron`, `launchd`, or `systemd` | All formats |
+| `--install` | Write and activate scheduler artifacts for the selected/default platform | Off |
+| `--dry-run` | Preview installed files and activation commands without writing | Off |
+| `--help` | Show help message | — |
+
+## Steps
+
+1. Run `selftune schedule` to see all examples
+2. Pick the scheduling system for your platform
+3. Install them directly with `--install`, or inspect/customize the raw snippets first
+
+## Alias
+
+`selftune schedule` is now an alias for `selftune cron`. Both commands are interchangeable. See `Workflows/Cron.md` for the full cron workflow reference.
+
+## Common Patterns
+
+- **User wants quick setup on a Linux server** -- Run `selftune schedule --install --format cron`.
+- **User wants setup on macOS** -- Run `selftune schedule --install --format launchd`.
+- **User wants setup on a systemd-based server** -- Run `selftune schedule --install --format systemd`.
+- **User mentions OpenClaw** -- Use `selftune cron setup --platform openclaw` for the OpenClaw scheduler adapter. The default product path is still `selftune schedule --install`. See `Workflows/Cron.md`.

package/skill/Workflows/Sync.md

@@ -0,0 +1,88 @@
+# selftune Sync Workflow
+
+Refresh source-truth telemetry across supported agent CLIs, then rebuild the
+repaired skill-usage overlay so status, dashboard, grading, and evolution work
+from real transcripts/rollouts instead of stale hook data.
+
+## When to Use
+
+- Before running `status`, `dashboard`, `watch`, or `evolve` when data may be stale
+- The user has run many Claude Code, Codex, OpenCode, or OpenClaw sessions since last sync
+- The agent detects host logs may be polluted and needs the repaired/source-first view
+- Before exporting data to cloud ingest
+
+## Default Command
+
+```bash
+selftune sync
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--since <date>` | Only sync sessions modified on/after this date |
+| `--dry-run` | Show summary without writing files |
+| `--force` | Ignore per-source markers and rescan everything |
+| `--no-claude` | Skip Claude transcript replay |
+| `--no-codex` | Skip Codex rollout ingest |
+| `--no-opencode` | Skip OpenCode ingest |
+| `--no-openclaw` | Skip OpenClaw ingest |
+| `--no-repair` | Skip rebuilding `skill_usage_repaired.jsonl` |
+
+## Output
+
+Writes/refreshed data:
+- `~/.claude/session_telemetry_log.jsonl`
+- `~/.claude/all_queries_log.jsonl`
+- `~/.claude/skill_usage_log.jsonl`
+- `~/.claude/skill_usage_repaired.jsonl`
+- per-source marker files
+
+## Steps
+
+### 1. Preview Sync
+
+Run `selftune sync --dry-run`. The output includes per-source `scanned`
+counts. Report the preview summary to the user.
+
+### 2. Run Sync
+
+Run `selftune sync`. The output includes:
+- Per-source `scanned`, `synced`, and `skipped` counts
+- Repaired overlay totals
+- Any errors or warnings
+
+### 3. Verify Results
+
+Verify there are no sync errors and that per-source counters are internally
+consistent (`scanned`, `synced`, `skipped`). `synced=0` is valid when no
+new sessions exist since the last sync. Run `selftune doctor` only when
+sync reports source/hook failures or expected active sources are missing.
+
+### 4. Continue to Next Workflow
+
+After sync completes, proceed with the user's intended workflow:
+`selftune status`, `selftune dashboard`, `selftune watch --sync-first`,
+or `selftune evolve --sync-first`.
+
+## Common Patterns
+
+**User wants to refresh telemetry data**
+> Run `selftune sync`. Report per-source `scanned`, `synced`, and `skipped` counts.
+
+**User wants to sync only recent sessions**
+> Run `selftune sync --since <date>` with the user's specified date.
+
+**User wants a full rescan from scratch**
+> Run `selftune sync --force`. This ignores per-source markers and rescans
+> all sessions.
+
+**Agent needs to verify sync worked**
+> Check per-source `scanned`, `synced`, and `skipped` counts. `synced=0`
+> is normal when data is already up-to-date. Verify `scanned > 0` for
+> expected sources to confirm sync ran successfully.
+
+**Agent is chaining into monitoring or evolution**
+> Use `selftune watch --sync-first` or `selftune evolve --sync-first` to
+> refresh source truth automatically before making decisions.

package/skill/Workflows/UnitTest.md

@@ -0,0 +1,150 @@
+# selftune Unit Test Workflow
+
+Run or generate unit tests for individual skills. Tests verify trigger
+accuracy, output content, and tool usage with deterministic assertions.
+
+## Default Command
+
+```bash
+selftune eval unit-test --skill <name> --tests <path> [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--skill <name>` | Skill name | Required |
+| `--tests <path>` | Path to unit test JSON file | `~/.selftune/unit-tests/<skill>.json` |
+| `--run-agent` | Run agent-based assertions (not just trigger checks) | Off |
+| `--generate` | Generate tests from skill content instead of running | Off |
+| `--skill-path <path>` | Path to SKILL.md (required for `--generate`) | None |
+| `--eval-set <path>` | Eval set for failure context (used with `--generate`) | None |
+| `--model <flag>` | Model flag for LLM calls | Agent default |
+
+## Test Format
+
+Tests are stored as JSON arrays in `~/.selftune/unit-tests/<skill>.json`:
+
+```json
+[
+  {
+    "test_id": "research-trigger-1",
+    "skill_name": "Research",
+    "description": "Should trigger on explicit research request",
+    "query": "Research the latest trends in AI safety",
+    "expected_trigger": true,
+    "assertions": [
+      {
+        "type": "trigger_check",
+        "value": "true",
+        "description": "Skill should trigger for this query"
+      }
+    ],
+    "tags": ["explicit", "core"],
+    "source": "manual"
+  }
+]
+```
+
+## Assertion Types
+
+| Type | What it checks | Requires agent? |
+|------|---------------|-----------------|
+| `trigger_check` | Query triggers the skill description | No (LLM only) |
+| `output_contains` | Agent output contains expected text | Yes |
+| `output_matches_regex` | Agent output matches regex pattern | Yes |
+| `tool_called` | Agent used a specific tool | Yes |
+
+Trigger check assertions are cheap (single LLM call). Agent-based assertions
+require `--run-agent` and run the query through the full agent.
+
+## Output Format
+
+```json
+{
+  "skill_name": "Research",
+  "total": 10,
+  "passed": 8,
+  "failed": 2,
+  "pass_rate": 0.80,
+  "results": [
+    {
+      "test_id": "research-trigger-1",
+      "overall_passed": true,
+      "trigger_passed": true,
+      "assertion_results": [
+        { "type": "trigger_check", "value": "true", "passed": true, "evidence": "LLM responded YES" }
+      ],
+      "duration_ms": 450
+    }
+  ],
+  "ran_at": "2026-03-04T12:00:00.000Z"
+}
+```
+
+## Steps
+
+### 1. Generate Tests (First Time)
+
+If no test file exists for the skill, generate initial tests:
+
+```bash
+selftune eval unit-test --skill Research --generate --skill-path ~/.claude/skills/Research/SKILL.md
+```
+
+Parse the output. The LLM creates test cases covering:
+- Explicit trigger queries
+- Implicit trigger queries
+- Contextual trigger queries
+- Negative examples (should NOT trigger)
+
+Tests are saved to `~/.selftune/unit-tests/Research.json`.
+
+### 2. Run Tests
+
+Run the test suite:
+
+```bash
+selftune eval unit-test --skill Research --tests ~/.selftune/unit-tests/Research.json
+```
+
+By default, only `trigger_check` assertions run (fast, no agent needed).
+Add `--run-agent` for full agent-based assertions.
+
+### 3. Parse Results
+
+Parse the JSON output. Check `pass_rate` and investigate failures:
+- Failed trigger checks -- description needs improvement (route to Evolve)
+- Failed output assertions -- skill workflow needs fixes
+- Failed tool assertions -- skill routing is broken
+
+Report the pass rate and any failures to the user.
+
+### 4. Post-Evolution Verification
+
+After evolving a skill, re-run unit tests to verify improvements:
+
+```bash
+selftune eval unit-test --skill Research
+```
+
+Compare the new `pass_rate` against the previous run. Report whether
+the evolution improved trigger accuracy.
+
+## Common Patterns
+
+**User asks to generate tests for a skill**
+> Run `selftune eval unit-test --skill <name> --generate --skill-path <path>`.
+> Parse the output and report how many tests were generated.
+
+**User asks to run existing tests**
+> Run `selftune eval unit-test --skill <name>`. Parse the JSON output and
+> report pass rate and any failures.
+
+**User asks for full agent-based testing**
+> Run `selftune eval unit-test --skill <name> --run-agent`. This runs queries
+> through the full agent, so inform the user it will take longer.
+
+**After an evolution completes**
+> Run unit tests to verify the evolution improved trigger accuracy. Compare
+> the new pass rate against the pre-evolution baseline.

package/skill/Workflows/Watch.md

@@ -65,6 +65,21 @@ selftune watch --skill <name> --skill-path <path> [options]
 
 ## Steps
 
+### 0. Read Evolution Context
+
+Read `~/.selftune/memory/context.md` for session context:
+- Active evolutions and their current status
+- Known issues and regression history
+- Last update timestamp
+
+If the file does not exist, proceed normally -- it will be created after
+the first watch.
+
+The evolution-guard hook prevents conflicting SKILL.md edits while watch is
+evaluating the skill. The auto-activation system uses watch results to
+adjust suggestion confidence -- skills showing regressions get flagged for
+attention in subsequent prompts.
+
 ### 1. Run Watch
 
 ```bash
@@ -87,7 +102,7 @@ Parse the JSON output. Key decision points:
 If regression is detected:
 - Review recent session transcripts to understand what changed
 - Check if the eval set is still representative
-- Run `rollback` if the regression is confirmed (see `Workflows/Rollback.md`)
+- Run `evolve rollback` if the regression is confirmed (see `Workflows/Rollback.md`)
 
 If `--auto-rollback` was set, the command automatically restores the
 previous description and logs a `rolled_back` entry.
@@ -100,6 +115,13 @@ Summarize the snapshot for the user:
 - Whether regression was detected
 - Recommended action
 
+### 5. Update Memory
+
+After watch completes, the memory writer updates
+`~/.selftune/memory/context.md` with the current regression status,
+pass rates, and recommended next action. This ensures continuity if the
+context window resets before the user acts on the results.
+
 ## Common Patterns
 
 **"Is the skill performing well after the change?"**
@@ -119,3 +141,13 @@ Summarize the snapshot for the user:
 **"Set a custom baseline"**
 > Use `--baseline 0.85` to override auto-detection. Useful when the
 > auto-detected baseline is from an older evolution.
+
+## Autonomous Mode
+
+When called by `selftune orchestrate`, watch runs automatically on recently
+evolved skills:
+
+- Checks all skills evolved in the last --recent-window hours (default 24)
+- Auto-rollback is enabled by default
+- Results are included in the orchestrate run report
+- No user notification — regressions are handled silently via rollback

package/skill/Workflows/Workflows.md

@@ -0,0 +1,129 @@
+# selftune Workflows Workflow
+
+## When to Use
+
+When the user asks about multi-skill workflows, workflow discovery, or skill composition.
+
+## Overview
+
+Discover repeated multi-skill sequences from telemetry and optionally save a
+discovered workflow into a skill's `## Workflows` section.
+
+## Default Commands
+
+```bash
+selftune workflows [options]
+selftune workflows save <workflow-id|index> [--skill-path <path>]
+```
+
+## Options
+
+- `--min-occurrences <n>`: Minimum times a workflow must appear before it is
+  shown. Default: `3`.
+- `--window <n>`: Only analyze the last `n` sessions. Default: all sessions.
+- `--skill <name>`: Only show workflows containing this skill. Default: all
+  skills.
+- `--json`: Emit machine-readable `WorkflowDiscoveryReport` JSON. Default:
+  human-readable text.
+- `--skill-path <path>`: Target SKILL.md when using `save`. Default:
+  auto-detect the first skill's SKILL.md path across contributing sessions. If
+  that skill maps to multiple SKILL.md files in those sessions, the command
+  errors and you must pass `--skill-path` explicitly.
+
+## Save Semantics
+
+`save` accepts either:
+
+- A workflow ID, which is the ordered skill chain joined with `→`
+- A 1-based index from the `selftune workflows` output
+
+Examples:
+
+```bash
+selftune workflows save "Copywriting→MarketingAutomation→SelfTuneBlog"
+selftune workflows save 1
+```
+
+When saved, selftune appends a subsection to `## Workflows` in the target
+SKILL.md. The subsection name is derived from the skill chain
+(`Copywriting-MarketingAutomation-SelfTuneBlog`) and includes
+discovered-source metadata with occurrence count and synergy score.
+
+## Output Format
+
+### Human-readable output
+
+The number prefix (for example, `1.`) is the 1-based index you can pass to
+`selftune workflows save <index>`.
+
+```text
+Discovered Workflows (from 450 sessions):
+
+  1. Copywriting → MarketingAutomation → SelfTuneBlog
+     Occurrences: 12 | Synergy: 0.72 | Consistency: 92% | Completion: 83%
+     Common trigger: "write and publish a blog post"
+```
+
+### JSON output
+
+```json
+{
+  "workflows": [
+    {
+      "workflow_id": "Copywriting→MarketingAutomation→SelfTuneBlog",
+      "skills": ["Copywriting", "MarketingAutomation", "SelfTuneBlog"],
+      "occurrence_count": 12,
+      "avg_errors": 0.5,
+      "avg_errors_individual": 1.8,
+      "synergy_score": 0.72,
+      "representative_query": "write and publish a blog post",
+      "sequence_consistency": 0.92,
+      "completion_rate": 0.83,
+      "first_seen": "2026-03-01T10:00:00Z",
+      "last_seen": "2026-03-08T16:30:00Z",
+      "session_ids": ["s1", "s2"]
+    }
+  ],
+  "total_sessions_analyzed": 450,
+  "generated_at": "2026-03-09T12:00:00.000Z"
+}
+```
+
+## How It Works
+
+1. Reads `session_telemetry_log.jsonl` and `skill_usage_log.jsonl`
+2. Orders skill usage inside each session by timestamp
+3. Deduplicates consecutive same-skill entries
+4. Keeps only sequences with 2+ skills
+5. Counts repeated ordered sequences across sessions
+6. Computes workflow metrics:
+   - `synergy_score` — whether the sequence performs better together than solo
+     baselines, where each skill's solo baseline is its average error rate from
+     single-skill sessions and the workflow uses the max of those solo rates
+   - `sequence_consistency` — how stable the ordering is for the same skill
+     set
+   - `completion_rate` — how often all skills in the sequence fire
+7. Filters by `--min-occurrences` and optional `--skill`
+8. Optionally appends the chosen workflow to SKILL.md via `save`
+
+## Interpreting Results
+
+- `synergy_score > 0.3`: Strong candidate for codifying as a workflow.
+- `synergy_score < -0.3`: The sequence adds friction or conflicts.
+- Low `sequence_consistency`: Same skills appear in multiple orders; the
+  pattern may still be unstable.
+- Low `completion_rate`: One or more skills in the sequence often are not
+  invoked, so the full workflow does not complete.
+
+## Common Patterns
+
+- "Which skills always get used together?"  
+  `selftune workflows`
+- "Only show workflows involving Deploy"  
+  `selftune workflows --skill Deploy`
+- "Focus on recent behavior"  
+  `selftune workflows --window 20`
+- "Save the top workflow into SKILL.md"  
+  `selftune workflows save 1 --skill-path /path/to/SKILL.md`
+- "Save a specific discovered workflow by ID"  
+  `selftune workflows save "Copywriting→MarketingAutomation→SelfTuneBlog"`

package/skill/assets/activation-rules-default.json

@@ -0,0 +1,26 @@
+{
+  "_readme": "Default activation rules for selftune auto-activation. Copy to ~/.selftune/activation-rules.json to customize.",
+  "_note": "These defaults are bundled inside the installed skill so setup does not depend on repository-level templates.",
+  "rules": [
+    {
+      "id": "post-session-diagnostic",
+      "enabled": true,
+      "description": "Suggest `selftune last` when session has >2 unmatched queries"
+    },
+    {
+      "id": "grading-threshold-breach",
+      "enabled": true,
+      "description": "Suggest `selftune evolve` when session pass rate < 60%"
+    },
+    {
+      "id": "stale-evolution",
+      "enabled": true,
+      "description": "Suggest `selftune evolve` when no evolution in >7 days and pending false negatives exist"
+    },
+    {
+      "id": "regression-detected",
+      "enabled": true,
+      "description": "Suggest `selftune rollback` when monitoring detects a regression"
+    }
+  ]
+}

package/skill/assets/multi-skill-settings.json

@@ -0,0 +1,63 @@
+{
+  "_readme": "Claude settings template for multi-skill selftune projects. Merge into ~/.claude/settings.json.",
+  "_usage": "These hooks use npx selftune, which works regardless of installation path.",
+  "_note": "Multi-skill projects use activation rules to route queries to the correct skill. See assets/activation-rules-default.json.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook prompt-log",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "npx selftune hook auto-activate",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook skill-change-guard",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "npx selftune hook evolution-guard",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook skill-eval",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook session-stop",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/skill/assets/single-skill-settings.json

@@ -0,0 +1,57 @@
+{
+  "_readme": "Claude settings template for single-skill selftune projects. Merge into ~/.claude/settings.json.",
+  "_usage": "These hooks use npx selftune, which works regardless of installation path.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook prompt-log",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "npx selftune hook auto-activate",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook skill-change-guard",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook skill-eval",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx selftune hook session-stop",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}