selftune 0.2.16 → 0.2.18

package/skill/Workflows/RepairSkillUsage.md

@@ -0,0 +1,87 @@
+# selftune Repair Skill Usage Workflow
+
+Rebuild trustworthy skill-usage records by replaying Claude Code transcripts
+and Codex rollouts. Produces a repaired overlay (`skill_usage_repaired.jsonl`)
+that corrects missing or inaccurate skill paths, scopes, and query associations
+from the raw hook-captured data.
+
+## When to Use
+
+- Skill usage data appears incomplete or has missing `skill_path` values
+- The user says "repair", "rebuild usage", "fix skill usage", or "trustworthy usage"
+- Before evolution or grading when hook data may be unreliable
+- After changing skill directory layouts or reinstalling skills
+
+## Default Command
+
+```bash
+selftune repair-skill-usage
+```
+
+## Options
+
+| Flag                        | Description                                              |
+| --------------------------- | -------------------------------------------------------- |
+| `--projects-dir <dir>`      | Claude transcript directory (default: `~/.claude/projects`) |
+| `--codex-home <dir>`        | Codex home directory (default: `~/.codex`)               |
+| `--since <date>`            | Only repair sessions modified on/after this date         |
+| `--out <path>`              | Repaired overlay log output path                         |
+| `--sessions-marker <path>`  | Repaired session-id marker file path                     |
+| `--skill-log <path>`        | Raw skill usage log path (for path lookup bootstrap)     |
+| `--dry-run`                 | Show summary counts without writing files                |
+| `--help`                    | Show usage information                                   |
+
+## How It Works
+
+1. **Discover transcripts** — Finds all Claude Code transcript JSONL files under `--projects-dir` and Codex rollout files under `--codex-home`.
+2. **Bootstrap path lookup** — Reads existing skill usage records from SQLite (or `--skill-log` JSONL) to build a skill-name-to-path lookup table.
+3. **Replay transcripts** — For each transcript, parses the conversation to find Skill tool invocations, associates them with the preceding user query, and resolves skill paths via installed-scope discovery or the lookup table.
+4. **Replay Codex rollouts** — Same process for Codex rollout files, using Codex-specific path resolution.
+5. **Write repaired overlay** — Writes deduplicated records to the repaired log and updates the session marker.
+
+## Output Format
+
+JSON summary printed to stdout:
+
+```json
+{
+  "transcripts_scanned": 42,
+  "codex_rollouts_scanned": 8,
+  "repaired_sessions": 35,
+  "repaired_records": 127,
+  "codex_repaired_records": 12,
+  "unique_matched_queries": 98,
+  "reins_queries_seen": 5,
+  "reins_skill_matches": 3,
+  "output": "~/.claude/skill_usage_repaired.jsonl"
+}
+```
+
+With `--dry-run`, the same summary is printed but no files are written.
+
+## Common Patterns
+
+**Preview repair scope**
+
+> Run `selftune repair-skill-usage --dry-run` to see how many sessions and records would be repaired.
+
+**Repair only recent sessions**
+
+> Run `selftune repair-skill-usage --since 2025-01-01` to limit the repair to sessions from this year.
+
+**Full rebuild from scratch**
+
+> Run `selftune repair-skill-usage` without `--since` to rebuild the entire overlay from all available transcripts.
+
+**Agent chaining into evolution**
+
+> Run repair before evolution to ensure skill usage data is accurate: `selftune repair-skill-usage && selftune evolve --skill my-skill`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `repaired_records: 0` | No Skill tool invocations found in transcripts | Verify skills are being invoked in sessions; check `selftune status` |
+| Many `(repaired:name)` paths | Skill not installed or path not discoverable | Install the skill or provide a `--skill-log` with known paths |
+| `transcripts_scanned: 0` | No transcripts in projects directory | Verify `~/.claude/projects/` contains session directories |
+| Invalid `--since` date error | Date format not parseable | Use ISO format: `--since 2025-01-15` |

package/skill/Workflows/Uninstall.md

