ATOCore/docs/decisions/2026-04-22-gbrain-plan-rejection.md

# Decision record: gbrain-inspired "Phase 8 Minions + typed edges" plan rejected

**Date:** 2026-04-22
**Author of plan:** Claude
**Reviewer:** Codex
**Ratified by:** Antoine
**Status:** Rejected as packaged. Underlying mechanic (durable background jobs + typed relationships) deferred to its correct home.

## Context

Antoine surfaced https://github.com/garrytan/gbrain and asked for a compare/contrast and a
plan to improve AtoCore. Claude proposed a "Phase 8" plan pairing:

1. A Minion-style durable job queue replacing the nightly cron pipeline
2. A typed-edge upgrade over existing wikilinks, with a six-predicate set
   (`mentions`, `decided_by`, `supersedes`, `evidences`, `part_of`, `blocks`)

Codex reviewed and rejected the plan as packaged. This record captures what went wrong,
what was right, and where the ideas should actually land.

## What Codex flagged (verified against repo)

### High — wrong sequencing

`docs/master-plan-status.md` defines the **Now** list:

1. Observe the enhanced pipeline for a week
2. Knowledge density — batch-extract over all 234 interactions, target 100+ memories
3. Multi-model triage (Phase 11 entry)
4. Fix p04-constraints harness failure

Engineering V1 appears under **Next** (line 179) as
"Engineering V1 implementation sprint — once knowledge density is sufficient and the
pipeline feels boring and dependable."

Claude's plan jumped over all four **Now** items. That was the primary sequencing error.

### High — wrong predicate set

`docs/architecture/engineering-ontology-v1.md` already defines a 17-predicate V1
ontology across four families:

- **Structural:** `CONTAINS`, `PART_OF`, `INTERFACES_WITH`
- **Intent / logic:** `SATISFIES`, `CONSTRAINED_BY`, `BASED_ON_ASSUMPTION`,
  `AFFECTED_BY_DECISION`, `SUPERSEDES`
- **Validation:** `ANALYZED_BY`, `VALIDATED_BY`, `SUPPORTS`, `CONFLICTS_WITH`,
  `DEPENDS_ON`
- **Artifact / provenance:** `DESCRIBED_BY`, `UPDATED_BY_SESSION`, `EVIDENCED_BY`,
  `SUMMARIZED_IN`

Claude's six-predicate set was a gbrain-shaped subset that could not express the V1
example statements at lines 141–147 of that doc. Shipping it first would have been
schema debt on day one.

### High — wrong canonical boundary

`docs/architecture/memory-vs-entities.md` and
`docs/architecture/engineering-v1-acceptance.md` establish that V1 is **typed
entities plus typed relationships**, with one canonical home per concept, a shared
candidate-review / promotion flow, provenance, conflict handling, and mirror
generation. Claude's "typed edges on top of wikilinks" framing bypassed the canonical
entity contract — it would have produced labelled links over notes without the
promotion / canonicalization machinery V1 actually requires.

### Medium — overstated problem

Claude described the nightly pipeline as a "monolithic bash script" that needed to be
replaced. The actual runtime is API-driven (`src/atocore/api/routes.py:516`,
`src/atocore/interactions/service.py:55`), SQLite is already in WAL with a busy
timeout (`src/atocore/models/database.py:151`), and the reflection loop is explicit
capture / reinforce / extract. The queue argument overstated the current shape.

## What was right

- gbrain is genuine validation of the general pattern: **durable background jobs +
  typed relationship graph compound value**. The gbrain v0.12.0 graph release and
  Minions benchmark (both 2026-04-18) are evidence, not just inspiration.
- Async-ification of extraction with retries, per-job visibility, and SLOs remains a
  real future win for AtoCore — but **additively, behind flags, after V1**, not as a
  replacement for the current explicit endpoints.

## What we will do instead

1. **Keep to the `master-plan-status.md` Now list.** No leapfrog. Observe the
   pipeline (including the confidence-decay Step F4 first real run), land knowledge
   density via full-backlog batch extract, progress multi-model triage, fix
   p04-constraints.
2. **When Engineering V1 is ready to start** (criterion: pipeline feels boring and
   dependable, knowledge density ≥ 100 active memories), write a V1 foundation plan
   that follows `engineering-ontology-v1.md`, `engineering-query-catalog.md`,
   `memory-vs-entities.md`, and `engineering-v1-acceptance.md` — entities +
   relationships + memory-to-entity bridge + mirror / query surfaces, in that order.
3. **Async workerization is optional and later.** Only after V1 is working, and only
   if observed contention or latency warrants it. Jobs stay in the primary SQLite
   (WAL already in place). No separate DB unless contention is measured.

## Lesson for future plans

A plan built from a **new external reference** (gbrain) without reading the
repository's own architecture docs will mis-specify predicates, boundaries, and
sequencing — even when the underlying mechanic is valid. Read the four V1
architecture docs end-to-end before proposing schema work.

## References

- https://github.com/garrytan/gbrain
- `docs/master-plan-status.md` (Now / Next / Later)
- `docs/architecture/engineering-ontology-v1.md`
- `docs/architecture/engineering-query-catalog.md`
- `docs/architecture/memory-vs-entities.md`
- `docs/architecture/engineering-v1-acceptance.md`
- `docs/architecture/llm-client-integration.md`
- `docs/architecture/human-mirror-rules.md`