Standing Priority Intake: handle an empty backlog without breaking bootstrap (#911) (#912)

* Add idle queue contract to standing-priority intake (#911)

* Harden idle queue helper detection (#911)

---------

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

Author: svelderrainruiz

AGENTS.md

@@ -20,6 +20,10 @@ line buffers).
   `.agent_priority_cache.json` and `tests/results/_agent/issue/` reflect the
   latest snapshot, hook preflight succeeds, and the working tree is anchored to
   `develop`; treat that issue as the top objective for edits, CI runs, and PRs.
+  If bootstrap reports `tests/results/_agent/issue/no-standing-priority.json`
+  with `reason = queue-empty`, treat the repository as intentionally idle
+  rather than misconfigured: do not create a work branch or PR until a new
+  tracked issue exists.
   These generated priority cache/router files are intentionally untracked.
 - The human operator is signed in with an admin GitHub token; assume privileged operations (labels, reruns, merges) are
   allowed when safe.
@@ -44,7 +48,9 @@ line buffers).
      to use the published tools image instead of building locally. After the Docker fallback completes, manually verify
      the working tree is on `develop` before creating a feature branch.
   2. Review `.agent_priority_cache.json` / `tests/results/_agent/issue/` for tasks, acceptance, and
-     linked PRs on the standing issue.
+     linked PRs on the standing issue. If the cache state is `NONE` with
+     `noStandingReason = queue-empty`, stop normal standing-priority execution
+     and restore intake first by creating or labeling the next tracked issue.
   3. For cross-issue or cross-repo coordination, run
      `node tools/npm/run-script.mjs priority:project:portfolio:check` to verify the dashboard state recorded in
      `tools/priority/project-portfolio.json`. Treat the project board as a visibility layer only; issues, labels, and

docs/DEVELOPER_GUIDE.md

@@ -376,6 +376,10 @@ For Docker/Desktop VI history validation, run fast-loop lanes explicitly:
   missing or duplicate standing-priority labels fail fast and emit deterministic diagnostics:
   - `tests/results/_agent/issue/no-standing-priority.json`
   - `tests/results/_agent/issue/multiple-standing-priority.json`
+  When the repository has zero open issues, the no-standing report now records
+  `reason = queue-empty` plus `openIssueCount = 0`; that is an idle-repository
+  state, not label drift, so bootstrap and lane sync should complete without
+  forcing a synthetic standing issue.
   By default, sync does not create `.agent_priority_cache.json` on fresh clones; pass
   `--materialize-cache` (or set `AGENT_PRIORITY_MATERIALIZE_CACHE=1`) when you explicitly want cache materialization.
 - Enforce milestone hygiene for `standing-priority` / `program` / `[P0|P1]` issues with

docs/knowledgebase/FEATURE_BRANCH_POLICY.md

@@ -283,7 +283,10 @@ to confirm each workflow includes both triggers.
 - **Standing-priority lane drift** – unattended flows should run `priority:sync:lane`; this fails fast when there is no
   standing issue or when multiple issues are labeled standing-priority, and writes deterministic diagnostics:
   `tests/results/_agent/issue/no-standing-priority.json` and
-  `tests/results/_agent/issue/multiple-standing-priority.json`.
+  `tests/results/_agent/issue/multiple-standing-priority.json`. When the
+  repository is truly idle, the no-standing report uses `reason = queue-empty`
+  and `openIssueCount = 0`; agents should treat that as an intake gap, not as a
+  mislabeled standing issue.
 - **Policy drift detected by `priority:policy`** – Align GitHub settings with `tools/priority/policy.json` (update the
   JSON if the new configuration is intentional), then rerun the helper.
 - **Policy guard auth failure (`Authorization unavailable` / `authenticated-no-admin`)** – verify and rotate upstream

docs/knowledgebase/GitHub-Intake-Layer.md

@@ -55,6 +55,21 @@ The helper script derives the PR title from linked issue metadata when available
 head commit subject when necessary, and then calls `gh pr create --title ... --body-file ...` with the rendered intake
 document.
 
+## Idle Repository Mode
+
+The standing-priority intake layer now distinguishes between:
+
+- a real standing issue
+- a misconfigured standing lane (missing/duplicate labels)
+- an intentionally idle repository with zero open issues
+
+When sync writes `tests/results/_agent/issue/no-standing-priority.json` with
+`reason = queue-empty`, treat that as a first-class idle state. Bootstrap should
+complete, the router should expose `issue = null`, and helpers that open new
+standing-priority branches/PRs should stop with a clear message instead of
+inventing a null issue context. The correct next action is to create or label
+the next tracked issue, then rerun bootstrap.
+
 ## Agent Metadata Contract
 
 Automation-authored PRs still use the `Agent Metadata` block:

tools/Branch-Orchestrator.ps1

@@ -22,6 +22,43 @@ function Get-GitDefaultBranch {
   try { (& git symbolic-ref refs/remotes/origin/HEAD).Split('/')[-1] } catch { 'develop' }
 }
 
+function Read-JsonFile {
+  param([string]$Path)
+
+  if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+    return $null
+  }
+
+  try {
+    return Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -ErrorAction Stop
+  } catch {
+    return $null
+  }
+}
+
+function Get-NoStandingReason {
+  param([string]$RepoRoot)
+
+  $cachePath = Join-Path $RepoRoot '.agent_priority_cache.json'
+  $cache = Read-JsonFile -Path $cachePath
+  if ($cache -and
+    ($cache.PSObject.Properties.Name -contains 'state') -and
+    ([string]$cache.state).Trim().ToUpperInvariant() -eq 'NONE' -and
+    ($cache.PSObject.Properties.Name -contains 'noStandingReason')) {
+    $reason = ([string]$cache.noStandingReason).Trim().ToLowerInvariant()
+    if ($reason) { return $reason }
+  }
+
+  $reportPath = Join-Path $RepoRoot 'tests/results/_agent/issue/no-standing-priority.json'
+  $report = Read-JsonFile -Path $reportPath
+  if ($report -and ($report.PSObject.Properties.Name -contains 'reason')) {
+    $reason = ([string]$report.reason).Trim().ToLowerInvariant()
+    if ($reason) { return $reason }
+  }
+
+  return $null
+}
+
 function Ensure-Branch([string]$Name,[string]$Base) {
   $current = (& git rev-parse --abbrev-ref HEAD).Trim()
   if ($current -eq $Name) { return $true }
@@ -67,13 +104,34 @@ $repo = Get-RepoRoot
 if (-not $Issue) {
   # Try resolve from router/snapshot
   $snapDir = Join-Path $repo 'tests/results/_agent/issue'
+  $router = $null
   $latest = $null
   if (Test-Path -LiteralPath $snapDir -PathType Container) {
-    $latest = Get-ChildItem -LiteralPath $snapDir -Filter '*.json' | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+    $router = Read-JsonFile -Path (Join-Path $snapDir 'router.json')
+    if ($router -and ($router.PSObject.Properties.Name -contains 'issue')) {
+      [int]$routerIssue = 0
+      if ([int]::TryParse([string]$router.issue, [ref]$routerIssue) -and $routerIssue -gt 0) {
+        $Issue = $routerIssue
+      }
+    }
+    if (-not $Issue) {
+      $latest = Get-ChildItem -LiteralPath $snapDir -Filter '*.json' |
+        Where-Object { $_.BaseName -match '^\d+$' } |
+        Sort-Object LastWriteTime -Descending |
+        Select-Object -First 1
+    }
+  }
+  if (-not $Issue -and -not $latest) {
+    $noStandingReason = Get-NoStandingReason -RepoRoot $repo
+    if ($noStandingReason -eq 'queue-empty') {
+      throw 'Standing-priority queue is empty; create or label the next issue before running Branch-Orchestrator.'
+    }
+    throw 'Issue not specified and no snapshot found.'
+  }
+  if (-not $Issue) {
+    $snap = Get-Content -LiteralPath $latest.FullName -Raw | ConvertFrom-Json -ErrorAction Stop
+    $Issue = [int]$snap.number
   }
-  if (-not $latest) { throw 'Issue not specified and no snapshot found.' }
-  $snap = Get-Content -LiteralPath $latest.FullName -Raw | ConvertFrom-Json -ErrorAction Stop
-  $Issue = [int]$snap.number
 }
 
 Write-Host ("[orchestrator] Issue: #{0}" -f $Issue)

tools/Get-StandingPriority.ps1

@@ -20,7 +20,12 @@ function Write-OutputObject {
       $title = if ($Priority.title) { $Priority.title } else { '(no title)' }
       Write-Output ("#{0} — {1}" -f $Priority.number, $title)
     } else {
-      Write-Output 'Standing priority not set'
+      $reason = if ($Priority.PSObject.Properties.Name -contains 'reason') { [string]$Priority.reason } else { $null }
+      if ($reason -eq 'queue-empty') {
+        Write-Output 'Standing priority not set (queue empty)'
+      } else {
+        Write-Output 'Standing priority not set'
+      }
     }
   } else {
     $Priority | ConvertTo-Json -Depth 5 | Write-Output
@@ -33,6 +38,8 @@ function Normalize-PriorityObject {
     [string]$Title,
     [string]$Url,
     [string]$Source,
+    [string]$State,
+    [string]$Reason,
     [object]$Sequence,
     [object]$Next
   )
@@ -46,6 +53,8 @@ function Normalize-PriorityObject {
     title = $cleanTitle
     url = $cleanUrl
     source = $Source
+    state = $State
+    reason = $Reason
     retrievedAtUtc = (Get-Date -AsUTC).ToString('o')
   }
   if ($null -ne $Sequence) { $obj.sequence = $Sequence }
@@ -76,7 +85,7 @@ function Parse-OverrideValue {
       $url = if ($obj.PSObject.Properties.Name -contains 'url') { [string]$obj.url } else { $null }
       $seq = if ($obj.PSObject.Properties.Name -contains 'sequence') { $obj.sequence } else { $null }
       $nxt = if ($obj.PSObject.Properties.Name -contains 'next') { $obj.next } else { $null }
-      return Normalize-PriorityObject -Number $num -Title $title -Url $url -Source 'override' -Sequence $seq -Next $nxt
+      return Normalize-PriorityObject -Number $num -Title $title -Url $url -Source 'override' -State $null -Reason $null -Sequence $seq -Next $nxt
     } catch {
       return $null
     }
@@ -88,7 +97,7 @@ function Parse-OverrideValue {
   $number = [int]$rawNumber
   $title = if ($parts.Count -gt 1 -and $parts[1]) { $parts[1].Trim() } else { $null }
   $url = if ($parts.Count -gt 2 -and $parts[2]) { $parts[2].Trim() } else { $null }
-  return Normalize-PriorityObject -Number $number -Title $title -Url $url -Source 'override'
+  return Normalize-PriorityObject -Number $number -Title $title -Url $url -Source 'override' -State $null -Reason $null
 }
 
 function Try-LoadCache {
@@ -125,7 +134,9 @@ function Try-LoadCache {
 
       $seq = $null; if ($cacheObj.PSObject.Properties.Name -contains 'sequence') { $seq = $cacheObj.sequence }
       $nxt = $null; if ($cacheObj.PSObject.Properties.Name -contains 'next') { $nxt = $cacheObj.next }
-      return Normalize-PriorityObject -Number $cacheNumber -Title $cacheTitle -Url $cacheUrl -Source 'cache' -Sequence $seq -Next $nxt
+      $cacheState = if ($cacheObj.PSObject.Properties.Name -contains 'state') { [string]$cacheObj.state } else { $null }
+      $cacheReason = if ($cacheObj.PSObject.Properties.Name -contains 'noStandingReason') { [string]$cacheObj.noStandingReason } else { $null }
+      return Normalize-PriorityObject -Number $cacheNumber -Title $cacheTitle -Url $cacheUrl -Source 'cache' -State $cacheState -Reason $cacheReason -Sequence $seq -Next $nxt
     }
   } catch {}
   return $null
@@ -200,7 +211,7 @@ function Try-GitHubPriority {
     }
     $title = if ($chosen.PSObject.Properties.Name -contains 'title') { [string]$chosen.title } else { $null }
     $url = if ($chosen.PSObject.Properties.Name -contains 'url') { [string]$chosen.url } else { $null }
-    return Normalize-PriorityObject -Number $num -Title $title -Url $url -Source 'github' -Sequence $Sequence
+    return Normalize-PriorityObject -Number $num -Title $title -Url $url -Source 'github' -State 'OPEN' -Reason $null -Sequence $Sequence
   } catch {
     return $null
   }
