continuous-improvement 3.1.0 → 3.9.1

package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: continuous-improvement
-description: "Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. Auto-levels from silent observation to active suggestions to auto-applied behaviors."
+tier: core
+description: "Install structured self-improvement loops with instinct-based learning into Claude Code — research, plan, execute, verify, reflect, learn, iterate. On-demand or weekly analysis to save tokens. Supports multi-agent parallel analysis."
 ---
 
 # continuous-improvement
@@ -28,9 +29,9 @@ Before executing, state:
 ## Law 3: One Thing at a Time
 
 - Complete and verify one task before starting the next
-- Never spawn parallel work for tasks you can do directly
 - Never report completion until you've checked actual output
 - If you want to "also quickly add" something — stop. Finish first.
+- **Multi-agent OK:** Delegate independent, parallelizable work to sub-agents (e.g., security review + code review + tests in parallel). Each agent follows the 7 Laws independently. Only parallelize when tasks have no shared state.
 
 ## Law 4: Verify Before Reporting
 
@@ -50,10 +51,35 @@ After non-trivial tasks:
 - What failed:
 - What I'd do differently:
 - Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary — strongest next move>
+  2. <alternative — different angle, if user wants to pivot>
+  3. <alternative — smaller/larger scope, if user wants to adjust>
 ```
 
 The "Rule to add" field feeds Law 7 — it becomes an instinct with 0.6 starting confidence.
 
+The "Iteration — Next best recommendations" field feeds Law 6. List the **top 3 ranked** core-development moves based on the current code state — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest recommendation; #2 and #3 are alternative directions the user can pick from. NOT git plumbing (commit, push, PR), NOT pure CI ceremony (run tests, type-check), NOT deploy steps. Those belong in the end-of-run summary, not here.
+
+Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
+
+Good examples (development progression):
+- `Implement settleWeekAndPostPrizes writer for quiz source in src/scheduled.ts (real_contest writer exists; quiz path is recognized but inert)`
+- `Refactor contestModeGuard at src/routes/trading-contest.ts to share the 4-mode switch with /admin/mode (logic duplicated, drift risk)`
+- `Investigate why Saturday cron occasionally skips Week activation in src/scheduled.ts:625 (one missed run on 2026-04-19; root cause unknown)`
+- `Add server-side enforcement for the $100 new-deposit rule in real-contest entry handler (currently advisory; admin reviews post-contest)`
+
+Anti-examples (rejected — these are workflow, not development):
+- `Commit changes` / `Open PR` / `Push to origin` → belongs in summary, not here
+- `Run vitest` / `Run tsc` → that is verification (Law 4), already done before reporting
+- `Deploy to prod` → operational, needs-approval, never an autonomous next step
+
+Rules:
+- Always exactly 3 items, ranked. Not 2, not 5.
+- All 3 must be distinct directions — do not pad with rephrases of #1.
+- If fewer than 3 real moves exist, fill remaining slots with `None — goal met from this angle.` rather than inventing busywork.
+- If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
+
 ## Law 6: Iterate Means One Thing
 
 One change → verify → next change.
@@ -74,6 +100,19 @@ If the user corrects you, the instinct weakens. If they don't, it strengthens.
 
 Nothing learned is permanent. Everything decays without reinforcement.
 
+### Friction Harvest Pipeline (`/harvest`)
+
+Beyond the reflection-driven path above, the **friction harvest classifier** turns observation logs (`~/.claude/instincts/<project-hash>/observations.jsonl`) into typed instincts automatically. Run via `/harvest` or `node bin/harvest-friction.mjs`. Four typed friction patterns with confidence scoring:
+
+- **`env_issue`** — jq missing, command not found, not recognized as cmdlet
+- **`permission_block`** — sandbox / harness blocked, Permission denied
+- **`wrong_approach`** — file changed since last read (parallel-actor stale)
+- **`buggy_code`** — file not read first, old_string ambiguous, file too large
+
+Idempotent: each instinct's `dedup_key = sha1(type + tool + summary[:120])`; re-running on the same observations does not duplicate previously-written instincts. Confidence weights frequency × recency-decay so old failures fade and recurring ones strengthen, in line with the Law 7 contract above.
+
+The harvest is opt-in: it runs only when explicitly invoked. Cron / hook triggers are deliberately not wired so the operator stays in control of when the classifier reads observation history.
+
 ## The Loop
 
 ```
