Summary

The github-backlog-manager pipeline and its three backing instruction files (github-backlog-planning.instructions.md, github-backlog-triage.instructions.md, github-backlog-discovery.instructions.md) hardcode an EVEN/ODD versioning strategy throughout their milestone assignment logic. Every section that touches milestones assumes that even-numbered milestones are stable releases and odd-numbered milestones are pre-release/development tracks. This coupling prevents the tooling from working correctly in any repository that uses a different release cadence, including standard semver (patch releases on any minor), CalVer, sprint-based milestones, single-track linear releases, feature-gated milestones, or LTS/current dual-track schemes.

This issue proposes replacing all hardcoded EVEN/ODD logic with a native milestone discovery protocol that infers the project's release semantics at runtime from the repository's actual milestone metadata (titles, descriptions, due dates, open/closed state, and issue distribution).

Problem Statement

Scope of the Hardcoding

Seven distinct touchpoints across three instruction files embed the EVEN/ODD assumption. Each one independently produces incorrect behavior when the strategy does not match the consuming repository.

1. Label Taxonomy Reference — github-backlog-planning.instructions.md

The label taxonomy table includes a "Versioning" column that statically maps each label to a milestone parity:

| Label             | Description                                | Versioning                  |
| ----------------- | ------------------------------------------ | --------------------------- |
| bug               | Something is not working                   | EVEN (stable fix)           |
| feature           | New capability or functionality            | ODD (pre-release)           |
| enhancement       | Improvement to existing functionality      | EVEN or ODD                 |
| maintenance       | Chores, refactoring, dependency updates    | EVEN (stable)               |
| security          | Security vulnerability or hardening        | EVEN (stable, expedited)    |
| breaking-change   | Incompatible API or behavior change        | ODD (pre-release only)      |
| infrastructure    | CI/CD, workflows, build tooling            | EVEN (stable)               |

This column tells agents where each label type belongs. In a repository using standard semver, there is no concept of "EVEN (stable)" versus "ODD (pre-release)" — all minor versions can carry bug fixes, features, or breaking changes depending on the project's branching model. The column produces wrong guidance in that context.

2. Milestone Conventions — github-backlog-planning.instructions.md

The Milestone Conventions section defines the two milestone categories as axiomatic:

Milestones follow the EVEN/ODD versioning strategy:

* **EVEN milestones** (v2.0, v2.2.0, v4.0): Stable releases. Bug fixes, security patches,
  maintenance, documentation, and low-risk enhancements.
* **ODD milestones** (v1.0, v2.3.0, v3.0): Pre-release and development. New features,
  breaking changes, experimental capabilities, and high-risk enhancements.

Agents reading this section will classify milestones by their numerical parity regardless of the actual project convention.

3. Milestone Assignment Recommendations — github-backlog-planning.instructions.md

The recommendation table maps every issue characteristic to either "Current EVEN" or "Next ODD":

| Issue Characteristic              | Recommended Milestone |
| --------------------------------- | --------------------- |
| Bug fix (production)              | Current EVEN          |
| Security vulnerability            | Current EVEN (expedited) |
| Maintenance and refactoring       | Current EVEN          |
| New feature                       | Next ODD              |
| Breaking change                   | Next ODD              |
| Infrastructure improvement        | Current EVEN          |

The fallback rule reinforces the assumption: "When uncertain about milestone assignment, agents should default to the next ODD milestone and flag for human review."

4. Triage Phase 1, Step 1 — github-backlog-triage.instructions.md

The very first operational step in the triage workflow instructs agents to derive EVEN/ODD milestones:

Before analyzing issues, determine the current EVEN and next ODD milestones.

1. Search for recent issues with milestone assignments using mcp_github_search_issues
   to identify active milestone names.
2. Derive the current EVEN milestone and next ODD milestone from the discovered names.
3. Record the discovered milestones in planning-log.md for reference during analysis.

Step 2 assumes every repository has exactly two milestone tracks distinguished by numerical parity. A repository with milestones named Sprint 42, Sprint 43, or 2025-Q1, 2025-Q2 will fail this derivation entirely.

5. Triage Milestone Recommendation — github-backlog-triage.instructions.md

A second recommendation table in the triage file duplicates and reinforces the EVEN/ODD mapping:

| Issue Characteristic        | Recommended Milestone      | Rationale                                      |
| --------------------------- | -------------------------- | ---------------------------------------------- |
| Bug fix                     | Current EVEN (stable)      | Stable releases receive production fixes       |
| Security fix                | Current EVEN (expedited)   | Security patches ship in nearest stable release |
| New feature                 | Next ODD (pre-release)     | Features incubate in pre-release milestones    |
| Breaking change             | Next major milestone       | Breaking changes require a major version bump  |

