continuous-improvement 3.1.0 → 3.9.1

package/commands/superpowers.md

@@ -0,0 +1,180 @@
+---
+name: superpowers
+description: "Law activator and dispatcher — route the task to the right Law-aligned specialist across continuous-improvement and four vendored upstream skill libraries (Obra superpowers, addy-agent-skills, ruflo-swarm, oh-my-claudecode)."
+---
+
+# /superpowers
+
+`/superpowers` is **the dispatcher**, not a peer skill. It does not do work itself; it routes each user task to the correct Law-aligned specialist so the right discipline fires automatically instead of the agent skipping a step.
+
+The 7 Laws define *what* discipline must be applied. `/superpowers` decides *which specialist* enforces it for this specific task, across five sources installed from this marketplace.
+
+## Routing surface (five sources)
+
+| Source | Where it lives | Examples of what it routes to |
+|---|---|---|
+| `continuous-improvement` (this plugin) | bundled — always present | `gateguard` (Law 1), `tdd-workflow` (Law 3+4), `verification-loop` (Law 4), `wild-risa-balance` (Law 2), `safety-guard` (Law 3), `proceed-with-the-recommendation` (all 7), `ralph` (Law 6), `workspace-surface-audit` (Law 1) |
+| `obra/superpowers` (Jesse Vincent) | vendored at `third-party/superpowers/`, pinned SHA `f2cbfbe` (v5.1.0) | `superpowers:brainstorming`, `:writing-plans`, `:executing-plans`, `:test-driven-development`, `:systematic-debugging`, `:requesting-code-review`, `:receiving-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:using-git-worktrees`, `:finishing-a-development-branch`, `:subagent-driven-development`, `:writing-skills`, `:using-superpowers` |
+| `addyosmani/agent-skills` | vendored at `third-party/addy-agent-skills/`, pinned SHA `742dca5` (v1.0.0) | `spec-driven-development`, `source-driven-development`, `context-engineering`, `idea-refine`, `incremental-implementation`, `code-review-and-quality`, `code-simplification`, `security-and-hardening`, `debugging-and-error-recovery`, `performance-optimization`, `api-and-interface-design`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `git-workflow-and-versioning`, `planning-and-task-breakdown`, `shipping-and-launch` |
+| `ruflo-swarm` (ruvnet) | vendored at `third-party/ruflo-swarm/`, pinned SHA `addb5cd` (v0.2.0) | `swarm-init`, `monitor-stream`; `swarm_*` and `agent_*` MCP tools; `/swarm`, `/watch` |
+| `oh-my-claudecode` (Yeachan-Heo) | vendored at `third-party/oh-my-claudecode/`, pinned SHA `aacde3e` (v4.13.6) | 39 skills + 19 agents — `release`, `ultrawork`, `ultraqa`, `team`, `trace`, `visual-verdict`, `debug`, `deep-dive`, `deep-interview`, `autopilot`, `autoresearch`, plus a separate `ralph` (overlaps with our `/ralph` — see "Distinct variants" below) |
+
+PM coverage (product-management skills) lives **outside** this marketplace. If you need it, install [`phuryn/pm-skills`](https://github.com/phuryn/pm-skills) separately via Claude Code's host marketplace; the dispatcher names it as a routing target without pre-resolving the namespace. See [docs/THIRD_PARTY.md § Routing in /superpowers](../docs/THIRD_PARTY.md#routing-in-superpowers).
+
+## Distinct variants — never collapse them
+
+Two routing targets carry the same short name across sources. Treat them as distinct; do not silently substitute one for the other.
+
+| Short name | `obra/superpowers` (Obra) | `continuous-improvement` (CI fork) |
+|---|---|---|
+| `superpowers` (skill) | activator routing into Obra skills | `superpowers` skill in this repo: Law-aligned activator wrapping the dispatcher commitments below |
+| `ralph` | not present in Obra | bundled here; `oh-my-claudecode` ships its own `ralph` — pick deliberately, do not auto-merge |
+
+If both Obra `superpowers` and continuous-improvement are loaded, you can call either explicitly: `superpowers:test-driven-development` (Obra) or `tdd-workflow` (CI). Same Law (3+4), different implementation depth.
+
+## Dispatcher commitments (override looser global defaults when `/superpowers` is in scope)
+
+When this dispatcher is active for a task, these six rules apply over any looser convention:
+
+1. **Subagent-driven development is the default for non-trivial tasks.** Two-stage spec + quality review per [obra/superpowers § subagent-driven-development](https://github.com/obra/superpowers).
+2. **Parallel fan-out goes through `superpowers:dispatching-parallel-agents`** (or `/swarm`), not hand-rolled `Task` calls.
+3. **TDD runs RED → GREEN → REFACTOR.** Code written before its test is **deleted**, not retrofitted. Routes to `tdd-workflow` (CI) or `superpowers:test-driven-development` (Obra) — pick by depth, never both for the same task.
+4. **Branch isolation is `using-git-worktrees`** by default for any task that touches more than one file.
+5. **`finishing-a-development-branch` runs before any push.** No bypass via `--no-verify`, `--force`, or direct push to `main`.
+6. **Obra `superpowers` and `continuous-improvement:superpowers` stay distinct.** Both can be installed; neither shadows the other; the dispatcher names which one is firing.
+
+## Routing rules (which source wins)
+
+| User intent | Preferred routing target | Source |
+|---|---|---|
+| New feature, vague requirements | `superpowers:brainstorming` → `:writing-plans` | `obra/superpowers` |
+| Fix this bug | `superpowers:systematic-debugging` → `tdd-workflow` (RED first) → `verification-loop` | Obra → CI → CI |
+| Walk an agent's recommendation list | `proceed-with-the-recommendation` | CI |
+| Write tests for new code | `tdd-workflow` (CI default) or `superpowers:test-driven-development` (Obra, deeper) | CI / Obra |
+| Verify before reporting "done" | `verification-loop` | CI |
+| Refactor, multi-file | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:finishing-a-development-branch` | Obra → Obra → CI → Obra |
+| Long autonomous PRD execution | `/ralph` (CI variant) | CI |
+| Parallel sub-agent fan-out | `superpowers:dispatching-parallel-agents` or `/swarm` | Obra / ruflo-swarm |
+| Spec-first, contract-first feature | `spec-driven-development` | addy-agent-skills |
+| Frontend / UI generation | `frontend-design` (external plugin) | external |
+| Diff walk + severity tagging | `code-review` (external plugin) or `superpowers:requesting-code-review` | external / Obra |
+| Library / framework docs lookup | `documentation-lookup` (Context7 MCP) | external |
+| Compliance / security gate | `security-and-hardening` (addy) → `security-review` (host built-in) | addy → host |
+| Release coordination across PRs | `/release-train` | CI |
+
+## Missing-companion detection
+
+If `/superpowers` is asked to route to a source that is not installed, it does not silently fall back to the inline placeholder. It must:
+
+1. **Name the missing source** explicitly (e.g. `obra/superpowers` not loaded).
+2. **Quote the exact install line** for it from the marketplace already added in setup, e.g. `/plugin install superpowers@continuous-improvement`.
+3. **State the inline-fallback equivalent** that will run if the user declines to install (and which Law that fallback enforces).
+4. **Stop and ask** before continuing. Do not silently downgrade.
+
+This is the same hard-halt discipline used by `proceed-with-the-recommendation` for `needs-approval` items.
+
+## Subcommands
+
+### `/superpowers status`
+
+Show which routing sources are loaded, which workflow stages are active for the current task, and which sources are **missing**:
+
+```
+=== Superpowers Status ===
+
+Sources:
+  [x] continuous-improvement       (bundled)
+  [x] obra/superpowers              v5.1.0 (vendored)
+  [ ] addyosmani/agent-skills       MISSING — /plugin install agent-skills@continuous-improvement
+  [x] ruflo-swarm                   v0.2.0 (vendored)
+  [ ] oh-my-claudecode              MISSING — /plugin install oh-my-claudecode@continuous-improvement
+
+Active for current task:
+  [x] brainstorming (trigger: new feature request)
+  [ ] using-git-worktrees (waiting: design approval)
+  [ ] writing-plans (waiting: worktree ready)
+  [ ] test-driven-development (waiting: plan approved)
+  [ ] requesting-code-review (waiting: implementation)
+  [ ] finishing-a-development-branch (waiting: completion)
+```
+
+### `/superpowers enable <skill>`
+
+Explicitly enable a skill for the current session — useful when the dispatcher's intent detection guesses wrong:
+
+```
+/superpowers enable test-driven-development
+/superpowers enable superpowers:writing-plans   # namespaced form for Obra
+```
+
+### `/superpowers workflow <type>`
+
+Activate a complete workflow preset:
+
+| Preset | Skills activated (in order) |
+|---|---|
+| `new-feature` | `superpowers:brainstorming` → `:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `verification-loop` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `bug-fix` | `superpowers:systematic-debugging` → `verification-loop` → `tdd-workflow` (regression test first) → `:requesting-code-review` |
+| `refactor` | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `review` | `superpowers:requesting-code-review` → `:receiving-code-review` |
+| `release` | `/release-train` → `verification-loop` → `superpowers:finishing-a-development-branch` |
+
+Example:
+```
+/superpowers workflow new-feature
+```
+
+## Verification protocol (Law 4)
+
+Every routed skill must verify before reporting completion. The dispatcher refuses to advance to the next stage until the current one shows:
+
+1. Code runs without errors
+2. Output matches expected result
+3. Actual result checked — not assumed
+4. Build passes
+5. Change explainable in one sentence
+
+This is `verification-loop` from `continuous-improvement`. It runs after every workflow stage, not just at the end.
+
+## Integration
+
+`/superpowers` integrates with:
+
+- **`/seven-laws`** — runs after each stage to capture the reflection block and update instincts (Laws 5 + 7)
+- **`/proceed-with-the-recommendation`** — orchestrates a list of recommendations end-to-end, using `/superpowers` per item
+- **`/workspace-surface-audit`** — runs at task start to confirm the right routing surface is actually present (Law 1 pre-flight)
+- **`/ralph`** — autonomous variant; takes a PRD and walks it story-by-story under the same routing table
+
+## Example session
+
+```
+User: "Build a checkout flow"
+
+[/superpowers status] →
+  Sources: continuous-improvement [x], obra/superpowers [x], others [ ]
+  Routing intent: new-feature
+
+[brainstorming activates — obra/superpowers]
+AI: "Clarifying questions: 1) Payment provider? 2) Guest checkout?"
+
+User: "Stripe, yes guest checkout"
+
+[using-git-worktrees activates — obra/superpowers]
+AI: "Created worktree at ../checkout-feature"
+
+[writing-plans activates — obra/superpowers]
+AI: "Plan created with 6 tasks. Approve?"
+
+User: "Approved"
+
+[tdd-workflow activates — continuous-improvement]
+AI: "Task 1 RED: write failing test for cart validation..."
+AI: "Task 1 GREEN: minimal handler. Verifying with `npm test cart.test.ts`..."
+AI: "Task 1 REFACTOR: extract validator, tests still green. Committing."
+
+[verification-loop activates — continuous-improvement]
+AI: "Build [x] Types [x] Lint [x] Tests 42/42 [x] Security scan clean [x]"
+
+[finishing-a-development-branch activates — obra/superpowers]
+AI: "Options: merge / PR / keep / discard?"
+```

package/commands/swarm.md

@@ -0,0 +1,101 @@
+---
+name: swarm
+description: "Fan out N parallel sub-agents on isolated worktrees with a shared contract test, produce a comparison report. Driven by report.html horizon item 'Parallel Provider-Migration Agents' — pick winners from real evidence instead of discovering tier limits in production."
+---
+
+# /swarm
+
+Parallel-agent fan-out for evidence-based decision-making. Driven by the user's session report: provider-swap epics (Trading Economics → Forex Factory, ETF → CFD, Finnhub → R StocksTrader, Stooq removal) each took multiple sessions and hit fallback bugs in production because alternatives were not vetted upfront.
+
+This command does not replace the `superpowers:dispatching-parallel-agents` skill — it builds on top of it with a contract-pinned, worktree-isolated, comparison-report shape.
+
+## When to use
+
+The right trigger is "I need to pick between N options and I have a contract test that defines what 'works' means." Examples:
+
+- Evaluating N candidate providers behind a shared interface (the report's recurring need)
+- Trying N candidate refactors against the same test suite
+- Prototyping N candidate library upgrades and measuring which breaks the fewest tests
+- Generating N candidate UI designs that all pass the same accessibility + performance budget
+
+Do NOT use this command for:
+
+- Open-ended exploration without a contract — use `superpowers:brainstorming` instead
+- Single-implementation tasks — use the `superpowers:dispatching-parallel-agents` skill directly
+- Tasks where the candidates have different contracts — that is N separate jobs, not a swarm
+
+## Preconditions
+
+1. A shared contract test exists at a path the agents can reference (e.g. `tests/contracts/<name>.test.ts`).
+2. Candidates are listed up front (3-6 typical; 8 max). Letting agents propose candidates is allowed but the list freezes before fan-out.
+3. The base branch is clean.
+4. Each candidate has a clear evaluation rubric: PASS/FAIL per contract test, plus per-candidate measurements (latency, coverage, cost, free-tier limits, etc. — domain-specific).
+
+## Behavior
+
+1. **Plan** — restate the objective, list candidates, confirm contract test path. If unclear, halt and ask.
+2. **Bootstrap** — for each candidate, create an isolated worktree off `origin/main`: `git worktree add -b swarm/<objective>-<candidate> ../<candidate>`. Pin the base SHA in the swarm log.
+3. **Fan out** — dispatch one fresh sub-agent per candidate via the `Agent` tool, in a single message (parallel, not serial). Each agent receives the contract test path, the candidate name, the rubric, and the worktree path.
+4. **Run** — each agent implements the candidate behind the shared interface, runs the contract test against it, captures measurements per the rubric, and writes findings to `reports/<objective>/<candidate>.md`.
+5. **Synthesize** — when all agents complete, this command produces a decision matrix (candidates × rubric metrics) and recommends a winner with citations to the per-candidate reports.
+6. **Stop** — does NOT merge any candidate's worktree. Does NOT modify production. Output is evidence; the operator decides which candidate to advance.
+
+## Topology
+
+The default topology is **flat fan-out** — all agents run in parallel, no inter-agent communication. This matches the report's actual gap (provider migrations were each independent prototypes).
+
+When `ruflo-swarm` is installed (`/plugin install ruflo-swarm@continuous-improvement`), an alternate topology becomes available: `hierarchical-mesh` with a coordinator role brokering stage hand-off. Activate via `/swarm --topology hierarchical-mesh`.
+
+Available topologies (when ruflo-swarm installed):
+
+| Topology | When to use |
+|---|---|
+| `flat` (default) | Independent prototypes, no shared state |
+| `hierarchical` | One coordinator + N workers; workers report to coordinator only |
+| `mesh` | Workers can share intermediate findings |
+| `hierarchical-mesh` | Coordinator plus worker-to-worker chat |
+| `ring` | Each worker hands off to the next; sequential within a parallel start |
+| `star` | All workers report to a central evaluator that filters before synthesis |
+| `adaptive` | Topology selected per-step based on intermediate findings |
+
+## Stop conditions
+
+Halt and surface to the operator if:
+
+- Any agent reports the contract test is itself broken (test suite is the source of truth; if it is wrong, no candidate can win).
+- A candidate's evaluation reveals the rubric is incomplete (a metric the rubric doesn't measure changes the answer).
+- More than 50% of agents fail to produce a report (likely environment or harness issue, not candidate quality).
+- The winner-by-rubric and the reports' qualitative findings disagree (surface the conflict; do not paper over it).
+
+## Stream observation
+
+Long swarm runs feel opaque. When `ruflo-swarm:monitor-stream` is installed, this command emits live progress events to a stream the operator can tail. Without it, this command writes per-step lines to `reports/<objective>/swarm.log` that can be tailed with `tail -f`.
+
+## Composition
+
+This command activates the unified `/superpowers` dispatcher and routes through:
+
+- `superpowers:dispatching-parallel-agents` for the fan-out shape
+- `ruflo-swarm:swarm-init` (when installed) for contract-pinned bootstrap
+- `ruflo-swarm:monitor-stream` (when installed) for stream observation
+- `superpowers:writing-plans` (or inline fallback) for the candidate list + rubric
+- `proceed-with-the-recommendation` for walking the synthesis output as a recommendation list
+
+## Anti-patterns this command refuses
+
+- **Letting one candidate run before others start.** All worktrees and agents bootstrap together; no early-bird advantage.
+- **Modifying the contract test mid-run.** Test is source of truth; halt instead.
+- **Picking a winner without measurements.** The synthesis must cite the rubric, not just the agents' summaries.
+- **Merging any worktree.** Output is evidence; operator decides advancement.
+
+## Example
+
+```
+/swarm "Pick the next market data provider"
+
+Candidates: Swissquote, R StocksTrader, Twelve Data, Finnhub
+Contract: tests/contracts/provider-contract.test.ts
+Rubric: PASS/FAIL per contract test, p50/p99 latency, symbol coverage for 50 tracked instruments, free-tier limits, monthly cost at expected volume
+```
+
+The orchestrator opens four worktrees, runs four agents in parallel, produces `reports/market-data-provider/{swissquote,rstockstrader,twelve-data,finnhub}.md`, and a `decision-matrix.md` with the recommended winner cited from the rubric.

package/commands/workspace-surface-audit.md

@@ -0,0 +1,77 @@
+---
+name: workspace-surface-audit
+description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
+---
+
+# /workspace-surface-audit
+
+Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
+
+## Usage
+
+```
+/workspace-surface-audit
+```
+
+## What It Checks
+
+1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
+2. **Environment surface** — `.env*` files (key names only, no secrets)
+3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
+4. **continuous-improvement surface** — existing skills, commands, hooks, agents
+
+## Output Format
+
+```
+=== Workspace Surface Audit ===
+
+## Current Surface
+- [What is usable right now]
+
+## Parity
+- [Where continuous-improvement matches or exceeds benchmarks]
+
+## Primitive-Only Gaps
+- [Tools exist, but continuous-improvement lacks clean operator skills]
+
+## Missing Integrations
+- [Capabilities not available yet]
+
+## Top 3-5 Next Moves
+1. [Concrete continuous-improvement-native addition]
+2. [Ordered by impact]
+```
+
+## Rules
+
+- **Never print secrets** — only provider names, capability names, file paths
+- **Prefer continuous-improvement** over generic "install another plugin" advice
+- **Organize by workflows**, not API brands
+- **Specific recommendations** — concrete enough to implement without another discovery pass
+
+## Example Output
+
+```
+## Current Surface
+- MCP: filesystem, github, playwright
+- Plugins: beginner, expert (continuous-improvement)
+- Env: STRIPE_API_KEY, FAL_KEY configured
+- Framework: Next.js 15, React 19, TypeScript
+
+## Parity
+- Continuous improvement: covered (native)
+- Testing discipline: covered (TDD workflows)
+
+## Primitive-Only Gaps
+- Stripe connected but no billing-operator skill
+- GitHub MCP available but no issue-triage workflow
+
+## Missing Integrations
+- No Linear connector detected
+- No Slack webhook configured
+
+## Top 3-5 Next Moves
+1. Create billing-operator skill (Stripe integration)
+2. Create github-ops workflow for issue triage
+3. Add Linear connector skill for project management
+```

package/hooks/gateguard.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Runtime PreToolUse gateguard hook.
+ *
+ * Stdin  : JSON { tool_name, tool_input }
+ * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Exit   : 0 always (decision is in stdout, fail-open on parse error).
+ *
+ * Three-stage gate per skills/gateguard.md:
+ * - DENY  : first mutating tool call per file, with fact-list reason
+ * - FORCE : agent presents facts (model-side; out of band)
+ * - ALLOW : retry once `_gateguard_facts_presented: true` is set or the
+ *           per-file marker is recorded in session state
+ *
+ * Read-only and exploratory tools (Read, Grep, Glob, routine Bash) bypass
+ * unconditionally. Destructive Bash gates EVERY call, not just first.
+ *
+ * V1 honest limitations (see src/lib/gateguard-state.mts header):
+ *   honor-system flag, state-file deletion, parallel-hook race.
+ *
+ * MultiEdit handling (V1): gates on edits[0].file_path only. Per-file
+ * batching is not implemented — TODO: extend to gate every entry in
+ * edits[]. Tracked in issue #106 acceptance criteria item 5.
+ */
+import { readFileSync } from "node:fs";
+import { isCapReached, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+const TOOL_ROUTE = {
+    Read: "allow",
+    Grep: "allow",
+    Glob: "allow",
+    LS: "allow",
+    NotebookRead: "allow",
+    Write: "mutating-file",
+    Edit: "mutating-file",
+    MultiEdit: "mutating-file",
+    NotebookEdit: "mutating-file",
+    Bash: "allow",
+};
+const DESTRUCTIVE_PATTERNS = [
+    "rm -rf",
+    "rm -fr",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "--force-with-lease",
+    "git branch -D",
+    "drop table",
+    "drop database",
+    "drop schema",
+    "truncate ",
+    "mkfs",
+    "dd if=",
+    "format ",
+    "rmdir /s",
+    "del /f /q",
+    "del /q /f",
+    "Remove-Item -Recurse",
+    "Remove-Item -Force",
+];
+function isDestructiveBash(command) {
+    const lower = command.toLowerCase();
+    return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+}
+function classifyTool(toolName, toolInput) {
+    const route = TOOL_ROUTE[toolName] ?? "allow";
+    if (route !== "allow")
+        return route;
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        if (isDestructiveBash(toolInput.command))
+            return "destructive-bash";
+    }
+    return "allow";
+}
+function extractFilePath(toolInput) {
+    if (typeof toolInput.file_path === "string")
+        return toolInput.file_path;
+    // MultiEdit V1: first edit's file_path is the canonical key.
+    if (Array.isArray(toolInput.edits) && toolInput.edits.length > 0) {
+        const first = toolInput.edits[0];
+        if (first && typeof first.file_path === "string")
+            return first.file_path;
+    }
+    if (typeof toolInput.command === "string")
+        return toolInput.command;
+    return "";
+}
+function buildMutatingFileReason(toolName, filePath) {
+    return [
+        `Before ${toolName === "Write" ? "creating" : "editing"} ${filePath || "<unknown>"}, present these facts:`,
+        "",
+        "  1. List ALL files that import/require this file (use Grep)",
+        "  2. List the public functions/classes affected by this change",
+        "  3. If this file reads/writes data files, show field names, structure, and date format",
+        "  4. Quote the user's current instruction verbatim",
+        "",
+        "After presenting the facts, retry with `_gateguard_facts_presented: true` in tool_input,",
+        "or with the same file_path after a previous clearance has been recorded for this session.",
+    ].join("\n");
+}
+function buildDestructiveBashReason(command) {
+    return [
+        `Destructive command requested: ${command}`,
+        "",
+        "  1. List ALL files/data this command will modify or delete",
+        "  2. Write a one-line rollback procedure",
+        "  3. Quote the user's current instruction verbatim",
+        "",
+        "Destructive Bash gates EVERY call — clearance is not cached.",
+    ].join("\n");
+}
+function buildCapReachedReason() {
+    return [
+        "Gateguard session clearance cap reached (50 distinct files).",
+        "Start a new Claude Code session to reset the gate. The cap exists to bound",
+        "stuck-loop or rogue-agent clearance from compounding within a single session.",
+    ].join("\n");
+}
+function emit(decision) {
+    process.stdout.write(`${JSON.stringify(decision)}\n`);
+    process.exit(0);
+}
+function main() {
+    let raw = "";
+    try {
+        raw = readFileSync(0, "utf8");
+    }
+    catch {
+        emit({ decision: "allow" });
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        emit({ decision: "allow" }); // fail-open
+        return;
+    }
+    const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
+    const toolInput = payload.tool_input ?? {};
+    const gate = classifyTool(toolName, toolInput);
+    if (gate === "allow") {
+        emit({ decision: "allow" });
+        return;
+    }
+    if (gate === "destructive-bash") {
+        const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
+        emit({ decision: "block", reason: buildDestructiveBashReason(cmd) });
+        return;
+    }
+    // mutating-file
+    const sessionDir = resolveSessionDir();
+    const state = loadState(sessionDir);
+    const filePath = extractFilePath(toolInput);
+    const factsFlagged = toolInput._gateguard_facts_presented === true;
+    const alreadyCleared = filePath !== "" && filePath in state.cleared_files;
+    if (!factsFlagged && !alreadyCleared) {
+        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePath) });
+        return;
+    }
+    if (factsFlagged && !alreadyCleared) {
+        if (isCapReached(state)) {
+            emit({ decision: "block", reason: buildCapReachedReason() });
+            return;
+        }
+        if (filePath !== "") {
+            saveState(sessionDir, markFileCleared(state, filePath));
+        }
+    }
+    emit({ decision: "allow" });
+}
+main();