@@ -86,11 +125,23 @@ If you're skipping a step, that's the step you need most.
 
 ## Instinct System (Mulahazah)
 
-At the start of every session, check `~/.claude/instincts/` for this project's instincts.
+### Execution Mode: On-Demand (Default)
+
+The instinct system does **NOT** run automatically at session start. This saves tokens.
+
+| Mode | When it runs | Token cost |
+|------|-------------|------------|
+| **On-demand** (default) | Only when user runs `/continuous-improvement` or `/dashboard` | Zero overhead per session |
+| **Weekly** | User schedules via `/loop 7d /continuous-improvement analyze` or cron | One analysis per week |
+| **Always-on** (opt-in) | Set `always_on: true` in project instinct config | Runs at every session start |
+
+**To enable always-on:** Create `~/.claude/instincts/<hash>/config.yaml` with `always_on: true`. Otherwise, instincts are only loaded when explicitly requested.
+
+**Hooks still capture silently** — observations accumulate in `observations.jsonl` with near-zero cost. The expensive part (reading, analyzing, creating instincts) only happens when you ask for it.
 
 ### Auto-Level Detection
 
-Determine current level automatically:
+When analysis is triggered (on-demand, weekly, or always-on), determine level:
 
 1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars of the path
 2. **Check observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
@@ -105,9 +156,9 @@ Determine current level automatically:
 
 Multiple levels can be active simultaneously — you might auto-apply some instincts while suggesting others.
 
-### Inline Analysis
+### Analysis (On-Demand)
 
-When 20+ unprocessed observations exist, analyze them as part of session startup:
+When triggered by `/continuous-improvement analyze`, weekly schedule, or always-on mode:
 
 1. Read `observations.jsonl` (last 500 lines)
 2. Read existing instincts (project + global `*.yaml` files)
@@ -119,6 +170,16 @@ When 20+ unprocessed observations exist, analyze them as part of session startup
 4. Create/update instinct YAML files in the project directory
 5. Be conservative: only create instincts for 3+ observations of the same pattern
 
+### Multi-Agent Analysis
+
+For large observation backlogs (500+ lines), parallelize analysis across agents:
+
+- **Agent 1:** Analyze user corrections and error→fix sequences
+- **Agent 2:** Analyze repeated workflows and tool preferences
+- **Agent 3:** Cross-reference with existing instincts for updates/promotions
+
+Each agent writes to separate temp files; the orchestrator merges results and deduplicates.
+
 ### Instinct Format
 
 Each instinct is a YAML file in `~/.claude/instincts/<hash>/` or `~/.claude/instincts/global/`:
@@ -160,12 +221,29 @@ Cap: 0.9 max. Scope: default to project; promote to global when seen in 2+ proje
 
 ## /continuous-improvement Command
 
-Run `/continuous-improvement` after significant work:
+Run `/continuous-improvement` when you want to reflect and learn — not every session.
 
 1. **Reflect** — Generate Law 5 reflection
 2. **Analyze** — Process pending observations into instincts
 3. **Status** — Show all instincts with confidence and current level
 
 Subcommands:
-- `/continuous-improvement status` — Instinct overview only
-- `/continuous-improvement analyze` — Force analysis of pending observations
+- `/continuous-improvement status` — Instinct overview only (lightweight, reads YAML only)
+- `/continuous-improvement analyze` — Process pending observations into instincts
+- `/continuous-improvement weekly` — Set up weekly analysis schedule
+- `/continuous-improvement always-on` — Enable/disable always-on mode for this project
+
+## Planning-With-Files (Opt-In)
+
+Use this workflow only when the user explicitly asks for persistent, file-based planning or asks to use Planning-With-Files.
+
+- Detect the project root with `git rev-parse --show-toplevel`; if that fails, use the current working directory.
+- Create and maintain three project-root files:
+  - `task_plan.md` — phases, status, questions, decisions, errors
+  - `findings.md` — research notes, sources, synthesized discoveries
+  - `progress.md` — session log, verification notes, checkpoints
+- Default phases in `task_plan.md`: `Research`, `Plan`, `Execute`, `Verify`, `Reflect`
+- Never create these files automatically for normal work. This workflow is opt-in.
+- Never overwrite existing planning files unless the user explicitly asks to reset or replace them.
+
+When resuming work, read the three files before making major decisions so context survives long tasks and new sessions.

