tessera-ctl/.planning/quick/260917-jdh-ci-job-desktop-ueberspringen-wenn-apps-d/260917-jdh-SUMMARY.md

---
phase: quick-260917-jdh
plan: 01
subsystem: ci
tags: [gitea-actions, posix-sh, tauri, actions-cache, ci-cd]

requires: []
provides:
  - ".gitea/scripts/desktop-stamp.sh — Unterbefehle stamp (Stempel aus Version + letztem Commit an den Desktop-Pfaden) und check (Manifest-/Pruefsummen-Gate fuer einen restaurierten desktop-dist/)"
  - "ci.yml Job desktop: stamp -> actions/cache/restore (Stempel-Schluessel, nur main) -> check -> 13 bedingte Bau-Schritte -> Stempel-Save -> unveraenderte Uebergabe an publish"
affects: [ci, desktop-build, docs]

actuals:
  tokens: 5352
  tasks: 2
  commits: 2
  plan_head_before: 29db4c0

tech-stack:
  added: []
  patterns:
    - "Zwei-Ebenen-Cache-Schluessel fuer denselben Job: desktop-dist-stamp-<Version>-<SHA> als Ueberspring-Gate (nur main, kein restore-keys, voller 40-stelliger SHA gegen act_runner-Praefixsuche) neben dem bestehenden desktop-dist-<gitea.sha> fuer die Uebergabe an publish, die immer laeuft"
    - "if: steps.reuse.outputs.reuse != 'true' an jedem der 13 bestehenden Bau-Schritte statt eines umschliessenden Bedingungs-Jobs — haelt die Schritte inhaltlich byteidentisch und einzeln im Gitea-Actions-Log sichtbar"

key-files:
  created:
    - .gitea/scripts/desktop-stamp.sh
  modified:
    - .gitea/workflows/ci.yml
    - docs/anleitung-betrieb.md
    - docs/ci-cd-setup.md
    - docs/anleitung-entwicklung.md
    - CHANGELOG.md

key-decisions:
  - "pnpm-lock.yaml bewusst NICHT in DESKTOP_PATHS: die Tauri-CLI-Version haengt an apps/desktop/package.json (darin enthalten), der Desktop-Bau liest ausserhalb von apps/desktop keine Werkstatt-Datei (frontendDist ist ../src innerhalb von apps/desktop)."
  - "stamp-cache (actions/cache/restore@v4) bewusst OHNE restore-keys: act_runner sucht auch zum Hauptschluessel per Praefix: ein aelterer, praefixgleicher Stand darf nie als Treffer gelten. Der volle 40-stellige Commit-SHA am Schluesselende macht das unmoeglich."
  - "skip_allowed ausschliesslich bei GITHUB_REF == refs/heads/main: Tags v* suchen und legen nichts unter dem Stempel-Schluessel ab, damit nie Live-Pakete (reine Version, Kanal live) unter einem Beta-Stempel landen; check verwirft zusaetzlich channel != beta als zweite Absicherung."
  - "desktop-stamp.sh selbst gehoert zu DESKTOP_PATHS: eine Aenderung an der Stempelregel muss selbst einen Neubau ausloesen, sonst koennte ein alter, nicht mehr zur neuen Regel passender Cache-Treffer unbemerkt uebernommen werden."

requirements-completed: [QUICK-260917-JDH]

