Context
The resources/content/issues directory has grown to over 1,000 markdown files. GitHub caps its UI folder tree view at 1,000 items, causing friction because tickets beyond the 1,000th item are invisible and inaccessible via the Web UI.
The Problem
As our repository continues to grow, maintaining a flat structure for active issues (and potentially large release archives in issue-archive/) breaks GitHub UX and creates developer friction. We need to split archives and issues into sub-folders.
The Architectural Reality
ai/services/github-workflow/sync/IssueSyncer.mjs determines the local file paths (e.g., issueSyncConfig.issuesDir). Currently, it saves OPEN issues flatly into resources/content/issues/issue-NNNN.md.
- Various consumers and build scripts (like
buildScripts/docs/index/tickets.mjs and Portal app components like apps/portal/model/Ticket.mjs) rely on this flat structure.
The Fix
- Subdivide
resources/content/issues/ and resources/content/issue-archive/ into smaller subfolders (e.g., groups of 100 issues each, using a naming convention like 1000-1099/ or 10xx/).
- Establish and document a standardized naming convention for these subfolders.
- Update
IssueSyncer.mjs (#getIssuePath) to dynamically compute and write to the correct subfolder based on the issue number.
- Update all downstream consumer logic (sync scripts, portal app views, ticket index generators) to recursively walk the directories instead of assuming a flat list.
- Run a migration script to organize all existing files into the new structure.
Acceptance Criteria
Origin Session ID: d5ed6767-0292-46bf-9346-439f268048ec
Retrieval Hint: "GitHub UI 1000 item folder limit IssueSyncer nested folders"
Context
The
resources/content/issuesdirectory has grown to over 1,000 markdown files. GitHub caps its UI folder tree view at 1,000 items, causing friction because tickets beyond the 1,000th item are invisible and inaccessible via the Web UI.The Problem
As our repository continues to grow, maintaining a flat structure for active issues (and potentially large release archives in
issue-archive/) breaks GitHub UX and creates developer friction. We need to split archives and issues into sub-folders.The Architectural Reality
ai/services/github-workflow/sync/IssueSyncer.mjsdetermines the local file paths (e.g.,issueSyncConfig.issuesDir). Currently, it savesOPENissues flatly intoresources/content/issues/issue-NNNN.md.buildScripts/docs/index/tickets.mjsand Portal app components likeapps/portal/model/Ticket.mjs) rely on this flat structure.The Fix
resources/content/issues/andresources/content/issue-archive/into smaller subfolders (e.g., groups of 100 issues each, using a naming convention like1000-1099/or10xx/).IssueSyncer.mjs(#getIssuePath) to dynamically compute and write to the correct subfolder based on the issue number.Acceptance Criteria
IssueSyncer.mjscorrectly routes new and updated issues into their appropriate subfolders.buildScripts/docs/index/tickets.mjsand other build scripts recursively parse the new nested structure.Origin Session ID: d5ed6767-0292-46bf-9346-439f268048ec Retrieval Hint: "GitHub UI 1000 item folder limit IssueSyncer nested folders"