package/hooks/observe.sh

@@ -1,11 +1,32 @@
 #!/usr/bin/env bash
-# observe.sh — Mulahazah PreToolUse/PostToolUse observation hook
-# Captures every tool call as a JSONL line. Must complete in <50ms. Always exits 0.
+# observe.sh — Mulahazah PreToolUse/PostToolUse observation hook.
+#
+# Two-phase design:
+#   1. PREFERRED: exec the Node observer (bin/observe.mjs) which captures the
+#      rich event schema (tool_input.command for Bash, file_path for Edit/
+#      Write/Read, tool_output) without depending on jq.
+#   2. FALLBACK: if either node is missing OR the Node observer file is not
+#      installed alongside this script, fall through to the in-bash thin-
+#      schema path below. The fallback preserves prior behavior so an
+#      operator who never re-runs `npx continuous-improvement install` is
+#      no worse off than today.
+#
+# Always exits 0 — never blocks the Claude session.
 # Usage: echo '<hook_json>' | observe.sh
 
-# Always exit 0 — never block the Claude session
 trap 'exit 0' EXIT ERR INT TERM
 
+# Phase 1 — try the Node observer. The shim copies bin/observe.mjs and
+# lib/observe-event.mjs alongside this script under ${HOME}/.claude/instincts/
+# preserving the bin/ + lib/ subdirectory layout so the relative import
+# resolves: observe.mjs lives at .../instincts/bin/observe.mjs, the imported
+# observe-event.mjs at .../instincts/lib/observe-event.mjs.
+NODE_OBSERVER="$(dirname "${BASH_SOURCE[0]}")/bin/observe.mjs"
+if [[ -f "$NODE_OBSERVER" ]] && command -v node &>/dev/null; then
+  exec node "$NODE_OBSERVER"
+fi
+
+# Phase 2 — bash fallback (thin schema; preserved for back-compat).
 INSTINCTS_DIR="${HOME}/.claude/instincts"
 
 # ---------------------------------------------------------------------------