@@ -216,7 +227,7 @@ if ($overrideValue) {
   $priority = Parse-OverrideValue -Override $overrideValue
   # If override didn't include sequence but cache has one, carry it along
   if ($priority -and -not ($priority.PSObject.Properties.Name -contains 'sequence') -and $cacheCandidate -and ($cacheCandidate.PSObject.Properties.Name -contains 'sequence')) {
-    $priority = Normalize-PriorityObject -Number $priority.number -Title $priority.title -Url $priority.url -Source $priority.source -Sequence $cacheCandidate.sequence -Next ($cacheCandidate.next)
+    $priority = Normalize-PriorityObject -Number $priority.number -Title $priority.title -Url $priority.url -Source $priority.source -State $priority.state -Reason $priority.reason -Sequence $cacheCandidate.sequence -Next ($cacheCandidate.next)
   }
 }
 

tools/priority/__tests__/create-pr.test.mjs

@@ -5,6 +5,8 @@ import assert from 'node:assert/strict';
 import {
   parseRouterIssueNumber,
   parseCacheIssueNumber,
+  parseCacheNoStandingReason,
+  parseNoStandingReasonFromReport,
   resolveStandingIssueNumberForPr,
   parseIssueNumberFromBranch,
   assertBranchMatchesIssue,
@@ -58,6 +60,40 @@ test('parseCacheIssueNumber rejects closed or non-standing cache entries', () =>
   );
 });
 
