Skip to content
Fera Docs

Search is only available in production builds. Try building and previewing the site to test it out locally.

Five verified stale/contradictory statements in the design corpus

Источник: dev/fera-research/docs/oc3/010-spec-hygiene-defects.md (read-only; сгенерировано scripts/sync-docs.mjs)

Five verified stale/contradictory statements in the design corpus

Section titled “Five verified stale/contradictory statements in the design corpus”
  • kind: problem
  • area: modules
  • severity: mid

Evidence

Section titled “Evidence”

All five verified by direct inspection in this session.

1. OQ-002 is duplicated in OQ.md. Two identical headings, 20 lines apart:

35: ### OQ-002: Single-pass vs two-pass hit-testing in the HoF rendering layer
55: ### OQ-002: Single-pass vs two-pass hit-testing in the HoF rendering layer

The resolution lives in the first block (:35-51, → ADR-030). The second block (:55-66) repeats the question with no resolution, and sits between OQ-002 and OQ-004 — so a reader scanning the ledger sees one resolved entry and one open one.

2. OQ.md:437 points at a document that does not exist.

437: **Progress (2026-09-30):** spec draft exists — `context/LATTICE.md`

The corpus contains: ADR.md conversation.md FUTURE-CHECKS.md NAMING-UX.md OPTIM-IDEAS*.md (5) OQ.md PREDICT.md QA.md RESEARCH-OQ-003.md RFC.md TECHSPEC.md — no LATTICE.md. The spec draft does exist, but at /home/nikki/dev/fera/lattice/SPEC.md (920 lines, tagged spec-v1.0). The reference is simply wrong.

3. RFC.md:30-31 contradicts OQ.md:205-209 on secret chats.

RFC.md:30-31:
- Secret chats (not discussed in architecture sessions to date — flagged in
  `OQ.md`).


OQ.md:205-209:
**Resolved (2026-09-30) → ADR-025.** Full support in v1; separate
sanakirja instance with TTL policy; MTProto E2E as-is (DH + emoji
fingerprint); per-device chats, no key migration; same passcode with a
dedicated Argon2id context.

RFC.md:25 heads this list “## 2. Non-goals (for initial release line)”. So the RFC tells an implementer secret chats are out of scope while the OQ ledger and ADR-025 say they are in v1 scope. ADR.md:506-517 (ADR-026) then adds the consequence: vanilla grammers does not expose what v1 needs, so grmrs must be forked. Anyone reading RFC.md §2 would skip that.

4. TECHSPEC.md:458 names a renderer that was rejected.

458: 3. Elm central loop + minimal GPUI rendering (text-only chat view) — prove
459:    the UI data flow before investing in HoF layer polish or pixel-1:1
460:    fidelity.

OQ.md:476-483 resolved OQ-014 to “Vello + Parley renderer with native text-input slots”, and ADR.md:957-1000 (ADR-028) adopted it, rejecting upstream GPUI on API-churn and documentation grounds. ADR.md:961-967 names GPUI specifically as the decisive negative. The repo correctly follows the resolution (core/crates/ui-engine-vello/), so this is stale prose rather than a wrong implementation.

5. QA.md:190 cites a structure that does not exist.

190: - [ ] Phase 1 of the sequencing plan (`TECHSPEC.md` §10) is achievable

TECHSPEC.md:451-469 enumerates 9 unnumbered steps under the heading “## 10. Sequencing notes (not a committed roadmap, a dependency ordering)”. There is no “Phase 1”. See docs/oc3/009-no-closed-alpha-scope.md for why this particular one matters more than the other four.

Bonus — two more in the same family, from the §7 audit:

6. TECHSPEC.md:363 and TECHSPEC.md:374-390 state two incompatible manifest schemas 11 lines apart — see docs/oc3/003-manifest-two-incompatible-schemas.md.

