continuous-improvement 3.8.0 → 3.9.2

package/skills/safety-guard.md

@@ -1,76 +1,76 @@
----
-name: safety-guard
-tier: "2"
-description: Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
-origin: continuous-improvement
----
-
-# Safety Guard — Prevent Destructive Operations
-
-## When to Use
-
-- When working on production systems
-- When agents are running autonomously (full-auto mode)
-- When you want to restrict edits to a specific directory
-- During sensitive operations (migrations, deploys, data changes)
-
-## How It Works
-
-Three modes of protection:
-
-### Mode 1: Careful Mode
-
-Intercepts destructive commands before execution and warns:
-
-```
-Watched patterns:
-- rm -rf (especially /, ~, or project root)
-- git push --force
-- git reset --hard
-- git checkout . (discard all changes)
-- DROP TABLE / DROP DATABASE
-- docker system prune
-- kubectl delete
-- chmod 777
-- sudo rm
-- npm publish (accidental publishes)
-- Any command with --no-verify
-```
-
-When detected: shows what the command does, asks for confirmation, suggests safer alternative.
-
-### Mode 2: Freeze Mode
-
-Locks file edits to a specific directory tree:
-
-```
-/safety-guard freeze src/components/
-```
-
-Any Write/Edit outside `src/components/` is blocked with an explanation. Useful when you want an agent to focus on one area without touching unrelated code.
-
-### Mode 3: Guard Mode (Careful + Freeze combined)
-
-Both protections active. Maximum safety for autonomous agents.
-
-```
-/safety-guard guard --dir src/api/ --allow-read-all
-```
-
-Agents can read anything but only write to `src/api/`. Destructive commands are blocked everywhere.
-
-### Unlock
-
-```
-/safety-guard off
-```
-
-## Implementation
-
-Uses PreToolUse hooks to intercept Bash, Write, Edit, and MultiEdit tool calls. Checks the command/path against the active rules before allowing execution.
-
-## Integration
-
-- Enable by default for `codex -a never` sessions
-- Pair with observability risk scoring in continuous-improvement v2
-- Logs all blocked actions to `~/.claude/safety-guard.log`
+---
+name: safety-guard
+tier: "2"
+description: Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
+origin: continuous-improvement
+---
+
+# Safety Guard — Prevent Destructive Operations
+
+## When to Use
+
+- When working on production systems
+- When agents are running autonomously (full-auto mode)
+- When you want to restrict edits to a specific directory
+- During sensitive operations (migrations, deploys, data changes)
+
+## How It Works
+
+Three modes of protection:
+
+### Mode 1: Careful Mode
+
+Intercepts destructive commands before execution and warns:
+
+```
+Watched patterns:
+- rm -rf (especially /, ~, or project root)
+- git push --force
+- git reset --hard
+- git checkout . (discard all changes)
+- DROP TABLE / DROP DATABASE
+- docker system prune
+- kubectl delete
+- chmod 777
+- sudo rm
+- npm publish (accidental publishes)
+- Any command with --no-verify
+```
+
+When detected: shows what the command does, asks for confirmation, suggests safer alternative.
+
+### Mode 2: Freeze Mode
+
+Locks file edits to a specific directory tree:
+
+```
+/safety-guard freeze src/components/
+```
+
+Any Write/Edit outside `src/components/` is blocked with an explanation. Useful when you want an agent to focus on one area without touching unrelated code.
+
+### Mode 3: Guard Mode (Careful + Freeze combined)
+
+Both protections active. Maximum safety for autonomous agents.
+
+```
+/safety-guard guard --dir src/api/ --allow-read-all
+```
+
+Agents can read anything but only write to `src/api/`. Destructive commands are blocked everywhere.
+
+### Unlock
+
+```
+/safety-guard off
+```
+
+## Implementation
+
+Currently implemented as skill-side discipline: when restricted-mode is active, the agent reads this skill and refuses Bash, Write, Edit, and MultiEdit calls that violate the rules before invoking the tool. There is no bundled tool-call gate today — the same enforcement gap that existed for `gateguard` before issue #106 / PR #108. A future runtime version would track via a follow-up issue.
+
+## Integration
+
+- Enable by default for `codex -a never` sessions
+- Pair with observability risk scoring in continuous-improvement v2
+- Logs all blocked actions to `~/.claude/safety-guard.log`

