LearnNewsExamplesServices
Frontmatter
id11372
titleEpic: Universal Ordinal-100 Content Architecture (ADR 0004)
stateClosed
labels
epicaiarchitecture
assignees[]
createdAtMay 14, 2026, 9:30 PM
updatedAtJun 5, 2026, 7:22 PM
githubUrlhttps://github.com/neomjs/neo/issues/11372
authorneo-gemini-pro
commentsCount13
parentIssuenull
subIssues
11361 Consumer-side ingestion: KB sources + MC ingestors recursive archive support
11364 Retire PR archiveVersion metadata carry-forward
11363 Remove gh-workflow legacy archive config fallbacks
11379 Consolidate chunkPath.mjs + archivePath.mjs into universal contentPath.mjs (ADR 0004 Lane A)
11390 Adopt contentPath index map in GH workflow syncers
11408 Delete obsolete migrate-substrate-11360 script
11451 Clean-slate migration: Delete existing substrate + run sync_all (ADR 0004 Phase 1 Task 10)
12176 Release notes index broken — release.mjs not migrated to chunk-N
12177 Remove dead issue-archive/pr-archive refs from 4 source files
subIssuesCompleted9
subIssuesTotal9
blockedBy[]
blocking[]
closedAtJun 5, 2026, 7:22 PM

Epic: Universal Ordinal-100 Content Architecture (ADR 0004)

Closed Backlog/active-chunk-12 epicaiarchitecture
neo-gemini-pro
neo-gemini-pro commented on May 14, 2026, 9:30 PM

Context

This Epic supersedes #11187. It tracks the implementation of the Universal Ordinal-100 Content Architecture codified in ADR 0004. See learn/agentos/decisions/0004-github-content-architecture.md for the full architectural rationale and phasing gates.

The Problem

The legacy resources/content/ substrate suffered from ID-range chunking gaps, folder density regret, and inconsistent archive vs active paths. ADR 0004 anchors the solution on a single chunk-N/ universal ordinal primitive and an _index.json map for ID lookups.

The Fix

Implement the ADR 0004 road-map in two strict phases. Phase 1 must complete (and be operationally verified with delta-updates) before Phase 2 begins.

Phase 1 — resources/content/ structure (blocks Phase 2)

  • Universal helper: consolidate chunkPath.mjs + archivePath.mjs into contentPath.mjs
  • Index map: _index.json schema + maintenance in syncers
  • LocalFileService rewrite: index-based lookup
  • Config audit: drop archiveDir + defaultArchiveVersion
  • Syncer updates: all 3 syncers consume contentPath.mjs + maintain _index.json
  • Release-notes chunking: new ReleaseNotesSyncer
  • publish.mjs review
  • Consumer rewires (data-layer only): recursive walk + index lookup in KB sources and IssueIngestor
  • Stale-reference cleanup in workflow-skill + docs
  • Clean-slate migration: Delete existing substrate + run sync_all

Phase 2 — Consumer / Portal / SEO substrate

  • buildScripts/docs/index/ refactor
  • Portal app tree-folder consumption
  • SEO substrate update (sitemap.xml + llms.txt)
  • middleware-v2 routing impact

Out of Scope

  • One-shot migration scripts. The migration is explicitly "clean-slate purge + re-sync" using the new syncer logic.
  • Phase 2 implementation before Phase 1 is verified.

Avoided Traps

  • Attempting to preserve git history with complex file-move scripts. Rejected by operator: "delete it all => clean slate".

Related

  • Authority: ADR 0004 (0004-github-content-architecture.md)
  • Supersedes: #11187
  • Graduating Discussion: #11180, #11359

Origin Session ID: 2c4aa4df-2628-45ae-a9c2-156fd9308f21

tobiu referenced in commit 0e4c016 - "feat(github-workflow/shared): consolidate path primitives into universal contentPath.mjs (#11379) (#11381) on May 15, 2026, 10:19 AM
tobiu referenced in commit ecadd27 - "feat(github-workflow): clean-slate purge of resources/content/ to enable ordinal-100 re-sync (#11451) (#11461) on May 16, 2026, 4:51 PM
tobiu removed the agent-task:blocked label on May 28, 2026, 12:15 AM