continuous-improvement 3.9.2 → 3.12.3

package/plugins/continuous-improvement/skills/skill-distillation/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: skill-distillation
+tier: "2"
+description: Enforces Law 7 (Learn From Every Session) of the 7 Laws of AI Agent Discipline. Distills repeated successful tool sequences into reusable draft instincts, so a pattern that worked three times becomes a captured recipe instead of being re-derived from scratch every session.
+origin: continuous-improvement
+user-invocable: true
+---
+
+# Skill Distillation — Turn Repeated Wins Into Reusable Instincts
+
+Law 7 says learn from every session. The friction harvester already learns from failures. This skill learns from the other side: when the same tool sequence keeps ending in a passing verification, that is a recipe worth keeping — not a coincidence to forget.
+
+## When to Activate
+
+- At end of session, after a successful multi-step task — check whether the pattern is worth keeping.
+- When you notice you have solved a similar problem the same way more than once.
+- During a retrospective, to mine the observation log for patterns that have proven themselves.
+
+## Core Concept
+
+Distillation walks the observation log, groups it into contiguous trajectories (split on session change or a long time gap), and keeps only the trajectories that ended in success:
+
+```
+verify-exit-0   — a Bash test/build/verify command with a non-failing output
+reflection-pass — an observation containing "verified" / "phase 4" / "verify:all green"
+```
+
+It then mines the tool-name sequences of successful trajectories for n-grams (length 3–5) that recurred **across multiple distinct sessions**. A pattern repeated only within a single session is rejected — that is repetition, not a reusable skill.
+
+## The Promotion Ladder
+
+Drafts never affect behavior until you promote them. Three explicit steps, no auto-promotion:
+
+```
+1. ci_distill_candidates           — list patterns that qualify (read-only)
+2. ci_distill_propose id=<id>      — write a DRAFT to ~/.claude/instincts/<hash>/drafts/
+                                      (placeholder body — you fill in the real recipe)
+3. <edit the draft body by hand>   — the tool sequence is evidence, not a recipe
+4. ci_distill_promote id=<id>      — promote to a live instinct at 0.5 confidence (SUGGEST)
+```
+
+The draft starts at 0.4 confidence and lives in a `drafts/` subdirectory that the instinct loader ignores. Only `ci_distill_promote` writes a live instinct, at 0.5 (SUGGEST tier) — it suggests, it does not auto-apply, until the normal reinforcement loop earns it more confidence.
+
+## Why Drafts, Not Auto-Instincts
+
+A tool sequence alone is cargo-cult evidence: `Read → Edit → Bash → Edit → Bash` is a TDD loop, but the *value* is in the preconditions and the specific steps, which the sequence does not capture. Requiring a human to edit the body before promotion is the guard against the system fabricating confident-sounding skills from coincidental call ordering.
+
+## Limitations
+
+- **Pattern detection only (no LLM in v1).** The draft body is a placeholder; you write the recipe. An optional model-assisted body draft is a planned follow-up.
+- **Tool-name granularity.** Distillation sees tool names and summaries, not full intent. Two unrelated tasks with the same call shape will look like one pattern — the human edit step resolves this.
+
+## Pairs With
+
+- **`continuous-improvement`** (core SKILL.md, Law 7) — distillation is the success-side complement to the friction-harvest failure side of the same observation log.
+- **`recall`** — before promoting, recall whether an existing instinct already covers the pattern.
+- **`tdd-workflow`** — the most common distilled pattern is the RED-GREEN-REFACTOR loop; promote it with project-specific test commands filled in.

package/plugins/continuous-improvement/skills/state-reconciliation/SKILL.md

@@ -3,6 +3,7 @@ name: state-reconciliation
 tier: "2"
 description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: reconcile DB-vs-disk-vs-memory state before any unit runs, so a stale flag, missing artifact, or out-of-sync row never re-dispatches a unit that already completed or never started."
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # State Reconciliation Skill

package/plugins/continuous-improvement/skills/strategic-compact/SKILL.md

@@ -3,6 +3,7 @@ name: strategic-compact
 tier: "2"
 description: Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline at phase boundaries. Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # Strategic Compact Skill