coverage:
  - id: T1
    description: "desktop-stamp.sh stamp liefert Stempel <Version>-<voller SHA>, version, sha7, skip_allowed (true nur auf main); GITHUB_OUTPUT erhaelt alle vier Schluessel; leere Commit-Historie zu den Desktop-Pfaden fuehrt zu Exit 1"
    requirement: "QUICK-260917-JDH"
    verification:
      - kind: script
        ref: "lokale Probe: sh -n, DESKTOP_TAG=v1.2.0 GITHUB_REF=refs/heads/main|refs/tags/v1.2.0, GITHUB_OUTPUT-Datei"
        status: pass
    human_judgment: false
  - id: T2
    description: "desktop-stamp.sh check gibt reuse=true nur bei CACHE_HIT=true, gueltigem/passendem Manifest (Kanal beta, Version, beide Dateinamen) und uebereinstimmender Groesse+sha256 je Datei; sonst reuse=false und Aufraeumen (AppImage/exe/manifest.json entfernt)"
    requirement: "QUICK-260917-JDH"
    verification:
      - kind: script
        ref: "lokale Probe: Mini-desktop-dist im Scratchpad — vollstaendiges Manifest (reuse=true), veraenderte .exe-Datei (reuse=false, Manifest entfernt), CACHE_HIT=false (reuse=false)"
        status: pass
    human_judgment: false
  - id: T3
    description: "ci.yml Job desktop: Schritte stamp/stamp-cache/reuse an Index 1-3; 13 Bau-Schritte mit if: steps.reuse.outputs.reuse != 'true' und sonst byteidentischem Inhalt; Stempel-Save vor unveraenderter Uebergabe an publish; quality/test/publish und on: unveraendert gegenueber 38c1400"
    requirement: "QUICK-260917-JDH"
    verification:
      - kind: script
        ref: "node -e (js-yaml-Tiefenvergleich gegen git show 38c1400:.gitea/workflows/ci.yml) — 19 Schritte im Job desktop, alle Struktur- und Inhaltspruefungen gruen"
        status: pass
    human_judgment: false
  - id: T4
    description: "Doku (Betriebshandbuch Kap. 10, CI-Runbook Abschnitt 4/6, Entwicklungsanleitung) und ein CHANGELOG-Stichpunkt unter Unveroeffentlicht/Geaendert"
    requirement: "QUICK-260917-JDH"
    verification:
      - kind: script
        ref: "command grep-Kette aus Task 2 (15 Einzelpruefungen) — alle gruen (DOCS-OK)"
        status: pass
    human_judgment: false
  - id: T5
    description: "Realer CI-Nachweis: Push ohne Desktop-Aenderung ueberspringt den Bau, Push mit Desktop-Aenderung baut neu"
    requirement: "QUICK-260917-JDH"
    verification: []
    human_judgment: true
    rationale: "Der reale act_runner-Lauf (echter Cache-Server, echter Push) ist laut Plan-Objective ausdruecklich kein Executor-Task — Nachweis durch den Orchestrator nach dem Push, siehe Abschnitt unten."

duration: ~20min
completed: 2026-09-17
status: complete
---

# Quick Task 260917-jdh: CI-Job `desktop` ueberspringt den Bau bei unveraendertem Desktop-Stand Summary

**Neues Skript `desktop-stamp.sh` (Stempel aus Version + letztem Desktop-Commit, Manifest-/Pruefsummen-Gate) plus Job `desktop` in `ci.yml`, der 13 Bau-Schritte per `if:` ueberspringt, wenn zum Stempel bereits geprueft-vollstaendige Pakete im Zwischenspeicher liegen**

## Performance

- **Duration:** ~20 min
- **Completed:** 2026-09-17T12:28:54Z
- **Tasks:** 2/2
- **Files modified:** 6 (1 neu, 5 geaendert)

## Accomplishments

