docs: add v3.1 "Make It True" design spec and phase plan - #31
Merged
RichardHightower merged 1 commit intoAug 30, 2026
Merged
Conversation
Full-project review (2026-08-30) found a systematic gap between planning-doc claims and running code: dead orchestrator crate, silent BM25 outbox no-op, mislabeled Hybrid layer, an unrun LOCOMO adapter with an invented schema and substring scoring, and a 65s TOC p50 in the recorded perf baseline. This spec defines milestone v3.1 (Phases 54-58): integration truth, performance truth, honest benchmarks with a real LOCOMO schema and LLM-as-judge, repo shop window + local-first positioning, and GSD process rules requiring execution evidence for verification. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R6oegDbEcoNgWHckPyZYCJ
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
RichardHightower
temporarily deployed
to
e2e-cli
August 30, 2026 07:23 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add the comprehensive design specification and phase plan for v3.1 "Make It True" milestone. This document outlines the systematic effort to close the gap between v3.0's claims and its actual implementation, focusing on integration truth, performance validation, honest benchmarking, and proper project positioning.
Key Changes
docs/plans/v3.1-make-it-true-plan.md(410 lines)Phase Structure
Phase 54 (Integration Truth): Wire the orchestrator into the CLI, fix silent no-ops in BM25 indexing, make the Hybrid retrieval layer actually hybrid, consolidate RRF implementations, remove dishonest daemon flags, and establish a lock-poisoning policy.
Phase 55 (Performance Truth): Root-cause the 65-second TOC p50 latency, fix percentile methodology (currently computed from 3 samples), and re-baseline measurements.
Phase 56 (Honest Benchmarks): Fix the custom benchmark harness (recall@k, compression_ratio, error handling), rewrite the LOCOMO adapter against the real dataset with LLM-as-judge scoring, and gate publication on honest methodology.
Phase 57 (Shop Window & Positioning): Add root README, LICENSE, positioning writeup, and declare supported-surface tiers to match solo-maintainer capacity.
Phase 58 (Launch): Blog post, community announcements, and v3.1.0 release.
Notable Details
Rationale
v3.0 shipped strong code (~1,200 tests, correct transactional outbox, real integrations) but with a systematic gap between documented claims and executable reality. This milestone prioritizes closing that gap over adding new capabilities, ensuring every public statement about Agent-Memory is measurable and defensible before opening the shop window.
https://claude.ai/code/session_01R6oegDbEcoNgWHckPyZYCJ