package/action.yml

@@ -1,5 +1,5 @@
 name: 'AI Agent Discipline Linter'
-description: 'Lint AI agent transcripts for compliance with the 7 Laws of AI Agent Discipline'
+description: 'Catch agents that skipped research, planning, or verification — by linting their transcript in CI against the 7 Laws of AI Agent Discipline.'
 author: 'naimkatiman'
 
 branding:

package/bin/analyze.sh

@@ -20,7 +20,15 @@ if [[ -z "$PROJECT_ROOT" ]]; then
   PROJECT_ROOT="global"
 fi
 
-PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
+# Use shasum on macOS, sha256sum on Linux
+if command -v sha256sum &>/dev/null; then
+  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
+elif command -v shasum &>/dev/null; then
+  PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | shasum -a 256 | cut -c1-12)"
+else
+  # Fallback: use project root basename if no hashing available
+  PROJECT_HASH="$(basename "$PROJECT_ROOT" | tr -cd 'a-zA-Z0-9' | cut -c1-12)"
+fi
 PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
 PROJECT_DIR="${INSTINCTS_DIR}/${PROJECT_HASH}"
 OBS_FILE="${PROJECT_DIR}/observations.jsonl"

package/bin/backfill.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// backfill.mts — Tag legacy thin-schema observation rows for skip-clean
+// consumption by the analysis pass.
+//
+// Walks ~/.claude/instincts/<hash>/observations.jsonl files and writes a
+// `schema: "thin" | "rich"` field on every row that doesn't already have one.
+// Per the plan doc: this is a flag-pass, not a content-recovery — the original
+// thin rows lack the input we'd need to fabricate richer fields. Tagging lets
+// the analysis pass cleanly skip thin rows and surface a "X% of observations
+// were thin" stat to operators so they understand why their auto-instinct
+// pipeline historically produced nothing.
+//
+// Output:
+//   - <home>/.claude/instincts/<hash>/observations.jsonl   (rewritten in place
+//     with schema field appended; original preserved as .bak)
+//   - <home>/.claude/instincts/backfill-summary.json       (per-project digest)
+//
+// Flags:
+//   --dry-run  Read everything, write nothing; print counts to stdout.
+//
+// Idempotent: re-running on already-tagged rows is a no-op.
+// Exit code: always 0. Failures land on stderr only.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run");
+const HELP = args.includes("--help") || args.includes("-h");
+if (HELP) {
+    console.log(`
+backfill — Tag legacy thin-schema observation rows.
+
+Usage:
+  npx continuous-improvement backfill            Tag rows in place
+  npx continuous-improvement backfill --dry-run  Report counts, write nothing
+
+What it does:
+  Walks ~/.claude/instincts/<hash>/observations.jsonl files and adds a
+  schema field ("thin" or "rich") to every row that lacks one. Thin rows
+  came from the legacy bash fallback (jq missing) and have no input_summary;
+  rich rows came from the Node observer and have full tool_input.command /
+  Edit.file_path / etc.
+
+Output:
+  - observations.jsonl rewritten in place (original kept as .bak)
+  - backfill-summary.json with per-project counts
+
+Idempotent. Always exits 0 — failures go to stderr only.
+`);
+    process.exit(0);
+}
+main();
+function main() {
+    try {
+        runBackfill();
+    }
+    catch (error) {
+        process.stderr.write(`[backfill] ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.exit(0);
+}
+function runBackfill() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    const instinctsDir = join(home, ".claude", "instincts");
+    if (!existsSync(instinctsDir)) {
+        if (!DRY_RUN)
+            mkdirSync(instinctsDir, { recursive: true });
+        return;
+    }
+    const projectDirs = listProjectDirs(instinctsDir);
+    const summary = {
+        total: 0,
+        thin: 0,
+        rich: 0,
+        projects: {},
+        generated_at: new Date().toISOString(),
+    };
+    for (const dir of projectDirs) {
+        const obsFile = join(dir, "observations.jsonl");
+        if (!existsSync(obsFile))
+            continue;
+        const projectId = basename(dir);
+        const stat = { total: 0, thin: 0, rich: 0 };
+        const newLines = [];
+        const corruptLines = [];
+        let mutated = false;
+        const raw = readFileSync(obsFile, "utf8");
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            let row;
+            try {
+                row = JSON.parse(trimmed);
+            }
+            catch {
+                process.stderr.write(`[backfill] skipped corrupt row in ${projectId}: ${trimmed.slice(0, 80)}\n`);
+                // Drop from main file but preserve in observations.corrupt.jsonl
+                // so the operator never silently loses data.
+                corruptLines.push(trimmed);
+                mutated = true;
+                continue;
+            }
+            stat.total++;
+            summary.total++;
+            const previousSchema = row.schema;
+            const isRich = typeof row.input_summary === "string" && row.input_summary.length > 0;
+            const newSchema = isRich ? "rich" : "thin";
+            if (previousSchema !== newSchema) {
+                row.schema = newSchema;
+                mutated = true;
+            }
+            if (newSchema === "thin") {
+                stat.thin++;
+                summary.thin++;
+            }
+            else {
+                stat.rich++;
+                summary.rich++;
+            }
+            newLines.push(JSON.stringify(row));
+        }
+        summary.projects[projectId] = stat;
+        if (mutated && !DRY_RUN) {
+            // Atomic-ish write: backup → write → keep .bak for one cycle.
+            const backup = obsFile + ".bak";
+            renameSync(obsFile, backup);
+            writeFileSync(obsFile, newLines.join("\n") + "\n", "utf8");
+            if (corruptLines.length > 0) {
+                // Quarantine corrupt rows so operator data is never silently lost.
+                const corruptFile = join(dir, "observations.corrupt.jsonl");
+                const existing = existsSync(corruptFile) ? readFileSync(corruptFile, "utf8") : "";
+                writeFileSync(corruptFile, existing + corruptLines.join("\n") + "\n", "utf8");
+            }
+        }
+    }
+    if (DRY_RUN) {
+        process.stdout.write(formatReport(summary, true));
+        return;
+    }
+    const summaryPath = join(instinctsDir, "backfill-summary.json");
+    writeFileSync(summaryPath, JSON.stringify(summary, null, 2) + "\n", "utf8");
+    process.stdout.write(formatReport(summary, false));
+}
+function listProjectDirs(instinctsDir) {
+    // Real project-hash dirs are sha256[:12] (hex). Test fixtures use 12-char
+    // alpha labels (g/h/i are not hex but make tests readable). Both are
+    // matched here; the broader pattern is harmless because real instincts/
+    // sub-dirs only ever contain hex hashes plus 'global' / loose dotfiles.
+    return readdirSync(instinctsDir)
+        .filter((name) => /^[0-9a-z]{12}$/.test(name))
+        .map((name) => join(instinctsDir, name))
+        .filter((dir) => {
+        try {
+            return statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function formatReport(summary, isDryRun) {
+    const projects = Object.keys(summary.projects);
+    const lines = [
+        isDryRun ? "[backfill --dry-run] would tag the following:" : "[backfill] tagged:",
+        `  total rows: ${summary.total}`,
+        `  thin rows:  ${summary.thin}`,
+        `  rich rows:  ${summary.rich}`,
+        `  projects:   ${projects.length}`,
+    ];
+    return lines.join("\n") + "\n";
+}

package/bin/check-doc-runtime-claims.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Doc Runtime-Claims Check
+ *
+ * Codifies the audit-twice rule (memory: feedback_grep_hook_before_claim).
+ *
+ * Any user-facing line that claims a runtime hook / PreToolUse gate /
+ * physical block must be accompanied by a `hooks/<file>.mjs` reference
+ * inside a ±5-line window. Without that anchor, the doc is making a
+ * claim a future reader cannot verify against the actual filesystem.
+ *
+ * Origin: PR #105 shipped a smoke test that promised gateguard would
+ * physically block, when the hook did not yet exist. PR #108 built the
+ * hook. PR #115 reverted the inverse drift after the hook shipped but
+ * docs still said "roadmap." This lint locks the audit-twice rule into
+ * automation so the next runtime claim cannot land without its anchor.
+ *
+ * Scope: QUICKSTART.md, README.md, skills/*.md.
+ * Out of scope: bundle mirrors under plugins/, docs/, third-party/.
+ *
+ * Trigger phrases (case-insensitive substring match on the line):
+ *   - "PreToolUse hook"
+ *   - "physically block"   (catches "physically blocks", "physical block")
+ *   - "runtime gate"
+ *
+ * Deliberately narrow per the spec that authorized this lint. "runtime
+ * hook" was considered and dropped: too prone to false positives on
+ * disclaimers ("not a runtime hook", "no runtime hook is bundled").
+ * Future trigger additions need an explicit owner decision; do not bolt
+ * on phrases just because they sound related.
+ *
+ * Anchor: any reference matching `hooks/<name>.mjs` (case-insensitive)
+ * inside the ±5-line window (the trigger line itself plus 5 lines above
+ * and 5 lines below).
+ *
+ * Usage:
+ *   node bin/check-doc-runtime-claims.mjs              # Check the current repo
+ *   node bin/check-doc-runtime-claims.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every runtime-claim line has an in-window hooks/ anchor
+ *   1 — at least one claim line is unanchored
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const SCAN_FILES = ["QUICKSTART.md", "README.md"];
+const SCAN_SKILL_DIR = "skills";
+const ANCHOR_WINDOW = 5;
+const TRIGGER_PHRASES = [
+    "pretooluse hook",
+    "physically block",
+    "runtime gate",
+];
+const ANCHOR_PATTERN = /hooks\/[a-z0-9-]+\.mjs/i;
+function listSkillFiles(repoRoot) {
+    const skillsDir = join(repoRoot, SCAN_SKILL_DIR);
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((f) => /^[a-z][a-z0-9-]*\.md$/.test(f))
+        .map((f) => join(SCAN_SKILL_DIR, f))
+        .sort();
+}
+function scanFile(repoRoot, relPath) {
+    const fullPath = join(repoRoot, relPath);
+    let content;
+    try {
+        content = readFileSync(fullPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split(/\r?\n/);
+    const violations = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const lower = lines[i].toLowerCase();
+        const matchedPhrase = TRIGGER_PHRASES.find((p) => lower.includes(p));
+        if (!matchedPhrase)
+            continue;
+        const start = Math.max(0, i - ANCHOR_WINDOW);
+        const end = Math.min(lines.length - 1, i + ANCHOR_WINDOW);
+        const window = lines.slice(start, end + 1).join("\n");
+        if (ANCHOR_PATTERN.test(window))
+            continue;
+        violations.push({
+            file: relPath,
+            line: i + 1,
+            text: lines[i].trim(),
+        });
+    }
+    return violations;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const files = [...SCAN_FILES, ...listSkillFiles(repoRoot)];
+    const allViolations = [];
+    for (const file of files) {
+        allViolations.push(...scanFile(repoRoot, file));
+    }
+    if (allViolations.length === 0) {
+        console.log(`OK doc-runtime-claims: every runtime-claim line in ${files.length} scanned file(s) has a hooks/<name>.mjs anchor within ±${ANCHOR_WINDOW} lines.`);
+        exit(0);
+    }
+    console.error(`FAIL doc-runtime-claims: ${allViolations.length} unanchored runtime-claim line(s) found.`);
+    console.error(`Each line below contains a runtime-claim phrase but has no hooks/<name>.mjs reference within ±${ANCHOR_WINDOW} lines.`);
+    console.error("Add the hook file path inline so a reader can verify the claim against the filesystem.");
+    console.error("");
+    for (const v of allViolations) {
+        console.error(`  ${v.file}:${v.line}`);
+        console.error(`    ${v.text}`);
+    }
+    exit(1);
+}
+main();