This table drives the actual mcp_github_issue_write calls that assign milestones during triage execution. Wrong recommendations here mean issues land on the wrong milestone in non-EVEN/ODD repositories.

6. Triage Priority Assessment — github-backlog-triage.instructions.md

The priority table references the "current EVEN milestone" directly:

| Priority | Label(s)    | Handling                                         |
| -------- | ----------- | ------------------------------------------------ |
| Highest  | security    | Flag for immediate attention. Assign to current
|          |             | EVEN milestone with expedited notation.          |
| High     | bug         | Assign to current EVEN milestone.                |

In a CalVer repository where the next milestone is 2025-03 regardless of parity, "current EVEN milestone" has no semantic meaning.

7. Discovery Phase 2 Cross-Reference — github-backlog-discovery.instructions.md

The cross-reference table in the discovery instructions tells agents to consult "EVEN/ODD versioning for milestone assignment" when building issue plans:

| Milestone Conventions | Phase 2 | EVEN/ODD versioning for milestone assignment |

This propagates the assumption into artifact-driven discovery, affecting milestone fields on every candidate issue generated from PRDs, roadmaps, or specifications.

Impact

• Portability: Any repository adopting hve-core's backlog management tooling inherits incorrect milestone logic unless it also adopts EVEN/ODD release cadence.
• Silent misassignment: Agents follow the instructions literally. A bug filed against a semver v3.1.0 milestone gets reassigned to v3.0.0 (the nearest even) with no warning.
• Maintenance burden: The EVEN/ODD tables are duplicated between planning and triage instructions, creating two sources of truth that can drift independently.
• Adoption friction: Teams evaluating hve-core see a hard dependency on a non-standard versioning strategy and may dismiss the tooling as too opinionated.

Proposed Solution

Three implementation phases, each independently shippable. Phase 1 is the core capability; Phase 2 is the fallback mechanism; Phase 3 is the cleanup of all EVEN/ODD hardcoding.

Phase 1: Milestone Discovery Protocol

Introduce a reusable milestone discovery step that any workflow (triage, discovery, sprint planning) invokes before making milestone assignment decisions. The protocol replaces the current "derive the current EVEN and next ODD milestones" step in triage and the implicit EVEN/ODD assumptions in planning and discovery.

Discovery Algorithm

FUNCTION discover_milestone_strategy(owner, repo):
  1. FETCH all open milestones via GitHub Milestones API
     - Retrieve: title, description, due_on, state, open_issues, closed_issues
     - Sort by due_on ascending (nearest due date first)

  2. DETECT naming pattern from milestone titles:
     a. SemVer pattern: titles match /^v?\d+\.\d+(\.\d+)?(-[\w.]+)?$/
        - Extract major.minor.patch components
        - Check for pre-release suffixes (-alpha, -beta, -rc, -preview)
     b. CalVer pattern: titles match /^\d{4}[-.]?(Q[1-4]|\d{2})$/
        - Extract year and period components
     c. Sprint pattern: titles match /^sprint[-_ ]?\d+$/i
        - Extract sprint number, treat as linear sequence
     d. Feature pattern: titles contain descriptive names without version numbers
        - Treat as linear, date-ordered sequence
     e. Mixed/Unknown: no single pattern covers >50% of open milestones

  3. CLASSIFY each milestone into a role:
     For SemVer naming:
       - "stable" : no pre-release suffix, OR description contains
                     stable|release|production|GA|LTS
       - "pre-release" : has pre-release suffix (-alpha/-beta/-rc/-preview),
                         OR description contains pre-release|preview|beta|RC|
                         experimental|development|canary|nightly
       - "hotfix" : patch-only increment from a closed stable milestone,
                    OR description contains hotfix|patch|urgent
     For CalVer/Sprint/Feature naming:
       - "current" : nearest future due date with open issues
       - "next"    : second-nearest future due date
       - "backlog" : no due date or due date far in the future

  4. BUILD assignment map:
     Replace the hardcoded EVEN/ODD table with:
       | Issue Characteristic    | Target Role                        |
       | ----------------------- | ---------------------------------- |
       | Bug fix (production)    | nearest "stable" or "current"      |
       | Security vulnerability  | nearest "stable" or "current" (expedited) |
       | Maintenance             | nearest "stable" or "current"      |
       | Documentation           | nearest "stable" or "current"      |
       | New feature             | nearest "pre-release" or "next"    |
       | Breaking change         | nearest "pre-release" or "next"    |
       | Experimental            | nearest "pre-release" or "next"    |
       | Infrastructure          | nearest "stable" or "current"      |

  5. RECORD the discovered strategy and classification in planning-log.md:
     - Detected naming pattern
     - Each milestone with its assigned role
     - The generated assignment map
     - Confidence level (high/medium/low based on signal strength)

  RETURN milestone_map