+test('parseCacheNoStandingReason exposes queue-empty idle cache state', () => {
+  assert.equal(
+    parseCacheNoStandingReason({
+      state: 'NONE',
+      noStandingReason: 'queue-empty'
+    }),
+    'queue-empty'
+  );
+  assert.equal(
+    parseCacheNoStandingReason({
+      state: 'OPEN',
+      noStandingReason: 'queue-empty'
+    }),
+    null
+  );
+});
+
+test('parseNoStandingReasonFromReport exposes queue-empty from the no-standing artifact', () => {
+  assert.equal(
+    parseNoStandingReasonFromReport({
+      schema: 'standing-priority/no-standing@v1',
+      reason: 'queue-empty'
+    }),
+    'queue-empty'
+  );
+  assert.equal(
+    parseNoStandingReasonFromReport({
+      schema: 'other/schema',
+      reason: 'queue-empty'
+    }),
+    null
+  );
+});
+
 test('resolveStandingIssueNumberForPr prefers router over cache', () => {
   const result = resolveStandingIssueNumberForPr('/tmp/repo', {
     readJsonFn: (filePath) => {
@@ -72,7 +108,7 @@ test('resolveStandingIssueNumberForPr prefers router over cache', () => {
     }
   });
 
-  assert.deepEqual(result, { issueNumber: 680, source: 'router' });
+  assert.deepEqual(result, { issueNumber: 680, source: 'router', noStandingReason: null });
 });
 
 test('resolveStandingIssueNumberForPr treats explicit empty router issue as authoritative', () => {
@@ -81,15 +117,21 @@ test('resolveStandingIssueNumberForPr treats explicit empty router issue as auth
       if (filePath.endsWith('router.json')) {
         return { issue: null };
       }
+      if (filePath.endsWith('no-standing-priority.json')) {
+        return {
+          schema: 'standing-priority/no-standing@v1',
+          reason: 'queue-empty'
+        };
+      }
       return {
         number: 680,
-        state: 'open',
-        labels: ['standing-priority']
+        state: 'NONE',
+        labels: []
       };
     }
   });
 
-  assert.deepEqual(result, { issueNumber: null, source: 'router' });
+  assert.deepEqual(result, { issueNumber: null, source: 'router', noStandingReason: 'queue-empty' });
 });
 
 test('resolveStandingIssueNumberForPr falls back to cache when router is unavailable', () => {
@@ -106,7 +148,27 @@ test('resolveStandingIssueNumberForPr falls back to cache when router is unavail
     }
   });
 
