---
id: 11405
title: 'Release-notes chunking: new ReleaseNotesSyncer'
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees:
  - neo-gemini-pro
  - neo-gpt
createdAt: '2026-05-15T09:37:00Z'
updatedAt: '2026-06-07T17:12:00Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11405'
author: neo-gemini-pro
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-16T10:04:52Z'
---
# Release-notes chunking: new ReleaseNotesSyncer

## Context
As part of Epic #11372 (Land ADR 0004), we are transitioning all `resources/content/` items to the universal ordinal-100 chunking primitive. Currently, `ReleaseSyncer.mjs` writes flat markdown files directly into `resources/content/release-notes/`. This violates the universal architecture of ADR 0004.

## The Problem
`ReleaseSyncer` does not use chunking. It writes directly to `release-notes/` without `chunk-N` folders and does not update `_index.json`. To fully realize ADR 0004 Phase 1, release notes must be chunked identically to issues, PRs, and discussions. This ensures consumer uniformity and prevents folder density issues.

## The Architectural Reality
The current `ai/services/github-workflow/sync/ReleaseSyncer.mjs` iterates over releases and writes `<tagName>.md` files directly using `path.join`. We need to rewire this to use `contentPath.mjs` for resolving paths (e.g. `resources/content/release-notes/chunk-1/v1.0.0.md`) and register each release in the `_index.json` map.

## The Fix
- Rename `ReleaseSyncer.mjs` to `ReleaseNotesSyncer.mjs` to match the canonical `type: 'release-notes'` naming.
- Update the write loop to use the universal `contentPath.mjs` helper.
- Calculate the `itemIndex` based on the chronological sort order of the releases (first release = index 0).
- Maintain the `_index.json` registry during the sync.

## Acceptance Criteria
- [ ] `ReleaseSyncer.mjs` renamed to `ReleaseNotesSyncer.mjs`.
- [ ] `ReleaseNotesSyncer.mjs` uses `contentPath` with `type: 'release-notes'`.
- [ ] `ReleaseNotesSyncer.mjs` calculates chronological `itemIndex` for chunk math.
- [ ] `ReleaseNotesSyncer.mjs` updates `_index.json` with release mappings.
- [ ] No direct writes to the `release-notes/` root directory.

## Out of Scope
- Migrating existing flat release notes. This will be handled by the clean-slate migration task (Phase 1, Task 10).
- Modifying other syncers (already handled in Lane B).

## Avoided Traps
- Using the release version string as an ID for chunk math. Instead, we use the chronological ordinal of the release (1st release is index 0, etc.) to calculate the `chunk-N` folder, mirroring the `itemIndex` logic of issues.

## Related
- **Epic**: #11372
- **Authority**: ADR 0004

Origin Session ID: 188acb85-b41e-435c-94ee-0cc9944d4c97

## Timeline

- 2026-05-15T09:37:01Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-15T09:37:01Z @neo-gemini-pro added the `enhancement` label
- 2026-05-15T09:37:01Z @neo-gemini-pro added the `ai` label
- 2026-05-15T09:37:01Z @neo-gemini-pro added the `agent-task:pending` label
- 2026-05-15T09:37:01Z @neo-gemini-pro added the `architecture` label
- 2026-05-15T09:43:13Z @neo-opus-ada cross-referenced by #11372
- 2026-05-15T09:44:24Z @neo-gemini-pro cross-referenced by PR #11407
- 2026-05-15T16:40:09Z @neo-gemini-pro referenced in commit `6313722` - "fix(sync): integrate _index.json maintenance across all syncers (#11405)"
- 2026-05-15T16:50:19Z @neo-gemini-pro referenced in commit `448c757` - "fix(github-workflow): resolve release hydration and generated tracking (#11405)

Fixed ReleaseNotesSyncer warm-cache bug failing to hydrate sortedReleases

Removed generated release-notes and test-unit.log from git tracking

Stripped trailing whitespace across syncers to satisfy CI diff checks

Added test coverage for warm-cache branch and ordinal pathing"
- 2026-05-15T16:54:57Z @neo-gemini-pro referenced in commit `d29bbfe` - "fix(github-workflow): restore release notes and fix diff check (#11405)

Restored resources/content/release-notes which were incorrectly removed from tracking

Removed resources/content/archive/pulls/v13.0.0/chunk-1/pr-12345.md from tracking

Removed trailing whitespace from ReleaseNotesSyncer.spec.mjs"
- 2026-05-15T17:00:02Z @neo-gemini-pro referenced in commit `30fa713` - "chore(github-workflow): remove leftover mock files from PR (#11405)

Deleted generated log and content test mocks to clean PR diff"
- 2026-05-15T17:15:05Z @neo-gemini-pro referenced in commit `f104359` - "fix(github-workflow): restore bucket planning for ordinal pathing (#11405)"
- 2026-05-15T17:32:31Z @neo-gemini-pro referenced in commit `0a87e9a` - "fix(ai): correct ReleaseNotesSyncer instance resolution in spec (#11405)"
- 2026-05-15T17:41:52Z @neo-gemini-pro referenced in commit `f49dea4` - "fix(github-workflow): resolve config parity and scope contamination (#11405)"
- 2026-05-15T17:49:39Z @neo-gemini-pro referenced in commit `4b39b56` - "fix(sync): integrate _index.json maintenance across all syncers (#11405)"
- 2026-05-15T17:49:39Z @neo-gemini-pro referenced in commit `dea44cf` - "fix(github-workflow): resolve release hydration and generated tracking (#11405)

Fixed ReleaseNotesSyncer warm-cache bug failing to hydrate sortedReleases

Removed generated release-notes and test-unit.log from git tracking

Stripped trailing whitespace across syncers to satisfy CI diff checks

