gitlink-cli/docs/issue-batch-design.md

Issue Batch Maintenance Design

Background

This change adds focused Issue batch maintenance shortcuts for GitLink CLI. The goal is to improve practical Issue management while keeping remote write operations explicit and guarded.

Commands

issue +batch-list

Lists candidate issues for batch maintenance. This command is read-only.

Supported filters:

• --state, default open
• --label
• --older-than-days
• --limit, capped at 100

issue +batch-close

Closes filtered issues in bulk. The command defaults to dry-run mode and only executes remote close operations when --yes is passed.

Safety guards:

• requires --older-than-days
• rejects values lower than 7
• caps --limit at 100
• records per-issue failures without hiding partial errors

issue +batch-label

Previews adding a label to filtered issues. It requires --add-label and defaults to dry-run mode. The current implementation does not fake remote label writes when a stable add-label API endpoint is unavailable.

Data Model

BatchIssueCandidate is the stable item DTO for candidate issues:

• number
• title
• state
• labels
• author
• updated_at
• days_inactive
• url

BatchIssueResult wraps the command result with:

• dry_run
• action
• total
• success
• failed
• candidates
• errors

API Strategy

The implementation reuses the existing shortcut runtime:

• RuntimeContext.ResolveOwnerRepo
• RuntimeContext.CallAPIWithQuery
• RuntimeContext.CallAPI
• existing /v1/{owner}/{repo}/issues paths

issue +batch-close --yes uses the existing issue close behavior: fetch the current issue details first, then patch status_id to the closed status while preserving title and description.

issue +batch-label --yes currently reports that the remote write endpoint is unavailable instead of pretending to mutate labels.

Output

The batch shortcuts support:

• table
• json

Table output is optimized for terminal review. JSON output is stable enough for scripts and agents.

Scope

This PR does not modify internal/output, does not introduce dependencies, and does not add unrelated workflow-agent functionality.