Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "devloop",
"version": "0.8.1",
"version": "0.9.0",
"description": "Generische agentische Dev-Loop-Kette: /devloop:specify|spec-to-tests|implement|critic|loop + Bindungs-Anker (Wächter-Vorbedingung, content-gebundene Stopps, CI-Required-Check). Projektübergreifend.",
"author": { "name": "Tobias Mogdans" }
}
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ fail-closed CI-Required-Check und GitHub-Branch-Protection.
- `/devloop:spec-to-twin` — *(optional, `.devloop` `twin.enabled`)* unabhängiges Verhaltens-Orakel (triviales Referenzmodell + REQ-getaggte Invarianten + fast-check model-based) aus Domänen-Wahrheiten — Korrektheit statt nur Spec-Treue
- `/devloop:implement` — konsumiert Spec+Tests, öffnet PR (schreibt Spec/Tests nicht selbst)
- `/devloop:critic` — adversarial, frischer Kontext, strukturiertes Verdikt
- `/devloop:smoke` — *(optional, `.devloop` `smoke.tiers`)* Smoke gegen einen lokalen Stack auf dem PR-Stand: erst die Konsumenten des geänderten Pfads belegen, dann Browser/API/CLI, Wirkung vorher/nachher messen; liefert die Abnahme-Anleitung für den Menschen
- `/devloop:loop` — der Driver (orchestriert die Stationen als isolierte Subagenten)
- `/devloop:init` — verdrahtet den CI-Bindungs-Anker in ein Ziel-Repo
- `/devloop:cleanup` — räumt lokale, im Remote gemergte Branches + ihre Worktrees sicher auf
Expand Down
12 changes: 11 additions & 1 deletion USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,16 @@ Was passiert (Spec-PR-zuerst; der Driver gehorcht dem getesteten Kern, trifft ni
`devloop-precondition-check`, `verify-unskip`, Tier aus dem Diff. Rot → Defektsignal über
`gh`-Rückkanal → neue `implement`-Runde (Rückkante, Max-Iter + Eskalation).
9. **critic** (eigener Subagent, adversarial) → strukturiertes Verdikt.
- *(optional, nur für Tiers in `.devloop` `smoke.tiers`)* **smoke** (eigener Subagent, ändert
nichts am Repo) nach einem akzeptierten Verdikt, **vor** `MARK_READY`: ermittelt, **wer** den
geänderten Pfad aufruft (mit `datei:zeile`), wählt danach Browser, API (echte Tokens) oder CLI,
baut den lokalen Stack nach `smoke.setup` auf dem PR-Stand auf und misst je Fall die Wirkung
vorher/nachher. Ergebnis leitet `smoke-verdict` ab (`failed` → Rückkante, `not-run` → ein
Neustart, dann Eskalation). Bericht + **Abnahme-Anleitung** kommen als PR-Kommentar; der Stack
bleibt für deine Abnahme laufen. Ersetzt sie nicht: Ob die Intention erreicht ist, prüft ein Mensch.
**Grenzen** (nicht maschinell prüfbar, nur per Prompt und deinem Blick auf den Bericht): dass
`effect` wirklich mehr als ein HTTP-Status ist, dass `not-applicable` stimmt, und dass die
Station den Arbeitsbaum nicht verändert hat.
10. **Merge je Tier:** T0/T1 Auto-Merge bei grün · T2 required Reviewer · **▣ STOPP: T3-Merge**.

> **Zwei PRs, zwei Mensch-Tore:** der **Spec-PR** (Schritt 5, Spec-Review §5.1) und der
Expand Down Expand Up @@ -185,7 +195,7 @@ Stand gebunden.
## 4. Einzelne Stationen ohne Orchestrierung

Jede Station gibt es auch als Einzel-Skill (ohne die harten Stopps), z.B. zum Üben:
`/devloop:specify`, `/devloop:spec-to-tests`, `/devloop:spec-to-twin` *(optional)*, `/devloop:implement`, `/devloop:critic`.
`/devloop:specify`, `/devloop:spec-to-tests`, `/devloop:spec-to-twin` *(optional)*, `/devloop:implement`, `/devloop:critic`, `/devloop:smoke` *(optional)*.
Für den echten, abgesicherten Lauf nimm `/devloop:loop`.

---
Expand Down
61 changes: 61 additions & 0 deletions agents/devloop-smoke.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: devloop-smoke
description: Fährt den Smoke gegen einen LOKALEN Stack auf dem PR-Stand — auf dem echten Konsumentenpfad (Browser, API oder CLI, je nachdem, wer den geänderten Pfad aufruft) und mit beobachteter Wirkung, nicht nur Status. Liefert einen maschinenlesbaren Bericht plus eine Abnahme-Anleitung für den Menschen. Läuft nach einem akzeptierten Critic-Verdikt, vor MARK_READY; nur für Tiers, die das Ziel-Repo einschaltet. Ändert keinen Repo-Inhalt.
tools: Read, Glob, Grep, Bash
---

# Station: smoke

Du belegst, dass die Änderung **auf dem Weg wirkt, auf dem sie benutzt wird**. Tests und Kritiker haben geprüft, ob der Code die Spec erfüllt. Du prüfst, ob das Gebaute im laufenden System das Verhalten zeigt, das die Spec verspricht. Du ersetzt **nicht** die Abnahme durch den Menschen: Ob die Intention erreicht ist, entscheidet am Ende ein Mensch. Du bereitest ihm diese Abnahme vor.

## Eingaben

- `spec.md` des Features, besonders den Abschnitt **„Smoke“** (Abnahme-Fälle aus Nutzersicht).
- Der PR-Diff (`git diff <base>...HEAD`).
- Die Aufbau-Anleitung des Ziel-Repos: `.devloop/config.json` → `smoke.setup` (Pfad zu einer Datei im Repo, die beschreibt, wie der lokale Stack startet, wie Testkonten entstehen und wie man abräumt). Fehlt sie: Bericht mit `setup.ok: false` und dem Grund in `setup.steps` — nicht improvisieren.

## Vorgehen

1. **Konsumenten ermitteln — zuerst, immer.** Für jeden geänderten Pfad (Endpunkt, Komponente, Job, Event): Wer ruft ihn tatsächlich auf? Belege mit `datei:zeile` (grep nach Pfad, Client-Funktion, Tool-Name). Typische Falle: Die Oberfläche benutzt einen *anderen* Endpunkt als den geänderten — dann ist ein Klicktest grün, ohne die Änderung zu berühren.
2. **Modus pro Fall wählen**, abgeleitet aus Schritt 1:
- `browser` — die Oberfläche ruft den Pfad auf: durchklicken (Playwright headless über die E2E-Werkzeuge des Repos, Screenshots als Beleg).
- `api` — nur Clients ohne Oberfläche (MCP, andere Dienste, externe Integrationen): echte Anfragen durch das Gateway mit **echten Tokens** aus dem lokalen Identity-Provider, keine selbst signierten.
- `cli` / `other` — Jobs, Konsumenten von Events usw.
Kein Laufzeitkonsument (reine Doku, Testcode, Build-Konfiguration): `cases: []` und `notApplicable` mit Begründung — die Konsumenten-Analyse muss trotzdem drinstehen.
3. **Stack aufbauen** nach `smoke.setup`, auf dem **PR-Stand** (eigener, abgekoppelter Worktree des PR-HEAD). Eigene, eindeutig benannte Testkonten anlegen. **Nur lokal:** keine Produktions-URLs, keine echten Zugangsdaten, keine geteilten Umgebungen.
4. **Fälle fahren.** Je Fall: Zustand **vorher** messen → Aktion → Zustand **nachher** messen. `effect` ist der Wirkungsbeleg (DB-Zeile, gespeicherte Datei, gerenderter Inhalt, ausgelöstes Event) — ein HTTP-Status allein ist kein Smoke. Fälle aus der Spec abdecken; dazu die Gegenfälle, die geschlossen bleiben müssen (ohne Token, falsche Rolle, gefälschte Header).
5. **Abnahme-Anleitung schreiben** (`abnahme`, Markdown): kurze, kopierbare Schritte, mit denen der Mensch dieselben Fälle **selbst** am laufenden Stack prüfen kann — woran er Erfolg erkennt, welche Testkonten es gibt. Das ist das wichtigste Ergebnis für den Menschen.
6. **Stack laufen lassen** für die Abnahme des Menschen. In `cleanup` die Befehle zum Abräumen (Container, Prozesse, Testkonten, Worktree).

## Grenzen

- **Kein Repo-Inhalt wird geändert**: kein Produktcode, keine Tests, keine Spec. Hilfsskripte nur unter `$TMPDIR`.
- Ein roter Fall ist ein Befund, kein Anlass, etwas „hinzubiegen“. Melde ihn mit `pass: false` und dem Beobachteten.
- Scheitert der Aufbau, ist das `setup.ok: false` — **nicht** ein roter Fall. Dasselbe gilt, wenn die Infrastruktur **während** der Fälle wegbricht (Container stirbt, Port weg): dann `setup.ok: false` mit dem Grund, nicht `pass: false`. Die Kette unterscheidet „Code falsch“ (Rückkante) von „Smoke lief nicht“ (Neustart, dann Eskalation).
- Nie Werte ausgeben, die Geheimnisse sind (Tokens, Client-Secrets) — auch nicht im Bericht.

## Output: Bericht (letzte Nachricht, ein JSON-Objekt)

Genau **ein** Objekt mit `cases` in der ganzen Nachricht — das Beispiel unten nicht mit ausgeben. Zwei solche Objekte gelten als mehrdeutig (`not-run`).

```json
{
"consumers": [
{ "changed": "PATCH /api/boardgames/{id}/versions/{vid}", "caller": "wuerfelgeist-mcp update_version", "evidence": "services/wuerfelgeist-mcp/src/domain/versions/VersionsClient.ts:42" }
],
"setup": { "ok": true, "steps": ["infra gestartet", "Gateway aus PR-HEAD", "Testkonten smoke-user, smoke-mod"] },
"cases": [
{ "id": "user-patch", "req": "REQ-X-1", "mode": "api",
"action": "PATCH notes als user",
"expected": "pending Contribution, Version unverändert",
"observed": "HTTP 200, contributions 37 -> 38 (pending)",
"effect": "versions.notes vorher = nachher; contributions.status = pending",
"pass": true }
],
"notApplicable": null,
"abnahme": "## Abnahme\n1. ...",
"cleanup": ["docker rm -f ...", "..."]
}
```

Das Ergebnis (`passed` / `failed` / `not-applicable` / `not-run`) leitet der Orchestrator mit `smoke-verdict` aus diesem Bericht **ab**. Ein eigenes Status-Label zählt nicht. Ungültig ist ein Bericht u. a. ohne `effect` je Fall, ohne Konsumenten-Analyse, ohne Abnahme-Anleitung, oder mit `setup.ok: false` — er gilt dann als `not-run`.
1 change: 1 addition & 0 deletions agents/devloop-specify.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Du erzeugst die **`spec.md`** — die Wurzel des Vertrauens (§5.1). Alles Spät
```
(Liegt die Map an einem ungewöhnlichen Ort, alternativ `{"touched":[...],"tierMap":<inhalt>}` durchreichen.) Schreibe das Ergebnis als `Tier:`-Feld in die `spec.md`. **Achtung:** dieses Tier ist **vorläufig/advisorisch** — es steuert nur Critic-Tiefe und Stopp-Strenge in der inneren Schleife. **Autoritativ** wird das Tier **aus dem tatsächlichen Diff auf CI** berechnet (§9/§10, derselbe `derive-tier` server-seitig), nie aus deiner Deklaration. Du kannst das Tier also nicht herunterspielen.
3. Schreibe `spec.md` (User Story, Tier, Liste der `REQ-`-Kriterien mit EARS-Typ-Tag).
4. Schreibe einen Abschnitt **`## Smoke`**: die Abnahme-Fälle aus **Nutzersicht** (wer tut was über welchen Weg, was muss danach sichtbar/gespeichert sein), inkl. der Gegenfälle, die geschlossen bleiben müssen. Getrennt davon **„Nach dem Deploy“**: was nur in Produktion nachweisbar ist (echte Konten, echte Konfiguration). Benenne, **wer den geänderten Pfad aufruft** (Oberfläche, MCP, anderer Dienst) — nachgesehen, mit `datei:zeile`, nicht angenommen. Die `smoke`-Station und der Mensch an der Abnahme arbeiten damit; der Abschnitt ist kein `REQ-`-Kriterium und erzeugt keine Tests.

## Spec-Änderung (Amend-Modus)

Expand Down
25 changes: 25 additions & 0 deletions dist/cli/smoke-tiers.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// CLI: print the smoke-enabled tiers of a repo (.devloop/config.json -> smoke.tiers) as JSON.
// Usage: smoke-tiers <repoPath>. Missing config/section -> []. Malformed -> exit 1 (fail closed:
// a typo must not silently switch the smoke gate off).
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { readSmokeTiers } from "../core/smoke.js";
const repo = process.argv[2] ?? ".";
let config;
try {
config = JSON.parse(readFileSync(join(repo, ".devloop", "config.json"), "utf8"));
}
catch (e) {
if (e.code === "ENOENT")
config = undefined;
else {
process.stderr.write("smoke-tiers: .devloop/config.json unlesbar; refusing to guess (fail-closed)\n");
process.exit(1);
}
}
const tiers = readSmokeTiers(config);
if (tiers === undefined) {
process.stderr.write("smoke-tiers: smoke.tiers ungültig (erlaubt: T0..T3); refusing to guess (fail-closed)\n");
process.exit(1);
}
process.stdout.write(JSON.stringify(tiers) + "\n");
21 changes: 21 additions & 0 deletions dist/cli/smoke-verdict.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
// CLI: raw smoke report -> DERIVED smoke result for the DriverState (REQ-SMOKE-2/3).
// stdin: { rawOutput: string, retried?: boolean }. Any `status` in the input or in the report is
// ignored — the status comes from validating the report (see core/smoke.ts).
// stdout: { smoke: DriverState["smoke"], failedCases, abnahme, notApplicable }
import { parseSmokeReport } from "../core/smoke.js";
import { readStdin } from "./_stdin.js";
let input = {};
try {
input = JSON.parse(await readStdin());
}
catch {
/* unparseable input -> not-run below */
}
const run = parseSmokeReport(typeof input.rawOutput === "string" ? input.rawOutput : "");
const smoke = run.status === "not-run" ? { status: "not-run", retried: input.retried === true } : { status: run.status };
process.stdout.write(JSON.stringify({
smoke,
failedCases: run.failedCases,
abnahme: run.abnahme,
notApplicable: run.notApplicable,
}) + "\n");
38 changes: 36 additions & 2 deletions dist/core/driver.js
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,37 @@
// "completed" critic round: MARK_READY (draft -> ready, which arms auto-merge) only comes
// from critiqued + completed + accepted; merge-pending without ready === true goes back to
// the critic; a not-run critic is retried once, then ESCALATE (never read as "no findings").
// 8. (REQ-SMOKE-1..4) Where the repo opts a tier into the smoke station (.devloop smoke.tiers),
// MARK_READY additionally requires a DERIVED smoke result "passed" or "not-applicable" —
// produced by the smoke-verdict CLI, never by the station's own label. "failed" is a defect
// signal (back-edge), "not-run" is retried once, then ESCALATE. Tiers not opted in: unchanged.
import { nextLoopDecision } from "./loop.js";
function smokeRequired(state) {
return (state.smokeTiers ?? []).includes(state.tier);
}
// Invariant 8: the smoke gate in front of MARK_READY (only for opted-in tiers).
function smokeGate(state) {
if (!smokeRequired(state))
return undefined;
const s = state.smoke;
if (!s)
return { kind: "SPAWN_STATION", station: "smoke" };
switch (s.status) {
case "passed":
case "not-applicable":
return undefined;
case "failed":
return handleRedGate(state); // observed wrong effect = defect signal -> back-edge
case "not-run":
// Setup broke / report unparseable: one restart, then escalate — never read as "passed".
return s.retried
? { kind: "ESCALATE", reason: "smoke-not-run" }
: { kind: "SPAWN_STATION", station: "smoke" };
default:
// Anything not produced by smoke-verdict (typo, hand-written label) is fail-closed.
return { kind: "ESCALATE", reason: "smoke-invalid-state" };
}
}
function handleRedGate(state) {
if (!state.loop || !state.loopParams) {
return { kind: "ESCALATE", reason: "loop-params-required" };
Expand Down Expand Up @@ -112,8 +142,12 @@ export function nextAction(state) {
}
if (c.verdict === "rejected")
return handleRedGate(state); // back-edge via nextLoopDecision
// accepted: mark ready first (arms auto-merge), then behave like merge-pending.
return state.ready === true ? handleReady(state) : { kind: "MARK_READY" };
// accepted: mark ready first (arms auto-merge), then behave like merge-pending. `ready` must
// mirror GitHub: the executor resets it to false on RE_GEN with markDraft, so new code after a
// human back-edge passes the smoke gate again before MARK_READY.
if (state.ready === true)
return handleReady(state);
return smokeGate(state) ?? { kind: "MARK_READY" };
}
case "merge-pending":
// Invariant 7: merge-pending is only legitimate for a ready PR (= accepted critic round).
Expand Down
6 changes: 4 additions & 2 deletions dist/core/init.js
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,10 @@ export function initRepo(targetRepo, ciTemplate, opts = {}) {
// hook defers to CI instead of demanding the (anchor-a) local token.
// anchor: CI is authoritative (b). twin: the optional spec-to-twin station, disabled by default
// (discoverable here; core stays schlank). Enable via twin.enabled=true + twin.area (the protected
// oracle path, e.g. "services/foo/twin") — see the spec-to-twin station.
writeIfAbsent(".devloop/config.json", JSON.stringify({ anchor: "b", twin: { enabled: false } }, null, 2) + "\n");
// oracle path, e.g. "services/foo/twin") — see the spec-to-twin station. smoke: the optional
// smoke station, off by default (tiers: []); enable per tier + point `setup` at a repo doc that
// says how to start the local stack and create test accounts — see the smoke station.
writeIfAbsent(".devloop/config.json", JSON.stringify({ anchor: "b", twin: { enabled: false }, smoke: { tiers: [], setup: null } }, null, 2) + "\n");
// Tier-map: NEVER shadow an existing one. resolveTierMapPath prefers .devloop/, so writing a
// default there would silently override a repo's own tools/tier-map.json -> gate regression.
const existingTierMap = resolveTierMapPath(targetRepo);
Expand Down
Loading
Loading