Signal Weighting

When multiple signals conflict (e.g., title suggests stable but description says "preview"), apply this precedence:

1. Explicit pre-release suffix in title (-beta, -rc) — highest signal
2. Description keywords — strong signal
3. Version number parity — weak signal (preserved for backward compatibility with EVEN/ODD repos)
4. Due date proximity — tiebreaker

This means that for hve-core (which uses EVEN/ODD), the discovery protocol examines the milestone titles (v2.2.0, v2.3.0, etc.), detects SemVer naming, finds no explicit pre-release suffixes, then falls to description keywords or version parity. If milestone descriptions contain "pre-release" or "stable" keywords, those drive classification. If they do not, parity becomes the decisive signal — preserving current hve-core behavior as a naturally discovered strategy rather than a hardcoded assumption.

Phase 2: Configurable Fallback

When the discovery protocol cannot classify milestones with medium or high confidence (no recognizable naming pattern, no descriptions, no due dates):

1. Check for repository configuration — Look for .github/milestone-strategy.yml (or a similar configuration file) that explicitly declares the versioning scheme:

   # .github/milestone-strategy.yml
   strategy: semver-even-odd    # or: semver, calver, sprint, linear, custom
   roles:
     stable: even-minor         # classify even minor versions as stable
     pre-release: odd-minor     # classify odd minor versions as pre-release

2. Prompt the user — If no configuration file exists and confidence is low, present the discovered milestones and ask the user to identify which milestones serve which role. Record the response in the planning log.
3. Never assume EVEN/ODD — The protocol must not silently default to parity-based classification. If confidence is low and no user input is available, assign milestone unclassified and flag the issue for human review.

Phase 3: Instruction File Refactoring

Remove all hardcoded EVEN/ODD references and replace them with references to the discovery protocol output. Detailed per-file, per-section changes:

File: github-backlog-planning.instructions.md

Section: Label Taxonomy Reference

Current state — the "Versioning" column maps labels to EVEN (stable) / ODD (pre-release):

| bug           | ... | EVEN (stable fix)           |
| feature       | ... | ODD (pre-release)           |
| security      | ... | EVEN (stable, expedited)    |
| breaking-change | ... | ODD (pre-release only)    |

Proposed change — replace the "Versioning" column with a "Target Role" column using abstract role names:

| bug           | ... | stable (fix)              |
| feature       | ... | pre-release               |
| security      | ... | stable (expedited)        |
| breaking-change | ... | pre-release (only)      |

Labels that currently say "EVEN or ODD" (enhancement, documentation, agents, etc.) become "any" — the discovery protocol assigns them to whichever milestone is contextually appropriate.

Section: Milestone Conventions

Current state — defines EVEN and ODD as axiomatic categories with hardcoded examples.

Proposed change — replace with a description of the milestone discovery protocol and the set of abstract roles it produces (stable, pre-release, development, hotfix, current, next, backlog, unclassified). Include a note that specific versioning strategies (EVEN/ODD, standard semver, CalVer, sprint-based) are discovered at runtime rather than prescribed.

Section: Milestone Assignment Recommendations

Current state — maps issue characteristics to "Current EVEN" / "Next ODD".

Proposed change — map issue characteristics to abstract roles:

| Issue Characteristic        | Target Milestone Role              |
| --------------------------- | ---------------------------------- |
| Bug fix (production)        | stable or current                  |
| Security vulnerability      | stable or current (expedited)      |
| New feature                 | pre-release or next                |
| Breaking change             | pre-release or next                |

Replace the fallback rule from "default to the next ODD milestone" to "default to the nearest pre-release or next milestone and flag for human review."

File: github-backlog-triage.instructions.md

Section: Purpose and Scope (line 11)

Current: "...assigns milestones using the EVEN/ODD versioning strategy..."
Proposed: "...assigns milestones using the repository's discovered versioning strategy..."

Section: Phase 1, Step 1 — Discover Available Milestones (lines 36-46)

Current state:

Before analyzing issues, determine the current EVEN and next ODD milestones.

1. Search for recent issues with milestone assignments using
   mcp_github_search_issues to identify active milestone names.
2. Derive the current EVEN milestone and next ODD milestone from the
   discovered names.
3. Record the discovered milestones in planning-log.md for reference
   during analysis.

Proposed change — replace with the full milestone discovery protocol invocation:

Before analyzing issues, discover the repository's milestone strategy.

