#7564 tickets as md files

Author: tobiu

.github/ISSUE/ticket-add-frontmatter-to-release-notes.md

@@ -0,0 +1,22 @@
+---
+title: "Add Frontmatter to Synchronized Release Notes"
+labels: enhancement, AI
+---
+
+GH ticket id: #7580
+
+**Epic:** #7564
+**Phase:** 2
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+To improve the structure and utility of the locally synchronized release notes, we should add YAML frontmatter containing key metadata, similar to how issues are handled.
+
+## Acceptance Criteria
+
+1.  The `#syncReleaseNotes` method in `SyncService.mjs` is updated to fetch `tagName`, `name`, and `publishedAt` in addition to the release `body`.
+2.  The `gray-matter` library is used to stringify the release `body` with the fetched metadata as YAML frontmatter.
+3.  The complete content (frontmatter + body) is saved to the local `.md` file.
+4.  The filename convention is clarified and implemented to be clean and predictable (e.g., `v10.9.0.md` from a `v10.9.0` tag).

.github/ISSUE/ticket-add-jsdoc-to-syncservice.md

@@ -0,0 +1,22 @@
+---
+title: "Add Comprehensive JSDoc to SyncService"
+labels: enhancement, AI, documentation
+---
+
+GH ticket id: #7581
+
+**Epic:** #7564
+**Phase:** 2
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+To improve the long-term maintainability and clarity of the `SyncService`, all private methods should be documented with comprehensive JSDoc blocks.
+
+## Acceptance Criteria
+
+1.  Comprehensive JSDoc blocks are added to all private methods in `SyncService.mjs` (e.g., `#ghCommand`, `#formatIssueMarkdown`, `#getIssuePath`, etc.).
+2.  Each comment clearly describes the method's purpose, all of its parameters (`@param`), and its return value (`@returns`).
+3.  Methods that can throw errors are documented with the `@throws` tag.
+4.  At least one complex method, such as `#getIssuePath`, includes an `@example` block demonstrating its usage in different scenarios.

.github/ISSUE/ticket-externalize-magic-numbers.md

@@ -0,0 +1,24 @@
+---
+title: "Externalize Magic Numbers and Strings in SyncService"
+labels: enhancement, AI
+---
+
+GH ticket id: #7582
+
+**Epic:** #7564
+**Phase:** 3
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+The `SyncService` implementation contains several hardcoded "magic numbers" and strings (e.g., API limits, buffer sizes, Markdown delimiters). To improve maintainability and make the service more configurable, these should be extracted and moved to the central `config.mjs` file.
+
+## Acceptance Criteria
+
+1.  The following properties are added to the `githubWorkflow.issueSync` object in `config.mjs`:
+    - `maxGhOutputBuffer` (e.g., `10 * 1024 * 1024`)
+    - `maxIssues` (e.g., `10000`)
+    - `maxReleases` (e.g., `1000`)
+    - `commentSectionDelimiter` (e.g., `'## Comments'`)
+2.  The `SyncService.mjs` file is refactored to import and use these new configuration values instead of the hardcoded numbers and strings.

.github/ISSUE/ticket-fix-gh-api-field-names.md

@@ -0,0 +1,22 @@
+---
+title: "Fix and Verify GitHub API Field Names in SyncService"
+labels: bug, AI
+---
+
+GH ticket id: #7576
+
+**Epic:** #7564
+**Phase:** 1
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+A code review has highlighted a critical potential bug: a mismatch between the JSON fields requested from the `gh` CLI (which often use camelCase like `createdAt`) and the fields it actually returns (which may use snake_case like `created_at`). This ticket covers verifying the correct field names and standardizing their usage throughout the `SyncService` to prevent runtime errors.
+
+## Acceptance Criteria
+
+1.  The actual JSON output of `gh issue view <N> --json createdAt,created_at,author,user` and `gh release view <T> --json publishedAt,published_at` is inspected to definitively identify the correct field names returned by the API.
+2.  All `gh` CLI calls in `SyncService.mjs` are updated to request the correct, verified field names.
+3.  All property accessors within the service's logic (e.g., `issue.createdAt` vs. `issue.created_at`) are updated to match the verified API response, ensuring consistency.
+4.  A new unit or integration test is created to validate the field name mappings for a sample issue and release payload, preventing future regressions.

.github/ISSUE/ticket-harden-release-caching.md

@@ -0,0 +1,21 @@
+---
+title: "Harden Release Caching and Add Fallback"
+labels: enhancement, AI
+---
+
+GH ticket id: #7578
+
+**Epic:** #7564
+**Phase:** 1
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+The `#fetchAndCacheReleases` method needs to be hardened to handle the edge case where no releases are found after the `syncStartDate`. Additionally, the fallback version for archiving should be made configurable.
+
+## Acceptance Criteria
+
+1.  A new property, `defaultArchiveVersion`, is added to the `githubWorkflow.issueSync` object in `config.mjs` with a value like `'unversioned'`.
+2.  The `#fetchAndCacheReleases` method in `SyncService.mjs` is updated to log a warning if `this.releases` is empty after filtering.
+3.  The `#getIssuePath` method is updated to use the new `defaultArchiveVersion` from the config as its fallback value instead of the hardcoded `'unknown'`.

.github/ISSUE/ticket-track-failed-pushes.md

@@ -0,0 +1,23 @@
+---
+title: "Track and Handle Failed Pushes in SyncService"
+labels: enhancement, AI
+---
+
+GH ticket id: #7579
+
+**Epic:** #7564
+**Phase:** 2
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+Currently, if a local issue file is modified but the corresponding issue is deleted on GitHub, the push operation will fail silently on every sync. We need to track these failures to prevent repeated API calls and to aid in debugging.
+
+## Acceptance Criteria
+
+1.  The `catch` block in the `#pushToGitHub` loop is updated to log the specific error message from the `gh` command.
+2.  A `push_failures` array is added to the metadata object that is managed throughout the sync process.
+3.  When a push for an issue fails, its number is added to the `push_failures` array.
+4.  The `#pushToGitHub` logic is updated to check if an issue number is present in the `metadata.push_failures` from the previous sync. If it is, the service should skip attempting to push it again and log a debug message.
+5.  After a full sync cycle, if an issue that was previously in `push_failures` is successfully pulled (i.e., it exists on GitHub again), it should be removed from the `push_failures` list in the new metadata.

.github/ISSUE/ticket-verify-gh-cli-version.md

@@ -0,0 +1,23 @@
+---
+title: "Verify Minimum gh CLI Version Before Sync"
+labels: enhancement, AI
+---
+
+GH ticket id: #7577
+
+**Epic:** #7564
+**Phase:** 1
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+The `SyncService` depends on specific features and output formats of the GitHub CLI (`gh`). To prevent unexpected errors, we must verify that the installed version of `gh` meets the minimum requirement defined in the configuration before attempting any synchronization operations.
+
+## Acceptance Criteria
+
+1.  A new private method, `#verifyGhVersion()`, is added to `SyncService.mjs`.
+2.  This method executes `gh --version`, parses the output to get the semantic version number.
+3.  It compares the installed version against the `aiConfig.githubWorkflow.minGhVersion` from the configuration.
+4.  If the installed version is lower than the minimum requirement, the method must throw a clear, informative error that includes the current version, the required version, and instructions to upgrade.
+5.  The `runFullSync()` method is updated to call `#verifyGhVersion()` at the very beginning of the process, ensuring the check runs before any other logic.