feat: Add read-only feature map command UX

docs-site/.vitepress/config.mts

@@ -47,6 +47,7 @@ export default defineConfig({
         items: [
           { text: 'Workspace', link: '/workspace' },
           { text: 'Ticket Workflow', link: '/ticket-workflow' },
+          { text: 'Feature Map', link: '/feature-map' },
           { text: 'State Model', link: '/state-model' },
           { text: 'Goal Mode', link: '/goal-mode' },
           { text: 'Sprint And Release', link: '/sprint-release' },

docs-site/agent-operator-skill.md

@@ -30,6 +30,9 @@ summarize that skill instead of redefining it.
 - `gira ticket wait [TICKET] [--repo OWNER/REPO] [--timeout 5m] [--interval 5s]`: Wait for pending linked PR checks without merging.
 - `gira ticket finish [TICKET] --dry-run|--apply [--repo OWNER/REPO] [--sync-local]`: Merge the linked PR when policy allows and close the ticket loop without local checkout sync by default.
 - `gira ticket status [TICKET] [--repo OWNER/REPO] [--json]`: Report ticket status, linked PR blockers, and next action.
+- `gira feature check [--repo OWNER/REPO] [--limit N] [--json]`: Validate optional feature map records and work links without mutating GitHub.
+- `gira feature for ISSUE [--repo OWNER/REPO] [--limit N] [--json]`: Show which feature or capability a work issue is linked to.
+- `gira feature list [--repo OWNER/REPO] [--limit N] [--json]`: List optional issue-backed feature or capability records.
 - `gira goal finish [GOAL] --dry-run|--apply [--repo OWNER/REPO] [--terminal done|human_review|blocked|superseded|abandoned] [--json]`: Preview goal finish readiness and apply human-review handoff receipts.
 - `gira goal next [GOAL] [--repo OWNER/REPO] [--json]`: Select the next safe child ticket for a goal or explain why work must stop.
 - `gira goal plan [GOAL] --dry-run [--repo OWNER/REPO] [--json]`: Propose dry-run child ticket packets from a goal issue without mutation.

docs-site/command-capabilities.md

@@ -6,6 +6,9 @@ Schema version: `gira-command-capabilities/v1`
 
 | Command | Aliases | Capability | JSON support | Mutation boundary | Docs |
 | --- | --- | --- | --- | --- | --- |
+| `gira feature check` | gira feat check | `read` | `stable_json` | none | docs/feature-map.md, docs-site/feature-map.md, docs-site/command-reference.md |
+| `gira feature for` | gira feat for | `read` | `stable_json` | none | docs/feature-map.md, docs-site/feature-map.md, docs-site/command-reference.md |
+| `gira feature list` | gira feat list | `read` | `stable_json` | none | docs/feature-map.md, docs-site/feature-map.md, docs-site/command-reference.md |
 | `gira goal finish` | none | `apply_mutation` | `stable_json` | posts an idempotent goal finish handoff receipt when run with --apply; --dry-run previews readiness and receipt | docs/goal-operating-model.md, docs-site/command-reference.md |
 | `gira goal next` | none | `read` | `stable_json` | none | docs/goal-operating-model.md, docs-site/command-reference.md |
 | `gira goal plan` | none | `dry_run_mutation` | `stable_json` | computes child ticket proposals only; no apply surface exists for this command | docs/goal-operating-model.md, docs-site/command-reference.md |

docs-site/command-reference.md

@@ -2,6 +2,91 @@
 
 This page is generated from Gira's command metadata registry. Update `internal/gira/command_registry.go` first, then refresh this page.
 
+## `feature check`
+
+Validate optional feature map records and work links without mutating GitHub.
+
+Usage:
+
+```bash
+gira feature check [--repo OWNER/REPO] [--limit N] [--json]
+```
+
+Since: `v1.18.0`
+
+Flags:
+
+- `--repo`: Target GitHub repo in OWNER/REPO format.
+- `--limit`: Max issues to inspect. Default: 1000.
+- `--json`: Emit stable feature-map-check/v1 JSON.
+
+Examples:
+
+- Check feature map health
+
+```bash
+gira feat check --repo OWNER/backlog
+```
+
+Documented in: `docs/feature-map.md`, `docs-site/feature-map.md`, `docs-site/command-reference.md`
+
+## `feature for`
+
+Show which feature or capability a work issue is linked to.
+
+Usage:
+
+```bash
+gira feature for ISSUE [--repo OWNER/REPO] [--limit N] [--json]
+```
+
+Since: `v1.18.0`
+
+Flags:
+
+- `--repo`: Target GitHub repo in OWNER/REPO format.
+- `--issue`: Work issue number. Can also be numeric positional.
+- `--limit`: Max issues to inspect. Default: 1000.
+- `--json`: Emit stable feature-map-for/v1 JSON.
+
+Examples:
+
+- Inspect one work issue
+
+```bash
+gira feat for 123 --repo OWNER/app
+```
+
+Documented in: `docs/feature-map.md`, `docs-site/feature-map.md`, `docs-site/command-reference.md`
+
+## `feature list`
+
+List optional issue-backed feature or capability records.
+
+Usage:
+
+```bash
+gira feature list [--repo OWNER/REPO] [--limit N] [--json]
+```
+
+Since: `v1.18.0`
+
+Flags:
+
+- `--repo`: Target GitHub repo in OWNER/REPO format.
+- `--limit`: Max issues to inspect. Default: 1000.
+- `--json`: Emit stable feature-map-list/v1 JSON.
+
+Examples:
+
+- List feature records
+
+```bash
+gira feat list --repo OWNER/backlog
+```
+
+Documented in: `docs/feature-map.md`, `docs-site/feature-map.md`, `docs-site/command-reference.md`
+
 ## `goal finish`
 
 Preview goal finish readiness and apply human-review handoff receipts.

docs-site/feature-map.md

@@ -0,0 +1,52 @@
+# Feature Map
+
+Gira supports an optional issue-backed feature map for teams that want a durable
+capability view in GitHub.
+
+The model is:
+
+| Surface | Role |
+| --- | --- |
+| GitHub issue | Canonical feature or capability record. |
+| GitHub Project | Visibility view for the map, roadmap, and todo slices. |
+| Milestone | Delivery batch for executable work. |
+| PR | Implementation evidence. |
+| Gira | Read-only checker/compiler. |
+
+Feature records are GitHub issues labeled `type:capability` or `type:feature`,
+or issues titled with `Capability:` or `Feature:`.
+
+```markdown
+Key: tl
+Status: stable
+
+## User Need
+## Capability
+## Surface
+## Docs
+## Evidence
+```
+
+Work issues can link back with:
+
+```markdown
+Related capability: #31
+```
+
+Start with the read-only commands:
+
+```bash
+gira feature list --repo OWNER/REPO
+gira feature check --repo OWNER/REPO
+gira feature for 123 --repo OWNER/REPO
+```
+
+For daily typing, use the short alias:
+
+```bash
+gira feat check
+gira feat for 123
+```
+
+If no feature records exist, the map is treated as not configured. Normal ticket
+lifecycle commands keep working.

docs-site/index.md

@@ -36,6 +36,7 @@ features:
 | Set up a repo or personal workspace | [Quick Start](/quickstart), [Global Config](/global-config) | `gira init`, `gira setup global`, `gira repo register`, `gira adopt repo` |
 | See work across repos | [Workspace](/workspace) | `gira workspace status`, `gira workspace repos sync` |
 | Run issue to PR work | [Ticket Workflow](/ticket-workflow) | `gira ticket new`, `start`, `pr`, `review`, `checks`, `wait`, `finish` |
+| Maintain an optional feature map | [Feature Map](/feature-map) | `gira feature list`, `feature check`, `feature for` |
 | Manage larger work packets | [Goal Mode](/goal-mode), [Sprint And Release](/sprint-release) | `gira goal status`, `goal next`, `goal finish`, `epic list`, `milestone plan` |
 | Diagnose readiness and drift | [Readiness And Audit](/readiness-audit), [Troubleshooting](/troubleshooting) | `gira ticket status`, `ticket review`, `audit drift`, `jira doctor` |
 | Map Jira concepts to GitHub | [Jira Mapping](/jira-mapping), [Jira Provider](/jira-primary-provider) | `gira jira init`, `jira mirror`, `jira transition`, `jira import`, `jira export` |
@@ -47,6 +48,7 @@ features:
 | `guide` | Built-in quickstart, ticket, stats, Jira, agent, skill, and concepts guides in the installed CLI. | [Quick Start](/quickstart), [Command Reference](/command-reference) |
 | `setup`, `init`, `repo`, `adopt`, `config` | First-run setup, global registry entries, repo adoption, issue adoption, and config source diagnosis. | [Global Config](/global-config), [Troubleshooting](/troubleshooting) |
 | `workspace`, `projects`, `status` | Multi-repo workspace status, repo allowlist sync, existing Project mirroring, and compact read-only repo summaries. | [Workspace](/workspace) |
+| `feature`, `feat` | Optional issue-backed feature map listing, validation, and work issue linkage checks. | [Feature Map](/feature-map) |
 | `ticket`, `start`, `work`, `dev` | Daily issue to branch to PR to finish lifecycle, plus compatibility aliases and lower-level helpers. | [Ticket Workflow](/ticket-workflow) |
 | `goal`, `epic`, `milestone`, `sprint`, `release` | Larger objective tracking, child ticket selection, milestone batches, sprint planning, and release readiness. | [Goal Mode](/goal-mode), [Sprint And Release](/sprint-release) |
 | `audit`, `jira` | Drift, readiness, provider compatibility, Jira mirror, transition planning, import, and export diagnostics. | [Readiness And Audit](/readiness-audit), [Jira Provider](/jira-primary-provider) |

docs/feature-map.md

@@ -0,0 +1,99 @@
+# Issue-Backed Feature Map
+
+Gira's feature map is an optional capability map over GitHub issues. It is for
+operators who want to keep a durable view of product capabilities while still
+using milestones and tickets as the delivery queue.
+
+The feature map is not required for normal ticket lifecycle work. If a repo has
+no feature records, `gira feature check` reports the map as not configured and
+does not block work.
+
+## Ownership
+
+| Surface | Role |
+| --- | --- |
+| GitHub issue | Canonical feature or capability record. |
+| GitHub Project | Visibility view for PM-style map, roadmap, and todo views. |
+| Milestone | Delivery batch for executable work issues. |
+| PR | Implementation evidence for a linked work issue. |
+| Docs | Optional snapshot or public contract. |
+| Gira | Read-only checker/compiler for links, sections, and maturity state. |
+
+This keeps the Project screen useful without making Project-only items the
+source of truth.
+
+## Feature Records
+
+A feature record is a GitHub issue that either:
+
+- has `type:capability` or `type:feature`; or
+- has a title beginning with `Capability:` or `Feature:`.
+
+Recommended body shape:
+
+```markdown
+# Capability: Ticket lifecycle
+
+Key: tl
+Status: stable
+
+## User Need
+
+## Capability
+
+## Surface
+
+## Docs
+
+## Evidence
+```
+
+Allowed maturity values are:
+
+- `optional`
+- `planned`
+- `preview`
+- `stable`
+- `legacy`
+- `deprecated`
+
+Maturity can be recorded as a body line such as `Status: stable`, or as a label
+such as `capability:stable` or `feature:stable` when the repo chooses to create
+those labels. `Key:` is a short daily identifier so operators can avoid typing
+long slugs.
+
+## Work Links
+
+Executable work remains normal Gira tickets. A work issue can link to a feature
+record with a readable body line:
+
+```markdown
+Related capability: #31
+```
+
+or:
+
+```markdown
+Feature: #31
+```
+
+In the first slice, Gira only reads these links. Mutation helpers such as
+`gira feat link` are planned separately.
+
+## Commands
+
+```bash
+gira feature list --repo OWNER/REPO
+gira feature check --repo OWNER/REPO
+gira feature for 123 --repo OWNER/REPO
+```
+
+`gira feat` is the short alias for daily use:
+
+```bash
+gira feat check
+gira feat for 123
+```
+
+`check` validates feature records and work links. In optional mode, missing
+feature links are diagnostics, not ticket readiness blockers.

docs/skills/gira-agent-operator.md

@@ -98,6 +98,9 @@ This generated section contains command facts for the agent lifecycle. Update `i
 - `gira ticket wait [TICKET] [--repo OWNER/REPO] [--timeout 5m] [--interval 5s]`: Wait for pending linked PR checks without merging.
 - `gira ticket finish [TICKET] --dry-run|--apply [--repo OWNER/REPO] [--sync-local]`: Merge the linked PR when policy allows and close the ticket loop without local checkout sync by default.
 - `gira ticket status [TICKET] [--repo OWNER/REPO] [--json]`: Report ticket status, linked PR blockers, and next action.
+- `gira feature check [--repo OWNER/REPO] [--limit N] [--json]`: Validate optional feature map records and work links without mutating GitHub.
+- `gira feature for ISSUE [--repo OWNER/REPO] [--limit N] [--json]`: Show which feature or capability a work issue is linked to.
+- `gira feature list [--repo OWNER/REPO] [--limit N] [--json]`: List optional issue-backed feature or capability records.
 - `gira goal finish [GOAL] --dry-run|--apply [--repo OWNER/REPO] [--terminal done|human_review|blocked|superseded|abandoned] [--json]`: Preview goal finish readiness and apply human-review handoff receipts.
 - `gira goal next [GOAL] [--repo OWNER/REPO] [--json]`: Select the next safe child ticket for a goal or explain why work must stop.
 - `gira goal plan [GOAL] --dry-run [--repo OWNER/REPO] [--json]`: Propose dry-run child ticket packets from a goal issue without mutation.