Issue Milestone Hygiene: restore GH_TOKEN-backed evaluation and failure reporting (#907) (#910)

* Restore milestone hygiene auth and failure reports (#907)

* Normalize milestone hygiene fallback inputs (#907)

---------

Co-authored-by: GitHub Copilot <copilot@users.noreply.github.com>

Author: svelderrainruiz

.github/workflows/issue-milestone-hygiene.yml

@@ -38,6 +38,10 @@ on:
         default: false
         type: boolean
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.issue.number || github.ref || github.run_id }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
   issues: write
@@ -53,6 +57,8 @@ jobs:
         shell: bash
         env:
           REPO_SLUG: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN || github.token }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN || github.token }}
           APPLY_INPUT: ${{ inputs.apply_default_milestone }}
           CREATE_INPUT: ${{ inputs.create_default_milestone }}
           DEFAULT_INPUT: ${{ inputs.default_milestone }}
@@ -133,12 +139,17 @@ jobs:
           const remaining = report.summary?.remainingViolationCount ?? 0;
           const lines = [
             '## Issue Milestone Hygiene',
+            `- execution status: \`${report.execution?.status ?? 'unknown'}\``,
             `- remaining violations: \`${remaining}\``,
             `- required issues evaluated: \`${report.summary?.requiredIssueCount ?? 0}\``,
             `- auto-assigned this run: \`${report.summary?.assignedDefaultMilestoneCount ?? 0}\``,
             `- failed assignments: \`${report.summary?.failedAssignmentsCount ?? 0}\``,
             `- default milestone created this run: \`${report.milestones?.createdDefaultMilestone ?? false}\``
           ];
