| name | sync-issues |
| description | Sync Faru backlog cards with GitHub issues in both directions — create the missing GH issue for every todo/wip card and the missing card for every open issue. Use for 'sync issues', 'cards to issues', 'GH issue coverage', 'reconcile backlog'. Not for closing/triaging issues. |
| context | fork |
sync-issues
Réconciliation bidirectionnelle entre les cartes Faru (docs/backlog/*/CARD.md)
et les issues GitHub du repo. Garantit l'invariant :
Toute carte todo/wip ↔ une issue GH ouverte, et toute issue GH ouverte pertinente ↔ une carte.
Le travail mécanique vit dans framework/tools/sync-issues.sh (0 token, réutilisable
par un hook ou une routine cron). Cette skill est l'enveloppe d'invocation.
Prérequis : gh authentifié (gh auth status), projet en mode Faru (docs/backlog/ présent).
Le lien carte ↔ issue
Matérialisé des deux côtés → idempotent (deux exécutions = no-op) :
| Côté | Marqueur |
|---|
| Carte | issue: <N> dans le frontmatter |
| Issue | <!-- ulk:card:<slug> --> dans le corps + ligne Carte : \docs/backlog/…`` |
Commandes
/sync-issues — prévisualiser (dry-run)
framework/tools/sync-issues.sh
Affiche le plan sans rien muter : cartes todo/wip sans issue, issues ouvertes sans carte,
et le bilan chiffré. Aucune issue ni carte n'est créée.
/sync-issues apply — appliquer
framework/tools/sync-issues.sh --apply
- Montant (carte → issue) : crée l'issue GH manquante (label
bug/enhancement selon
le type: de la carte), écrit issue: N dans le frontmatter, pose le marqueur dans l'issue.
- Descendant (issue → carte) : crée
docs/backlog/YYYY-MM-DD-<type>-<slug>/CARD.md
(type déduit des labels : bug→fix, enhancement→feat, sinon task), y écrit issue: N,
et pose le marqueur <!-- ulk:card:<slug> --> dans le corps de l'issue.
⚠️ Action sortante : --apply crée des issues publiques et édite leur corps.
Toujours lancer un dry-run d'abord et confirmer le volume.
Options
| Flag | Effet |
|---|
--apply | Applique (défaut : dry-run) |
--no-up | Désactive le sens carte → issue |
--no-down | Désactive le sens issue → carte |
--statuses "todo wip" | Statuts de cartes considérés actifs (défaut : todo wip doing in-progress) |
--exclude-labels "a b" | Labels d'issues à ne pas transformer en carte (défaut : dependencies wontfix duplicate invalid question) |
Filtres appliqués au sens descendant (issue → carte)
- Bots — auteurs
dependabot / renovate / github-actions / *[bot]* ignorés
(ex. #7 Dependency Dashboard).
- Labels de maintenance —
dependencies, wontfix, duplicate, invalid, question.
- Idempotence — une issue déjà liée (numéro présent dans un
issue: ou marqueur dans le corps)
n'est jamais redupliquée.
Câblage automatique (optionnel)
Le script étant sans état et idempotent, il se câble tel quel :
- Cron cloud —
/schedule ou agent routine (53) : sync-issues.sh --apply 1×/jour.
- Checkpoint — appelé par 2b3 (08) en fin de session pour garder le backlog aligné.
- bruce (25) — diagnostic : lance le dry-run et signale l'écart carte↔issue.
Sortie type (dry-run)
🔗 sync-issues · repo=izo/Ulk · mode=DRY-RUN (aucune mutation)
── MONTANT · cartes todo/wip sans issue ──
➕ créerait une issue ← 2026-06-28-SPEC-HERMES-TASK-RUNNER (type=spec, label=—)
── DESCENDANT · issues ouvertes sans carte ──
➕ créerait 2026-07-04-fix-sentinel-sh-…/CARD.md ← #230 (sentinel.sh: …)
⤫ #7 ignorée (label exclu : dependencies)
── Bilan (DRY-RUN) ──
issues créées (montant) : 34
cartes créées (descend.): 5