package/skills/state-reconciliation.md

@@ -0,0 +1,63 @@
+---
+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
+---
+
+# State Reconciliation Skill
+
+A pre-dispatch invariant. Before the verification ladder runs (or any auto-loop unit dispatches), reconcile the three state sources — DB / disk / in-memory — and surface any divergence as a blocker, not a silent re-dispatch.
+
+## When to Use
+
+- Before Phase 1 of `verification-loop` if the project tracks runtime state outside source control (sqlite, KV, redis, `completed-units.json`, milestone JSON, lockfiles).
+- Before any auto-loop iteration in long-running sessions.
+- After a crash, pause/resume, or context compaction — the in-memory loop state is gone but DB and disk persist.
+- When a flag like `is_sketch`, `in_progress`, or a stale lock keeps re-firing the same unit.
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "State Reconciliation" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Stale flags re-dispatch completed units** — `is_sketch`, stale worker rows, stale sequence/dependency rows that no one cleared.
+- **Disk artifacts present, DB status lags** — `PROJECT.md` milestone registration, completion timestamps, roadmap divergence.
+- **Recovery helpers exist but aren't wired into dispatch** — divergence accrues silently between iterations.
+
+A verification ladder that runs against unreconciled state reports green on the wrong inputs.
+
+## The Reconciliation Contract
+
+For every state class the project tracks, define and run before dispatch:
+
+1. **Authority** — which surface is the source of truth (DB, disk artifact, in-memory loop state).
+2. **Projection** — direction of state flow (DB → disk, disk → DB, or both with a named winner).
+3. **Reconciliation** — the deterministic check that proves authority and projection match.
+4. **Failure mode** — what happens on divergence (block dispatch, repair, ask operator).
+
+Output a single fenced block before any dispatch, so the operator sees the resolved state before it costs a misread:
+
+```
+state-reconciliation (resolved):
+  participants table:        DB authoritative; disk projection at data/participants.json — match (1247 rows)
+  completed_units.json:      project root authoritative after crash; worktree projection — match
+  is_sketch flag:            DB authoritative — clear (no re-dispatch risk)
+  open lock at /tmp/foo.lck: stale (PID 1234 not running) — STALE, blocks dispatch
+  milestone registration:    PROJECT.md authoritative; DB row — DIVERGED (DB shows in_progress, disk shows complete)
+```
+
+Each row shows class + authority + reconciliation result. `STALE`, `DIVERGED`, `MISSING` surface as blockers; only every-row-`match` unblocks dispatch.
+
+## Anti-Patterns
+
+- **Reconciling at unit boundary, not lifecycle boundary.** Checking only when a unit is about to run lets earlier units write to invalid state. Reconcile once at lifecycle start and on every resume.
+- **One-way trust.** Assuming DB is always right (or disk always right) without naming authority per state class. Authority is a per-class decision; codify it.
+- **Silent repair.** Auto-fixing divergence without surfacing it. If reconciliation fixes 12 rows, the operator must see the count and the classes.
+- **Reconciling the wrong direction.** Projecting disk → DB when DB was the authority overwrites correct state with stale data. The direction is part of the contract, not a default.
+- **Treating "missing" as "match".** An absent state class is not the same as a reconciled one. Missing means the projection never ran; surface it explicitly.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — runs as a pre-Phase-0 invariant; the resolved-state block fires before the resolved-ladder block.
+- [worktree-safety](worktree-safety.md) — both fire before dispatch; safety runs first because reconciliation depends on a valid worktree root.
+- [recovery-classification](recovery-classification.md) — divergence found here routes through recovery-classification on the next loop iteration if the reconciler can't auto-repair.

package/skills/strategic-compact.md

