Repository navigation
docs(research): two completed research documents exist only on unmerged branches, while the issues they produced are being worked #15220
Description
Found while auditing branches whose work never reached Dev_new_gui.
What
Two completed research documents exist only on unmerged branches. Both produced issues that are now filed and being worked; neither document is in the repository. So the conclusions are being acted on while the reasoning behind them lives nowhere a reader can reach.
| Document | Branch | Size | What it produced |
|---|---|---|---|
| Voxel-grid canvas techniques vs the workflow canvas and LLC Gantt | research-mykonos-voxels |
617 lines, no TODOs | Seven issues — #14765–#14769 and #14770 closed, #14771 open |
| Multi-provider quota headroom and account pooling | research-provider-quota-headroom |
~350 lines | Umbrella #15021 (open) and six children |
The second is the sharper case. PR #15033 was closed deliberately, with the stated reason that merging "would leave a dated comparison snapshot in the repo with no consumer" — a defensible call at the time. But both the closing comment and the branch's own handoff file record that the branch is the only surviving copy. A worktree sweep, a branch prune, or a machine rebuild loses it. It also contains the finding that GET /costs/quota-windows returns structure with no values because a declared "phase 3 quota monitor" was never built.
Why this is worth an issue rather than a shrug
The repository's rule is that unwired work gets finished rather than deleted, and this is that rule applied to analysis instead of code. Six issues under #15021 and one under #14771 are open right now; someone picking one up cannot see why the shape was chosen, what alternatives were rejected, or what was measured. They will re-derive it, and this backlog already carries #15217 — "no trust-boundary reference exists, so every security review re-derives the threat model from scratch" — which is the same defect one domain over.
The "no consumer" objection is also now answered: #15206's settled target state gives research documents a home. Research goes to docs/research/ with an RES_ prefix, and docs/research/_index.md is the index that makes them reachable. That did not exist when PR #15033 was closed.
Acceptance criteria
- Both documents land in
docs/research/under theRES_naming settled on docs: design documents live in four folders and disagree with each other — 18 still teach a name the code deprecated, while 72 use the canonical one #15206, with the date recovered from their commits rather than the date of landing. - Each is listed in
docs/research/_index.mdand cross-linked from the issues it produced — fix(frontend): no safe-area inset handling — bottom-anchored chrome sits under the home indicator #14771, and Umbrella: provider quota headroom + multi-account failover — finish the declared-but-unbuilt quota monitor #15021 with its six children — so the reasoning is reachable from the work. - Each carries a dated status header saying what it was true of and when. A research snapshot is not wrong for being dated, but it is misleading for being undated.
- Confirm no other unmerged branch holds a document in the same position. Two found by audit is not evidence there are two — the audit covered nine branches, not all of them.
- Sequence after security(docs): the internal fleet addressing sweep (#3315) never reached docs/archives — 37 documents still map roles, hosts and database endpoints to private addresses #15208, which redacts internal addressing from archived documents. Do not land new documents into the published tree while that sweep is outstanding, and check both of these for addressing before they land.
Activity