Skip to content

docs: open-issue priority + dependency DAG snapshot #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robotrocketscience merged 1 commit into from
Apr 29, 2026
Merged

docs: open-issue priority + dependency DAG snapshot #301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 205 additions & 0 deletions docs/issue_priority_dag.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
# Open-issue priority + dependency DAG

**Snapshot:** 2026-04-29. Sources of truth are the GitHub issues + open
PRs; this doc is a stable index. Refresh whenever an issue closes or
a new design dependency surfaces.

## Reading guide

- **Wave** = ordering layer. All items in the same wave are
independent and can land in parallel; later waves block on
earlier ones.
- **Dep** = explicit prerequisite issue (must merge first).
- **Soft-dep** = informational dependency that won't block PRs but
will cause rework if ignored.
- **Status:** `S` = spec-ready (memo merged or in-flight); `I` =
implementation work; `R` = research / bench-gated; `B` = bug; `C`
= closeable (already shipped or duplicate).

## Wave 0 — close out before starting anything new

Stale items. Walk these to zero so they stop showing up in `gh
issue list` triage.

| # | Title | Action |
|---|---|---|
| 223 | feedback_history orphan audit | **Close on PR #283 merge** — fix already in `store.py:514`, test exists. Comment posted. |
| 254 | T1 corroboration trigger gap | **Effectively closed by PR #283** (`UNIQUE(content_hash)` shipped). Operator close needed. |
| 281 | duplicate + off-topic beliefs | **Re-scope:** dedup half = PR #293 (fix-tests blocker). Floor half → #289. Comment-link both. |
| 286 | rebuild redesign parent | **Convert to tracker** — children #287→#291 carry the work. Parent stays open as roll-up. |
| 287 | rebuild eval harness (dup of #288) | **Close as duplicate** — comment posted on 2026-04-29. |
| 280 | hook hardening | **Spec PR #292 merged** — Phase-1 implementation PR #297 in flight. Issue auto-closes on #297 merge. |
| 288 | rebuild eval harness | **Spec PR #294 merged** — implementation issue stays open until layer-1 log code lands. |

## Wave 1 — unblocks the rest of the rebuild redesign

Land in any order; all four are spec memos awaiting ratification +
implementation.

| # | Title | Spec PR | Status | Soft-dep |
|---|---|---|---|---|
| 288 | Eval harness — phase-1 logs | #294 (merged) | S → I | none |
| 289 | Relevance floor + silent contract | #295 (open) | S | #288 (calibration of T values lands later) |
| 290 | Belief retention class + aging | #296 (open) | S | #289 (extends composite score), #288 (audit data), #196 (substrate) |
| 291 | Query understanding | #298 (open) | S | #289 (per-intent floor multipliers) |

**Rule of thumb:** ratify all four memos *first*, then land the four
implementations in numeric order (#288 first because the others
need its log to calibrate). Implementations that touch
`context_rebuilder.py` will conflict — sequence them, don't
parallelise.

**v2.0 substrate cross-cut:** #196 (multi-axis vs single-axis
posterior) is informational soft-dep for #290's `posterior_mean`
term. The retention-class memo's score formula is robust to either
substrate; ratify the substrate before *implementing* #290 so the
formula doesn't get rewritten.

## Wave 2 — phantom-prereqs (T1→T2→T3)