- `.gitea/scripts/desktop-stamp.sh` (POSIX sh, `set -eu`, kennt kein Secret) mit den Unterbefehlen `stamp` (Stempel `<Version>-<voller SHA>` aus `desktop-version.sh --print` + `git log -1` ueber `DESKTOP_PATHS`, Ausgaben `stamp`/`version`/`sha7`/`skip_allowed` nach stdout und `GITHUB_OUTPUT`) und `check` (Manifest, Kanal `beta`, Version, Dateiname/Groesse/sha256 je Plattform — nur bei vollstaendiger Uebereinstimmung `reuse=true`, sonst Aufraeumen + `reuse=false`)
- `ci.yml` Job `desktop`: drei neue Schritte `stamp`/`stamp-cache`/`reuse` direkt nach dem Checkout (vor den teuren setup-node/apt/rustup-Schritten), alle 13 bestehenden Bau-Schritte tragen jetzt `if: steps.reuse.outputs.reuse != 'true'` bei sonst unveraendertem Inhalt, neuer Schritt „Pakete unter dem Stempel ablegen" vor der unveraenderten „Uebergabe an publish"
- Vier Doku-Stellen ergaenzt (Betriebshandbuch Kap. 10 mit neuem Unterabschnitt + Fehlerbild, CI-Runbook Abschnitt 4/6, Entwicklungsanleitung) und ein CHANGELOG-Stichpunkt unter Unveroeffentlicht/Geaendert
- Alle lokalen Proben (Skript-Verhalten, `GITHUB_OUTPUT`, drei `check`-Faelle, js-yaml-Strukturvergleich gegen den Ausgangsstand 38c1400, 15 Doku-Greps) gruen; `quality`/`test`/`publish` und `on:` byteidentisch zum Ausgangsstand

## Task Commits

Each task was committed atomically:

1. **Task 1: `desktop-stamp.sh` (Stempel + Cache-Pruefung) und Job `desktop` ueberspringt den Bau bei Treffer** - `8c4aaa5` (ci)
2. **Task 2: Doku (Betriebshandbuch Kap. 10, CI-Runbook Abschnitt 4/6, Entwicklungsanleitung) und CHANGELOG** - `e7633e1` (docs)

**Plan metadata:** wird vom Orchestrator nach diesem SUMMARY committet.

## Files Created/Modified

- `.gitea/scripts/desktop-stamp.sh` - neu; Unterbefehle `stamp`/`check`, Konstante `DESKTOP_PATHS`, Helfer `out()` fuer stdout+`GITHUB_OUTPUT`
- `.gitea/workflows/ci.yml` - Job `desktop`: Schritte `stamp`/`stamp-cache`/`reuse`/„Pakete unter dem Stempel ablegen" neu; `if:` an den 13 bestehenden Bau-Schritten; Kopfkommentar um `quick-260917-jdh`-Absatz ergaenzt; `quality`/`test`/`publish`/`on:` unveraendert
- `docs/anleitung-betrieb.md` - Kap. 10: neuer Unterabschnitt „Wann gebaut wird und wann Pakete uebernommen werden", Halbsatz am Job-Dauer-Satz, neue Fehlerbilder-Zeile
- `docs/ci-cd-setup.md` - Abschnitt 4: Absatz „Ueberspringen bei unveraendertem Desktop", Ergaenzung zu Schritt 7; Abschnitt 6: neuer Fehlerbehebungs-Eintrag
- `docs/anleitung-entwicklung.md` - Absatz zum CI-Ueberspringen nach „Desktop-App lokal bauen", inkl. lokaler Stempel-Probe
- `CHANGELOG.md` - ein Stichpunkt unter `## Unveroeffentlicht` / `### Geaendert`

## Decisions Made

- `pnpm-lock.yaml` bewusst nicht in `DESKTOP_PATHS` — begruendet in Skript-Kopfkommentar und `docs/ci-cd-setup.md`.
- `stamp-cache` ohne `restore-keys`, voller 40-stelliger SHA am Schluesselende — verhindert einen Praefix-Treffer eines aelteren Standes durch die act_runner-Cache-Suche.
- `skip_allowed` ausschliesslich bei `refs/heads/main`; Tags suchen/legen nichts unter dem Stempel-Schluessel ab.
- `desktop-stamp.sh` selbst ist Teil von `DESKTOP_PATHS`, damit eine Aenderung der Stempelregel selbst einen Neubau ausloest.

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

