roadmap-clips — cross-source roadmap synthesis (LUNA-59)

You turn the luna vault's scattered actionable signal into ONE sequenced
roadmap note in 60-Maps/. You propose — you never auto-file Jira tickets
and never restructure the vault (same contract as /synthesize-clips).

Deterministic collection lives in tools/roadmap-aggregate.mjs (read-only,
no network). You do the judgement work: cluster, sequence, map to tools, dedup
candidate tickets against open Jira. HIMMEL-128: invoke the tool and the
Jira CLI with the Bash tool only — no headless / print-mode claude invocations.

Inputs

$ARGUMENTS (all optional): [--vault <path>] [--dry-run].

• --vault <path> — luna vault root. Default $HOME/Documents/luna.
• --dry-run — do everything EXCEPT the final write; print the roadmap to
  stdout instead.

Steps

1. Aggregate (deterministic)

Run the aggregator and capture its JSON inventory:

node <plugin>/tools/roadmap-aggregate.mjs [--vault "$VAULT"]

<plugin> = marketplace/plugins/obsidian-triage. The JSON is
{vault, counts, total, items:[{source_type, text, origin, category}]} with
source_type ∈ action-item | deferred | synthesis-proposal | promotion | component. If total is 0, print roadmap-clips: no actionable items found — nothing to map and exit 0.

2. Cluster into themes (judgement)

Group the items into 3–8 coherent themes (e.g. "vault enrichment depth",
"pipeline automation", "source-trust hygiene"). A theme spans source types —
a deferred github ref, a synthesis-proposal, and an action-item can all
belong to the same theme. Note the supporting item count + origins per theme.
Skip pure noise (e.g. a bare fan-out URL with no thematic signal) but log how
many items you dropped so coverage is honest.

3. Sequence + map to tools (judgement)

Order themes by a rough effort × impact read (cheap-high-impact first).
For each theme, annotate the target it would land in: code (harness /
plugin / tooling work in a tracked repo) or vault-only (a note/MOC, no
code). These are hints, not commitments. Don't assume any particular repo —
which repo code maps to is the operator's call.

4. Dedup candidate tickets against open Jira (skip when no project configured)

Dedup against the operator's tracked Jira project(s) — never a hardcoded
project. The tracked keys are the keys of projects in the jira metadata
cache that /jira-init writes (not a secret — project keys + issue types):
~/.cache/himmel-cli/jira/metadata.json (POSIX) /
%LOCALAPPDATA%/himmel-cli/jira/metadata.json (Windows).

If the cache is missing or has no projects, SKIP this step: emit no Jira
candidate list and mark every candidate (new) — i.e. vault-only proposals
(a user who doesn't track this work in Jira gets no spurious ticket
suggestions). Otherwise, for each tracked project KEY, fetch open issues (one
literal command per project):

node scripts/jira/dist/index.js list --project <KEY> --status "To Do,In Progress,Backlog" --limit 50

For each theme you'd propose as a ticket, compare its title against the open
summaries across all tracked projects. If an open issue clearly already covers
it, mark the candidate already-tracked: <KEY> and EXCLUDE it from the
"propose to file" list. Only genuinely-new work reaches the candidate list.
Do NOT create tickets — that is the operator's call (and an external write
the auto-mode classifier gates).

5. Write the roadmap note (skip entirely under --dry-run — print instead)

Deterministic path 60-Maps/<TODAY>-roadmap.md (TODAY=$(date +%Y-%m-%d)).
If it already exists, rewrite it in place and add supersedes: listing the
prior content's generated_at (idempotent per day). Shape:

---
type: roadmap
generated_at: <ISO>
generated_by: /roadmap-clips
source_counts: { deferred: N, synthesis-proposal: M, ... }   # = the aggregator's `counts`
---

# Roadmap — <TODAY>

> Auto-generated by `/roadmap-clips` from the luna vault. Proposals only —
> nothing here is filed or restructured automatically.

## Themes (sequenced: cheap-high-impact first)
### 1. <theme> — effort:<lo|med|hi> impact:<lo|med|hi> → <target: code|vault-only>
<1–2 line synthesis>. Supporting items (<count>): [[<origin>]], …

## Candidate tickets (deduped vs open Jira — NOT filed; omitted when no Jira project is configured)
- [ ] <title> → <target>  (new)
- ~~<title>~~ already-tracked: <KEY>

## Sources scanned
<counts table from the aggregator JSON>

6. Report

One summary line: roadmap-clips: <T> themes from <N> items (<S> sources); <C> candidate tickets (<D> deduped vs open Jira). Wrote 60-Maps/<TODAY>-roadmap.md
(or (dry-run, nothing written)).

Scope (MVP)

• Proposals only — no Jira creation, no vault restructuring.
• Dedup is title-vs-summary judgement, not a guaranteed match; when unsure,
  keep the candidate and annotate verify-not-dup.
• Read-only aggregation; the only write is the single 60-Maps roadmap note.