+          const errors = Array.isArray(report.execution?.errors) ? report.execution.errors : [];
+          if (errors.length > 0) {
+            lines.push(`- execution errors: \`${errors.length}\``);
+          }
           if (process.env.GITHUB_STEP_SUMMARY) {
             fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${lines.join('\\n')}\\n`);
           }
@@ -151,4 +162,4 @@ jobs:
         with:
           name: issue-milestone-hygiene-report
           path: tests/results/_agent/issue/milestone-hygiene-report.json
-          if-no-files-found: warn
+          if-no-files-found: error

docs/schemas/issue-milestone-hygiene-report-v1.schema.json

@@ -10,6 +10,7 @@
     "generatedAt",
     "repository",
     "state",
+    "execution",
     "flags",
     "policy",
     "milestones",
@@ -35,6 +36,21 @@
     "state": {
       "enum": ["open", "all"]
     },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "errors"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pass", "warn", "fail", "error"]
+        },
+        "errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "flags": {
       "type": "object",
       "additionalProperties": false,

tools/priority/__tests__/issue-milestone-hygiene-schema.test.mjs

@@ -9,7 +9,7 @@ import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
-import { runMilestoneHygiene } from '../check-issue-milestones.mjs';
+import { runMilestoneHygiene, runMilestoneHygieneWithFailureReport } from '../check-issue-milestones.mjs';
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -93,7 +93,47 @@ test('issue milestone hygiene schema validates generated report and asserts labe
 
   assert.equal(report.flags.createDefaultMilestone, true);
   assert.equal(report.flags.applyDefaultMilestone, true);
+  assert.equal(report.execution.status, 'pass');
   assert.equal(report.policy.requiredLabels.includes('program'), true);
   assert.equal(report.reconciliations[0].triggers.includes('label:program'), true);
   assert.equal(report.summary.triggerCounts['label:program'], 1);
 });
+
+test('issue milestone hygiene schema validates generated error report when evaluation aborts early', async () => {
+  const schemaPath = path.join(repoRoot, 'docs', 'schemas', 'issue-milestone-hygiene-report-v1.schema.json');
+  const schema = JSON.parse(await readFile(schemaPath, 'utf8'));
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'milestone-hygiene-error-schema-'));
+  const outputPath = path.join(tmpDir, 'report.json');
+
+  const result = await runMilestoneHygieneWithFailureReport({
+    argv: ['--repo', 'example/repo', '--report', outputPath],
+    now: new Date('2026-03-06T12:00:00Z'),
+    loadPolicyFn: async () => ({
+      path: path.join(repoRoot, 'tools', 'policy', 'issue-milestone-hygiene.json'),
+      required: {
+        labels: ['standing-priority', 'program'],
+        titlePriorityPattern: String.raw`\[(P0|P1)\]`,
+        requireOpenMilestone: true
+      },
+      defaultMilestone: null,
+      defaultMilestoneDueOn: null,
+      warnOnly: false,
+      createDefaultMilestone: false
+    }),
+    runGhJsonFn: () => {
+      throw new Error('gh issue list failed: gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable.');
+    }
+  });
+
+  assert.equal(result.exitCode, 1);
+
+  const report = JSON.parse(await readFile(outputPath, 'utf8'));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  const valid = validate(report);
+  assert.equal(valid, true, JSON.stringify(validate.errors, null, 2));
+  assert.equal(report.execution.status, 'error');
+  assert.equal(report.summary.issueCount, 0);
+});

tools/priority/__tests__/issue-milestone-hygiene-workflow-contract.test.mjs

@@ -20,6 +20,8 @@ test('issue milestone hygiene workflow has deterministic trigger and artifact co
   assert.match(workflow, /-\s*demilestoned/);
   assert.match(workflow, /schedule:\s*\n\s*-\s*cron:\s*'25 \* \* \* \*'/);
   assert.match(workflow, /workflow_dispatch:/);
+  assert.match(workflow, /concurrency:\s*\n\s*group:\s+\$\{\{\s*github\.workflow\s*\}\}-\$\{\{\s*github\.event_name\s*\}\}-\$\{\{\s*github\.event\.issue\.number \|\| github\.ref \|\| github\.run_id\s*\}\}/);
+  assert.match(workflow, /cancel-in-progress:\s+true/);
 
   assert.match(workflow, /apply_default_milestone:/);
   assert.match(workflow, /create_default_milestone:/);
@@ -28,9 +30,13 @@ test('issue milestone hygiene workflow has deterministic trigger and artifact co
   assert.match(workflow, /warn_only:/);
 
   assert.match(workflow, /issues:\s*write/);
+  assert.match(workflow, /GITHUB_TOKEN:\s+\$\{\{\s*secrets\.GH_TOKEN \|\| secrets\.GITHUB_TOKEN \|\| github\.token\s*\}\}/);
+  assert.match(workflow, /GH_TOKEN:\s+\$\{\{\s*secrets\.GH_TOKEN \|\| secrets\.GITHUB_TOKEN \|\| github\.token\s*\}\}/);
   assert.match(workflow, /priority:milestone:hygiene/);
   assert.match(workflow, /--create-default-milestone/);
   assert.match(workflow, /--default-milestone-due-on/);
   assert.match(workflow, /tests\/results\/_agent\/issue\/milestone-hygiene-report\.json/);
+  assert.match(workflow, /execution status/);
   assert.match(workflow, /uses:\s+actions\/upload-artifact@v5/);
+  assert.match(workflow, /if-no-files-found:\s+error/);
 });

tools/priority/__tests__/issue-milestone-hygiene.test.mjs

@@ -8,7 +8,8 @@ import {
   parseArgs,
   normalizePolicy,
   evaluateIssue,
-  runMilestoneHygiene
+  runMilestoneHygiene,
+  runMilestoneHygieneWithFailureReport
 } from '../check-issue-milestones.mjs';
 
 function makeRunGhJson({ issues = [], milestones = [], createdMilestone = null, calls = [] } = {}) {
@@ -124,6 +125,8 @@ test('runMilestoneHygiene fails when required issues have no milestone and emits
   });
 
   assert.equal(result.exitCode, 1);
+  assert.equal(result.report.execution.status, 'fail');
+  assert.deepEqual(result.report.execution.errors, []);
   assert.equal(result.report.flags.requireOpenMilestone, true);
   assert.equal(result.report.summary.remainingViolationCount, 1);
   assert.equal(result.report.summary.triggerCounts['title-priority'], 1);
@@ -173,6 +176,7 @@ test('runMilestoneHygiene assigns default milestone in apply mode', async () =>
   });
 
   assert.equal(result.exitCode, 0);
+  assert.equal(result.report.execution.status, 'pass');
   assert.equal(result.report.summary.initialViolationCount, 1);
   assert.equal(result.report.summary.remainingViolationCount, 0);
   assert.equal(result.report.summary.assignedDefaultMilestoneCount, 1);
@@ -242,6 +246,7 @@ test('runMilestoneHygiene creates missing default milestone when requested', asy
   });
 
   assert.equal(result.exitCode, 0);
+  assert.equal(result.report.execution.status, 'pass');
   assert.equal(result.report.milestones.createdDefaultMilestone, true);
   assert.equal(result.report.policy.defaultMilestoneDueOn, '2026-06-30T00:00:00Z');
   assert.equal(result.report.summary.assignedDefaultMilestoneCount, 1);
@@ -279,3 +284,73 @@ test('runMilestoneHygiene rejects closed default milestone in strict mode', asyn
     /closed/
   );
 });
+
+test('runMilestoneHygieneWithFailureReport emits an error report when gh evaluation fails early', async () => {
+  const writes = [];
+  const result = await runMilestoneHygieneWithFailureReport({
+    argv: ['--repo', 'example/repo', '--report', 'tests/results/_agent/issue/milestone-hygiene-report.json'],
+    loadPolicyFn: async () => ({
+      path: path.join(process.cwd(), 'tools', 'policy', 'issue-milestone-hygiene.json'),
+      required: {
+        labels: ['standing-priority', 'program'],
+        titlePriorityPattern: String.raw`\[(P0|P1)\]`,
+        requireOpenMilestone: true
+      },
+      defaultMilestone: null,
+      defaultMilestoneDueOn: null,
+      warnOnly: false,
+      createDefaultMilestone: false
+    }),
+    runGhJsonFn: () => {
+      throw new Error(
+        'gh issue list --repo example/repo failed: gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable.'
+      );
+    },
+    writeJsonReportFn: async (reportPath, payload) => {
+      writes.push({ reportPath, payload });
+      return reportPath;
+    }
+  });
+
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.report.execution.status, 'error');
+  assert.match(result.report.execution.errors[0], /GH_TOKEN environment variable/i);
+  assert.equal(result.report.summary.issueCount, 0);
+  assert.equal(writes.length, 1);
+});
+
+test('runMilestoneHygieneWithFailureReport normalizes invalid fallback state and due date values', async () => {
+  const result = await runMilestoneHygieneWithFailureReport({
+    argv: [
+      '--repo',
+      'example/repo',
+      '--report',
+      'tests/results/_agent/issue/milestone-hygiene-report.json',
+      '--state',
+      'All',
+      '--default-milestone-due-on',
+      'not-a-date'
+    ],
+    loadPolicyFn: async () => ({
+      path: path.join(process.cwd(), 'tools', 'policy', 'issue-milestone-hygiene.json'),
+      required: {
+        labels: ['standing-priority', 'program'],
+        titlePriorityPattern: String.raw`\[(P0|P1)\]`,
+        requireOpenMilestone: true
+      },
+      defaultMilestone: null,
+      defaultMilestoneDueOn: null,
+      warnOnly: false,
+      createDefaultMilestone: false
+    }),
+    runGhJsonFn: () => {
+      throw new Error('simulated gh auth failure');
+    },
+    writeJsonReportFn: async (reportPath, payload) => ({ reportPath, payload })
+  });
+
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.report.state, 'all');
+  assert.equal(result.report.policy.defaultMilestoneDueOn, null);
+  assert.ok(result.report.execution.errors.some((entry) => /default milestone due date/i.test(entry)));
+});