selftune 0.1.4 → 0.2.1

package/skill/references/invocation-taxonomy.md

@@ -1,7 +1,7 @@
 # Invocation Taxonomy Reference
 
 How selftune classifies the ways users trigger (or should trigger) a skill.
-Used by the `evals` command and referenced by evolution workflows to understand
+Used by the `selftune eval generate` command and referenced by evolution workflows to understand
 coverage gaps.
 
 ---
@@ -92,7 +92,7 @@ The invocation taxonomy directly drives the evolution feedback loop:
 
 ### Missed Implicit = Undertriggering
 
-When `evals` shows implicit queries that don't trigger the skill, the
+When `selftune eval generate` shows implicit queries that don't trigger the skill, the
 description is too narrow. The `evolve` command will:
 1. Extract the missed implicit patterns
 2. Propose description changes that cover them

package/skill/references/logs.md

@@ -1,7 +1,8 @@
 # Log Format Reference
 
-selftune writes to four log files. This reference describes each format
-in detail for the skill to use when parsing sessions and audit trails.
+selftune writes raw legacy logs plus a canonical event log. This reference
+describes each format in detail for the skill to use when parsing sessions,
+audit trails, and cloud-ingest exports.
 
 ---
 
@@ -54,12 +55,30 @@ One record per skill trigger event. Populated by skill-eval.ts (PostToolUse hook
   "session_id": "abc123",
   "skill_name": "pptx",
   "skill_path": "/mnt/skills/public/pptx/SKILL.md",
+  "skill_scope": "project",
+  "skill_project_root": "/home/user/projects/myapp",
+  "skill_registry_dir": "/home/user/projects/myapp/.agents/skills",
+  "skill_path_resolution_source": "raw_log",
   "query": "Make me a slide deck for the board meeting",
   "triggered": true,
   "source": "claude_code"
 }
 ```
 
+Optional provenance fields:
+- `skill_scope`: `project | global | admin | system | unknown`
+- `skill_project_root`: resolved repo/worktree root when the skill came from a project-local registry
+- `skill_registry_dir`: the registry directory where the resolved `SKILL.md` came from
+- `skill_path_resolution_source`: `raw_log | installed_scope | launcher_base_dir | fallback`
+
+The repaired overlay at `~/.claude/skill_usage_repaired.jsonl` uses the same
+record shape, but is rebuilt from source-truth transcripts/rollouts rather than
+hooks alone.
+
+Notes:
+- `launcher_base_dir` means selftune recovered Claude's `Base directory for this skill:` launcher metadata. If that recovered `SKILL.md` path points into a stable registry like `~/.agents/skills`, `~/.claude/skills`, `/etc/codex/skills`, or a real project checkout, selftune now reclassifies the invocation into the matching `skill_scope`. Ephemeral temp launcher directories still remain `unknown`.
+- `fallback` means selftune confirmed a skill invocation but could not yet resolve a concrete `SKILL.md` path.
+
 ---
 
 ## ~/.claude/all_queries_log.jsonl
@@ -77,6 +96,149 @@ Every user query, whether or not it triggered a skill. Populated by prompt-log.t
 
 ---
 
+## ~/.claude/canonical_telemetry_log.jsonl
+
+Canonical append-only event stream. This is the normalization boundary for local
+and cloud ingestion. Raw legacy logs remain unchanged; canonical events are
+written separately. Parse it as JSONL: UTF-8 text, one canonical JSON object
+per line, newline-delimited, with parsers reading line-by-line and allowing a
+final trailing newline.
+
+Observed record kinds:
+
+- `session`
+- `prompt`
+- `skill_invocation`
+- `execution_fact`
+- `normalization_run` (reserved for future normalization job summaries)
+
+Example prompt record:
+
+```json
+{
+  "record_kind": "prompt",
+  "schema_version": "2.0",
+  "normalizer_version": "1.0.0",
+  "normalized_at": "2026-03-10T10:00:00.000Z",
+  "platform": "claude_code",
+  "capture_mode": "hook",
+  "source_session_kind": "interactive",
+  "session_id": "abc123",
+  "raw_source_ref": {
+    "event_type": "UserPromptSubmit"
+  },
+  "prompt_id": "abc123:p0",
+  "occurred_at": "2026-03-10T10:00:00.000Z",
+  "prompt_text": "Make me a slide deck for the board meeting",
+  "prompt_hash": "4d6c5c0b1a2f7a40",
+  "prompt_kind": "user",
+  "is_actionable": true,
+  "prompt_index": 0
+}
+```
+
+Example skill invocation record:
+
+```json
+{
+  "record_kind": "skill_invocation",
+  "schema_version": "2.0",
+  "normalizer_version": "1.0.0",
+  "normalized_at": "2026-03-10T10:00:05.000Z",
+  "platform": "claude_code",
+  "capture_mode": "hook",
+  "source_session_kind": "interactive",
+  "session_id": "abc123",
+  "raw_source_ref": {
+    "path": "/home/user/.claude/projects/.../abc123.jsonl",
+    "event_type": "PostToolUse"
+  },
+  "skill_invocation_id": "abc123:s:pptx:0",
+  "occurred_at": "2026-03-10T10:00:05.000Z",
+  "matched_prompt_id": "abc123:p0",
+  "skill_name": "pptx",
+  "skill_path": "/mnt/skills/public/pptx/SKILL.md",
+  "invocation_mode": "explicit",
+  "triggered": true,
+  "confidence": 1
+}
+```
+
+Run `selftune export-canonical --out ~/.claude/canonical_telemetry_log.jsonl`
+to write a canonical JSONL telemetry export ready for downstream cloud
+ingestion.
+
+---
+
+## ~/.selftune/canonical-session-state-<session>.json
+
+Per-session helper state used only to preserve deterministic canonical prompt IDs
+for live Claude hooks. `<session>` is the `session_id` with every character
+outside `[A-Za-z0-9_-]` replaced by `_`, so `user:abc/123` becomes
+`canonical-session-state-user_abc_123.json`.
+
+```json
+{
+  "session_id": "abc123",
+  "next_prompt_index": 2,
+  "last_prompt_id": "abc123:p1",
+  "last_actionable_prompt_id": "abc123:p1",
+  "updated_at": "2026-03-10T10:00:05.000Z"
+}
+```
+
+This is operational state, not an analytics source of truth.
+
+---
+
+## ~/.claude/improvement_signals.jsonl
+
+One record per detected improvement signal. Written by `prompt-log.ts` when a
+user correction or explicit skill request is detected. Read by the orchestrator
+for signal-aware candidate selection, and by `session-stop.ts` to decide whether
+to spawn a reactive orchestrate run.
+
+```json
+{
+  "timestamp": "2026-03-15T14:00:00.000Z",
+  "session_id": "abc123",
+  "query": "why didn't you use the commit skill?",
+  "signal_type": "correction",
+  "mentioned_skill": "commit",
+  "consumed": false
+}
+```
+
+Signal records are append-only. When an orchestrate run processes a signal,
+the original record remains unchanged and the orchestrator rewrites the file
+with `consumed: true` set on processed entries. This is the one exception
+to strict append-only semantics in the log system — the rewrite is atomic
+and race-protected by the orchestrate lockfile.
+
+Consumed signal example:
+
+```json
+{
+  "timestamp": "2026-03-15T14:00:00.000Z",
+  "session_id": "abc123",
+  "query": "why didn't you use the commit skill?",
+  "signal_type": "correction",
+  "mentioned_skill": "commit",
+  "consumed": true,
+  "consumed_at": "2026-03-15T14:05:00.000Z",
+  "consumed_by_run": "run_1710511500000_a1b2c3"
+}
+```
+
+**signal_type values:**
+- `correction` — User pointing out a missed skill ("why didn't you use X?", "you should have used X", "next time use X")
+- `explicit_request` — User asking to use a skill ("please use the X skill", "use the commit skill")
+- `manual_invocation` — Direct `/skill` invocation detected
+
+**Detection:** Pure regex in `prompt-log.ts`, no LLM calls. Skill names are matched against installed skills in `~/.claude/skills/`.
+
+---
+
 ## ~/.claude/evolution_audit_log.jsonl
 
 One record per evolution action. Written by the evolution and rollback modules.

package/skill/references/setup-patterns.md

@@ -0,0 +1,65 @@
+# selftune Setup Patterns
+
+This reference keeps the core initialize workflow portable. Use it when the
+user needs project-type-specific setup guidance after `selftune init`.
+
+## Single-Skill Project
+
+Use when the workspace has one primary `SKILL.md`.
+
+- Merge `assets/single-skill-settings.json` into `~/.claude/settings.json`
+- Keep the bundled `./settings_snippet.json` from the skill root nearby as the
+  minimal hook reference
+- Verify with `selftune doctor`
+
+## Multi-Skill Project
+
+Use when the workspace has multiple `SKILL.md` files that coexist in one repo.
+
+- Merge `assets/multi-skill-settings.json` into `~/.claude/settings.json`
+- Copy `assets/activation-rules-default.json` to
+  `~/.selftune/activation-rules.json`
+- Tune activation rules after `selftune doctor` reports healthy hooks
+- Use `selftune workflows` once telemetry accumulates to discover repeated
+  multi-skill chains
+
+## Monorepo
+
+Use the same template as a multi-skill project, but run `selftune init` from
+the repo root so hook paths and telemetry cover the whole workspace.
+
+## Codex-Only
+
+- Install the CLI and run `selftune init --agent codex`
+- Use `selftune ingest wrap-codex -- <args>` for real-time capture or
+  `selftune ingest codex` for batch ingestion
+- Use `selftune doctor` to verify the shared logs are healthy
+
+## OpenCode-Only
+
+- Run `selftune init --agent opencode`
+- Use `selftune ingest opencode` to backfill session data into the shared logs
+
+## OpenClaw-Only
+
+- Run `selftune init --agent openclaw`
+- Use `selftune ingest openclaw` for ingestion
+- Use `selftune doctor` to verify the shared logs are healthy
+- Use `selftune cron setup` if the user specifically wants OpenClaw-managed recurring runs
+
+## Mixed-Agent Setup
+
+Use when telemetry from Claude Code, Codex, OpenCode, or OpenClaw should be
+combined.
+
+- Initialize each platform against the same `~/.selftune/` data directory
+- Ingest platform-specific logs into the shared JSONL schema
+- Use `selftune schedule --install` for the default autonomous scheduler path
+- Use `selftune status`, `selftune dashboard`, and `selftune workflows` on the
+  merged dataset
+
+## Optional Repository Extensions
+
+Some repositories also bundle Claude-specific helper agents in `.claude/agents/`
+for diagnosis, evolution review, or setup help. These are optional extensions,
+not part of the core skill package installed by `npx skills add`.

package/skill/references/version-history.md

@@ -0,0 +1,40 @@
+# selftune Skill Version History
+
+This file is maintainer-facing. Keep operational instructions in
+`../SKILL.md`; record version history here so the main skill stays focused on
+agent execution.
+
+## Versioning Rules
+
+- Bump the version when command coverage, routing, or user-facing workflow
+  guidance changes in a meaningful way.
+- Update the `metadata.version` and `metadata.last_updated` fields in
+  `../SKILL.md` at the same time.
+- Record a short, high-signal summary here. Avoid duplicating the full skill
+  body.
+
+## Change Log
+
+### 0.2.2 — 2026-03-09
+
+- Tightened the top-level skill description and added an explicit
+  `compatibility` field
+- Surfaced the bundled badge workflow in quick reference, routing, and resource
+  index sections
+- Moved setup-pattern guidance fully inside the skill package via
+  `references/setup-patterns.md`
+- Bundled Claude settings and activation-rule templates under `assets/` so the
+  installed skill no longer depends on repository-level `templates/`
+- Marked Claude-specific specialist agents as optional repository extensions
+  rather than part of the core installed skill
+
+### 0.2.1 — 2026-03-09
+
+- Added first-class routing and quick-reference coverage for
+  `selftune workflows`
+- Added a dedicated `Workflows/Workflows.md` guide for workflow discovery and
+  codification
+- Updated composability guidance to reflect synergy, conflicts, and workflow
+  candidates
+- Synced workflow save documentation with the shipped
+  `<workflow-id|index>` behavior

package/skill/settings_snippet.json

@@ -1,6 +1,7 @@
 {
   "_readme": "Merge the 'hooks' block below into your ~/.claude/settings.json",
   "_readme2": "Replace /PATH/TO/ with the actual directory where you saved the scripts",
+  "_readme3": "This is the comprehensive template. Portable single-skill and multi-skill variants are bundled in assets/",
 
   "hooks": {
     "UserPromptSubmit": [
@@ -10,6 +11,28 @@
             "type": "command",
             "command": "bun run /PATH/TO/cli/selftune/hooks/prompt-log.ts",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bun run /PATH/TO/cli/selftune/hooks/auto-activate.ts",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run /PATH/TO/cli/selftune/hooks/skill-change-guard.ts",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bun run /PATH/TO/cli/selftune/hooks/evolution-guard.ts",
+            "timeout": 5
           }
         ]
       }

package/templates/activation-rules-default.json

@@ -0,0 +1,27 @@
+{
+  "_readme": "Default activation rules for selftune auto-activation. Copy to ~/.selftune/activation-rules.json to customize.",
+  "_docs": "See docs/integration-guide.md for details on each rule.",
+
+  "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/templates/multi-skill-settings.json

@@ -0,0 +1,64 @@
+{
+  "_readme": "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 templates/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/templates/single-skill-settings.json

@@ -0,0 +1,58 @@
+{
+  "_readme": "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
+          }
+        ]
+      }
+    ]
+  }
+}