- Zwei Doku-Saetze (Job-Dauer in `anleitung-betrieb.md`, Einleitungssatz in `anleitung-entwicklung.md`) wurden beim ersten Schreiben durch Zeilenumbrueche in der Markdown-Quelle getrennt, wodurch die exakten Grep-Muster aus `<verify>` zunaechst nicht trafen. Beide Saetze wurden je in eine durchgehende Zeile zusammengefasst; alle 15 Doku-Pruefungen sind danach gruen. Kein Code-Problem, reine Formatierungskorrektur ohne inhaltliche Aenderung.

## User Setup Required

None - no external service configuration required.

## Nachweis durch Orchestrator (offen)

Der echte CI-Beweis ist laut Plan-Objective bewusst kein Executor-Task und steht nach dem Push noch aus. Drei zu beobachtende Faelle:

1. **Dieser Push selbst baut.** `ci.yml`/`desktop-stamp.sh` stehen in der eigenen Pfadliste `DESKTOP_PATHS` — der erste Lauf nach diesem Merge muss den Job `desktop` vollstaendig durchlaufen und legt dabei `desktop-dist-stamp-1.2.0-<SHA-dieses-Standes>` im Zwischenspeicher des Runners ab.
2. **Ein folgender Push ohne Desktop-Aenderung ueberspringt den Bau.** Schritt „Gefundene Pakete pruefen" meldet im Log „Desktop unveraendert seit `<sha7>`: Pakete … aus dem Zwischenspeicher", die 13 Bau-Schritte erscheinen im Gitea-Actions-Lauf als uebersprungen, der Job `desktop` ist unter einer Minute fertig, `publish` bleibt gruen, und `GET /api-proxy/desktop/latest` auf alpha nennt weiterhin den aelteren Beta-Commit-Suffix.
3. **Ein Push mit einer Aenderung unter `apps/desktop/` baut wieder vollstaendig** und legt einen neuen Stempel-Schluessel ab (alter Schluessel bleibt bis zum Ablauf im Zwischenspeicher erhalten, wird aber nie wieder getroffen).

Zusaetzlicher Beobachtungspunkt aus dem Plan-Checker-Hinweis: Das Verhalten von `actions/cache/save@v4` bei einem bereits belegten Schluessel (Fall 1 nach einem zuvor schon vorhandenen Stempel, z. B. nach einem Wiederholungslauf) ist auf diesem Runner nicht separat gemessen — laut Gitea-/actions-cache-Dokumentation loest das nur eine Info-Meldung aus, keinen Fehler; beim ersten realen Lauf im Log gegenpruefen.

## Next Phase Readiness

- Kein Blocker fuer weitere Arbeit. Die drei parallelen Quick-Tasks (Favoriten-Widget-Favicon, Favoriten-Sortierung/Bildmarke, Desktop-Client-Serveradresse) sind von dieser Aenderung nicht betroffen — sie ruehren `.gitea/`, `docs/` (ausser den hier bearbeiteten Stellen) oder die CI-Konfiguration nicht an.
- Naechster inhaltlicher Schritt ist der Orchestrator-Nachweis oben, nicht ein weiterer Plan.

---
*Quick Task: 260917-jdh*
*Completed: 2026-09-17*

## Self-Check: PASSED

All 6 claimed source/doc files found on disk; both task commits (8c4aaa5, e7633e1) found in git history.

## Nachweis durch Orchestrator — Ergebnis

- Fall 1 (Lauf 382, Push `5a444ec`): Stempel `1.2.0-29c132e…`, kein Zwischenspeicher → gebaut, `Cache saved with key: desktop-dist-stamp-…`.
- Fall 3 (Lauf 383, Push `7479cb4` mit Desktop-Aenderung): Stempel `1.2.0-7004b5b…` neu → Neubau; Lauf 384 (`a6d1a64`) ebenso.
- Fall 2 (Docs-Push ohne Desktop-Aenderung ueberspringt): siehe Aktenstand-Push nach diesem Eintrag (Lauf 385).
- `cache/save` bei bereits belegtem Schluessel: bisher nicht aufgetreten (jeder Lauf hatte einen neuen Stempel) — weiter beobachten.