-  assert.deepEqual(result, { issueNumber: 680, source: 'cache' });
+  assert.deepEqual(result, { issueNumber: 680, source: 'cache', noStandingReason: null });
+});
+
+test('createPriorityPr refuses to open a priority PR when the standing queue is empty', () => {
+  assert.throws(
+    () =>
+      createPriorityPr({
+        env: {},
+        getRepoRootFn: () => '/tmp/repo',
+        getCurrentBranchFn: () => 'feature/manual-follow-up',
+        ensureGhCliFn: () => {},
+        resolveUpstreamFn: () => ({ owner: 'upstream-owner', repo: 'repo' }),
+        ensureOriginForkFn: () => ({ owner: 'fork-owner', repo: 'repo' }),
+        pushBranchFn: () => {},
+        runGhPrCreateFn: () => {
+          throw new Error('should not create PR');
+        },
+        resolveStandingIssueNumberFn: () => ({ issueNumber: null, source: 'router', noStandingReason: 'queue-empty' })
+      }),
+    /Standing-priority queue is empty/i
+  );
 });
 
 test('parseIssueNumberFromBranch extracts issue numbers from issue/* branches', () => {

tools/priority/__tests__/github-intake-contract.test.mjs

@@ -64,17 +64,21 @@ test('github intake docs and manifest reference the new helper layer', () => {
   const automationGuide = readText('docs/knowledgebase/GitHub-Wiki-Portal-Automation-Evaluation.md');
   const wikiGuide = readText('docs/knowledgebase/GitHub-Wiki-Portal.md');
   const orchestrator = readText('tools/Branch-Orchestrator.ps1');
+  const getStandingPriority = readText('tools/Get-StandingPriority.ps1');
   const intakeModule = readText('tools/GitHubIntake.psm1');
   const oneButtonValidate = readText('tools/Run-OneButtonValidate.ps1');
 
   assert.match(snippets, /New-IssueBody\.ps1/);
   assert.match(snippets, /Branch-Orchestrator\.ps1/);
   assert.match(agents, /New-IssueBody\.ps1/);
   assert.match(agents, /GitHub wiki as a curated portal only/);
+  assert.match(agents, /queue-empty/);
   assert.match(readme, /compare-vi-cli-action\/wiki/);
   assert.match(agents, /-PRTemplate workflow-policy\|human-change/);
   assert.match(intakeGuide, /New-PullRequestBody\.ps1/);
   assert.match(intakeGuide, /GitHub-Wiki-Portal\.md/);
+  assert.match(intakeGuide, /Idle Repository Mode/);
+  assert.match(intakeGuide, /reason = queue-empty/);
   assert.match(intakeGuide, /gh pr create --title "<title>" --body-file pr-body\.md/);
   assert.match(automationGuide, /Keep manual curation for now/);
   assert.match(automationGuide, /compare-vi-cli-action\.wiki\.git/);
@@ -85,6 +89,10 @@ test('github intake docs and manifest reference the new helper layer', () => {
   assert.match(orchestrator, /'pr'\s+'create'\s+'--title'/);
   assert.match(orchestrator, /'pr'\s+'view'\s+\$branchName\s+'--json'\s+'number'/);
   assert.match(orchestrator, /'pr'\s+'edit'\s+\$pr\.number\s+'--title'\s+\$prTitle\s+'--body-file'/);
+  assert.match(orchestrator, /Standing-priority queue is empty/);
+  assert.match(orchestrator, /router\.json/);
+  assert.match(orchestrator, /no-standing-priority\.json/);
+  assert.match(getStandingPriority, /Standing priority not set \(queue empty\)/);
   assert.doesNotMatch(orchestrator, /'pr'\s+'create'\s+'--fill(?:-first)?'/);
   assert.doesNotMatch(orchestrator, /'pr'\s+'view'\s+'--json'\s+'number'\s+'--head'/);
   assert.match(oneButtonValidate, /gh pr view \$branch --json number/);

tools/priority/__tests__/project-portfolio-config.test.mjs

@@ -22,7 +22,7 @@ test('project portfolio config item URLs are unique and cover the tracked portfo
   const parsedUrls = config.items.map((item) => new URL(item.url));
   const urlStrings = parsedUrls.map((item) => item.toString());
   assert.equal(new Set(urlStrings).size, urlStrings.length);
-  assert.equal(parsedUrls.length, 28);
+  assert.equal(parsedUrls.length, 29);
 
   const issueCoordinates = new Set(
     parsedUrls.map((item) => {
@@ -48,6 +48,7 @@ test('project portfolio config item URLs are unique and cover the tracked portfo
   assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/compare-vi-cli-action#904'));
   assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/compare-vi-cli-action#906'));
   assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/compare-vi-cli-action#907'));
+  assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/compare-vi-cli-action#911'));
   assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/comparevi-history#14'));
   assert.ok(issueCoordinates.has('LabVIEW-Community-CI-CD/comparevi-history#15'));
 });