chore: release v0.5.0 — host-agent review protocol + memory search [BETA]

Written by Minimax-M2.7 in Claude Code Harness.

- Bumps VERSION to 0.5.0 in onboard_render.py and the banner.
- README rewritten to cover the host-agent review protocol (CLI
  tools graduate / reject / reopen / list_candidates), the new
  structured lessons.jsonl source of truth, BETA FTS5 memory
  search, and Windows install path.
- Formula bumped to v0.5.0 tarball URL; sha256 placeholder gets
  updated in the follow-up commit once GitHub cuts the archive.
  install list now includes onboard_features.py; brew test
  asserts .features.json is written alongside PREFERENCES.md.
- install.ps1 (new): PowerShell installer parallel to install.sh,
  so Windows users don't need Git Bash / WSL. Same adapters,
  same wizard invocation, same flags (--yes / --reconfigure /
  --force via PowerShell switches).

Author: codejunkie99

Formula/agentic-stack.rb

@@ -1,16 +1,17 @@
 class AgenticStack < Formula
   desc "One brain, many harnesses — portable .agent/ folder for AI coding agents"
   homepage "https://github.com/codejunkie99/agentic-stack"
-  url "https://github.com/codejunkie99/agentic-stack/archive/refs/tags/v0.4.0.tar.gz"
-  sha256 "71367b277e2b91a241f7c0e37d491708b081104de0b6174e360234d5b5508270"
-  version "0.4.0"
+  url "https://github.com/codejunkie99/agentic-stack/archive/refs/tags/v0.5.0.tar.gz"
+  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
+  version "0.5.0"
   license "MIT"
 
   def install
     # install the brain + adapters alongside install.sh so relative paths hold
     pkgshare.install ".agent", "adapters", "install.sh",
                      "onboard.py", "onboard_ui.py", "onboard_widgets.py",
-                     "onboard_render.py", "onboard_write.py"
+                     "onboard_render.py", "onboard_write.py",
+                     "onboard_features.py"
 
     # wrapper so `agentic-stack cursor` works from anywhere
     (bin/"agentic-stack").write <<~EOS
@@ -22,9 +23,10 @@ def install
   test do
     output = shell_output("#{bin}/agentic-stack 2>&1", 2)
     assert_match "usage", output
-    # Wizard --yes must write PREFERENCES.md into a temp project dir
+    # Wizard --yes must write PREFERENCES.md AND .features.json into a temp project dir
     (testpath/".agent/memory/personal").mkpath
     system "#{bin}/agentic-stack", "claude-code", testpath.to_s, "--yes"
     assert_predicate testpath/".agent/memory/personal/PREFERENCES.md", :exist?
+    assert_predicate testpath/".agent/memory/.features.json", :exist?
   end
 end

README.md

@@ -1,13 +1,13 @@
 # agentic-stack
 
