feat: enforce maximum of 5 completed Good First Issues per contributor (#1286)

Signed-off-by: Rob Walworth <robert.walworth@swirldslabs.com>

Author: rwalworth

.github/scripts/commands/assign-comments.js

@@ -14,6 +14,13 @@ const { MAINTAINER_TEAM, LABELS, ISSUE_STATE } = require('../helpers');
  */
 const MAX_OPEN_ASSIGNMENTS = 2;
 
+/**
+ * Maximum number of Good First Issues a contributor may complete before being
+ * redirected to Beginner and higher-level issues. Enforced by handleAssign in assign.js.
+ * @type {number}
+ */
+const MAX_GFI_COMPLETIONS = 5;
+
 /**
  * Skill-level prerequisite map. Each key is a LABELS skill-level constant.
  * - requiredLabel: the prerequisite skill label the user must have completed, or null if none.
@@ -323,6 +330,32 @@ function buildLabelUpdateFailureComment(username, error) {
   ].join('\n');
 }
 
+/**
+ * Builds the comment posted when a contributor has already completed the maximum
+ * number of Good First Issues (MAX_GFI_COMPLETIONS). Rejects the assignment
+ * warmly and redirects them toward Beginner and higher-level issues.
+ *
+ * @param {string} requesterUsername - The GitHub username who commented /assign.
+ * @param {number} completedCount - How many Good First Issues the user has completed.
+ * @param {string} owner - Repository owner (for the search URL).
+ * @param {string} repo - Repository name (for the search URL).
+ * @returns {string} The formatted Markdown comment body.
+ */
+function buildGfiLimitExceededComment(requesterUsername, completedCount, owner, repo) {
+  const searchQuery = `is:issue is:open no:assignee label:"${LABELS.BEGINNER}" label:"${LABELS.READY_FOR_DEV}"`;
+  const searchUrl = buildIssuesSearchUrl(owner, repo, searchQuery);
+  return [
+    `👋 Hi @${requesterUsername}! You've completed **${completedCount} Good First Issues** — that's a fantastic achievement, and it shows you know the workflow inside and out. 🎉`,
+    '',
+    'Good First Issues are designed to help new contributors get comfortable with the process, and you\'ve clearly mastered it. We believe you\'re more than ready to take on bigger challenges!',
+    '',
+    '👉 **Find Beginner and higher issues to work on:**',
+    `[Browse available Beginner issues](${searchUrl})`,
+    '',
+    'Come take on something more challenging — we\'re excited to see what you\'ll build next! 🚀',
+  ].join('\n');
+}
+
 /**
  * Builds the comment posted when the addAssignees API call itself fails.
  * Tags the maintainer team to manually assign the user and includes the error details.
@@ -343,6 +376,7 @@ function buildAssignmentFailureComment(requesterUsername, error) {
 
 module.exports = {
   MAX_OPEN_ASSIGNMENTS,
+  MAX_GFI_COMPLETIONS,
   SKILL_HIERARCHY,
   SKILL_PREREQUISITES,
   buildWelcomeComment,
@@ -351,6 +385,7 @@ module.exports = {
   buildPrerequisiteNotMetComment,
   buildNoSkillLevelComment,
   buildAssignmentLimitExceededComment,
+  buildGfiLimitExceededComment,
   buildApiErrorComment,
   buildLabelUpdateFailureComment,
   buildAssignmentFailureComment,

.github/scripts/commands/assign.js

@@ -22,6 +22,7 @@ const {
 
 const {
   MAX_OPEN_ASSIGNMENTS,
+  MAX_GFI_COMPLETIONS,
   SKILL_HIERARCHY,
   SKILL_PREREQUISITES,
   buildWelcomeComment,
@@ -30,6 +31,7 @@ const {
   buildPrerequisiteNotMetComment,
   buildNoSkillLevelComment,
   buildAssignmentLimitExceededComment,
+  buildGfiLimitExceededComment,
   buildApiErrorComment,
   buildLabelUpdateFailureComment,
   buildAssignmentFailureComment,
@@ -221,6 +223,42 @@ async function updateLabels(botContext, requesterUsername) {
   }
 }
 
+/**
+ * Checks whether the requester has reached the GFI completion cap. Only applies
+ * when skillLevel is LABELS.GOOD_FIRST_ISSUE. Posts an encouraging comment and
+ * returns false when the cap is reached; returns true otherwise.
+ *
+ * @param {object} botContext - Bot context from buildBotContext.
+ * @param {string} skillLevel - The skill-level label on the issue (a LABELS constant).
+ * @param {string} requesterUsername - GitHub username requesting assignment.
+ * @returns {Promise<boolean>} True if under the cap or not a GFI; false otherwise.
+ */
+async function enforceGfiCompletionLimit(botContext, skillLevel, requesterUsername) {
+  if (skillLevel !== LABELS.GOOD_FIRST_ISSUE) return true;
+
+  const completedCount = await countAssignedIssues(
+    botContext.github, botContext.owner, botContext.repo,
+    requesterUsername, ISSUE_STATE.CLOSED, LABELS.GOOD_FIRST_ISSUE
+  );
+  if (completedCount === null) {
+    logger.log('Exit: could not verify GFI completion count due to API error');
+    await postComment(botContext, buildApiErrorComment(requesterUsername));
+    logger.log('Posted API error comment, tagged maintainers');
+    return false;
+  }
+  if (completedCount >= MAX_GFI_COMPLETIONS) {
+    logger.log('Exit: contributor has reached GFI completion cap', {
+      maxAllowed: MAX_GFI_COMPLETIONS, completedCount,
+    });
+    await postComment(botContext,
+      buildGfiLimitExceededComment(requesterUsername, completedCount, botContext.owner, botContext.repo));
+    logger.log('Posted GFI-limit-exceeded comment');
+    return false;
+  }
+  logger.log('GFI completion count OK:', { maxAllowed: MAX_GFI_COMPLETIONS, completedCount });
+  return true;
+}
+
 /**
  * Validates that the issue is in a state that allows assignment. Checks three
  * gates in order: no existing assignees, "status: ready for dev" label present,
@@ -327,6 +365,7 @@ async function assignAndFinalize(botContext, requesterUsername, skillLevel) {
  *   4. No skill-level label? -> no-skill-level comment (tags maintainers).
  *   5. Open-assignment count API error? -> API-error comment (tags maintainers).
  *   6. At or above MAX_OPEN_ASSIGNMENTS? -> limit-exceeded comment.
+ *   6b. GFI cap reached (skill: good first issue only)? -> GFI-limit-exceeded comment.
  *   7. Skill prerequisites not met? -> prerequisite-not-met comment.
  *   8. Assignment API failure? -> assignment-failure comment (tags maintainers).
  *
@@ -349,6 +388,9 @@ async function handleAssign(botContext) {
   const withinLimit = await enforceAssignmentLimit(botContext, requesterUsername);
   if (!withinLimit) return;
 
+  const withinGfiCap = await enforceGfiCompletionLimit(botContext, skillLevel, requesterUsername);
+  if (!withinGfiCap) return;
+
   const prereqsPassed = await checkPrerequisites(botContext, skillLevel, requesterUsername);
   if (!prereqsPassed) return;
 

.github/scripts/tests/test-assign-bot.js

@@ -352,6 +352,107 @@ Good luck! 🚀`,
     ],
   },
 
+  // ---------------------------------------------------------------------------
+  // GFI COMPLETION CAP TESTS (3 tests)
+  // Gate added in enforceGfiCompletionLimit
+  // ---------------------------------------------------------------------------
+
+  {
+    name: 'GFI Cap - Exactly At Limit (5 Completed)',
+    description: 'Contributor with 5 completed GFIs is rejected with encouraging redirect',
+    context: {
+      eventName: 'issue_comment',
+      payload: {
+        issue: {
+          number: 300,
+          assignees: [],
+          labels: [
+            { name: 'status: ready for dev' },
+            { name: 'skill: good first issue' },
+          ],
+        },
+        comment: { id: 3001, body: '/assign', user: { login: 'veteran-gfi-user', type: 'User' } },
+      },
+      repo: { owner: 'hiero-ledger', repo: 'hiero-sdk-cpp' },
+    },
+    githubOptions: { completedIssueCounts: { [LABELS.GOOD_FIRST_ISSUE]: 5 } },
+    expectedAssignee: null,
+    expectedComments: [
+      `👋 Hi @veteran-gfi-user! You've completed **5 Good First Issues** — that's a fantastic achievement, and it shows you know the workflow inside and out. 🎉
+
+Good First Issues are designed to help new contributors get comfortable with the process, and you've clearly mastered it. We believe you're more than ready to take on bigger challenges!
+
+👉 **Find Beginner and higher issues to work on:**
+[Browse available Beginner issues](https://github.com/hiero-ledger/hiero-sdk-cpp/issues?q=is%3Aissue%20is%3Aopen%20no%3Aassignee%20label%3A%22skill%3A%20beginner%22%20label%3A%22status%3A%20ready%20for%20dev%22)
+
+Come take on something more challenging — we're excited to see what you'll build next! 🚀`,
+    ],
+  },
+
+  {
+    name: 'GFI Cap - Below Limit (4 Completed)',
+    description: 'Contributor with 4 completed GFIs is still allowed to take another GFI',
+    context: {
+      eventName: 'issue_comment',
+      payload: {
+        issue: {
+          number: 301,
+          assignees: [],
+          labels: [
+            { name: 'status: ready for dev' },
+            { name: 'skill: good first issue' },
+          ],
+        },
+        comment: { id: 3002, body: '/assign', user: { login: 'almost-capped-user', type: 'User' } },
+      },
+      repo: { owner: 'hiero-ledger', repo: 'hiero-sdk-cpp' },
+    },
+    githubOptions: { completedIssueCounts: { [LABELS.GOOD_FIRST_ISSUE]: 4 } },
+    expectedAssignee: 'almost-capped-user',
+    expectedComments: [
+      `👋 Hi @almost-capped-user, welcome to the Hiero C++ SDK community! Thank you for choosing to contribute — we're thrilled to have you here! 🎉
+
+You've been assigned this **Good First Issue**, and the **Good First Issue Support Team** (@hiero-ledger/hiero-sdk-good-first-issue-support) is ready to help you succeed.
+
+The issue description above has everything you need: implementation steps, contribution workflow, and links to guides. If anything is unclear, just ask — we're happy to help.
+
+If you realize you cannot complete this issue, simply comment \`/unassign\` to return it to the community pool.
+
+Good luck, and welcome aboard! 🚀`,
+    ],
+  },
+
+  {
+    name: 'GFI Cap - Does Not Apply to Beginner Issues',
+    description: 'Contributor with 5 completed GFIs can still take a Beginner issue',
+    context: {
+      eventName: 'issue_comment',
+      payload: {
+        issue: {
+          number: 302,
+          assignees: [],
+          labels: [
+            { name: 'status: ready for dev' },
+            { name: 'skill: beginner' },
+          ],
+        },
+        comment: { id: 3003, body: '/assign', user: { login: 'gfi-graduated-user', type: 'User' } },
+      },
+      repo: { owner: 'hiero-ledger', repo: 'hiero-sdk-cpp' },
+    },
+    githubOptions: { completedIssueCounts: { [LABELS.GOOD_FIRST_ISSUE]: 5 } },
+    expectedAssignee: 'gfi-graduated-user',
+    expectedComments: [
+      `👋 Hi @gfi-graduated-user, thanks for continuing to contribute to the Hiero C++ SDK! You've been assigned this **Beginner** issue. 🙌
+
+If this task involves any design decisions or you'd like early feedback, feel free to share your plan here before diving into the code.
+
+If you realize you cannot complete this issue, simply comment \`/unassign\` to return it to the pool.
+
+Good luck! 🚀`,
+    ],
+  },
+
   // ---------------------------------------------------------------------------
   // VALIDATION FAILURES (9 tests)
   // Bot rejects assignment with helpful message