continuous-improvement 3.1.0 → 3.9.1

package/hooks/three-section-close.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// three-section-close.mjs — Stop hook that requires every substantive
+// assistant reply to close with three named sections:
+//   "What has been done", "What is next", "Recommendation".
+//
+// Implements Law 4 + Law 5 in-band: verify before reporting, reflect at
+// the end. See SKILL.md for the discipline rationale.
+//
+// Behavior:
+//   - exit 0 to allow the response to stand
+//   - emit {"decision":"block","reason":"..."} on stdout to re-prompt
+//   - never block on internal failure (parse error, missing transcript,
+//     unexpected message shape) — fail open
+//
+// Heuristic: skip messages shorter than 600 chars. Pure clarifying replies
+// don't need the close; only substantive technical responses (work
+// summaries, plan responses, post-execution reports) get gated.
+//
+// Telemetry: best-effort JSONL line per gated invocation written to
+// ~/.claude/hook-telemetry/<project-hash>.jsonl. Never throws, never
+// blocks the response. No network. No transcript content recorded.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { platform } from "node:os";
+import { dirname, join } from "node:path";
+import { performance } from "node:perf_hooks";
+
+import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
+
+const MIN_LENGTH_TO_GATE = 600;
+
+const REQUIRED_SECTIONS = [
+  {
+    heading: "What has been done",
+    hint: "concrete summary of changes/findings from this turn",
+    pattern: /^#+ +What has been done(?:\s|$)/m,
+  },
+  {
+    heading: "What is next",
+    hint: "minimum 5 specific, actionable bullets",
+    pattern: /^#+ +What is next(?:\s|$)/m,
+  },
+  {
+    heading: "Recommendation",
+    hint: "ranked descending by impact, or write \"no\" if there is no recommendation",
+    pattern: /^#+ +Recommendation(?:\s|$)/m,
+  },
+];
+
+function readStdinSync() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function extractLastAssistantText(transcriptPath) {
+  const raw = readFileSync(transcriptPath, "utf8");
+  const lines = raw.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const obj = safeJsonParse(line);
+    if (!obj || obj.type !== "assistant") continue;
+    const blocks = obj.message?.content;
+    if (!Array.isArray(blocks)) continue;
+    const texts = blocks
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text);
+    if (texts.length === 0) continue;
+    return texts.join("\n");
+  }
+  return null;
+}
+
+function emitBlock(missing) {
+  const bullets = missing
+    .map(
+      (s) =>
+        `- "## ${s.heading}" — ${s.hint}`,
+    )
+    .join("\n");
+  const reason =
+    `Your reply is missing the required 3-section close. Add these sections at the end of the reply with these exact headings:\n${bullets}`;
+  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
+}
+
+function projectHashFor(transcriptPath) {
+  const dir = dirname(transcriptPath);
+  let normalized = dir.split("\\").join("/");
+  if (platform() === "win32") normalized = normalized.toLowerCase();
+  return createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+}
+
+function recordTelemetry(entry, transcriptPath) {
+  try {
+    const home = resolveHomeDir();
+    if (!home) return;
+    const telemetryDir = join(home, ".claude", "hook-telemetry");
+    try {
+      mkdirSync(telemetryDir, { recursive: true });
+    } catch {
+      return;
+    }
+    const file = join(telemetryDir, `${projectHashFor(transcriptPath)}.jsonl`);
+    try {
+      appendFileSync(file, JSON.stringify(entry) + "\n", "utf8");
+    } catch {
+      return;
+    }
+  } catch {
+    // belt-and-suspenders: telemetry must never throw
+  }
+}
+
+function main() {
+  // Per-operator opt-out. When CLAUDE_THREE_SECTION_CLOSE_DISABLED=1, the hook
+  // short-circuits entirely: no enforcement, no telemetry. Public default is
+  // unchanged (rule still fires for everyone else). See feedback memory
+  // 2026-05-04 for rationale: an audit found 22,876 observations produced
+  // only 2 graduated instincts, so visible end-of-turn reflection earns its
+  // keep poorly enough that operators may want to run it as internal thinking.
+  if (process.env.CLAUDE_THREE_SECTION_CLOSE_DISABLED === "1") return;
+  const startedAt = performance.now();
+  const stdin = readStdinSync();
+  if (!stdin) return;
+
+  const payload = safeJsonParse(stdin);
+  if (!payload || typeof payload.transcript_path !== "string") return;
+  if (!existsSync(payload.transcript_path)) return;
+
+  let lastText;
+  try {
+    lastText = extractLastAssistantText(payload.transcript_path);
+  } catch {
+    return; // fail open on read error
+  }
+  if (!lastText) return;
+
+  const textLength = lastText.length;
+  let action;
+  let missing = [];
+
+  if (textLength < MIN_LENGTH_TO_GATE) {
+    action = "skip-short";
+  } else {
+    missing = REQUIRED_SECTIONS.filter((s) => !s.pattern.test(lastText));
+    if (missing.length === 0) {
+      action = "pass";
+    } else {
+      action = "block";
+      emitBlock(missing);
+    }
+  }
+
+  const entry = {
+    ts: new Date().toISOString(),
+    hook: "three-section-close",
+    action,
+    textLength,
+    missing: missing.map((s) => s.heading),
+    durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
+  };
+  recordTelemetry(entry, payload.transcript_path);
+}
+
+try {
+  main();
+} catch {
+  // fail open — never block the session due to a hook bug
+}

