compound-agent 2.5.2 → 2.6.0

package/CHANGELOG.md

@@ -9,6 +9,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-04-01
+
+### Added
+
+- **`--compact-pct` flag** for `ca loop`, `ca improve`, and `ca polish`: Sets `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` in generated scripts to trigger context compaction earlier during autonomous workflows. Default 0 (use Claude Code default). Suggested value: 50 for Opus 1M sessions. Only affects generated scripts, not interactive sessions. Validates range 0-100.
+- **Windows Native Support**: Native Windows binaries (amd64 + arm64) distributed via npm. Pure-Go SQLite driver eliminates CGO requirement. Real `LockFileEx`/`UnlockFileEx` file locking, `OpenProcess`/`GetExitCodeProcess` process detection, and `cmd /c start` URL opening with command injection prevention. Search gracefully degrades to keyword-only FTS5 (embed daemon is Unix-only). CI matrix includes `windows-latest`.
+- **Self-Explaining System (`ca info`)** (Epic 4): New CLI command displaying comprehensive system health — version, hooks, skills, phase state, telemetry, and lesson corpus stats. 13 tests.
+- **Skill Phase Metadata** (Epic 3): Structured `phase` field in YAML frontmatter of all SKILL.md files with pre-compiled `skills_index.json` for fast runtime skill lookup. Phase guard uses `ResolveSkillPath` for phase-aware routing.
+- **Telemetry Foundation** (Epic 2): Schema v7 with telemetry table, `ca health` command, file-based lock for concurrent access, and hook execution instrumentation.
+- **V3.0 Harness Overhaul Specification**: Spec and advisory brief for upcoming harness overhaul.
+- **GOTCHA.md for architect skill**: Documented common pitfalls for architect workflows.
+
+### Changed
+
+- **SQLite driver**: Replaced `mattn/go-sqlite3` (CGO) with `modernc.org/sqlite` (pure Go). Enables `CGO_ENABLED=0` builds and Windows cross-compilation. DSN format uses `_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)`. FTS5 included by default — no build tags required.
+- **Build pipeline**: All builds now use `CGO_ENABLED=0`. Removed `-tags sqlite_fts5` from Makefile, CI, GoReleaser, and lint config. Added `windows-amd64` and `windows-arm64` targets to GoReleaser, CI matrix, and Makefile.
+- **npm distribution**: Added `@syottos/win32-x64` and `@syottos/win32-arm64` platform packages. Updated `bin/ca` wrapper, `postinstall.cjs`, and `publish-platforms.cjs` for `.exe` handling and embed daemon exclusion on Windows.
+
+### Fixed
+
+- **Documentation inaccuracies** (Epic 1): Fixed TypeScript/npm references across docs and templates, corrected hook counts, rewrote README with Mermaid diagram, added WSL2 doctor check.
+- **Screen session name collisions**: Unique session names using `compound-loop-$(basename $(pwd))` pattern to avoid host-level collisions (PR #10).
+- **6 golangci-lint violations**: gofmt alignment in map literals, extracted `checkHooks`/`printDoctorResults` helpers to reduce cyclop/funlen, handled `flockUnlock` error return.
+- **Review findings**: Multiple rounds of P0-P3 fixes from external reviewers across Epics 1-4.
+- **Command injection in `openURL`**: Windows `cmd /c start` now validates URL scheme (`http://`/`https://` only) and uses `exec.Command` argument splitting to prevent shell metacharacter injection.
+
+### Dependencies
+
+- **modernc.org/sqlite**: v1.48.0 — pure-Go SQLite driver replacing mattn/go-sqlite3 (CGO). Enables Windows native builds.
+- **golang.org/x/sys**: v0.42.0 — Windows `LockFileEx`/`UnlockFileEx` and process APIs.
+- **thiserror**: 1.0.69 to 2.0.18 in Rust embed daemon — major version bump with no-std support and improved diagnostics (PR #8).
+- **tokenizers**: 0.21.4 to 0.22.2 in Rust embed daemon — PyO3 0.26, faster vocab loading, GIL-free (PR #7).
+
 ## [2.5.2] - 2026-03-31
 
 ### Added

package/README.md

@@ -14,12 +14,12 @@ AI coding agents forget everything between sessions. Each session starts with wh
 
 ## What gets installed
 
-`npx ca setup` injects a complete development environment into your repository:
+`ca setup` injects a complete development environment into your repository:
 
 | Component | What ships |
 |-----------|-----------|
-| 15 slash commands | `/compound:architect`, `cook-it`, `spec-dev`, `plan`, `work`, `review`, `compound`, `learn-that`, `check-that`, and more |
-| 24 agent role skills | Security reviewers, TDD pair, decomposition convoy, spec writers, test analysers, drift detectors, and more |
+| 16 slash commands | `/compound:architect`, `cook-it`, `spec-dev`, `plan`, `work`, `review`, `compound`, `learn-that`, `check-that`, and more |
+| 26 agent role skills | TDD pair, drift detector, audit, research specialist, external reviewers, and more |
 | 7 automatic hooks | Fire on session start, prompt submit, tool use, tool failure, pre-compact, phase guard, and session stop |
 | 5 phase skill files | Full workflow instructions for `architect`, `spec-dev`, `cook-it`, `work`, and `review` |
 | 5 deployed docs | Workflow reference, CLI reference, skills guide, integration guide, and overview |
@@ -202,9 +202,9 @@ Once installed, seven Claude Code hooks fire without any commands:
 | `PreToolUse` | During cook-it | Enforces phase gates — prevents jumping ahead |
 | `PostToolUse` | After tool success | Clears failure tracking state |
 | `PostToolUseFailure` | After tool failure | Tracks failures; suggests memory search after repeated errors |
-| `Stop` | Session end | Audits session for uncaptured lessons and unclosed issues |
+| `Stop` | Session end | Enforces phase gates — prevents skipping required steps |
 
-No configuration needed. `npx ca setup` wires them into your `.claude/settings.json`.
+No configuration needed. `ca setup` wires them into your `.claude/settings.json`.
 
 ## `/compound:architect`
 
@@ -235,25 +235,20 @@ npx ca setup
 
 ### Requirements
 
-- Node.js >= 20
+- Node.js >= 20 (for `npx` wrapper — the CLI itself is a Go binary)
 - ~278MB disk space for the embedding model (one-time download, shared across projects)
-- ~23MB RAM during embedding operations (nomic-embed-text-v1.5 via Transformers.js)
+- Embedding runs via `ca-embed` Rust daemon (nomic-embed-text-v1.5 ONNX)
 
-### pnpm Users
+### Windows Users
 
-pnpm v9+ blocks native addon builds by default. Running `npx ca setup` automatically detects pnpm and adds the required config to your `package.json`.
+Compound-agent runs natively on Windows (amd64 and arm64). Install and use it the same way as on macOS/Linux:
 
-If you prefer to configure manually, add to your `package.json`:
-
-```json
-{
-  "pnpm": {
-    "onlyBuiltDependencies": ["better-sqlite3", "onnxruntime-node"]
-  }
-}
+```bash
+pnpm add -D compound-agent
+npx ca setup
 ```
 
-Then run `pnpm install`.
+**Note**: The embedding daemon (`ca-embed`) is not available on Windows. Search automatically falls back to keyword-only mode (FTS5). All other features work identically. WSL2 users get full functionality including vector search.
 
 ## CLI Reference
 
@@ -380,16 +375,16 @@ confirmation_boost: confirmed=1.3, unconfirmed=1.0
 A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first with git-tracked storage and local embeddings — no API keys or cloud services needed. It also goes beyond memory with structured workflows, multi-agent review, and issue tracking.
 
 **Q: Does this work offline?**
-A: Yes, completely. Embeddings run locally via @huggingface/transformers (Transformers.js). No network requests after the initial model download.
+A: Yes, completely. Embeddings run locally via the `ca-embed` Rust daemon (nomic-embed-text-v1.5 ONNX). No network requests after the initial model download.
 
 **Q: How much disk space does it need?**
 A: ~278MB for the embedding model (one-time download, shared across projects) plus negligible space for lessons.
 
 **Q: Can I use it with other AI coding tools?**
-A: The CLI (`ca`) works standalone with any tool. Full hook integration is available for Claude Code and Gemini CLI. The TypeScript API can be integrated into other tools.
+A: The CLI (`ca`) works standalone with any tool. Full hook integration is available for Claude Code and Gemini CLI.
 
 **Q: What happens if the embedding model isn't available?**
-A: Search gracefully falls back to keyword-only mode. Other commands that require embeddings will tell you what's missing. Run `npx ca doctor` to diagnose issues.
+A: Search gracefully falls back to keyword-only mode. Other commands that require embeddings will tell you what's missing. Run `ca doctor` to diagnose issues.
 
 **Q: Is the loop production-ready?**
 A: The loop works and has been used to ship real projects, including compound-agent itself. Long-duration autonomous runs across many epics are the current area of hardening. For 3–5 epic sequences, it is reliable today.
@@ -397,9 +392,9 @@ A: The loop works and has been used to ship real projects, including compound-ag
 ## Development
 
 ```bash
-cd go && go build -tags sqlite_fts5 ./cmd/ca   # Build CLI binary
-cd go && go test -tags sqlite_fts5 ./...        # Full test suite
-cd go && go vet -tags sqlite_fts5 ./...         # Static analysis
+cd go && go build ./cmd/ca   # Build CLI binary
+cd go && go test ./...       # Full test suite
+cd go && go vet ./...        # Static analysis
 ```
 
 ## Technology Stack
@@ -408,14 +403,56 @@ cd go && go vet -tags sqlite_fts5 ./...         # Static analysis
 |-----------|------------|
 | Language | Go |
 | Package Manager | Go modules (+ pnpm for npm wrapper) |
-| Build | go build with CGO + sqlite_fts5 tag |
+| Build | go build with CGO_ENABLED=0 (pure Go) |
 | Testing | go test + table-driven tests |
-| Storage | mattn/go-sqlite3 + FTS5 |
+| Storage | modernc.org/sqlite + FTS5 (pure Go, no CGO) |
 | Embeddings | ca-embed (Rust daemon via IPC) |
 | CLI | Cobra |
 | Release | GoReleaser |
 | Issue Tracking | Beads (bd) |
 
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "Claude Code Session"
+        H[Hooks] -->|SessionStart| P[ca prime]
+        H -->|UserPromptSubmit| UP[user-prompt hook]
+        H -->|PostToolUseFailure| TF[failure tracker]
+        H -->|PreToolUse| PG[phase guard]
+        H -->|Stop| SA[stop audit]
+    end
+
+    subgraph "CLI (Go + Cobra)"
+        CA[ca binary] --> LEARN[ca learn]
+        CA --> SEARCH[ca search]
+        CA --> LOOP[ca loop]
+        CA --> SETUP[ca setup]
+        CA --> DOCTOR[ca doctor]
+    end
+
+    subgraph "Storage"
+        JSONL[".claude/lessons/index.jsonl<br/>(git-tracked source of truth)"]
+        SQLITE[".claude/.cache/lessons.sqlite<br/>(FTS5 search index)"]
+        JSONL -->|rebuild| SQLITE
+    end
+
+    subgraph "Embeddings"
+        EMBED["ca-embed (Rust daemon)"] -->|IPC via Unix socket| VEC[Vector similarity]
+    end
+
+    UP -->|inject lessons| SEARCH
+    TF -->|suggest search| SEARCH
+    LEARN --> JSONL
+    SEARCH --> SQLITE
+    SEARCH --> VEC
+```
+
+Three layers work together:
+- **Portable storage**: JSONL in git for conflict-free collaboration
+- **Fast index**: SQLite + FTS5 for keyword search, rebuilt from JSONL on demand
+- **Semantic search**: Rust embedding daemon for vector similarity, falls back to keyword-only if unavailable
+
 ## Documentation
 
 | Document | Purpose |
@@ -447,4 +484,4 @@ Bug reports and feature requests are welcome via [Issues](https://github.com/Nat
 
 MIT — see [LICENSE](LICENSE) for details.
 
-> The embedding model (EmbeddingGemma-300M) is downloaded on-demand and subject to Google's [Gemma Terms of Use](https://ai.google.dev/gemma/terms). See [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) for full dependency license information.
+> The embedding model (nomic-embed-text-v1.5) is downloaded on-demand from Hugging Face under the Apache 2.0 license. See [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) for full dependency license information.

package/bin/ca

@@ -19,9 +19,10 @@ const require = createRequire(import.meta.url);
 
 function resolvePlatformBinary() {
   const pkg = `@syottos/${process.platform}-${process.arch}`;
+  const ext = process.platform === "win32" ? ".exe" : "";
   try {
     const pkgDir = dirname(require.resolve(`${pkg}/package.json`));
-    const bin = resolve(pkgDir, "bin", "ca");
+    const bin = resolve(pkgDir, "bin", `ca${ext}`);
     if (existsSync(bin)) return bin;
   } catch {
     // Platform package not installed
@@ -30,11 +31,12 @@ function resolvePlatformBinary() {
 }
 
 function findBinary() {
+  const ext = process.platform === "win32" ? ".exe" : "";
   const candidates = [
     process.env.CA_BINARY_PATH,
     resolvePlatformBinary(),
-    resolve(__dirname, "ca-binary"),
-    resolve(__dirname, "..", "go", "dist", "ca"),
+    resolve(__dirname, `ca-binary${ext}`),
+    resolve(__dirname, "..", "go", "dist", `ca${ext}`),
   ].filter(Boolean);
 
   return candidates.find((p) => existsSync(p)) || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-agent",
-  "version": "2.5.2",
+  "version": "2.6.0",
   "type": "module",
   "description": "Learning system for Claude Code — avoids repeating mistakes across sessions",
   "bin": {
@@ -21,7 +21,8 @@
   ],
   "os": [
     "darwin",
-    "linux"
+    "linux",
+    "win32"
   ],
   "cpu": [
     "x64",
@@ -50,10 +51,12 @@
     "knowledge-management"
   ],
   "optionalDependencies": {
-    "@syottos/darwin-arm64": "2.5.2",
-    "@syottos/darwin-x64": "2.5.2",
-    "@syottos/linux-arm64": "2.5.2",
-    "@syottos/linux-x64": "2.5.2"
+    "@syottos/darwin-arm64": "2.6.0",
+    "@syottos/darwin-x64": "2.6.0",
+    "@syottos/linux-arm64": "2.6.0",
+    "@syottos/linux-x64": "2.6.0",
+    "@syottos/win32-x64": "2.6.0",
+    "@syottos/win32-arm64": "2.6.0"
   },
   "author": "Nathan Delacrétaz",
   "license": "MIT",

package/scripts/postinstall.cjs

@@ -12,7 +12,7 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 const { createHash } = require("crypto");
 
-const PLATFORM_MAP = { darwin: "darwin", linux: "linux" };
+const PLATFORM_MAP = { darwin: "darwin", linux: "linux", win32: "windows" };
 const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
 const REPO = "Nathandela/compound-agent";
 
@@ -21,7 +21,7 @@ function getPlatformKey(platform, arch) {
   const a = ARCH_MAP[arch];
   if (!p || !a) {
     throw new Error(
-      `Unsupported platform: ${platform}-${arch}. Supported: darwin-amd64, darwin-arm64, linux-amd64, linux-arm64`
+      `Unsupported platform: ${platform}-${arch}. Supported: darwin-amd64, darwin-arm64, linux-amd64, linux-arm64, windows-amd64, windows-arm64`
     );
   }
   return `${p}-${a}`;
@@ -51,12 +51,13 @@ function verifyChecksum(filePath, artifactName, checksumsPath) {
 }
 
 function shouldSkipDownload(binDir, expectedVersion) {
-  const caPath = path.join(binDir, "ca-binary");
+  const isWindows = require("os").platform() === "win32";
+  const caPath = path.join(binDir, isWindows ? "ca-binary.exe" : "ca-binary");
   const embedPath = path.join(binDir, "ca-embed");
 
-  if (!fs.existsSync(caPath) || !fs.existsSync(embedPath)) {
-    return false;
-  }
+  if (!fs.existsSync(caPath)) return false;
+  // ca-embed is not available on Windows — only require it on Unix
+  if (!isWindows && !fs.existsSync(embedPath)) return false;
 
   try {
     const output = execFileSync(caPath, ["version"], { stdio: "pipe", encoding: "utf-8" });
@@ -133,16 +134,21 @@ async function downloadBinary(binDir, url, destName, label) {
 }
 
 function cleanupBinaries(binDir) {
-  for (const name of ["ca-binary", "ca-binary.tmp", "ca-embed", "ca-embed.tmp", "checksums.txt"]) {
+  for (const name of [
+    "ca-binary", "ca-binary.tmp", "ca-binary.exe", "ca-binary.exe.tmp",
+    "ca-embed", "ca-embed.tmp", "checksums.txt",
+  ]) {
     try { fs.unlinkSync(path.join(binDir, name)); } catch { /* ignore */ }
   }
 }
 
 function platformPackageInstalled() {
-  const pkg = `@syottos/${require("os").platform()}-${require("os").arch()}`;
+  const platform = require("os").platform();
+  const pkg = `@syottos/${platform}-${require("os").arch()}`;
+  const ext = platform === "win32" ? ".exe" : "";
   try {
     const pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
-    return fs.existsSync(path.join(pkgDir, "bin", "ca"));
+    return fs.existsSync(path.join(pkgDir, "bin", `ca${ext}`));
   } catch {
     return false;
   }
@@ -187,20 +193,34 @@ async function main() {
     const checksumsPath = path.join(binDir, "checksums.txt");
     await downloadFile(`${baseUrl}/checksums.txt`, checksumsPath);
 
-    // Download both binaries in parallel (to .tmp names)
-    const caArtifact = `ca-${platformKey}`;
-    // No x86_64 macOS embed build (ort-sys limitation) — use arm64 via Rosetta
-    const embedKey = platformKey === "darwin-amd64" ? "darwin-arm64" : platformKey;
-    const embedArtifact = `ca-embed-${embedKey}`;
+    // Download binaries in parallel (to .tmp names)
+    const isWindows = require("os").platform() === "win32";
+    const caExt = isWindows ? ".exe" : "";
+    const caArtifact = `ca-${platformKey}${caExt}`;
+
+    const downloads = [
+      downloadBinary(binDir, `${baseUrl}/${caArtifact}`, `ca-binary${caExt}`, "CLI binary"),
+    ];
+
+    // ca-embed is not available on Windows
+    let embedArtifact = null;
+    if (!isWindows) {
+      // No x86_64 macOS embed build (ort-sys limitation) — use arm64 via Rosetta
+      const embedKey = platformKey === "darwin-amd64" ? "darwin-arm64" : platformKey;
+      embedArtifact = `ca-embed-${embedKey}`;
+      downloads.push(
+        downloadBinary(binDir, `${baseUrl}/${embedArtifact}`, "ca-embed", "Embed daemon"),
+      );
+    }
 
-    await Promise.all([
-      downloadBinary(binDir, `${baseUrl}/${caArtifact}`, "ca-binary", "CLI binary"),
-      downloadBinary(binDir, `${baseUrl}/${embedArtifact}`, "ca-embed", "Embed daemon"),
-    ]);
+    await Promise.all(downloads);
 
     // Verify checksums against .tmp files
-    const caOk = verifyChecksum(path.join(binDir, "ca-binary.tmp"), caArtifact, checksumsPath);
-    const embedOk = verifyChecksum(path.join(binDir, "ca-embed.tmp"), embedArtifact, checksumsPath);
+    const caOk = verifyChecksum(path.join(binDir, `ca-binary${caExt}.tmp`), caArtifact, checksumsPath);
+    let embedOk = true;
+    if (embedArtifact) {
+      embedOk = verifyChecksum(path.join(binDir, "ca-embed.tmp"), embedArtifact, checksumsPath);
+    }
 
     if (!caOk || !embedOk) {
       const failed = [];
@@ -214,14 +234,17 @@ async function main() {
     console.log("[compound-agent] Checksums verified");
 
     // Checksums passed — rename .tmp to final names and set executable
-    fs.renameSync(path.join(binDir, "ca-binary.tmp"), path.join(binDir, "ca-binary"));
-    fs.chmodSync(path.join(binDir, "ca-binary"), 0o755);
-    fs.renameSync(path.join(binDir, "ca-embed.tmp"), path.join(binDir, "ca-embed"));
-    fs.chmodSync(path.join(binDir, "ca-embed"), 0o755);
+    const caFinal = path.join(binDir, `ca-binary${caExt}`);
+    fs.renameSync(path.join(binDir, `ca-binary${caExt}.tmp`), caFinal);
+    fs.chmodSync(caFinal, 0o755);
+    if (embedArtifact) {
+      fs.renameSync(path.join(binDir, "ca-embed.tmp"), path.join(binDir, "ca-embed"));
+      fs.chmodSync(path.join(binDir, "ca-embed"), 0o755);
+    }
 
     // Functional verification (P1-2 fix: use execFileSync)
     try {
-      execFileSync(path.join(binDir, "ca-binary"), ["version"], { stdio: "pipe" });
+      execFileSync(caFinal, ["version"], { stdio: "pipe" });
       console.log("[compound-agent] Functional check passed");
     } catch {
       cleanupBinaries(binDir);