7. ADR.md:801-805 (ADR-020 naming addendum) declares the for-X-types prefix “dead”, yet ADR-020’s own title and tier list at ADR.md:757 and :778 still use for-struct-types. Minor, but it is the same pattern: an addendum updates the body without updating the heading.

Суть

Section titled “Суть”

QA.md:188-189 states the corpus’s own completeness bar: “Every ‘open question’ flagged inline across these docs is also present in OQ.md (no orphaned TODOs)”. Items 1 and 2 are precisely orphaned-TODO failures by that definition, and the corpus has no automated check for it.

Items 3 and 4 are more consequential than typos because they are contradictions about scope, and they point in opposite directions — one understates the work (secret chats), one names dead technology (GPUI). RFC.md is the document an implementer would most plausibly treat as the summary of “what this project is”, and its §2 currently misstates the v1 feature set.

The pattern across all seven is consistent: the corpus is amended by appending addenda, and the older body text is not revisited. ADR-020’s naming addendum, ADR-016’s superseded-by-ADR-031 tiering, ADR-009’s stale “three axes” title (amended three times, title unchanged), TECHSPEC §10 step 3’s GPUI. Each individual amendment is correct; the accumulated result is a corpus where any given line may be stale and there is no way to tell without reading the addenda.

Варианты решения (с tradeoffs)

Section titled “Варианты решения (с tradeoffs)”

Option A — fix all seven now.

  • Cost: ~30 minutes of careful editing. Two of them (items 3, 5) require a decision, not just an edit: is the RFC’s non-goal list meant to be authoritative, and what is “Phase 1”?
  • Benefit: the corpus stops lying. QA.md:181-192’s three gates can then actually pass.
  • Risk: editing a spec corpus mid-flight can itself introduce inconsistency if done casually.

Option B — fix only the two contradictions (3, 4), leave the rest.

  • Cost: 10 minutes.
  • Benefit: removes the two actively misleading statements; items 1, 2, 7 are low-consequence.
  • Risk: leaves QA.md:188-189 failing on its own criterion.

Option C — add a staleness convention instead of fixing. e.g. “superseded by” markers inline.

  • Cost: ongoing discipline, and it must be applied retroactively to have any effect now.
  • Benefit: prevents recurrence, which is the real problem.

Предлагаемое решение

Section titled “Предлагаемое решение”

A, in one pass, with two decisions escalated rather than guessed.

Straightforward edits (no decision required):

  1. Delete the duplicate OQ-002 block at OQ.md:55-66.
  2. Fix OQ.md:437 to point at lattice/SPEC.md in the lattice repo (tagged spec-v1.0), not context/LATTICE.md.
  3. Update TECHSPEC.md:458 “GPUI” → “Vello + Parley” to match ADR-028 and the actual repo.
  4. Update the ADR-020 title/tier naming at ADR.md:757,778 to X-types.

Two need the owner’s call — I am not going to guess at either: 5. RFC.md:30-31 secret chats: either delete the line, or annotate it “→ resolved into v1 scope by ADR-025; requires a grmrs fork per ADR-026”. The second is strictly more informative and matches how the rest of the corpus records resolutions. 6. QA.md:190 “Phase 1”: the repo’s own CLAUDE.md says “§10 items 1-2 first”, which suggests step 1 or steps 1-2. Whatever it is, write the step numbers — the current text cannot be evaluated.

Then, to stop recurrence (C, cheap): when an ADR addendum changes a decision, amend the heading as well as the body. ADR-020 and ADR-009 both show what happens otherwise — the title is now the only part a reader is certain to see first, and in both cases it is the stale part.

Cross-references

Section titled “Cross-references”
  • docs/oc3/003-manifest-two-incompatible-schemas.md — item 6, the most serious of these
  • docs/oc3/009-no-closed-alpha-scope.md — item 5
  • docs/oc3/006-lattice-not-consumable.md — item 2
  • oc1/oc2/oc4/oc5 are reading the same corpus; a single fix pass would save all five agents from re-deriving these.