package/plugins/continuous-improvement/skills/superpowers/SKILL.md

@@ -5,7 +5,7 @@ description: "Law activator for the 7 Laws of AI Agent Discipline. Unified four-
 origin: https://github.com/obra/superpowers
 ---
 
-# Superpowers — Mandatory Agent Workflows (Five-Source Dispatcher)
+# Superpowers — Mandatory Agent Workflows (Four-Source Dispatcher)
 
 Superpowers enforces a structured development workflow. Skills activate automatically when their trigger conditions are met. This is not optional guidance — it is mandatory workflow.
 
@@ -21,7 +21,7 @@ The dispatcher now routes across **four registered marketplaces** instead of rel
 /plugin install superpowers@continuous-improvement       # Obra's 14 workflow skills
 /plugin install agent-skills@continuous-improvement      # Addy's 21 SDLC skills
 /plugin install ruflo-swarm@continuous-improvement       # Agent swarm + Monitor stream
-/plugin install oh-my-claudecode@continuous-improvement  # 39 skills + 19 agents
+/plugin install oh-my-claudecode@continuous-improvement  # 38 skills + 19 agents
 ```
 
 The CI plugin (this dispatcher + `tdd-workflow`, `verification-loop`, `gateguard`, `ralph`, `deploy-receipt`, etc.) installs by default. The four companions are opt-in — install only what you need.
@@ -94,6 +94,80 @@ When a task trigger fires, the dispatcher resolves to the first available skill
 
 When no installed plugin in the chain resolves, the dispatcher falls back to the inline protocols below (Test-Driven Development, Brainstorming, Plan Format, etc.) so the workflow still works on a clean install.
 
+## Companion-Preference Override
+
+The four-source routing table above is **CI-first by default**: where a CI-bundled skill (`ci:tdd-workflow`, `ci:verification-loop`, `ci:planning-with-files`, `ci:context-budget`, `ci:ralph`, `ci:learn-eval`) and a companion skill resolve the same trigger, the table lists the CI skill first and the dispatcher picks it. That is the conservative default — the CI plugin ships with the marketplace, the companions are opt-in installs, so a clean install routes to skills that are guaranteed present.
+
+Once the operator has explicitly installed a companion plugin (`superpowers@continuous-improvement`, `agent-skills@continuous-improvement`, `ruflo-swarm@continuous-improvement`, `oh-my-claudecode@continuous-improvement`), the default starts working against them: the installed companion is shadowed by the CI fallback for the same trigger. This override flag respects the operator's explicit install choice without forcing every user to relitigate routing per task.
+
+### Setting the flag
+
+Add a `continuous_improvement.companion_preference` key to `~/.claude/settings.json`:
+
+```json
+{
+  "continuous_improvement": {
+    "companion_preference": "companions-first"
+  }
+}
+```
+
+Valid values:
+
+| Value | Behavior |
+|---|---|
+| `"ci-first"` (default) | Unchanged from the routing tables above. CI-bundled skills win every chain where they appear. |
+| `"companions-first"` | For any routing row that lists both a CI skill and a companion alternative, the dispatcher reads the chain right-to-left: companion first, CI as the silent fallback if the companion plugin is not installed. CI-only rows (`ci:gateguard`, `ci:deploy-receipt`, `ci:workspace-surface-audit`, `ci:proceed-with-the-recommendation`) are unaffected because no companion exists. |
+| `"strict-companions"` | Same as `companions-first`, but the CI fallback is suppressed. If the companion plugin is not installed, the dispatcher hard-halts with the same shape as the missing-companion detection in `/superpowers` and asks the operator to install the companion or change the flag. Use when you want a guarantee that the installed companion ran, not the CI shim. |
+
+### Which rows the override affects
+
+These are the routing rows where the override changes the resolved target. Rows not listed here are CI-only or companion-only and route the same under any setting.
+
+| Trigger | `ci-first` (default) | `companions-first` |
+|---|---|---|
+| Write a failing test before code | `ci:tdd-workflow` | `superpowers:test-driven-development`, then `agent-skills:test-driven-development` |
+| Verify before declaring done | `ci:verification-loop` | `superpowers:verification-before-completion` |
+| Curate the right context window | `ci:context-budget` | `agent-skills:context-engineering` |
+| Long autonomous run with quality gates | `ci:ralph` | `oh-my-claudecode:ultrawork`, then `ci:ralph` |
+| Reflect after session, extract patterns | `ci:learn-eval` | `oh-my-claudecode:retrospective` |
+
+`superpowers:writing-plans` already wins the planning chain under both settings — it is the first entry, with `ci:planning-with-files` as the third fallback — so that row is unchanged.
+
+### Hard halts that remain regardless of the flag
+
+The override does not disable:
+
+- `gateguard` PreToolUse fact-list enforcement (Law 1, runtime layer in `hooks/gateguard.mjs`)
+- Stop-hook three-section-close discipline (Law 4 + Law 7, runtime layer in `hooks/three-section-close.mjs`)
+- Dispatcher commitments 1–6 above (subagent-driven-development default, parallel fan-out routing, TDD RED-GREEN-REFACTOR, worktree isolation, finishing-a-development-branch before push, distinct Obra/CI variants)
+- Phase 0 P-MAG in `proceed-with-the-recommendation` (Law 5 + Law 7)
+
+These are framework invariants, not routing preferences. The flag re-orders which specialist runs; it does not weaken what the framework guarantees.
+
+### Runtime enforcement
+
+The override is enforced at the PreToolUse layer by `hooks/companion-preference.mjs`. On every `Skill` tool call, the hook reads `~/.claude/settings.json` for the `companion_preference` value and:
+
+- `ci-first` (default): no-op, allow.
+- `companions-first`: emit a one-line stderr advisory naming the preferred companion; allow.
+- `strict-companions`: block the call. Reason names the companion when its plugin is installed, or the `/plugin install <plugin>@continuous-improvement` hint when it is not.
+
+The override map inside `hooks/companion-preference.mjs` stays row-aligned with the "Which rows the override affects" table above. Drift surfaces in the hook test suite, which walks the same pairs and fails on any new CI→companion row that the hook does not recognize.
+
+The hook fails open. If `~/.claude/settings.json` is missing, malformed, or unreadable, the hook emits `{ "decision": "allow" }` and exits 0. Bugs in the hook never block tool calls — they only fail to enforce.
+
+### Telemetry
+
+Every hook invocation that touches a mapped CI skill appends one JSONL line to `~/.claude/instincts/<project-hash>/companion-preference.jsonl`. The line carries `ts`, `mode`, `action`, `ci_skill`, `companion`, `plugin`, and `companion_installed`. The action enum is:
+
+- `observation` — mode is `ci-first`; this is the shadow row showing what `companions-first` would have done.
+- `advisory` — mode is `companions-first`; stderr advisory was emitted.
+- `block` — mode is `strict-companions`; companion installed; tool call blocked.
+- `block-not-installed` — mode is `strict-companions`; companion missing; blocked with install hint.
+
+Non-mapped skills and non-`Skill` tool calls write nothing. The writer wraps `appendFileSync` in try/catch — telemetry failure never changes the hook decision, preserving the fail-open invariant. The JSONL file is the evidence base for a future default-flip decision: after a 7-day window, the operator can grep / aggregate the file to see which routing rows the override fires on, how often, and whether the companion was installed at the time.
+
 ## Stacked-PR Plan Precondition (≥3 files)
 
 Any change touching three or more files — across `skills/`, `src/`, `bin/`, `commands/`, or any combination — must produce a stacked-PR plan as a precondition to the first edit landing. The 28-day usage report shows a clean correlation: sessions that opened with a stacked-PR plan landed at `fully_achieved`; sessions that began as a single big-bang multi-file edit landed at `partially_achieved` (landing-page dark theme, market-data-hub wiring, RAG misrouting). Single-concern PRs are the lever that closes that gap.
@@ -206,7 +280,7 @@ Clean separation, parallel development, easy cleanup.
 
 ## Using Superpowers
 
-Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the five-source routing table above:
+Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the four-source routing table above:
 
 - "Create a feature" → `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:executing-plans`
 - "Fix this bug" → `superpowers:systematic-debugging` → `superpowers:verification-before-completion`