1. Invoke the milestone discovery protocol (defined in
   github-backlog-planning.instructions.md) to fetch, classify, and
   build the milestone assignment map.
2. Record the detected naming pattern, per-milestone role classification,
   and generated assignment map in planning-log.md.
3. When discovery confidence is low, check for .github/milestone-strategy.yml
   or prompt the user before proceeding.

Section: Milestone Recommendation (lines 171-188)

Current state — a table mapping issue characteristics to "Current EVEN (stable)" / "Next ODD (pre-release)" with rationale.

Proposed change — replace the table with role-based references:

| Issue Characteristic  | Target Milestone Role          | Rationale                            |
| --------------------- | ------------------------------ | ------------------------------------ |
| Bug fix               | stable or current              | Production fixes target the nearest
|                       |                                | stable release                       |
| Security fix          | stable or current (expedited)  | Security patches ship in the nearest
|                       |                                | stable release with expedited handling |
| New feature           | pre-release or next            | Features incubate before stable release |
| Breaking change       | pre-release or next            | Breaking changes land in development
|                       |                                | milestones only                      |

Section: Priority Assessment (lines 227+)

Current: "Assign to current EVEN milestone with expedited notation."
Proposed: "Assign to the nearest stable or current milestone with expedited notation."

Current: "Assign to current EVEN milestone. Prioritize in triage plan."
Proposed: "Assign to the nearest stable or current milestone. Prioritize in triage plan."

File: github-backlog-discovery.instructions.md

Section: Cross-References table, Milestone Conventions row (line 219)

Current: "EVEN/ODD versioning for milestone assignment"
Proposed: "Milestone role classification for milestone assignment"

Edge Case Matrix

Different versioning schemes the discovery protocol must handle correctly:

Implementation Dependencies

Phase 1 (Discovery Protocol)
  └── Phase 3 (Instruction Refactoring) depends on Phase 1
       ├── planning instructions update
       ├── triage instructions update
       └── discovery instructions update

Phase 2 (Configurable Fallback)
  └── Independent of Phase 3, but should ship before or alongside

Phase 1 can ship as a standalone addition (new section in github-backlog-planning.instructions.md) without modifying existing sections. Phase 3 requires Phase 1 to be in place so refactored sections can reference the protocol. Phase 2 is independently implementable at any point.

Migration Notes

• hve-core specifically: After Phase 3, the EVEN/ODD behavior continues to work because the discovery protocol detects SemVer naming and classifies by version parity when no stronger signals (descriptions, pre-release suffixes) are present. No milestone descriptions or configurations need to be added for hve-core to continue operating as-is.
• Other adopters: Repositories adopting hve-core's backlog tooling after this change will get correct milestone behavior automatically if they use any recognized naming pattern. Repositories with non-standard milestone names benefit from adding descriptions or a .github/milestone-strategy.yml file.
• No backward-compatibility layer: Per repository conventions, backward compatibility is not maintained — the EVEN/ODD code paths are removed entirely.

Acceptance Criteria

• A milestone discovery protocol section exists in github-backlog-planning.instructions.md that describes how to fetch, classify, and build milestone assignment maps at runtime.
• The protocol correctly classifies milestones for SemVer, SemVer with pre-release suffixes, CalVer, sprint-based, feature-based, and single-milestone repositories.
• A configurable fallback mechanism (.github/milestone-strategy.yml or user prompt) exists for repositories where automated inference yields low confidence.
• The protocol never silently defaults to EVEN/ODD assumptions — low confidence triggers user interaction or explicit configuration lookup.
• All 7 EVEN/ODD hardcoded references are removed from the three instruction files.
• The Label Taxonomy Reference "Versioning" column uses abstract role names (stable, pre-release, any) instead of parity references.
• The Milestone Conventions section describes the discovery protocol and abstract roles instead of defining EVEN/ODD categories.
• The Milestone Assignment Recommendations table maps issue characteristics to abstract roles instead of "Current EVEN" / "Next ODD".
• The triage Phase 1 Step 1 invokes the milestone discovery protocol instead of deriving "current EVEN and next ODD."
• The triage Milestone Recommendation table uses role-based references throughout.
• The triage Priority Assessment table references stable or current milestones instead of "current EVEN milestone."
• The discovery Cross-References table references "Milestone role classification" instead of "EVEN/ODD versioning."
• Existing hve-core EVEN/ODD behavior is preserved as a naturally discovered strategy — not a special case and not a hardcoded fallback.

Affected Files

Related Issues

• feat(agents): add GitHub backlog management pipeline #447 — feat(agents): add GitHub backlog management pipeline (parent feature, closed)