Neo identity maintenance: facts-vs-framing ADR + update skill

Context

Neo's identity is not a document — it is a distributed property across ~30+ surfaces (canonical prose, machine-facing JSON/HTML, build-generated SEO files, external platform settings, agent substrate). Epic #10452 ("Identity Rewrite", CLOSED 2026-04-30 via #10453/#10455) did a one-shot rewrite of README + AGENTS.md into the 4-pillar digital-organism frame, but created no machinery to keep identity coherent over time, and no policy for the surfaces it didn't touch. A 2026-05-30 brainstorm (@tobiu + Opus 4.8) + an 11-agent fan-out audit confirmed identity drifts continuously and the drift is already live. This ticket builds the repeatable machinery.

The Problem

Identity splits into two materials with opposite update semantics:

• Facts (version, MCP count, Node req, GA date, awards) — one true value; rot independently across surfaces.
• Framing (taglines, positioning, audience) — deliberately audience-segmented; forcing one value destroys signal.

Hand-editing prose can't keep facts coherent (they live in JSON/HTML/generated files); naive find-replace destroys framing segmentation. The fan-out found ~25 live drift rows, e.g.:

• MCP-server count understated in 11 surfaces (correct = 5 functional: KB, Memory Core, GitHub Workflow, Neural Link, File System; gitlab-workflow is a PoC, never counted).
• apps/portal/index.html ld+json: version: 11.18.0 (pkg is 12.1.0), Node.js 18+ (actual 24+), "three MCP servers".
• package.json has no engines field → Node floor unenforced.
• @neo-opus-ada in 63 files; ModelStats.md sunset trigger ("Opus 4.8+") already fired with no rotation.
• AGENTS.md self-contradicts (L12 "3 pillars" vs L119 "four pillars").
• VISION/ROADMAP "Corporate HQ / CEOs / PMs / Drones" hierarchy contradicts the canonical Flat Peer-Team (§swarm_topology_anchor); Triad/[3] cardinality is hard-coded.
• Heritage layer near-absent: GA Nov 2019, OS-Awards top-5 2021, "first multi-worker UI engine" have no canonical home in prose.

The Architectural Reality

Affected-areas map by update mechanism (each class = a distinct edit point + failure mode):

1. Hand-edited prose — README.md, .github/VISION.md, ROADMAP.md, CONTRIBUTING.md, learn/benefits/**, learn/agentos/*.md, .claude/CLAUDE.md (§neo_identity_anchor, §swarm_topology_anchor), learn/agentos/AGENTS_ATLAS.md.
2. Generated-output-source (TRAP — edit the script, not the output) — buildScripts/docs/seo/generate.mjs:539-559 (hardcoded llms.txt header) + PRIORITIES map (28-110) → emits apps/portal/llms.txt + apps/portal/sitemap.xml.
3. Structured-facts-in-code (ROT ZONE) — package.json (description/keywords/version), apps/portal/index.html (3× ld+json + meta + title + FAQ), apps/portal/view/home/parts/*.mjs (hero cycleTexts, AiToolchain, Features, FooterContainer version literal).
4. External-platform (not in git; needs API) — GitHub repo description + 20 topics, npm (derives from package.json), Discord/Slack/LinkedIn/Sponsors.
5. Dated-snapshot (calendar-stale) — README "State of May 1, 2026" ↔ learn/guides/fundamentals/CodebaseOverview.md (lock-step); ROADMAP metrics; learn/agentos/ModelStats.md.

Propagation targets (facts in 2+ surfaces — SSOT candidates the ADR resolves): package version, MCP-server count, Node requirement, identity handle, the recurring motto, the tagline cluster. Existing seams: buildScripts/release/prepare.mjs (version bump — currently skips ld+json + NeuralLink.md), ai/graph/identityRoots.mjs (handle centralization).

Contract Ledger

The Fix

One coherent unit, ADR-founded:

1. ADR 0018 — Neo Identity Source-of-Truth Model (foundational). Per propagation target, decides the facts-vs-framing contract: which surface is canonical, and whether others derive (build-time), generate, or coherence-check. Facts → single source + derive/generate; framing → audience-segmented clusters governed against the canonical apex (README organism frame) with a drift-vs-intentional-divergence escalation branch.
2. /create-skill neo-identity-update — built on ADR 0018, authored per the create-skill Progressive Disclosure contract (Map / World-Atlas split, no router bloat). Routes: enumerate surfaces by class → detect fact drift vs SSOT → coherence-check framing → split mechanical-fix from escalate-worthy divergence → require a cross-family review gate before any identity-surface PR merges.
3. Affected-areas map captured as the skill's reference payload (the map above, file:line enumerated).

Decision Record impact

Introduces ADR 0018. aligned-with closed #10452 (maintains the prose it created). depends-on ADR 0012 (handle de-versioning must preserve 0012's per-model-identity decision — only the GitHub handle de-versions; the model-version pin stays in ModelStats).

Acceptance Criteria

• ADR 0018 authored in learn/agentos/decisions/, deciding facts-vs-framing SSOT per propagation target, merged to dev (foundational — blocks the skill; gets cross-family review)
• /create-skill neo-identity-update authored per create-skill contract; ai:lint-skill-manifest passes
• Skill encodes the 5-class affected-areas map as reference payload (file:line)
• Skill mandates a cross-family review gate on identity-surface PRs (empirical anchors #12146 / #11999 / #11962)
• Skill distinguishes mechanical-fix (stale fact) from escalate-worthy divergence (framing fossils, e.g. CEO/PM/Drone hierarchy; Triad/[3] cardinality)
• turn-memory-pre-flight applied (skill-loaded substrate)

Out of Scope

• Running the skill / fixing live drift — separate item (operator direction); this ticket builds machinery only.
• GitHub account renames — operator-owned (Tier-4). The skill propagates a rename across surfaces; it doesn't perform the account change.
• De-versioning per-model identity prose in ModelStats — deliberate per ADR 0012; preserved.
• Engine/runtime code changes — identity machinery only.
• Heritage-layer content authoring — gap flagged; disposition is an ADR 0018 decision, authoring is follow-up.

Avoided Traps / Gold Standards Rejected

• Naive tagline find-replace — destroys deliberate audience-segmentation. Rejected.
• Editing generated output (llms.txt/sitemap) directly — clobbered on build; source is generate.mjs. Rejected.
• Blanket de-versioning of per-model identity — only the GitHub handle de-versions (ADR 0012). Rejected.
• Single canonical SSOT doc for everything — fights the facts-vs-framing split; framing isn't single-valued. Rejected in favor of the hybrid model.

Related

• #10452 — Identity Rewrite (CLOSED origin; this maintains what it created)
• ADR 0012 — per-model identity / ModelStats (depends-on)
• #10332, #10030, #10291 — frontier tickets cited in README identity
• Discussions #10454, #10137, #10119 (context, not graduation source)
• Brainstorm + fan-out audit: Memory Core session 94a91ebc-d325-4d32-a746-4ff8c26c0342

Origin Session ID

Origin Session ID: 94a91ebc-d325-4d32-a746-4ff8c26c0342

Handoff Retrieval Hints

Retrieval Hint: "neo identity affected-areas map facts-vs-framing SSOT" Retrieval Hint: "fan-out drift register MCP server count 63 files handle"