-Follow me on : [@AV1DLIVE](https://twitter.com/AV1DLIVE) for updates/collabs on projects
+Follow me on [@AV1DLIVE](https://twitter.com/AV1DLIVE) for updates/collabs on projects.
 
 [![GitHub release](https://img.shields.io/github/v/release/codejunkie99/agentic-stack)](https://github.com/codejunkie99/agentic-stack/releases)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 > **One brain, many harnesses.** A portable `.agent/` folder (memory + skills
 > + protocols) that plugs into Claude Code, Cursor, Windsurf, OpenCode,
-> OpenClient, Hermes, or a DIY Python loop — and keeps its knowledge when
+> OpenClient, Hermes, or a DIY Python loop, and keeps its knowledge when
 > you switch.
 
 <p align="center">
@@ -27,21 +27,47 @@ Based on the article:
 ## What this is
 
 Every guide shows the folder structure. This repo gives you the folder
-structure **plus the files that actually go inside** — a working portable
+structure **plus the files that actually go inside**: a working portable
 brain with five seed skills, four memory layers, enforced permissions, a
-nightly dream cycle, and adapters for seven harnesses.
+nightly staging cycle, host-agent review tools, and adapters for seven
+harnesses.
 
 - **Memory** — `working/`, `episodic/`, `semantic/`, `personal/`. Each
-  layer has its own retention policy. Salience-scored retrieval; nightly
-  compression.
-- **Skills** — progressive disclosure. A lightweight manifest always loads;
-  full `SKILL.md` files only load when triggers match the task. Every
-  skill ships with a self-rewrite hook.
+  layer has its own retention policy. Query-aware retrieval (salience ×
+  relevance); nightly compression into reviewable candidates.
+- **Review protocol** — `auto_dream.py` stages candidate lessons
+  mechanically. Your host agent reviews them via CLI tools
+  (`graduate.py`, `reject.py`, `reopen.py`) and commits decisions with
+  a required rationale. No unattended reasoning, no provider coupling.
+- **Skills** — progressive disclosure. A lightweight manifest always
+  loads; full `SKILL.md` files only load when triggers match the task.
+  Every skill ships with a self-rewrite hook.
 - **Protocols** — typed tool schemas, a `permissions.md` that the
   pre-tool-call hook enforces, and a delegation contract for sub-agents.
 
+## What's new in v0.5.0
+
+- **Host-agent review protocol.** Python handles filing (cluster, stage,
+  heuristic prefilter, decay). The host agent handles reasoning via
+  `list_candidates.py` / `graduate.py` / `reject.py` / `reopen.py`.
+  Graduation requires `--rationale` so rubber-stamping is structurally
+  impossible.
+- **Structured `lessons.jsonl` as source of truth.** `LESSONS.md` is
+  rendered from it. Hand-curated content above the sentinel is
+  preserved across renders; legacy bullets auto-migrate on first run.
+- **Content clustering.** Proper single-linkage Jaccard with bridge
+  merging. Pattern IDs derived from canonical claim + conditions, stable
+  across cluster-membership changes.
+- **[BETA] FTS5 memory search.** Opt-in full-text search over all
+  `.md` / `.jsonl` memory documents. Default **off**; enable during
+  onboarding or edit `.agent/memory/.features.json` directly.
+- **Windows-native installer.** `install.ps1` runs natively in
+  PowerShell; `install.sh` continues to work under Git Bash / WSL.
+
 ## Quickstart
 
+### macOS / Linux
+
 ```bash
 # tap + install (one-time — both lines required)
 brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
@@ -53,24 +79,37 @@ agentic-stack claude-code
 # or: cursor | windsurf | opencode | openclient | hermes | standalone-python
 ```
 
-> **Already installed? Update to the latest version:**
-> ```bash
-> brew update && brew upgrade agentic-stack
-> ```
+### Windows (PowerShell)
+
+```powershell
+# clone + run the native installer
+git clone https://github.com/codejunkie99/agentic-stack.git
+cd agentic-stack
+.\install.ps1 claude-code C:\path\to\your-project
+```
+
+### Already installed?
+
+```bash
+brew update && brew upgrade agentic-stack
+```
+
+### Clone instead?
 
-> **Clone instead?**
-> ```bash
-> git clone https://github.com/codejunkie99/agentic-stack.git
-> cd agentic-stack && ./install.sh claude-code
-> ```
+```bash
+git clone https://github.com/codejunkie99/agentic-stack.git
+cd agentic-stack && ./install.sh claude-code         # mac / linux / git-bash
+# or on Windows PowerShell: .\install.ps1 claude-code
+```
 
 ## Onboarding wizard
 
-After the adapter is installed, a colorful terminal wizard runs automatically
-and populates `.agent/memory/personal/PREFERENCES.md` — the **first file your
-AI reads at the start of every session**.
+After the adapter is installed, a terminal wizard populates
+`.agent/memory/personal/PREFERENCES.md` — the **first file your AI reads
+at the start of every session** — and writes a feature-toggle file at
+`.agent/memory/.features.json`.
 
-It asks six questions with arrow-key selection, each skippable with Enter:
+Six preference questions (each skippable with Enter):
 
 | Question | Default |
 |---|---|
@@ -81,40 +120,99 @@ It asks six questions with arrow-key selection, each skippable with Enter:
 | Commit message style? | `conventional commits` |
 | Code review depth? | `critical issues only` |
 
+Plus one **Optional features** step (opt-in, off by default):
+
+| Feature | Default |
+|---|---|
+| Enable FTS memory search `[BETA]` | `no` |
+
 **Flags:**
 
 ```bash
-agentic-stack claude-code --yes          # accept all defaults silently (CI / scripted)
+agentic-stack claude-code --yes          # accept all defaults, beta off (CI/scripted)
 agentic-stack claude-code --reconfigure  # re-run the wizard on an existing project
 ```
 
-Edit `.agent/memory/personal/PREFERENCES.md` any time to add or refine your
-conventions — the agent re-reads it fresh every session.
+Edit `.agent/memory/personal/PREFERENCES.md` any time to refine your
+conventions, or `.agent/memory/.features.json` to flip feature toggles.
+
+## Review protocol (host-agent CLI)
+
+The nightly `auto_dream.py` cycle only **stages** candidate lessons. It
+does not mark anything accepted or modify semantic memory. Your host
+agent does the review in-session:
+
+```bash
+# list pending candidates, sorted by priority
+python3 .agent/tools/list_candidates.py
+
+# accept with rationale (required)
+python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"
+
+# reject with reason (required); preserves decision history
+python3 .agent/tools/reject.py <id> --reason "too specific to generalize"
+
+# requeue a previously-rejected candidate
+python3 .agent/tools/reopen.py <id>
+```
+
+Graduated lessons land in `semantic/lessons.jsonl` (source of truth) and
+are rendered to `semantic/LESSONS.md`. Rejected candidates retain full
+decision history so recurring churn is visible, not fresh.
+
+See [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.
+
+## Memory search `[BETA]`
+
+Opt-in FTS5 keyword search over all memory documents:
+
+```bash
+# enable during onboarding (or set manually in .agent/memory/.features.json)
+python3 .agent/memory/memory_search.py "deploy failure"
+python3 .agent/memory/memory_search.py --status
+python3 .agent/memory/memory_search.py --rebuild
+```
+
+Falls back to `grep` (restricted to `.md` / `.jsonl`) when SQLite FTS5
+isn't available. The index is stored at `.agent/memory/.index/` and
+gitignored.
 
 ## Repo layout
 
 ```
-.agent/                         # the portable brain (same across all harnesses)
+.agent/                         # the portable brain (same across harnesses)
 ├── AGENTS.md                   # the map
-├── harness/                    # dumb conductor + hooks (standalone path)
+├── harness/                    # conductor + hooks (standalone path)
 ├── memory/                     # working / episodic / semantic / personal
+│   ├── auto_dream.py           # staging-only dream cycle
+│   ├── cluster.py              # content clustering + pattern extraction
+│   ├── promote.py              # stage candidates
+│   ├── validate.py             # heuristic prefilter (length + exact duplicate)
+│   ├── review_state.py         # candidate lifecycle + decision log
+│   ├── render_lessons.py       # lessons.jsonl → LESSONS.md
+│   └── memory_search.py        # [BETA] FTS5 search (opt-in)
 ├── skills/                     # _index.md + _manifest.jsonl + SKILL.md files
 ├── protocols/                  # permissions + tool schemas + delegation
-└── tools/                      # skill loader, memory reflect, budget tracker
+└── tools/                      # host-agent CLI + memory_reflect + skill_loader
+    ├── list_candidates.py
+    ├── graduate.py
+    ├── reject.py
+    └── reopen.py
 
 adapters/                       # one small shim per harness
 ├── claude-code/   (CLAUDE.md + settings.json hooks)
 ├── cursor/        (.cursor/rules/*.mdc)
 ├── windsurf/      (.windsurfrules)
 ├── opencode/      (AGENTS.md + opencode.json)
 ├── openclient/    (system-prompt include)
-├── hermes/       (AGENTS.md)
+├── hermes/        (AGENTS.md)
 └── standalone-python/  (DIY conductor entrypoint)
 
 docs/                           # architecture, getting-started, per-harness
-examples/                       # minimal first_run.py
-install.sh                      # one-command adapter install + wizard trigger
+install.sh                      # mac / linux / git-bash installer
+install.ps1                     # Windows PowerShell installer
 onboard.py                      # onboarding wizard entry point
+onboard_features.py             # .features.json read/write
 onboard_ui.py                   # ANSI palette, banner, clack-style layout
 onboard_widgets.py              # arrow-key prompts (text, select, confirm)
 onboard_render.py               # answers → PREFERENCES.md content
@@ -136,29 +234,31 @@ onboard_write.py                # atomic file write with backup
 ## Seed skills
 
 - **skillforge** — creates new skills from recurring patterns
-- **memory-manager** — runs reflection cycles, promotes lessons
+- **memory-manager** — runs reflection cycles, surfaces candidate lessons
 - **git-proxy** — all git ops, with safety constraints
 - **debug-investigator** — reproduce → isolate → hypothesize → verify
 - **deploy-checklist** — the fence between staging and production
 
 ## How it compounds
 
 1. Skills log every action to episodic memory.
-2. `memory-manager` detects recurring patterns, promotes them to semantic.
-3. `on_failure` flags skills that fail 3+ times in 14 days for rewrite.
-4. Self-rewrite hooks on each skill update `KNOWLEDGE.md` conservatively.
-5. `git log .agent/memory/` becomes the agent's autobiography.
-
-See [`docs/architecture.md`](docs/architecture.md) for the full picture.
+2. `auto_dream.py` clusters recurring patterns into candidate lessons.
+3. The host agent reviews candidates with `graduate.py` / `reject.py`.
+4. Graduated lessons append to `lessons.jsonl`; `LESSONS.md` re-renders.
+5. Future sessions load query-relevant accepted lessons automatically.
+6. `on_failure` flags skills that fail 3+ times in 14 days for rewrite.
+7. `git log .agent/memory/` becomes the agent's autobiography.
 
-## Run the dream cycle nightly
+## Run the staging cycle nightly
 
 ```bash
 crontab -e
 0 3 * * * python3 /path/to/project/.agent/memory/auto_dream.py >> /path/to/project/.agent/memory/dream.log 2>&1
 ```
 
-`auto_dream.py` resolves its own paths absolutely, so no `cd` is needed — cron runs it correctly regardless of working directory.
+`auto_dream.py` resolves its paths absolutely and performs only mechanical
+file operations (cluster, stage, prefilter, decay). No git commits, no
+network, no reasoning — safe to run unattended.
 
 ## License