T1 already shipped (`belief_corroborations` table). T2 (PR #256) is
stuck on author rebase + post-#283 merge conflict; T3 hasn't started
because it depends on T2's `session_id` plumbing.

| # | Title | Status | Dep | Action |
|---|---|---|---|---|
| 189 | Tracker | meta | — | stays open until T3 ships |
| 191 | T2 deferred-feedback sweeper | I (PR #256 stale) | #190 (✅), #283 (✅) | author rebase → re-review |
| 192 | T3 session_id propagation | I (not started) | #191 (must merge first) | wait for #256 to clear |

**Soft-dep with Wave 1:** #290's promotion rule (snapshot → fact)
references `corroboration_count` from the same table T1 created.
No conflict, but #190's ledger is the signal source.

## Wave 3 — v2.0 substrate decision tree

These resolve "what shape is the posterior" and propagate
downstream. Order matters here.

| # | Title | Status | Dep | Notes |
|---|---|---|---|---|
| 196 | Multi-axis vs single-axis substrate | S (substrate decision in `docs/substrate_decision.md`; cascade landed) | — | **gate for everything below** |
| 151 | Posterior-weighted ranking (Beta-Bernoulli, log-additive) | S (PR #277 spec) | #196 | implementation after #196 final ratify |
| 228 | Wonder-consolidation strategy bake-off (RW/TC/STS) | R (spec-ready, bench-gated) | #196, #229 (consumes promotion trigger) | research lane |
| 229 | Phantom promotion-trigger rule | R (spec-ready, bench-gated) | #196, #190 (✅), #228 (informs trigger calibration) | research lane |
| 197 | Dedup module (v2.0 evaluation) | R (bench-gated) | #196, #283 (✅ — output-stage dedup distinct from store-stage) | evaluation lane |
| 198 | Multi-LLM consensus (multimodel) | R (bench-gated) | #196 | evaluation lane |
| 199 | Enforcement module (directives + audit) | R (bench-gated) | #280 (✅ on hook hardening), #196 | evaluation lane |
| 201 | Semantic contradiction detector | R (bench-gated) | #196, #190 (✅) | evaluation lane |
| 193 | Sentiment-from-prose feedback | S (spec-ready) | #196, privacy review | evaluation lane |

**Rule of thumb:** anything `bench-gated` doesn't ship until #288
harness is producing precision/recall numbers (Wave 1). The R-tag
research can run in parallel against synthetic stores; don't merge
anything bench-gated until the harness has a calibration fixture.

## Wave 4 — v2.x materialization (write-log-as-truth)

Sequential by design. Each step probes a fail-closed condition for
the next.

| # | Title | Status | Dep | Notes |
|---|---|---|---|---|
| 262 | replay_full_equality probe | S (spec in PR #267 docs/v2_replay.md) | #205 (✅ ingest_log), #271 (✅ legacy_unknown) | probe lands first |
| 264 | Derivation worker | S | #262 (probe must pass) | beliefs become materialized |
| 265 | View-flip — beliefs/edges as views over ingest_log | S | #264, #262 | terminal step of v2.x materialization |

Don't ship in parallel — #264 changes write-path ownership; #265
changes read-path; landing them out of order leaves the store in a
state where `replay_full_equality` doesn't hold and #262's probe is
useless.

## Wave 5 — long-tail retrieval and research

Lower priority; can pick up between waves whenever an operator has
appetite.

| # | Title | Status | Dep | Notes |
|---|---|---|---|---|
| 154 | Pipeline composition tracker (unified `retrieve()`) | S (v1.7 target) | #289 + #290 + #291 (all memos must land first — they all touch the unified path) | refactor only after #289-#291 implementations merge |
| 153 | uri_baki post-rank adjuster retest | R | #154, #288 (calibration data) | research lane, low-priority |

**Rule of thumb:** #154 is a refactor; doing it before #289–#291
ship guarantees rework. Hold.

## Cross-cutting hazards (write these on the wall)

These come up repeatedly and have caused rework or near-rework
already.

1. **`context_rebuilder.py` is the merge-conflict spot.** Any two
PRs that touch `_query_for_recent_turns`, `rebuild_v14`, or
`_format_block` will collide. Wave-1 implementations must
sequence; do **not** open two of #288 / #289 / #290 / #291 PRs
simultaneously.
2. **`store.py` schema list is the other merge-conflict spot.**
Any two PRs that add a column or touch the migration helpers
(`_maybe_*`) will collide. #283 → #284 is the current
live conflict; #290 retention-class column adds a third surface.
3. **`UNIQUE(content_hash)` from #283 broke #293's tests.** Pattern
to avoid: any PR that inserts duplicate `content_hash` rows
directly via `store.insert_belief` will fail. Use raw `sqlite3`
or refactor the dedup logic to take a `Belief` list at the
pack-stage so tests can construct dups without the store.
4. **Calibration data is the bench-gate.** Multiple memos defer
their *constants* (#289's T, #290's half-lives, #291's intent
thresholds) to "after #288 logs land." If #288's log
implementation slips, every Wave-1 calibration follow-up slips
with it. Treat #288's implementation PR as a critical-path
blocker, not a phase-1 nicety.
5. **Ratify the substrate (#196) before implementing #290.** The
retention-aging multiplier consumes `posterior_mean`. The
formula is robust to either substrate, but the implementation
is not — a multi-axis posterior would mean computing
per-aspect multipliers, which doubles test surface.

## Suggested ratification order (operator decision queue)

Each line is a yes/no the operator can stamp without code review:

1. **#296 retention-class memo** — accept the three live values +
defaults table.
2. **#295 relevance-floor memo** — accept composite score shape +
per-lane floors.
3. **#298 query-understanding memo** — accept three-bucket recency
+ role weighting + intent classes.
4. **#285 hibernation memo** — accept Candidate-A trigger
+ closed grammar + sweeper placement (after author sanitises
the tier-leak flagged in 2026-04-29 review).
5. **#277 posterior-ranking memo** — accept log-additive weight
= 0.5 (after #196 substrate ratification).

Once 1-3 are stamped, Wave-1 implementations unblock in sequence
(#288 first). Once 4 is stamped, #196 substrate work unblocks.
Once 5 is stamped, #151 implementation unblocks.

## What's *not* on this DAG

- Operator-facing UX work (`/aelf:*` slash commands, README, etc.)
lives outside the rebuild / substrate / phantom-prereqs lanes.
- `aelfrice-lab` private experiments that haven't surfaced as
public issues. Track those in the lab repo.
- v3 horizon items (multi-operator, federation). Out of scope until
v2.0 ships.

## Index of in-flight specs and their status

| Spec PR | Issue | Status (2026-04-29) |
|---|---|---|
| #277 | #151 | open, awaiting ratification |
| #285 | #196 hibernation half | open, **leak flagged**, author needs sanitise |
| #292 | #280 | merged |
| #294 | #288 | merged |
| #295 | #289 | open, awaiting ratification |
| #296 | #290 | open, awaiting ratification |
| #297 | #280 phase-1 implementation | open, in review |
| #298 | #291 | open, awaiting ratification |

Implementation PRs:

| Impl PR | Issue | Status |
|---|---|---|
| #256 | #191 | DIRTY, awaiting author rebase |
| #284 | #254 | DIRTY (pytest 3.13), awaiting author |
| #293 | #281 partial | failing tests post-#283; needs test refactor |
| #297 | #280 phase-1 | in review |
Loading