tiagojcperez / maestro-cli / 27174959210

100%

push

github

release: 2.5.2 — SQLite FTS5 lexical retrieval for knowledge ranking

New zero-dependency `fts.py` primitive backed by the FTS5 extension that ships
with the standard-library sqlite3 (indexed, standard BM25 via bm25()):
rank_documents / relevance_by_rank / fts5_available. Injection-safe
(parameter-bound MATCH, quoted tokens), deterministic (ORDER BY rank, rowid),
tokenizer pinned (unicode61 remove_diacritics 2), graceful fallback ([] / {}).

select_relevant_knowledge() (source of {{ task_knowledge }}) now ranks the
lexical signal with FTS5 when available — fed the stopword-filtered keyword set,
domain boosts preserved, byte-identical fallback to the in-Python BM25. Set
MAESTRO_KNOWLEDGE_FTS=0 to force the legacy ranker. Affects advisory prompt
context only — not cache keys or the event hash chain, so artifacts stay
replayable.

Hardened via a 3-lens adversarial review (3 findings confirmed + fixed, 3
refuted). Tests: 28 in test_fts.py + 4 knowledge regression guards. Full suite
green (13,442), strict mypy clean. First retrieval gap closed from the Deep
Research gap-analysis.

Docs cascade: CHANGELOG, README (banner + repo-state), CLAUDE (arch + module
table + task_knowledge note), CODEX, docs/VERSIONING (drift 2.4.0->2.5.2 +
looser-policy alignment).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

77 of 82 new or added lines in 3 files covered. (93.9%)

23083 of 23118 relevant lines covered (99.85%)

1.0 hits per line