@@ -0,0 +1,82 @@
+# selftune Uninstall Workflow
+
+Clean removal of all selftune data, configuration, hooks, and scheduling
+artifacts. Surgically removes selftune entries from shared config files
+(like `settings.json`) without affecting user-owned entries.
+
+## When to Use
+
+- The user wants to completely remove selftune
+- The user says "uninstall", "remove selftune", "clean up", or "teardown"
+- The agent needs to undo all selftune installation side effects
+
+## Default Command
+
+```bash
+selftune uninstall
+```
+
+## Options
+
+| Flag              | Description                                                |
+| ----------------- | ---------------------------------------------------------- |
+| `--dry-run`       | Preview what would be removed without deleting anything    |
+| `--keep-logs`     | Preserve JSONL telemetry logs (remove everything else)     |
+| `--npm-uninstall` | Also run `npm uninstall -g selftune` to remove the binary  |
+| `--help`          | Show usage information                                     |
+
+## Removal Steps
+
+The uninstall command removes artifacts in this order:
+
+1. **Autonomy scheduling** — Removes launchd plist (`~/Library/LaunchAgents/dev.selftune.orchestrate.plist`) on macOS, or cron jobs via `selftune cron remove` on other platforms.
+2. **Hooks from settings.json** — Surgically removes only selftune hook entries from `~/.claude/settings.json`. Preserves all user-defined hooks.
+3. **Claude subagents** — Removes selftune-managed agent files from `~/.claude/agents/`.
+4. **JSONL telemetry logs** — Removes all selftune log files from `~/.claude/` (session telemetry, skill usage, evolution audit, orchestrate runs, etc.). Skipped with `--keep-logs`.
+5. **Config directory** — Removes `~/.selftune/` and all contents.
+6. **Ingest markers** — Removes per-source marker files that track which sessions have been ingested.
+7. **npm package** — Runs `npm uninstall -g selftune` only when `--npm-uninstall` is passed.
+
+## Output Format
+
+Output is JSON with per-step results:
+
+```json
+{
+  "dryRun": false,
+  "schedule": { "removed": true, "details": "Removed launchd plist: ..." },
+  "hooks": { "removed": 6, "details": "Removed 6 selftune hook entries from ..." },
+  "agents": { "removed": 4, "files": ["..."] },
+  "logs": { "removed": 10, "skipped": false, "files": ["..."] },
+  "config": { "removed": true, "path": "~/.selftune" },
+  "markers": { "removed": 5, "files": ["..."] },
+  "npm": { "uninstalled": false, "skipped": true }
+}
+```
+
+## Common Patterns
+
+**Preview before removing**
+
+> Run `selftune uninstall --dry-run` first to see what would be removed.
+
+**Keep telemetry data for later**
+
+> Run `selftune uninstall --keep-logs` to remove config and hooks but preserve log files for potential re-installation.
+
+**Full removal including npm package**
+
+> Run `selftune uninstall --npm-uninstall` for a complete teardown.
+
+**Re-install after uninstall**
+
+> Run `npx skills add selftune-dev/selftune` followed by `selftune quickstart` to set up again from scratch.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Hooks still present after uninstall | `settings.json` was not writable | Check file permissions on `~/.claude/settings.json` |
+| Scheduling still active | launchd/cron removal failed | Manually run `launchctl unload ~/Library/LaunchAgents/dev.selftune.orchestrate.plist` or remove cron entries |
+| npm package still installed | `--npm-uninstall` was not passed | Run `npm uninstall -g selftune` manually or re-run with `--npm-uninstall` |
+| Some log files remain | Files were locked by another process | Stop any running `selftune` processes and retry, or delete manually |

package/skill/settings_snippet.json

@@ -68,6 +68,17 @@
             "statusMessage": "selftune: evaluating skill usage"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /PATH/TO/bin/run-hook.cjs /PATH/TO/cli/selftune/hooks/commit-track.ts",
+            "timeout": 8,
+            "statusMessage": "selftune: tracking git commit"
+          }
+        ]
       }
     ],
     "Stop": [