package/instinct-packs/meta.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "skip-thin-observation-schema",
+    "trigger": "when running /continuous-improvement and observations.jsonl entries contain only tool_start events with no inputs/outputs/errors",
+    "body": "Skip instinct fabrication and report the schema gap instead. With only ts/event/session/tool/project_id/project_name fields, the stream cannot distinguish a `git status` Bash call from a `rm -rf` Bash call. Tool-name bigrams (Bash→Bash, Edit→Edit, Read→Edit) reflect parallel-call artifacts and harness-enforced read-before-edit, not learned preferences. Recommend enhancing PostToolUse/PreToolUse hooks to log tool inputs (Bash command head, Skill name) and tool_end with success flag before retrying analysis.",
+    "confidence": 0.6,
+    "domain": "meta"
+  },
+  {
+    "id": "parallelize-independent-tool-calls",
+    "trigger": "when issuing 2+ tool calls with no data dependency between them in the same turn",
+    "body": "Batch independent tool calls into a single message instead of issuing them sequentially. Independent reads, independent greps, independent git inspections, independent file edits in unrelated files belong in one message with multiple tool blocks. Dependent calls (output of A determines input of B) stay sequential. Exception: when a single check would short-circuit the whole task (e.g., `git status` returning empty), one call first is fine. Sequential issuing of independent calls wastes wall-clock time and burns context per round-trip.",
+    "confidence": 0.6,
+    "domain": "workflow"
+  }
+]

