---
id: 12229
title: De-fossilize VISION.md to the canonical apex
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-gpt
createdAt: '2026-05-30T21:26:13Z'
updatedAt: '2026-06-07T17:17:33Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12229'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12225
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-31T11:23:00Z'
---
# De-fossilize VISION.md to the canonical apex

Parent epic: #12225

## Context

`.github/VISION.md` carries two fossil framings that contradict the canonical apex (ADR 0018 §2.7 OD-1 — *self-evolving software organism*, graduated via Discussion #12234):
1. *"the platform for the next generation of web applications"* — the framework/web framing the current identity explicitly rejects.
2. A *"Corporate HQ / CEOs / PMs / Drones"* hierarchical swarm model — contradicts the canonical **flat peer-team** topology.

## The Fix

Rewrite VISION.md to lead with the canonical organism apex + flat peer-team. VISION is the home for the deeper *self-evolving organism / Four-Pillars* cluster (per the `neo-identity-update` skill's framing-governance) — so it leads with the organism framing made compatible with the apex, not a flatter institution-only lead:

- Replace the "web applications" lead with the canonical apex (self-evolving software organism — a professional end-to-end AI engineering team; Body `/src/` + Brain `/ai/` the two hemispheres beneath).
- Replace the hierarchical CEO/PM/Drone model with the flat cross-family peer-team.
- Preserve any Command Center concept only as a **product interface / orchestration UI** if it remains useful; it must not describe the maintainer swarm's topology, which is flat.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `.github/VISION.md` opening | ADR 0018 §2.7 OD-1, #12225, Discussion #12234 | Lead with Neo.mjs as a self-evolving software organism and professional end-to-end AI engineering team, with Body `/src/` and Brain `/ai/` as the two hemispheres beneath the apex | If the exact apex paragraph is too long for VISION, use a compatible long-form projection without reverting to web-framework or app-engine-only framing | `.github/VISION.md` | Targeted grep proving the old web-app lead is gone; diff review against ADR 0018 |
| `.github/VISION.md` Agent OS / swarm section | AGENTS.md §swarm_topology_anchor, ADR 0018 §2.3 and §2.7, #12225 | Describe the named maintainer swarm as a flat cross-family peer-team with independent agency, review rights, and human merge gate governance | If a Command Center product concept is retained, frame it explicitly as an operator UI for coordinating agents, not as the maintainer-team topology | `.github/VISION.md` | Targeted grep proving CEO/PM/Drone and Corporate HQ hierarchy terms are gone or explicitly rejected; cross-family review |
| `.github/VISION.md` deeper organism / Four-Pillars framing | `neo-identity-update` framing governance and affected-areas map | Keep VISION as the deeper research/organism surface while making it compatible with the canonical apex | Remove or demote stale pillar labels only where they fight the apex; preserve valid Body/Brain/Evolution/Governance substance | `.github/VISION.md` | Markdown diff plus stale-string sweep |

## Intake Classification

Ticket reality classification: `valid-as-written` after contract-ledger backfill. The V-B-A sweep confirms `.github/VISION.md` still contains the web-app lead and Corporate HQ / CEO / PM / Drone hierarchy. ADR 0018 explicitly names this surface as a fossil-prone contradiction, and the parent #12225 epic requires VISION to lead with the canonical apex. Command Center language may be preserved only as product/interface framing, never as the maintainer swarm topology.

## Acceptance Criteria

- [ ] "web applications" lead replaced with the canonical organism apex
- [ ] CEO/PM/Drone hierarchy replaced with flat peer-team (or explicitly reframed as a product concept if that intent is confirmed by the operator)
- [ ] VISION remains the home for the deeper organism / Four-Pillars framing
- [ ] Cross-family review per ADR 0018 §2.6

## Out of Scope

- README opening (sibling sub)
- Any business/product roadmap content

## Related

- Parent: #12225 · Apex + escalation: ADR 0018 §2.3 / §2.7 OD-1 (graduated via Discussion #12234)

Origin Session ID: 94a91ebc-d325-4d32-a746-4ff8c26c0342
Retrieval Hint: "VISION.md fossil web-applications CEO PM Drone flat peer-team organism apex"

## Timeline

- 2026-05-30T21:26:14Z @neo-opus-ada added the `documentation` label
- 2026-05-30T21:26:14Z @neo-opus-ada added the `enhancement` label
- 2026-05-30T21:26:14Z @neo-opus-ada added the `ai` label
- 2026-05-30T21:29:01Z @neo-opus-ada added parent issue #12225
- 2026-05-31T02:27:04Z @neo-opus-ada changed title from **De-fossilize VISION.md to the institution apex** to **De-fossilize VISION.md to the canonical apex**
- 2026-05-31T02:34:21Z @neo-gpt cross-referenced by #12225
- 2026-05-31T05:46:57Z @neo-gpt assigned to @neo-gpt
- 2026-05-31T05:51:52Z @neo-gpt cross-referenced by PR #12246
- 2026-05-31T06:08:42Z @neo-opus-ada cross-referenced by PR #12248
- 2026-05-31T10:56:37Z @neo-gpt referenced in commit `a5afd2c` - "docs(identity): recast VISION trajectory (#12229)"
- 2026-05-31T11:11:46Z @neo-gpt referenced in commit `f318699` - "docs(identity): clarify gated RSI governance (#12229)"
- 2026-05-31T11:23:01Z @tobiu referenced in commit `54f6752` - "docs(identity): de-fossilize VISION apex (#12229) (#12246)

* docs(identity): de-fossilize VISION apex (#12229)

* docs(identity): recast VISION trajectory (#12229)

* docs(identity): clarify gated RSI governance (#12229)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-31T11:23:01Z @tobiu closed this issue
- 2026-05-31T11:37:20Z @neo-opus-ada cross-referenced by #12251
- 2026-05-31T12:07:10Z @neo-opus-ada cross-referenced by PR #12252

