Add read-only feature map command UX

[StatPan]

Goal

Add the first issue-backed feature map UX to Gira so operators and agents can inspect optional capability/feature map records without requiring every managed repository to generate docs.

Context

The product direction from StatPan/backlog#26 is to treat feature maps as optional GitHub issue-backed capability maps. GitHub issues remain the source of truth, GitHub Projects are visibility views, docs are optional snapshots/contracts, and Gira acts as a deterministic checker/compiler.

This first implementation slice should keep the command short for daily use while preserving a clearer canonical command family:

• canonical: gira feature ...
• short alias: gira feat ...

Scope

Implement a narrow read-only feature map slice:

• Add a small feature map convention document for issue-backed capability records.
• Add CLI help/dispatch for gira feature and alias gira feat.
• Add read-only commands for listing and checking feature records from GitHub issues.
• Add a read-only for command that reports whether a work issue is linked to a feature/capability issue.
• Keep the feature map optional: if no configured feature records exist, report that state without failing as a workflow blocker.
• Do not mutate GitHub Projects or create Project fields/views.

Non-goals

• Do not implement Project v2 field/view automation.
• Do not require feature map coverage in ticket readiness yet.
• Do not generate or update docs/feature-map.md yet.
• Do not add LLM PRD-to-issue decomposition.
• Do not introduce a separate PM database.

Acceptance Criteria

• gira feature --help and gira feat --help describe the feature map UX.
• gira feature list --repo OWNER/REPO reads issue-backed feature records and handles the empty/not-configured case.
• gira feature check --repo OWNER/REPO emits deterministic diagnostics for missing sections, missing/invalid maturity, and feature link health.
• gira feature for ISSUE --repo OWNER/REPO reports linked feature/capability state for a work issue, or a clear missing-link next step.
• gira feat works as a short alias for the same commands.
• Tests cover CLI dispatch, parsing, empty feature map behavior, and diagnostics.
• go test ./... passes.

Doctor Impact

Adds read-only feature map diagnostics only. No existing repo workflow, status label, ticket readiness, PR readiness, or finish behavior should change in this slice. Future required-mode integration should be a separate ticket.

Expected Delivery

A focused Go CLI implementation, tests, and a short docs page defining the optional issue-backed feature/capability map convention.

planning: human
implementation: codex
review:

base_branch: main
base_source: branch_policy.default
branch_policy_mode: github-flow
target: default
work_branch: issue-635-add-read-only-feature-map-command-ux

[StatPan]

Finish Receipt

• Finished at: 2026-05-24T11:19:59Z
• Ticket: Add read-only feature map command UX #635 status=Done state=closed
• Linked PR: feat: Add read-only feature map command UX #636 state=MERGED merged=true
• Checks: passed total=11 passing=11 pending=0 failing=0
• Review: unknown
• Evidence: closing_reference,branch_binding,checks
• AI Delivery Telemetry: present
• Label changes: add=status:done remove=status:in-progress
• Warnings: missing_acceptance_criteria
• Next: ticket is done