feat: spec-change loopback — SDD 'change spec -> regenerate affected code'

Operationalises framework §5.1 for an existing feature. Same pipeline (driver unchanged);
stations become amend-aware; tests are the change-propagation layer.

- core/req-delta.ts reqDelta(old,new) -> {added,changed,removed} REQ-ids (TDD); cli/req-delta.
- spec-to-tests (amend): per req-delta — added -> new .skip'd; changed -> edit test + RE-SKIP
  (keeps main green until code catches up); removed -> delete test. On the spec PR.
- implement (amend): un-skip new+changed tests, update code, remove dead code for removed REQs.
- verify-unskip is PR-type-aware (core/unskip.isSpecBranch): no-op on devloop/spec/* (spec-to-tests
  is the legit author there; vitest/trace/mutation + spec-review keep it honest), enforces
  unskip-only on devloop/<slug> (the implement seam). template passes the PR head branch.
- specify (amend existing spec, stable REQ ids); loop skill (spec PR on devloop/spec/<slug>).
- design doc docs/2026-06-21-spec-change-loopback-design.md; USAGE section. driver state machine
  unchanged. v0.4.0, 146 tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RjNiTNchAZoTmkmovVngnR

Author: TMogdans

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devloop",
-  "version": "0.3.1",
+  "version": "0.4.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" }
 }

USAGE.md

@@ -100,6 +100,21 @@ Was passiert (Spec-PR-zuerst; der Driver gehorcht dem getesteten Kern, trifft ni
 > **Zwei PRs, zwei Mensch-Tore:** der **Spec-PR** (Schritt 5, Spec-Review §5.1) und der
 > **Implementierungs-PR** (Schritt 10, Merge-Stopp §9). Beide sind echte CODEOWNER-Reviews (Anker b).
 
+### Eine Spec ändern (Rückschleife)
+
+SDD: **erst die Spec ändern, dann den Code regenerieren.** Läuft als *dieselbe* Kette auf einem
+*bestehenden* Feature — die Stationen arbeiten amend-fähig:
+
+1. `specify` lädt die `spec.md` und ändert gezielt die betroffenen `REQ-`-Kriterien (IDs **stabil** halten).
+2. `spec-to-tests` fasst per `req-delta` **genau** die geänderten REQs an: neu → `.skip`'t; **geändert →
+   Test ändern + wieder `.skip`'en** (sonst rötet der jetzt-aktive Test `main`); entfernt → Test weg.
+3. Spec-PR auf `devloop/spec/<slug>` → Review → Merge.
+4. `implement` entskippt die neuen + geänderten Tests, zieht den **Code** nach und entfernt **toten
+   Code** für entfernte REQs. An Tests weiterhin nur `.skip` entfernen.
+
+Die **Tests sind die Change-Propagation:** geänderte Tests röten genau den betroffenen Code; `implement`
+macht sie grün. Beide Mensch-Tore + die Entskip-Naht gelten unverändert.
+
 ---
 
 ## 3. Die zwei Stopps — wie du freigibst (Anker b)

agents/devloop-implement.md

@@ -25,6 +25,10 @@ Du läufst in der **Sandbox** auf dem Dev-Rechner: Lichter aus (`--dangerously-s
 2. Implementiere minimal gegen die Tests/Spec. **Der volle Gate-Satz läuft hier lokal mit** (`vitest` · Stryker · Semgrep · Traceability) — nicht nur `tsc`/`biome`. Iteriere, bis lokal grün. Dieser lokale Lauf ist **advisorisch, nicht autoritativ** (er ist korrumpierbar) — er kauft *Tempo*, nicht *Vertrauen*.
 3. Erst wenn lokal grün: öffne einen **PR** auf den Feature-Branch (die Capability-Grenze; nie Push auf main). Das **Verdikt von Rang** kommt vom **geschützten Runner** (CI = Gate of Record), nicht von deinem lokalen Lauf.
 
+## Spec-Änderung (Amend-Modus)
+
+Liegt eine Spec-Änderung vor (der Spec-PR mit geänderten/neuen `.skip`'ten Tests ist schon auf `main`): **entskippe** die neuen + geänderten Tests, zieh den **Code** nach, bis sie grün sind, und **entferne toten Code** für entfernte REQs. An den Tests weiterhin **nur `.skip` entfernen** — die geänderten Assertions kamen von `spec-to-tests` (Spec-PR), du aktivierst sie nur (`verify-unskip` erzwingt das auf `devloop/<slug>`).
+
 ## Rückkante (äußere Schleife — CI)
 
 CI re-runt die Gates autoritativ. Kommt ein rotes Verdikt als **Defektsignal** über den schmalen Rückkanal zurück (`gh pr checks`, `gh run view --log-failed`: Datei:Zeile:Regel / überlebende Mutante), behebe den **Defekt** — nicht das Signal. Den **geschützten Satz** dabei nie anfassen (CI-Protected-Set-Ratchet greift sonst). Stagniert es, übernimmt der Driver (frischer Kontext / Eskalation).

agents/devloop-spec-to-tests.md

@@ -25,6 +25,18 @@ Für **jede** `REQ-<CTX>-<nr>`-ID **mindestens einen** Test, getaggt mit der ID
 - Markiere jeden mit **`.skip`** (Vitest-Familie: `test.skip`/`it.skip`/`describe.skip`). So zählt das Trace-Gate sie als Abdeckung, aber Vitest rötet nicht (red-before-green), solange der Code fehlt → der Spec-PR hält `main` grün.
 - **Du schreibst KEINEN Produktcode.** Nur Tests. `implement` darf später **ausschließlich das `.skip` entfernen** — nie deine Assertions/Titel ändern. Genau deshalb müssen deine Tests jetzt vollständig sein: was du nicht schreibst, kann `implement` nicht hinzufügen, ohne die Gewaltenteilung zu brechen (maschinell geprüft von `verify-unskip`).
 
+## Spec-Änderung (Amend-Modus)
+
+Ändert sich eine *bestehende* Spec, fasst du **nur die betroffenen REQs** an — nicht das ganze Feature. Hol das Delta deterministisch:
+```
+node "${CLAUDE_PLUGIN_ROOT}"/dist/cli/req-delta.js <alte-spec> <neue-spec>   # {added, changed, removed}
+```
+(alte Spec: `git show <base>:<spec.md>`). Dann je Fall:
+- **added** → neuen Test, `.skip`'t (wie oben).
+- **changed** → den bestehenden Test (gleiche `REQ-`-ID) ändern **und `.skip` wieder setzen**. Sonst rötet der jetzt-aktive Test gegen den (noch alten) Code `main` beim Spec-PR-Merge. `implement` entskippt ihn später, nachdem der Code nachgezogen ist.
+- **removed** → den Test entfernen (sonst rote verwaiste `REQ-`-Referenz im Trace-Gate).
+Unveränderte Tests **nicht** anfassen (sie bleiben aktiv und grün). Das läuft alles auf dem **Spec-PR** (`devloop/spec/<slug>`); dort darfst du Tests autoren/ändern/re-skippen — `verify-unskip` greift dort nicht.
+
 ## Grenzen
 
 - Du bist **nicht** die Implement-Station; deine Unabhängigkeit von ihr ist der Sinn der Trennung.

agents/devloop-specify.md

@@ -20,6 +20,10 @@ 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).
 
+## Spec-Änderung (Amend-Modus)
+
+Existiert die `spec.md` schon (Feature wird geändert, nicht neu angelegt): **lade sie und ändere gezielt** die betroffenen `REQ-`-Kriterien (ändern/hinzufügen/entfernen) — `REQ-`-IDs **stabil halten** (geänderter REQ behält seine ID, damit `spec-to-tests`/Trace die Zuordnung halten). Tier neu ableiten. Der Rest der Kette läuft identisch (Spec-PR → Review → implement); die Stationen erkennen die Änderung am Delta.
+
 ## Grenzen
 
 - **Kein Produktcode, keine Tests.** Nur die Spec.

bin/devloop

@@ -16,6 +16,7 @@ const ALLOWED = [
   "verify-review",
   "verify-unskip",
   "check-codeowners",
+  "req-delta",
   "cleanup",
 ];
 const [sub, ...rest] = process.argv.slice(2);

dist/cli/req-delta.js

@@ -0,0 +1,19 @@
+// CLI: which REQs changed between two spec.md versions -> {added, changed, removed}. spec-to-tests
+// uses it to amend exactly the affected tests on a spec change (surgical re-derivation).
+// Usage: req-delta <oldSpecPath> <newSpecPath>   (oldSpecPath may be absent -> treated as empty).
+import { readFileSync } from "node:fs";
+import { reqDelta } from "../core/req-delta.js";
+const [, , oldPath, newPath] = process.argv;
+if (!newPath) {
+    process.stderr.write("usage: req-delta <oldSpecPath> <newSpecPath>\n");
+    process.exit(64);
+}
+const readOr = (p, fallback) => {
+    try {
+        return p ? readFileSync(p, "utf8") : fallback;
+    }
+    catch {
+        return fallback;
+    }
+};
+process.stdout.write(JSON.stringify(reqDelta(readOr(oldPath, ""), readOr(newPath, "")), null, 2) + "\n");

dist/cli/verify-unskip.js

@@ -5,9 +5,16 @@
 //
 // Usage: verify-unskip <repoPath> <baseRef>   (baseRef e.g. origin/main)
 import { execFileSync } from "node:child_process";
-import { isAllowedTestEdit } from "../core/unskip.js";
+import { isAllowedTestEdit, isSpecBranch } from "../core/unskip.js";
 const repo = process.argv[2] ?? ".";
 const base = process.argv[3] ?? "origin/main";
+const headBranch = process.argv[4] ?? "";
+// Spec-PR: spec-to-tests is the legitimate test author here (gated by spec-review + vitest +
+// mutation). The unskip seam applies only to the Impl-PR. No-op pass on devloop/spec/* branches.
+if (isSpecBranch(headBranch)) {
+    process.stdout.write(JSON.stringify({ ok: true, skipped: "spec-PR (devloop/spec/*)" }) + "\n");
+    process.exit(0);
+}
 const gitSafe = (args) => {
     try {
         return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8" });

dist/core/req-delta.js

@@ -0,0 +1,34 @@
+// Spec-change delta: which EARS criteria (REQ-<CTX>-<nr>) were added, changed, or removed
+// between two spec.md versions. Lets spec-to-tests touch exactly the affected REQs (surgical
+// re-derivation) instead of the whole feature (design: spec-change loopback, §5.1).
+//
+// One criterion per line (the EARS convention): a line carrying a REQ id maps that id to its
+// criterion text (everything after the id, minus an optional ":" / "-" / "—" separator).
+// Comparison is whitespace-normalised.
+const REQ_LINE = /\b(REQ-[A-Z0-9]+-\d+)\b\s*[:\-—]?\s*(.*)$/;
+const normalize = (s) => s.trim().replace(/\s+/g, " ");
+function parseReqs(spec) {
+    const reqs = new Map();
+    for (const line of spec.split("\n")) {
+        const m = line.match(REQ_LINE);
+        if (m)
+            reqs.set(m[1], normalize(m[2]));
+    }
+    return reqs;
+}
+export function reqDelta(oldSpec, newSpec) {
+    const before = parseReqs(oldSpec);
+    const after = parseReqs(newSpec);
+    const delta = { added: [], changed: [], removed: [] };
+    for (const [id, text] of after) {
+        if (!before.has(id))
+            delta.added.push(id);
+        else if (before.get(id) !== text)
+            delta.changed.push(id);
+    }
+    for (const id of before.keys()) {
+        if (!after.has(id))
+            delta.removed.push(id);
+    }
+    return delta;
+}

dist/core/unskip.js

@@ -5,6 +5,9 @@
 // isUnskipOnly(old, new) is true iff `new` can be produced from `old` by DELETING zero or more
 // `.skip` tokens — nothing else. Editing an assertion/title, adding/removing a test, or ADDING
 // a `.skip` anywhere (sneaking a test off — even while unskipping another) is forbidden.
+// Spec-PRs (devloop/spec/<slug>) are where spec-to-tests legitimately authors/amends/re-skips
+// tests; the unskip seam constrains only the Impl-PR. The driver controls the branch prefix.
+export const isSpecBranch = (branch) => branch.startsWith("devloop/spec/");
 const SKIP = ".skip";
 const isWordChar = (c) => c !== undefined && /\w/.test(c);
 // A `.skip` token only counts at a word boundary (so `.skipped` is not treated as `.skip`).