Added test coverage for warm-cache branch and ordinal pathing"
- 2026-05-15T17:49:39Z @neo-gemini-pro referenced in commit `aba546a` - "fix(github-workflow): restore release notes and fix diff check (#11405)

Restored resources/content/release-notes which were incorrectly removed from tracking

Removed resources/content/archive/pulls/v13.0.0/chunk-1/pr-12345.md from tracking

Removed trailing whitespace from ReleaseNotesSyncer.spec.mjs"
- 2026-05-15T17:49:39Z @neo-gemini-pro referenced in commit `7867fa6` - "chore(github-workflow): remove leftover mock files from PR (#11405)

Deleted generated log and content test mocks to clean PR diff"
- 2026-05-15T17:49:40Z @neo-gemini-pro referenced in commit `093cc96` - "fix(github-workflow): restore bucket planning for ordinal pathing (#11405)"
- 2026-05-15T17:49:40Z @neo-gemini-pro referenced in commit `91d5a8c` - "fix(ai): correct ReleaseNotesSyncer instance resolution in spec (#11405)"
- 2026-05-15T17:49:40Z @neo-gemini-pro referenced in commit `b9db20e` - "fix(github-workflow): resolve config parity and scope contamination (#11405)"
- 2026-05-15T18:10:00Z @neo-gemini-pro referenced in commit `04ffc05` - "fix(sync): integrate _index.json maintenance across all syncers (#11405)"
- 2026-05-15T18:10:01Z @neo-gemini-pro referenced in commit `b3af61a` - "fix(github-workflow): resolve release hydration and generated tracking (#11405)

Fixed ReleaseNotesSyncer warm-cache bug failing to hydrate sortedReleases

Removed generated release-notes and test-unit.log from git tracking

Stripped trailing whitespace across syncers to satisfy CI diff checks

Added test coverage for warm-cache branch and ordinal pathing"
- 2026-05-15T18:10:01Z @neo-gemini-pro referenced in commit `3886809` - "fix(github-workflow): restore release notes and fix diff check (#11405)

Restored resources/content/release-notes which were incorrectly removed from tracking

Removed resources/content/archive/pulls/v13.0.0/chunk-1/pr-12345.md from tracking

Removed trailing whitespace from ReleaseNotesSyncer.spec.mjs"
- 2026-05-15T18:10:01Z @neo-gemini-pro referenced in commit `0d9c500` - "chore(github-workflow): remove leftover mock files from PR (#11405)

Deleted generated log and content test mocks to clean PR diff"
- 2026-05-15T18:10:01Z @neo-gemini-pro referenced in commit `a7e1afb` - "fix(github-workflow): restore bucket planning for ordinal pathing (#11405)"
- 2026-05-15T18:10:01Z @neo-gemini-pro referenced in commit `872116a` - "fix(ai): correct ReleaseNotesSyncer instance resolution in spec (#11405)"
- 2026-05-15T18:10:02Z @neo-gemini-pro referenced in commit `71a34f3` - "fix(github-workflow): resolve config parity and scope contamination (#11405)"
- 2026-05-16T02:54:07Z @neo-gpt assigned to @neo-gpt
- 2026-05-16T02:54:59Z @neo-gpt referenced in commit `5587153` - "chore(github-workflow): polish issue syncer whitespace (#11405)"
- 2026-05-16T10:04:52Z @tobiu closed this issue
- 2026-05-16T10:04:52Z @tobiu referenced in commit `2d51cb8` - "feat(ai): chunk release notes to universal ordinal-100 pathing (#11405) (#11407)

* fix(sync): rename ReleaseSyncer and implement chunking

* fix(sync): integrate _index.json maintenance across all syncers (#11405)

* fix(github-workflow): resolve release hydration and generated tracking (#11405)

Fixed ReleaseNotesSyncer warm-cache bug failing to hydrate sortedReleases

Removed generated release-notes and test-unit.log from git tracking

Stripped trailing whitespace across syncers to satisfy CI diff checks

Added test coverage for warm-cache branch and ordinal pathing

* fix(github-workflow): restore release notes and fix diff check (#11405)

Restored resources/content/release-notes which were incorrectly removed from tracking

Removed resources/content/archive/pulls/v13.0.0/chunk-1/pr-12345.md from tracking

Removed trailing whitespace from ReleaseNotesSyncer.spec.mjs

* chore(github-workflow): remove leftover mock files from PR (#11405)

Deleted generated log and content test mocks to clean PR diff

* fix(github-workflow): restore bucket planning for ordinal pathing (#11405)

* fix(github-workflow): exclude dropped issues from ordinal planning (#11407)

* fix(ai): correct ReleaseNotesSyncer instance resolution in spec (#11405)

* fix(github-workflow): resolve config parity and scope contamination (#11405)

* chore(github-workflow): polish issue syncer whitespace (#11405)

---------

Co-authored-by: neo-gemini-3-1-pro <neo-gemini-3-1-pro@users.noreply.github.com>
Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-29T18:43:41Z @neo-opus-ada cross-referenced by #12176
- 2026-05-29T18:52:47Z @neo-opus-ada cross-referenced by PR #12178
- 2026-05-29T20:01:04Z @tobiu referenced in commit `ec34408` - "fix(docs): release index recursive scan for chunk-N release-notes (#12176) (#12178)

release.mjs globbed *.md non-recursively and emitted flat paths, so after #11405 chunked release-notes the index went stale (paths 404; regen would empty it). Switch to a recursive glob and path.relative so the chunk-N segment is preserved. Regenerated releases.json (166 entries, all resolve on disk). Fixed stale path comments in Ticket/Release models.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-30T00:36:15Z @neo-opus-ada cross-referenced by #12186

