docs(adaptive-context): fresh spec + four-phase plan, retire the 2026-07 bundle#692
Merged
Merged
Conversation
…-07 bundle The previous bundle was six documents and ~7,700 lines specifying an eleven-phase roadmap. Phases 0 and 1 shipped — nine ADRs, ~3,200 lines of tested domain types, an inert settings block — and the product did not move. The bundle also planned two subsystems that would duplicate ones already running, and had rotted factually within days of being written: it pinned a workspace version 58 patch releases stale, a store schema version two migrations behind, a dependency rev that had already moved, and ~40 file:line anchors into files since rewritten. Replace it with two documents: docs/design/adaptive-context.md what and why, plus invariants docs/design/adaptive-context-plan.md four phases, each observable Three rules drove the rewrite. No coordinates — line numbers, version constants and pins rot faster than they can be maintained, so decisions live in ADRs and positions live in the code. Extend before inventing — a parallel implementation of a shipped mechanism is a defect, not a phase. Every phase changes something a user can see. What the fresh survey of the code found, and the plan now accounts for: - A lexical adaptive loop already ships, on by default, undocumented by the spec: reflection lessons cluster into candidate skills that are written to disk, capped per session, no-clobber, filtered against tombstones from two surfaces. Replacing it is a migration with a behavior-compatibility obligation, not a greenfield build. - The receipts plane already emits an ordered, content-addressed, digest-verified record of what each turn saw. That is ~80% of the proposed CompiledContextFrame. The plan extends the step manifest rather than building an aggregate that could disagree with it. - Fixed per-section prompt budgets are load-bearing for provider cache stability. A dynamic allocator over the system prefix is now rejected permanently, not deferred. - Four defects sit underneath every remaining gap: recall considers the whole corpus per query, the point-in-time cutoff reaches adjacency only, there is no supersede path in the plane that owns the data, and editing a memory mints a duplicate. Phase 1 is defect repair and ships without a flag. Also adds ADR 0010 (Proposed), which amends ADR 0005: it keeps the authority model and replaces the big-bang cutover with incremental transfer, taking the roadmap's self-described riskiest step off the critical path. ADR 0005 gains an amendment notice. ADRs 0001 and 0009 keep their references to the retired bundle — they are accurate records of what was decided and when, and rewriting them to cite a later document would falsify the record. Deletions are recoverable from git history. Inbound links repaired in docs/README.md, docs/context-pr.md, docs/adr/README.md, stella-fleet/README.md and scripts/check-file-size.sh. No Rust changed.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
macanderson
marked this pull request as ready for review
July 26, 2026 16:14
This was referenced Jul 26, 2026
Closed
Closed
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
1 participant
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.
Replaces the six-document, ~7,700-line adaptive-context bundle with two documents and a four-phase plan.
Net: +801 / −9,007. No Rust changed.
Why
Phases 0 and 1 shipped — nine ADRs, ~3,200 lines of tested domain types, an inert settings block — and the product did not move. Meanwhile the bundle rotted factually within days: it pins a workspace version 58 patch releases stale, a store schema two migrations behind, a dependency rev that already moved, and ~40
file:lineanchors into files since rewritten. It also plans two subsystems that would duplicate ones already shipping.What's here
docs/design/adaptive-context.mddocs/design/adaptive-context-plan.mddocs/adr/0010-…Deleted: the implementation plan, both lifecycle drafts, the build prompt, the Phase 0 baseline, and
fleet.plan.toml. All recoverable from git history.Findings that changed the plan
CompiledContextFrame— already ordered, content-addressed, digest-verified, byte-exactly reconstructable. The plan extends the step manifest instead of building an aggregate that could disagree with it. The real gap is narrower: four block kinds are defined and never emitted, so recall collapses into one undifferentiated block.stella memory forgetdoesn't stop one shipping. That's a gap in a guarantee feat(memory): stella memory forget/restore, as a tombstone that survives re-learning #671 already made.ADR 0010
Keeps ADR 0005's authority model, replaces its big-bang cutover with incremental transfer — new record kinds born canonical, legacy rows transferred on write, optional resumable backfill. Takes the roadmap's self-described "single riskiest step" off the critical path. Its cost (two coexisting regimes, possibly indefinitely) is written down rather than hand-waved.
ADRs 0001 and 0009 keep their references to the retired bundle — they're accurate records of what was decided and when.
Gates
check-doc-citations(47 citations resolve),check-normative-home,check-no-scratch,check-file-size— all pass. No Rust touched, so no compile surface.Needs a decision
node/edgetransfer authority at all? Recommend no. Decides whether the lineage column lands on two tables or five.adaptive-context-plan.mdcarries an old→new disposition table.