@@ -16,6 +37,11 @@ INPUT="$(cat)"
 
 # ---------------------------------------------------------------------------
 # Parse hook payload — use jq if available, otherwise basic extraction
+#
+# When jq is missing, observation rows lack tool_input/tool_output, which
+# defeats the auto-instinct pipeline. Emit a one-shot stderr warning per
+# project so the operator notices at the next session start instead of
+# discovering the gap weeks later. The marker file makes it idempotent.
 # ---------------------------------------------------------------------------
 if command -v jq &>/dev/null; then
   read -r TOOL_NAME SESSION_ID HAS_OUTPUT INPUT_JSON OUTPUT_JSON <<< "$(
@@ -28,6 +54,15 @@ if command -v jq &>/dev/null; then
     ' | paste - - - - -
   )"
 else
+  # One-shot stderr warning per HOME so the operator learns the constraint.
+  # Marker lives next to instincts/ (not inside it) so it never collides with
+  # tests or analysis loops that iterate INSTINCTS_DIR for project-hash dirs.
+  JQ_WARN_MARKER="${HOME}/.claude/.continuous-improvement-jq-warned"
+  if [[ ! -f "$JQ_WARN_MARKER" ]]; then
+    mkdir -p "${HOME}/.claude" 2>/dev/null
+    printf '[continuous-improvement] jq not found on PATH — observe.sh is using thin-schema fallback. Install jq to enable auto-instinct detection (winget install jqlang.jq | brew install jq | apt install jq). This warning is one-shot per host.\n' >&2
+    : > "$JQ_WARN_MARKER"
+  fi
   # Fallback: extract tool_name with basic pattern matching
   TOOL_NAME="$(printf '%s' "$INPUT" | sed -n 's/.*"tool_name" *: *"\([^"]*\)".*/\1/p' | head -1)"
   SESSION_ID="$(printf '%s' "$INPUT" | sed -n 's/.*"session_id" *: *"\([^"]*\)".*/\1/p' | head -1)"
@@ -83,7 +118,10 @@ OBS_FILE="${PROJECT_DIR}/observations.jsonl"
 if [[ -f "$OBS_FILE" ]]; then
   LINE_COUNT="$(wc -l < "$OBS_FILE")"
   if (( LINE_COUNT >= 10000 )); then
-    mv "$OBS_FILE" "${PROJECT_DIR}/observations.$(date -u +"%Y-%m-%d").jsonl"
+    mv "$OBS_FILE" "${PROJECT_DIR}/observations.$(date -u +"%Y-%m-%d-%H%M%S").jsonl"
+    
+    # Clean up old archives - keep only 10 most recent
+    ls -t "${PROJECT_DIR}"/observations.*.jsonl 2>/dev/null | tail -n +11 | xargs -r rm -f
   fi
 fi
 

package/hooks/session.sh

@@ -78,9 +78,9 @@ if [[ "$EVENT_TYPE" == "SessionStart" || "$EVENT_TYPE" == "unknown" ]]; then
           [[ -f "$f" ]] || continue
           conf="$(grep '^confidence:' "$f" 2>/dev/null | head -1 | sed 's/confidence: *//')"
           if [[ -n "$conf" ]]; then
-            # Compare as integer (multiply by 100)
-            int_conf="$(printf '%.0f' "$(echo "$conf * 100" | bc 2>/dev/null || echo 0)")"
-            if (( int_conf >= 70 )); then
+            # Compare as integer (multiply by 100) using awk for portability
+            int_conf="$(printf '%s' "$conf" | awk '{printf "%.0f", $1 * 100}')"
+            if [[ -n "$int_conf" ]] && (( int_conf >= 70 )); then
               LEVEL="AUTO-APPLY"
               break 2
             elif (( int_conf >= 50 )); then