package/lib/cli-anything.mjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+/**
+ * CLI-Anything: Turn open-source software into agent-native CLIs.
+ *
+ * Analyzes a repository and generates an agent-friendly CLI wrapper that
+ * language models can drive automatically.
+ */
+import { existsSync } from "node:fs";
+import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const DEFAULT_OPTIONS = {
+    outputDir: "./generated-clis",
+    verbose: false,
+};
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export default class CLIAnything {
+    options;
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    async generateCLI(repoPath, options = {}) {
+        try {
+            this.log(`Analyzing repository: ${repoPath}`);
+            const repoInfo = await this.analyzeRepository(repoPath);
+            const commands = await this.extractCommands(repoPath, repoInfo);
+            const cliWrapper = await this.generateCLIWrapper(repoInfo, commands, options);
+            const outputPath = await this.saveCLI(repoInfo, cliWrapper);
+            this.log(`✅ CLI generated: ${outputPath}`);
+            return { outputPath, repoInfo, commands };
+        }
+        catch (error) {
+            throw new Error(`Failed to generate CLI: ${getErrorMessage(error)}`);
+        }
+    }
+    async analyzeRepository(repoPath) {
+        const packageJsonPath = join(repoPath, "package.json");
+        const readmePath = join(repoPath, "README.md");
+        let packageJson = {};
+        let readme = "";
+        try {
+            const packageContent = await readFile(packageJsonPath, "utf8");
+            packageJson = JSON.parse(packageContent);
+        }
+        catch {
+            // Not a Node.js project or no package.json.
+        }
+        try {
+            readme = await readFile(readmePath, "utf8");
+        }
+        catch {
+            // No README.
+        }
+        const projectType = this.detectProjectType(repoPath, packageJson);
+        const existingCLI = this.extractExistingCLI(packageJson);
+        const hasBin = !!packageJson.bin &&
+            (typeof packageJson.bin === "string" ||
+                Object.keys(packageJson.bin).length > 0);
+        return {
+            name: packageJson.name ?? this.extractRepoName(repoPath),
+            version: packageJson.version ?? "1.0.0",
+            description: packageJson.description ?? "",
+            projectType,
+            existingCLI,
+            hasBin,
+            scripts: packageJson.scripts ?? {},
+            dependencies: packageJson.dependencies ?? {},
+            readme,
+        };
+    }
+    detectProjectType(repoPath, packageJson) {
+        const { dependencies = {}, devDependencies = {} } = packageJson;
+        const allDeps = { ...dependencies, ...devDependencies };
+        if (allDeps.express || allDeps.koa || allDeps.fastify)
+            return "node-server";
+        if (allDeps.react || allDeps["react-dom"])
+            return "react-app";
+        if (allDeps.vue)
+            return "vue-app";
+        if (allDeps.angular)
+            return "angular-app";
+        if (allDeps.next)
+            return "next-app";
+        if (allDeps.gatsby)
+            return "gatsby-app";
+        if (allDeps.python || allDeps["python-shell"])
+            return "python-wrapper";
+        if (allDeps.docker || allDeps["dockerode"])
+            return "docker-tool";
+        if (existsSync(join(repoPath, "Dockerfile")))
+            return "docker-project";
+        if (existsSync(join(repoPath, "requirements.txt")) ||
+            existsSync(join(repoPath, "setup.py")) ||
+            existsSync(join(repoPath, "pyproject.toml"))) {
+            return "python-project";
+        }
+        if (existsSync(join(repoPath, "Cargo.toml")))
+            return "rust-project";
+        if (existsSync(join(repoPath, "go.mod")))
+            return "go-project";
+        return "generic";
+    }
+    extractExistingCLI(packageJson) {
+        const cli = {
+            bin: packageJson.bin ?? {},
+            scripts: {},
+            mainCommand: null,
+        };
+        if (packageJson.scripts) {
+            for (const [name, script] of Object.entries(packageJson.scripts)) {
+                if (name.includes("start") ||
+                    name.includes("build") ||
+                    name.includes("test") ||
+                    name.includes("dev") ||
+                    name.includes("serve") ||
+                    name.includes("run")) {
+                    cli.scripts[name] = script;
+                }
+            }
+        }
+        if (typeof cli.bin === "object") {
+            const keys = Object.keys(cli.bin);
+            if (keys.length > 0)
+                cli.mainCommand = keys[0] ?? null;
+        }
+        else if (typeof cli.bin === "string") {
+            cli.mainCommand = "main";
+        }
+        return cli;
+    }
+    async extractCommands(_repoPath, repoInfo) {
+        const commands = [];
+        for (const [name, script] of Object.entries(repoInfo.scripts)) {
+            commands.push({
+                type: "script",
+                name,
+                command: script,
+                description: this.generateScriptDescription(name),
+                category: this.categorizeScript(name),
+            });
+        }
+        const { bin } = repoInfo.existingCLI;
+        if (typeof bin === "object") {
+            for (const [name, path] of Object.entries(bin)) {
+                commands.push({
+                    type: "binary",
+                    name,
+                    path,
+                    description: `Execute ${name} command`,
+                    category: "core",
+                });
+            }
+        }
+        commands.push(...this.generateProjectTypeCommands(repoInfo));
+        return commands;
+    }
+    generateProjectTypeCommands(repoInfo) {
+        const commands = [];
+        switch (repoInfo.projectType) {
+            case "node-server":
+                commands.push({ type: "generated", name: "start", command: "npm start", description: "Start the server", category: "lifecycle" }, { type: "generated", name: "dev", command: "npm run dev", description: "Start in development mode", category: "development" }, { type: "generated", name: "test", command: "npm test", description: "Run tests", category: "testing" });
+                break;
+            case "react-app":
+            case "next-app":
+                commands.push({ type: "generated", name: "dev", command: "npm run dev", description: "Start development server", category: "development" }, { type: "generated", name: "build", command: "npm run build", description: "Build for production", category: "build" }, { type: "generated", name: "test", command: "npm test", description: "Run tests", category: "testing" }, { type: "generated", name: "lint", command: "npm run lint", description: "Run linting", category: "quality" });
+                break;
+            case "python-project":
+                commands.push({ type: "generated", name: "install", command: "pip install -r requirements.txt", description: "Install dependencies", category: "setup" }, { type: "generated", name: "run", command: "python main.py", description: "Run main script", category: "core" }, { type: "generated", name: "test", command: "python -m pytest", description: "Run tests", category: "testing" });
+                break;
+            case "docker-project":
+                commands.push({ type: "generated", name: "build", command: "docker build -t app .", description: "Build Docker image", category: "build" }, { type: "generated", name: "run", command: "docker run -p 3000:3000 app", description: "Run Docker container", category: "core" });
+                break;
+            default:
+                break;
+        }
+        return commands;
+    }
+    async generateCLIWrapper(repoInfo, commands, options = {}) {
+        const template = await this.getTemplate(options.template ?? "default");
+        const className = repoInfo.name.replace(/[^a-zA-Z0-9]/g, "");
+        return template
+            .replace(/{{NAME}}/g, className)
+            .replace(/{{VERSION}}/g, repoInfo.version)
+            .replace(/{{DESCRIPTION}}/g, repoInfo.description)
+            .replace(/{{COMMANDS}}/g, this.generateCommandsCode(commands))
+            .replace(/{{PROJECT_TYPE}}/g, repoInfo.projectType)
+            .replace(/{{REPO_INFO}}/g, JSON.stringify(repoInfo, null, 2));
+    }
+    generateCommandsCode(commands) {
+        const commandGroups = this.groupCommands(commands);
+        let code = "";
+        for (const [category, categoryCommands] of Object.entries(commandGroups)) {
+            code += `  // ${category.toUpperCase()} COMMANDS\n`;
+            for (const cmd of categoryCommands) {
+                const safeName = cmd.name.replace(/[^a-zA-Z0-9]/g, "_");
+                code += `  ${safeName}: {
+    description: '${cmd.description}',
+    execute: async (args = []) => {
+      return await this.runCommand('${cmd.command ?? ""}', args);
+    }
+  },\n`;
+            }
+            code += "\n";
+        }
+        return code.trim();
+    }
+    groupCommands(commands) {
+        return commands.reduce((groups, cmd) => {
+            const category = cmd.category || "general";
+            if (!groups[category])
+                groups[category] = [];
+            groups[category].push(cmd);
+            return groups;
+        }, {});
+    }
+    async getTemplate(templateName) {
+        const templates = {
+            default: `#!/usr/bin/env node
+
+/**
+ * Auto-generated CLI wrapper for {{NAME}}
+ * Generated by CLI-Anything tool
+ */
+
+import { spawn } from 'node:child_process';
+
+const repoInfo = {{REPO_INFO}};
+
+class {{NAME}}CLI {
+  constructor() {
+    this.commands = {
+{{COMMANDS}}
+    };
+  }
+
+  async runCommand(command, args = []) {
+    return new Promise((resolve, reject) => {
+      const process = spawn(command, args, {
+        stdio: 'inherit',
+        shell: true
+      });
+
+      process.on('close', (code) => {
+        if (code === 0) {
+          resolve({ success: true, code });
+        } else {
+          reject(new Error(\`Command failed with code \${code}\`));
+        }
+      });
+
+      process.on('error', reject);
+    });
+  }
+
+  async execute(commandName, args = []) {
+    if (!this.commands[commandName]) {
+      throw new Error(\`Unknown command: \${commandName}\`);
+    }
+
+    const command = this.commands[commandName];
+    console.log(\`Executing: \${command.description}\`);
+
+    try {
+      const result = await command.execute(args);
+      console.log(\`✅ \${command.description} completed successfully\`);
+      return result;
+    } catch (error) {
+      console.error(\`❌ \${command.description} failed:\`, error.message);
+      throw error;
+    }
+  }
+
+  listCommands() {
+    console.log('Available commands for {{NAME}}:');
+    Object.entries(this.commands).forEach(([name, cmd]) => {
+      console.log(\`  \${name.padEnd(15)} - \${cmd.description}\`);
+    });
+  }
+}
+
+if (import.meta.url === \`file://\${process.argv[1]}\`) {
+  const cli = new {{NAME}}CLI();
+  const [,, command, ...args] = process.argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    cli.listCommands();
+    process.exit(0);
+  }
+
+  cli.execute(command, args).catch(error => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+export default {{NAME}}CLI;`,
+        };
+        return templates[templateName] ?? templates.default;
+    }
+    async saveCLI(repoInfo, cliWrapper) {
+        const outputDir = this.options.outputDir;
+        const fileName = `${repoInfo.name.toLowerCase().replace(/[^a-z0-9]/g, "-")}-cli.mjs`;
+        const outputPath = join(outputDir, fileName);
+        try {
+            await access(outputDir);
+        }
+        catch {
+            await mkdir(outputDir, { recursive: true });
+        }
+        await writeFile(outputPath, cliWrapper, "utf8");
+        try {
+            await chmod(outputPath, 0o755);
+        }
+        catch {
+            // Ignore on Windows.
+        }
+        return outputPath;
+    }
+    extractRepoName(repoPath) {
+        const segments = repoPath.split(/[\\/]/);
+        const last = segments[segments.length - 1] ?? repoPath;
+        return last.replace(/[^a-zA-Z0-9]/g, "-");
+    }
+    generateScriptDescription(name) {
+        const descriptions = {
+            start: "Start the application",
+            dev: "Start in development mode",
+            build: "Build the application",
+            test: "Run tests",
+            lint: "Run linting",
+            serve: "Start the server",
+            deploy: "Deploy the application",
+        };
+        return descriptions[name] ?? `Execute script: ${name}`;
+    }
+    categorizeScript(name) {
+        if (["start", "dev", "serve"].includes(name))
+            return "lifecycle";
+        if (["build", "compile"].includes(name))
+            return "build";
+        if (["test", "spec"].includes(name))
+            return "testing";
+        if (["lint", "format", "type-check"].includes(name))
+            return "quality";
+        if (["deploy", "publish"].includes(name))
+            return "deployment";
+        return "general";
+    }
+    log(message) {
+        if (this.options.verbose) {
+            console.log(`[CLI-Anything] ${message}`);
+        }
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const [, , repoPath, ...args] = process.argv;
+    if (!repoPath || repoPath === "--help" || repoPath === "-h") {
+        console.log(`
+Usage: cli-anything <repository-path> [options]
+
+Options:
+  --output-dir <dir>    Output directory for generated CLIs (default: ./generated-clis)
+  --verbose             Enable verbose logging
+  --template <name>     Template to use (default: default)
+  --help                Show this help
+
+Examples:
+  cli-anything ./my-project
+  cli-anything ./my-project --output-dir ./tools --verbose
+`);
+        process.exit(0);
+    }
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (flag === "--output-dir" && args[i + 1]) {
+            options.outputDir = args[i + 1];
+            i++;
+        }
+        else if (flag === "--verbose") {
+            options.verbose = true;
+        }
+        else if (flag === "--template" && args[i + 1]) {
+            options.template = args[i + 1];
+            i++;
+        }
+    }
+    const cliAnything = new CLIAnything(options);
+    cliAnything
+        .generateCLI(repoPath, { template: options.template })
+        .then((result) => {
+        console.log(`✅ CLI generated successfully!`);
+        console.log(`📁 Output: ${result.outputPath}`);
+        console.log(`📊 Commands found: ${result.commands.length}`);
+    })
+        .catch((error) => {
+        console.error(`❌ Error: ${getErrorMessage(error)}`);
+        process.exit(1);
+    });
+}