@@ -1,104 +1,104 @@
----
-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
----
-
-# Strategic Compact Skill
-
-Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
-
-## When to Activate
-
-- Running long sessions that approach context limits (200K+ tokens)
-- Working on multi-phase tasks (research → plan → implement → test)
-- Switching between unrelated tasks within the same session
-- After completing a major milestone and starting new work
-- When responses slow down or become less coherent (context pressure)
-
-## Why Strategic Compaction?
-
-Auto-compaction triggers at arbitrary points:
-- Often mid-task, losing important context
-- No awareness of logical task boundaries
-- Can interrupt complex multi-step operations
-
-Strategic compaction at logical boundaries:
-- **After exploration, before execution** — Compact research context, keep implementation plan
-- **After completing a milestone** — Fresh start for next phase
-- **Before major context shifts** — Clear exploration context before different task
-
-## How It Works
-
-The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
-
-1. **Tracks tool calls** — Counts tool invocations in session
-2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
-3. **Periodic reminders** — Reminds every 25 calls after threshold
-
-## Hook Setup
-
-Add to your `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit",
-        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
-      },
-      {
-        "matcher": "Write",
-        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
-      }
-    ]
-  }
-}
-```
-
-## Configuration
-
-Environment variables:
-- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
-
-## Compaction Decision Guide
-
-Use this table to decide when to compact:
-
-| Phase Transition | Compact? | Why |
-|-----------------|----------|-----|
-| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
-| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
-| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
-| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
-| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
-| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
-
-## What Survives Compaction
-
-Understanding what persists helps you compact with confidence:
-
-| Persists | Lost |
-|----------|------|
-| Agent instructions (from CLAUDE.md / AGENTS.md) | Intermediate reasoning and analysis |
-| TodoWrite task list | File contents you previously read |
-| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
-| Git state (commits, branches) | Tool call history and counts |
-| Files on disk | Nuanced user preferences stated verbally |
-
-## Best Practices
-
-1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
-2. **Compact after debugging** — Clear error-resolution context before continuing
-3. **Don't compact mid-implementation** — Preserve context for related changes
-4. **Read the suggestion** — The hook tells you *when*, you decide *if*
-5. **Write before compacting** — Save important context to files or memory before compacting
-6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
-
-## Related
-
-- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
-- Memory persistence hooks — For state that survives compaction
-- `continuous-learning` skill — Extracts patterns before session ends
+---
+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
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Activate
+
+- Running long sessions that approach context limits (200K+ tokens)
+- Working on multi-phase tasks (research → plan → implement → test)
+- Switching between unrelated tasks within the same session
+- After completing a major milestone and starting new work
+- When responses slow down or become less coherent (context pressure)
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** — Compact research context, keep implementation plan
+- **After completing a milestone** — Fresh start for next phase
+- **Before major context shifts** — Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** — Counts tool invocations in session
+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** — Reminds every 25 calls after threshold
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
+
+## Compaction Decision Guide
+
+Use this table to decide when to compact:
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| Agent instructions (from CLAUDE.md / AGENTS.md) | Intermediate reasoning and analysis |
+| TodoWrite task list | File contents you previously read |
+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
+- Memory persistence hooks — For state that survives compaction
+- `continuous-learning` skill — Extracts patterns before session ends

package/skills/superpowers.md

@@ -1,7 +1,7 @@
 ---
 name: superpowers
 tier: companion
-description: "Law activator for the 7 Laws of AI Agent Discipline. Unified five-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode, pm-skills) so the right discipline fires automatically instead of the agent skipping a step. Not a peer skill — a dispatcher for the others."
+description: "Law activator for the 7 Laws of AI Agent Discipline. Unified four-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode) so the right discipline fires automatically instead of the agent skipping a step. Product-management coverage comes from phuryn/pm-skills via an out-of-band marketplace install (see docs/THIRD_PARTY.md). Not a peer skill — a dispatcher for the others."
 origin: https://github.com/obra/superpowers
 ---
 
@@ -15,17 +15,32 @@ AI agents skip steps, guess, and declare "done" without verifying. Superpowers b
 
 ## What changed in v3.8.0
 
-The dispatcher now routes across **five registered marketplaces** instead of relying on Obra installed separately. All five are installable from one marketplace entry:
+The dispatcher now routes across **four registered marketplaces** instead of relying on Obra installed separately. All four are installable from one marketplace entry:
 
 ```
 /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 pm-skills@continuous-improvement         # 41 PM skills + 47 commands
 ```
 
