livepilot 1.21.2 → 1.21.4

package/CHANGELOG.md

@@ -1,5 +1,239 @@
 # Changelog
 
+## 1.21.4 — v1.21.2 audit carry-over: slashed-compound filler + dev-install runbook (April 25 2026)
+
+Ships two items the v1.21.2 audit #2 deferred to v1.22 but that turned
+out to be safer to close in a patch cycle than to carry forward:
+
+1. **`check_prose_claim` regex widen for slashed/chained compound fillers** —
+   `"38 spectral/analyzer tools"` drift across 3 docs silently passed
+   `sync_metadata --check` because the filler group required trailing
+   whitespace. Now caught.
+2. **Dev-install runbook** (`docs/manual/dev-install.md`) — documented
+   path for contributors to run LivePilot from a local checkout without
+   publishing to npm. Previously every contributor had to reverse-engineer
+   this from `bin/livepilot.js` + `mcp_server/__main__.py`.
+
+No API changes. No user-observable behavior change at runtime. Four new
+TDD regression tests for the regex widening; ~180 lines of new
+documentation. `sync_metadata --check` now catches an entire class of
+compound-form drift that would otherwise have shipped untracked.
+
+### 1. `sync_metadata` slashed/chained compound filler
+
+All 4 regex patterns in `scripts/sync_metadata.py` (`check_tool_count`,
+`check_prose_claim`, `fix_tool_count`, `_fix_count`) had an optional
+filler group that required trailing whitespace —
+`[A-Za-z]+\s+` — and matched at most once (`?` quantifier). Slashed
+compounds like `"spectral/analyzer"` were rejected because `/` is not
+whitespace; chained compounds like `"spectral/MCP tools"` (two filler
+segments) were rejected because of the single-match quantifier.
+
+v1.21.4 widens the filler to two branches, iterable 0+ times:
+
+| Branch | Pattern | Matches |
+|---|---|---|
+| (a) Space-joined, uppercase-anchored | `[A-Z][A-Za-z\-]*\s+` | `"MCP "` in `"430 MCP Tools"` |
+| (b) Slash-joined, any-case | `[A-Za-z][A-Za-z\-]*/` | `"spectral/"` in `"38 spectral/analyzer tools"` |
+
+The uppercase anchor on branch (a) is preserved deliberately — without
+it, lowercase English articles ("the tool") would false-positive on
+prose like "released in 2020 the tool was first previewed." The slash
+on branch (b) is itself an unambiguous compound marker that doesn't
+appear in normal English, so any-case there is safe. The `*` quantifier
+lets branches chain: `"300 spectral/MCP tools"` now parses as
+`(b)"spectral/"` + `(a)"MCP "` + `"tools"`.
+
+For `check_prose_claim` + its paired `_fix_count`, the filler is a
+simpler single-branch `[A-Za-z][A-Za-z\-]*(?:/|\s+)` — these don't need
+the uppercase anchor (prose-claim nouns predate the v1.21.4 cycle and
+already allowed lowercase-start fillers).
+
+**Concrete effect**: `sync_metadata --check` now flags drift in all 3
+real surfaces that previously escaped:
+
+- `README.md` — `"38 spectral/analyzer tools"` × 2
+- `docs/manual/getting-started.md` — `"38 spectral/analyzer tools"` × 1
+- `livepilot/skills/livepilot-release/SKILL.md` — `"38 spectral/analyzer tools"` × 1
+
+(Today these say "38" and the count is 38, so no drift reported — but
+the next time the analyzer module gains or loses a `@mcp.tool`, CI will
+fail loudly instead of silently drifting.)
+
+Tests added to `tests/test_claim_consistency.py` (4):
+
+- `test_prose_claim_catches_slashed_compound` — drift detection
+- `test_fix_count_rewrites_slashed_compound` — `--fix` preserves the adjective
+- `test_tool_count_catches_slashed_compound` — chained filler (`"300 spectral/MCP tools"`)
+- `test_tool_count_no_false_positive_on_year_prose` — uppercase anchor guard
+
+### 2. Dev-install runbook
+
+New file `docs/manual/dev-install.md` (~180 lines) documents the
+bare-python local-checkout workflow for contributors:
+
+1. **venv setup** — `python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
+2. **Local Remote Script install** — `node bin/livepilot.js --install` (NOT `npx livepilot --install`, which resolves to the registry and silently discards local edits)
+3. **MCP client config pointing at `python -m mcp_server`** — per-client examples for Claude Desktop, Claude Code, Cursor/VS Code
+4. **Iterate loop** — client restart for `mcp_server/` edits; `node bin/livepilot.js --install` + `reload_handlers` tool for `remote_script/` edits
+5. **Test suite** — `python -m pytest tests/ -q` (3128 tests as of v1.21.4)
+6. **`sync_metadata` drift check** — `python scripts/sync_metadata.py --check` / `--fix`
+7. **Going back to published** — remove the dev MCP entry or stop using it
+
+Plus a troubleshooting section for the 4 most common first-run failures:
+`ModuleNotFoundError: No module named 'mcp_server'`, `Another client is
+already connected` on port 9878, stale `__pycache__` shadowing edits, and
+module-level constants not reloading via `reload_handlers` (full Ableton
+restart required).
+
+Cross-links added:
+
+- `docs/manual/getting-started.md` — callout at top routing contributors to dev-install before they commit to the npm path
+- `docs/manual/index.md` — new "Contributing" section in the Chapters TOC
+- `CLAUDE.md` — pointer in the Project section
+
+### Carried forward to v1.22
+
+Still deferred from the v1.21.2 audit:
+
+- Atlas `.enriched` schema canonicalization (`stats.enriched_devices = 87`
+  vs 120 YAML files vs 135 historical claim — pick one and derive the
+  others at build time; add a sync_metadata gate matching JSON stats to
+  YAML file count)
+
+## 1.21.3 — Third audit-response: manual-docs drift + sync_metadata file-list widening + unicode-escape regex fix (April 24 2026)
+
+Fourth same-day patch in 48 hours, third audit-response in 24 hours.
+Audit #3 surfaced that v1.21.2's `sync_metadata` scope expansion had
+added new check TYPES but didn't widen the FILE LISTS — so docs/manual
+pages kept drifting (1305 devices, 135 enriched, 52 domains) while
+`sync_metadata --check` passed. This patch widens the file lists AND
+fixes a latent regex bug that v1.21.2's new "device" check would have
+triggered with data-corrupting consequences.
+
+No API changes. No test additions beyond what `sync_metadata` newly
+enforces. No new features.
+
+### P2 — Manual-doc atlas/domain drift (audit finding)
+
+Three manual pages shipped with stale counts through v1.21.2 because
+they weren't in the `sync_metadata` file lists for `enriched` /
+`domain` / the new `device` check:
+
+| File | Stale claim | Corrected to |
+|---|---|---|
+| `docs/manual/device-atlas.md` | 1305 devices / 135 enriched / 641 pack-indexed | 5264 / 120 / (claim dropped) |
+| `docs/manual/index.md` | 1305 devices | 5264 |
+| `docs/manual/tool-reference.md` | 1305 devices / 135 enriched / 52 domains | 5264 / 120 / 53 |
+
+The 5 numeric substitutions (device count, enriched count, domain count)
+were auto-closed by `sync_metadata --fix` once the file lists were
+widened. The `641 pack-indexed` claim was manually dropped (the fixer
+substitutes numbers, doesn't delete claims) — the shipped atlas has an
+empty `.packs` list, so any specific pack-indexed number would be
+meaningless anyway.
+
+### Critical — Latent regex bug in `check_prose_claim` and `_fix_count`
+
+Adding the `"device"` noun to `PROSE_CLAIM_FILES` exposed a regex
+vulnerability that had existed since v1.15-era. `check_prose_claim`'s
+pattern was:
+
+```python
+r"(\d+)[-\s]+(?:[A-Za-z]+\s+)?{noun}s?\b"
+```
+
+No word-boundary assertion at the start. In `manifest.json`, the em-dash
+is stored as the JSON escape `\u2014`. Raw characters are
+`\`, `u`, `2`, `0`, `1`, `4` — so the literal text "2014" appears
+next to a space, next to "device atlas". The regex matched:
+
+```
+...\u2014 device atlas...
+       ^^^^^^^^^^^^^^^
+       (captures "2014", next optional word is empty, then "device")
+```
+
+Reported as `manifest.json: has '2014 device', expected '5264 device'`.
+If `sync_metadata --fix` had run, it would have rewritten `\u2014`
+(em-dash) to `\u5264` (CJK ideograph `剤`). The JSON would become
+visually corrupted and linguistically nonsensical.
+
+**Prior versions got away with this** because no earlier PROSE_CLAIM
+noun could align adjacent to the 4-char "2014":
+  - "tool" starts with `t` — no match
+  - "bridge command" starts with `b` — no match
+  - "enriched" starts with `e` — no match
+  - "semantic move" / "analyzer tool" / "genre default" — none start with `d`
+
+The new `"device"` noun (starts with `d`) was the first to align.
+v1.21.2's extension would have shipped a corrupting `--fix` if anyone
+had run it immediately.
+
+Fix: leading `\b` assertion on all 4 regex patterns in sync_metadata
+(`check_tool_count`, `check_prose_claim`, `fix_tool_count`,
+`_fix_count`). Word-boundary before `\d+` means the digit must start
+at a non-word-to-word transition — which excludes digits adjacent to
+other word chars (like the `u` in `\u2014`).
+
+Verified: post-fix, `check_prose_claim(noun="device")` reports only
+the intended `5264 devices` in `manifest.json` — the `2014` ghost is
+gone. All existing checks (tool count, bridge command, enriched, etc.)
+continue to match correctly because their valid matches are always
+preceded by non-word chars (space, parenthesis, start-of-string, etc.).
+
+### `sync_metadata.py` expansion — new scope + 3 new file-list entries
+
+Added:
+  * **`get_atlas_device_count()`** + `PROSE_CLAIM_FILES["device"]`
+    (threshold=1000) — enforces atlas device-count claims match
+    `stats.total_devices`. Deferred from v1.21.2 because generic
+    noun="device" was thought too broad; threshold=1000 filters
+    historical "5 devices" mentions entirely. Enabled here based on
+    audit #3 finding.
+  * **`PROSE_CLAIM_FILES["enriched"]`** file list widened: added
+    `docs/manual/device-atlas.md`, `docs/manual/tool-reference.md`.
+    These had stale "135 enriched" while README said "120".
+  * **`DOMAIN_COUNT_FILES`** file list widened: added
+    `docs/manual/tool-reference.md`. Its "52 domains" had drifted
+    while the rest of the repo was at 53.
+
+New `sync_metadata --check` banner reports:
+`version=1.21.3, tools=430, domains=53, bridge_cmds=31, enriched=120,
+genres=4, moves=44, analyzer_tools=38, atlas_devices=5264`.
+
+### Deferred to v1.22
+
+- **`check_prose_claim` regex slash-prefix broadening** — still needs
+  doing (would let "spectral/analyzer tools" match the "analyzer tool"
+  check). Not landed in this patch because it would touch every
+  existing noun and warrants its own regression test pass.
+- **Atlas `.enriched` schema decision** — three definitions (87 stats,
+  120 YAML files, 135 flag count). v1.21.3 standardized on 120 across
+  all descriptions via widened `enriched` check, but the schema
+  question is still open.
+- **`dev-install` path** — still open.
+
+### Scope stats
+
+- 1 code fix (`sync_metadata.py` regex `\b` insertion on 4 patterns —
+  prevents future unicode-escape corruption)
+- 1 code expansion (`sync_metadata.py` — new `device` check type +
+  file-list widening on 2 existing checks)
+- 3 doc corrections auto-closed by `sync_metadata --fix` (9 numeric
+  substitutions across 3 manual files) + 1 manual prose-drop (641
+  pack-indexed in device-atlas.md)
+- 15 version-string sites + `.amxd` binary patch (2 bytes) + `.maxpat`
+  source label + `package-lock.json` (2 fields) bumped 1.21.2 → 1.21.3
+- Test suite: 3124 passed, 1 skipped (unchanged — no-regression patch)
+
+### Credits
+
+Third external audit by the repo owner. Fourth same-day patch since
+v1.20.1. Audit-to-ship pattern stable at ~2h per round.
+
+---
+
 ## 1.21.2 — Second audit-response: atlas reconciliation + manual hygiene + sync_metadata expansion (April 24 2026)
 
 Second same-day audit-response patch. After v1.21.1 shipped, the repo

package/m4l_device/livepilot_bridge.js

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.21.2";
+var VERSION = "1.21.3";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.21.2"
+__version__ = "1.21.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.21.2",
+  "version": "1.21.4",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "Agentic production system for Ableton Live 12 — 430 tools, 53 domains, 44 semantic moves. Device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, 12 creative intelligence engines",
   "author": "Pilot Studio",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.21.2"
+__version__ = "1.21.4"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.21.2",
+  "version": "1.21.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.21.2",
+      "version": "1.21.4",
       "transport": {
         "type": "stdio"
       }