docs: v2 (GitHub-backed) design doc - #29
Open
budhash wants to merge 1 commit into
Open
Conversation
Capture the v2 architecture settled in the 2026-08-04 brainstorm and sharpened by an adversarial review: every item is a GitHub issue (collision-free ids by construction), a 4-level release -> milestone -> feature -> task tree, and a pluggable Backend interface (GitHub is one impl). Prose stays repo-primary (offline-first preserved) and is mirrored to issue bodies; reconciliation is nonce-keyed. Record the hard sequencing prerequisite: a selfupdate cross-major guard must ship in the last 1.x release before v2 lands on main. Open items are flagged in the doc for red-penning. No engine changes. Point MEMORY.md at the v2 direction and this prerequisite.
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.
Captures the v2 architecture — the next major version — settled in the 2026-08-04 brainstorm and sharpened by an adversarial (Fable) design review. Design doc only; no engine changes.
What v2 is
type:*label) → ids are collision-free by construction, retiring the whole Feature: renumber verb — reassign a task's ID (+ repoint references) #12/Feature: collision-resistant ID allocation (ref-aware / explicit --id / reserve) #13/Feature: reference-integrity check (validate --refs) for dangling/repurposed IDs #14 triad at the v2 line.Backendinterface — GitHub is one impl; an in-memory (file-backed) fake drives the e2e suite.new, batch-on-sync; offlinenew→ random-suffixed provisional id, reconciled via a nonce-keyed idempotent sync.Why this PR now
Per the repo's own lesson — decisions made in chat evaporate; specs in-repo don't — this commits the settled decisions before implementation, and points
MEMORY.mdat the v2 direction.Hard sequencing prerequisite (verified against the code)
DEFAULT_CANONICAL_SOURCEpoints atmain's rawtasks.pyandselfupdateoverwrites whenever the fetched version is greater, with no major-boundary check. So aselfupdatecross-major guard must ship in the last 1.x release before v2 lands onmain, or vendored 1.x copies self-update across the major boundary. Recorded in the doc's Sequencing and inMEMORY.md.Status
Load-bearing decisions are settled; open items (file-layout mockup, id display, token/CI contract, GitHub operational ceilings, migration mechanics, pull semantics) are flagged in the doc for red-penning. The 1.x queue (#14 + #25 + the guard) ships first, then a 1.x freeze.