-The CI plugin (this dispatcher + `tdd-workflow`, `verification-loop`, `gateguard`, `ralph`, `deploy-receipt`, etc.) installs by default. The five companions are opt-in — install only what you need.
+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.
+
+Product-management coverage (PRD, OKRs, personas, GTM, etc.) is provided by `phuryn/pm-skills` via an out-of-band Claude Code marketplace install:
+
+```
+claude plugin marketplace add phuryn/pm-skills
+claude plugin install pm-toolkit@pm-skills
+claude plugin install pm-product-strategy@pm-skills
+claude plugin install pm-product-discovery@pm-skills
+claude plugin install pm-market-research@pm-skills
+claude plugin install pm-data-analytics@pm-skills
+claude plugin install pm-marketing-growth@pm-skills
+claude plugin install pm-go-to-market@pm-skills
+claude plugin install pm-execution@pm-skills
+```
+
+See `docs/THIRD_PARTY.md` for plugin-by-plugin scope.
 
 ## The Basic Workflow
 
@@ -42,7 +57,7 @@ The CI plugin (this dispatcher + `tdd-workflow`, `verification-loop`, `gateguard
 
 The agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.
 
-## Five-Source Routing Table
+## Four-Source Routing Table
 
 When a task trigger fires, the dispatcher resolves to the first available skill in the preference chain. Order = preference order. Items prefixed with `ci:` are bundled in this plugin; others are namespaced by their installed plugin name.
 
@@ -75,14 +90,7 @@ When a task trigger fires, the dispatcher resolves to the first available skill
 | Reflect after session, extract patterns | 5+7 | `ci:learn-eval` → `oh-my-claudecode:retrospective` |
 | Long autonomous run with quality gates | 6 | `oh-my-claudecode:ultrawork` → `ci:ralph` |
 | Coordinator role for staged hand-off | 3 | `ruflo-swarm:agents/coordinator` (when ruflo installed) |
-| Draft a PRD before implementation | 2 | `pm-skills:prd` (only source) |
-| Decompose into user stories + acceptance criteria | 2 | `pm-skills:user-stories` + `pm-skills:acceptance-criteria` |
-| Write or grade quarterly OKRs | 2 | `pm-skills:okr-writer` + `pm-skills:okr-grader` |
-| Design hypothesis-driven experiment | 2 | `pm-skills:experiment-design` + `pm-skills:hypothesis` |
-| Discovery framework: persona, JTBD, lean canvas | 1 | `pm-skills:persona` + `pm-skills:jtbd-canvas` + `pm-skills:lean-canvas` |
-| Market sizing / competitive analysis | 1 | `pm-skills:market-sizing` + `pm-skills:competitive-analysis` |
-| Meeting agenda / brief / recap / synthesize | 5 | `pm-skills:meeting-*` family |
-| Launch checklist before product release | 4 | `pm-skills:launch-checklist` (no engineering equivalent) |
+| Product-management work (PRD, OKRs, personas, GTM, growth, market research, analytics) | 1+2+5 | Install `phuryn/pm-skills` via Claude Code marketplace — see docs/THIRD_PARTY.md. Eight installable plugins (`pm-toolkit`, `pm-product-strategy`, `pm-product-discovery`, `pm-market-research`, `pm-data-analytics`, `pm-marketing-growth`, `pm-go-to-market`, `pm-execution`) cover the full lifecycle. Out of band — not a `/plugin install <name>@continuous-improvement` target. |
 
 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.
 
@@ -203,8 +211,7 @@ Superpowers skills activate when their trigger conditions are detected. The disp
 - "Create a feature" → `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:executing-plans`
 - "Fix this bug" → `superpowers:systematic-debugging` → `superpowers:verification-before-completion`
 - "Review this PR" → `superpowers:requesting-code-review`
-- "Draft a PRD" → `pm-skills:prd` → `pm-skills:user-stories` → `pm-skills:acceptance-criteria`
-- "Write OKRs for next quarter" → `pm-skills:okr-writer` then `pm-skills:okr-grader`
+- "Draft a PRD" / "Write OKRs" / "Build a persona" → install `phuryn/pm-skills` (out of band — see docs/THIRD_PARTY.md)
 - "Run this PRD autonomously" → `ci:ralph`
 - "Fan out parallel provider migration" → `superpowers:dispatching-parallel-agents` or `/swarm` (PR D)
 - "Visual regression check the landing page" → `oh-my-claudecode:visual-verdict`